tagpdf-mc-generic.dtx

% \iffalse meta-comment
%
%% File: tagpdf-mc-generic.dtx
%
% Copyright (C) 2019-2024 Ulrike Fischer
%
% 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
%
% This file is part of the "tagpdf bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https:/latex3/tagpdf
%
% for those people who are interested.
%<*driver>
\DocumentMetadata{}
\documentclass{l3doc}
\usepackage{array,booktabs,caption}
\hypersetup{pdfauthor=Ulrike Fischer,
 pdftitle=tagpdf-mc module (tagpdf)}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% \title{^^A
%   The \pkg{tagpdf-mc-generic} module\\ Code related to Marked Content (mc-chunks), generic mode  ^^A
%   \\ Part of the tagpdf package
% }
%
% \author{^^A
%  Ulrike Fischer\thanks
%    {^^A
%      E-mail:
%        \href{mailto:fischer@troubleshooting-tex.de}
%          {fischer@troubleshooting-tex.de}^^A
%    }^^A
% }
%
% \date{Version 0.99f, released 2024-09-16}
% \maketitle
% \begin{documentation}
% \end{documentation}
% \begin{implementation}
% \section{Marked content code -- generic mode}
%    \begin{macrocode}
%<@@=tag>
%<*generic>
\ProvidesExplPackage {tagpdf-mc-code-generic} {2024-09-16} {0.99f}
 {part of tagpdf - code related to marking chunks - generic mode}
%</generic>
%<*debug>
\ProvidesExplPackage {tagpdf-debug-generic} {2024-09-16} {0.99f}
 {part of tagpdf - debugging code related to marking chunks - generic mode}
%</debug>
%    \end{macrocode}
%
%\subsection{Variables}
%
%    \begin{macrocode}
%<*generic>
%    \end{macrocode}
%
% \begin{variable}{\l_@@_mc_ref_abspage_tl}
% We need a ref-label system to ensure that the MCID cnt
% restarts at 0 on a new page
% This will be used to store the tagabspage attribute retrieved from
% a label.
%    \begin{macrocode}
\tl_new:N \l_@@_mc_ref_abspage_tl
%    \end{macrocode}
% \end{variable}

% \begin{variable}{\l_@@_mc_tmpa_tl}
% temporary variable
%    \begin{macrocode}
\tl_new:N \l_@@_mc_tmpa_tl
%    \end{macrocode}
% \end{variable}

% \begin{variable}
%   {
%     \g_@@_mc_marks,
%   }
% a marks register to keep track of the mc's at page breaks and a sequence
% to keep track of the data for the continuation
% extra-tmb. We probably will need to track mc-marks
% in more than one stream, so the seq contains the name of the stream.
%
%    \begin{macrocode}
\newmarks  \g_@@_mc_marks
%    \end{macrocode}
% \end{variable}
%
%  \begin{variable}
%   {
%    \g_@@_mc_main_marks_seq,
%    \g_@@_mc_footnote_marks_seq,
%    \g_@@_mc_multicol_marks_seq
%   }
%    Each stream has an associated global seq variable holding the
%    bottom marks from the/a previous chunk in the stream.
%    We provide three by default: main, footnote and multicol.
%    TODO: perhaps an interface for more streams will be needed.
%    \begin{macrocode}
\seq_new:N \g_@@_mc_main_marks_seq
\seq_new:N \g_@@_mc_footnote_marks_seq
\seq_new:N \g_@@_mc_multicol_marks_seq
%    \end{macrocode}
%  \end{variable}

