-
Notifications
You must be signed in to change notification settings - Fork 0
/
etoctagging.tex
204 lines (175 loc) · 8.24 KB
/
etoctagging.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
\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}