| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 2021-2025 |
| 4 |
% The LaTeX Project and any individual authors listed elsewhere |
| 5 |
% in this file. |
| 6 |
% |
| 7 |
% This file is part of the LaTeX base system. |
| 8 |
% -—————————————— |
| 9 |
% |
| 10 |
% It may be distributed and/or modified under the |
| 11 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 12 |
% of this license or (at your option) any later version. |
| 13 |
% The latest version of this license is in |
| 14 |
% https://www.latex-project.org/lppl.txt |
| 15 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 16 |
% version 2008 or later. |
| 17 |
% |
| 18 |
% This file has the LPPL maintenance status "maintained". |
| 19 |
% |
| 20 |
% The list of all files belonging to the LaTeX base distribution is |
| 21 |
% given in the file `manifest.txt'. See also `legal.txt' for additional |
| 22 |
% information. |
| 23 |
% |
| 24 |
% The list of derived (unpacked) files belonging to the distribution |
| 25 |
% and covered by LPPL is defined by the unpacking scripts (with |
| 26 |
% extension .ins) which are part of the distribution. |
| 27 |
% |
| 28 |
% \fi |
| 29 |
% Filename: ltnews37.tex |
| 30 |
% |
| 31 |
% This is issue 37 of LaTeX News. |
| 32 |
|
| 33 |
\NeedsTeXFormat{LaTeX2e}[2020-02-02] |
| 34 |
|
| 35 |
\documentclass{ltnews} |
| 36 |
|
| 37 |
%% Maybe needed only for Chris' inadequate system: |
| 38 |
\providecommand\Dash {\unskip \textemdash} |
| 39 |
|
| 40 |
%% NOTE: Chris' preferred hyphens! |
| 41 |
%%\showhyphens{parameters} |
| 42 |
%% \hyphenation{because parameters parameter} |
| 43 |
|
| 44 |
\usepackage[T1]{fontenc} |
| 45 |
|
| 46 |
\usepackage{lmodern,url,hologo} |
| 47 |
|
| 48 |
\usepackage{csquotes} |
| 49 |
\usepackage{multicol} |
| 50 |
\usepackage{color} |
| 51 |
|
| 52 |
\providecommand\hook[1]{\texttt{#1}} |
| 53 |
|
| 54 |
\providecommand\meta[1]{$\langle$\textrm{\itshape#1}$\rangle$} |
| 55 |
\providecommand\option[1]{\texttt{#1}} |
| 56 |
\providecommand\env[1]{\texttt{#1}} |
| 57 |
\providecommand\Arg[1]{\texttt\{\meta{#1}\texttt\}} |
| 58 |
|
| 59 |
|
| 60 |
\providecommand\eTeX{\hologo{eTeX}} |
| 61 |
\providecommand\XeTeX{\hologo{XeTeX}} |
| 62 |
\providecommand\LuaTeX{\hologo{LuaTeX}} |
| 63 |
\providecommand\pdfTeX{\hologo{pdfTeX}} |
| 64 |
\providecommand\MiKTeX{\hologo{MiKTeX}} |
| 65 |
\providecommand\CTAN{\textsc{ctan}} |
| 66 |
\providecommand\TL{\TeX\,Live} |
| 67 |
\providecommand\githubissue[2][]{\ifhmode\unskip\fi |
| 68 |
\quad\penalty500\strut\nobreak\hfill |
| 69 |
\mbox{\small\slshape(% |
| 70 |
\href{https://github.com/latex3/latex2e/issues/\getfirstgithubissue#2 \relax}% |
| 71 |
{github issue#1 #2}% |
| 72 |
)}% |
| 73 |
\par\smallskip} |
| 74 |
%% But Chris has to mostly disable \href for his TEXPAD app: |
| 75 |
%% \def\href #1{} % Only For Chris' deficient TeX engine |
| 76 |
|
| 77 |
% simple solution right now (just link to the first issue if there are more) |
| 78 |
\def\getfirstgithubissue#1 #2\relax{#1} |
| 79 |
|
| 80 |
\providecommand\sxissue[1]{\ifhmode\unskip |
| 81 |
\else |
| 82 |
% githubissue preceding |
| 83 |
\vskip-\smallskipamount |
| 84 |
\vskip-\parskip |
| 85 |
\fi |
| 86 |
\quad\penalty500\strut\nobreak\hfill |
| 87 |
\mbox{\small\slshape(\url{https://tex.stackexchange.com/#1})}\par} |
| 88 |
|
| 89 |
\providecommand\gnatsissue[2]{\ifhmode\unskip\fi |
| 90 |
\quad\penalty500\strut\nobreak\hfill |
| 91 |
\mbox{\small\slshape(% |
| 92 |
\href{https://www.latex-project.org/cgi-bin/ltxbugs2html?pr=#1\%2F\getfirstgithubissue#2 \relax}% |
| 93 |
{gnats issue #1/#2}% |
| 94 |
)}% |
| 95 |
\par} |
| 96 |
|
| 97 |
\let\cls\pkg |
| 98 |
\providecommand\env[1]{\texttt{#1}} |
| 99 |
\providecommand\acro[1]{\textsc{#1}} |
| 100 |
|
| 101 |
\vbadness=1400 % accept slightly empty columns |
| 102 |
|
| 103 |
|
| 104 |
\makeatletter |
| 105 |
% maybe not the greatest design but normally we wouldn't have subsubsections |
| 106 |
\renewcommand{\subsubsection}{% |
| 107 |
\@startsection {subsubsection}{2}{0pt}{1.5ex \@plus 1ex \@minus .2ex}% |
| 108 |
{-1em}{\@subheadingfont\colonize}% |
| 109 |
} |
| 110 |
\providecommand\colonize[1]{#1:} |
| 111 |
\makeatother |
| 112 |
|
| 113 |
\let\finalvspace\vspace % for document layout fixes |
| 114 |
|
| 115 |
% Undo ltnews's \verbatim@font with active < and > |
| 116 |
% (we have meta variables in verbatim, so keep it.) |
| 117 |
%\makeatletter |
| 118 |
%\def\verbatim@font{% |
| 119 |
% \normalsize\ttfamily} |
| 120 |
%\makeatother |
| 121 |
|
| 122 |
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 123 |
\providecommand\tubcommand[1]{} |
| 124 |
\tubcommand{\input{tubltmac}} |
| 125 |
|
| 126 |
% \publicationday{01} % change this if it's not released on 1st of a month |
| 127 |
\publicationmonth{June} |
| 128 |
%\publicationyear{2023 --- DRAFT version for upcoming release} |
| 129 |
\publicationyear{2023} |
| 130 |
|
| 131 |
\publicationissue{37} |
| 132 |
|
| 133 |
\begin{document} |
| 134 |
|
| 135 |
\tubcommand{\addtolength\textheight{4.1pc}} % only for TUB |
| 136 |
|
| 137 |
\maketitle |
| 138 |
{\hyphenpenalty=10000 \exhyphenpenalty=10000 \spaceskip=3.33pt \hbadness=10000 |
| 139 |
\tableofcontents} |
| 140 |
|
| 141 |
\setlength\rightskip{0pt plus 3em} |
| 142 |
|
| 143 |
% for ltnews37, squeeze to five pages. |
| 144 |
\tubcommand{\fontsize{9.6}{12}\selectfont} |
| 145 |
|
| 146 |
|
| 147 |
\medskip |
| 148 |
|
| 149 |
|
| 150 |
%\section{Introduction} |
| 151 |
|
| 152 |
|
| 153 |
\section{New functionality offered as part of the |
| 154 |
\enquote{\LaTeX{} Tagged PDF} project} |
| 155 |
|
| 156 |
We have now enabled new automatic tagging functionality for additional |
| 157 |
\LaTeX{} elements, among them most display environments, standard |
| 158 |
sectioning commands, content, figure and table listings, floats and graphics and |
| 159 |
bibliographies. This can |
| 160 |
be activated through |
| 161 |
\begin{verbatim} |
| 162 |
\DocumentMetadata{testphase=phase-III} |
| 163 |
\end{verbatim} |
| 164 |
At this point in time tagging support is only available for a |
| 165 |
restricted set of documents, i.e., those that use one of the basic |
| 166 |
document classes (\texttt{article}, \texttt{report}, and |
| 167 |
\texttt{book}) and only use commands and environments described in |
| 168 |
Lamport's \LaTeX{} manual. |
| 169 |
|
| 170 |
Using other document classes or adding additional packages in the |
| 171 |
preamble may work (or may partially work) but at this stage it is not |
| 172 |
very likely, at least not for packages or classes that excessively |
| 173 |
alter internals of \LaTeX{}. |
| 174 |
|
| 175 |
Also note that there are still several environments and commands |
| 176 |
described in the \LaTeX{} manual that do not have tagging support yet, |
| 177 |
notably tabulars, \texttt{tabbing}, the various math environment and a |
| 178 |
few others. They will get this support as part of \texttt{phase-III}, |
| 179 |
but some of them will be delayed until after the June release. |
| 180 |
|
| 181 |
A prototype for math tagging (including support for the \pkg{amsmath} |
| 182 |
environments) is already available, but it is mainly intended for |
| 183 |
experimentation and feedback and the resulting tagging is by no means |
| 184 |
the way we envision it to be eventually. If you would like to try it out use |
| 185 |
the following line: |
| 186 |
\begin{verbatim} |
| 187 |
\DocumentMetadata{testphase={phase-III,math}} |
| 188 |
\end{verbatim} |
| 189 |
Note that the math tagging code at this point in time will clash with |
| 190 |
packages that redefine the \texttt{\$} character (which then may lead to strange |
| 191 |
errors) and that packages that use math mode for non-mathematical |
| 192 |
constructs may result in surprising output as far as tagging is |
| 193 |
concerned. Feedback on which packages fail with the code in one or |
| 194 |
another way would be appreciated. |
| 195 |
|
| 196 |
The \texttt{latex-lab} bundle contains various |
| 197 |
(still untagged) documentation files about the new code that can |
| 198 |
be accessed with \verb|texdoc -l latex-lab|. |
| 199 |
|
| 200 |
Feedback is welcome! |
| 201 |
Please use \url{https://github.com/latex3/latex2e/discussions/1010}. |
| 202 |
|
| 203 |
|
| 204 |
|
| 205 |
\section{New or improved commands} |
| 206 |
|
| 207 |
\subsection{Extending hooks to take arguments} |
| 208 |
|
| 209 |
Hooks have always been containers for code whose outcome was entirely |
| 210 |
dependent on the contents of the hook alone. If any type of contextual |
| 211 |
information had to be passed to the hook, it had to be done by setting |
| 212 |
some variable before the hook so that the code in the hook could use |
| 213 |
that. But this is somewhat hard to keep track of, clumsy to implement, |
| 214 |
and it required the programmer to have some kind of \enquote{hook before |
| 215 |
the hook} to do that setup. |
| 216 |
|
| 217 |
To make things a bit easier, \pkg{lthooks} was enhanced to support hooks |
| 218 |
with arguments. Hooks can now be declared and used with arguments, then |
| 219 |
the code added to these hooks can reference the hook's arguments using |
| 220 |
\verb|#1|, \verb|#2|, etc., so now hooks can behave more like macros |
| 221 |
than like \emph{token lists} (using \pkg{expl3} terminology). Regular |
| 222 |
argument-less hooks continue to work exactly like they did before: this |
| 223 |
extension is completely compatible with older documents and packages. |
| 224 |
|
| 225 |
\AddToHook{cmd/verbatim@font/after}[hack]{\small} |
| 226 |
To declare a hook with arguments, use |
| 227 |
\begin{verbatim} |
| 228 |
\NewHookWithArguments {<hook>} {<num-args>} |
| 229 |
\end{verbatim} |
| 230 |
then, similarly, to use the code in the hook, supposing a hook declared |
| 231 |
with 2 arguments, write |
| 232 |
\begin{verbatim} |
| 233 |
\UseHookWithArguments {<hook>} {2} {<arg1>} {<arg2>} |
| 234 |
\end{verbatim} |
| 235 |
|
| 236 |
Or, if you want to add some code to a hook that takes arguments, write |
| 237 |
\begin{verbatim} |
| 238 |
\AddToHookWithArguments {<hook>} [<label>] {<code>} |
| 239 |
\end{verbatim} |
| 240 |
exactly like you would for regular hooks, except that the \meta{code} |
| 241 |
can use the arguments by referencing \verb|#1|, \verb|#2|, etc. In this |
| 242 |
case, if you want to add an actual parameter token (\verb|#|) to the |
| 243 |
\meta{code}, you have to double it, as usual. |
| 244 |
\RemoveFromHook{cmd/verbatim@font/after}[hack] |
| 245 |
|
| 246 |
Additionally, if you want to add \enquote{regular} code to a hook with |
| 247 |
arguments, you can still use \cs{AddToHook} --- in that case \verb|#| |
| 248 |
tokens are \emph{not} doubled. This means that a package author can |
| 249 |
decide to add arguments to an existing hook without worrying about |
| 250 |
compatibility: \cs{AddToHook} will do the right thing and will not |
| 251 |
mistakenly reference the newly added arguments. |
| 252 |
|
| 253 |
The commands \cs{NewReversedHookWithArguments}, \cs |
| 254 |
{NewMirroredHookPairWithArguments}, \cs |
| 255 |
{AddToHookNextWithArguments}, \cs{UseOneTimeHookWithArguments}, and |
| 256 |
the \pkg{expl3} counterparts of the commands discussed in this section |
| 257 |
were also added. The complete documentation can be found in the |
| 258 |
\pkg{lthooks} documentation \cite{37:lthooks-doc}. |
| 259 |
|
| 260 |
\subsubsection{Generic \texttt{cmd} hooks with arguments} |
| 261 |
|
| 262 |
Along with the possibility of passing arguments to a regular hook as |
| 263 |
discussed above, generic \hook{cmd} hooks can now access the arguments |
| 264 |
of the command they are patched into, using the interface described in |
| 265 |
the previous section. |
| 266 |
|
| 267 |
For example, if you were to add some code to the \cs{title} command |
| 268 |
using hooks, you could access the actual title given in the argument. |
| 269 |
Thus, to write the title of the document in the terminal you |
| 270 |
could use: |
| 271 |
\begin{verbatim} |
| 272 |
\AddToHookWithArguments{cmd/title/before} |
| 273 |
{\typeout{Document title: #1}} |
| 274 |
\end{verbatim} |
| 275 |
|
| 276 |
As with regular hooks, code added to a \hook{cmd} hook using |
| 277 |
\cs{AddToHook} will not be able to access the command's arguments. This |
| 278 |
means that, as with regular hooks, this change is completely backwards |
| 279 |
compatible, so previous usages of \hook{cmd} hooks will work exactly as |
| 280 |
they did before. |
| 281 |
|
| 282 |
\subsection{Providing copy and show functions for environments} |
| 283 |
|
| 284 |
To copy a command definition we introduced \cs{NewCommandCopy} in |
| 285 |
2022. This even allows you to copy commands that consist of several internal |
| 286 |
components, such as robust commands or those with a complex signature. |
| 287 |
To do the same with environments, e.g., to define the environment |
| 288 |
\env{myitemize} to be equivalent to \env{itemize}, you can now write |
| 289 |
\begin{verbatim} |
| 290 |
\NewEnvironmentCopy{myitemize}{itemize} |
| 291 |
\end{verbatim} |
| 292 |
There are also \cs{Renew...}\ and \cs{Declare...}, which may be useful |
| 293 |
depending on the circumstances. |
| 294 |
|
| 295 |
In addition, we offer a \cs{ShowEnvironment} command, which displays the |
| 296 |
\cs{begin} and \cs{end} code of the environment passed as an |
| 297 |
argument. E.g., \verb=\ShowEnvironment{center}= results in the |
| 298 |
following output: |
| 299 |
\begin{verbatim} |
| 300 |
>> \begin{center}=environment: |
| 301 |
>> ->>\trivlist \centering \item \relax . |
| 302 |
<<recently read>> } |
| 303 |
l. ...\ShowEnvironment{center} |
| 304 |
>> \end{center}: |
| 305 |
>> ->>\endtrivlist . |
| 306 |
<<recently read>> } |
| 307 |
l. ...\ShowEnvironment{center} |
| 308 |
\end{verbatim} |
| 309 |
% |
| 310 |
\githubissue{963} |
| 311 |
|
| 312 |
\subsection{\cs{IfFileAtLeastTF}} |
| 313 |
|
| 314 |
The 2020-10-01 \LaTeX{} release introduced the CamelCase tests |
| 315 |
\cs{IfClassAtLeastTF} and \cs{IfPackageAtLeastTF} for checking class |
| 316 |
and package dates. We have now added \cs{IfFileAtLeastTF} to allow the |
| 317 |
same to happen for generic files which contain a \cs{ProvidesFile} |
| 318 |
line. |
| 319 |
% |
| 320 |
\githubissue{1015} |
| 321 |
|
| 322 |
\subsection{\cs{DeclareLowercaseMapping}, \cs{DeclareTitlecaseMapping} |
| 323 |
and \cs{DeclareUppercaseMapping}\texorpdfstring{\raggedright}{}} |
| 324 |
|
| 325 |
The move from a case-changing approach using \cs{lccode} and \cs{uccode} data |
| 326 |
to one where information is stored by a kernel-managed structure left a gap in |
| 327 |
the ability of the user to \emph{tune} the case changing outcomes. This has now |
| 328 |
been addressed by the addition of three commands |
| 329 |
\begin{itemize}\tubcommand{\setlength{\parskip}{0pt}}% |
| 330 |
\item \cs{DeclareLowercaseMapping} |
| 331 |
\item \cs{DeclareTitlecaseMapping} |
| 332 |
\item \cs{DeclareUppercaseMapping} |
| 333 |
\end{itemize} |
| 334 |
which can be used to customise the outcome for codepoints. This can be applied |
| 335 |
generally or to a specific locale (see also the next section). A small number |
| 336 |
of pre-defined customisations have been set up in the kernel where the outcomes |
| 337 |
for \pdfTeX{} should be different for those from Unicode engines. For |
| 338 |
example |
| 339 |
\begin{verbatim} |
| 340 |
\DeclareUppercaseMapping{"01F0}{\v{J}} |
| 341 |
\end{verbatim} |
| 342 |
allows \v{J} to be produced in 8-bit engines: without this customisation, |
| 343 |
an error would occur as there is no pre-composed \v{J} in Unicode. More detail |
| 344 |
is given in \texttt{usrguide}. |
| 345 |
% |
| 346 |
\githubissue{1033} |
| 347 |
|
| 348 |
\subsection{\cs{BCPdata}} |
| 349 |
|
| 350 |
Improvements in the Unicode handling for case changing have highlighted that |
| 351 |
the kernel has not to-date been locale-aware. The packages \pkg{babel} and |
| 352 |
\pkg{polyglossia} provide comprehensive locale support, but did not have |
| 353 |
an agreed unified interface to pass that information back to other code. |
| 354 |
Following discussion with the maintainers of those two bundles, the kernel |
| 355 |
now defines \cs{BCPdata} as a stub (so it is always defined), and \pkg{babel} |
| 356 |
and \pkg{polyglossia} will redefine it to provide the locale data. An agreed |
| 357 |
set of keywords mean that \cs{BCPdata} can be queried in a structured way |
| 358 |
by both the kernel and any other \enquote{consumer} packages. |
| 359 |
% |
| 360 |
\githubissue{1035} |
| 361 |
|
| 362 |
\subsection{Improve \cs{samepage}} |
| 363 |
|
| 364 |
The \cs{samepage} declaration sets various parameters to |
| 365 |
\texttt{10000} to prevent undesired page breaks. The |
| 366 |
\cs{predisplaypenalty} parameter has already by default a value of |
| 367 |
\texttt{10000}, and to save space in the past it was therefore not |
| 368 |
explicitly set. However, there are a few classes that change the |
| 369 |
parameter and as result the user might experience a page break in |
| 370 |
front of a display formula within the scope of \cs{samepage} when |
| 371 |
using such classes. This has now been corrected and |
| 372 |
\cs{predisplaypenalty} is also explicitly set to \texttt{10000}. |
| 373 |
% |
| 374 |
\githubissue{1022} |
| 375 |
|
| 376 |
\subsection{Groups in \cs{MakeUppercase}} |
| 377 |
% |
| 378 |
Prior to 2022, \cs{MakeUppercase} and \cs{MakeLowercase} used a brace |
| 379 |
group around their argument so providing a scope for any declarations |
| 380 |
within the argument. This grouping has been restored (also |
| 381 |
for \cs{MakeTitlecase}), although the underlying L3 text case commands do |
| 382 |
not use grouping. |
| 383 |
% |
| 384 |
\githubissue{1021} |
| 385 |
|
| 386 |
\subsection{Extension of the \cs{label} command} |
| 387 |
|
| 388 |
Previously, in standard \LaTeX{}, the \cs{label} command wrote a \cs{newlabel} declaration into |
| 389 |
the \texttt{.aux} file and stored two values in |
| 390 |
the second argument of this \cs{newlabel} command: |
| 391 |
\cs{@currentlabel}, which normally contains the state of the current |
| 392 |
counter and \cs{thepage} for the current page number. |
| 393 |
|
| 394 |
The packages \pkg{hyperref} and |
| 395 |
\pkg{nameref} then patched the \cs{label} command to store five values instead. |
| 396 |
In addition to the above they saved \cs{@currentlabelname}, which normally contains the |
| 397 |
current title text and can be retrieved with \cs{nameref}, and |
| 398 |
\cs{@currentHref}, which is the name of the destination needed to create an |
| 399 |
active link. The fifth argument was only used if external |
| 400 |
references were loaded with the \pkg{xr-hyper} package. |
| 401 |
|
| 402 |
Starting with this release, the number of values stored in \cs{newlabel} has been unified. |
| 403 |
\cs{label} now writes a |
| 404 |
\cs{newlabel} command that always contains five values in the second argument (each in a brace group): |
| 405 |
\cs{@currentlabel}, \cs{thepage}, \cs{@currentlabelname}, |
| 406 |
\cs{@currentHref}, and \cs{@kernel@reserved@label@data} (which is reserved for the kernel). |
| 407 |
|
| 408 |
Additionally, a hook with the name \texttt{label} has been |
| 409 |
added. It takes one argument: the label string. |
| 410 |
Code added to the hook can refer to this argument with~\verb+#1+. |
| 411 |
The hook is executed directly before the \cs{label} command writes to the \texttt{.aux} file |
| 412 |
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. |
| 413 |
|
| 414 |
\section{Code improvements} |
| 415 |
|
| 416 |
\subsection{Performance in checking file existence} |
| 417 |
|
| 418 |
The addition of hooks, etc., to file operations had a side effect of making |
| 419 |
multiple checks that the file existed. In larger documents using |
| 420 |
many files, these file system operations caused non-trivial performance |
| 421 |
impact. We now cache the existence of files, such that these repeated filesystem |
| 422 |
calls are avoided. |
| 423 |
|
| 424 |
\subsection{\pkg{doc}: Handle \texttt{\textbackslash\textvisiblespace} correctly in the index} |
| 425 |
|
| 426 |
Due to some problems in the code it wasn't possible to prevent |
| 427 |
\verb*=\ = from showing up in the index\Dash \verb=\DoNotIndex{\ }=, etc.\ had no effect. This has now been corrected. |
| 428 |
% |
| 429 |
\githubissue{943} |
| 430 |
|
| 431 |
|
| 432 |
\subsection{\pkg{doc}: Support the \pkg{upquote} package} |
| 433 |
|
| 434 |
The default quote and backquote characters in typewriter fonts are |
| 435 |
typographical quotes, e.g., the input |
| 436 |
\begin{verbatim} |
| 437 |
\verb/`prog 'my input'`/ |
| 438 |
\end{verbatim} |
| 439 |
is rendered as \verb/`prog 'my input'`/ and not as |
| 440 |
% |
| 441 |
\begingroup % code to mimic upquote.sty |
| 442 |
\catcode`'=\active |
| 443 |
\catcode``=\active |
| 444 |
\makeatletter |
| 445 |
\g@addto@macro\@noligs |
| 446 |
{\let'\textquotesingle |
| 447 |
\let`\textasciigrave |
| 448 |
\ifx\encodingdefault\upquote@OTone |
| 449 |
\ifx\ttdefault\upquote@cmtt |
| 450 |
\def'{\char13 }% |
| 451 |
\def`{\char18 }% |
| 452 |
\fi\fi} |
| 453 |
\endgroup |
| 454 |
% |
| 455 |
\verb/`prog 'my input'`/ as preferred by many programmers. |
| 456 |
|
| 457 |
This can be adjusted, for example, with the \pkg{upquote} package, |
| 458 |
which results in the second output. However, for historical reasons |
| 459 |
\pkg{doc} had its own definition of \cs{verb} and \env{verbatim} and |
| 460 |
as a consequence the two packages did not cooperate. This has now |
| 461 |
been fixed and loading \pkg{upquote} together with \pkg{doc} has the |
| 462 |
desired effect. |
| 463 |
% |
| 464 |
\githubissue{953} |
| 465 |
|
| 466 |
|
| 467 |
\subsection{Default definition for \cs{do}} |
| 468 |
|
| 469 |
The command \cs{do} with its nice public name is in reality an |
| 470 |
internal command inherited from plain \TeX{} for list |
| 471 |
processing. However, it only got a definition when |
| 472 |
\verb=\begin{document}= was executed, with a result that a user |
| 473 |
definition in the preamble was unconditionally overwritten at this |
| 474 |
point. To properly alert the user that this command is not freely |
| 475 |
available we now make a definition in the format, so that |
| 476 |
\cs{newcommand} and friends produce a proper error message instead of |
| 477 |
allowing a definition that doesn't last. |
| 478 |
% |
| 479 |
\githubissue{975} |
| 480 |
|
| 481 |
|
| 482 |
|
| 483 |
|
| 484 |
\subsection{New key for \env{filecontents}} |
| 485 |
|
| 486 |
The \env{filecontents} environment warns on the terminal if a file |
| 487 |
gets overwritten even if that is intentional, |
| 488 |
e.g., when you write a temporary file over and over again. To make |
| 489 |
the warning less noisy in this case we added a new \texttt{nowarn} key |
| 490 |
that redirects the overwriting warning to the transcript file. We |
| 491 |
think that some record of the action is still required to help with |
| 492 |
debugging, thus it is not completely silenced. The warning that |
| 493 |
nothing gets written, because the file already exists (and the |
| 494 |
\texttt{force} key was not used), is not altered and still shows up on |
| 495 |
the terminal. |
| 496 |
% |
| 497 |
\githubissue{958} |
| 498 |
|
| 499 |
|
| 500 |
\subsection{A further hook for shipping out pages} |
| 501 |
|
| 502 |
Since October 2020 the shipout process offers a number of hooks to |
| 503 |
adjust what is happening before, during, and after the |
| 504 |
\cs{shipout}. For example, with the \hook{shipout/before} hook, packages |
| 505 |
can reset code they have altered (e.g., \cs{catcode}s during |
| 506 |
verbatim-like processing) and with \hook{shipout/background} and |
| 507 |
\hook{shipout/foreground} material can be added to the pages. |
| 508 |
Details are given in \cite{37:ltshipout-doc}. |
| 509 |
|
| 510 |
However, still |
| 511 |
missing was a hook that allows a package writer to manipulate the |
| 512 |
completed page (with foreground and background attached) just before |
| 513 |
the actual shipout happens. |
| 514 |
For this we now provide the additional hook \hook{shipout}. One |
| 515 |
use case (sometimes needed in print production) is to mirror the |
| 516 |
whole page via \cs{reflectbox} including all the extra data that may |
| 517 |
have been added into the fore- or background. |
| 518 |
% |
| 519 |
\githubissue{920} |
| 520 |
|
| 521 |
|
| 522 |
|
| 523 |
\subsection{Displaying release information in the \texttt{.log}} |
| 524 |
|
| 525 |
\LaTeX{} displays its release information at the very beginning of the |
| 526 |
\LaTeX{} run on the terminal, and also writes it to the transcript file |
| 527 |
if that is already opened at this point. While this is normally true, |
| 528 |
it is not the case if the \LaTeX{} run was started passing additional |
| 529 |
\TeX{} code on the command line, e.g., |
| 530 |
\begin{verbatim} |
| 531 |
pdflatex '\PassOptionsToClass{11pt}{article} |
| 532 |
\input{myarticle}' |
| 533 |
\end{verbatim} |
| 534 |
In this case the release information is displayed when |
| 535 |
\cs{PassOptionsToClass} is processed but the transcript file is only |
| 536 |
opened when the output file name is known, i.e., after \cs{input} has |
| 537 |
been seen, and as a result the release information is only shown on |
| 538 |
the terminal. |
| 539 |
|
| 540 |
To account for this scenario, we now repeat the release information |
| 541 |
also at the very end of the transcript file where we can be sure that |
| 542 |
it is open and ready to receive material. |
| 543 |
% |
| 544 |
\githubissue{944} |
| 545 |
|
| 546 |
|
| 547 |
|
| 548 |
|
| 549 |
|
| 550 |
\section{Bug fixes} |
| 551 |
|
| 552 |
\subsection{Incompatibility between \pkg{doc} and \pkg{unicode-math}} |
| 553 |
|
| 554 |
The \pkg{unicode-math} package alters the catcode of \verb=|= but does |
| 555 |
not adjust its value for use in \pkg{doc}, with the result that |
| 556 |
\enquote{or} modules, i.e., $\langle A | B \rangle$ are displayed in a |
| 557 |
strange way. This is now fixed with some firstaid code that will |
| 558 |
eventually be moved into \pkg{unicode-math}. |
| 559 |
% |
| 560 |
\githubissue{820} |
| 561 |
|
| 562 |
|
| 563 |
\subsection{A fix for \cs{hspace}} |
| 564 |
|
| 565 |
The change to \cs{hspace}, done in 2020 to make it \pkg{calc}-aware, |
| 566 |
had the unfortunate side effect that starting a paragraph with |
| 567 |
\cs{hspace} would result in the execution of \cs{everypar} inside a |
| 568 |
group (i.e., any local changes would immediately be revoked, breaking, |
| 569 |
for example, \pkg{wrapfig} in that special situation). |
| 570 |
% |
| 571 |
This got fixed with the 2022-11 PL1 hotfix, so was already corrected in |
| 572 |
the previous release, but is only now documented in the newsletter. |
| 573 |
% |
| 574 |
\githubissue{967} |
| 575 |
|
| 576 |
\subsection{Ensure that \cs{cs} is defined in \cls{ltxdoc}} |
| 577 |
|
| 578 |
The class \cls{ltxdoc} defined the command \cs{cs} to typeset a |
| 579 |
command name with a backslash in front. This definition was moved to |
| 580 |
the \pkg{doc} package itself. This meant that it was suddenly missing |
| 581 |
when reverting to the old \pkg{doc} package implementation via the |
| 582 |
class option \texttt{doc2}. This has now been corrected. |
| 583 |
% |
| 584 |
\githubissue{981} |
| 585 |
|
| 586 |
|
| 587 |
|
| 588 |
\subsection{Improve spacing at top of \env{minipage}s} |
| 589 |
|
| 590 |
A list and several other document elements add some vertical space in |
| 591 |
front of them. However this should not happen at the beginning of a |
| 592 |
box (such as a \env{minipage}) and normally it doesn't, because |
| 593 |
\TeX{} automatically drops such space at the start of a vertical |
| 594 |
list. However, if there is some invisible material, such as a |
| 595 |
\cs{color} command, a \pkg{hyperref} anchor, a \cs{write} or |
| 596 |
other such items, then the list is no longer empty and \TeX{} no longer |
| 597 |
drops the vertical space. |
| 598 |
|
| 599 |
With the new paragraph handling introduced in 2021 it is now finally |
| 600 |
possible to detect and avoid this problem and apply appropriate |
| 601 |
counter measures so that from now on the spacing will always be |
| 602 |
correct. |
| 603 |
% |
| 604 |
\githubissue{989} |
| 605 |
|
| 606 |
|
| 607 |
\subsection{A fix for \cs{NewCommandCopy} and \cs{ShowCommand}} |
| 608 |
|
| 609 |
When copying and showing definitions of (non-expandable) document commands |
| 610 |
(a.k.a.\ commands defined by \cs{NewDocumentCommand} and friends) containing empty |
| 611 |
or only \texttt{m}-type arguments, these commands were wrongly recognized as |
| 612 |
expandable ones. |
| 613 |
This is fixed in the present \LaTeX{} release. |
| 614 |
% |
| 615 |
\githubissue{1009} |
| 616 |
|
| 617 |
\subsection{Corrections for switching math version} |
| 618 |
Some internal code improvements improve support for switching math version |
| 619 |
when nested within an outer math expression. |
| 620 |
This will improve \cs{boldsymbol} and \cs{bm} and similar commands. |
| 621 |
% |
| 622 |
\githubissue{1028} |
| 623 |
|
| 624 |
\subsection{Allow par as a filename} |
| 625 |
\verb|\input{par}| or \verb|\includegraphics{par}| could give spurious |
| 626 |
errors. This has been fixed by making an internal command \cs{long}. |
| 627 |
% |
| 628 |
\githubissue{942} |
| 629 |
|
| 630 |
\subsection{Correct setting of \cs{endlinechar} in \texttt{+v} arguments} |
| 631 |
In the particular case of a document command with a \texttt{+v}-type |
| 632 |
argument used inside \cs{ExplSyntaxOn}\texttt{/Off}, newlines would be |
| 633 |
misinterpreted as spaces because the value of \cs{endlinechar} was |
| 634 |
set too late. This has been fixed, and now newlines are correctly |
| 635 |
translated to ``\verb|the character ^^M|''. |
| 636 |
% |
| 637 |
\githubissue{876} |
| 638 |
|
| 639 |
\subsection{Correct handling of hooks with only `next' code} |
| 640 |
When \cs{AddToHookNext} was used on a not-yet-declared hook, that hook |
| 641 |
would be incorrectly identified as empty by \cs{ShowHook}. Also, if |
| 642 |
that hook was later declared, that `next' code would not be executed. |
| 643 |
This has been fixed by correctly initializing the hook structure when |
| 644 |
\cs{AddToHookNext} is used. |
| 645 |
% |
| 646 |
\githubissue{1052} |
| 647 |
|
| 648 |
\subsection{Ignoring space after \texttt{\$\$}} |
| 649 |
Space is normally ignored after a closing \texttt{\$\$}, |
| 650 |
but internal \LaTeX{} font handling code could interfere if |
| 651 |
\cs{eqno} was used. \cs{eqno} and \cs{leqno} have been redefined |
| 652 |
to add \cs{ignorespaces} after the math group. |
| 653 |
% |
| 654 |
\githubissue{1059} |
| 655 |
|
| 656 |
\section{Documentation improvements} |
| 657 |
|
| 658 |
\subsection{Updates to the guides} |
| 659 |
|
| 660 |
When \LaTeXe{} was released, the team provided documentation for both document |
| 661 |
authors and package/class developers in the two files \texttt{usrguide} and |
| 662 |
\texttt{clsguide}. Over time, the team have augmented these documents as new |
| 663 |
methods have been added to the kernel. However, they retained their structure |
| 664 |
as assuming familiarity with \LaTeX{}~2.09. This meant that for new users, |
| 665 |
there was material which is no longer relevant, and less clarity than desirable |
| 666 |
regarding the approaches that are recommended today. |
| 667 |
|
| 668 |
The two files have now been (partially) re-written, with the versions available |
| 669 |
previously now frozen as \texttt{usrguide-historic} and \texttt{clsguide-historic}. |
| 670 |
More material has been carried forward in the class/package guide than in the |
| 671 |
user guide, but both are worth a re-read by experienced \LaTeX{} users. |
| 672 |
|
| 673 |
|
| 674 |
|
| 675 |
\subsection{Displaying the exact release dates for \LaTeX{}} |
| 676 |
|
| 677 |
In some situations it is necessary to find out the exact release dates |
| 678 |
for older versions of the \LaTeX{} format, for example, when you need |
| 679 |
to use different code in a package depending on the availability of a |
| 680 |
certain feature and you therefore want to use |
| 681 |
\cs{IfFormatAtLeastTF}\texttt\{\meta{date}\texttt\} or the |
| 682 |
rather horrible construction \verb/\@ifl@t@r\fmtversion{/\meta{date}\texttt\}, |
| 683 |
if you |
| 684 |
want to cater for formats that are older than 2020. |
| 685 |
|
| 686 |
Or you know that your package is definitely not going to work with a |
| 687 |
format before a certain \meta{date}, in which case you could use |
| 688 |
\verb/\NeedsTeXFormat{LaTeX2e}[/\meta{date}\texttt] to ensure that |
| 689 |
users are alerted if their format is too old. |
| 690 |
|
| 691 |
The big problem is knowing the exact \meta{date} to put into such |
| 692 |
commands; in the past, that was not that easy to find. You could have |
| 693 |
looked in the file \file{changes.txt}, but that is hidden somewhere |
| 694 |
in your installation and if you try |
| 695 |
\verb/texdoc -l changes.txt/ you get more than thirty results and the %* |
| 696 |
right file is by no means the first. |
| 697 |
|
| 698 |
Yukai Chou (\textsf{@muzimuzhi}) kindly provided a patch for this, so that we now have |
| 699 |
the exact dates for each \LaTeX{} format listed in an easy to remember |
| 700 |
place: in \file{ltnews.pdf} and that file conveniently also contains all major |
| 701 |
features and changes to \LaTeX{} over the years\Dash one of which is |
| 702 |
most likely the reason you need the \meta{date} in the first |
| 703 |
place. |
| 704 |
|
| 705 |
The date is now given in parentheses in the newsletter title, thus this |
| 706 |
newsletter tells you that on |
| 707 |
% |
| 708 |
\makeatletter |
| 709 |
\mbox{\expandafter\@gobblenonyear\@year\@nil |
| 710 |
-\@julianmonthtonum\@month-\two@digits\@day} |
| 711 |
\makeatother |
| 712 |
% |
| 713 |
the command |
| 714 |
\cs{NewEnvironmentCopy}, a new \texttt{shipout} hook, etc.\ was made |
| 715 |
available. And looking into \file{ltnews.pdf} you can now easily find |
| 716 |
out that the \LaTeX3 programming layer was added on 2020-02-02 |
| 717 |
(because the date was so nice) and not on the first of the month. |
| 718 |
% |
| 719 |
\githubissue{982} |
| 720 |
|
| 721 |
\subsection{Fresh from the press:\ \enquote{The \LaTeX{} Companion, third~edition} is now in print} |
| 722 |
|
| 723 |
The third edition of \emph{The \LaTeX{} Companion} is now |
| 724 |
available. This is the result of five years of careful work and we hope |
| 725 |
that it will provide our readers with all the information they need to |
| 726 |
successfully navigate the \LaTeX{} ecosystem and efficiently produce |
| 727 |
beautiful documents. |
| 728 |
|
| 729 |
Since the publication of the last edition (2004), a lot has happened in |
| 730 |
the \LaTeX{} world and thus a complete rewrite was necessary. All |
| 731 |
chapters have been thoroughly revised, and in many cases significantly |
| 732 |
extended, to describe new important functionality and features. More |
| 733 |
than 5,000 add-on packages have been analyzed in detail, out of which |
| 734 |
roughly 10\% have been chosen for inclusion in \emph{The \LaTeX{} |
| 735 |
Companion}. All important aspects of these packages are described to |
| 736 |
provide the user once again with a satisfying one-stop–shop experience |
| 737 |
for the decade to come. |
| 738 |
|
| 739 |
To cover what we thought worth describing today, the book nearly |
| 740 |
doubled in size. The print edition is therefore produced as a |
| 741 |
two-volume set and sold as a bundle. Both volumes come as hardcover |
| 742 |
with ribbons to easily mark pages in the book. |
| 743 |
|
| 744 |
To give you an idea of what is covered in the third edition you can |
| 745 |
find some excerpts at |
| 746 |
\begin{quote} |
| 747 |
\url{https://www.latex-project.org/news/2023/03/17/TLC3} |
| 748 |
\end{quote} |
| 749 |
|
| 750 |
The edition is also available as an eBook (Parts~I and~II combined) |
| 751 |
consisting of PDF and ePub format, without DRM\@. Finally, the publisher |
| 752 |
offers the combination of the printed books and the digital versions at |
| 753 |
a very attractive price not available anywhere else. |
| 754 |
|
| 755 |
%% bb -- add reference to TUGboat review here |
| 756 |
|
| 757 |
|
| 758 |
%\section{Changes to packages in the \pkg{amsmath} category} |
| 759 |
|
| 760 |
%\section{Changes to packages in the \pkg{graphics} category} |
| 761 |
|
| 762 |
\section{Changes to packages in the \pkg{tools} category} |
| 763 |
|
| 764 |
|
| 765 |
\subsection{\pkg{multicol}: Better support for CJK languages} |
| 766 |
|
| 767 |
The default minimum depth of each column in a \env{multicols} |
| 768 |
corresponds to the depth of a \enquote{p} in the current font. This |
| 769 |
helps to get some uniformity if rules are used between the columns and |
| 770 |
makes sense for Latin-based languages. Until now it was hard-wired, |
| 771 |
but for CJK (Chinese/Japanese/Korean) languages it is better to use a zero depth, because there |
| 772 |
all characters have the same height and depth. And even with |
| 773 |
Latin-based languages one might want to use the depth of a \cs{strut} |
| 774 |
or that of a parenthesis. So we now offer a way to adjust this while |
| 775 |
maintaining backward compatibility: redefine |
| 776 |
\cs{multicolmindepthstring} to hold whatever you want to get measured |
| 777 |
for its depth (the width is not relevant). |
| 778 |
% |
| 779 |
\githubissue{698} |
| 780 |
|
| 781 |
|
| 782 |
\subsection{\pkg{multicol}: Fix handling of nested environments} |
| 783 |
|
| 784 |
If \env{multicols} environments have been nested into each other (the |
| 785 |
inner one boxed) it could fail if the boxed environment appeared near a |
| 786 |
page break. The problem was that the output routine was called while |
| 787 |
the \cs{hsize} was still altered to fit the column width of the inner |
| 788 |
\env{multicols} --- thereby messing up the placement of columns of the |
| 789 |
page. This has now been fixed. |
| 790 |
% |
| 791 |
\githubissue{1002} |
| 792 |
|
| 793 |
|
| 794 |
|
| 795 |
%\medskip |
| 796 |
|
| 797 |
\begin{thebibliography}{9} |
| 798 |
|
| 799 |
%\fontsize{9.3}{11.3}\selectfont |
| 800 |
|
| 801 |
\bibitem{37:ltshipout-doc} Frank Mittelbach, \LaTeX{}~Project~Team: |
| 802 |
\emph{The~\texttt{\upshape ltshipout} documentation}.\\ |
| 803 |
Run \texttt{texdoc} \texttt{ltshipout-doc} to view. |
| 804 |
|
| 805 |
\bibitem{37:lthooks-doc} Frank Mittelbach, Phelype Oleinik, \LaTeX{}~Project~Team: |
| 806 |
\emph{\LaTeX's hook management}.\\ |
| 807 |
Run \texttt{texdoc} \texttt{lthooks-doc} to view. |
| 808 |
|
| 809 |
%\bibitem{37:blueprint} Frank Mittelbach and Chris Rowley: |
| 810 |
% \emph{\LaTeX{} Tagged PDF \Dash A blueprint for a large project}.\\ |
| 811 |
% \url{https://latex-project.org/publications/indexbyyear/2020/} |
| 812 |
|
| 813 |
%\bibitem{37:source2e} |
| 814 |
% \emph{\LaTeX{} documentation on the \LaTeX{} Project Website}.\\ |
| 815 |
% \url{https://latex-project.org/help/documentation/} |
| 816 |
|
| 817 |
%\bibitem{37:Lamport} |
| 818 |
%Leslie Lamport. |
| 819 |
%\newblock {\LaTeX}: {A} Document Preparation System: User's Guide and Reference |
| 820 |
% Manual. |
| 821 |
%\newblock \mbox{Addison}-Wesley, Reading, MA, USA, 2nd edition, 1994. |
| 822 |
%\newblock ISBN 0-201-52983-1. |
| 823 |
%\newblock Reprinted with corrections in 1996. |
| 824 |
% |
| 825 |
%\bibitem{37:ltnews32} \LaTeX{} Project Team: |
| 826 |
% \emph{\LaTeXe{} news 32}.\\ |
| 827 |
% \url{https://latex-project.org/news/latex2e-news/ltnews32.pdf} |
| 828 |
% |
| 829 |
%\bibitem{37:ltnews34} \LaTeX{} Project Team: |
| 830 |
% \emph{\LaTeXe{} news 34}.\\ |
| 831 |
% \url{https://latex-project.org/news/latex2e-news/ltnews34.pdf} |
| 832 |
% |
| 833 |
%\bibitem{37:ltnews35} \LaTeX{} Project Team: |
| 834 |
% \emph{\LaTeXe{} news 35}.\\ |
| 835 |
% \url{https://latex-project.org/news/latex2e-news/ltnews35.pdf} |
| 836 |
% |
| 837 |
%\bibitem{37:fntguide} \LaTeX{} Project Team: |
| 838 |
% \emph{\LaTeXe{} font selection}.\\ |
| 839 |
% \url{https://latex-project.org/help/documentation/} |
| 840 |
% |
| 841 |
%\bibitem{37:ltfilehook-doc} Frank Mittelbach, Phelype Oleinik, \LaTeX{}~Project~Team: |
| 842 |
% \emph{The \texttt{\upshape ltfilehook} documentation}.\\ |
| 843 |
% Run \texttt{texdoc} \texttt{ltfilehook-doc} to view. |
| 844 |
\end{thebibliography} |
| 845 |
|
| 846 |
|
| 847 |
|
| 848 |
\end{document} |