[latex3-commits] [git/LaTeX3-latex3-latex2e] copyedits-chris: ltnews34: getting there (adc15a41)
Chris Rowley
car222222 at users.noreply.github.com.org
Tue Oct 19 11:38:55 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : copyedits-chris
Link : https://github.com/latex3/latex2e/commit/adc15a41c40d3f2d2aef24700d591e3bcb6945a2
>---------------------------------------------------------------
commit adc15a41c40d3f2d2aef24700d591e3bcb6945a2
Author: Chris Rowley <car222222 at users.noreply.github.com>
Date: Tue Oct 19 16:38:55 2021 +0700
ltnews34: getting there
Still some queries in emails
No intro yet
No final tidying
>---------------------------------------------------------------
adc15a41c40d3f2d2aef24700d591e3bcb6945a2
base/doc/ltnews34.tex | 244 ++++++++++++++++++++++++++------------------------
1 file changed, 128 insertions(+), 116 deletions(-)
diff --git a/base/doc/ltnews34.tex b/base/doc/ltnews34.tex
index e1d450a9..8551f40b 100644
--- a/base/doc/ltnews34.tex
+++ b/base/doc/ltnews34.tex
@@ -34,7 +34,7 @@
\documentclass{ltnews}
-%%CCC Temporary definitions:
+%%CCC Temporary definitions: CCC Remove these!
\providecommand\Dash {\unskip ---}
@@ -119,7 +119,8 @@
\tubcommand{\input{tubltmac}}
\publicationmonth{November}
-\publicationyear{2021 --- Second Draft Version (with unfinished blocks and unresolved queries)}
+\publicationyear{2021 --- Third Draft Version
+ (not quite cmplete, eg needs Intro?)} %% CCC
\publicationissue{34}
@@ -140,9 +141,9 @@
\emph{Not yet written}
-\section{???}
+\subsection{???}
-\emph{write}
+\emph{write} ??
@@ -204,9 +205,9 @@ such as \hook{babel/\meta{language}/afterextras}
that enable a user
to add language specific declarations to these \enquote{extras}. One can then write
\begin{verbatim}
-\ActivateGenericHook
+ \ActivateGenericHook
{babel/ngerman/afterextras}
-\AddToHook{babel/ngerman/afterextras}
+ \AddToHook{babel/ngerman/afterextras}
{\color{blue}}
\end{verbatim}
after which all German words would be colored blue in the text.
@@ -258,9 +259,9 @@ Classes, packages and included files can only be loaded once in a
files have been made one-time hooks. Beside being more efficient, this
supports the following important use case
\begin{verbatim}
-\AddToHook{package/varioref/after}
- { ... apply when the package gets loaded,
- or apply now (if it is already loaded) ... }
+ \AddToHook{package/varioref/after}
+ {... apply when the package gets loaded,
+ or apply now (if it is already loaded) ...}
\end{verbatim}
without the need to first test whether the package is already loaded.
%
@@ -333,17 +334,17 @@ confusion and also led to further problems.
The implementation has now been changed, so that
\cs{RemoveFromHook} removes only code
-labels that already exist in a hook: it will display a warning if there is no such code label.
-%% CCC meaning?? :
-%% When this is used across packages
-%% FMi: meaning that if package A want's to get rid of what package B might have done it should use a ``void'' relation, but if you are within your own code and have set up something and at a later point want to remove it again then RemoveFromHook is fine (and the right solution).
-For removing code from a hook, the
-\texttt{voids} relation should preferably be used instead: this relation is
-non-destructive (meaning it can be later reverted by using another relation), and
-%%FMi it is independent of pkg order but that has nothing to do with previous part, so no ``so''
-%%so
-it is truly independent of package loading order.
-%% CCC so it should be preferred.
+labels that already exist in a hook: it will display a
+warning if there is no such code label.
+
+Note that, whereas when working with a single package
+you should use \cs{RemoveFromHook} to remove a code label,
+when working with more than one package, the
+\texttt{voids} relation should preferably be used.
+%
+This is best because this relation is non-destructive
+(meaning that it can be later reverted by using another relation),
+and it is also truly independent of package loading order.
%
\githubissue{625}
@@ -358,25 +359,25 @@ it is truly independent of package loading order.
\subsection{\cs{PackageNote} and \cs{ClassNote} added}
-\LaTeX{} offers these three commands:\cs{PackageError} to signal errors that stop
-processing; \cs{PackageWarning} to generate a warning message on the
-terminal but continue with the processing; and \cs{PackageInfo}
+\LaTeX{} offers these three commands:\cs{PackageError} to signal errors that
+stop the processing; \cs{PackageWarning} to generate a warning message on the
+terminal but continue with the processing; and \cs{PackageInfo}
to provide some information that is only written to the \texttt{.log}
file but not sent to the terminal.
%
What has not existed up to now is a way to provide
information on the terminal that identifies itself as coming from
-a specific package but which does not claim to be a warning. (Packages that wanted to write to the terminal used \cs{PackageWarning}
+a specific package but which does not claim to be a warning.
+(Packages that wanted to write to the terminal used \cs{PackageWarning}
even though the information wasn't really a warning.)
-We have therefore
-now added \cs{PackageNote} and \cs{PackageNoteNoLine}, that identify
-themselves as \enquote{informational}, but that still go to the terminal and
-not only to the transcript.
-% CCC ?? And: say what the NoLine means?
-%% FMi That exists for 30 year for \PackageWarningNoLine \PackageInfoNoLine and the like so don't think it is needed. But in case you don't know it... it doesn't report the line at which the warning/info/note was discovered.
+We have therefore now added \cs{PackageNote} (and the closely
+related \cs{PackageNoteNoLine}): these identify
+themselves as \enquote{informational}, but they still go to the terminal and
+not only to the \texttt{.log} file.
+%
Similar commands exist for classes and so there too we have
-added the two new commands \cs{ClassNote} and \cs{ClassNoteNoLine}.
+new commands: \cs{ClassNote} and \cs{ClassNoteNoLine}.
%
\githubissue{613}
@@ -384,18 +385,17 @@ added the two new commands \cs{ClassNote} and \cs{ClassNoteNoLine}.
\subsection{New argument for \cs{counterwithin/without}}
The commands \cs{counterwithout} and \cs{counterwithin} each now has
-an additional optional argument, similar to the command
-%% CCC so it becomes a drop-in replacement for
+an additional optional argument, similar to that for the command
+ \cs{numberwithin} from \pkg{amsmath},
%% FMi the implicit suggestion is to use the kernel method
- \cs{numberwithin} from \pkg{amsmath}.
+%% CCC Like this? EMAIL
+for which these are now the preferred replacements.
This optional argument
specifies the format of the counter, such as \cs{roman},
the default value being \cs{arabic}.
-
-
-\subsection{New default for \cs{tracinglostchars}}
+\subsection{New default value for \cs{tracinglostchars}}
In 2021 all \TeX{} engines were enhanced so that \cs{tracinglostchars}
supported the extra value \texttt{3}, that turns missing
@@ -405,12 +405,21 @@ This engine change made us
realize that \LaTeX{} should set a better default value for this parameter
(previously, the warning was written only to the transcript file).
Using the now available \texttt{3} as the default would really be best, but for
-compatibility reasons we have only set it to \texttt{2} in the kernel.
+compatibility reasons we have only increased it to \texttt{2} in the kernel.
%
-However, we recommend adding \cs{tracinglostchars}\texttt{=3} to the
-preamble of documents: this is because having missing glyphs in the output is definitely an
-error and should therefore be flagged as such (to ensure that it gets proper attention).
+However, we recommend setting \cs{tracinglostchars}\texttt{=3},
+in either a package or the
+preamble of your documents: this is because having missing glyphs
+in the output is definitely an error and should therefore be
+flagged as such (to ensure that it gets proper attention).
+%% CCC ADD see also ... another reason
+\iffalse
+We
+strongly recommend this, especially for Unicode engines where missing
+characters are common as no font supports the full Unicode range.
+%% CCC From text accents in math
+\fi
\subsection{Tests for package and class loading}
@@ -495,17 +504,17 @@ The only remedy for this was to
define your own math version, which is a complicated and cumbersome process.
This situation has now been improved by the introduction of a new counter
-\texttt{localmathalphabets}, which governs how many of the math group
-slots are assigned only locally when a new math alphabet (and a new
-math group) is needed.
+\texttt{localmathalphabets}: this counter governs how many of
+the math group slots are assigned only locally when a new math
+alphabet (and a new math group) is needed.
%
Once the current formula is finished, every such further (local)
allocation is undone, giving you a fighting chance of being
able to use different new math alphabets in the next formula.
-%
+
The default value of \texttt{localmathalphabets} is 2,
but if you need more local alphabets because of the complexity of your
-document, you can set this to a higher value, e.g., 4 or 5.
+document, you can set this to a higher value such as 4 or 5.
Setting it even higher is possible, but this would seldom
be useful because many group slots will be taken up by
symbol fonts and such slots are always permanently allocated,
@@ -514,17 +523,18 @@ whether used or not.
\githubissue{676}
+\subsection{Better handling for a misuse of \cs{include}}
-\subsection{Improvements to \cs{include}}
-If \cs{include} is used before \verb|\begin{document}| then previously
- it would write \verb|\@include{...}| to the terminal and log as the
- aux file has not yet been opened. It also locally changed
- the aux filename which could have unintended effects. \LaTeX\ now
- warns about any use of \cs{include} before \verb|\begin{document}|
- and as a recovery action will input the specified file if it exists (as
- before) but without any adjustments to the aux file settings, and
- without running the \cs{include} file hooks (only the generic file
- hooks from \cs{InputIfFileExists}).
+The command \cs{include} is by now getting used quite often, but
+erroneously, to input a variety files in the preamble of the document
+(before \verb|\begin{document}|).
+%
+Therefore \LaTeX\ now warns about such bad use of \cs{include}.
+As a recovery action it will nevertheless input the specified file
+if it exists (this is as before). Note, however, that this is now done
+without any adjustments to the aux file settings and without running
+the \cs{include} file hooks (only the generic
+file hooks from \cs{InputIfFileExists} are run).
%
\githubissue{645}
@@ -534,26 +544,24 @@ If \cs{include} is used before \verb|\begin{document}| then previously
\subsection{Check ``\cs{endfoo}'' in \cs{NewDocumentEnvironment}}
-%% CCC needs further visual improvement
The \cs{newenvironment} command has always checked that neither \cs{foo} nor
\cs{endfoo} exists before creating a \texttt{foo} environment.
-In contrast, \cs{NewDocumentEnvironment}
+In contrast (for historical reasons) the more recently introduced
+command \cs{NewDocumentEnvironment}
checked only for \cs{foo}.
-%% CCC removed since not understood.
-%% this reflects the fact that historically the code was
-%% designed around the target of an entirely new format.
-%%FMi what Joseph meant is that the code was initiall written for a new standalone format initially and so not faithfully done error recovery the way 2e did it.
-
-The behavior of \cs{NewDocumentEnvironment}
-now aligns with that of \cs{newenvironment}, except that it gives distinct errors
+%
+The behavior of \cs{NewDocumentEnvironment} now aligns with that
+of \cs{newenvironment}, except that it gives distinct errors
concerning the existence of \cs{foo} and \cs{endfoo}.
+
\subsection{Improve the error message ``\cs{begin} ended by''}
In the past it was possible to get an error message something
like \verb=\begin{foo} ended by \end{foo}=. This could happen when the
-environment name was partly hidden inside a macro. It happened because the test was
-comparing the literal strings while the error message fully expanded them.
+environment name was partly hidden inside a macro. It happened because
+the test was comparing the literal strings, whereas in the error message
+these got fully expanded.
%
This has now been changed to show a more sensible error
message in this instance.
@@ -563,8 +571,8 @@ message in this instance.
\subsection{Additional Extended Latin characters predefined}
-Some additional characters, such as \'k (U+1E131), are now pre-defined and
-will work without needing a \verb|\DeclareUnicodeCharacter| declaration.
+More characters, such as \'k (U+1E131), are now pre-defined and
+do not need a \verb|\DeclareUnicodeCharacter| declaration.
%
\githubissue{593}
@@ -581,14 +589,14 @@ A \cs{contentsline} command in the TOC file is always followed by
four arguments, the last one being empty except when using the
\pkg{hyperref} package. The \cs{contentsline} command itself only used the
first three arguments and it relied on the fourth being empty (and thus
-doing no harm). But this assumption is not always correct, e.g., if
-you use \pkg{hyperref} and then remove
-%%CCC What is "it" here:
-%%FMi it is hyperref ... but I agree the writing is not clear (you use hyperref then drop it so that aux file is left with an extra argument which is next time no longer use so blows up
-it from the preamble.
+doing no harm).
+%
+But this assumption is not always correct: e.g., if
+you at first decide to load \pkg{hyperref} but then later you remove
+this loading from the preamble.
%
-So now the code picks up all four arguments, saving the
-last one away so that it can be used by \pkg{hyperref}.
+So now all four arguments ate picked up, with the
+fourth being saved away so that it can be used by \pkg{hyperref}.
%
\githubissue{633}
@@ -601,39 +609,49 @@ the callback handler indicates removal of the entire math list.
%
\githubissue{644}
-
\subsection{Extended label handling in Package code}
Since 2020, as noted in \LaTeX News 32~\cite{34:ltnews32}, \LaTeX\ has
recorded the name of the counter associated with the current label in
the internal command \cs{@currentcounter}. This facility (originally
from the \pkg{zref} package of Heiko Oberdiek) can be used to generate
-prefixes such as \enquote{Figure} before the reference text. In the
-common case the current label is set by \cs{refstepcounter} and the
-counter name is stored automatically, but some constructs (alignments
-and footnotes) may need to store the current label directly. In such a
-case it is useful to also update \cs{@currentcounter}. In this release
-the footnote command in the kernel the \pkg{amsmath} package has been
-updated in this way. We encourage maintainers of any class and
-package files that are defining \cs{@currentlabel} to set
+prefixes such as \enquote{Figure} before the reference text.
+%
+In the most
+common cases the current label is set by \cs{refstepcounter}, which
+automatically stores the counter name; but some constructs (alignments
+and footnotes) may need to store the current label directly and so for
+these it is useful to update additionally \cs{@currentcounter} so as to
+store this counter name.
+
+In this release both the footnote command in the kernel and
+also some of the environments in the \pkg{amsmath} package
+have been updated in this way.
+%
+We encourage the maintainers of any class or
+package files that defines \cs{@currentlabel} to also set
\cs{@currentcounter} at the same point.
%
\githubissue{300, 687}
-\subsection{Better Error handling of text accents in Math}
+\subsection{Better error when text accent used in mathmode}
+%% CCC \subsection{Better Error handling of text accents in Math}
+
If you use a text accent such as \verb|\^| in math mode instead of the
math accent \cs{hat}, then \LaTeX\ gives a warning,
which is usually followed by a \TeX\ primitive error message produced by the \cs{accent} command.
If the accent and base would form a composite character in text mode,
(often the case with Unicode engines) then typically you will get
a warning such as\\
-\verb|Missing character:|\\
-\verb| There is no á (U+00E1) in font cmmi10!|\\
+\verb| Missing character:|\\
+\verb| There is no á (U+00E1) in font cmmi10!|\\
+%% CCC fix non-ascii character in verbatim ??
With \TeX\ implementations from 2020 onwards this warning can be
converted to an error by setting \cs{tracinglostchars} to 3 in the preamble. We
strongly recommend this, especially for Unicode engines where missing
characters are common as no font supports the full Unicode range.
+%% CCC ADD see also ... another reason in value of tracinglost
%
\githubissue{643}
@@ -646,7 +664,7 @@ characters are common as no font supports the full Unicode range.
\subsection[Replicate argument processors for all
embellishments in command declarations]
- {Replicate argument processors for all \\ %%CCC ??
+ {Replicate argument processors for all \\
\mbox{}\qquad embellishments in command declarations}
There was a bug in \pkg{ltcmd} (formerly \pkg{xparse}) that caused
@@ -657,9 +675,9 @@ resulting in too few processors in some cases and thus leading to unpredictable
behavior. This bug has been fixed by applying the same argument
processors to all the embellishments in a set, so that a declaration like:
\begin{verbatim}
-\NewDocumentCommand\foo{>{\TrimSpaces}e{_^}}
- {(#1)[#2]}
-\foo^{ a }_{ b }
+ \NewDocumentCommand\foo{>{\TrimSpaces}e{_^}}
+ {(#1)[#2]}
+ \foo^{ a }_{ b }
\end{verbatim}
will now correctly apply \cs{TrimSpaces} to both arguments.
%
@@ -740,17 +758,6 @@ This key is unused by default; it can be deployed by extension packages and it w
\section{Changes to packages in the \pkg{tools} category}
-\subsection{\pkg{varioref}: Improved handling of missing labels}
-
-If an undefined label is referenced, \pkg{varioref} makes a default
-definition so that later processing finds the right structure (two
-brace groups inside \cs{r@}\meta{label}) However, if \pkg{nameref} or
-\pkg{hyperref} is loaded this data structure changes to having five
-arguments; this could cause low-evel errors in some cases. The code has therefore now
-been changed to avoid these errors.
-%
-\sxissue{603948}
-
\subsection{\pkg{array}: No \cs{mathsurround} around a \env{tabular}}
A \env{tabular} environment is typeset (internally) as an \env{array}
@@ -763,6 +770,7 @@ Note that this bug has been present ``forever’’, which shows that \cs{maths
%
\githubissue{614}
+
\subsection{\pkg{longtable}: Improvements after a section heading}
The \env{longtable} environment now sets the \cs{@nobreakfalse} flag
to correct the typesetting when a table immediately follows a heading.
@@ -781,16 +789,27 @@ a run-in heading rather than appearing before that heading.
\subsection{\pkg{multicol}: Better column break control}
From version 1.9 onwards \cs{columnbreak} accepts an optional
-argument (just like \cs{pagebreak}) in which you can specify the
-desirability to break the column after the current line: supported values are
-\texttt{1} to \texttt{4} with higher numbers increasing the likelihood.
-This version also adds \cs{newcolumn}
-which forces a column break but runs the column short (comparible to
+argument (like \cs{pagebreak}) in which you can specify the
+desirability of breaking the column after the current line: supported values are
+\texttt{1} to \texttt{4}, with higher numbers indicating increased desirability.
+This version also adds \cs{newcolumn},
+which forces a break but runs the column short (comparable to
\cs{newpage} for pages).
%
\githubissue{682}
+\subsection{\pkg{varioref}: Improved handling of missing labels}
+
+If an undefined label is referenced, \pkg{varioref} makes a default
+definition so that later processing finds the right structure (two
+brace groups inside \cs{r@}\meta{label}) However, if \pkg{nameref} or
+\pkg{hyperref} is loaded this data structure changes to having five
+arguments; this could cause low-evel errors in some cases. The code has therefore now
+been changed to avoid these errors.
+%
+\sxissue{603948}
+
\section{Changes to packages in the \pkg{amsmath} category}
\subsection{Improved compatibility with \pkg{hyperref}}
@@ -801,7 +820,7 @@ method used in \pkg{hyperref} to change the \env{equation} environment.
For simplicity, an explicit, low-level (hence possibly temporary)
patch has been added to \pkg{amsmath}: this consists of an extra, empty (hence invisible)
\cs{mathopen} atom (with no mathematical meaning) at the start of the
-environment’s mathematical content.
+environment's mathematical content.
%
\githubissue{652}
@@ -833,11 +852,4 @@ environment’s mathematical content.
\end{document}
-%%CCC original re hyperref/amsmath
-When \pkg{hyperref} is used, increkmenting a counter creates anchors and this can affect spacing.
-For a long time \pkg{hyperref} patched the \env{equation} environment to
-avoid some of the side effects. This patch has now been moved directly into \pkg{amsmath}.
-Additionally,
-a \cs{mathopen} has been added to avoid that the anchor affects a following unary symbol.
-
More information about the latex3-commits
mailing list.