Merge pull request #1333 from mathjax/update/readme

Update/readme

Author: dpvc

README.md

@@ -1,6 +1,7 @@
 # MathJax (Source Repository)
 
 ![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)
 ![jsdelivr rank](https://flat.badgen.net/jsdelivr/rank/npm/mathjax?color=green)
@@ -15,15 +16,16 @@
 ## Beautiful math in all browsers
 
 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:
 
@@ -63,52 +65,71 @@ 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.
 
 
 ### Using MathJax Components in node applications
 
-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({ ... });
+```
 
-Then require `mathjax` within your application:
+where `{ ... }` is the MathJax configuration you want to use.  E.g., 
 
-``` javascript
-require('mathjax').init({ ... }).then((MathJax) => { ... });
+``` 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));
+```
+
+
+Alternatively, in an ES5 node application, you can use
+
+```js
+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.
 
-``` javascript
-require('mathjax').init({
+```js
+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 applications 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)
 and the [MathJax Node
@@ -120,30 +141,30 @@ Repository](https://github.com/mathjax/MathJax-demos-node) for more details.
 You can use the MathJax JavaScript files (as opposed to MathJax
 components) directly in node applications.  This gives you the
 greatest flexibility, but requires more coding.  To use this approach,
-install the `mathjax-full` package:
+install the `@mathjax/src` package:
 
-    npm install mathjax-full
+    npm install @mathjax/src
 
 This will provide the following directories:
 
     node_modules/
-      mathjax-full/
+      @mathjax/src/
         ts/                  the MathJax source TypeScript files
         js/                  the compiled JavaScript files
         components/          the component build tools and control files
-        es5/                 the packages component files
+        bundle/              the packages component files
 
 You can use the components and JavaScript files directly in your node
 applications (see the [MathJax node
 demos](https://github.com/mathjax/MathJax-demos-node) for examples).
 
-If you want to work from the GitHub repository directly, then do the following:
+If you want to work from the GitHub repository directly, then do the
+following:
 
 ``` bash
 git clone https://github.com/mathjax/MathJax-src.git mathjax-src
 cd mathjax-src
-npm run --silent compile
-npm run --silent make-components
+npm run --silent build-all
 ```
 
 in order to compile the JavaScript files from the TypeScript source,