Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve mathematics capabilities for authors #70

Open
SteelWagstaff opened this issue Jul 31, 2022 · 2 comments
Open

Improve mathematics capabilities for authors #70

SteelWagstaff opened this issue Jul 31, 2022 · 2 comments
Labels

Comments

@SteelWagstaff
Copy link
Member

SteelWagstaff commented Jul 31, 2022

As an author, I want to be able to include mathematical expressions in my text using syntax that is familiar to me and have these expressions produce accessible math in the browser. I also want these math expressions to render atttractively for readers of export files produced from my book (i.e. EPUB and PDF files).

Expectations:

  1. Users should be able to input LaTeX using the delimiters that they are accustomed to using (and not be forced to use [latex] shortcodes). For example, Pressbooks should recognize \( ... \) and \[...\] as math delimiters and should provide some kind of option for the $ character. See https://docs.mathjax.org/en/latest/input/tex/index.html and Add support for additional LaTeX delimiters #18
  2. Users should be able to define TeX macros and have these be added to their MathJax configuration. See http://docs.mathjax.org/en/latest/tex.html#defining-tex-macros and http://docs.mathjax.org/en/latest/configuration.html#local-config-files and Add ability to support user-added LaTeX Macros #16
  3. Users should be able to include automatic numbering for their equations. See https://docs.mathjax.org/en/latest/input/tex/eqnumbers.html and [Feature] Add support for equation numbering #32. Automatic numbering should work in the webbook and exports.
  4. We should provide support for some of the most popular/commonly used TeX and LaTeX extensions. See https://docs.mathjax.org/en/latest/input/tex/extensions.html and Investigate MathJax support for other desired/additional packages (like polynom) #28
  5. Users should be able to input MathML and have it be rendered in the webbook and export files. When they input MathML in the text editor, it should not be altered or destroyed when switching to the visual editor.
  6. Users should be able to input ASCIIMath markup (http://asciimath.org/).

See https://www.princexml.com/forum/topic/4594/support-for-mathjax-3 for an exciting development re: Prince.

For EPUBs, see https://docs.mathjax.org/en/v2.7-latest/misc/epub.html + https://manual.calibre-ebook.com/typesetting_math.html + https://www.peterkrautzberger.org/0129/

See also electricbookworks/electric-book#198 for implementation in a book publishing tool based on Jekyll, a popular static site generation tool.

@SteelWagstaff SteelWagstaff changed the title Update Pressbooks MathJax Improve mathematics capabilities for authors Feb 3, 2023
@SteelWagstaff
Copy link
Member Author

Feedback from former math professor:

As an author, I want to be able to include mathematical expressions in my text using syntax that is familiar to me and have these expressions produce accessible math in the browser. I also want these math expressions to render atttractively for readers of export files produced from my book (i.e. EPUB and PDF files).

Yes, absolutely! You have to understand the ubiquity of TeX/LaTeX in the math/physics/computer science literature: it is the standard, it is used by everyone. It is a markup language, to be sure, and perhaps many humans don't like markup languages ... but every math/physics/CS professional is comfortable with this and if you make it available to them (maybe wrapped in a GUI like PB ... although I like to think that since they already know at least one markup language, other text-based interfaces will also be easy to learn) they will instantly be able to produce texts for their teaching and scholarship.

OK, perhaps I should back off a tiny bit: math/physics/CS people who are a little older -- maybe 50s and up? -- might have less familiarity with TeX, as perhaps who were trained in less research-oriented environments. Still, a huge percentage of such STEM folks will be fluent in TeX. Additionally, I've had my students at CSU-Pueblo write in TeX (an early open pedagogy project I did, writing a collaborative textbook using MediaWiki) and they were able to do it instantly -- during the semester of that open ped project, I got exactly zero questions about the TeX part of the project!

So if TeX is available in PB, not only will the great majority of math/physics/CS folks instantly be able to use it, but also others will be able to come on board quickly!

  1. Users should be able to input LaTeX using the delimiters that they are accustomed to using (and not be forced to use [latex] shortcodes). For example, Pressbooks should recognize ( ... ) and [...] as math delimiters and should provide some kind of option for the $ character.

I do think this is important. People have files of handouts that they've built for years which they want to be able to import into PB by just copying and pasting. Or if something is in PB, they might want to copy-paste it into a LaTeX file to use in a standalone handout or test sheet or something. It would be great if that were possible without having to monkey with the delimiters!

I would normally say it isn't that big a deal since those folks probably use an editor which could do search-replace to fix the delimiters ... but TeX uses an annoying syntax for delimiters so that is not as easy as it seems! Certainly if someone is used to using (, ), [, and ] , then it will be easy just to use string replacement to go back and forth to an environment which uss [latex] shortcodes, but most folks I know use $ and $$ instead.... Add to that the fact that "[latex]" just looks clunky and large and as if one is shoe-horning equations into an environment where they aren't natively supported (which, ok, is close to the truth, but no need to rub it in!). Whereas discrete delimiters like any of the ones used in TeX make the equations seem more natural.

So the only backup solution would be to have some sort of tool which parses code on both sides to translate delimiters. But because of the annoying TeX syntax, this is actually not a lot of fun. It's a bit like parsing HTML: seems easy -- just look for tags with "<" and ">" ... but then you think about it and realize how annoying it wil actually be....

  1. Users should be able to define TeX macros and have these be added to their MathJax configuration.

This is absolutely vital and no one will use LaTeX in PB without it. Fortunately, it should be quite simple, technically, because of how MathJax implements macro definition.

  1. Users should be able to include automatic numbering for their equations....

Yeah, I like this. ...It does open a whole kettle of fish, though: if folks are going to reference equations, they might want to use similar functionality to reference sections, numbered theorems and other LaTeX environments ... will those be available? .. as an author, I use them as much, if not more, than bare numbered equations. And it does seem like a similar mechanism.
In LaTeX, such things are handled by running LaTeX twice on the same source file ... so there are presumably implementation complications that would ensue. E.g., also, what about equations numbered in another page ... would that other page have to be processed as if it were to be displayed, so equations would all be numbered, before the selected page was displayed?

These are all desirable things, though, but I don't know how much work they would be to implement, and what the gain/pain ratio would be.

You know, another thing related to cross-references which would be as important as automatically numbered equations and environments: how about some reference-management system like bibtex? This is very widely used in the STEM world and is absolutely wonderful: in fact, I hate doing citations and references without using bibtex! With bibtex, you enter semantic information like title, author, date, etc., and then when you import it into a LaTeX doc, you specify a style file which formats that information in whatever way is appropriate: MLA, ASA, XYZ, etc. Very valuable!

  1. We should provide support for some of the most popular/commonly used TeX and LaTeX extensions....

Sure, I suggest supporting all of the packages that MathJax supports. This is probably vital, and might require a fair bit of tinkering. I can imagine the polynom package might be used in some textbooks, but I've never used it myself (in pedagogical or scholarly contexts). My personal opinion -- although perhaps this is tainted by my particular disciplinary tastes? although I don't think so... -- is that some commutative diagram package like amscd and some drawing package like tikz are the the highest priorities for enabling within

  1. Users should be able to input MathML and have it be rendered in the webbook and export files. When they input MathML in the text editor, it should not be altered or destroyed when switching to the visual editor.

Sure. I don't know anyone who authors in MathML, but maybe to translate between different environments this would be nice. Note that MathJax allows, by clicking on a rendered equation, one to get the TeX source code and a MathML version ... I think! ... so the MathML functionality is probably already built into MathJax. I don't use MathML myself, nor do I know anyone who does -- no scholarly journal or online platform or other context of which I am aware requires MathML source code (although many require LaTeX!), for example -- so I've not bothered to learn much about it. I think maybe there are screenreaders that use the MathML output of MathJax to help with reading web pages that have equations...?

  1. Users should be able to input ASCIIMath markup (http://asciimath.org/).

I mean, sure, why not. But I don't think this is all that widely used. I think it's a toy that some people thought would be more palatable to students and other folks who are scared of markup languages. But, as I mentioned above, people in STEM are used to symbolic decorations carrying a lot of meaning, and students and professionals alike don't actually have big problems with real TeX, so ascimath is really not much needed. IMHO, of course!

@pkra
Copy link

pkra commented Feb 3, 2023

https://www.peterkrautzberger.org/0129/

Oh my, blast from the past -- don't do that!

There are (much) better ways nowadays, see https://www.peterkrautzberger.org/0216/ // https://pkra.github.io/2022-athen-stem-conf/ for some demos (the video demo using Thorium in particular). Feel free to ping me if you have questions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants