% \iffalse meta-comment
%
%% File: latex-lab-float.dtx (C) Copyright 2023 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
% license or (at your option) any later version. The latest version
% of this license is in the file
%
% https://www.latex-project.org/lppl.txt
%
%
% The development version of the bundle can be found below
%
% https://github.com/latex3/latex2e/required/latex-lab
%
% for those people who are interested or want to report an issue.
%
\def\ltlabfloatdate{2024-12-27}
\def\ltlabfloatversion{0.81h}
%<*driver>
\documentclass{l3doc}
\EnableCrossrefs
\CodelineIndex
\begin{document}
\DocInput{latex-lab-float.dtx}
\end{document}
%</driver>
%
% \fi
%
%
% \title{The \textsf{latex-lab-floats} package\\
% Tagging of floats }
% \author{\LaTeX{} Project\thanks{Initial implementation done by Ulrike Fischer}}
% \date{v\ltlabfloatversion\ \ltlabfloatdate}
%
% \maketitle
%
% \newcommand{\xt}[1]{\textsl{\textsf{#1}}}
% \newcommand{\TODO}[1]{\textbf{[TODO:} #1\textbf{]}}
% \newcommand{\docclass}{document class \marginpar{\raggedright document class
% customizations}}
%
% \providecommand\hook[1]{\texttt{#1}}
% \ProvideDocElement[printtype=\textit{plug},idxtype=plug,idxgroup=Plugs]{Plug}{plugdecl}
% \ProvideDocElement[printtype=\textit{socket},idxtype=socket,idxgroup=Sockets]{Socket}{socketdecl}
%
% \begin{documentation}
% \begin{abstract}
% The following code implements a first draft for the tagging of float
% environments
% \end{abstract}
%
%
% \section{Introduction}
%
% The code here handle the tagging of float environments.
%
% Figures (and tables) are in \LaTeX{} typically typeset in float environments.
% These are boxes which can \emph{float} away to special float areas on the pages,
% e.g., to the top or the bottom of a page or to special float pages.
% If the rules allow it they can also be placed in the main text stream (\enquote{here}).
% Floats can also be collected at the end of the document.
% In either case the order within each type of floats
% (e.g., figures, tables, algorithms, etc.) is preserved.
%
% A special type, called a H-float, (provided by the float package)
% is always placed in the main text stream and does not
% necessarily preserve the order with normal floats of the same type: It is basically
% a minipage with a caption.
%
% Floats typically contain a figure (or a table, etc.) and a caption,
% but more complex constructions with subfigures,
% copyright statements, sources or additional description are possible too.
%
% In the \LaTeX{} source a float is normally more or less at the place of
% the first call-out, but when preparing a document for print the code
% is sometimes moved to place floats in a more visually pleasing way.
%
% \section{Tagging}
%
% Floats (with the exception of H-floats) do not belong into the text stream, they
% are \enquote{consultation objects}: Readers must be able to choose if and when they read the float.
% Floats have captions, the PDF rules require that a \texttt{Caption} is the first or last
% structure in its parent structure.
% This poses some challenges on a good tagging.
%
% In PDF~2.0 there is the suitable \texttt{Aside} tag which hopefully will
% be handled correctly regarding the reading order once processor actually support
% PDF~2.0. But in PDF~1.7 we rolemap it to \texttt{Note} and this doesn't lead to
% a good reading order. The code therefore collects the float structures and moves
% them to a \texttt{Sect} at the end of the document or the chapter
% (H-floats once they are handled will not be moved).
%
% To fulfill the requirement that a \texttt{Caption} should be at the begin or end, we always
% move it to the begin of the structure. If a float has two captions the author
% has to insert a command which splits the float in two.
%
% Subfigures and subcaptions are currently not handled, but will be implemented
% as simple \texttt{Part} with their own \texttt{Caption}.
%
% \section{Links}
% The code disable the caption patches from hyperref. It will add an anchor at the
% begin of the float or a split. It changes caption so that a link to a caption label
% will go to the begin of the float.
%
% \section{Tools}
%
% The code add two keys for the \cs{tagtool} command
%
%
% \begin{function}{flush-floats,split-float}
% \begin{description}
% \item[flush-floats] This will flush out the collected floats sofar (currently
% table and figure. The value is a sectioning level, e.g. \texttt{section} or \texttt{chapter},
% the floats will then inserted as a \texttt{Sect} of this level (all \texttt{Sect} of smaller or equal
% level are closed). The key then starts a new container for following floats.
% If no value is given, the \texttt{Sect} is at the document level. The code automatically
% flush all open floats at the end of the document.
%
% \item[split-float] This can be used inside a float if there are two captions.
% It will only work reasonably well if the content of the float parts are in a sensible order
% and can be separated by this command. More complex setups with tabulars will need more
% thoughts.
% \end{description}
% \end{function}
%
% \section{Kernel commands}
% \begin{function}{\@current@float@struct}
% This variable holds the number of the current float structure. With tagging
% this is the structure number, without tagging a unique counter. A float
% can contain more than one float structure (e.g. if there is more than one
% caption).
% \end{function}
%
% \begin{function}{\@makecaption}
% \cs{@makecaption} is defined by the classes so we overwrite it for now
% at begin document.
% \end{function}
%
%
% \begin{macrocode}
%<@@=tag>
%<*package>
% \end{macrocode}
% \end{documentation}
% \begin{implementation}
% \section{Implementation}
% \begin{macrocode}
\ProvidesExplPackage {latex-lab-testphase-float} {\ltlabfloatdate} {\ltlabfloatversion}
{Code related to the tagging of floats}
% \end{macrocode}
% \subsection{Variables}
% We rolemap floats to Aside, and float sections to Sect.
%
% \begin{variable}{
% \g_@@_float_sect_prop,
% \g_@@_float_types_seq,
% \@current@float@struct,
% \g_@@_float_int
% }
% These variables will hold the structure number for the float container
% and the list of float types. Currently only figure and table are supported
% TODO: interface to declare new float types.
% To set the target for links we need also a unique counter.
% With tagging we could use the structure number, but
% the structure commands now are hidden inside tagging sockets
% so we use a dedicated counter.
% \begin{macrocode}
\prop_new:N \g_@@_float_sect_prop
\seq_new:N \g_@@_float_types_seq
\seq_gput_right:Nn \g_@@_float_types_seq {figure}
\seq_gput_right:Nn \g_@@_float_types_seq {table}
\tl_new:N\@current@float@struct
\int_new:N\g_@@_float_int
% \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_float_sect_bool}
% With this boolean float collection is switched on and off.
% Currently it is always on and set globally.
% TODO: think if an interface is needed.
% TODO: would a local variable make more sense?
% \begin{macrocode}
\bool_new:N \g_@@_float_sect_bool
\bool_gset_true:N \g_@@_float_sect_bool
% \end{macrocode}
% \end{variable}
%
% \begin{macro}{\@@_float_init:}
% To be able to set unique targets for links, we
% need a counter outside the tagging sockets.
% TODO: check if this command should be public or
% a socket or a hook.
% \begin{macrocode}
\cs_new_protected:Npn \@@_float_init:
{
\int_gincr:N \g_@@_float_int
\tl_set:Ne \@current@float@struct { \int_use:N \g_@@_float_int}
}
% \end{macrocode}
% \end{macro}
%
%\subsection{Moving float structures}
%
% Currently it is for all float types or none.
% Probably we will need some more options here to select some float types.
%
% \begin{macro}{\@@_float_init_collect:}
% This initializes a container structure for every float type.
% It can be used more than once in a document, this allows to have e.g.
% chapter wise containers.
% \begin{macrocode}
\cs_new_protected:Npn\@@_float_init_collect:
{
\bool_if:NT\g_@@_float_sect_bool
{
\seq_map_inline:Nn\g_@@_float_types_seq
{
\tag_struct_begin:n{tag=##1s,stash}
\prop_gput:Nne\g_@@_float_sect_prop {##1-struct}{\int_use:N\c@g__tag_struct_abs_int}
\tag_struct_end:
}
}
}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\@@_float_stop_sect:}
% This pushes out the floats. For every type is checks if there is actually
% a float of this type and then writes out the container structure.
% \begin{macrocode}
\cs_new_protected:Npn \@@_float_stop_sect:
{
\bool_if:NT\g_@@_float_sect_bool
{
\seq_map_inline:Nn\g_@@_float_types_seq
{
\prop_get:NnNT\g_@@_float_sect_prop{##1-used}\l_@@_tmpa_tl
{
\exp_args:Ne
\tag_struct_use_num:n{\prop_item:Nn\g_@@_float_sect_prop{##1-struct}}
\prop_gremove:Nn \g_@@_float_sect_prop{##1-used}
}
}
}
}
% \end{macrocode}
% \end{macro}
% \begin{macro}{flush-floats}
% This is a key for \cs{tagtool} to flush out the collected floats.
% The value allows to set to which level the create Sect contains.
% So \texttt{section} will close all previous Sect until the section level
% and create a new section.
% \begin{macrocode}
\keys_define:nn { tag / tool}
{
flush-floats .code:n =
{
\keys_set:nn {tag / tool} {sec-stop=#1}
\@@_float_stop_sect:
\@@_float_init_collect:
},
flush-float .default:n = Document
}
% \end{macrocode}
% \end{macro}
% We need at least one pair
% \begin{macrocode}
\AddToHook{begindocument/end}[latex-lab/float]
{\@@_float_init_collect:}
\AddToHook{tagpdf/finish/before}[latex-lab/float]
{\par\__tag_sec_end:n{-10}\@@_float_stop_sect:}
\DeclareHookRule{tagpdf/finish/before}{latex-lab/float}{before}{tagpdf}
% \end{macrocode}
%
% \subsection{Splitting floats}
% \begin{macro}{split-float}
% TODO: check if the target affect spacing!!
% \begin{macrocode}
\keys_define:nn { tag / tool}
{
split-float .code:n =
{
\UseTaggingSocket{float/end}
\@@_float_init:
\UseTaggingSocket{float/begin}
\MakeLinkTarget*{floatstructure.\@current@float@struct}
}
}
% \end{macrocode}
% \end{macro}
%
% \subsection{Tagging sockets}
% For now we test if the sockets are already defined
% \begin{macrocode}
\socket_if_exist:nF {tagsupport/float/begin}
{
\NewSocket{tagsupport/float/hmode/begin}{0}
\NewSocket{tagsupport/float/hmode/end}{0}
\NewSocket{tagsupport/float/begin}{0}
\NewSocket{tagsupport/float/end}{0}
}
% \end{macrocode}
%
% \begin{plugdecl}{default (tagsupport/float/hmode/begin)}
% This plug should be used if a float is called in hmode.
% In then closes the MC-chunks and starts the structure.
% \begin{macrocode}
\NewSocketPlug {tagsupport/float/hmode/begin}{default}
{
\@@_float_stop_par:
}
\AssignSocketPlug{tagsupport/float/hmode/begin}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \begin{plugdecl}{default (tagsupport/float/hmode/end)}
% This plug should be used if a float is called in hmode
% and the end of the float it then restarts the MC.
% \begin{macrocode}
\NewSocketPlug{tagsupport/float/hmode/end}{default}
{
\@@_float_start_par:
}
\AssignSocketPlug{tagsupport/float/hmode/end}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \begin{plugdecl}{default (tagsupport/float/begin)}
% \begin{macrocode}
\NewSocketPlug{tagsupport/float/begin}{default}
{
\@@_float_begin:
}
\AssignSocketPlug{tagsupport/float/begin}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \begin{plugdecl}{default (tagsupport/float/end)}
% \begin{macrocode}
\NewSocketPlug{tagsupport/float/end}{default}
{
\@@_float_end:
}
\AssignSocketPlug{tagsupport/float/end}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \begin{macro}{\@@_float_stop_par:,\@@_float_start_par:}
% if a float is in a par, we need commands to stop and restart the P-mc
% \begin{macrocode}
\cs_new_protected:Npn \@@_float_stop_par:
{
\tag_mc_end:
\bool_if:NF \g_@@_float_sect_bool
{
\tag_struct_end:
}
}
\cs_new_protected:Npn \@@_float_start_par:
{
\bool_if:NF \g_@@_float_sect_bool
{
\tag_struct_begin:n{tag=text}%
}
\tag_mc_begin:n{tag=P}
}
% \end{macrocode}
% \end{macro}
% These commands are the main commands to start and end the float tagging.
%
% \begin{macrocode}
\cs_new_protected:Npn \@@_float_begin:
{%
% \end{macrocode}
% We test if the float structure should be included directly or move to a dedicated section.
% \begin{macrocode}
\bool_if:NTF\g_@@_float_sect_bool
{
\exp_args:Ne
\tag_struct_begin:n{tag=float,parent=0\prop_item:No\g_@@_float_sect_prop{\@captype-struct}}%
\prop_gput:Nee \g_@@_float_sect_prop {\@captype-used}{true}
}
{
\tag_struct_begin:n{tag=float}
}
\tl_set:Ne\@current@float@struct{\tag_get:n{struct_num}}%
\typeout{Float structure: \@current@float@struct}
}
\cs_new_protected:Npn\@@_float_end:{\tag_struct_end:} %end Aside
% \end{macrocode}
% \subsection{Patching}
% This patches the main command \cs{@xfloat}.
% There is a : in the code, so we disable expl3 syntax
% \begin{macrocode}
\ExplSyntaxOff
\def\@xfloat #1[#2]{%
\@nodocument
\def \@captype {#1}%
\def \@fps {#2}%
\@onelevel@sanitize \@fps
\def \reserved@b {!}%
\ifx \reserved@b \@fps
\@fpsadddefault
\else
\ifx \@fps \@empty
\@fpsadddefault
\fi
\fi
\ifhmode
\@bsphack
% \end{macrocode}
% If the float is in hmode we have to interrupt the P
% \begin{macrocode}
\UseTaggingSocket{float/hmode/begin}%
\@floatpenalty -\@Mii
\else
\@floatpenalty-\@Miii
\fi
\ifinner
\@parmoderr\@floatpenalty\z@
\else
\@next\@currbox\@freelist
{%
\@tempcnta \sixt@@@@n
\expandafter \@tfor \expandafter \reserved@a
\expandafter :\expandafter =\@fps
\do
{%
\if \reserved@a h%
\ifodd \@tempcnta
\else
\advance \@tempcnta \@ne
\fi
\else\if \reserved@a t%
\@setfpsbit \tw@
\else\if \reserved@a b%
\@setfpsbit 4%
\else\if \reserved@a p%
\@setfpsbit 8%
\else\if \reserved@a !%
\ifnum \@tempcnta>15
\advance\@tempcnta -\sixt@@@@n\relax
\fi
\else
\@latex@error{Unknown float option `\reserved@a'}%
{Option `\reserved@a' ignored and `p' used.}%
\@setfpsbit 8%
\fi\fi\fi\fi\fi
}%
\@tempcntb \csname ftype@\@captype \endcsname
\multiply \@tempcntb \@xxxii
\advance \@tempcnta \@tempcntb
\global \count\@currbox \@tempcnta
}%
\@fltovf
\fi
% \end{macrocode}
% This starts the structure for the float.
% \begin{macrocode}
\csname @@_float_init:\endcsname
\UseTaggingSocket{float/begin}%
\global \setbox\@currbox
\color@vbox
\normalcolor
\vbox \bgroup
\hsize\columnwidth
\@parboxrestore
\@floatboxreset
% \end{macrocode}
% We add a target for links. TODO: check that it doesn't affect spacing!!
% \begin{macrocode}
\MakeLinkTarget*{\@captype.struct.\@current@float@struct}%
}%
% \end{macrocode}
% The end code of the float ...
% \begin{macrocode}
\def\end@float{%
\@endfloatbox
\UseTaggingSocket{float/end}%
\ifnum\@floatpenalty <\z@
\@largefloatcheck
\@cons\@currlist\@currbox
\ifnum\@floatpenalty <-\@Mii
\penalty -\@Miv
\@tempdima\prevdepth
\vbox{}%
\prevdepth\@tempdima
\penalty\@floatpenalty
\else
\vadjust{\penalty -\@Miv \vbox{}\penalty\@floatpenalty}\@Esphack
\UseTaggingSocket{float/hmode/end}%
\fi
\fi
}
% \end{macrocode}
% and similar for double floats:
% \begin{macrocode}
\def\end@dblfloat{%
\if@twocolumn
\@endfloatbox
\UseTaggingSocket{float/end}%
\ifnum\@floatpenalty <\z@
\@largefloatcheck
\global\dp\@currbox1sp %
\@cons\@currlist\@currbox
\ifnum\@floatpenalty <-\@Mii
\penalty -\@Miv
\@tempdima\prevdepth
\vbox{}%
\prevdepth\@tempdima
\penalty\@floatpenalty
\else
\vadjust{\penalty -\@Miv \vbox{}\penalty\@floatpenalty}\@Esphack
\UseTaggingSocket{float/hmode/end}%
\fi
\fi
\else
\end@float
\fi
}%
\ExplSyntaxOn
% \end{macrocode}
%
% \subsection{Handling captions}
%
% To avoid that hyperref interferes we disable its patches:
% \begin{macrocode}
\def\hyper@nopatch@caption{}
% \end{macrocode}
%
% \subsubsection{(Tagging) sockets}
%
% First some temporary sockets.
% These sockets are in lttagging.
% \begin{macrocode}
\socket_if_exist:nF {tagsupport/caption/begin}
{
\NewSocket{tagsupport/caption/begin}{1}
\NewSocket{tagsupport/caption/end}{0}
\NewSocket{tagsupport/caption/label/begin}{0}
\NewSocket{tagsupport/caption/label/end}{0}
}
% \end{macrocode}
% These socket are currently defined in tagpdf.
% \changes{v0.81g}{2024-11-21}{add missing argument to socket}
% \begin{macrocode}
\socket_if_exist:nF {tagsupport/para/begin}
{
\NewSocket{tagsupport/para/begin}{0}
\NewSocket{tagsupport/para/end}{0}
}
% \end{macrocode}
%
% \begin{socketdecl}{caption/label}
% This socket is a lightweight start for
% some interface to format the label or add a font command.
% The argument is the label text.
% The default plug \texttt{kernel} adds a colon
% and a space.
% TODO: revisit after checking float and caption packages
% to identify which sockets and hooks are needed.
% \begin{macrocode}
\NewSocket{caption/label}{1}
% \end{macrocode}
% \end{socketdecl}
%
% \begin{plugdecl}{kernel (caption/label)}
% The standard label formatting from the kernel.
% \begin{macrocode}
\NewSocketPlug{caption/label}{kernel}
{
#1:~
}
\AssignSocketPlug{caption/label}{kernel}
% \end{macrocode}
% \end{plugdecl}
% \begin{plugdecl}{default}
% The caption begin socket takes an argument: the structure number of
% the parent float. If the argument is empty, the current structure is used.
% TODO: a tagpdf key that moves a structure to the begin of the parent.
% The caption is moved to the first position with the firstkid option.
% \begin{macrocode}
\NewSocketPlug {tagsupport/caption/begin}{default}
{
\tl_if_empty:eTF {#1}
{
\tag_struct_begin:n{tag=Caption,firstkid}
}
{
\tag_struct_begin:n{tag=Caption,parent=#1,firstkid}
}
\bool_set_true:N \l__tag_para_flattened_bool
}
\AssignSocketPlug{tagsupport/caption/begin}{default}
% \end{macrocode}
% \end{plugdecl}
% \begin{plugdecl}{default}
% \begin{macrocode}
\NewSocketPlug {tagsupport/caption/end}{default}
{
\tag_struct_end:
}
\AssignSocketPlug{tagsupport/caption/end}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \begin{plugdecl}{default (tagsupport/caption/label/begin)}
% \begin{macrocode}
\NewSocketPlug {tagsupport/caption/label/begin}{default}
{
% \end{macrocode}
% suppress para tagging at the begin.
% \begin{macrocode}
\tagpdfparaOff
\tag_struct_begin:n{tag=Lbl}
\tag_mc_begin:n{}
}
\AssignSocketPlug{tagsupport/caption/label/begin}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \begin{plugdecl}{default (tagsupport/caption/label/end)}
% \begin{macrocode}
\NewSocketPlug {tagsupport/caption/label/end}{default}
{
\tag_mc_end:
\tag_struct_end:
\tagpdfparaOn
}
\AssignSocketPlug{tagsupport/caption/label/end}{default}
% \end{macrocode}
% \end{plugdecl}
%
% \subsubsection{Redefinitions}
%
% With hyperref that means that the \cs{refstepcounter} now can affect spacing so we
% change that to the kernel refstepcounter:
% \begin{macrocode}
\def\caption{%
\ifx\@captype\@undefined
\@latex@error{\noexpand\caption\c_space_tl outside~float}\@ehd
\expandafter\@gobble
\else
% \end{macrocode}
% if a caption is used outside a float no
% target has been set and \cs{@current@float@struct} is empty
% \begin{macrocode}
\tl_if_empty:NTF\@current@float@struct
{
\refstepcounter\@captype
}
{
\@kernel@refstepcounter\@captype
% \end{macrocode}
% we need to reset the target for \cs{addcontentsline}.
% We use \cs{@captype} to support autoref.
% \begin{macrocode}
\xdef\@currentHref{\@captype.struct.\@current@float@struct}%
}
\expandafter\@firstofone
\fi
{\@dblarg{\@caption\@captype}}%
}
% \end{macrocode}
%
% \begin{macro}{\@makecaption}
% \cs{@makecaption} is defined by the classes so we overwrite it for now
% at begin document.
% \begin{macrocode}
\AddToHook{begindocument}
{
\long\def\@makecaption#1#2{%
\vskip\abovecaptionskip
% \end{macrocode}
% we don't want tagging when storing the caption for the singleline check
% \begin{macrocode}
\SuspendTagging{\@makecaption}
\sbox\@tempboxa{#1:~#2}%
\ResumeTagging{\@makecaption}
% \end{macrocode}
% We pass \cs{@current@float@struct} as parent structure
% number. If that is empty the socket will use the parent structure and hope ...
% \begin{macrocode}
\UseTaggingSocket{caption/begin}{\@current@float@struct}
\ifdim \wd\@tempboxa >\hsize
\UseTaggingSocket{caption/label/begin}
\UseSocket{caption/label}{#1}
\UseTaggingSocket{caption/label/end}
\UseTaggingSocket{para/begin}
#2
\par
\else
% \end{macrocode}
% we don't reuse the box as it doesn't contain tagging, but set the text explicitly.
% \begin{macrocode}
\global \@minipagefalse
\hb@xt@\hsize{\hfil
\UseTaggingSocket{caption/label/begin}
\UseSocket{caption/label}{#1}
\UseTaggingSocket{caption/label/end}
\UseTaggingSocket{para/begin}
#2
\UseTaggingSocket{para/end}
\hfil}%
\fi
\UseTaggingSocket{caption/end}
\vskip\belowcaptionskip}
}
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
%</package>
% \end{macrocode}
% \begin{macrocode}
%<*latex-lab>
\ProvidesFile{float-latex-lab-testphase.ltx}
[\ltlabfloatdate\space v\ltlabfloatversion\space latex-lab wrapper float]
\RequirePackage{latex-lab-testphase-float}
%</latex-lab>
% \end{macrocode}
% \end{implementation}