commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [math] formulas in Javadoc (was Re: [jira] [Commented] (MATH-968) Pareto distribution is missing)
Date Sun, 28 Apr 2013 14:49:56 GMT
On 4/28/13 3:19 AM, Thomas Neidhart wrote:
> On 04/28/2013 12:08 PM, Thomas Neidhart wrote:
>> On 04/27/2013 11:12 PM, Luc Maisonobe wrote:
>>> [switching to the dev list for the discussion]
>>> Le 26/04/2013 00:04, Gilles (JIRA) a écrit :
>>>>     [
>>>> Gilles commented on MATH-968:
>>>> -----------------------------
>>>> I proposed to test something similar some time ago:
>>>> But there has been significant reluctance about licensing, dependencies,
and plainly having LaTeX code inside the Javadoc.
>>>> IMHO, there are two options:
>>>> # LaTeX-based extension to create beautiful (when generated!) comments
>>>> # Basic Javadoc, no fancy formulae (especially _not_ using plain HTML)
>>> For simple formulas, like greek letters, using plain UTF-8 in javadoc
>>> seems OK to me. We could even do a global search and replace easily to
>>> change the most frequent html entities in our current code (pi, alpha,
>>> and perhaps times, sum, int and radic...) into the appropriate unicode
>>> character. It is even possible to use numerical superscripts for writing
>>> polynomials.
>>> However, I agree with Gilles we should not go too far this way and don't
>>> try to tranlitterates everything. I don't if if the following example
>>> will show up in the mail, but I wrote it in plain UTF-8:
>>>  ∫𝛼ₘ²+𝛽ₙ⁶
>>> In case it does not show up, it is an integral sign, alpha, subscript m,
>>> superscript 2, plus sign, beta, subscript n, superscript 6. Writing
>>> these 8 characters was a pain and a lot of copy/pasting from reference
>>> character tables. On my computer, it does not even looks very good
>>> because mising subscript and superscript does not work well as they are
>>> separate characters and are not aligned vertically. Another problem with
>>> this approach is that we will hit the limits pretty quickly. As an
>>> example, using a greek letter as an exponent like is done in the patch
>>> proposed for MATH-968 is not possible in unicode. There are only a few
>>> characters available for superscript or subscript.
>>> So using unicode and only unicode seems to be a pain and not sufficient.
>>> On the other hand, going to the other extreme and getting a dedicated
>>> doclet that implies installing LaTeX to generate javadocs is really to
>>> much for users.
>>> So I think the intermediate solution using mathjax with LaTeX syntax as
>>> suggested by Thomas would be good. In fact, it could also be used in the
>>> user guide as we have already discussed about it. One message from
>>> Sébastien in particular <>
>>> showed we could add support for mathjax in our user guide very easily.
>>> Even more since we switched to svnpubsub and changing the site is mainly
>>> doing a commit.
>>> Note that our documentation is expected to be viewed either generated as
>>> a web site inside a browser or read in an editor while working on the
>>> code itself. MathJax takes care of the former case beautifully, and
>>> using LaTeX syntax (instead of mathml for example) would be fine for the
>>> second case. LaTeX formulas remain understandable when read without any
>>> tools (even on a paper copy of the code), as long as we restrict
>>> ourselves to not writing complete mathematical articles. I don't expect
>>> our documentation to be generated as a PDF document for example, so a
>>> full-blown LaTeX seems overkill to me.
>> I experimented a bit with it and it works as described on the linked page:
>> * add this to the pom.xml in the build/plugins section:
>>         <plugin>
>>           <groupId>org.apache.maven.plugins</groupId>
>>           <artifactId>maven-javadoc-plugin</artifactId>
>>           <configuration>
>>             <additionalparam>-header &apos;&lt;script
>> type=&quot;text/javascript&quot;
>> src=&quot;;&gt;&lt;/script&gt;&apos;</additionalparam>
>>           </configuration>
>>         </plugin>
>> * add some formulas to javadoc, e.g.
>>  * The probability distribution function of {@code X} is given by (for
>> {@code x >= k}):
>>  * \( \alpha * k^\alpha / x^{\alpha + 1} \)
>> this should render inline formulas.
>> Mathjax supports the same environments as tex/latex (see
>>  * inline formulas: \( ... \)
>>  * equations: $$ ... $$  or \[ ... \]
>> the $ ... $ is disabled by default, but could be added via configuration.
> ah I forgot, the formulas do not work inside a <pre> tag.

That is probably OK, since most of the time when we use <pre> it is
to correctly format formulas :)

> Thomas
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message