There should be an unsubscribe link on this page: https://commons.apache.org/mail-lists.html
> On Apr 5, 2019, at 9:13 AM, Javin Paul <savingfu...@gmail.com> wrote: > > 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
