From 3183539b7cf96584b2e0993e49e230bee3755b09 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Fri, 15 Oct 2021 03:01:00 +0000
Subject: CTAN sync 202110150301

---
 fonts/newtx/doc/newtxdoc.tex | 78 +++++++++++++++++++++++++-------------------
 1 file changed, 44 insertions(+), 34 deletions(-)

(limited to 'fonts/newtx/doc/newtxdoc.tex')

diff --git a/fonts/newtx/doc/newtxdoc.tex b/fonts/newtx/doc/newtxdoc.tex
index a561e27599..72e3e16aa6 100644
--- a/fonts/newtx/doc/newtxdoc.tex
+++ b/fonts/newtx/doc/newtxdoc.tex
@@ -121,13 +121,14 @@ If you use the {\tt babel} package, you should load it before {\tt newtxtext}---
 More generally, the pattern of the preamble should be:
 \begin{verbatim}
 <encoding options>
-[optional] \usepackage{substitutefont} % so you can change babel's fonts
+%next line no longer needed---use macro \DeclareFontfamilySubstitution
+[optional]\usepackage{substitutefont} % can change babel's fonts
 [optional] \usepackage[<babel options>]{babel}
 \usepackage[p,osf]{newtxtext}% osf in text, lining figures in math
 [optional] redefine the plain theorem style if necessary
 <other font loading commands>
 \usepackage{newtxmath}
-<substitutefont commands>
+[optional]<\DeclareFontfamilySubstitution commands>
 \end{verbatim}
 As an example of a {\tt theoremstyle} definition,
 \begin{verbatim}
@@ -149,14 +150,14 @@ Here is a specific example following this pattern, but without {\tt theoremfont}
 \begin{verbatim}
 \usepackage[LGR,T1]{fontenc} % spell out all text encodings used
 \usepackage[utf8]{inputenc} % 
-\usepackage{substitutefont} % so we can use fonts other than those in babel
+[no longer needed]\usepackage{substitutefont} % so we can use fonts other than those in babel
 \usepackage[greek.polutoniko,english]{babel}
 \usepackage[largesc,osf]{newtxtext} % 
 \usepackage[varqu,varl]{zi4}% inconsolata
 \usepackage{cabin}% sans serif
 \usepackage[vvarbb]{newtxmath}
 \useosf % use oldstyle figures except in math
-\substitutefont{LGR}{\rmdefault}{Tempora} % use Tempora to render Greek text
+\DeclareFontfamilySubstitution{LGR}{\rmdefault}{Tempora} % use Tempora to render Greek text
 \end{verbatim}
 
 As of version 1.4, there are four normal figure styles: tabular lining, tabular oldstyle, proportional lining and proportional oldstyle, the default figure alignment being \texttt{tabular}. To make \texttt{proportional} the default, use the option \texttt{p} or \texttt{proportional}.
@@ -280,15 +281,17 @@ requires  {\tt amsmath}---there is no need to load it separately.
 %\usepackage[cmintegrals]{newtxmath}
 %\end{verbatim}
 %allows you to use the forms \verb|\iint|, \verb|\iiint|, \verb|\iiiint| and \verb|\idotsint| defined in {\tt amsmath}, but using the pumped-up Computer Modern integral loaded by {\tt newtxmath}. 
-\item If you wish to use \verb|\usepackage{amsthm}|, place it before loading {\tt newtxmath} or the result will  be
+\item If you wish to use \verb|\usepackage{amsthm}|, place it after \verb|\usepackage{amsmath}| and before loading {\tt newtxmath} or the result will  be
 \begin{verbatim}
 ! LaTeX Error: Command \openbox already defined.
 \end{verbatim}
