Latex equation support in the documentation created by generate_html package

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

Latex equation support in the documentation created by generate_html package

TrucomanX XnamocurT
I am writing to call your attention and ask for your comments about a pacth/improved that I am proposing.

https://savannah.gnu.org/patch/?9009

I like propose to use JavaScript to give Latex equation support
in texinfo source documentation created by generate_html package.

the result can be seen in the next page:

http://nongnu.org/bsltl/bsltl_refman/bsltl/package_doc/index.html

Please I would to know your comments about this proposal.

Fernando
Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

siko1056
If the documentation is always intended to be read online, is there a reason not to use MathJax?

https://en.wikipedia.org/wiki/JsMath

JsMath seems to be no longer actively developed and MathJax is very easy to use as well.

I currently work on a Matlab compatible publish function https://github.com/siko1056/octave-publish/blob/master/__publish_html_output__.m where just the equations in $ $ signs must be present + a script include and the output looks more "natural" than the one of JsMath.

Best,
Kai
Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

Michael Godfrey


On 05/24/2016 08:21 PM, siko1056 wrote:

> If the documentation is always intended to be read online, is there a reason
> not to use MathJax?
>
> https://en.wikipedia.org/wiki/JsMath
>
> JsMath seems to be no longer actively developed and MathJax is very easy to
> use as well.
>
> I currently work on a Matlab compatible publish function
> https://github.com/siko1056/octave-publish/blob/master/__publish_html_output__.m
> where just the equations in $ $ signs must be present + a script include and
> the output looks more "natural" than the one of JsMath.
>
> Best,
> Kai
>
MathJax is the obvious choice. This has been discussed to some extent. If
you want to help make it happen, you are more than welcome.


Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

TrucomanX XnamocurT
In reply to this post by TrucomanX XnamocurT
Hi siko1056
I had not
used mathjax,
It seems to be a good option.
I'll see as used, if you have some tips, appreciate your help,
Seeking something that only need to add some lines to the head of the html files.
Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

Oliver Heimlich
Am 28. Mai 2016 21:23:00 MESZ, schrieb TrucomanX XnamocurT <[hidden email]>:
>Hi siko1056
>I had not used mathjax,
>It seems to be a good option.
>I'll see as used, if you have some tips, appreciate your help,
>Seeking something that only need to add some lines to the head of the
>html
>files.

Hi,

I guess that I have mentioned it already, but my experience with math in HTML is that MathJax produces poor quality math rendering on other websites.

AFAIK, the only good math rendering in HTML can be achieved with MathML in browsers that support it.

Since MathJax should be able to use native MathML rendering if available, this hopefully can be fixed by careful configuration of MathJax.

Compatibility with the @math Texinfo macro would be appreciated, but I'm not sure if that is possible. If @math uses simple <em>...</em> markup we cannot identify this as math content in the final HTML.

Oliver

Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

TrucomanX XnamocurT
In reply to this post by TrucomanX XnamocurT
One thing that we should have in consideration is that

jsMath has a weight 10MB
MathJax has a weight 33MB

Because this, it is hard to think in a off-line version of documentation for each package.

Maybe, because that jsMath is a older version can be cleaned (discarding some fonts).

By other side, as says Oliver, MathJax shows more complete, supporting MathML.
Bun I don't see a poor quality without MathML.  What parts are failing in MathJax?

Fernando
Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

Oliver Heimlich
Am 29. Mai 2016 04:37:50 MESZ, schrieb TrucomanX XnamocurT <[hidden email]>:

>One thing that we should have in consideration is that
>
>jsMath has a weight 10MB
>MathJax has a weight 33MB
>
>Because this, it is hard to think in a off-line version of
>documentation
>for each package.
>
>Maybe, because that jsMath is a older version can be cleaned
>(discarding
>some fonts).
>
>By other side, as says Oliver, MathJax shows more complete, supporting
>MathML.
>Bun I don't see a poor quality without MathML.  What parts are failing
>in
>MathJax?
>
>Fernando

We could use the MathJax CDN and would not have to host the full 33MB ourselves. Also, this would work in "offline" documentation if an Internet connection was available.  Otherwise, the user would see plain TeX equations.

I have observed rendering problems in my browser with the Feynman lectures. All math content seems to have a wrong font, font size, and/or font weight. I couldn't identify the root cause yet, but I guess that it is caused by wrong configuration.

Another approach to equation support in HTML would be to produce HTML plus MathML. However, the final page would not work in certain browsers. Also we would have to find some preprocessor that could produce the MathML from TeX equations during makeinfo.

Maybe I will try and experiment with MathJax and give it another try next week.

Oliver

Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

Michael Godfrey
In reply to this post by Oliver Heimlich


On 05/29/2016 03:25 AM, Oliver Heimlich wrote:
> I guess that I have mentioned it already, but my experience with math in HTML is that MathJax produces poor quality math rendering on other websites.
This is quite different from my experience. For an extremely high
quality use of MathJax see:
http://www.feynmanlectures.caltech.edu/

It is also useful to point out that MathJax, as in the example above,
supports viewing
on PC screens, tablets, and phones. Octave documentation that provides
these options
will be increasingly important as Corbin Champion's port to Android
indicates.