% \begin{variable}{\l_@@_mc_firstmarks_seq,\l_@@_mc_botmarks_seq}
% The marks content contains a number of data which we will have to access and
% compare, so we will store it locally in two sequences.
% topmarks is unusable in LaTeX so we ignore it.
%
%    \begin{macrocode}
\seq_new:N  \l_@@_mc_firstmarks_seq
\seq_new:N  \l_@@_mc_botmarks_seq
%    \end{macrocode}
% \end{variable}
%
% \subsection{Functions}
%
% \begin{macro}{\@@_mc_begin_marks:nn,\@@_mc_artifact_begin_marks:n,\@@_mc_end_marks:}
% Generic mode need to set marks for the page break and split stream handling.
% We always set two marks to be able to detect the case when no mark is on a
% page/galley. MC-begin commands will set (b,-,data) and (b,+,data),
% MC-end commands will set (e,-,data) and (e,+,data).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_mc_begin_marks:nn #1 #2 %#1 tag, #2 label
  {
    \tex_marks:D \g_@@_mc_marks
      {
        b-, %first of begin pair
        \int_use:N\c@g_@@_MCID_abs_int, %mc-num
        \g_@@_struct_stack_current_tl,  %structure num
        #1, %tag
        \bool_if:NT \l_@@_mc_key_stash_bool{stash}, % stash info
        #2, %label
      }
    \tex_marks:D \g_@@_mc_marks
      {
        b+, % second of begin pair
        \int_use:N\c@g_@@_MCID_abs_int, %mc-num
        \g_@@_struct_stack_current_tl,  %structure num
        #1, %tag
        \bool_if:NT \l_@@_mc_key_stash_bool{stash}, % stash info
        #2, %label
      }
  }
\cs_generate_variant:Nn \@@_mc_begin_marks:nn {oo}
\cs_new_protected:Npn \@@_mc_artifact_begin_marks:n #1 %#1 type
  {
    \tex_marks:D \g_@@_mc_marks
      {
        b-, %first of begin pair
        \int_use:N\c@g_@@_MCID_abs_int, %mc-num
        -1, %structure num
        #1 %type
      }
    \tex_marks:D \g_@@_mc_marks
      {
        b+, %first of begin pair
        \int_use:N\c@g_@@_MCID_abs_int, %mc-num
        -1,  %structure num
        #1  %Type
      }
  }

\cs_new_protected:Npn \@@_mc_end_marks:
  {
    \tex_marks:D \g_@@_mc_marks
      {
        e-, %first of end pair
        \int_use:N\c@g_@@_MCID_abs_int, %mc-num
        \g_@@_struct_stack_current_tl,  %structure num
      }
    \tex_marks:D \g_@@_mc_marks
      {
        e+, %second of end pair
        \int_use:N\c@g_@@_MCID_abs_int, %mc-num
        \g_@@_struct_stack_current_tl,  %structure num
      }
  }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@@_mc_disable_marks:}
% This disables the marks. They can't be reenabled, so it should only
% be used in groups.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_mc_disable_marks:
 {
   \cs_set_eq:NN \@@_mc_begin_marks:nn \use_none:nn
   \cs_set_eq:NN \@@_mc_artifact_begin_marks:n \use_none:n
   \cs_set_eq:NN \@@_mc_end_marks: \prg_do_nothing:
 }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@@_mc_get_marks:}
% This stores the current content of the marks in the sequences. It naturally
% should only be used in places where it makes sense.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_mc_get_marks:
 {
   \exp_args:NNe
   \seq_set_from_clist:Nn \l_@@_mc_firstmarks_seq
     { \tex_firstmarks:D \g_@@_mc_marks }
   \exp_args:NNe
   \seq_set_from_clist:Nn \l_@@_mc_botmarks_seq
     { \tex_botmarks:D   \g_@@_mc_marks }
 }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_mc_store:nnn}
