[math] formulas in Javadoc (was Re: [jira] [Commented] (MATH-968) Pareto distribution is missing)

Discussion:

Luc Maisonobe

2013-04-27 21:12:14 UTC

[switching to the dev list for the discussion]

[ https://issues.apache.org/jira/browse/MATH-968?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13642278#comment-13642278 ]
-----------------------------
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.
# 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.

Luc

Pareto distribution is missing
------------------------------
Key: MATH-968
URL: https://issues.apache.org/jira/browse/MATH-968
Project: Commons Math
Issue Type: New Feature
Affects Versions: 3.2
Reporter: Alex Gryzlov
Priority: Minor
Attachments: MATH-968.zip
Seems that org.apache.commons.math3.distribution lacks a ParetoDistribution for some reason. This is a real common type of distribution, so providing it would be very nice!

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira

Phil Steitz

2013-04-27 22:18:38 UTC

Permalink

Post by Luc Maisonobe
[switching to the dev list for the discussion]

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
∫𝛼ₘ²+𝛽ₙ⁶
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.

mathjax sounds like a reasonable approach assuming we can get it to
work in javadoc, which Thomas' link appears to indicate it can. I
have not tried to use it in javadoc, but I have used it in my blog
and it is pretty easy to use. The nice thing is that there are no
extra plugins or dependencies dragged along. I also agree that the
embedded TeX will certainly look better than unicode gobledy-gook
and that people reading the source will likely be able to make sense
of it.

Phil

Post by Luc Maisonobe
Luc

---------------------------------------------------------------------

Thomas Neidhart

2013-04-28 10:08:28 UTC

Permalink

Post by Luc Maisonobe
[switching to the dev list for the discussion]

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
∫𝛼ₘ²+𝛽ₙ⁶
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

Thomas Neidhart

2013-04-28 10:19:29 UTC

Permalink

Post by Thomas Neidhart

Post by Luc Maisonobe
[switching to the dev list for the discussion]

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
∫𝛼ₘ²+𝛽ₙ⁶
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.

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-header '<script
type="text/javascript"
</configuration>
</plugin>
* add some formulas to javadoc, e.g.
* $ \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.

Thomas

Phil Steitz

2013-04-28 14:49:56 UTC

Permalink

Post by Thomas Neidhart

Post by Luc Maisonobe
[switching to the dev list for the discussion]

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
∫𝛼ₘ²+𝛽ₙ⁶
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.

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 :)

Phil

Post by Thomas Neidhart
Thomas
---------------------------------------------------------------------