% \iffalse meta-comment
%
%% File: latex-lab-minipage.dtx
%%
% Copyright (C) 2023-2026 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 latex-lab bundle is developed in the LaTeX2e GitHub.
% Issues may be reported at
%
%    https://github.com/latex3/latex2e/issues
%
\def\ltlabminipagedate{2026-04-24}
\def\ltlabminipageversion{0.81k}
%<*driver>
\DocumentMetadata{tagging=on,pdfstandard=ua-2}
\documentclass[kernel]{l3in2edoc}

\EnableCrossrefs
\CodelineIndex
\begin{document}
  \DocInput{latex-lab-minipage.dtx}
\end{document}
%</driver>
%
% \fi
%
%
% \title{The \textsf{latex-lab-minipage} package\\
% Changes related to the tagging of minipage and parbox}
% \author{\LaTeX{} Project\thanks{Initial implementation done by Ulrike Fischer}}
% \date{v\ltlabminipageversion\ \ltlabminipagedate}
%
% \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}}
%
% \begin{abstract}
% \end{abstract}
%
% \section{Introduction}
%
%  How to best tag minipages and parboxes is still under discussion.
%  But as they start and contain paragraphs it is clear that
%  some sockets are needed to interrupt and restart the tagging.
%
%  The tagging added is currently quite simple-minded. See the
%  todo-testfiles and the code comments for some open points.
%
%  One of the main problems is how to properly embed them in the
%  surrounding.  When used in normal text (in a paragraph) they
%  typically should close the \texttt{text} structure and reopen one
%  at the end. But when used inside low-level \cs{vbox} or \cs{hbox}
%  this is often wrong. The code uses now there two tagging sockets
%  \texttt{parbox/before} and
%  \texttt{parbox/after} which can be set to noop, if
%  necessary.
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \section{Implementation}
%    \begin{macrocode}
\ProvidesExplPackage {latex-lab-testphase-minipage}
  {\ltlabminipagedate} {\ltlabminipageversion}
  {Code related to the tagging of minipages and parboxes}