+
 \item {\tt uprightGreek} and {\tt slantedGreek} determine the form of Greek alphabet loaded---the default is {\tt uprightGreek}, which loads upright uppercase and slanted lowercase Greek symbols, as is customary in Anglo-American mathematical typesetting. With the option {\tt slantedGreek}, which you might want to use if you cared about ISO standards, all Greek symbols are slanted. No matter which is set, \verb|\Gammaup| (or \verb|\upGamma|) gives you upright \verb|\Gamma|, etc, and \verb|\Deltait|, \verb|\zetait| give you italic (i.e., slanted) versions of those letters. If you are using a text font family with properly constructed OT$1$--encoded versions, then, no matter what you chose as the default shape for upper case Greek letters, \verb|\mathnormal{\Omega}| etc will always produce the slanted version. (The macro \verb|\mathnormal| means essentially ``use the version of the symbol in {\tt letters}''---i.e., the math italic form. This did not always work as expected in versions prior to 1.45.) Currently, this works as expected with {\tt newtxtext} and {\tt libertine}. 
 \item Option {\tt frenchmath} sets the default style in math mode for rendering uppercase Roman and Greek letters to upright, and lowercase Greek letters to upright. (Introduced in v.\ 1.28.)
 \item The option {\tt cmbraces} instructs {\tt newtxmath} to ignore the brace collections from {\tt txfonts}, substituting a collection based on thickened versions of the Computer Modern braces, which I find much easier to distinguish from other delimiters. This works quite well in regular weight but looks a bit clunky in bold. The option {\tt bigdelims}, which superseded {\tt cmbraces}, is now not necessary---it is the default as of version 1.5.
 \item Option {\tt nonewtxmathopt} (or {\tt scale}, a mistake I cannot now erase) causes newtxmath to not make use of the optical math sizes (7{\tt pt}, 5{\tt pt}), as preferred by some.
-\item Option {\tt subscriptcorrection} enables the special spacing of some subscripts. (The default is {\tt nosubscriptcorrection}.)
+\item Option {\tt subscriptcorrection} enables the special spacing of some subscripts. (The default is {\tt nosubscriptcorrection}.) 
+\item Option {\tt subscriptcorrectionfile} may be used to specify your own file that will serve in place of the default subscript correction file.
 \item The \textsf{newtxmath} package contains three different Blackboard Bold alphabets, where the original \textsf{txfonts} contained two. The default, triggered by \verb|\mathbb{}|, takes its glyphs from the font which replaces {\tt msbm} and has the same overall appearance of a hollowed-out text font, which I find neither bold nor blackboard-like. The second option, taken from \textsf{txfonts}, is triggered by \verb|\varmathbb{}|, is more geometric and, in my opinion, preferable but not optimal. The option {\tt varbb} makes \verb|\mathbb{}| synonymous with \verb|\varmathbb{}|. The third option is the double-struck glyphs from the STIX collection. See the expanded discussion below.
 \item {\tt noOT1} affects only those text-math combinations where {\tt operators} is defined by default to OT1 with Greek uppercase letters. It causes {\tt operators} to keep the same encoding as in tex, allowing operatornames to use accented characters, but losing Greek uppercase.
 \item {\tt nosymbolsc} causes the package to not load the {\tt symbolsC} fonts, saving  a math family. (This font contains mostly exotic symbols, along with some very useful, commonly used symbols like \verb|\coloneq| $\coloneq$, \verb|\eqcolon| $\eqcolon$, \verb|\notin| $\notin$, \verb|\notni| $\notni$, \verb|\neq| $\neq$, \verb|\nsubset| $\nsubset$ and \verb|\nsupset| $\nsupset$, but these have been moved (virtually) to {\tt lettersA} so they may continue to be used even if you use the option {\tt nosymbolsc}.) If this option is selected, then, as of version 1.53, new definitions are made for the missing negated symbols. The package {\tt centernot} is now required.
@@ -860,7 +863,7 @@ Here is a sample  preamble showing the elements you will need to specify to gene
 \InputIfFileExists{glyphtounicode-ntx.tex}{}{}
 \usepackage{newtxtext} %T1 is default encoding
 \usepackage[scaled=0.95]{inconsolata}  % typewriter
-%\usepackage[leqno]{amsmath} 
+\usepackage[leqno]{amsmath} % must be loaded before amsthm
 \usepackage{amsthm}
 \usepackage[vvarbb]{newtxmath} % vvarbb gives STIX Bbb
 \end{verbatim}
