% \iffalse meta-comment
%
%% File: latex-lab-minipage.dtx 
%% 
% Copyright (C) 2023-2024 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\ltlabminipagedate{2024-08-08}
\def\ltlabminipageversion{0.81d}
%<*driver>
\documentclass{l3doc}
\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 sockets
%  \texttt{tagsupport/parbox/before} and
%  \texttt{tagsupport/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}
% As minipage uses a socket from the footnote code we must load the OR-code:
%    \begin{macrocode}
\RequirePackage{latex-lab-testphase-new-or-1}
\RequirePackage{latex-lab-testphase-new-or-2}
%    \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.
%    \begin{macrocode}
\socket_new:nn {tagsupport/minipage/before}{0}
\socket_new:nn {tagsupport/minipage/after} {0}
\socket_new:nn {tagsupport/parbox/before}  {0}
\socket_new:nn {tagsupport/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_stop:n{minipage}
  \expandafter\@iiiparbox\@mpargs{\unvbox\@tempboxa}%
  \tag_start:n{minipage}
  \UseTaggingSocket{minipage/after} %new end ...
  }
%    \end{macrocode}
%
% And similar for \cs{parbox}
%    \begin{macrocode}
\long\def\@iiiparbox#1#2[#3]#4#5{%
  \@kernel@init@parbox
  \leavevmode
  \@pboxswfalse
  \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\ifmmode\vcenter
    \else\@pboxswtrue $\vcenter
    \fi\fi\fi
    \@parboxto{\let\hss\vss\let\unhbox\unvbox
       \csname bm@#3\endcsname}%
    \if@pboxsw \m@th$\fi
  \@end@tempboxa%
  \UseTaggingSocket{parbox/after}
  }
%    \end{macrocode}
%
% \subsection{Tagging commands}
% 
%    \begin{macrocode}
\tl_new:N  \l__ltboxes_tag_tl
\tl_set:Nn \l__ltboxes_tag_tl {Div}
\socket_new_plug:nnn{tagsupport/minipage/before}{tag/dflt}
  {
%    \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=\l__ltboxes_tag_tl}
  }
%    \end{macrocode}
% similar for the other sockets:
%    \begin{macrocode}
\socket_new_plug:nnn{tagsupport/minipage/after}{tag/dflt}
  {
   \tag_struct_end:
   \bool_if:NT \l__tag_para_bool {\tag_struct_begin:n{tag=\l__tag_para_tag_tl}}
   \tag_mc_begin_pop:n{}
  }
  
\socket_new_plug:nnn{tagsupport/parbox/before}{tag/dflt}
  {
   \tag_mc_end_push:
   \bool_if:NT \l__tag_para_bool {\tag_struct_end:}
   \tag_struct_begin:n{tag=\l__ltboxes_tag_tl}
  }
  
\socket_new_plug:nnn{tagsupport/parbox/after}{tag/dflt}
  {
   \tag_struct_end:
   \bool_if:NT \l__tag_para_bool {\tag_struct_begin:n{tag=\l__tag_para_tag_tl}}
   \tag_mc_begin_pop:n{}
   }
%    \end{macrocode}
% Activate the default tagging plug
%    \begin{macrocode}
\socket_assign_plug:nn{tagsupport/minipage/before}{tag/dflt}
\socket_assign_plug:nn{tagsupport/minipage/after} {tag/dflt}
\socket_assign_plug:nn{tagsupport/parbox/before}  {tag/dflt}
\socket_assign_plug:nn{tagsupport/parbox/after}   {tag/dflt}
%    \end{macrocode}
%    \begin{macrocode}
%</package>  
%    \end{macrocode}

%    \begin{macrocode}
%<*latex-lab>
\ProvidesFile{minipage-latex-lab-testphase.ltx}
        [\ltlabminipagedate\space v\ltlabminipageversion 
         code related to the tagging of minipage and parbox]
\RequirePackage{latex-lab-testphase-minipage}
%</latex-lab>
%    \end{macrocode}
