How to unsubscribe from this group? On Fri, Apr 5, 2019 at 8:24 PM Alex Herbert <alex.d.herb...@gmail.com> wrote:
> 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 > > > -- Thanks Javin http://javarevisited.blogspot.com/ Twitter : https://twitter.com/javinpaul blog : http://java67.blogspot.com blog : http://savingsfunda.blogspot.com