@@ -879,14 +882,46 @@ and then use \verb|$x_{\jj}$| instead of \verb|$x_j$|, turning $x_j$ into $x_{\j
 There are also interactions with {\tt pstricks} that have to be worked around because {\tt subscriptcorrection} redefines \verb|_| as an active character, as do parts of {\tt pstricks}. In particular, the {\tt pstricks} short forms for macros like \verb|\tbput| and \verb|\nbput| for attaching labels beneath node connections must be avoided.
 
 
-If you do enable {\tt subscriptcorrection}, there is a default correction table in the {\tt sty} file, but the sty file also looks for a file named, e.g., {\tt newtx-subs.tex} if you are using the {\tt newtx} default math letters. There is already such a file located in the {\tt newtx} distribution in the \verb|/tex/latex/| folder. If you wish to make changes to this file, copy the file to your home TeX folder where it will be found by TeX before the one in the distribution. The entries in the file are lines like
+If you do enable {\tt subscriptcorrection}, there is a default correction table in the {\tt sty} file, but the sty file also looks for a file named, e.g., {\tt newtx-subs.tex} if you are using the {\tt newtx} default math letters. There is already such a file located in the {\tt newtx} distribution in the \verb|/tex/latex/| folder. For the moment, the recommended way to override the entries that file is to make
+entries in a \verb|filecontents*| environment as below.
+
+\textbf{A sample {\tt newtx-subs.tex}}\\
+Copy the entire block below, starting with the line \verb|\begin{...| and ending after the line beginning \verb|\end{|
+and paste it into the top of your document before the \verb|\documentclass...| line, which will allow for easy editing and will write the file to the same folder as your document.
+
+(New as of version $1.658$:) If you wish to make changes to {\tt newtx-subs.tex}, it is possible though not wise to copy the file to your home TeX folder where it will be found by TeX before the one in the distribution. The problem is that it is easy to forget where the file is located when you want to make changes. For the moment, my advice is to place the file contents with your changes inside a {\tt filecontents} environment at the top of your source file, as shown below. The effect will be to write that file in the same folder as your source, overwriting any existing copy. Version $1.658$ also offers you a new option {\tt subscriptcorrectionfile} that lets you specify a file name other than the default {\tt newtx-subs.tex} that can be used to specify a subscript correction file for some special use.
+
 \begin{verbatim}
+\begin{filecontents*}[force,nosearch]{newtx-subs.tex}
+{f}{-3}
 {j}{-3}
+{p}{-1}
+{y}{-1}
+{A}{-3}
+{B}{-1}
+{D}{-1}
+{H}{-1}
+{I}{-1}
+{K}{-1}
+{L}{-1}
+{M}{-1}
+{N}{-0.5}
+{P}{-1}
+{X}{-1}
+{\rho}{-1.5}
+{\mu}{-1}
+\end{filecontents*}
 \end{verbatim}
-each of which will have the same effect as the above macro if the first item in the subscript is j. You can also specify Greek letters with lines like
+
+The entries in the file are lines like
+\begin{verbatim}
+{j}{-3}
+\end{verbatim}
+each of which will have the same effect as the above macro \verb|\jj| if the first item in the subscript is {\tt j}. You can also specify Greek letters with lines like
 \begin{verbatim}
 {\beta}{-1.5}
 \end{verbatim}
+
 The complete list of file names recognized for specifying subscript corrections is:
 \begin{verbatim}
 newtx-subs.tex
@@ -949,31 +984,6 @@ The AMS fonts replacement, {\tt ntxsym} corrects the former misplacement of \ver
 \fonttable{ntxsy}
 \newpage 
  
-\subsection{A sample newtx-subs.tex}
-You may either copy the entire block below, starting with the line \verb|\begin{...| and ending after the line beginning \verb|\end{|
-and pasting it into the top of your document before the \verb|\documentclass...| line, which will allow for easy editing and will write the file to the same folder as your document, or make your own file, omitting those outer two lines.
-
-\begin{verbatim}
-\begin{filecontents*}{newtx-subs.tex}
-{f}{-3}
-{j}{-3}
-{p}{-1}
-{y}{-1}
-{A}{-3}
-{B}{-1}
-{D}{-1}
-{H}{-1}
-{I}{-1}
-{K}{-1}
-{L}{-1}
-{M}{-1}
-{N}{-0.5}
-{P}{-1}
-{X}{-1}
-{\rho}{-1.5}
-{\mu}{-1}
-\end{filecontents*}
-\end{verbatim}
 \subsection*{The {\tt ebgaramond} option to newtxmath}
 As {\tt ebgaramond} has an x-height considerably smaller than {\tt newtx}, some amount of scaling is useful to bridge the gap. In making the replacement letters, I increased the size of the EBGaramond letters by 5\%, so make some scaling combination that compensates for this. The weights of {\tt ebgaramond} used in the substitutions were regular and semibold. This dictates one of the options used for {\tt ebgaramond}.
 
-- 
cgit v1.2.3

