Add v3 to v4 upgrading, and adjust some what's new pages

Author: dpvc

upgrading/v3.rst

@@ -4,7 +4,59 @@
 Upgrading from v3 to v4
 #######################
 
-Under construction
+Because version 3 was a complete rewrite of MathJax, the API had major
+changes from version 2 to version 3, making that upgrade one that
+could require significant work.  That is not the case for upgrading
+from v3 to v4.  The API for v4 is largely the same as v3, with most
+changes being additions rather than changes.
+
+There are many new features in v4.  See the :ref:`whats-new-4.0`
+section for complete details.  There are some breaking changes, which
+are outlined in the :ref:`v4-breaking-changes` section.
+
+For those who are using MathJax in web pages by just configuring and
+loading MathJax without calling its API directly, you may not have to
+make any changes other than changing the URL to load version 4.
+
+If you are calling the MathJax API, then you may need to change to
+using the promise-based calls like :js:meth:`MathJax.typesetPromise()`
+rather than the synchronous ones like :js:meth:`MathJax.typeset()`.
+See the :ref:`v4-promises` section for details and suggestions for how
+to proceed.
+
+MathJax v4 now produces ES6 modules rather than the older ES5 CommonJS
+modules of v3.  This means has lead to changes in the MathJax source
+directories and the build tools that are used to compile and pack
+MathJax and its extensions.  See the sections on
+:ref:`v4-es6-modules`, :ref:`v4-api-modules`, and
+:ref:`v4-build-tools` for more information.
+
+There are significant changes to how MathJax handles speech generation
+in v4.  See the :ref:`Explorer Technical Details
+<v4-explorer-details>` and :ref:`v4-breaking-speech` sections for more
+information on these changes and how to address them.
+
+If you have written extensions or other customizations for MathJax,
+then there are changes that you may need to take into account.  See
+the :ref:`v4-breaking-changes` section for more details about these.
+There are also many more examples available here for both the
+web-based and node-based applications of MathJax.  See
+:ref:`web-examples` and :ref:`node-examples` for lists of the most
+important ones.
+
+There are a number of changes to the TeX input jax and its extensions
+that may affect existing content.  For example, the
+:ref:`tex-textmacros` extension is no by default in the :ref:`combined
+components <combined-components>`, which has implecations for
+``\text{}`` and othe text-mode macros if they contain text that will
+now be considered as macro references that where ignored in the past.
+There are also changes to the :ref:`tex-mathtools` extension, and to
+several other extensions.  See the :ref:`v4-tex-improvements` section
+for details on this and the other such changes.
+
+The ``all-packages`` extension has been removed, as have the combined
+components ending in ``-full``.  See :ref:`v4-all-packages` for more on this.
+
 
 |-----|
 

upgrading/whats-new-4.0/accessing.rst

@@ -81,6 +81,10 @@ and if you want a different font, a command like
 to get the latest `mathjax-stx2` font package.  The other fonts can be
 obtained similarly.
 
+In your code, you will need to change any references to the
+``mathjax-full`` package to ``@mathjax/src``, and any references to
+``mathjax-[fontname]-font`` to ``@mathjax/mathjax-[fontname]-font``.
+
 
 .. _v4-browser-fonts:
 

upgrading/whats-new-4.0/output.rst

@@ -12,6 +12,12 @@ be used in the new renderer without needing additional configuration.
 The individual :data:`chtml` and :data:`svg` blocks then should only
 include options that are specific to those output formats.
 
+
+.. _v4-CHTML:
+
+CHTML Improvements
+==================
+
 An important improvement has been made in v4 to the way the CHTML
 output renderer handles stretchy delimiters.  In the past, the CHTML
 output would use CSS transforms to stretch the extender to the needed
@@ -40,6 +46,12 @@ includes a work-around that should help with the alignment in
 where the characters
 are grouped into a single MathML element.
 
+
+.. _v4-SVG:
+
+SVG Improvements
+================
+
 The SVG output jax has two new configuration options.  The first is
 :data:`svg.blacker`, which is a number that indicates the stroke width
 (in thousandths of an em) to use for the character paths.  Because
@@ -65,6 +77,12 @@ characters to form a single glyph will be handled properly.  So use
 Note that this was already being done for CHTML output, so this brings
 the two in line with each other.
 
+
+.. _v4-assisitve-mml:
+
+Assistive MathML Size
+=====================
+
 In the past, the hidden MathML that is produced by the
 :ref:`assistive-mml-component` extension could be rendered by the
 browser larger than the math typeset by MathJax, which could interfere