etoctagging.tex

\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[hscale=0.66,vscale=0.75]{geometry}
\usepackage[scaled=.96,helvratio=0.9270833]{newtxtext}
\usepackage[scaled=.96,zerostyle=b,straightquotes]{newtxtt}
\usepackage{clara}
\makeatletter
\def\bfseries@rm{bx}
\def\mdseries@rm{m}
\makeatother

\AtBeginDocument{%
    \renewcommand{\familydefault}{\sfdefault}%
    \rmfamily
}

\usepackage{xspace}
\usepackage[dvipsnames,svgnames]{xcolor}
%\usepackage{graphicx}
\usepackage[inline]{enumitem}
\usepackage{setspace}
\usepackage{hyperref}
\hypersetup{%
  %linktoc=all,%
  breaklinks=true,%
  colorlinks,%
  linkcolor=RoyalBlue,% Orchid
  urlcolor=OliveGreen,%
  pdfauthor={Jean-François B.},% on peut y aller maintenant avec ç en 2022...
  pdftitle={WIP tagging with the etoc package},%
  pdfsubject={Tables of contents with LaTeX},%
  pdfkeywords={LaTeX, table of contents},%
  pdfstartview=FitH,%
  %%pdfpagemode=UseOutlines,
}
\usepackage{colorframed}% fix color issues with framed.sty (JFB 2022)
\colorlet{shadecolor}{gray!10}
\usepackage{centeredline}% custom macro now in public package

