Update the README for v4

Author: dpvc

README.md

@@ -2,24 +2,25 @@
 ## Beautiful math in all browsers
 
 ![GitHub release version](https://img.shields.io/github/v/release/mathjax/MathJax-src.svg?sort=semver)
+![GitHub release version (v3)](https://img.shields.io/github/package-json/v/mathjax/MathJax/legacy-v3.svg?label=release-v3)
 ![GitHub release version (v2)](https://img.shields.io/github/package-json/v/mathjax/MathJax/legacy-v2.svg?label=release-v2)
 ![NPM version](https://img.shields.io/npm/v/mathjax.svg?style=flat)
-<a href="http://www.numfocus.org">![powered by NumFOCUS](https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat)</a>  
 ![jsdelivr rank](https://flat.badgen.net/jsdelivr/rank/npm/mathjax?color=green)
 ![jsDelivr hits (npm)](https://img.shields.io/jsdelivr/npm/hm/mathjax)
 ![npm monthly downloads (full)](https://img.shields.io/npm/dm/mathjax?label=npm)
 ![npm total downloads](https://img.shields.io/npm/dt/mathjax.svg?style=flat&label=npm%20total)
 
 MathJax is an open-source JavaScript display engine for LaTeX, MathML,
-and AsciiMath notation that works in all modern browsers.  It was
-designed with the goal of consolidating the recent advances in web
-technologies into a single, definitive, math-on-the-web platform
-supporting the major browsers and operating systems.  It requires no
-setup on the part of the user (no plugins to download or software to
-install), so the page author can write web documents that include
-mathematics and be confident that users will be able to view it
-naturally and easily.  Simply include MathJax and some mathematics in
-a web page, and MathJax does the rest.
+and AsciiMath notation that works in all modern browsers, with
+built-in support for assistive technology like screen readers,
+including automatic speech generation and an expression explorer that
+can be used to investigate typeset mathematics on a more granular
+level than the complete expression.  It requires no setup on the part
+of the user (no plugins to download or software to install), so the
+page author can write web documents that include mathematics and be
+confident that users will be able to view it naturally and easily.
+Simply include MathJax and some mathematics in a web page, and MathJax
+does the rest.
 
 Some of the main features of MathJax include:
 
@@ -40,7 +41,7 @@ and <https://docs.mathjax.org> for the MathJax documentation.
 
 ## MathJax Components
 
-MathJax version 3 uses files called *components* that contain the
+MathJax uses files called *components* that contain the
 various MathJax modules that you can include in your web pages or
 access on a server through NodeJS.  Some components combine all the
 pieces you need to run MathJax with one or more input formats and a
@@ -66,12 +67,10 @@ source code for MathJax (which are available in a separate [MathJax
 source repository](https://github.com/mathjax/MathJax-src/)).  These
 component files are the ones served by the CDNs that offer MathJax to
 the web.  In version 2, the files used on the web were also the source
-files for MathJax, but in version 3, the source files are no longer on
-the CDN, as they are not what are run in the browser.
+files for MathJax, but in version 3 and above, the source files are no
+longer on the CDN, as they are not what are run in the browser.
 
-The components are stored in the `es5` directory, and are in ES5 format
-for the widest possible compatibility.  In the future, we may make an
-`es6` directory containing ES6 versions of the components.
+The components are ES6 format as CommonJS modules.
 
 ## Installation and Use
 
@@ -82,42 +81,38 @@ need to install anything.  Simply use a `script` tag that loads
 MathJax from the CDN.  E.g.,
 
 ``` html
-<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js" defer></script>
 ```
 
 See the [MathJax
-documentation](https://docs.mathjax.org/en/latest/index.html#browser-components),
-the [MathJax Web Demos](https://github.com/mathjax/MathJax-demos-web),
-and the [MathJax Component
-Repository](https://github.com/mathjax/MathJax-demos-web) for more information.
+documentation](https://docs.mathjax.org/en/latest/index.html#browser-components)
+and the [MathJax Web Demos](https://github.com/mathjax/MathJax-demos-web), and the [MathJax
+Node Demos](https://github.com/mathjax/MathJax-demos-node) for more
+information.
 
 ### Hosting your own copy of the MathJax Components
 
 If you want to host MathJax from your own server, you can do so by
-installing the `mathjax` package using `npm` and moving the `es5`
-directory to an appropriate location on your server:
+installing the `mathjax` package using `npm` and moving the contents
+to an appropriate location on your server:
 
-``` bash
-npm install mathjax@3
-mv node_modules/mathjax/es5 <path-to-server-location>/mathjax
 ```
-
-Note that we are still making updates to version 2, so include `@3`
-when you install, since the latest chronological version may not be
-version 3.
+npm install mathjax@4
+mv node_modules/mathjax <path-to-server-location>/mathjax
+```
 
 Alternatively, you can get the files via GitHub:
 
-``` bash
-git clone https://github.com/mathjax/MathJax.git mj-tmp
-mv mj-tmp/es5 <path-to-server-location>/mathjax
-rm -rf mj-tmp
+```
+git clone https://github.com/mathjax/MathJax.git mathjax
+mv mathjax <path-to-server-location>/mathjax
+rm -rf mathjax
 ```
 
 Then (in either case) you can use a script tag like the following:
 
 ``` html
-<script id="MathJax-script" async src="<url-to-your-site>/mathjax/tex-chtml.js"></script>
+<script src="<url-to-your-site>/mathjax/tex-chtml.js" defer></script>
 ```
 
 where `<url-to-your-site>` is replaced by the URL to the location
@@ -129,39 +124,58 @@ for details.
 
 ### Using MathJax components in a node application
 
-To use MathJax components in a node application, install the `mathjax` package:
+To use MathJax components in a node application, install the `mathjax`
+package:
 
 ``` bash
-npm install mathjax@3
+npm install mathjax@4
 ```
 
-(we are still making updates to version 2, so you should include `@3`
-since the latest chronological version may not be version 3).
+Then import `mathjax` within your application and initialize it:
+
+``` js
+import MathJax from 'mathjax';
+await MathJax.init({ ... });
+```
+
+where `{ ... }` is the MathJax configuration you want to use.  E.g., 
+
+``` js
+import MathJax from 'mathjax';
+await MathJax.init({
+  loader: {load: ['input/tex', 'output/svg']}
+});
+const svg = await MathJax.tex2svgPromise('\\frac{1}{x^2-1}', {display: true});
+console.log(MathJax.startup.adaptor.outerHTML(svg));
+```
 
-Then require `mathjax` within your application:
+
+Alternatively, in an ES5 node application, you can use
 
 ```js
-require('mathjax').init({ ... }).then((MathJax) => { ... });
+const MathJax = require('mathjax');
+MathJax.init({ ... }).then(() => { ... });
 ```
 
 where the first `{ ... }` is a MathJax configuration, and the second
 `{ ... }` is the code to run after MathJax has been loaded.  E.g.
 
 ```js
-require('mathjax').init({
+const MathJax = require('mathjax');
+MathJax.init({
   loader: {load: ['input/tex', 'output/svg']}
-}).then((MathJax) => {
+}).then(() => {
   const svg = MathJax.tex2svg('\\frac{1}{x^2-1}', {display: true});
   console.log(MathJax.startup.adaptor.outerHTML(svg));
 }).catch((err) => console.log(err.message));
 ```
 
-**Note:** this technique is for node-based application only, not for
-browser applications.  This method sets up an alternative DOM
-implementation, which you don't need in the browser, and tells MathJax
-to use node's `require()` command to load external modules.  This
-setup will not work properly in the browser, even if you webpack it or
-bundle it in other ways.
+**Note:** the technique in the two examples above is for node-based
+application only, not for browser applications.  This method sets up
+an alternative DOM implementation, which you don't need in the
+browser, and it depends on node and the local file system in other
+ways.  This setup will not work properly in the browser, even if you
+webpack it or use some other bundler.
 
 See the
 [documentation](https://docs.mathjax.org/en/latest/index.html#server-nodejs)
@@ -170,45 +184,51 @@ Repository](https://github.com/mathjax/MathJax-demos-node) for more details.
 
 ## Reducing the Size of the Components Directory
 
-Since the `es5` directory contains *all* the component files, so if
+Since the MathJax package contains *all* the component files, so if
 you are only planning one use one configuration, you can reduce the
 size of the MathJax directory by removing unused components. For
 example, if you are using the `tex-chtml.js` component, then you can
-remove the `tex-mml-chtml.js`, `tex-svg.js`, `tex-mml-svg.js`,
-`tex-chtml-full.js`, and `tex-svg-full.js` configurations, which will
-save considerable space.  Indeed, you should be able to remove
-everything other than `tex-chtml.js`, and the `input/tex/extensions`,
-`output/chtml/fonts/woff-v2`, `adaptors`, `a11y`, and `sre`
-directories.  If you are using the results only on the web, you can
-remove `adaptors` as well.
-
-If you are not using A11Y support (e.g., speech generation, or
-semantic enrichment), then you can remove `a11y` and `sre` as well
-(though in this case you may need to disable the assistive tools in
-the MathJax contextual menu in order to avoid MathJax trying to load
-them when they aren't there).
-
-If you are using SVG rather than CommonHTML output (e.g., `tex-svg.js`
-rather than `tex-chtml.js`), you can remove the
-`output/chtml/fonts/woff-v2` directory.  If you are using MathML input
+remove the `tex-mml-chtml.js`, `tex-svg.js`, `tex-mml-svg.js`, and the
+files ending in `-nofont.js`, which will save considerable space.
+Indeed, you should be able to remove everything other than
+`tex-chtml.js`, and the `input/tex/extensions`, `adaptors`, `a11y`,
+and `sre` directories.  If you are using the results only on the web,
+you can remove `adaptors` as well.  If you are using MathML input
 rather than TeX (e.g., `mml-chtml.js` rather than `tex-chtml.js`),
 then you can remove `input/tex/extensions` as well.
 
-
-## The Component Files and Pull Requests
-
-The `es5` directory is generated automatically from the contents of the
-MathJax source repository.  You can rebuild the components using the
-command
+If you are using a font other than the default `mathjax-newcm` font in
+a node application, then you will need to install that font as well.
+E.g.,
 
 ``` bash
-npm run make-es5 --silent
+npm install @mathjax/mathjax-stix2-font@4
+```
+
+to install the `mathjax-stix2` font locally.  On the web, MathJax will
+look for the font and its dynamic ranges on the `cdn.jsdelivr.net` CDN
+service, so if you want to use the font from your own server, you will
+need to configure the path to the font.  For example:
+
+``` js
+MathJax = {
+  loader: {
+    paths: {
+      'mathjax-stix2': '<url-to-your-server>/mathjax-stix2-font'
+    }
+  }
+};
 ```
 
-Note that since the contents of this repository are generated
-automatically, you should not submit pull requests that modify the
-contents of the `es5` directory.  If you wish to submit a modification
-to MathJax, you should make a pull request in the [MathJax source
+to set the location for the `mathjax-stix2` font to a URL on your server.
+
+
+## The Component Files and Pull Requests
+
+The contents of this repository are generated automatically, so you
+should not submit pull requests that modify this repository.  If you
+wish to submit a modification to MathJax, you should make a pull
+request in the [MathJax source
 repository](https://github.com/mathjax/MathJax-src).
 
 ## MathJax Community