search

miyuchina / mistletoe

A fast, extensible and spec-compliant Markdown parser in pure Python.
MIT License
818 stars 118 forks source link

Latex ams packages #207

Closed chrisbresten closed 8 months ago

chrisbresten commented 9 months ago

This adds some ubiquitously used packages to the latex document header if there is a math environment parsed. mathjax automatically uses these if it detects features from them present in the math environment. So adding these keeps behavior consistent with mathjax, and general community expectations for people who write math in latex.

Adding them selectively(the way mathjax functions) doesn't seem to have enough benefit to justify the added lines of code in this case. I think mathjax must do it to keep memory footprint lower as a browser app.

coveralls commented 9 months ago

Coverage Status

coverage: 94.166% (+0.004%) from 94.162% when pulling a1c76587817ae04f2e9cf6f4d374a985815759d6 on chrisbresten:latex_ams_packages into b911e5b64a98d537bb44a0212cbf8fa708d37d48 on miyuchina:master.

pbodnar commented 9 months ago

@chrisbresten, LGTM [^1]. Just for reference, do you think you can add a link to why just these 3 ams* packages (and not some others)?

[^1]: With the exception of flake8 warnings (flake8 extension for vscode - to see the issues upon opening a file).

chrisbresten commented 9 months ago

These three packages plus default latex mathmode form the baseline standard math environment that we use in the math community. This convention is reflected in mathjax and katex. neither actually use these packages as they are not latex, rather an emulation of a subset of latex with focus on the math environment. There may be other packages safe to include but you run into the issue of clobbering commands, and potential headaches with dependencies that become less predictable with regards to package manager and distribution idiosyncrasies as you get more adventurous. So there is risk in adding the kitchen sink that warrants more caution. These three dont have those problems as they are from the same org and safe to assume anyone including mathmode will have them in any kind of environment forseeable

pbodnar commented 9 months ago

OK, yet you haven't provided any links, so I've done a little research myself and here come my additional questions for you. :)

  1. Pages here and here say that amsfonts is automatically included by amssymb. So it is probably rather a "widespread convention" that you specify usage of amsfonts explicitly, isn't it?
  2. I can see that this package named amsthm is also relatively popular. Yet again, from you experience, you can probably tell better than me whether it is worth (not) including it as well.
chrisbresten commented 9 months ago

OK, yet you haven't provided any links, so I've done a little research myself and here come my additional questions for you. :)

  1. Pages here and here say that amsfonts is automatically included by amssymb. So it is probably rather a "widespread convention" that you specify usage of amsfonts explicitly, isn't it?
  2. I can see that this package named amsthm is also relatively popular. Yet again, from you experience, you can probably tell better than me whether it is worth (not) including it as well.

amsthm introduces a popular environment/macro to latex that is used for declaration of theorems. It will not add any functionality unless there is markup syntax added that renders to it.

The packages i included are to keep math environment behavior in the latex documents consistent with mathjax behavior. i was making the case that adding these three packages doesnt introduce any risk of breaking anything or alienating any users by including a package they dont have when they dont need it. there are other packages partially emulated in mathjax that might be worth including but i didnt include them because i am not 100% on that. It may be worth detecting their use before including them. I assumed you were referencing this small subset of packages emulated by mathjax. In those terms i am not operating off of referenced second hand knowledge in this decision, so there is no link for me to reference.

In terms of the greater universe of latex packages i can reference the mathjax doc: https://docs.mathjax.org/en/latest/input/tex/macros/index.html

pbodnar commented 8 months ago

...

amsthm introduces a popular environment/macro to latex that is used for declaration of theorems. It will not add any functionality unless there is markup syntax added that renders to it.

Yeah, that is exactly what I've expected.

...I assumed you were referencing this small subset of packages emulated by mathjax.

Just to clarify, I was originally referencing the 3 LaTeX packages added by you, i.e. amsmath, amsfonts (as I noted, apparently transitively included by the last one) and amssymb. Apart from that, amsthm caught my attention later on. Without the aspiration to match them all to MathJax exactly.

... In terms of the greater universe of latex packages i can reference the mathjax doc: https://docs.mathjax.org/en/latest/input/tex/macros/index.html

Great, this actually does help to make a better picture of the MathJax <-> LaTeX (TeX) relations. 👍 On that page, they say that MathJax's ams "extension" gets autoloaded and the extension is described as The ams extension implements AMS math environments and macros, and macros for accessing the characters in the AMS symbol fonts. So this most probably covers the 3 discussed packages.

That being said, the 3 packages seem to be optimal, so I think I can safely accept your changes, thank you.