%  This inserts the mc-chunk \meta{mc-num} into the structure {struct-num}
%  after the \meta{mc-prev}.
%  The structure must already exist.
%  The additional mcid dictionary is stored in a property. The item is retrieved
%  when the kid entry is built. We test if there is already
%  an addition and append if needed.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_mc_store:nnn #1 #2 #3 %#1 mc-prev, #2 mc-num #3 structure-num
  {
    %\prop_show:N \g_@@_struct_cont_mc_prop
    \prop_get:NnNTF \g_@@_struct_cont_mc_prop {#1} \l_@@_tmpa_tl
      {
        \prop_gput:Nne \g_@@_struct_cont_mc_prop {#1}{ \l_@@_tmpa_tl \@@_struct_mcid_dict:n {#2}}
      }
      {
        \prop_gput:Nne \g_@@_struct_cont_mc_prop {#1}{ \@@_struct_mcid_dict:n {#2}}
      }
    \prop_gput:Nee \g_@@_mc_parenttree_prop
      {#2}
      {#3}
  }
\cs_generate_variant:Nn \@@_mc_store:nnn {eee}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_mc_insert_extra_tmb:n,\@@_mc_insert_extra_tme:n}
% These two functions should be used in the output routine at the place
% where a mc-literal could be missing due to a page break or some other split.
% They check (with the help of the marks) if a extra-tmb or extra-tme is needed.
% The tmb command stores also the mc into the structure, the tme has to store
% the data for a following extra-tmb.
% The argument takes a stream name like main or footnote to allow different handling
% there.
% The content of the marks must be stored before (with |\@@_mc_get_marks:|
% or manually)
% into |\l_@@_mc_firstmarks_seq| and |\l_@@_mc_botmarks_seq| so that the tests
% can use them.
%
%    \begin{macrocode}
\cs_new_protected:Npn \@@_mc_insert_extra_tmb:n #1 % #1 stream: e.g. main or footnote
  {
     \@@_check_typeout_v:n {=>~ first~ \seq_use:Nn \l_@@_mc_firstmarks_seq {,~}}
     \@@_check_typeout_v:n {=>~ bot~ \seq_use:Nn \l_@@_mc_botmarks_seq {,~}}
     \@@_check_if_mc_tmb_missing:TF
       {
         \@@_check_typeout_v:n {=>~ TMB~ ~ missing~ --~ inserted}
         %test if artifact
         \int_compare:nNnTF { \seq_item:cn { g_@@_mc_#1_marks_seq } {3} } = {-1}
           {
              \tl_set:Ne \l_@@_tmpa_tl { \seq_item:cn { g_@@_mc_#1_marks_seq } {4} }
              \@@_mc_handle_artifact:N \l_@@_tmpa_tl
           }
           {
              \exp_args:Ne
              \@@_mc_bdc_mcid:n
                {
                  \seq_item:cn { g_@@_mc_#1_marks_seq } {4}
                }
              \str_if_eq:eeTF
                {
                  \seq_item:cn { g_@@_mc_#1_marks_seq } {5}
                }
                {}
                {
                  %store
                  \@@_mc_store:eee
                    {
                      \seq_item:cn { g_@@_mc_#1_marks_seq } {2}
                    }
                    { \int_eval:n{\c@g_@@_MCID_abs_int} }
                    {
                      \seq_item:cn { g_@@_mc_#1_marks_seq } {3}
                    }
                }
                {
                   %stashed -> warning!!
                }
           }
       }
       {
         \@@_check_typeout_v:n {=>~ TMB~ not~ missing}
       }
  }

\cs_new_protected:Npn \@@_mc_insert_extra_tme:n #1 % #1 stream, eg. main or footnote
 {
   \@@_check_if_mc_tme_missing:TF
     {
       \@@_check_typeout_v:n {=>~ TME~ ~ missing~ --~ inserted}
       \@@_mc_emc:
       \seq_gset_eq:cN
         {  g_@@_mc_#1_marks_seq }
         \l_@@_mc_botmarks_seq
     }
     {
       \@@_check_typeout_v:n {=>~ TME~ not~ missing}
     }
 }
%    \end{macrocode}
% \end{macro}
%
%  \subsection{Looking at MC marks in boxes}
%  \begin{macro}{\@@_add_missing_mcs:Nn}
%    Assumptions:
%    \begin{itemize}
%    \item
%       test for tagging active outside;
%    \item
%       mark retrieval also outside.
%    \end{itemize}
%
%    This takes a box register as its first argument (or the register
%    number in a count register, as used by \pkg{multicol}). It adds
%    an extra tmb at the top of the box if necessary and similarly
%    an extra tme at the end. This is done by adding hboxes in a way
%    that the positioning and the baseline of the given box is not
%    altered.  The result is written back to the box.
%
%    The second argument is the stream this box belongs to und is
%    currently either \texttt{main} for the main galley,
%    \texttt{footnote} for footnote note text, or \texttt{multicol}
%    for boxes produced for columns in that environment. Other streams
%    may follow over time.
%    \begin{macrocode}
\cs_new_protected:Npn\@@_add_missing_mcs:Nn #1 #2 {
  \vbadness \@M
  \vfuzz    \c_max_dim
  \vbox_set_to_ht:Nnn #1 { \box_ht:N #1 } {
    \hbox_set:Nn \l_@@_tmpa_box { \@@_mc_insert_extra_tmb:n {#2} }
    \hbox_set:Nn \l_@@_tmpb_box { \@@_mc_insert_extra_tme:n {#2} }
    \int_compare:nNnT {\l_@@_loglevel_int} > { 0 }
         {
           \seq_log:c { g_@@_mc_#2_marks_seq}
         }
%    \end{macrocode}
%    The box placed on the top gets zero size and thus will not affect
%    the box dimensions of the box we are modifying.
%    \begin{macrocode}
    \box_set_ht:Nn \l_@@_tmpa_box \c_zero_dim
    \box_set_dp:Nn \l_@@_tmpa_box \c_zero_dim
%    \end{macrocode}
%    The box added at the bottom will get the depth of the original
%    box. This way we can arrange that from the outside everything
%    looks as before.
%    \begin{macrocode}
    \box_set_ht:Nn \l_@@_tmpb_box \c_zero_dim
    \box_set_dp:Nn \l_@@_tmpb_box { \box_dp:N #1 }
%    \end{macrocode}
%    We need to set \cs{boxmaxdepth} in case the original box has an
%    unusually large depth, otherwise that depth is not preserved when
%    we string things together.
%    \begin{macrocode}
    \boxmaxdepth \@maxdepth
    \box_use_drop:N        \l_@@_tmpa_box
    \vbox_unpack_drop:N     #1
%    \end{macrocode}
%    Back up by the depth of the box as we add that later again.
%    \begin{macrocode}
    \tex_kern:D -\box_dp:N \l_@@_tmpb_box
%    \end{macrocode}
%    And we don't want any glue added when we add the box.
%    \begin{macrocode}
    \nointerlineskip
    \box_use_drop:N \l_@@_tmpb_box
  }
}
%    \end{macrocode}
%  \end{macro}

%  \begin{macro}{\@@_add_missing_mcs_to_stream:Nn}
%    This is the main command to add mc to the stream. It is therefore
%    guarded by the mc-boolean.
%
%    If we aren't in the main stream then processing is a bit more
%    complicated because to get at the marks in the box we need to
%    artificially split it and then look at the split marks.
%
%    First argument is the box to update and the second is the \enquote{stream}.
%    In lua mode the command is a no-op.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_add_missing_mcs_to_stream:Nn #1#2
  {
    \@@_check_if_active_mc:T {
%    \end{macrocode}
%    First set up a temp box for trial splitting.
%    \begin{macrocode}
    \vbadness\maxdimen
    \box_set_eq:NN \l_@@_tmpa_box #1
%    \end{macrocode}
%    Split the box to the largest size available. This should give us
%    all content (but to be sure that there is no issue we could test
%    out test box is empty now (not done).
%    \begin{macrocode}
    \vbox_set_split_to_ht:NNn \l_@@_tmpa_box \l_@@_tmpa_box \c_max_dim
%    \end{macrocode}
%    As a side effect of this split we should now have the first and
%    bottom split marks set up. We use this to set up
%    \cs{l_@@_mc_firstmarks_seq}
%    \begin{macrocode}
    \exp_args:NNe
    \seq_set_from_clist:Nn \l_@@_mc_firstmarks_seq
        { \tex_splitfirstmarks:D \g_@@_mc_marks }
%    \end{macrocode}
%    Some debugging info:
%    \begin{macrocode}
%    \iow_term:n { First~ mark~ from~ this~ box: }
%    \seq_log:N \l_@@_mc_firstmarks_seq
%    \end{macrocode}
%    If this mark was empty then clearly the bottom mark will too be
%    empty. Thus in this case we make use of the saved bot mark from
%    the previous chunk. Note that if this is the first chunk in the
%    stream the global seq would contain a random value, but then we
%    can't end in this branch because the basis assumption is that
%    streams are properly marked up so the first chunk would always
%    have a mark at the beginning!
%    \begin{macrocode}
    \seq_if_empty:NTF \l_@@_mc_firstmarks_seq
        {
          \@@_check_typeout_v:n
            {
              No~ marks~ so~ use~ saved~ bot~ mark:~
              \seq_use:cn {g_@@_mc_#2_marks_seq} {,~} \iow_newline:
            }
           \seq_set_eq:Nc \l_@@_mc_firstmarks_seq {g_@@_mc_#2_marks_seq}
%    \end{macrocode}
%    We also update the bot mark to the same value so that we can
%    later apply \cs{@@_add_missing_mcs:Nn} with the data
%    structures in place (see assumptions made there).
%    \begin{macrocode}
          \seq_set_eq:NN \l_@@_mc_botmarks_seq \l_@@_mc_firstmarks_seq
        }
%    \end{macrocode}
%    If there was a first mark then there is also a bot mark (and it
%    can't be the same as our marks always come in pairs).
%    So if that branch is chosen we update
%    \cs{l_@@_mc_botmarks_seq} from the bot mark.
%    \begin{macrocode}
        {
          \@@_check_typeout_v:n
            {
              Pick~ up~ new~ bot~ mark!
            }
          \exp_args:NNe
          \seq_set_from_clist:Nn \l_@@_mc_botmarks_seq
              { \tex_splitbotmarks:D   \g_@@_mc_marks }
        }
%    \end{macrocode}
%    Finally we call \cs{@@_add_missing_mcs:Nn} to add any missing
%    tmb/tme as needed,
%    \begin{macrocode}
    \@@_add_missing_mcs:Nn #1 {#2}
%%
    \seq_gset_eq:cN  {g_@@_mc_#2_marks_seq} \l_@@_mc_botmarks_seq
%%
  }
}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}[pTF]{\@@_mc_if_in:,\tag_mc_if_in:}
% This is a test if a mc is open or not. It depends simply on a global boolean:
% mc-chunks are added linearly so nesting should not be relevant.
%
% One exception are header and footer (perhaps they are more, but for now
% it doesn't seem so, so there are no dedicated code to handle this situation):
% When they are built and added to the page we could be both inside or outside a mc-chunk.
% But header and footer should ignore this and not push/pop or warn about nested mc.
% It is therefore important there to set and reset the boolean manually.
% See the tagpddocu-patches.sty for an example.
%    \begin{macrocode}
\prg_new_conditional:Nnn \@@_mc_if_in: {p,T,F,TF}
  {
    \bool_if:NTF \g_@@_in_mc_bool
      { \prg_return_true:  }
      { \prg_return_false: }
  }

\prg_new_eq_conditional:NNn \tag_mc_if_in: \@@_mc_if_in: {p,T,F,TF}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{ \@@_mc_bmc:n,\@@_mc_emc:,\@@_mc_bdc:nn}
% These are the low-level commands. There are now equal to the
% pdfmanagement commands generic mode, but we use an indirection
% in case luamode need something else.
% change 04.08.2018: the commands do not check the validity of the arguments or try
% to escape them, this should be done before using them.
% change 2023-08-18: we are delaying the writing to the shipout.
%    \begin{macrocode}
% #1 tag, #2 properties
\cs_set_eq:NN \@@_mc_bmc:n  \pdf_bmc:n
\cs_set_eq:NN \@@_mc_emc:   \pdf_emc:
\cs_set_eq:NN \@@_mc_bdc:nn \pdf_bdc:nn
\cs_set_eq:NN \@@_mc_bdc_shipout:ee \pdf_bdc_shipout:ee
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}
%   {
%     \@@_mc_bdc_mcid:nn,\@@_mc_bdc_mcid:n,
%     \@@_mc_handle_mcid:nn,\@@_mc_handle_mcid:VV
%   }
%
% This create a BDC mark with an |/MCID| key. Most of the work here is to get
% the current number value for the MCID: they must be numbered by page
% starting with 0 and then successively.
% The first argument is the tag, e.g. |P| or |Span|, the second is used to pass
% more properties.
% Starting with texlive 2023 this is much simpler and faster as we can use
% delay the numbering to the shipout. 
% We also define a wrapper around the low-level command as luamode will need
% something different.
%    \begin{macrocode}
\bool_if:NTF\g_@@_delayed_shipout_bool 
  { 
    \hook_gput_code:nnn {shipout/before}{tagpdf}{ \flag_clear:n { @@/mcid } }
    \cs_set_protected:Npn \@@_mc_bdc_mcid:nn #1 #2
      {
        \int_gincr:N \c@g_@@_MCID_abs_int
        \@@_property_record:eV
         {
           mcid-\int_use:N \c@g_@@_MCID_abs_int
         }
         \c_@@_property_mc_clist     
        \@@_mc_bdc_shipout:ee
          {#1}
          { 
            /MCID~\flag_height:n { @@/mcid }
            \flag_raise:n { @@/mcid }~  #2  
          }
      }
  } 
%    \end{macrocode}
% if the engine is too old, we have to revert to earlier method.
%    \begin{macrocode}
 { 
   \msg_new:nnn { tagpdf } { old-engine }
    { 
      The~engine~or~the~PDF management~is~too~old~or\\
      delayed~shipout~has~been~disabled.\\
      Fast~numbering~of~MC-chunks~not~available.\\
      More~compilations~will~be~needed~in~generic~mode.
    }  
   \msg_warning:nn { tagpdf} { old-engine }   
   \@@_prop_new:N \g_@@_MCID_byabspage_prop
   \int_new:N \g_@@_MCID_tmp_bypage_int
   \cs_generate_variant:Nn \@@_mc_bdc:nn {ne}
%    \end{macrocode}
% revert the attribute:
%    \begin{macrocode}
   \property_gset:nnnn {tagmcid } { now }
       {0}  { \int_use:N \g_@@_MCID_tmp_bypage_int }
   \cs_new_protected:Npn \@@_mc_bdc_mcid:nn #1 #2
     {
       \int_gincr:N \c@g_@@_MCID_abs_int
       \tl_set:Ne \l_@@_mc_ref_abspage_tl
         {
           \property_ref:enn %3 args
             {
               mcid-\int_use:N \c@g_@@_MCID_abs_int
             }
             { tagabspage }
             {-1}
         }
       \prop_get:NoNTF
         \g_@@_MCID_byabspage_prop
         {
           \l_@@_mc_ref_abspage_tl
         }
         \l_@@_mc_tmpa_tl
         {
           %key already present, use value for MCID and add 1 for the next
           \int_gset:Nn \g_@@_MCID_tmp_bypage_int { \l_@@_mc_tmpa_tl }
           \@@_prop_gput:Nee
             \g_@@_MCID_byabspage_prop
             { \l_@@_mc_ref_abspage_tl }
             { \int_eval:n {\l_@@_mc_tmpa_tl +1} }
         }
         {
           %key not present, set MCID to 0 and insert 1
           \int_gzero:N \g_@@_MCID_tmp_bypage_int
           \@@_prop_gput:Nee
             \g_@@_MCID_byabspage_prop
             { \l_@@_mc_ref_abspage_tl }
             {1}
         }
       \@@_property_record:eV
         {
           mcid-\int_use:N \c@g_@@_MCID_abs_int
         }
         \c_@@_property_mc_clist
        \@@_mc_bdc:ne
          {#1}
          { /MCID~\int_eval:n { \g_@@_MCID_tmp_bypage_int }~ \exp_not:n { #2 } }
      }        
 }  
 \cs_new_protected:Npn \@@_mc_bdc_mcid:n #1
  {
    \@@_mc_bdc_mcid:nn {#1} {}
  }

\cs_new_protected:Npn \@@_mc_handle_mcid:nn #1 #2 %#1 tag, #2 properties
  {
    \@@_mc_bdc_mcid:nn {#1} {#2}
  }

\cs_generate_variant:Nn \@@_mc_handle_mcid:nn {VV}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\@@_mc_handle_stash:n,\@@_mc_handle_stash:e}
% This is the handler which puts a mc into the
% the current structure. The argument is the number of the mc.
% Beside storing the mc into the structure, it also has to record the
% structure for the parent tree.
% The name is a bit confusing, it does \emph{not} handle mc with the stash key
% \ldots.
% TODO: why does luamode use it for begin + use, but generic mode only for begin?
%    \begin{macrocode}
\cs_new_protected:Npn \@@_mc_handle_stash:n #1 %1 mcidnum
  {
    \@@_check_mc_used:n {#1}
    \@@_struct_kid_mc_gput_right:nn
      { \g_@@_struct_stack_current_tl }
      {#1}
   \prop_gput:Nee \g_@@_mc_parenttree_prop
     {#1}
     { \g_@@_struct_stack_current_tl }
  }
\cs_generate_variant:Nn \@@_mc_handle_stash:n { e }
%    \end{macrocode}
% \end{macro}

% \begin{macro}
%  {
%    \@@_mc_bmc_artifact:,
%    \@@_mc_bmc_artifact:n,
%    \@@_mc_handle_artifact:N
%   }
% Two commands to create artifacts, one without type, and one with.
% We define also a wrapper handler as luamode will need a different definition.
% TODO: perhaps later: more properties for artifacts
%    \begin{macrocode}
\cs_new_protected:Npn  \@@_mc_bmc_artifact:
  {
    \@@_mc_bmc:n {Artifact}
  }
\cs_new_protected:Npn \@@_mc_bmc_artifact:n #1
  {
    \@@_mc_bdc:nn {Artifact}{/Type/#1}
  }
\cs_new_protected:Npn \@@_mc_handle_artifact:N #1
   % #1 is a var containing the artifact type
  {
    \int_gincr:N \c@g_@@_MCID_abs_int
    \tl_if_empty:NTF #1
      { \@@_mc_bmc_artifact: }
      { \exp_args:NV\@@_mc_bmc_artifact:n #1 }
  }
%    \end{macrocode}
% \end{macro}

% \begin{macro}{ \@@_get_data_mc_tag: }
% This allows to retrieve the active mc-tag.
% It is use by the get command.
%    \begin{macrocode}
\cs_new:Nn \@@_get_data_mc_tag: { \g_@@_mc_key_tag_tl }
%</generic>
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\tag_mc_begin:n,\tag_mc_end:}
% These are the core public commands to open and close an mc.
% They don't need to be in the same group or grouping level,
% but the code expect that they are issued linearly. The tag and
% the state is passed to the end command through a global var and
% a global boolean.
%    \begin{macrocode}
%<base>\cs_new_protected:Npn \tag_mc_begin:n #1 { \@@_whatsits: \int_gincr:N \c@g_@@_MCID_abs_int }
%<base>\cs_new_protected:Nn \tag_mc_end:{ \@@_whatsits: }
%<*generic|debug>
%<*generic>
\cs_set_protected:Npn \tag_mc_begin:n #1 %#1 keyval
  {
    \@@_check_if_active_mc:T
      {
%</generic>
%<*debug>
\cs_set_protected:Npn \tag_mc_begin:n #1 %#1 keyval
  {
    \@@_check_if_active_mc:TF
      {
        \@@_debug_mc_begin_insert:n { #1 }
%</debug>
        \group_begin: %hm
        \@@_check_mc_if_nested:
        \bool_gset_true:N \g_@@_in_mc_bool
%    \end{macrocode}
% set default MC tags to structure:
%    \begin{macrocode}
        \tl_set_eq:NN \l_@@_mc_key_tag_tl \g_@@_struct_tag_tl
        \tl_gset_eq:NN\g_@@_mc_key_tag_tl \g_@@_struct_tag_tl        
        \keys_set:nn { @@ / mc } {#1}
        \bool_if:NTF \l_@@_mc_artifact_bool
          { %handle artifact
            \@@_mc_handle_artifact:N \l_@@_mc_artifact_type_tl
            \exp_args:NV
            \@@_mc_artifact_begin_marks:n \l_@@_mc_artifact_type_tl
          }
          { %handle mcid type
            \@@_check_mc_tag:N  \l_@@_mc_key_tag_tl
            \@@_mc_handle_mcid:VV
               \l_@@_mc_key_tag_tl
               \l_@@_mc_key_properties_tl
            \@@_mc_begin_marks:oo{\l_@@_mc_key_tag_tl}{\l_@@_mc_key_label_tl}
            \tl_if_empty:NF {\l_@@_mc_key_label_tl}
              {
                \exp_args:NV
                \@@_mc_handle_mc_label:e \l_@@_mc_key_label_tl
              }
            \bool_if:NF \l_@@_mc_key_stash_bool
              {
                \exp_args:NV\@@_struct_get_parentrole:nNN 
                    \g_@@_struct_stack_current_tl 
                    \l_@@_get_parent_tmpa_tl
                    \l_@@_get_parent_tmpb_tl
                 \@@_check_parent_child:VVnnN
                   \l_@@_get_parent_tmpa_tl
                   \l_@@_get_parent_tmpb_tl
                   {MC}{}
                   \l_@@_parent_child_check_tl 
                \int_compare:nNnT {\l_@@_parent_child_check_tl}<{0}
                 {
                    \prop_get:cnN 
                     { g_@@_struct_ \g_@@_struct_stack_current_tl _prop}
                     {S}
                     \l_@@_tmpa_tl
                    \msg_warning:nneee 
                     { tag } 
                     {role-parent-child} 
                     { \l_@@_get_parent_tmpa_tl/\l_@@_get_parent_tmpb_tl  } 
                     { MC~(real content) }
                     { not~allowed~
                       (struct~\g_@@_struct_stack_current_tl,~\l_@@_tmpa_tl)
                     }  
                 }    
                \@@_mc_handle_stash:e { \int_use:N \c@g_@@_MCID_abs_int }
              }
          }
        \group_end:
      }
%<*debug>
      {
        \@@_debug_mc_begin_ignore:n { #1 }
      }
%</debug>
  }
%<*generic>
\cs_set_protected:Nn \tag_mc_end:
  {
    \@@_check_if_active_mc:T
      {
%</generic>
%<*debug>
\cs_set_protected:Nn \tag_mc_end:
  {
    \@@_check_if_active_mc:TF
      {
        \@@_debug_mc_end_insert:
%</debug>
        \@@_check_mc_if_open:
        \bool_gset_false:N \g_@@_in_mc_bool
        \tl_gset:Nn  \g_@@_mc_key_tag_tl { }
        \@@_mc_emc:
        \@@_mc_end_marks:
      }
%<*debug>
      {
        \@@_debug_mc_end_ignore:
      }
%</debug>
  }
%</generic|debug>
%    \end{macrocode}
% \end{macro}

%
% \subsection{Keys}
% Definitions are different in luamode.
% |tag| and |raw| are expanded as |\lua_now:e| in lua does it too and
% we assume that their values are safe.
% \begin{macro}
%  {
%   tag (mc-key),
%   raw (mc-key),
%   alt (mc-key),
%   actualtext (mc-key),
%   label (mc-key),
%   artifact (mc-key)
%  }
%    \begin{macrocode}
%<*generic>
\keys_define:nn { @@ / mc }
  {
    tag .code:n = % the name (H,P,Span) etc
      {
        \tl_set:Ne   \l_@@_mc_key_tag_tl { #1 }
        \tl_gset:Ne  \g_@@_mc_key_tag_tl { #1 }
      },
    raw  .code:n =
      {
        \tl_put_right:Ne \l_@@_mc_key_properties_tl { #1 }
      },
    alt .code:n      = % Alt property
      {
        \str_set_convert:Noon
          \l_@@_tmpa_str
          { #1 }
          { default }
          { utf16/hex }
        \tl_put_right:Nn \l_@@_mc_key_properties_tl { /Alt~< }
        \tl_put_right:No \l_@@_mc_key_properties_tl { \l_@@_tmpa_str>~ }
      },
    alttext .meta:n = {alt=#1},
    actualtext .code:n      = % ActualText property
      {
        \tl_if_empty:oF{#1}
         {
           \str_set_convert:Noon
             \l_@@_tmpa_str
             { #1 }
             { default }
             { utf16/hex }
           \tl_put_right:Nn \l_@@_mc_key_properties_tl { /ActualText~< }
           \tl_put_right:No \l_@@_mc_key_properties_tl { \l_@@_tmpa_str>~ }
         }  
      },
    label .tl_set:N        = \l_@@_mc_key_label_tl,
    artifact .code:n       =
      {
        \exp_args:Nne
          \keys_set:nn
            { @@ / mc }
            { __artifact-bool, __artifact-type=#1 }
      },
    artifact .default:n    = {notype}
  }
%</generic>
%    \end{macrocode}
% \end{macro}
% \end{implementation}
% \PrintIndex