diff options
Diffstat (limited to 'macros/latex-dev/base/ltnews37.tex')
| -rw-r--r-- | macros/latex-dev/base/ltnews37.tex | 472 |
1 files changed, 394 insertions, 78 deletions
diff --git a/macros/latex-dev/base/ltnews37.tex b/macros/latex-dev/base/ltnews37.tex index a1197e1052..5b2a55dda3 100644 --- a/macros/latex-dev/base/ltnews37.tex +++ b/macros/latex-dev/base/ltnews37.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright 2021-2023 +% Copyright (C) 2021-2023 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -124,7 +124,8 @@ % \publicationday{01} % change this if it's not released on 1st of a month \publicationmonth{June} -\publicationyear{2023 --- DRAFT version for upcoming release} +%\publicationyear{2023 --- DRAFT version for upcoming release} +\publicationyear{2023} \publicationissue{37} @@ -142,7 +143,8 @@ \medskip -\section{Introduction} +%\section{Introduction} + \section{New functionality offered as part of the @@ -150,7 +152,8 @@ We have now enabled new automatic tagging functionality for additional \LaTeX{} elements, among them most display environments, standard -sectioning commands and content, figure and table listings. This can +sectioning commands, content, figure and table listings, floats and graphics and +bibliographies. This can be activated through \begin{verbatim} \DocumentMetadata{testphase=phase-III} @@ -168,9 +171,9 @@ alter internals of \LaTeX{}. Also note that there are still several environments and commands described in the \LaTeX{} manual that do not have tagging support yet, -notably tabulars, floats, \texttt{tabbing} and the various math -environment. They will get this support as part of \texttt{phase-III} -between now and the June release. +notably tabulars, \texttt{tabbing}, the various math environment and a +few others. They will get this support as part of \texttt{phase-III}, +but some of them will be delayed until after the June release. A prototype for math tagging (including support for the \pkg{amsmath} environments) is already available, but it is mainly intended for @@ -194,60 +197,84 @@ be accessed with \verb|texdoc -l latex-lab|. Feedback is welcome! Please use \url{https://github.com/latex3/latex2e/discussions/1010}. -\section{Documentation improvements} - - -\subsection{Displaying the exact release dates for \LaTeX{}} - -In some situations it is necessary to find out the exact release dates -for older version of the \LaTeX{} format, for example, when you need -to use different code in a package depending on the availablilty of a -certain feature and you therefore want to use -\cs{IfFormatAtLeastTF}\texttt\{\meta{date}\texttt\} or the -rather horrible construction \verb/\@ifl@t@r\fmtversion{/\meta{date}\texttt\}, -if you -want to cater for formats that are older than 2020. - -Or you know that your package is definitely not going to work with a -format before a certain \meta{date}, in which case you could use -\verb/\NeedsTeXFormat{LaTeX2e}[/\meta{date}\texttt] to ensure that any - user is alerted if their format is too old. - -The big problem is to know the exact \meta{date} to put into such -commands and in the past that was not that easy to find. You could have -looked in the the file \file{changes.txt}, but that is hidden somewhere -in your installation and if you try -\verb*/texdoc -l changes.txt/ you get more than thirty results and the -right file is by no means the first. - -Yukai Chou (\textsf{@muzimuzhi}) kindly provided a patch for this, so that we now have -the exact dates for each \LaTeX{} format listed in an easy to remember -place: in \file{ltnews.pdf} and that file conveniently also contains all major -features and changes to \LaTeX{} over the years\Dash one of which is -most likely the reason you need the \meta{date} date in the first -place. - -It is given in parentheses in the newsletter title, thus this -newsletter tells you that on -% -\makeatletter -\mbox{\expandafter\@gobblenonyear\@year\@nil - -\@julianmonthtonum\@month-\two@digits\@day} -\makeatother -% -the command -\cs{NewEnvironmentCopy}, a new \texttt{shipout} hook, etc.\ was made -available. And looking into \file{ltnews.pdf} you can now easily find -out that the \LaTeX3 programming layer was added on 2020-02-02 -(because the date was so nice) and not on the first of the month. -% -\githubissue{982} - \section{New or improved commands} +\subsection{Extending hooks to take arguments} + +Hooks have always been containers for code whose outcome was entirely +dependent on the contents of the hook alone. If any type of contextual +information had to be passed to the hook, it had to be done by setting +some variable before the hook so that the code in the hook could use +that. But this is somewhat hard to keep track of, clumsy to implement, +and it required the programmer to have some kind of \enquote{hook before +the hook} to do that setup. + +To make things a bit easier, \pkg{lthooks} was enhanced to support hooks +with arguments. Hooks can now be declared and used with arguments, then +the code added to these hooks can reference the hook's arguments using +\verb|#1|, \verb|#2|, etc., so now hooks can behave more like macros +than like \emph{token lists} (using \pkg{expl3} terminology). Regular +argument-less hooks continue to work exactly like they did before: this +extension is completely compatible with older documents and packages. + +\AddToHook{cmd/verbatim@font/after}[hack]{\small} +To declare a hook with arguments, use +\begin{verbatim} +\NewHookWithArguments {<hook>} {<num args>} +\end{verbatim} +then, similarly, to use the code in the hook (supposing a hook declared +with 2 arguments), write +\begin{verbatim} +\UseHookWithArguments {<hook>} {2} {<arg 1>} {<arg 2>} +\end{verbatim} + +Or, if you want to add some code to a hook that takes arguments, write +\begin{verbatim} +\AddToHookWithArguments {<hook>} [<label>] {<code>} +\end{verbatim} +exactly like you would for regular hooks, except that the \meta{code} +can use the arguments by referencing \verb|#1|, \verb|#2|, etc. In this +case, if you want to add an actual parameter token (\verb|#|) to the +\meta{code}, you have to double it, as usual. +\RemoveFromHook{cmd/verbatim@font/after}[hack] + +Additionally, if you want to add \enquote{regular} code to a hook with +arguments, you can still use \cs{AddToHook} --- in that case \verb|#| +tokens are \emph{not} doubled. This means that a package author can +decide to add arguments to an existing hook without worrying about +compatibility: \cs{AddToHook} will do the right thing and will not +mistakenly reference the newly added arguments. + +The commands \cs{NewReversedHookWithArguments}, \cs +{NewMirroredHookPairWithArguments}, \cs +{AddToHookNextWithArguments}, \cs{UseOneTimeHookWithArguments}, and +the \pkg{expl3} conterparts of the commands discussed in this section +were also added. The complete documentation can be found in the +\pkg{lthooks} documentation \cite{37:lthooks-doc}. + +\subsubsection{Generic \texttt{cmd} hooks with arguments} + +Along with the possibility to pass arguments to a regular hook as +discussed above, generic \hook{cmd} hooks now can access the arguments +of the command they are patched into using the interface described in +the previous section. + +For example, if you were to add some code to the \cs{title} command +using hooks, you could access the actual title given in the argument. +For example, to write the title of the document in the terminal you +could use: +\begin{verbatim} + \AddToHookWithArguments{cmd/title/before} + {\typeout{Document title: #1}} +\end{verbatim} +As with regular hooks, code added to a \hook{cmd} hook using +\cs{AddToHook} will not be able to access the command's arguments. This +means that, as with regular hooks, this change is completely backwards +compatible, so previous usages of \hook{cmd} hooks will work exactly as +they did before. \subsection{Providing copy and show functions for environments} @@ -279,31 +306,124 @@ following output: % \githubissue{963} +\subsection{\cs{IfFileAtLeastTF}} +The 2020-10-01 \LaTeX{} release introduced the CamelCase tests +\cs{IfClassAtLeastTF} and \cs{IfPackageAtLeastTF} for checking class +and package dates. We have now added \cs{IfFileAtLeastTF} to allow the +same to happen for generic files which contain a \cs{ProvidesFile} +line. +% +\githubissue{1015} + +\subsection{\cs{DeclareLowercaseMapping}, \cs{DeclareTitlecaseMapping} + and \cs{DeclareUppercaseMapping}} + +The move from a case-changing approach using \cs{lccode} and \cs{uccode} data +to one where information is stored by a kernel-managed structure left a gap in +the ability of the user to \emph{tune} the case changing outcomes. This has now +been addressed by the addition of three commands +\begin{itemize} + \item \cs{DeclareLowercaseMapping} + \item \cs{DeclareTitlecaseMapping} + \item \cs{DeclareUppercaseMapping} +\end{itemize} +which can be used to customise the outcome for codepoints. This can be applied +generally or to a specific locale (see also the next section). A small number +of pre-defined customisations have been set up in the kernel where the outcomes +for \pdfTeX{} should be different for those from Unicode engines. For +example +\begin{verbatim} + \DeclareUppercaseMapping{"01F0}{\v{J}} +\end{verbatim} +allows \v{J} to be produced in 8-bit engines: without this customisation, +an error would occur as there is no pre-composed \v{J} in Unicode. More detail +is given in \texttt{usrguide}. +% +\githubissue{1033} + +\subsection{\cs{BCPdata}} + +Improvements in the Unicode handling for case changing have highlighted that +the kernel has not to-date been locale-aware. The packages \pkg{babel} and +\pkg{polyglossia} provide comprehensive locale support, but did not have +an agreed unified interface to pass that information back to other code. +Following discussion with the maintainers of those two bundles, the kernel +now defines \cs{BCPdata} as a stub (so it is always defined), and \pkg{babel} +and \pkg{polyglossia} will redefine it to provide the locale data. An agreed +set of keywords mean that \cs{BCPdata} can be queried in a structured way +by both the kernel and any other \enquote{consumer} packages. +% +\githubissue{1035} + +\subsection{Improve \cs{samepage}} + +The \cs{samepage} declaration sets various parameters to +\texttt{10000} to prevent undesired page breaks. The +\cs{predisplaypenalty} parameter has already by default a value of +\texttt{10000} and to save space back in the days it was therefore not +explicitly set. However, there are a few classes that change the +parameter and as result the user might experience a page break in +front of a display formula within the scope of \cs{samepage} when +using such classes. This has now been corrected and +\cs{predisplaypenalty} is also explicitly set to \texttt{10000}. +% +\githubissue{1022} +\subsection{Groups in \cs{MakeUppercase}} +% +Prior to 2022, \cs{MakeUppercase} and \cs{MakeLowercase} used a brace +group around their argument so providing a scope for any declarations +within the argument. This grouping has been restored (also +for \cs{MakeTitlecase}), although the underlying L3 text case commands do +not use grouping. +% +\githubissue{1021} + +\subsection{Extension of the \cs{label} command} + +Previously, in standard \LaTeX{}, the \cs{label} command wrote a \cs{newlabel} declaration into +the \texttt{.aux} file and stored two values in +second argument of this \cs{newlabel} command: +\cs{@currentlabel}, which normally contains the state of the current +counter and \cs{thepage} for the current page number. + +The packages \pkg{hyperref} and +\pkg{nameref} then patched the \cs{label} command to store five values instead. +In addition to the above they saved \cs{@currentlabelname}, which normally contains the +current title text and can be retrieved with \cs{nameref}, and +\cs{@currentHref}, which is the name of the destination needed to create an +active link. The fifth argument was only used if external +references were loaded with the \pkg{xr-hyper} package. + +Starting with this release, the number of values stored in \cs{newlabel} have been unified. +\cs{label} now writes a +\cs{newlabel} command that always contains five values in the second argument (each in a brace group): +\cs{@currentlabel}, \cs{thepage}, \cs{@currentlabelname}, +\cs{@currentHref}, and \cs{@kernel@reserved@label@data} (which is reserved for the kernel). + +Additionally, a hook with the name \texttt{label} has been +added. It takes one argument: the label string. +Code added to the hook can refer to this argument with \verb+#1+. +The hook is executed directly before the \cs{label} command writes to the \texttt{.aux} file +but \emph{after} the \cs{@bsphack} command has done its spacing magic and it is located \emph{inside} a group, thus its code only affects the write operation. \section{Code improvements} -\subsection{\pkg{doc}: Index \texttt{\textbackslash\textvisiblespace} correctly} - -\emph{to write} -% -\githubissue{943} +\subsection{Performance in checking file existence} +The addition of hooks, etc., to file operations had a side-effect in that +multiple checks were made that the file existed. In larger documents using +lots of files, these file system operations caused non-trivial performance +impact. We now cache the existence of files, such that these repeated filesystem +calls are avoided. -\subsection{Default definition for \cs{do}} +\subsection{\pkg{doc}: Handle \texttt{\textbackslash\textvisiblespace} correctly in the index} -The command \cs{do} with its nice public name is in reality an -internal command inherited from plain \TeX{} for list -processing. However, it only got a definition when -\verb=\begin{document}= was executed, with a result that a user -definition in the preamble was unconditionally overwritten at this -point. To properly alert the user that this command is not freely -available we now already provide a definition in the format so that -\cs{newcommand} and friends produce a proper error message instead of -providing a definition that doesn't last. +Due to some problems in the code it wasn't possible to prevent +\verb*=\ = from showing up in the index\Dash \verb=\DoNotIndex{\ }=, etc.\ had no effect. This has now been corrected. % -\githubissue{975} +\githubissue{943} \subsection{\pkg{doc}: Support the \pkg{upquote} package} @@ -341,6 +461,23 @@ desired effect. \githubissue{953} +\subsection{Default definition for \cs{do}} + +The command \cs{do} with its nice public name is in reality an +internal command inherited from plain \TeX{} for list +processing. However, it only got a definition when +\verb=\begin{document}= was executed, with a result that a user +definition in the preamble was unconditionally overwritten at this +point. To properly alert the user that this command is not freely +available we now already provide a definition in the format so that +\cs{newcommand} and friends produce a proper error message instead of +providing a definition that doesn't last. +% +\githubissue{975} + + + + \subsection{New key for \env{filecontents}} The \env{filecontents} environment warns on the terminal if a file @@ -350,14 +487,13 @@ the warning less noisy in this case we added a new \texttt{nowarn} key that redirects the overwriting warning to the transcript file. We think that some record of the action is still required to help with debugging, thus it is not completely silenced. The warning that -nothing gets written, because the file aready exists (and the +nothing gets written, because the file already exists (and the \texttt{force} key was not used), is not altered and still shows up on the terminal. % \githubissue{958} - \subsection{A further hook for shipping out pages} Since October 2020 the shipout process offers a number of hooks to @@ -429,10 +565,21 @@ group (i.e., any local changes would immediately be revoked, breaking, for example, \pkg{wrapfig} in that special situation). % This got fixed with the 2022-11 PL1 hotfix, so was already corrected in -the previous release, but only now documented in a newletter. +the previous release, but only now documented in the newsletter. % \githubissue{967} +\subsection{Ensure that \cs{cs} is defined in \cls{ltxdoc}} + +The class \cls{ltxdoc} defined the command \cs{cs} to typeset a +command name with a backslash in front. This definition was moved to +the \pkg{doc} package itself. This meant that it was suddenly missing +when reverting to the old \pkg{doc} package implementation via the +class option \texttt{doc2}. This has now been corrected. +% +\githubissue{981} + + \subsection{Improve spacing at top of \env{minipages}} @@ -453,15 +600,180 @@ correct. \githubissue{989} +\subsection{A fix for \cs{NewCommandCopy} and \cs{ShowCommand}} + +When copying and showing definitions of (non-expandable) document commands +(aka commands defined by \cs{NewDocumentCommand} and friends) containing empty +or only \texttt{m}-type arguments, these commands were wrongly recognized as +expandable ones. +This is fixed in the present \LaTeX{} release. +% +\githubissue{1009} + +\subsection{Corrections for switching math version} +Some internal code improvements improve support for switching math version +when nested within an outer math expression. +This will improve \cs{boldsymbol} and \cs{bm} and similar commands. +% +\githubissue{1028} + +\subsection{Allow par as a filename} +\verb|\input{par}| or \verb|\includegraphics{par}| could give spurious +errors. This has been fixed by making an internal command \cs{long}. +% +\githubissue{942} + +\subsection{Correct setting of \cs{endlinechar} in \texttt{+v} arguments} +In the particular case of a document command with a \texttt{+v}-type +argument used inside \cs{ExplSyntaxOn}\texttt{/Off}, newlines would be +misinterpreted as spaces because the value of \cs{endlinechar} was +set too late. This has been fixed, and now newlines are correctly +translated to ``\verb|the character ^^M|''. +% +\githubissue{876} + +\subsection{Correct handling of hooks with only `next' code} +When \cs{AddToHookNext} was used on a not-yet-declared hook, that hook +would be incorrectly identified as empty by \cs{ShowHook}. Also, if +that hook was later declared, that `next' code would not be executed. +This has been fixed by correctly initializing the hook structure when +\cs{AddToHookNext} is used. +% +\githubissue{1052} + +\subsection{Ignoring space after \texttt{\$\$}} +Space is normally ignored after a closing \texttt{\$\$}, +but internal \LaTeX{} font handling code could interfere if +\cs{eqno} was used. \cs{eqno} and \cs{leqno} have been redefined +to add \cs{ignorespaces} after the math group. +% +\githubissue{1059} + +\section{Documentation improvements} + +\subsection{Updates to the guides} + +When \LaTeXe{} was released, the team provided documentation for both document +authors and package/class developers in the two files \texttt{usrguide} and +\texttt{clsguide}. Over time, the team have augmented these documents as new +methods have been added to the kernel. However, they retained there structure +as starting from familiarity with \LaTeX{}~2.09. This meant that for new users, +there was material which is no longer relevant, and less clarity than desirable +in what approaches are recommended today. + +The two files have now been (partially) re-written, with the versions available +previously now frozen as \texttt{usrguide-historic} and \texttt{clsguide-historic}. +More material has been carried forward in the class/package guide than in the +user guide, but both are worth a re-read by experienced \LaTeX{} users. + + + +\subsection{Displaying the exact release dates for \LaTeX{}} -\section{Changes to packages in the \pkg{amsmath} category} +In some situations it is necessary to find out the exact release dates +for older version of the \LaTeX{} format, for example, when you need +to use different code in a package depending on the availability of a +certain feature and you therefore want to use +\cs{IfFormatAtLeastTF}\texttt\{\meta{date}\texttt\} or the +rather horrible construction \verb/\@ifl@t@r\fmtversion{/\meta{date}\texttt\}, +if you +want to cater for formats that are older than 2020. -\section{Changes to packages in the \pkg{graphics} category} +Or you know that your package is definitely not going to work with a +format before a certain \meta{date}, in which case you could use +\verb/\NeedsTeXFormat{LaTeX2e}[/\meta{date}\texttt] to ensure that any + user is alerted if their format is too old. + +The big problem is to know the exact \meta{date} to put into such +commands and in the past that was not that easy to find. You could have +looked in the the file \file{changes.txt}, but that is hidden somewhere +in your installation and if you try +\verb*/texdoc -l changes.txt/ you get more than thirty results and the %* +right file is by no means the first. + +Yukai Chou (\textsf{@muzimuzhi}) kindly provided a patch for this, so that we now have +the exact dates for each \LaTeX{} format listed in an easy to remember +place: in \file{ltnews.pdf} and that file conveniently also contains all major +features and changes to \LaTeX{} over the years\Dash one of which is +most likely the reason you need the \meta{date} date in the first +place. + +It is given in parentheses in the newsletter title, thus this +newsletter tells you that on +% +\makeatletter +\mbox{\expandafter\@gobblenonyear\@year\@nil + -\@julianmonthtonum\@month-\two@digits\@day} +\makeatother +% +the command +\cs{NewEnvironmentCopy}, a new \texttt{shipout} hook, etc.\ was made +available. And looking into \file{ltnews.pdf} you can now easily find +out that the \LaTeX3 programming layer was added on 2020-02-02 +(because the date was so nice) and not on the first of the month. +% +\githubissue{982} + +\subsection{Fresh from the press: \enquote{The \LaTeX{} Companion, third edition} is now in print} + +The third edition of \emph{The \LaTeX{} Companion} is now +available. This is the end of five years of careful work and we hope +that it will provide our readers with all the information they need to +successfully navigate the \LaTeX{} ecosystem and efficiently produce +beautiful documents. + +Since the publication of the last edition (2004) a lot has happened in +the \LaTeX{} world and thus a complete rewrite was necessary. All +chapters have been thoroughly revised and in many cases largely +extended to describe new important functionality and features. More +than 5,000 add-on packages have been analyzed in detail, out of which +roughly 10\% have been chosen for inclusion in \emph{The \LaTeX{} +Companion}. All important aspects of these packages are described to +provide the user once again with a satisfying one-stop–shop experience +for the decade to come. + +To cover what we thought worth describing today, the book nearly +doubled in size. The print edition is therefore produced as a +two-volume set and sold as a bundle. Both volumes come as hard-cover +with ribbons to easily mark pages in the book. + +To give you an idea of what is covered in the third edition you can +find some excerpts at +\begin{quote} +\url{https://www.latex-project.org/news/2023/03/17/TLC3} +\end{quote} + +The edition is also available as an eBook (Parts I and II combined) +consisting of PDF and ePub format without DRM. Finally, the publisher +offers the combination of the printed books and the digital versions at +a very attractive price not available anywhere else. + + +%\section{Changes to packages in the \pkg{amsmath} category} + +%\section{Changes to packages in the \pkg{graphics} category} \section{Changes to packages in the \pkg{tools} category} -\subsection{Fix handling of nested \env{multicols}} +\subsection{\pkg{multicol}: Better support for CJK languages} + +The default minimum depth of each column in a \env{multicols} +corresponds to the depth of a \enquote{p} in the current font. This +helps to get some uniformity if rules are used between the columns and +makes sense for Latin-based languages. Until now it was hard-wired, +but for CJK (Chinese/Japanese/Korean) languages it is better to use a zero depth, because there +all characters have the same height and depth. And even with +Latin-based languages one might want to use the depth of a \cs{strut} +or that of a parenthesis. So we now offer a way to adjust this while +maintaining backward compatibility. Just redefine +\cs{multicolmindepthstring} to hold whatever you want to get measured +for its depth (the width is not relevant). +% +\githubissue{698} + + +\subsection{\pkg{multicol}: Fix handling of nested environments} If \env{multicols} environments have been nested into each other (the inner one boxed) it could fail if the boxed environment appeared near a @@ -484,6 +796,10 @@ page. This has now been fixed. \emph{The \texttt{\upshape ltshipout} documentation}.\\ Run \texttt{texdoc} \texttt{ltshipout-doc} to view. +\bibitem{37:lthooks-doc} Frank Mittelbach, Phelype Oleinik, \LaTeX{}~Project~Team: + \emph{\LaTeX's hook management}.\\ + Run \texttt{texdoc} \texttt{lthooks-doc} to view. + %\bibitem{37:blueprint} Frank Mittelbach and Chris Rowley: % \emph{\LaTeX{} Tagged PDF \Dash A blueprint for a large project}.\\ % \url{https://latex-project.org/publications/indexbyyear/2020/} |