# commons-dev mailing list archives

##### Site index · List index
Message view
Top
From Gilles <gil...@harfang.homelinux.org>
Subject Re: [math] Updating documentation to use MathJax
Date Sun, 27 Oct 2013 00:48:26 GMT
Hello.

On Sat, 26 Oct 2013 20:02:14 -0400, Matt Adereth wrote:
> I recently wrote JavaDocs for a class I was adding to Commons Math
> and I
> tried to adhere to this requirement:
>
>> External references or full statements of definitions for all
> mathematical terms used in component documentation must be provided.
>
> I wanted to make my documentation appear consistent with the rest of
> the
> JavaDocs, but I found that formulas were written using multiple
> conventions.  Sometimes it would be plain text with tags for sub and
> superscript and sometimes it would be inside {@code} blocks.  Other
> inconsistencies include "sum" written out vs. ∑ vs. Σ and "abs(x)"
> vs.
> "|x|".
>
> I had the idea to add MathJax support, but I was happy to find that
> documentation will encourage its use.
>
> I'm left with a few questions:
>
> 1. Are there any thoughts about doing a pass through all the JavaDocs
> and
> updating the formulas to consistently use LaTeX?  This would be
> something
> I'm interested in doing to improve the usability and appearance of
> the
> documentation.

Your help is certainly welcome. Thanks.
I totally agree that uniformity is a quality to be sought in
documentation.

If you intend to work on this, please open a ticket on the
bug-tracking system.
I'd suggest to create (at least) one patch per Java file where

> 2. If there were a full pass, it might be a good opportunity to make
> the
> documentation consistent in other ways, such as consistent reference
> styles
> for bibliographies and links to MathWorld or Wikipedia.  Are there
> any
> other sweeping changes you would like to see?

Could you please report here the different "styles" (or lack
thereof) used for references?  We should collect input and then

>
> 3. Should MathJax also be used in the User Guide?

I think so.

> 4. What changed after Luc Maisonobe's comment on MATH-581 (
>
> https://issues.apache.org/jira/browse/MATH-581?focusedCommentId=13054851)
> that made it ok to start depending on MathJax?  I'd hate to do work
> on this
> only to have the MathJax dependency removed.

I understand your concern. I sure hope that this won't
happen.
The dependency is through a maven plugin, specified in
the project's "pom.xml". This move was done fairly recently
and nobody opposed it.
I don't know whether it is now necessary to be connected to
the Internet in order to be able to visualize the formulae,
nor whether it is still a problem if it were the case...

Best regards,
Gilles

>
> Thanks!
>