diff options
Diffstat (limited to 'macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx')
-rw-r--r-- | macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx | 341 |
1 files changed, 274 insertions, 67 deletions
diff --git a/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx b/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx index 74d56d687f..d2011256b1 100644 --- a/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx +++ b/macros/latex-dev/required/latex-lab/latex-lab-new-or-2.dtx @@ -1,7 +1,7 @@ % \iffalse meta-comment % %% File: latex-lab-new-or-2.dtx -% Copyright (C) 2022 The LaTeX Project +% Copyright (C) 2022-2023 The LaTeX Project % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -17,6 +17,9 @@ % % for those people who are interested or want to report an issue. % +\def\ltlabneworIIdate{2023-09-04} +\def\ltlabneworIIversion{0.85c} + %<*driver> \documentclass{l3doc} \EnableCrossrefs @@ -31,41 +34,58 @@ % % \title{The \texttt{latex-lab-testphase-new-or-2} code\thanks{}} % \author{Frank Mittelbach, \LaTeX{} Project} -% +% % \date{v\ltlabneworIIversion\ \ltlabneworIIdate} % \maketitle % % \newcommand\fmi[1]{\begin{quote} TODO: \itshape #1\end{quote}} % \newcommand\NEW[1]{\marginpar{\mbox{}\hfill\fbox{New: #1}}} % \providecommand\pkg[1]{\texttt{#1}} % +% \providecommand\hook[1]{\texttt{#1\DescribeHook[noprint]{#1}}} +% \providecommand\socket[1]{\texttt{#1\DescribeSocket[noprint]{#1}}} +% \providecommand\plug[1]{\texttt{#1\DescribePlug[noprint]{#1}}} +% +% \NewDocElement[printtype=\textit{socket},idxtype=socket,idxgroup=Sockets]{Socket}{socketdecl} +% \NewDocElement[printtype=\textit{plug},idxtype=plug,idxgroup=Plugs]{Plug}{plugdecl} +% \NewDocElement[printtype=\textit{hook},idxtype=hook,idxgroup=Hooks]{Hook}{hookdecl} +% +% % \begin{abstract} +% This code implements changes to the output routine intended to be +% moved in the \LaTeX{} kernel at some point in the future. % \end{abstract} % -% \section{Introduction} -% -% This code implements changes to the output routine. % % % +% \section{Introduction} % -% \section{Hooks and configuration points} % -% Note: the configuration points do not have an interface mechanism -% yet and all their names are temporary right now. +% \section{Hooks and replaceable code blocks} % % -% \subsubsection{Configuration points} +% \subsubsection{Replaceable code blocks (sockets)} % % To cater for different layouts with respect to text, footnotes, -% and bottom-floats placements there are two configuration points for +% and bottom-floats placements there are two sockets for % now. % \begin{description} -% \item[\cs{@makecol@cfgpoint} (0 arguments)] +% \item[\socket{@makecol/outputbox} (0 arguments)] % -% In this configuration point the \cs{@outputbox} (holding the +% In code for this socket the \cs{@outputbox} (holding the % galley text for the current column or page) is augmented by % attaching floats and footnote areas together with appropriate -% spacing. Before the code is run any existing glue at the bottom +% spacing. +% +% Prior to calling the socket the output routine has already +% decided which floats go into which area and which get deferred. +% Therefore, the assumption is that the code in the socket attaches all +% areas that contain floats. If this is not done, then the order +% of floats is likely to be screwed up unless unused floats +% are moved to the defer list in an appropriate way (for now we +% don't offer any interface for that scenario). +% +% Before the code in the socket is run, any existing glue at the bottom % of the \cs{@outputbox} is removed and stored in a safe % place. If needed, it can be reinserted with one of the helper % commands. @@ -74,17 +94,25 @@ % \begin{description} % \item[\cs{@outputbox@append} (1 argument)] % +% \DescribeMacro[noprint]{@outputbox@append} +% % This general purpose command alters the \cs{@outputbox} box by % appending material to it. % % \item[\cs{@outputbox@appendfootnotes} (0 arguments)] % +% \DescribeMacro[noprint]{@outputbox@appendfootnotes} +% % This command appends the footnotes to the \cs{@outputbox} (if % there are any). If not, then it does nothing. % % \item[\cs{@outputbox@attachfloats} (0 arguments)] % \item[\cs{@outputbox@attachtopfloats} (0 arguments)] % \item[\cs{@outputbox@attachbottomfloats} (0 arguments)] +% +% \DescribeMacro[noprint]{@outputbox@attachfloats} +% \DescribeMacro[noprint]{@outputbox@attachtopfloats} +% \DescribeMacro[noprint]{@outputbox@attachbottomfloats} % % Attaching top and bottom floats can usually be done in one % go, but for special layouts we might want more control so we @@ -92,11 +120,16 @@ % % \item[\cs{@outputbox@reinsertbskip} (0 arguments)] % +% \DescribeMacro[noprint]{@outputbox@reinsertbskip} +% % Reinsert the bottom skip of the \cs{@outputbox} that was % saved before. % % \item[Testing for existence of material] % +% \DescribeMacro[noprint]{@if@footnotes@TF} +% \DescribeMacro[noprint]{@if@bfloats@TF} +% % There are a number of helpers to run conditional code % depending on whether or not there are footnotes or bottom % floats. They are \cs{@if@footnotes@TF} and @@ -104,16 +137,67 @@ % (names are likely to change). % % \end{description} -% This configuration point needs an appropriate definition; a -% default is already given in the kernel. % -% \item[\cs{@makecol@cfgpointii} (0 arguments)] +% \fmi{Decide on names for these helper commands. We could keep +% them similar to the above (because they are only supposed to be +% used by a few packages). However, we could alternatively use +% CamelCase names, under the assumption that classes may also +% directly define a plug for the socket, instead of loading a +% support package such as \pkg{footmisc} (or in addition +% to). --- decide} +% +% This socket cannot be empty but needs appropriate code; a set +% of suitable plugs for it are already given in the kernel. These +% are +% \begin{description} +% \item[\plug{space-footnotes-floats}] +% +% After the galley text there is a vertical \cs{vfill} +% followed by any footnotes followed by the bottom floats, if any. +% +% \item[\plug{floats-footnotes-space}] +% +% As before but the \cs{vfill} is at the bottom (page is +% ragged bottom). +% +% \item[\plug{footnotes-space-floats}] +% +% As before but the \cs{vfill} is between footnotes and floats. % -% This configuration point is used to manipulate the footnote +% \item[\plug{space-floats-footnotes}] +% +% Here the footnotes come last.\footnote{There are two more +% permutations, but neither of them has ever been requested so +% they aren't set up by default --- doing that in a class +% would be trivial though.} +% +% \item[\plug{floats-footnotes}] +% +% All excess space has to be distributed across the existing +% glue on the page, e.g., within the text galley, the +% separation between blocks, etc. +% The order is text, floats, footnotes. +% +% \item[\plug{footnotes-floats}] +% +% As the previous one but floats and footnotes are +% swapped. This is the \LaTeX{} default, i.e., this plug is +% assigned to the socket. +% +% \end{description} +% +%----------------------- +% +% \item[\socket{@makecol/footnotes} (0 arguments)] +% +% This socket is used to manipulate the footnote % material inside \cs{box}\cs{footins}. It if contains code, it % is supposed to do some processing of that box and then write % the result back into it (and nothing else!). By default it -% does nothing. +% does nothing, i.e., has the \plug{noop} assigned. +% +% If (short) footnotes are run as a paragraph this socket gets +% the plug \plug{para} assigned which is defined elsewhere. % % \end{description} % @@ -123,28 +207,32 @@ % \section{The Implementation} % % \begin{macrocode} -%<*code> +%<*package> % \end{macrocode} % % \subsection{File declaration} % \begin{macrocode} \ProvidesPackage{latex-lab-testphase-new-or-2} - [2022-11-04 v0.1c changes to the output routine] + [\ltlabneworIIdate\space v\ltlabneworIIversion\space + Changes to the output routine] % \end{macrocode} +% % \subsection{\cs{@makecol} reimplementation} % % In order for other packages to prepend or append code to -% \cs{@makecol}, they can use the generic command hooks -% \texttt{cmd/@makecol/before} and \texttt{cmd/@makecol/after}, so -% there is nothing we need to do here. +% \cs{@makecol} the generic command hooks +% \texttt{cmd/@makecol/before} and \texttt{cmd/@makecol/after} can +% be used, so for now there is nothing we need to do for this. % % % \begin{macro}{\@makecol} % \cs{@makecol} is shortened a lot, basically all the hardwired -% code in the middle has moved into a configuration point. +% code in the middle has moved into a socket. % \begin{macrocode} \def \@makecol {% - \@kernel@before@cclv +% \end{macrocode} +% Save away box 255 as \cs{@outputbox} to make it available for further adjustments. +% \begin{macrocode} \setbox\@outputbox \box\@cclv % \end{macrocode} % The only real addition is the next command which either does @@ -153,25 +241,31 @@ % \begin{macrocode} \@outputbox@removebskip % \end{macrocode} -% Any ``here'' floats in the \cs{@outputbox} are now handled so we +% Now a kernel hook for tagging. +% \fmi{The name is likely to change and it probably will eventually +% be replaced with a socket.} +% \begin{macrocode} + \@kernel@tagsupport@@makecol +% \end{macrocode} +% When this code is run any ``here'' floats in the \cs{@outputbox} are already handled, so we % recycle their registers and put them back to the \cs{@freelist}. % \begin{macrocode} \let\@elt\relax \xdef\@freelist{\@freelist\@midlist}% \global \let \@midlist \@empty % \end{macrocode} -% Here we have the configurable part. -% \fmi{Interface to configuration points will change in the future} +% Here we have the configurable part. This socket is supposed to add floats, +% footnotes and stretchable vertical space as appropriate to the \cs{@outputbox}. % \begin{macrocode} - \@makecol@cfgpoint + \UseSocket{@makecol/outputbox}% % \end{macrocode} -% The we deal with any \cs{enlargethispage} or run the normal code +% Then we deal with any \cs{enlargethispage} or run the normal code % to build a column. % \begin{macrocode} \ifvbox\@kludgeins - \@makespecialcolbox + \@make@specialcolbox \else - \@makenormalcolbox + \@make@normalcolbox \fi \global \maxdepth \@maxdepth } @@ -188,10 +282,10 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\@makenormalcolbox} +% \begin{macro}{\@make@normalcolbox} % Taken out of \cs{@makecol} for readability. % \begin{macrocode} -\def \@makenormalcolbox {% +\def \@make@normalcolbox {% \setbox\@outputbox \vbox to\@colht {% \@texttop \@outputbox@depth \dp\@outputbox @@ -204,10 +298,10 @@ % \end{macro} % % -% \begin{macro}{\@makespecialcolbox} +% \begin{macro}{\@make@specialcolbox} % Make the colbox when \cs{enlargethispage} was used. % \begin{macrocode} -\def \@makespecialcolbox {% +\def \@make@specialcolbox {% \@outputbox@append {\vskip-\@outputbox@depth}% \@tempdima \@colht \ifdim \wd\@kludgeins>\z@ @@ -235,7 +329,7 @@ % \begin{macro}{\@outputbox@removebskip} % % This is really a bug fix for the kernel but one we only -% automatically make in new documents using \cs{DocumentMetadata}. +% automatically make in new documents that are using \cs{DocumentMetadata}. % \fmi{may make optional for legacy docs} % If % \cs{raggedbottom} is in force, footnotes get attached to the main @@ -248,7 +342,7 @@ % short, but the footnotes are not pushed to the bottom. % % In \pkg{footmisc} \cs{@outputbox@removebskip} is only applied when -% \pkg{footmisc} is called with with an option specifying the +% \pkg{footmisc} is called with an option specifying the % footnote placement, i.e., not in the default case. % In new documents we apply it always. % \begin{macrocode} @@ -270,6 +364,7 @@ \ifnum \gluestretchorder\@tempskipa>\z@ \vskip-\@tempskipa % \end{macrocode} +% % \begin{macro}{\@outputbox@reinsertbskip} % We also record the value so that it can be reinserted % elsewhere. As we have to do this globally, we also need to @@ -295,25 +390,28 @@ % % % -% \begin{macro}{\@kernel@before@cclv} -% \begin{macro}{\@kernel@before@footins} +% \begin{macro}{\@kernel@before@cclv, +% \@kernel@before@footins} % These two commands are internal kernel hooks intended for tagging -% support in case that is active. By default they do nothing (and +% support in case that is active. They should not be altered by package code! +% By default they do nothing (and % may have been defined already by \cs{DocumentMetadata}). +% \fmi{The names might change and perhaps each of them is turned +% into a socket named something like \socket{tagsupport/before/cclv} +% or similar.} % \begin{macrocode} \providecommand\@kernel@before@cclv{} \providecommand\@kernel@before@footins{} % \end{macrocode} % \end{macro} -% \end{macro} % % % % % \subsection{The output routine configuration components} % -% Here we provide the components that are used to define -% \cs{@makecol@cfgpoint}. +% Here we provide the components that are used to define code for the +% \socket{@makecol/outputbox} socket. % % % \begin{macro}{\@outputbox@append} @@ -346,7 +444,7 @@ % \begin{macro}{\@outputbox@appendfootnotes} % % This command appends the footnotes to the \cs{@outputbox} (if -% there are any). If not then it does nothing. +% there are any). If not, then it does nothing. % \begin{macrocode} \def\@outputbox@appendfootnotes {% \ifvoid\footins \else @@ -354,22 +452,34 @@ % First come two configuration points: what to do if we are in a split % footnote situation and a second one that does some manipulation % of the \cs{footins} box before it gets appended. -% \fmi{this code will get revised as part of CP handling in the future} +% \fmi{The code for handling split footnotes will get revised as part of socket handling in the future} % \begin{macrocode} \@makecol@handlesplitfootnotes - \@makecol@cfgpointii +% \end{macrocode} +% +% \begin{macrocode} + \UseSocket{@makecol/footnotes}% % \end{macrocode} % Then the footnotes are appended: % \begin{macrocode} \@outputbox@append{% \vskip \skip\footins +% \end{macrocode} +% This is a kernel hook for tagging. +% \fmi{The name is likely to change and it probably will eventually +% be replaced with a socket.} +% \begin{macrocode} \@kernel@before@footins +% \end{macrocode} +% +% \begin{macrocode} \color@begingroup \normalcolor \footnoterule % \end{macrocode} % Support for \pkg{pdfcolfoot}, eventually this can go once color -% is properly supported. +% is properly supported. The csname is constructed in case it +% doesn't exist. % \begin{macrocode} \csname pdfcolfoot@current\endcsname \unvbox \footins @@ -435,17 +545,16 @@ % % % -% \begin{macro}{\@makecol@cfgpointii} +% \begin{socketdecl}{@makecol/footnote} % -% Configuration point to support manipulation of footins box -% (result needs to be moved back in there). Used by the -% \texttt{para} option. -% \fmi{Interface will change in the future} +% The socket allowing the manipulation of \cs{footins} box +% (result needs to be moved back in there). Used when footnotes are +% reformatted into a single paragraph by the +% \texttt{para} option of \pkg{footmisc}. By default it does nothing. % \begin{macrocode} -\let \@makecol@cfgpointii \@empty +\NewSocket{@makecol/footnotes}{0} % \end{macrocode} -% -% \end{macro} +% \end{socketdecl} % % % @@ -497,27 +606,124 @@ % \subsection{The \cs{@makecol} configuration} % % -% \begin{macro}{\@makecol@cfgpoint} +% \begin{socketdecl}{@makecol/outputbox} +% We have one socket that is supposed to augment the \cs{@outputbox} +% by attaching floats and footnotes with appropriate spacing. +% +% \begin{macrocode} +\NewSocket{@makecol/outputbox}{0} +% \end{macrocode} +% \end{socketdecl} +% +% The following plugs are available for +% this socket: +% +% \begin{plugdecl}{space-footnotes-floats} +% After the galley text there is a vertical \cs{vfill} followed by +% any footnotes followed by the bottom floats, if any. +% \begin{macrocode} +\NewSocketPlug {@makecol/outputbox}{space-footnotes-floats} {% + \@if@footnotes@TF + {\@outputbox@append{\vfill}}% + {\@if@bfloats@TF + {\@outputbox@append{\vfill}}% + {\@outputbox@reinsertbskip}% + }% + \@outputbox@appendfootnotes + \@outputbox@attachfloats +} +% \end{macrocode} +% \end{plugdecl} % -% Here is only the configuration for the default case for now, -% others are provided by \pkg{footmisc}. +% \begin{plugdecl}{floats-footnotes-space} +% As before but the \cs{vfill} is at the bottom (page is ragged +% bottom). +% \begin{macrocode} +\NewSocketPlug {@makecol/outputbox}{floats-footnotes-space} {% + \@outputbox@attachfloats + \@if@footnotes@TF + {\@outputbox@append{\vfill}}% + {\@outputbox@reinsertbskip}% + \@outputbox@appendfootnotes +} +% \end{macrocode} +% \end{plugdecl} % +% \begin{plugdecl}{footnotes-space-floats} +% As before but the \cs{vfill} is between footnotes and floats. % \begin{macrocode} - \def\@makecol@cfgpoint {% - \@outputbox@appendfootnotes - \@outputbox@attachfloats +\NewSocketPlug {@makecol/outputbox}{footnotes-space-floats} {% + \@outputbox@appendfootnotes + \@if@bfloats@TF + {\@outputbox@append{\vfill}}% + {\@outputbox@reinsertbskip}% + \@outputbox@attachfloats +} % \end{macrocode} -% We do, however, reinsert the bottom skip from \cs{newpage} if it +% \end{plugdecl} +% +% \begin{plugdecl}{space-floats-footnotes} +% Here the footnotes come last.\footnote{There are two more +% permutations, but neither of them has ever been requested so +% they aren't set up by default --- doing that in a class +% would be trivial though.} +% \begin{macrocode} +\NewSocketPlug {@makecol/outputbox}{space-floats-footnotes} {% + \@if@footnotes@TF + {\@outputbox@append{\vfill}}% + {\@if@bfloats@TF + {\@outputbox@append{\vfill}}% + {\@outputbox@reinsertbskip}}% + \@outputbox@attachfloats + \@outputbox@appendfootnotes +} +% \end{macrocode} +% \end{plugdecl} +% +% +% +% \begin{plugdecl}{floats-footnotes} +% All excess space has to be distributed across the existing +% glue on the page, e.g., within the text galley, the +% separation between blocks, etc. +% The order is text, floats, footnotes. +% \begin{macrocode} +\NewSocketPlug {@makecol/outputbox}{floats-footnotes} {% + \@outputbox@attachfloats + \@outputbox@appendfootnotes +% \end{macrocode} +% We do reinsert the bottom skip from \cs{newpage} if it % was taken out earlier. This is, strictly speaking, not necessary % in most cases, but it is a \cs{vfil} while \cs{raggedbottom} is % only generating \verb=\vspace{0pt plus .0001fil}=, so if you have % several \cs{vfil} on the page before the \cs{newpage} you would % alter the space distribution if one is taken out. % \begin{macrocode} - \@outputbox@reinsertbskip - } + \@outputbox@reinsertbskip +} % \end{macrocode} -% \end{macro} +% +% \end{plugdecl} +% +% \begin{plugdecl}{footnotes-floats} +% \begin{macrocode} +\NewSocketPlug {@makecol/outputbox}{footnotes-floats} {% + \@outputbox@appendfootnotes + \@outputbox@attachfloats + \@outputbox@reinsertbskip +} +% \end{macrocode} +% The \texttt{footnote-floats} plug is the default used by +% \LaTeX{}; it can be overwritten either through \pkg{footmisc} or +% by assigning any of the other plugs (or by coding yet another +% plug for the socket). +% \begin{macrocode} +\AssignSocketPlug {@makecol/outputbox}{footnotes-floats} +% \end{macrocode} +% \end{plugdecl} +% +% +% % % % \section {Replacement for the \pkg{footmisc} package} @@ -532,13 +738,14 @@ % % \section {Temp stuff that is related but should go to the kernel} % +% This is the code from \texttt{latex-lab-footnotes.dtx}. % \begin{macrocode} \input{latex-lab-footnotes.ltx} % \end{macrocode} % % % \begin{macrocode} -%</code> +%</package> % \end{macrocode} % % \Finale |