\DeclareRobustCommand\csa [1]
                {{\ttfamily\hyphenchar\font45 \char`\\ #1}}

% the real \csb is much more sophisticated... see etoc.dtx
\def\csb#1{\textcolor{RoyalBlue}{\csa{#1}}}

\newcommand\etoc{%
        \texorpdfstring{{\color{joli}\ttfamily\bfseries etoc}}{etoc}\xspace}
\newcommand\toc{\csb{tableofcontents}\xspace}
\newcommand\localtoc{\csb{localtableofcontents}\xspace}
\definecolor{joli}{RGB}{225,95,0}

\DeclareRobustCommand\ctanpkg[1]
      {\texorpdfstring{\href{https://ctan.org/pkg/#1}{#1}}{#1}}

\usepackage{doc}[=v2]
\MakeShortVerb{\|}
\providecommand\marg[1]{%
  {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
\providecommand\oarg[1]{%
  {\ttfamily[}\meta{#1}{\ttfamily]}}
\providecommand\parg[1]{%
  {\ttfamily(}\meta{#1}{\ttfamily)}}

\nonfrenchspacing

\begin{document}

(in the real document, the \textcolor{RoyalBlue}{blue} colored words are
doubly hyperlinked to their user manual definition and to their source code definition)

\onehalfspacing

\section{(WIP) Tagging}
\label{etoctaggingon}
\label{etoctaggingoff}
\label{etoctagginginlineoff}
\label{etoctagstartTOCcontents}
\label{etocthetocitembegintag}
\label{etoctagReference}
\label{etoctagLbl}
\label{etocthetocitemendtag}
\label{etoctagfinishTOCcontents}

For some years upstream \LaTeX{} maintainers have been engaged into a
``\LaTeX{} Tagged PDF'' project to enable automatic tagging of PDF documents
produced via \LaTeX, see the relevant entries in
\centeredline{\url{https://latex-project.org/news/latex2e-news/ltnews.pdf}}
and a general overview in this 2020 paper
\centeredline{\url{https://www.latex-project.org/publications/2020-FMi-TUB-tb129mitt-tagpdf.pdf}}
See also further relevant articles in \href{https://tug.org/tugboat}{TUGboat}.

This means that there are ongoing kernel (and \ctanpkg{hyperref}) changes
which have to be taken into account by \etoc to not be broken, or cause a
broken PDF structure, once the user activates the feature, currently via usage
of suitable \csa{DocumentMetadata} keys, cf.\@ above documentation.

\begingroup\colorlet{shadecolor}{red!10}
\begin{shaded}
The author has neither the time nor the resources nor the appropriate tools to
do any kind of testing beyond the most basic by himself.

Besides he is mostly ignorant attow about tagging related matters.
\end{shaded}
\endgroup

At this time of development (1.2e-dev 2024/01/12) the following holds:
\begin{itemize}
\item A document using \etoc only for its \localtoc et al.\@ should provide as
  good-quality tagging regarding tables of contents (inclusive of local lists
  of figures/tables) as kernel \LaTeX{} does (for the latter for the sole TOC
  of the document) as \etoc left in compatibility mode hands over the
  typesetting of the TOC lines entirely to the kernel code.  The global
  ``display'' aspects (the title of the TOC, sometimes one may wish also to
  add some rule after the TOC) via \csb{etocsettocstyle} do not involve the
  TOC-related kernel hooks at all.  If they use for example \csa{section*} the
  tagging will be from the upstream additions to that command.  If not using
  such upstream commands, perhaps user will need to add tagging code using
  \ctanpkg{tagpdf} interface.

\item Simple custom user line styles done via \csb{etocsetlinestyle} should
  \emph{simply work}.  For example the ``fall-back line styles'' which one
  triggers via \csb{etocfallbacklines} worked out of the box with nothing
  changed, in our brief testing.  Paradoxically this was helped by the fact
  that they use core \TeX{} and not higher level \LaTeX{} and later it was
  found out that \etoc had to deactivate temporarily the kernel tagging hooks
  for \csa{parbox} and \texttt{minipage} (the list may have to be extended in
  future) which were not compatible with being employed in the midst of a
  |<TOCI>| PDF struct.  Not much testing has been done yet.  We used
  \url{https://ngpdf.com} to check the structure tree and the HTML
  conversions. Both looked fine in general but we examined very few
  examples.

  It should be noted here that the approach so far is that the entire contents
  of each toc line (i.e. data from a single line from the \texttt{.toc} file)
  will be tagged globally as one |<Reference>|, and everything except
  \csb{etocname}, \csb{etocnumber} and \csb{etocpage} are handled as
  artifacts.  Each of the three stops the artifact, does its job, then
  restarts an artifact marked content.

\item Advanced usages of \etoc's \toc and \localtoc which serve only as
  parsers of the \texttt{.toc} data to construct some structure which is then
  displayed \emph{later}, for example as a
  \href{https://ctan.org/pkg/tikz}{TikZ} picture, have been tested and
  sometimes been made to work.  But in contrast to standard usage of \etoc for
  which all efforts has been made for existing document to work \emph{as is},
  with no modification at all, here the more advanced tricky ways will require
  special mark-up to be added by the user.  Check the
  \href{https://github.com/jfbu/etoc/test_issues}{test\_issues} sub-directory
  at the \href{https://github.com/jfbu/etoc}{dev repo} for examples of use:
  \begin{itemize}
    \item \csb{etoctagstartTOCcontents}
    \item \csb{etocthetocitembegintag}
    \item \csb{etoctagReference}
    \item \csb{etoctagLbl}
    \item \csb{etocthetocitemendtag}
    \item \csb{etoctagfinishTOCcontents}
  \end{itemize}
\end{itemize}

\begingroup\colorlet{shadecolor}{red!10}
\begin{shaded}
  All user interface is to be considered currently unstable and may change at
any time.
\end{shaded}
\endgroup

\begin{description}
\item[\csb{etoctaggingon}] activates the tagging-related code from \etoc.
  This is a no-op if document has not activated tagging.  If document has
  activated tagging this is on per default.

\item[\csb{etoctaggingoff}] turns off (almost) all \etoc tagging-related code.
  This has been mentioned in the context of adding extra mark-up to let things
  such as \hyperref[sec:molecule]{The TOC as a molecule} example work.  For
  time being examples are given only at the
  \href{https://github.com/jfbu/etoc}{dev repo}.

\item[\csb{etoctagginginlineoff}] This is in case user employs
  \csb{etocsetlinestyle} to re-employ kernel macros such as
  \csa{@dottedtocline} or \csa{l@section}, see \autoref{sec:anothercompat}: it
  tells \etoc to free \csb{etocname}, \csb{etocnumber} and
  \csb{etocpage} from contributing any tagging data by themselves, as
  this will be inserted already by the used \LaTeX{} kernel macros where
  \csb{etocname} et al. have been reinserted.  It also turns off \etoc
  added hyperlinking because the kernel \csa{@dottedtocline} or
  \csa{l@section} will originate it by themselves if tagging has been
  activated in the document.

  This command (as \csb{etoctaggingoff}) is supposed to be used right
  before \toc or \localtoc.  It may (untested) also be used from inside
  the \marg{start} part of \csb{etocsetlinestyle} for
  a given sectioning name, it this is the only level using the \LaTeX{}
  kernel macros as per \autoref{sec:anothercompat}.  Then the
  \marg{finish} part may use \csb{etoctaggingon}.

  There is no \csa{etoctagginginlineon}, use \csb{etoctaggingon}.

\end{description}

\section{Another compatibility mode}
\label{sec:anothercompat}

mock target for copied-pasted above text.
\end{document}