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 :
>>
>> [
>> https://issues.apache.org/jira/browse/MATH-968?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13642278#comment-13642278
>> ]
>>
>> Gilles commented on MATH-968:
>> -----------------------------
>>
>> I proposed to test something similar some time ago:
>> http://users.informatik.uni-halle.de/~grau/LaTeXlet/
>>
>> 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 <http://markmail.org/message/ljvfldrzvxsmh2ak>
> 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 '<script
type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML"></script>'</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
http://en.wikibooks.org/wiki/LaTeX/Mathematics):
* inline formulas: \( ... \)
* equations: $$ ... $$ or \[ ... \]
the $ ... $ is disabled by default, but could be added via configuration.
btw. I have seen that the opengamma project does exactly the same, e.g.
see here:
http://docs-static.opengamma.com/1.1.0/java/javadocs/com/opengamma/analytics/math/statistics/distribution/GeneralizedParetoDistribution.html
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
