You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sebb <se...@gmail.com> on 2019/04/05 08:27:22 UTC
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re:
[jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
On Tue, 12 Mar 2019 at 12:28, Rob Tompkins <ch...@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?
I think it would be sensible for the processing to be optional, e.g.
via a marker file.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re:
[jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Javin Paul <sa...@gmail.com>.
Thanks, Rob, found it. It's actually in this email itself:
*to unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
<de...@commons.apache.org> *
On Fri, Apr 5, 2019 at 9:40 PM Rob Tompkins <ch...@gmail.com> wrote:
> 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 <sa...@gmail.com> wrote:
> >
> > How to unsubscribe from this group?
> >
> > On Fri, Apr 5, 2019 at 8:24 PM Alex Herbert <al...@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 <ch...@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-unsubscribe@commons.apache.org
> >>> For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
> > --
> > Thanks
> > Javin
> > http://javarevisited.blogspot.com/
> > Twitter : https://twitter.com/javinpaul
> > blog : http://java67.blogspot.com
> > blog : http://savingsfunda.blogspot.com
>
--
Thanks
Javin
http://javarevisited.blogspot.com/
Twitter : https://twitter.com/javinpaul
blog : http://java67.blogspot.com
blog : http://savingsfunda.blogspot.com
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re: [jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Rob Tompkins <ch...@gmail.com>.
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 <sa...@gmail.com> wrote:
>
> How to unsubscribe from this group?
>
> On Fri, Apr 5, 2019 at 8:24 PM Alex Herbert <al...@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 <ch...@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-unsubscribe@commons.apache.org
>>> For additional commands, e-mail: dev-help@commons.apache.org
>
>
> --
> Thanks
> Javin
> http://javarevisited.blogspot.com/
> Twitter : https://twitter.com/javinpaul
> blog : http://java67.blogspot.com
> blog : http://savingsfunda.blogspot.com
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re:
[jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Javin Paul <sa...@gmail.com>.
How to unsubscribe from this group?
On Fri, Apr 5, 2019 at 8:24 PM Alex Herbert <al...@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 <ch...@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-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
--
Thanks
Javin
http://javarevisited.blogspot.com/
Twitter : https://twitter.com/javinpaul
blog : http://java67.blogspot.com
blog : http://savingsfunda.blogspot.com
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re:
[jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Alex Herbert <al...@gmail.com>.
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 <ch...@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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re:
[jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Gilles Sadowski <gi...@gmail.com>.
> On 05/04/2019 09:27, sebb wrote:
> > On Tue, 12 Mar 2019 at 12:28, Rob Tompkins <ch...@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 \)
>
> 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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re: [jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Rob Tompkins <ch...@gmail.com>.
> On Apr 5, 2019, at 5:12 AM, Alex Herbert <al...@gmail.com> wrote:
>
>> On 05/04/2019 09:27, sebb wrote:
>>> On Tue, 12 Mar 2019 at 12:28, Rob Tompkins <ch...@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:
>
> 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) \)
>
I suppose that depends on one’s familiarity with LaTeX :-p
Definitely a fair point because the above is indeed ugly
>
> [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.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [all] Should we use MathJaX in Javadoc on all repos? (Was: Re:
[jira] [Commented] (NUMBERS-58) Javadoc: Use MathJaX)
Posted by Alex Herbert <al...@gmail.com>.
On 05/04/2019 09:27, sebb wrote:
> On Tue, 12 Mar 2019 at 12:28, Rob Tompkins <ch...@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:
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.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org