[discussion] re-organizing the examples in /bin

[pkra]

As per F2F, the examples in /bin have been growing and becoming a burden to maintain.

A couple of ideas to move forward:

• turn them it into a separate repository and node module (or several modules), hosted but not officially maintained by the MathJax team (cf. the MathJax third-party extension repository). This could also open ta path to a refactoring, e.g., into one unified tool (though that might increase the maintenance load going forward).
• replace them some other way, e.g., as a collection of recipes like gulp's

Any other suggestions?

[pkra]

I've created an example repice in #119; I'm growing to the idea.

[dpvc]

I think that making them into a single tool is probably the right approach. I don't have strong feelings about whether that should be in a separate repository or not.

I don't see a collection of recipes as being any less burdensome than the current collection of tools.

[pkra]

I think that making them into a single tool is probably the right approach.

Fair enough. I just don't think it's a core product.

I don't see a collection of recipes as being any less burdensome than the current collection of tools.

Right (though I would drop most of them); I do think that having them in ./bin gives people the wrong idea about their status (as we've seen in bug reports). Examples in a documentation have a different status; one that fits better, I think.

[pkra]

How about this as a compromise: rename the folder "examples" instead of "bin"?

[pkra]

#119 (comment) and #205 (comment) relate to this problem. They make good examples but no more.

[michael-okeefe]

If it helps, as a somewhat anecdotal example, I came to this repository after much Google searching and have been using the scripts in the bin/ directory as a pathway to pre-render MathJax for a static website.

I'm not sure how many other people are in the same boat but I barely know node.js and found these ready-to-run scripts to be extremely useful. One problem I'm running into is that the default script for page2svg runs rather slow although that's a separate issue and one I'm willing to put up with.

If my use-case (people looking for a pathway to command-line access to mathjax pre-rendering who don't know node.js well) is not a complete outlier, I would recommend and would personally love to see more effort put into the bin/ scripts to make sure they are robust, performant, and well-documented. Seems like you have a good start already.

So if nothing else, I just wanted to communicate how incredibly useful the bin/ scripts have been to me. I could see a scenario where the bin scripts could actually become a core offering of this project if you take into account all the people who could use mathjax-node if they didn't have to learn node.js to get started.

Either way, just wanted to communicate a "thank you" for all the great work!

[pkra]

Thanks for sharing your comment, @michael-okeefe -- we really appreciate it!

I think everyone on the MathJax team agrees that the CLI tools are useful. The problem for us is one of maintenance costs and fit within the library.

My first response to your comment would be that I want to think more about the first option mentioned in the OP -- moving them into a separate package where they can be developed independently (e.g., towards a kitchen-sink CLI tool or a bunch of micro packages). This makes the CLI tools less dependent on the core library and vice versa. An independent package can also be maintained more easily, and might prove to be a lower bar for community contributions.

As with #205, #206, #207, this might also provide us with better understanding of what parts of the mathjax-node APIs are missing or need changes.

[pkra]

Just a minor note. I stumbled upon https://www.npmjs.com/package/tex-equation-to-svg.

[PatrickMassot]

For reference, I guess the conversation in #254 qualifies as a contribution to the discussion in this issue. I really think the ability to prerender to svg is a very nice addition to the awesomeness of mathjax. As far as I can see, even a rather heavy-on-math page can be turned into somethings that loads instantly. And having a command line program which does this in the most simple way is really helpful. I'm aware that this path ruins accessibility but we can still keep an accessible version since the same tool handles both.

TL&DR: I'm a mathematician knowing nothing about node.js and I love page2svg, please keep it somewhere.

[pkra]

I built a unified CLI tool as part of mathjax-node-sre, https://github.com/pkra/mathjax-node-sre/blob/master/bin/mjsre.js, and as part of mathjax-node-page, https://github.com/pkra/mathjax-node-page/blob/master/bin/mjpage.js.

I plan to move these into their own packages at which point they could be refactored into several modules (with/without SRE).

I'm hoping these will make the examples in /bin obsolete. I believe they are easier to maintain that way. They also reduce the dependencies of mathjax-node.

[PatrickMassot]

Thank you for your work on this. Could you provide any example of using mjpage that would allow one to reproduce the behavior of page2svg? I tried to put in test.html:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Test mjpage</title>
</head>
<body>
Hello $x=1$.
</body>
</html>

Then cat test.html | mathjax-node-page/bin/mjpage.js > out.html gives me an error Unknown format: AsciiMath,TeX,MathML and adding the option --format=TeX gives me the following output:

<!DOCTYPE html><html lang="en"><head>
<meta charset="utf-8">
<title>Test mjpage</title>
</head>
<body>
Hello $x=1$.


<svg style="display: none;"><defs id="MathJax_SVG_glyphs"></defs></svg></body></html>

whereas page2svg does work on this example (without any command line flag).

[pkra]

Could you report this on the other repo? The format default is wrong -- a bug. You need to add --dollars to enable dollars as delimiters.

[PatrickMassot]

Thank you very much. I was confused when reading:

        dollars: {
            boolean: true,
            describe: "use single-dollar delimiters"
        },

I incorrectly assumed the boolean: true line to mean this was the default option. I count this as one more evidence that those ready to use scripts are immensely useful because there are (many? most?) mathjax users knowing nothing about node.

[ickc]

I built a unified CLI tool as part of mathjax-node-sre, https://github.com/pkra/mathjax-node-sre/blob/master/bin/mjsre.js, and as part of mathjax-node-page, https://github.com/pkra/mathjax-node-page/blob/master/bin/mjpage.js.

I plan to move these into their own packages at which point they could be refactored into several modules (with/without SRE).

I'm hoping these will make the examples in /bin obsolete. I believe they are easier to maintain that way. They also reduce the dependencies of mathjax-node. @pkra

Does it mean the bin for single equation will be discontinued? (e.g. MathJax-node/page2svg) Some tools are already depending on that script. e.g. jgm/pandoc-tex2svg: Pandoc filter to convert math to SVG using MathJax-node's tex2svg. May be mjpage can have an option for standalone equation (that might contradict the name page however).

[Klortho]

I'd recommend:

• Put all these utilities into a separate repo, named mathjax-cli. This follows the conventions of a lot of other libraries. Configure things such that mathjax-cli is installed globally, but is not tied to the specific mathjax version. It acts as a wrapper/manager, and, when the user is in a project directory, it invokes the script from the version of mathjax they have installed locally. grunt-cli is a decent example.
• Combine these utilities into one executable with subcommands. So, e.g., mathjax mml2png. It's more typing, but users can add their own aliases if they want them.

[pkra]

Coming back to this after we hit v1 beta.

I was thinking of moving https://github.com/pkra/mathjax-node-sre/blob/master/bin/mjsre.js (which is a unification of the old mj-single-based CLI tools) to its own repo and making the sre integration optional.

There's also https://github.com/pkra/mathjax-node-page/blob/master/bin/mjpage.

I think that would be a sufficient replacement.

[ickc]

Will the single-equation-version of the bins be staying, besides the page-version?

[pkra]

As per F2F, the examples will be dropped in favor of https://github.com/mathjax/mathjax-node-cli.

[pkra]

Merged into develop.