On 05/04/2019 12:06, Gilles Sadowski wrote:
On 05/04/2019 09:27, sebb wrote:
On Tue, 12 Mar 2019 at 12:28, Rob Tompkins <chtom...@gmail.com> wrote:
For those unfamiliar with MathJaX, is the javascript mechanism for
accommodating for LaTeX (the math typesetting language, written by Donald
Knuth) in html.
It could be convenient to use mathematical notation in our javadoc generally.
That said, Java doesn’t do this so it would indeed be non-standard. My opinion
is in the +0.5 zone currently.
Thoughts?
Is it likely that existing Javadoc comments will trigger MathJaX?
That would perhaps mean lots of changes just to stay still.
What does it look like if JavaScript is not in use?
Not very readable. Have a look at this page:
If one knows LaTeX somewhat, it's fairly readable.
Another advantage is that, within the source code, it is
more readable than the equivalent formula in HTML.
E.g. compare
r<sub>1</sub>x<sub>1</sub>
with
\( r_1 x_1 \)
So this depends on the use case:
Use case
LaTex
HTML
Reading the Javadoc online Nice equations. Needs Javascript enabled.
Q. Is disabling Javascript common?
OK equations. No need for Javascript.
Accessing the Javadoc in an IDE No equations. Needs fluency in LaTeX.
Can resort to viewing Javadocs in a browser (with Javscript). OK
equations.
Reading the source code No equations. Needs fluency in LaTeX. Can
resort to viewing Javadocs in a browser (with Javscript). Verbose HTML
equations. Needs fluency in HTML. Can view Javadocs in an IDE/browser.
Maintaining the source code LaTex is easier to write complex equations.
IDE cannot show the Javadoc.
Javadoc tool cannot spot errors.
Javadoc must be built and viewed locally before commit.
Verbose HTML equations. Some equations not easily possible without
imagination.
IDE can show the Javadoc for a quick check.
Javadoc tool can spot errors so can be part of a series of checks for a PR.
In the common use case I question if the disabling of Javascript in a
browser is a common thing nowadays? Using LaTeX will be better. Someone
who sees the pages without Javascript and raises a bug will be kindly
directed towards enabling Javascript in their browser for the
commons.apache.org host.
In the developer use case then an IDE can support the HTML which is
nice. It can be used for simple equations. For the LaTeX I think that a
developer is quite capable of understanding what is going on and can
open a browser to view the Javadoc if needed.
For reading the source code it is the same as above. If you got this far
then you can figure it out.
In the source code maintainer use case then writing the HTML for a
complex equation is more work than using LaTeX. But the equations cannot
be checked by Javadoc. So the onus is on the developer who wants to use
LaTeX to render the javadocs and make sure they look correct.
So to allow MathJax in any commons project would require an explicit
validation of the LaTeX that may be present in any PR or new commit.
My vote is to enable via a profile (as Sebb suggested) and let the
project developers decide if they want to maintain it.
http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/analysis/polynomials/PolynomialsUtils.html
Then turn off Javascript (e.g. [1]) and look again.
An example non-javascript output for an equation (method
createJacobiPolynomial(int, int, int)) is:
\( P_0^{vw}(x) = 1 \\ P_{-1}^{vw}(x) = 0 \\ 2k(k + v + w)(2k + v + w -
2) P_k^{vw}(x) = \\ (2k + v + w - 1)[(2k + v + w)(2k + v + w - 2) x +
v^2 - w^2] P_{k-1}^{vw}(x) \\ - 2(k + v - 1)(k + w - 1)(2k + v + w)
P_{k-2}^{vw}(x) \)
[1] https://www.lifewire.com/disable-javascript-in-google-chrome-4103631
I think it would be sensible for the processing to be optional, e.g.
via a marker file.
Not all projects might expect improvement with MathJaX; if so,
they should not use it. But deactivating MathJaX when it is used
in the Javadoc does not seem very user-friendly (if the marker file
would not include the HTML snippet necessary to invoke the script).
Anyways, it seems to be a component-level decision.
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
