[latex3-commits] [latex3/latex2e] latexlab/rcb: more docu (c7126d0d)
github at latex-project.org
github at latex-project.org
Sun Jul 23 00:18:46 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : latexlab/rcb
Link : https://github.com/latex3/latex2e/commit/c7126d0d7ee05db0730b3a9df4310c162fcab1dc
>---------------------------------------------------------------
commit c7126d0d7ee05db0730b3a9df4310c162fcab1dc
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Sun Jul 23 00:18:46 2023 +0200
more docu
>---------------------------------------------------------------
c7126d0d7ee05db0730b3a9df4310c162fcab1dc
required/latex-lab/latex-lab-footnotes.dtx | 223 +++++++++++++----------------
1 file changed, 97 insertions(+), 126 deletions(-)
diff --git a/required/latex-lab/latex-lab-footnotes.dtx b/required/latex-lab/latex-lab-footnotes.dtx
index 0dd74dc6..0d816dad 100644
--- a/required/latex-lab/latex-lab-footnotes.dtx
+++ b/required/latex-lab/latex-lab-footnotes.dtx
@@ -38,12 +38,12 @@
% \newcommand\NEW[1]{\marginpar{\mbox{}\hfill\fbox{New: #1}}}
% \providecommand\class[1]{\texttt{#1.cls}}
% \providecommand\pkg[1]{\texttt{#1}}
-% \providecommand\hook[1]{\texttt{#1}}
+% \providecommand\hook[1]{\texttt{#1}}9
% \providecommand\socket[1]{\texttt{#1}}
% \providecommand\plug[1]{\texttt{#1}}
%
-% \NewDocElement[printtype=socket]{Socket}{socketdecl}
-% \NewDocElement{Plug}{plugdecl}
+% \NewDocElement[printtype=\textit{socket},idxtype=socket,idxgroup=Sockets]{Socket}{socketdecl}
+% \NewDocElement[printtype=\textit{hook},idxtype=hook,idxgroup=Hooks]{Hook}{hookdecl}
%
% \begin{abstract}
% \emph{to be written}
@@ -61,7 +61,7 @@
% some adjustments are mutually exclusive). This is achieved by
% providing a larger number of hooks (for areas where different
% packages/classes can easily coexist with their adjustments) and a
-% number of configuration points to which only one class or package
+% number of sockets to which only one class or package
% can write to successfully (in case of multiple changes the
% last one wins). The latter are for special functionality, e.g.,
% if footnote text is typeset as a single paragraph, it can't be configured
@@ -140,7 +140,7 @@
% formatting of marks.
%
%
-% \subsubsection{Hooks}
+% \subsubsection{Hooks for formatting the footnote mark in text}
%
% The hooks to customize the marks in the text are the following:
% \begin{description}
@@ -221,10 +221,10 @@
%
% This socket receives all material that is to be processed (or
% stored) including color protection code and what have you.
+% The \plug{default} executes \cs{insert}\cs{footins}.
%
-% Available plugs are \plug{default}, \plug{side}, and \plug{mp}.
+% Available plugs are \plug{default}, \plug{side} (side notes), and \plug{mp} (minipage).
%
-% The \plug{default} executes \cs{insert}\cs{footins}.
%
% \item[\socket{@footnotetext/make} (1 argument)]
%
@@ -321,7 +321,7 @@
%
%
%
-% \subsubsection{Hooks}
+% \subsubsection{Hooks for formatting the footnote text}
%
% \begin{description}
% \item[\hook{fntext/before}]
@@ -602,16 +602,17 @@
% by the mark commands) and one for the structure number of the footnotetest itself
% (used as target by \cs{footref}s commands).
%
-% \subsection{Implementation details}
+% \subsection{Implementation details regarding tagging}
%
% \subsection{Handling the mark}
%
-% The mark in the text is handled by redefining the kernel configuration point
-% \cs{@kernel at process@makefnmark} to \cs{tag at FEMark}.
-% It takes one argument, \cs{@makefnmark}, the command which formats the
-% mark, and surrounds it by link and tagging commands.
-% At the point where \cs{@kernel at process@makefnmark} is issued \cs{@thefnmark} has already been
-% defined and can be used to setup the reference detections.
+% The mark in the text is handled by redefining the kernel
+% hook \cs{@kernel at process@makefnmark} to
+% \cs{tag at FEMark}. It takes one argument, \cs{@makefnmark}, the
+% command which formats the mark, and surrounds it by link and tagging
+% commands. At the point where \cs{@kernel at process@makefnmark} is
+% issued \cs{@thefnmark} has already been defined and can be used to
+% setup the reference detections.
%
%
% \subsection{Handling the footnotetext}
@@ -623,9 +624,10 @@
% attempt to detect to which mark the note is related.
%
% The actual typesetting of the note text is done by
-% \cs{@makefntext}/\cs{fnote_makefntext:n}. In the new implementation
-% this contains two configuration points, \cs{@makefntext at cfgpoint}
-% and \cs{@makefntext at cfgpointii}. These are redefined to add the
+% \cs{fnote_makefntext:n} (or its \LaTeXe{} name \cs{@makefntext}). In
+% the new implementation this contains two kernel hooks for tagging:
+% \cs{@kernel at process@makefntext at mark} and
+% \cs{@kernel at process@makefntext at text}. These are redefined to add the
% tagging commands around note mark and note text.
%
% \subsection{Footnotes in minipages}
@@ -662,9 +664,6 @@
%
% \item manyfoot doesn't work correctly and must be analyzed.
%
-% \item Check if additional kernel configuration points are needed/possible
-% to avoid the redefinitions of \cs{@makefntext at cfgpoint} and \cs{@makefntext at cfgpointii}.
-%
% \item \pkg{memoir} is not supported at all and errors when the code tries to patch
% \cs{@makefntext}.
% \end{itemize}
@@ -897,14 +896,20 @@
%
% \subsection{Hooks}
%
-% Hooks in the footnotemark command.
+% \begin{hookdecl}{fnmark/before,fnmark/after,
+% fnmark/begin,fnmark/end}
+% Hooks in the footnotemark command.
% \begin{macrocode}
\NewMirroredHookPair{fnmark/before}{fnmark/after}
\NewHook{fnmark}
\NewHook{fnmark/begin}
\NewHook{fnmark/end}
% \end{macrocode}
-% Hooks in the footnotetext command
+% \end{hookdecl}
+%
+% \begin{hookdecl}{fntext/before,fntext/after,
+% fntext/begin,fntext/end,fntext/para}
+% Hooks in the footnotetext command:
% \begin{macrocode}
\NewMirroredHookPair{fntext/before}{fntext/after}
\NewHook{fntext}
@@ -912,6 +917,7 @@
\NewHook{fntext/begin}
\NewHook{fntext/end}
% \end{macrocode}
+% \end{hookdecl}
%
% \subsection{Debugging code}
% the debugging code is just temporary
@@ -995,12 +1001,16 @@
% hyperref.sty
\UseHook{fnmark/begin}
%-------
+% \end{macrocode}
+% The kernel hook for tagging. It picks up \cs{@makefnmark} as its
+% argument if tagging is active.
+% \begin{macrocode}
\@kernel at process@makefnmark \@makefnmark
%-------
% \end{macrocode}
% If a footnote mark is placed by its own then it should finish by
-% executing \hook{fnmark/end}, resetting the space factor, and
-% finishing with \hook{fnmark/after}. However, in a complete
+% executing the hook \hook{fnmark/end}, resetting the space factor, and
+% finishing with the hook \hook{fnmark/after}. However, in a complete
% footnote these actions have to happen only after we have handled
% the footnote text (e.g., by placing it into an \cs{insert}). In
% such a situation \cs{_@@_footmark_finish:} below does nothing
@@ -1035,14 +1045,16 @@
% \end{macro}
%
% \begin{macro}{\@kernel at process@makefnmark}
-% Not a public config point but the kernel hook to add tagging
+% Not a public config point but the kernel hook to add tagging. By
+% default it does nothing and is redefined if tagging is active.
% \begin{macrocode}
\cs_new_protected:Npn \@kernel at process@makefnmark { }
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@footnotemark}
-% At last provide the name \LaTeXe{} is used to.
+% Here we provide the traditional \LaTeXe{} name in case it is used
+% in some legacy class.
% \begin{macrocode}
\cs_set_eq:NN \@footnotemark \fnote_footnotemark:
% \end{macrocode}
@@ -1060,8 +1072,15 @@
% ./linguex/linguex.sty
\UseHook{fntext/before}
%-------
+% \end{macrocode}
+% Execute a kernel hook for tagging.
+% \begin{macrocode}
\@kernel at process@footnotetext at begin
- \UseSocket{@footnotetext/process} { % config point
+% \end{macrocode}
+%
+% \begin{macrocode}
+ \UseSocket{@footnotetext/process}
+ {
%-------
% resetting baselinestretch ... (could be done further down)
% ./uafthesis/uafthesis.cls
@@ -1133,6 +1152,10 @@
\color at endgroup
}
%-------
+% \end{macrocode}
+% The corresponding kernel hook that ends the tagging structure if
+% tagging is active.
+% \begin{macrocode}
\@kernel at process@footnotetext at end
%-------
% ./linguex/linguex.sty
@@ -1227,9 +1250,9 @@
% \end{macro}
%
% Provide the name \LaTeXe{} is used to and do this unconditionally
-% (no patching of class code if any). This means that if a class provides it own
-% definition that gets lost and if necessary needs to be handled
-% with firstaid (or updating of the class).
+% (no patching of class code if any). This means that if a class
+% provides it own definition that gets lost and if necessary needs to
+% be handled with firstaid (or updating of the class).
% \begin{macrocode}
\AddToHook{begindocument}
{
@@ -1237,6 +1260,9 @@
}
% \end{macrocode}
%
+%
+%
+%
% \subsection{The new \cs{@makefntext} command}
%
% \cs{footnotemargin} is the logic implemented by footmisc. Perhaps we
@@ -1253,62 +1279,10 @@
\fi
}
% \end{macrocode}
-
-
-% stuff to sort out ...
-% \begin{macrocode}
-\def\@kernel at makefntext@mark at before {
- \tag_mc_end_push:
-% \end{macrocode}
-% We create a link target for every related mark. The name is footnote* + structure number
-% of the mark. We also add a link target for the current structure (for footref)
-% \begin{macrocode}
- %\seq_show:N\l_@@_currentrefs_seq
- \seq_map_inline:Nn\l_@@_currentrefs_seq {\MakeLinkTarget*{footnote*.##1}}
- \MakeLinkTarget*{footnote*.\l_@@_currentstruct_tl}
-% \end{macrocode}
-% now we add the tagging commands. We move the structure of the label to
-% to the container at the begin of the note.
-% \begin{NOTE}{UF}
-% check if the NonStruct is really needed. Perhaps we can simply move the mc.
-% \end{NOTE}
-% \begin{macrocode}
- \tag_struct_begin:n { tag=NonStruct,parent=\l_@@_currentstruct_tl +1 }
- \tag_mc_begin:n { tag=Lbl }
-}
-
-
-\def \@kernel at makefntext@mark at after {
- \tag_mc_end:
- \tag_struct_end:
- \tag_mc_begin_pop:n{} % <--- unnecessary if followed by next
- % kernel hook
-}
-
-\def \@kernel at makefntext@text at before {
- \tag_mc_end_push: % <--- unnecessary
- \tag_mc_begin:n{}
-}
-
-\def \@kernel at makefntext@text at after {
- \tag_mc_end:
- \tag_mc_begin_pop:n{}
-}
-
-\long\def \@kernel at process@makefntext at mark #1 {
- \@kernel at makefntext@mark at before
- #1
- \@kernel at makefntext@mark at after
-}
-
-\long\def \@kernel at process@makefntext at text #1 {
- \@kernel at makefntext@text at before
- #1
- \@kernel at makefntext@text at after
-}
-% \end{macrocode}
-
-
+%
+%
+%
+%
% \begin{macro}{\fnote_makefntext:n}
% \begin{macrocode}
\cs_new_protected:Npn \fnote_makefntext:n #1 {
@@ -1319,28 +1293,23 @@
% not provide a further hook at this point.
% \begin{macrocode}
\noindent
-%
-% \@kernel at makefntext@mark at before
-% \UseSocket{@makefntext/mark}
-% \@kernel at makefntext@mark at after
-% \@kernel at makefntext@text at before
-% \UseSocket{@makefntext/text}{#1}
-% \@kernel at makefntext@text at after
-%
% \end{macrocode}
-% or perhaps better
-% \begin{macrocode}
%
+% \begin{macrocode}
\@kernel at process@makefntext at mark { \UseSocket{@makefntext/mark} }
\@kernel at process@makefntext at text { \UseSocket{@makefntext/text}{#1} }
}
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\@makefntext at cfgpoint}
-% default for config point (1 arg)
+% \begin{socketdecl}{@makefntext/mark}
+% A socket to typeset the mark at the start of a footnote.
% \begin{macrocode}
\NewSocket {@makefntext/mark}{0}
+% \end{macrocode}
+% The \plug{default} plug implements the logic introduced with the
+% \pkg{footmisc} package.
+% \begin{macrocode}
\NewSocketPlug{@makefntext/mark}{default}{
\ifdim\footnotemargin>\z@
\hb at xt@ \footnotemargin{\hss\@makefnmark}
@@ -1356,27 +1325,31 @@
\fi
\fi
}
-
+% \end{macrocode}
+%
+% \begin{macrocode}
\AssignSocketPlug{@makefntext/mark}{default}
% \end{macrocode}
-% \end{macro}
+% \end{socketdecl}
%
-% \begin{macro}{\@makefntext at cfgpointii}
-% default for config point (1 arg)
+% \begin{socketdecl}{@makefntext/text}
+% By default this socket does nothing special and simply processes
+% its argument as provided.
% \begin{macrocode}
-%\cs_new_protected:Npn \@makefntext at cfgpointii #1 { #1 }
\NewSocket {@makefntext/text}{1}
\NewSocketPlug{@makefntext/text}{default}{ #1 }
-
\AssignSocketPlug{@makefntext/text}{default}
% \end{macrocode}
-% \end{macro}
+% \end{socketdecl}
+%
+%
+%
%
% \subsubsection{Making documents use the new \cs{@makefntext}}
%
% If the definition for \cs{@makefntext} is that of the standard
% classes then replace it with \cs{fnote_makefntext:n}, otherwise
-% try to patch the definition.
+% try to patch the definition used in the class.
%
% Here is the definition the way it is in
% \texttt{classes.dtx}. Notice that (for saving space) there is no
@@ -1938,48 +1911,47 @@
\tag_mc_begin_pop:n{}
}
% \end{macrocode}
-% At last set the kernel commands
+% At last set the kernel commands:
% \begin{macrocode}
\cs_set_eq:NN \@kernel at process@footnotetext at begin \tag at FENote@begin
\cs_set_eq:NN \@kernel at process@footnotetext at end \tag at FENote@end
% \end{macrocode}
%
-% \cs{@makefntext at cfgpoint} is the configuration point responsible for
-% typesetting the mark in the note. We use it to surround
+% The kernel hook \cs{@kernel at process@makefntext at mark} is responsible for
+% tagging the mark in the note. We use it to surround
% the mark with the needed tagging commands.
%
-% TODO check if this should/can be kernel configuration points
-% or if an additional kernel configuration points are needed.
+% TODO check if additional kernel configuration points are needed.
% If yes, what about the paragraph start and the paratagging??
%
% \begin{macrocode}
-\cs_set_protected:Npn \@makefntext at cfgpoint #1 %#1 code that typesets the mark.
+\cs_set_protected:Npn \@kernel at process@makefntext at mark #1 %#1 code that typesets the mark.
{
- \noindent
\tag_mc_end_push:
\tag at FENoteLbl { #1 }
\tag_mc_begin_pop:n{}
}
% \end{macrocode}
-% \cs{tag at FENoteLbl} creates the label in the note on the bottom.
-% It also adds link targets for the hyperlinking.
%
% \begin{macro}{\tag at FENoteLbl}
+% \cs{tag at FENoteLbl} creates the label in the note on the bottom.
+% It also adds link targets for the hyperlinking.
% \begin{macrocode}
\cs_new_protected:Npn \tag at FENoteLbl #1
{
% \end{macrocode}
-% We create a link target for every related mark. The name is footnote* + structure number
-% of the mark. We also add a link target for the current structure (for footref)
+% We create a link target for every related mark. The name is
+% \texttt{footnote*} \meta{structure number of the mark}. We also add a link
+% target for the current structure (for \cs{footref}).
% \begin{macrocode}
%\seq_show:N\l_@@_currentrefs_seq
\seq_map_inline:Nn\l_@@_currentrefs_seq {\MakeLinkTarget*{footnote*.##1}}
\MakeLinkTarget*{footnote*.\l_@@_currentstruct_tl}
% \end{macrocode}
-% now we add the tagging commands. We move the structure of the label to
-% to the container at the begin of the note.
+% Now we add the tagging commands. We move the structure of the label to
+% to the container at the begin of the note.
% \begin{NOTE}{UF}
-% check if the NonStruct is really needed. Perhaps we can simply move the mc.
+% Check if the NonStruct is really needed. Perhaps we can simply move the mc.
% \end{NOTE}
% \begin{macrocode}
\tag_struct_begin:n { tag=NonStruct,parent=\l_@@_currentstruct_tl +1 }
@@ -1992,18 +1964,17 @@
% \end{macro}
%
%
-% \cs{@makefntext at cfgpointii} is the
-% configuration point around the actual note text.
-%
-% TODO check if this should/can be kernel configuration points
+% \cs{@kernel at process@makefntext at text} is the kernel hook
+% around the actual note text.
% \begin{macrocode}
-\cs_set_protected:Npn \@makefntext at cfgpointii #1
+\cs_set_protected:Npn \@kernel at process@makefntext at text #1
{
\tag_mc_end_push:
\tag at FENotetext { #1 }
\tag_mc_begin_pop:n{}
}
% \end{macrocode}
+%
% \begin{macro}{\tag at FENotetext}
%
% This command currently only adds an MC chunk,
More information about the latex3-commits
mailing list.