Debian Codegraph @

texmf-dist/doc/latex/base/ltnews35.tex

raw
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: ltnews35.tex
30 %
31 % This is issue 35 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 \makeatletter
117 \def\verbatim@font{%
118 \normalsize\ttfamily}
119 \makeatletter
120
121 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
122 \providecommand\tubcommand[1]{}
123 \tubcommand{\input{tubltmac}}
124
125 \publicationmonth{June}
126 \publicationyear{2022}
127
128 \publicationissue{35}
129
130 \begin{document}
131
132 \tubcommand{\addtolength\textheight{4.2pc}} % only for TUB
133
134 \maketitle
135 {\hyphenpenalty=10000 \exhyphenpenalty=10000 \spaceskip=3.33pt \hbadness=10000
136 \tableofcontents}
137
138 \setlength\rightskip{0pt plus 3em}
139
140
141 \medskip
142
143
144 \section{Introduction}
145
146 The 2022 June release of \LaTeX{} is again focussing on improvements
147 made for our multi-year project to automatically offer tagged PDF
148 output~\cite{35:blueprint}. These are the new document metadata
149 interface, the new mark mechanism for \LaTeX{}, a standard key/value
150 approach for options, and the introduction of the \texttt{latex-lab}
151 area for temporary code that can be optionally loaded by a document
152 (when \cs{DocumentMetadata} is used with certain test keys). These
153 additions are described in the first sections. Related to this effort
154 there are updates to \pkg{hyperref} and \pkg{tagpdf}, both of which
155 have their own distributions.
156
157 As usual, we also added a number of smaller improvements and bug
158 fixes in various components of core \LaTeX{}. Perhaps the most
159 interesting ones (for some users) are direct support for floating
160 point arithmetic (via \cs{fpeval}; see below) and the ability to
161 properly color parts of math formulas without introducing spacing
162 problems. For this we now offer the command \cs{mathcolor}; see the
163 description near the end of the newsletter. There is also a new major
164 release of the \pkg{doc} package that supports a more fine-grained
165 classification of code elements and properly supports \pkg{hyperref}.
166
167
168 \section{Document metadata interface}
169
170 Until recently there was no dedicated location to declare
171 settings that affect a document as a whole. Settings had to be placed
172 somewhere in the preamble or as class options or sometimes even as
173 package options. For some such settings this may cause issues, e.g.,
174 setting the PDF version is only possible as long as the PDF output
175 file has not yet been opened which can be caused by loading one or the
176 other package.
177
178 For the \enquote{\LaTeX{} Tagged PDF project}~\cite{35:blueprint}
179 further metadata about the whole document (and its processing) need to
180 be specified and again this data should be all placed in a single
181 well-defined place.
182
183 For this reason we introduce the new command \cs{DocumentMetadata} to
184 unify all such settings in one place. The command expects a key/value
185 list that describes all document metadata for the current document. It
186 is only allowed to be used at the very beginning of the document,
187 i.e., the declaration has to be placed \emph{before}
188 \cs{documentclass} and will issue an error if found later.
189
190
191 At this point in time we provide only the bare command in the format;
192 the actual processing of the key/value is defined externally and the
193 necessary code will be loaded if the command is used. This scheme is
194 chosen for two reasons: by adding the command in the kernel it is
195 available to everybody without the need to load a special package
196 using \cs{RequirePackage}. The actual processing, though, is external
197 so that we can easily extend the code (e.g., offering additional keys
198 or changing the internal processing) while the above-mentioned project
199 is progressing. Both together allows users to immediately benefit from
200 intermediate results produced as part of the project, as well as
201 offering the \LaTeX{} Project Team the flexibility to enable such
202 intermediate results (for test purposes or even production use)
203 in-between and independently of regular \LaTeX{} releases. Over time,
204 tested and approved functionality can then seamlessly move into the
205 kernel at a later stage without any alterations to documents already
206 using it. At the same time, not using the new consolidated interface
207 means that existing documents are in no way affected by the work that
208 is carried out and is in a wider alpha or beta test phase.
209
210 Documentation about the new command and
211 already existing keys are in \file{ltmeta} (part of \file{source2e.pdf}) and \file{documentmetadata-support.pdf}
212 and also in the documentation of the \pkg{pdfmanagement-testphase} package.
213
214 Package and class authors can test if a user has used \cs{DocumentMetadata}
215 with \cs{IfDocumentMetadataTF}.
216
217
218 \section{The \pkg{latex-lab} bundle}
219
220 We added a new \pkg{latex-lab}oratory bundle in which we place new
221 code that is going to be available only through a
222 \cs{DocumentMetadata} declaration and that is\Dash most
223 importantly\Dash work under development and subject to
224 change without further notice. This means that commands and interfaces provided there may
225 get altered or removed again after some public testing. The code can
226 be accessed through the \cs{DocumentMetadata} key \texttt{testphase}.
227 Currently supported values are \texttt{phase-I} and \texttt{phase-II}
228 that enable code of the tagged PDF project (phase~I is frozen, and
229 phase~II is the phase we are currently working on). With
230 \begin{verbatim}
231 \DocumentMetadata{testphase=phase-II}
232 \end{verbatim}
233 you currently enable tagging for paragraphs and footnotes; more
234 document elements will follow soon.
235
236 Eventually, code will move (once considered stable) from the
237 testphase into the \LaTeX{} kernel itself. Tagging will continue to
238 require a \cs{DocumentMetadata} declaration, but you will then be able
239 to drop the \texttt{testphase} key setting.
240
241
242 \section{A new mark mechanism for \LaTeX{}}
243
244 The mark mechanism is \TeX{}'s way to pass information to the
245 page-building process, which happens asynchronously, in order to
246 communicate relevant data for running headers and footers to the
247 latter, e.g., what is the first section on the page or the last
248 subsection, etc. However, marks may also be
249 used for other purposes. The new kernel module provides a generalized
250 mechanism for marks of independent classes.
251
252 The \TeX{} engines offer a low-level mark mechanism to
253 communicate information about the content of the current page to
254 the asynchronous operating output routine. It works by placing
255 \cs{mark} commands into the source document.
256
257 This mechanism works well for simple formats (such as plain \TeX)
258 whose output routines are only called to generate pages. It
259 fails, however, in \LaTeX{} (and other more complex formats),
260 because here the output routine is sometimes called without
261 producing a page, e.g., when encountering a float and placing it
262 into one of the float regions.
263 %
264 When that happens \TeX{}'s \cs{topmark} no
265 longer reflects the situation at the top of the next page when that
266 page is finally boxed.
267
268 Furthermore, \TeX{} only offered a single mark while \LaTeX{} wanted to
269 keep track of more than one piece of information. For that reason,
270 \LaTeX{} implemented its own mark mechanism where the marks always
271 contained two parts with their own interfaces: \cs{markboth} and
272 \cs{markright} to set marks and \cs{leftmark} and \cs{rightmark} to
273 retrieve them.
274
275 Unfortunately, this extended mechanism, while supporting scenarios such
276 as chapter/section marks, was far from general. The mark
277 situation at the top of a page (i.e., \cs{topmark}) remained
278 unusable and the two marks offered were not really independent of
279 each other because \cs{markboth} (as the name indicates) was
280 always setting both.
281
282
283 The new mechanism now available in \LaTeX{} starting with the 2022
284 release overcomes both issues:
285 \begin{itemize}
286 \item
287 It provides arbitrary many, fully independent named marks, that
288 can be allocated and from that point onwards used.
289 \item
290 It offers access for each such mark to retrieve its top,
291 first, and bottom value separately.
292 \item
293 Furthermore, the mechanism is augmented to give access to marks
294 in different ``regions'', which may be other than full pages.
295 \end{itemize}
296 The legacy interfaces, e.g., \cs{markboth}, are kept. Thus classes and
297 packages making use of them continue to work seamlessly. To make use
298 of the extended possibility a new set of commands for the declaration of
299 mark classes, setting their values and querying their state (in the
300 output routine) is now available in addition.
301 %
302 You find the documentation for the new interfaces together with
303 examples and further notes on the mechanism in the file
304 \texttt{ltmarks-doc.pdf}. Just call \texttt{texdoc}
305 \texttt{ltmarks-doc} to display it on your computer.
306
307
308 \section{A key/value approach to option handling}
309
310 The classical \LaTeXe{} method for handling options, using \cs{ProcessOptions},
311 treats each entry in the list as a string. Many package authors have sought to
312 extend this handling by treating each entry as a key--value pair (keyval)
313 instead. To date, this has required the use of additional packages, for example
314 \pkg{kvoptions}.
315
316 The \LaTeX{} team have for some time offered the package \pkg{l3keys2e} to
317 allow keyvals defined using the L3 programming layer module \pkg{l3keys} to act
318 as package options. This ability has now been integrated directly into the
319 kernel. As part of this integration, the syntax for processing keyval options
320 has been refined, such that
321 \begin{verbatim}
322 \ProcessKeyOptions
323 \end{verbatim}
324 will now automatically pick up the package name as the key \emph{family},
325 unless explicitly given as an optional argument:
326 \begin{verbatim}
327 \ProcessKeyOptions[family]
328 \end{verbatim}
329
330 To support creating key options for this mechanism, the new command
331 \cs{DeclareKeys} has been added. This works using the same general
332 approach as \pkg{l3keys} or \pkg{pgfkeys}: each key has one or more
333 \emph{properties} which define its behavior.
334
335 Options for packages which use this new approach will not be checked for
336 clashes by the kernel. Instead, each time a \cs{usepackage} or
337 \cs{RequirePackage} line is encountered, the list of options given will be
338 passed to \cs{ProcessKeyOptions}. Options which can only be given
339 the first time a package is loaded can be marked using the property
340 \texttt{.usage = load}, and will result in a warning if used in a subsequent
341 package loading line.
342
343 Package options defined in this way can also be set within a package using
344 the new command \cs{SetKeys}, which again takes an optional argument
345 to specify the \emph{family}, plus a mandatory one for the options themselves.
346
347
348
349 \section{New or improved commands}
350
351
352 \subsection{Floating point and integer calculations}
353
354 The L3 programming layer offers expandable commands for calculating
355 floating point and integer values, but so far these functions have
356 only been available to programmers, because they require
357 \cs{ExplSyntaxOn} to be in force. To make them easily available at the
358 document level, the small package \pkg{xfp} defined \cs{fpeval} and
359 \cs{inteval}.
360
361
362 An example of use could be the following:
363 \begin{verbatim}
364 \LaTeX{} can now compute:
365 \[ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
366 = \fpeval{sin(3.5)/2 + 2e-3} \]
367 \end{verbatim}
368 which produces the following output:
369 \begin{quote}
370 \LaTeX{} can now compute:
371 \[ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
372 = \fpeval{sin(3.5)/2 + 2e-3} \]
373 \end{quote}
374 These two commands have now been moved into the kernel and in addition
375 we also provide \cs{dimeval} and \cs{skipeval}. The details of their
376 syntax are described in \file{usrguide3.pdf}. The command \cs{fpeval}
377 offers a rich syntax allowing for extensive calculations, whereas the
378 other three commands are essentially thin wrappers for \cs{numexpr},
379 \cs{dimexpr}, and \cs{glueexpr} \Dash therefore inheriting some syntax
380 peculiarities and limitations in expressiveness.
381 \begin{verbatim}
382 \newcommand\calculateheight[1]{%
383 \setlength\textheight{\dimeval{\topskip
384 + \baselineskip * \inteval{#1-1}}}}
385 \end{verbatim}
386 The above, for example, calculates the appropriate \cs{textheight} for
387 a given number of text lines.
388 %
389 \githubissue{711}
390
391
392 \subsection{CamelCase commands for changing arguments to csnames}
393
394 It is sometimes helpful to \enquote{construct} a command name on the
395 fly rather than providing it as a single \cs{...}\ token. For these
396 kinds of tasks the \LaTeX3 programming layer offers a general mechanism
397 (in the form of \cs{exp\_args:N...}\ and
398 \cs{cs\_generate\_variant:Nn}). However, when declaring new
399 document-level commands with \cs{NewDocumentCommand} or
400 \cs{NewCommandCopy}, etc.\ the L3 programming layer may not be active,
401 and even if it is, mixing CamelCase syntax with L3 programming syntax
402 is not really a good approach. We have therefore added the commands
403 \cs{UseName} and \cs{ExpandArgs} to assist in such
404 situations, e.g.,
405 \begin{verbatim}
406 \NewDocumentCommand\newcopyedit{mO{red}}
407 {\newcounter{todo#1}%
408 \ExpandArgs{c}\NewDocumentCommand{#1}{s m}%
409 {\stepcounter{todo#1}%
410 \IfBooleanTF {##1}%
411 {\todo[color=#2!10]%
412 {\UseName{thetodo#1}: ##2}}%
413 {\todo[inline,color=#2!10]%
414 {\UseName{thetodo#1}: ##2}}%
415 }%
416 }
417 \end{verbatim}
418 which provides a declaration mechanism for copyedit commands, so that
419 \verb=\newcopyedit{FMi}[blue]= then defines \cs{FMi} (and the
420 necessary counter).
421
422 The command \cs{ExpandArgs} can be useful with the argument \texttt{cc} or
423 \texttt{Nc} in
424 combination with \cs{NewCommandCopy} if the old or new command name
425 or both need constructing. Finally, there is \cs{UseName} which
426 takes its argument and turns it into a command (i.e., a CamelCase
427 version of \cs{@nameuse} (\LaTeXe) or \cs{use:c} (L3 programming
428 layer)) which was also used in the example above.
429 %
430 \githubissue{735}
431
432
433 \subsection{Testing for (nearly) empty arguments}
434 %
435 In addition to \cs{IfNoValueTF} to test if an optional argument was
436 provided or not, there is now also \cs{IfBlankTF}, which tests if the
437 argument is empty or contains only blanks. Based on the result it
438 selects a true or false code branch. As usual, the variants
439 \cs{IfBlankT} and \cs{IfBlankF} are also provided for use when only one
440 branch leads to some action. Further details and examples are given
441 in \file{usrguide3.pdf}.
442
443
444 \subsection{Better allocator for Lua command ids}
445
446 In \LuaTeX\ we already had the \cs{newluafunction} macro which allocates
447 a Lua function identifier which can be used to define commands
448 with \cs{luadef}. But this always required two steps: \cs{newluafunction}
449 defines the passed control sequence as an integer, which then has to be used
450 to define the actual Lua command with \cs{luadef}. After that, the integer is
451 no longer needed. This was inconsistent with other allocators. Therefore we
452 added two new allocators \cs{newluacmd} and \cs{newexpandableluacmd} which
453 directly define a control sequences invoking the allocated Lua function.
454 The former defines a non-expandable Lua command, the latter an expandable
455 one. Of course, the associated Lua function still has to be defined by assigning
456 a function to the \verb|lua.get_functions_table()| table. The required index is
457 available in \cs{allocationnumber}.
458
459 An example could be
460 \begin{verbatim}
461 \newluacmd \greeting
462 \directlua {
463 lua.get_functions_table()
464 [tex.count.allocationnumber]
465 = function()
466 local name = token.scan_argument()
467 tex.sprint('Hello ', name, '!')
468 end
469 }
470
471 \greeting{world}
472 \end{verbatim}
473 %
474 \githubissue{536}
475
476 \subsection{Starred command version for \cs{ref}, \cs{Ref} and \cs{pageref}}
477
478 For a long time \pkg{hyperref} has provided starred versions for the reference commands
479 which do not create active links. This syntax extension required users and
480 package authors to check if \pkg{hyperref} was loaded and adjust the coding
481 accordingly or take the starred forms out if text was copied to a document
482 without \pkg{hyperref}. The commands have now been aligned with
483 the \pkg{hyperref} usage and always allow an optional star. The \pkg{showkeys} package
484 has been updated to handle the starred versions too, both with \pkg{hyperref} or \pkg{nameref}
485 and without. The commands are defined with \cs{NewDocumentCommand} and so no longer expand when
486 written to auxiliary files. This reduces the number of compilations needed to resolve references
487 in captions and sectioning commands. The package \pkg{ifthen} has been updated to ensure that
488 \cs{pageref} can still be used inside tests like \cs{isodd}.
489
490
491 \subsection{Preparation for supporting PDF in backends}
492
493 At the current point in time, basic support for PDF in
494 backends is not part of \LaTeX{} core; it is provided by an external
495 package like \pkg{hyperref}.
496 At some time in the future that work will be placed
497 into the kernel but for now it is separate and has to be
498 explicitly loaded in the document. To enable class and package authors
499 to support PDF-specific tasks like the creation of link targets without
500 having to test first if \pkg{hyperref} has been loaded, dummy versions of
501 the commands \cs{MakeLinkTarget}, \cs{LinkTargetOn}, \cs{LinkTargetOff} and
502 \cs{NextLinkTarget} are provided.
503
504 \section{Code improvements}
505
506 \subsection{\cs{protected} UTF-8 character definitions}
507 The characters defined via \file{utf8.def} are now defined as \cs{protected}
508 macros. This makes them safe to use in expansion contexts where the
509 classic \cs{protect} mechanism is not enabled, notably L3 programming
510 layer \texttt{e} and \texttt{x} arguments.
511
512 Related to this change \cs{MakeUppercase} and \cs{MakeLowercase} have
513 been updated to use the Unicode-aware case changing functions
514 \cs{text\string_lowercase:n} in place of the \TeX\ primitive \cs{lowercase}.
515 The \cs{NoCaseChange} command from the \pkg{textcase} package has also been added.
516
517 Note: for technical reasons these low-level character handling changes
518 will not be rolled back if the format version is rolled back using the
519 \pkg{latexrelease} package rollback mechanism.
520 %
521 \githubissue{780}
522
523 \subsection{A small update to \cs{obeylines} and \cs{obeyspaces}}
524
525 The plain \TeX{} versions of \cs{obeylines} and \cs{obeyspaces} make
526 \verb=^^M= and \verb*= = active and force them to execute \cs{par} %*
527 and \cs{space}, respectively. Don Knuth makes a remark in the \TeX{}book
528 that one can then use a trick such as
529 \begin{verbatim}
530 \let\par=\cr \obeylines \halign{...
531 \end{verbatim}
532 However, redefining \cs{par} like this
533 may lead to all kinds of problems in \LaTeX. We have therefore changed
534 the commands to use an indirection: the active characters now execute
535 \cs{obeyedline} and \cs{obeyedspace}, which in turn do what the
536 hardwired solution did before.
537
538 \begin{quote}
539 \renewcommand\obeyedspace{\ \textbullet\ }
540 \footnotesize\obeyspaces%
541 This means that it is now possible to %
542 achieve special effects in a safe way. %
543 This paragraph, for example, was produced by %
544 making \cs{obeyedspace} generate %
545 \texttt{\{\cs{\verbvisiblespace}\cs{textbullet}\cs{\verbvisiblespace}\}} and %
546 enabling \cs{obeyspaces} within a %
547 quote environment.
548 \end{quote}
549 Thus, if you are keen to use the plain \TeX{} trick, you need to say
550 \cs{let}\cs{obeyedline}\texttt{=}\cs{cr} now.
551 %
552 \githubissue{367}
553
554
555 \subsection{\pkg{doc} upgraded to version~3}
556
557 After roughly three decades the \pkg{doc} package received a cautious
558 uplift, as already announced at the 2019 TUG conference\Dash changes
559 to \pkg{doc} are obviously always done in a leisurely manner.
560
561 Given that most documentation is nowadays viewed on screen,
562 \pkg{hyperref} support is added and by default enabled (suppress it
563 with option \option{nohyperref} or alternatively with
564 \option{hyperref}\texttt{=false}) so the internal cross-references are
565 properly resolved including those from the index back into the
566 document.
567
568 Furthermore, \pkg{doc} now has a general mechanism to define
569 additional \enquote{doc} elements besides the two \texttt{Macro} and
570 \texttt{Env} it has known in the past. This enables better
571 documentation because you can now clearly mark different types of
572 objects instead of simply calling them all \enquote{macros}.
573 If desired, they can be collected together under a heading
574 in the index so that you have a section just with your document
575 interface commands, or with all parameters, or \ldots
576
577 The code borrows ideas from Didier Verna's \pkg{dox} package (although
578 the document level interface is different) and it makes use of Heiko
579 Oberdiek's \pkg{hypdoc} package, which at some point in the future
580 will be completely integrated, given that its whole purpose it to
581 patch \pkg{doc}'s internal commands to make them \pkg{hyperref}-aware.
582
583 All changes are expected to be upward compatible, but if you run into
584 issues with older documentation using \pkg{doc} a simple and quick
585 solution is to load the package as follows:
586 \verb/\usepackage{doc}[=v2]/
587
588 \subsection{\pkg{doc} can now show dates in change log}
589
590 Up to now the change log was always sorted by version numbers
591 (ignoring the date that was given in the \cs{changes} command). It
592 can now be sorted by both version and date if you specify the option
593 \option{reportchangedates} on package level and in that case the
594 changes are displayed with
595 \begin{quote}
596 \meta{version} -- \meta{date}
597 \end{quote}
598 as the heading (instead of just \meta{version}), when using
599 \cs{PrintChanges}.
600 %
601 \githubissue{531}
602
603
604
605 \subsection{\class{ltxdoc} gets options \option{nocfg} and \option{doc2}}
606
607 The \LaTeX{} sources are formatted with the \class{ltxdoc} class,
608 which supports loading a local config file \file{ltxdoc.cfg}. In the
609 past the \LaTeX{} sources used such a file but it was not distributed.
610 As a result reprocessing the \LaTeX{} sources elsewhere showed
611 formatting changes. We now distribute this file which means that it
612 is loaded by default. With the option \option{nocfg} this can be
613 prevented.
614
615 We also added a \option{doc2} option to the class so that it is
616 possible to run old documentation with \pkg{doc} version~2, if
617 necessary.
618
619
620
621 \subsection{Lua\TeX\ callback improvements}
622
623 The Lua\TeX\ callbacks \texttt{hpack\_quality} and \texttt{vpack\_quality} are
624 now \texttt{exclusive} and therefore only allow a single handler.
625 The previous type \texttt{list} resulted in incorrect parameters when multiple
626 handlers were set; therefore, this only makes an existing restriction more
627 explicit.
628
629 Additionally the return value \texttt{true} for \texttt{list}
630 callbacks is now handled internally and no longer passed on to the
631 engine. This simplifies the handling of these callbacks and makes it
632 easier to provide consistent interfaces for user-defined \texttt{list}
633 callbacks.
634
635
636 \subsection{Class \class{proc} supports \option{twoside}}
637
638 The document class \class{proc}, which is a small variation on the
639 \class{article} class, now supports the \option{twoside} option,
640 displaying different data in the footer line on recto and verso pages.
641 %
642 \githubissue{704}
643
644
645 \subsection{Croatian character support}
646
647 The default \pkg{inputenc} support has been extended to support the 9 characters
648 D\v Z, D\v z, d\v z, LJ, Lj, lj, NJ, Nj, nj, input as single UTF-8 code points
649 in the range U+01C4 to U+01CC.
650 %
651 \githubissue{723}
652
653
654 \subsection{Cleanup of the Unicode declaration interface}
655
656 When declaring encoding specific commands for the Unicode (TU)
657 encoding some declarations (e.g., \cs{DeclareUnicodeComposite}) do not
658 have an explicit argument for the encoding name, but instead use
659 the command \cs{UnicodeEncodingName} internally. There was one
660 exception though: \cs{DeclareUnicodeAccent} required an explicit
661 encoding argument. This inconsistency has now been removed and the
662 encoding name is always implicit. To avoid a breaking change for a few
663 packages on CTAN, \cs{DeclareUnicodeAccent} still accepts three
664 arguments if the second argument is \texttt{TU} or
665 \cs{UnicodeEncodingName}. Once all packages have been updated this
666 code branch will get removed.
667
668 At the same time we added \cs{DeclareUnicodeCommand} and
669 \cs{DeclareUnicodeSymbol} for consistency. They also use
670 \cs{UnicodeEncodingName} internally, instead of requiring an encoding
671 argument as their general purpose counterparts do.
672 %
673 \githubissue{253}
674
675
676 \subsection{New hook:\ \hook{include/excluded}}
677
678 A few releases ago we introduced a number of file hooks for different
679 types of files; see~\cite{35:ltnews32} and in
680 particular~\cite{35:ltfilehook-doc}.
681 %
682 The hooks for \cs{include} files now have an addition: if such a file
683 is not included (because \cs{includeonly} is used and its \meta{name}
684 is not listed in the argument) then the hooks \hook{include/excluded}
685 and \hook{include/\meta{name}/excluded} are executed in that
686 order\Dash of course, only if they contain code. This happens after
687 \LaTeX{} has loaded the \texttt{.aux} file for this include file,
688 i.e., after \LaTeX{} has updated its counters to pretend that the file
689 was seen.
690
691
692 \subsection{Input support for normalized angle brackets}
693
694 Source files containing \textlangle\ or \textrangle\ directly written
695 as Unicode codepoints U+2329 and U+232A no longer break when the
696 source file gets normalized under Unicode normalization rules.
697 %
698 \githubissue{714}
699
700
701
702
703 \section{Bug fixes}
704
705 \subsection{Using \cs{DeclareUnicodeCharacter} with C1 control points}
706 An error in the UTF-8 handling for non-Unicode \TeX\ has prevented
707 \cs{DeclareUnicodeCharacter} being used with characters in the range
708 hex 80 to 9F. This has been corrected in this release.
709 %
710 \githubissue{730}
711
712
713
714 \subsection{Fix \cs{ShowCommand} when used with \pkg{ltcmd}}
715
716 When \cs{ShowCommand} support was added for \pkg{ltcmd} in the previous
717 release~\cite{35:ltnews34}, a blunder in the code made it so that
718 when \cs{ShowCommand} was used on a command defined with \pkg{ltcmd}, it
719 only printed the meaning of the command in the terminal, but didn't stop
720 for interaction as it does elsewhere (mimicking \cs{show}). The issue
721 is now fixed.
722 %
723 \githubissue{739}
724
725
726
727 \subsection{Make \cs{cite}\texttt{\textbraceleft\textbraceright} produce a warning}
728
729 When the \cs{cite} command can't resolve a citation label it issues a
730 warning \enquote{Citation `\meta{label}' on page \meta{page}
731 undefined}. However, due to some implementation details a completely
732 empty argument was always silently accepted. Given that there are probably
733 people who write \verb=\cite{}= with the intention to fill in the
734 correct label later it is rather unfortunate if that is not generating
735 a warning that something in the document is still amiss.
736 This has finally been corrected and a warning is now generated also in this case.
737 %
738 \githubissue{790}
739
740
741
742 \subsection{Fix adding \hook{cmd} hooks to simple macros}
743
744 A bug in how \LaTeX{} detected the type of a command caused a
745 premature forced expansion of such commands, which, depending on their
746 definition, could be harmless or could cause severe trouble. This has
747 been fixed in the latest release.
748 %
749 \githubissue{795}
750 \sxissue{q/637565}
751
752
753 \subsection{Warn if \hook{shipout/lastpage} hook is executed too early}
754
755 The hook \hook{shipout/lastpage} is intended to place \cs{special}s
756 into the last page shipped out. This is needed for some use cases,
757 e.g., tagging. If that hook is nonempty and the user has added additional
758 pages since the last run, then \LaTeX{} executes this hook too early,
759 but until now without giving any indication that the document needs
760 rerunning. This has now been corrected and an appropriate warning is
761 given.
762 %
763 \githubissue{813}
764
765
766 \subsection{More consistent use of cramped math styles in \LuaTeX}
767
768 Using \LuaTeX's \cs{Udelimiterover} to place a horizontally extensible glyph
769 on top of a mathematical expression now causes the expression to be set in cramped
770 style, as used in similar situations by traditional \TeX\ math rendering.
771 Similarly, cramped style is now used for expressions set under such a delimiter
772 using \cs{Uunderdelimiter}, but is no longer used when setting an expression on top
773 of such extensible glyphs using \cs{Uoverdelimiter}.
774 This new behavior follows \TeX's rule that cramped style is used whenever something
775 else appears above the expression.
776 Additionally the math style of these constructs can now be detected using \cs{mathstyle}.
777
778 The old behavior can be restored by adding
779 \begin{verbatim}
780 \mathdefaultsmode=0
781 \end{verbatim}
782 to a document.
783
784
785 \subsection{Fixed bug when setting hook rules for one-time hooks}
786
787 If a \cs{DeclareHookRule} command is set for a one-time hook, it has to
788 come \emph{before} the hook gets used, because otherwise it never
789 applies\Dash after all, the hook is used only once. There was a bug in
790 the implementation in that the sorting mechanism was still applied if
791 the \cs{DeclareHookRule} declaration appeared while the one-time hook was
792 executed, causing the spurious typesetting of the code labels and the
793 hook name. This bug is now fixed and an error is raised when a new
794 sorting rule is added to an already-used one-time hook.
795
796 A possible scenario in which this new error is raised is the following:
797 package \pkg{AAA} declares a hook rule for \hook{begindocument} (i.e.,
798 \cs{AtBeginDocument}) to sort out the behavior between itself and some
799 other package. Package \pkg{BBB} wants to load package \pkg{AAA} but
800 only if it hasn't been loaded in the preamble, so delays the loading to
801 \hook{begindocument}. In that case the hook rule declared by \pkg{AAA}
802 can no longer be applied and you get the error. If that happens the
803 solution is to load the package in \hook{begindocument/before}, which
804 is executed at the very end of the preamble but before
805 \hook{begindocument} is processed.
806 %
807 \githubissue{818}
808
809
810
811
812 \section{Changes to packages in the \pkg{amsmath} category}
813
814
815 \subsection{\pkg{amsopn}:\ Do not reset \cs{operator@font}}
816
817 The package \pkg{amsopn} used to define \cs{operator@font} but this
818 command has been provided by the \LaTeX{} format for at least 14
819 years. As a result the definition in \pkg{amsopn} is equivalent to a
820 reset to the kernel definition, which is unnecessary and surprising if
821 you alter the math setup (e.g., by loading a package) and at a later
822 stage add \pkg{amsmath}, which then undoes part of your setup. For
823 this reason the definition was taken out and
824 \pkg{amsmath}/\pkg{amsopn} now relies on the format definition.
825
826 In the unlikely event that you want the resetting to happen, use
827 \begin{verbatim}
828 \makeatletter
829 \def\operator@font{\mathgroup\symoperators}
830 \makeatother
831 \end{verbatim}
832 after loading the package.
833 %
834 \githubissue{734}
835
836 \subsection{\pkg{amsmath}:\ Error in \cs{shoveleft}}
837
838 If \cs{shoveleft} started out with the words \enquote{plus} or
839 \enquote{minus} it was misunderstood as part of a rubber length and
840 led either to an error or was swallowed without trace. By adding a
841 \cs{relax} this erroneous scanning into the argument of \cs{shoveleft}
842 is now prevented.
843 %
844 \githubissue{714}
845
846
847 \subsection{\pkg{amsmath} and \pkg{amsopn}:\ Robustify user commands}
848
849 Most user-level commands have been made robust in the \LaTeX{} kernel
850 during the last years, but variant definitions in \pkg{amsmath} turned
851 them back into fragile beings. We have now made most commands in
852 \pkg{amsmath} and \pkg{amsopn} robust as well to match the kernel
853 behavior. This also resolves a bug recently discovered in the
854 \pkg{mathtools} package, which was due to \cs{big} not being robust after
855 \pkg{amsmath} was loaded.
856 %
857 \githubissue{123}
858
859
860
861 \section{Changes to packages in the \pkg{graphics} category}
862
863 \subsection{Color in formulas}
864
865 While it is possible to color parts of a formula using \cs{color}
866 commands the approach is fairly cumbersome. For example, to color a
867 summation sign, but not its limits, you need four \cs{color} commands and
868 some seemingly unnecessary sets of braces to get coloring and spacing
869 right:
870 {\hfuzz=1pt
871 \begin{verbatim}
872 \[ X = \color{red} \sum
873 % without {{ the superscript below is misplaced
874 _{{\color{black} i=1}}
875 % without {{ the \sum is black
876 ^{{\color{black} n}}
877 \color{black} % without it the x_i is red
878 x_i \]
879 \end{verbatim}
880 }\noindent
881 Leaving out any of the \cs{color} commands or any of the \verb={{...}}=
882 will give you a wrong result instead of the desired
883 \[ X = \color{red} \sum
884 _{{\color{black} i=1}} % without {{ the superscript is misplaced
885 ^{{\color{black} n}} % without {{ the \sum is black
886 \color{black} % without it the x_i is red
887 x_i
888 \]
889 So even if this is possible, it is not a very practical solution and
890 furthermore there are a number of cases where it is impossible to
891 color a certain part of a formula, for example, an opening symbol such
892 as \verb=\left(= but not the corresponding \verb=\right)=.
893
894 We have therefore added the command \cs{mathcolor} to the \pkg{color}
895 and \pkg{xcolor} package, which has the same syntax as \cs{textcolor},
896 but is specially designed for use in math and handles sub and
897 superscripts and other aspects correctly and preserves correct
898 spacing. Thus, the above example can now be written as
899 \begin{verbatim}
900 \[ X = \mathcolor{red}{\sum}_{i=1}^n x_i \]
901 \end{verbatim}
902 This command is \emph{only} allowed in formulas.
903 For details and further examples, see \file{mathcolor.pdf}.
904
905
906 \subsection{Fix locating files with \cs{graphicspath}}
907
908 If a call to \cs{includegraphics} asked for a file (say, \file{image})
909 without extension, and if both \file{A/image.pdf} and \file{B/image.tex}
910 existed (both \file{A/} and \file{B/} in \cs{graphicspath}, but neither
911 in a folder searched by \TeX), then \file{A/image.pdf} would not be
912 found, and a \enquote{file not found} error would be incorrectly thrown.
913 The issue is now fixed and the graphics file is correctly found.
914 %
915 \githubissue{776}
916 \sxissue{q/630167}
917
918
919
920
921 \section{Changes to packages in the \pkg{tools} category}
922
923 \subsection{\pkg{multicol}:\ Fix \cs{newcolumn}}
924
925 The recently added \cs{newcolumn} didn't work properly if used in
926 vertical mode, where it behaved like \cs{columnbreak}, i.e., spreading
927 the column material out instead of running the column short.
928 %
929 \sxissue{q/624940}
930
931
932 \subsection{\pkg{bm}:\ Fix for \pkg{amsmath} operators}
933
934 An internal command used in the definition of operator commands such
935 as \cs{sin} in \pkg{amsmath} has been guarded in \cs{bm} to prevent
936 internal syntax errors due to premature expansion.
937 %
938 \githubissue{744}
939
940
941
942 \medskip
943
944 \begin{thebibliography}{9}
945
946 \fontsize{9.3}{11.3}\selectfont
947
948 \bibitem{35:blueprint} Frank Mittelbach and Chris Rowley:
949 \emph{\LaTeX{} Tagged PDF \Dash A blueprint for a large project}.\\
950 \url{https://latex-project.org/publications/indexbyyear/2020/}
951
952 \bibitem{35:ltnews32} \LaTeX{} Project Team:
953 \emph{\LaTeXe{} news 32}.\\
954 \url{https://latex-project.org/news/latex2e-news/ltnews32.pdf}
955
956 \bibitem{35:ltnews34} \LaTeX{} Project Team:
957 \emph{\LaTeXe{} news 34}.\\
958 \url{https://latex-project.org/news/latex2e-news/ltnews34.pdf}
959
960 \bibitem{35:ltfilehook-doc} Frank Mittelbach, Phelype Oleinik, \LaTeX{}~Project~Team:
961 \emph{The \texttt{\upshape ltfilehook} documentation}.\\
962 Run \texttt{texdoc} \texttt{ltfilehook-doc} to view.
963 \end{thebibliography}
964
965
966
967 \end{document}