diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex-dev/base/ltnews38.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex-dev/base/ltnews38.tex | 489 |
1 files changed, 417 insertions, 72 deletions
diff --git a/Master/texmf-dist/doc/latex-dev/base/ltnews38.tex b/Master/texmf-dist/doc/latex-dev/base/ltnews38.tex index 38745b9dbfb..04ffe1a0ed2 100644 --- a/Master/texmf-dist/doc/latex-dev/base/ltnews38.tex +++ b/Master/texmf-dist/doc/latex-dev/base/ltnews38.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright 2021-2023 +% Copyright 2023 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -101,6 +101,8 @@ \vbadness=1400 % accept slightly empty columns +\let\finalpagebreak\pagebreak % for TUB (if they use it) + \makeatletter % maybe not the greatest design but normally we wouldn't have subsubsections \renewcommand{\subsubsection}{% @@ -123,7 +125,8 @@ \tubcommand{\input{tubltmac}} \publicationmonth{November} -\publicationyear{2023 --- DRAFT version for upcoming release} +%\publicationyear{2023 --- DRAFT version for upcoming release} +\publicationyear{2023} \publicationissue{38} @@ -139,118 +142,460 @@ \medskip -\section{Introduction} - +%\section{Introduction} -\section{Sockets and plugs} -\emph{write} +\section{News from the \enquote{\LaTeX{} Tagged PDF} project} -For documentation see \texttt{texdoc ltsockets-doc} for now. +The multi-year project to automatically tag \LaTeX{} documents in +order to make them accessible~\cite{38:blueprint} is progressing +steadily (at this point in time mainly as experimental +\texttt{latex-lab} code). -\section{Extended cross-referencing of document properties} +Just recently we added support for automatic tagging of tabular +structures including environments from \pkg{tabularx} and +\pkg{longtable}. The code is still in its early stages and lacks +configuration possibilities\Dash these will be added in the future. -Traditionally \LaTeX{} allowed with \cs{label} to record two \enquote{local} -properties of the document: the representation of the current page number and -of the current counter. Their values could then be referenced with the -(non-expandable) commands \cs{ref} and \cs{pageref} in arbitrary places of a -document. With the summer 2023 release the \cs{label} was enhanced to record -also if set by packages like \pkg{nameref} or \pkg{hyperref} the title and -the name of the link target. +\subsection{Approaching an important milestone} -Over the years packages extended the label-ref system in various ways. -Examples are for example the \pkg{refcount} package to reference the values -expandably, the \pkg{smartref} package, which allows to store more counter -values and so to reference the current chapter together with the current -equation, the \pkg{cleveref} package, which stores in a second internal label -beside other the name of the counter, the \pkg{hyperref} package whose -\cs{autoref} command tries to retrieve the name of the counter from the name -of the link target, the \pkg{tikzmarks} which records absolute positions on -the page, and the \pkg{zref} package which implements a general method to -record and reference properties. +Nevertheless, with this new addition we are more or less able to +automatically tag any document that confines itself to the commands +and environments described in Leslie Lamport's \emph{\LaTeX{} +Manual}~\cite{38:Lamport} by simply adding a single configuration line +at the top. -Starting with this release the \LaTeX{} kernel contains now its own -extension. It is loosely based on \pkg{zref}. It allows to declare new -properties, to record arbitrary combinations of properties. The values are -retrieved expandably. +In addition, a number of extension packages that go beyond Lamport are +already supported, most importantly perhaps \pkg{amsmath} (providing +extended math capabilities) and \pkg{hyperref} (enhancing \LaTeX{} +with interactive hyperlinking features). +\finalpagebreak +Also already supported are +some of the major bibliography support packages such as \pkg{natbib} +and \pkg{biblatex}. -As an example to setup a new property which records the current chapter -number the following declaration could be used: +For now activation is done through the line +\begin{verbatim} +\DocumentMetadata + {testphase={phase-III,math,tabular}} +\end{verbatim} +The math and the tabular support are not yet incorporated into +\texttt{phase-III} but need their own activation, so that we can +better experiment with additions and code adjustments. + +The \texttt{latex-lab} bundle contains various (still untagged) +documentation files about the new code that can be accessed with +\verb|texdoc -l latex-lab|. + +\subsection{A GitHub repository dedicated to the project} + +We have also started a new GitHub repository mainly intended for +reporting issues, and offering a platform for discussions. For +example, there is one discussion on ways to extend the \LaTeX{} +\env{tabular} syntax to allow describing the logical structure of +tables (e.g., which cells are header cells, etc.). + +Having all issues and discussions related to the project in a single +place instead of being spread across multiple repositories such as +\pkg{latex2e}, \pkg{latex3}, \pkg{tagpdf}, \pkg{hyperref}, +\pkg{pdfresources}, etc., helps people to find information easily +and report any issue related to the project without needing to know in which +code repository the problematic code resides. + +You find this repository at +\url{https://github.com/latex3/tagging-project} and the mentioned +discussion on \env{tabular} syntax at +\url{https://github.com/latex3/tagging-project/discussions/1}. + +Your feedback is important and reporting what doesn't yet work is +beneficial to all users, so we hope to see you there and thank you for +any contribution, whether it is an issue or a post on a discussion +thread. + + +\section{Hooks, sockets and plugs} + +In previous releases of \LaTeX{} we introduced the general concept of +hooks (both specific and generic ones). These are places in the +code into which different packages (or the user in the document +preamble) can safely add their own code to extend the functionality of +existing commands and environments without the need to overwrite or +patch them in incompatible ways. An important feature of such hooks is +that the code chunks added by different packages can be ordered by +rules, if necessary, +\finalpagebreak +thereby avoiding problems arising from +differences in package loading order. See \LaTeX{} News issues +32--34~\cite{38:ltnews} for more information. + +However, sometimes you need a kind of \enquote{hook} into which only a +single chunk of code is placed at any time.\footnote{While this is in +theory possible to model with the existing hook mechanism, it is +inefficient and cumbersome.} For example, there is code that +implements footnote placement in relation to bottom floats (above or +below them). But at any time in the document only one such placement +code can be in force. Or consider the extra code needed for making +\LaTeX{} documents accessible (e.g., adding tags to the PDF +output). Such code is either there (perhaps in alternative versions) +or not at all, but it cannot have code from other packages added at +the same point interfering with the algorithm. + +For these use cases we now introduce the concept of sockets and plugs. +A socket is a place in the code into which one can put a plug (a +chunk of code with a name) after which the socket is in use; to put in +a different plug, the former one has to be taken out +first.\footnote{Think of electric outlets and plugging something into +them.} A socket may or may not have inputs that can then be used by +the plugs. +% +While this is technically not much different to putting a command in +the code and at some point alter its definition, the advantage is that +this offers a consistent interface, allows for status information, +supports tracing, etc. + +You declare a new socket and possibly some plugs for it with +\begin{flushleft} + \cs{NewSocket}\Arg{socket name}\Arg{\# of inputs} \\ + \cs{NewSocketPlug}\Arg{socket name}\Arg{plug name}\Arg{code} +\end{flushleft} +For example, after the declaration \verb=\NewSocket{foo}{0}= you can +immediately use this socket in your code with \verb=\UseSocket{foo}=. +The \cs{NewSocket} declaration automatically defines a simple plug +with the name \texttt{noop} for the socket and assigns it to the socket +(plugs it in), thus your \cs{UseSocket} sits idle doing +nothing\footnote{Sockets with one input also define an +\texttt{identity} plug and initially assign that to the socket\Dash +this means that their input is simply returned without processing.} +until you assign it a different plug, which is done with +\cs{AssignSocketPlug}. This takes the current plug out and puts the +new one in. +% +All the declarations and commands are also available in the \LaTeX3 +programming layer as \cs{socket\_new:nn}, \cs{socket\_new\_plug:nnn}, +etc. + +With this concept we can, for example, add tagging support for the +\enquote{\LaTeX{} Tagged PDF} project to various packages without +altering their behavior if the tagging code is inactive. Activating +one or the other form of tagging then just means to assign named plugs +to the different sockets. + +This is just a brief introduction to the mechanism; for more detailed +documentation see \texttt{texdoc ltsockets-doc}. + + +\finalpagebreak + +\section{Document properties and cross-referencing} + +Traditional \LaTeX{} uses \cs{label}\Arg{key} to record the values of two +\enquote{local} properties of the document: the textual +representations of the \emph{current page number} and the +\emph{current \textup{\cs{ref}} value} set by \cs{refstepcounter} +declarations~\cite[p.~209]{38:Lamport}. (These declarations are +issued, for example, by sectioning commands, by numbered environments +like \env{equation}, and by \cs{item} in an \env{enumerate} or +similar environment.) + +These two recorded values can then be accessed and typeset (from +anywhere in the next run of the document) by use of the +(non-expandable) commands \cs{ref} and \cs{pageref} using the +\emph{key} that was specified as the argument to \cs{label} when +recording these values. This supported basic cross-referencing +(within a document), using these recorded values to provide both +page-related and counter-related information (such as the page xvii or +the subsection number 4.5.2).\footnote{In the Spring 2023 release of +\LaTeX{}, the \cs{label} command was extended to record, in addition, +both a title (such as the text used in a section head) and the +\emph{logical name} used for an associated link target provided these +have been set by packages such as \pkg{nameref} or \pkg{hyperref}.} + + +Over the years \LaTeX{} packages have appeared that extend +this basic \enquote{label-ref system} in various ways. +% +For example, the \pkg{refcount} package made a small but significant change +to the functions used to access recorded values, by making them expandable. +And the \pkg{smart-ref} package supports the storage of a larger +collection of counter values so that, for example, a cross-reference +can refer to the relevant chapter together with an equation tag. +The \pkg{cleveref} package stores (by means of a second, internal +\enquote{logical label}) extra information such as the name of the counter. +The \pkg{hyperref} package adds the \cs{autoref} command, which +tries to retrieve the name of a counter from the \emph{logical name} +used for a link target. +The \pkg{tikzmarks} library records information about + \emph{labelled positions} on the page when using \pkg{tikz}. +Finally, the \pkg{zref} package implements many related ideas, including a general +idea of properties and lists of properties, with methods to record, and +subsequently access, the value of any declared property. + + +Starting with this release, the \LaTeX{} kernel provides handling of +general document properties as a core functionality with standard +interfaces. +% +This is based on concepts introduced by the \pkg{zref} package but +with some differences in detail, particularly in the implementation. +It supports the declaration of new properties, and the recording of +the values of any list of properties. These values are retrieved +expandably. + +To set up a new property that is the current chapter +number, for example, here is the declaration to use. \begin{verbatim} -\NewProperty{chapter}{now}{?}{\thechapter} + \NewProperty{chapter}{now}{?}{\thechapter} \end{verbatim} -The second argument means that the property is recorded immediately -(\enquote{now}) and not at shipout. The third argument sets a default if a -label is unknown. It is then possible to record a list of properties with -\cs{RecordProperties}: +\par\finalpagebreak\noindent +The second argument means that the property value will be recorded +immediately (\enquote{now}), and not \enquote{during the next + \cs{shipout}}. The third argument sets a default to be used when, +for example, an unknown label is supplied. +% +The final argument contains the code that will, as part of the +recording process, be expanded to obtain the value to record for this +property. + +Then, to record the value of this new property, +together with others, use this command. \begin{verbatim} -\RecordProperties{mylabel}{chapter,page,currentlabel} + \RecordProperties{mylabel} + {chapter,page,label} \end{verbatim} -To reference the value the \cs{RefProperty} command is provided which takes -two arguments, the label and the property: +This records the current values for the properties \texttt{chapter}, +\texttt{page}, and \texttt{label}, using \texttt{mylabel} as the +label, or \emph{key}, for the record. + +To \emph{reference} (i.e., retrieve) this recorded value for use in a +cross-reference to this chapter, use the \cs{RefProperty} command with +two arguments: the label, or \emph{key}, and the property. \begin{verbatim} -\RefProperty{mylabel}{chapter} + \RefProperty{mylabel}{chapter} \end{verbatim} - -The new module predeclares a set of generally useful properties: -\texttt{currentlabel} (the standard counter representation), \texttt{page} -(the page representation), \texttt{title} (the title if set e.g.~by -\pkg{nameref}), \texttt{target} (the name of the link target if set e.g.~by -\pkg{hyperref}), \texttt{pagenum} (the page as an arabic number), -\texttt{abspage} (the absolute page number), \texttt{counter} (the name of -the current counter), \texttt{xpos} and \texttt{ypos} the position on the -page as set by a previous \cs{pdfsavepos}. - -The module provides both \LaTeXe{} camel case commands and expl3 commands. - -For documentation see \texttt{texdoc ltproperties-doc}. -\section{New or improved commands} +The +\LaTeX{} kernel itself contains +declarations for some generally useful properties, +including these: +\begin{description} +\item[\texttt{label}] the textual representation of the \emph{current +\textup{\cs{ref}} value}, see above; + +\item[\texttt{page}] the textual representation of the page number for + the page currently under construction; + +\item[\texttt{title}] the title, if set by, e.g.,~\pkg{nameref}; + +\item[\texttt{target}] the logical name of the associated link target, + if set by, e.g.,~\pkg{hyperref}; + +\item[\texttt{pagetarget}] the logical name of the target added by + \pkg{hyperref} at the origin of each shipped out page; +\item[\texttt{pagenum}] the value of the \LaTeX{} counter + \texttt{page} in Arabic numerals; + +\item[\texttt{abspage}] the absolute page number of the page under + construction, i.e., one more than the number of pages shipped out so + far (thus it starts at 1 and is increased by 1 whenever a page is + shipped out); + +\item[\texttt{counter}] the name of the counter that produced the + \emph{current \textup{\cs{ref}} value}, i.e., the counter that was + stepped in the most recent \cs{refstepcounter} within the current + scope; + +\item[\texttt{xpos}, \texttt{ypos}] the position on the shipped out + page as set by the most recent \cs{pdfsavepos}: recording these + properties should be done as soon as possible after saving the + position. +\end{description} + +Both \LaTeXe{} commands (using camel-case names) and +\LaTeX3 programming layer commands are provided. % -\githubissue{xxx} +For a more complete documentation, see \texttt{texdoc ltproperties-doc}. -\section{\emph{Removed} commands} -It is very rare that commands are removed from the \LaTeX{} kernel. However, in -this release we have elected to remove \cs{GetDocumentCommandArgSpec}, -\cs{GetDocumentEnvironmentArgSpec}, \cs{ShowDocumentCommandArgSpec} and -\cs{ShowDocumentEnvironmentArgSpec} from the kernel. These commands have been -moved back to the \enquote{stub} \pkg{xparse} provided in \pkg{l3packages}. The -reason for this change is that the commands were essentially part of debugging -early forms of the kernel code, and expose implementation detail in a way that -was not helpful. + +\finalpagebreak + +\section{New or improved commands} + +\subsection{Testing for the \LaTeX3 programming layer version: \cs{IfExplAtLeastTF}} + +The integration of \pkg{expl3} (the \LaTeX3 programming layer) +into the kernel means that programmers can use all of the features +available without needing to load it explicitly. However, as \pkg{expl3} +is upgraded separately from \LaTeXe{} and is not a separate package, its +version is different from that of \LaTeXe{} and cannot be tested using +\cs{IfPackageAtLeastTF}. To date, low-level methods have therefore +been needed to check for the availability of features in +\pkg{expl3}. We have now added \cs{IfExplAtLeastTF} as a test working +in the same way as \cs{IfPackageAtLeastTF} but focused on the +pre-loaded programming layer. Programmers can check the date of +\pkg{expl3} they are using in the \texttt{.log}, as it appears both at +the start and end in the format +\begin{verbatim} + L3 programming layer <YYYY-MM-DD> +\end{verbatim} +just after the line which identifies the format (\texttt{LaTeX2e}, etc.). +% +\githubissue{1004} + \section{Code improvements} -\subsection{Support for tabs in \cs{verb*} and \texttt{verbatim*}} +\subsection{Support for tabs in \cs{verb*} and \env{verbatim*}} \LaTeX{} converts a single tab to a single space, which is then treated like a \enquote{real} space in typesetting. The same has been true to date inside \cs{verb}, but was done in a way that meant that they remained as normal spaces even in \cs{verb*}, etc. We have now adjusted the code so that tabs are retained within the argument to \cs{verb} and \cs{verb*}, and the -\texttt{verbatim} and \texttt{verbatim*} environments independently from +\env{verbatim} and \env{verbatim*} environments, independently from spaces, and are set up to print in the same way spaces do. This means that they -now generate visible spaces inside \cs{verb*} and \texttt{verbatim*}, and their +now generate visible spaces inside \cs{verb*} and \env{verbatim*}, and their behavior can be adjusted if required to be different from that of spaces. % \githubissue{1085} -\section{Bug fixes} -\section{Changes to packages in the \pkg{amsmath} category} +\subsection{Improved argument checking for box commands} +Previously if an alignment option had an unexpected value, such as +\verb|\makebox[4cm][x]{text}|, +no warning was given but the box content was silently discarded. +This will now produce a warning and act like the default \texttt{c} alignment. +\cs{framebox} and \cs{parbox} have a similar change. +% +\githubissue{1072} + + +\subsection{Aligning status of tilde with other active characters} + +Some time ago we revised the definition of active characters in \pdfTeX{} to +allow the full range of UTF-8 codepoints to be used in for example labels, +file names, etc. However, \verb|~| was not changed at that point as it is active +independent of the engine in use. This has now been corrected: the definition +of \verb|~| is an engine-protected one which gives the string version of the +character if used inside a csname. + +\finalpagebreak + +\subsection{In the programming layer} -\section{Changes to packages in the \pkg{graphics} category} +In the programming layer (\pkg{expl3}), we have revised the behavior of the +titlecasing function to enable this to either titlecase only the first word of +the input, or to titlecase every word. This should be transparent at the +document level but will be useful for programmers. + +We have also added the ability to define variables and functions inside +\cs{fpeval} (at the \pkg{expl3} level this is \cs{fp\_eval:n}). This allows +programmers to create non-standard functions that can then be used inside +\cs{fpeval}. For example, this could be used to create a new function +\texttt{dinner}: +\begin{verbatim} +\ExplSyntaxOn +\fp_new_variable:n{duck} +\fp_new_function:n{dinner} +\fp_set_function:nnn{dinner}{duck} + {duck - 0.25 * duck} +\fp_set_variable:nn{duck}{1} +$\fp_eval:n{duck} + >\fp_eval:n{dinner(duck)} + \fp_set_variable:nn{duck}{dinner(duck)} + >\fp_eval:n{dinner(duck)} + \fp_set_variable:nn{duck}{dinner(duck)} + >\fp_eval:n{dinner(duck)} + \fp_set_variable:nn{duck}{dinner(duck)} + >\fp_eval:n{dinner(duck)} +$ +\ExplSyntaxOff +\end{verbatim} + +The computation above would then generate +\begin{quote} +\ExplSyntaxOn +\fp_new_variable:n{duck} +\fp_new_function:n{dinner} +\fp_set_function:nnn{dinner}{duck} + {duck - 0.25 * duck} +\fp_set_variable:nn{duck}{1} +$\fp_eval:n{duck} + >\fp_eval:n{dinner(duck)} + \fp_set_variable:nn{duck}{dinner(duck)} + >\fp_eval:n{dinner(duck)} + \fp_set_variable:nn{duck}{dinner(duck)} + >\fp_eval:n{dinner(duck)} + \fp_set_variable:nn{duck}{dinner(duck)} + >\fp_eval:n{dinner(duck)} +$ +\ExplSyntaxOff +\end{quote} + +Users will be able to access added functions without needing to use the +\pkg{expl3} layer. It is possible that a future release of \LaTeX{} will +add the ability to create and set floating point variables at the +document level: this will be examined based on feedback on the +utility of the programming layer change. + + +\section{\emph{Removed} kernel commands} + +It is very rare that commands are removed from the \LaTeX{} kernel. However, in +this release we have elected to remove \cs{GetDocumentCommandArgSpec}, +\cs{GetDocumentEnvironmentArgSpec}, \cs{ShowDocumentCommandArgSpec} and +\cs{ShowDocumentEnvironmentArgSpec} from the kernel. These commands have been +moved back to the \enquote{stub} \pkg{xparse} provided in \pkg{l3packages}. The +reason for this change is that the removed commands exposed implementation +details. They were essentially debugging tools which with hindsight should +not have been made available directly in the kernel. + + +% \section{Bug fixes} + +\finalpagebreak \section{Changes to packages in the \pkg{tools} category} +\subsection{\pkg{longtable}: correct p-column definition} + +In general the \pkg{longtable} implementation follows the \pkg{array} +usage but the package didn't take over a change made 1992 in +\pkg{array} which adjusted the handling of the strut inserted at the +begin of p-columns. As a consequence there are a number of +inconsistencies in the output of p-columns between \pkg{tabular} and +\pkg{longtable}. This has been corrected; \pkg{longtable} now uses for +the strut the same definition as \pkg{array}. +% +\githubissue{1128} -%\medskip +\medskip +\tubcommand{\newpage} \begin{thebibliography}{9} -\fontsize{9.3}{11.3}\selectfont +%\fontsize{9.3}{11.3}\selectfont + + +\bibitem{38:Lamport} +Leslie Lamport. +\newblock \emph{{\LaTeX}: {A} Document Preparation System: User's Guide and Reference + Manual}. +\newblock \mbox{Addison}-Wesley, Reading, MA, USA, 2nd edition, 1994. +\newblock ISBN 0-201-52983-1. +\newblock Reprinted with corrections in 1996. + + +\bibitem{38:ltnews} \LaTeX{} Project Team. + \emph{\LaTeXe{} news 1--38}.\\ + \url{https://latex-project.org/news/latex2e-news/ltnews.pdf} + +\bibitem{38: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/} + + \end{thebibliography} |