search

ggrossetie / asciidoctor-web-pdf

Convert AsciiDoc documents to PDF using web technologies
https://asciidoctor.org
MIT License
443 stars 90 forks source link

Create an Asciidoctor Postprocessor for MathJax #230

Open henriette-einstein opened 4 years ago

henriette-einstein commented 4 years ago

At the moment, formulas are converted with MathJax by embedding and configuring the MathJax scripts in the HTML page.

Another option would be to create an Asciidoctor post processor that does the MathJax processing during the generation phase. That could possibly enhance the performance and testability.

If you are interested, I can try to write such an extension for this project.

ggrossetie commented 4 years ago

That's a good idea but you should probably join effort with @djencks on https://gitlab.com/djencks/asciidoctor-mathjax.js

I didn't had the chance to give it a try yet but I would be great if we could use this extension with Asciidoctor Web PDF (it might already be the case).

djencks commented 4 years ago

@djencks/asciidoctor-mathjax works fine with @djencks/antora-pdf, I'd expect it to work with asciidoctor web pdf but I haven't tried that recently.

henriette-einstein commented 4 years ago

That is perfect! I will give it a try!

henriette-einstein commented 4 years ago

It did not work immediatelly. I have submitted an issue for @djencks.

https://gitlab.com/djencks/asciidoctor-mathjax.js/-/issues/7

But it - to me - actually looks like it is not an error in @djencks code.

henriette-einstein commented 4 years ago

@djencks Your plugin works perfect now! Here a sample that I created with

asciidoctor-pdf -r @djencks/asciidoctor-mathjax math.adoc

math.pdf

ggrossetie commented 4 years ago

Pretty neat!

I wonder if it would be possible to disable client-side MathJax when an extension already did all the work "server-side". Currently we are using the stem attribute as an hint to enable "client-side" MathJax. One solution could be to remove this attribute but I don't think it's a good idea (it might have side effects). So maybe the extension could set an attribute named stem-server-side?

What do you think?

henriette-einstein commented 4 years ago

That is a very good idea. When I run asciidoctor with the extension, the MathJax library is still included as a script in the resulting HTML, even though it is not used anymore. That increases the load-time of the page and possibly also has other unwanted results. For example, what happens, when I try to embed the HTML in an ebook (even though I am not sure that ebook readers can render SVG).

henriette-einstein commented 4 years ago

Overall I think, going with the plugin will be preferable to dynamic rendering with a script. Maybe it would be better to include the plugin in asciidoctor.js directly as a default and get rid of the MathJax scripts.

ggrossetie commented 4 years ago

Not sure, we should definitely make sure that we provide a good integration with extensions but I don't think we should get rid of the MathJax client side. For instance, I'm creating a browser-compatible version of this converter: https://github.com/Mogztter/asciidoctor-pdf.js/pull/228, and if we remove the MathJax scripts then stem will not work at all in this context. You might also want to use the client-side rendering while using the --preview option. In short, I think the "client-side" is still relevant in some scenarios and works in both a Node environment and a browser environment.

djencks commented 4 years ago

I got into all this because Antora doesn't actually include references to the MathJax client side libraries and wondered why my stem wasn't rendering. So, isn't the client side asciidoctor.js support a template issue, now presumably made more tractable by the enhanced template support?

henriette-einstein commented 4 years ago

It would probably be easy to add a new Asciidoctor option nostem that would could tell the default template not to render the client side libraries. Then the user could decide whether to include the script in the resulting HTML if she uses the preprocessor.

ggrossetie commented 4 years ago

In my mind, the stem attribute tells us to enable the feature but it does not tell us how to fulfill this request. If nostem is present then we should disable this feature. Where it gets confusing is that we have a built-in support with a client-side implementation. But we could also provide a built-in support with a server-side implementation. In Asciidoctor (Ruby) we are using a client-side implementation because we don't want to add additional dependencies in the core processor.

We do have the same situation for syntax highlighting where you can do it server-side or client-side. To some extend, the same goes for icons where you can resolve the icons server-side (ie. output inline SVG) or client-side using JavaScript and/or a font.

For syntax highlighting we have a nice API where you can indicate if your implementation is running client-side or server-side. I think Asciidoctor (Ruby) should provide an API for the stem and icon built-in features. It could provide a default client-side implementation that could be replaced by a server-side implementation using the API. In my opinion, that's how we should do it.

nostem is a good (temporary) solution with the assumption is that stem is client-side (which is true today but might not be true tomorrow). Arguably stem-server-side is also a temporary solution but the main benefit is that the users don't have to explicitly define this attribute. It's a contract between Asciidoctor MathJax and Asciidoctor Web PDF. So when a better solution becomes available in Asciidoctor (Ruby) we can then update our tools and it should be seamless for the users.

What do you think?

henriette-einstein commented 4 years ago

In my opinion too, Asciidoctor should provide an API which can be used to replace the client-side stuff with server side rendering. However, nobody knows how long that may take.

For the time being, the stem-server-side attribute could help with Asciidoctor Web PDF. I try to render Asciidoctor files with other rendering engines (Antennahouse, PrinceXML) and not all of them support Javascript processing. On the other hand, their feature-set is much closer or even exceeds the standard. I hope - and am quite sure - that PagedJS will catch up quickly.

https://print-css.rocks is starting to reference PagedJS in their lessons, but there are only very few results yet (e.g. https://print-css.rocks/lesson/lesson-hyphenation)

djencks commented 4 years ago

I very much like the idea of a server side api for stem. In e.g. asciidoctor-mathjax having to use a tree processor and search for the stem blocks is pretty much ridiculous.