On 10/26/13 5:48 PM, Gilles wrote:
> 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...
+1 to all of Gilles' comments. Lets track each javadoc improvement
as a separate issue. We want to be careful to review changes so
meaning / correctness is not lost. You are right, Matt, that we
never really fully addressed Luc's concerns referenced above.
Basically, what is left open is that the current setup depends on
the MathJax CDN to view the generated content correctly. So 0) we
are depending on that site to be always up 1) users can't view the
formulas offline. Note that the same applies to Wikipedia,
MathWorld and any other external references depended on by the
javadoc.
I proposed and implemented the change to support MathJax in
MATH-1006. Hopefully 0) and 1) are not going to be big issues for
anyone (and we can probably find workarounds for those for whom
these cause issues). Given that we have yet to release anything
including MathJax-generated formulas, I think it is probably best
though that we go slowly on the conversion process and see if we get
community pushback/problems following the 3.3 release that will
include some of it.
One more comment. Many thanks in advance for help improving the
accuracy and comprehension of the javadoc. When it comes to
references, what is most important is that definitional references
refer *exactly* to what we have implemented, or we clearly explain
what is different about our implementation. One of the benefits of
having TeX available in-line is that we can just explicitly state
formulas instead of referring to potentially changing or unstable
web references. As you review documentation, please take the
opportunity to suggest improvements in content as well as just format.
Thanks again for your interest in helping improve our documentation.
Phil
>
>
> Best regards,
> Gilles
>
>>
>> Thanks!
>>
>> -Matt Adereth
>> http://adereth.github.io
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
> For additional commands, e-mail: dev-h...@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