%    \end{macrocode}
%
%
% \subsection{Provide the kernel hooks}
% [kernel?]
% We need to check/set the status before the
% initial \cs{leavevmode} to decide how to handle the structure.
% Perhaps the same command will work for both?
%    \begin{macrocode}
\def\@kernel@init@minipage{}
\def\@kernel@init@parbox{}
%    \end{macrocode}
% We use sockets for the tag support code, as there will be cases where we want
% to exchange the content or disable it.
% The socket declarations are in lttagging.dtx.
%    \begin{macrocode}
%   \NewTaggingSocket{minipage/before}{0}
%   \NewTaggingSocket{minipage/after} {0}
%   \NewTaggingSocket{parbox/before}  {0}
%   \NewTaggingSocket{parbox/after}{0}
%    \end{macrocode}
%
% \subsection{Patch minipage}
% [kernel?]
% The begin hook is inserted in \cs{@iiiminipage}
%    \begin{macrocode}
\def\@iiiminipage#1#2[#3]#4{%
%    \end{macrocode}
% Before switching to hmode we insert a hook. It is currently unused
% but could for example check if we are in vmode and change the following
% paragraph tag.
%    \begin{macrocode}
  \@kernel@init@minipage
  \leavevmode
  \@pboxswfalse
  \setlength\@tempdima{#4}%
  \def\@mpargs{{#1}{#2}[#3]{#4}}%
%    \end{macrocode}
% insert the socket
%    \begin{macrocode}
  \UseTaggingSocket{minipage/before}% new
  \setbox\@tempboxa\vbox\bgroup
    \color@begingroup
      \hsize\@tempdima
      \textwidth\hsize \columnwidth\hsize
      \@parboxrestore
%    \end{macrocode}
% minipages are perhaps used in environments where the tagging of paragraphs
% has been altered. So we try to restore this. TODO: this should
% perhaps be done in \cs{@parboxrestore} directly.
%    \begin{macrocode}
      \UseTaggingSocket{para/restore}
      \def\@mpfn{mpfootnote}\def\thempfn{\thempfootnote}\c@mpfootnote\z@
      \socket_assign_plug:nn{fntext/process}{mp}%
      \let\@listdepth\@mplistdepth \@mplistdepth\z@
      \@minipagerestore
      \@setminipage}
%    \end{macrocode}
%  And a hook at the end
%    \begin{macrocode}
\def\endminipage{%
    \par
    \unskip
    \ifvoid\@mpfootins\else
      \vskip\skip\@mpfootins
      \normalcolor
      \footnoterule
      \unvbox\@mpfootins
    \fi
    \@minipagefalse   %% added 24 May 89
  \color@endgroup
  \egroup
%    \end{macrocode}
%    As the parbox command is called, we must prevent that it adds its
%    additional tagging commands:
%    \begin{macrocode}
  \tag_suspend:n{minipage}
  \expandafter\@iiiparbox\@mpargs{\unvbox\@tempboxa}%
  \tag_resume:n{minipage}
  \UseTaggingSocket{minipage/after} %new end ...
  }
%    \end{macrocode}
%
% \changes{v0.81i}{2026-02-24}{Use text mode vertical centering}
% And similar for \cs{parbox}
%    \begin{macrocode}
\long\def\@iiiparbox#1#2[#3]#4#5{%
  \@kernel@init@parbox
  \leavevmode
  \setlength\@tempdima{#4}%
  \UseTaggingSocket{parbox/before}
  \@begin@tempboxa\vbox{\hsize\@tempdima\@parboxrestore
%    \end{macrocode}
% parbox are perhaps used in environments where the tagging of paragraphs
% has been altered. So we try to restore this. TODO: this should
% perhaps be done in \cs{@parboxrestore} directly.
%    \begin{macrocode}
  \UseTaggingSocket{para/restore}
  #5\@@par}%
    \ifx\relax#2\else
      \setlength\@tempdimb{#2}%
      \edef\@parboxto{to\the\@tempdimb}%
    \fi
    \if#1b\vbox
    \else\if #1t\vtop
    \else\vcenter@text
    \fi\fi
    \@parboxto{\let\hss\vss\let\unhbox\unvbox
       \csname bm@#3\endcsname}%
  \@end@tempboxa%
  \UseTaggingSocket{parbox/after}
  }
%    \end{macrocode}
%
% \subsection{Tagging commands}
%
%    \begin{macrocode}
\NewTaggingSocketPlug{minipage/before}{kernel}
  {
%    \end{macrocode}
% As there was a \cs{leavevmode} before that is a P/text open that we have to close
% if para tagging is active:
%    \begin{macrocode}
    \tag_mc_end_push:
    \bool_if:NT \l__tag_para_bool {\tag_struct_end:}
%    \end{macrocode}
% TODO: the P can be further up, we need a proper method to test and handle this.
%    \begin{macrocode}
    \tag_struct_begin:n{tag=\UseStructureName{minipage}}
  }
%    \end{macrocode}
% similar for the other sockets:
%    \begin{macrocode}
\NewTaggingSocketPlug{minipage/after}{kernel}
  {
   \tag_struct_end:
   \bool_if:NT \l__tag_para_bool
     {\tag_struct_begin:n{tag=\UseStructureName{para/textblock}}}
   \tag_mc_begin_pop:n{}
  }

\NewTaggingSocketPlug{parbox/before}{kernel}
  {
   \tag_mc_end_push:
   \bool_if:NT \l__tag_para_bool {\tag_struct_end:}
   \tag_struct_begin:n{tag=\UseStructureName{parbox}}
  }

\NewTaggingSocketPlug{parbox/after}{kernel}
  {
   \tag_struct_end:
   \bool_if:NT \l__tag_para_bool
     {\tag_struct_begin:n{tag=\UseStructureName{para/textblock}}}
   \tag_mc_begin_pop:n{}
   }
%    \end{macrocode}
%
% Copies of the plugs with the previous names for compatibility.
% After release 2026-06-01 they should be replaced by the new names and then removed.
%    \begin{macrocode}
\NewTaggingSocketPlug{minipage/before}{tag/dflt}
  {
    \tag_mc_end_push:
    \bool_if:NT \l__tag_para_bool {\tag_struct_end:}
    \tag_struct_begin:n{tag=\UseStructureName{minipage}}
  }
\NewTaggingSocketPlug{minipage/after}{tag/dflt}
  {
   \tag_struct_end:
   \bool_if:NT \l__tag_para_bool
     {\tag_struct_begin:n{tag=\UseStructureName{para/textblock}}}
   \tag_mc_begin_pop:n{}
  }
\NewTaggingSocketPlug{parbox/before}{tag/dflt}
  {
   \tag_mc_end_push:
   \bool_if:NT \l__tag_para_bool {\tag_struct_end:}
   \tag_struct_begin:n{tag=\UseStructureName{parbox}}
  }
\NewTaggingSocketPlug{parbox/after}{tag/dflt}
  {
   \tag_struct_end:
   \bool_if:NT \l__tag_para_bool
     {\tag_struct_begin:n{tag=\UseStructureName{para/textblock}}}
   \tag_mc_begin_pop:n{}
   }
%    \end{macrocode}
% Activate the default tagging plug
%    \begin{macrocode}
\AssignTaggingSocketPlug{minipage/before}{kernel}
\AssignTaggingSocketPlug{minipage/after} {kernel}
\AssignTaggingSocketPlug{parbox/before}  {kernel}
\AssignTaggingSocketPlug{parbox/after}   {kernel}
%    \end{macrocode}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