Michael



Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

siko1056
Dear Fernando,

I can hardly add anything to this conversation.

* No 30 MB Javascript needs to be included, too many people are 24/7 online these days, use the CDN.
* There should be a PDF version generated by makeinfo attached to a package for reading offline / print.
* I guess rendering issues will be solved with upcoming versions (too many projects use MathJax for this not to happen), we have to follow the changes.
* My biggest concern is the texinfo markup language. As Oliver explained @math expands to some emphasize, that would eat brackets {}, and it would require something like @verb{$My math$} to get the LaTeX through makeinfo or texi2pdf.


I uploaded a modified part of the Octave documentation, where the effort of including MathJax should become obvious

Exponents_and_Logarithms_mathjax.html

Looking at the source, the only lines I added to the <head> are

-------------------------------
<script type="text/x-mathjax-config"> MathJax.Hub.Config({ tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]} }); </script><script type="text/javascript" async src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML"> </script>-------------------------------

The first five lines only ensure $ $ to be interpreted as inline Math, as many users familiar to LaTeX are used to this syntax, otherwise only three lines of code would be needed. The last thing I inserted was a more verbose exponential function formula:

$e^x = \lim\limits_{n\rightarrow\infty}\left(1+\dfrac{x}{n}\right)^{n}$

That's all and in Firefox and Chrome everything looks great.

Best,
Kai
Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

Oliver Heimlich
On 29.05.2016 22:49, siko1056 wrote:

> Dear Fernando,
>
> I can hardly add anything to this conversation.
>
> * No 30 MB Javascript needs to be included, too many people are 24/7 online
> these days, use the CDN.
> * There should be a PDF version generated by makeinfo attached to a package
> for reading offline / print.
> * I guess rendering issues will be solved with upcoming versions (too many
> projects use MathJax for this not to happen), we have to follow the changes.
> * My biggest concern is the texinfo markup language. As Oliver explained
> @math expands to some emphasize, that would eat brackets {}, and it would
> require something like @verb{$My math$} to get the LaTeX through makeinfo or
> texi2pdf.
>
>
> I uploaded a modified part of the Octave documentation, where the effort of
> including MathJax should become obvious
>
> Exponents_and_Logarithms_mathjax.html
> <http://octave.1599824.n4.nabble.com/file/n4677253/Exponents_and_Logarithms_mathjax.html>  
>
Kai,

thanks for providing an example. Please find attached the same example,
but with HTML5 (MathML is part of HTML5) instead of MathJax. I have
changed the doctype to <!DOCTYPE HTML> and converted the math from Tex
syntax into a <math> structure (which could be automated by some tool
and could be integrated into Texinfo).

The main drawback of MathML would be that it is only supported by Gecko
browsers (however, this is not going to change if everybody prefers
MathJax over MathML). The main drawback of MathJax is that it requires
Javascript.


Back to MathJax:

I'd like to keep additional “LaTeX” fonts out of the website. These make
sense in a printed document, but on a low definition device (most
computer monitors) they add to the problem of rendering the characters
and also don't fit into the sans-serif fonts that we currently use.

Also I dislike that MathJax increases the font-size by 13% in your
example. I found out that this comes from a feature that tries to match
font heights (and does a bad job IMHO).

I could achieve a better result in MathJax for all renderers (see
screenshot attached) except SVG with the following CSS:

/* Common HTML and Preview HTML renderers do not support styles */
.MJXc-TeX-main-R, .MJXp-math {font-family: inherit !important}
.MJXc-TeX-math-I {font-family: inherit !important; font-style: italic;}


… and extended load script:

  MathJax.Hub.Config({
    tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]},
    /* don't download LaTeX fonts */
    webfont: null,

    /*
        don't increase font size of math in contrast to regular text
        and use custom fonts from the surrounding text
     */
    CommonHTML: {
        matchFontHeight: false,
        mtextFontInherit: true
    },
    "HTML-CSS": {
        matchFontHeight: false,
        mtextFontInherit: true,
        styles: {
            ".mi, .mn, .mo": {
                "font-family": "inherit !important"
            }
        }
    },
    NativeMML: {
        matchFontHeight: false,
        styles: {
            "math": {
                /* This affects upright characters and numbers only */
                /* I don't know how to affect other glyphs */
                "font-family": "inherit"
            }
        }
    },
    PreviewHTML: {
        mtextFontInherit: true
    }

    });


Best
Oliver

Exponents and Logarithms MathML.html (19K) Download Attachment
mathjax-with-custom-fonts.png (41K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Latex equation support in the documentation created by generate_html package

Oliver Heimlich
In reply to this post by siko1056
On 29.05.2016 22:49, siko1056 wrote:
> * My biggest concern is the texinfo markup language. As Oliver explained
> @math expands to some emphasize, that would eat brackets {}, and it would
> require something like @verb{$My math$} to get the LaTeX through makeinfo or
> texi2pdf.

FYI, I will try to improve this in Texinfo.
http://lists.gnu.org/archive/html/bug-texinfo/2016-05/msg00045.html