mathjax and latexmath support: differences to Asciidoc

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

mathjax and latexmath support: differences to Asciidoc

jvdh
hi list,
coming from Asciidoc I note an incompatible difference in how Asciidoctor handles embedded math.  specifically, in Asciidoc I have to use something like

//source code example
an inline equation like latexmath:[$y=x^2$] requires the latex equation delimiters as does a display equation like
[latexmath]
++++++++++++
\[
y = x^2
\]
++++++++++++
//source code example

for one, asciidoctor does not request inclusion of the latex equation delimites `$' and `\[' but
tolerates them in the case of display equations it seems: if I feed this into asciidoctor the display equation is rendered correctly via mathjax but the inline equation incorporates the `$' equation delimiters required by latex (which are needed if one postprocesses xml output with dblatex etc.) into the rendered formula. I think it would be very good if the `$' is tolerated as well (i.e. eliminated before rendering the equation) so that one could format a given document with asciidoc as well as asciidoctor (whether the latex delimiters should be enforced to guarantee compatibility is another question ...)

another observation: the mathjax rendering has a minor problem it seems: if you switch the mathjax settings (crtl-click on equation in the html page) mathsettings ->zoomtrigger->hover and move the mouse over the equation the equation is correctly zoomed but the bounding box is wrong (equation extends beyond right margin of box).

can someone confirm these issues?

thank you
joerg
Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

mojavelinux
Administrator
joerg,

I acknowledge there are some differences in this area between AsciiDoc and Asciidoctor in this area. For the most part, these are conscious choices. In particular, I found it quite absurd that AsciiDoc Python is requiring authors to use both the AsciiMath / LaTeX delimiters *and* the macro or block syntax. We have complete control over the output, so there's no reason to make the author add the extra delimiters. The converter will add them.

Therefore, you can write the snippet as follows:

----
An inline equation like latexmath:[y=x^2].

.A block equation
[latexmath] 
++++
y = x^2 
++++
----

The delimiters are added properly in the HTML5 (html5) and LaTeX (latex) backends. (We are still working on getting math working correctly in the DocBook backend, but it shouldn't require a change to the source document).

If you insist on using the delimiters, one way to solve it is to simply use the pass macro and block.

----
An inline equation like pass:[\(y=x^2\)].

.A block equation
++++
y = x^2
++++
----

Note that we configure MathJax to use \( and \) as delimiters around inline equations in LaTex. See https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor.rb#L333-L341. (This solves parsing problems).

While we generally try to be compatible with AsciiDoc Python, this is one of the areas where that is simply not a goal. If you need the same source to work with AsciiDoc Python, then it will be necessary to tap into its customization capabilities using a configuration file for compatibility. For a starting point, see https://github.com/asciidoctor/asciidoctor/blob/master/compat/asciidoc.conf.

I do recognize that the delimiters are not tolerated in the inline equations. For example:

----
latexmath:[\(y=x^2\)]
----

Let's discuss whether those should be stripped to be consistent with blocks in the following issue: https://github.com/asciidoctor/asciidoctor/issues/1339
 

another observation: the mathjax rendering has a minor problem it seems: if you switch the mathjax settings (crtl-click on equation in the html page) mathsettings ->zoomtrigger->hover and move the mouse over the equation the equation is correctly zoomed but the bounding box is wrong (equation extends beyond right margin of box).

This sounds like a MathJax issue. Aside from putting the equation on the page, we don't really do any layout or rendering. There are plans to upgrade MathJax in 1.5.3. See https://github.com/asciidoctor/asciidoctor/issues/1329. In the meantime, you could change the version in the output document and see if it resolves the issue.

Cheers,

-Dan


--
Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

jvdh
dan,

thanks for your reply. I agree with your view that it should not be required to use latex delimiters as well as the/macro/block "delimiters"/syntax, so asciidoctor is "nicer" here in not demanding them. however, I feel it is of substantial importance to maintain compatibility  to asciidoc also in the future as far as possible (which of course implies the possibility that asciidoc is adjusted accordingly I presume). so asciidoctor should in my view at least _allow_ to use an asciidoc compatible syntax.

the way asciidoc currently handles latexmath/mathjax it would suffice if display/block equations can be delimited with \[, \] (this, actually, is already the case) and inline equations could be delimited with \(, \). these delimiters are correctly handled by asciidoc, but -- as you point out -- asciidoctor right now does not do this for inline equations. --

regarding the mathjax zoom/bounding box problem: it might very well be a mathjax issue, but actually  `asciidoc' generated html of the same display equation (quering https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML to render th mathjax stuff), e.g., does show the bounding box just fine .... just to let you know.

best regards,
joerg
Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

mojavelinux
Administrator
On Mon, May 11, 2015 at 7:10 AM, jvdh [via Asciidoctor :: Discussion] <[hidden email]> wrote:
inline equations could be delimited with \(, \). these delimiters are correctly handled by asciidoc, but -- as you point out -- asciidoctor right now does not do this for inline equations. --

This is the crux of the issue.

Note that it is possible to fix AsciiDoc Python so that it adds the missing delimiters. I think we should pursue that. I tried to solve it in the compatibility file, but I can't get access to the body text to do the check.
 

regarding the mathjax zoom/bounding box problem: it might very well be a mathjax issue, but actually  `asciidoc' generated html of the same display equation (quering https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML to render th mathjax stuff), e.g., does show the bounding box just fine .... just to let you know.

We'll need more details to address this. In particular:

1. Sample math code
2. Which browsers are affected
3. A screenshot so that we can visualize what's wrong

(However, I'm pretty sure that your response reveals the problem. Asciidoctor uses a fixed version of MathJax, whereas AsciiDoc Python is loading the latest version. Since we're planning the upgrade already, this will be solved if it was a problem that was solved in MathJax 2.5.

Cheers,

-Dan 


--
Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

jvdh
On Tue, 12 May 2015 01:26:32 +0200, mojavelinux [via Asciidoctor ::  
Discussion] <[hidden email]> wrote:

>
>
> On Mon, May 11, 2015 at 7:10 AM, jvdh [via Asciidoctor :: Discussion] <
> [hidden email]> wrote:
>
>> inline equations could be delimited with \(, \). these delimiters are
>> correctly handled by asciidoc, but -- as you point out -- asciidoctor  
>> right
>> now does not do this for inline equations. --
>>
>
> This is the crux of the issue.
>
> Note that it is possible to fix AsciiDoc Python so that it adds the  
> missing
> delimiters. I think we should pursue that. I tried to solve it in the
> compatibility file, but I can't get access to the body text to do the  
> check.

thanks for pursuing this. as I said, I believe it will benefit both  
asciidoc as well as asciidoctor if compatibility is kept as high as  
possible.

>
>
>>
>> regarding the mathjax zoom/bounding box problem: it might very well be a
>> mathjax issue, but actually  `asciidoc' generated html of the same  
>> display
>> equation (quering
>> https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML 
>> to
>> render th mathjax stuff), e.g., does show the bounding box just fine  
>> ....
>> just to let you know.
>>
>
> We'll need more details to address this. In particular:
>
> 1. Sample math code
> 2. Which browsers are affected
> 3. A screenshot so that we can visualize what's wrong
>
> (However, I'm pretty sure that your response reveals the problem.
> Asciidoctor uses a fixed version of MathJax, whereas AsciiDoc Python is
> loading the latest version. Since we're planning the upgrade already,  
> this
> will be solved if it was a problem that was solved in MathJax 2.5.

I agree, that one should first wait and see whether the problem goes away  
after upgrading mathjax. actually, as I recall, the `latest' mathjax link  
is the one the mathjax guys themself recommend on their webpage, rather  
than using some static version. would that not be good to use for  
asciidoctor as well?

best regards,

joerg

>
> Cheers,
>
> -Dan
>
>


--
Using Opera's revolutionary email client: http://www.opera.com/mail/
Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

mojavelinux
Administrator

On Tue, May 12, 2015 at 1:38 AM, jvdh [via Asciidoctor :: Discussion] <[hidden email]> wrote:
actually, as I recall, the `latest' mathjax link  
is the one the mathjax guys themself recommend on their webpage, rather  
than using some static version. would that not be good to use for  
asciidoctor as well?

While tempting, this is a very dangerous source of incompatibility. We don't want published documents that are working fine to all of a sudden stop working. If you link to a remote resource, it's very important that it be stable (assuming, of course, the CDN doesn't disappear). It also gives us a chance to test before we commit to a new version.

I already notice an alignment issue when using the latext MathJax with the reveal.js backend, so this safeguard is more than theory :)

Cheers,

Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

mojavelinux
Administrator
In reply to this post by jvdh
Having said that, there is an open issue to allow the document to set the version of MathJax. We just haven't done it yet. That way, you aren't stuck with the version we're currently using.


Cheers,

-Dan

On Tue, May 12, 2015 at 6:45 PM, Dan Allen <[hidden email]> wrote:

On Tue, May 12, 2015 at 1:38 AM, jvdh [via Asciidoctor :: Discussion] <[hidden email]> wrote:
actually, as I recall, the `latest' mathjax link  
is the one the mathjax guys themself recommend on their webpage, rather  
than using some static version. would that not be good to use for  
asciidoctor as well?

While tempting, this is a very dangerous source of incompatibility. We don't want published documents that are working fine to all of a sudden stop working. If you link to a remote resource, it's very important that it be stable (assuming, of course, the CDN doesn't disappear). It also gives us a chance to test before we commit to a new version.

I already notice an alignment issue when using the latext MathJax with the reveal.js backend, so this safeguard is more than theory :)

Cheers,




--
Reply | Threaded
Open this post in threaded view
|

Re: mathjax and latexmath support: differences to Asciidoc

jvdh
On Wed, 13 May 2015 02:45:11 +0200, mojavelinux [via Asciidoctor ::  
Discussion] <[hidden email]> wrote:

>
>
> Having said that, there is an open issue to allow the document to set the
> version of MathJax. We just haven't done it yet. That way, you aren't  
> stuck
> with the version we're currently using.
>
> See https://github.com/asciidoctor/asciidoctor/issues/761.

that sounds reasonable (I was on the verge of proposing something like  
this ;-)). good to know that you are considering it.

best wishes,

joerg

>
> Cheers,
>
> -Dan
>
> On Tue, May 12, 2015 at 6:45 PM, Dan Allen <[hidden email]> wrote:
>
>>
>> On Tue, May 12, 2015 at 1:38 AM, jvdh [via Asciidoctor :: Discussion] <
>> [hidden email]> wrote:
>>
>>> actually, as I recall, the `latest' mathjax link
>>> is the one the mathjax guys themself recommend on their webpage, rather
>>> than using some static version. would that not be good to use for
>>> asciidoctor as well?
>>>
>>
>> While tempting, this is a very dangerous source of incompatibility. We
>> don't want published documents that are working fine to all of a sudden
>> stop working. If you link to a remote resource, it's very important  
>> that it
>> be stable (assuming, of course, the CDN doesn't disappear). It also  
>> gives
>> us a chance to test before we commit to a new version.
>>
>> I already notice an alignment issue when using the latext MathJax with  
>> the
>> reveal.js backend, so this safeguard is more than theory :)
>>
>> Cheers,
>>
>> -Dan
>>
>>
>> --
>> Dan Allen | http://google.com/profiles/dan.j.allen
>>
>
>
>


--
Using Opera's revolutionary email client: http://www.opera.com/mail/