[latex3-commits] [latex3/latex2e] develop: more docu in ltnews38 (78d05750)
github at latex-project.org
github at latex-project.org
Thu Oct 26 08:33:26 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/78d05750d0f65ac8f6665aecf764148dd0061ded
>---------------------------------------------------------------
commit 78d05750d0f65ac8f6665aecf764148dd0061ded
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Wed Oct 25 12:48:27 2023 +0200
more docu in ltnews38
>---------------------------------------------------------------
78d05750d0f65ac8f6665aecf764148dd0061ded
base/doc/ltnews38.tex | 265 +++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 221 insertions(+), 44 deletions(-)
diff --git a/base/doc/ltnews38.tex b/base/doc/ltnews38.tex
index 337bbd4b..f4f7b21d 100644
--- a/base/doc/ltnews38.tex
+++ b/base/doc/ltnews38.tex
@@ -123,7 +123,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,14 +140,143 @@
\medskip
-\section{Introduction}
+%\section{Introduction}
-\section{Sockets and plugs}
+\section{News from the \enquote{\LaTeX{} Tagged PDF} project}
+
+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).
+
+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.
+
+\subsection{Approaching an important milestone}
+
+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.
+
+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). Also already supported are some of the
+major bibliography support packages such as \pkg{natbib} and
+\pkg{biblatex}.
+
+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 needs 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{} \texttt{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
+\texttt{latex2e}, \texttt{latex3}, \texttt{tagpdf}, \texttt{hyperref},
+\texttt{pdfresources}, etc., help people to find information easily
+and report any issue related to the project without needing to knowing 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 tabular syntax at
+\url{https://github.com/latex3/tagging-project/discussions/1}.
+
+Your feedback is imported 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 that 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, 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 can not 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 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 and to put
+a different plug in, 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{NewSocketPug}\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 it (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 \LaTeX{}
+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}.
-\emph{write}
-For documentation see \texttt{texdoc ltsockets-doc} for now.
\section{Extended cross-referencing of document properties}
@@ -180,11 +310,12 @@ number the following declaration could be used:
\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
+(\enquote{now}) and not at \cs{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}:
\begin{verbatim}
-\RecordProperties{mylabel}{chapter,page,currentlabel}
+\RecordProperties{mylabel}
+ {chapter,page,currentlabel}
\end{verbatim}
To reference the value the \cs{RefProperty} command is provided which takes
two arguments, the label and the property:
@@ -193,31 +324,35 @@ two arguments, the label and the property:
\end{verbatim}
The new module predeclares a set of generally useful properties:
-\texttt{currentlabel} (the standard counter representation), \texttt{page}
+\texttt{label} (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}.
+\pkg{nameref}), \texttt{target} (the name of the link target if set,
+e.g., by \pkg{hyperref}), \texttt{pagetarget} (the name of target
+added each page 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.
+The module provides both \LaTeXe{} camel case commands and \LaTeX{} programming layer commands.
For documentation see \texttt{texdoc ltproperties-doc}.
\section{New or improved commands}
-\section{Testing for \pkg{expl3} version: \cs{IfExplAtLeastTF}}
-
-The integration of \pkg{expl3} into the kernel means that programmers can use
-all of the features available without needing to load explicitly. However, as
-\pkg{expl3} is not a separate package, the version can't be tested using
-\cs{IfPackageAtLeastTF}. To date, low-level methods have therefore been needed
-to check for the availablity of features in \pkg{expl3}. We have now added
-\cs{IfExplAtLeastTF} as a test working in the same way as
-\cs{IfPackageAtLeastTF} but focussed 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
+\subsection{Testing for the \LaTeX{} programming layer version: \cs{IfExplAtLeastTF}}
+
+The integration of \pkg{expl3} into the kernel (the \LaTeX{}
+programming layer) means that programmers can use all of the features
+available without needing to load explicitly. However, as \pkg{expl3}
+is not a separate package, the version can't 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 focussed 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}
@@ -226,16 +361,6 @@ just after the line which identifies the format (\texttt{LaTeX2e}, etc.).
%
\githubissue{1004}
-\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.
\section{Code improvements}
@@ -253,6 +378,8 @@ behavior can be adjusted if required to be different from that of spaces.
%
\githubissue{1085}
+
+
\subsection{In the programming layer}
In the programming layer (\pkg{expl3}), we have revised the behavior of the
@@ -266,12 +393,11 @@ 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}
-\documentclass{article}
-\begin{document}
\ExplSyntaxOn
\fp_new_variable:n{duck}
\fp_new_function:n{dinner}
-\fp_set_function:nnn{dinner}{duck}{duck - 0.25 * duck}
+\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)}
@@ -283,29 +409,80 @@ $\fp_eval:n{duck}
>\fp_eval:n{dinner(duck)}
$
\ExplSyntaxOff
-\end{document}
\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 to the
document level: this will be examined based on feedback on the
utility of the programming layer change.
-\section{Bug fixes}
-\section{Changes to packages in the \pkg{amsmath} category}
+\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.
+
+% \section{Bug fixes}
+
+%\section{Changes to packages in the \pkg{amsmath} category}
-\section{Changes to packages in the \pkg{graphics} category}
+%\section{Changes to packages in the \pkg{graphics} category}
-\section{Changes to packages in the \pkg{tools} category}
+%\section{Changes to packages in the \pkg{tools} category}
%\medskip
\begin{thebibliography}{9}
-\fontsize{9.3}{11.3}\selectfont
+%\fontsize{9.3}{11.3}\selectfont
+
+
+\bibitem{38:Lamport}
+Leslie Lamport.
+\newblock {\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}
More information about the latex3-commits
mailing list.