Merge pull request #69 from mathjax/v4-update

V4 update

Author: dpvc

README.md

@@ -1,56 +1,138 @@
 # [MathJax-demos-node](https://github.com/mathjax/MathJax-demos-node)
-<img class="shield" alt="GitHub release version" src="https://img.shields.io/github/v/release/mathjax/MathJax-src.svg?sort=semver">
-
-A repository with examples using [MathJax version 3](https://github.com/mathjax/MathJax-src) in node applications.
-
-See the [MathJax Web Demos](https://github.com/mathjax/MathJax-demos-web) for examples of how to use MathJax in web pages.  See the [MathJax documentation](https://docs.mathjax.org/) for complete details of how to use MathJax in web browsers and node.
+<img class="shield" alt="GitHub release version" src="https://img.shields.io/github/v/release/mathjax/MathJax-demos-node.svg?sort=semver">
+
+A repository with examples using [MathJax version 4](https://github.com/mathjax/MathJax-src) in node applications.
+
+See the [MathJax Web
+Demos](https://github.com/mathjax/MathJax-demos-web) for examples of
+how to use MathJax in web pages.  See the [MathJax
+documentation](https://docs.mathjax.org/) for complete details of how
+to use MathJax in web browsers and node.  In particular, the [Examples
+in Node](https://docs.mathjax.org/en/latest/server/examples.html) page
+contains a list of the most important examples for node applications;
+the [Examples in a
+Browser](https://docs.mathjax.org/en/latest/web/examples.html) page
+lists other examples that may be useful; though they target web pages,
+the same techniques can be employed in node.
 
 ## The Example files
 
-This repository contains examples of how to use MathJax v3 in your node projects.  These are divided into three main categories:  ones based on the MathJax v3 components and its loading system, ones based on the MathJax v3 components that you preload by hand (for easier synchronous use), and ones that use the base MathJax files directly without using the MathJax components.
-
-All three groups include examples of conversion from the various input formats to the various output formats, both for individual expressions, and for complete pages containing math.  Each category includes the following executables:
+This repository contains a number of examples of command-line tools
+that exhibit the features of MathJax.  The tools provide a number of
+command-line options, which you can discover by using the `--help`
+option when running them.  Most of the examples include the ability to
+generate speech strings for the output, for example, via the
+`--speech` or ``--braille` options, and the language can be specified
+using `--sre locale de`, for example to get a German localization.
+
+The tools accept one or more mathematical expressions as their
+arguments, or you can use the `--file` option to specify an HTML file
+that will be processed in full.  If you don't give a file name, then
+the file is taken from standard input.  Similarly, if you don't give
+any expressions, then they are taken from standard in, with a blank
+line separating expressions.
+
+The tools come in two forms, one using ESM modules in the [`mjs`](mjs)
+directory, and one using CommonJS modules in the [`cjs`](cjs) folder,
+so you can see examples of both types.  These directories are further
+subdivided into groups based on the mechanism by which MathJax is
+used: [`simple`](mjs/simple) uses a node-only mechanism that makes it
+easy to start experimenting with MathJax, but can't be used in web
+applications; [`component`](mjs/component) uses the MathJax Component
+framework to access MathJax's components via a configuration object
+like the one used in web browsers; [`direct`](mjs/direct) uses direct
+calls to the MathJax modules, without using MathJax components (so
+dynamic loading of TeX extensions is not supported for example); and
+finally, [`mixed`](mjs/mixed) combines direct calls with MathJax
+Components for the best of both worlds.
+
+All four groups include examples of conversion from the various input
+formats to the various output formats, and include the following
+executables:
 
 * `tex2chtml`
 * `tex2svg`
 * `tex2mml`
 * `mml2chtml`
+* `mml2mml`
 * `mml2svg`
 * `am2chtml`
 * `am2mml`
-* `tex2chtml-page`
-* `tex2svg-page`
-* `tex2mml-page`
-* `mml2chtml-page`
-* `mml2svg-page`
-* `am2chtml-page`
-
-The first seven convert an expression from either a TeX, MathML, or AsciiMath string (given as its first argument) to a CommonHTML, SVG, or MathML string.  The ones ending in `-page` take an HTML file and convert the math in it from the given input format to the specified output format and output the modified page.
-
-Use the `--help` option to get a list of all the possible options for each command.
-
-The three categories of commands are stored in the directories called [`component`](component), [`simple`](simple), [`preload`](preload), and [`direct`](direct).  Both the `component` and `simple` directories are examples of the component-based approach, with the `component` directory containing versions that mirror the approach needed when MathJax is used in web pages, and the `simple` directory containing examples that take advantage of some simplifications available in node.  Each of those directories contain additional information about the example files they contain.
-
-There is also a directory [`speech`](speech) that give examples of converters that add speech strings to their results, which illustrate more sophisticated operations in MathJax.  This is described in more detail in that directory.
-
-The [`custom-tex-extension`](custom-tex-extension) directory contains an example of how to create your own custom TeX extension and load it as a component.  Again, see the directory for more details.
-
-The [`puppeteer`](puppeteer) directory contains an example of how to use the [Puppeteer](https://developers.google.com/web/tools/puppeteer) library to use a headless Chrome instance to do server-side conversion of mathematics using MathJax.  This is useful in situations where you are using characters that are not included in the main MathJax fonts, as Chrome will be able to measure the widths of these characters so that they can be displayed more reliably.
+* `am2svg`
+* `typeset`
+
+The first nine convert from the format listed before the `2` to the
+format listed after it, and represent all combinations of the three
+input formats with three output formats.  The `mml2mml` example is
+useful for reformatting a MathML string, or for converting it to use
+the Mathematical Alphanumerics block of Unicode characters rather than
+`mathvariant` attributes with ASCII characters, as required by
+MathML-Core, for instance.
+
+The `typeset` tool allows you to convert from any input format to any
+output format, so is a "swiss army knife" example that gives you
+access to all the options within a common command.
+
+Use the `--help` option to get a list of all the possible options for
+each tool.
+
+The [`custom-tex-extension`](custom-tex-extension) directory contains
+an example of how to create your own custom TeX extension and load it
+as a component.  See that directory for more details.
+
+The [`puppeteer`](puppeteer) directory contains an example of how to
+call the
+[Puppeteer](https://developers.google.com/web/tools/puppeteer) library
+to use a headless Chrome instance to do server-side conversion of
+mathematics using MathJax.  This is useful in situations where you are
+using characters that are not included in the main MathJax fonts, or
+including HTML within TeX or MathML expressions, as Chrome will be
+able to measure the sizes of these so that they can be displayed more
+reliably.
+
+Finally, the [`jsdom`](jsdom) and [`linkedom`](linkedom) directories
+include examples of how to use those DOM libraries instead of
+MathJax's usual `LiteDOM` library as a replacement for the browser
+DOM.
+
+## The Utility Libraries
+
+The tools in the `mjs` and `cjs` directories share a lot of common
+code, and that shared code has been moved to separate utility files in
+the [`util`](mjs/util) sub-directories of those directories.  There is
+one for each of the input and output formats (the `Mml.js` file
+contains the code for both input and output in MathML format), and a
+main `Util.js` file that holds code common to all the tools.  The
+`Direct.js` and `Mixed.js` utilities have code specific to those
+mechanisms of accessing MathJax, and the `Typeset.js` file handles the
+special needs of the `typeset` tool.
+
+These utilities form the heart of the command-line tools, and it is in
+them that you will see the real details of how to work with MathJax;
+the individual tool files basically just load the needed libraries or
+MathJax modules, set up the configuration needed, and call the utility
+libraries to handle the details or getting the command-line arguments,
+setting up the needed configuration options, converting the expression
+or files, filtering the results according to the options given, and
+printing the results.
 
 ## Installation
 
-In order to try out these examples, clone this repository, enter the directory, and install the dependencies:
+In order to try out these examples, clone this repository, enter the
+directory, and install the dependencies:
 
 ``` bash
 git clone https://github.com/mathjax/MathJax-demos-node.git MathJax-demos-node
 cd MathJax-demos-node
 npm install
 ```
 
-The examples should be executable files that you can run.  On non-unix systems, you may need to call
+To run the tools, cd to the directory containing the tools and use
 
-``` bash
-node -r esm <example-name>
+```
+node <example-name> [options] [expressions...]
 ```
 
-where `<example-name>` is the name of the example file.  Some examples take an argument (like a TeX string) that follows the `<example-name>` above.
+where `<example-name>` is the name of the example file, like
+`tex2svg`.  Use the `--help` options to get more details about the
+options and arguments that each tool needs.

cjs/component/am2chtml

@@ -0,0 +1,62 @@
+#! node
+
+/*************************************************************************
+ *
+ *  cjs/component/am2chtml
+ *
+ *  Uses MathJax v4 to convert an AsciiMath string to an HTML string.
+ *
+ * ----------------------------------------------------------------------
+ *
+ *  Copyright (c) 2019-2025 The MathJax Consortium
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+//
+// Load the needed utilities.
+//
+const {Util} = require('../util/Util.js');
+const {Am} = require('../util/Am.js');
+const {Chtml} = require('../util/Chtml.js');
+const {Sre} = require('../util/Sre.js');
+
+//
+// Get the command-line arguments.
+//
+const args = Util.args('"math" > file.html', [Am, Chtml, Sre]);
+
+//
+// Set up the MathJax configuration.
+//
+global.MathJax = {
+  loader:    Util.config.loader(['adaptors/liteDOM', 'input/asciimath', 'output/chtml', 'a11y/speech'], args),
+  options:   Util.config.options(args),
+  startup:   Util.config.startup(args),
+  asciimath: Am.config(args),
+  chtml:     Chtml.config(args),
+  'adaptors/liteDOM': Util.config.adaptor(args),
+};
+
+//
+// Load the needed components.
+//
+Util.load('startup', args);
+
+//
+// Typeset the math and print the result.
+// Then tell MathJax we are done.
+//
+Util.typeset(args, Chtml)
+  .then((output) => console.log(output))
+  .then(() => MathJax.done());

cjs/component/am2mml

@@ -0,0 +1,58 @@
+#! node
+
+/*************************************************************************
+ *
+ *  cjs/component/am2mml
+ *
+ *  Uses MathJax v4 to convert an AsciiMath string to a MathML string.
+ *
+ * ----------------------------------------------------------------------
+ *
+ *  Copyright (c) 2019-2025 The MathJax Consortium
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+//
+// Load the needed utilities.
+//
+const {Util} = require('../util/Util.js');
+const {Am} = require('../util/Am.js');
+const {Mml} = require('../util/Mml.js');
+
+//
+// Get the command-line arguments.
+//
+const args = Util.args('"math"', [Am, Mml.output], false);
+
+//
+// Set up the MathJax configuration.
+//
+global.MathJax = {
+  loader:    Util.config.loader(['adaptors/liteDOM', 'input/asciimath'], args),
+  options:   Util.config.options(args),
+  startup:   Util.config.startup(args),
+  asciimath: Am.config(args),
+  'adaptors/liteDOM': Util.config.adaptor(args),
+};
+
+//
+// Load the needed components.
+//
+Util.load('startup', args);
+
+//
+// Convert and print the math.
+//
+Util.typeset(args, Mml)
+  .then((output) => console.log(output));

cjs/component/am2svg

@@ -0,0 +1,62 @@
+#! node
+
+/*************************************************************************
+ *
+ *  cjs/component/am2svg
+ *
+ *  Uses MathJax v4 to convert an AsciiMath string to an SVG string.
+ *
+ * ----------------------------------------------------------------------
+ *
+ *  Copyright (c) 2019-2025 The MathJax Consortium
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+//
+// Load the needed utilities.
+//
+const {Util} = require('../util/Util.js');
+const {Am} = require('../util/Am.js');
+const {Svg} = require('../util/Svg.js');
+const {Sre} = require('../util/Sre.js');
+
+//
+// Get the command-line arguments.
+//
+const args = Util.args('"math" > file.svg', [Am, Svg, Sre]);
+
+//
+// Set up the MathJax configuration.
+//
+global.MathJax = {
+  loader:    Util.config.loader(['adaptors/liteDOM', 'input/asciimath', 'output/svg', 'a11y/speech'], args),
+  options:   Util.config.options(args),
+  startup:   Util.config.startup(args),
+  asciimath: Am.config(args),
+  svg:       Svg.config(args),
+  'adaptors/liteDOM': Util.config.adaptor(args),
+};
+
+//
+// Load the needed components.
+//
+Util.load('startup', args);
+
+//
+// Typeset the math and print the result.
+// Then tell MathJax we are done.
+//
+Util.typeset(args, Svg)
+  .then((output) => console.log(output))
+  .then(() => MathJax.done());