commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
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 
> it had
> already been added in MATH-1006 and that the updated developer
> 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
the Javadoc is upgraded.

> 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
decide about the style to be adopted.

>
> 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!
>
> -Matt Adereth
> http://adereth.github.io


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message