Re: [4/4] commons-numbers git commit: Avoid "malformed HTML" javadoc error

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [4/4] commons-numbers git commit: Avoid "malformed HTML" javadoc error

Gilles Sadowski
On Tue, 09 May 2017 11:09:49 -0000, [hidden email] wrote:
> Avoid "malformed HTML" javadoc error

-1

This is not malformed HTML!  It is LateX (to be interpreted by
MathJax).

Regards,
Gilles

>
>
> Project: http://git-wip-us.apache.org/repos/asf/commons-numbers/repo
> Commit:
>
> http://git-wip-us.apache.org/repos/asf/commons-numbers/commit/851b17ec
> Tree:
> http://git-wip-us.apache.org/repos/asf/commons-numbers/tree/851b17ec
> Diff:
> http://git-wip-us.apache.org/repos/asf/commons-numbers/diff/851b17ec
>
> Branch: refs/heads/task_NUMBERS-33__Gamma
> Commit: 851b17ece739245bc04f7f03dc20cfe4c0ea60a8
> Parents: 8d2b162
> Author: Stian Soiland-Reyes <[hidden email]>
> Authored: Tue May 9 11:07:20 2017 +0100
> Committer: Stian Soiland-Reyes <[hidden email]>
> Committed: Tue May 9 12:09:40 2017 +0100
>
>
> ----------------------------------------------------------------------
>  .../src/main/java/org/apache/commons/numbers/gamma/Digamma.java    |
> 2 +-
>  .../src/main/java/org/apache/commons/numbers/gamma/LogGamma.java   |
> 2 +-
>  2 files changed, 2 insertions(+), 2 deletions(-)
>
> ----------------------------------------------------------------------
>
>
>
> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/851b17ec/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/Digamma.java
>
> ----------------------------------------------------------------------
> diff --git
>
> a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/Digamma.java
>
> b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/Digamma.java
> index a10f1df..32d7bf5 100644
> ---
>
> a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/Digamma.java
> +++
>
> b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/Digamma.java
> @@ -47,7 +47,7 @@ public class Digamma {
>       *
>       * Some of the constants have been changed to increase accuracy
> at the moderate
>       * expense of run-time.  The result should be accurate to within
> \( 10^{-8} \)
> -     * relative tolerance for \( 0 < x < 10^{-5} \) and within \(
> 10^{-8} \) absolute
> +     * relative tolerance for \( 0 &lt; x &lt; 10^{-5} \)  and
> within \( 10^{-8} \) absolute
>       * tolerance otherwise.
>       *
>       * @param x Argument.
>
>
> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/851b17ec/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/LogGamma.java
>
> ----------------------------------------------------------------------
> diff --git
>
> a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/LogGamma.java
>
> b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/LogGamma.java
> index 57146a2..e4fac6e 100644
> ---
>
> a/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/LogGamma.java
> +++
>
> b/commons-numbers-gamma/src/main/java/org/apache/commons/numbers/gamma/LogGamma.java
> @@ -34,7 +34,7 @@ public class LogGamma {
>      private static final LogGamma1p LOG_GAMMA_1P =
> LogGamma1p.instance;
>
>      /**
> -     * Computes the function \( \ln \Gamma(x) \) for \( x > 0 \).
> +     * Computes the function \( \ln \Gamma(x) \) for \( x &gt; 0 \).
>       *
>       * For \( x \leq 8 \), the implementation is based on the double
> precision
>       * implementation in the <em>NSWC Library of Mathematics
> Subroutines</em>,


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [4/4] commons-numbers git commit: Avoid "malformed HTML" javadoc error

Raymond DeCampo
How does MathJax interact with HTML entities?

My LateX is very rusty - is there a suitable escape sequence (like the \leq
used in other parts of the doc) that could be used instead?


On Tue, May 9, 2017 at 7:17 AM, Gilles <[hidden email]> wrote:

> On Tue, 09 May 2017 11:09:49 -0000, [hidden email] wrote:
>
>> Avoid "malformed HTML" javadoc error
>>
>
> -1
>
> This is not malformed HTML!  It is LateX (to be interpreted by MathJax).
>
> Regards,
> Gilles
>
>
>
>>
>> Project: http://git-wip-us.apache.org/repos/asf/commons-numbers/repo
>> Commit:
>>
>> http://git-wip-us.apache.org/repos/asf/commons-numbers/commit/851b17ec
>> Tree: http://git-wip-us.apache.org/repos/asf/commons-numbers/tree/
>> 851b17ec
>> Diff: http://git-wip-us.apache.org/repos/asf/commons-numbers/diff/
>> 851b17ec
>>
>> Branch: refs/heads/task_NUMBERS-33__Gamma
>> Commit: 851b17ece739245bc04f7f03dc20cfe4c0ea60a8
>> Parents: 8d2b162
>> Author: Stian Soiland-Reyes <[hidden email]>
>> Authored: Tue May 9 11:07:20 2017 +0100
>> Committer: Stian Soiland-Reyes <[hidden email]>
>> Committed: Tue May 9 12:09:40 2017 +0100
>>
>>
>> ----------------------------------------------------------------------
>>  .../src/main/java/org/apache/commons/numbers/gamma/Digamma.java    | 2
>> +-
>>  .../src/main/java/org/apache/commons/numbers/gamma/LogGamma.java   | 2
>> +-
>>  2 files changed, 2 insertions(+), 2 deletions(-)
>>
>> ----------------------------------------------------------------------
>>
>>
>>
>> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/
>> 851b17ec/commons-numbers-gamma/src/main/java/org/apache/
>> commons/numbers/gamma/Digamma.java
>>
>> ----------------------------------------------------------------------
>> diff --git
>>
>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/Digamma.java
>>
>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/Digamma.java
>> index a10f1df..32d7bf5 100644
>> ---
>>
>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/Digamma.java
>> +++
>>
>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/Digamma.java
>> @@ -47,7 +47,7 @@ public class Digamma {
>>       *
>>       * Some of the constants have been changed to increase accuracy
>> at the moderate
>>       * expense of run-time.  The result should be accurate to within
>> \( 10^{-8} \)
>> -     * relative tolerance for \( 0 < x < 10^{-5} \) and within \(
>> 10^{-8} \) absolute
>> +     * relative tolerance for \( 0 &lt; x &lt; 10^{-5} \)  and
>> within \( 10^{-8} \) absolute
>>       * tolerance otherwise.
>>       *
>>       * @param x Argument.
>>
>>
>> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/
>> 851b17ec/commons-numbers-gamma/src/main/java/org/apache/
>> commons/numbers/gamma/LogGamma.java
>>
>> ----------------------------------------------------------------------
>> diff --git
>>
>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/LogGamma.java
>>
>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/LogGamma.java
>> index 57146a2..e4fac6e 100644
>> ---
>>
>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/LogGamma.java
>> +++
>>
>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>> bers/gamma/LogGamma.java
>> @@ -34,7 +34,7 @@ public class LogGamma {
>>      private static final LogGamma1p LOG_GAMMA_1P = LogGamma1p.instance;
>>
>>      /**
>> -     * Computes the function \( \ln \Gamma(x) \) for \( x > 0 \).
>> +     * Computes the function \( \ln \Gamma(x) \) for \( x &gt; 0 \).
>>       *
>>       * For \( x \leq 8 \), the implementation is based on the double
>> precision
>>       * implementation in the <em>NSWC Library of Mathematics
>> Subroutines</em>,
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>
Reply | Threaded
Open this post in threaded view
|

Re: [4/4] commons-numbers git commit: Avoid "malformed HTML" javadoc error

Gilles Sadowski
On Tue, 9 May 2017 09:03:13 -0400, Raymond DeCampo wrote:
> How does MathJax interact with HTML entities?

Seems that javadoc8 breaks the build even before MathJax has the chance
to interpret the LaTeX code.

See this for a more complete answer:
   http://docs.mathjax.org/en/latest/tex.html

>
> My LateX is very rusty - is there a suitable escape sequence (like
> the \leq
> used in other parts of the doc) that could be used instead?

See reference above; there is "\lt" (defined by "MathJax", not LaTeX
IIUC).

Anyways, I think that we should try and use "{@code ...}" whenever the
"formula" is just stating inequalities between simple entities
(numbers).
[See the latest Javadoc changes in branch "task_NUMBERS-33_Gamma".]

Gilles

>
>
> On Tue, May 9, 2017 at 7:17 AM, Gilles <[hidden email]>
> wrote:
>
>> On Tue, 09 May 2017 11:09:49 -0000, [hidden email] wrote:
>>
>>> Avoid "malformed HTML" javadoc error
>>>
>>
>> -1
>>
>> This is not malformed HTML!  It is LateX (to be interpreted by
>> MathJax).
>>
>> Regards,
>> Gilles
>>
>>
>>
>>>
>>> Project:
>>> http://git-wip-us.apache.org/repos/asf/commons-numbers/repo
>>> Commit:
>>>
>>>
>>> http://git-wip-us.apache.org/repos/asf/commons-numbers/commit/851b17ec
>>> Tree: http://git-wip-us.apache.org/repos/asf/commons-numbers/tree/
>>> 851b17ec
>>> Diff: http://git-wip-us.apache.org/repos/asf/commons-numbers/diff/
>>> 851b17ec
>>>
>>> Branch: refs/heads/task_NUMBERS-33__Gamma
>>> Commit: 851b17ece739245bc04f7f03dc20cfe4c0ea60a8
>>> Parents: 8d2b162
>>> Author: Stian Soiland-Reyes <[hidden email]>
>>> Authored: Tue May 9 11:07:20 2017 +0100
>>> Committer: Stian Soiland-Reyes <[hidden email]>
>>> Committed: Tue May 9 12:09:40 2017 +0100
>>>
>>>
>>>
>>> ----------------------------------------------------------------------
>>>  .../src/main/java/org/apache/commons/numbers/gamma/Digamma.java    
>>> | 2
>>> +-
>>>  .../src/main/java/org/apache/commons/numbers/gamma/LogGamma.java  
>>> | 2
>>> +-
>>>  2 files changed, 2 insertions(+), 2 deletions(-)
>>>
>>>
>>> ----------------------------------------------------------------------
>>>
>>>
>>>
>>> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/
>>> 851b17ec/commons-numbers-gamma/src/main/java/org/apache/
>>> commons/numbers/gamma/Digamma.java
>>>
>>>
>>> ----------------------------------------------------------------------
>>> diff --git
>>>
>>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/Digamma.java
>>>
>>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/Digamma.java
>>> index a10f1df..32d7bf5 100644
>>> ---
>>>
>>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/Digamma.java
>>> +++
>>>
>>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/Digamma.java
>>> @@ -47,7 +47,7 @@ public class Digamma {
>>>       *
>>>       * Some of the constants have been changed to increase
>>> accuracy
>>> at the moderate
>>>       * expense of run-time.  The result should be accurate to
>>> within
>>> \( 10^{-8} \)
>>> -     * relative tolerance for \( 0 < x < 10^{-5} \) and within \(
>>> 10^{-8} \) absolute
>>> +     * relative tolerance for \( 0 &lt; x &lt; 10^{-5} \)  and
>>> within \( 10^{-8} \) absolute
>>>       * tolerance otherwise.
>>>       *
>>>       * @param x Argument.
>>>
>>>
>>> http://git-wip-us.apache.org/repos/asf/commons-numbers/blob/
>>> 851b17ec/commons-numbers-gamma/src/main/java/org/apache/
>>> commons/numbers/gamma/LogGamma.java
>>>
>>>
>>> ----------------------------------------------------------------------
>>> diff --git
>>>
>>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/LogGamma.java
>>>
>>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/LogGamma.java
>>> index 57146a2..e4fac6e 100644
>>> ---
>>>
>>> a/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/LogGamma.java
>>> +++
>>>
>>> b/commons-numbers-gamma/src/main/java/org/apache/commons/num
>>> bers/gamma/LogGamma.java
>>> @@ -34,7 +34,7 @@ public class LogGamma {
>>>      private static final LogGamma1p LOG_GAMMA_1P =
>>> LogGamma1p.instance;
>>>
>>>      /**
>>> -     * Computes the function \( \ln \Gamma(x) \) for \( x > 0 \).
>>> +     * Computes the function \( \ln \Gamma(x) \) for \( x &gt; 0
>>> \).
>>>       *
>>>       * For \( x \leq 8 \), the implementation is based on the
>>> double
>>> precision
>>>       * implementation in the <em>NSWC Library of Mathematics
>>> Subroutines</em>,
>>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: [hidden email]
>> For additional commands, e-mail: [hidden email]
>>
>>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [4/4] commons-numbers git commit: Avoid "malformed HTML" javadoc error

sebb-2-2
On 9 May 2017 at 14:28, Gilles <[hidden email]> wrote:

> On Tue, 9 May 2017 09:03:13 -0400, Raymond DeCampo wrote:
>>
>> How does MathJax interact with HTML entities?
>
>
> Seems that javadoc8 breaks the build even before MathJax has the chance
> to interpret the LaTeX code.
>
> See this for a more complete answer:
>   http://docs.mathjax.org/en/latest/tex.html

WHich says:

"Alternatively, you can use the HTML entities &lt;, &gt; and &amp; to
encode these characters so that the browser will not interpret them,
but MathJax will."


>>
>> My LateX is very rusty - is there a suitable escape sequence (like the
>> \leq
>> used in other parts of the doc) that could be used instead?
>
>
> See reference above; there is "\lt" (defined by "MathJax", not LaTeX IIUC).
>
> Anyways, I think that we should try and use "{@code ...}" whenever the
> "formula" is just stating inequalities between simple entities (numbers).
> [See the latest Javadoc changes in branch "task_NUMBERS-33_Gamma".]

+1

But that won't always be possible, in which case HTML entities can be used.

> Gilles
>
>
>>
>>
>> On Tue, May 9, 2017 at 7:17 AM, Gilles <[hidden email]>
>> wrote:
>>
>>> On Tue, 09 May 2017 11:09:49 -0000, [hidden email] wrote:
>>>
>>>> Avoid "malformed HTML" javadoc error
>>>>
>>>
>>> -1
>>>
>>> This is not malformed HTML!  It is LateX (to be interpreted by MathJax).

It *is* malformed HTML.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [4/4] commons-numbers git commit: Avoid "malformed HTML" javadoc error

Gilles Sadowski
On Tue, 9 May 2017 15:19:13 +0100, sebb wrote:

> On 9 May 2017 at 14:28, Gilles <[hidden email]> wrote:
>> On Tue, 9 May 2017 09:03:13 -0400, Raymond DeCampo wrote:
>>>
>>> How does MathJax interact with HTML entities?
>>
>>
>> Seems that javadoc8 breaks the build even before MathJax has the
>> chance
>> to interpret the LaTeX code.
>>
>> See this for a more complete answer:
>>   http://docs.mathjax.org/en/latest/tex.html
>
> WHich says:
>
> "Alternatively, you can use the HTML entities &lt;, &gt; and &amp; to
> encode these characters so that the browser will not interpret them,
> but MathJax will."

"browser" != "javadoc"

These entities are noisy when reading the _source_ Javadoc, even
more so when they are mixed with LaTeX; hence my suggestion to avoid
them in simple statements (the vast majority of Javadoc comments that
use "less than" or "greater than").

MathJax also provides the "\lt" macro (which at least looks like
LaTeX).

Gilles

>>>
>>> My LateX is very rusty - is there a suitable escape sequence (like
>>> the
>>> \leq
>>> used in other parts of the doc) that could be used instead?
>>
>>
>> See reference above; there is "\lt" (defined by "MathJax", not LaTeX
>> IIUC).
>>
>> Anyways, I think that we should try and use "{@code ...}" whenever
>> the
>> "formula" is just stating inequalities between simple entities
>> (numbers).
>> [See the latest Javadoc changes in branch "task_NUMBERS-33_Gamma".]
>
> +1
>
> But that won't always be possible, in which case HTML entities can be
> used.
>
>> Gilles
>>
>>
>>>
>>>
>>> On Tue, May 9, 2017 at 7:17 AM, Gilles
>>> <[hidden email]>
>>> wrote:
>>>
>>>> On Tue, 09 May 2017 11:09:49 -0000, [hidden email] wrote:
>>>>
>>>>> Avoid "malformed HTML" javadoc error
>>>>>
>>>>
>>>> -1
>>>>
>>>> This is not malformed HTML!  It is LateX (to be interpreted by
>>>> MathJax).
>
> It *is* malformed HTML.
>


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]