Debian Codegraph @

texmf-dist/source/latex/etoc/etoc.dtx

raw
1 % -*- coding: utf-8; time-stamp-format: "%02d-%02m-%:y at %02H:%02M:%02S %Z" ; time-stamp-active: nil -*-
2 % N.B.: this dtx file does NOT use \DocInput. It does NOT prefix the user
3 % manual part with percent characters.
4 %<*none>
5 \def\etocdtxtimestamp {Time-stamp: <04-05-2026 at 21:30:53 CEST>}%
6 %</none>
7 %<*!readme>
8 %%
9 %% Package: etoc
10 %% Version: 1.2e
11 %% License: LPPL 1.3c
12 %% Copyright (C) 2012-2023, 2026 Jean-Francois B.
13 %% (jfbu on GitHub)
14 %</!readme>
15 %<*none>
16 \def\etocpkgdate {2026/05/04}
17 \def\etocdocdate {2026/05/04}
18 \def\etocpkgversion {1.2e}
19 \def\etocpkgdescription {Completely customisable TOCs (JFB)}
20 %% Formerly this etoc.dtx also included source for a German translation
21 %% etoc-DE.pdf. But all additions since April 2015 had been only in English.
22 %% Since 1.09f of 2022/08/30 etoc-DE.pdf is not produced anymore and the
23 %% existing translated sections have been removed from this etoc.dtx.
24 % Definition of \etocLicense
25 % --------------------------
26 \begingroup
27 \long\def\firstofone #1{#1}\catcode1=14\catcode2=0
28 \catcode`\%=12\catcode`\_=12\endlinechar13\catcode13=13 ^^A
29 \catcode32=13\catcode`\\=12^^Brelax^^A
30 ^^Bfirstofone{^^Bendgroup^^Bdef^^BetocLicense^^A
31 {% Package: etoc
32 % Version: 1.2e
33 % License: LPPL 1.3c
34 % Copyright (C) 2012-2023, 2026 Jean-Francois Burnol <jfbu at free dot fr>
35 %
36 % This Work may be distributed and/or modified under the
37 % conditions of the LaTeX Project Public License, in its
38 % version 1.3c. This version of this license is in
39 % http://www.latex-project.org/lppl/lppl-1-3c.txt
40 % and the latest version of this license is in
41 % http://www.latex-project.org/lppl.txt
42 % and version 1.3 or later is part of all distributions of
43 % LaTeX version 2005/12/01 or later.
44 %
45 % The Author of this Work is:
46 % Jean-Francois Burnol <jfbu at free dot fr>
47 %
48 % This Work consists of the main source file etoc.dtx and the derived
49 % files etoc.sty, etoc.tex, etoc.pdf, etoc.dvi, README.md.
50 %
51 % Running etex (or latex or pdflatex) on etoc.dtx extracts etoc.sty,
52 % etoc.tex and README.md. See README.md for further instructions.
53 }}%
54 \bgroup\catcode2 0 \catcode`\\ 12 ^^Biffalse
55 %</none>
56 %<*readme>
57 <!-- -->
58
59 Source: etoc.dtx (1.2e)
60 Author: Jean-Francois Burnol
61 Summary: Completely customisable TOCs
62 License: LPPL 1.3c
63 Copyright (C) 2012-2023, 2026 Jean-Francois Burnol.
64 <jfbu at free dot fr>
65 Repository: https://github.com/jfbu/etoc
66 Bug tracker: https://github.com/jfbu/etoc/issues
67
68 ABSTRACT
69 ========
70
71 With `etoc` loaded, `\tableofcontents` can be used multiple times and
72 an added command `\localtableofcontents` allows to typeset "local"
73 tables of contents, i.e. having their scope limited to the last
74 sectioning command encountered.
75
76 No auxiliary file is used additionally to the standard `.toc` file.
77 Release 1.2 provides **experimental** additions `\locallistoffigures` and
78 `\locallistoftables` which also use only the `.toc` file.
79
80 Such local TOCs or "Lists Of" typically need to adopt a "display
81 style" (i.e. the way the title is rendered, whether it should add
82 itself an entry in the `.toc` file, ...) somewhat distinct from the
83 global TOC. The release 1.2 default adapts automatically the titles
84 of local TOCs to their depths in the sectioning hierarchy. Should the
85 need arise to customize such "display style", full control is allowed
86 by package commands.
87
88 Regarding how the individual "contents lines" are handled, here again
89 complete control is given to the user to define from the ground-up how
90 to use the *name*, *number*, and *page number* for each entry,
91 according to their "levels" (i.e. part, chapter, section, subsection,
92 ...). As this requires some LaTeX fluency, many examples which can
93 serve as starting points are attached to the PDF documentation as
94 extractible files.
95
96 Loading `etoc` per itself modifies nothing to "contents lines"
97 rendering from the class default or changes from other packages. But
98 full usage of the package allows spectacular effects such as displaying
99 TOCs as trees or mind maps.
100
101
102 INSTALLATION
103 ============
104
105 For manual installation do `etex etoc.dtx` to extract files then move
106 `etoc.sty` to a place where TeX can find it.
107
108 etoc.sty -> TDS:tex/latex/etoc/etoc.sty
109 etoc.dtx -> TDS:source/latex/etoc/etoc.dtx
110 etoc.pdf -> TDS:doc/latex/etoc/etoc.pdf
111 README.md -> TDS:doc/latex/etoc/README.md
112
113 To produce `etoc.pdf` run pdflatex on the extracted file `etoc.tex`
114 sufficiently many times (`latexmk -pdf etoc` is recommended).
115
116
117 LICENSE
118 =======
119
120 This Work may be distributed and/or modified under the
121 conditions of the LaTeX Project Public License, in its
122 version 1.3c. This version of this license is in
123
124 > <http://www.latex-project.org/lppl/lppl-1-3c.txt>
125
126 and the latest version of this license is in
127
128 > <http://www.latex-project.org/lppl.txt>
129
130 and version 1.3 or later is part of all distributions of
131 LaTeX version 2005/12/01 or later.
132
133 The Author of this Work is Jean-Francois Burnol <jfbu at free dot fr>
134
135 This Work consists of the main source file etoc.dtx and the derived files
136 etoc.sty, etoc.tex, etoc.pdf, etoc.dvi.
137
138
139 RECENT CHANGES
140 ==============
141
142 - `1.2e 2026/05/04` compatibility hotfix with `hyperref v7.01q`
143
144 - `1.2d 2023/10/29` bugfix
145
146 - `1.2c 2023/10/28` compatibility hotfix with `hyperref v7.01c`
147
148 - `1.2b 2023/07/01` bugfix, docs
149
150 - `1.2a 2023/05/01` `deeplevels` option, removal of the requirement of
151 a recent LaTeX
152
153 - `1.2 2023/03/01` *experimental* `\locallistoffigures` and
154 `\locallistoftables`, automatic choice of level by `localtableofcontents`
155 adapted to its location inside the document hierarchy, options `toctotoc`,
156 `localtoctotoc`, `locallottotoc`, `localloftotoc`, `ouroboros`.
157 Compatibility with `tocbibind` package, too.
158
159 %</readme>
160 %<*tex>-------------------------------------------------------------------------
161 %% To produce the documentation etoc.pdf with source code included:
162 %% latexmk -pdf etoc.tex
163 %% (or sufficiently many times pdflatex etoc.tex)
164 %% For customizations see comments and classe options below.
165 \tracinglostchars3
166 \chardef\Withdvipdfmx 0 % replace 0 by 1 for using latex+dvipdfmx
167 \chardef\NoSourceCode 0 % replace 0 by 1 for the doc *without* the source code
168 \NeedsTeXFormat{LaTeX2e}
169 \ProvidesFile {etoc.tex}[Driver for etoc documentation]%
170 \PassOptionsToClass {a4paper,fontsize=10pt,twoside}{scrartcl}
171 \PassOptionsToPackage {ngerman,english}{babel}
172 \input etoc.dtx
173 %%% Local Variables:
174 %%% mode: latex
175 %%% End:
176 %</tex>-------------------------------------------------------------------------
177 %<*none>------------------------------------------------------------------------
178 ^^Bfi^^Begroup
179 %
180 \chardef\noetex 0
181 \ifx\numexpr\undefined\chardef\noetex 1 \fi
182 \ifnum\noetex=1 \chardef\extractfiles 0 % extract files, then stop
183 \else
184 \ifx\ProvidesFile\undefined
185 \chardef\extractfiles 0 % etex etc.. on etoc.dtx, only file extraction.
186 \else % latex/pdflatex on etoc.tex or on etoc.dtx
187 \ifx\Withdvipdfmx\undefined
188 % latex/pdflatex run is on etoc.dtx
189 \chardef\extractfiles 1 % 1 = extract files and typeset manual, 2 = only typeset
190 \chardef\Withdvipdfmx 0 % 0 = pdflatex or latex+dvips, 1 = dvipdfmx
191 \chardef\NoSourceCode 1 % 0 = include source code, 1 = do not
192 \NeedsTeXFormat {LaTeX2e}%
193 \PassOptionsToClass {a4paper,fontsize=10pt,twoside}{scrartcl}%
194 \PassOptionsToPackage {ngerman,english}{babel}%
195 \else % latex run is on etoc.tex
196 \chardef\extractfiles 2 % do not extract files, only typeset
197 \fi
198 \ProvidesFile{etoc.dtx}%
199 [etoc source and documentation (\etocdtxtimestamp)]%
200 \fi
201 \fi
202 \ifnum\extractfiles<2 % extract files
203 \def\MessageDeFin{\newlinechar10 \let\Msg\message
204 \Msg{********************************************************************^^J}%
205 \Msg{*^^J}%
206 \Msg{* To finish the installation you have to move the following^^J}%
207 \Msg{* file into a directory searched by TeX:^^J}%
208 \Msg{*^^J}%
209 \Msg{*\space\space\space\space etoc.sty^^J}%
210 \Msg{*^^J}%
211 \Msg{* To produce the documentation with source code included execute^^J}%
212 \Msg{* latexmk -pdf etoc.tex^^J}%
213 \Msg{*^^J}%
214 \Msg{* Happy TeXing!^^J}%
215 \Msg{*^^J}%
216 \Msg{********************************************************************^^J}%
217 }%
218 \begingroup
219 \input docstrip.tex
220 \askforoverwritefalse
221 \generate{\nopreamble\nopostamble
222 \file{README.md}{\from{etoc.dtx}{readme}}%
223 \usepostamble\defaultpostamble
224 \file{etoc.tex}{\from{etoc.dtx}{tex}}%
225 \usepreamble\defaultpreamble
226 \file{etoc.sty}{\from{etoc.dtx}{package}}}%
227 \endgroup
228 \fi % end of file extraction (from etex/latex/pdflatex run on etoc.dtx)
229 \ifnum\noetex=1 % warning for README.md
230 \expandafter\def\expandafter\MessageDeFin\expandafter
231 {\MessageDeFin
232 \Msg{* warning: to get correct utf-8 encoded README.md ^^J}%
233 \Msg{* do etex etoc.dtx and not as here tex etoc.dtx ^^J}%
234 \Msg{********************************************************************^^J}}%
235 \fi
236 \ifnum\extractfiles=0 % tex/etex/xetex/etc on etoc.dtx, files extracted, stop
237 \MessageDeFin\expandafter\end
238 \fi
239 % From this point on, run is necessarily with e-TeX.
240 % Check if \MessageDeFin got defined, if yes put it at end of run.
241 \ifdefined\MessageDeFin\AtEndDocument{\MessageDeFin}\fi
242 %-------------------------------------------------------------------------------
243 % START OF USER MANUAL TEX SOURCE
244 \documentclass{scrartcl}
245
246 \makeatletter
247 %%% START OF CUSTOM doc.sty LOADING (May 21, 2022 in xint.dtx)
248 %%% (August 26, 2022 here, comments trimmed)
249 %
250 % For some legacy reason (because I started like this and it
251 % worked to my satisfaction) I had used scrdoc.cls all those
252 % years, without in fact needing most of its features.
253 %
254 % It loads ltxdoc class, from which again I need very little. On
255 % testing May 20, 2022 the upcoming LaTeX 2022-06-01 I had some
256 % problems with ltxdoc not having suitable interface for rolling
257 % back to doc=V2.
258 %
259 % ...
260 %
261 % Thus it turns out I need very little of doc.sty, and almost
262 % nothing of ltxdoc.cls and scrdoc.cls.
263 %
264 % (maybe provisory, try to see if usage of cross-hyperlinking
265 % as in sourcexint.pdf makes sense here for rendering of
266 % implementation part - loading time of etoc.pdf in viewer
267 % in increased, though. 2022/08/26)
268 %
269 % Let's load the doc=V2 version to avoid having to work around
270 % hypdoc loading interfering with my use of hyperref.
271 \ifdefined\IfFormatAtLeastTF
272 \IfFormatAtLeastTF{2022/06/01}%
273 {%
274 \IfFileExists{doc-2021-06-01.sty}%
275 {\usepackage{doc}[=v2]}%
276 % Why on earth do I lose my time doing this?
277 {\GenericError
278 {(etoc build doc)\@spaces}%
279 {etoc build error: %
280 Your LaTeX installation seems to be broken, format is\MessageBreak
281 2022-06-01 or later but `doc' package in its `v2' version\MessageBreak
282 seems to not be available. \space Will try with `doc' but if\MessageBreak
283 its `v3' is used there will be an option clash error\MessageBreak
284 regarding hyperref.}%
285 {}%
286 {Please make sure `doc' package matches your LaTeX format.}%
287 \usepackage{doc}%
288 }%
289 }%
290 {\usepackage{doc}}%
291 \else
292 \usepackage{doc}
293 \fi
294 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
295 % MACROS OF doc.sty WILL BE HACKED (2022/06/06) FOR THE IMPLEMENTATION PART
296 %
297 % First we want to turn CodelineNo into a real LaTeX counter
298 % This will spare defining an extra counter for the hyperlinks with \hyperref
299 \begingroup\let\newcount\@gobble\@definecounter{CodelineNo}\endgroup
300 % Let's now reenact the doc.sty default for \theCodeLineNo
301 \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}
302 % But as we will reset CodelineNo at each style file we need some unique id
303 \def\theHCodelineNo{\the\value{section}.\the\value{CodelineNo}}
304 % This is all for now.
305 % The further hacks are to be found after the \StopEventually (i.e. a few
306 % thousands lines down from here if you don't have access to the private
307 % sources, which is probably the case if you are not the author).
308 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
309
310 % As explained above I was formerly using scrdoc hence ltxdoc indirectly.
311 % Let's emulate here the little I appear to need from ltxdoc.cls and
312 % srcdoc.cls.
313 %
314 \AtBeginDocument{\MakeShortVerb{\|}}
315 \DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{}
316 \DeclareFontFamily{OMS}{cmtt}{\skewchar\font 48} % '60
317 \DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{}
318 \DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{}
319 \DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{}
320 \ifnum\NoSourceCode=1
321 \OnlyDescription
322 \fi
323 \CodelineNumbered
324 \EnableCrossrefs % but this will be hacked
325 % \setcounter{StandardModuleDepth}{1} % we don't use this mechanism currently
326 \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
327 \def\cmd@to@cs#1#2{\char\number`#2\relax}
328 % Here I am loading doc=v2 but formerly I was using ltxdoc via scrdoc
329 % which I dropped at release 1.4l (2022-05-29) and without much
330 % thinking I had kept this.
331 \DeclareRobustCommand\cs[1]{\texttt{\bslash#1}}
332 % As I may have the * active, or macro names with _ or ^, I should
333 % add \detokenize. But see below for a redefinition anyhow.
334 %
335 % More urgent is that I am also using hyperref and this definition gives wrong
336 % bookmarks if \cs is used in section titles. As I had very very few usags of
337 % \cs in the whole of xint.dtx, it took me a while to realize the problem
338 % here. Turns out that doc=v3 by default loads hypdoc which includes this
339 % configuation for hyperref compatibility:
340 \AtBeginDocument{%
341 \pdfstringdefDisableCommands{\def\cs#1{\textbackslash\detokenize{#1}}}%
342 }%
343 % As I have not loaded hyperref yet I must delay it to AtBeginDocument.
344 \providecommand\marg[1]{%
345 {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
346 \providecommand\oarg[1]{%
347 {\ttfamily[}\meta{#1}{\ttfamily]}}
348 \providecommand\parg[1]{%
349 {\ttfamily(}\meta{#1}{\ttfamily)}}
350 % \@addtoreset{CodelineNo}{part}% No need for this here
351 % \def\partname{File}% \partname is "fixed" somewhere further down anyhow
352 % No need for this, anyhow I don't build the indices
353 % \gdef\codeline@wrindex#1{\if@filesw
354 % \begingroup
355 % \let\protect\noexpand
356 % \immediate\write\@indexfile
357 % {\string\indexentry{#1}%
358 % {\filesep\number\c@CodelineNo}}%
359 % \endgroup\fi}
360 % \let\filesep\@empty
361
362 % There is very little we seem to need from the scrdoc extras: page geometry
363 % is set by geometry package and a4paper option from xint.tex file. So it
364 % seems I only need the hologo loading:
365 \usepackage{hologo}
366 \DeclareRobustCommand*{\eTeX}{\hologo{eTeX}}%
367 \DeclareRobustCommand*{\LuaTeX}{\hologo{LuaTeX}}%
368 %
369 \makeatother
370 %%% end of ltxdoc+srcdoc emulation from June 2022 xint.dtx,
371 %%% copied over almost verbatim to etoc.dtx on 2022/08/26.
372 %%% See after \StopEventually for doc.sty hacks.
373
374 \makeatletter
375 % pour maintenir les % en début de ligne dans les blocs verbatim
376 \let\original@check@percent\check@percent
377 \let\check@percent\relax
378 \makeatother
379
380
381 % We got sensible result with attachfile or attachfile2
382 % only with pdflatex. So this is remnant of earlier
383 % times when etoc.pdf was produced via latex+dvipdfmx
384
385 \usepackage{ifpdf}
386 \ifpdf\chardef\Withdvipdfmx 0 \fi
387
388 \makeatletter
389 \ifnum\Withdvipdfmx=1
390 \@for\@tempa:=hyperref,bookmark,graphicx,xcolor,pict2e\do
391 {\PassOptionsToPackage{dvipdfmx}\@tempa}
392 %
393 \PassOptionsToPackage{dvipdfm}{geometry}
394 \PassOptionsToPackage{bookmarks=true}{hyperref}
395 \PassOptionsToPackage{dvipdfmx-outline-open}{hyperref}
396 \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
397 %
398 \def\pgfsysdriver{pgfsys-dvipdfm.def}
399 \else
400 \PassOptionsToPackage{bookmarks=true}{hyperref}
401 \fi
402 \makeatother
403
404 \usepackage[T1]{fontenc}
405 \usepackage[hscale=0.66,vscale=0.75]{geometry}
406
407 % Some problems with headers
408 \pagestyle{headings}
409 % \sectionmark uses \markboth in twoside but
410 % with an empty right mark! As a result if a section starts
411 % on an odd page, it does not appear in the header mark.
412 % Perhaps there was a subsection of 3 lines on that page
413 % and it is the subsection which decides what is in the header.
414
415 % Some custom \sectionmark to get headers more to my taste.
416 % But it is hard to find algorithm giving satisfaction in all cases.
417
418 \makeatletter
419 \renewcommand *{\sectionmark }[1]{%
420 % Que c'est pénible cette syntaxe \markboth/\markright de LaTeX !
421 % Pourquoi est-ce que \markright n'a pas été définie comme #1#2-> truc avec #2 ??
422 \if@twoside \expandafter \markboth \else
423 \expandafter\expandafter\expandafter \markright\expandafter \@firstoftwo
424 \fi
425 {\MakeMarkcase {\Ifnumbered {section}{\sectionmarkformat }{}#1}}%
426 {\MakeMarkcase {\Ifnumbered {section}{\sectionmarkformat }{}#1}}%
427 }
428
429 % Par ailleurs je vais remplacer \firstmark par \botmark dans \rightmark
430 % dont la définition par défaut est :
431
432 % \rightmark:
433 % macro:->\expandafter \@rightmark \firstmark \@empty \@empty
434
435 \renewcommand*\rightmark{\expandafter\@rightmark\botmark \@empty\@empty}
436 % Au passage l'output de latexdef à un : supplémentaire bizarre
437 % $ latexdef botmark
438 %
439 % \botmark:
440 % \botmark:
441 %
442
443 % Néanmoins pour les \part il ne faut clairement pas utiliser \botmark
444 % Tous mes \part sont après un \clearpage explicite
445 % Je crois que le plus simple est encore de faire ceci:
446 \def\ps@mypartheadings{%
447 \ps@headings
448 \let\@evenhead\@empty
449 \let\@oddhead\@empty
450 }
451
452 % peut-être serait-ce mieux de mettre le \thispagestyle après mon \clearpage,
453 % explicitement dans la source
454 \def\part{\thispagestyle{mypartheadings}\scr@startpart {part}}
455 \makeatother
456
457 % pour les environnements verbatim, 2013
458 % updated 2023 (setspace) and 2024 (usage of newtxtt nomono font
459 % with modified \fontdimen's (see below), it has \hyphenchar45
460 \def\MacroFont{\ttfamily\small\setstretch{1}}
461
462
463 %----
464 % better \verb pour doc.
465 % 12 octobre 2013, importé de xint.dtx
466 % je rajoute pour { afin que truc{machin puisse avoir hyphénation
467 % retire \leavemmode, pas nécessaire pour emploi ici
468
469 % NOTE 9 mars 2015. J'ai depuis une version plus aboutie dans xint.dtx
470 % mais je laisse ici tel quel.
471
472 \def\MicroFont{\ttfamily\hyphenchar\font45 }
473 % modif de \do@noligs: \char`#1} --> \char`#1 }
474 \makeatletter
475 \def\do@noligs #1%
476 {%
477 \catcode `#1\active
478 \begingroup \lccode `\~=`#1\relax
479 \lowercase {\endgroup \def ~{\kern \z@ \char `#1 }}%
480 }%
481 \def\dobackslash
482 {%
483 \catcode92 \active
484 \begingroup \lccode `\~=92\relax
485 \lowercase {\endgroup \def ~{\kern \z@ \char 92 }}%
486 }%
487 \def\dobraces
488 {%
489 \catcode123 \active
490 \begingroup \lccode `\~=123\relax
491 \lowercase {\endgroup \def ~{\hskip \z@\@plus.1pt\@minus.1pt
492 \char 123 }}%
493 \catcode125 \active
494 \begingroup \lccode `\~=125\relax
495 \lowercase {\endgroup \def ~{\char 125 \hskip \z@\@plus.1pt\@minus.1pt }}%
496 }%
497 \def\verb
498 {%
499 \relax \ifmmode\hbox\else\leavevmode\null\fi
500 \bgroup \MicroFont
501 \let\do\do@noligs \verbatim@nolig@list
502 \let\do\@makeother \dospecials
503 \catcode32 10
504 \dobackslash \dobraces \makestarlowast
505 \@jfverb
506 }%
507 \def\@jfverb #1{\catcode`#1\active
508 \lccode`\~`#1\lowercase{\def~{\egroup\unskip}}}%
509 % (\unskip ajouté le 14 octobre)
510 % \lowast est défini plus loin
511 \begingroup
512 \lccode`\~=`\*
513 \lowercase{%
514 \endgroup
515 \def\makestarlowast {\catcode`\*\active\let~\lowast}}%
516 \makeatother
517 %
518
519 %----
520 % privatecodecomments environment
521 % transferred 2024/01/11 from xint, some things may not make real sense here
522 \newenvironment{privatecodecomments}
523 {\par \textbf{\textcolor{red}{COMMENTAIRES PRIVÉS.}}\par
524 % inutile ici car déjà dans un hook à macrocode \makestarlowast
525 \color{privatecodecommentscolor}%
526 \begingroup\lccode`\~`\%\lowercase{\endgroup\let~\lverbpercent}%
527 \catcode`\%\active}
528 {\par \textbf{\textcolor{red}{FIN DES COMMENTAIRES PRIVÉS.}}\par}
529
530 \makeatletter
531 \long\def\xintdothis #1#2\xintorthat #3{\fi #1}
532 \let\xintorthat \@firstofone
533
534 % transferred with trimming from xint, some things may still not make real
535 % sense here
536 \def\lverbpercent {\catcode32\active\lverbpercenta}%
537 \def\lverbpercenta #1{%
538 \if\@sptoken\detokenize{#1}%
539 \catcode32 10 %
540 \fi
541 % The %! mark-up is used for private things which are trimmed by the
542 % build-script out of the dtx.
543 \if!\detokenize{#1}\xintdothis{%
544 \lverbpercentb
545 }\fi
546 \xintorthat{\lverbpercentb{#1}}%
547 }%
548 \def\lverbpercentb#1{%
549 \if\@sptoken\detokenize{#1}\xintdothis{\catcode32 10 }\fi
550 % Special mark-up after % to control linewrap
551 % %- says to start a new paragraph
552 \if-\detokenize{#1}\xintdothis{\par #1}\fi
553 % %( start an obeylines+obeyspaces context
554 \if(\detokenize{#1}\xintdothis{\par\bgroup\myobeyspaces\obeylines}\fi
555 \if:\detokenize{#1}\xintdothis{}\fi
556 % I don't remember why this, it seems I want to kill next indentation
557 % after the obeylines context
558 \if)\detokenize{#1}\xintdothis{\egroup\everypar{\hskip-\parindent\everypar{}}}\fi
559 % Introduce a \par token if we have two empty commented-out lines
560 % Or if we have a % at the end of the input line
561 \ifx#1\lverbpercent\xintdothis{\catcode32 10 \par #1}\fi
562 \xintorthat{\catcode32 10 #1}%
563 }
564 \makeatother
565
566 %%%% FONT CONFIGURATION
567
568 \usepackage[scaled=.96,helvratio=0.9270833]{newtxtext}
569 \usepackage[scaled=.96,zerostyle=b,straightquotes,nomono]{newtxtt}
570 % nomono is a trick to simply allow hyphenation. But I still want
571 % no interword space for macrocode rendering.
572 %
573 % straightquotes allows to not have to apply here our former workaround to
574 % latex3/latex2e#953, latex3/latex2e#1230 (which have been fixed in dev early
575 % January 2024, so in future \usepackage{upquote} would be enough)
576
577 \makeatletter
578 % Attention that this is only for normalsize
579 \AtBeginDocument{\setbox0\hbox{\ttfamily\fontdimen2\font=5.04002pt
580 \fontdimen3\font=\z@
581 \fontdimen4\font=\z@
582 \fontdimen7\font=\z@
583 \small \fontdimen2\font=4.53603pt
584 \fontdimen3\font=\z@
585 \fontdimen4\font=\z@
586 \fontdimen7\font=\z@}%
587 }
588 \makeatother
589
590
591 % Use of Clara (January 2024)
592 % But it seems I noted somewhere I did not like so much this font.
593 % Sticking with it for 1.2e hotfix release on 2026/05/04.
594 \usepackage{clara}
595 \makeatletter
596 \def\bfseries@rm{bx}
597 \def\mdseries@rm{m}
598 \makeatother
599 % cf https://github.com/latex3/latex2e/issues/1240
600
601 \AtBeginDocument{%
602 \renewcommand{\familydefault}{\sfdefault}%
603 \rmfamily
604 }
605
606 \usepackage{xspace}
607 % added svgnames 2022/08/26 on occasion of transfer from xint colouring scheme
608 \usepackage[dvipsnames,svgnames]{xcolor}
609 \usepackage{graphicx}
610 \usepackage[inline]{enumitem}
611 \usepackage{array}
612 \usepackage{longtable}
613
614 \definecolor{joli}{RGB}{225,95,0}
615 \definecolor{JOLI}{RGB}{225,95,0}
616 \definecolor{BLUE}{RGB}{0,0,255}
617 \colorlet{niceone}{green!35!blue!75}
618 \colorlet{optioncolor}{Maroon}
619
620 % These colours mostly used only after stopeventually
621 \definecolor{etocnamecolor}{RGB}{228,57,0}
622 \colorlet{verbcolor}{Maroon}
623 \colorlet{privatecodecommentscolor}{cyan}
624 \colorlet{macrocodecommentcolor}{gray}
625 \colorlet{macrocodenewmacrocolor}{verbcolor}
626 \colorlet{macrocodelinktouserdoccolor}{etocnamecolor}% and bold face
627 \colorlet{macrocodelinktosectioncolor}{DarkBlue}% and bold face
628 \colorlet{macrocodelinktocodelinecolor}{Blue}
629 \colorlet{macrocodenoncscolor}{Green}
630
631 \usepackage {babel} % ngerman and english options have been passed to babel
632 \AtBeginDocument {%
633 % this may be obsolete as I don't use scrdoc or ltxdoc classes anymore
634 \renewcommand\partname{Part}%
635 \addto\captionsenglish {\renewcommand\partname{Part}}
636 }
637
638 \usepackage{tikz}
639 \usetikzlibrary{trees} % added for "cyclic" grow function 2013/03/02
640 \usepackage{forest}[2015/05/04]
641 % switched from tikz-qtree to forest 2013/09/09
642 % No problem with hyperlinks then, contrarily to tikz-qtree.
643
644
645
646 % 12 mars 2015, pour 1.08a, see http://tex.stackexchange.com/a/232584/4686
647 \usetikzlibrary{mindmap}
648 % Vendredi 13 mars 2015 à 18:10:40
649 % POUR LA TOC DE TITLE PAGE
650 \usepackage{eso-pic}
651 % Le package picture dit qu'il est obsolète (2026/05/04). Croyons-le
652 %\usepackage{picture}
653 \usepackage{ragged2e}
654 % setspace usage added February 2023... (to accompany change of document font)
655 % It must be loaded before hyperref
656 \usepackage{setspace}
657
658 \usepackage{hyperref}% I had used [pdfencoding=pdfdoc] until 1.09f
659 \hypersetup{%
660 linktoc=all,%
661 %%linktoc=none,% STRESS TEST OF 1.1a
662 %% bookmarksdepth=3,% (not needeed anymore now, 1.07g)
663 breaklinks=true,%
664 colorlinks,%
665 linkcolor=RoyalBlue,% Orchid
666 urlcolor=OliveGreen,%
667 pdfauthor={Jean-François Burnol},% on peut y aller maintenant avec ç en 2022...
668 pdftitle={The etoc package},%
669 pdfsubject={Tables of contents with LaTeX},%
670 pdfkeywords={LaTeX, table of contents},%
671 pdfstartview=FitH,%
672 %%pdfpagemode=UseOutlines,% commented-out for 1.09h
673 }
674 % added usage of package bookmark 2013/10/10
675 \usepackage{bookmark}
676 \usepackage{varioref}
677
678 % Vendredi 16 septembre 2016
679 % pour rendre accessibles les exemples
680 % Fait package filecontentsdef le Samedi 17.
681 \usepackage{filecontentsdef}
682
683 %\ifnum\Withdvipdfmx=1
684 %% Attempts to use attachfile2 for latex+dvipdfmx fail:
685 %%
686 %% - 2016: (I did not record which version of attachfile2 was used)
687 %% (this \the\value comment presumably refers to how I was using
688 %% \attachfile at that time)
689 %%
690 %% I have an issue that with \thesubsection or \the\value{section} in code
691 %% snippet filename, the file is not correctly attached, it appears in the
692 %% pdf interface but with a wrong filename and one can not obtain the file
693 %% from the pdf (tested on Acrobat Reader 11 Vendredi 16 septembre 2016).
694 %%
695 %% - 2023 (January, 1.2, with 2019/11/26 v2.11):
696 %%
697 %% I had to comment-out the mimetype, created and modified key settings.
698 %% Then latex run passed but dvipdfmx complained with a dozen of
699 %% dvipdfmx:warning: Object @atfi_obj_67 used, but not defined. Replaced by null.
700 %% The Adobe Reader (same as in 2016...) Attachment panel lists a dozen of
701 %% Inconnu in section 39
702 %% lines clearly matching the dvipdfmx warnings.
703 %%
704 %% The panel of Comments does display the list. From there or from the
705 %% Attachment panels one can recover the snippets. The «etocsnippet» name
706 %% is displayed in a strange greyed-out rendering, and one has to guess that
707 %% CTRL-click gives access to the file. (not different from pdflatex route)
708 %%
709 %% I also tried with attachfile2.dtx from github at commit 660cea7 of May
710 %% 19, 2022, and the same problem with the Attachment panel was there. Only
711 %% difference I saw with attachfile2 from TL2022 was the ordering in the
712 %% Attachment panel (with TL2022 attachfile2, the «Inconnu» lines were all
713 %% grouped together).
714 %%
715 %% So I can still not go via latex+dvipdfmx in 2023. But the size reduction
716 %% which is motivation for dvipdfmx was modest in this renewed testing,
717 %% roughly 740Kb vs 840Kb with pdflatex.
718 %%
719 % \usepackage[dvipdfmx]{attachfile2}
720 %% MEMO: I use \widthof in Linked list of the main package commands in
721 %% a \makebox, since August 30, 2022, for 1.09f release.
722 %% This requires calc, which is loaded only by attachfile among
723 %% used packages; and calc is not loaded by attachfile2.
724 % \usepackage{calc}
725 %\else
726 \usepackage{attachfile}% no op with dvipdfmx
727 %\fi
728 %
729 \def\CEST{+02'00'}\def\CET{+01'00'}
730 \def\ExtractDateStamp #1<#2-#3-#4 at #5:#6:#7 #8>%
731 {D:#4#3#2#5#6#7\csname#8\endcsname}
732 \edef\DateForSamples {\expandafter\ExtractDateStamp\etocdtxtimestamp}
733 \attachfilesetup{%icon=Paperclip,% attention Paperclip pas PaperClip !!
734 mimetype=application/x-tex,
735 %appearance=false,
736 % These comments and next are from November 19, 2022
737 % author={Jean-François Burnol},
738 % author={\pdfescapestring{Jean-François Burnol}},
739 % TODO: resolve this at some point in my future life
740 author={Jean-Francois Burnol},
741 % doing this has fixed the date shown in Acrobat annotation panel
742 % but now some strange seemingly unrelated date is printed in
743 % the "Comment panel"
744 created=\DateForSamples,
745 modified=\DateForSamples,
746 % allright this one next sets the dates shown in the "Comment Panel",
747 % whereas the above two (or only modified) impacts the panel of
748 % annotations on the left in my (very old) Adobe Reader. Not yet
749 % tested with evince
750 date=\DateForSamples
751 }%
752
753 \colorlet{etocsnippet}{blue}
754 \newcommand\marginattach{%
755 \noindent Depending on the PDF viewer\normalmarginpar
756 % syntaxe pénible n'y-a-t-il pas un moyen plus commode
757 % j'hésite à tester \value{page}
758 \marginpar
759 [% left
760 {\hfill
761 \textattachfile[description={in section \the\value{section}}]%
762 {etocsnippet-\snippetno.tex}%
763 {\textcolor{etocsnippet}{etocsnippet-\snippetno.tex}}%
764 }%
765 ]%
766 {% right
767 \textattachfile[description={in section \the\value{section}}]%
768 {etocsnippet-\snippetno.tex}%
769 {\textcolor{etocsnippet}{etocsnippet-\snippetno.tex}}%
770 \hfill
771 }%
772 \stepcounter{snippet},
773 a click (or CTRL-click) on the filename in the margin may allow to extract
774 it. Or check if an ``attachments'' or ``comments'' panel is available.
775 }
776 % Sadly, on non-attachement supporting viewers such as Skim.app,
777 % the filename is not even searchable : entering "etocsnippet"
778 % in the PDF viewer search form does not find the margin texts.
779
780 % But I did not want to add to the filename the section number,
781 % or perhaps even the page number (which could have been perilous
782 % and I did not want to have to test and experiment, as I have
783 % done enough for today with these code snippets).
784
785 % In Acrobat the description field gives rise to some "tooltip"
786 % display on hover, which displays the description field.
787
788 \newcounter{snippet}%[section]
789 \stepcounter{snippet}
790 \makeatletter
791 \newcommand\snippetno{%
792 \ifnum\value{snippet}<10 0\fi\the\value{snippet}%
793 %%% emulating former manual mark-up (with reset at each section) but I drop this
794 %%% \ifnum\value{snippet}>0 -\@Alph{\numexpr\value{snippet}+\@ne\relax}\fi
795 }
796 \makeatother
797
798 \usepackage{colorframed}% fix color issues with framed.sty (JFB 2022)
799 \colorlet{shadecolor}{gray!10}
800 \usepackage{centeredline}% custom macro now in public package
801 \usepackage{xinttools}% for easier construction of the doubly hyperlinked cs names
802
803 \usepackage{etoc} % (loads multicol)
804 % There is clearly a bug of \singlespacing to do this \vskip\baselineskip.
805 % What then if one goes from double to onehalf spacing? no such adjustment
806 % in \onehalfspacing? Not coherent. And caused me a lost of half an hour
807 % to first spot the problem (with "inline" TOCs first), then understand
808 % that it originated into the setspace.sty commands, then waste time
809 % canceling the hook locally and finally do this after going into checking
810 % setspace.sty.
811 \def\etocbeforetitlehook{\setstretch{1}}
812
813 % for etoc's own default line styles. <1.08b had \partname by default but this
814 % does not work well with babel+frenchb hence the default is now simply Part.
815 % Here we can use \partname as we do (did) the documentation for English or German.
816 % Careful with the customization of \partname done by scrdoc class! (obsolete remark)
817 \renewcommand{\etocpartname}{\partname}
818 % see the \AtBeginDocument with \addto\captionsngerman etc...
819
820 %--------
821 % 10 octobre 2013:
822 \AtBeginDocument{\addtocontents{toc}{\protect\hypersetup{hidelinks}}}
823
824 %--------
825 % add-ons for the new section `surprising uses of etoc' (2013/01/24)
826 % use of \the\value rather than \arabic due to paranoia in 2023.
827 \newcounter{visibletoc}
828 \renewcommand{\etocaftertitlehook}
829 {\stepcounter{visibletoc}%
830 \phantomsection
831 \etoctoccontentsline{visibletoc}{\the\value{visibletoc}}}
832 % at 1.2a \etocthemaxlevel for test of build with deeplevels option
833 \etocsetlevel{visibletoc}{\etocthemaxlevel}
834 %--------
835 % Statistics on sections and subsections in a part \thispartstats:
836 % 2 mars 2013
837 % cette version utilise des box, plutôt que des macros.
838 % mais on ne peut plus alors changer de police etc...
839
840 % 11 octobre 2013, je retire les \color{teal}.
841
842 \newsavebox\firstnamei
843 \newsavebox\firstnumberi
844 \newsavebox\lastnamei
845 \newsavebox\lastnumberi
846 \newsavebox\firstnameii
847 \newsavebox\firstnumberii
848 \newsavebox\lastnameii
849 \newsavebox\lastnumberii
850 \newcounter{mycounti}
851 \newcounter{mycountii}
852
853 \newcommand*{\thispartstatsauxi}{}
854 \newcommand*{\thispartstatsauxii}{}
855 \newcommand*{\oldtocdepth}{}
856
857 \newcommand*{\thispartstats}{%
858 \setcounter{mycounti}{0}%
859 \setcounter{mycountii}{0}%
860 \def\thispartstatsauxi{%
861 \sbox{\firstnamei}{\footnotesize\etocname}%
862 \sbox{\firstnumberi}{\footnotesize\etocnumber}%
863 \def\thispartstatsauxi{}}%
864 \def\thispartstatsauxii{%
865 \sbox{\firstnameii}{\footnotesize\etocname}%
866 \sbox{\firstnumberii}{\footnotesize\etocnumber}%
867 \def\thispartstatsauxii{}}%
868 \begingroup
869 \etocsetlinestyle{subsection}
870 {}
871 {}
872 {\thispartstatsauxii
873 \stepcounter{mycountii}%
874 \sbox{\lastnameii}{\footnotesize\etocname}%
875 \sbox{\lastnumberii}{\footnotesize\etocnumber}}
876 {}
877 \etocsetlinestyle{section}
878 {}
879 {}
880 {\thispartstatsauxi
881 \stepcounter{mycounti}%
882 \sbox{\lastnamei}{\footnotesize\etocname}%
883 \sbox{\lastnumberi}{\footnotesize\etocnumber}}
884 {{\footnotesize\itshape
885 Here are some statistics for this part: it contains \arabic{mycounti}
886 section\ifnum\value{mycounti}>1 s\fi{} and
887 \ifnum\value{mycountii}>1 \arabic{mycountii} \else no \fi
888 subsection\ifnum\value{mycountii}>1 s\fi. The name of
889 the first section is
890 ``\unhbox\firstnamei{}'' and the corresponding number is
891 ``\unhbox\firstnumberi''. The name of the last section is
892 ``\unhbox\lastnamei{}'' and its number is
893 ``\unhbox\lastnumberi''.
894 \ifnum\value{mycountii}>0 The name of
895 the first subsection is
896 ``\unhbox\firstnameii{}'' and the corresponding number is
897 ``\unhbox\firstnumberii''. The name of the last subsection is
898 ``\unhbox\lastnameii{}'' and its number is
899 ``\unhbox\lastnumberii''.\fi
900 \par}}
901 \etocinline
902 % october 10, 2013.
903 \etocsetnexttocdepth {2}%
904 \etocsettocstyle {\pdfbookmark[1]{Statistics}{\thepart.STATS}}{}
905 \localtableofcontents
906 \endgroup
907 }
908 %--------
909 % add-ons pour les TOC comme TikZ mind map, tree ou molécules
910 % hyperlinks to source code... added November 20, 2022
911 % works in sync with macrocode hacks explained after \StopEventually
912 % which were added in August 2022
913 % imported/adapted from code originally added to xint.dtx
914
915 % FINALLY, after many hesitations and great suffering with \marginpar
916 % I decide to simply divide the name into two parts and use two
917 % distinct hyperlinks, so as to not render the reading to painful.
918
919 % use a slightly different colour for second half?
920 % MEMO: we can change \ttfamily as hyperref uses a scope limiting group.
921 % Modified 2023/03/20 to devote the left two-thirds to linking to the user manual.
922 \makeatletter % for \on@line
923 \DeclareRobustCommand\csb[1]{%
924 \edef\nbforuser{\the\numexpr2*\xintLength{#1}/3}%
925 \ifcsname r@#1\endcsname
926 \hyperref[#1]{\ttfamily\hyphenchar\font45 \char`\\ \xintKeepUnbraced{\nbforuser}{#1}}%
927 \ifcsname r@etocmacro-#1\endcsname
928 \hyperref[etocmacro-#1]{\ttfamily\hyphenchar\font45 \xintTrim{\nbforuser}{#1}}%
929 \else
930 % for .toc suffixed macros
931 \ifcsname r@etocmacro-\xintTrimUnbraced{-4}{#1}\endcsname
932 \hyperref[etocmacro-\xintTrimUnbraced{-4}{#1}]{\ttfamily\hyphenchar\font45
933 \xintTrim{\nbforuser}{#1}}%
934 \else
935 % 2023/02/27 also catch non existing destinations in source code
936 {\fboxsep-\fboxrule\color{Orchid}%
937 \fbox{\ttfamily\hyphenchar\font45 \xintTrim{\nbforuser}{#1}#1}%
938 }%
939 \ifcsname r@etocname\endcsname
940 \expanded{\noexpand\AtEndDocument
941 {\noexpand\PackageError{etoc}{Pas de référence dans
942 le code à #1\on@line}%
943 {Corriger!}
944 }%
945 }%
946 \fi
947 % \hyperref[#1]{\ttfamily\hyphenchar\font45 \xintTrim{\nbforuser}{#1}}%
948 \fi
949 \fi
950 \else
951 % 1.1a, updated 2023/01/22 1.2
952 {\fboxsep-\fboxrule\color{Orchid}%
953 \fbox{\ttfamily\hyphenchar\font45 \char`\\ #1}%
954 }%
955 % make second run of compilation raise an error if macro name has been
956 % misspelled so target (in the documentation) does not exist ; but this will
957 % trigger error first time the documentation is added, one has to make
958 % one compilation after adding the label and before continuing doc edits
959 % 2023/01/22 1.2
960 \ifcsname r@etocname\endcsname
961 \expanded{\noexpand\AtEndDocument
962 {\noexpand\PackageError{etoc}{Pas de référence à #1\on@line}%
963 {Corriger!}
964 }%
965 }%
966 \fi
967 \fi
968 }
969 \makeatother
970
971 \DeclareRobustCommand\csa [1]
972 {{\ttfamily\hyphenchar\font45 \char`\\ #1}}
973
974 \newcommand\cshyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}}
975
976 \newcommand\csbhyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}}
977
978 \newcommand\etoc{%
979 \texorpdfstring{{\color{joli}\ttfamily\bfseries etoc}}{etoc}\xspace}
980 \newcommand\toc{\csb{tableofcontents}\xspace}
981 \newcommand\localtoc{\csb{localtableofcontents}\xspace}
982 \newcommand\invisiblelocaltoc{\csb{invisiblelocaltableofcontents}\xspace}
983 \newcommand\localtocwrdp{\csb{localtableofcontentswithrelativedepth}\xspace}
984
985 \newcommand\lowast{\raisebox{-.25\height}{*}}
986 \newcommand\starit[1]{\csa{#1\lowast}}
987 \newcommand\staritb[1]{\csb{#1}\lowast}
988
989 % 2023/01/23, mais pas la peine de s'embêter avec robust et texorpdfstring
990 \newcommand\etocrelease[1]{\hyperlink{v#1}{\texttt{#1}}}
991 % 2024/01/11. Utiliser \texttt ou autre?
992 \newcommand\etocissue[1]{\href{https://github.com/jfbu/etoc/issues/#1}{jfbu/etoc\##1}}
993
994 \DeclareRobustCommand\ctanpkg[1]
995 {\texorpdfstring{\href{https://ctan.org/pkg/#1}{#1}}{#1}}
996
997 \hyphenation{
998 table-of-con-tents
999 local-table-of-con-tents
1000 local-table-of-con-tents-with-rel-a-tive-depth
1001 etoc-local-list-of-ta-bles-hook
1002 etoc-local-list-of-fig-ures-hook
1003 local-list-of-fig-ures
1004 local-list-of-ta-bles
1005 %
1006 toc-depth
1007 sec-num-depth
1008 con-tents-line
1009 %
1010 etoc-stan-dard-lines
1011 etoc-de-fault-lines
1012 etoc-toc-lines
1013 etoc-set-style
1014 etoc-name
1015 etoc-page
1016 etoc-skip-first-pre-fix
1017 etoc-num-ber
1018 etoc-if-first
1019 etoc-x-if-first
1020 etoc-if-num-bered
1021 etoc-x-if-num-bered
1022 etoc-if-was-empty
1023 etoc-x-if-was-empty
1024 etoc-checks-empti-ness
1025 etoc-no-toc-if-no-toc
1026 etoc-the-name
1027 etoc-the-num-ber
1028 etoc-the-page
1029 etoc-link
1030 etoc-the-linked-name
1031 etoc-the-linked-num-ber
1032 etoc-the-linked-page
1033 etoc-the-link
1034 etoc-set-level
1035 etoc-set-toc-depth
1036 etoc-set-next-toc-depth
1037 etoc-set-toc-depth
1038 etoc-obey-toc-toc-depth
1039 etoc-ig-nore-toc-depth
1040 etoc-depth-tag
1041 etoc-set-tag-depth
1042 etoc-obey-depth-tags
1043 etoc-ig-nore-depth-tags
1044 etoc-toc-con-tents-line
1045 etoc-set-local-top
1046 etoc-stan-dard-dis-playstyle
1047 etoc-ar-ti-cle-style
1048 etoc-book-style
1049 etoc-set-toc-style
1050 etoc-mul-ti-col-style
1051 etoc-mul-ti-col
1052 etoc-lo-cal-mul-ti-col
1053 etoc-toc-style
1054 etoc-toc-style-with-marks
1055 etoc-toc-style-with-marks-nouc
1056 etoc-ruled-style
1057 etoc-ruled
1058 etoc-lo-cal-ruled
1059 etoc-framed-style
1060 etoc-framed
1061 etoc-lo-cal-framed
1062 etoc-in-line
1063 etoc-af-ter-ti-tle-hook
1064 etoc-af-ter-con-tents-hook
1065 etoc-af-ter-toc-hook
1066 etoc-skip-first-pre-fix
1067 etoc-only-on-first
1068 %
1069 etoc-font-mi-nus-two
1070 etoc-font-mi-nus-one
1071 etoc-font-zero
1072 etoc-font-one
1073 etoc-font-two
1074 etoc-font-three
1075 etoc-sep-mi-nus-two
1076 etoc-sep-mi-nus-one
1077 etoc-sep-zero
1078 etoc-sep-one
1079 etoc-sep-two
1080 etoc-sep-three
1081 etoc-mi-nus-two-left-mar-gin
1082 etoc-mi-nus-two-right-mar-gin
1083 etoc-mi-nus-one-left-mar-gin
1084 etoc-mi-nus-one-right-mar-gin
1085 etoc-base-line-spread-mi-nus-two
1086 etoc-base-line-spread-mi-nus-one
1087 etoc-base-line-spread-zero
1088 etoc-base-line-spread-one
1089 etoc-base-line-spread-two
1090 etoc-base-line-spread-three
1091 etoc-toc-line-lead-ers
1092 etoc-ab-brev-page-name
1093 etoc-part-name
1094 etoc-book-name
1095 etoc-above-toc-skip
1096 etoc-be-low-toc-skip
1097 etoc-column-sep
1098 etoc-mul-ti-col-sep
1099 etoc-mul-ti-col-pre-tol-er-ance
1100 etoc-mul-ti-col-tol-er-ance
1101 etoc-de-fault-nb-col
1102 etoc-in-ner-top-sep
1103 etoc-top-rule
1104 etoc-top-rule-col-or-cmd
1105 etoc-in-ner-left-sep
1106 etoc-in-ner-right-sep
1107 etoc-in-ner-bot-tom-sep
1108 etoc-left-rule
1109 etoc-right-rule
1110 etoc-bot-tom-rule
1111 etoc-left-rule-col-or-cmd
1112 etoc-right-rule-col-or-cmd
1113 etoc-bot-tom-rule-col-or-cmd
1114 etoc-bkg-col-or-cmd
1115 etoc-framed-mp-hook
1116 etoc-keep-orig-i-nal-table-of-con-tents
1117 etoc-im-me-di-ate-set-toc-dep-th
1118 etoc-im-me-di-ate-depth-tag
1119 etoc-im-me-di-ate-toc-con-tents-line
1120 etoc-im-me-di-ate-set-local-top
1121 %
1122 next-toc-with-tags
1123 }
1124
1125 % no more \frenchspacing since 2022/08/26
1126
1127 % for illustration only. Not to be recommended in general.
1128 \setcounter{secnumdepth}{4}
1129
1130 % Usage of microtype added for 1.2 release; now that for some time
1131 % due to the business of attachfile I am tied with pdflatex.
1132 \ifnum\Withdvipdfmx=1
1133 \else
1134 % should I check for xetex/luatex ?
1135 \usepackage[nopatch=toc]{microtype}
1136 \AtBeginDocument{\addtocontents{toc}{\protect\microtypesetup{protrusion=false}}}
1137 \fi
1138
1139 \def\etocoption#1{{\color{optioncolor}\bfseries\texttt{#1}}}
1140
1141 \begin{document}
1142 % \normalsize % change rien à un parindent un peu grand si 4
1143 \parindent 3\fontcharwd\font`x\relax
1144
1145 \marginparsep 6bp
1146 \thispagestyle{empty}
1147
1148 \bookmark[named=FirstPage,level=1]{Title page}
1149 % depth tags for title page toc
1150 \etocsettagdepth {preamble} {part}
1151 \etocsettagdepth {overview} {section}
1152 \etocsettagdepth {styling} {section}
1153 \etocsettagdepth {control} {section}
1154 \etocsettagdepth {examples} {section}
1155 \etocsettagdepth {advanced} {section}
1156 \etocsettagdepth {etocandworld}{part}
1157 \etocsettagdepth {code} {section}
1158
1159 % pour les TOC à la TikZ
1160 \newtoks\treetok
1161 \newtoks\parttok
1162 \newtoks\sectiontok
1163 \newtoks\subsectiontok
1164 \newtoks\subsubsectiontok
1165 \newtoks\tmptok
1166
1167 \newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
1168 #1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}}
1169
1170 % 12 et 13 mars 2015 pour la mind map de title page
1171 % pour les Mindmap avec branch color
1172 \def\appendpart #1#2#3{%
1173 \edef\tmpstuff {\the#1 child [branch color = #3]{\the#2}}%
1174 #1\expandafter {\tmpstuff }%
1175 }
1176 % for 1.09f mind map on title page
1177 \def\prependpart #1#2#3{%
1178 \edef\tmpstuff {child [branch color = #3]{\the#2} \the#1}%
1179 #1\expandafter {\tmpstuff }%
1180 }
1181
1182
1183 % TOC MIND MAP ON TITLE PAGE
1184 \newcount\tikznumberofcurrentgrandchild
1185
1186 % copied originally from http://tex.stackexchange.com/a/232914
1187 %
1188
1189 % \newcount\tikzdeltaofcurrentgrandchild % not needed at 1.2
1190
1191 % 1.2 causes quite a few adjustments as the parts have been modified, there
1192 % are now only 8 of them, and it is not same number of sections too.
1193 % As I don't read TikZ well, I had some trouble, but I take this opportunity
1194 % to clean up some complications from recent layouts which handled some
1195 % sections to lie on circular arcs, as exception to the general rectangular
1196 % rule. This was because not everything could fit, but I could find
1197 % satisfactorily layout this time, simply inhibiting via depth tags a few
1198 % sections.
1199
1200 \def\tikzmycustomgrowth {%
1201 \pgftransformreset
1202 \ifnum\tikztreelevel=1
1203 \pgftransformrotate{(\pgfkeysvalueof{/tikz/sibling angle})
1204 *
1205 (\tikznumberofcurrentchild-2)}%
1206 \pgftransformxshift{\the\tikzleveldistance}%
1207 \fi
1208 \ifnum\tikztreelevel=2
1209 \pgfmathsetmacro\tikzoffsetofcurrentchild{%
1210 (\tikzsiblingdistance)*(\tikznumberofcurrentgrandchild)
1211 }%
1212 \ifdim\tikzoffsetofcurrentchild pt<\tikzlevelheight
1213 \pgftransformxshift{\tikzlevelwidth/2}
1214 \pgftransformyshift{-\tikzlevelheight/2+\tikzoffsetofcurrentchild}
1215 \else
1216 \pgfmathsetmacro\tikzoffsetofcurrentchild{\tikzoffsetofcurrentchild-\tikzlevelheight}%
1217 \ifdim\tikzoffsetofcurrentchild pt<\tikzlevelwidth
1218 \pgftransformxshift{\tikzlevelwidth/2-\tikzoffsetofcurrentchild}
1219 \pgftransformyshift{\tikzlevelheight/2}
1220 \else
1221 \pgfmathsetmacro\tikzoffsetofcurrentchild{\tikzoffsetofcurrentchild-\tikzlevelwidth}%
1222 \ifdim\tikzoffsetofcurrentchild pt<\tikzlevelheight
1223 \pgftransformxshift{-\tikzlevelwidth/2}
1224 \pgftransformyshift{\tikzlevelheight/2-\tikzoffsetofcurrentchild}
1225 \else
1226 \pgfmathsetmacro\tikzoffsetofcurrentchild{\tikzoffsetofcurrentchild-\tikzlevelheight}%
1227 \ifdim\tikzoffsetofcurrentchild pt<\tikzlevelwidth
1228
1229 \pgftransformxshift{-\tikzlevelwidth/2+\tikzoffsetofcurrentchild}
1230 \pgftransformyshift{-\tikzlevelheight/2}
1231 \else
1232 \pgfmathsetmacro\tikzoffsetofcurrentchild{\tikzoffsetofcurrentchild-\tikzlevelwidth}%
1233 \pgftransformxshift{\tikzlevelwidth/2}
1234 \pgftransformyshift{-\tikzlevelheight/2+\tikzoffsetofcurrentchild}
1235 \fi\fi\fi\fi
1236 \pgftransformrotate {\pgfkeysvalueof{/tikz/sibling angle}
1237 *
1238 \tikznumberofcurrentgrandchild}%
1239 \global\advance\tikznumberofcurrentgrandchild by1
1240 \fi
1241 }
1242
1243 % % % version circulaire utilisée avec les versions 1.08a--1.09e du manuel.
1244 % \def\tikzmycustomgrowth {%
1245 % \pgftransformreset
1246 % \ifnum\tikztreelevel=1
1247 % \pgftransformrotate {126+(\pgfkeysvalueof{/tikz/sibling angle})*(\tikznumberofcurrentchild-1)}%
1248 % \fi
1249 % \ifnum\tikztreelevel=2
1250 % \pgftransformrotate {(\pgfkeysvalueof{/tikz/sibling angle})*(2+\tikznumberofcurrentgrandchild)}%
1251 % \global\advance\tikznumberofcurrentgrandchild by 1
1252 % \fi
1253 % \pgftransformxshift {\the\tikzleveldistance}%
1254 % }
1255
1256 \newcounter{partco}
1257 % 1,2,3,4,5,... -> 1,2,3,1,2,3,1,2,3
1258 \def\pseudomodthree #1{\numexpr #1 + 3 - 3*((#1+1)/3)\relax}
1259
1260
1261 \newbox\TitlePageMindmapTOC
1262
1263 \etocsetlinestyle{part}
1264 {\etocskipfirstprefix}
1265 {\ifcase\pseudomodthree{\value{partco}}%
1266 \or \appendpart\treetok\parttok {Dandelion!50}% first (was teal!60 until 1.09f)
1267 \or \appendpart\treetok\parttok {teal!40}% second (was yellow!80 until 1.2)
1268 \else\appendpart\treetok\parttok {green!40}% third
1269 \fi
1270 }
1271 {\stepcounter{partco}%
1272 \edef\treenode{node
1273 {\noexpand\textbf{\etocifnumbered{\unexpanded\expandafter{\etocthelinkednumber}.}{}
1274 \unexpanded\expandafter{\etocthelinkedname}}}}%
1275 \parttok\expandafter{\treenode}}
1276 {% 1.09f used \prependpart for the last... reverted at 1.2,
1277 % better to append, avoids overlaps by rays of some balls
1278 \ifcase\pseudomodthree{\value{partco}}%
1279 \or \appendpart\treetok\parttok {Dandelion!50}% first
1280 \or \appendpart\treetok\parttok {teal!40}% second
1281 \else\appendpart\treetok\parttok {green!40}% third
1282 \fi
1283 }
1284
1285 \etocsetlinestyle{section}
1286 {}
1287 {}
1288 {% define the section node
1289 \edef\childnode{child {node
1290 % The Bitter font does not have bold italic
1291 % Adding \baselineskip setting, and \endgraf to activate because \par causes
1292 % ! Paragraph ended before \tikz@collect@child@code was complete.
1293 % There must be some way to configure the TikZ node but I don't have
1294 % the time to go into its documentation.
1295 {\baselineskip10pt\noexpand\itshape%\noexpand\bfseries
1296 \unexpanded\expandafter{\etocthelinkedname}\hfil\break
1297 p. \unexpanded\expandafter{\etocthelinkedpage}\noexpand\endgraf
1298 }%
1299 }%
1300 }%
1301 \appendtotok\parttok\childnode
1302 }
1303 {}
1304
1305 % title page toc
1306 % 1.09f used a prepend for last part so we needed to delay
1307 % the insertion of the root node to after the treetok had
1308 % been finished.
1309 % 1.2 uses append always so we can initialize here
1310 \treetok{\node [root concept]{\normalfont{The \etoc package}\par {\normalsize\textsc
1311 {Jean-François Burnol}\par \ttfamily jfbu (at) free (dot) fr}\par
1312 {\normalsize
1313 Package version:\par \hyperref[changelog]{\etocpkgversion{} (\etocpkgdate )}\par}}%
1314 }
1315
1316 \etocsettocstyle
1317 {\setcounter{partco}{0}}
1318 {\global\treetok\expandafter{\the\treetok;}}
1319
1320 \etocsetnexttocdepth{section}
1321
1322 % fill in the \treetok
1323 \etocinline
1324 \tableofcontents\label{toc:mindmaptitlepage}
1325
1326 % For debugging
1327 % \newwrite\TOCasTree
1328 % \immediate\openout\TOCasTree=\jobname.toctree
1329 % \immediate\write\TOCasTree{\the\treetok}%
1330 % \immediate\closeout\TOCasTree
1331
1332 \tikzset {branch color/.style={concept color=#1!white,
1333 every child/.append style={concept color=#1!white!30!white,
1334 opacity=0.3, text opacity=1},
1335 },
1336 % ajout pour versions depuis 1.08g
1337 level width/.store in=\tikzlevelwidth,
1338 level height/.store in=\tikzlevelheight,
1339 }%
1340 \global\setbox\TitlePageMindmapTOC\hbox {%
1341 \resizebox{\dimexpr\paperwidth-1cm\relax}!{
1342 \begin{tikzpicture}[mindmap,
1343 text width=2cm,
1344 align = flush center,
1345 % pour 1.09 je reviens à version circulaire simplifiée
1346 % pour 1.09f je reviens à version rectangulaire
1347 growth function=\tikzmycustomgrowth,
1348 nodes={concept},
1349 % trying cyan I get some surprising brutal color change
1350 % much more visible than with orange
1351 concept color=yellow!50,% orange!60 until 1.2
1352 % root concept/.append style={font=\huge, text width = 6cm},
1353 root concept/.append style={font=\Large, text width = 5cm},
1354 % level 1/.append style={level distance=7cm, sibling
1355 level 1/.append style={level distance=6cm,
1356 sibling angle=360/8},% 8 parties
1357 % level 1 concept/.append style={font=\Large, text width = 3cm},
1358 % ancienne version circulaire
1359 % level 2/.append style={level distance=12.5cm, sibling angle=360/39},%
1360 % pour version rectangulaire, par tâtonnements:
1361 % réactivée pour 1.09f (étonnamment, juste quelques petits ajustements, mais ça
1362 % a tout de même pris pas mal de temps...)
1363 level 2/.append style={level width=21cm,
1364 level height=30cm,
1365 sibling distance=2.075cm,% 1.2e à ajuster manuellement
1366 % 1.09f pour essayer certaines parties en
1367 % circulaire; plus besoin pout 1.2
1368 % level distance=10cm,% distance depuis le centre !
1369 % sibling angle=12,% à ajuster manuellement
1370 % 2.12cm pour 1.2d en particulier
1371 },
1372 level 2 concept/.append style={text width=2cm},
1373 ]
1374 \the\treetok
1375 \end{tikzpicture}%
1376 }%
1377 }% end of \hbox
1378 % On l'envoie au shipout
1379 \AddToShipoutPictureFG*{\put(.5\paperwidth,.5\paperheight)
1380 {\makebox(0,0){\box\TitlePageMindmapTOC}}}
1381 % trigger first page
1382 \noindent\null\par\vskip-5cm\hbox{\hypertarget{FRONTPAGE}{}}\vskip5cm
1383
1384 % % for standard TOC
1385 % \etocstandardlines
1386 % \etocclasstocstyle
1387 % \tableofcontents
1388
1389 % reset toc global to class default and line styles to etoc default
1390 \etocfallbacklines
1391 \etocclasstocstyle
1392
1393 \clearpage
1394 \etocdepthtag.toc {preamble}
1395
1396 %----
1397 % MAIN TOC
1398 % made invisible at 1.2
1399 \invisibletableofcontents \label{toc:main}
1400
1401
1402 \part*{\etoc}
1403 \addcontentsline{toc}{part}{\etoc (read this first)}
1404
1405 \onehalfspacing
1406
1407 \begin{shaded}\small
1408 % lien pour pour les "attachment annotations"
1409 % https://helpx.adobe.com/acrobat/using/comments.html
1410 %
1411 % Memo: https://english.stackexchange.com/questions/42370/is-two-thirds-plural
1412 % Yes and no. Yes, when you're talking about multiples of fractions eg. two
1413 % thirds they are plural. But when you're talking about a portion of a single
1414 % item, that item is singular.
1415 % 1). One third of the pizza was eaten. (part of one pizza was eaten)
1416 % Two thirds of the pizza was eaten. (part of one pizza was eaten)
1417 % The subject is pizza - singular. If you have one third of a pizza, and I have
1418 % one third of that same pizza we have two thirds (plural) of one pizza
1419 % (singular).
1420 % Of course this changes when the subject becomes plural:
1421 % One third of two pizzas were eaten. (part of two pizzas were eaten)
1422 % 2). One third of the visitors were men. (multiple visitors were men)
1423 % Two thirds of the visitors were men. (multiple visitors were men)
1424 % The subject in this case - men - is plural.
1425 %
1426 % Cependant j'ai un doute à cause de «the first» qui en française se traduirait
1427 % par un pluriel «les premiers deux-tiers» et ensuite on aurait envie de mettre
1428 % un pluriel; mais de toute la Grammaire n'a pas de Logique ! Tout le monde le
1429 % sait !
1430 %
1431 The command names throughout
1432 the user documentation which are displayed
1433 {\textcolor{RoyalBlue}{with this colour}} are doubly hyperlinked:
1434 the first two-thirds of the command name hyperlinks to the user documentation, and the
1435 remaining third part hyperlinks to the source code. You can try it out now:
1436 \csb{localtableofcontents}. But read this first: if you get lost
1437 inside the source code, clicking on control sequences displayed
1438 {\textcolor{macrocodelinktouserdoccolor}{with this colour}} brings
1439 you back to the part of the user manual discussing that specific
1440 command. \ifnum\NoSourceCode=1 (but this PDF does not include the
1441 source code) \fi
1442 \end{shaded}
1443
1444
1445 \section*{Abstract}
1446
1447 %\renewcommand\abstractname{}
1448
1449 %\begin{abstract}
1450 \begingroup
1451 \leftskip1cm
1452 \rightskip1cm
1453
1454 With \etoc loaded, \csb{tableofcontents} can be used multiple times and
1455 an added command \csb{localtableofcontents} allows to typeset ``local''
1456 tables of contents, i.e. having their scope limited to the last
1457 sectioning command encountered.
1458
1459 No auxiliary file is used additionally to the standard \texttt{.toc}
1460 file. Release \etocrelease{1.2} provides EXPERIMENTAL additions
1461 \csb{locallistoffigures} and \csb{locallistoftables} which also use
1462 only the \texttt{.toc} file.
1463
1464 Such local TOCs or ``Lists Of'' typically need to adopt a ``display
1465 style'' (i.e. the way the title is rendered, whether it should add
1466 itself an entry in the \texttt{.toc} file, ...) somewhat distinct from
1467 the global TOC. The release \etocrelease{1.2} default adapts
1468 automatically the titles of local TOCs to their depths in the
1469 sectioning hierarchy. Should the need arise to customize such
1470 ``display style'', full control is allowed by package commands.
1471
1472 Regarding how the individual ``contents lines'' are handled, here again
1473 complete control is given to the user to define from the ground-up how
1474 to use the \emph{name}, \emph{number}, and \emph{page number} for each
1475 entry, according to their ``levels'' (i.e. part, chapter, section,
1476 subsection, ...). As this requires some \LaTeX{} fluency, many examples
1477 which can serve as starting points are attached to the PDF
1478 documentation as extractible files.
1479
1480 Loading \etoc per itself modifies nothing to ``contents lines''
1481 rendering from the class default or changes from other packages. But
1482 full usage of the package allows spectacular effects such as displaying
1483 TOCs as trees or mind maps.
1484
1485 %\end{abstract}
1486 \endgroup
1487
1488 %\clearpage
1489
1490 \setstretch{1}
1491
1492 \section*{License}
1493 \addcontentsline{toc}{section}{License}
1494
1495 \begingroup
1496 \ttfamily
1497 \hyphenchar\font -1
1498 \parindent0pt
1499 \obeyspaces\obeylines %
1500 \etocLicense\endgroup
1501
1502 \onehalfspacing
1503 \clearpage
1504 \onehalfspacing
1505 \etocignoredepthtags
1506 \etocsettocdepth {subsubsection}
1507
1508 \etocdepthtag.toc{overview}
1509 \part{Overview}\label{part:overview}
1510
1511 \thispartstats
1512
1513 \etocfallbacklines
1514 \etocsettocstyle{}{}
1515 \localtableofcontents \label{toc:overview}
1516
1517 \section[\csbhyp{(local)\-tableofcontents}]{The \csbhyp{tableofcontents},
1518 \csbhyp{localtableofcontents} and other main package commands}
1519
1520 \begin{description}
1521 \item [\csb{tableofcontents}] can be used arbitrarily many times in the
1522 document,
1523
1524 \item [\csb{localtableofcontents}] produces tables of contents which are
1525 limited in scope by the nearest preceding sectioning command,%
1526 %
1527 \footnote{After adding a \localtoc in-between existing ones, the first
1528 compilation will typeset at its location a pre-existing next one; only at
1529 second compilation will the contents match the location. Hence often a
1530 third compilation is needed for document to stabilize. And if the ``to toc''
1531 mechanism is active (see the discussion of \csb{etocsetup} option
1532 \etocoption{localtoctotoc} and
1533 similar options), only on second compilation is a new entry made in the
1534 \texttt{.toc} file so three compilations is always a minimum. If one
1535 starts compilations from a given source, and no auxiliary files, the first
1536 compilation prepares the |.toc| file, the second typesets the main and local
1537 TOCs, possibly changing page numbers due to added contents, and only at the
1538 third compilation will things perhaps stabilize, and this third step is
1539 surely needed in case of \etocoption{localtoctotoc}. \ctanpkg{latexmk} is highly
1540 recommended.}
1541
1542
1543 \item [\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}] defines
1544 (from the ground up, completely) the TOC titles, or more generally
1545 everything either before or after the actual TOC contents,
1546
1547 \item [\csb{etocsetlinestyle}\marg{levelname}%
1548 \marg{start}\marg{prefix}\marg{contents}\marg{finish}] defines (completely,
1549 from the ground up) arbitrarily the way the \csa{contentsline} entries in
1550 the |.toc| file are rendered, depending on their first argument, which is a
1551 `level name' such as |part|, |chapter|, |section|, |subsection|, \dots
1552
1553 It is possible to create new levels or re-assign the numerical level of a
1554 named one via \csb{etocsetlevel}\marg{levelname}\marg{number}, thus opening
1555 the way for sophisticated (ab)-uses of the data stored in the |.toc| file.
1556
1557 \item [\csb{etocname}, \csb{etocnumber}, \csb{etocpage}] are free to use
1558 arbitrarily in the \csb{etocsetlinestyle} \marg{prefix} and \marg{contents}
1559 arguments for a given contents line level name, they stand for what will be
1560 extracted by \etoc from the actual data which is stored in the |.toc| file
1561 and is a bit entangled there (for the first two).
1562 \end{description}
1563
1564 %% \vskip-\baselineskip\vskip0pt % sigh LaTeX spaces !
1565
1566 Throughout this documentation ``layout'', ``display'', ``TOC style'' always are
1567 synonyms and refer roughly to how the TOC title is typeset. And ``line
1568 styles'' refer to how each individual entry in the TOC will be rendered
1569 according to its ``level''. Whenever ``TOC style'' is mentioned it is for the
1570 title related things, else the documentation will say ``line styles''.
1571
1572 \csb{etocsetlinestyle} is for line styles and it requires \LaTeX{} fluency. It is
1573 however absolutely not required to use it: by default \etoc does not intervene
1574 at all into the rendering of the contents lines. For example, one can use
1575 packages such as \ctanpkg{tocloft} to customize these contents lines as wished.
1576
1577 \csb{etocsettocstyle} is for styling the titles (and all things related to
1578 material before and after the actual TOC contents). It was originally
1579 conceived mainly for being used after the main document TOC (assuming it comes
1580 first). By default \etoc renders the main TOC as specified by the class it
1581 knows about. But for example in a |book|-class document, one does not want to
1582 use a chapter-like heading for a local TOC in a section. Hence the need for
1583 \csb{etocsettocstyle}. But if used in the preamble it will apply to the main
1584 TOC too (if it comes first in the document body), hence its usage has to be
1585 delayed or stored into some command, else one has to insert branches in the
1586 original definition to query the kind of TOC it is applied to.
1587
1588 With \etocrelease{1.2} some utilities facilitate using
1589 \csb{etocsettocstyle} only once in the preamble and branch according to
1590 whether it is handling a main document TOC or a local one. But the macro was
1591 really initially conceived to be used for local TOCs once the main TOC was
1592 typeset (commands are provided to restore the default configuration in time
1593 for a main TOC at end of document). There is no command to customize the
1594 titles only for local TOCs from the preamble.
1595
1596 With \etocrelease{1.2} an effort has been made to make using
1597 \csb{etocsettocstyle} for local TOCs purely an option: by default the package
1598 adopts a style for local headings which takes into account the local top
1599 level. This corresponds to the command \csb{etocetoclocaltocstyle}, which is emitted
1600 by default by the package.
1601
1602 Furthermore \etocrelease{1.2} detects \ctanpkg{tocbibind}%
1603 %
1604 \footnote{Support for \ctanpkg{tocloft} customization of contents lines was
1605 already in place for many years; the compatibility with \ctanpkg{tocbibind}
1606 was added only at \etocrelease{1.2} and required to update the
1607 \ctanpkg{tocloft} related code.}
1608 %
1609 and executes a compatilibity layer so that this package can be used with
1610 hopefully the same result as in the main document classes. Package options
1611 \etocoption{maintoctotoc}, \etocoption{localtoctotoc},
1612 \etocoption{localloftotoc} and \etocoption{locallottotoc} trigger ``to toc''
1613 mechanisms even without \ctanpkg{tocbibind} if desired, directly at \etoc
1614 level. The starred variants of the table of contents and ``list of'' commands
1615 will ignore the status of these options, as in the \ctanpkg{memoir} class.
1616
1617
1618 \section[\csbhyp{locallistof\-(figures\textbar\-tables)}]{The \protect\etocrelease{1.2}
1619 \csbhyp{locallistoffigures} and \csbhyp{locallistoftables} commands}
1620 \label{locallistoffigures}
1621 \label{locallistoftables}
1622 \label{etocsetup}
1623
1624 The major novelty with \etocrelease{1.2} is the addition of
1625 \csb{locallistoffigures} and \csb{locallistoftables}.
1626
1627 \begin{framed}
1628 The following major problem is known with the current implementation:
1629 \csb{locallistoffigures} and \csb{locallistoftables} actually list the
1630 figures, respectively the tables, say in a given \csa{section} which are
1631 \textbf{TYPESET THEREIN}, which is not necessarily the same figures, tables,
1632 which in the \LaTeX{} source are located \textbf{``WITHIN'' THAT SECTION}.
1633
1634 Recall that \LaTeX{} does not have a structured representation of the
1635 document (despite what many people like to think), so there is no
1636 pre-existing official way from inside a table to know in which section or
1637 subsection it is defined. And figures and tables are \emph{floating}.
1638
1639 If a figure, for example, floats to next page, and the section were it was
1640 \emph{defined} is followed on the initial page by another one, then a
1641 \csb{locallistoffigures} in the first section will NOT see the figure which
1642 has drifted to next page! That floating figure will be listed by a
1643 \csb{locallistoffigures} in the NEXT section!
1644
1645 Now, if all sections are equipped with \csb{locallistoffigures} this current
1646 ``feature'' of \etoc means that all figures will be accounted for and one
1647 will be able to see in which section they physically reside after
1648 typesetting!
1649
1650 Which is nice but perhaps counter intuitive.
1651
1652 The source of this problem is well-understood by package author but
1653 addressing the issue is delayed probably for some months, by lack of time
1654 and ressources; or may remain a permanent ``feature'' as the author does not
1655 intend to hack in any way into code for floats, or even captions.
1656
1657 Here is a non-\etoc file you can play with and which illustrates the
1658 mechanism:
1659 \begin{verbatim}
1660 \documentclass{article}
1661 \begin{document}
1662 \tableofcontents % the table of contents will show the "table" entry
1663 % as belonging to **second** section
1664 \section{first}
1665 \begin{table}[p]
1666 some tabular
1667 \makeatletter
1668 % add some entry in the toc file, like a subsection would do
1669 \write\@auxout{\string \@writefile {toc}
1670 {\protect \contentsline {subsection}{table}{\thepage }{}}}
1671 \caption{table}
1672 \end{table}
1673
1674 \section{second}
1675 \end{document}
1676 \end{verbatim}
1677 \end{framed}
1678 \begin{itemize}
1679 \item This is experimental code and the user interface as well as the
1680 output may change.
1681 \item It is mandatory to load \etoc with option \etocoption{lof} for
1682 \csb{locallistoffigures} and \etocoption{lot} for \csb{locallistoftables}.
1683 \item \etoc does not interfere whatsoever with \csa{listoffigures} and
1684 \csa{listoftables}, and can not customize them in any way.
1685 \item \etoc still uses no additional auxiliary file, it uses only the
1686 |.toc| file.
1687 \item This is experimental code and the user interface as well as the
1688 output may change.
1689 \item The new command \csb{etocsetup} allows to configure at any
1690 location in the preamble or in the document body the boolean options
1691 \etocoption{maintoctotoc}, \etocoption{localtoctotoc},
1692 \etocoption{localloftotoc}, \etocoption{locallottotoc}, and
1693 \etocoption{ouroboros} which can also be issued as package options.
1694 The first four default to |false|, except with the \ctanpkg{memoir}
1695 class, in which case they are set to |true|, or when
1696 \ctanpkg{tocbibind} is detected, in which case they are set to
1697 |true| depending on the setting of the \ctanpkg{tocbibind} options.
1698 \item The \etocoption{ouroboros} option defaults to |true|. When set
1699 to |false|, local TOCs which have been added to the |.toc| file due
1700 to \etocoption{localtoctotoc} will \emph{not} list themselves (they
1701 will still list entries from local TOCs at deeper levels in their
1702 scope, and the ``lists of'' at their same level, and are listed in
1703 the main TOC, the only thing is that they don't show themselves in
1704 themselves).%
1705 %
1706 \footnote{It is complex to try to anticipate all scenarii, but in general, it
1707 is expected this behavior may cause the |.toc| file to need more time to
1708 stabilize when a new local TOC is added in the midst of a document having
1709 already a bunch of them.}
1710 %
1711 The default is that they \emph{do} list themselves, hence the name
1712 \etocoption{ouroboros}. It has no impact on the main TOCs, use their
1713 starred variant to inhibit the self-display, but then why have issued
1714 \etocoption{maintoctotoc} in the first place?
1715 \item An effort has been made to facilitate as much as possible
1716 customization by the user, i.e. via commands without |@| letter.
1717 However this documentation will only list their names with very
1718 brief comments at the appropriate place and the reader is expected
1719 to check in the source code to understand better what they are for.
1720 \item This is experimental code and the user interface as well as the
1721 output may change.
1722 \item For example, the actual figure entries or table entries use by
1723 default the code from the main LOF or LOT; but one may prefer to
1724 render them in a way taking into account the local ``list of''
1725 scope: for example in a section, perhaps use the same style as
1726 subsections. This is possible and is explained briefly later.
1727 \item Although the default ``\etoc'' choices for local titles should
1728 be hopefully satisfactory in most cases, it is also possible to tell
1729 \etoc to try to use emulation from the document class via the
1730 command \csb{etocclasstocstyle}. An effort has been made to obtain
1731 something which works at one level deeper than the ones under
1732 \csa{part}. For example with \ctanpkg{KOMA-script}, we use the
1733 option |leveldown|. However this will not really work for deeper
1734 local ``lists of''.%
1735 %
1736 \footnote{And with \ctanpkg{KOMA-script} at version \texttt{3.30} or later the
1737 fact that unnumbered sections reset the subsection counter will cause bad
1738 problems in a \texttt{scrbook} document if a TOC, local to a \csa{subsection}
1739 uses a title which is un unnumbered section!}
1740 %
1741 But for some document using local ``lists of'' only for chapters or
1742 for sections in classes without chapters, this \csb{etocclasstocstyle}
1743 may be appropriate as it may allow the user to use the class interface
1744 for advanced control of the marks or other details.
1745 \item The \etoc document class agnostic default, from
1746 \csb{etocetoclocaltocstyle} which is automatically issued at package
1747 loading time, is completely customizable.
1748 \item This is experimental code and the user interface as well as the
1749 output may change.
1750 \item If using for example all three of \csb{localtableofcontents},
1751 \csb{locallistoffigures} and \csb{locallistoftables}, in the same
1752 location after a division heading, and if the ``to toc'' related
1753 options either from \etoc or from \ctanpkg{tocbibind} are used, then
1754 \csb{localtableofcontents} must be the first one in order to be able
1755 to list the other two (and itself). It can not see the ``lists of''
1756 coming before itself at the same division level.
1757 \item Regarding the TOC title style, \etoc knows the standard classes,
1758 the \ctanpkg{KOMA-script} main classes and the \ctanpkg{memoir}
1759 class. In an unknown class it will use the code from the |article|
1760 class emulation. For the local TOCs and local ``lists of'' it uses
1761 as with the known classes its own class-independent code from
1762 \csb{etocetoclocaltocstyle}.
1763 \item One can tell \etoc to not replace the original
1764 \csa{tableofcontents} via \csb{etockeeporiginaltableofcontents} (it
1765 will still be possible to use \csb{etoctableofcontents}), but the
1766 non-etoc \csa{tableofcontents} is usable only if document does not
1767 use \csb{locallistoffigures} or \csb{locallistoftables} as the
1768 latter two insert entries for figures, resp.\@ tables, in the main
1769 |.toc| file and only \etoc's \csb{tableofcontents} knows to ignore
1770 them.
1771 \item This is experimental code and the user interface as well as the
1772 output may change.
1773 \end{itemize}
1774
1775 \section{The \csbhyp{etocsettocstyle} command}
1776 \label{etocsettocstyleintro}
1777
1778 This is a command with two mandatory arguments:
1779 \centeredline{\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}
1780 The \marg{before\_toc} part is responsible for typesetting the
1781 heading, for example it can be something like
1782 \starit{section}|{\contentsname}|. Here is an example of input:
1783 \begin{verbatim}
1784 \etocsettocstyle
1785 {\section*{Local table of contents}}%
1786 {}% don't do anything special after the toc contents
1787 \end{verbatim}
1788
1789 Once issued it will have an impact on all next usages of \localtoc (or \toc)
1790 until it is used again (or some related command).
1791
1792 Generally speaking the \marg{before\_toc} part should leave \TeX{} in
1793 ``vertical mode'': the line styles (either from the standard classes or the
1794 package default ones) all expect to get started in `vertical mode'.
1795
1796 For more documentation of this and related commands see first
1797 \autoref{sec:compatoverview} then
1798 \autoref{sec:tocstyle} for the more detailed pre-\etocrelease{1.2} documentation.
1799
1800 Only daring people will continue reading documentation as it now starts
1801 telling how to truly activate \etoc power.
1802
1803 \section{The \csbhyp{etocsetlinestyle} command}
1804 \label{etocsetstyleintro}
1805
1806 A distinction must be made between the \emph{line styles}, \emph{i.e.} the way
1807 the name, number and page numbers (aka \etoc-provided \csb{etocname},
1808 \csb{etocnumber}, and \csb{etocpage}) are used at each level, and the \emph{toc
1809 display style} (for lack of a better name) which tells how the title should
1810 be set, whether an entry in the |.toc| file should be made, whether the
1811 contents should be typeset with multiple columns, etc... the latter is governed
1812 by the command \csb{etocsettocstyle} (and related commands) which has already
1813 been mentioned, and the former by the command \csb{etocsetlinestyle} with is the
1814 core of \etoc functionality.
1815
1816 It has five mandatory arguments.
1817 %
1818 \centeredline
1819 {\csb{etocsetlinestyle}\color{blue}\marg{levelname}%
1820 \marg{start}\marg{prefix}\marg{contents}\marg{finish}}
1821 %
1822 The first one is the name of the sectional unit: a priori known names are
1823 |book|, |part|, |chapter|, |section|, |subsection|, |subsubsection|,
1824 |paragraph|, and |subparagraph|. Any other name can be declared and
1825 assigned to a (numeric) level via the \csb{etocsetlevel} command.%
1826 %
1827 \footnote{\etoc issues automatically
1828 \csb{etocsetlevel}\texttt{\string{appendix\string}\string{0\string}} (or wit
1829 h |1| if the document has no \csa{chapter} command), since
1830 \etocrelease{1.2}. Formerly this was done only with class
1831 \ctanpkg{memoir}.}
1832
1833 The four other arguments of \csb{etocsetlinestyle} specify: 1) \emph{what to do
1834 when this level is first encountered, down from a more general one,} then 2)
1835 \& 3) (two arguments, a `prefix' and a `contents') \emph{how to use for this
1836 level the \csb{etocname}, \csb{etocnumber} and \csb{etocpage} parsed data,}
1837 and 4) \emph{the last argument is the code to execute when a division unit of
1838 higher importance than the defined level style is encountered.}
1839
1840 Notice that this means that virtually \etoc manages a kind of tree-like
1841 substratum which is abstracted from the `flat' structure of the |.toc| data.
1842
1843 You should now read \autoref{sec:linestyles} for the detailed documentation.
1844
1845
1846 \section{No auxiliary file is used beyond the TOC file}
1847 \label{sec:compatoverview}
1848
1849 An important characteristic of \etoc is that it is allows many different TOCs
1850 in the same document, \emph{using only one} |.toc| \emph{file}!
1851
1852 \begingroup
1853 \setcounter{mycounti}{0}%
1854 \etocinline
1855 \etocsetlevel{part}{1}
1856 \etocsetlevel{chapter}{1}
1857 \etocsetlevel{visibletoc}{0}
1858 \etocsetlinestyle{visibletoc}
1859 {}
1860 {\stepcounter{mycounti}}
1861 {}
1862 {}
1863 \etocsettocstyle{}{}
1864 \etocsetnexttocdepth{0}
1865 \tableofcontents
1866 The present documentation contains \arabic{mycounti} visible tables of
1867 contents (and a few invisible ones) and uses only one |.toc| file!%
1868 %
1869 \footnote{and the counting itself has been achieved by a table of contents
1870 which was inserted in this paragraph! See \autoref{sec:tocoftocs}.}
1871 \endgroup
1872
1873 However, each \localtoc or \toc command will trigger the execution of the
1874 \emph{full contents} from the |.toc| file. The effect of \localtoc as well as
1875 the enforcement of the line styles as defined via \csb{etocsetlinestyle} are
1876 achieved via suitable redefinition of the \csa{contentsline} \LaTeX{} macro.
1877 But everything else present in the |.toc| file will be executed, as it is not
1878 possible for \etoc to control in any way what is present in the |.toc|
1879 file beyond \csa{contentsline} entries.
1880
1881 So one should think twice before adding manually extra commands to the |.toc|
1882 file. See \autoref{sec:addingtotoc} for further discussion.
1883
1884
1885
1886
1887 \section{Compatibility mode}\label{subs:compat}
1888 \label{etoctoclines}
1889 \label{etocstandardlines}
1890 \label{etocclasstocstyle}
1891 \label{etocetoclocaltocstyle}
1892 \label{etocusertocstyle}
1893 \label{etoclocallistoffigureshook}
1894 \label{etoclocallistoftableshook}
1895
1896 \etoc starts in a ``compatibility mode'', which means that it does not at all
1897 interfere with how the commands from the |.toc| file get executed as long as
1898 it has not been told explicitly to do so.%
1899 %
1900 \footnote{\label{fn:compat}for the ``toc display style'', by this we mean the
1901 aspects independant from the contents of the \texttt{.toc} file, \etoc checks
1902 if it knows the class, and then uses emulation code which was added manually
1903 to its source, and if not it defaults to the |article| class layout. No
1904 automated way to recover the global toc display for arbitrary document
1905 classes is implemented. But \etoc will detect if \ctanpkg{tocloft} has
1906 customized the TOC title.}
1907
1908 This ``compatibility mode'' stops for matters of the ``toc display style'' as
1909 soon as \csb{etocsettocstyle} is made use of, and for matters of the ``toc
1910 line styles'' as soon as \csb{etocsetlinestyle} is used for \emph{any} level
1911 (part, chapter, section, ...). Levels not receiving explicit configurations
1912 will use some pre-defined defaults which are in \etoc source code.
1913
1914 \begin{description}
1915 \item[\csb{etocclasstocstyle}] sets the `main toc layout' to be as without
1916 |\usepackage{|\etoc\unskip|}|. Local TOCs will also obey the document class
1917 style but with an attempt to use a heading one level down. This tries to
1918 adapt to being in the top level below \csa{part} (i.e. in a \csa{chapter} or
1919 \csa{section}) but is not adapted to deeper local TOCs.
1920
1921 At \etocrelease{1.2}, previously existing \csa{etocstandarddisplaystyle}
1922 was made into a deprecated synonym to this (the version from earlier
1923 releases made no attempt to adapt the style of the local TOCs to the level
1924 where it is located).
1925
1926 \item [\csb{etocetoclocaltocstyle}] (package default) Activates a heading
1927 style for local tables of contents (and ``lists of'') which tries to adapt
1928 automatically to the surrounding level. It thus by-passes the configuration
1929 done by \csb{etocsettocstyle} which will then apply only to the main TOC.
1930 Using again \csb{etocsettocstyle} de-activates this behavior.
1931
1932 \item [\csb{etocusertocstyle}] means to obey the \csb{etocsettocstyle}
1933 configuration as previously in place, not only for the main TOC but also for
1934 local ones. If \csb{etocsettocstyle} has never been used, this means that
1935 we return to the situation from \csb{etocclasstocstyle}.
1936
1937 \item [\csb{etocstandardlines}] (package default) Sets the `content lines' to be as without
1938 |\usepackage{|\etoc\unskip|}|.
1939
1940 \item [\csb{etoctoclines}] sets the `content lines' to match the last encountered
1941 \csb{etocsetlinestyle} specs.
1942
1943 \item [\csb{etocfallbacklines}] sets the `content lines' to use \etoc pre-defined
1944 ones. The denomination is a bit confusing as `default' here means that
1945 these line styles are the ones defined by default, but not used by
1946 default\dots{} perhaps \csa{etocfallbacklines} would have been a better name.
1947
1948 Please be aware that by design the |paragraph| and |subparagraph| linestyles
1949 are configured by \csb{etocfallbacklines} to display nothing at all.
1950
1951 \emph{Nota bene:} this is the same as legacy \csb{etocdefaultlines} which
1952 still exists.
1953 \end{description}
1954
1955 Naturally \csb{etocsettocstyle} and \csb{etocsetlinestyle} can be used arbitrarily
1956 many times in the document body (or already in the preamble but there one can
1957 not typeset a TOC; however one can prepare commands which will be activated
1958 later from inside the document body). And they obey the scope-limiting effect
1959 of \LaTeX{} environments.
1960
1961 For an illustration of using \etoc in compatibility mode see
1962 \autoref{sec:testingcompat}. And see \autoref{sec:anothercompat} for some
1963 ways to let the line styles use the code from the document class but with some
1964 custom changes.
1965
1966 During expansion of \csb{locallistoffigures} or
1967 \csb{locallistoftables}, the macros \csb{etoclocallistoffigureshook} resp.\@
1968 \csb{etoclocallistoftableshook} are executed right before typesetting
1969 the entries. Their default definitions (refer to source code for more info):
1970 \begin{verbatim}
1971 \def\etoclocallistoffigureshook{\etocstandardlines}%
1972 \def\etoclocallistoftableshook {\etocstandardlines}%
1973 \end{verbatim}
1974 means compatibility mode, i.e.\@ the macros \csa{l@figure} and \csa{l@table}
1975 will be the ones involved, as if we were in the global \csa{listoffigures} or
1976 \csa{listoftables}.
1977
1978 If you redefine these ``hook''-macros to do nothing, the figure/table entries
1979 will use the style as appropriate for entries at numerical level one deeper
1980 than the ``local top'': i.e. in a section they will be typeset as if being
1981 subsections. If you have both \csb{locallistoffigures} and a \localtoc, this
1982 may align better vertically than the \LaTeX{} line style from the global
1983 ``Lists Of''.
1984
1985
1986 Note that ``hook'' is used here in a very naive meaning of some macro which is
1987 pre-located somewhere and that one can redefine to obtains various effects.
1988
1989
1990 \section{A list of the commands added at \texorpdfstring{\protect\etocrelease{1.2}}{1.2}}
1991 \label{etocstoretocstyleinto}
1992 \label{etocstorelinestylesinto}
1993 \label{etocstorethislinestyleinto}
1994 \label{etocifislocal}
1995 \label{etocifislocaltoc}
1996 \label{etocifislocallof}
1997 \label{etocifislocallot}
1998 %%\label{etocsettocstyle}
1999 \label{etocifmaintoctotoc}
2000 \label{etociflocaltoctotoc}
2001 \label{etociflocalloftotoc}
2002 \label{etociflocallottotoc}
2003 \label{etocifisstarred}
2004 \label{etoclevel}
2005 \label{etocthelevel}
2006 %%\label{etocthemaxlevel}
2007 \label{etocifunknownlevelTF}
2008 \label{etocdivisionnameatlevel}
2009 \label{etoclocalheadtotoc}
2010 \label{etocglobalheadtotoc}
2011 \label{etocetoclocaltocmaketitle}
2012 %%\label{etocetoclocaltocstyle}
2013 \label{localcontentsname}
2014 \label{locallistfigurename}
2015 \label{locallisttablename}
2016 \label{etocetoclistoffiguresmaketitle}
2017 \label{etocetoclistoftablesmaketitle}
2018 \label{etocclasslocaltocmaketitle}
2019 \label{etocclasslocallofmaketitle}
2020 \label{etocclasslocallotmaketitle}
2021 \label{etocclassmaintocaddtotoc}
2022 \label{etocclasslocaltocaddtotoc}
2023 \label{etocclasslocallofaddtotoc}
2024 \label{etocclasslocallotaddtotoc}
2025
2026 \begin{shaded}\footnotesize
2027 %\setstretch{1}
2028 One pre-existing command has been modified: \csa{etocstandarddisplaystyle}
2029 which is now deprecated and replaced by \csb{etocetoclocaltocstyle}. The
2030 former behavior was to set also local TOCs to apply the style from the main
2031 TOC, which basically never works really well. As explained already one can
2032 use \csb{etocclasstocstyle} to try to get for top local TOCs a suitable
2033 behavior, for example in the case of \ctanpkg{KOMA-script} classes, a
2034 behavior using their |leveldown| option. But this will not be satisfactory
2035 for deeper local TOCs or ``lists of''.
2036 \end{shaded}
2037
2038 \DeleteShortVerb\|
2039
2040 First there is \csb{etocsetup}:
2041 \begin{description}
2042 \item [\csb{etocsetup}\marg{key[=true|false],...}] has already been mentioned
2043 earlier. It is usable with \etocoption{maintoctotoc},
2044 \etocoption{localtoctotoc}, \etocoption{localloftotoc},
2045 \etocoption{locallottotoc}, and \etocoption{ouroboros}, everywhere in the
2046 document after the package loading.
2047 \end{description}
2048
2049 \MakeShortVerb\|
2050
2051 Then some utilities relative to the
2052 \csb{etocsetlevel} command:
2053 \begin{itemize}
2054 \item \csb{etoclevel}\marg{levelname} expands to a numeric quantity giving the
2055 level of a given string argument. For example \csb{etoclevel}|{section}|
2056 will usually produce a \TeX{} number denotation of value one. It is
2057 provided for matters of programming, as its output format is suitable for
2058 usage in \csa{ifnum} test. For typesetting, it should be prefixed
2059 by the \TeX{} primitive \csa{number}.
2060
2061 \item \csb{etocthelevel}\marg{levelname} expands to a explicit digits
2062 (possibly prefixed by a minus sign), i.e.\@ it is equivalent to
2063 |\number|\csb{etoclevel}\marg{levelname} and is provided as a
2064 convenience. (added at \etocrelease{1.2a})
2065
2066 \item \csb{etocthemaxlevel} expands to either |12| or |6| (default) depending
2067 on whether the \etocoption{deeplevels} option was used or not. See the
2068 documentation of \csb{etocsetlevel} for more. (added at \etocrelease{1.2a})
2069
2070 \item \csb{etocifunknownlevelTF}\marg{levelname}\marg{True}\marg{False} is a
2071 conditional to test if a level name has been declared to \etoc.
2072 \end{itemize}
2073
2074 Then two utilities to help store and restore toc line styles:
2075
2076 \begin{description}
2077 \item [\csb{etocstorelinestylesinto}\marg{control\_sequence}] This is a
2078 command with one mandatory argument which must be a control sequence such as
2079 \csa{foo}. The macro \csa{foo} is then overwritten with no check if it
2080 exists already. Its effect is to store inside \csa{foo} the current toc
2081 line styles configuration, for all levels at once. Then inserting \csa{foo}
2082 in the document will restore all line styles to the state they were in at
2083 time of usage of \csb{etocstorelinestylesinto}.
2084
2085 \item [\csb{etocstorethislinestyleinto}\marg{name or
2086 number}\marg{control\_sequence}] Same principle but now \csa{foo} will
2087 store the line style for the specified level only. This argumant can be
2088 numerical or a name. And thus executing \csa{foo} will then have the same
2089 effect as re-doing the \csb{etocsetlinestyle} for that level.
2090 \end{description}
2091
2092 The more numerous additions are relative to usage of \csb{etocsettocstyle},
2093 i.e.\@ customizing the ``display'' style. This mainly means matters relative
2094 to the title of the local TOCs or Lists Of, inclusive of whether they should
2095 add an entry into the |.toc| file matching their titles. Indeed, please be
2096 aware that as soon as you use \csb{etocsettocstyle} you will have to handle
2097 yourself the support for such behavior. Of course, as you also control the
2098 options, you don't have to use the provided command layer which tests the
2099 status of these options, but it is provided anyway as public interface.
2100 Indeed all of this is done via commands with no |@| letter in their names, and
2101 the package itself uses this public interface in its implementation of the
2102 default behavior, adjusted to the document class. The documentation here is
2103 brief, check for more the source code to which the listed commands are
2104 hyperlinked (from the last third of their names).
2105
2106 Some of these commands are defined via batch processing done in loops in the
2107 code, and the hyperlinks only point to some initial dummy definitions, which
2108 were added only to provide such link targets, and one has to read the code
2109 further to discover the actual definitions.
2110
2111 \begin{itemize}
2112 \item \csb{etocifislocal}, \csb{etocifislocaltoc}, \csb{etocifislocallof},
2113 \csb{etocifislocallot} can be used from inside the \csb{etocsettocstyle}
2114 first or second argument to select either one of the \marg{True} and
2115 \marg{False} branches.
2116
2117 \item \csb{etocifmaintoctotoc}, \csb{etociflocaltoctotoc},
2118 \csb{etociflocalloftotoc}, \csb{etociflocallottotoc}, are conditionals
2119 matching the options and selecting one of the \marg{True} or \marg{False}
2120 branches.
2121
2122 \item \csb{etocifisstarred}\marg{True}\marg{False} says from inside the
2123 \csb{etocsettocstyle} arguments if the toc or `list of' command was in
2124 starred form.
2125
2126 The \csb{etocetoclocaltocstyle} and \csb{etocclasstocstyle} have been
2127 configured so that when a |*| follows a \toc or \localtoc or local ``lists
2128 of'', its ``to toc'' behavior (if active from \ctanpkg{tocbibind} or \etoc
2129 own options) is canceled. They use \csb{etocifisstarred} to this effect.
2130
2131 \item \csb{etoclocalheadtotoc}\marg{levelname}\marg{text} is a synonym for
2132 \centeredline{\csa{addcontentsline}|{toc}|\marg{@levelname}\marg{text}}
2133 %
2134 Pay
2135 attention to automatically added |@| character.%
2136 %
2137 \footnote{Without this syntax, it would not be possible to have all three of
2138 \localtoc, \csb{locallistoffigures} and \csb{locallistoftables} one after
2139 the other following a given document heading, due to deep internals of the
2140 local TOC \etoc mechanism. Notice that these internal details are
2141 susceptible to change with no advance notice and the actual implementation
2142 of \csb{etoclocalheadtotoc} may change.}
2143
2144
2145 Use this for example in the second argument of \csb{etoclocalmulticol}.%
2146 %
2147 \footnote{There is currently no analog of \csb{etoclocalmulticol} and similar
2148 commands which would be related to \csb{locallistoffigures} or
2149 \csb{locallistoftables} as \csb{etoclocalmulticol} is to \localtoc.}
2150
2151 \item \csb{etocglobalheadtotoc}\marg{levelname}\marg{text} is a synonym for
2152 \centeredline{\csa{addcontentsline}|{toc}|\marg{levelname}\marg{text}}
2153 %
2154 We have so many commands we can define another useless one\dots{} for
2155 aesthetic reasons of coherent names\dots{}
2156
2157 \item \csb{etocdivisionnameatlevel}\marg{number} is an expandable construct
2158 which starts from a numerical level from |-2| to |5| and produces one of
2159 |book|, |part|, ..., up to |subparagraph| as per the built-in \LaTeX\
2160 (and standard classes) default assignments (and \ctanpkg{memoir} for
2161 |book|).
2162
2163 Under option \etocoption{deeplevels} the numerical level can go up to |11|
2164 but as there is no standard default for documents with extra sectioning
2165 commands (e.g. is it using \csa{subsubsubparagraph}? or
2166 \csa{subsubsubsection}? or some \csa{subivsection}?), the user has probably
2167 to copy and redo with changes the package definition of
2168 \csb{etocdivisionnameatlevel} in that case.
2169
2170 \item \csb{etocetoclocaltocmaketitle} is the command used by
2171 \csb{etocetoclocaltocstyle} which typesets a local ``list of'' title using
2172 an un-numbered sectioning appropriate to its scope. See the source code for
2173 how it looks.
2174
2175 \item \csb{etocetoclistoffiguresmaketitle} and
2176 \csb{etocetoclistoftablesmaketitle} are similar, see the source code.
2177
2178 \item \csb{localcontentsname}, \csb{locallistfigurename},
2179 \csb{locallisttablename} are self-explanatory.
2180
2181 \item \csb{etocclasslocaltocmaketitle}, \csb{etocclasslocallofmaketitle},
2182 \csb{etocclasslocallotmaketitle}, \csb{etocclassmaintocaddtotoc},
2183 \csb{etocclasslocaltocaddtotoc}, \csb{etocclasslocallofaddtotoc},
2184 \csb{etocclasslocallotaddtotoc}, well again see source code.
2185 \end{itemize}
2186
2187 Finally there is a command to help store/restore a given display style configuration.
2188 \begin{description}
2189 \item [\csb{etocstoretocstyleinto}\marg{control\_sequence}] This is a command
2190 with one mandatory argument which must be a control sequence such as
2191 \csa{foo}. The macro \csa{foo} is then overwritten with no check if it
2192 exists already. Its effect is to store inside \csa{foo} the data configured
2193 by the last \csb{etocsettocstyle}. Then inserting \csa{foo} in the document
2194 will restore the saved toc style.%
2195 %
2196 \footnote{It is impossible to store the style used by the
2197 \csb{etocetoclocaltocstyle} for local TOCs. Only the one for main TOCs,
2198 which was configured by last usage of \csb{etocsettocstyle} is saved in
2199 \csa{foo}. After \csa{foo} is executed, one needs to again issue
2200 \csb{etocetoclocaltocstyle} if one wants the latter to be active.}
2201 \end{description}
2202
2203
2204
2205 % {\footnotesize (clearing this page as next display must be on one page
2206 % only)\par}
2207 % \clearpage
2208
2209 \section{A partial list of the package commands}
2210
2211 %\enlargethispage{2\baselineskip}
2212
2213 %\vskip-\baselineskip\vskip0pt
2214
2215
2216
2217
2218 %\parshape 1 -1.5cm \dimexpr\linewidth+3cm\relax
2219 %\begin{minipage}{\dimexpr\linewidth+3cm\relax}
2220 \begin{multicols}{2}\parindent0pt\relax\setstretch{1}%
2221 \csb{etocbeforetitlehook}\par
2222 \csb{etocaftertitlehook}\par
2223 \csb{etocaftercontentshook}\par
2224 \csb{etocaftertochook}\par
2225 \csb{etocsettocstyle}\par
2226 \csb{etocclasstocstyle}\par
2227 \csb{etocetoclocaltocstyle}\par
2228 \csb{etocmulticol}\par
2229 \csb{etocframed}\par
2230 \csb{etocruled}\par
2231 \csb{etocsettocdepth}\par
2232 \csb{etocsettocdepth.toc}\par
2233 \csb{etocsetnexttocdepth}\par
2234 \csb{etocdepthtag.toc}\par
2235 \csb{etocsettagdepth}\par
2236 \csb{etocobeydepthtags}\par
2237 \csb{etocfallbacklines}\par
2238 \csb{etocstandardlines}\par
2239 \csb{etoctoclines}\par
2240 \csb{etocsetlevel}\par\columnbreak
2241 \flushright
2242 \csb{etocsetlinestyle}\par
2243 \csb{etocskipfirstprefix}\par
2244 \csb{etocifnumbered}\par
2245 \csb{etociffirst}\par
2246 \csb{etoclink}\par
2247 \csb{etocthelink}\par
2248 \csb{etocname}\par
2249 \csb{etocnumber}\par
2250 \csb{etocpage}\par
2251 \csb{etocthename}\par
2252 \csb{etocthenumber}\par
2253 \csb{etocthepage}\par
2254 \csb{etocthelinkedname}\par
2255 \csb{etocthelinkednumber}\par
2256 \csb{etocthelinkedpage}\par
2257 % \csb{etocdisplay}\par
2258 % \csb{etocframedstyle}\par
2259 % \csb{etocignoredepthtags}\par
2260 % \csb{etocignoretoctocdepth}\par
2261 % \csb{etocimmediatedepthtag.toc}\par
2262 % \csb{etocimmediatesettocdepth.toc}\par
2263 % \csb{etocimmediatetoccontentsline}\par
2264 % \csb{etocinline}\par
2265 % \csb{etoclocalframed}\par
2266 % \csb{etoclocalmulticol}\par
2267 % \csb{etoclocalruled}\par
2268 % \csb{etocmulticolstyle}\par
2269 % \csb{etocobeytoctocdepth}\par
2270 % \csb{etocruledstyle}\par
2271 % \csb{etoctoccontentsline}\par
2272 %\flushright
2273 \csb{localtableofcontents}\par
2274 \mbox{}\llap{\csb{localtableofcontentswithrelativedepth}}\par
2275 \csb{locallistoffigures}\par
2276 \csb{locallistoftables}\par
2277 \csb{tableofcontents}\par
2278 %\vspace{5\baselineskip}\hrule height 0pt
2279 \end{multicols}
2280 %\end{minipage}\par
2281
2282
2283 {\footnotesize\setstretch{1}
2284 The above is not an exhaustive list of all the package user commands.
2285 For example, it does not include most of those added at \etocrelease{1.2}
2286 and which were listed in the previous section.\par
2287 }
2288
2289 \clearpage
2290
2291
2292 \etocdepthtag.toc {styling}
2293 \part{The \etoc styling commands}
2294 \label{part:styling}
2295
2296 \thispartstats
2297
2298 \etocsetlinestyle{section}
2299 {\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered
2300 {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]}
2301 {\normalsize\bfseries\rmfamily\item}
2302 {\etocname{} (page \etocpage)}
2303 {\end{enumerate}}
2304
2305 \etocsetlinestyle{subsection}
2306 {\begin{enumerate}[leftmargin=0cm, label=\etocnumber]}
2307 {\normalfont \item}
2308 {\etocname{} (p.~\etocpage)}
2309 {\end{enumerate}}
2310
2311 \etocsetlinestyle{subsubsection}
2312 {\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix}
2313 {\allowbreak\,--\,}
2314 {\etocname}
2315 {.\hfil\par\endgroup\pagebreak[3]}
2316
2317 % 27 janvier 2013 22:30
2318 % je définis les macros (non protégées)
2319 % \etocthename, \etocthenumber, \etocthepage
2320
2321 \etocruledstyle[1]{\etocfontminusone\color{green}%
2322 \fboxrule1pt\fboxsep1ex
2323 \framebox[\linewidth]
2324 {\normalcolor\hss Contents of \autoref{part:styling}\hss}}
2325
2326 \localtableofcontents \label{toc:part:styling}
2327
2328 The two main commands \csb{etocsettocstyle} and \csb{etocsetlinestyle} can be used
2329 anywhere in the document. Typically one will render the main global TOC in
2330 one style and local tables of contents in another. So the commands to style
2331 the local tables of contents will be executed after the main \toc (if it is
2332 first in document) either by direct injection in the document source, or
2333 encapsulated in user commands defined in the preamble.
2334
2335 All commands obey the scope limiting effect induced by \LaTeX{} environments
2336 or the core \TeX |\begingroup/\endgroup| (or braces |{...}|) constructs.
2337
2338 \section{The \csbhyp{etocsettocstyle} and related commands}
2339 \label{sec:tocstyle}
2340
2341 \begingroup
2342 \etocsettocstyle{}{}
2343 \etocstandardlines
2344 \microtypesetup{protrusion=false}
2345 \DeclareTOCStyleEntry[numwidth=3em,indent=0em]{tocline}{subsection}
2346 \DeclareTOCStyleEntry[numwidth=3.5em,indent=3em]{tocline}{subsubsection}
2347 \localtableofcontents \label{toc:tocstyle}
2348 \endgroup
2349
2350
2351
2352 \subsection{The \csbhyp{etocsettocstyle} command}
2353 \label{etocsettocstyle}
2354
2355 The basics are explained in \autoref{etocsettocstyleintro}. Recall that the
2356 syntax is
2357 \centeredline{\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}} and
2358 here is a typical example of use:
2359 \begin{verbatim}
2360 \etocsettocstyle
2361 {\section*{Local table of contents}}%
2362 {}% don't do anything special after the toc contents
2363 \end{verbatim}
2364
2365 The first argument to \csb{etocsettocstyle} can also contain instructions to
2366 mark the page headings. Or it could check to see if two-column mode is on,
2367 and switch to one-column style, and the \meta{after\_toc} part would then
2368 reenact the two-column mode.
2369
2370
2371 The commands to be described next \csb{etocmulticolstyle},
2372 \csb{etocruledstyle}, and \csb{etocframedstyle} all call \csb{etocsettocstyle}
2373 as a lower-level routine, to initiate a \texttt{multi\-cols} environment in
2374 \marg{before\_toc} and close it in \marg{after\_toc}.
2375
2376 \subsubsection{The \csbhyp{etocarticlestyle}, \csbhyp{etocbookstyle},
2377 and others commands}
2378 \label{etocarticlestyle}
2379 \label{etocarticlestylenomarks}
2380 \label{etocbookstyle}
2381 \label{etocbookstylenomarks}
2382 \label{etocreportstyle}
2383 \label{etocreportstylenomarks}
2384
2385 These are the commands used internally by \etoc in compatibility mode
2386 depending on the document class. For example \csb{etocarticlestyle} instructs
2387 \etoc to use |\section*{\contentsname}| (with marks on the page) and
2388 \csb{etocbookstyle} says to use |\chapter*{\contentsname}|. It can prove
2389 useful to issue \csb{etocarticlestyle} for a \csa{localtableofcontents} inside
2390 a chapter, in |book| class and compatibility mode for the global TOC display
2391 style.
2392
2393 Here is the current list:
2394 \begin{itemize}[nosep]
2395 \item \csb{etocarticlestyle}
2396 \item \csb{etocarticlestylenomarks}
2397 \item \csb{etocreportstyle}
2398 \item \csb{etocreportstylenomarks}
2399 \item \csb{etocbookstyle}
2400 \item \csb{etocbookstylenomarks}
2401 \item \csb{etocmemoirstyle}
2402 \item \csb{etocscrartclstyle}
2403 \item \csb{etocscrreprtstyle}
2404 \item \csb{etocscrbookstyle}
2405 \end{itemize}
2406 The command \csb{etocclasstocstyle} will adapt to the document class.
2407 One can not use the \ctanpkg{KOMA-script} related commands or the
2408 \ctanpkg{memoir} one in standard classes.
2409
2410
2411 \subsubsection{The \csbhyp{etocinline} and \csbhyp{etocdisplay} commands}
2412 \label{etocinline}
2413 \label{etocnopar}
2414 \label{etocdisplay}
2415
2416 With \csb{etocinline}, or its synonym |\etocnopar|, the \localtoc command and
2417 its variants do \emph{not} first issue a |\par| to close the previous
2418 paragraph. Hence, the table of contents can be printed in an inline style; or,
2419 if used only for preparing some token list or macro, it will leave nothing in
2420 the token stream on execution.
2421
2422 Issue \csb{etocdisplay} to return to the default situation that \localtoc and
2423 variants issue a |\par| to switch to vertical mode before typesetting the TOC
2424 title and contents.
2425
2426 Here is an example of an \emph{inline} table of contents, which has only
2427 subsections and uses the |itemize*| environment from \ctanpkg{enumitem} for
2428 them. The code used is
2429 \begin{verbatim}
2430 And the output is:
2431 \begingroup
2432 \etocglobaldefs
2433 \etocsetlinestyle {subsection}
2434 {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
2435 {}
2436 {\item [{\bfseries\etocnumber.}] \etocname\ (\emph{p. \etocpage })}
2437 {\end{itemize*}.}%
2438 \etocsetnexttocdepth {subsection}%
2439 \etocsettocstyle {a clone of a local table of contents, originally defined in
2440 \autoref{sec:tocstyle}, but here rendered completely
2441 differently via an inline \ctanpkg{enumitem} list: }{}%
2442 \etocinline\tableofcontents \ref{toc:tocstyle}
2443 \endgroup
2444 \end{verbatim}
2445
2446 (observe that on executing the above there is no extra space after the colon
2447 beyond what is intended, and the current paragraph is simply continued)
2448 And the output is:
2449 \begingroup
2450 \etocglobaldefs
2451 \etocsetlinestyle {subsection}
2452 {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
2453 {}
2454 {\item [{\bfseries\etocnumber.}] \etocname\ (\emph{p. \etocpage })}
2455 {\end{itemize*}.}%
2456 \etocsetnexttocdepth {subsection}%
2457 \etocsettocstyle {a clone of a local table of contents, originally defined in
2458 \autoref{sec:tocstyle}, but here rendered completely
2459 differently via an inline \ctanpkg{enumitem} list: }{}%
2460 \etocinline\tableofcontents \ref{toc:tocstyle}
2461 \endgroup
2462
2463 It was needed to use \csb{etocglobaldefs} because the \csa{item} command,
2464 as modified by \ctanpkg{enumitem} closes a group, hence the meaning
2465 of \csb{etocname}, \csb{etocnumber} and \csb{etocpage} would have been lost
2466 after it.
2467
2468 A more impressive example of an inline table of contents (containing the full
2469 contents of this document, which subsections rendered as page footnotes...) is
2470 to be found in \autoref{sec:crazy}.
2471
2472 \subsection{The \csbhyp{etocmulticolstyle}, \csbhyp{etocmulticol},
2473 and \csbhyp{etoclocalmulticol} commands}
2474 \label{etocmulticolstyle}
2475 \label{etocmulticol}
2476 \label{etoclocalmulticol}
2477
2478 This is a command with one optional and one mandatory argument:
2479 \centeredline{\csb{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}}
2480 The
2481 \meta{number\_of\_columns} can go from 1 to 10 (it defaults to 2; if its
2482 value is 1, naturally no |multicols| environment is then created). The
2483 \meta{heading} will typically be some `vertical' material like:
2484 \meta{heading} = |\section*|\marg{title}
2485 but one may also have horizontal material like |\fbox{Hello World}| (\etoc
2486 adds automatically a |\par| at the end of this ``heading'' argument to
2487 \csb{etocmulticolstyle}). Here is an example:
2488 \begin{verbatim}
2489 \etocmulticolstyle{\noindent\bfseries\Large
2490 \leaders\hrule height1pt\hfill
2491 \MakeUppercase{Table of Contents}}
2492 \localtableofcontents
2493 \end{verbatim}
2494 After \csb{etocmulticolstyle} all future \csa{tableofcontents} will use the
2495 specified style until modified by renewed usage of \csb{etocsettocstyle} or variants.
2496
2497 A shortcut combining the style specification and the table of contents and not
2498 impacting the styles of later TOCs is:%
2499 %
2500 \centeredline{\csb{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}}
2501 %
2502 So the above example can be also obtained using:
2503 \begin{verbatim}
2504 \etoclocalmulticol{\noindent\bfseries\Large
2505 \leaders\hrule height1pt\hfill
2506 \MakeUppercase{Table of Contents}}
2507 \end{verbatim}
2508 %
2509 It has the advantage that the TOC styling as specified applies only to this
2510 sole local TOC.
2511
2512 And there is also
2513 \csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading} for global TOC.
2514
2515 \subsection{The \csbhyp{etoctocstyle} command}
2516 \label{etoctocstyle}
2517
2518 \centeredline{\csb{etoctocstyle}\oarg{kind}\marg{number\_of\_columns}\marg{title}%
2519 }
2520 %
2521 is the exact equivalent of doing
2522 %
2523 \centeredline{%
2524 \csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
2525 |{\kind*{|\itshape title\upshape|}}|}
2526 %
2527 where |kind| is one of |chapter|, |section|, . . . and defaults
2528 to |chapter| or |section| depending on the document class.
2529
2530 As explained above one still has to issue \localtoc to typeset the TOC. And
2531 the styling, if not enclosed in a scope-limiting group or environment, applies
2532 to subsequent local TOCs.
2533
2534 \subsubsection{The \csbhyp{etoctocstylewithmarks} command}
2535 \label{etoctocstylewithmarks}
2536 \label{etoctocstylewithmarksnouc}
2537
2538 \centeredline{\csb{etoctocstylewithmarks}\oarg{kind}%
2539 \marg{number\_of\_columns}\marg{title}\marg{mark}%
2540 }
2541 %
2542 is the exact equivalent of doing
2543 %
2544 \centeredline
2545 {\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
2546 |{\kind*{|\itshape title \ttfamily\upshape\string\markboth%
2547 |{\MakeUppercase{|{\rmfamily\itshape mark}|}}}}|}
2548 %
2549 where |kind| is one of |chapter|, |section|, ... The
2550 actual display of the marks depends on the settings of the
2551 page style. There is variant \csb{etoctocstylewithmarksnouc}
2552 which does not uppercase.
2553
2554 \paragraph{Do we really want paragraph entries in the TOC?}
2555
2556 \paragraph{really?}
2557
2558 \subsection{The \csbhyp{etocruledstyle}, \csbhyp{etocruled} and
2559 \csbhyp{etoclocalruled} commands}
2560 \label{etocruledstyle}
2561 \label{etocruled}
2562 \label{etoclocalruled}
2563
2564 The general format of \csb{etocruledstyle} is:
2565 %
2566 \centeredline{\csb{etocruledstyle}%
2567 \oarg{number of columns}\marg{title of the toc}%
2568 }%
2569 \noindent
2570 The title is horizontal material (the |LR| mode of
2571 \emph{\LaTeX{}, a document preparation system}): if it
2572 does not fit on one line it should be put in a \csa{parbox} of
2573 a given width.
2574 The green frame for the heading of the table of contents at
2575 the \hyperref[toc:part:styling]{the start of this part} was obtained with:
2576 \begin{verbatim}
2577 \etocruledstyle[1]{\etocfontminusone\color{green}%
2578 \fboxrule1pt\fboxsep1ex
2579 \framebox[\linewidth]
2580 {\normalcolor\hss Contents of this part\hss}}
2581 \localtableofcontents
2582 \end{verbatim}
2583
2584 As a shortcut to set the style with \csb{etocruledstyle} and then issue a
2585 \localtoc, all inside a group so that future table of contents will not be
2586 affected, there is:
2587 %
2588 \centeredline{\csb{etoclocalruled}\oarg{number\_of\_columns}\marg{title}}
2589 %
2590 And there is also \csb{etocruled} for the global TOC.
2591
2592 \subsection{The \csbhyp{etocframedstyle}, \csbhyp{etocframed}, and
2593 \csbhyp{etoclocalframed} commands}
2594 \label{etocframedstyle}
2595 \label{etocframed}
2596 \label{etoclocalframed}
2597
2598 Same mechanism:
2599 %
2600 \centeredline{\csb{etocframedstyle}\oarg{number\_of\_columns}\marg{title}}
2601 %
2602 and the accompanying shortcut:
2603 %
2604 \centeredline{\csb{etoclocalframed}\oarg{number\_of\_columns}\marg{title}}
2605 %
2606 The
2607 shortcut is used if one does not want to modify the style of the next
2608 TOCs (the other way is to put the whole thing inside braces or a
2609 |\begingroup...\endgroup|; there is also \csb{etocframed} for a
2610 global table of contents).
2611
2612 The entire table of contents is framed. The title itself is not framed:
2613 if one wants a frame one should set it up inside the \meta{title}
2614 argument to \csb{etocframedstyle} or \csb{etocframed}. The colors for
2615 the background and for the components (top, left, right, bottom) of the
2616 border are specified via suitable |\renewcommand|'s (see
2617 \autoref{ssec:customdisplay}).
2618
2619 A |minipage| is used, hence the produced table of contents isn't compatible
2620 with a page break. For allowing page breaks, use of the commands of
2621 \ctanpkg{mdframed} or \ctanpkg{tcolorbox} in the arguments of
2622 \csb{etocsettocstyle} is recommended.
2623
2624 Examples in this document are on pages \pageref{toc:d},
2625 \pageref{toc:floating}, \pageref{toc:b}, and \pageref{toc:clone}.
2626
2627
2628 \subsection{Customizing the pre-defined toc display styles}
2629 \label{ssec:customdisplay}
2630 \label{etocabovetocskip}
2631 \label{etocbelowtocskip}
2632 \label{etoccolumnsep}
2633 \label{etocmulticolsep}
2634 \label{etocmulticolpretolerance}
2635 \label{etocmulticoltolerance}
2636 \label{etocdefaultnbcol}
2637 %\label{etocinnertopsep}% déjà défini
2638 \label{etoctoprule}
2639 \label{etoctoprulecolorcmd}
2640 \label{etocinnerleftsep}
2641 \label{etocinnerrightsep}
2642 \label{etocinnerbottomsep}
2643 \label{etocleftrule}
2644 \label{etocrightrule}
2645 \label{etocbottomrule}
2646 \label{etocleftrulecolorcmd}
2647 \label{etocrightrulecolorcmd}
2648 \label{etocbottomrulecolorcmd}
2649 \label{etocbkgcolorcmd}
2650 \label{etocframedmphook}
2651
2652 We list the relevant macros, what they do should be legible from their
2653 names. Note that dimensions are stored in macros so are modifed using
2654 \csa{renewcommand}'s and not \csa{setlength}'s. And color related commands
2655 are not color definitions, they execute \csa{color}, and their effect gets canceled
2656 by re-defining them to do \csa{relax} or \csa{empty}.
2657 \begin{verbatim}
2658 \newcommand*\etocabovetocskip{3.5ex plus 1ex minus .2ex}
2659 \newcommand*\etocbelowtocskip{3.5ex plus 1ex minus .2ex}
2660
2661 \newcommand*\etoccolumnsep{2em}
2662 \newcommand*\etocmulticolsep{0ex}
2663 \newcommand*\etocmulticolpretolerance{-1}
2664 \newcommand*\etocmulticoltolerance{200}
2665 \newcommand*\etocdefaultnbcol{2}
2666 \newcommand*\etocinnertopsep{2ex}
2667 \newcommand*\etoctoprule{\hrule}
2668 \newcommand*\etoctoprulecolorcmd{\relax}
2669
2670 % for the framed style only:
2671 \newcommand*\etocinnerleftsep{2em}
2672 \newcommand*\etocinnerrightsep{2em}
2673 \newcommand*\etocinnerbottomsep{3.5ex}
2674
2675 \newcommand*\etocleftrule{\vrule}
2676 \newcommand*\etocrightrule{\vrule}
2677 \newcommand*\etocbottomrule{\hrule}
2678 \newcommand*\etocleftrulecolorcmd{\relax}
2679 \newcommand*\etocrightrulecolorcmd{\relax}
2680 \newcommand*\etocbottomrulecolorcmd{\relax}
2681
2682 \newcommand*\etocbkgcolorcmd{\relax}
2683
2684 % hooks
2685 \newcommand\etocframedmphook{\relax}
2686 \end{verbatim}
2687
2688 The \csa{etocframedmphook} is positioned immediately
2689 after the beginning of a minipage environment where the
2690 contents of the framed TOC are typeset.
2691
2692 The \csa{...colorcmd} commands are initially set to expand to
2693 \csa{relax} (hence do not require package |color| or |xcolor|
2694 to be loaded). If one has modified a command such as
2695 \csa{etocbkgcolorcmd} to expand to a color command and wants
2696 to reset it to do nothing, one \emph{must} use
2697 |\renewcommand{\etocbkgcolorcmd}{\relax}| and not
2698 \csa{let}\csa{etocbkgcolorcmd}\csa{relax}.
2699
2700 Regarding the dimensions of the top rule they can be specified
2701 in |ex|'s or |em|'s as in this example:
2702 \centeredline{|\renewcommand{\etoctoprule}{\hrule height 1ex}|}
2703 The package code is done in such a manner
2704 that it is the font size in instance at the end of typesetting
2705 the title argument to \csb{etocruled} or
2706 \csb{etocframed} which will be used for the meaning of the
2707 `1ex'. Of course also the other rule commands can have their
2708 dimensions in font relative units, but their values are
2709 decided on the basis of the font in effect just before the
2710 table of contents.
2711
2712 The top and bottom rules do not have to be rules and can be
2713 horizontal \emph{leaders} (of a specified height) in the general
2714 \TeX{} sense. However the left and right rules are not
2715 used as (horizontal) leaders but as objects of a given specified
2716 width. Note that \emph{only} the Plain \TeX{} syntax for rules is
2717 accepted here.
2718
2719
2720 \subsection{Headings, titles, \csbhyp{etocoldpar}, \csbhyp{etocinnertopsep}}
2721 \label{etocinnertopsep}
2722 \label{etocoldpar}
2723
2724 For \csb{etocmulticolstyle} the mandatory \meta{heading} argument can be
2725 either
2726 vertical mode material like |\section*{\emph{Table of Contents}}| or
2727 horizontal mode material like in the simple |\etocmulticolstyle{Hello World}|.
2728
2729 No explicit |\par| or empty line can be inserted in the mandatory
2730 argument of \csb{etocmulticolstyle}, but \etoc provides \csb{etocoldpar}
2731 as a substitute: it does |\let\etocoldpar\par| before the |multicols|
2732 environment and inserts this |\etocoldpar|\footnote{this command
2733 \csb{etocoldpar} (= working \csa{par} in the argument to
2734 \csb{etocmulticolstyle}) is not related to the switch \csb{etocinline}
2735 whose purpose is to tell \etoc not to do a \csa{par} before the table
2736 of contents.} at the end of the heading, then does a vertical skip of
2737 value \csb{etocinnertopsep}. The command \csb{etocoldpar} can also be
2738 used explicitely if needed in the mandatory argument to
2739 \csb{etocmulticolstyle} (it is not allowed to insert an empty line
2740 in this argument).
2741
2742 On the other hand the commands \csb{etocruledstyle} and
2743 \csb{etocframedstyle} expect an argument ``in LR mode'' (to use the
2744 terminology from \emph{LaTeX, a document preparation system}). This
2745 means that multiline titles are only possible if enclosing
2746 them inside something like a \csa{parbox}.
2747
2748 An important dimension used by all three of \csb{etocmulticolstyle},
2749 \csb{etocruledstyle} and \csb{etocframedstyle} is
2750 \csb{etocinnertopsep}. It gives the amount of separation
2751 between the heading and the start of the contents. Its default
2752 value is |2ex| and it is changed with
2753 |\renewcommand*{\etocinnertopsep}|\marg{new\_value}, not with
2754 |\setlength|.
2755
2756
2757 \section{Starred variants and hooks}
2758 \label{tableofcontents*}
2759 \label{localtableofcontents*}
2760 \label{etocbeforetitlehook}
2761 \label{etocaftertitlehook}
2762 \label{etocaftercontentshook}
2763 \label{etocaftertochook}
2764
2765 The \toc, \localtoc, \csb{etocmulticol}, and all their cousins have starred
2766 variants (the star must be before the other arguments). The non-starred
2767 variants execute the \csb{etocaftertitlehook}, whose default definition is to
2768 do nothing. The starred variants do not execute this hook.
2769
2770 For example, imagine you are using |book| class and want \localtoc to use a
2771 section-like title, but unnumbered. Assuming the main \toc comes first in the
2772 document, you can insert this after it:
2773 \begin{verbatim}
2774 \etocarticlestyle
2775 \renewcommand{\etocaftertitlehook}{\addcontentsline{toc}{section}{\contentsname}}
2776 \end{verbatim}
2777 This configures the way \localtoc will behave (or \toc) from now on in the
2778 document.
2779
2780 The first line tells essentially to use |\section*{\contentsname}|, and the
2781 second line says to insert the title in the |.toc| file itself (thus to be
2782 displayed by the main table of contents). Notice that \ctanpkg{hyperref} package will
2783 then automatically create suitable anchor and one should \emph{not} use
2784 explicitly \cs{phantomsection} here (it would let the anchor be located below
2785 not above the title).
2786
2787 % problème avec \xspace
2788 With this set-up issuing \localtoc\unskip|*| will ignore the \csb{etocaftertitlehook}
2789 hence not send the local toc title to the |.toc| file. This mimics the
2790 \ctanpkg{memoir} class behavior, and can also be used with it. For more on \ctanpkg{memoir}
2791 class with \etoc, see \autoref{ssec:memoir}.
2792
2793 There are further hook macros:
2794 \csb{etocaftercontentshook}, \csb{etocbeforetitlehook} and
2795 \csb{etocaftertochook} which are initially defined to do nothing and can be
2796 used for some special effects. They are executed whether or not the table of
2797 contents command was starred.
2798
2799 For example, the present document executed
2800 \begin{verbatim}
2801 \renewcommand{\etocbeforetitlehook}{\setstretch{1}}
2802 \end{verbatim}
2803 as it is globally using the \ctanpkg{setspace} command \csa{onehalfspacing}.
2804 Not using \csa{singlespacing} in the hook as it does a systematic vertical
2805 skip of one baseline, which is unwanted in our usage.
2806
2807 \begin{framed}
2808 In recent years, the \LaTeX{} kernel has added a general ``hook'' mechanism
2809 with a user interface of the type |\AddToHook{...}{...}|.
2810
2811 The \etoc macros with `hook' ending their names are much simpler things
2812 which are supposed to be manipulated only via \csa{renewcommand} or
2813 \csa{def} direct overwrites.
2814
2815 In future, and to the extent the author has time for that addition, with its
2816 costly documentation updates collaterals, and thoughts about backward
2817 compatibility, \etoc should arguably tap into the general tools provided by
2818 recent \LaTeX{} kernels.
2819 \end{framed}
2820
2821 \section{The \csbhyp{etocsetlinestyle} and related commands}
2822 \label{sec:linestyles}
2823 \label{etocsetstyle}
2824 \label{etocsetlinestyle}
2825 \label{etocname}
2826 \label{etocpage}
2827
2828 \begingroup
2829 \etocsettocstyle{}{}
2830 %\setuptoc{toc}{noprotrusion}% pas d'effet mais c'est normal car ce n'est pas
2831 % % KOMA mais etoc qui fait le style global
2832 \microtypesetup{protrusion=false}
2833 \DeclareTOCStyleEntry[numwidth=3.2em,indent=0em]{tocline}{subsection}
2834 \etocstandardlines
2835 \localtableofcontents \label{toc:linestyles}
2836 \endgroup
2837
2838 Remark: \csb{etocsetlinestyle} is an alias added at \etocrelease{1.2e} for
2839 the legacy \csb{etocsetstyle}. The documentation has been updated to use
2840 everywhere the new preferred name. Here ``line'' refers to the fact that the
2841 data comes indeed from a specific line in the |.toc| file; the actual
2842 rendering of these ``toc lines'' for a given sectioning unit is what
2843 \csb{etocsetlinestyle} decides upon.
2844
2845 It has five mandatory arguments.
2846 %
2847 \centeredline
2848 {\csb{etocsetlinestyle}\color{blue}\marg{levelname}%
2849 \marg{start}\marg{prefix}\marg{contents}\marg{finish}}
2850 %
2851
2852 The initially recognized \meta{levelname}'s are the sectioning
2853 levels of the standard document classes: from \emph{part} (or
2854 \emph{book} which is used by the \ctanpkg{memoir} class) down to
2855 \emph{subparagraph}.
2856
2857 The \meta{start} code is executed when a toc entry of that level is
2858 encountered and the previous one was at a higher level. The
2859 \meta{finish} code is executed when one again encounters a higher
2860 level toc entry. In the meantime all entries for that level are
2861 typeset by executing first the \meta{prefix} code and then the
2862 \meta{contents} code.
2863
2864 The (robust) commands \csb{etocname}, \csb{etocnumber} and \csb{etocpage} are
2865 provided for use inside the \meta{prefix} and \meta{contents} parts of the
2866 \csb{etocsetlinestyle} specification. They represent of course, the name, number,
2867 and page number of the corresponding toc entry. If package \ctanpkg{hyperref} is
2868 active in the document and has added hyperlinks to the TOC data, then these
2869 links are kept in the commands \csb{etocname}, \csb{etocnumber} and
2870 \csb{etocpage} (this last one will have a link only if \ctanpkg{hyperref} was passed
2871 either option \emph{linktoc=all} or option \emph{linktoc=page}.)%
2872 %
2873 \footnote{As expected, in case of \emph{linktoc=page}, only \csb{etocpage} is
2874 an hyperlink, not \csb{etocname} nor \csb{etocnumber}. See \csb{etoclink} on
2875 how to create hyperlinks with the entry target.}
2876 %
2877 In accordance with the \ctanpkg{hyperref} native behavior, no
2878 link gets incorporated into \csb{etocpage} if the page number is empty.
2879
2880
2881 Let us show here how \etoc was used to produce the table of contents displayed
2882 at the beginning of this \autoref{part:styling}. This is a local table of
2883 contents, and we used the command \localtoc.
2884
2885
2886 The line styles were (essentially) obtained in the following manner:%
2887 \footnote{the present document has {\ttfamily\string\renewcommand\string{%
2888 \string\familydefault\string}\string{\string\sfdefault\string}} in its
2889 preamble, hence \csa{normalfont} switches to the |sans| typeface; so in the
2890 section line-style, I wrote \csa{rmfamily} instead.}
2891
2892 \begingroup\small
2893 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
2894 \etocsetlinestyle{section}
2895 {\begin{enumerate}}
2896 {\normalsize\bfseries\rmfamily\item}
2897 {\etocname{} (page \etocpage)}
2898 {\end{enumerate}}
2899
2900 \etocsetlinestyle{subsection}
2901 {\begin{enumerate}}
2902 {\normalfont\item}
2903 {\etocname{} (p.~\etocpage)}
2904 {\end{enumerate}}
2905
2906 \etocsetlinestyle{subsubsection}
2907 {\par\nobreak\begingroup\normalfont
2908 \footnotesize\itshape\etocskipfirstprefix}
2909 {\allowbreak\,--\,}
2910 {\etocname}
2911 {.\hfil\par\endgroup\pagebreak[3]}
2912 \end{filecontentshere}
2913 \endgroup
2914 % Note 2023/02/22: pour une raison que je ne vais pas chercher à comprendre
2915 % le etocsnippet-01 était mis du mauvais côté (dans la marge intérieure, pas
2916 % extérieure) lorsque ce \marginattach était avant le \endgroup
2917 \marginattach
2918
2919 These provisory style definitions rely on the automatic
2920 numbering generated by the |enumerate| environments but it is
2921 much better to use the further command \csb{etocnumber} inside
2922 the item label, which gives the real thing. The improved
2923 definitions will thus be explained later.
2924
2925 With this style, one would have
2926 to be imaginative to design something then for paragraph and
2927 subparagraph entries! perhaps as superscripts? Well, usually
2928 one does not need paragraphs and subparagraphs numbered and
2929 listed in the TOC, so our putative user here chose a design
2930 where no provision is made for them and added the definitive:
2931 \begin{verbatim}
2932 \etocsetlinestyle{paragraph}{}{}{}{}
2933 \etocsetlinestyle{subparagraph}{}{}{}{}
2934 \end{verbatim}
2935 This is also the situation with the default package line styles!
2936
2937
2938 \subsection{The \csbhyp{etocskipfirstprefix} and \csbhyp{etociffirst} commands}
2939 \label{etocskipfirstprefix}
2940 \label{etociffirst}
2941 \label{etocxiffirst}
2942
2943 The chosen |subsubsection| style made use of the command
2944 \csb{etocskipfirstprefix}, which instructs \etoc to \emph{not} use
2945 for the first item the specified \meta{prefix} code.
2946
2947
2948 The command \csb{etociffirst}\marg{YES CODE}\marg{NO CODE}
2949 is a more flexible way to customize the \meta{prefix}
2950 (and \meta{contents}) specifications. It executes the \meta{YES
2951 CODE} branch if this is the first unit at that level (inside a
2952 lower level) and the \meta{NO CODE} if not. This is a robust
2953 command which survives to expansion (for example in an |enumitem| label).
2954
2955 The variant \csb{etocxiffirst} does the same, but is expandable.
2956
2957
2958 \subsection{The \csbhyp{etocnumber} command}
2959 \label{etocnumber}
2960
2961 So far, our specifications would use the numbering generated
2962 by the |enumerate| environments, but of course we generally want
2963 the actual numbers as found in the |.toc| file. This is
2964 available via the \csb{etocnumber} command. To get the labels
2965 in the |enumerate| list to use it we can proceed with the
2966 syntax {\ttfamily label=\char32} from the package |enumitem|:
2967 \begin{verbatim}
2968 \etocsetlinestyle{section}
2969 {\begin{enumerate}[label=\etocnumber]}
2970 {\normalsize\bfseries\rmfamily\item}
2971 {\etocname{} (page \etocpage)}
2972 {\end{enumerate}}
2973 \end{verbatim}
2974 Rather than just \csb{etocnumber} we then used something like
2975 |\fbox{\etocnumber}|. Note that \csb{etocnumber} is a robust
2976 command which explains why it can be used inside the label specification
2977 without needing an added |\protect|.
2978
2979
2980 \subsection{The \csbhyp{etocifnumbered} switch}
2981 \label{etocifnumbered}
2982 \label{etocxifnumbered}
2983
2984 The \csa{fbox} would give an unaesthetic result in the case of
2985 an unnumbered section (which ended up in the table of
2986 contents via an \csa{addcontentsline} command).\footnote{as
2987 seen we use \csa{fcolorbox} rather than \csa{fbox}. Due
2988 to some redefinition made by package |xcolor|, had we used
2989 \csa{fbox} (and not used \ctanpkg{hyperref}) we would have needed
2990 \csa{protect}\csa{fbox}.}
2991
2992 The \csb{etocifnumbered}\marg{A}\marg{B} command executes
2993 \meta{A} if the number exists, and \meta{B} if not. So we use
2994 it in the code which was finally chosen for the |section| level:
2995 \begin{verbatim}
2996 \etocsetlinestyle{section}
2997 {\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered
2998 {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]}
2999 {\normalsize\bfseries\rmfamily\item}
3000 {\etocname{} (page \etocpage)}
3001 {\end{enumerate}}
3002
3003 \etocsetlinestyle{subsection}
3004 {\begin{enumerate}[leftmargin=0cm, label=\etocnumber]}
3005 {\normalfont \item}
3006 {\etocname{} (p.~\etocpage)}
3007 {\end{enumerate}}
3008 \end{verbatim}
3009
3010 If we had changed only the |section| level, and not the
3011 |subsection| level, an error on compilation would have occurred
3012 because the package style for subsections expects to start `in
3013 vertical mode'. An additional \csa{par} token in the
3014 \meta{contents} part of the |section| level would have fixed
3015 this: |{...(page \etocpage)\par}|.
3016
3017 The command \csb{etocifnumbered} is robust; \csb{etocxifnumbered}
3018 has the same effect but is expandable.
3019
3020
3021 \subsection{The \csbhyp{etocthename}, \csbhyp{etocthenumber}, and
3022 \csbhyp{etocthepage} commands}
3023 \label{etocthename}
3024 \label{etocthenumber}
3025 \label{etocthepage}
3026
3027 It is sometimes desirable to have access to the name, number and page
3028 number without the hyperref link data: something similar to the starred
3029 variant of the \csa{ref} command, when package \ctanpkg{hyperref} is used. For
3030 example one may wish to use the unit or page number in some kind of
3031 numeric context, or change its formatting. This is provided by
3032 \csb{etocthename}, \csb{etocthenumber}, and \csb{etocthepage}.
3033
3034 These commands are not ``robust'', in fact it is expected they will be often
3035 submitted to one expansion step so that their contents can easily be recovered
3036 and stored perhaps for delayed usage.
3037
3038 \subsection{The \csbhyp{etoclink} command}
3039 \label{etoclink}
3040
3041 The command \csb{etoclink}\marg{text} can be used in the line style
3042 specifications in a manner analogous to \csb{etocname}, \csb{etocnumber} and
3043 \csb{etocpage}. It creates a link (if \ctanpkg{hyperref} is present%
3044 %
3045 \footnote{Prior to \etocrelease{1.1a}, no such link was added if the \texttt{.toc}
3046 file entry was encountered
3047 with \ctanpkg{hyperref}'s option \texttt{linktoc} set to \texttt{none}.})
3048 %
3049 whose target is the corresponding document unit and
3050 whose name is the given \meta{text} mandatory argument.
3051
3052 Hence |\etoclink{\etocthename}| is under default conditions of \ctanpkg{hyperref} like
3053 the original \csb{etocname}, because the latter is already hyperlinked. Under
3054 \emph{linktoc=page} context |\etoclink{\etocthename}| adds the hyperlink which
3055 is missing from \csb{etocname}. Similarly under the default \ctanpkg{hyperref}
3056 condition (i.e.\@ \emph{linktoc=section}) \csb{etocpage} is not an hyperlink, but one
3057 can use |\etoclink{\etocthepage}|.
3058
3059 The command \csb{etoclink} is robust.
3060
3061 % Since |etoc 1.08j| it contains the link
3062 % destination in an already expanded form, so for example can be used even after
3063 % a |&| in a tabular construction, if \csb{etocglobaldefs} was issued.
3064
3065
3066
3067
3068 \makeatletter\scr@activate@xsection{1}\makeatother
3069 % [] goes to head but {} to toc
3070
3071 % What would really be useful is an option for the length of {} to be measured
3072 % and opt for [] only if does not fit on one header line
3073 \subsection[The \csbhyp{etocthelinkedname} et al.\protect\@{} commands]
3074 {The \csbhyp{etocthelinkedname}, \csbhyp{etocthelinkednumber},
3075 \csbhyp{etocthelinkedpage} and \csbhyp{etocthelink} commands}
3076 \label{etocthelinkedname}
3077 \label{etocthelinkednumber}
3078 \label{etocthelinkedpage}
3079 \label{etocthelink}
3080
3081 \makeatletter\scr@activate@xsection{0}\makeatother
3082
3083 The meanings of these commands
3084 can be stored for delayed usage. For example this is
3085 done in the \hyperref[tocastree]{examples with trees}.
3086
3087 There has been a \textbf{breaking change} at \etocrelease{1.1a}. Here is the behavior
3088 \emph{prior} to this release:
3089 \begin{itemize}[noitemsep]
3090 \item \csb{etocthelinkedname} and \csb{etocthelinkednumber} were hyperlinks
3091 only if \ctanpkg{hyperref} was configured via |linktoc=all| or
3092 |linktoc=section| (the default),
3093 \item \csb{etocthelinkedpage} was an hyperlink only if \ctanpkg{hyperref} was
3094 configured via |linktoc=all| or |linktoc=page| and the page number was not empty.
3095 \end{itemize}
3096 This behavior was coherent with the commands \csb{etocname}, \csb{etocnumber},
3097 and \csb{etocpage} being the robust variants of \csb{etocthelinkedname},
3098 \csb{etocthelinkednumber}, and \csb{etocthelinkedpage}.
3099
3100 At \etocrelease{1.1a} it was decided that the commands should match their denominations.%
3101 %
3102 \footnote{To tell the whole truth, the author in refactoring the code completely at \etocrelease{1.1a} was tricked by the names and forgot to read the old documentation so the new behavior was implemented and it was decided to keep the change.}
3103 %
3104 So they are now \emph{always} hyperlinks independently of |linktoc| \ctanpkg{hyperref}
3105 option (\csb{etocthelinkedpage} has no hyperlink if the page number is empty,
3106 to match \ctanpkg{hyperref} behavior):
3107 \begin{itemize}[noitemsep]
3108 \item \csb{etocthelinkedname} and \csb{etocthelinkednumber} and
3109 \csb{etocthelinkedpage} are always (in presence of \ctanpkg{hyperref})
3110 hyperlinks (for \csb{etocthelinkedpage} the page number must not be empty).
3111 \end{itemize}
3112
3113
3114 A further command is provided: \csb{etocthelink}, which wraps%
3115 %
3116 \footnote{Prior to \etocrelease{1.1a}, there was a link added only if \ctanpkg{hyperref} option \texttt{linktoc} was not \texttt{none}.}
3117 %
3118 an hyperlink around its argument: |\etocthelink|\marg{foo} hyperlinks an
3119 arbitrary text \meta{foo} to the target sectioning unit in the document.
3120 The command \csb{etoclink} is its robust variant.
3121
3122
3123
3124 \subsection{The \csbhyp{etocsetlevel} command}
3125 \label{etocsetlevel}
3126 \label{etocthemaxlevel}
3127
3128 One
3129 can inform \etoc of a level to associate to a given sectioning
3130 command with \csb{etocsetlevel}. For example:
3131 \begin{verbatim}
3132 \etocsetlevel{cell}{0}
3133 \etocsetlevel{molecule}{1}
3134 \etocsetlevel{atom}{2}
3135 \etocsetlevel{nucleus}{3}
3136 \end{verbatim}
3137 In compatibility mode, it will be assumed that the commands |\l@cell|,
3138 |\l@molecule|, ..., have been defined somewhere either by the user or a class:
3139 doing only |\etocsetlevel| is not enough for the corresponding level to work
3140 out-of-the-box in compatibility mode.
3141
3142 However, if table of contents are never using compatibility mode, then all
3143 that matters is that the various line styles have been set. If, for example
3144 |section| is at level |1|, then there is no need to do some
3145 \csb{etocsetlinestyle}|{molecule}{..}{..}{..}{..}| after
3146 \csb{etocsetlevel}|{molecule}{1}| if
3147 \csb{etocsetlinestyle}|{section}{..}{..}{..}{..}| has already been done (and it
3148 has been done by the package itself in its definition of its own line styles).
3149
3150 The accepted levels (but see the frame below) run from |-1| to |6| inclusive
3151 (also |-2| with class \ctanpkg{memoir}). Anything else is mapped to |6|,
3152 which is a dummy level, never displayed. The package does:
3153 \begin{verbatim}
3154 \etocsetlevel{book}{-2}% (only with class memoir)
3155 \etocsetlevel{part}{-1}
3156 \etocsetlevel{chapter}{0}
3157 \etocsetlevel{appendix}{0}% or 1 if document has no \chapter
3158 \etocsetlevel{section}{1}
3159 \etocsetlevel{subsection}{2}
3160 \etocsetlevel{subsubsection}{3}
3161 \etocsetlevel{paragraph}{4}
3162 \etocsetlevel{subparagraph}{5}
3163 \end{verbatim}
3164 \etoc own custom styles are activated by \csb{etocfallbacklines}.
3165 \begin{framed}
3166 Boolean option \etocoption{deeplevels} added at \etocrelease{1.2a} has the
3167 effect of replacing \texttt{6} by \texttt{12} as the maximal numerical level
3168 (which, as has been said above, is never displayed). The value |6|
3169 (default) or |12| (if \etocoption{deeplevels} is set to true) is held by
3170 \csb{etocthemaxlevel}. With \etocoption{deeplevels} option one can for
3171 example do:
3172 \begin{verbatim}
3173 \etocsetlevel{subsubsubsection}{4}
3174 \etocsetlevel{subsubsubsubsection}{5}
3175 \etocsetlevel{subsubsubsubsubsection}{6}
3176 \etocsetlevel{paragraph}{7}
3177 \etocsetlevel{subparagraph}{8}
3178 \end{verbatim}
3179 but it is up to user to actually define \LaTeX{} commands such as
3180 \csa{subsubsubsection}, and also to provide, if \etoc is left in
3181 ``compatibility mode'', the suitable \csa{l@subsubsubsection} et al. needed
3182 for TOC rendering. If you use \csb{etocsetlinestyle} (even only for one level
3183 name) though, which quits ``compatiblity mode'', it is not
3184 \csa{l@subsubsubsection} which needs definition, but
3185 \csb{etocsetlinestyle}|{subsubsubsection}{..}{..}{..}{..}| which has to have
3186 been used.
3187 \end{framed}
3188 The numerical level assignments can be modified at anytime. See
3189 \autoref{part:surprising} for various applications of this technique.
3190
3191
3192
3193 \subsection{Using \texttt{enumerate} or \texttt{itemize} environments for
3194 line styles}
3195
3196 The code for the line styles of the \localtoc of this part was already
3197 reproduced in \autoref{sec:linestyles}. It is very simple and uses
3198 \texttt{enumerate} environments for sections and subsections, then an
3199 ``inline'' paragraph style for subsubsection titles.
3200
3201 Actually, the very first version of \etoc from 2012 was originally motivated
3202 by the aim to do exactly this kind of things, which necessitates to be aware
3203 of when for example after a series of subsections, a section line appears in
3204 the |.toc| file.%
3205 %
3206 \footnote{At the source code level, the legacy method dating back to the
3207 origins in 2012 was replaced
3208 by a completely new one at release \etocrelease{1.2}.}
3209 %
3210 Indeed, this should trigger the emission of an |\end{enumerate}|.
3211
3212 With the \marg{start} and \marg{finish} arguments of \csb{etocsetlinestyle}, \etoc
3213 provides an easy systematic interface to accomplish this kind of task.
3214
3215 But there are some limitations to the use of list environments for typesetting
3216 TOCs. One of them is intrinsic to the scope limitations created by the groups
3217 associated to the environments: the |.toc| file may contain, besides the
3218 information to be typeset in the TOCs, some other commands, such as language
3219 changing commands from \ctanpkg{babel}, and some such commands do not expect
3220 to see their scope limited in this way by the presence of an environment
3221 (which will not be visible in the |.toc| file itself but enacted dynamically
3222 by the user-specified line styles).
3223
3224 The built-in ``default line styles'' provided with \etoc (see
3225 \autoref{sec:custom}) do not make use of environments. Actually, in this
3226 user manual, only the \hyperref[toc:part:styling]{table of contents} at the start of this
3227 \autoref{part:styling}, the \autoref{toc:allsubsections} (which is a TOC!) and
3228 examples from \autoref{etocthelink} have their line styles expressed in terms
3229 of \texttt{enumerate} or \texttt{itemize} environments.
3230
3231 \subsection{The\csbhyp{etocglobaldefs} and \csbhyp{etoclocaldefs} commands}
3232 \label{etocglobaldefs}
3233 \label{etoclocaldefs}
3234
3235 In \LaTeX{} the meaning of a command defined via |\newcommand\foo{...}| inside
3236 an environment (or group) vanishes from \TeX's memory on exit from this
3237 environment (or group). At times however it is needed to make definitions with
3238 global scope, for this \TeX{} has the primitive prefix |\global|.
3239
3240 By default \etoc's definitions of \csb{etocname} etc... are local. This causes
3241 problems in certain contexts such as TOC as tables (\autoref{sec:tocastable},
3242 \autoref{ssec:tocastableold}) and also with |enumitem| \emph{inline} variants
3243 of its standard environments, because the command |\item| then closes a group
3244 (see \autoref{etocthelink}).
3245
3246 After \csb{etocglobaldefs} has been issued, the \csb{etocname},
3247 \csb{etocnumber} and \csb{etocpage} will be defined during execution of \toc
3248 and \localtoc with global scope. For normal use this is not necessary. It
3249 does not hurt either to activate it systematically.
3250
3251 To return to the default, which lets \etoc only define them locally to the
3252 context in place where the \csa{contentsline} is encountered, execute
3253 \csb{etoclocaldefs}. Both \csb{etocglobaldefs} and \csb{etoclocaldefs} have
3254 an effect only locally to the environment or group where they are used.
3255
3256 \section{The \etoc fall-back line styles}
3257 \label{sec:custom}
3258
3259 \etocfallbacklines
3260 \renewcommand{\etoctoprule}{\hrule height2pt depth0pt}
3261 \renewcommand{\etoctoprulecolorcmd}{\color{red}}
3262
3263 \etocruledstyle{\normalfont\normalsize\rmfamily\fboxrule1pt\color{red}%
3264 \fbox{\parbox{.8\linewidth}{\centering\normalcolor This is a table of
3265 contents for the (few) subsections of this section. It carries the label |toc:c|}}}
3266
3267 \localtableofcontents \label{toc:c}
3268
3269 \subsection{A demo of a TOC using \csbhyp{etocfallbacklines}}
3270 \label{etocdefaultlines}
3271 \label{etocfallbacklines}
3272
3273 These line styles were written at an early stage in the
3274 development of the package; although the next section explains how
3275 to customize the font choicess or vertical spaces, etc\dots, used
3276 by these line styles, most other changes would require copying
3277 them from the sources and modify them directly. Admittedly they
3278 have been written at a rather scary low-\TeX{} level, and will not
3279 serve as a very friendly starting point.
3280
3281 Activating their use is done via \csb{etocfallbacklines}, or
3282 \csb{etoctoclines} if the line styles have not been modified with
3283 \csb{etocsetlinestyle}. Sections and sub-sections are printed in
3284 essentially the same manner, except that the leading for
3285 sub-sections is a bit smaller (with document classes lacking a
3286 \csa{chapter} command, the sections are printed in bold typeface;
3287 this is the case in the present document). Sub-sub-sections are
3288 printed inline, in one paragraph, with no numbers or page numbers.
3289 This style was designed and tested with documents having lots of
3290 sub-sub-sections, and should be used on a two-column layout: it
3291 provides (only in that situation with many sub-sub-sections) a
3292 more compact presentation than what is achieved by the \LaTeX{}
3293 default.\footnote{and there will never be a Part or Chapter entry
3294 alone at the bottom of a column or page (except if it has no
3295 sub-unit).} On the other hand, used with a one-column layout,
3296 and with few sub-sub-sections, the style is a bit more spread out
3297 vertically than the \LaTeX{} default, sub-sections are not
3298 visually much different from sections (especially for document
3299 classes with a \csa{chapter} command), so the result is less
3300 hierarchical in appearance than in the \LaTeX{} default.
3301
3302 Let us typeset the global table of contents of the present document as if it
3303 had been done with a class having the \csa{chapter} command: we will print
3304 sections as chapters, and subsections as sections. We use \csb{etocsetlevel}
3305 for that, and also we need to change the font style of ``sections'' (which in
3306 truth are our subsections) to use not the bold but the medium series; we
3307 modify the \csb{etocfontone} command for that. Also we use dot leaders which
3308 are less spread out than in the package default.
3309
3310
3311 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
3312 \etocruledstyle[2]{\normalfont\normalsize\rmfamily\itshape
3313 \fbox{\parbox{.6\linewidth}{
3314 \leftskip 0pt plus .5fil
3315 \rightskip 0pt plus -.5fil
3316 \parfillskip 0pt plus 1fil This is the global table of
3317 contents on two columns, using \etoc default line styles, but with
3318 sections as chapters, and subsections as sections.
3319 }}}
3320 \etocfallbacklines
3321 \etocsetnexttocdepth{1}
3322 \begingroup
3323 \etocsetlevel{section}{0}
3324 \etocsetlevel{subsection}{1}
3325 \renewcommand*{\etocfontone}{\normalfont \normalsize}
3326 \renewcommand*{\etoctoclineleaders}
3327 {\hbox{\normalfont\normalsize\hbox to 1ex {\hss.\hss}}}
3328 \sloppy
3329 \tableofcontents
3330 \endgroup
3331 \end{filecontentshere}
3332 \marginattach
3333
3334 \filecontentsexec\filecontentsheremacro
3335
3336 \subsection{Customizing the \etoc pre-defined line styles}
3337 \label{etocfontminustwo}
3338 \label{etocfontminusone}
3339 \label{etocfontzero}
3340 \label{etocfontone}
3341 \label{etocfonttwo}
3342 \label{etocfontthree}
3343 \label{etocsepminustwo}
3344 \label{etocsepminusone}
3345 \label{etocsepzero}
3346 \label{etocsepone}
3347 \label{etocseptwo}
3348 \label{etocsepthree}
3349 \label{etocminustwoleftmargin}
3350 \label{etocminustworightmargin}
3351 \label{etocminusoneleftmargin}
3352 \label{etocminusonerightmargin}
3353 \label{etocbaselinespreadminustwo}
3354 \label{etocbaselinespreadminusone}
3355 \label{etocbaselinespreadzero}
3356 \label{etocbaselinespreadone}
3357 \label{etocbaselinespreadtwo}
3358 \label{etocbaselinespreadthree}
3359 \label{etoctoclineleaders}
3360 \label{etocabbrevpagename}
3361 \label{etocpartname}
3362 \label{etocbookname}
3363
3364
3365 We will simply list the relevant commands as defined in the
3366 package. Customizing them goes through suitable
3367 \csa{renewcommand}s:
3368 \begin{verbatim}
3369 \newcommand*\etocfontminustwo{\normalfont \LARGE \bfseries}
3370 \newcommand*\etocfontminusone{\normalfont \large \bfseries}
3371 \newcommand*\etocfontzero{\normalfont \large \bfseries}
3372 \newcommand*\etocfontone{\normalfont \normalsize \bfseries}
3373 % (in classes with chapter, \etocfontone does not do \bfseries)
3374 \newcommand*\etocfonttwo{\normalfont \normalsize}
3375 \newcommand*\etocfontthree{\normalfont \footnotesize}
3376
3377 \newcommand*\etocsepminustwo{4ex plus .5ex minus .5ex}
3378 \newcommand*\etocsepminusone{4ex plus .5ex minus .5ex}
3379 \newcommand*\etocsepzero{2.5ex plus .4ex minus .4ex}
3380 \newcommand*\etocsepone{1.5ex plus .3ex minus .3ex}
3381 \newcommand*\etocseptwo{.5ex plus .1ex minus .1ex}
3382 \newcommand*\etocsepthree{.25ex plus .05ex minus .05ex}
3383
3384 \newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil}
3385 \newcommand*\etocminustworightmargin{1.5em plus -0.5fil}
3386 \newcommand*\etocminusoneleftmargin{1em}
3387 \newcommand*\etocminusonerightmargin{1em}
3388
3389 \newcommand*\etocbaselinespreadminustwo{1}
3390 \newcommand*\etocbaselinespreadminusone{1}
3391 \newcommand*\etocbaselinespreadzero{1}
3392 \newcommand*\etocbaselinespreadone{1}
3393 \newcommand*\etocbaselinespreadtwo{1}
3394 \newcommand*\etocbaselinespreadthree{.9}
3395 \newcommand*\etoctoclineleaders
3396 {\hbox{\normalfont\normalsize\hbox to 2ex {\hss.\hss}}}
3397 \newcommand*\etocabbrevpagename{p.~} % initial of "page"
3398 \newcommand*\etocpartname{Part} % prior to 1.08b, was \partname
3399 % but this didn't make sense e.g. with babel+frenchb whose \frenchpartname
3400 % takes into account the value of the part counter.
3401 \newcommand*\etocbookname{Book} % to be modified according to language
3402 \end{verbatim}
3403
3404 No customizing of the standard line styles is possible from
3405 within \etoc. As already explained, when
3406 \csb{etocstandardlines} has been issued, the package just makes
3407 itself very discrete and acts only at the global level, and
3408 the TOC entries are (hopefully) formatted as would have
3409 happened in the absence of \etoc.\footnote{with the
3410 \ctanpkg{KOMA-script} classes, we noticed that
3411 \csb{etocclasstocstyle} was apparently needed for the
3412 KOMA options |toc=left| to be active at the level of the line entries.}
3413
3414
3415 The \csb{etocstandardlines} compatibility mode will work also with
3416 sectioning commands made known to \etoc via \csb{etocsetlevel},
3417 under the condition of course that these sectioning commands
3418 are accompanied with all the relevant definitions for
3419 typesetting toc entries in the \LaTeX{} default manner
3420 (existence of the macros \csa{l@something} . . .).
3421
3422 Using the command \csb{etocsetlinestyle}, be it in the preamble or
3423 in the body of the document, has the secondary effect of
3424 switching off the compatibility mode.
3425
3426 \section{Summary of the main styling commands}
3427
3428 \subsection{Setting up local styles}
3429
3430 \hbox{\color{green}\fboxrule1pt\fboxsep1em
3431 \setbox0\hbox{\csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}, \csb{etoclink}\marg{linkname}}%
3432 \framebox[\linewidth][c]
3433 {\vbox{\hsize\wd0\normalcolor\noindent
3434 \csb{etocsetlinestyle}\marg{levelname}%
3435 \marg{start}\marg{prefix}\marg{contents}\marg{finish}\\
3436 \csb{etocname}, \csb{etocnumber}, \csb{etocpage},
3437 \csb{etocifnumbered}\marg{A}\marg{B}\\
3438 \csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}, \csb{etoclink}\marg{linkname}
3439 }}}
3440
3441 \subsection{Setting up toc display styles}
3442
3443 \medskip
3444 \hbox{\color{green}\fboxrule1pt\fboxsep1em
3445 \setbox0\hbox{\csb{etoctocstylewithmarksnouc}\oarg{kind}%
3446 \marg{number\_of\_columns}\marg{title}\marg{mark}}%
3447 \framebox[\linewidth][c]
3448 {\vbox{\hsize\wd0
3449 \normalcolor\noindent
3450 \csb{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}\\
3451 \csb{etoctocstyle}\oarg{kind}\marg{number\_of\_columns}\marg{title}\\
3452 \csb{etoctocstylewithmarks}\oarg{kind}\marg{number\_of\_columns}%
3453 \marg{title}\marg{mark}\\
3454 \csb{etoctocstylewithmarksnouc}\oarg{kind}\marg{number\_of\_columns}%
3455 \marg{title}\marg{mark}\\
3456 \csb{etocruledstyle}\oarg{number\_of\_columns}\marg{title}\\
3457 \csb{etocframedstyle}\oarg{number\_of\_columns}\marg{title}\\
3458 \csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}}}
3459
3460 \subsection{Displaying tables of contents}
3461
3462
3463 \medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
3464 \setbox0\hbox{\csb{etocname}, \csb{etocnumber},
3465 \csb{etocpage}, \csb{etocifnumbered}\marg{A}\marg{B}}%
3466 \framebox[\linewidth][c]
3467 {\vbox{\hsize\wd0\normalcolor\noindent
3468 \toc\\
3469 \localtoc\\
3470 \csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading}\\
3471 \csb{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}\\
3472 \csb{etocruled}\oarg{number\_of\_columns}\marg{title}\\
3473 \csb{etoclocalruled}\oarg{number\_of\_columns}\marg{title}\\
3474 \csb{etocframed}\oarg{number\_of\_columns}\marg{title}\\
3475 \csb{etoclocalframed}\oarg{number\_of\_columns}\marg{title}\\
3476 \hbox{}{\itshape\ttfamily\ \ \ \ and their starred variants}
3477 }}}
3478
3479 \subsection{Labels and references}
3480 \label{ssec:labelref}
3481
3482 The commands (starred or not) to actually display the table of contents
3483 can be followed with optional labels or references:\par
3484
3485 \medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
3486 \setbox0\hbox{\csb{etocname}, \csb{etocnumber},
3487 \csb{etocpage}, \csb{etocifnumbered}\marg{A}\marg{B}}%
3488 \framebox[\linewidth][c]
3489 {\vbox{\hsize\wd0\normalcolor\noindent
3490 \toc \csa{label}|\{toc:here\}|\\
3491 \toc \csa{ref}|\{toc:far\}| \\
3492 \toc \csa{label}|\{toc:here\}| \csa{ref}|\{toc:far\}| \\
3493 \localtoc \csa{label}|\{toc:here\}|\\
3494 \localtoc \csa{ref}|\{toc:far\}| \\
3495 \localtoc \csa{label}|\{toc:here\}| \csa{ref}|\{toc:far\}| \\
3496 \hbox{}{\itshape\ttfamily\ \ \ \ similarly with\ }%
3497 \csb{etocmulticol}{\itshape\ttfamily\ etc . . . }
3498 }}}
3499
3500
3501 \medskip
3502
3503 \localtoc \csa{ref}|{toc:far}| acts the same as \toc
3504 \csa{ref}|{toc:far}|.
3505 % <--- car à 1.2 cela permet d'éviter une page quasi vide...
3506 When re-displaying another toc, only its contents are transferred:
3507 both the line styles and the toc display style are the ones
3508 currently defined, not the ones from the cloned toc.
3509
3510
3511 \clearpage
3512 \etocdepthtag.toc {control}
3513 \part{Control of contents}
3514 \label{part:control}
3515
3516 \thispartstats
3517
3518 \etocsettocstyle{}{}% maybe I should use \etocclasstocstyle here ?
3519 % but then I probably need some extra KOMA stuff to
3520 % counteract the setspace effet
3521 \begingroup
3522 \microtypesetup{protrusion=false}
3523 \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
3524 \DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection}
3525 \DeclareTOCStyleEntry[numwidth=3em,indent=4.5em]{tocline}{subsubsection}
3526 \etocstandardlines
3527 \localtableofcontents
3528 \endgroup
3529
3530 \section[The \csbhyp{tableofcontents} et al. commands]{The
3531 \csbhyp{tableofcontents}, \csbhyp{localtableofcontents} and
3532 \csbhyp{localtableofcontentswithrelativedepths} commands}
3533 \label{tableofcontents}
3534 \label{etoctableofcontents}
3535 \label{localtableofcontents}
3536 \label{localtableofcontentswithrelativedepth}
3537 \label{etockeeporiginaltableofcontents}
3538
3539 \begin{description}
3540 \item[\toc] can be used arbitrarily many times in the document. Styling either
3541 globally the TOC or its individual entries is customizable at any time in
3542 the document.
3543
3544 \csb{etoctableofcontents} is a synonym to \etoc's \toc. The \toc command
3545 reverts to its non-\etoc definition if \csa{etockeeporiginaltableofcontents}
3546 is issued after loading the package.
3547 %
3548 \footnote{%
3549 This
3550 was added to fix a compatiblity issue with \ctanpkg{listings}'s
3551 \texttt{\string\lstlistoflistings}, as it needs the
3552 \texttt{\string\tableofcontents} macro to keep its original meaning.}
3553
3554 \item[\localtoc] will print local tables of
3555 contents: \emph{i.e.} all sections and sub-units inside a
3556 given chapter, or all subsubsections and lower inside a given
3557 subsection, etc... (see also \csb{etocsetnexttocdepth}).%
3558 %
3559 \footnote{As is explained in \autoref{sec:labeling} the syntax allows to
3560 create somewhere a local table of contents and to display it at some other
3561 location either before or after its origin.}%
3562 \textsuperscript{,}%
3563 \footnote{As is explained in \autoref{sec:tocdepth} \etoc allows at anytime to
3564 locally redefine the numeric levels associated to named ones, which brings
3565 great flexibility to achieve special effects, all done using only a single
3566 auxiliary file, the standard |.toc| file.}
3567 %
3568 \item[\localtocwrdp\marg{number}]
3569 %
3570 \mbox{}\footnote{Thanks to Tony \textsc{Roberts} for feature request.}
3571 %
3572 can be used to override the document or
3573 current tocdepth setting (see \autoref{sec:tocdepth} for a discussion of
3574 tocdepth) to become relative to where the local TOC originates. For example,
3575 assuming the default numeric level assignments to standard sectioning units
3576 \begin{verbatim}
3577 \section{This is a section}
3578 \localtableofcontentswithrelativedepth{+2}
3579 \end{verbatim}
3580 will create a local table of contents taking into account the subsections
3581 and subsubsections inside this section, independently of what is the value
3582 of the |tocdepth| counter at this position in the document. If the numeric
3583 argument had been |3|, the local TOC would have displayed also paragraphs.
3584 If the section had been a chapter, and again for a relative tocdepth of |2|,
3585 the taken into account levels would have been sections and subsections.
3586 \end{description}
3587
3588 \section{Labeling and reusing elsewhere}
3589 \label{sec:labeling}
3590 \label{invisiblelocaltableofcontents}
3591
3592 \etoc allows to typeset at some location a local table of contents which is
3593 defined elsewhere. For this, two simple steps:
3594 \begin{enumerate}
3595 \item insert \localtoc at the distant place, and follow it by some
3596 |\label{foo}|.
3597 \item insert \toc|\ref{foo}| (or \localtoc|\ref{foo}|, it does the same) at the
3598 place where you want this distant table of contents to appear.
3599 \item in step \textbf{1}, if you use \invisiblelocaltoc in place of \localtoc,
3600 there will be no typesetting at its place of definition.
3601 \end{enumerate}
3602 At the place of use of \toc|\ref{foo}|, the layout and looks is entirely
3603 configurable locally. It may be completely different from how the same
3604 contents are rendered elsewhere by another \toc|\ref{foo}| or by the original
3605 label-decorated \localtoc|\label{foo}|. The current value of the |tocdepth|
3606 counter is obeyed.
3607
3608 As an example the table of contents corresponding to \autoref{part:styling}
3609 has been cloned here in a
3610 \hyperref[toc:d]{float} which appears \vpageref{toc:d}.
3611 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
3612 \begin{figure}[ht!]
3613 \centering
3614 \begingroup
3615 % this is a KOMA-script specific customization
3616 \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
3617 \DeclareTOCStyleEntry[numwidth=3.2em,indent=2em]{tocline}{subsection}
3618 \etocstandardlines % <-- use the defaults from the document class
3619 \renewcommand{\etocbkgcolorcmd}{\color{green!5}}
3620 \renewcommand{\etocbelowtocskip}{0pt\relax}
3621 \fboxsep1ex
3622 \etocframedstyle [1]{\fbox{\makebox[.5\linewidth]{\etocfontminusone
3623 I am from \hyperref[toc:part:styling]{far away}}}}
3624 \etocsetnexttocdepth{subsection}
3625 \tableofcontents \label{toc:d} \ref{toc:part:styling}
3626 \endgroup
3627 \end{figure}
3628 \end{filecontentsdef}
3629 \filecontentsexec\foo
3630 We used this: \filecontentsprintviascan\foo
3631 \marginattach
3632
3633 In the above example, not only did we use |\ref{toc:part:styling}| to print
3634 here the distant (local) table of contents which has been labeled |toc:part:styling| but
3635 we added a (possibly confusing) |\label{toc:d}|. This is done for the
3636 down-to-earth reason of being able to use, as we did in the previous
3637 paragraph, |\vpageref{toc:d}|. But if one wants to clone again the original
3638 local table of contents, one must reference its original label:
3639 \toc|\ref{toc:part:styling}|.%
3640 %
3641 \footnote{Why does this author always give
3642 complicated examples rather than down-to-earth ones?}
3643 %
3644 This original local table of contents is to be found \vpageref{toc:part:styling}.
3645
3646 \section[\csbhyp{etocsetlevel}]{A powerful functionality of \etoc: the
3647 re-assignment of levels with \csbhyp{etocsetlevel}}
3648 \label{sec:tocdepth}
3649
3650 The intrinsic levels manipulated by \etoc are numeric: from
3651 |-2| (which corresponds to |book| in the \ctanpkg{memoir} class)
3652 down (from the big to the small)
3653 to |5| (|subparagraph|). But the assignment of a numeric level
3654 to a given name can be modified at any time with the command
3655 \csb{etocsetlevel}\marg{level\_name}\marg{number}. In conjunction
3656 with the use of the \LaTeX{} |tocdepth| counter, this has
3657 powerful applications: \meta{level\_name} does not have to
3658 coincide with an actual document sectioning command, and \etoc
3659 can be used to print arbitrary ``lists of things'', using no
3660 other auxiliary file than the |.toc| file. This is
3661 explained further in \autoref{part:surprising}.
3662
3663 \begin{framed}
3664 It is often said that in the standard classes, the sectioning
3665 level of |\part| is |0| in the classes not having a |\chapter|
3666 command, and |-1| in classes having a |\chapter| command. This
3667 is \emph{correct} for what regards the \emph{automatic
3668 numbering}, as is governed by the value of the |secnumdepth|
3669 counter; but it is \emph{wrong} for what regards the effect of
3670 the |tocdepth| counter: setting the |tocdepth| to |-1| in the
3671 |article| class just before |\tableofcontents| does \emph{not}
3672 prevent Parts from appearing in the Table of Contents. One has
3673 to set it to |-2| for that, whether in the |article| or in the
3674 |book| class.
3675
3676 The canonical levels, a priori known to \etoc, are those of
3677 relevance to the \textbf{|tocdepth|} counter in the standard
3678 classes and are recapitulated in this table: \centeredline{
3679 \fbox{\begin{tabular}{rc}
3680 (\ctanpkg{memoir} class) book&-2\\ part&-1\\ chapter&0 \\
3681 section&1\\ subsection&2 \\
3682 subsubsection&3 \\ paragraph&4 \\ subparagraph& 5
3683 \end{tabular}}}
3684
3685 \smallskip With \etoc, the user can easily print a local table of
3686 contents inside a given subsection, where subsubsections will be
3687 printed in the style of sections, paragraphs in the style of
3688 subsections, and subparagraphs in the style of subsubsections, if
3689 so desired. One can also decide to set everything to be at the level
3690 |6| (never displayed by \etoc), except for example
3691 paragraphs, promoted to be at level |1|, and then one obtains a nice
3692 table of contents of all the paragraphs from the document!
3693 (|tocdepth| at least |1|)\footnotemark
3694 \end{framed}
3695
3696 \footnotetext{and one should naturally not print this TOC of paragraphs in
3697 compatibility mode, which would insist on inserting a gigantic left
3698 margin.}
3699
3700 \section{The \csbhyp{etocsettocdepth} and \csbhyp{etocsetnexttocdepth} commands}
3701 \label{etocsettocdepth}
3702 \label{etocsetnexttocdepth}
3703 \label{invisibletableofcontents}
3704
3705 The |tocdepth| counter has no bearing on what gets written to the |.toc| file;
3706 its action is only on the actual typesetting of the table of
3707 contents.\footnote{In the standard classes (at least), it also influences the
3708 \csa{listoftables} and \csa{listoffigures}, via \csa{@dottedtocline}.} In the
3709 standard classes there is only one |\tableofcontents| possible, whereas with
3710 \etoc, arbitrarily many are allowed, so one may change |tocdepth| to the
3711 appropriate value (which decides the finest sectioning level displayed) again
3712 and again each time a table of contents needs to be typeset.
3713
3714 \etoc provides \csb {etocsettocdepth}\marg{level} whose mandatory argument is
3715 either
3716 numeric (from |-3| to |5|) or a division name such as |subsection| or
3717 |subsubsection| or any name previously declared to \etoc with
3718 \csb{etocsetlevel} (the keywords |all| and |none| are recognized, although not
3719 corresponding to a document division).
3720 This does the appropriate |\setcounter{tocdepth}{numeric_level}|.
3721
3722 As is explained in the next subsection, |tocdepth| is used by \ctanpkg{hyperref}, and
3723 one must take steps to prevent its changes from influencing the bookmarks, too.
3724 So, \etoc has \csb {etocsetnexttocdepth}\marg{level} whose influence ceases
3725 immediately after the next table of contents. The package defines
3726 \csb{invisibletableofcontents}
3727 essentially as
3728 \centeredline{\csb{etocsetnexttocdepth}|{none}|\csb{tableofcontents}}
3729
3730 The simplest organization is probably to have after |\begin{document}| and before the
3731 first |\tableofcontents| a single instance of the \csb{etocsettocdepth}
3732 command, with argument the deepest level (or most commonly used deepest level)
3733 among the tables of contents of the document, and to use locally,
3734 where needed, \csb{etocsetnexttocdepth} before |\tableofcontents| or
3735 |\localtableofcontents|.
3736
3737 \begin{framed}
3738 It is possible to use \csb{etocsettocdepth} inside the first argument of
3739 \csb{etocsettocstyle} (possibly in conjunction with checking the
3740 \csb{etoclocaltop} value, \emph{which however will be up-to-date there only if
3741 \csb{etocchecksemptiness} was executed}). There is no worry then about
3742 possible impact on hyperref bookmarks later on, because \etoc always resets
3743 the |tocdepth| counter after typesetting a TOC to the value it had before
3744 it.
3745
3746 % Since \etocrelease{1.09}
3747 The macro \csb{etocsetnexttocdepth} works also if located in
3748 first argument of \csb{etocsettocstyle}, but there is no reason to use it
3749 there as \csb{etocsettocdepth} has no durable effet on the |tocdepth|
3750 counter if executed there.
3751
3752 Check \csb{localtableofcontentswithrelativedepth} for a simpler way to
3753 control the depth of local tables of contents. This has the advantage of
3754 working reliably whether or not the \csb{etocchecksemptiness} is used.
3755 \end{framed}
3756
3757 \subsection{The hyperref option \emph{bookmarksdepth}}
3758 \label{ssec:bookmarksdepth}
3759
3760 When modifying the counter |tocdepth| for the purposes of
3761 multiple uses of \toc or \localtoc, one should be aware that
3762 package \ctanpkg{hyperref} by default takes into account the
3763 \emph{current} value of the |tocdepth| counter to decide
3764 whether the |pdf| file will contain a bookmark corresponding
3765 to sectioning commands encountered in the source file. Thus,
3766 one typically needs to reset |tocdepth| to its previous
3767 value after having temporarily modified it for a given table of
3768 contents.
3769
3770 Or, there is the \emph{bookmarksdepth=n} option of package
3771 \ctanpkg{hyperref}, with \emph{n} the desired document bookmarks
3772 maximal depth, which can be numeric or the name of a level known to
3773 \ctanpkg{hyperref}. This documentation previously passed |bookmarksdepth=3| as
3774 option to \ctanpkg{hyperref}, so even if |tocdepth| was left to |1|
3775 by inadvertance after printing a certain table of contents
3776 this did not modify the bookmark tree of the |pdf| file. Now that
3777 \csb{etocsetnexttocdepth} has been added to the package, we have used it
3778 systematically and there was no need for |bookmarksdepth=3| anymore.
3779
3780 \section[The \csbhyp{etocsettocdepth.toc} command]{The
3781 \csbhyp{etocsettocdepth.toc} and
3782 \csbhyp{etocimmediatesettocdepth.toc} and commands}
3783 \label{etocsettocdepth.toc}
3784 \label{etocimmediatesettocdepth.toc}
3785
3786 This command \csb{etocsettocdepth.toc} implements some functionality of
3787 \ctanpkg{tocvsec2}%
3788 %
3789 \footnote{I thank Denis \textsc{Bitouzé} for drawing
3790 my attention to the incompatibility of this package with \etoc.},
3791 %
3792 a package
3793 which however was incompatible with \etoc (it can still be used for its
3794 |secnumdepth|-related commands, but its |toc|-related activities will get
3795 canceled by \etoc) and more-or-less designed for a single table of contents.
3796
3797 The action of \csb{etocsettocdepth.toc} is totally different than the one of
3798 \csb{etocsettocdepth}. Rather than modifying the |tocdepth| counter immediately,
3799 it adds a line to the |.toc| file which, when executed inside a table of
3800 contents will enact this change.
3801
3802 The command \csb{etocsettocdepth.toc}, like
3803 \csb{etocsettocdepth}, accepts both numeric and named
3804 arguments. In the case of a named argument, the actual numeric
3805 value to be used is not yet decided at the time the |.toc|
3806 file is created; it will be the value currently specified for
3807 the named level at the time each table of contents (not having
3808 done |\etocignoretoctocdepth|) is typeset.
3809
3810 The |tocdepth| counter will never be set to a value finer than its initial value
3811 at the start of the table of contents: so adding commands
3812 \csb{etocsettocdepth.toc} in the document is a way to \emph{restrict} locally
3813 the depth of the table of contents. For example to prevent inclusion in the
3814 tables of contents of the sub-sub-sections of a given chapter.
3815
3816 This
3817 {\fbox{gets executed in ALL tables of contents.}}
3818
3819 Also \csb{etocimmediatesettocdepth.toc} is provided. For explanations,
3820 refer to the discussion of \csb{etocimmediatedepthtag.toc} in the
3821 next section.
3822
3823 \subsection{The \csbhyp{etocobeytoctocdepth} and
3824 \csbhyp{etocignoretoctocdepth} commands}
3825 \label{etocobeytoctocdepth}
3826 \label{etocignoretoctocdepth}
3827
3828
3829 So \csb{etocignoretoctocdepth} is provided to cancel the
3830 \csb{etocsettocdepth.toc} mechanism when
3831 needed; and \csb{etocobeytoctocdepth} will
3832 re-activate it. The package does initially \csb{etocobeytoctocdepth}.
3833
3834 \section[The \csbhyp{etocdepthtag.toc} and \csbhyp{etocsettagdepth} commands]{The
3835 \csbhyp{etocdepthtag.toc}, \csbhyp{etocimmediatedepthtag.toc} and
3836 \csbhyp{etocsettagdepth} commands}
3837 \label{etocdepthtag.toc}
3838 \label{etocimmediatedepthtag.toc}
3839 \label{etocsettagdepth}
3840 \label{sec:depthtags}
3841
3842
3843
3844 % Release \etocrelease{1.07h} has a
3845 The command \csb{etocdepthtag.toc}
3846 allows to control dynamically the which contents end up included in the
3847 displayed TOCs (this documentation also decribed formerly a way
3848 using \csb{etocsettocdepth.toc} with some dummy level name, which got
3849 then set via \csb{etocsetlevel} according to what was locally needed,
3850 but it was too hacky and I am not sure if it was understandable).
3851
3852 It is used as \csb{etocdepthtag.toc}\marg{tag\_name}, where the
3853 \meta{tag\_name} is anything, and this will put the tag in the |.toc|
3854 file. When typesetting a TOC, one issues a series of commands
3855 \csb{etocsettagdepth}\marg{tag\_name}\marg{level} where the
3856 \meta{level} may be either numeric (from |-3| to |5|) or the name of a
3857 division unit known to \etoc, or |none| or |all|. The effect of the tag
3858 inside the |.toc| file will then be to set the |tocdepth| counter to
3859 the desired value, in real time (this can not get finer than the
3860 initial value of |tocdepth| at the start of the TOC).
3861
3862 The added flexibility is thus that \csb{etocsetlevel} has not been used in a
3863 kind of hacky way, that one may use named level depths, and the
3864 keywords |none| and |all|.
3865
3866 As usual, once the tag depths have been set, they remain in effect until getting
3867 redefined or seeing their scope expire via the closing of a group or of a
3868 surrounding
3869 environment. For an example, see \autoref{sec:tocwithdepthtags}.
3870
3871 When using \csb{etocdepthtag.toc} in combination with \LaTeX's |\include|,
3872 data may not end up in the |.toc| file in the correct order. For example in
3873 this situation:
3874 \begin{verbatim}
3875 \clearpage % or anything ending up causing its presence here right before
3876 % the \etocdepthtag.toc
3877 \etocdepthtag.toc{sometag}
3878 \include{some file containing sections}
3879 \end{verbatim}
3880 The tag will end up in the |.toc| file \emph{after} all section headings from
3881 the included file. The cause is that \LaTeX\ inserts immediately in the
3882 main auxiliary file a command to input the auxiliary file of the included file
3883 (which in turn, contains instructions to add data to the |.toc| file). But
3884 \csb{etocdepthtag.toc} does not internally use such immediateness, as it uses
3885 the same interface as |\section| and alike commands when they want to write
3886 extra data to the |.toc| file.
3887
3888 So%
3889 %
3890 \footnote{Thanks to Norman \textsc{Ramsey} who reported this problem, together
3891 with a fix, in July\dots 2016. Sorry for long delay before updating
3892 \etoc six years later\dots}
3893 %
3894 % \etocrelease{1.09f} adds
3895 there is \csb{etocimmediatedepthtag.toc} which will force the tag to be written
3896 immediately to the |.toc| file (well, rather immediately to the |.aux| file,
3897 so before the inclusion of the auxiliary file of the included file).
3898
3899 One should not use this variant systematically. For example if your document
3900 looks like:
3901 \begin{verbatim}
3902 \clearpage
3903
3904 \section{bbbb}
3905
3906 Some text
3907
3908 \etocdepthtag.toc{sometag}
3909 \etocimmediatedepthtag.toc{someimmediatetag}
3910 \section{cccc}
3911
3912 Some text
3913
3914 \end{document}
3915 \end{verbatim}
3916 then the |someimmediatetag| will end up being inserted in |.toc| file
3917 \emph{before} the |bbbb| section. This is because \LaTeX's |\section|
3918 uses a \emph{delayed} write, not an \emph{immediate} one. And
3919 \csb{etocdepthtag.toc} wisely uses a \emph{delayed} write.
3920
3921 As it seems very hard programmatically to identify automatically if the
3922 \emph{immediate} variant of \csb{etocdepthtag.toc} should be used, the package
3923 provides two separate commands and it is up to user to make the correct
3924 choice.
3925
3926
3927 \subsection{The \csbhyp{etocobeydepthtags} and \csbhyp{etocignoredepthtags} commands}
3928 \label{etocobeydepthtags}
3929 \label{etocignoredepthtags}
3930
3931
3932 After \csb{etocignoredepthtags}, the |.toc| depth tags are ignored (but
3933 \csb{etocdepthtag.toc} still works). The package does initially
3934 \csb{etocobeydepthtags} which makes \etoc react to the found tags in the
3935 |.toc| file.
3936
3937 \section{Adding commands to the \texorpdfstring{\texttt{.toc}}{.toc} file}
3938 \label{sec:addingtotoc}
3939
3940 We described above \csb{etocsettocdepth.toc} and \csb{etocdepthtag.toc} which
3941 both insert commands inside the |.toc| file. An even more general mechanism of
3942 adding ``action tags'' to the |.toc| file could be envisioned, but this would
3943 just be a wrapper for direct use of |\addtocontents{toc}{\something}|.
3944
3945 One should be cautious when adding in this way
3946 things
3947 to the |.toc| file. For example, inserting
3948 \csa{addtocontents}|{toc}{\string\clearpage}|
3949 just
3950 before a \csa{part} to fix the problem when some part entry (in
3951 the table of contents) is isolated at the bottom of one page,
3952 will cause problems with multiple TOCs: this \csa{clearpage}
3953 will be executed by \etoc each time a \toc or \localtoc
3954 command is encountered! The more prudent thing is to do
3955 rather: {\csa{addtocontents}|{toc}{\string\myclearpage}|,}
3956 to have a |\let\myclearpage\relax| at the top level of the
3957 document and to use where needed something like:
3958 \begin{verbatim}
3959 \let\myclearpage\clearpage
3960 \tableofcontents
3961 \let\myclearpage\relax
3962 \end{verbatim}
3963 The \ctanpkg{memoir} class has the command \csa{settocdepth} which
3964 writes a \csa{changetoc\-depth} command inside the |.toc| file.
3965 This will impact the typesetting by \etoc of \emph{all} tables
3966 of contents, with (possibly) unexpected results: imagine the
3967 document has \csa{settocdepth}|{chapter}| at some point to
3968 avoid having the sections from subsequent chapters be listed
3969 in the main table of contents. Then a local table of contents
3970 in one of these chapters will print a title but will be
3971 without any entry.
3972
3973 As the \ctanpkg{memoir} class by itself allows multiple\toc
3974 these issues already arise there,
3975 independently of \etoc, see page 170 of the \ctanpkg{memoir}
3976 manual.
3977
3978 For this specific issue, the commands \csb{etocsettocdepth.toc},
3979 \csb{etocignoretoctocdepth} and \csb{etocobeytoctocdepth} are the way to go; or
3980 their variants \csb{etocdepthtag.toc} and \csb{etocsettagdepth}.
3981
3982 As an aside, any |\setcounter{tocdepth}{n}| command added directly to the |.toc|
3983 file will see its effect
3984 % (since release \etocrelease{1.07g})
3985 cease when the end of a table of contents is reached, as \etoc executes a
3986 |\setcounter{tocdepth}{previous_value}| there, to reste the \texttt{tocdepth}
3987 counter to the value it had on entering the table of contents.
3988
3989 \subsection{The hyperref option \emph{hidelinks}}\label{ssec:hidelinks}
3990
3991 The colored links (and also the rectangle links) are a bit
3992 annoying when used in tables of contents, especially when
3993 the document uses \etoc and has plenty of them! One may wish
3994 for having colored links, \emph{except} for those within
3995 table of contents!
3996 Indeed, why would things in TOCs need to be either framed in
3997 rectangles or colored, when the user \emph{already expects
3998 them to be links}?
3999
4000 I use the following trick: either in the preamble using
4001 |\AtBeginDocument|, or right after |\begin{document}|, I
4002 have the command
4003 \centeredline{|\addtocontents{toc}{\protect\hypersetup{hidelinks}}|}
4004
4005 \begin{framed}
4006 All TOCs typeset by \etoc have their contents done
4007 within a group (as if enclosed in an environment). So
4008 the command \csa{hypersetup}|{hidelinks}| will be
4009 executed by \emph{each} TOC, but its effect will be
4010 limited to that TOC.
4011 \end{framed}
4012
4013 I found out experimentally that the option |hidelinks| could
4014 indeed be set many times with |\hypersetup| (this is not the
4015 case of all \ctanpkg{hyperref} options).
4016
4017 \subsection{Disabling protrusion in all TOCs}
4018 \label{ssec:disableprotrusion}
4019
4020 If using \ctanpkg{microtype} it looks like a generally advisable counsel to
4021 disable protrusion in particular for all TOCs (see however
4022 \autoref{ssec:microtype} for further information if you don't want to do
4023 that). To achieve this simply add
4024 %
4025 \centeredline{|\addtocontents{toc}{\protect\microtypesetup{protrusion=false}}|}
4026 %
4027 immediately after |\begin{document}| (or use |\AtBeginDocument|). We ended up
4028 doing this for the present document after checking for a few of our TOCs that
4029 it improved their looks. As \etoc always encloses the typesetting of tables of
4030 contents inside scope limiting groups, the effect will be limited to tables of
4031 contents only. Notice that adding the above command to an existing document will
4032 have an effect only on second compilation.
4033
4034
4035 \section[The \csbhyp{etocsetlocaltop.toc} command]
4036 {The \csbhyp{etocsetlocaltop.toc} and
4037 \csbhyp{etocimmediatesetlocaltop.toc} commands}
4038 \label{etocsetlocaltop.toc}
4039 \label{etocimmediatesetlocaltop.toc}
4040
4041 It is important to understand that \csb{localtableofcontents} works entirely
4042 from data \emph{in the |.toc| file}. If the document, say with |article|
4043 class, contains starred sectioning commands, which are not accompanied
4044 by suitable \csa{addcontentsline}, then these units are completely
4045 transparent to \csb{localtableofcontents}:
4046 \begin{itemize}
4047 \item If \localtoc is issued before |\section*{Foo}|, say locally to a |\section|,
4048 then the local TOC will include not only the |subsection|s between the
4049 |\section| and the |\section*{Foo}| but also those following, and it will
4050 stop only at encountering a later |\section| or |\part| from the document's body.
4051 \item If the command is issued right after |\section*{Foo}| and the later was
4052 itself subsequent to a (numbered) |\subsection|, then \etoc will think it
4053 must display a TOC local to the \emph{subsection}.
4054 \end{itemize}
4055
4056 % Since release \etocrelease{1.08k}, \etoc provides the one-argument
4057 There is the command
4058 \csb{etocsetlocaltop.toc} to insert into the |.toc| file a kind
4059 of ``ghost'' of a given sectioning unit. Here is an example:
4060
4061 \begin{verbatim}
4062 \part*{Extra unnumbered part}
4063 \etocsetlocaltop.toc{part}
4064 \localtableofcontents
4065 \end{verbatim}
4066
4067 So with no |\part| heading inserted into the table of contents via an
4068 |\addcontentsline|, still \localtoc will know it is local to a part. In this
4069 example the local contents will be delimited by the next numbered |\part|, or
4070 |\part*| with |\addcontentsline|, or also by a later, second,
4071 |\etocsetlocaltop.toc{part}|.
4072
4073 As a (counter)-example consider this document:
4074 \begin{verbatim}
4075 \documentclass{article}
4076 \usepackage{etoc}
4077 \begin{document}
4078 \tableofcontents
4079
4080 \part*{A}
4081 \etocsetlocaltop.toc{part}
4082 \localtableofcontents
4083
4084 \section{I}
4085
4086 \section{II}
4087
4088 \part*{B}
4089
4090 \section{III}
4091
4092 \part*{C}
4093
4094 \section{IV}
4095 \end{document}
4096 \end{verbatim}
4097 It uses only |\part*|. Thanks to the \csb{etocsetlocaltop.toc} the \localtoc
4098 knows it should report only sections. But the other |\part*| are invisible to
4099 it as nothing is recorded in the |.toc| file. So the local table of contents
4100 in this example will list \emph{all} sections not only |I| and |II|. To fix thix one may
4101 e.g.\@ insert another |\etocsetlocaltop.toc{part}|, this time after |\part*{B}|
4102 (or make this a numbered part, or use |\addcontentsline| for it).
4103
4104 The above document amended with added |\etocsetlocaltop.toc{part}| after each
4105 unnumbered part will thus have its main TOC without any |Part| heading, but
4106 each |\part| can show a correct \localtoc. The simpler
4107 approach would be to use |\addcontentsline| with each unnumbered |\part| so
4108 that it ends up in the |.toc| file, but \etoc is keen on allowing the most
4109 diverse point of views.
4110
4111 It should be stressed that the various |\etocsetlocaltop.toc|\marg{sect. unit}
4112 do impact the global \toc: they really act like actual sectioning units,
4113 except for not inducing any typesetting. In usual document classes, this
4114 would appear to mean that they are completely transparent to the global \toc.
4115 Not the case with \etoc, which adds a virtual assembly of levels: the |.toc|
4116 data originating in |\etocsetlocaltop.toc|\marg{sect. unit} will trigger the
4117 execution of the \marg{finish} parts of the line styles of finer sectioning
4118 units encountered before (either in the global \toc or in an active
4119 \localtoc); and it triggers the \marg{start} parts of the line styles of finer
4120 units encountered after it (again in the global \toc, but also in any
4121 \localtoc which is already activated at a coarser lever).
4122
4123 Depending on how the toc line styles are configured this may translate into
4124 some visual effect; for example with the \etoc own line styles the
4125 \marg{start} and \marg{finish} mostly insert penalties or vertical spaces.
4126
4127 It is a matter of debate if this is good design; a variant serving purely to
4128 influence boundaries of local table of contents with no collateral effects
4129 could be provided. And the name of the macro was perhaps not so well chosen
4130 as it suggests it acts as would such an hypothetical variant. In absence of
4131 feature requests we leave the matter standing for now.%
4132 %
4133
4134 Usage of \csb{etocsetlocaltop.toc} interacts with
4135 \csb{etocchecksemptiness} in the expected way: it modifies (as explained
4136 above) the selection made by \csb{localtableofcontents}, hence the decision
4137 whether this local TOC will end up empty or not.
4138
4139 There is also \csb{etocimmediatesetlocaltop.toc}. This may be useful in some
4140 very special circumstances involving |\include|. For related discussion see
4141 the documentation of \csb{etocimmediatedepthtag.toc}.
4142
4143
4144 \section{The \csbhyp{etoclocaltop} command}
4145 \label{etoclocaltop}
4146
4147 Within either the TOC style
4148 (\csb{etocsettocstyle}) or the local title styles (\csb{etocsetlinestyle}), the
4149 control sequence \csb{etoclocaltop} is made equivalent for the duration of
4150 \csb{localtableofcontents} to a numeric (self-delimiting) denotation of the
4151 current top level.
4152
4153 Thus: it will in numeric contexts (|\ifnum|, |\ifcase|, ...) represent zero
4154 for a local TOC corresponding to chapter, or one if in a section, or two if in
4155 a subsection, etc..., assuming of course here that the default levels are
4156 obeyed (see \autoref{sec:tocdepth}).
4157
4158 %\begin{framed}
4159 \csb{etoclocaltop} from inside the TOC heading (first argument of
4160 \csb{etocsettocstyle}) has the correct value \emph{only under
4161 \csb{etocchecksemptiness} regime}. Special circumstances correspond to
4162 some special values:
4163 \begin{description}[nolistsep]
4164 \item[|-3|] (|-\thr@@|)\newline
4165 signals that \etoc considers the local TOC to be
4166 ``unknown''; this happens at the last local TOC, for the first \LaTeX\ run
4167 after adding a new \localtoc to the document. In doubt, \etoc assumes the
4168 TOC will prove non empty, hence it prints (independently of whether the
4169 check for emptiness was activated or not) the heading as specified by
4170 \csb{etocsettocstyle}. Thus, check if \csb{etoclocaltop} gives |-3| as a
4171 a \meta{number} to detect that situation from within the first argument of
4172 \csb{etocsettocstyle}, if desired.
4173 \item[|-1000|](|-\@m|)\newline is in case of a \localtoc
4174 being considered ``known'' (although it may still refer to the data in the
4175 |.toc| file from the previous run) but without the check for emptiness
4176 having been executed.
4177 \item[|-10000|](|-\@M|)\newline is the value when accessed from the title
4178 of a global TOCs.
4179 \end{description}
4180 %\end{framed}
4181 %\begin{framed}
4182
4183 When executed from within a local table of contents \textbf{line styles}
4184 (\csb{etocsetlinestyle}), \csb{etoclocaltop} always will hold the correct value,
4185 whether or not the emptiness check was executed.
4186
4187 For a global table of contents however, it will always keep the value |-3|.
4188 %\end{framed}
4189
4190 Attention! \cs{etoclocaltop} is only to be queried not set.
4191
4192
4193
4194 \section{Checking TOCs for emptiness}
4195
4196 \subsection{The \csbhyp{etocchecksemptiness} command}
4197 \label{etocchecksemptiness}
4198 \label{etocdoesnotcheckemptiness}
4199
4200 The user needs to issue \csb{etocchecksemptiness} to tell \etoc to check whether
4201 local tables of contents are empty and in case of emptiness to print nothing
4202 at all.\footnote{Thanks to Paul Gaborit who asked for
4203 such a feature.} This
4204 can be useful to authors of \LaTeX{} classes who for example wish to have a
4205 |\chapter| command doing systematically a \localtoc, or for
4206 people producing files via automatic conversions and some of those might have
4207 sectioning commands and others not.
4208
4209 «Emptiness» means that no \csa{contentsline} command would get executed within
4210 the scope of the local table of contents --- empty line styles by themselves do
4211 not make the TOC empty. \etoc always executes the \csb{etocaftertochook}
4212 command; and the test for emptiness itself executes everything else found in
4213 the |.toc| file. See \autoref{sec:addingtotoc} in this context.
4214 \begin{enumerate}
4215 \item the \csb{etocifwasempty} command discussed below can be used from inside
4216 \csb{etocaftertochook}, and even from inside \csb{etocbeforetitlehook}.
4217 \item there is also \csb{etocdoesnotcheckemptiness}.%
4218 % (since \etocrelease{1.08i}.)
4219 \end{enumerate}
4220
4221 The suppression of the heading (more precisely of the toc display style
4222 elements) may be effective only for the final \LaTeX{} runs. For example in
4223 the situation of a \toc|\ref{foo}| where the label |foo| is
4224 not yet recognized, the heading (but not the contents) is printed and the TOC
4225 is declared non-empty. Or, if one adds a \localtoc to a document, on the next
4226 run, the test for emptiness will in fact apply to the next one, and the last
4227 local TOC of the document will have its contents temporarily unknown to \etoc,
4228 hence will be declared non empty, and the heading will be printed.
4229
4230 For a finalized document compiled with initially no auxiliary files, the first
4231 \LaTeX{} run will declare all local TOCs non empty and print for each of them a
4232 heading (and no contents naturally). The second \LaTeX{} run will then
4233 correctly decide which local TOC is empty or not.
4234
4235 \subsection{The \csbhyp{etocnotocifnotoc} command}
4236 \label{etocnotocifnotoc}
4237
4238 The user can then extend the emptiness-checking to the global TOCs with
4239 \csb{etocnotocifnotoc}. May I respectfully give the advice then to rather do
4240 none of |\usepackage{etoc}| nor \toc ? |;-)|. Well, there is always the case
4241 of batch conversions of documents having or not sectioning units.
4242
4243 \subsection{The \csbhyp{etocifwasempty} command}
4244 \label{etocifwasempty}
4245 \label{etocxifwasempty}
4246
4247 The command \csb{etocifwasempty}\marg{YES}\marg{NO} executes \meta{YES} if
4248 the previous TOC was found to be empty and \meta{NO} if its was not so. This
4249 may serve to act appropriately after a truly empty TOC. If
4250 \csb{etocchecksemptiness} has not been issued, this conditional always
4251 executes the \meta{NO} branch.
4252
4253 This command is robust, and \csb{etocxifwasempty} is its expandable
4254 version.
4255
4256 \fbox{Do not forget the second argument: at least an empty pair of braces |{}|
4257 must be present.}
4258
4259 This conditional may wrongly say that the local TOC is empty or not empty
4260 until \LaTeX{} compilations stabilize. But if it says that a local TOC is
4261 empty, this does mean that \etoc considered the just encountered local table
4262 of contents to be empty (for that run) and thus printed nothing (not even a
4263 |\par|).
4264
4265
4266 \clearpage
4267 \etocdepthtag.toc {examples}
4268 \part{Examples}\label{part:examples}
4269
4270 \thispartstats %% (pas de sous-section)
4271
4272 \etocfallbacklines
4273 \etocsettocstyle {}{}
4274 \localtableofcontents
4275
4276 To understand all code snippets in detail,
4277 one will need to have first browsed through \autoref{sec:linestyles}
4278 and \autoref{sec:tocstyle}.
4279
4280
4281
4282 \section{A first example}
4283 \label{sec:firstexample}
4284
4285 This section is called ``a first example'' due to legacy reasons of the
4286 various defects of this documentation...
4287
4288 Let us present a ``first example'' (sort of) of specification for line styles:
4289 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
4290 \begingroup\parindent 0pt \parfillskip 0pt \leftskip 0cm \rightskip 1cm
4291 \etocsetlinestyle {section}
4292 {}
4293 {\leavevmode\leftskip 0cm\relax}
4294 {\bfseries\normalsize\makebox[.5cm][l]{\etocnumber.}%
4295 \etocname\nobreak\hfill\nobreak
4296 \rlap{\makebox[1cm][r]{\mdseries\etocpage}}\par}
4297 {}
4298 \etocsetlinestyle {subsection}
4299 {}
4300 {\leavevmode\leftskip .5cm\relax }
4301 {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
4302 \etocname\nobreak\hfill\nobreak
4303 \rlap{\makebox[1cm][r]{\etocpage}}\par}
4304 {}
4305 \etocsetlinestyle {subsubsection}
4306 {}
4307 {\leavevmode\leftskip 1.5cm\relax }
4308 {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
4309 \etocname\nobreak\hfill\nobreak
4310 \rlap{\makebox[1cm][r]{\etocpage}}\par}
4311 {}
4312 \etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of
4313 \autoref{part:overview} (\nameref{part:overview})}
4314 \tableofcontents \ref{toc:overview}
4315 \endgroup
4316 \end{filecontentsdef}
4317
4318 \begin{verbatim}
4319 \begingroup\parindent 0pt \parfillskip 0pt \leftskip 0cm \rightskip 1cm
4320 \etocsetlinestyle {section}
4321 {}
4322 {\leavevmode\leftskip 0cm\relax}
4323 {\bfseries\normalsize\makebox[.5cm][l]{\etocnumber.}%
4324 \etocname\nobreak\hfill\nobreak
4325 \rlap{\makebox[1cm][r]{\mdseries\etocpage}}\par}
4326 {}
4327 \etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of
4328 \autoref{part:overview} (\nameref{part:overview})}
4329 \tableofcontents \ref{toc:overview}
4330 \endgroup
4331 \end{verbatim}
4332
4333 In the above verbatim there is a mysterious
4334 \centeredline{|\ref{toc:overview}|}
4335 which will be commented upon later. But let use first see what this code
4336 produces (of course its output depends on the contents of the present
4337 document, as applies to all other examples in this documentation).
4338
4339 \filecontentsexec\foo
4340
4341 This author always complicates things, so the above
4342 example had one additional twist I now have to explain. The mysterious
4343 %
4344 \centeredline{|\tableofcontents \ref{toc:overview}|}
4345 %
4346 means that the contents which are displayed are those of a local table of
4347 contents located somewhere else and labeled there via a
4348 %
4349 \centeredline{|\label{toc:overview}|}
4350 %
4351 Turns out that this was done via a \localtoc located at the start of
4352 \autoref{part:overview}, here is how the code looked like overthere:
4353 \begin{verbatim}
4354 \part{Overview}
4355 \etocfallbacklines
4356 \etocsettocstyle{}{}
4357 \localtableofcontents \label{toc:overview}
4358 \end{verbatim}
4359 For more explanations refer to \autoref{sec:labeling}. Notice in particular
4360 that there is no relation whatsoever between the line styles used for the
4361 original \localtoc and those applying here to the cloned one. Actually the
4362 original one could even have been made invisible via usage of \invisiblelocaltoc!
4363
4364 Regarding the line styles, we could have used those defined by \etoc, which
4365 are activated via \csb{etocfallbacklines}, or the default document class styles
4366 which are activated by \csb{etocstandardlines}, but we were a bit more
4367 ambitious here and wanted to design our own. The technique is a simple one:
4368 each heading is in its own paragraph, which may extend on multiple lines; it
4369 is responsible for setting its own |\leftskip|.
4370
4371 Here is again the code used (now displayed more fully). Notice that we
4372 defined styles for sections, subsections, and subsubsections, but actually
4373 that \autoref{part:overview} only has sections!
4374 \filecontentsprintviascan\foo
4375 \marginattach
4376
4377 The two commands used are \csb{etocsetlinestyle} for specifying the line styles,
4378 and \csb{etocruledstyle} for the TOC global style.
4379
4380 The |\rightskip| is shared by all, and creates space where the page
4381 numbers get printed. For an elaboration of this technique see the next
4382 \autoref{sec:secondexample} as well as \autoref{sec:tocwithdepthtags}
4383 which provides a TOC with parts and paragraphs. Both allow multi-line
4384 headings and employ a technique for putting page numbers in the right margin
4385 which was inspired from what \LaTeX2e's |\@dottedtocline| macro does.
4386
4387
4388
4389 \section{A second example}
4390 \label{sec:secondexample}
4391
4392 This second example:
4393 \begin{enumerate}
4394 \item illustrates displaying subsections of a given section ``horizontally''
4395 in one single paragraph,
4396 \item does a selection of contents via the technique of \emph{depth tags},
4397 described in \autoref{sec:depthtags}.
4398 \end{enumerate}
4399 Again the qualities
4400 of the author innovative pedagogy skills are well illustrated by the
4401 simplicity of the example.
4402
4403 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
4404 \begingroup
4405 \newcommand*{\DotsAndPage}% follow it by \par
4406 {\nobreak\leaders\hbox{\bfseries\normalsize\hbox to .75ex {\hss.\hss}}%
4407 \hfill\nobreak
4408 \makebox[\rightskip][r]{\bfseries\normalsize\etocpage}}
4409
4410 \etocsetlinestyle {part}
4411 {\parindent 0pt
4412 \nobreak
4413 \large\bfseries\centering\scshape
4414 \etocskipfirstprefix}
4415 {\pagebreak[3]\medskip}
4416 {\etocifnumbered{Part \etocnumber{} -- }{}\etocname\par}
4417 {}
4418
4419 \etocsetlinestyle {section}
4420 {\begingroup
4421 \leftskip 0pt \rightskip .75cm \parfillskip-\rightskip
4422 \normalsize \normalfont \bfseries
4423 \nobreak\medskip
4424 \etocskipfirstprefix}
4425 {\leftskip 0pt \rightskip .75cm \parfillskip-\rightskip
4426 \pagebreak[1]\smallskip}
4427 {\etocnumber. \etocname\DotsAndPage\par}
4428 {\endgroup }
4429
4430 \etocsetlinestyle {subsection}
4431 {\begingroup
4432 \leftskip 1cm \rightskip .75cm \parfillskip 0pt plus 1fil\relax
4433 \footnotesize\sffamily\mdseries\itshape
4434 \nobreak
4435 %\smallskip
4436 }
4437 {}
4438 {\etocname{} \textup{(\etocnumber, p.\@{} \etocpage).} }
4439 {\par
4440 \endgroup
4441 %\smallskip
4442 }
4443
4444 \etocsettagdepth {preamble} {none}
4445 \etocsettagdepth {overview} {none}
4446 \etocsettagdepth {styling} {subsection}
4447 \etocsettagdepth {control} {none}
4448 \etocsettagdepth {examples} {none}
4449 \etocsettagdepth {advanced} {none}
4450 \etocsettagdepth {etocandworld}{subsection}
4451 \etocsettagdepth {code} {none}
4452
4453 \etocsettocstyle {\centering\LARGE\textsc{\contentsname}\par\nobreak\medskip}{}
4454 \etocsetnexttocdepth {all} % but depth tags will control the actual contents
4455 \etocobeydepthtags % this is default anyhow, but may have been turned off
4456 \tableofcontents
4457 \endgroup
4458 \end{filecontentsdef}
4459 \filecontentsexec\foo
4460
4461 \medskip
4462 The code looks like this. For more explanations relative to depth tags, and
4463 especially how they were incorporated into the present document, see also
4464 \autoref{sec:tocwithdepthtags}.
4465 \filecontentsprintviascan\foo
4466 \marginattach
4467
4468 Observe how we used \csa{begingroup} and \csa{endgroup} in the \marg{start}
4469 and \marg{finish} parts of the |section| and |subsection| styles. Another
4470 approach would have been to configure each \marg{prefix} or \marg{contents} to
4471 reset entirely the font characteristics (including the set size, and one has
4472 to be careful where changes are located then with respect to \csa{par}; notice
4473 that on the other hand size changing commands do not modify the amount of
4474 vertical space injected by \csa{bigskip}, \csa{medskip}, \csa{smallskip}).
4475
4476 One last remark: the code above uses \csb{etocsetlinestyle} only for parts,
4477 sections and subsections. Non-styled levels would be displayed using
4478 fall-back defaults which are incorporated into the package code: this proves
4479 (about) fine with ``chapter'' but the fall-back ``subsubsection'' style
4480 expects to get started in vertical mode, so would induce breakage if the
4481 tocdepth allows it. The fall-back defaults for |paragraph| and
4482 |subparagraph| display nothing at all (deliberately).
4483
4484
4485 \section{A Beautiful Thesis example}
4486
4487 Here is a relatively simple example of use of the package
4488 functionalities.
4489 Let us set up some line styles. We choose a style for sections and
4490 sub-sections which would be suitable for, respectively, sections and
4491 sub-sections in an average length memoir. The line style specifications have
4492 some redundancy for clarity, and do not care about what to do at possible page
4493 breaks. Also, they do not worry about potential multi-column use.
4494
4495 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
4496 \begingroup % we start a group to keep the style changes local
4497 \newlength{\tocleftmargin} \setlength{\tocleftmargin}{4cm}
4498 \newlength{\tocrightmargin} \setlength{\tocrightmargin}{1cm}
4499
4500 \etocsetlinestyle{section} % will pretend to be a Chapter
4501 {\addvspace{1ex}\parfillskip0pt
4502 \leftskip\tocleftmargin % (already done in title)
4503 \rightskip\the\tocrightmargin plus 1fil
4504 \parindent0pt\color{cyan}} % (already done)
4505 {\bfseries\LARGE\upshape\addvspace{1ex}\leavevmode}
4506 {\llap{Chapter\hspace{.5em}{\etocnumber}\hspace{.75cm}}\etocname
4507 \nobreak\hfill\kern1em\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
4508 {}
4509
4510 \etocsetlinestyle{subsection} % will pretend to be a Section
4511 {}
4512 {\mdseries\large\addvspace{.5ex}\leavevmode}
4513 {\llap{\etocnumber\hspace{.75cm}}\textit{\etocname}%
4514 \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
4515 {}
4516
4517 \def\tmptitle{My Beautiful Thesis}
4518 \etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin
4519 \leavevmode\leaders\hrule height 1pt\hfill\
4520 \huge\textit{\tmptitle}\par}{\bigskip}
4521
4522 \tableofcontents \ref{toc:overview}
4523 \endgroup
4524 \end{filecontentsdef}
4525
4526 \filecontentsexec\foo
4527
4528 \filecontentsprintviascan\foo
4529 \marginattach
4530
4531
4532 \section{Testing the compatibility mode}\label{sec:testingcompat}
4533
4534 As a further example we now print the local table of contents
4535 of \autoref{sec:tocstyle}. First we will test the compatibility mode.\footnote{the
4536 present document uses the \ctanpkg{scrartcl} class, and we check here that
4537 the \etoc compatibility mode does respect the customizing done via the
4538 class commands.} The original is the local table of contents of
4539 \autoref{sec:tocstyle}, to which we allocated the label |toc:tocstyle|.
4540 \begin{verbatim}
4541 \begingroup % to keep in particular toc=left with local effect
4542 \KOMAoptions{toc=left}
4543 \etocclasstocstyle % necessary for the display to obey toc=left
4544 \etocstandardlines % use the document class built-in TOC line styles
4545 \tableofcontents \ref{toc:tocstyle}
4546 \endgroup
4547 \end{verbatim}
4548 \begingroup
4549 \KOMAoptions{toc=left}
4550 \etocclasstocstyle
4551 \etocstandardlines
4552 \tableofcontents \ref{toc:tocstyle}
4553 \endgroup
4554
4555 \section{Another compatibility mode}
4556 \label{sec:anothercompat}
4557
4558 As explained in \autoref{subs:compat}, the commands \csb{etocstandardlines}
4559 and \csb{etocetoclocaltocstyle} tell \etoc to, essentially, act as an
4560 observer. And it starts in this state initially. The document class layout
4561 for the table of contents is then perfectly obeyed (well, hopefully). There
4562 is no way \emph{if remaining in this compatibility mode} to customize this
4563 standard layout (change fonts, margins, vertical spacings, etc...) from within
4564 the package.
4565
4566 For customizing \emph{while remaining in the compatibility mode}, use some
4567 package dedicated to this task; because \etoc either is (temporarily perhaps)
4568 in compatibility mode with no customization on its part possible, or the user
4569 has specified the layout in \csb{etocsetlinestyle} commands (and
4570 \csb{etocsettocstyle}) and is supposedly in complete control.
4571
4572 Well, there is actually an alternative. It is possible to use the
4573 \csb{etocsetlinestyle} commands to recreate an artificial compatibility mode, in
4574 order to achieve effects like the following, all things being otherwise equal
4575 to the document class defaults:
4576 \begin{enumerate}[noitemsep]
4577 \item get the \ctanpkg{hyperref} link to encapsulate only the names, but not the numbers
4578 of each entry of the table of contents,
4579 \item use the document class style for chapters and sections, but modify it only
4580 for subsections,
4581 \item do either of the above only for some portions of the table of contents.
4582 \end{enumerate}
4583
4584 One only needs
4585 to use within the arguments of \csb{etocsetlinestyle} the \LaTeX{} standard
4586 \csa{l@chapter}, \csa{l@section}, etc... re-constituting their arguments using
4587 \csb{etocname}, \csb{etocnumber}, \csb{etocpage} as one wishes.
4588 Here is an example. Include in your document preamble:
4589
4590 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
4591 \makeatletter
4592 \newcommand{\MyLocalTOC}[1][section]{%
4593 \begingroup
4594 \etocsetlinestyle{chapter}{}{}
4595 {\l@chapter{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
4596 \etocsetlinestyle{section}{}{}
4597 {\l@section{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
4598 \etocsetlinestyle{subsection}{}{}
4599 {\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
4600 \etocsetlinestyle{subsubsection}{}{}
4601 {\l@subsubsection{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
4602 % etc... if further sectioning units are needed
4603 % (i.e. not excluded by tocdepth and actually there in document)
4604 % Here #1 defaults to section, meaning this is appropriate
4605 % for local TOC in a chapter
4606 \etocsettocstyle{\@nameuse{#1}*{Local contents}}
4607 {}%
4608 %
4609 \localtableofcontents
4610 \endgroup}
4611 \makeatother
4612 \end{filecontentshere}
4613 \marginattach
4614
4615 Then use \csa{MyLocalTOC} in the document body. It is prepared
4616 for being local to a \csa{chapter}'s as it typesets the heading of the TOC
4617 by default as un unnumbered section.%
4618 %
4619 \footnote{Parts are handled somewhat differently according to whether
4620 one uses the standard or other classes; please check the source of these
4621 classes for what is to emulate here.}
4622
4623 One can add to the above arbitrary text formatting commands, for example
4624 one can replace |\etocpage| in the code above by |\textcolor{blue}{\etocpage}|.
4625
4626 Only pay attention to using |\makeatletter/\makeatother| as we are handling
4627 \LaTeX{} macros with the dangerous sign |@| in their names.
4628
4629 To give another example, one sees in \texttt{article.cls} the following
4630 definition:
4631 \begin{verbatim}
4632 \newcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.3em}}
4633 \end{verbatim}
4634 The first argument is the level, the second the indent, and the third the
4635 numwidth (see the \ctanpkg{tocloft} documentation). So if we issue in a
4636 document using the \texttt{article} class:
4637 \begin{verbatim}
4638 \makeatletter
4639 \etocsetlinestyle{subsection}
4640 {]
4641 {}
4642 {\@dottedtocline{2}{1.5em}{2.3em}{\numberline{etocnumber}\etocname}{\etocpage}}
4643 {}
4644 \makeatother
4645 \end{verbatim}
4646 we then basically reconstitute the default rendering. Here is more careful
4647 code:
4648 \begin{verbatim}
4649 \makeatletter
4650 \etocsetlinestyle{subsection}
4651 {]
4652 {}
4653 {\@dottedtocline{2}{1.5em}{2.3em}{\etocifnumbered{\numberline{etocnumber}}{}%
4654 \etocname}{\etocpage}}
4655 {}
4656 \makeatother
4657 \end{verbatim}
4658 Hence one can very easily without any (additional...) package modify the
4659 hard-coded indent |1.5em| and numwidth |2.3em|. But in general one has to do
4660 this in a synchronized way also for subsubsections, and for sections. The
4661 definition of |\l@section| in the \texttt{article} class source is a bit more
4662 complex.
4663
4664 Nevertheless this technique is probably the fastest (but see the example at
4665 start of \autoref{sec:linestyles}) to get going with \etoc even if one is
4666 primarily interested only in its \localtoc, as typesetting local tables of
4667 contents exactly as global tables of contents is not ideal. For example for a
4668 local TOC in a section, it looks appropriate to modify the above into
4669 \begin{verbatim}
4670 \makeatletter
4671 \etocsetlinestyle{subsection}
4672 {]
4673 {}
4674 {\@dottedtocline{2}{0}{2.3em}{\etocifnumbered{\numberline{etocnumber}}{}%
4675 \etocname}{\etocpage}}
4676 {}
4677 \makeatother
4678 \end{verbatim}
4679 to cancel the indentation. One will have to keep the indents and numwidths in
4680 sync with similar changes to other line styles, if \csa{contentsline}'s of
4681 various levels are to be executed.
4682
4683 %
4684 %
4685 The number and the name of each entry are each separately an \ctanpkg{hyperref}
4686 links, as is always the case with \etoc, when not in compatibility
4687 mode. Replacing \csb{etocnumber} with \csb{etocthenumber} will give a TOC where
4688 the numbers are not links anymore, but the names still are. Or one may decide
4689 to use \csb{etocthename} and keep an hyperlinked number with \csb{etocnumber}.
4690
4691 For a more sophisticated example see \autoref{sec:anothercompatadvanced}.
4692
4693
4694 \section{Emulating the book class}\label{sec:thirdexample}
4695
4696 As explained in \autoref{subs:compat}: without explicit use of an
4697 \csb{etocsetlinestyle} command the package will leave to the document class the
4698 hand regarding the ``toc line styles''. It is sometimes asked by users (for
4699 example those using \etoc for its \csb{localtableofcontents}) how to stay
4700 close to but not completely identical with the design implemented by the
4701 standard classes, such as |book|. I can recommend package \ctanpkg{tocloft} for this,
4702 as it is compatible with \etoc (see \autoref{subs:tocloft}) and thus \etoc will
4703 obey the \ctanpkg{tocloft} customizations (as long as no use has been made of
4704 \csb{etocsetlinestyle}). It is also possible to modify only the style for, say,
4705 sections and leave the parts, chapters, subsections as in the document class,
4706 via the technique from \autoref{sec:anothercompat}.
4707
4708 But for complete control, here is a translation of the |book| class code into
4709 \etoc lingua. It is then easy to modify the relevant lengths or adjust the
4710 used fonts. I thank \textsc{Denis Bitouzé} for prompting me to include this in
4711 the \etoc manual, as it resulted from some conversation we had about this. The
4712 code is not 100\% faithful to the |book| class, and particularly its rendering
4713 of (multi-line) non-numbered units differs (... I think, as I copied pasted as
4714 is the code from where I had stored it and did not do much thinking about it
4715 again). Some proficiency in low-level \TeX\ and \LaTeX\ macros is needed to
4716 understand what the code says, but for modifying fonts or some lengths such
4717 in-depth understanding is not needed.
4718
4719 With some extra code one can \emph{automatically adjust the widths} assigned
4720 to typesetting sectioning numbers in order to prevent overflows, even with for
4721 example \MakeUppercase{\romannumeral 38}; but this is a more advanced feature
4722 which I have moved to \autoref{sec:thirdexampleextra}.
4723
4724 First we set up some lengths. I use macro registers, not real \LaTeX\ lengths.
4725 When using |em|'s however, this means that one must pay attention to when the
4726 actual dimension assignment is made, as this will then depend upon the current
4727 font settings. In the code below, at the location where the \csa{TOCnumwidthB}
4728 and \csa{TOCnumwidthC} will be used, the |1em| from their specification will
4729 be matched to the normal medium series font, not the bold font; this is
4730 deliberate so that one can compare more readily with the other dimensions;
4731 besides, with the \csa{TOCcomputenumwidths} from
4732 \autoref{sec:thirdexampleextra} these macros will actually hold a dimension
4733 using |pt| as dimensional unit.
4734
4735 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
4736 % it will be easy to globally shift the TOC horizontally if needed
4737 \def\TOCleftmargin {0pt}
4738 \def\TOCrightmargin {2.55em}% like LaTeX's \@tocrmarg
4739
4740 % this is for dotted leaders
4741 \newbox\TOCleaderbox
4742 \def\TOCleaderboxwidth {0.7777em}% about like what standard classes do
4743
4744 % vertical spacing
4745 \def\TOCverysmallvskip {0pt plus .2pt}
4746 \def\TOCmedvskip {1em plus 1pt}
4747 \def\TOCbigvskip {2.25em plus 1pt}
4748
4749 % the ``numwidths'' for typesetting the numbering of division units.
4750 % I don't recall exactly how (and for which fonts) these figures were chosen.
4751 % They quickly prove too small if using Roman numerals (as do too the book
4752 % class defaults even though they are a bit larger).
4753 % NOTA BENE IT WOULD PROBABLY BE BETTER TO NOT USE THE FONT-DEPENDENT
4754 % em DIMENSION UNIT HERE BUT EITHER pt OR bp
4755 \def\TOCnumwidthB {1.5em} % chapter
4756 \def\TOCnumwidthC {2.278em}% section, I think default is 2.3em
4757 \def\TOCnumwidthD {3.056em}% analog in standard class is 3.2em
4758 \def\TOCnumwidthE {3.833em}% analog in standard class is 4.1em
4759 \def\TOCnumwidthF {4.611em}% analog in standard class is 5em
4760 \def\TOCnumwidthG {5.389em}% analog in standard class is 6em
4761
4762 % The code for the ``global toc style''.
4763 \makeatletter % (was missing from this code snippet demo up to doc v1.2e)
4764 \newcommand*\TOCglobalstyle {%
4765 \etocsettocstyle
4766 {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi
4767 \parindent\z@ \leftskip\z@skip \rightskip \z@skip
4768 \setbox\TOCleaderbox\hbox to \TOCleaderboxwidth{\hss.\hss}%
4769 \chapter *{\noindent\kern\TOCleftmargin\relax % uses "pt"...
4770 \contentsname
4771 \@mkboth {\MakeUppercase \contentsname}{\MakeUppercase \contentsname}}%
4772 \rightskip \TOCrightmargin\relax
4773 \parfillskip -\rightskip % or a smaller value if desired
4774 \leftskip \TOCleftmargin \relax }
4775 {\if@restonecol \twocolumn \fi\cleardoublepage}%
4776 %
4777 \etocsetlinestyle{part}
4778 {}
4779 {\addpenalty {-\@highpenalty}%
4780 \addvspace \TOCbigvskip
4781 \leavevmode
4782 {\large \bfseries % use a group to limit font change
4783 \interlinepenalty\@M
4784 \etocifnumbered{\etocnumber\hspace{1em}}{}%
4785 \etocname
4786 \nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}}\par
4787 \nobreak
4788 }
4789 {}
4790 {}%
4791 %
4792 \etocsetlinestyle{chapter}
4793 {\advance\leftskip\TOCnumwidthB\relax}
4794 {\addpenalty {-\@highpenalty }%
4795 \vskip \TOCmedvskip\relax
4796 \leavevmode
4797 {\interlinepenalty\@M
4798 \etocifnumbered
4799 {\llap{\makebox[\TOCnumwidthB][l]{\bfseries\etocnumber}}}
4800 {\advance\leftskip-\TOCnumwidthB\relax}%
4801 \bfseries\etocname
4802 \nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}\par }%
4803 \penalty \@highpenalty
4804 }
4805 {}
4806 {\advance\leftskip-\TOCnumwidthB\relax}%
4807 %
4808 \TOCsetlinestyle {section} {\TOCnumwidthC}%
4809 \TOCsetlinestyle {subsection} {\TOCnumwidthD}%
4810 \TOCsetlinestyle {subsubsection}{\TOCnumwidthE}%
4811 \TOCsetlinestyle {paragraph} {\TOCnumwidthF}%
4812 \TOCsetlinestyle {subparagraph} {\TOCnumwidthG}%
4813 }% end of \TOCglobalstyle
4814
4815 %The common code for line styles is abstracted into a macro:
4816
4817 \newcommand\TOCsetlinestyle [2]{% #1= unit, #2= numwidth as macro
4818 \etocsetlinestyle{#1}
4819 {\advance\leftskip#2\relax}
4820 {\vskip \TOCverysmallvskip\relax
4821 \leavevmode
4822 {\interlinepenalty\@M
4823 \etocifnumbered
4824 {\llap{\makebox[#2][l]{\etocnumber}}}{\advance\leftskip-#2\relax}%
4825 \etocname
4826 \nobreak\leaders \copy\TOCleaderbox
4827 \hfil\makebox[-\parfillskip][r]{\etocpage}%
4828 \par }%
4829 }
4830 {}
4831 {\advance\leftskip-#2\relax}%
4832 }
4833 \makeatother
4834 \end{filecontentshere}
4835 \marginattach
4836
4837 Nota Bene: the code deliberately handles the non-numbered sectioning units
4838 differently from what the standard document classes \texttt{article},
4839 \texttt{report}, \texttt{book} do, particularly regarding the alignment of
4840 multi-line headings.
4841
4842 Important: the whole thing is encapsulated in a command \csa{TOCglobalstyle},
4843 and you must used that command to see the effect of the above definitions if
4844 copied pasted to your document.
4845
4846 We also want a \csa{TOClocalstyle} for local tables of contents which
4847 typically will want to use |\section*| rather than |\chapter*| and not insert
4848 page marks in the headers. The \csa{TOClocalstyle} is to be issued once, after
4849 the main document TOC, or rather before using \localtoc. If one needs a full
4850 TOC also at end of document one will have to execute there again
4851 \csa{TOCglobalstyle}.
4852
4853 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
4854 \makeatletter
4855 \newcommand*\TOClocalstyle {%
4856 \etocsettocstyle
4857 {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi
4858 \setbox\TOCleaderbox\hbox to \TOCleaderboxwidth{\hss.\hss}%
4859 \parindent\z@
4860 \dimen@ 2.25em % for left indenting
4861 \section *{\kern\dimen@ % use of \dimen@ works here by sheer luck
4862 \contentsname
4863 % un-comment this if marks are wanted:
4864 %\@mkboth {\MakeUppercase \contentsname}{\MakeUppercase \contentsname}%
4865 }% end of \section
4866 \parskip \z@skip
4867 \vspace{-1.25\baselineskip}% somewhat ad hoc
4868 \leftskip 2.25em
4869 \rightskip 4.5em
4870 \advance\rightskip-\TOCrightmargin\relax
4871 \leavevmode\leaders\hrule\@height\p@\hfill\kern\z@\par
4872 \rightskip 4.5em
4873 \parfillskip -\TOCrightmargin\relax }
4874 {\nobreak\vskip-.5\baselineskip
4875 \leavevmode\leaders\hrule\@height\p@\hfill\kern\z@\par
4876 \bigskip
4877 \if@restonecol \twocolumn \fi }%
4878 %
4879 \etocsetlinestyle{section}
4880 {\advance\leftskip\TOCnumwidthC\relax}
4881 {\addpenalty \@secpenalty
4882 \etociffirst{}{\addvspace{\TOCmedvskip}}%
4883 \leavevmode
4884 {\interlinepenalty\@M
4885 % \bfseries % <<<< commented out for the 1.2e version of documentation
4886 % no good if \TOCnumwidthC is expressed with em unit
4887 % as the latter has been used already above for \leftskip
4888 % so better to either redefine it to use pt or to move
4889 % the \bfseries to after usage of \TOCnumwidthC
4890 \etocifnumbered
4891 {\llap{\makebox[\TOCnumwidthC][l]{\etocnumber}}}
4892 {\advance\leftskip-\TOCnumwidthC}%
4893 \etocname\nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}\par }%
4894 \penalty \@highpenalty }
4895 {}
4896 {\advance\leftskip-\TOCnumwidthC\relax}%
4897 % the rest is identical with code for global tocs:
4898 \TOCsetlinestyle {subsection} {\TOCnumwidthD}%
4899 \TOCsetlinestyle {subsubsection}{\TOCnumwidthE}%
4900 \TOCsetlinestyle {paragraph} {\TOCnumwidthF}%
4901 \TOCsetlinestyle {subparagraph} {\TOCnumwidthG}%
4902 }% end of \TOClocalstyle
4903 \makeatother
4904 \end{filecontentshere}
4905 \marginattach
4906
4907 As mentioned previously, this handles non-numbered (multi-line) sectioning
4908 units somewhat differently from what happens in the standard document classes.
4909
4910 For some reason this code has some hard-coded |2.25em| and |4.5em| which were
4911 not abstracted into macros or lengths. The code inserts horizontal rules above
4912 and below the TOC contents in a non-separable by pagebreak way.
4913
4914 See \autoref{sec:thirdexampleextra} for more.
4915
4916 \section{A framed display}
4917
4918 We now opt for a ``framed'' style, using the package default
4919 line styles and some colors added (it has been put in a float which appears
4920 \vpageref{toc:b}).
4921
4922
4923 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
4924 \etocfallbacklines
4925 \begingroup
4926 \renewcommand{\etoccolumnsep}{2em}
4927 \renewcommand{\etocinnerleftsep}{1.5em}
4928 \renewcommand{\etocinnerrightsep}{1.5em}
4929 % specify a background color for the toc contents
4930 \renewcommand{\etocbkgcolorcmd}{\color{yellow!10}}
4931 % set up the top and bottom rules
4932 \renewcommand{\etoctoprule}{\hrule height 1pt}
4933 \renewcommand{\etoctoprulecolorcmd}{\color{red!25}}
4934 \renewcommand{\etocbottomrule}{\hrule height 1pt}
4935 \renewcommand{\etocbottomrulecolorcmd}{\color{red!25}}
4936 % set up the left and right rules
4937 \renewcommand{\etocleftrule}{\vrule width 5pt}
4938 \renewcommand{\etocrightrule}{\vrule width 5pt}
4939 \renewcommand{\etocleftrulecolorcmd}{\color{red!25}}
4940 \renewcommand{\etocrightrulecolorcmd}{\color{red!25}}
4941 % use \fcolorbox to set up a colored frame for the title
4942 \fboxrule1pt
4943 \renewcommand{\etocbelowtocskip}{0pt\relax}
4944 \etocframedstyle {\normalsize\rmfamily\itshape
4945 \fcolorbox{red}{white}{\parbox{.8\linewidth}{\centering
4946 This is a table of contents \`a la \etoc, but for
4947 the subsections and subsubsections of \autoref{sec:tocstyle}.
4948 As it is put in a frame, it has to be small enough to fit on
4949 one page. It has the label |toc:b|.}}}
4950 \begin{figure}[ht!]
4951 \centering
4952 \tableofcontents \label{toc:b} \ref{toc:tocstyle}
4953 \end{figure}
4954 \endgroup
4955 \end{filecontentshere}
4956 \marginattach
4957
4958 \filecontentsexec\filecontentsheremacro
4959
4960
4961
4962
4963 \section{Another TOC with background color}\label{ssec:again}
4964
4965 Let us now try out some more sophisticated line styles. The display will use
4966 the \csb{etocframedstyle} package command, which requires that the produced
4967 table of contents fits on a single page. We wrap it up in a
4968 \hyperref[toc:floating]{figure environment} showing up
4969 \vpageref{toc:floating}.
4970
4971 This design uses the \etoc `framed' style with a background color. The frame
4972 borders have been set to have the same color as the one serving as background
4973 for the entire thing. It would be advantageous to use rather inside
4974 \csb{etocsettocstyle} commands from a package like |tcolorbox| as this allows
4975 sophisticated breakable boxes (with |TikZ/pgf| for decoration.)
4976
4977 The details of the line styles used here are a bit involved, they were written
4978 by the author at some early stage of this documentation and have only been
4979 slightly revised to use more \LaTeX-commands and less \TeX-primitives. Similar
4980 code is used also for \hyperref[toc:clone]{this other toc}.
4981
4982
4983 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
4984 \begin{figure}[htbp!]\centering
4985 \colorlet{subsecnum}{black}
4986 \colorlet{secbackground}{green!30}
4987 \colorlet{tocbackground}{red!20!green!20}
4988
4989 \renewcommand{\etocbkgcolorcmd}{\color{tocbackground}}
4990 \renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
4991 \renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
4992 \renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
4993 \renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
4994
4995 \renewcommand{\etocleftrule}{\vrule width 3cm}
4996 \renewcommand{\etocrightrule}{\vrule width 1cm}
4997 \renewcommand{\etocbottomrule}{\hrule height 12pt}
4998 \renewcommand{\etoctoprule}{\hrule height 12pt}
4999
5000 \renewcommand{\etocinnertopsep}{0pt}
5001 \renewcommand{\etocinnerbottomsep}{0pt}
5002 \renewcommand{\etocinnerleftsep}{0pt}
5003 \renewcommand{\etocinnerrightsep}{0pt}
5004
5005 \newcommand\shiftedwhiterule[2]{%
5006 \hbox to \linewidth{\color{white}%
5007 \hskip#1\leaders\vrule height1pt\hfil}\nointerlineskip
5008 \vskip#2}
5009
5010 \etocsetlinestyle{subsubsection}
5011 {\etocskipfirstprefix}
5012 {\shiftedwhiterule{\leftskip}{6pt}}
5013 {\sffamily\footnotesize
5014 \leftskip2.3cm\hangindent1cm\rightskip.5cm\relax
5015 \makebox[1cm][l]{\color{subsecnum}\etocnumber}%
5016 \color{black}\etocname
5017 \nobreak\leaders\hbox to.2cm{\hss.}\hfill
5018 \rlap{\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}\par
5019 \nointerlineskip\vskip3pt}
5020 {}
5021
5022 \etocsetlinestyle{subsection}
5023 {\etocskipfirstprefix}
5024 {\shiftedwhiterule{1.5cm}{6pt}}
5025 {\sffamily\small
5026 \leftskip1.5cm\hangindent.8cm\rightskip.5cm\relax
5027 \makebox[.75cm][l]{\color{subsecnum}\etocnumber}%
5028 \color{black}\etocname
5029 \nobreak\leaders\hbox to.2cm{\hss.}\hfill
5030 \rlap{\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}\par
5031 \nointerlineskip\vskip3pt}
5032 {}
5033
5034 \newcommand{\coloredstuff}[2]{%
5035 \leftskip0pt\rightskip0pt\parskip0pt
5036 \fboxsep0pt % \colorbox uses \fboxsep also when no frame!
5037 \noindent\colorbox{secbackground}
5038 {\parbox{\linewidth}{%
5039 \vskip5pt
5040 {\noindent\color{#1}#2\par}\nointerlineskip
5041 \vskip3pt}}%
5042 \par\nointerlineskip}
5043
5044 \etocsetlinestyle{section}
5045 {\coloredstuff{blue}{\hfil \bfseries\large Contents of Part One\hfil}}
5046 {\vskip3pt\sffamily\small}
5047 {\coloredstuff{blue}
5048 {\leftskip1.5cm\rightskip.5cm\parfillskip-\rightskip
5049 \makebox[0pt][r]{\makebox[.5cm][l]{\etocnumber}}%
5050 \etocname\nobreak\hfill\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}%
5051 \vskip6pt}
5052 {}
5053
5054 \etocframedstyle[1]{}
5055 \tableofcontents \label{toc:floating} \ref{toc:part:styling}
5056 \vspace{-\baselineskip}
5057 \centeredline{|\tableofcontents \ref{toc:part:styling}|
5058 (\emph{cf.} \hyperref[toc:clone]{this other toc})}
5059 \end{figure}
5060 \end{filecontentshere}
5061 \marginattach
5062
5063 \filecontentsexec\filecontentsheremacro
5064 The table of contents produced by this code appears on \vpageref{toc:floating}.
5065
5066 \section{A (crazy) inline display}
5067 \label{sec:crazy}
5068
5069 Let us construct some crazy inline display of the table of
5070 contents of this entire document. We will typeset the subsections as
5071 footnotes... This kind of style is suitable for a hyperlinked
5072 document, probably not for print! (although I like it, but my personal tastes in
5073 many matters do not seem to be widely shared).
5074
5075 %%%% Note: 27 april 2014
5076
5077 %%%% except for a miraculous situation depending from the quantity of previous
5078 %%%% material this TOC will have links extending accross pagebreaks, which
5079 %%%% dvipdfmx does not know how to handle completely. Apart from that the output
5080 %%%% is ok, thus no need to try seriously to avoid them.
5081
5082 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
5083 \begingroup
5084 \newsavebox{\forsubsections}
5085 \etocsetlinestyle{part}{\upshape. \etocskipfirstprefix}
5086 {. \upshape}
5087 {\bfseries\etocname:~~}
5088 {}
5089 \etocsetlinestyle{section}{\itshape\etocskipfirstprefix}
5090 {, }
5091 {\mdseries\etocname}
5092 {}
5093 \etocsetlinestyle{subsection}
5094 {\begin{lrbox}{\forsubsections}\footnotesize\upshape\etocskipfirstprefix}
5095 {; }
5096 {\etocname}
5097 {.\end{lrbox}\footnote{\unhbox\forsubsections}}
5098 \etocsetlinestyle{subsubsection}
5099 { (\itshape\etocskipfirstprefix}
5100 {, }
5101 {\etocname}
5102 {\/\upshape)}
5103 \etocsettocstyle{Here is the inline table of contents. }{.\par}
5104 \tableofcontents \label{toc:crazyinline}
5105 \endgroup
5106 \end{filecontentsdef}
5107
5108 \filecontentsexec\foo
5109
5110 The code used:
5111 \filecontentsprintviascan\foo
5112 \marginattach
5113
5114 \section{One more example of colored TOC layout}
5115 \label{ssec:tocclone}
5116
5117 The command \csb{etocframedstyle} puts the title on the top
5118 rule in a centered position. This is not very convenient for
5119 this example so we included the title as part of the
5120 \meta{start} code at section level, to get it \emph{inside}
5121 the frame.
5122
5123 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
5124 \begingroup
5125 \definecolor{subsecnum}{RGB}{13,151,225}
5126 \definecolor{secbackground}{RGB}{0,177,235}
5127 \definecolor{tocbackground}{RGB}{212,237,252}
5128
5129 \renewcommand{\etocbkgcolorcmd}{\color{tocbackground}}
5130 \renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
5131 \renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
5132 \renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
5133 \renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
5134
5135 \renewcommand{\etocleftrule}{\vrule width 1cm}
5136 \renewcommand{\etocrightrule}{\vrule width .5cm}
5137 \renewcommand{\etocbottomrule}{\hrule height 12pt}
5138 \renewcommand{\etoctoprule}{\hrule height 12pt}
5139
5140 \renewcommand{\etocinnertopsep}{0pt}
5141 \renewcommand{\etocinnerbottomsep}{0pt}
5142 \renewcommand{\etocinnerleftsep}{0pt}
5143 \renewcommand{\etocinnerrightsep}{0pt}
5144
5145 \newcommand\shiftedwhiterule[2]{%
5146 \hbox to \linewidth{\color{white}%
5147 \hskip#1\leaders\vrule height1pt\hfil}\nointerlineskip\vskip#2}
5148
5149 \etocsetlinestyle{subsubsection}{\etocskipfirstprefix}
5150 {\shiftedwhiterule{\leftskip}{6pt}}
5151 {\sffamily\footnotesize
5152 \leftskip2.5cm\hangindent1cm\rightskip1cm\noindent
5153 \hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
5154 \color{black}\etocname\leaders\hbox to .2cm{\hss.}\hfill
5155 \rlap{\hbox to 1cm{\hss\etocpage\hskip.2cm}}\par
5156 \nointerlineskip\vskip3pt}
5157 {}
5158
5159 \etocsetlinestyle{subsection}{\etocskipfirstprefix}
5160 {\shiftedwhiterule{1.5cm}{6pt}}
5161 {\sffamily\small
5162 \leftskip1.5cm\hangindent1cm\rightskip1cm\noindent
5163 \hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
5164 \color{black}\etocname\leaders\hbox to .2cm{\hss.}\hfill
5165 \rlap{\hbox to 1cm{\hss\etocpage\hskip.2cm}}\par
5166 \nointerlineskip\vskip6pt}
5167 {}
5168
5169 \newcommand{\coloredstuff}[2]{%
5170 \leftskip0pt\rightskip0pt\parskip0pt
5171 \fboxsep0pt % \colorbox uses \fboxsep also when no frame!
5172 \noindent\colorbox{secbackground}
5173 {\parbox{\linewidth}{%
5174 \vskip5pt
5175 {\noindent\color{#1}#2\par}\nointerlineskip
5176 \vskip3pt}}%
5177 \par\nointerlineskip}
5178
5179 \etocsetlinestyle{section}
5180 {\coloredstuff{white}
5181 {\hfil \hyperref[toc:b]{\bfseries\large I am a twin of
5182 that other TOC (click me!)}\hfil}}
5183 {\vskip3pt\sffamily\small}
5184 {\coloredstuff{white}
5185 {\leftskip1.5cm\rightskip.5cm\parfillskip-\rightskip
5186 \makebox[0pt][r]{\makebox[.5cm][r]{\etocnumber\hspace{.2cm}}}%
5187 \etocname\hfill\makebox[.5cm][r]{\etocpage\hspace{.2cm}}}%
5188 \vskip6pt }
5189 {}
5190
5191 \etocframedstyle[1]{}
5192 \tableofcontents \label{toc:clone} \ref{toc:tocstyle}
5193 \endgroup
5194 \end{filecontentshere}
5195 \marginattach
5196
5197 \filecontentsexec\filecontentsheremacro
5198 % 1.07l on the occasion of traduction into German documentation
5199 % APRIL 26, 2014 Improvement in the section style for better placement of
5200 % page number when the section name is more than one line long. Use of
5201 % \makebox rather than \hbox, to be more LaTeX like.
5202
5203 The TOC has been put in a \hyperref[toc:clone]{float} which appears
5204 \vpageref{toc:clone}. The coding is a bit involved\footnote{and reveals the
5205 author's preference for the \TeX{} syntax...} as it does not use any
5206 additional package. Also, it was written at some early stage and I have not
5207 revised it since.
5208
5209 A better solution would be to use some package to set
5210 up a background color possibly extending accross pages, as the
5211 framed style (which we used to get this background
5212 color) can only deal with material short enough to fit on one
5213 page.
5214
5215 % 1.2 doc: commenté out to avoid a new page
5216 % ah non finalement car cause TOC as a tree d'être sur page impaire,
5217 % ce qui est moins bien à cause des overlap.
5218 Regarding colors, generally speaking all color commands inside
5219 \etoc are initially defined to do nothing, and the choice to
5220 use or not colors is left to the user.
5221
5222 \clearpage
5223 \etocdepthtag.toc {advanced}
5224 \part{Advanced examples}
5225 \label{part:surprising}
5226
5227 \thispartstats %% (pas de sous-section)
5228
5229 \etocfallbacklines
5230 \etocsettocstyle {}{}
5231 \localtableofcontents
5232
5233 \section{The TOC of TOCs}
5234 \label{sec:tocoftocs}
5235
5236 \begingroup % \endgroup just after the \tableofcontents command
5237 \etocinline
5238 \etocsetlevel{part}{1}
5239 \etocsetlevel{visibletoc}{0}
5240 \etocsetlinestyle{visibletoc}
5241 {\etocskipfirstprefix}
5242 {, }
5243 {{\color{niceone}\etocname}}
5244 {}
5245 \etocsettocstyle{}{}
5246 \etocsetnexttocdepth{visibletoc}
5247
5248
5249 Here is the numbered and linked list of all tables of contents which are
5250 displayed within this document:\footnote{The TOCs put in
5251 floats may change the order: the numbers are listed
5252 in the order the TOCs are typeset in the document; but the numbering
5253 itself is from the order of the TOCs in the \emph{source} of
5254 this document... }
5255 \tableofcontents
5256 \endgroup. And to obtain
5257 it here we just wrote:\par\smallskip
5258 {\leftskip1cm\rightskip2cm
5259 \ttfamily\small\baselineskip11pt \noindent Here is the
5260 numbered and linked list of all tables of contents which are
5261 displayed within this
5262 document:~\string\tableofcontents.\par}
5263
5264 The preparatory work was the following. First, we defined a
5265 counter |visibletoc| whose vocation is to get incremented at
5266 each displayed toc. \etoc has its own private counter but it
5267 counts all TOCs, even those not displayed because the |tocdepth|
5268 value was |-2| or |-3|.
5269
5270 We could have added manually |\refstepcounter{visibletoc}|
5271 and |\label| commands at all suitable locations in the
5272 document source, and we would then have used here |\ref|
5273 commands, but this imposes heavy manual editing of the source.
5274
5275 There is a much better way: there is a hook
5276 \csb{etocaftertitlehook} and we told it to increment the
5277 |visibletoc| counter and to write a line to the |.toc| file,
5278 in a manner analogous to what sectioning commands such as
5279 |chapter|, |section|, or |subsection| do. As \etoc
5280 increments its own private counter even before typesetting
5281 the title of a table of contents, this provides (most of the
5282 time) a better link destination than any counter manipulated
5283 from inside \csb{etocaftertitlehook} (for which the link
5284 would target the area just after the title). So, rather than
5285 including |\refstepcounter{visibletoc}| inside
5286 \csb{etocaftertitlehook}, we just put there
5287 |\stepcounter{visibletoc}| followed by the command
5288 \csb{etoctoccontentsline}|{visibletoc}{\thevisibletoc}|. This \etoc
5289 command \csb{etoctoccontentsline}\marg{level\_name}\marg{name} has the same
5290 effect as:
5291 \centeredline{| ||\addcontentsline{toc}|\marg{level\_name}\marg{name}}
5292 but its usefulness is to circumvent\footnote{using \csa{addtocontents} rather
5293 than \csa{addcontentsline}} the patching for automatic creation
5294 of bookmarks done to \csa{addcontentsline} by the \ctanpkg{hyperref} package,
5295 as pdf bookmarks don't make
5296 much sense here (and would elicit a complaint
5297 of \ctanpkg{hyperref} that the bookmark level is `unknown').\footnote{%
5298 The package provides a starred variant
5299 \staritb{etoctoccontentsline}, which does allow the creation
5300 of bookmarks and has a third mandatory argument which is the
5301 Level to be used by these bookmarks; depending on the context
5302 the starred as well as the non-starred variants may be
5303 profitably preceded by \csa{phantomsection}.}
5304
5305 Finally, the preamble of the document did
5306 \csb{etocsetlevel}|{visibletoc}{6}|. The level |6| (or anything
5307 with a higher number) is ignored, even if |tocdepth| has
5308 value |10| for example; this is independently of whether \etoc
5309 uses the document class default line styles or its own line
5310 styles, or the ones defined by the user with the
5311 \csb{etocsetlinestyle} command. So there is no need to worry that
5312 something could go wrong.
5313
5314 \emph{The example actually uses \csb{etocthemaxlevel}, see the
5315 \etocrelease{1.2a} change log entry.}
5316
5317 Then, only here we have set \csb{etocsetlevel}|{visibletoc}{0}|. And to display
5318 only this kind of entries we assign temporarily to |part| and |chapter| level
5319 |1| (or anything higher than zero) and set |tocdepth| to the value |0|. We
5320 also did%
5321 %
5322 \centeredline{\csb{etocsetlinestyle}\{visibletoc\}\{\csb{etocskipfirstprefix}\}%
5323 \{, \}\{\string\etocname\}\{\}}
5324 %
5325 which defines an inline display with the comma (plus space)
5326 as separator. Finally, as \etoc issues |\par| automatically by default just
5327 before typesetting a table of contents, we used the command \csb{etocinline}
5328 (also known as \cs{etocnopar}) which turns off this behavior.
5329
5330 Here are the implementation details:
5331
5332 \begingroup
5333 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
5334 < in the preamble >
5335 \newcounter{visibletoc}
5336 \renewcommand{\etocaftertitlehook}
5337 {\stepcounter{visibletoc}\etoctoccontentsline{visibletoc}{\thevisibletoc}}
5338 \etocsetlevel{visibletoc}{\etocthemaxlevel}
5339 \begin{document}
5340 < document body >
5341 \subsection{Surprising uses of etoc}
5342 \begingroup
5343 \etocinline
5344 \etocsetlevel{part}{1}
5345 % \etocsetlevel{chapter}{1} % (no chapters in scrartcl class)
5346 \etocsetlevel{visibletoc}{0}
5347 \etocsetlinestyle{visibletoc}
5348 {\etocskipfirstprefix}{, }{{\color{niceone}\etocname}}{}
5349 \etocsettocstyle{}{} % don't set any title, rules or frame or multicol!
5350 \etocsetnexttocdepth{visibletoc} % display only the `visibletoc' entries from .toc
5351
5352 Here is the numbered and linked list of all tables of contents which are
5353 displayed within this document: \tableofcontents.
5354 \endgroup
5355 \end{filecontentshere}
5356 \marginattach
5357 \endgroup
5358
5359 After |\etocsetlinestyle{visibletoc}{..}{..}{..}{..}|, all future TOCs (not in
5360 compatibility mode) will use the
5361 defined style for level |0| (which is normally the level for
5362 chapters). To keep these changes strictly local the simplest
5363 manner is to put everything inside a group.
5364
5365 The \autoref{subsec:interverting} gives another use of the
5366 shuffling of levels.
5367
5368
5369 \section[Arbitrary ``Lists Of...'', \csbhyp{etoctoccontentsline}]{%
5370 Arbitrary ``Lists Of...'', \csbhyp{etoctoccontentsline} and
5371 \csbhyp{etocimmediatetoccontentsline}}
5372 \label{etoctoccontentsline}
5373 \label{etocimmediatetoccontentsline}
5374
5375 This idea of interverting the levels is very powerful and allows
5376 to let \etoc display lists of arbitrary things contained in the
5377 document. All of that still
5378 using nothing else than the |.toc| file!
5379 Example: imagine a document with dozens of
5380 exercises, perhaps defined as |\newtheorem{exercise}{}[section]|. Let
5381 us explain how to instruct \etoc to display an hyperlinked list
5382 of all these exercises. For this we put in the preamble: (but see
5383 \etocrelease{1.2a} change log entry)
5384 \begin{verbatim}
5385 \newtheorem{exerci}{}[section]
5386 % the exercice number will be recoverable via \etocname: v--here--v
5387 \newcommand*{\exercisetotoc}{\etoctoccontentsline{exercise}{\theexerci}}
5388 \newenvironment{exercise}{\begin{exerci}\exercisetotoc}{\end{exerci}}
5389 \etocsetlevel{exercise}{6}
5390 \end{verbatim}
5391 In this way, \csb{etocname} will give the exercise number (but \csb{etocnumber}
5392 will be empty). Had we used instead
5393 \begin{verbatim}
5394 \newcommand*{\exercisetotoc}
5395 {\etoctoccontentsline{exercise}{\protect\numberline{\theexerci}}}
5396 \end{verbatim}
5397 the exercise number would then have been available via \csb{etocnumber}, and
5398 \csb{etocname} would have been empty. It doesn't matter which one of the two
5399 methods is used. The \etoc command \csb{etoctoccontentsline}|{..}{..}| is
5400 provided as a substitute to \csa{addcon\-tentsline}|{toc}{..}{..}|: this is to
5401 avoid the patching which is done by \ctanpkg{hyperref} to \csa{addcontentsline} in its
5402 process of creation of bookmarks. If one wants to authorize \ctanpkg{hyperref} to create
5403 bookmarks at a specific level \meta{n}, one can use (here with \meta{n}$=$|2|)
5404 the starred variant \starit{etoctoccontentsline} which has an additional
5405 argument:
5406 \begin{verbatim}
5407 \newcommand{\exercisetotoc}{\etoctoccontentsline*{exercise}{\theexerci}{2}}
5408 \end{verbatim}
5409
5410 The counter |exerci| is already
5411 incremented by the |exerci| theorem environment, and
5412 provides the correct destination for the link added by package
5413 \ctanpkg{hyperref}. The command \csa{exercisetotoc} adds for each exercise a line
5414 to the |.toc| file, corresponding to a fictitious document
5415 unit with name `|exercise|'. A
5416 four-column list, including the sections, can then be
5417 typeset with the following code:
5418 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
5419 \etocsetnexttocdepth{2} % sections are at level 1 and will show up
5420 \begingroup
5421 \etocsetlevel{exercise}{2} % but:
5422 \etocsetlevel{chapter}{3} % no chapters
5423 \etocsetlevel{subsection}{3} % no subsections
5424 \etocsetlevel{part}{3} % no parts
5425 \etocsetlinestyle{exercise}{}{} % \etocname = exercise number
5426 {\noindent\etocname\strut\leaders\etoctoclineleaders\hfill\etocpage\par}
5427 {\pagebreak[2]\vskip\baselineskip}
5428 \etocsetlinestyle{section}{}{}
5429 {\noindent\strut{\bfseries\large\etocnumber\hskip.5em\etocname}\par
5430 \nopagebreak[3]}{}
5431 \etocruledstyle[4]{\Large\bfseries List of the exercises}
5432 \setlength{\columnseprule}{.4pt}
5433 \tableofcontents
5434 \endgroup
5435 \end{filecontentshere}
5436 \marginattach
5437
5438 A related command \csb{etocimmediatetoccontentsline} (and its starred version)
5439 is also provided. For discussion and the meaning of ``immediate'', refer to
5440 the analogous case of \csb{etocimmediatedepthtag.toc}.
5441
5442 \section{The TOC as a tree}\label{tocastree}
5443
5444 Using \ctanpkg{tikz} and the package \ctanpkg{forest} we shall display the
5445 table of contents of \autoref{part:styling} as a tree. The technique is to use
5446 the \etoc modified command \toc not for typesetting, but to prepare a macro,
5447 or rather here a \csa{toks} variable, with all the instructions to be executed
5448 later. \textsc{Leslie Lamport}'s book has no mention whatsoever of such token
5449 lists registers, and \LaTeX{} gives the impression to not really expect the
5450 general user to ever hear about them (or delimited macros); this whole section
5451 and the next are thus for advanced users.
5452
5453 Putting the \csb{etocnumber} and \csb{etocname} commands in \csa{treetok}
5454 would be of no use: to which number or name would they then refer to, in a
5455 delayed execution?
5456
5457 We need to store, not the macro names, but the macro contents. And also we wish
5458 to maintain the correct \ctanpkg{hyperref} hyperlinks.
5459 The
5460 commands \csb{etocname}, etc\dots, are robust, it is easier to work with
5461 \csb{etocthelinkednumber}, \csb{etocthelinkedname}, and \csb{etocthelinkedpage}
5462 which contain the same information in an easier accessible form.%
5463 %
5464 \normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
5465 At \etocrelease{1.1a} the commands \csa{etocthelinkedname}, etc\dots, are
5466 always providing an hyperlink, so it is not true that \csb{etocname}, etc\dots,
5467 are always simply their robust variants.}
5468
5469 For this |forest| tree we have designed very special \etoc styles for sections
5470 and subsections. They use a token list register called |\treetok| and a
5471 macro |\appendtotok| whose r\^ole is to append to a given token list variable
5472 the contents of a macro given as second argument. All this will happen in
5473 reaction to a |\tableofcontents| command, but \emph{nothing} has yet been
5474 printed in the process.\footnote{There is always a \csa{par}, which here is not
5475 a problem, but can be suppressed if need be via the command \csb{etocinline} or
5476 its synonym \csb{etocnopar}.} This is the later job of a |forest| environment
5477 which will be given the contents of |\treetok|.
5478
5479
5480
5481 \let\appendtotok\relax
5482
5483 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
5484 % \newtoks\treetok % put this (uncommented) preferably in the preamble
5485 % \newtoks\tmptok % (idem)
5486 \begingroup
5487 \newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
5488 #1\expandafter\expandafter\expandafter
5489 {\expandafter\the\expandafter #1#2}}
5490
5491 \newcommand*\PrepareSectionNode{%
5492 \tmptok {\centering\bfseries}%
5493 \appendtotok\tmptok\etocthelinkedname
5494 \edef\foresttreenode{ [{\noexpand\parbox{2cm}{\the\tmptok}}}%
5495 }
5496
5497 \newcommand*{\PrepareSubsectionNode}{%
5498 \tmptok {\raggedright}%
5499 \appendtotok\tmptok\etocthelinkedname
5500 \edef\foresttreenode{ [{\noexpand\parbox{6cm}{\the\tmptok}}}%
5501 }
5502
5503 \etocsetlinestyle{section}
5504 {\etocskipfirstprefix}
5505 {\appendtotok\treetok{ ]}}
5506 {\PrepareSectionNode \appendtotok\treetok\foresttreenode}
5507 {\appendtotok\treetok{ ]}}
5508
5509 \etocsetlinestyle{subsection}
5510 {\etocskipfirstprefix}
5511 {\appendtotok\treetok{ ]}}
5512 {\PrepareSubsectionNode \appendtotok\treetok\foresttreenode}
5513 {\appendtotok\treetok{ ]}}
5514
5515 \etocsettocstyle
5516 {\treetok{[{\hyperref[part:styling]{The \etoc styling commands}}}}
5517 {\global\appendtotok\treetok{ ]}}
5518
5519 % forest does not like @\the\treetok if \treetok is empty. On first latex
5520 % run, this will be the case because the TOC style defined above will not
5521 % have been executed, as the label {toc:overview} does not refer to a valid
5522 % TOC yet. So we must give a safe default value to \treetok
5523 \treetok{[{run latex again}]}
5524
5525 \begin{figure}[htbp!]
5526 \centering
5527 \etocsetnexttocdepth{subsection}
5528 \tableofcontents \label{toc:forest}\ref{toc:part:styling}
5529 \hypersetup{hidelinks}%
5530 \bracketset{action character=@}
5531 % manual adjustments to fit the printed page
5532 % \kern-1cm
5533 \noindent\kern-3cm
5534 \begin{forest}
5535 for tree={anchor=center,child anchor=west,
5536 grow'=east,draw,thick,
5537 edge={draw,thick,dashed,color=teal}},
5538 where={level()==1}{circle,thick,fill=blue!5,
5539 before computing xy={l=6cm}}{},
5540 where={level()==2}{fill=red!5,
5541 before computing xy={l=6cm}}{},
5542 rectangle, thick, fill=cyan!5, inner sep=6pt,
5543 @\the\treetok
5544 \end{forest}
5545 \end{figure}
5546 \endgroup
5547 \end{filecontentsdef}
5548 \filecontentsexec\foo
5549
5550 The resulting tree has been put in a \hyperref[toc:forest]{float}, which
5551 appears \vpageref[above]{toc:forest}. Here is the code used for its
5552 production: \filecontentsprintviascan\foo \marginattach
5553
5554 Why |\hypersetup{hidelinks}|? as explained in
5555 \autoref{ssec:hidelinks}, I prefer the links in TOCs not to be
5556 colorized, nor framed, so this document inserts a command
5557 %\csa{hypersetup}\texttt{\{hidelinks\}} % ok pour hyphénation
5558 %\csa{hypersetup}|{hidelinks}| % pas ok
5559 |\hypersetup{hidelinks}| % ok maintenant 12 octobre 2013
5560 in the |.toc| file. But at the time the
5561 |\treetok| contents are unpacked the |\hyperlink| commands
5562 originating in
5563 |\etocthelinkedname|, etc\dots{} will be executed in the normal
5564 environment for links (which, in this document, is to colorize
5565 them). Rather than having \etoc's code try to guess what the current ``style''
5566 for links is (a concept not really provided by \ctanpkg{hyperref} it
5567 seems) and store it in |\etocthelinkedname|, etc\dots, I opted for
5568 the simpler solution to leave it up to the user to recreate
5569 whatever conditions are desired. So here it is necessary to re-issue
5570 |\hypersetup{hidelinks}| in the |figure| environment.
5571
5572 There are some other examples in this documentation where
5573 |\tableofcontents| is used to prepare material for later
5574 typesetting:
5575 \begin{itemize}
5576 \item printing the statistics at the start of each Part (see
5577 \autoref{ssec:statistics}) is done using save boxes (so the problem of the
5578 appearance of the links does not arise then).
5579 \item typesetting of the TOC as a table without benefiting from
5580 \csb{etocglobaldefs} (see \autoref{ssec:tocastableold}).
5581 \item and the examples in the next section.
5582 \end{itemize}
5583
5584
5585 \section{The TOC as a molecule}\label{sec:molecule}
5586
5587 It is also possible to construct a TOC tree obeying the TikZ
5588 syntax for trees: but this is a more complicated task for the
5589 \etoc line styles for reasons related to the way braces are
5590 handled by \TeX{} (they need, when filling up the token list to be
5591 always balanced at each step, else complicated tricks must be
5592 employed.)
5593
5594 The simplest strategy is to allocate a token list (or use a macro) for each
5595 level used: we may need a \csa{parttok}, a \csa{chaptertok}, a
5596 \csa{sectiontok} and a \csa{subsectiontok}, to help in the task of filling
5597 up the total \csa{treetok}. As we are interested here in the table of
5598 contents of this (or another) document part, only a \csa{sectiontok} and a
5599 \csa{subsectiontok} will be needed.
5600
5601 \let\appendtotok\relax
5602 \let\treenode\relax
5603 \let\appendchildtree\relax
5604 \let\preparetreenode\relax
5605 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
5606 % To run this code you must have \usetikzlibrary{trees} in preamble
5607 % and as color SkyBlue is neeed you need xcolor with dvipsnames or svgnames
5608
5609 % \newtoks\treetok % put this (uncommented) preferably in the preamble
5610 % \newtoks\subsectiontok
5611 % \newtoks\subsubsectiontok
5612 % Attention: this code has been prepared only for subsections
5613 % and subsubsections.
5614
5615 \newcommand*{\treenode}{}% only to make sure our \edef's do not overwrite
5616 % an existing command
5617
5618 % expands 2nd argument (macro) and appends it to 1st argument (toks)
5619 \newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
5620 #1\expandafter\expandafter\expandafter
5621 {\expandafter\the\expandafter #1#2}}
5622
5623 % appends 2nd argument contents (toks) as child of first argument (toks)
5624 \newcommand*{\appendchildtree}[2]{% token list t1 becomes: t1 child {t2}
5625 \edef\tmp{\the#1 child {\the#2}}%
5626 #1\expandafter{\tmp}%
5627 }
5628
5629 % this one sets the node, it is the core macro where we actually
5630 % define the contents of all the nodes. We **must** expand
5631 % \etocthelinkednumber once. Commented-out is the old syntax.
5632 \newcommand*{\preparetreenode}{%
5633 % \tmptok\expandafter{\etocthelinkednumber}% expanded once (needed)
5634 % \edef\treenode{node {\the\tmptok}}%
5635 %
5636 \edef\treenode{node {\unexpanded\expandafter{\etocthelinkednumber}}}%
5637 }
5638
5639 % The main objective of these somewhat subtle constructs is to build up
5640 % the expected by TikZ input tree in its syntax
5641 \etocsetlinestyle{subsection}
5642 {\etocskipfirstprefix}
5643 {\appendchildtree\treetok\subsectiontok}
5644 {\preparetreenode
5645 \subsectiontok\expandafter{\treenode}}
5646 {\appendchildtree\treetok\subsectiontok}
5647
5648 \etocsetlinestyle{subsubsection}
5649 {\etocskipfirstprefix}
5650 {\appendchildtree\subsectiontok\subsubsectiontok}
5651 {\preparetreenode
5652 \subsubsectiontok\expandafter{\treenode}}
5653 {\appendchildtree\subsectiontok\subsubsectiontok}
5654
5655 % Finally here we have the core code to create and finish the \treetok
5656 % we need a global in the "after" code because there will be a grouping
5657 % created always by \tableofcontents
5658 \etocsettocstyle
5659 {\treetok{\node {\hyperref[sec:linestyles]{Line styles}}}}
5660 {\global\appendtotok\treetok{ ;}}
5661
5662 \centeredline{% from package centeredline
5663 % btw, the \centeredline creates a scope limiting group
5664 \etocsetnexttocdepth{subsubsection}%
5665 \etocinline% avoid issueing a \par
5666 \tableofcontents \label{toc:molecule} \ref{toc:tocstyle}%
5667 \hypersetup{hidelinks}%
5668 \begin{tikzpicture}
5669 [grow cyclic,
5670 level 1/.style={level distance=4cm,sibling angle=72},
5671 level 2/.style={level distance=2cm,sibling angle=60},
5672 every node/.style={ball color=red,circle,text=SkyBlue},
5673 edge from parent path={[dashed,very thick,color=cyan]
5674 (\tikzparentnode) --(\tikzchildnode)}]
5675 \the\treetok
5676 \end{tikzpicture}%
5677 }
5678 \end{filecontentshere}
5679 \marginattach
5680
5681 \filecontentsexec\filecontentsheremacro
5682
5683
5684
5685 The |\tableofcontents| command is executed prior to the |tikzpicture|
5686 environment which will actually typeset it via insertion of the accumulated
5687 data in the \csa{toks} register \csa{treetok}. This
5688 \hyperref[toc:molecule]{TikZ TOC} is fully hyperlinked, like the previous
5689 \hyperref[toc:forest]{Forest TOC}.
5690
5691 % Mercredi 01 mars 2023 à 23:27:29
5692 % arrrrrrgggghhh
5693 % desperate attempt to avoid an annoying varioref "may loop" error.
5694 % at last minute, arose from a suppression of a paragraph a few
5695 % dozen pages earlier.
5696 % [76]
5697
5698 % ! Package varioref Error: \vref or \vpageref at page boundary 65-66 (may loop).
5699
5700 % See the varioref package documentation for explanation.
5701 % Type H <return> for immediate help.
5702 % ...
5703 %
5704 % l.6114 appears \vpageref{toc:mindmap}
5705
5706 % mais ça n'a pas suffit. Bon 10 minutes de perdues je vais déplacer la ligne.
5707
5708 \enlargethispage{3\baselineskip}
5709 Another example:
5710
5711 \etocsettocstyle
5712 {\treetok{\node {\autoref{sec:tocstyle}}}}
5713 {\global\appendtotok\treetok{ ;}}
5714
5715 \etocsetnexttocdepth {subsubsection}
5716 \tableofcontents \ref{toc:tocstyle}
5717
5718 \centeredline{%
5719 \hypersetup{hidelinks}
5720 \begin{tikzpicture}
5721 [grow cyclic,
5722 level 1/.style={level distance=2.5cm,sibling angle=60},
5723 level 2/.style={level distance=1cm,sibling angle=45},
5724 every node/.style={ball color=red!50,circle,text=black},
5725 edge from parent path={[very thick,color=cyan]
5726 (\tikzparentnode) --(\tikzchildnode)}]
5727 \the\treetok
5728 \end{tikzpicture}
5729 }%
5730 %
5731 The above is the fully hyperlinked table of contents of
5732 \autoref{sec:tocstyle}.
5733
5734 \section{The TOC as a TikZ mind map}
5735 \label{sec:mindmap}
5736
5737 This is in the same spirit as the ``molecule'' example. The use of the \eTeX{}
5738 primitive \csa{unexpanded} will simplify the code.%
5739 %
5740
5741
5742 \let\partnode\relax
5743 \let\childnode\relax
5744 \let\appendtotok\relax
5745 \let\appendchildtree\relax
5746 \expandafter\let\csname c@partco\endcsname\relax
5747
5748 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
5749 % \newtoks\treetok % done in preamble
5750 % \newtoks\parttok
5751 \newcommand*\partnode {} % check with \newcommand we will not overwrite something
5752 \newcommand*\childnode {}
5753
5754 \newcommand*\tmprotate {} % (idem)
5755 \newcommand*\tmpoption {} %
5756 \newcommand*\tmpstuff {} %
5757
5758 \newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
5759 #1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}}
5760
5761 \newcommand*{\appendchildtree}[3]{%
5762 % this is to construct "t1 child [#3]{t2}" from #1=t1 and #2=t2
5763 % t1 and t2 are two toks variable (not macros)
5764 % #3 = for example teal!60
5765 \edef\tmpstuff {\the#1 child [#3]{\the#2}}%
5766 #1\expandafter {\tmpstuff }%
5767 }
5768
5769 \newcounter{partco}
5770
5771 % 1,2,3,4,5,... -> 1,2,3,1,2,3,1,2,3
5772 \def\pseudomodthree #1{\numexpr #1 + 3 - 3*((#1+1)/3)\relax}
5773
5774 \etocsetlinestyle{part}
5775 {\etocskipfirstprefix}
5776 % This updates the global tree with the data from the previous
5777 % part and all its children sections. Moved here because for some parts the
5778 % sections are not displayed due to depth tags.
5779 {\ifnum\value{partco}=3
5780 \appendchildtree\treetok\parttok {branch color= green!50,level distance=10cm}%
5781 \else
5782 \ifcase\pseudomodthree{\value{partco}}%
5783 \or \appendchildtree\treetok\parttok {branch color= teal!30}% first
5784 \or \appendchildtree\treetok\parttok {branch color= yellow!80}% second
5785 \else\appendchildtree\treetok\parttok {branch color= green!50}% third and next ...
5786 \fi\fi
5787 }
5788 {\stepcounter{partco}%
5789 % customize manually some TikZ set-up (should be done inside the TikZ thing I guess)
5790 \def\tmpoption {}%
5791 \def\tmprotate {}% first
5792 %\ifnum\value{partco}=5 \def\tmprotate {[counterclockwise from =-40]}\fi
5793 %\ifnum\value{partco}=8 \def\tmprotate {[counterclockwise from =-50]}\fi
5794 % define the part node
5795 \edef\partnode{node \tmpoption
5796 {\unexpanded\expandafter{\etocthelinkednumber}.
5797 \unexpanded\expandafter{\etocthelinkedname}}\tmprotate }%
5798 % this is a starting point which will be filled it by the section children
5799 \parttok\expandafter{\partnode}}
5800 {\ifcase\pseudomodthree{\value{partco}}%
5801 \or \appendchildtree\treetok\parttok {branch color= teal!60}% first
5802 \or \appendchildtree\treetok\parttok {branch color= yellow!80}% second
5803 \else\appendchildtree\treetok\parttok {branch color= green!50}% third and next ...
5804 \fi
5805 }
5806
5807 \etocsetlinestyle{section}
5808 {}
5809 {}
5810 {% define the section node
5811 \edef\childnode{child {node {\unexpanded\expandafter{\etocthelinkednumber}
5812 \unexpanded\expandafter{\etocthelinkedname}}}}%
5813 % append it to the current \parttok
5814 \appendtotok\parttok\childnode
5815 }
5816 {}
5817
5818 \etocsettocstyle
5819 {\setcounter{partco}{0}%
5820 \treetok{\node [root concept]{\textbf{The \etoc documentation}}}}
5821 {\global\appendtotok\treetok{ ;}}
5822 % The \global above is mandatory because etoc always typesets TOC inside a group
5823
5824 \etocsetnexttocdepth{section}
5825 % use of depth tags to cut out sections for most parts, the sections
5826 % are too numerous to fit well with the circular growth
5827 \etocsettagdepth {preamble} {part}
5828 \etocsettagdepth {overview} {part}
5829 \etocsettagdepth {styling} {part}
5830 \etocsettagdepth {control} {part}
5831 \etocsettagdepth {examples} {part}
5832 \etocsettagdepth {advanced} {part}
5833 \etocsettagdepth {etocandworld}{part}
5834 \etocsettagdepth {code} {section}
5835
5836 \tikzset{
5837 branch color/.style={
5838 concept color=#1!white,
5839 every child/.append style={concept color=#1!white!30!white, font=\normalsize},
5840 }
5841 }%
5842
5843 \begin{figure}[htbp!]
5844 \etocobeydepthtags % obey the depth tags restrictions (which is default anyhow)
5845 \tableofcontents\label{toc:mindmap}%
5846 \centeredline{\resizebox{.85\paperwidth}{!}%
5847 {\begin{tikzpicture}[mindmap,
5848 grow cyclic,
5849 text width=2cm,
5850 align=flush center,
5851 nodes={concept},
5852 concept color=orange!60,
5853 root concept/.append style={text width=4cm, font=\Large},
5854 level 1/.append style={level distance=5cm,sibling angle=45, text width=3cm},
5855 level 2/.append style={level distance=7cm,sibling angle=30, text width=3cm},
5856 level 1 concept/.append style={font=\normalsize},
5857 ]
5858 \the\treetok
5859 \end{tikzpicture}}}
5860 \end{figure}
5861 \end{filecontentsdef}
5862 \filecontentsexec\foo
5863
5864 It is difficult to get everything to fit on one page. However \csa{resizebox}
5865 comes to the rescue. And it preserves hyperlinks. Nevertheless for this
5866 example I excluded some sections from the display, using the technique of the
5867 \etoc \hyperref[etocdepthtag.toc]{depth tags}.
5868
5869 % The fully hyperlinked TOC
5870 % appears \vpageref{toc:mindmap}.
5871
5872 \filecontentsprintviascan\foo
5873 \marginattach
5874
5875 The fully hyperlinked TOC appears \vpageref{toc:mindmap}.
5876
5877 An interesting alternative is to use \etoc rather to convert the entire TOC
5878 into a TikZ tree (perhaps excluding some parts) and print it out to a file
5879 from which it can be recovered and manipulated directly by the author of the
5880 document. Things written to the |.log| file get broken into lines. Here is a
5881 technique to get non-broken output. Once the \csa{treetok} has been computed
5882 by \etoc (as in the \hyperref[toc:molecule]{molecule} example, or the current
5883 example), this demo will write it out to file with extension
5884 |.toctree|:
5885 \begin{verbatim}
5886 \newwrite\TOCasTree
5887 \immediate\openout\TOCasTree=\jobname.toctree
5888 \immediate\write\TOCasTree{\the\treetok}%
5889 \end{verbatim}
5890
5891
5892 \section{The TOC as a (long) table}
5893 \label{sec:tocastable}
5894
5895 % With release \etocrelease{1.08} it is easier to typeset a TOC as a table.
5896 It is possible to open a \texttt{tabular} (or \texttt{longtable}) in the title part of the TOC
5897 (first argument to \csb{etocsettocstyle}) and then close it after the contents
5898 (second argument to \csb{etocsettocstyle}), and specify in the line styles how
5899 to use the tabulation |&| and tabular end of row |\\|.
5900
5901 But there are some conditions and a few caveats:
5902 \begin{enumerate}
5903 \item it is \textbf{mandatory} to issue \csb{etocglobaldefs} for \etoc's
5904 definitions of \csb{etocname} et al. to have global scope, i.e. not be
5905 extinguished on encountering a |&|,
5906 \item it is impossible to start one of the \meta{start}, \meta{prefix},
5907 \meta{contents} or \meta{finish} specification with a sole |\hline|,
5908 \emph{i.e.} one not preceded by a |\\|,
5909 % (it is however possible to put
5910 % |\\| at the end of \meta{prefix} and the |\hline| at the start of
5911 % \meta{contents}).
5912 \item as is explained next, it is recommended to put the
5913 |\\| at the start of the \meta{prefix} or \meta{contents}
5914 specifications in order to close the \emph{previous} row, rather
5915 that at the end with the idea to close the \emph{current} row;
5916 and when the TOC is a partial one (a \csa{localtableofcontents}) this
5917 is (in almost all situations) mandatory.
5918 \end{enumerate}
5919
5920 Here is an example of a TOC as a |longtable|. Yes this is only \emph{one} table!
5921 The code follows.
5922
5923 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
5924 \begingroup
5925 \etocglobaldefs % necessary for \etocname etc... to survive &
5926 \makeatletter
5927 % hack into longtable \hline to avoid annoying (here) stray lines at top
5928 \def\LT@@hline{%
5929 \ifx\@let@token\hline
5930 \global\let\@gtempa\@gobble
5931 \global\let\@gtempb\@firstofone %%% ADDED
5932 \gdef\LT@sep{\penalty-\@medpenalty\vskip\doublerulesep}%
5933 \else
5934 \global\let\@gtempa\@empty
5935 \global\let\@gtempb\@gobble %%% ADDED
5936 \gdef\LT@sep{\penalty-\@lowpenalty\vskip-\arrayrulewidth}%
5937 \fi
5938 \ifnum0=`{\fi}%
5939 \multispan\LT@cols
5940 \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr
5941 \@gtempb{% %%% ADDED
5942 \noalign{\LT@sep}%
5943 \multispan\LT@cols
5944 \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr
5945 \noalign{\penalty\@M}%
5946 }% %%% ADDED
5947 \@gtempa}
5948 \makeatother
5949
5950 % observe the locations of the \\
5951 \etocsetlinestyle{part}
5952 {}
5953 {}
5954 {\\\hline\multicolumn{3}{c}{\bfseries\vrule height6ex depth3ex width0pt
5955 \makebox[0pt]{\etocifnumbered{\etocnumber. }{}\etocname}}}
5956 {}
5957
5958 \etocsetlinestyle{section}
5959 {}
5960 {\etociffirst{\\\hline}{\\}}
5961 {\etocnumber&\etocname &\etocpage }
5962 {}
5963
5964 \etocsetlinestyle{subsection}
5965 {}
5966 {\\}
5967 {&\makebox[1cm][c]{\etocnumber}%
5968 \parbox[t]{\dimexpr6cm-\tabcolsep\relax}{\sloppy\itshape\etocname\strut}%
5969 &\itshape\etocpage }
5970 {}
5971
5972 \etocsettocstyle
5973 {\hypersetup{hidelinks}%
5974 \begin{longtable}{|>{\bfseries}c|p{7cm}|r|}
5975 \hline
5976 \multicolumn{3}{|c|}{\Large\bfseries\strut\strut TABLE OF CONTENTS}%
5977 }
5978 {\\\hline\end{longtable}}
5979
5980 \etocsetnexttocdepth {subsection}
5981
5982 \tableofcontents
5983 \endgroup
5984 \end{filecontentsdef}
5985
5986 \filecontentsexec\foo
5987
5988 \filecontentsprintviascan\foo
5989 \marginattach
5990
5991 Examining the code above the reader will wonder why the |\\| are
5992 always given first in \meta{prefix+contents} and not, as is more
5993 intuitive, rather last. In some favorable cases (but almost never
5994 for local tables of contents) one may indeed construct
5995 TOC-as-tables with the |\\| located at the end of the style
5996 specifications. The problem in the previous example was with the
5997 positioning of the |\hline|'s.
5998
5999 Due to technical aspects of how \TeX{} constructs alignments any
6000 definition or assignment done after an |\\| starts a new row, and
6001 thus makes |\hline| an illegal token (this shows as a |misplaced
6002 \noalign| error.) Not only does \etoc have to do such definitions
6003 to construct \csb{etocname} etc..., it is furthermore the case that
6004 some packages put things in the |.toc| file and as a result there
6005 is never any guarantee that between two \csa{contentsline} there
6006 will not be such a token like |\relax| which in the contexts of
6007 alignments forces \TeX{} to start a cell and thus makes it
6008 impossible then to insert an |\hline|.
6009
6010 The safest way is thus to start with an |\\| each line style
6011 specification in order to close the \emph{previous} table row. We
6012 had a little problem with the fact that we wanted parts not only
6013 to have a rule above them (easy, they do |\\\hline|) but also
6014 below them: after each part there is a section, and it is these
6015 sections which are used to insert the missing |\hline|
6016 (this is done with the help of the \csb{etociffirst}
6017 conditional).
6018
6019
6020 Last technical note: because we put the |\\\hline| inside the branches, there
6021 was no need to employ the expandable variants \csb{etocxiffirst} and
6022 \csb{etocxifnumbered}.
6023
6024 For the hardliner's old way see \autoref{ssec:tocastableold}.
6025
6026 Here is also a much simpler example. It is a local table of
6027 contents.
6028
6029 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
6030 \begin{center}
6031 \etocsetlinestyle{section}
6032 {}
6033 {\etociffirst{\\\hline\hline}{\\\hline}}
6034 {\etocname & \etocnumber & \etocpage }
6035 {}
6036
6037 \etocsettocstyle
6038 {\hypersetup{hidelinks}\begin{tabular}{|>{\RaggedRight}p{4.5cm}|c|c|}\hline
6039 \multicolumn{1}{|c|}{\bfseries Section title}&
6040 \bfseries number&
6041 \bfseries page}
6042 {\\\hline\end{tabular}}
6043
6044 \etocglobaldefs % MANDATORY !!
6045 \etocsetnexttocdepth{1}
6046
6047 \tableofcontents\ref{toc:overview}
6048 \end{center}
6049 \end{filecontentsdef}
6050
6051 \filecontentsexec\foo
6052
6053 \filecontentsprintviascan\foo
6054 \marginattach
6055
6056 \section{A TOC self-adjusting widths for its typesetting}
6057 \label{sec:thirdexampleextra}
6058
6059 This is a continuation of \autoref{sec:thirdexample}. The goal is to adjust
6060 automatically the ``numwidths'' used for typesetting the unit numbers in the
6061 (local) tables of contents.
6062 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
6063 \makeatletter
6064 \newcommand*\TOCcompute@numwidths [2]{% #1=empty/"local", #2=minimal indent
6065 \begingroup
6066 \def\TOCnumwidthB {0pt}%
6067 \def\TOCnumwidthC {0pt}%
6068 \def\TOCnumwidthD {0pt}%
6069 \def\TOCnumwidthE {0pt}%
6070 \def\TOCnumwidthF {0pt}%
6071 \def\TOCnumwidthG {0pt}%
6072 \etocsetlinestyle{part}{}{}{}{}%
6073 \etocsetlinestyle{chapter}{}
6074 {\setbox0\hbox{\bfseries\etocthenumber\kern#2}}
6075 {\ifdim\wd0>\TOCnumwidthB\edef\TOCnumwidthB{\the\wd0}\fi}{}%
6076 \etocsetlinestyle{section}{}
6077 {\setbox0\hbox{\bfseries\etocthenumber\kern#2}}
6078 {\ifdim\wd0>\TOCnumwidthC\edef\TOCnumwidthC{\the\wd0}\fi}{}%
6079 \etocsetlinestyle{subsection}{}
6080 {\setbox0\hbox{\etocthenumber\kern#2}}
6081 {\ifdim\wd0>\TOCnumwidthD\edef\TOCnumwidthD{\the\wd0}\fi}{}%
6082 \etocsetlinestyle{subsubsection}{}
6083 {\setbox0\hbox{\etocthenumber\kern#2}}
6084 {\ifdim\wd0>\TOCnumwidthE\edef\TOCnumwidthE{\the\wd0}\fi}{}%
6085 \etocsetlinestyle{paragraph}{}
6086 {\setbox0\hbox{\etocthenumber\kern#2}}
6087 {\ifdim\wd0>\TOCnumwidthF\edef\TOCnumwidthF{\the\wd0}\fi}{}%
6088 \etocsetlinestyle{subparagraph}{}
6089 {\setbox0\hbox{\etocthenumber\kern#2}}
6090 {\ifdim\wd0>\TOCnumwidthG\edef\TOCnumwidthG{\the\wd0}\fi}{}%
6091 %
6092 \etocsettocstyle
6093 {}
6094 {\global\let\TOCnumwidthB\TOCnumwidthB
6095 \global\let\TOCnumwidthC\TOCnumwidthC
6096 \global\let\TOCnumwidthD\TOCnumwidthD
6097 \global\let\TOCnumwidthE\TOCnumwidthE
6098 \global\let\TOCnumwidthF\TOCnumwidthF
6099 \global\let\TOCnumwidthG\TOCnumwidthG
6100 }% make the found maximal widths have global scope
6101 \etocnopar
6102 \csname #1tableofcontents\endcsname
6103 \typeout{Next TOCs will use \TOCnumwidthB\space for chapter number width}%
6104 \typeout{Next TOCs will use \TOCnumwidthC\space for section number width}%
6105 \typeout{Next TOCs will use \TOCnumwidthD\space for subsection number width}%
6106 \typeout{Next TOCs will use \TOCnumwidthE\space for subsubsection number width}%
6107 \typeout{Next TOCs will use \TOCnumwidthF\space for paragraph number width}%
6108 \typeout{Next TOCs will use \TOCnumwidthG\space for subparagraph number width}%
6109 \endgroup % matches \begingroup at start of definition
6110 }%
6111 \newcommand*\TOCcomputenumwidths [1][0.5em]{%
6112 \TOCcompute@numwidths {}{#1}%
6113 }%
6114 \newcommand*\TOCcomputelocalnumwidths [1][0.5em]{%
6115 \TOCcompute@numwidths {local}{#1}%
6116 }%
6117 \makeatother
6118 \end{filecontentshere}
6119 \marginattach
6120
6121 The optional parameter to \csa{TOCcomputenumwidths} specifies the minimal
6122 indent. In case nothing is numbered you may wish a higher value than |0.5em|.
6123 For each local table of contents to have its own width computations, the macro
6124 \csa{TOCcomputelocalnumwidths} is provided. As the code makes global
6125 assignments, either use (once) \csa{TOCcomputenumwidths} or do
6126 \csa{TOCcomputelocalnumwidths} for each local table of contents.
6127 \begin{verbatim}
6128 \TOCcomputelocalnumwidths % may use optional argument to replace 0.5em
6129 \localtableofcontents
6130 \end{verbatim}
6131 Notes:
6132 \begin{enumerate}[nosep]
6133 \item naturally these are only suggestions. For example one could put
6134 everything in single macros \csa{TOCtoc} and \csa{TOClocaltoc} to
6135 simultaneously compute the numwidths and then typeset the (local) table of
6136 contents.
6137 \item if you want to adjust the |tocdepth| recall from
6138 \autoref{ssec:bookmarksdepth} that it influences \ctanpkg{hyperref} hence you may
6139 need to use a group |\begingroup...\endgroup|. Or, one can use
6140 \csb{etocsetnexttocdepth}\marg{level} but (with the code as here) this must
6141 then be issued twice, once for \csa{TOCcomputelocalnumwidths}, once for
6142 \csa{localtableofcontents}.
6143 \item the bold font serves above for both chapter and section numwidth
6144 computations, but the code from \autoref{sec:thirdexample} uses |\bfseries|
6145 only in local TOCs. Thus the \csa{TOCcomputenumwidth} will set the parameter
6146 \csa{TOCnumwidthC} to a value slightly larger than needed in the main TOC.
6147 Hence the section style in \csa{TOCcompute@numwidths} should possibly insert
6148 the |\bfseries| in the box only after testing for the optional parameter
6149 |local|.
6150 \end{enumerate}
6151
6152
6153
6154 \section{Interverting the levels}
6155 \label{subsec:interverting}
6156
6157 Let us display and count all subsections occurring in this
6158 document (see \autoref{part:surprising} for other uses of
6159 this technique):
6160 \begin{verbatim}
6161 \etocsetnexttocdepth{2}
6162 \begingroup
6163 \etocsetlevel{part}{3}
6164 \etocsetlevel{section}{3}
6165 \etocsetlinestyle{subsection}
6166 {\small\begin{enumerate}[itemsep=0pt,label=,leftmargin=0pt]}
6167 {\normalfont\bfseries\item}
6168 {\roman{enumi}. \mdseries\etocname{} (\etocnumber, p.~\etocpage)}
6169 {\end{enumerate}}
6170 \renewcommand{\etoccolumnsep}{2.75em}
6171 \renewcommand{\columnseprule}{1pt}
6172 \etocmulticol[3]{\subsection{All subsections of this document}}
6173 \endgroup
6174 \end{verbatim}
6175
6176 \etocsetnexttocdepth{2}
6177
6178 \begingroup
6179 \etocfallbacklines
6180 \etocclasstocstyle
6181 \etocsetlevel{book}{3}
6182 \etocsetlevel{part}{3}
6183 \etocsetlevel{chapter}{3}
6184 \etocsetlevel{section}{3}
6185 \etocsetlinestyle{subsection}{\small
6186 \begin{enumerate}[itemsep=0pt,label=,leftmargin=0pt]}
6187 {\normalfont\bfseries\item}
6188 {\roman{enumi}. \mdseries\etocname{} (\etocnumber, p.~\etocpage)}
6189 {\end{enumerate}}
6190
6191 \renewcommand{\etoccolumnsep}{2.75em}
6192 \renewcommand{\columnseprule}{1pt}
6193
6194 %%\etocmarkbothnouc{List of all subsections}
6195 %% le mark (\markright) est fait par \subsection
6196
6197 \etocmulticol[3]{\subsection{All subsections of this document}\label{toc:allsubsections}}
6198
6199 \endgroup
6200
6201 \section{Displaying statistics}\label{ssec:statistics}
6202
6203 Each part of this document starts with a paragraph telling how many
6204 sections and subsections it has. Well, each one of this paragraph is a
6205 table of contents! We designed a macro \csa{thispartstats} to do that.
6206 It uses ``storage'' boxes to keep the information about the first and
6207 last section or subsection. Using boxes is the simplest manner to
6208 encapsulate the \ctanpkg{hyperref} link for later use (whether there is one or
6209 none). However, one cannot modify then the font or the color.
6210 % (using the
6211 % \TeX{} primitive \csa{setbox} rather than the \LaTeX{} \csa{sbox} would
6212 % allow to change the color of the un-boxed saved box)
6213 If such a need
6214 arises, one must switch from using boxes to using macros, and store the
6215 \ctanpkg{hyperref} data for later use as was done in the code presented in
6216 \autoref{sec:molecule}. We present also this second method.
6217
6218 But first, the code of \csa{thispartstats}:\par
6219 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
6220 \newsavebox\firstnamei \newsavebox\firstnumberi
6221 \newsavebox\lastnamei \newsavebox\lastnumberi
6222 \newsavebox\firstnameii \newsavebox\firstnumberii
6223 \newsavebox\lastnameii \newsavebox\lastnumberii
6224 \newcounter{mycounti} \newcounter{mycountii}
6225 \newcommand*{\thispartstatsauxi}{} \newcommand*{\thispartstatsauxii}{}
6226 \newcommand*{\oldtocdepth}{}
6227 \newcommand*{\thispartstats}{%
6228 \setcounter{mycounti}{0}%
6229 \setcounter{mycountii}{0}%
6230 \def\thispartstatsauxi{%
6231 \sbox{\firstnamei}{\footnotesize\etocname}%
6232 \sbox{\firstnumberi}{\footnotesize\etocnumber}%
6233 \def\thispartstatsauxi{}}%
6234 \def\thispartstatsauxii{%
6235 \sbox{\firstnameii}{\footnotesize\etocname}%
6236 \sbox{\firstnumberii}{\footnotesize\etocnumber}%
6237 \def\thispartstatsauxii{}}%
6238 \begingroup
6239 \etocsetlinestyle{subsection} {} {}
6240 {\thispartstatsauxii
6241 \stepcounter{mycountii}%
6242 \sbox{\lastnameii}{\footnotesize\etocname}%
6243 \sbox{\lastnumberii}{\footnotesize\etocnumber}} {}%
6244 \etocsetlinestyle{section} {} {}
6245 {\thispartstatsauxi
6246 \stepcounter{mycounti}%
6247 \sbox{\lastnamei}{\footnotesize\etocname}%
6248 \sbox{\lastnumberi}{\footnotesize\etocnumber}}
6249 {{\footnotesize\itshape
6250 Here are some statistics for this part: it contains \arabic{mycounti}
6251 section\ifnum\value{mycounti}>1 s\fi{} and \arabic{mycountii}
6252 subsection\ifnum\value{mycountii}>1 s\fi. The name of the first section is
6253 \unhbox\firstnamei{} and the corresponding number is \unhbox\firstnumberi.
6254 The name of the last section is \unhbox\lastnamei{} and its number is
6255 \unhbox\lastnumberi. The name of the first subsection is \unhbox\firstnameii{}
6256 and the corresponding number is \unhbox\firstnumberii. The name of the last
6257 subsection is \unhbox\lastnameii{} and its number is \unhbox\lastnumberii.\par}}%
6258 \etocinline % cancels the automatic \par automatically before the TOC
6259 \etocsettocstyle {}{}
6260 \etocsetnexttocdepth{2}%
6261 \localtableofcontents % to be used at the top level of a Part.
6262 \endgroup
6263 }
6264 \end{filecontentshere}
6265 \marginattach
6266
6267 And now, the variant with macros rather than boxes (this variant as it
6268 stands here is for using within a section).
6269 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
6270 \makeatletter
6271 \newcommand*\firstsubname {} \newcommand*\lastsubname {}
6272 \newcommand*\firstsubnumber {} \newcommand*\lastsubnumber {}
6273 \newcommand*\thisspecialstatsaux{}
6274 \newcommand*{\thisspecialstats}{%
6275 \setcounter{mycounti}{0}%
6276 \def\thisspecialstatsaux{%
6277 \let\firstsubname\etocthelinkedname
6278 \let\firstsubnumber\etocthelinkednumber
6279 \def\thisspecialstatsaux{}}
6280 \begingroup
6281 \etocsetlinestyle{subsection} {} {}
6282 {\thisspecialstatsaux
6283 \stepcounter{mycounti}%
6284 \let\lastsubname\etocthelinkedname
6285 \let\lastsubnumber\etocthelinkednumber }
6286 {Here are some statistics for this section. It contains \arabic{mycounti}
6287 subsections. The name of its first is \emph{\firstsubname{}} and the
6288 corresponding number is {\firstsubnumber}. The name of the last
6289 subsection is \emph{\lastsubname{}} and its number is {\lastsubnumber}.}%
6290 \etocsettocstyle {}{}
6291 \etocinline
6292 \etocsetnexttocdepth {1}%
6293 \localtableofcontents % to be used within a section
6294 \endgroup
6295 }
6296 \makeatother
6297 \end{filecontentshere}
6298 \marginattach
6299
6300 \section{Using depth tags}
6301 \label{sec:tocwithdepthtags}
6302
6303 \etoc provides via the concept of \emph{depth tags} the possibility to decide
6304 that, for example, a table of contents will display sections and subsections
6305 in a given chapter or part, but only sections, or nothing at all, for the
6306 other chapters (or parts) included in the given table of contents. You will
6307 find more explanations at \autoref{sec:depthtags}
6308
6309 For this the user adds to the source usage in the document body of
6310 \csb{etocdepthtag.toc} commands, located right before the |\part|, or
6311 |\chapter|, or whatever division headings whose control is desired, for
6312 example
6313 %
6314 \centeredline{|\etocdepthtag.toc{specialchapter}|}
6315 %
6316 and then when using
6317 \toc or \localtoc, user will add some command such as
6318 %
6319 \centeredline{|\etocsettagdepth{specialchapter}{section}|}
6320 %
6321 which will have the effect that only sections but no subsections of that
6322 chapter get displayed in that (possibly local, here to a Part) table of
6323 contents. Actually, one also has to add a depth tag at end of the desired
6324 scope of first one, something such as
6325 %
6326 \centeredline{|\etocdepthtag.toc{endofspecialchapter}|}
6327 %
6328 and one will then issue
6329 %
6330 \centeredline{|\etocsettagdepth{endofspecialchapter}{all}|}
6331 %
6332 to left further chapters again include in the so-configured table of contents
6333 all of their sub-units (as limited by current |tocdepth|). The simplest way
6334 thus is, if one decides to add a depth tag for one part or chapter to also add
6335 depth tags to all other parts, respectively chapters, and configure them
6336 appropriately.
6337
6338 Think of this as a way to add \emph{inside} the |.toc| file some changes to
6339 the |tocdepth| counter, except that those changes are dynamically
6340 configurable, and also the whole thing can be ignored if
6341 \csb{etocignoredepthtags} is used.
6342
6343 As an example, one can imagine a document with various Parts, each part
6344 displaying a table of contents of the \emph{complete} document, but which
6345 shows regarding other parts only their title and no finer division, whereas
6346 for the Part where it is located it will show all levels allowed by
6347 |tocdepth|. This is a variant of a ``local'' table of contents, which does
6348 display things external to the Part where it is located, but in a more limited
6349 way than regarding that Part itself.
6350
6351 The commands \csb{etocobeydepthtags} (which is default behavior) and
6352 \csb{etocignoredepthtags} can be used to control which TOC obey depth tags.
6353 If generally they should not, issue once \csb{etocignoredepthtags} in
6354 preamble, and then use \csb{etocobeydepthtags} for specific TOCs, either
6355 inside a scope-limiting group, or re-issue \csb{etocignoredepthtags} after
6356 each such (local or not) table of contents.
6357
6358 Here is a demonstration using the contents of this documentation. We want a
6359 TOC which will have a heading for each |\part|, with two Parts being handle
6360 especially: the \autoref{part:control} will show all its divisions down to
6361 subsubsection (if present) and the \autoref{part:code} will even show
6362 paragraphs (turns out that this document used there some |\paragraph|
6363 mark-up). To achieve this we added various
6364 \csb{etocdepthtag.toc} commands inside the source of this document prior to
6365 each |\part| command. It only remains now to set appropriately the depth of
6366 each such depth tag, which will be done like this:
6367 \begin{verbatim}
6368 \etocsettagdepth {preamble} {part}
6369 \etocsettagdepth {overview} {part}
6370 \etocsettagdepth {styling} {part}
6371 \etocsettagdepth {control} {subsubsection}
6372 \etocsettagdepth {examples} {part}
6373 \etocsettagdepth {advanced} {part}
6374 \etocsettagdepth {etocandworld}{part}
6375 \etocsettagdepth {code} {paragraph}
6376 \end{verbatim}
6377
6378 As said, we want here to display even paragraph entries in a specific part.
6379 The standard document class paragraph TOC line styles give too much vertical
6380 spacing in this context. So we cook up our own, quickly designed, line
6381 styles, a bit like what we did for \autoref{sec:firstexample}, but with a way
6382 (see the command |\EndParWithPageNumberInMarginAndLeaders|) to put page
6383 numbers on the right which is more like the method used by \LaTeX2e's
6384 |\@dottedtocline|; headings occupying more than one line will now wrap in a
6385 way achieving some hanging indentation relative to the entry number (but there
6386 is no such long heading in this example).
6387
6388 \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
6389 \etocsetnexttocdepth {all}
6390 \begingroup
6391 \parindent 0pt \leftskip 0cm \rightskip .75cm \parfillskip -\rightskip
6392 \newcommand*{\EndParWithPageNumberInMargin}
6393 {\nobreak\hfill
6394 % I initially added \etocnoprotrusion after \etocpage, but
6395 % finally switched to using monospace font for page number,
6396 % and it seems to have deactivated the protrusion anyhow.
6397 \makebox[0.75cm][r]{\mdseries\normalsize\ttfamily\etocpage}%
6398 \par}
6399 \renewcommand*\etoctoclineleaders
6400 {\hbox{\normalfont\normalsize\hbox to .75ex {\hss.\hss}}}
6401 \newcommand*{\EndParWithPageNumberInMarginAndLeaders}
6402 {\nobreak\leaders\etoctoclineleaders\hfill
6403 \makebox[0.75cm][r]{\mdseries\normalsize\ttfamily\etocpage}%
6404 \par }
6405 \etocsetlinestyle {part}
6406 {}
6407 {\leavevmode\leftskip 1cm\relax}
6408 {\bfseries\large\llap{\makebox[1cm][r]{\etocnumber\ \ }}%
6409 \etocname\EndParWithPageNumberInMargin\smallskip}
6410 {}
6411 \etocsetlinestyle {section}
6412 {}
6413 {\leavevmode\leftskip 1.75cm\relax}
6414 {\bfseries\normalsize\llap{\makebox[.75cm][l]{\etocnumber}}%
6415 \etocname\EndParWithPageNumberInMarginAndLeaders}
6416 {}
6417 \etocsetlinestyle {subsection}
6418 {}
6419 {\leavevmode\leftskip 2.75cm\relax }
6420 {\mdseries\normalsize\llap{\makebox[1cm][l]{\etocnumber}}%
6421 \etocname\EndParWithPageNumberInMarginAndLeaders}
6422 {}
6423 \etocsetlinestyle {subsubsection}
6424 {}
6425 {\leavevmode\leftskip 4cm\relax }
6426 {\mdseries\normalsize\llap{\makebox[1.25cm][l]{\etocnumber}}%
6427 \etocname\EndParWithPageNumberInMarginAndLeaders}
6428 {}
6429 \etocsetlinestyle {paragraph}
6430 {}
6431 {\leavevmode\leftskip 5.5cm\relax }
6432 {\mdseries\normalsize\llap{\makebox[1.5cm][l]{\etocnumber}}%
6433 \etocname\EndParWithPageNumberInMarginAndLeaders}
6434 {}
6435 \etocsettagdepth {preamble} {part}
6436 \etocsettagdepth {overview} {part}
6437 \etocsettagdepth {styling} {part}
6438 \etocsettagdepth {control} {subsubsection}
6439 \etocsettagdepth {examples} {part}
6440 \etocsettagdepth {advanced} {part}
6441 \etocsettagdepth {etocandworld}{part}
6442 \etocsettagdepth {code} {paragraph}
6443 \renewcommand\etoctoprule {\hrule height 3pt\relax }
6444 \renewcommand\etoctoprulecolorcmd {\color{blue}}
6445 \renewcommand\etocaftercontentshook
6446 {\medskip\begingroup \color{blue}\hrule height 3pt \endgroup }
6447 \etocruledstyle [1]{\Large\bfseries
6448 \fbox{\makebox[8cm]{A TOC using depth tags}}}
6449 \sloppy
6450 \etocobeydepthtags % let's not forget to activate this (default anyhow)
6451 \tableofcontents
6452 \endgroup
6453 \end{filecontentsdef}
6454
6455 \filecontentsexec\foo
6456
6457 \filecontentsprintviascan\foo
6458 \marginattach
6459
6460 \section{Sections styling subsections}
6461 \label{sec:anothercompatadvanced}
6462
6463 Here is a subtler example where one only marginally modifies the sections
6464 (adding color to the number, removing the \ctanpkg{hyperref} link, changing
6465 the color for one specific section) but let them decide almost one by one
6466 of the style which will be followed by their subsections. Furthermore one
6467 configures some sections to decide they will not display subsections at all or
6468 only count how many there are!
6469
6470 % modified for 1.2 doc to make the argument optional and update number
6471 % of exceptional section
6472
6473 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
6474 \makeatletter
6475 \newcommand*{\MyQuasiStandardTOC}[2][]{%
6476 % #1 is an optional "\ref{somelabeltoanothertoc}"
6477 % #2 is the number of some exceptional section
6478 \begingroup
6479 \etocsetlinestyle{section}
6480 {}
6481 {\etociffirst{% Suppress display of subsections for the first section!
6482 \etocsetlevel{subsection}{\etocthemaxlevel}}
6483 {\etocsetlevel{subsection}{2}}%
6484 \ifnum\etocthenumber=#2 % Handle especially section number #2 !
6485 \etocsetlinestyle{subsection}
6486 {\def\foo{}\par\nopagebreak\begingroup
6487 \leftskip2em \rightskip\@tocrmarg
6488 \parfillskip \@flushglue
6489 \parindent 0pt
6490 \normalfont\normalsize\rmfamily\itshape
6491 \etocskipfirstprefix}
6492 {\allowbreak\,--\,}
6493 {\edef\foo{\the\numexpr\foo+1}\etocname\ \textup{(\etocnumber)}}
6494 {.\par \upshape My AI counted circa \foo\space subsections,
6495 was it right?\par\endgroup}%
6496 \else
6497 \ifnum\etocthenumber>#2 % Only count subsections in those sections !
6498 \etocsetlinestyle{subsection}
6499 {\def\foo{}}%
6500 {\edef\foo{\the\numexpr\foo+1}}%
6501 {}%
6502 {\leftskip2em \emph{There are \foo\space subsections here,
6503 but I will need payment to display them.}\par}%
6504 \else
6505 \etocsetlinestyle{subsection}
6506 {}%
6507 {}%
6508 {\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}%
6509 {}%
6510 \fi
6511 \fi
6512 }%
6513 {% Display in a special color the number of the special section!
6514 \l@section{\numberline{{\ifnum\etocthenumber=#2
6515 \color{red}\else\color{cyan}\fi\etocthenumber}}%
6516 \etociffirst{\etocname\space (SUBSECTIONS SKIPPED)}{\etocname}}
6517 {\etocpage}}%
6518 {}%
6519 \etocclasstocstyle % will use the ambient document class
6520 % special KOMA-script customization as this document uses scrartcl
6521 % and we need to enlarge numwidth for some subsections
6522 \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
6523 \DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection}
6524 \etocsetnexttocdepth {subsection}%
6525 \tableofcontents #1
6526 \endgroup
6527 }
6528 \makeatother
6529 \end{filecontentshere}
6530
6531 \marginattach
6532 \filecontentsexec\filecontentsheremacro
6533
6534 The optional argument stands for a suitable |\ref|, see \autoref{sec:labeling}.
6535 Here is what
6536 \begin{verbatim}
6537 \MyQuasiStandardTOC[\ref{toc:part:styling}]{11}% treat especially section 11
6538 \end{verbatim}
6539 gives:
6540 \MyQuasiStandardTOC[\ref{toc:part:styling}]{11}%
6541
6542 \vskip.5\baselineskip
6543
6544 The page heading (on the page where this TOC appears) may have been modified
6545 as is expected from usage of \csb{etocclasstocstyle} in the code.
6546
6547 Sections are printed exactly as in the default, \emph{except} that a special
6548 section number is displayed especially and that its subsections are then
6549 displayed inline! And other sections may only count subsections or
6550 ignore them altogether!
6551
6552 Note: for this code to work the macro \csa{thesection} \emph{must} not have
6553 been modified from its default which produces simply arabic digits. In other
6554 terms it must be usable as \TeX{} number denotation. Typically this would
6555 fail if we were handling subsections as their number in the |.toc| file will
6556 be typically something like |3.7| which does not work in a \TeX{} integer-only
6557 context. But it is possible to use a counter and configure the line styles to
6558 increment it, and use its value.
6559
6560
6561
6562 \section{The TOC as a (long) table (alternative)}
6563 \label{ssec:tocastableold}
6564
6565 Due to, among other things, the fact that alignment cells create and close
6566 groups, and that by default definitions of \csb{etocname}, \csb{etocnumber},
6567 \csb{etocpage} made by \etoc are local, it was not easy to typeset a TOC as
6568 table with \etoc, prior to release to the addition of \csb{etocglobaldefs} at
6569 \etocrelease{1.08}.
6570
6571 Not only \csb{etocname} etc... caused a problem, but also the basic
6572 redefinition of \csa{contentsline} was made by \etoc only after the
6573 first argument to \csb{etocsettocstyle} had been executed, hence if this
6574 argument were to open a tabular, the \etoc redefinition of
6575 \csa{contentsline} would be done in the first cell of the first row and
6576 get lost thereafter.
6577
6578 Thus one had to resort to the technique explained in \autoref{tocastree}
6579 of using the execution of \csa{tableofcontents} as a way to store data
6580 which was then displayed later.
6581
6582 For the record, here is how the TOC from \autoref{sec:tocastable} was
6583 coded in the old days.%
6584 %
6585 \footnote{At release \etocrelease{1.09f} the design anb contents of the TOC
6586 from \autoref{sec:tocastable} were modified; the code here, if executed,
6587 which will not, reproduces the
6588 former looks.}
6589 %
6590 We don't have here the problems with the
6591 positioning of |\hline|'s we face with the newer method; on the other
6592 hand we must manipulate token registers which are not familiar to most
6593 \LaTeX{} users (macros could be used, but would be more cumbersome,
6594 except perhaps if using the \eTeX{} \csa{unexpanded}).
6595
6596 The method here is the most powerful because it filters out of the
6597 |.toc| file only the data we want (the other things are not ignored,
6598 they are executed but hopefully do not create havoc; typically they are
6599 language changing instructions, etc...),
6600 and we are less susceptible to fall potential victims of various
6601 external macros inserted in the |.toc| file by other packages.
6602
6603 Note: rather than |\toks| registers it would be easier here to use \eTeX{}
6604 \csa{unexpanded} primitive. See for example \autoref{sec:mindmap}.
6605
6606 \let\appendtotok\relax
6607 \let\PreparePart\relax
6608 \let\PrepareSection\relax
6609 \let\PrepareSubsection\relax
6610 \begin{filecontentshere}{etocsnippet-\snippetno.tex}
6611 \newtoks\toctabletok
6612 \newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
6613 #1\expandafter\expandafter\expandafter {\expandafter\the\expandafter #1#2}}
6614
6615 \newcommand*\PreparePart{%
6616 \toks0 \expandafter{\etocthelinkednumber}%
6617 \toks2 \expandafter{\etocthelinkedname}%
6618 \toks4 \expandafter{\etocthelinkedpage}%
6619 \edef\toctablepiece {\noexpand\hline
6620 \noexpand\strut\the\toks0 &\noexpand\bfseries\the\toks2
6621 &\the\toks4 \noexpand\\\noexpand\hline}%
6622 }
6623 \newcommand*\PrepareSection{%
6624 \toks0 \expandafter{\etocthelinkednumber}%
6625 \toks2 \expandafter{\etocthelinkedname}%
6626 \toks4 \expandafter{\etocthelinkedpage}%
6627 \edef\toctablepiece {\the\toks0 &\the\toks2 &\the\toks4 \noexpand\\}%
6628 }
6629 %
6630 \newcommand*{\PrepareSubsection}{%
6631 \toks0 \expandafter{\etocthelinkednumber}%
6632 \toks2 \expandafter{\expandafter\itshape\etocthelinkedname\strut}%
6633 \toks4 \expandafter{\expandafter\itshape\etocthelinkedpage}%
6634 \edef\toctablepiece{&\noexpand\makebox[1cm][c]{\the\toks0}%
6635 \noexpand\parbox[t]{\dimexpr6cm-\tabcolsep\relax}
6636 {\noexpand\sloppy\the\toks2}%
6637 &\the\toks4 \noexpand\\}%
6638 }
6639
6640 \begingroup
6641 \etocsetlinestyle{part}{}{}{\PreparePart \appendtotok\toctabletok\toctablepiece}{}
6642
6643 \etocsetlinestyle{section}{}{}{\PrepareSection \appendtotok\toctabletok\toctablepiece}{}
6644
6645 \etocsetlinestyle{subsection}{}{}{\PrepareSubsection\appendtotok\toctabletok\toctablepiece}{}
6646
6647 \etocsettocstyle
6648 {\toctabletok{\hypersetup{hidelinks}%
6649 \begin{longtable}{|>{\bfseries}c|p{7cm}|r|}\hline
6650 \multicolumn{3}{|c|}{\Large\bfseries\strut TABLE OF CONTENTS}%
6651 \\\hline\hline}}
6652 {\global\toctabletok\expandafter{\the\toctabletok\hline\end{longtable}}}
6653 \etocsettocdepth {subsection}
6654 \tableofcontents
6655 \the\toctabletok
6656 \endgroup
6657 \end{filecontentshere}
6658 \marginattach
6659
6660 \clearpage
6661 \etocdepthtag.toc {etocandworld}
6662 \part{\etoc and the world}
6663
6664 \etocsettocstyle{}{}
6665 \etocfallbacklines % etoc own default
6666 \localtableofcontents
6667
6668 \section{Constraints on the \texttt{.toc} file constitution}
6669
6670 The contents of the |.toc| file (if it already exists) are read into memory by
6671 \etoc once, at the time of |\begin{document}|.%
6672 %
6673 \footnote{%
6674 Versions earlier than \etocrelease{1.07m} read the |.toc| file at the time of
6675 \csa{usepackage\{etoc\}}. Thanks to Denis Bitouzé who signaled a Babel
6676 related problem, which turned out to be caused by this.}
6677
6678 The |.toc| file remains available
6679 to other packages for read operations until the location of the first table
6680 of contents at which time a write stream is opened by \etoc and from that
6681 point the file is erased until its contents are again written to the disk by
6682 \LaTeX{} at the end of the compilation.
6683
6684 Don't use |\if<condition> stuff \tableofcontents\fi|, but:
6685 \centeredline{|\if<condition> stuff \expandafter\tableofcontents\fi|}
6686 Also a |\else| immediately following \csa{tableofcontents} or
6687 \csa{localtableofcontents} requires a previous \csa{expandafter}.
6688
6689
6690 \etoc can not really cohabit with packages modifying the \csa{tableofcontents}
6691 command: some sort of truce can be achieved if \etoc is loaded last, hence is
6692 the winner.
6693
6694 \begin{framed}
6695 Do not modify the |\tableofcontents| command like this:
6696 \centeredline{|\let\oldtableofcontents\tableofcontents|}
6697 \centeredline{|\renewcommand\tableofcontents{\oldtableofcontents foo}|}
6698 as this will make the |\label/\ref| mechanism impossible.
6699
6700 Rather, redefine \csb{etocaftertochook}
6701 \centeredline{|\renewcommand\etocaftertochook{foo}|} and there
6702 is also \csb{etocaftercontentshook} which is executed a bit
6703 earlier\footnotemark{} just before the closing part of the toc display
6704 style (and thus still within a group.)
6705
6706 Prepending is less of a problem (and anyhow there is also
6707 \csb{etocbeforetitlehook} available to the user).
6708
6709 Under certain circumstances \etoc imposes its views on
6710 \csa{tableofcontents} at the time of |\begin{document}|. You may thus have
6711 to use \csa{AtBeginDocument} to delay your (necessarily ugly and
6712 non-recommendable) patches. Patching after |\begin{document}| is
6713 naturally possible but I feel almost a rebel to mention this to \LaTeX{} users!
6714 \end{framed}
6715 \footnotetext{Contrarily to \csb{etocaftertochook},
6716 \csb{etocaftercontentshook} is not executed if the |tocdepth| did not
6717 allow the printing of the TOC.}
6718
6719 \etoc \textbf{requires} the |.toc| file to use the \csa{contentsline}
6720 macro. It \textbf{can not} work if there is no |.toc| file or if the
6721 |.toc| file does
6722 not use the \csa{contentsline} macro or if the \csa{contentsline} macro
6723 second argument mixes number and name in a manner unexpected by \etoc.%
6724 %
6725 \footnote{Prior to \etocrelease{1.1a}, \etoc required the \csa{contentsline} macro
6726 expansion to invoke \csa{l@section} et al. It now does not expand
6727 \csa{contentsline} hence is immune to whatever would happen during this
6728 expansion, and does not use nor modify the \csa{l@section} et al.\@ macros.}
6729
6730 \section{Compatibility with document classes}
6731
6732 \etoc has mainly been tested with the |article| and |book| standard classes.
6733 Some compatibility layer with the \ctanpkg{KOMA-script} and \ctanpkg{memoir} classes was added at
6734 \etocrelease{1.05} of |2012/12/01|.%
6735 %
6736 \footnote{That this is still in the doc on \texttt{2023/02/22} shows
6737 the frequency of \etoc syncing with upstream changes... but let me reassure
6738 the reader there has
6739 been indeed some occasional, although admittedly rare, internal updates
6740 in the more than ten years elapsed since.}
6741 %
6742 A compatibility layer is required for what this
6743 document designates as the ``global display style'': \etoc tries to emulate the
6744 default behaviour of the document class when \csb{etocsettocstyle} has not
6745 been used, so that it is still in ``compatibility mode''. There does not seem
6746 to be an easy
6747 way to extract this in an automated manner dynamically, so it is basically
6748 some manual work which the author initiated in 2012 and which got sporadically
6749 updated since.
6750
6751 \subsection{Compatibility with the \ctanpkg{KOMA-script} classes}
6752 \label{etocscrartclstyle}
6753 \label{etocscrbookstyle}
6754 \label{etocscrreprtstyle}
6755
6756 Not really tested... well, tested by this document with its dozens of \etoc
6757 TOCs and which uses \ctanpkg{scrartcl}! The package code contains
6758 \begin{verbatim}
6759 \@ifclassloaded{scrartcl}
6760 {\renewcommand*\etocclasstocstyle{\etocscrartclstyle}}{}
6761 \end{verbatim}
6762 with \cs{etocscrartclstyle} trying to emulate the global display style of the
6763 \cs{tableofcontents} within the class \ctanpkg{scrartcl}. Thus \etoc is ready
6764 for basic usage in compatibility mode. See further \autoref{ssec:tocbasic}.
6765
6766 \subsection{Compatibility with the \ctanpkg{memoir} class}
6767 \label{ssec:memoir}
6768 \label{etocmemoirtoctotocfmt}
6769 \label{etocmemoirstyle}
6770
6771 Release \etocrelease{1.07l} has also improved the compatibility with the \ctanpkg{memoir} class: its
6772 |appendix| level has been made known to \etoc. It is at the same level as
6773 |chapter|, thus the chapter line style should possibly do a test for some user
6774 defined boolean whose activation may be added to the |.toc| file at the suitable
6775 location via |\addtocontents{toc}{..}|, if one needs to distinguish the two
6776 kinds of divisions.
6777
6778 The \ctanpkg{memoir} mechanism relative to \toc versus \toc|*| is obeyed
6779 automatically, and applies with \localtoc too.
6780
6781 With release \etocrelease{1.2} some issues which were previously described here
6782 when the ``to toc'' feature of \ctanpkg{memoir} was left acting on local TOCs
6783 have been resolved, as an after-effect of the support for
6784 \etocoption{localtoctotoc} etc..., see \csb{etocsetup}.
6785
6786 \subsection{Compatibility with \ctanpkg{beamer}}
6787
6788 For the reasons mentioned already regarding the constraints on the |.toc| file
6789 constitution, \etoc is incompatible with the
6790 \ctanpkg{beamer} class. However, if \ctanpkg{beamer} is used in an article mode, i.e., with
6791 the article class in conjunction with the \ctanpkg{beamerarticle} package, then \etoc
6792 should work.
6793
6794 \section{Compatibility with other packages}
6795
6796 \subsection{Compatibility with \ctanpkg{babel}}
6797
6798 \begin{framed}
6799 One must load \etoc \emph{after} \ctanpkg{babel}. This is in order for
6800 \ctanpkg{babel}'s shorthands to be active at the time when \etoc loads the |.toc|
6801 file.
6802 \end{framed}
6803
6804 \subsection{Compatibility with \ctanpkg{hyperref}}
6805
6806 Please inform the author in case of issues: \etoc was from the start designed
6807 to be |100%| compatible with package \ctanpkg{hyperref}.
6808
6809 \begin{framed}
6810 Releases of \etoc prior to \etocrelease{1.2c} copied over some legacy
6811 internals of \ctanpkg{hyperref} which got removed there at release
6812 |v7.01c| of |2023-10-21|, and this caused \etoc to stop displaying
6813 tables of contents. You must use at least \etocrelease{1.2c} to avoid
6814 that mishap.
6815 \end{framed}
6816
6817 The macros \csb{etocname}, \csb{etocnumber}, and \csb{etocpage} contain the
6818 \ctanpkg{hyperref} links, if present (note that the \emph{linktoc=all} option of
6819 \ctanpkg{hyperref} tells it to put a link also in the page number corresponding to a
6820 given toc entry). For example, the tables of contents of the present document
6821 are all fully linked.
6822
6823 It doesn't matter whether \etoc or \ctanpkg{hyperref} is loaded
6824 first.
6825
6826 \subsection{Compatibility with \ctanpkg{microtype}}
6827 \label{ssec:microtype}
6828 \label{etocnoprotrusion}
6829
6830 (this doc added at \etocrelease{1.2b})
6831
6832 \ctanpkg{microtype} patches the \LaTeX{} \csa{numberline} command (which is
6833 used in |.toc| file) to execute \csa{leftprotrusion}. The reason
6834 \ctanpkg{microtype} does this patch to \csa{numberline} is that the default
6835 \LaTeX{} contents line styles do some \csa{hskip} which inhibit left
6836 protrusion of the (explicit digits or letters of the) argument of
6837 \csa{numberline}, which is the first typeset material on the contents line.
6838
6839 Some other contexts than a previous \csa{hskip} inhibit left protrusion, in
6840 particular a non-zero paragraph indentation.
6841
6842 One could imagine that \etoc user only has to add \csa{leftprotrusion} if so
6843 desired at start of the defined line styles. But usage of the
6844 \csa{leftprotrusion} command is delicate, it must be followed with an explicit
6845 character or with a very limited set of \LaTeX{} commands. In particular, and
6846 imagining here that the defined line style starts a paragraph with
6847 \csb{etocnumber}, and that this paragraph is indented so that automatic left
6848 protrusion does not apply, an attempt to force reactivation of left protrusion
6849 via:
6850 %
6851 \centeredline{|\leftprotrusion\etocnumber|}
6852 %
6853 fails. One has to resort to use:
6854 %
6855 \centeredline{|\expandafter\leftprotrusion\etocthenumber|}
6856 %
6857 This
6858 would not work with \csb{etocthelinkednumber}, so to get the protruding number
6859 to also be hyperlinked one has to use
6860 %
6861 \centeredline{|\etoclink{\expandafter\leftprotrusion\etocthenumber}|}
6862
6863 The package does not provide yet (nor is it planned in near future in absence
6864 of user requests) extra support such as an option to insert internally
6865 \csa{leftprotrusion} \emph{inside} \csb{etocnumber} which would avoid such
6866 gymnastics. But the user can easily add a definition such as
6867 %
6868 \centeredline{|\newcommand\leftprotrudingetocnumber{\etoclink{\expandafter\leftprotrusion\etocthenumber}}|}
6869 %
6870 to the preamble, and use the defined wrapper or a variant built upon
6871 \csb{etocthename} in custom \csb{etocsetlinestyle} line style definitions.
6872
6873 If on the contrary you want to avoid left protrusion, it is coherent to load
6874 \ctanpkg{microtype} this way:
6875 %
6876 \centeredline{|\usepackage[nopatch=toc]{microtype}|}
6877 %
6878 This avoids the \csa{leftprotrusion} addition done by \ctanpkg{microtype} to
6879 \csa{numberline}; but this is of relevance only if you use \etoc in
6880 compatibility mode, because user-defined \etoc line styles will not
6881 execute \csa{numberline} except if explicitly added to the line style, and
6882 even if they do, as explained above something such as
6883 %
6884 \centeredline{|\numberline{\etocnumber}|}
6885 %
6886 will inject a \csa{leftprotrusion} which will remain without effect.
6887
6888 \etoc provides since \etocrelease{1.2b} a macro \csb{etocnoprotrusion} which
6889 is a copy of the \LaTeX{} \csa{noprotrusion} command available since its
6890 |2018/12/01| release, and is used since by \LaTeX{} default TOC code with page
6891 numbers. You can use this if a style definition, perhaps modeled on the
6892 standard \LaTeX{} layout from \csa{@dottedtocline}, also locates
6893 \csb{etocpage} at right margin preceded on the line by some dot leaders.
6894 Indeed protrusion may cause an extra dot, compared to other lines, which is
6895 really ugly visually. Use \csa{noprotrusion} in the style after
6896 \csb{etocpage} (or whatever is at end of the line style contents) if you can
6897 assume that \LaTeX{} is recent enough, or use \csb{etocnoprotrusion} which
6898 will work with all \LaTeX{} versions, even old ones.
6899
6900 You may also consider turning protrusion off completely for tables of
6901 contents. For this, see \autoref{ssec:disableprotrusion}.
6902
6903 Notice that some problem with page number alignment look like
6904 protrusion-related ones but may simply be caused by the fact that the font
6905 used does not assign the same width to all digits, and the line style pushes
6906 these digits to the right end of the line (to confirm this in case of
6907 suspicion, temporarily make package \ctanpkg{microtype} inactive or remove it
6908 from your document). If for example \texttt{20} is, in the used font, wider
6909 than \texttt{27}, the latter will look shifted a bit to the right compared to
6910 the former. Centering the page number in a fixed width box (itself
6911 flushed-right to end of line) is one solution, but it may not be to everyone's
6912 taste due to single-digit page number; in that case the line style code could
6913 make a test on the page number (or its width, if it is not assumed it is
6914 purely numerical) and make appropriate decisions. I will leave the matter to
6915 your \LaTeX{} coding skills. Using a font with tabular lining figures fixes
6916 such problem.
6917
6918
6919
6920 \subsection{Compatibility with \ctanpkg{multicol}}
6921
6922 \etoc loads the package \ctanpkg{multicol}.
6923
6924 \subsection{Compatibility with \ctanpkg{tableof}}
6925
6926 It is possible to use simultaneously \etoc and
6927 \ctanpkg{tableof}. Release
6928 \etocrelease{1.08} of \etoc requires at least version |1.4a| of \ctanpkg{tableof}. If
6929 \csb{etocglobaldefs} is put in the preamble, this must be after the loading of
6930 package \ctanpkg{tableof}. {\color{niceone}\ctanpkg{tableof}} command \csa{nexttocwithtags}
6931 should work as expected.
6932
6933 \ctanpkg{tableof} commands \csa{tableof}, \csa{tablenotof}, ... will
6934 typeset the (a priori global) table of contents according to the document
6935 class defaults, obeying the \etoc depth tags; as explained in the \ctanpkg{tableof}
6936 documentation they do not typeset a TOC title. They should \emph{not} be used
6937 in case \csb{etocglobaldefs} was issued before, except if its scope has been
6938 terminated since then, or \csb{etoclocaldefs} has cancelled its influence.
6939
6940
6941 \subsection{Compatibility with \ctanpkg{tocbasic}}
6942 \label{ssec:tocbasic}
6943
6944 (doc last updated for \etocrelease{1.2})
6945
6946 This has only been tested to the extent of production of this PDF file (which
6947 does have dozens of TOCs, among them a few in compatibility mode). I
6948 noticed that some things required the global display style to also be set
6949 to compatiblity mode for some \ctanpkg{KOMA-script} user interface to produce
6950 the desired effect. As an example, the local table of contents of
6951 \autoref{sec:testingcompat} uses |\KOMAoptions{toc=left}| and
6952 \csb{etocstandardlines} but it had to use also \csb{etocclasstocstyle}:
6953 \begin{verbatim}
6954 \begingroup % to keep in particular toc=left with local effect
6955 \KOMAoptions{toc=left}
6956 \etocclasstocstyle % necessary for the display to obey toc=left
6957 \etocstandardlines
6958 \tableofcontents \ref{toc:tocstyle}
6959 \endgroup
6960 \end{verbatim}
6961 On the other hand I could use some other interface without having to activate
6962 the compatibility for the global display style. See \hyperref[toc:d]{the example} from
6963 \autoref{sec:labeling} or the one from the \autoref{part:control} which uses
6964 \begin{verbatim}
6965 \begingroup
6966 \etocsettocstyle{}{}
6967 \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
6968 \DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection}
6969 \DeclareTOCStyleEntry[numwidth=3em,indent=4.5em]{tocline}{subsubsection}
6970 \etocstandardlines
6971 \localtableofcontents
6972 \endgroup
6973 \end{verbatim}
6974 and demonstrates that this interface works also when not using the
6975 compatibility mode from \csb{etocclasstocstyle}. Of course, here the
6976 display style is a bit plain... but the \hyperref[toc:d]{example} of
6977 \autoref{sec:labeling} less so; it uses about the same TOCStyleEntry lines as
6978 above with some more width for the numbers of subsections.
6979
6980 \subsection{Compatibility with \ctanpkg{tocloft}}\label{subs:tocloft}
6981
6982 Steps are
6983 taken to prevent the redefinition of |\tableofcontents| done by
6984 \ctanpkg{tocloft} at |\begin{document}|.
6985 %
6986 As long as \etoc is left in compatibility mode the customization done by
6987 \ctanpkg{tocloft} will be obeyed, for both the line styles and the TOC title.
6988 One may still benefit from the \emph{depth tags} management by \etoc,
6989 from its |\localtableofcontents|, from its |\label+\ref| mechanism. One
6990 may use |\etocsetlinestyle| to define via \etoc the layout for one TOC and
6991 then use rather \ctanpkg{tocloft} for another one, if |\tableofcontents| follows
6992 \csb{etocstandardlines} and \csb{etocclasstocstyle}. In this
6993 compatibility mode \csb{etocsetlevel}\marg{division unit}|{|\csb{etocthemaxlevel}|}| will render
6994 invisible the chosen division level, but exchanging levels is otherwise
6995 not possible.
6996
6997 \begin{framed}
6998 One should load \etoc \emph{after} \ctanpkg{tocloft}. A warning is
6999 issued if otherwise, because if \etoc is loaded before it will realize that at
7000 the time of |\begin{document}| and trick \ctanpkg{tocloft} into believing
7001 having been loaded with the |titles| option.
7002
7003 Some bugs with \etocrelease{1.2} and \etocrelease{1.2a} were fixed at
7004 \etocrelease{1.2b}.
7005 \end{framed}
7006
7007 It is possible to modify midway in the document the macros \csa{l@section},
7008 \csa{l@subsection} ... but the effect will be seen only in table of contents
7009 typeset by \etoc in compatibility mode (and of course after those
7010 customizations). It will have no effect on true \etoc TOCs.
7011
7012 \subsection{Compatibility with \ctanpkg{tocbibind}}\label{subs:tocbibind}
7013
7014 Added at \etocrelease{1.2} (but with a bug fixed only at
7015 \etocrelease{1.2d}). See also \csb{etocsetup} for a discussion of the
7016 package options which are all related to this (they will achieve the
7017 \ctanpkg{tocbibind} ``to toc'' features without requiring the package).
7018
7019 Thanks to Denis Bitouzé for feature request.
7020
7021 \subsection{Compatibility with \ctanpkg{tocvsec2}}
7022
7023 \etoc used to be incompatible with package
7024 \ctanpkg{tocvsec2}; it now cohabits, sort
7025 of, as it deactivates \ctanpkg{tocvsec2}'s modification of |\tableofcontents|
7026 and also cancels its other |toc|-related macros, but
7027 reimplements partially their functionality with \csb{etocsettocdepth.toc}. By
7028 the way, at least two latex runs are necessary for new uses of this command in
7029 a document to have an effect in tables of contents.
7030
7031 \section{\TeX nical matters}
7032
7033 The \csb{etocname}, \csb{etocnumber}, \csb{etocpage} commands are protected
7034 against premature expansion. They are hyperlinks if package \ctanpkg{hyperref}
7035 is loaded and depending on its option |linktoc| value; under the default
7036 |linktoc=section|, only name and number are hyperlinked, not the page
7037 number.
7038
7039 On the other hand \csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}
7040 are \emph{not} protected against expansion. And neither are
7041 \csb{etocthelinkedname}, \csb{etocthelinkednumber}, \csb{etocthelinkedpage}.
7042 They were modified at \etocrelease{1.1a} and now are always hyperlinks (except for the
7043 latter if the page number is empty), if
7044 \ctanpkg{hyperref} is present, independently of |linktoc| status.
7045
7046 The commands \csb{etoclink} and \csb{etocifnumbered} are also
7047 protected against premature expansion. Also \csb{etociffirst} and
7048 \csb{etoctoccontentsline}.
7049
7050 Commands such as \csb{etocsetlinestyle}, \csb{etocsetlevel},
7051 \csb{etocsettocstyle}, \csb{etocmulticolstyle},
7052 \csb{etocruledstyle}, \csb{etocframedstyle} obey \LaTeX{}'s
7053 groups. All TOCs are typeset inside groups.
7054
7055 When a \localtoc is inserted by the user in the document, a
7056 line containing an \etoc inner command and an identification
7057 number is added to the |.toc| file on first subsequent compilation.
7058 The correct local table of
7059 contents will be displayed only on the second compilation.
7060
7061
7062 %%% de-\section this for matters of avoiding too cramped mindmap TOC
7063 %%%\section{Errors and catastrophes}
7064
7065 After using \csb{etocsetlinestyle} for one level, the remaining
7066 uncustomized levels use the \etoc default styles (those
7067 which are activated by \csb{etocfallbacklines}). One has to
7068 make sure that \textbf{all levels} needed for the next table of
7069 contents are mutually compatible: in particular the \etoc
7070 default line styles expect each to be started in ``vertical mode''.
7071
7072 When using multiple \toc commands in a document, one should beware from
7073 adding typesetting instructions directly in the |.toc| file, as they will be
7074 executed by \etoc for \textbf{all TOCs}: even for a \localtoc it doesn't
7075 matter if that instruction seems to concern material outside of its scope,
7076 it will get executed nevertheless. If absolutely necessary to add extra
7077 commands to the |.toc| file, make it in such a way that they can be
7078 activated or deactivated easily from the document source, e.g.\@ via some
7079 booleans.
7080
7081 As is usual with toc and labels, after each change, one has
7082 to run latex a certain number of times to let the produced
7083 document get its final appearance (at least twice).\par
7084
7085 \clearpage
7086 \etocdepthtag.toc {code}
7087 \normalmarginpar\marginparwidth72bp
7088 \part{The code}
7089 \label{part:code}
7090
7091 % return to single spacing
7092 \setstretch{1}
7093
7094 \etocfallbacklines
7095 \etocsettocstyle{}{}
7096
7097 \localtableofcontents
7098
7099 % IL FAUT METTRE AVANT \section{Timestamps} SINON FOUTU
7100 % (non plus maintenant puisque j'utilise \botmark pas \firstmark
7101 % dans le \rightmark)
7102 % Que c'est pénible cette syntaxe \markboth/\markright de LaTeX !
7103 % Pourquoi est-ce que \markright n'a pas été définie comme #1#2-> truc avec #2 ??
7104 \makeatletter
7105 \if@twoside
7106 \renewcommand *{\sectionmark }[1]{%
7107 \markboth
7108 {\unexpanded{\ifodd\value{page}(\hyperref[imp]{implementation},
7109 \hyperlink{FRONTPAGE}{user manual
7110 front page})\hfill\fi
7111 \hyperref[changelog]{\thesection. Change history}%
7112 \ifodd\value{page}\else\hfill(\hyperref[imp]{implementation},
7113 \hyperlink{FRONTPAGE}{user manual
7114 front page})\fi}}%
7115 {\unexpanded{\ifodd\value{page}(\hyperref[imp]{implementation},
7116 \hyperlink{FRONTPAGE}{user manual
7117 front page})\hfill\fi
7118 \hyperref[changelog]{\thesection. Change history}%
7119 \ifodd\value{page}\else\hfill(\hyperref[imp]{implementation},
7120 \hyperlink{FRONTPAGE}{user manual
7121 front page})\fi}}%
7122 }
7123 \else\error
7124 % faudrait cependant que je réfléchisse à quoi faire exactement en oneside
7125 % mais comme ceci ne peut arriver que si quelqu'un customise etoc.tex
7126 % ce qui n'arrivera JAMAIS, je laisse tomber
7127 \renewcommand *{\sectionmark }[1]{%
7128 \markright
7129 {\unexpanded{\ifodd\value{page}(\hyperref[imp]{implementation},
7130 \hyperlink{FRONTPAGE}{user manual
7131 front page})\hfill\fi
7132 \hyperref[changelog]{\thesection. Change history}%
7133 \ifodd\value{page}\else\hfill(\hyperref[imp]{implementation},
7134 \hyperlink{FRONTPAGE}{user manual
7135 front page})\fi}}%
7136 }
7137 \fi
7138 \makeatother
7139
7140 \section{Timestamp}
7141
7142 This is the documentation as of \texttt{\etocdocdate}, printed from the
7143 source file with the time stamp \texttt{\etocdtxtimestamp}. The package
7144 version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
7145
7146 \catcode1 13
7147
7148 \begingroup
7149 \renewcommand\lowast{{\normalsize\raisebox{-.4\height}{*}}}
7150
7151 \small
7152
7153 \section{Change history}\label{changelog}
7154
7155 \setlength{\columnsep}{\etoccolumnsep}
7156
7157 \makeatletter
7158
7159 % 27 avril 2014 un petit hack pour hyphénation (éventuelle) en allemand
7160 % j'ai déjà ~ qui sera de catcode 0, cependant il faudrait aussi les accolades,
7161 % donc finalement pour aller vite, je rends le + actif. Je modifie aussi le test
7162 % fait par \jfverbaspace (n'ayant pas commenté mon code, j'ai dû réfléchir pour
7163 % me rappeler à peu près ce que c'était censé faire).
7164
7165 \def\jfverbatim{\@beginparpenalty \predisplaypenalty
7166 \parindent \z@
7167 \parfillskip \@flushglue
7168 \parskip \tw@\p@ plus 1fil\relax
7169 \let \do \@makeother
7170 \dospecials
7171 \makestarlowast
7172 \catcode`$ \active
7173 \begingroup\lccode`~`$
7174 \lowercase{\endgroup\def~[##1]{\foreignlanguage{ngerman}{##1}}}%
7175 \catcode`^ \active
7176 \begingroup\lccode`~`^
7177 \lowercase{\endgroup\def~{\nopagebreak}}% ajouté 2014/04/28, oblige à un peu
7178 % plus de mark-up cependant
7179 \catcode`\~\z@
7180 \footnotesize\normalfont\baselineskip10pt\relax
7181 % \def\v{\vskip\baselineskip v}% ajouté 2015/05/09; faudra trouver mieux.
7182 % 2022/08/30, I remove all "v"'s from version numbers.
7183 % 2023/01/25, creating hypertargets
7184 \begingroup\lccode`~32
7185 \lowercase{\endgroup
7186 \def\1##1~{\vskip\baselineskip\hypertarget{v1##1}{1##1}~}}%
7187 % 2022/08/26, stop using \frenchspacing
7188 % \frenchspacing
7189 % 2023/01/14
7190 \def\2##1.{\ctanpkg{##1}}%
7191 % 2022/08/26. I realized that rendering was broken, and finally identified
7192 % the bad commit to be in LaTeX 2022/06/01 release. Its \obeyspaces not only
7193 % makes the ascii32 \active but it also redefines it! Solution could be to
7194 % actually use \obeyedspace in the definition of active space about 20 lines
7195 % below but this would tie to LaTeX 2022/06/01 or later for building etoc.pdf
7196 \catcode`\ \active % was \obeyspaces
7197 \jf@xverbatim
7198 }
7199
7200 \begingroup
7201 \catcode `|=0 \catcode `[= 1 \catcode`]=2
7202 \catcode `\{=12 \catcode `\}=12 \catcode`\\=12
7203 |long|gdef|jf@xverbatim#1\end{jfverbatim}[#1|end[jfverbatim]]
7204 |endgroup
7205
7206 \def\endjfverbatim{}
7207
7208 \newdimen\jfverbadim
7209 \makeatother
7210
7211 \begin{multicols}{2}
7212 % un \raggedcolumns ne fonctionne pas vraiment pour faire de l'alignement
7213 % de grid à cause du \parskip
7214 \makeatletter
7215 \everypar{\leftskip\jfverbadim\bgroup
7216 \def\par{\egroup\jfverbadim\z@\@@par}%
7217 \def\jfverbaspace#1{\if\@sptoken\string#1\unskip\else\ \fi#1}}
7218 %
7219 % see 2022/08/26 above note
7220 \begingroup\obeyspaces\def\x{\endgroup%
7221 \def {\ifvmode\advance\jfverbadim.5em\relax\else\expandafter\jfverbaspace\fi}}\x
7222 \makeatother
7223 \vskip-\baselineskip
7224 \begin{jfverbatim}
7225 ~1.2e [2026/05/04]^
7226
7227 Compatibility hotfix with hyperref v7.01q (jfbu/etoc#7, jfbu/etoc#28).
7228 Thanks to @pkl97 for report.
7229
7230 \etocfallbacklines as preferred alias to \etocdefaultlines.
7231
7232 \etocsetlinestyle as preferred alias to \etocsetstyle.
7233
7234 Hacker note: \etocthelinkedname, \etocthelinkednumber,
7235 \etocthelinkedpage now employ internally a \protected wrapper of
7236 \hyperlink so they can be used inside \edef (or rather, preferably,
7237 \protected@edef for the name in particular). This facilitates
7238 advanced techniques as found in "The TOC as a TikZ mind map" and
7239 similar sections.
7240
7241 ~1.2d [2023/10/29]^
7242
7243 Fix crash (present since 1.2) if used with
7244 \usepackage[nottoc]{tocbibind} (the faulty code was avoided if also
7245 tocloft was used by document). Thanks to François Jonca for report.
7246
7247 ~1.2c [2023/10/28]^
7248
7249 Compatibility hotfix with hyperref v7.01c; etoc had copied
7250 over a now unneeded internal hyperref test, and since
7251 v7.01c the result was that etoc produced empty tables of
7252 contents. Thanks to Denis Bitouzé for report.
7253
7254 ~1.2b [2023/07/01]^
7255
7256 bugfix: a refactoring at 1.2 accidentally removed a needed
7257 \AtBeginDocument and as a result the tocloft redefinition
7258 of \tableofcontents was not undone, if etoc got loaded after
7259 tocloft, as is advised by the documentation. Thanks to
7260 user691586 for report.
7261
7262 Add section documenting compatibility aspects with usage of
7263 package microtype. Add \etocnoprotrusion an alias to LaTeX
7264 2018/12/01 \noprotrusion and use it after \etocpage inside the
7265 package built-in fallback section and subsection toc line styles.
7266
7267 Fix some of the documentation (in particular the sections "A first
7268 example" and "A second example") as some of its highly pedagogical
7269 comments had lost sync with other changes. Don't hesitate getting
7270 in touch with the author to obtain further improvements.
7271
7272 ~1.2a [2023/05/01]^
7273
7274 The requirements (added respectively at 1.1a and 1.2) of a LaTeX
7275 kernel at least as recent as 2020-10-01 and of availability of
7276 \expanded engine primitive have been lifted. Due to lack of time
7277 and ressources, etoc is not retro-tested on old LaTeX installations,
7278 though.
7279
7280 Boolean option `deeplevels' extends the maximal allowed numerical
7281 level from 6 to 12. Adapted from a patch courtesy of Matthew
7282 Trescott. See
7283
7284 https://github.com/doxygen/doxygen/pull/9936
7285
7286 for context.
7287
7288 Using this option does not change anything to tocdepth and
7289 secnumdepth LaTeX counters, nor does it do any of the needed extras
7290 to let a sectioning level be known to LaTeX (if etoc is used in
7291 "compatibility mode", the suitable \l@<levelname> macros must have
7292 been declared to LaTeX for TOC rendering). Whether or not using
7293 etoc in compatibility mode (i.e. whether or not using
7294 \etocsetlinestyle{<levelname>}{...}{...}{...}{...}), recall that all new
7295 levels must be declared to etoc at least once via
7296 \etocsetlevel{<levelname>}{<number>}.
7297
7298 The macro \etocthemaxlevel expands accordingly to either 6 (default)
7299 or 12 (if option `deeplevels'). So
7300 \etocsetlevel{foo}{\etocthemaxlevel} should now be used in place of
7301 \etocsetlevel{foo}{6} when one wants to make foo entries invisible
7302 in a document context which may have used, or not, the `deeplevels'
7303 option.
7304
7305 The auto-selection-of-heading-by-local-tocs from 1.2 uses a macro
7306 \etocdivisionnameatlevel which will need most probably user
7307 adaptation with `deeplevels', as etoc can not know what are the
7308 standard names chosen by user, and how many deep levels were
7309 actually added. So it opted to the choices done by the Doxygen
7310 project. Check the etoc source code for this macro and redefine it
7311 appropriately. Note though that this only matters if your documents
7312 has local TOCs located under division units at least as deep as
7313 subsubsection.
7314
7315 Fix a 1.2 bug: using `six' as first argument of `\etocsetlevel'
7316 caused an internal control sequence to be redefined, with various
7317 strange potential aftereffects.
7318
7319 ~1.2 [2023/03/01]^
7320
7321 \locallistoffigures and \locallistoftables.
7322
7323 MAKE SURE TO READ THE FRAMED TEXT IN THE DOCUMENTATION AT START OF
7324 SECTION 2 WHICH DESCRIBES THESE NEW COMMANDS.
7325
7326 It is for time being required to pass options `lof', resp. `lot'
7327 at package loading time to activate these features. Whether or
7328 not these features are enabled, etoc interferes in absolutely no
7329 way with \listoffigures and \listoftables and their respective
7330 auxiliary files.
7331
7332 Boolean options (and utility \etocsetup) `maintoctotoc',
7333 `localtoctotoc', `localloftotoc', `locallottotoc', and
7334 `ouroboros'. For above reasons, no `mainloftotoc' or
7335 `mainlottotoc'. With `ouroboros=false` local TOCs whose heading
7336 has been added to the `.toc' file due to `localtoctotoc` will show
7337 deeper ones and the local `lists of' from their own level, but not
7338 themselves.
7339
7340 Compatibility layer with `tocbibind'. Thanks to Denis Bitouzé for
7341 feature request many years ago. Sorry for the delay!
7342
7343 New feature (and breaking change): local tables of contents
7344 in the default package configuration auto-adapt their titles
7345 to use the appropriate unnumbered division heading (for example
7346 a \subsection* if inside a \section).
7347
7348 Formerly, it was intended one would use \etocsettocstyle (or
7349 higher level commands), else local TOCs were rendered using the
7350 same emulation of the document class as for the main TOC. One can
7351 still require this document class emulation but then etoc tries at
7352 least to adapt to the division unit one level below \part (i.e.
7353 \chapter or \section). E.g., for KOMA-script the option
7354 `leveldown' is used. But this is not appropriate for deeper
7355 levels in general.
7356
7357 Ultimate control of toc titling can still be achieved via
7358 \etocsettocstyle. Many commands have been added to ease its
7359 usage. It is also possible to customize the default behavior
7360 without \etocsettocstyle.
7361
7362 Details of the user interface and produced output from these novel
7363 commands and options are susceptible to change. Use at own risk.
7364
7365 Bugfix: the emptiness check could fail for
7366 \localtableofcontentswithrelativedepth as it ignored tocdepth changes
7367 originating from inside the .toc file, contrarily to the actual
7368 typesetting (and behavior with other local tocs)
7369
7370 Bugfix: the \tableofcontents\ref{foo} syntax caused a
7371 ``Missing number'' after \vpageref{foo} from package varioref
7372 in certain circumstances due to \r@foo having then acquired a
7373 value with an unexpected non-numerical first chunk.
7374
7375 Breaking change: the \etocsavedsectiontocline et al. macros
7376 which raised a deprecation warning since 1.1a now use an
7377 error message.
7378
7379 \expanded primitive is required. [reverted at 1.2a]
7380
7381 ~1.1d (not released, part of 1.2)^
7382
7383 Complete internal refactoring of the legacy core code behind
7384 the concept of ``start'' and ``finish'' parts for line styles.
7385
7386 \etocifunknownlevelTF and \etoclevel abstract away some
7387 internals and may be useful for class or package authors.
7388
7389 \etocsetlevel filters out forbidden keywords `all', `none' and
7390 others. Its second argument can be an expression.
7391
7392 \etocsetlinestyle checks and warns appropriately if the level is
7393 unknown to etoc or has a non-accepted numerical value.
7394
7395 Extensive refactoring of the documentation.
7396
7397 ~1.1c [2023/01/20]^
7398
7399 Fix a brace removal bug in the construction of \etocname. It
7400 remained without visible effects in documents using hyperref and
7401 default settings, thanks to the hyperlink wrapper, but e.g.
7402 \section{{\color{blue}Blue}} in a document not using hyperref,
7403 and not using etoc only in "compatibility mode", could cause a
7404 color leak in the table of contents.
7405
7406 With the KOMA-script numberline toc feature, unnumbered entries in
7407 TOCs typeset via etoc user-defined or package provided line styles
7408 but using compatibility mode for the global display style were
7409 (knowingly) considered to be numbered with an empty number. They
7410 are now considered by \etocifnumbered to be not numbered and the
7411 empty \etocnumber will carry no hyperlink.
7412
7413 Fix a 1.1a regression in the context of KOMA-script unnumbered TOC
7414 entries: \etocthelinkedname could lose its hyperlink.
7415
7416 Continue internal trimming of old code branches which became
7417 un-needed after the 1.1a refactoring. Add relatively decent
7418 code comments to accompany the 1.1a-c refactoring. Update
7419 warning messages to use more consistently LaTeX's templates.
7420
7421 ~1.1b [2023/01/15]^
7422
7423 Documentation fix, 1.1a forgot to mention the following change:
7424 \etocthelinkedname, \etocthelinkednumber, \etocthelinkedpage
7425 are now always hyperlinks independently of linktoc status.
7426
7427 ~1.1a [2023/01/14]^
7428
7429 This version brings no new functionality, despite the number bump.
7430 It implements a complete rewrite of old legacy core internals.
7431 Formerly, etoc waited for ~2hyperref. (if present) to have added
7432 hyperlinks via its patch to LaTeX's \contentsline.
7433 etoc examined the arguments of \l@section and other commands to extract
7434 hyperlinking information, if any.
7435 With this release etoc decides earlier according to
7436 ~2hyperref. linktoc status whether section names and page numbers
7437 should be hyperlinked, and adds links itself via \hyperlink. etoc
7438 is thus now immune to the details of how ~2hyperref. patches the
7439 \contentsline command, which is not executed anymore.
7440 Overall, the code is greatly simplified.
7441
7442 \etoclink now wraps its argument in an hyperlink even if
7443 ~2hyperref. is configured via
7444 linktoc=none. Formerly no hyperlink was added then.
7445
7446 Deprecation of \etocsavedsectiontocline and similarly named
7447 commands. They are not needed as \l@section et al. are with this
7448 release left unmodified during the table of contents typesetting.
7449
7450 ~LaTeX kernel from 2020-10-01 or later is required (to allow
7451 assuming the \contentsline entries in the TOC file always have
7452 four arguments). [reverted at 1.2a]
7453
7454 ~1.09i [2022/11/21]^
7455
7456 Fix bug showing when a document uses both \etocchecksemptiness and
7457 \etocsetlocaltop.toc: the start and finish parts of some levels were
7458 executed possibly causing extra printed output.
7459
7460 More hyperlinking in the implementation part of the documentation.
7461
7462 ~1.09h [2022/11/20]^
7463
7464 Documentation improvements. In particular, attached code snippets
7465 are now visible via their filenames in the page margins. Also,
7466 command names are doubly hyperlinked: first half links to the devoted
7467 part of the user manual, second half links to the implementation part.
7468
7469 ~1.09g [2022/11/17]^
7470
7471 Compatibility hotfix with recent hyperref 7.00u of 2022-11-13.
7472 Thanks to Denis Bitouzé for signaling the breakage to the author.
7473
7474 ~1.09f [2022/08/30]^
7475
7476 No more shipping of a German translation of the documentation,
7477 as it was last updated in April 2015.
7478
7479 (etoc.pdf) User level commands hyperlink from their code source definitions
7480 to their descriptions in the documentation part. Macros used in the code
7481 source hyperlink to where they first got defined there.
7482
7483 Wrap the \etocpartname (from etoc's package provided toc line style)
7484 together with the part number in a potential common hyperlink.
7485
7486 Try to sync the emulation of the global display style with KOMA-script
7487 v3.37 (in particular regarding the noparskipfake KOMA toc feature).
7488
7489 Improve documentation of some aspects under memoir class.
7490
7491 Remove the \nonumberline token, even though empty, from the meaning of
7492 \etocthename (KOMA-script classes).
7493
7494 Add \etocimmediatedepthtag.toc to work around problems related to
7495 \include (see user doc). Thanks to Norman Ramsey who reported the problem
7496 and proposed a work-around in July 2016. Apologies for the somewhat longish
7497 delay in incorporating it...
7498
7499 Also add \etocimmediatesettocdepth.toc.
7500
7501 Also add \etocimmediatetoccontentsline and its starred variant.
7502
7503 Also add \etocimmediatesetlocaltop.toc.
7504
7505 Fix an obscure bug (see source code comments) in the
7506 \etocsetlocaltop.toc mechanism.
7507
7508 ~1.09e [2021/09/23]^
7509
7510 Needed (if etoc is used without hyperref) updates to
7511 internal macros to prepare for the upcoming LaTeX November
7512 2021 change to \contentsline.
7513
7514 Related updates to the user macro \etoctoccontentsline.
7515
7516 ~1.09d [2021/07/13]^
7517
7518 Some minor synching with tableof 1.4c.
7519
7520 Add \etockeeporiginaltableofcontents to provide a work-around to a
7521 compatibility issue with listings's \lstlistoflistings, which abuses
7522 \tableofcontents for doing something unrelated to the actual contents.
7523 Thanks to Denis Bitouzé for report.
7524
7525 Usage: \usepackage{etoc}\etockeeporiginal-tableofcontents, then
7526 however you must employ \etoctableofcontents, not \tableofcontents.
7527
7528 ~1.09c [2020/05/15]^
7529
7530 Syncs with KOMA-script deprecation of \iftocfeature.
7531
7532 ~1.09b [2019/11/17]^~par~nobreak~vskip-~parskip~vskip-~baselineskip
7533 ~1.09a ^
7534
7535 Sync with memoir v3.7i which has a better location of the TOC
7536 hyperref anchor. The \etocaftertitlehook can now freely be
7537 used also with memoir class (formerly its usage in case of
7538 memoir class was preempted by etoc itself). For more details
7539 refer to the section "Compatibility with the memoir class".
7540
7541 ~1.09 [2019/03/09]^
7542
7543 New features: \etoclocaltop, \localtableofcontentswithrelativedepth. Thanks
7544 to Tony Roberts for feature request.
7545
7546 Note to hackers: internal control sequence \Etoc@localtop is gone.
7547
7548 etoc now requires e-TeX (\numexpr, \unless).
7549
7550 ~1.08p [2018/07/04]^
7551
7552 Fixed bug surfacing in case of linktoc=page option of hyperref.
7553 Thanks to Denis Bitouzé for report. Cf:~\
7554 https://github.com/ho-tex/hyperref/issues/65~\
7555 https://github.com/dbitouze/yathesis/issues/61
7556
7557 ~1.08o [2018/06/15]^
7558
7559 Fixed bug showing up if an unnumbered TOC entry starts with a brace,
7560 and document uses hyperref. Caused by a typo in a macro name at
7561 previous release.
7562
7563
7564 ~1.08n [2018/02/23]^
7565
7566 Refactoring of core macros detecting \numberline and its variants.
7567
7568
7569 ~1.08m [2018/02/07]^
7570
7571 Fix to 1.08k's introduced incompatibility with KOMA-script
7572 and tocbasic's \nonumberline.
7573
7574
7575 ~1.08l [2017/10/23]^
7576
7577 Workaround an issue with Emacs/AUCTeX wrongly reporting about
7578 actually non-existent LaTeX errors, which was triggered by some
7579 strings written (indirectly) to log file by etoc under some
7580 circumstances.
7581
7582
7583 ~1.08k [2017/09/28]^
7584
7585 Adds \etocsetlocaltop.toc. See corresponding manual section for
7586 details.
7587
7588 Adds \etocsavedparttocline, \etocsavedchaptertocline,
7589 \etocsavedsectiontocline, ... They can be used in the context of
7590 the technique explained in section "Another compatibility mode".
7591
7592 Formerly, etoc redefined for the duration of the TOC the memoir
7593 macro \chapternumberline and its likes to have same meaning as
7594 \numberline (of course, not when executed in compatibility mode),
7595 for the sake of extraction of \etocnumber.
7596
7597 New method detects presence of any \<foo>numberline macro without
7598 any change to originals; they can thus be used as is when applying
7599 the approach of "Another compatibility mode" section from manual.
7600
7601
7602 ~1.08j [2017/09/21]^
7603
7604 Since 1.08a-2015/03/13 \etocname, \etocnumber, \etocpage
7605 contain, if hyperref is present and configured for using
7606 hyperlinks in the TOC, the link destination in already expanded
7607 form. This means one can use them even if the style closes a
7608 group (for example from a & in a tabular), if \etocglobaldefs
7609 was issued; also one can save their meaning for delayed usage
7610 (with for example \LetLtxMacro as they are robust).
7611
7612 But for some legacy reason \etoclink, contrarily to
7613 \etocthelink, was handled differently. Now, \etoclink also
7614 contains the link destination in already expanded form, and can
7615 thus be used even if the line style issues a &, as long as
7616 \etocglobaldefs is issued.
7617
7618 Also, bugs dating back to the early days of the package, but
7619 surfacing only under relatively rare conditions such as usage
7620 of hyperref with its option "linktoc=page" got fixed.
7621
7622
7623 ~1.08i [2016/09/29]^
7624
7625 This fixes an issue dating back to 1.08e-2015/04/17: under
7626 \etocchecksemptiness regime, some circumstances (such as
7627 adding to an already compiled document a \localtableofcontents
7628 before the main \tableofcontents) created an "Undefined
7629 control sequence \Etoc@localtop" error. Thanks to Denis Bitouzé
7630 for reporting the problem.
7631
7632 On this occasion, \etocdoesnotcheckemptiness
7633 has been added to unset the flag.
7634
7635 A rather more exotic issue was fixed: the emptiness check for
7636 local tocs could get confused if the tocdepth counter was varying
7637 in some specific ways from inside the toc file.
7638
7639 After adding to a document a \localtableofcontents, two LaTeX
7640 passes are needed for etoc to get a chance to print the
7641 correct local contents. Formerly, etoc issued a Warning on
7642 the first pass; it now also induces LaTeX into
7643 announcing "There were undefined references", as this is nearer
7644 to the end of the log file and console output.
7645
7646
7647 ~1.08h [2016/09/25]^
7648
7649 New functioning of \etocsetnexttocdepth: the tocdepth counter is
7650 modified only at the time of the table of contents, not before.
7651 This fixes an issue which arose when \etocsetnexttocdepth was
7652 used multiple times with no intervening table of contents.
7653 Thanks to Denis Bitouzé for reporting the problem.
7654
7655 The PDF documentation includes about 25 LaTeX code snippets also
7656 as file attachment annotations, additionally to their verbatim
7657 typesetting. The ordering of the documentation contents has been
7658 slightly re-organized.
7659
7660 A previous documentation-only update on 2016/09/09 added a new
7661 section with the (approximate) translation into etoc lingua of the
7662 book class toc style, for easy customizability.
7663
7664
7665 ~1.08g [2015/08/29]^
7666
7667 Downgraded to a mere info message the etoc-issued warning
7668 (relative to \settocdepth/\maxtocdepth) under class memoir.
7669
7670
7671 ~1.08f [2015/04/28]^
7672
7673 Minor changes to the documentation. \etocsetlevel more economical.
7674
7675
7676 ~1.08e [2015/04/17]^
7677
7678 The command \etocchecksemptiness tells etoc to not print, from
7679 that point on, the headings of the local tables of contents if
7680 they have empty contents. This is mainly for class authors who
7681 might want to have their \section or \chapter automatically do
7682 a \localtableofcontents. Could prove also useful for batch
7683 conversions of documents. Thanks to Paul Gaborit who asked for
7684 such a feature.
7685
7686 The command \etocnotocifnotoc extends this behaviour to global
7687 TOCs: indeed why should documents with no sectioning units take
7688 this as an excuse not to use package etoc ?
7689
7690 The command \etocifwasempty{yes}{no} can be used for
7691 suitable extra action.
7692
7693 A \tableofcontents\ref{foo} now expects foo to be a label to a
7694 _local_ TOC. The use with foo a label to a _global_ TOC is not
7695 supported anymore as it had no utility and made the code more
7696 complex.
7697
7698 The syntax \localtableofcontents\ref{foo} is now accepted as a
7699 synonym to the earlier syntax \tableofcontents\ref{foo}.
7700
7701
7702 ~1.08d [2015/04/09]^
7703
7704 Translation into German of the additions made to the documentation
7705 for the 1.08x series of releases.
7706
7707 Thanks to Christine Römer!
7708
7709
7710 ~1.08c [2015/03/30]^
7711
7712 - removed a few unneeded \long from the code.
7713
7714 - removed use of \arabic at one location of the code, as it may get
7715 redefined by some language modules for babel or polyglossia.
7716
7717
7718 ~1.08b [2015/03/18]^
7719
7720 Bug fixes:
7721
7722 - extra space token removed from `\localtableofcontents` (showed
7723 only for inline TOCs.)
7724
7725 - \etocpartname (a macro used by the package own default line
7726 styles) was defined to be \partname, but this is not compatible
7727 at least with babel+french context. Now simply expands to Part.
7728
7729 - some problems fixed in the German documentation.
7730
7731 - [2015/03/28] some more problems fixed in the documentation. Added
7732 mention of \etocarticlestyle and \etocbookstyle.
7733
7734
7735 ~1.08a [2015/03/13]^
7736
7737 \etocname, \etocnumber and \etocpage are now the robust
7738 variants of \etocthelinkedname, \etocthelinkednumber and
7739 \etocthelinkedpage. This should arguably have been done since
7740 the addition of the latter to etoc with 1.07f [2013/03/07].
7741 The earlier robust commands \etocname etc... contained
7742 the hyperlink destination only in an unexpanded form.
7743
7744 The documentation has a brand new title page and a new section
7745 The TOC as a TikZ mind map both illustrating further uses of
7746 etoc to display tables of contents as trees in an automatic
7747 manner.
7748
7749
7750 ~1.08 [2015/03/10]^
7751
7752 \etocskipfirstprefix may now appear anywhere in the <start>
7753 part of a level style.
7754
7755 New commands \etociffirst, \etocxiffirst, \etocxifnumbered,
7756 \etocglobaldefs and \etoclocaldefs.
7757
7758 It is now possible to issue line style specifications directly
7759 with & and \\ tokens, in order to typeset a TOC as a tabular
7760 or longtable with the opening for example in the first
7761 argument of \etocsettocstyle and the closing in its second
7762 argument.
7763
7764 It is mandatory for such uses to issue \etocglobaldefs which
7765 tells etoc to proceed globally for certain definitions. This
7766 is also useful in the context of the inline environments of
7767 package enumitem.
7768
7769 On this occasion, various old parts of the code have been
7770 improved.
7771
7772
7773 ~1.07n [2015/03/05]^
7774
7775 No more use of \toks@ when etoc constructs \etocthelinkedname
7776 etc... Thus \toks@ can be put in the line styles in order to
7777 accumulate information. Only useful if it is certain nothing
7778 else will change \toks@ either.
7779
7780 In the documentation: list of main commands now in alphabetic
7781 order.
7782
7783
7784 ~1.07m [2015/01/23]^
7785
7786 Reading of .toc file is delayed to \begin{document} to account for
7787 possible Babel active characters used therein. Thanks to Denis
7788 Bitouzé who reported a Babel related problem.
7789
7790 Improved global toc display emulation under KOMA-script classes.
7791
7792 New command \etocbeforetitlehook. New command \etocdisplay.
7793
7794
7795 ~1.07l [doc of 2014/04/29]^
7796
7797 Added to the documentation an example of use of \etocthelinkedname together
7798 with an enumitem inline itemize* environment; moved main TOC to immediately
7799 after the title, and license to the first pages.
7800
7801 Incorporation of the translation into German done on the initiative of
7802 $[Christine Römer] by $[Felix Baral-Weber, Jenny Rothkrämer-Vogt, Daniel
7803 Büttner, Claudia Dahl, Christian Otto and Christine Römer (FSU Jena).] My
7804 grateful thanks to all!
7805
7806
7807 ~vskip~baselineskip1.07l [2014/04/22]^
7808
7809 Fixes a bug with the 1.07k compatibility layer with tocloft which had broken
7810 the 1.07k (sic) compatibility with memoir (yes, memoir class 1.07k testing
7811 had been done before adding the tocloft thing to the source code . . . ).
7812 Also, etoc when detecting tocvsec2 now checks if this is under the memoir
7813 class, as then nothing special needs to be done to rescue \tableofcontents,
7814 contrarily to the situation with the native tocvsec2.
7815
7816
7817 ~1.07k [2014/03/06]^
7818
7819 Compatibility with package tocloft; and improved compatibility with
7820 class memoir. Novel TOC example in Overview.
7821
7822
7823 ~1.07j [2013/12/03]^
7824
7825 Some issues with the documentation formatting (now two-sided) have been
7826 addressed, and a novel documentation section ``Typesetting the TOC as a
7827 table'' has been added. Very minor code change (\Etoc@readtoc).
7828
7829
7830 ~1.07i [2013/10/21]^
7831
7832 Changes to the \etocmulticolstyle and \etocruledstyle codes
7833 to lessen the risk of a page break after the title (in the one-column case).
7834
7835
7836 ~1.07h [2013/10/16]^
7837
7838 New commands \etocdepthtag.toc, \etocsettagdepth, \etocobeydepthtags,
7839 \etocignoredepthtags.
7840
7841
7842 ~1.07g [2013/10/13]^
7843
7844 New commands \etocsettocdepth, \etocsettocdepth.toc,
7845 \etocobeytoctocdepth, \etoc~-ignoretoctocdepth which
7846 emulate part of tocvsec2 functionality ; measures to
7847 make tocvsec2 partially compatible with etoc.
7848
7849 New commands \etocsetnexttocdepth, \invisibletableofcontents,
7850 \invisiblelocaltableofcontents.
7851
7852 Switched from tikz-qtree to forest for the first `toc as
7853 tree' example.
7854
7855 Command names are linked to their descriptions, and many
7856 other changes in the documentation.
7857
7858 Removed printing of temporary message when the local toc
7859 id is not yet stabilized; indeed \localtableofcontents
7860 can have many uses, such as filling up some token list
7861 register and one may wish to not have anything typeset,
7862 even in an intermediate run.
7863
7864 All of tex etoc.dtx, etex etoc.dtx, xetex etoc.dtx, latex
7865 etoc.dtx, pdflatex etoc.dtx are now possible, and the
7866 extracted file etoc.tex allows easy customization of
7867 compilation options for the documentation (default is via
7868 dvipdfmx which produces the smallest file).
7869
7870
7871 ~1.07f [2013/03/07]^
7872
7873 New macros \etocthelinkedname, \etocthelinkednumber,
7874 \etocthelinkedpage, and \etocthelink.
7875
7876
7877 ~1.07e [2013/03/01]^
7878
7879 Improvements in the package own line styles with
7880 regards to penalties and vertical spaces.
7881
7882 Addition to the documentation of an example of
7883 a tree-like table of contents (uses tikz).
7884
7885 More such examples added 2013/03/03.
7886
7887
7888 ~1.07d [2013/02/24]^
7889
7890 Minor code improvements and new documentation
7891 section ``Another compatibility mode''.
7892
7893
7894 ~1.07b [2013/02/02]^
7895
7896 Removal of the \xspace from the macros \etocname,
7897 \etocnumber, \etocpage.
7898
7899 Additional examples in the documentation.
7900
7901
7902 ~1.07 [2013/01/29]^
7903
7904 New commands:
7905
7906 \etocthename, \etocthenumber, \etocthe~-page, \etoclink,
7907
7908 \etoctoccontentsline, \etoctoccontentsline~lowast
7909
7910 \etocnopar, \etocaftercontentshook
7911
7912 Modified command: \etocmulticolstyle
7913
7914 New documentation section ``Surprising uses of etoc'' which
7915 explains how to do ``Lists of arbitrary things'', in
7916 addition to the tables of contents.
7917
7918
7919 ~1.06 [2012/12/07]^
7920
7921 The standard macros \l@section etc... are modified only
7922 during the calls to \tableofcontents; they can thus be
7923 customized as will by the user (with the help of a
7924 package like tocloft) and this will be taken into account
7925 by etoc for the TOCs typeset in compatibility mode.
7926
7927
7928 ~1.05 [2012/12/01]^
7929
7930 \localtableofcontents replaces \tableofcontents~lowast (for
7931 compatibility with the memoir class).
7932
7933 Compatibility with KOMA-script and memoir document
7934 classes.
7935
7936
7937 ~1.04 [2012/11/24]^
7938
7939 A (possibly local) table of contents can be labeled:
7940
7941 \tableofcontents \label{toc:1}
7942
7943 and reproduced elsewhere in the document (with a possibly
7944 completely different layout):
7945
7946 \tableofcontents \ref{toc:1}
7947
7948
7949 ~1.02 [2012/11/18]^
7950
7951 Initial version.
7952
7953 \end{jfverbatim}
7954 \end{multicols}
7955 \endgroup % group for modified verbatim printing of the changes log
7956
7957 \makeatletter
7958 \let\check@percent\original@check@percent
7959 \makeatother
7960
7961
7962 % Que c'est pénible cette syntaxe \markboth/\markright de LaTeX !
7963 % Pourquoi est-ce que \markright n'a pas été définie comme #1#2-> truc avec #2 ??
7964 \makeatletter
7965 \if@twoside
7966 \renewcommand *{\sectionmark }[1]{%
7967 \markboth
7968 {\unexpanded{{%
7969 % counteract some changes done by my macrocode hooks
7970 % so we must make sure it is in a scope limiting context
7971 % (perhaps it is already, will not check, wasted already
7972 % too much time on this header matter) November 2022
7973 \hypersetup{linkcolor=RoyalBlue}%
7974 \ifodd\value{page}(\hyperref[changelog]{change log},
7975 \hyperlink{FRONTPAGE}{user manual
7976 front page})\hfill\fi
7977 \hyperref[imp]{\thesection. Implementation}%
7978 \ifodd\value{page}\else\hfill(\hyperref[changelog]{change log},
7979 \hyperlink{FRONTPAGE}{user manual
7980 front page})\fi
7981 }}%
7982 }
7983 {\unexpanded{{%
7984 \hypersetup{linkcolor=RoyalBlue}%
7985 \ifodd\value{page}(\hyperref[changelog]{change log},
7986 \hyperlink{FRONTPAGE}{user manual
7987 front page})\hfill\fi
7988 \hyperref[imp]{\thesection. Implementation}%
7989 \ifodd\value{page}\else\hfill(\hyperref[changelog]{change log},
7990 \hyperlink{FRONTPAGE}{user manual
7991 front page})\fi
7992 }}%
7993 }%
7994 }
7995 \else
7996 % faudrait cependant que je réfléchisse à quoi faire exactement en oneside
7997 % mais comme ceci ne peut arriver que si quelqu'un customise etoc.tex
7998 % ce qui n'arrivera JAMAIS, je laisse tomber
7999 \renewcommand *{\sectionmark }[1]{%
8000 \markright
8001 {\unexpanded{{%
8002 \hypersetup{linkcolor=RoyalBlue}%
8003 \ifodd\value{page}(\hyperref[changelog]{change log},
8004 \hyperlink{FRONTPAGE}{user manual
8005 front page})\hfill\fi
8006 \hyperref[imp]{\thesection. Implementation}%
8007 \ifodd\value{page}\else\hfill(\hyperref[changelog]{change log},
8008 \hyperlink{FRONTPAGE}{user manual
8009 front page})\fi
8010 }}%
8011 }%
8012 }
8013 \fi
8014 \makeatother
8015
8016 \section{Implementation}\label{imp}
8017
8018 % ce \noindent est obsolète 2022/08/26 à cause des hooks à macrocode plus bas
8019 % transférés depuis xint.dtx. Il est doublement obsolète car je rajoute un
8020 % paragraphe de texte de toute façon avant le premier macrocode.
8021 % \indent % !!!!!!!!!!!!!!!!! Lundi 09 mars 2015 à 09:32:22
8022 % il faut faire un paragraphe après \section sinon pas d'espacement
8023 % vertical en sortie de blocs macrocode. Pas évident à trouver, vu que
8024 % je customisais différentes choses qui pouvaient affecter macrocode.
8025
8026
8027 % 13 janvier 2024
8028 % On a maintenant le \setstretch{1} dans
8029 % \def\MacroFont{\ttfamily\small\setstretch{1}}
8030 % depuis 28 février 2023. Pas besoin ici du \setstretch{1} car déjà
8031 % fait depuis le début de la \part The code
8032 \makeatletter
8033 \def\macro@font{\ttfamily\small}
8034 \makeatother
8035
8036 % 26 septembre 2021
8037 \catcode1 14 % pour pouvoir utiliser ^^A, car je l'avais mis à \active
8038
8039 \StopEventually{\normalsize
8040 \ifnum\NoSourceCode=1
8041 \texttt{\parindent 0pt\rightskip 1cm minus 1cm
8042 This documentation has been compiled without inclusion of the source
8043 code. To produce the documentation with source code included:\endgraf
8044 \ \ \ \ run etex on etoc.dtx to produce etoc.tex,\endgraf
8045 \ \ \ \ then thrice pdflatex on etoc.tex.\endgraf
8046 }%
8047 \fi
8048 \end{document}}
8049
8050 %%%%%%%%%%%%
8051 % 26 août 2022, transfert depuis xint de hack de doc
8052 %
8053 % This worked remarkably well with almost no changes! Particularly for
8054 % hyperlinking to the documentation part from the macro definitions! But
8055 % also for internall cross-links in implementation part despite no usage
8056 % there of any sectioning mark-up (so I don't need the \@sect hack, and
8057 % related \csa, \csan, \csh, \cshn, \cshintitle, \cshnintitle macros).
8058 % I noticed in passing that I never used any \begin{macro} mark-up here
8059 % in the etoc.dtx. Perhaps I should and should one day look at what doc=V3
8060 % brings...
8061 %
8062 % See xint.dtx for comments, as I have removed most when copying.
8063 \makeatletter
8064 \def\odef #1{\expandafter\def\expandafter#1\expandafter}% needed from xintkernel
8065
8066 %%% etoc.dtx: see further below for how the * is handled in \macro@finish
8067 \renewcommand\lowast{{\iflabelmacro@allowed\xintdocMacrocodeFallbackColorCmd\fi
8068 \raisebox{-.25\height}{*}}}
8069 \AddToHook{env/macrocode/begin}{\makestarlowast}
8070 % https://github.com/latex3/latex2e/issues/563
8071 % (but I don't use sectioning commands in implementation part of etoc.dtx so far)
8072 \AddToHook{env/macrocode/after}{\@nobreakfalse}
8073 \AddToHook{env/macrocode/begin}{\partopsep0pt\relax}
8074 \begingroup
8075 \catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
8076 \catcode`\{=12 \catcode`\}=12
8077 % Let % be active to use a color for it and gray-out
8078 % comments left in code (there are few)
8079 \catcode`\%=13 \catcode`\ =\active \catcode`\\=\active
8080 |gdef|xmacro@code#1% \end{macrocode}[#1|end[macrocode]]
8081 |endgroup
8082 %%% 2022/08/27: for etoc.dtx try to really use comment color in comments
8083 %%% this is not a complete solution, but enough for use case
8084 \begingroup\catcode`\%=\active\catcode`\^^M 13
8085 \gdef%{\begingroup\color{macrocodecommentcolor}^^A
8086 \let\xintdocMacrocodeFallbackColorCmd\@empty^^A
8087 \@percentchar\odef
8088 {\expandafter\endgroup
8089 }}\endgroup
8090 \begingroup\let\newcount\@gobble\@definecounter{CodelineNo}\endgroup
8091 \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}
8092 \def\theHCodelineNo{\the\value{section}.\the\value{CodelineNo}}
8093 %%% not needed for etoc.dtx
8094 %%%%%%% attention j'utilise plus bas \MakePrivateLetters pour
8095 %%%%%%% problème de straight quotes depuis 2023/01/18 (1.1c)
8096 %%% \def\xintMakePrivateLetters{\catcode`: 11 \catcode`? 11 \catcode`@ 11
8097 %%% \catcode`^ 11 \catcode`_ 11 }
8098 %%% \def\xintexprMakePrivateLetters{\xintMakePrivateLetters \catcode`! 11 }
8099 %%% \let\MakePrivateLetters\xintMakePrivateLetters
8100 % \definecolor{etocnamecolor}{RGB}{228,57,0}
8101 % \colorlet{verbcolor}{Maroon}
8102 %
8103 % \colorlet{privatecodecommentscolor}{cyan}
8104 % \colorlet{macrocodecommentcolor}{gray}
8105 % \colorlet{macrocodenewmacrocolor}{verbcolor}
8106 % \colorlet{macrocodelinktouserdoccolor}{etocnamecolor}% and bold face
8107 % \colorlet{macrocodelinktosectioncolor}{DarkBlue}% and bold face
8108 % \colorlet{macrocodelinktocodelinecolor}{DarkBlue}
8109 % \colorlet{macrocodenoncscolor}{Green}
8110 \def\xintdocMacrocodeFallbackColorCmd{\normalcolor}
8111 \odef\init@crossref{\init@crossref%
8112 \everypar{\refstepcounter{CodelineNo}%
8113 \llap{{\xintdocMacrocodeFallbackColorCmd\theCodelineNo}\
8114 \hskip\@totalleftmargin}%
8115 }%
8116 \catcode`\%\active
8117 }%
8118 \def\scan@macro{%
8119 % we do not insert it yet
8120 % \special@escape@char
8121 \step@checksum
8122 % \ifscan@allowed
8123 \let\macro@namepart\@empty
8124 % we need this for reasons explained below
8125 \let\macro@spacepart\@empty
8126 \def\next{\futurelet\next\macro@switch}%
8127 % \else \let\next\@empty \fi
8128 \next
8129 }
8130 % unchanged:
8131 % \def\macro@switch{\ifcat\noexpand\next a%
8132 % \let\next\macro@name
8133 % \else \let\next\short@macro \fi
8134 % \next}
8135 \def\short@macro#1{\special@escape@char#1}
8136 % \def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}%
8137 % \futurelet\next\more@macroname}
8138 % \def\more@macroname{\ifcat\noexpand\next a%
8139 % \let\next\macro@name
8140 % \else \let\next\macro@finish \fi
8141 % \next}
8142 \def\more@macroname{\ifcat\noexpand\next a%
8143 \expandafter\macro@name
8144 % we keep the \next for usage later and start filtering out of the way spaces
8145 % this is caused by necessity of handling things such as \let<space>\foo\bar
8146 % but also not be fooled by \let<space>#6\macro
8147 \else \expandafter\macro@gatherspaces \fi
8148 }
8149 \def\macro@gatherspaces{%
8150 \ifx\next\@xobeysp
8151 \expandafter\macro@gatherspaces@i
8152 \else
8153 \expandafter\macro@finish
8154 \fi}%
8155 \def\macro@gatherspaces@i#1{%
8156 \odef\macro@spacepart{\macro@spacepart#1}% #1 = active space
8157 \futurelet\next\macro@gatherspaces}%
8158 \newif\iflabelmacro@allowed
8159 \newcounter{xintMacroCnt}
8160 %%% pour l'instant pas relevant pour etoc, pas de mark-up par \subsection etc...
8161 \def\xintimplabelprefix{src-}
8162 \let\xintdoclabelprefix\empty
8163 %%% next thing is used in xint.dtx in a hack of \@sect but we don't have so
8164 %%% far sectioning mark-up in etoc.dtx implementation part
8165 %%% \let\xintlabelprefix\xintimplabelprefix
8166 \catcode`_ 11 \catcode`* 11
8167 \def\macro@finish{%
8168 \iflabelmacro@allowed
8169 \expandafter\in@\expandafter{\expandafter.\macro@namepart,}%
8170 {.csname,.expandafter,.noexpand,.else,%
8171 %.t,.w,.x,.y,.z,.XINT_x,.XINT_y,%
8172 %.XINT_tmpa,.XINT_tmpb,.XINT_tmpc,.XINT_tmpd,.XINT_tmpe,% _ is letter here
8173 %.XINT_expr_defbin_b,.XINT_expr_defbin_c,.XINT_expr_defbin_d,%
8174 .empty,.space,.protect,}%
8175 \ifin@
8176 {\xintdocMacrocodeFallbackColorCmd\special@escape@char\macro@namepart}%
8177 \else
8178 \ifcsname alreadydefined-\macro@namepart\endcsname
8179 \hyperref[etocmacro-\macro@namepart]{\special@escape@char\macro@namepart}%
8180 \else
8181 % this will make a rather large number of macro names in the string pool...
8182 \global\expandafter\let\csname alreadydefined-\macro@namepart\endcsname\@empty
8183 \label{etocmacro-\macro@namepart}%
8184 \stepcounter{xintMacroCnt}%
8185 % try to link to a labeled reference in the user documentation (xint-all.pdf)
8186 \ifcsname r@\xintdoclabelprefix\macro@namepart\endcsname
8187 {\hypersetup{linkcolor=macrocodelinktouserdoccolor}%
8188 \hyperref[\xintdoclabelprefix\macro@namepart]%
8189 {\textbf{\special@escape@char\macro@namepart}}}%
8190 \else
8191 % try to link to a labeled section in implementation part
8192 %% THIS BRANCH WILL NEVER BE USED IN etoc.dtx FROM ABSENCE OF
8193 %% ASSOCIATED MARK-UP
8194 \ifcsname r@\xintimplabelprefix\macro@namepart\endcsname
8195 {\hypersetup{linkcolor=macrocodelinktosectioncolor}%
8196 \hyperref[\xintimplabelprefix\macro@namepart]%
8197 {\textbf{\special@escape@char\macro@namepart}}}%
8198 \else
8199 \textcolor{macrocodenewmacrocolor}{\textbf{\special@escape@char\macro@namepart}}%
8200 \fi\fi
8201 \fi
8202 \fi
8203 \labelmacro@allowedfalse
8204 \expandafter\in@\expandafter{\expandafter.\macro@namepart,}{.expandafter,}%
8205 \ifin@
8206 \ifx\next\scan@macro\labelmacro@allowedtrue\fi
8207 \fi
8208 \else % end of labelmacro@allowedtrue branch
8209 %%% etoc.dtx adds complications to handle \newcommand*
8210 \if0\ifx\next\scan@macro0\else\ifx\next\lowast0\else1\fi\fi
8211 \expandafter\in@\expandafter{\expandafter.\macro@namepart,}%
8212 {.def,.edef,.let,.gdef,.xdef,%.odef,.oodef,.fdef,
8213 .chardef,.newif,.newtoks,.newcommand,.DeclareRobustCommand,%
8214 .newread,.newwrite,}%
8215 \ifin@\labelmacro@allowedtrue\fi
8216 \fi
8217 \ifcsname r@etocmacro-\macro@namepart\endcsname
8218 \hyperref[etocmacro-\macro@namepart]{\special@escape@char\macro@namepart}%
8219 \else
8220 {\xintdocMacrocodeFallbackColorCmd\special@escape@char\macro@namepart}%
8221 \fi
8222 \fi
8223 % \ifnot@excluded
8224 % \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}%
8225 % \@tempa
8226 % \fi
8227 \macro@spacepart
8228 }%
8229 \catcode`_ 8 \catcode`* 11
8230 %%% In order mainly to colorize #1, #2, etc... we do this rather
8231 %%% non-economical thing of colorizing all of macrocode with
8232 %%% the "non control sequence color", hence this means all
8233 %%% control sequences will have their own color command...
8234 %%% This is because when doing this in June 2022 for xint, I did
8235 %%% not want to hack more doc.sty scanning process of tokens,
8236 %%% but perhaps I should, it would be more economical. Kept as is
8237 %%% when transferring to etoc.dtx 2022/08/26
8238 {\sbox0{\color{macrocodenoncscolor}\xdef\foo{\current@color}}}
8239 \ifpdf
8240 \edef\xintdoc@macrocode@pushcolor
8241 {\pdfcolorstack\noexpand\@pdfcolorstack push{\foo}\relax}
8242 \def\xintdoc@macrocode@popcolor{\pdfcolorstack\@pdfcolorstack pop\relax}
8243 \else
8244 \ifxetex
8245 \edef\xintdoc@macrocode@pushcolor{\special{color push \foo}}
8246 \def\xintdoc@macrocode@popcolor{\special{color pop}}
8247 \else
8248 \ifnum\Withdvipdfmx=1
8249 \edef\xintdoc@macrocode@pushcolor{\special{color push \foo}}
8250 \def\xintdoc@macrocode@popcolor{\special{color pop}}
8251 \fi\fi\fi
8252 %%% 2022/08/26 \par added for etoc.dtx
8253 \AddToHook{env/macrocode/before}{\xintdoc@macrocode@pushcolor\par}
8254 \AddToHook{env/macrocode/end}{\xintdoc@macrocode@popcolor}
8255 % let's use some more quiet color for links inside the code
8256 \AddToHook{env/macrocode/begin}{\hypersetup{linkcolor=macrocodelinktocodelinecolor}}
8257 % let code line numbers really be fully in the margin
8258 \MacroIndent\z@
8259
8260 % 2023/02/22, 1.2 uses setspace
8261 % 2023/02/27, I return to single line spacing finally
8262 %\AddToHook{env/macrocode/before}{\vskip.5\baselineskip}
8263
8264 \makeatother
8265
8266
8267 % will be used in code comments
8268 % I could re-define \csb, but perhaps better as the mark-up is not yet there
8269 % when I define this to opt for a new name
8270 \makeatletter
8271 \DeclareRobustCommand\csbc[1]{{\hypersetup{linkcolor=macrocodelinktocodelinecolor}%
8272 \ifcsname r@etocmacro-#1\endcsname
8273 \hyperref[etocmacro-#1]{\ttfamily\hyphenchar\font45 \char`\\ #1}%
8274 \else
8275 % for .toc suffixed macros
8276 \ifcsname r@etocmacro-\xintTrimUnbraced{-4}{#1}\endcsname
8277 \hyperref[etocmacro-\xintTrimUnbraced{-4}{#1}]
8278 {\ttfamily\hyphenchar\font45 \char`\\ #1}%
8279 \else
8280 % red color was not enough for me to identify misspelled macro names
8281 % but I should have a warning mechanism, the problem is how to
8282 % have it activated only at right time?
8283 {\fboxsep-\fboxrule\color{Orchid}%
8284 %\fbox{\textcolor{red}{\ttfamily\hyphenchar\font45 \char`\\ #1}}%
8285 \fbox{\ttfamily\hyphenchar\font45 \char`\\ #1}%
8286 }%
8287 % ah ok let's do this (2023/01/22, 1.2)
8288 \ifcsname r@etocmacro-etocname\endcsname
8289 \expanded{\noexpand\AtEndDocument
8290 {\noexpand\PackageError{etoc}{Pas de référence à #1\on@line}%
8291 {Corriger!}
8292 }%
8293 }%
8294 \fi
8295 \fi
8296 \fi }%
8297 }
8298 \makeatother
8299
8300 \setcounter{secnumdepth}{3}
8301
8302 \paragraph{About the syntax highlighting of the code:}
8303 Control\normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
8304 The ``syntax highlighting'' was added at release \etocrelease{1.09f} of 2022/08/30.\par}
8305 sequences are mostly hyperlinks. When a user level command gets defined it
8306 hyperlinks to the user documentation with bold face and
8307 \textbf{\textcolor{macrocodelinktouserdoccolor}{using this colour}}. Further
8308 instances if they occur will use \textcolor{macrocodelinktocodelinecolor}{this
8309 colour} to link to their place of first definition inside the code lines.
8310 Package macros with no user level documentation hyperlink to their first
8311 place of definition in the code.
8312 And such non-user level macros, at the location of
8313 their first definitions will have their names displayed using bold face and
8314 \textbf{\textcolor{macrocodenewmacrocolor}{this colour}} (it is not
8315 an hyperlink then). Comments located \emph{inside} the code source (very little are
8316 left at \etocrelease{1.1a}) have been configured
8317 \textcolor{macrocodecommentcolor}{to be rendered in their own colour}, and
8318 \textcolor{macrocodenoncscolor}{non commented-out and non-control sequences
8319 tokens use this colour}. Other tokens use the fall-back normal colour.
8320 A package macro mentioned in code comments also hyperlinks
8321 to the location of its first definition using
8322 {\textcolor{macrocodelinktocodelinecolor}{this colour}}.
8323
8324 Known limitations:
8325 \begin{enumerate}[nosep]
8326 \item The location of first definition may be disappointing as it may be a
8327 provisory definition.
8328 \item Macros such as \csbc{Etoc@next} are there for matters of code branching
8329 only, and the first encountered definition has no relevant significance.
8330 \item Macros defined using |\csname...\endcsname| or alike constructs are not
8331 detected by the syntax highlighting automatization. Apart from manual
8332 intervention, this appears complex to solve as moreover the macro name may be
8333 there indirectly as an argument such as |#1|.
8334 %%%% This was caused by a ... 2013 oversight in my way of customizing txtt,
8335 %%%% see in preamble near loading of txfonts... fixed 2023/01/18
8336 %%%% \item Bold face has an increased character width, somewhat offsetting the
8337 %%%% codelines alignment.
8338 \end{enumerate}
8339
8340 \paragraph{An apology:}
8341 the code comments served mainly as a record for the author's benefit
8342 of the historical evolution of the package and rarely as a description of what
8343 the macros do. At \etocrelease{1.1a} I have removed almost all code comments which had
8344 accumulated as in a palimpsest. As a result, very few comments actually
8345 remain. \etocrelease{1.1c} re-added comments to those parts of the code which
8346 got refactored at and since \etocrelease{1.1a}, revigorating the
8347 palimpsest stratification.
8348 Some purging done at \etocrelease{1.2e}.
8349
8350 \paragraph{About \etoc and the processing of \texttt{.toc} file data:}
8351 \etoc,%
8352 %
8353 \normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
8354 This paragraph and the next were added very late in the history of the
8355 package, at \etocrelease{1.09h} and later...\par}
8356 %
8357 when not left in compatibility mode, hijacks the \csa{contentsline} expansion
8358 so as to not execute \csa{l@chapter}, \csa{l@section} etc..., but rather to
8359 parse the data and extract from it the \emph{name}, \emph{number}, and
8360 \emph{page number}.
8361 %
8362 The \LaTeX{} |.toc| data
8363 is \emph{not structured}, but contains already typesetting mark-up.
8364 The
8365 \etoc maneuvers to disentangle \emph{name} and \emph{number} are somewhat
8366 fragile as they expect the |.toc| file to contain the
8367 \csa{contentsline} arguments to be arranged in a certain manner.%
8368 %
8369 \normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
8370 ...but transcribe conclusions drawn by author at time of creation.\par}
8371 %
8372 Of course \etoc can be easily broken if changes happen to how data is stored
8373 there. Things would have been much easier for \etoc in 2012 if the
8374 \csa{contentsline} arguments had considered the section titles (aka
8375 \emph{name} for \etoc) and their numbers (which are not numbers in the sense
8376 of things with which \TeX\ can compute, in general) separately, each providing
8377 an argument to \csa{contentsline}. But some mix is prepared, which may depend
8378 on the document class also, and besides usually handles \csa{part} levels very
8379 differently. Fortunately upstream changes happen rarely.%
8380 %
8381 \normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
8382 Prior to \etocrelease{1.1a}, \etoc aliased \csa{l@chapter},
8383 \csa{l@section}, etc... (at the time of TOC typesetting only)
8384 to its own \csbc{Etoc@lxyz} in order to leave time to
8385 \ctanpkg{hyperref} to add its mark-up. Thus the disentangling
8386 of name from number
8387 was more complex than it is now. With \etocrelease{1.1a}, \etoc
8388 leaves \csa{l@chapter} etc... unmodified (and unused) and
8389 only hijacks \csa{contentsline}.}
8390 %
8391
8392 The other core part of \etoc present from day one of the package is that it
8393 creates a tree-like structure of the sectioning levels present in the |.toc|
8394 file. But this is purely virtual, and handled via a notion of ``level'' and
8395 \TeX\ conditionals. It could be fun to implement officially such a tree
8396 (where the children of a sectioning title are the sectioning levels at a
8397 greater depth such as subsections versus a section). Let us recall that
8398 \LaTeX{} provides zero means to know from a subsection for example, what is
8399 the title of the section containing it, or chapter, or part. To do this one
8400 has to create a really structured document which neither core \LaTeX{} nor the
8401 main document classes do. This remark was given for document body, but it
8402 also applies to the |.toc| data. But \etoc adds at least some kind of
8403 follow-up to the successive encountered sectioning titles, and is thus able,
8404 to ``on-the-fly'' add some kind of structure and follow the chaining of
8405 levels. Ultimately this is why the \csbc{etocsetstyle} offers \marg{start}
8406 and \marg{finish} parts in additions to \marg{contents} (which I divided into
8407 a \marg{prefix} and a \marg{contents}). At some point one could imagine that
8408 a really \emph{structured} document (in opposition to what core \LaTeX{} from
8409 thirty years ago up to nowadays realizes) would store in the |.toc| data
8410 directly a tree structure, where each node would have attributes name, number,
8411 page number, completely separated from any typesetting. Once this exists then
8412 basically \etoc disappears. In brief, once \etoc ideas will have permeated
8413 the society, it will disappear as its was born only to palliate the absence of
8414 real structure in the |.toc| file (which is sort of inherited from the absence
8415 of real structure in a \LaTeX{} document body).
8416
8417 % 9 avril 2015 (1.08d) pour forcer indentation après macrocode
8418 % par un effet particulier si avant macrocode un enumerate, inefficient,
8419 % mais vraiment pas envie d'investiguer.
8420 %
8421 % l'esthétique est un peu douteuse mais je laisse ?
8422
8423 % non finalement je supprime
8424
8425 % \makeatletter
8426 % \def\endmacrocode{%
8427 % \ifpm@module \endgroup \pm@modulefalse \fi
8428 % \everypar{}%
8429 % \global\@inlabelfalse
8430 % \endtrivlist\@endpefalse % <<-- ajouté
8431 % \close@crossref}
8432 % \makeatother
8433
8434
8435 % This is obsolete as 1.09g of 2022/11/17 has removed this hack, also
8436 % for colorizing reasons from 1.09n.
8437 % November 2012
8438 % I don't want to have to type at this location (far from the top of the
8439 % file) explicitly the package version or version date, as it is
8440 % inconvenient to have to remember to do this when updating the package.
8441 % Also, I prefer not to add macros to the |.sty| file giving the package
8442 % date, name, or version. So I extracted this from the real macrocode
8443 % environment (leaving out the \init@crossref.)
8444
8445 % The catcode hackery next is to avoid to have <*package> to be listed
8446 % in the commented source code...
8447 % (c) 2012/11/19 jf burnol ;-)
8448
8449 \MakePercentIgnore
8450
8451 %
8452 % \catcode`\<=0 \catcode`\>=11 \catcode`\*=11 \catcode`\/=11
8453 % \let</none>\relax
8454 % \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12}
8455 %
8456 %</none>
8457 %<*package>
8458 % \etocrelease{1.1a} implements a radical change to legacy core internals for
8459 % compatibility with (on-going and in future) \ctanpkg{hyperref} changes. It
8460 % required \LaTeX{} 2020-10-01 (for matters of the \cs{contentsline}
8461 % signature) but this has now been lifted. \etocrelease{1.2} required
8462 % \csa{expanded} primitive, we now test for its existence and provide
8463 % alternative code if it is not provided by the engine.
8464 % \begin{macrocode}
8465 \NeedsTeXFormat{LaTeX2e}[2003/12/01]
8466 \ProvidesPackage{etoc}[2026/05/04 v1.2e Completely customisable TOCs (JFB)]
8467 % \end{macrocode}
8468 % Gentle Info message in the log to mention no testing is done of current
8469 % \etoc on old \LaTeX{} installations.
8470 % \begin{macrocode}
8471 \newif\ifEtoc@oldLaTeX
8472 \@ifl@t@r\fmtversion{2020/10/01}
8473 {}
8474 {\Etoc@oldLaTeXtrue
8475 \PackageInfo{etoc}{Old LaTeX (\fmtversion) detected!\MessageBreak
8476 Since 1.1a (2023/01/14), etoc prefers LaTeX at least\MessageBreak
8477 as recent as 2020-10-01, for reasons of the .toc file,\MessageBreak
8478 and used to require it (from 1.1a to 1.2).\MessageBreak
8479 This etoc (1.2e) does not *require* it, but has not been\MessageBreak
8480 tested thoroughly on old LaTeX (especially if document\MessageBreak
8481 does not use hyperref) and retrofitting was done only\MessageBreak
8482 on basis of author partial remembrances of old context.\MessageBreak
8483 Reported}}
8484 % \end{macrocode}
8485 % \etocrelease{1.2} adds experimental support (only tested with standard
8486 % classes and few packages) for \csbc{locallistoffigures} and
8487 % \csbc{locallistoftables}. See \csbc{Etoc@hackedaddcontentsline} for one
8488 % aspect of this.
8489 %
8490 % Now that \etoc uses package options, I will use \ctanpkg{kvoptions} as I am
8491 % familiar with it. I understand upstream \LaTeX{} now has support for
8492 % key-value input, put I simply have had no time to read the interface.
8493 % Besides not sure it was there for the |2020-10-01| required release.
8494 % \begin{macrocode}
8495 \RequirePackage{kvoptions}
8496 \SetupKeyvalOptions{prefix=Etoc@}
8497 \newif\ifEtoc@lof
8498 \DeclareVoidOption{lof}{\Etoc@loftrue
8499 \PackageInfo{etoc}{Experimental support for \string\locallistoffigures.\MessageBreak
8500 Barely tested, use at own risk}%
8501 }
8502 \newif\ifEtoc@lot
8503 \DeclareVoidOption{lot}{\Etoc@lottrue
8504 \PackageInfo{etoc}{Experimental support for \string\locallistoftables.\MessageBreak
8505 Barely tested, use at own risk}%
8506 }
8507 \@ifclassloaded{memoir}{
8508 \PackageInfo{etoc}
8509 {As this is with memoir class, all `...totoc' options\MessageBreak
8510 are set true by default. Reported}
8511 \DeclareBoolOption[true]{maintoctotoc}
8512 \DeclareBoolOption[true]{localtoctotoc}
8513 \DeclareBoolOption[true]{localloftotoc}
8514 \DeclareBoolOption[true]{locallottotoc}
8515 }{
8516 \DeclareBoolOption[false]{maintoctotoc}
8517 \DeclareBoolOption[false]{localtoctotoc}
8518 \DeclareBoolOption[false]{localloftotoc}
8519 \DeclareBoolOption[false]{locallottotoc}
8520 }
8521 \DeclareBoolOption[true]{ouroboros}
8522 % \end{macrocode}
8523 % The \etocoption{deeplevels} option added at \etocrelease{1.2a}. Adapted
8524 % from an intial patch contributed by Matthew Trescott in the context of
8525 % the \href{https://github.com/doxygen/doxygen}{Doxygen} project.
8526 % It sets the maximum level usable with \csbc{etocsetlevel} (and never
8527 % displayed) at |12| rather than |6|.
8528 % \begin{macrocode}
8529 \DeclareBoolOption[false]{deeplevels}
8530 \DeclareDefaultOption{\PackageWarning{etoc}{Option `\CurrentOption' is unknown.}}
8531 \ProcessKeyvalOptions*
8532 \DisableKeyvalOption[action=error,package=etoc]{etoc}{lof}
8533 \DisableKeyvalOption[action=error,package=etoc]{etoc}{lot}
8534 \DisableKeyvalOption[action=error,package=etoc]{etoc}{deeplevels}
8535 % \end{macrocode}
8536 % For many many years \etoc had no options. Let's be modern and provide an
8537 % \csbc{etocsetup}.
8538 % \begin{macrocode}
8539 \def\etocsetup#1{\setkeys{etoc}{#1}}
8540 \def\etocifmaintoctotoc{\ifEtoc@maintoctotoc
8541 \expandafter\@firstoftwo
8542 \else
8543 \expandafter\@secondoftwo
8544 \fi}
8545 \def\etociflocaltoctotoc{\ifEtoc@localtoctotoc
8546 \expandafter\@firstoftwo
8547 \else
8548 \expandafter\@secondoftwo
8549 \fi}
8550 \def\etociflocalloftotoc{\ifEtoc@localloftotoc
8551 \expandafter\@firstoftwo
8552 \else
8553 \expandafter\@secondoftwo
8554 \fi}
8555 \def\etociflocallottotoc{\ifEtoc@locallottotoc
8556 \expandafter\@firstoftwo
8557 \else
8558 \expandafter\@secondoftwo
8559 \fi}
8560 \RequirePackage{multicol}
8561 \def\etoc@{\etoc@}
8562 \long\def\Etoc@gobtoetoc@ #1\etoc@{}
8563 \newtoks\Etoc@toctoks
8564 %% was using a \csa{def} prior to \etocrelease{1.2e}
8565 \def\etocinline{\let\Etoc@par\@empty}\let\etocnopar\etocinline
8566 \def\etocdisplay{\def\Etoc@par{\par}}
8567 \etocdisplay
8568 % \end{macrocode}
8569 % \csbc{etocglobaldefs} should be used only for special things such as TOC as
8570 % a table; it should be put in a group to limit its scope. If used in the
8571 % preamble, it must come \emph{after} \ctanpkg{tableof} if the latter is
8572 % loaded too.
8573 % \begin{macrocode}
8574 \let\Etoc@global\@empty
8575 \def\etocglobaldefs{\let\Etoc@global\global\let\tof@global\global}
8576 \def\etoclocaldefs {\let\Etoc@global\@empty\let\tof@global\@empty}
8577 % \end{macrocode}
8578 % Some have been renamed at \etocrelease{1.2}.
8579 % \begin{macrocode}
8580 \newif\ifEtoc@numbered
8581 \newif\ifEtoc@hyperref
8582 \newif\ifEtoc@parskip
8583 \newif\ifEtoc@tocwithid
8584 \newif\ifEtoc@standardlines
8585 % \end{macrocode}
8586 % These next three added at \etocrelease{1.2}. The latter two for handling
8587 % compatibility layer with \ctanpkg{tocloft}
8588 % and \ctanpkg{tocbibind}.\par^^A encore ce problème de ligne supp si plein!
8589 % \begin{macrocode}
8590 \newif\ifEtoc@etocstyle
8591 \newif\ifEtoc@classstyle
8592 \newif\ifEtoc@keeporiginaltoc
8593 \newif\ifEtoc@skipprefix
8594 \newif\ifEtoc@isfirst
8595 \newif\ifEtoc@localtoc
8596 \newif\ifEtoc@skipthisone
8597 \newif\ifEtoc@stoptoc
8598 \newif\ifEtoc@notactive
8599 \newif\ifEtoc@mustclosegroup
8600 \newif\ifEtoc@isemptytoc
8601 \newif\ifEtoc@checksemptiness
8602 \def\etocchecksemptiness {\Etoc@checksemptinesstrue }
8603 \def\etocdoesnotcheckemptiness {\Etoc@checksemptinessfalse }
8604 \newif\ifEtoc@notocifnotoc
8605 \def\etocnotocifnotoc {\Etoc@checksemptinesstrue\Etoc@notocifnotoctrue }
8606 \newcounter{etoc@tocid}
8607 \def\Etoc@tocext{toc}
8608 \def\Etoc@lofext{lof}
8609 \def\Etoc@lotext{lot}
8610 \let\Etoc@currext\Etoc@tocext
8611 \def\etocifislocal{\ifEtoc@localtoc\expandafter\@firstoftwo\else
8612 \expandafter\@secondoftwo\fi
8613 }
8614 \def\etocifislocaltoc{\etocifislocal{\ifx\Etoc@currext\Etoc@tocext
8615 \expandafter\@firstoftwo\else
8616 \expandafter\@secondoftwo\fi}%
8617 {\@secondoftwo}%
8618 }
8619 \def\etocifislocallof{\etocifislocal{\ifx\Etoc@currext\Etoc@lofext
8620 \expandafter\@firstoftwo\else
8621 \expandafter\@secondoftwo\fi}%
8622 {\@secondoftwo}%
8623 }
8624 \def\etocifislocallot{\etocifislocal{\ifx\Etoc@currext\Etoc@lotext
8625 \expandafter\@firstoftwo\else
8626 \expandafter\@secondoftwo\fi}%
8627 {\@secondoftwo}%
8628 }
8629 % \end{macrocode}
8630 % Formerly a \LaTeX{} counter |etoc@tocdepth| was declared here but at
8631 % \etocrelease{1.2} it has been replaced by macro storage.\par
8632 % \begin{macrocode}
8633 \expandafter\def\csname Etoc@-3@@\endcsname {-\thr@@}
8634 \expandafter\def\csname Etoc@-2@@\endcsname {-\tw@}
8635 \expandafter\let\csname Etoc@-1@@\endcsname \m@ne
8636 \expandafter\let\csname Etoc@0@@\endcsname \z@
8637 \expandafter\let\csname Etoc@1@@\endcsname \@ne
8638 \expandafter\let\csname Etoc@2@@\endcsname \tw@
8639 \expandafter\let\csname Etoc@3@@\endcsname \thr@@
8640 \expandafter\chardef\csname Etoc@4@@\endcsname 4
8641 \expandafter\chardef\csname Etoc@5@@\endcsname 5
8642 \expandafter\chardef\csname Etoc@6@@\endcsname 6
8643 % \end{macrocode}
8644 % \etocoption{deeplevels} option needs a few extra declarations.
8645 % \begin{macrocode}
8646 \ifEtoc@deeplevels
8647 \expandafter\chardef\csname Etoc@7@@\endcsname 7
8648 \expandafter\chardef\csname Etoc@8@@\endcsname 8
8649 \expandafter\chardef\csname Etoc@9@@\endcsname 9
8650 \expandafter\chardef\csname Etoc@10@@\endcsname 10
8651 \expandafter\chardef\csname Etoc@11@@\endcsname 11
8652 \expandafter\chardef\csname Etoc@12@@\endcsname 12
8653 \fi
8654 % \end{macrocode}
8655 % \etocrelease{1.2a} adds \csbc{Etoc@maxlevel} which replaces formerly
8656 % used \csa{Etoc@@six@@}. It adds also \csbc{etocthemaxlevel} as
8657 % user interface to its explicit numerical value.
8658 % \begin{macrocode}
8659 \expandafter\let\expandafter\Etoc@maxlevel
8660 \csname Etoc@\ifEtoc@deeplevels12\else6\fi @@\endcsname
8661 \edef\etocthemaxlevel{\number\Etoc@maxlevel}
8662 % \end{macrocode}
8663 % For \csbc{etocsetlevel}, \etocrelease{1.2a} uses a comparison with
8664 % \csbc{Etoc@minf} so that only levels suitable for the document class can be
8665 % used. So \etoc now will not define unneeded `book' levelname with numerical
8666 % level |-2| except if with \ctanpkg{memoir}.
8667 % \begin{macrocode}
8668 \@ifclassloaded{memoir}{\def\Etoc@minf{-\thr@@}}{\def\Etoc@minf{-\tw@}}
8669 \let\Etoc@none@@ \Etoc@minf
8670 \expandafter\let\expandafter\Etoc@all@@
8671 \csname Etoc@\ifEtoc@deeplevels11\else5\fi @@\endcsname
8672 % \end{macrocode}
8673 % \csa{Etoc@dolevels} will hold the names of all declared levels
8674 % (independently of their numerical levels), in a traditional
8675 % \LaTeX{} |\do| separated manner, except that for some reason
8676 % I used \csa{Etoc@do}. TODO: maybe use |\do|.
8677 % \begin{macrocode}
8678 \let\Etoc@dolevels\@empty
8679 \def\Etoc@newlevel #1{\expandafter\def\expandafter\Etoc@dolevels\expandafter
8680 {\Etoc@dolevels\Etoc@do{#1}}}
8681 % \end{macrocode}
8682 %
8683 % \etocrelease{1.2} adds here \csbc{etocifunknownlevelTF} and
8684 % \csbc{etoclevel} for a higher level interface, which may be used by third
8685 % parties such as the \ctanpkg{yathesis} class and will allow \etoc at some
8686 % point to modify its internal naming conventions.
8687 %
8688 % The |-\tw@| case needed for \csbc{Etoc@minf} (or for \ctanpkg{memoir}) means
8689 % that two expansions of \csbc{etoclevel} do not always deliver a single
8690 % token, it is at any rate always self-delimiting in assignments and
8691 % \csa{ifnum} tests. I hesitated using only explicit digit tokens by the way.
8692 %
8693 % The dummy sectioning levels ``all'' and ``none'' play a special role and
8694 % will be declared by \csbc{etocifunknownlevelTF} as ``known''.
8695 %
8696 % TODO: is it worthwile to still allow `7' to `12` as level ``names''? This is
8697 % done here for perfact backward compatibility but they have to be excluded
8698 % under \etocoption{deeplevels} option, and it would be better to do something
8699 % not depending on whether that option is used or not.
8700 % \begin{macrocode}
8701 \ifdefined\expanded
8702 \def\etocsetlevel#1#2{\expanded{\noexpand\etoc@setlevel{#1}{#2}}}%
8703 \else
8704 \def\etocsetlevel#1#2{{\edef\Etoc@tmp{\noexpand\etoc@setlevel{#1}{#2}}\expandafter}\Etoc@tmp}%
8705 \fi
8706 \def\etoc@setlevel#1#2{%
8707 \edef\Etoc@tmp{\the\numexpr#2}%
8708 \if1\ifnum\Etoc@tmp>\Etoc@maxlevel0\fi\unless\ifnum\Etoc@minf<\Etoc@tmp;\fi1%
8709 \ifEtoc@deeplevels
8710 \in@{.#1,}{.none,.all,.figure,.table,.-3,.-2,.-1,.0,.1,.2,.3,.4,.5,.6,%
8711 .7,.8,.9,.10,.11,.12,}%
8712 \else
8713 \in@{.#1,}{.none,.all,.figure,.table,.-3,.-2,.-1,.0,.1,.2,.3,.4,.5,.6,}%
8714 \fi
8715 % \end{macrocode}
8716 % Letter or other agnostic test. First time I ever use \csa{@car} as I never
8717 % paid attention to its existence and in more macro-coding intensive context
8718 % such as \ctanpkg{xint} I use my own.
8719 % \begin{macrocode}
8720 \ifin@\else\if\@car#1\@nil @\in@true\fi\fi
8721 \ifin@
8722 \PackageWarning{etoc}
8723 {Sorry, but `#1' is forbidden as level name.\MessageBreak
8724 \if\@car#1\@nil @%
8725 (because of the @ as first character)\MessageBreak\fi
8726 Reported}%
8727 \else
8728 \etocifunknownlevelTF{#1}{\Etoc@newlevel{#1}}{}%
8729 \expandafter\let\csname Etoc@#1@@\expandafter\endcsname
8730 \csname Etoc@\Etoc@tmp @@\endcsname
8731 % \end{macrocode}
8732 % This is to allow ``to toc'' entries to not break the core mechanism
8733 % used to let local tables of contents (now also lists of)
8734 % know their scope, in case for example we have one after the other
8735 % \csbc{localtableofcontents}, \csbc{locallistoffigures},
8736 % \csbc{locallistoftables} and each has created its ``to toc'' entry:
8737 % main TOC will handle the |@<division>| as aliases to |<division>| and local
8738 % TOCs and Lists Of will ignore them.
8739 % \begin{macrocode}
8740 %% TODO: review next code/comment in tagpdf context
8741 %% So we create |@<levelname>| as aliases to |<levelname>|. This is really
8742 %% needed only for the level names actually involved by ``to toc'' thing, but
8743 %% let's do it systematically to avoid implementation complications.
8744 \expandafter\edef\csname Etoc@@#1@@\endcsname
8745 {\expandafter\noexpand\csname Etoc@#1@@\endcsname}%
8746 %% TODO: review next code/comment in tagpdf context
8747 %% As ``to toc'' will use some \csa{addcontentsline}, we must make
8748 %% \ctanpkg{hyperref} happy and also define the suitable |toclevel@| prefixed
8749 %% extra macros.
8750 %% ATTENTION! this means that \csa{toclevel@#1} will exist as \csa{relax} if
8751 %% it did not exist beforehand (and then |\toclevel@@#1->\toclevel#1|).
8752 \expandafter\edef\csname toclevel@@#1\endcsname
8753 {\expandafter\noexpand\csname toclevel@#1\endcsname}%
8754 %% TODO: review next code/comment in tagpdf context
8755 %% But we don't set \ctanpkg{hyperref}'s \csa{toclevel@\string#1} to be
8756 %% numerically \csa{Etoc@tmp}, with some hesitation. The level defined by
8757 %% \csbc{etocsetlevel} should only be for interpretation by \etoc for the
8758 %% contents of the |.toc| file. If it also influences how \ctanpkg{hyperref}
8759 %% hooks into \csa{section} and like commands influence the PDF bookmarks,
8760 %% unexpected results could follow. It is up to user to set-up by themself
8761 %% possibly needed extra \ctanpkg{hyperref} configuration in this regard.
8762 \fi
8763 \else
8764 \PackageWarning{etoc}
8765 {Argument `\detokenize{#2}' of \string\etocsetlevel\space should
8766 represent one of\MessageBreak
8767 \ifnum\Etoc@minf=-\thr@@-2, \fi-1, 0, 1, 2, \ifEtoc@deeplevels ...\else3, 4\fi,
8768 \the\numexpr\Etoc@maxlevel-1, or \number\Etoc@maxlevel\space
8769 but evaluates to \Etoc@tmp.\MessageBreak
8770 The level of `#1' will be set to \number\Etoc@maxlevel.\MessageBreak
8771 Tables of contents will ignore `#1' as long\MessageBreak
8772 as its level is \number\Etoc@maxlevel\space (=\string\etocthemaxlevel).%
8773 \MessageBreak
8774 Reported}%
8775 \etocifunknownlevelTF{#1}{\Etoc@newlevel{#1}}{}%
8776 \expandafter\let\csname Etoc@#1@@\endcsname\Etoc@maxlevel
8777 \fi
8778 }
8779 % \end{macrocode}
8780 % Maybe let it first use \csbc{etocifunknownlevelTF} and raise in the
8781 % ``unknown'' branch a suitable expandable error message (and return say |-3|)?
8782 %
8783 % I may also need for internal usage a variant for only numerical |#1| which be
8784 % submitted to a \csa{the}\csa{numexpr}. Not so far.
8785 %
8786 % Unfortunately the name ``level'' here does not convey to user the fact that
8787 % the argument of \csbc{etocifunknownlevelTF} is a ``name'' not a numerical
8788 % thing.
8789 % \begin{macrocode}
8790 \def\etoclevel#1{\csname Etoc@#1@@\endcsname}
8791 \def\etocthelevel#1{\number\csname Etoc@#1@@\endcsname}
8792 \def\etocifunknownlevelTF#1{\@ifundefined{Etoc@#1@@}}
8793 \@ifclassloaded{memoir}{\etocsetlevel{book}{-2}}{}
8794 \etocsetlevel{part}{-1}
8795 \etocsetlevel{chapter}{0}
8796 \etocsetlevel{section}{1}
8797 \etocsetlevel{subsection}{2}
8798 \etocsetlevel{subsubsection}{3}
8799 \etocsetlevel{paragraph}{4}
8800 \etocsetlevel{subparagraph}{5}
8801 % \end{macrocode}
8802 % Prior to \etocrelease{1.2}, only under class \ctanpkg{memoir} was
8803 % \csbc{etocsetlevel} used with |appendix|. It does not seem to hurt to do it
8804 % generally, with a check whether document class provides chapters.
8805 % \begin{macrocode}
8806 \ifdefined\c@chapter
8807 \etocsetlevel{appendix}{0}
8808 \else
8809 \etocsetlevel{appendix}{1}
8810 \fi
8811 % \end{macrocode}
8812 % The ``to toc'' mechanism will add to the |.toc| file \csa{contentsline} entries
8813 % with first argument such as |@section| or |@subsection|. They will
8814 % generally behave as |section|, resp. |subsection|, etc\dots\ This special
8815 % mark-up is needed for ``to toc'' inclusions to not break the \etoc mechanism
8816 % for delimiting the scope of local tables of contents.
8817 % \begin{macrocode}
8818 \def\Etoc@do#1{\@namedef{l@@#1}{\csname l@#1\endcsname}}
8819 \Etoc@dolevels
8820 % \end{macrocode}
8821 % We do not issue \csbc{etocsetlevel}|{figure}{6}| (or |{12}|) as anyhow the
8822 % \csbc{etocsetlevel} interface forbids |figure| and |table| as first
8823 % argument.
8824 % \begin{macrocode}
8825 \let\Etoc@figure@@\Etoc@maxlevel
8826 \let\Etoc@table@@ \Etoc@maxlevel
8827 % \end{macrocode}
8828 % We can not assume \csa{@gobblethree} exists... hesitation here
8829 % whether to use a \csbc{Etoc@gobblethree} or directly name it
8830 % \csa{@gobblethree}.
8831 % \begin{macrocode}
8832 \let\Etoc@gobblethreeorfour\@gobblefour
8833 \ifdefined\@gobblethree
8834 \let\Etoc@gobblethree\@gobblethree
8835 \else
8836 \long\def\Etoc@gobblethree#1#2#3{}%
8837 \fi
8838 \AtBeginDocument{%
8839 \@ifpackageloaded{parskip}{\Etoc@parskiptrue}{}%
8840 \@ifpackageloaded{hyperref}
8841 {\Etoc@hyperreftrue}
8842 {\ifEtoc@oldLaTeX
8843 \let\Etoc@gobblethreeorfour\Etoc@gobblethree
8844 \let\Etoc@etoccontentsline@fourargs\Etoc@etoccontentsline@
8845 \long\def\Etoc@etoccontentsline@#1#2#3{%
8846 \Etoc@etoccontentsline@fourargs{#1}{#2}{#3}{}%
8847 }%
8848 \fi
8849 }%
8850 }
8851 \def\etocskipfirstprefix {\global\Etoc@skipprefixtrue }
8852 % \end{macrocode}
8853 % Start of heart of \etoc's hacks into the execution of the |.toc| file
8854 % commands. It goes via a redefinition of \csa{contentsline} which will
8855 % launch an extraction process leading to the construction of \csbc{etocname},
8856 % \csbc{etocnumber}, and \csbc{etocpage}, then the styles as defined by user
8857 % via \csbc{etocsetstyle} get executed in accordance to the levels.
8858 %
8859 % In passing \etoc is witness to the linear succession of sectioning levels
8860 % and executes the \marg{start} and \marg{finish} parts of each used level at
8861 % the right time (they are rather called ``|begin|'' and ``|end|'' in the code
8862 % though).
8863 %
8864 % \etocrelease{1.2} did a complete rewrite of how \etoc creates virtually a
8865 % nesting structure out of the flat succession of the \csa{contentsline}'s for
8866 % various levels. Ever since the first release this was based on using
8867 % boolean flags, one for each level. The flag was on if the level had been
8868 % seen, hence its ``begin'' macro executed, but not yet its ``end'' macro.
8869 % This is now replaced by a stack storage \csbc{Etoc@stackofends} which is
8870 % simply, e.g. |{2}{0}{-3}{}|, to mean that first a chapter (|0|) was seen
8871 % then a subsection (|2|). The |{-3}{}| trail is for matters of avoiding
8872 % brace removal in the implementation next (I could have replaced it by a
8873 % single token being numerically |-3|). This structure made implementing the
8874 % \etocoption{deeplevels} painless (but time-consumingly documented) at
8875 % \etocrelease{1.2a}.
8876 %
8877 % When a new level is encountered and set in \csbc{Etoc@level}, it is compared
8878 % to the left most entry in the stack. If higher, the ``begin'' macro is
8879 % executed and the \csbc{Etoc@level} is pushed (as a digit with possibly a
8880 % minus sign) to the left of the stack to record that the ``end'' macro is now
8881 % on the queue for execution (sic). If equal, nothing has to be done, if
8882 % lower, the ``end'' macro of the left-most stored level is executed then this
8883 % level is removed, and one proceeds with the next one, etc... legacy code was
8884 % using a bunch of TeX conditionals rather, and I recall how in 2012 I was
8885 % unfamiliar with its strange syntax and had lots of troubles; once I got
8886 % something working it got frozen and basically did not change since then.
8887 % The \etocrelease{1.2} implementation has replaced all of this by
8888 % maintenance of a single ``stack'', which is more economical in terms of
8889 % used macros and potentially more scalable too.
8890 %
8891 % This (always globally defined) \csbc{Etoc@level} must now never be set to
8892 % the numerical value \texttt{6} (or \texttt{12} if option
8893 % \etocoption{deeplevels}): it is legal to add to the |.toc| file dummy
8894 % sectioning levels associated to the maximal numerical level
8895 % \csbc{etocthemaxlevel} (such dummy sectioning will be ignored but can be
8896 % assigned locally a non-ignored level for special effects) and if
8897 % \csbc{Etoc@level} was, as prior to \etocrelease{1.2}, systematically set to
8898 % the numerical level of the last seen \csa{contentsline}, this could cause
8899 % \csbc{Etoc@@startlocaltoc} to fail to correctly set the ``local top''.
8900 % Indeed it now only has \csbc{Etoc@level} at his disposal, the legacy boolean
8901 % flags being gone.
8902 %
8903 % \begin{macrocode}
8904 \def\Etoc@updatestackofends#1\etoc@{\gdef\Etoc@stackofends{#1}}
8905 \def\Etoc@stackofends{{-3}{}}
8906 \def\Etoc@doendsandbegin{%
8907 \expandafter\Etoc@traversestackofends\Etoc@stackofends\etoc@
8908 }
8909 % \end{macrocode}
8910 % We compare the new level with those for which the \marg{start} parts of the
8911 % \csbc{etocsetstyle} declarations have been executed to decide if it is time
8912 % to execute their \marg{finish} parts. In passing we set the boolean
8913 % \csbc{ifEtoc@isfirst} which is needed for \csbc{etociffirst} and
8914 % \csbc{etocxiffirst}.
8915 % \begin{macrocode}
8916 \def\Etoc@traversestackofends#1{%
8917 \ifnum#1>\Etoc@level
8918 \csname Etoc@end@#1\endcsname
8919 \expandafter\Etoc@traversestackofends
8920 \else
8921 \Etoc@traversestackofends@done{#1}%
8922 \fi
8923 }
8924 \def\Etoc@traversestackofends@done#1#2{#2%
8925 \ifnum#1<\Etoc@level
8926 \csname Etoc@begin@\the\numexpr\Etoc@level\endcsname
8927 \Etoc@global\Etoc@isfirsttrue
8928 \edef\Etoc@tmp{{\the\numexpr\Etoc@level}}%
8929 \else
8930 \Etoc@global\Etoc@isfirstfalse
8931 \let\Etoc@tmp\@empty
8932 \fi
8933 \expandafter\Etoc@updatestackofends\Etoc@tmp{#1}%
8934 }
8935 % \end{macrocode}
8936 % Ever since the first release of \etoc, the code has to be careful that the
8937 % |\Etoc@end@<level>| user defined macros may close groups. This is the reason
8938 % why some assignments have to be done globally (|2015/03/08|).
8939 %
8940 %
8941 % TODO: should this code ensure |#1| is actually a legit level name and if not
8942 % issue some nice error message? This would add system-level overhead only for
8943 % careless people who do not read docs...
8944 % \begin{macrocode}
8945 \def\Etoc@etoccontentsline #1{%
8946 \let\Etoc@next\Etoc@gobblethreeorfour
8947 \ifnum\csname Etoc@#1@@\endcsname=\Etoc@maxlevel
8948 \else
8949 \Etoc@skipthisonefalse
8950 % \end{macrocode}
8951 % MEMO: the mechanism added to make
8952 % added toc entries from ``list of'' titles invisible to the local tocs,
8953 % goes via such a |#1| starting with an |@|. In that case \csa{Etoc@\string#1@@}
8954 % is not a \csa{chardef} but expands to one (or to a count or |-\tw@| perhaps,
8955 % or a |\numexpr...\relax|).
8956 % \begin{macrocode}
8957 \global\expandafter\let\expandafter\Etoc@level\csname Etoc@#1@@\endcsname
8958 % \end{macrocode}
8959 % The trick goes through a slight overhead here to filter out such special
8960 % ``|@|``-level names and not make them update what will serve as top level for
8961 % local tocs or listsof. Formerly this was managed by booleans, then for
8962 % \etocrelease{1.1d} (released as \etocrelease{1.2}) it got replaced by
8963 % sole usage of \csbc{Etoc@level}, and finally a specific
8964 % \csbc{Etoc@virtualtop} which gets its updates here.
8965 % \begin{macrocode}
8966 \if @\@car#1\@nil\else\global\let\Etoc@virtualtop\Etoc@level\fi
8967 \ifEtoc@localtoc
8968 \ifEtoc@stoptoc
8969 \Etoc@skipthisonetrue
8970 \else
8971 \ifEtoc@notactive
8972 \Etoc@skipthisonetrue
8973 \else
8974 \unless\ifnum\Etoc@level>\etoclocaltop
8975 \Etoc@skipthisonetrue
8976 \global\Etoc@stoptoctrue
8977 \fi
8978 \fi
8979 \fi
8980 \fi
8981 \ifEtoc@skipthisone
8982 \else
8983 \unless\ifnum\Etoc@level>\c@tocdepth
8984 \ifEtoc@standardlines
8985 \let\Etoc@next\Etoc@savedcontentsline
8986 \else
8987 \let\Etoc@next\Etoc@etoccontentsline@
8988 \fi
8989 \fi
8990 \fi
8991 \fi
8992 \Etoc@next{#1}%
8993 }
8994 % \end{macrocode}
8995 % Hesitation at \etocrelease{1.2} about having \csbc{Etoc@level} being
8996 % always explicit digit and perhaps negative sign. For now is a
8997 % \csa{chardef} or \csa{m@ne} \csa{count} (perhaps |-\tw@| also).
8998 %
8999 % Memo: \csbc{Etoc@etoccontentsline@} signature is modified at begin document
9000 % in case of old \LaTeX{} and absence of \ctanpkg{hyperref}, so that it
9001 % fetches 3 not 4 arguments and then uses the code here but with an empty fourth
9002 % argument.
9003 % \begin{macrocode}
9004 \def\Etoc@etoccontentsline@ #1#2#3#4{%
9005 \Etoc@doendsandbegin
9006 \Etoc@global\edef\Etoc@prefix {\expandafter\noexpand
9007 \csname Etoc@prefix@\the\numexpr\Etoc@level\endcsname }%
9008 \Etoc@global\edef\Etoc@contents{\expandafter\noexpand
9009 \csname Etoc@contents@\the\numexpr\Etoc@level\endcsname }%
9010 \ifEtoc@skipprefix \Etoc@global\def\Etoc@prefix{\@empty}\fi
9011 \global\Etoc@skipprefixfalse
9012 \gdef\@contentsline@destination{#4}%
9013 \Etoc@lxyz{#2}{#3}{#4}%
9014 \Etoc@prefix
9015 \Etoc@contents
9016 }
9017 % \end{macrocode}
9018 %
9019 % Under |linktoc=page| option, \ctanpkg{hyperref} has a ``feature'' to add one
9020 % level of bracing to first argument of the \csa{l@section} etc macros. So
9021 % for \etoc |<1.1a| this meant some extra work to dig into such a possible
9022 % brace pair to check if the entry was numbered. At \etocrelease{1.1a}, the
9023 % \ctanpkg{hyperref} modified \csa{contentsline} is not executed, hence there
9024 % is no such complication. But the trimming of the now unneeded branches was
9025 % not yet done at \etocrelease{1.1a}, \etocrelease{1.1b}, and got completed
9026 % only at \etocrelease{1.1c}, together with some renamings and refactoring.
9027 % \begin{macrocode}
9028 %% \etocrelease{1.2e} defines \csbc{etochyperlink} as a \csa{protected} wrapper
9029 %% to \csa{hyperlink} and uses it in the \csbc{etocthelinkedname} et al. This
9030 %% allows easier constructs of 2-stages TOC where first pass will use
9031 %% \csa{edef} to prepare some structure.
9032 %% does \long make any sense here?
9033 \long\protected\def\etochyperlink{\hyperlink}%
9034 \def\Etoc@lxyz #1#2#3{%
9035 \Etoc@global\def\etocthepage{#2}%
9036 % \end{macrocode}
9037 % Define \csbc{etocthename} but this will perhaps be adjusted later if it is
9038 % found out that the entry was numbered.
9039 % \begin{macrocode}
9040 \Etoc@global\def\etocthename{#1}%
9041 % \end{macrocode}
9042 % Now we check if the entry is numbered and disentangle the number from the
9043 % name to define correctly \csbc{etocthename} and \csbc{etocthenumber}. The
9044 % delimiter tokens were modified at \etocrelease{1.1c} for a slight
9045 % optimization. And secondary macros have less to do since the
9046 % \etocrelease{1.1a} initiated refactoring.
9047 % \begin{macrocode}
9048 \futurelet\Etoc@getnb@token\Etoc@@getnb #1\hspace\etoc@
9049 % \end{macrocode}
9050 % Even if \csbc{etocthenumber} was let to \csa{@empty}, it may happen in
9051 % special circumstances (related to KOMA-script, see below) that
9052 % \csbc{etocthename} got redefined. We will thus use its current contents to
9053 % define appropriately \csbc{etocthelinkedname}.
9054 %
9055 % In presence of \ctanpkg{hyperref} we let always \csbc{etocthelinkedname} and
9056 % \csbc{etocthelinkednumber} (for a numbered entry) carry an hyperlink. This
9057 % is a \textbf{breaking change} at \etocrelease{1.1a}: formerly if the TOC (or
9058 % the specific entry in the |.toc| file, as it is always possibly to inject
9059 % \csa{hypersetup}) was typeset under |linktoc=none| or |linktoc=page| status,
9060 % then no hyperlinks were incorporated. This is how \csbc{etocthename} and
9061 % \csbc{etocthenumber} are configured, but \csbc{etocthelinkedname} and
9062 % \csbc{etocthelinkednumber} will since \etocrelease{1.1a} always be
9063 % hyperlinked in presence of \ctanpkg{hyperref}.
9064 %
9065 % Prior to \etocrelease{1.1a} an hyperlink was incorporated into
9066 % \csbc{etocthelinkedpage} only if \ctanpkg{hyperref} added an hyperlink to
9067 % the page number, i.e.\@ under |linktoc=page| or |linktoc=all| (and a non
9068 % empty page number). With \etocrelease{1.1a}, the hyperlink is always added
9069 % (if a non empty page number).
9070 %
9071 % In order to facilitate possibly merging at some point the \texttt{tagging}
9072 % dev branch, we keep here some common architecture and thus some aliases here
9073 % with \texttt{tagged} in their names, so that this differs fomr the code of
9074 % the \texttt{tagging} dev branch only via removal of some conditional branches.
9075 % \begin{macrocode}
9076 \ifEtoc@hyperref
9077 %% "tagged" here in case of hyperref means "tagged but not linked"
9078 \Etoc@global\let\etocthetaggedname \etocthename
9079 \Etoc@global\let\etocthetaggedpage \etocthepage
9080 \Etoc@global\let\etocthetaggednumber\etocthenumber
9081 %% \etocthetaggedlink is not public for time being
9082 %% let's define it now and modify below if tagging is active
9083 \Etoc@global\def\etocthetaggedlink##1{\etochyperlink{#3}{##1}}%
9084 \def\Etoc@tmp##1##2{\Etoc@global\def##2{\etochyperlink{#3}{##1}}}%
9085 \expandafter\Etoc@tmp\expandafter{\etocthename}\etocthelinkedname
9086 \expandafter\Etoc@tmp\expandafter{\etocthepage}\etocthelinkedpage
9087 \expandafter\Etoc@tmp\expandafter{\etocthenumber}\etocthelinkednumber
9088 \else
9089 \Etoc@global\let\etocthetaggedlink\@firstofone
9090 \let\etocthelinkedname \etocthename
9091 \let\etocthelinkedpage \etocthepage
9092 \let\etocthelinkednumber\etocthenumber
9093 \Etoc@global\let\etocthetaggedname \etocthelinkedname
9094 \Etoc@global\let\etocthetaggednumber\etocthelinkednumber
9095 \Etoc@global\let\etocthetaggedpage \etocthelinkedpage
9096 \fi
9097 \Etoc@global\let\etocthelink\etocthetaggedlink
9098 \ifx\etocthepage\@empty
9099 \Etoc@global\let\etocthelinkedpage\@empty
9100 \Etoc@global\let\etocthetaggedpage\@empty
9101 \fi
9102 \ifEtoc@numbered\else
9103 %% TODO: It is possible that I added this |\let\etocthenumber\@empty| now and it
9104 %% is in fact superfluous
9105 \let\etocthenumber\@empty
9106 \let\etocthelinkednumber\@empty
9107 \let\etocthetaggednumber\@empty
9108 \fi
9109 % \end{macrocode}
9110 % Defaults in absence of \ctanpkg{hyperref}. We externalize to another
9111 % macro the \ctanpkg{hyperref} case switch.
9112 % \begin{macrocode}
9113 \Etoc@global\expandafter\let\csname etoclink \endcsname \etocthelink
9114 \Etoc@global\expandafter\let\csname etocname \endcsname \etocthetaggedname
9115 \Etoc@global\expandafter\let\csname etocnumber \endcsname\etocthetaggednumber
9116 \Etoc@global\expandafter\let\csname etocpage \endcsname \etocthetaggedpage
9117 \ifEtoc@hyperref
9118 \Etoc@lxyz@linktoc
9119 \fi
9120 }
9121 % \end{macrocode}
9122 % In presence of \ctanpkg{hyperref}, \etoc \etocrelease{1.1a} imports the
9123 % \ctanpkg{hyperref} own logic and tests \csa{Hy@linktoc} to decide if
9124 % \emph{name}, \emph{number} and \emph{page} get hyperlinks. This adds a
9125 % dependency that \csa{Hy@linktoc} should exist and have the expected
9126 % interpretation.
9127 % \begin{macrocode}
9128 \def\Etoc@lxyz@linktoc{%
9129 \ifcase\Hy@linktoc
9130 % \end{macrocode}
9131 % none: nothing to do
9132 % \begin{macrocode}
9133 \or
9134 % \end{macrocode}
9135 % section (aka name for etoc): link name and number
9136 % \begin{macrocode}
9137 \Etoc@global\expandafter\let\csname etocname \endcsname\etocthelinkedname
9138 \Etoc@global\expandafter\let\csname etocnumber \endcsname\etocthelinkednumber
9139 \or % page
9140 \Etoc@global\expandafter\let\csname etocpage \endcsname\etocthelinkedpage
9141 \else % all
9142 \Etoc@global\expandafter\let\csname etocname \endcsname\etocthelinkedname
9143 \Etoc@global\expandafter\let\csname etocnumber \endcsname\etocthelinkednumber
9144 \Etoc@global\expandafter\let\csname etocpage \endcsname\etocthelinkedpage
9145 \fi
9146 }
9147 % \end{macrocode}
9148 % Now for the disentangling of the ``number'' from the ``name''.
9149 %
9150 % At some point we will pick up the first token and check if it is
9151 % \csa{numberline} or like token to identify a numbered entry.
9152 % But this step can cause brace removal so we \csa{futurelet} to
9153 % peek ahead.
9154 %
9155 % Prior to \etocrelease{1.1a} it could be possible that the first token following
9156 % \csbc{Etoc@@getnb} was an opening brace and nevertheless the entry was
9157 % numbered, because of a \ctanpkg{hyperref} ``feature'' in case of
9158 % |linktoc=page| option. But at \etocrelease{1.1a}, \etoc handles directly the argument
9159 % of \csa{contentsline} so the presence of an opening brace implies the entry
9160 % is not numbered.
9161 %
9162 %
9163 % The |@nonbr| means ``no number'', and is not to be misinterpreted as
9164 % ``non braced''... (this was more confusing to the author on return to
9165 % \etoc code, when it still had branches
9166 % handling issues described above with an extra brace pair).
9167 % \begin{macrocode}
9168 \def\Etoc@@getnb {%
9169 \let\Etoc@next\Etoc@getnb
9170 \ifx\Etoc@getnb@token\@sptoken\let\Etoc@next\Etoc@getnb@nonbr\fi
9171 \ifx\Etoc@getnb@token\bgroup \let\Etoc@next\Etoc@getnb@nonbr\fi
9172 \Etoc@next
9173 }
9174 % \end{macrocode}
9175 % \etocrelease{1.08n} tries to handle reasonably the \csa{nonumberline} of
9176 % \ctanpkg{KOMA-script}.
9177 %
9178 % At \etocrelease{1.09f} we avoid including \csa{nonumberline} inside
9179 % \csbc{etocthename} when it the former has empty meaning.
9180 %
9181 % A change at \etocrelease{1.1c} regarding the KOMA-script \csa{nonumberline}
9182 % token: formerly, when it expanded to \csa{numberline}|{}| (this
9183 % can happen only when the TOC is typeset in compatibility mode for
9184 % the global display) then \csbc{ifEtoc@numbered} was set to true.
9185 % But this is only a KOMA-script typesetting thing, and should not
9186 % have influenced \etoc's decisions when its (user or package) own
9187 % line styles are used: at \etocrelease{1.1c} it is thus decided that in such
9188 % circumstances the \csbc{etocifnumbered} will pick the false
9189 % branch, and the empty \csbc{etocthelinkednumber} will not be
9190 % hyperlinked.
9191 %
9192 % No brace removal of the |#1| here a priori possible because we took care to
9193 % check that \csbc{Etoc@getnb} was not followed by either a space or an
9194 % opening brace.
9195 %
9196 % The \csbc{Etoc@@getit} branch for ``Parts'' used to be executed from inside
9197 % \csbc{Etoc@lxyz}. At \etocrelease{1.1c} we jump directly to it from here.
9198 % \begin{macrocode}
9199 \def\Etoc@getnb #1{%
9200 \in@{#1}{\numberline\chapternumberline\partnumberline\booknumberline}%
9201 \ifin@
9202 \let\Etoc@next\Etoc@getnb@nmbrd
9203 \else
9204 \ifnum\Etoc@level=\m@ne
9205 \let\Etoc@next\Etoc@@getit
9206 \else
9207 \let\Etoc@next\Etoc@getnb@nonbr
9208 \fi
9209 % \end{macrocode}
9210 % Remove a KOMA-script \csa{nonumberline} token if present and process the
9211 % entry always as not numbered (see above comments). Prior to \etocrelease{1.1c}, the
9212 % code branched according to the meaning of the \csa{nonumberline} token,
9213 % which was a bit silly.
9214 % \begin{macrocode}
9215 \in@{#1}{\nonumberline}%
9216 \ifin@
9217 \let\Etoc@next\Etoc@getnb@nonumberline
9218 \fi
9219 \fi
9220 \Etoc@next #1%
9221 }
9222 % \end{macrocode}
9223 % Prior to \etocrelease{1.1a}, \csbc{etocthelinkedname} and \csbc{etocthelinkednumber}
9224 % (for a numberd entry) were defined to carry links only if an hyperlink was
9225 % actually found, now they are defined in \csbc{Etoc@lxyz} to always provide
9226 % the hyperlinking to the target heading in the document.
9227 %
9228 %
9229 % \etocrelease{1.1c} fixes here a brace removal bug (which had always been there I
9230 % guess): if the numbered heading was braced, one level of bracing was
9231 % removed. The bug had no effect in a document using \ctanpkg{hyperref} (and
9232 % its default |linktoc| setting) as the \csa{hyperlink} wrapper limited the
9233 % scope. But in a document without hyperref it would have been seen with
9234 % input such as |\section{{\color{blue}Stuff}}|.
9235 % \begin{macrocode}
9236 \def\Etoc@getnb@nmbrd #1#2{%
9237 \Etoc@global\Etoc@numberedtrue
9238 \Etoc@global\def\etocthenumber {#2}%
9239 \Etoc@getnb@nmbrd@getname\@empty
9240 }%
9241 % \end{macrocode}
9242 % We added an \csa{@empty} token to prevent brace removal.
9243 % \begin{macrocode}
9244 \def\Etoc@getnb@nmbrd@getname #1\hspace\etoc@ {%
9245 \Etoc@global\expandafter\def\expandafter\etocthename\expandafter{#1}%
9246 }
9247 % \end{macrocode}
9248 % Not numbered entry.
9249 % \begin{macrocode}
9250 \def\Etoc@getnb@nonbr #1\etoc@ {%
9251 \Etoc@global\Etoc@numberedfalse
9252 \Etoc@global\let\etocthenumber \@empty
9253 }
9254 % \end{macrocode}
9255 % Special KOMA branch: |#1| starts with \csa{nonumberline} (prior to \etocrelease{1.1c}
9256 % the |#1| would have already lost this token, and this branch was executed
9257 % only in case \csa{nonumberline} had empty meaning). We need to remove this
9258 % token from |#1| and redefine \csbc{etocthename}.
9259 %
9260 %
9261 % The \csa{nonumberline} extra token guarantees no brace stripping can happen here.
9262 % \begin{macrocode}
9263 \def\Etoc@getnb@nonumberline #1\hspace\etoc@ {%
9264 \Etoc@global\Etoc@numberedfalse
9265 \Etoc@global\let\etocthenumber \@empty
9266 \Etoc@global\expandafter\def\expandafter\etocthename\expandafter{\@gobble#1}%
9267 }
9268 % \end{macrocode}
9269 % This branch handles the peculiar ``Part'' syntax. No brace stripping
9270 % possible here when grabbing |#1|, due to previous checks that it does
9271 % not start by a space token or an opening brace.
9272 %
9273 % \etocrelease{1.1c} handles this as a sub-branch from \csbc{Etoc@@getnb} which brings
9274 % simplifications. Also the code has been somewhat strengthened so as to
9275 % avoid in later processing a brace removal issue on the name (which was a bug
9276 % of legacy earlier code), when it turns our we are handling a numbered Part
9277 % indeed.
9278 %
9279 % The whole thing is anyhow quite fragile due to \LaTeX{}'s handling by
9280 % standard classes of |.toc| file entries for parts being even more already
9281 % pre-formatted for typesetting than for other levels.
9282 % \begin{macrocode}
9283 \def\Etoc@@getit #1\hspace#2{%
9284 \ifx\etoc@#2%
9285 \Etoc@global\Etoc@numberedfalse
9286 \Etoc@global\let\etocthenumber \@empty
9287 \else
9288 \Etoc@global\Etoc@numberedtrue
9289 \Etoc@global\def\etocthenumber {#1}%
9290 \expandafter\Etoc@getit@getname \expandafter\@empty
9291 \fi
9292 }
9293 % \end{macrocode}
9294 % Chain of \csa{expandafter}'s to get rid of the added \csa{@empty} token to
9295 % avoid a brace removal. And this is the end of the \etocrelease{1.1a} refactoring,
9296 % completed at \etocrelease{1.1c}.
9297 % \begin{macrocode}
9298 \def\Etoc@getit@getname #1\hspace\etoc@ {%
9299 \Etoc@global\expandafter\def\expandafter\etocthename\expandafter{#1}%
9300 }
9301 % \end{macrocode}
9302 % place-holder
9303 % \begin{macrocode}
9304 \let\etocthename \@empty
9305 \let\etocthenumber \@empty
9306 \let\etocthepage \@empty
9307 \let\etocthelinkedname \@empty
9308 \let\etocthelinkednumber \@empty
9309 \let\etocthelinkedpage \@empty
9310 \let\etocthelink \@firstofone
9311 \DeclareRobustCommand*{\etocname} {}
9312 \DeclareRobustCommand*{\etocnumber}{}
9313 \DeclareRobustCommand*{\etocpage} {}
9314 \DeclareRobustCommand*{\etoclink} {\@firstofone}
9315 \DeclareRobustCommand*{\etocifnumbered}
9316 {\ifEtoc@numbered\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
9317 \expandafter\let\expandafter\etocxifnumbered\csname etocifnumbered \endcsname
9318 \DeclareRobustCommand*{\etociffirst}
9319 {\ifEtoc@isfirst\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
9320 \expandafter\let\expandafter\etocxiffirst\csname etociffirst \endcsname
9321 \def\Etoc@readtoc {%
9322 \ifeof \Etoc@tf
9323 \else
9324 \read \Etoc@tf to \Etoc@buffer
9325 \Etoc@toctoks=\expandafter\expandafter\expandafter
9326 {\expandafter\the\expandafter\Etoc@toctoks\Etoc@buffer}%
9327 \expandafter\Etoc@readtoc
9328 \fi
9329 }
9330 % \end{macrocode}
9331 % \etocrelease{1.07m} moves the reading of the toc file At Begin Document. Needed for
9332 % Babel activated characters.\par^^A extra \par needed to avoid empty line...
9333 % \begin{macrocode}
9334 \Etoc@toctoks {}% (superfluous, but for clarity)
9335 \AtBeginDocument{\IfFileExists{\jobname.toc}
9336 {{\endlinechar=\m@ne
9337 \makeatletter
9338 \newread\Etoc@tf
9339 \openin\Etoc@tf\@filef@und
9340 \Etoc@readtoc
9341 \global\Etoc@toctoks=\expandafter{\the\Etoc@toctoks}%
9342 \closein\Etoc@tf}}
9343 {\typeout{No file \jobname.toc.}}}
9344 % \end{macrocode}
9345 % \etocrelease{1.2c} removes a legacy test it had copied over
9346 % from \ctanpkg{hyperref} internals, whose purpose was to check
9347 % if the |.toc| file had been produced in an earlier
9348 % no-hyperref pass, which in the past would trigger
9349 % failure. For specifics see
9350 % \url{https://github.com/latex3/hyperref/issues/305}.
9351 % \begin{macrocode}
9352 \def\Etoc@openouttoc{%
9353 \if@filesw
9354 \newwrite \tf@toc
9355 \immediate \openout \tf@toc \jobname .toc\relax
9356 \fi
9357 \global\let\Etoc@openouttoc\empty
9358 }
9359 % \end{macrocode}
9360 % The |\gdef\Etoc@stackofends{{-3}{}}| is in theory superfluous as normally
9361 % this stack should always have been restored on exit to its initial state,
9362 % but...
9363 %
9364 % It would perhaps be better to issue here \csa{Etoc@notactivetrue}, prior to
9365 % |\the\Etoc@toctoks| but it is up to the caller macros to do it.
9366 % \csbc{Etoc@minf} is a level which is lower (i.e. more encompassing than all
9367 % others), so numerically \texttt{-2} for standard classes and \texttt{-3} for
9368 % \ctanpkg{memoir} class.
9369 %
9370 % The \csbc{Etoc@doendsandbegin} will not try to execute a (non-existing)
9371 % ``begin'' macro for the level \texttt{-3}.
9372 %
9373 % \begin{macrocode}
9374 \def\Etoc@toctoc{%
9375 \gdef\Etoc@stackofends{{-3}{}}%
9376 \global\let\Etoc@level\Etoc@minf
9377 \global\let\Etoc@virtualtop\Etoc@minf
9378 %% for local toc gets done in \csbc{Etoc@@startlocaltoc}/\csbc{Etoc@@startlocallistof}
9379 \the\Etoc@toctoks
9380 \ifEtoc@notactive
9381 \else
9382 \gdef\Etoc@level{-\thr@@}%
9383 \Etoc@doendsandbegin
9384 \fi
9385 }
9386 % \end{macrocode}
9387 % Memo: \csbc{etoclocaltop} has only meaningful meaning when the toc is local
9388 % and is ``active''. Except that I used a "notactive" flag to torture myself,
9389 % so: has the \csbc{ifEtoc@notactive} flag set to |false|.
9390 %
9391 % The \etocrelease{1.2} removal of usage of boolean flags associated to
9392 % the levels has made the next definition more succinct. Their former r\^ole is
9393 % picked up by \csbc{Etoc@level}.
9394 %
9395 % MEMO: the \csbc{etoclocaltableofcontentshook} has been added during development
9396 % \etocrelease{1.2} probably for reasons of symmetry with handling of the
9397 % local ``lists of'' code, but at time of release I can't remember clearly.
9398 % Hesitation where to put it exactly.
9399 %
9400 % \etocrelease{1.2} adds a \csbc{Etoc@@startlocaltochook} for a refactoring of
9401 % \csbc{localtableofcontentswithrelativedepth}. It also serves to make the
9402 % emptiness check with local ``lists of'', as will be seen further down.
9403 % \begin{macrocode}
9404 \def\Etoc@@startlocaltoc#1#2{%
9405 \ifEtoc@localtoc
9406 \ifnum #1=#2\relax
9407 \global\let\etoclocaltop\Etoc@virtualtop
9408 \Etoc@@startlocaltochook
9409 \etoclocaltableofcontentshook
9410 % \end{macrocode}
9411 % The \csbc{ifEtoc@etocstyle} boolean is true when \etoc is left in its default
9412 % mode (no usage of \csbc{etocsettocstyle} or \csbc{etocclasstocstyle}). It
9413 % inhibits \csbc{Etoc@tableofcontents} from using the specified
9414 % \marg{before\string_toc} and \marg{after\string_toc} from usage of
9415 % \csbc{etocsettocstyle}. And here we can insert the code we wish to do the
9416 % title.
9417 %
9418 % \begin{shaded}
9419 % \setstretch{1}%
9420 % \textbf{MEMO}: for legacy reason \etoc shares a lot of code between global TOC and
9421 % local TOCs. But it would probably have been better to separate the two and
9422 % provide an \csa{etocsetlocaltocstyle} that the user can use in preamble.
9423 % As it stands \csbc{etocsettocstyle} if used in preamble also influences the
9424 % global TOC, so basically one has to use it again after it (if it comes first
9425 % in the document).
9426 % \end{shaded}
9427 %
9428 % The \csa{ifEtoc@ouroboros} mechanism when it is set to false appears rather
9429 % audacious.
9430 % \begin{macrocode}
9431 \ifEtoc@etocstyle
9432 \etocetoclocaltocmaketitle
9433 \fi
9434 \ifx\Etoc@aftertitlehook\@empty
9435 \else
9436 \ifEtoc@localtoctotoc
9437 \ifEtoc@ouroboros
9438 \else
9439 \let\Etoc@tmp\contentsline
9440 \def\contentsline{\let\contentsline\Etoc@tmp\Etoc@gobblethreeorfour}%
9441 \fi
9442 \fi
9443 \fi
9444 \global\Etoc@notactivefalse
9445 \fi
9446 \fi
9447 }
9448 \let\etoc@startlocaltoc\@gobble
9449 \let\Etoc@@startlocaltoc@toc\Etoc@@startlocaltoc
9450 \let\Etoc@@startlocaltochook\@empty
9451 \unless\ifEtoc@deeplevels
9452 % \end{macrocode}
9453 % This only hard-codes the built-in \LaTeX\ defaults.
9454 % \begin{macrocode}
9455 \def\etocdivisionnameatlevel#1{%
9456 \ifcase\numexpr#1\relax
9457 \ifdefined\c@chapter chapter\else section\fi%
9458 \or section%
9459 \or subsection%
9460 \or subsubsection%
9461 \or paragraph%
9462 \or subparagraph%
9463 \or empty%
9464 \else\ifnum\numexpr#1<\m@ne
9465 book%
9466 \else
9467 part%
9468 \fi
9469 \fi
9470 }
9471 \else
9472 % \end{macrocode}
9473 % The definition given to \csbc{etocdivisionnameatlevel} in the
9474 % \etocoption{deeplevels} branch is only needed if one wants to locate a
9475 % local table of contents at a deep place, and one has not made use of
9476 % \csbc{etocsettocstyle} to configure the heading by oneself. I have
9477 % used in the default definition the headings as in the
9478 % \href{https://github.com/doxygen/doxygen/}{Doxygen} \LaTeX{} templates
9479 % originating in the
9480 % \href{https://github.com/doxygen/doxygen/pull/9936}{Doxygen\#9936} PR.
9481 % \begin{macrocode}
9482 \def\etocdivisionnameatlevel#1{%
9483 \ifcase\numexpr#1\relax
9484 \ifdefined\c@chapter chapter\else section\fi%
9485 \or section%
9486 \or subsection%
9487 \or subsubsection%
9488 \or subsubsubsection%
9489 \or subsubsubsubsection%
9490 \or subsubsubsubsubsection%
9491 \or subsubsubsubsubsubsection%
9492 \or paragraph%
9493 \or subparagraph%
9494 \else\ifnum\numexpr#1>\z@
9495 empty%
9496 \else\ifnum\numexpr#1=\m@ne
9497 part%
9498 \else
9499 book%
9500 \fi\fi
9501 \fi
9502 }
9503 \fi
9504 \def\etoclocalheadtotoc#1#2{\addcontentsline{toc}{@#1}{#2}}
9505 \def\etocglobalheadtotoc{\addcontentsline{toc}}
9506 % \end{macrocode}
9507 % I have coded this so that it can be copied pasted to a user document and
9508 % customized at will. \etocrelease{1.2a} uses a better test for knowing if
9509 % the starred command of previous line created an inline heading with
9510 % \csa{everypar}: \etocrelease{1.2} simply tested if \csbc{etoclocaltop} was
9511 % at least |3| but this does not scale well with \etocoption{deeplevels}.
9512 % Only worry here is whether the \csa{if@noskipsec} thing really works with
9513 % all document classes. At least it is in \LaTeX{} kernel.\par^^A pénible
9514 % \begin{macrocode}
9515 \providecommand*\UseName{\@nameuse}
9516 \def\etocetoclocaltocmaketitle{%
9517 \UseName{\etocdivisionnameatlevel{\etoclocaltop+1}}*{\localcontentsname}%
9518 \if@noskipsec\leavevmode\par\fi
9519 \etociflocaltoctotoc
9520 {\etocifisstarred
9521 {}% star variant, do not add to toc
9522 {\etoclocalheadtotoc
9523 {\etocdivisionnameatlevel{\etoclocaltop+1}}%
9524 {\localcontentsname}%
9525 }%
9526 }%
9527 {}%
9528 }%
9529 % \end{macrocode}
9530 % In dev, I used \csa{etoc} prefix for the next two, but I
9531 % decided to drop it for release.
9532 % \begin{macrocode}
9533 \def\localcontentsname {\contentsname}%
9534 \let\etoclocaltableofcontentshook\@empty
9535 % \end{macrocode}
9536 % The big thing at \etocrelease{1.2}: experimental support code for
9537 % \csbc{locallistoffigures} and \csbc{locallistoftables}! There were two
9538 % possibilities to implement the `localtoc' mechanism: either add some extra
9539 % things to the |.lof| and |.lot| files, or get their data duplicated in the
9540 % |.toc| file. I have chosen for time being the latter path, hence this goes
9541 % via hacking into \csa{addcontentsline} and it must be the case that the
9542 % document class uses it (from \csa{caption}). If some package has modified
9543 % the implementation of captions of figures and tables and insertes data in
9544 % the |.lof| or |.lot| files directly via \csa{addtocontents} for example
9545 % and not via \csa{addcontentsline}, then the \etoc mechanism will fail.
9546 % \begin{macrocode}
9547 \if1\ifEtoc@lof0\fi\ifEtoc@lot0\fi1%
9548 \else
9549 % \end{macrocode}
9550 % This fixes \etocissue{7}.
9551 % Formerly we did
9552 % \centeredline{|\def\addcontentsline{\Etoc@hackedaddcontentsline}|}
9553 % but this
9554 % change of signature of \csa{addcontentsline} breaks the hyperref way to alter
9555 % \csa{addcontentsline} (but currently |2024/01/09| only if tagpdf
9556 % related code is loaded), as it uses then generic cmd hooks with arguments
9557 % to add its code. Let's not
9558 % complicate things, so we unconditionally use the proper signature. This
9559 % should work independently of whether hyperref adds its hook before or
9560 % after this is executed but actually the kernel applies the cmd hooks
9561 % it seems always both after package ABD code and also after preamble user
9562 % ABD code. So the hyperref cmd/addcontentsline/before will end up inserted
9563 % before the \csbc{Etoc@hackedaddcontentsline} token. It does not matter actually
9564 % because the only aim of our hack is to filter |#1| and take appropriate
9565 % additional action which does not interfere with hyperref hook.
9566 %
9567 % Update |2026/05/04|, this patch had not yet been released and an update to
9568 % \ctanpkg{hyperref} to |7.01q| triggered a user report \etocissue{28}.
9569 % So I de-comment-out the above comments, fix typos in it and release |1.2e|,
9570 % fingers crossed but |git log| on the |master| branch looks fine.
9571 % \begin{macrocode}
9572 \AtBeginDocument{%
9573 \let\Etoc@originaladdcontentsline\addcontentsline
9574 \def\addcontentsline#1#2#3{\Etoc@hackedaddcontentsline{#1}{#2}{#3}}%
9575 }%
9576 \fi
9577 % \end{macrocode}
9578 % For optimization of execution speed we define the macro conditionnally on
9579 % the option status (wihch is frozen). In the first case, |#1=lof,.lot| would
9580 % work but this is not realistic.
9581 % \begin{macrocode}
9582 \ifEtoc@lof
9583 \ifEtoc@lot
9584 \def\Etoc@hackedaddcontentsline#1{%
9585 \expanded{\noexpand\in@{.#1,}}{.lof,.lot,}%
9586 \ifin@\expandafter\Etoc@hackedaddcontentsline@i
9587 \else\expandafter\Etoc@originaladdcontentsline
9588 \fi {#1}}
9589 \else
9590 \def\Etoc@hackedaddcontentsline#1{%
9591 \expanded{\noexpand\in@{.#1,}}{.lof,}%
9592 \ifin@\expandafter\Etoc@hackedaddcontentsline@i
9593 \else\expandafter\Etoc@originaladdcontentsline
9594 \fi {#1}}
9595 \fi
9596 \else
9597 \def\Etoc@hackedaddcontentsline#1{%
9598 \expanded{\noexpand\in@{.#1,}}{.lot,}%
9599 \ifin@\expandafter\Etoc@hackedaddcontentsline@i
9600 \else\expandafter\Etoc@originaladdcontentsline
9601 \fi {#1}}
9602 \fi
9603 % \end{macrocode}
9604 % This business of \csa{protected@file@percent} is not really needed as anyhow
9605 % \etoc reads the |.toc| file with no space token from end of lines.
9606 % \begin{macrocode}
9607 \def\Etoc@hackedaddcontentsline@i#1#2#3{%
9608 \expanded{\noexpand\in@{.#1;#2,}}{.lof;figure,.lot;table,}%
9609 \ifin@
9610 \addtocontents {toc}{%
9611 \protect\contentsline{#2}{#3}{\thepage}{\ifEtoc@hyperref\@currentHref\fi}%
9612 \ifdefined\protected@file@percent\protected@file@percent\fi
9613 }%
9614 \fi
9615 \Etoc@originaladdcontentsline{#1}{#2}{#3}%
9616 }
9617 % \end{macrocode}
9618 % The two macros need to be redefined if \csa{expanded} is not provided by the
9619 % engine. Here we leave some tests done at execution time although they could
9620 % have been done (as above) here at definition time.
9621 % \begin{macrocode}
9622 \unless\ifdefined\expanded
9623 \def\Etoc@hackedaddcontentsline#1{%
9624 {\edef\Etoc@tmp{\noexpand\in@{.#1,}{\[email protected],\fi\[email protected],\fi}}\expandafter}%
9625 \Etoc@tmp
9626 \ifin@\expandafter\Etoc@hackedaddcontentsline@i
9627 \else\expandafter\Etoc@originaladdcontentsline
9628 \fi {#1}%
9629 }
9630 \def\Etoc@hackedaddcontentsline@i#1#2#3{%
9631 {\edef\Etoc@tmp{\noexpand\in@{.#1;#2,}}\expandafter}%
9632 \Etoc@tmp{.lof;figure,.lot;table,}%
9633 \ifin@
9634 \addtocontents {toc}{%
9635 \protect\contentsline{#2}{#3}{\thepage}{\ifEtoc@hyperref\@currentHref\fi}%
9636 \ifdefined\protected@file@percent\protected@file@percent\fi
9637 }%
9638 \fi
9639 \Etoc@originaladdcontentsline{#1}{#2}{#3}%
9640 }
9641 \fi
9642 % \end{macrocode}
9643 % We will simply let \csbc{locallistoffigures} and \csbc{locallistoftables}
9644 % use \csbc{localtableofcontents}. We need some dedicated variant of
9645 % \csbc{Etoc@@startlocaltoc}. Hesitation where to put
9646 % \csbc{Etoc@@startlocaltochook} which has multiple usages.
9647 % \begin{macrocode}
9648 %% #1 is |figure| or |table|
9649 %%
9650 %% TODO: decide if it should be rather `lof' or `lot' rather. But then some
9651 %% auxiliaries must be renamed. For example \csbc{etoclocallistoffigureshook}
9652 %% but unfortunately it is already documented; I am sure noone on Earth has
9653 %% read the docs and those few who did do not use it anyhow.
9654 \def\Etoc@@startlocallistof#1#2#3{%
9655 \ifEtoc@localtoc
9656 \ifnum #2=#3\relax
9657 \global\let\etoclocaltop\Etoc@virtualtop
9658 \global\Etoc@notactivefalse
9659 %% MEMO: this has been configured in \csbc{locallistoffigures} or
9660 %% \csbc{locallistoftables} to trigger \csbc{Etoc@@startlocallistof@setlevels}
9661 %% with |figure| or |table| as argument as it must match the actual first
9662 %% argument of \csa{contentsline} in the |.toc| file. But I see here that the
9663 %% |#1| here is not tied by that.
9664 \Etoc@@startlocaltochook
9665 %% TODO: decide if this next one should be before or after the maketitle It
9666 %% looks odd before, as the maketitle here is executed only in a specific
9667 %% case, which however is the default package configuration to detect
9668 %% appropriate level automatically. If after I could use it to insert the
9669 %% tagging thing. Maybe I need a private one, in addition.
9670 \csname etoclocallistof#1shook\endcsname
9671 \ifEtoc@etocstyle
9672 \csname etocetoclistof#1smaketitle\endcsname
9673 \fi
9674 \fi
9675 \fi
9676 }
9677 \def\Etoc@@startlocallistof@setlevels#1{%
9678 % \end{macrocode}
9679 % |#1| is |figure| or |table|.
9680 %
9681 % \csbc{etoclocaltop} represents the level which will stop the local ``list
9682 % of'' contents. I hesitated whether local ``lists of'' should obey the
9683 % |tocdepth|, especially a varying one. Finally at last minute I opted for
9684 % ``Yes'', so in the end no alteration of |tocdepth| will be done here. We
9685 % will set the level to have value
9686 % \centeredline{|min(1, |\csbc{etoclocaltop}|+1)|}
9687 % At least |1|, because it really would not make
9688 % sense to show figure entries as chapter entries for a local list of figures
9689 % in a Part (if the user has for example set the
9690 % \csbc{etoclocallistoffigureshook} to do nothing, so that the line styles as
9691 % configured via \csbc{etocsetstyle} are not avoided). And it must be greater
9692 % than \csbc{etoclocaltop} else such an entry would terminate the scope of the
9693 % local contents.
9694 %
9695 % In the default context which has issued via
9696 % \csbc{etoclocallistoffigureshook} a local \csbc{etocstandardlines}, the
9697 % actual value of the level only has a ``all or nothing'' meaning: if it is
9698 % greater than |tocdepth| then the \csbc{Etoc@etoccontentsline} will not call
9699 % \csa{contentsline}, else it will and then the code from document class will
9700 % kick in. The |article| class defines \csa{l@figure} as
9701 % \centeredline{|\@dottedtocline {1}{1.5em}{2.3em}|}
9702 % And we are here in a context where necessarily |tocdepth| is at least |1|
9703 % (if it was |0| or less, as the level has been set to at least |1|, the entry
9704 % would have been filtered out earlier by \csbc{Etoc@etoccontentsline}), so
9705 % the line will show. And if \csbc{etoclocallistoffigureshook} was modified
9706 % and did not issue \csbc{etocstandardlines} and we are in this situation that
9707 % the |tocdepth| comparison did not inhibit the entry, then it will show too,
9708 % at least if the line style does not say to do nothing (notice that the \etoc
9709 % fall-back line styles are configured to do nothing for paragraph and
9710 % subparagraph entries).
9711 %
9712 % On the other hand if the |tocdepth| inhibits entries of level
9713 % \csbc{etoclocaltop}|+1|, then a \csbc{localtableofcontents} at this level
9714 % would display no contents, so why should it not also mute
9715 % \csbc{locallistoffigures}?
9716 %
9717 % This change to the level \csbc{Etoc@figure@@} or \csbc{Etoc@table@@} is done
9718 % only locally, no need to worry about collaterals after the ``List of''.
9719 % \begin{macrocode}
9720 \ifnum\etoclocaltop<\z@
9721 \expandafter\let\csname Etoc@#1@@\endcsname\@ne
9722 \else
9723 \expandafter\let\csname Etoc@#1@@\expandafter\endcsname
9724 \csname Etoc@\the\numexpr\etoclocaltop+\@ne @@\endcsname
9725 \fi
9726 % \end{macrocode}
9727 % We now make invisible all level names whose numerical level would have
9728 % allowed them to show in these contents. |figure| and |table| are never
9729 % included in the \csbc{Etoc@dolevels} no danger to cancel them out. The
9730 % special level names |@section| etc... which are inserted by headings of
9731 % local ``lists of'' or local TOCs under \etocoption{localloftotoc} and other
9732 % options have been made invisible by \csbc{Etoc@listofhook}, no need to do
9733 % anything about them here.
9734 % \begin{macrocode}
9735 \def\Etoc@do##1{%
9736 \ifnum\etoclevel{##1}>\etoclocaltop
9737 \expandafter\let\csname Etoc@##1@@\endcsname\Etoc@maxlevel
9738 \fi}%
9739 \Etoc@dolevels
9740 }
9741 % \end{macrocode}
9742 % Let's for time being configure the figure and table lines to be rendered as
9743 % in class default.
9744 %
9745 % Ah, I remember why I added \csbc{etoclocaltableofcontentshook} above. It is
9746 % by symmetry as I had defined those next two already.
9747 % \begin{macrocode}
9748 \def\etoclocallistoffigureshook{\etocstandardlines}
9749 \def\etoclocallistoftableshook {\etocstandardlines}
9750 % \end{macrocode}
9751 % Here is some info about usage of \csbc{etoclocallistoffigureshook}, for
9752 % those who end up here from having clicked on the name from the user
9753 % manual. Its default as above means to use the class default for lines in
9754 % \csa{listoffigures}. If you redefine it to be empty, the effect is that
9755 % (except of course if \csbc{etocstandardlines} has been issued globally) the
9756 % figure lines will adopt the style configured for level
9757 % \csbc{etoclocaltop}|+1| (or more precisely the minimum of that and of |1|).
9758 % You can definitely put into the hook some
9759 % \centeredline{\csbc{etocsetstyle}|{\number\etoclevel{figure}}{}{}{...}{}|}
9760 % where the dots represent some code with \csbc{etocnumber}, \csbc{etocname},
9761 % \csbc{etocpage}, itself possibly querying \csbc{etoclevel}|{figure}|, or
9762 % perhaps \csbc{etoclocaltop} to know the actual depth (which may the one of a
9763 % Part which can thus be distinguished from being in a Chapter, whereas
9764 % \csa{number}\csbc{etoclevel}|{figure}| will give |1| in both cases).
9765 %
9766 % There is variant which is to maintain the default \csbc{etocstandardlines}
9767 % in the hook and then re-define the kernel macro \csa{l@figure} to do the
9768 % desired thing. For example the default with |article| is for \csa{l@figure}
9769 % to do {|\@dottedtocline {1}{1.5em}{2.3em}|} so you can do some variant where
9770 % the second and third argument (indent and numwidth) are set according to
9771 % \csbc{etoclocaltop}.
9772 %
9773 % I hope the above explanations help, they appear too advanced for inclusion
9774 % in the user manual so I give them here.
9775 %
9776 % In dev, I used \csa{etoc} prefix here, but I decided to drop it for release.
9777 % \begin{macrocode}
9778 \def\locallistfigurename{\listfigurename}
9779 \def\locallisttablename {\listtablename}
9780 % \end{macrocode}
9781 % Same observations as for \csbc{etocetoclocaltocmaketitle}.
9782 % \begin{macrocode}
9783 \def\etocetoclistoffiguresmaketitle{%
9784 \UseName{\etocdivisionnameatlevel{\etoclocaltop+1}}*{\locallistfigurename}%
9785 \ifnum\etoclocaltop>\tw@\mbox{}\par\fi
9786 \etociflocalloftotoc
9787 {\etocifisstarred
9788 {}% star variant, do not add to toc
9789 {\etoclocalheadtotoc
9790 {\etocdivisionnameatlevel{\etoclocaltop+1}}%
9791 {\locallistfigurename}%
9792 }%
9793 }%
9794 {}%
9795 }%
9796 \def\etocetoclistoftablesmaketitle{%
9797 \UseName{\etocdivisionnameatlevel{\etoclocaltop+1}}*{\locallisttablename}%
9798 \ifnum\etoclocaltop>\tw@\mbox{}\par\fi
9799 \etociflocallottotoc
9800 {\etocifisstarred
9801 {}% star variant, do not add to toc
9802 {\etoclocalheadtotoc
9803 {\etocdivisionnameatlevel{\etoclocaltop+1}}%
9804 {\locallisttablename}%
9805 }%
9806 }%
9807 {}%
9808 }%
9809 % \end{macrocode}
9810 % The local lists of do support the |\label/\ref| syntax as we are careful
9811 % here to position \csbc{localtableofcontents} as last token.
9812 %
9813 % The reset to \csa{@empty} of the \csa{Etoc@listofreset} is not strictly
9814 % needed as the other things can always be done with no harm.
9815 % \begin{macrocode}
9816 \let\Etoc@listofreset\@empty
9817 % \end{macrocode}
9818 % Memo: \csa{ext@toc} defined in KOMA and memoir but not in the standard classes.
9819 % \begin{macrocode}
9820 \ifEtoc@lof
9821 \def\locallistoffigures{%
9822 \def\Etoc@listofreset{%
9823 \let\Etoc@currext\Etoc@tocext
9824 \let\Etoc@@startlocaltoc\Etoc@@startlocaltoc@toc
9825 \let\Etoc@@startlocaltochook\@empty
9826 \let\Etoc@listofreset\@empty
9827 % \end{macrocode}
9828 % The \csbc{Etoc@listofhook} is executed by \csbc{localtableofcontents}. It
9829 % will be used here to let local ``lists of'' ignore all the special |.toc|
9830 % entries whose level names start with a |@|. This is to avoid the scope
9831 % limiting detection of the local list of figures or tables from being
9832 % influenced by another list of, such as a list of tables following a list of
9833 % figures which has put its title inside the |.toc| due to |locallottotoc|
9834 % option of \etoc.
9835 % \begin{macrocode}
9836 \let\Etoc@listofhook\@empty
9837 }%
9838 \let\Etoc@currext\Etoc@lofext
9839 \def\Etoc@@startlocaltoc{\Etoc@@startlocallistof{figure}}%
9840 \def\Etoc@@startlocaltochook{\Etoc@@startlocallistof@setlevels{figure}}%
9841 \def\Etoc@listofhook{%
9842 \def\Etoc@do####1{%
9843 \expandafter\let\csname Etoc@@####1@@\endcsname\Etoc@maxlevel
9844 }%
9845 \Etoc@dolevels
9846 }%
9847 \localtableofcontents
9848 }
9849 \else
9850 \def\locallistoffigures{%
9851 \PackageError{etoc}{%
9852 \string\locallistoffigures \on@line\space but\MessageBreak
9853 package was loaded without `lof' option}%
9854 {Try again with \string\usepackage[lof]{etoc}}%
9855 }
9856 \fi
9857 \ifEtoc@lot
9858 \def\locallistoftables{%
9859 \def\Etoc@listofreset{%
9860 \let\Etoc@currext\Etoc@tocext
9861 \let\Etoc@@startlocaltoc\Etoc@@startlocaltoc@toc
9862 \let\Etoc@@startlocaltochook\@empty
9863 \let\Etoc@listofreset\@empty
9864 \let\Etoc@listofhook\@empty
9865 }%
9866 \let\Etoc@currext\Etoc@lotext
9867 \def\Etoc@@startlocaltoc{\Etoc@@startlocallistof{table}}%
9868 \def\Etoc@@startlocaltochook{\Etoc@@startlocallistof@setlevels{table}}%
9869 \def\Etoc@listofhook{%
9870 \def\Etoc@do####1{%
9871 \expandafter\let\csname Etoc@@####1@@\endcsname\Etoc@maxlevel
9872 }%
9873 \Etoc@dolevels
9874 }%
9875 \localtableofcontents
9876 }
9877 \else
9878 \def\locallistoftables{%
9879 \PackageError{etoc}{%
9880 \string\locallistoftable \on@line\space but\MessageBreak
9881 package was loaded without `lot' option}%
9882 {Try again with \string\usepackage[lot]{etoc}}%
9883 }
9884 \fi
9885 % \end{macrocode}
9886 % \csbc{Etoc@tocid} is the number of the toc (possibly gotten via a |\ref|
9887 % following a \csbc{tableofcontents}), or it is |\z@| if the emptiness test is
9888 % from a global toc. Until the compilations stabilize, some local TOCs can get
9889 % printed at wrong locations naturally and emptiness tests can not be trusted
9890 % either.
9891 %
9892 % Note: (\etocrelease{1.08i} |2016/09/29|) the code has to handle both local
9893 % and total toc. Hence the flag \csbc{ifEtoc@notactive} has to be set prior
9894 % to it. For a global toc, the \csbc{Etoc@tocid} was set to |\z@|, and the
9895 % |\ifnum| in \csbc{etoc@startlocaltoc} did always fail, but I now prefer to
9896 % simply nullify the \csbc{etoc@startlocaltoc}. As its default fallback is
9897 % |\@gobble| I simply test here for the \csbc{ifEtoc@localtoc} flag. The
9898 % \csbc{Etoc@tocid} will be undefined for a global toc but it is not tested
9899 % anymore.
9900 %
9901 % The initialization such as |\global\let\Etoc@level\Etoc@minf| is needed in
9902 % case the |.toc| file contains an \csbc{etoc@startlocaltoc} before any
9903 % \csa{contentsline}.
9904 %
9905 % Local list of figures and tables set especially the tocdepth and a hook is
9906 % added here for emptiness check to work correctly with them.
9907 %
9908 % MEMO: Should I also execute \csbc{etoclocaltableofcontentshook}?
9909 % Then I would need to set \csbc{etoclocallistoffigureshook} to redefine it,
9910 % rather than be inserted as itself.
9911 % \begin{macrocode}
9912 \def\Etoc@checkifempty {%
9913 \global\Etoc@isemptytoctrue
9914 \global\Etoc@stoptocfalse
9915 \global\let\Etoc@level\Etoc@minf
9916 \global\let\Etoc@virtualtop\Etoc@minf
9917 \gdef\Etoc@stackofends{{-3}{}}%
9918 \begingroup
9919 \ifEtoc@localtoc
9920 \def\etoc@startlocaltoc##1{%
9921 \ifnum##1=\Etoc@tocid\relax
9922 \global\let\etoclocaltop\Etoc@virtualtop
9923 \Etoc@@startlocaltochook
9924 \global\Etoc@notactivefalse
9925 \fi
9926 }%
9927 % \end{macrocode}
9928 % The mechanism is to check if any \csa{contentsline} triggers execution.
9929 % For this we replace the \etoc replacement by another replacement.
9930 % \begin{macrocode}
9931 \let\contentsline\Etoc@testingcontentslinelocal
9932 \else
9933 \let\contentsline\Etoc@testingcontentsline
9934 \fi
9935 \Etoc@storetocdepth
9936 % \end{macrocode}
9937 % This here is a \etocrelease{1.09i} added work-around to avoid usage of
9938 % \csbc{etocsetlocaltop.toc} which could cause the test of emptiness of a
9939 % global TOC to actually execute some start and finish parts in some cases.
9940 % \begin{macrocode}
9941 \let\Etoc@setlocaltop@doendsandbegin\@empty
9942 \the\Etoc@toctoks
9943 \Etoc@restoretocdepth
9944 \endgroup
9945 }
9946 \DeclareRobustCommand*\etocifwasempty
9947 {\ifEtoc@isemptytoc\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi }
9948 \expandafter\let\expandafter\etocxifwasempty\csname etocifwasempty \endcsname
9949 \def\Etoc@testingcontentslinelocal #1{%
9950 \ifEtoc@stoptoc
9951 \else
9952 \ifnum\csname Etoc@#1@@\endcsname=\Etoc@maxlevel
9953 \else
9954 \global\expandafter\let\expandafter\Etoc@level\csname Etoc@#1@@\endcsname
9955 \if @\@car#1\@nil\else\global\let\Etoc@virtualtop\Etoc@level\fi
9956 \ifEtoc@notactive
9957 \else
9958 % \end{macrocode}
9959 % \csbc{ifEtoc@notactive} is \csa{iffalse} in case of a local TOC once it has
9960 % encountered the \csbc{etoc@startlocaltoc} with matching id. So here
9961 % \csbc{etoclocaltop} has been set by \csbc{Etoc@@startlocaltoc} and we
9962 % compare to the new level encountered. If the latter is at most equal to
9963 % \csbc{etoclocaltop} this means the local TOC ends there and is empty, so we
9964 % set the \csbc{ifEtoc@stoptoc} to true, which will cause the subsequent
9965 % parsing to abort immediately. If it is greater we check how it compares to
9966 % the local required toc depth. If lower or equal we conclude the toc is not
9967 % empty, and toggle the flag to stop the parsing; if greater, we are still in
9968 % doubt and must continue.
9969 % \begin{macrocode}
9970 \ifnum\Etoc@level>\etoclocaltop
9971 \unless\ifnum\Etoc@level>\c@tocdepth
9972 \global\Etoc@isemptytocfalse
9973 \global\Etoc@stoptoctrue
9974 \fi
9975 \else
9976 \global\Etoc@stoptoctrue
9977 \fi
9978 \fi
9979 \fi
9980 \fi
9981 % \end{macrocode}
9982 % The \csa{@gobblethree} was added to the \LaTeX{} kernel for its 2020-02-02
9983 % PL 5 release and we require 2020-10-01 since \etocrelease{1.1a}.
9984 % \begin{macrocode}
9985 \Etoc@gobblethreeorfour{}%
9986 }
9987 % \end{macrocode}
9988 % Test of emptiness of the global TOC (according to current setting of the
9989 % levels and a possibly evolving tocdepth).
9990 % \begin{macrocode}
9991 \def\Etoc@testingcontentsline #1{%
9992 \ifEtoc@stoptoc
9993 \else
9994 \ifnum\csname Etoc@#1@@\endcsname=\Etoc@maxlevel
9995 \else
9996 \unless\ifnum\csname Etoc@#1@@\endcsname>\c@tocdepth
9997 \global\Etoc@isemptytocfalse
9998 \global\Etoc@stoptoctrue
9999 \fi
10000 \fi
10001 \fi
10002 \Etoc@gobblethreeorfour{}%
10003 }
10004 % \end{macrocode}
10005 % \etocrelease{1.08e} lets \csbc{localtableofcontents} do a
10006 % first scan of the |.toc| file (as stored in \csbc{Etoc@toctoks}) to
10007 % determine if the table of contents will in fact end up empty. Only,
10008 % however if user has added \csbc{etocchecksemptiness} to document.
10009 %
10010 % If this optional emptiness check is positive, nothing is typeset.
10011 % The command \csbc{etocaftertochook} is still executed though. Other
10012 % ways were envisioned (like delimited macros) to determine this potential
10013 % emptiness, but in the end I opted for execution of the |.toc| file with
10014 % suitable definitions for \csa{contentsline} and
10015 % \csbc{etoc@startlocaltoc}. Notice though that if emptiness would result from
10016 % empty line styles, this can not be detected. Emptiness means ``no
10017 % \csa{contentsline} under the TOC scope''.
10018 %
10019 % For this detection of emptiness, assignments (here and in
10020 % \csbc{Etoc@testingcontentsline}) are made globally, I think this is the best
10021 % (just in case some portions of the |.toc| file turn out to be inside some
10022 % groups --- perhaps for some silly color assignments, etc... --- whose
10023 % boundaries do not necessarily respect unit levels).
10024 %
10025 % The flag \csbc{ifEtoc@tocwithid} discriminates between a \localtoc and a
10026 % \toc|\ref{foo}|; the latter could so far possibly refer to a local or also to
10027 % a global table of contents but release \etocrelease{1.08e} has deprecated the latter use
10028 % as it complicated the code, for something truly silly. Thus |\ref{foo}| must
10029 % now be with |foo| a label of a \emph{local} TOC. As a result \csbc{ifEtoc@tocwithid} is
10030 % less used now.
10031 %
10032 % In the case of a |\ref|ed-to toc whose label was just added hence is not yet
10033 % in the |.aux| file, \csbc{Etoc@tocid} is |0|. \etoc used to issue a warning to
10034 % run latex again and did no printing at all. Release \etocrelease{1.08e} in such cases
10035 % prints the heading (this may gain one compilation step). Emptiness test is
10036 % not executed as it would necessarily turn out positive and can not be
10037 % trusted anyhow. The TOC is declared non empty, which it probably is...
10038 %
10039 % Emptiness detection for local tables of contents (either from a
10040 % \csbc{localtableofcontents} or from a \csbc{tableofcontents}|\ref{localtoc}|)
10041 % can be trusted only when the |.toc| file has stabilized.The emptiness status
10042 % of a local TOC whose Id is not yet in the |.toc| is by necessity undecided
10043 % yet (and not to be trusted really as the numbering may have changed; only
10044 % when compilation runs settle is the emptiness status to be trusted). The
10045 % code declares the TOC non empty, as it will be in 95\% of use cases.
10046 %
10047 % Dropping support for \toc|\ref{globaltoc}| means here that when a TOC id is
10048 % not found in the |.toc| file we can assume it definitely has to be a local
10049 % TOC needing more compilations. The emptiness status is undecided, the code
10050 % declares the TOC non empty.
10051 %
10052 % \etocrelease{1.08i} |2016/09/29| now does \csa{Etoc@localtoctrue} right at the start (the
10053 % earlier code could have to handle table of contents which were actually
10054 % global, via the |\label/\ref| mechanism.) It does not rely on the |\ifnum|
10055 % automatically false in \csbc{Etoc@@startlocaltoc} due to the special values |0|
10056 % or |\z@| for \csbc{Etoc@tocid}, but simply leaves \csbc{etoc@startlocaltoc} to its
10057 % default |\@gobble|. The \csa{Etoc@isemptytocfalse} is upfront in case some
10058 % code using \csbc{etocifwasempty} is in user hooks. The default is to assume the
10059 % TOC non-empty as its contents are actually still unknown. Under the
10060 % \csa{Etoc@stoptoctrue} flag, the \csbc{Etoc@etoccontentsline} is more efficient now.
10061 %
10062 % The \csbc{ifEtoc@notactive} flag needs to be set before calling
10063 % \csbc{Etoc@checkifempty}.
10064 %
10065 % I hesitated with \etocrelease{1.08i} to write something to aux file in order to let
10066 % \LaTeX\ prompt the user for extra pass, after insertion of some new
10067 % \csa{localtableofcontents}, but finally I prefer to only trick \LaTeX\ into
10068 % telling about undefined references.
10069 %
10070 % The \csa{PackageWarning} approach has the advantage
10071 % that at least in Emacs/AUCTeX the |C-cC-c| will propose |LaTeX|, not |View|.
10072 % But perhaps some automated scripts checking |aux| file will not like the
10073 % extra line which is then removed in next pass, and could possibly do one
10074 % extra unneeded compilation to check |aux| file remains identical. Hence the
10075 % second approach. (edit |2017/10/23|: good thing I documented that! I had
10076 % completely forgotten that rationale, but I wonder if it is correct.)
10077 %
10078 % Also the \csa{PackageWarning} does not trigger a visible message
10079 % near the end of the log file or console output, contrarily to a
10080 % \centeredline{|LaTeX Warning: There were undefined references.|}
10081 % followed by a
10082 % \centeredline{|LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.|}
10083 %
10084 % Method used here seems to work fine also with |latexmk|: it does not seem to
10085 % induce it into making too many runs.
10086 % \begin{macrocode}
10087 \def\Etoc@localtableofcontents#1{%
10088 \gdef\etoclocaltop{-\@m}%
10089 \Etoc@localtoctrue
10090 \global\Etoc@isemptytocfalse
10091 \edef\Etoc@tocid{#1}%
10092 \ifnum\Etoc@tocid<\@ne
10093 \setbox0\hbox{\ref{Unknown toc ref \@secondoftwo#1. \space Rerun LaTeX}}%
10094 % \end{macrocode}
10095 % Do only heading, skip all the rest.
10096 % \begin{macrocode}
10097 \global\Etoc@stoptoctrue
10098 \gdef\etoclocaltop{-\thr@@}%
10099 \Etoc@tableofcontents
10100 \expandafter\Etoc@gobtoetoc@
10101 \fi
10102 \global\Etoc@notactivetrue
10103 \ifEtoc@checksemptiness
10104 \Etoc@checkifempty
10105 \fi
10106 \ifEtoc@isemptytoc
10107 \ifEtoc@notactive
10108 \setbox0\hbox{\ref{Unknown toc ID \number\Etoc@tocid. \space Rerun LaTeX}}%
10109 % \end{macrocode}
10110 % Assume real one will be non-empty and print only heading for this pass.
10111 % \begin{macrocode}
10112 \global\Etoc@isemptytocfalse
10113 \global\Etoc@stoptoctrue
10114 \gdef\etoclocaltop{-\thr@@}%
10115 \Etoc@tableofcontents
10116 \expandafter\expandafter\expandafter\Etoc@gobtoetoc@
10117 \fi
10118 \else
10119 \global\Etoc@stoptocfalse
10120 \global\Etoc@notactivetrue
10121 % \end{macrocode}
10122 % We can end up here either if the emptiness check was done and turned
10123 % negative (then \csbc{etoclocaltop} has the correct level for usage in first
10124 % argument of \csbc{etocsettocstyle}), or if the emptiness check was not done.
10125 % For the latter case \csbc{etoclocaltop} has setting |-\@m|.
10126 % \begin{macrocode}
10127 \edef\etoc@startlocaltoc##1%
10128 {\noexpand\Etoc@@startlocaltoc{##1}{\Etoc@tocid}}%
10129 \Etoc@tableofcontents
10130 \fi
10131 \@gobble\etoc@
10132 \endgroup\ifEtoc@mustclosegroup\endgroup\fi
10133 \Etoc@tocdepthreset
10134 \Etoc@listofreset
10135 \etocaftertochook
10136 }% \Etoc@localtableofcontents
10137 % \end{macrocode}
10138 % |2013/03/07|: I discover a \csa{@namedef} trick to construct the
10139 % \csbc{Etoc@again} space delimited macro:\\
10140 % | \@namedef {Etoc@again} {...stuff...}|\\
10141 % Original version was (copied from analogous stuff in |source2e|):\\
10142 % | {\def\1{\Etoc@again}\expandafter\gdef\1 {...stuff...}}|\\
10143 % and in the end (now that I think about it) I simply use \csa{@firstofone}.
10144 %
10145 % \etocrelease{1.2} has a removed a \csa{Etoc@getrefno} as the author now
10146 % knows about \csa{@car} so need to define a similar utility here!
10147 %
10148 % Much more importantly (and embarrassingly) \etocrelease{1.2} fixes a bug
10149 % which had been here for ever. The code in its innocence 2012 birth year
10150 % assumed that the first entry of \csa{r@foo}, if the latter is defined, is
10151 % always numerical! But this is broken by \ctanpkg{varioref} if one used for
10152 % example \csa{vpageref}|{foo}| before! The first brace pair will then be
10153 % |{??}|... causing in \etoc a ``Missing number'' error.
10154 %
10155 % About the current fixed code, there is no strong reason that
10156 % \csbc{Etoc@getref} should work expandably. Later
10157 % \csbc{Etoc@localtableofcontents} does
10158 % \centeredline{|\edef\Etoc@tocid{#1}\iffnum\Etoc@tocid<\@ne|} but I certainly
10159 % could organize things differently.
10160 %
10161 % Maybe I should investigate more on what nasty things car be in
10162 % first argument. Or submit it to an \csa{expanded}?
10163 % \begin{macrocode}
10164 \def\Etoc@getref #1{%
10165 \@ifundefined{r@#1}
10166 {0}
10167 {\expandafter\Etoc@getref@i\romannumeral-`0%
10168 \expandafter\expandafter\expandafter
10169 \@car\csname r@#1\endcsname0\@nil\@etoc
10170 }%
10171 }
10172 \def\Etoc@getref@i#1#2\@etoc{\ifnum9<1\string#1 #1#2\else 0\fi}
10173 \def\Etoc@ref#1{\Etoc@localtableofcontents{\Etoc@getref{#1}}}
10174 \def\Etoc@label#1{\label{#1}\futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
10175 \@firstofone{\def\Etoc@again} {\futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
10176 % \end{macrocode}
10177 % |\ref{foo}| expects |foo| to be a label to a \emph{local} TOC.
10178 %
10179 % The syntax \csbc{localtableofcontents}|\ref{foo}| is supported.
10180 % \begin{macrocode}
10181 \def\Etoc@dothis #1#2\etoc@ {\fi #1}
10182 \def\Etoc@t@bleofcontents{%
10183 \gdef\etoclocaltop{-\@M}%
10184 \ifx\Etoc@nexttoken\label\Etoc@dothis{\expandafter\Etoc@label\@gobble}\fi
10185 \ifx\Etoc@nexttoken\@sptoken\Etoc@dothis{\Etoc@again}\fi
10186 % \end{macrocode}
10187 % \csbc{Etoc@ref} will hand over directly to \csbc{Etoc@localtableofcontents}.
10188 % Argument will be (or rather expand to) zero if the reference is non-existent
10189 % yet.
10190 % \begin{macrocode}
10191 \ifx\Etoc@nexttoken\ref\Etoc@dothis{\expandafter\Etoc@ref\@gobble}\fi
10192 % \end{macrocode}
10193 % Flag to check if we were called from a \csbc{localtableofcontents}.
10194 % \begin{macrocode}
10195 \ifEtoc@tocwithid\Etoc@dothis{\Etoc@localtableofcontents{\c@etoc@tocid}}\fi
10196 % \end{macrocode}
10197 % From now on we are handling a global TOC. Earlier, I used the trick of
10198 % setting \csbc{Etoc@tocid} to |\z@| for compatibility with expansion of
10199 % \csbc{etoc@startlocaltoc}. But since \etocrelease{1.08i} \csbc{etoc@startlocaltoc} is left to be
10200 % |\@gobble|, and \csbc{Etoc@tocid} is never tested. We don't need to set the
10201 % \csbc{ifEtoc@notactive} flag as now \csbc{Etoc@testingcontentsline} tests first the
10202 % \csbc{ifEtoc@localtoc} flag (was already the case of \csbc{Etoc@etoccontentsline}). I change
10203 % a bit the style of conditionals here for clarity of code.
10204 % \begin{macrocode}
10205 \global\Etoc@isemptytocfalse
10206 \ifEtoc@checksemptiness\Etoc@checkifempty\fi
10207 \ifEtoc@isemptytoc
10208 \ifEtoc@notocifnotoc
10209 \expandafter\expandafter\expandafter\@gobble
10210 \fi
10211 \fi
10212 \Etoc@tableofcontents
10213 \endgroup
10214 \ifEtoc@mustclosegroup\endgroup\fi
10215 \Etoc@tocdepthreset
10216 \Etoc@listofreset
10217 \etocaftertochook
10218 \@gobble\etoc@
10219 }% \Etoc@t@bleofcontents
10220 % \end{macrocode}
10221 % \etocrelease{1.08c} does not use |\arabic| in the \csa{addtocontents} since I have seen
10222 % that in some circumstances (for some right to left languages with
10223 % polyglossia or babel), one can not rely on |\arabic| having its default
10224 % definition. As the number written here will be used later in an \csa{ifnum}, I
10225 % should not have used it in the first place (done |2015/03/30|).
10226 % \begin{macrocode}
10227 \def\Etoc@table@fcontents{%
10228 \refstepcounter{etoc@tocid}%
10229 \Etoc@tocwithidfalse
10230 \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents
10231 }
10232 \def\Etoc@localtable@fcontents{%
10233 \refstepcounter{etoc@tocid}%
10234 \addtocontents{toc}{\string\etoc@startlocaltoc{\the\c@etoc@tocid}}%
10235 \Etoc@tocwithidtrue
10236 \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents
10237 }
10238 % \end{macrocode}
10239 % Attention that there could be a |\ref| following, thus we don't yet know
10240 % whether this is a local or global table of contents.
10241 %
10242 % The \csbc{Etoc@tocdepthset} is for \csbc{etocsetnexttocdepth} mechanism.
10243 % \begin{macrocode}
10244 \def\etoctableofcontents{%
10245 \Etoc@openouttoc
10246 \Etoc@tocdepthset
10247 \begingroup
10248 % \end{macrocode}
10249 % This group will be closed in \csbc{Etoc@t@bleofcontents} or
10250 % \csbc{Etoc@localtableofcontents}.
10251 %
10252 % Prior to its release |1.4c|, \ctanpkg{tableof} added a group pair via \csa{tof@begin}
10253 % and \csa{tof@finish}. It was removed at |1.4c|, so no need to do anything now
10254 % here about silencing \csa{tof@begingroup} and \csa{tof@endgroup}: they are
10255 % inserted only in the \ctanpkg{tableof} private copy of the |.toc| file which is
10256 % used by its own table of contents typesetting command.
10257 %
10258 % \etocrelease{1.09b} uses a |\def| in non-starred variant for allowing tricks to
10259 % recognize later on if we are in a starred or non-starred case, whatever the
10260 % user definition of \csbc{etocaftertitlehook} may be.
10261 % \begin{macrocode}
10262 \@ifstar
10263 {\let\Etoc@aftertitlehook\@empty\Etoc@table@fcontents}
10264 {\def\Etoc@aftertitlehook{\etocaftertitlehook}\Etoc@table@fcontents}%
10265 }% \etoctableofcontents
10266 \def\etocifisstarred{\ifx\Etoc@aftertitlehook\@empty
10267 \expandafter\@firstoftwo\else
10268 \expandafter\@secondoftwo
10269 \fi}
10270 \let\etocoriginaltableofcontents\tableofcontents
10271 \let\tableofcontents\etoctableofcontents
10272 % \end{macrocode}
10273 % The \csbc{Etoc@listofhook} is configured by \csbc{locallistoffigures} and
10274 % \csbc{locallistoftables}. The latter two use hooks rather than
10275 % |\begingroup...\endgroup| to manage local configuration, in part because
10276 % they want to support the |\label/\ref| special \etoc mechanism, so need to
10277 % issue \csbc{localtableofcontents} last for it to be able to pick up a
10278 % following |\label| or |\ref|.
10279 % \begin{macrocode}
10280 \let\Etoc@listofhook\@empty
10281 \newcommand*\localtableofcontents{%
10282 \Etoc@openouttoc
10283 \Etoc@tocdepthset
10284 % \end{macrocode}
10285 % This group closed in \csbc{Etoc@t@bleofcontents} or \csbc{Etoc@localtableofcontents}.
10286 % Same comment relative to \ctanpkg{tableof}. No need to do anything here.
10287 % \begin{macrocode}
10288 \begingroup
10289 \Etoc@listofhook
10290 \@ifstar
10291 {\let\Etoc@aftertitlehook\@empty\Etoc@localtable@fcontents}
10292 {\def\Etoc@aftertitlehook{\etocaftertitlehook}\Etoc@localtable@fcontents}%
10293 }% \localtableofcontents
10294 % \end{macrocode}
10295 % \etocrelease{1.09} adds \localtocwrdp. Note that changes to the tocdepth
10296 % from inside the |.toc| file during duration of local toc will remain without
10297 % effect as a substitute is used which gets a frozen non-dynamical value.
10298 %
10299 % It seems \etocrelease{1.09} actually forgot a change to
10300 % \csbc{Etoc@etoccontentsline} and the previous sentence was false and
10301 % described only what happened during the emptiness check which thus could
10302 % give false positives or false negatives. But if I had done the needed
10303 % change in \csbc{Etoc@etoccontentsline} to keep the two in sync, even if
10304 % |tocdepth| evolves from the |.toc| file, I would have created a divergence
10305 % between local TOCs (not only the
10306 % \csbc{localtableofcontentswithrelativedepth} ones) under
10307 % \csbc{etocstandardlines} and those not with standard lines.
10308 %
10309 % Redoing the whole thing at \etocrelease{1.2}. I needed to insert a suitable
10310 % hook in \csbc{Etoc@@startlocaltoc} (and also in the version used by
10311 % \csbc{Etoc@checkifempty}). And I have now at my disposal
10312 % \csbc{Etoc@listofreset} to reset it (it will be expanded after both the
10313 % emptiness check and the typesetting are completed, and at same grouping
10314 % level as the trigger command defined here). I do not want to add tokens
10315 % after \csbc{localtableofcontents} to not break the |\label/\ref| thing,
10316 % which is one reason for this way of proceeding.
10317 % \begin{macrocode}
10318 \newcommand*\localtableofcontentswithrelativedepth[1]{%
10319 \def\Etoc@@startlocaltochook{%
10320 \global\c@tocdepth\numexpr\etoclocaltop+#1\relax
10321 }%
10322 \def\Etoc@listofreset{\let\Etoc@@startlocaltochook\@empty
10323 \let\Etoc@listofreset\@empty}%
10324 \localtableofcontents
10325 }% \localtableofcontentswithrelativedepth
10326 % \end{macrocode}
10327 % Prior to \etocrelease{1.2}, \csbc{Etoc@tableofcontents} was constructed
10328 % by \csbc{etocsettocstyle} as one big macro where |#1| and |#2| had been
10329 % inserted. It now simply stores |#1| and |#2| each in a macro and
10330 % \csbc{Etoc@tableofcontents} is defined once and for all. Also the boolean
10331 % \csbc{ifEtoc@etocstyle} is added which helps keeping the emulation of
10332 % the document class only for the global document TOC but use a better choice
10333 % for local tables of contents (especially those in deeper sub-levels),
10334 % which is activated via \csbc{etocetoclocaltocstyle} (near end of code).
10335 %
10336 % \csbc{etocstoretocstyleinto} added at \etocrelease{1.2}. Too lazy
10337 % to check if |#1| pre-exists. Well, rather, too annoying to do this check
10338 % as one may want to redefine |#1| without further ado.
10339 % \begin{macrocode}
10340 \newcommand\etocsettocstyle[2]{%
10341 \Etoc@etocstylefalse
10342 \Etoc@classstylefalse
10343 \def\Etoc@tableofcontents@user@before{#1}%
10344 \def\Etoc@tableofcontents@user@after {#2}%
10345 }%
10346 \def\etocstoretocstyleinto#1{%
10347 %% \@ifdefinable#1{%
10348 \edef#1{\noexpand\Etoc@etocstylefalse\noexpand\Etoc@classstylefalse
10349 \def\noexpand\Etoc@tableofcontents@user@before{%
10350 \unexpanded\expandafter{\Etoc@tableofcontents@user@before}%
10351 }%
10352 \def\noexpand\Etoc@tableofcontents@user@after{%
10353 \unexpanded\expandafter{\Etoc@tableofcontents@user@after}%
10354 }%
10355 }%
10356 %% }%
10357 }%
10358 % \end{macrocode}
10359 % The macro names added here at \etocrelease{1.2} are provisory (update at
10360 % \etocrelease{1.2e}: this provisory status is lasting long...). Next
10361 % release will probably do a complete renaming of various internals because
10362 % this is currently a complete mess with some names differing only by an |@|
10363 % versus a voyel, but not necessarily being at a deeper level of expansion the
10364 % more |@|'s they have... the deepest one being this \csbc{Etoc@tableofcontents}...
10365 % \begin{macrocode}
10366 \def\Etoc@tableofcontents {%
10367 \Etoc@tableofcontents@etoc@before
10368 \ifEtoc@localtoc\ifEtoc@etocstyle\expandafter\expandafter\expandafter\@gobble\fi\fi
10369 \Etoc@tableofcontents@user@before
10370 \Etoc@tableofcontents@contents
10371 \ifEtoc@localtoc\ifEtoc@etocstyle\expandafter\expandafter\expandafter\@gobble\fi\fi
10372 \Etoc@tableofcontents@user@after
10373 \Etoc@tableofcontents@etoc@after
10374 \@gobble\etoc@
10375 }
10376 \def\Etoc@tableofcontents@etoc@before{%
10377 \ifnum\c@tocdepth>\Etoc@minf
10378 \else
10379 \expandafter\Etoc@gobtoetoc@
10380 \fi
10381 \Etoc@par
10382 \Etoc@beforetitlehook
10383 \etocbeforetitlehook
10384 \Etoc@storetocdepth
10385 \let\Etoc@savedcontentsline\contentsline
10386 \let\contentsline\Etoc@etoccontentsline
10387 \ifEtoc@standardlines
10388 \else
10389 % \end{macrocode}
10390 % \etocrelease{1.1a}'s \csbc{Etoc@lxyz} now fetches 3 not 2 arguments and the
10391 % \csa{l@section} etc... are not |\let| to it anymore, as they used to be here
10392 % formerly.
10393 %
10394 % For backwards compatibility the \csa{etocsavedchaptertocline}
10395 % etc... are still defined but issue a warning since \etocrelease{1.1a}
10396 % and an error since \etocrelease{1.2}.
10397 % \begin{macrocode}
10398 \def\Etoc@do##1{%
10399 \expandafter\def\csname etocsaved##1tocline\endcsname
10400 {\PackageError{etoc}{%
10401 \expandafter\string\csname etocsaved##1tocline\endcsname\space
10402 has been deprecated\MessageBreak
10403 at 1.1a and is removed at 1.2.\MessageBreak
10404 Use \expandafter\string\csname l@##1\endcsname\space directly.\MessageBreak
10405 Reported \on@line}%
10406 {I will use \expandafter\string
10407 \csname l@##1\endcsname\space myself for this time.%
10408 }%
10409 \csname l@##1\endcsname
10410 }%
10411 }%
10412 \Etoc@dolevels
10413 \fi
10414 }%
10415 % \end{macrocode}
10416 % \etocrelease{1.09} makes \csbc{etocsetnexttocdepth} usable in |#1| (but this
10417 % is not 100\% compatible with the emptiness check). It makes an
10418 % \csbc{etoclocaltop} usable in |#1| if under checksemptiness regime.
10419 %
10420 % (|#1| above now means \csbc{Etoc@tableofcontents@user@before} since \etocrelease{1.2})
10421 % \begin{macrocode}
10422 \def\Etoc@tableofcontents@contents{%
10423 \Etoc@tocdepthset
10424 \ifEtoc@parskip\parskip\z@skip\fi
10425 \Etoc@aftertitlehook
10426 % \end{macrocode}
10427 % \etocrelease{1.09} has replaced former \csa{Etoc@localtop} (\emph{minus one}) by
10428 % \csbc{etoclocaltop}. Under checksemptinesstrue regime its value is already
10429 % known, but it will be obtained again from the toc file execution. As it is
10430 % used only if TOC is active, resetting it here this way is decorative and
10431 % could be removed.
10432 % \begin{macrocode}
10433 \gdef\etoclocaltop{-\thr@@}%
10434 \Etoc@toctoc
10435 \etocaftercontentshook
10436 }%
10437 \def\Etoc@tableofcontents@etoc@after{%
10438 %% TODO:
10439 %% this \csa{nobreakfalse} has been here for ages, probably from upstream
10440 %% kernel code, check its status
10441 \@nobreakfalse
10442 \Etoc@restoretocdepth
10443 % \end{macrocode}
10444 % \csa{contentsline} was set to \csbc{Etoc@etoccontentsline} by a non-global |\let|,
10445 % and it will recover its normal value from exiting a scope limiting group.
10446 % But \ctanpkg{tableof} (since |1.4a|) under \csbc{etocglobaldefs} does a global
10447 % redefinition of \csa{contentsline}. Its \csa{tof@finish} then does a global
10448 % restore of \csa{contentsline}, but it will be to the \etoc set
10449 % value. \csa{tof@finish} is active only if either the table of contents was
10450 % typeset using \csa{tableof}, \csa{tablenotof}, \csa{tableoftaggedcontents}, or
10451 % \csa{nextocwithtags} was used. If not active it is either undefined (no
10452 % package \ctanpkg{tableof}) or |\@empty|. Prior to \ctanpkg{tableof} |1.4c|, the
10453 % \csa{tof@finish} closed a group and could be undefined as well, but not if
10454 % \csbc{etocglobaldefs}.
10455 %
10456 % If rather than |\@empty| the \csa{tof@finish} fall-back was |\relax| we could
10457 % use here \csa{@ifundefined} to check in one go (matters of speaking because
10458 % expansion of \csa{@ifundefined} is not in "one-go"). Maybe I should update
10459 % \ctanpkg{tableof}, but for time being I will simply add an extra test. All this is
10460 % probably lots of time on irrelevant issue.
10461 % \begin{macrocode}
10462 \ifx\Etoc@global\global
10463 \@ifundefined{tof@finish}
10464 {}
10465 {\ifx\tof@finish\@empty
10466 \else
10467 \global\let\contentsline\Etoc@savedcontentsline
10468 \fi
10469 }%
10470 \fi
10471 }
10472 % \end{macrocode}
10473 % Refactored at \etocrelease{1.2} to check if the style is actually known
10474 % and its level is from |-1| (|-2| in memoir class) to |5| inclusive.
10475 % If not raise a warning.
10476 %
10477 % \etocrelease{1.2e} adds \csbc{etocsetlinestyle} as alias to
10478 % \csbc{etocsetstyle} and updates all documentation to use it.
10479 % \begin{macrocode}
10480 \def\etocsetstyle#1{\ifcsname Etoc@#1@@\endcsname
10481 \expandafter\Etoc@setstyle@a
10482 \else
10483 \expandafter\Etoc@setstyle@error
10484 \fi {#1}%
10485 }
10486 \let\etocsetlinestyle\etocsetstyle
10487 \def\Etoc@setstyle@error #1{%
10488 \PackageWarning{etoc}{`#1' is unknown to etoc. \space Did you\MessageBreak
10489 forget some \string\etocsetlevel{#1}{<level>}?\MessageBreak
10490 Reported}%
10491 \@gobblefour
10492 }
10493 \def\Etoc@setstyle@a #1{%
10494 \edef\Etoc@tmp{\the\numexpr\csname Etoc@#1@@\endcsname}%
10495 \if1\unless\ifnum\Etoc@tmp<\Etoc@maxlevel 0\fi
10496 \unless\ifnum\Etoc@tmp>\Etoc@minf 0\fi1%
10497 \Etoc@standardlinesfalse
10498 \expandafter\Etoc@setstyle@b\expandafter\Etoc@tmp
10499 \else
10500 \ifnum\Etoc@tmp=\Etoc@maxlevel
10501 \in@{.#1,}{.figure,.table,}%
10502 \ifin@
10503 \PackageWarning{etoc}
10504 {You can not use \string\etocsetlinestyle\space (or
10505 its\MessageBreak
10506 legacy alias \string\etocsetstyle) with `#1'.\MessageBreak
10507 Check the package documentation (in particular about\MessageBreak
10508 \string\etoclocallistoffigureshook/\string\etoclocallistoftableshook)%
10509 \MessageBreak on how to customize
10510 figure and table entries in local\MessageBreak lists. Reported}%
10511 \else
10512 \PackageInfo{etoc}
10513 {Attempt to set the style of `#1',\MessageBreak
10514 whose level is currently the maximal one \etocthemaxlevel,\MessageBreak
10515 which is never displayed. \space This will be ignored\MessageBreak
10516 but note that we do quit compatibility mode.\MessageBreak
10517 Reported}%
10518 \Etoc@standardlinesfalse
10519 \fi
10520 \else
10521 % \end{macrocode}
10522 % This branch was actually in the end only for the case of a level equal to
10523 % |-2|, with a document class not \ctanpkg{memoir}, but \etocrelease{1.2a}
10524 % prevents \csbc{etocsetlevel} to use numerical level |-2| in such case.
10525 % \begin{macrocode}
10526 \PackageWarning{etoc}{This should not happen. Reported}%
10527 \fi
10528 \expandafter\@gobblefour
10529 \fi
10530 }
10531 % \end{macrocode}
10532 % Prior to \etocrelease{1.2} the |#1| here was some alphabetical string
10533 % such as |minusone|. We now use digit tokens (and minus sign) in the macro
10534 % names. The ``begin'' macros formerly incorporated
10535 % \csa{Etoc@global}\csa{Etoc@isfirsttrue}. They are now located in
10536 % \csbc{Etoc@traversestackofends}.
10537 %
10538 % \etocrelease{1.2} adds \csbc{etocstorelinestylesinto}. And
10539 % \csbc{etocstorethislinestyleinto}. No error check on the level.
10540 % \begin{macrocode}
10541 \long\def\Etoc@setstyle@b#1#2#3#4#5{%
10542 \expandafter\def\csname Etoc@begin@#1\endcsname {#2}%
10543 \expandafter\def\csname Etoc@prefix@#1\endcsname {#3}%
10544 \expandafter\def\csname Etoc@contents@#1\endcsname {#4}%
10545 \expandafter\def\csname Etoc@end@#1\endcsname {#5}%
10546 }
10547 \def\Etoc@setstyle@e#1{%
10548 \expandafter\let\csname Etoc@begin@#1\endcsname \@empty
10549 \expandafter\let\csname Etoc@prefix@#1\endcsname \@empty
10550 \expandafter\let\csname Etoc@contents@#1\endcsname \@empty
10551 \expandafter\let\csname Etoc@end@#1\endcsname \@empty
10552 }
10553 \def\Etoc@storelines@a#1{%
10554 \noexpand\Etoc@setstyle@b{#1}%
10555 {\expandafter\Etoc@expandonce\csname Etoc@begin@#1\endcsname}%
10556 {\expandafter\Etoc@expandonce\csname Etoc@prefix@#1\endcsname}%
10557 {\expandafter\Etoc@expandonce\csname Etoc@contents@#1\endcsname}%
10558 {\expandafter\Etoc@expandonce\csname Etoc@end@#1\endcsname}%
10559 }
10560 \def\Etoc@expandonce#1{\unexpanded\expandafter{#1}}
10561 \def\etocstorelinestylesinto#1{%
10562 \edef#1{\Etoc@storelines@a{-2}\Etoc@storelines@a{-1}\Etoc@storelines@a{0}%
10563 \Etoc@storelines@a {1}\Etoc@storelines@a {2}\Etoc@storelines@a{3}%
10564 \Etoc@storelines@a {4}\Etoc@storelines@a {5}%
10565 \ifEtoc@deeplevels
10566 \Etoc@storelines@a{6}\Etoc@storelines@a{7}\Etoc@storelines@a{8}%
10567 \Etoc@storelines@a{9}\Etoc@storelines@a{10}\Etoc@storelines@a{11}%
10568 \fi
10569 }%
10570 }
10571 \def\etocstorethislinestyleinto#1#2{%
10572 \edef#2{\expandafter\Etoc@storelines@a\expandafter{\number\etoclevel{#1}}}%
10573 }%
10574 % \end{macrocode}
10575 % Customization macros of the package default line styles.
10576 % \begin{macrocode}
10577 \def\etocfontminustwo {\normalfont \LARGE \bfseries}
10578 \def\etocfontminusone {\normalfont \large \bfseries}
10579 \def\etocfontzero {\normalfont \large \bfseries}
10580 \def\etocfontone {\normalfont \normalsize \bfseries}
10581 \def\etocfonttwo {\normalfont \normalsize}
10582 \def\etocfontthree {\normalfont \footnotesize}
10583 % \end{macrocode}
10584 % placeholder for comments
10585 % \begin{macrocode}
10586 \def\etocsepminustwo {4ex \@plus .5ex \@minus .5ex}
10587 \def\etocsepminusone {4ex \@plus .5ex \@minus .5ex}
10588 \def\etocsepzero {2.5ex \@plus .4ex \@minus .4ex}
10589 \def\etocsepone {1.5ex \@plus .3ex \@minus .3ex}
10590 \def\etocseptwo {.5ex \@plus .1ex \@minus .1ex}
10591 \def\etocsepthree {.25ex \@plus .05ex \@minus .05ex}
10592 % \end{macrocode}
10593 % placeholder for comments
10594 % \begin{macrocode}
10595 \def\etocbaselinespreadminustwo {1}
10596 \def\etocbaselinespreadminusone {1}
10597 \def\etocbaselinespreadzero {1}
10598 \def\etocbaselinespreadone {1}
10599 \def\etocbaselinespreadtwo {1}
10600 \def\etocbaselinespreadthree {.9}
10601 % \end{macrocode}
10602 % placeholder for comments
10603 % \begin{macrocode}
10604 \def\etocminustwoleftmargin {1.5em plus 0.5fil}
10605 \def\etocminustworightmargin {1.5em plus -0.5fil}
10606 \def\etocminusoneleftmargin {1em}
10607 \def\etocminusonerightmargin {1em}
10608 \def\etoctoclineleaders
10609 {\hbox{\normalfont\normalsize\hb@xt@2ex {\hss.\hss}}}
10610 \def\etocabbrevpagename {p.~}
10611 % \end{macrocode}
10612 % Versions earlier than \etocrelease{1.08b} (and since \etocrelease{1.05} |2012/12/01|) defined
10613 % \csbc{etocpartname} (for use by \etoc's own line styles) to expand to
10614 % \csa{partname}. But this didn't make sense in the context for example of
10615 % \ctanpkg{babel} and \ctanpkg{babel-french}, because \csa{frenchpartname} does things depending on
10616 % the current value of the counter |part|. The code in recent \ctanpkg{babel-french} (but
10617 % not yet |v2.5a| when \csbc{etocpartname} was introduced) constructs control
10618 % sequences \csa{ordinali}, etc... If the part counter is zero, this gives
10619 % \csa{ordinal}. Usually this is not defined, hence no error happens (as it is
10620 % constructed via |\csname|), but under class \ctanpkg{memoir} the bug showed up. All
10621 % this to explain that I found out about this long lasting problem only on
10622 % |2015/03/14|. Probably a sign that \etoc's own line styles are rarely
10623 % used...
10624 % \begin{macrocode}
10625 \def\etocpartname {Part}
10626 \def\etocbookname {Book}
10627 % \end{macrocode}
10628 % \csbc{etocfallbacklines} (\etocrelease{1.2e}) was originally called
10629 % \csbc{etoctoclines}, then for a very long time it was
10630 % \csbc{etocdefaultlines} which still exists with the same meaning. The
10631 % current \csbc{etoctoclines} just does \csa{Etoc@standardlinesfalse}.
10632 %
10633 % Version \etocrelease{1.09f} wraps \csbc{etocbookname}, respectively
10634 % \csbc{etocpartname}, in the book, resp. part, line styles inside a
10635 % (potential) hyperlink together with the number.
10636 %
10637 % \etocrelease{1.2a} does not define a `book' style if not with
10638 % \ctanpkg{memoir} class as the numerical level |-2| is made available only
10639 % with that class.
10640 %
10641 % Unfortunately \csa{@ifclassloaded} was preamble-only until the |2021-11-15|
10642 % LaTeX release (and also \csa{@ifpackageloaded}). Anyway let's refactor this
10643 % \csbc{etocdefaultlines} at \etocrelease{1.2a} to use encapsulating macros
10644 % rather than be a single one with gigantic contents.
10645 % \begin{macrocode}
10646 \def\etocfallbacklines{%
10647 \Etoc@standardlinesfalse
10648 \etocfallbacklines@setbook
10649 \etocfallbacklines@setpart
10650 \etocfallbacklines@setchapter
10651 \etocfallbacklines@setsection
10652 \etocfallbacklines@setsubsection
10653 \etocfallbacklines@setsubsubsection
10654 \etocfallbacklines@setdeeperones
10655 }
10656 \let\etocdefaultlines\etocfallbacklines
10657 % \end{macrocode}
10658 % \etocrelease{1.2b} adds \csb{etocnoprotrusion} as an alias to the
10659 % \LaTeX{} kernel |2018/12/01| command \csa{noprotrusion} which is used since
10660 % that release in \csa{@dottedtocline} after the page number. And it uses it
10661 % in its own default line styles for section and subsection.
10662 % \begin{macrocode}
10663 \def\etocnoprotrusion{\leavevmode\kern-\p@\kern\p@}
10664 \@ifclassloaded{memoir}{%
10665 \def\etocfallbacklines@setbook{%
10666 \Etoc@setstyle@b
10667 {-2}%
10668 {\addpenalty\@M\etocskipfirstprefix}
10669 {\addpenalty\@secpenalty}
10670 {\begingroup
10671 \etocfontminustwo
10672 \addvspace{\etocsepminustwo}%
10673 \parindent \z@
10674 \leftskip \etocminustwoleftmargin
10675 \rightskip \etocminustworightmargin
10676 \parfillskip \@flushglue
10677 \vbox{\etocifnumbered{\etoclink{\etocbookname\enspace\etocthenumber:\quad}}{}%
10678 \etocname
10679 \baselineskip\etocbaselinespreadminustwo\baselineskip
10680 \par}%
10681 \addpenalty\@M\addvspace{\etocsepminusone}%
10682 \endgroup}
10683 {}%
10684 }
10685 }{\let\etocfallbacklines@setbook\@empty}
10686 \def\etocfallbacklines@setpart{%
10687 \Etoc@setstyle@b
10688 {-1}%
10689 {\addpenalty\@M\etocskipfirstprefix}
10690 {\addpenalty\@secpenalty}
10691 {\begingroup
10692 \etocfontminusone
10693 \addvspace{\etocsepminusone}%
10694 \parindent \z@
10695 \leftskip \etocminusoneleftmargin
10696 \rightskip \etocminusonerightmargin
10697 \parfillskip \@flushglue
10698 \vbox{\etocifnumbered{\etoclink{\etocpartname\enspace\etocthenumber.\quad}}{}%
10699 \etocname
10700 \baselineskip\etocbaselinespreadminusone\baselineskip
10701 \par}%
10702 \addpenalty\@M\addvspace{\etocsepzero}%
10703 \endgroup}
10704 {}%
10705 }
10706 % \end{macrocode}
10707 % No need to worry about left protrusion activation and the delicacies of
10708 % \csa{leftprotrusion} from \ctanpkg{microtype}, as the paragraph indentation
10709 % here is nil. So, no changes at \etocrelease{1.2b}.
10710 % \begin{macrocode}
10711 \def\etocfallbacklines@setchapter{%
10712 \Etoc@setstyle@b
10713 {0}%
10714 {\addpenalty\@M\etocskipfirstprefix}
10715 {\addpenalty\@itempenalty}
10716 {\begingroup
10717 \etocfontzero
10718 \addvspace{\etocsepzero}%
10719 \parindent \z@ \parfillskip \@flushglue
10720 \vbox{\etocifnumbered{\etocnumber.\enspace}{}\etocname
10721 \baselineskip\etocbaselinespreadzero\baselineskip
10722 \par}%
10723 \endgroup}
10724 {\addpenalty{-\@highpenalty}\addvspace{\etocsepminusone}}%
10725 }
10726 % \end{macrocode}
10727 % This is now very old code, dating back to earliest releases, and looks
10728 % a bit too convoluted. There was probably a better way with suitable
10729 % \csa{nobreak} and |\null| trick. But I am too old to revisit these things
10730 % now. And, by the way, as paragraph indentation is zeroed, no need to worry
10731 % about perhaps activating explictly protrusion on the left.
10732 % \begin{macrocode}
10733 \def\etocfallbacklines@setsection{%
10734 \Etoc@setstyle@b
10735 {1}%
10736 {\addpenalty\@M\etocskipfirstprefix}
10737 {\addpenalty\@itempenalty}
10738 {\begingroup
10739 \etocfontone
10740 \addvspace{\etocsepone}%
10741 \parindent \z@ \parfillskip \z@
10742 \setbox\z@\vbox{\parfillskip\@flushglue
10743 \etocname\par
10744 \setbox\tw@\lastbox
10745 \global\setbox\@ne\hbox{\unhbox\tw@\ }}%
10746 \dimen\z@=\wd\@ne
10747 \setbox\z@=\etoctoclineleaders
10748 \advance\dimen\z@\wd\z@
10749 \etocifnumbered
10750 {\setbox\tw@\hbox{\etocnumber, \etocabbrevpagename\etocpage\etocnoprotrusion}}
10751 {\setbox\tw@\hbox{\etocabbrevpagename\etocpage\etocnoprotrusion}}%
10752 \advance\dimen\z@\wd\tw@
10753 \ifdim\dimen\z@ < \linewidth
10754 \vbox{\etocname~%
10755 \leaders\box\z@\hfil\box\tw@
10756 \baselineskip\etocbaselinespreadone\baselineskip
10757 \par}%
10758 \else
10759 \vbox{\etocname~%
10760 \leaders\copy\z@\hfil\break
10761 \hbox{}\leaders\box\z@\hfil\box\tw@
10762 \baselineskip\etocbaselinespreadone\baselineskip
10763 \par}%
10764 \fi
10765 \endgroup}
10766 {\addpenalty\@secpenalty\addvspace{\etocsepzero}}%
10767 }
10768 \def\etocfallbacklines@setsubsection{%
10769 \Etoc@setstyle@b
10770 {2}%
10771 {\addpenalty\@medpenalty\etocskipfirstprefix}
10772 {\addpenalty\@itempenalty}
10773 {\begingroup
10774 \etocfonttwo
10775 \addvspace{\etocseptwo}%
10776 \parindent \z@ \parfillskip \z@
10777 \setbox\z@\vbox{\parfillskip\@flushglue
10778 \etocname\par\setbox\tw@\lastbox
10779 \global\setbox\@ne\hbox{\unhbox\tw@}}%
10780 \dimen\z@=\wd\@ne
10781 \setbox\z@=\etoctoclineleaders
10782 \advance\dimen\z@\wd\z@
10783 \etocifnumbered
10784 {\setbox\tw@\hbox{\etocnumber, \etocabbrevpagename\etocpage\etocnoprotrusion}}
10785 {\setbox\tw@\hbox{\etocabbrevpagename\etocpage\etocnoprotrusion}}%
10786 \advance\dimen\z@\wd\tw@
10787 \ifdim\dimen\z@ < \linewidth
10788 \vbox{\etocname~%
10789 \leaders\box\z@\hfil\box\tw@
10790 \baselineskip\etocbaselinespreadtwo\baselineskip
10791 \par}%
10792 \else
10793 \vbox{\etocname~%
10794 \leaders\copy\z@\hfil\break
10795 \hbox{}\leaders\box\z@\hfil\box\tw@
10796 \baselineskip\etocbaselinespreadtwo\baselineskip
10797 \par}%
10798 \fi
10799 \endgroup}
10800 {\addpenalty\@secpenalty\addvspace{\etocsepone}}%
10801 }
10802 \def\etocfallbacklines@setsubsubsection{%
10803 \Etoc@setstyle@b
10804 {3}%
10805 {\addpenalty\@M
10806 \etocfontthree
10807 \vspace{\etocsepthree}%
10808 \noindent
10809 \etocskipfirstprefix}
10810 {\allowbreak\,--\,}
10811 {\etocname}
10812 {.\hfil
10813 \begingroup
10814 \baselineskip\etocbaselinespreadthree\baselineskip
10815 \par
10816 \endgroup
10817 \addpenalty{-\@highpenalty}}
10818 }
10819 \def\etocfallbacklines@setdeeperones{%
10820 \Etoc@setstyle@e{4}%
10821 \Etoc@setstyle@e{5}%
10822 \ifEtoc@deeplevels
10823 \Etoc@setstyle@e{6}%
10824 \Etoc@setstyle@e{7}%
10825 \Etoc@setstyle@e{8}%
10826 \Etoc@setstyle@e{9}%
10827 \Etoc@setstyle@e{10}%
10828 \Etoc@setstyle@e{11}%
10829 \fi
10830 }
10831 % \end{macrocode}
10832 % The \csbc{etocinnertopsep} default value is too big as well as \csbc{etocbelowtocskip}
10833 % and \csbc{etocabovetocskip}, I guess, but if I am remember correctly I chose them
10834 % to mimic the standard TOC spacings in |article| class.
10835 % \begin{macrocode}
10836 \def\etocabovetocskip{3.5ex \@plus 1ex \@minus .2ex}
10837 \def\etocbelowtocskip{3.5ex \@plus 1ex \@minus .2ex}
10838 \def\etoccolumnsep{2em}
10839 \def\etocmulticolsep{0ex}
10840 \def\etocmulticolpretolerance{-1}
10841 \def\etocmulticoltolerance{200}
10842 \def\etocdefaultnbcol{2}
10843 \def\etocinnertopsep{2ex}
10844 \newcommand\etocmulticolstyle[2][\etocdefaultnbcol]{%
10845 \etocsettocstyle
10846 {\let\etocoldpar\par
10847 \addvspace{\etocabovetocskip}%
10848 \ifnum #1>\@ne
10849 \expandafter\@firstoftwo
10850 \else \expandafter\@secondoftwo
10851 \fi
10852 {\multicolpretolerance\etocmulticolpretolerance
10853 \multicoltolerance\etocmulticoltolerance
10854 \setlength{\columnsep}{\etoccolumnsep}%
10855 \setlength{\multicolsep}{\etocmulticolsep}%
10856 \begin{multicols}{#1}[#2\etocoldpar\addvspace{\etocinnertopsep}]}
10857 {#2\ifvmode\else\begingroup\interlinepenalty\@M\parskip\z@skip
10858 \@@par\endgroup
10859 \fi
10860 \nobreak\addvspace{\etocinnertopsep}%
10861 \pretolerance\etocmulticolpretolerance
10862 \tolerance\etocmulticoltolerance}%
10863 }%
10864 {\ifnum #1>\@ne
10865 \expandafter\@firstofone
10866 \else \expandafter\@gobble
10867 \fi
10868 {\end{multicols}}%
10869 \addvspace{\etocbelowtocskip}}%
10870 }
10871 % \end{macrocode}
10872 % placeholder for comments
10873 % \begin{macrocode}
10874 \def\etocinnerbottomsep{3.5ex}
10875 \def\etocinnerleftsep{2em}
10876 \def\etocinnerrightsep{2em}
10877 \def\etoctoprule{\hrule}
10878 \def\etocleftrule{\vrule}
10879 \def\etocrightrule{\vrule}
10880 \def\etocbottomrule{\hrule}
10881 \def\etoctoprulecolorcmd{\relax}
10882 \def\etocbottomrulecolorcmd{\relax}
10883 \def\etocleftrulecolorcmd{\relax}
10884 \def\etocrightrulecolorcmd{\relax}
10885 % \end{macrocode}
10886 % placeholder
10887 % \begin{macrocode}
10888 \def\etoc@ruledheading #1{%
10889 \hb@xt@\linewidth{\color@begingroup
10890 \hss #1\hss\hskip-\linewidth
10891 \etoctoprulecolorcmd\leaders\etoctoprule\hss
10892 \phantom{#1}%
10893 \leaders\etoctoprule\hss\color@endgroup}%
10894 \nointerlineskip\nobreak\vskip\etocinnertopsep}
10895 \newcommand*\etocruledstyle[2][\etocdefaultnbcol]{%
10896 \etocsettocstyle
10897 {\addvspace{\etocabovetocskip}%
10898 \ifnum #1>\@ne
10899 \expandafter\@firstoftwo
10900 \else \expandafter\@secondoftwo
10901 \fi
10902 {\multicolpretolerance\etocmulticolpretolerance
10903 \multicoltolerance\etocmulticoltolerance
10904 \setlength{\columnsep}{\etoccolumnsep}%
10905 \setlength{\multicolsep}{\etocmulticolsep}%
10906 \begin{multicols}{#1}[\etoc@ruledheading{#2}]}
10907 {\etoc@ruledheading{#2}%
10908 \pretolerance\etocmulticolpretolerance
10909 \tolerance\etocmulticoltolerance}}
10910 {\ifnum #1>\@ne\expandafter\@firstofone
10911 \else \expandafter\@gobble
10912 \fi
10913 {\end{multicols}}%
10914 \addvspace{\etocbelowtocskip}}}
10915 % \end{macrocode}
10916 % placeholder
10917 % \begin{macrocode}
10918 \def\etocframedmphook{\relax}
10919 \long\def\etocbkgcolorcmd{\relax}
10920 \long\def\Etoc@relax{\relax}
10921 % \end{macrocode}
10922 % \etocrelease{1.2e} re-indents the code here which was very badly format
10923 % probably as an Emacs buffer accident a long long time ago.
10924 % \begin{macrocode}
10925 \newbox\etoc@framed@titlebox
10926 \newbox\etoc@framed@contentsbox
10927 \newcommand*\etocframedstyle[2][\etocdefaultnbcol]{%
10928 \etocsettocstyle{%
10929 \addvspace{\etocabovetocskip}%
10930 \sbox\z@{%
10931 #2}% title (horizontal material)
10932 \dimen\z@\dp\z@
10933 \ifdim\wd\z@<\linewidth \dp\z@\z@ \else \dimen\z@\z@ \fi
10934 %% attention should I use kernel \sbox which has an \endgraf added
10935 \setbox\etoc@framed@titlebox=\hb@xt@\linewidth{%
10936 \color@begingroup
10937 \hss
10938 \ifx\etocbkgcolorcmd\Etoc@relax
10939 \else
10940 \sbox\tw@{\color{white}%
10941 \vrule\@width\wd\z@\@height\ht\z@\@depth\dimen\z@}%
10942 \ifdim\wd\z@<\linewidth \dp\tw@\z@\fi
10943 \box\tw@
10944 \hskip-\wd\z@
10945 \fi
10946 \copy\z@% the title
10947 \hss
10948 \hskip-\linewidth
10949 \etoctoprulecolorcmd\leaders\etoctoprule\hss
10950 \hskip\wd\z@
10951 \etoctoprulecolorcmd\leaders\etoctoprule\hss
10952 \color@endgroup
10953 }% \etoc@framed@titlebox
10954 \setbox\z@\hbox{\etocleftrule\etocrightrule}%
10955 \dimen\tw@\linewidth\advance\dimen\tw@-\wd\z@
10956 \advance\dimen\tw@-\etocinnerleftsep
10957 \advance\dimen\tw@-\etocinnerrightsep
10958 \setbox\etoc@framed@contentsbox=%
10959 \vbox\bgroup % this is in "before"
10960 \hsize\dimen\tw@
10961 \kern\dimen\z@
10962 \vskip\etocinnertopsep
10963 \hbox\bgroup
10964 % the start of a minipage which will hold a multicols if nbofcolumns>1
10965 \begin{minipage}{\hsize}%
10966 \etocframedmphook
10967 % \end{macrocode}
10968 % Very very old code seems anguished about starting multicols before \cs{fi},
10969 % leaving as is for time being
10970 % \begin{macrocode}
10971 \ifnum #1>\@ne
10972 \expandafter\@firstoftwo
10973 \else
10974 \expandafter\@secondoftwo
10975 \fi
10976 {\multicolpretolerance\etocmulticolpretolerance
10977 \multicoltolerance\etocmulticoltolerance
10978 \setlength{\columnsep}{\etoccolumnsep}%
10979 \setlength{\multicolsep}{\etocmulticolsep}%
10980 \begin{multicols}{#1}%
10981 }
10982 {\pretolerance\etocmulticolpretolerance
10983 \tolerance\etocmulticoltolerance
10984 }%
10985 }% end of \etocsettocstyle first argument
10986 {% start of \etocsettocstyle second argument
10987 % \end{macrocode}
10988 % Very very old code seems anguished about ending multicols before \cs{fi},
10989 % leaving as is for time being
10990 % \begin{macrocode}
10991 \ifnum #1>\@ne\expandafter\@firstofone\else \expandafter\@gobble \fi
10992 {\end{multicols}\unskip }%
10993 \end{minipage}% started in the \hbox
10994 \egroup % end of \hbox wrapper around minipage (inside \vbox)
10995 \vskip\etocinnerbottomsep
10996 \egroup % end of \vbox which included the TOC contents
10997 \vbox{%
10998 \hsize\linewidth
10999 \ifx\etocbkgcolorcmd\Etoc@relax
11000 \else
11001 \kern\ht\etoc@framed@titlebox
11002 \kern\dp\etoc@framed@titlebox
11003 \hb@xt@\linewidth{%
11004 \color@begingroup
11005 \etocleftrulecolorcmd
11006 \etocleftrule
11007 \etocbkgcolorcmd
11008 \leaders\vrule
11009 \@height\ht\etoc@framed@contentsbox
11010 \@depth\dp\etoc@framed@contentsbox
11011 \hss
11012 \etocrightrulecolorcmd
11013 \etocrightrule
11014 \color@endgroup
11015 }%
11016 \nointerlineskip
11017 \vskip-\dp\etoc@framed@contentsbox
11018 \vskip-\ht\etoc@framed@contentsbox
11019 \vskip-\dp\etoc@framed@titlebox
11020 \vskip-\ht\etoc@framed@titlebox
11021 \fi
11022 \box\etoc@framed@titlebox
11023 \nointerlineskip
11024 \hb@xt@\linewidth{%
11025 \color@begingroup
11026 {\etocleftrulecolorcmd\etocleftrule}%
11027 \hss\box\etoc@framed@contentsbox\hss
11028 \etocrightrulecolorcmd\etocrightrule
11029 \color@endgroup
11030 }%
11031 \nointerlineskip
11032 \vskip\ht\etoc@framed@contentsbox
11033 \vskip\dp\etoc@framed@contentsbox
11034 \hb@xt@\linewidth{%
11035 \color@begingroup
11036 \etocbottomrulecolorcmd
11037 \leaders\etocbottomrule\hss
11038 \color@endgroup
11039 }%
11040 }% end of \vbox in after part!
11041 \addvspace{\etocbelowtocskip}%
11042 }% end of \etocsettocstyle second argument
11043 }% end of \etocframedstyle definition
11044 % \end{macrocode}
11045 % For time being I will not however add the versions for ``lists of'', as
11046 % anyhow probably nobody apart myself ever uses these things.
11047 %
11048 % It is impossible to know what kind of division heading |#2| uses, so there
11049 % is not much I can do here at \etocrelease{1.2} apart from providing a
11050 % user interface for adding the suitable thing to the |.toc| file. And I
11051 % discover at time of writing (finishing the \etocrelease{1.2}
11052 % documentation) that I already have \csbc{etoclocalheadtotoc}. I only need to
11053 % add \csbc{etocglobalheadtotoc}.
11054 % \begin{macrocode}
11055 \newcommand\etoc@multicoltoc[2][\etocdefaultnbcol]{%
11056 \etocmulticolstyle[#1]{#2}%
11057 \tableofcontents}
11058 \newcommand\etoc@multicoltoci[2][\etocdefaultnbcol]{%
11059 \etocmulticolstyle[#1]{#2}%
11060 \tableofcontents*}
11061 \newcommand\etoc@local@multicoltoc[2][\etocdefaultnbcol]{%
11062 \etocmulticolstyle[#1]{#2}%
11063 \localtableofcontents}
11064 \newcommand\etoc@local@multicoltoci[2][\etocdefaultnbcol]{%
11065 \etocmulticolstyle[#1]{#2}%
11066 \localtableofcontents*}
11067 % \end{macrocode}
11068 % placeholder for comments
11069 % \begin{macrocode}
11070 \newcommand*\etoc@ruledtoc[2][\etocdefaultnbcol]{%
11071 \etocruledstyle[#1]{#2}%
11072 \tableofcontents}
11073 \newcommand*\etoc@ruledtoci[2][\etocdefaultnbcol]{%
11074 \etocruledstyle[#1]{#2}%
11075 \tableofcontents*}
11076 \newcommand*\etoc@local@ruledtoc[2][\etocdefaultnbcol]{%
11077 \etocruledstyle[#1]{#2}%
11078 \localtableofcontents}
11079 \newcommand*\etoc@local@ruledtoci[2][\etocdefaultnbcol]{%
11080 \etocruledstyle[#1]{#2}%
11081 \localtableofcontents*}
11082 % \end{macrocode}
11083 % placeholder for comments
11084 % \begin{macrocode}
11085 \newcommand*\etoc@framedtoc[2][\etocdefaultnbcol]{%
11086 \etocframedstyle[#1]{#2}%
11087 \tableofcontents}
11088 \newcommand*\etoc@framedtoci[2][\etocdefaultnbcol]{%
11089 \etocframedstyle[#1]{#2}%
11090 \tableofcontents*}
11091 \newcommand*\etoc@local@framedtoc[2][\etocdefaultnbcol]{%
11092 \etocframedstyle[#1]{#2}%
11093 \localtableofcontents}
11094 \newcommand*\etoc@local@framedtoci[2][\etocdefaultnbcol]{%
11095 \etocframedstyle[#1]{#2}%
11096 \localtableofcontents*}
11097 % \end{macrocode}
11098 % placeholder for comments
11099 % \begin{macrocode}
11100 \def\etocmulticol{\begingroup
11101 \Etoc@mustclosegrouptrue
11102 \@ifstar
11103 {\etoc@multicoltoci}
11104 {\etoc@multicoltoc}}
11105 \def\etocruled{\begingroup
11106 \Etoc@mustclosegrouptrue
11107 \@ifstar
11108 {\etoc@ruledtoci}
11109 {\etoc@ruledtoc}}
11110 \def\etocframed{\begingroup
11111 \Etoc@mustclosegrouptrue
11112 \@ifstar
11113 {\etoc@framedtoci}
11114 {\etoc@framedtoc}}
11115 \def\etoclocalmulticol{\begingroup
11116 \Etoc@mustclosegrouptrue
11117 \@ifstar
11118 {\etoc@local@multicoltoci}
11119 {\etoc@local@multicoltoc}}
11120 \def\etoclocalruled{\begingroup
11121 \Etoc@mustclosegrouptrue
11122 \@ifstar
11123 {\etoc@local@ruledtoci}
11124 {\etoc@local@ruledtoc}}
11125 \def\etoclocalframed{\begingroup
11126 \Etoc@mustclosegrouptrue
11127 \@ifstar
11128 {\etoc@local@framedtoci}
11129 {\etoc@local@framedtoc}}
11130 % \end{macrocode}
11131 % \etocrelease{1.2} makes local TOCs in compatibility display style use
11132 % |\subsection*| rather than |\section*|. This is not good for local TOCs to
11133 % a |\part| but anyhow the default is via \csbc{etocetoclocaltocstyle} which
11134 % will do the right thing and the change here is irrelevant. More comments
11135 % below about handling \ctanpkg{memoir} and \ctanpkg{KOMA-script}.
11136 %
11137 % The macros next will be modified if under |book| or \ctanpkg{memoir} class.
11138 % The \ctanpkg{KOMA-script} case uses rather the |leveldown| mechanism.
11139 % These local TOCs things are used only under \csbc{etocclasstocstyle}.
11140 % With \csbc{etocetoclocaltocstyle}, they are not used.
11141 % \begin{macrocode}
11142 \def\etocmemoirtoctotocfmt #1#2{%
11143 \PackageWarning{etoc}
11144 {\string\etocmemoirtoctotocfmt\space is deprecated.\MessageBreak
11145 Use in its place \string\etocsettoclineforclasstoc,\MessageBreak
11146 and \string\etocsettoclineforclasslistof{toc} (or {lof}, {lot}).
11147 I will do this now.\MessageBreak
11148 Reported}%
11149 \etocsettoclineforclasstoc{#1}{#2}%
11150 \etocsettoclineforclasslistof{toc}{#1}{#2}%
11151 }
11152 \def\etocsettoclineforclasstoc #1#2{%
11153 \def\etocclassmaintocaddtotoc{\etocglobalheadtotoc{#1}{#2}}%
11154 }
11155 \def\etocsettoclineforclasslistof #1#2#3{%
11156 \@namedef{etocclasslocal#1addtotoc}{\etoclocalheadtotoc{#2}{#3}}%
11157 }
11158 \let\etocclasslocaltocaddtotoc\@empty
11159 \let\etocclasslocallofaddtotoc\@empty
11160 \let\etocclasslocallotaddtotoc\@empty
11161 \ifdefined\c@chapter
11162 \def\etocclasslocaltocmaketitle{\section*{\localcontentsname}}
11163 \def\etocclasslocallofmaketitle{\section*{\locallistfigurename}}
11164 \def\etocclasslocallotmaketitle{\section*{\locallisttablename}}
11165 \etocsettoclineforclasstoc {chapter}{\contentsname}
11166 \etocsettoclineforclasslistof{toc}{section}{\localcontentsname}
11167 \etocsettoclineforclasslistof{lof}{section}{\locallistfigurename}
11168 \etocsettoclineforclasslistof{lot}{section}{\locallisttablename}
11169 \else
11170 \def\etocclasslocaltocmaketitle{\subsection*{\localcontentsname}}%
11171 \def\etocclasslocallofmaketitle{\subsection*{\locallistfigurename}}%
11172 \def\etocclasslocallotmaketitle{\subsection*{\locallisttablename}}%
11173 \etocsettoclineforclasstoc {section}{\contentsname}
11174 \etocsettoclineforclasslistof{toc}{subsection}{\localcontentsname}
11175 \etocsettoclineforclasslistof{lof}{subsection}{\locallistfigurename}
11176 \etocsettoclineforclasslistof{lot}{subsection}{\locallisttablename}
11177 \fi
11178 % \end{macrocode}
11179 % This is moved to a macro to localize complications with conditionals.
11180 % \begin{macrocode}
11181 \def\etocclasslocalperhapsaddtotoc #1{%
11182 \etocifisstarred
11183 {}
11184 {\csname ifEtoc@local#1totoc\endcsname
11185 \csname etocclasslocal#1addtotoc\endcsname
11186 \fi
11187 }%
11188 }
11189 % \end{macrocode}
11190 % No need for a \csa{phantomsection} if the \csa{addcontentsline} is after
11191 % |\section*|. For the standard classes, I make no effort to adjust level
11192 % used for the local heading if it is local to a \csa{part}, not a
11193 % \csa{section}. Anyhow this code will not be used by default for
11194 % local TOCs due to \csbc{etocetoclocaltocstyle}.
11195 % \begin{macrocode}
11196 \def\etocarticlestyle{%
11197 \etocsettocstyle
11198 {\ifEtoc@localtoc
11199 \@nameuse{etocclasslocal\Etoc@currext maketitle}%
11200 \etocclasslocalperhapsaddtotoc\Etoc@currext
11201 \else
11202 \section *{\contentsname
11203 \@mkboth {\MakeUppercase \contentsname}
11204 {\MakeUppercase \contentsname}}%
11205 \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
11206 \fi
11207 }
11208 {}%
11209 }
11210 \def\etocarticlestylenomarks{%
11211 \etocsettocstyle
11212 {\ifEtoc@localtoc
11213 \@nameuse{etocclasslocal\Etoc@currext maketitle}%
11214 \etocclasslocalperhapsaddtotoc\Etoc@currext
11215 \else
11216 \section *{\contentsname}%
11217 \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
11218 \fi
11219 }
11220 {}%
11221 }
11222 % \end{macrocode}
11223 % Make definitions with |book| in the macro names or redefine them
11224 % for |book|? Chose the latter.
11225 % \begin{macrocode}
11226 \def\etocbookstyle{%
11227 \etocsettocstyle
11228 {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi
11229 \ifEtoc@localtoc
11230 \@nameuse{etocclasslocal\Etoc@currext maketitle}%
11231 \etocclasslocalperhapsaddtotoc\Etoc@currext
11232 \else
11233 \chapter *{\contentsname
11234 \@mkboth {\MakeUppercase \contentsname}
11235 {\MakeUppercase \contentsname}}%
11236 \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
11237 \fi
11238 }%
11239 {\if@restonecol \twocolumn \fi}%
11240 }
11241 \def\etocbookstylenomarks{%
11242 \etocsettocstyle
11243 {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi
11244 \ifEtoc@localtoc
11245 \@nameuse{etocclasslocal\Etoc@currext maketitle}%
11246 \etocclasslocalperhapsaddtotoc\Etoc@currext
11247 \else
11248 \chapter *{\contentsname}%
11249 \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
11250 \fi
11251 }%
11252 {\if@restonecol \twocolumn \fi}%
11253 }
11254 \let\etocreportstyle\etocbookstyle
11255 \let\etocreportstylenomarks\etocbookstylenomarks
11256 % \end{macrocode}
11257 % |v3.7i| of memoir has moved the \csa{phantomsection} to a better location,
11258 % before typesetting the title and we follow suit at \etocrelease{1.09a}, and
11259 % at \etocrelease{1.09b}. Formerly \etoc used \csbc{etocaftertitlehook} to
11260 % mimic the memoir code but as its name indicate, it is supposedly executed
11261 % after the title... and this also had the defect of making
11262 % \csbc{etocaftertitlehook} not anymore a user command. Thus we here use some
11263 % refactoring of the \csbc{Etoc@aftertitlehook} internal mechanism to help
11264 % recognize if we are in the starred case or not.
11265 %
11266 % \csa{phantomsection} is always defined by memoir, empty if hyperref absent.
11267 %
11268 % Updates at \etocrelease{1.2} for the standard display style inherited
11269 % from the class to actually be usable with local table of contents.
11270 % Unfortunately the printing of the title rigidly hard-codes a
11271 % |\thispagestyle{chapter}|:
11272 % \begin{verbatim}
11273 % \@lofmaketitle ->\@nameuse {lofheadstart} {\parindent \z@ \parskip \z@ \interli
11274 % nepenalty \@M \@nameuse {printlofnonum}\@nameuse {printloftitle}{\listfigurenam
11275 % e }\@nameuse {lofmark}\thispagestyle {chapter}\@nameuse {afterloftitle} } \@aft
11276 % erheading
11277 % \end{verbatim}
11278 % \vskip-\baselineskip
11279 % Oh well I discover there is a \csa{chapterheadstart} but not
11280 % \csa{sectionheadstart}...
11281 %
11282 % Actually now \etoc will by default not use the class inherited style for the
11283 % local TOC titles, so maybe I should have not wasted time on this. From the
11284 % \csbc{etocsettocstyle} arguments one can know if this is for a local TOC,
11285 % but one can not know the level, which is inferred from the actual execution
11286 % of the TOC data. There is a problem though that the \ctanpkg{memoir}
11287 % default would be usable for a local TOC in a |\part|. Although one can
11288 % argue if it makes sense to display a TOC as prominently as a chapter anyway.
11289 % Again, the default with \etoc will anyhow not use this as
11290 % \csbc{etocetoclocaltocstyle} deactivates the \csbc{etocsettocstyle} for
11291 % local TOCs.
11292 %
11293 % MEMO: would it make sense to have an \csa{etocsetlocaltocstyle}? As
11294 % explained above this would however induced dramatic internal \etoc changes as one
11295 % would have to wait for title insertion until the time one knows the local
11296 % level. Which is exactly what \csbc{etocetoclocaltocstyle} via the
11297 % \csbc{ifEtoc@etocstyle} does.
11298 %
11299 % Update at \etocrelease{1.2} to account for \csbc{locallistoffigures} and
11300 % \csbc{locallistoftables}.
11301 % \begin{macrocode}
11302 \def\etocmemoirstyle{%
11303 \etocsettocstyle
11304 {\ensureonecol \par \begingroup \phantomsection
11305 \ifx\Etoc@aftertitlehook\@empty
11306 \else
11307 % \end{macrocode}
11308 % This branch executed for the non-starred variant
11309 % \begin{macrocode}
11310 \ifmem@em@starred@listof
11311 \else
11312 % \end{macrocode}
11313 % Global case is only for \csa{tableofcontents} as \etoc does not hack into
11314 % \csa{listofpictures} and \csa{listoftables}.
11315 %
11316 % Local case will not be executed in default configurations (cf
11317 % \csbc{etocetoclocaltocstyle}).
11318 %
11319 % \csbc{etocclasslocalperhapsaddtotoc} is to avoid worries with conditionals.
11320 % \begin{macrocode}
11321 \ifEtoc@localtoc
11322 \etocclasslocalperhapsaddtotoc\Etoc@currext
11323 \else
11324 \ifEtoc@maintoctotoc
11325 \etocclassmaintocaddtotoc
11326 \fi
11327 \fi
11328 \fi
11329 \fi
11330 \ifEtoc@localtoc
11331 % \end{macrocode}
11332 % Trying to mimic a section title but there is no \csa{sectionheadstart}
11333 % there is no \csa{printsectiontitle} etc... Oh well I will be more
11334 % radical then.
11335 % \begin{macrocode}
11336 \@namedef{@\Etoc@currext maketitle}{%
11337 \@nameuse{etocclasslocal\Etoc@currext maketitle}%
11338 }%
11339 \fi
11340 \@nameuse {@\Etoc@currext maketitle} %<< space token here from memoir code
11341 \ifx\Etoc@aftertitlehook\@empty
11342 \else
11343 % \end{macrocode}
11344 % Execute etoc hook before the \csa{cfttocbeforelisthook} and keep distinction
11345 % between starred and non-starred contexts for other hooks (by testing if
11346 % \csbc{Etoc@aftertitlehook} is empty or not). Notice that the memoir class
11347 % way of implementing \csbc{tableofcontents} leaves no way for code executed
11348 % by the TOC code to know if it is executed in starred or non-starred context.
11349 % \begin{macrocode}
11350 \Etoc@aftertitlehook \let \Etoc@aftertitlehook \relax
11351 \fi
11352 \parskip \cftparskip \@nameuse {cft\Etoc@currext beforelisthook}%
11353 }%
11354 {\@nameuse {cft\Etoc@currext afterlisthook}%
11355 \endgroup\restorefromonecol
11356 }%
11357 }
11358 % \end{macrocode}
11359 % Compatibility layer for the \ctanpkg{KOMA-script} classes:
11360 %
11361 % \etocrelease{1.09c} (|2020/05/15|) did an update as \ctanpkg{KOMA-script}
11362 % deprecated \csa{iftocfeature}. Thanks to Bilel Omrani for report. I
11363 % did not check if cloning of KOMA code required some further updates.
11364 % \etocrelease{1.09f} added more updates.
11365 %
11366 % At \etocrelease{1.2} this is further updated to be usable also for list
11367 % of figures and tables. However, this update is somewhat theoretical because
11368 % \etoc does not interfere at all with \csa{listoffigures} and
11369 % \csa{listoftables}: the update is useful only to make \etoc's
11370 % \csbc{locallistoffigures} and \csbc{locallistoftables} usable in display
11371 % style compatibility mode.
11372 %
11373 % But during development on this I became aware that \ctanpkg{KOMA-script}
11374 % since its |3.30| release has the feature that an unnumbered section resets
11375 % the counters of subsections. This creates a problem (whose description I
11376 % have moved to the user manual) which can be alleviated for local TOCs at the
11377 % highest level below global one by using KOMA's |\setuptoc{toc}{leveldown}|.
11378 % So I decided to do this systematically, as in the code next via a new
11379 % private hook, but the problem will remain for local TOCs at lower levels,
11380 % and there does not seem to be any way to tell KOMA to use say
11381 % |\subsubsection*|, barring, from what I understand from the manual, usage of
11382 % its \csa{deftocheading}. So in a second stage I decided that per default
11383 % \etoc would rather use for local TOCs, and not only for KOMA classes but all
11384 % classes, an adaptive heading fitted to the ``local top''. As this ``local
11385 % top'' can only be determined from inside the expansion of \csbc{Etoc@toctoc}
11386 % which contains the |.toc| file data, the boolean \csbc{ifEtoc@etocstyle}
11387 % was added which will make \csbc{etocsettocstyle} configuration ignored. In
11388 % this way, with \csbc{etocetoclocaltocstyle}, the document class emulation
11389 % will apply to the global TOC whereas local TOCs will use the adaptive
11390 % scheme. To avoid duplication other relevant info is moved to the user
11391 % manual.
11392 %
11393 % We put the trigger of |leveldown| for KOMA classes in
11394 % \csbc{Etoc@beforetitlehook}. So there will be no test with
11395 % \csbc{ifEtoc@localtoc} here contrarily to the case of standard classes
11396 % and memoir. Again, all of this normally is not relevant as by default \etoc
11397 % \etocrelease{1.2} will use its \csbc{etocetoclocaltocstyle} which
11398 % for local TOCs ignores the emulation code of the main TOC.
11399 % \begin{macrocode}
11400 \let\Etoc@beforetitlehook\@empty
11401 \if1\@ifclassloaded{scrartcl}0{\@ifclassloaded{scrbook}0{\@ifclassloaded{scrreprt}01}}%
11402 \expandafter\@gobble
11403 \else
11404 % \end{macrocode}
11405 % Surely paranoid here but I don't have time to go through KOMA documentation
11406 % (I am not really familiar with these classes).
11407 %
11408 % MEMO: I do not know if \ctanpkg{KOMA-script}'s \csa{setuptoc} sets options
11409 % locally or globally. If globally the code below must be modifed to unset
11410 % the |totoc| option depending on at time of use status of the \etoc own
11411 % |totoc| options.
11412 % \begin{macrocode}
11413 \ifdefined\setuptoc
11414 \def\Etoc@beforetitlehook{%
11415 \ifEtoc@localtoc
11416 \etocclasslocalperhapsaddtotoc\Etoc@currext
11417 \setuptoc{\Etoc@currext}{leveldown}%
11418 \else
11419 \etocifisstarred{}{\etocifmaintoctotoc{\setuptoc{toc}{totoc}}}%
11420 \fi
11421 }%
11422 \fi
11423 \expandafter\@firstofone
11424 \fi
11425 {\def\etocclasslocalperhapsaddtotoc #1{%
11426 \etocifisstarred
11427 {}%
11428 {\csname ifEtoc@local#1totoc\endcsname
11429 \setuptoc{\Etoc@currext}{totoc}%
11430 \fi
11431 }%
11432 }%
11433 }
11434 \ifdefined\Iftocfeature
11435 \def\etoc@Iftocfeature{\Iftocfeature}%
11436 \else
11437 \def\etoc@Iftocfeature{\iftocfeature}%
11438 \fi
11439 % \end{macrocode}
11440 % Peut-être en fait je devrais toujours faire |\let\if@dynlist\if@tocleft|?
11441 % Mais je ne l'ai pas vu dans le code de KOMA pour les LOF et LOT (globales,
11442 % évidemment). Mais cela m'obligerait à lire vraiment le code source de KOMA.
11443 % Pas le temps.
11444 % \begin{macrocode}
11445 \def\etocscrartclstyle{%
11446 \etocsettocstyle
11447 {\ifx\Etoc@currext\Etoc@tocext
11448 \expandafter\@firstofone
11449 \else
11450 \expandafter\@gobble
11451 \fi
11452 {\let\if@dynlist\if@tocleft}%
11453 \edef\@currext{\Etoc@currext}%
11454 \@ifundefined{listof\@currext name}%
11455 {\def\list@fname{\listofname~\@currext}}%
11456 {\expandafter\let\expandafter\list@fname
11457 \csname listof\@currext name\endcsname}%
11458 \etoc@Iftocfeature {\@currext}{onecolumn}
11459 {\etoc@Iftocfeature {\@currext}{leveldown}
11460 {}
11461 {\if@twocolumn \aftergroup \twocolumn \onecolumn \fi }}
11462 {}%
11463 \etoc@Iftocfeature {\@currext}{numberline}%
11464 {\def \nonumberline {\numberline {}}}{}%
11465 \expandafter\tocbasic@listhead\expandafter {\list@fname}%
11466 \begingroup \expandafter \expandafter \expandafter
11467 \endgroup \expandafter
11468 \ifx
11469 \csname microtypesetup\endcsname \relax
11470 \else
11471 \etoc@Iftocfeature {\@currext}{noprotrusion}{}
11472 {\microtypesetup {protrusion=false}%
11473 \PackageInfo {tocbasic}%
11474 {character protrusion at \@currext\space deactivated}}%
11475 \fi
11476 \etoc@Iftocfeature{\@currext}{noparskipfake}{}{%
11477 \ifvmode \@tempskipa\lastskip \vskip-\lastskip
11478 \addtolength{\@tempskipa}{\parskip}\vskip\@tempskipa\fi
11479 }%
11480 \setlength {\parskip }{\z@ }%
11481 \setlength {\parindent }{\z@ }%
11482 \setlength {\parfillskip }{\z@ \@plus 1fil}%
11483 \csname tocbasic@@before@hook\endcsname
11484 \csname tb@\@currext @before@hook\endcsname
11485 }% end of before_toc
11486 {% start of after_toc
11487 % \end{macrocode}
11488 % (This next discussion has not been revised at \etocrelease{1.2} so let's
11489 % hope it is fine).
11490 %
11491 % At \etocrelease{1.09f} I considered adding this \csa{BeforeClosingMainAux} hunk
11492 % to the second argument of \csbc{etocsettocstyle}-emulation of \ctanpkg{KOMA-script}.
11493 % But:
11494 % \begin{itemize}
11495 % \item there seems to be no interface to \csa{tocbasic@end@toc@file},
11496 %
11497 % \item
11498 % it defaults to issuing a \csa{par}, but we want etoc to still be able
11499 % to produce other TOCs, possibly inline, and they should not be
11500 % influenced by it and I don't want at this stage to add an interface
11501 % to enable/disable and have to document it,
11502 %
11503 % \item
11504 % the whole thing appears to me to be ill-conceived in so far as it
11505 % sort of implies the \csbc{tableofcontents} is used only once, as each
11506 % instance will again add this \csa{tocbasic@end@toc@file} to end of
11507 % toc file, which may thus end up being executed multiple times.
11508 % \end{itemize}
11509 % So rather than putting the thing in the |.toc| file, we will execute
11510 % it here. This way it will not impact other TOCs typeset via etoc
11511 % design facilities in the document.
11512 % \begin{macrocode}
11513 % \BeforeClosingMainAux
11514 % {\addtocontents
11515 % {toc}{\string\providecommand\string\tocbasic@end@toc@file{}%
11516 % \string\tocbasic@end@toc@file}%
11517 % }%
11518 \providecommand\tocbasic@end@toc@file{}\tocbasic@end@toc@file
11519 \edef\@currext{\Etoc@currext}%
11520 \csname tb@\@currext @after@hook\endcsname
11521 \csname tocbasic@@after@hook\endcsname
11522 }% end of after_toc
11523 }
11524 \let\etocscrbookstyle\etocscrartclstyle
11525 \let\etocscrreprtstyle\etocscrartclstyle
11526 % \end{macrocode}
11527 % The \csbc{etocclasstocstyle} will be redefined according to document
11528 % class. Then, later, it will be extended with an
11529 % \csa{Etoc@classstyletrue}.
11530 % \begin{macrocode}
11531 \def\etocclasstocstyle{\etocarticlestyle}
11532 \newcommand*\etocmarkboth[1]{%
11533 \@mkboth{\MakeUppercase{#1}}{\MakeUppercase{#1}}}
11534 \newcommand*\etocmarkbothnouc[1]{\@mkboth{#1}{#1}}
11535 \newcommand\etoctocstyle[3][section]{\etocmulticolstyle[#2]%
11536 {\csname #1\endcsname *{#3}}}
11537 \newcommand\etoctocstylewithmarks[4][section]{\etocmulticolstyle[#2]%
11538 {\csname #1\endcsname *{#3\etocmarkboth{#4}}}}
11539 \newcommand\etoctocstylewithmarksnouc[4][section]{\etocmulticolstyle[#2]%
11540 {\csname #1\endcsname *{#3\etocmarkbothnouc{#4}}}}
11541 \def\Etoc@redefetocstylesforchapters{%
11542 \renewcommand\etoctocstylewithmarks[4][chapter]{%
11543 \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3\etocmarkboth{##4}}}%
11544 }
11545 \renewcommand\etoctocstylewithmarksnouc[4][chapter]{%
11546 \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3\etocmarkbothnouc{##4}}}%
11547 }
11548 \renewcommand\etoctocstyle[3][chapter]{%
11549 \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3}}
11550 }
11551 }
11552 \@ifclassloaded{scrartcl}
11553 {\renewcommand*\etocclasstocstyle{\etocscrartclstyle}}{}
11554 \@ifclassloaded{book}
11555 {\renewcommand*\etocfontone{\normalfont\normalsize}
11556 \renewcommand*\etocclasstocstyle{\etocbookstyle}
11557 \Etoc@redefetocstylesforchapters}{}
11558 \@ifclassloaded{report}
11559 {\renewcommand*\etocfontone{\normalfont\normalsize}
11560 \renewcommand*\etocclasstocstyle{\etocreportstyle}
11561 \Etoc@redefetocstylesforchapters}{}
11562 \@ifclassloaded{scrbook}
11563 {\renewcommand*\etocfontone{\normalfont\normalsize}
11564 \renewcommand*\etocclasstocstyle{\etocscrbookstyle}
11565 \Etoc@redefetocstylesforchapters}{}
11566 \@ifclassloaded{scrreprt}
11567 {\renewcommand*\etocfontone{\normalfont\normalsize}
11568 \renewcommand*\etocclasstocstyle{\etocscrreprtstyle}
11569 \Etoc@redefetocstylesforchapters}{}
11570 \@ifclassloaded{memoir}
11571 {\renewcommand*\etocfontone{\normalfont\normalsize}
11572 \renewcommand*\etocclasstocstyle{\etocmemoirstyle}
11573 \Etoc@redefetocstylesforchapters}{}
11574 \def\etoctocloftstyle {%
11575 \etocsettocstyle{%
11576 \@cfttocstart
11577 \par
11578 \begingroup
11579 \parindent\z@ \parskip\cftparskip
11580 % \end{macrocode}
11581 % I don't feel like redefining \csa{@cftmaketoctitle} etc to apply ``level
11582 % down''. Up to the user to use the tocloft interface after the main TOC
11583 % to do appropriate actions. I consider emitting a warning, but then if
11584 % the user has customize \csa{@cftmaketoctitle} or variant, how to know?
11585 % (apart from numerous ifx tests).
11586 % \begin{macrocode}
11587 \@nameuse{@cftmake\Etoc@currext title}%
11588 % \end{macrocode}
11589 % But for adding an appropriate entry to the toc file I can intervene silently.
11590 % I can remove the test \csa{if@cfttocbibind} here as anyhow I have to test
11591 % status of \etoc `to toc' options.
11592 % \begin{macrocode}
11593 \ifEtoc@localtoc
11594 \etoctocloftlocalperhapsaddtotoc\Etoc@currext
11595 \else
11596 \etocifisstarred {}{\ifEtoc@maintoctotoc\@cftdobibtoc\fi}%
11597 \fi
11598 }%
11599 {%
11600 \endgroup
11601 \@cfttocfinish
11602 }%
11603 }
11604 \def\etoctocloftlocalperhapsaddtotoc#1{%
11605 \etocifisstarred
11606 {}%
11607 {\csname ifEtoc@local#1totoc\endcsname
11608 \ifdefined\c@chapter\def\@tocextra{@section}\else\def\@tocextra{@subsection}\fi
11609 \csname @cftdobib#1\endcsname
11610 \fi
11611 }%
11612 }
11613 % \end{macrocode}
11614 % This is active only if \ctanpkg{tocbibind} boolean \csa{if@dotoctoc} is found
11615 % true at begin document and there was no use of \csbc{etocsettocstyle} in the
11616 % preamble. The part on local TOC also applies to local LOF and LOT but is
11617 % executed only if \csbc{etocclasstocstyle} was present in the preamble. Under
11618 % the default \csbc{etocetoclocaltocstyle}, only the global TOC is under
11619 % influence of this (assuming thus that \ctanpkg{tocbibind} was loaded without
11620 % its |nottoc| or |none| option).
11621 % \begin{macrocode}
11622 \def\etoctocbibindstyle {%
11623 \etocsettocstyle {%
11624 \toc@start
11625 \ifEtoc@localtoc
11626 \@nameuse{etocclasslocal\Etoc@currext maketitle}%
11627 \etocclasslocalperhapsaddtotoc\Etoc@currext
11628 \else
11629 \etoc@tocbibind@dotoctitle
11630 \fi
11631 }%
11632 {\toc@finish}%
11633 }
11634 \def\etoc@tocbibind@dotoctitle {%
11635 % \end{macrocode}
11636 % If \ctanpkg{tocbibind} is loaded but later between |\begin{document}| and
11637 % \csa{tableofcontents} the user does \csbc{etocsetup}|{maintoctotoc=afalse}|
11638 % we have to catch this.
11639 % \begin{macrocode}
11640 \if@bibchapter
11641 \etocifisstarred
11642 {\chapter*{\contentsname}\prw@mkboth{\contentsname} % id.
11643 }%
11644 {\ifEtoc@maintoctotoc
11645 \toc@chapter{\contentsname} %<-space from original
11646 \else
11647 \chapter*{\contentsname}\prw@mkboth{\contentsname} % id.
11648 \fi
11649 }%
11650 \else
11651 \etocifisstarred
11652 {\@nameuse{\@tocextra}*{\contentsname\prw@mkboth{\contentsname}} %<-space
11653 }
11654 {\ifEtoc@maintoctotoc
11655 \toc@section{\@tocextra}{\contentsname} %<-space from original
11656 \else
11657 \@nameuse{\@tocextra}*{\contentsname\prw@mkboth{\contentsname}} % id.
11658 \fi
11659 }%
11660 \fi
11661 }%
11662 % \end{macrocode}
11663 % The \etocrelease{1.2} added a bug here in the non-\ctanpkg{memoir}
11664 % \ctanpkg{tocloft} branch, the needed \csa{AtBeginDocument} was removed by
11665 % accident and as a result the overwriting by \ctanpkg{tocloft} of
11666 % \csbc{tableofcontents} was not undone.
11667 % \begin{macrocode}
11668 \@ifclassloaded{memoir}
11669 {}
11670 {% memoir not loaded
11671 \@ifpackageloaded{tocloft}
11672 {\if@cftnctoc\else
11673 \ifEtoc@keeporiginaltoc
11674 \else
11675 \AtBeginDocument{\let\tableofcontents\etoctableofcontents}%
11676 \fi
11677 \fi }
11678 {\AtBeginDocument
11679 {\@ifpackageloaded{tocloft}
11680 {\if@cftnctoc\else
11681 \PackageWarningNoLine {etoc}
11682 {Package `tocloft' was loaded after `etoc'.\MessageBreak
11683 To prevent it from overwriting \protect\tableofcontents, it will\MessageBreak
11684 be tricked into believing to have been loaded with its\MessageBreak
11685 option `titles'. \space But this will cause the `tocloft'\MessageBreak
11686 customization of the titles of the main list of figures\MessageBreak
11687 and list of tables to not apply either.\MessageBreak
11688 You should load `tocloft' before `etoc'.}%
11689 \AtEndDocument{\PackageWarning{etoc}
11690 {Please load `tocloft' before `etoc'!\@gobbletwo}}%
11691 \fi
11692 \@cftnctoctrue }%
11693 {}%
11694 }%
11695 }%
11696 }
11697 \@ifclassloaded{memoir}
11698 {}
11699 {% memoir not loaded
11700 \AtBeginDocument{%
11701 \@ifpackageloaded{tocloft}
11702 {%
11703 \def\etocclasstocstyle{%
11704 \etoctocloftstyle
11705 \Etoc@classstyletrue
11706 }%
11707 \ifEtoc@etocstyle
11708 \ifEtoc@classstyle
11709 \etocclasstocstyle
11710 \Etoc@etocstyletrue
11711 \fi
11712 \else
11713 \ifEtoc@classstyle
11714 \etocclasstocstyle
11715 \fi
11716 \fi
11717 }%
11718 {% no tocloft
11719 \@ifpackageloaded {tocbibind}
11720 % \end{macrocode}
11721 % For some reason this \etocrelease{1.2} code had no |\fi| matching the
11722 % |\if@dotoctoc|. Fixed at \etocrelease{1.2d}.
11723 % \begin{macrocode}
11724 {\if@dotoctoc
11725 \def\etocclasstocstyle{%
11726 \etoctocbibindstyle
11727 \Etoc@classstyletrue
11728 }%
11729 \ifEtoc@etocstyle
11730 \ifEtoc@classstyle
11731 \etocclasstocstyle
11732 \Etoc@etocstyletrue
11733 \fi
11734 \else
11735 \ifEtoc@classstyle
11736 \etocclasstocstyle
11737 \fi
11738 \fi
11739 % \end{macrocode}
11740 % Not clear if I should interpret \csa{Etoc@keeporiginaltoctrue} in this sense
11741 % to not modify \ctanpkg{tocbibind} overwrite of \csbc{tableofcontents}. But
11742 % let's obey this interpretation.
11743 % \begin{macrocode}
11744 \ifEtoc@keeporiginaltoc
11745 \else
11746 \let\tableofcontents\etoctableofcontents
11747 \fi
11748 \fi
11749 }% end of tocbibind without tocloft at begin document code
11750 {}% empty false branch
11751 }% end of no tocloft at begin document code
11752 % \end{macrocode}
11753 % Maybe I should check if the options were already set. I will simply
11754 % make the message more generic.
11755 % \begin{macrocode}
11756 \@ifpackageloaded{tocbibind}
11757 {% tocbibind, perhaps with tocloft
11758 \if@dotoctoc
11759 \ifEtoc@keeporiginaltoc
11760 \else
11761 \let\tableofcontents\etoctableofcontents
11762 \fi
11763 \etocsetup{maintoctotoc,localtoctotoc}%
11764 \PackageInfo{etoc}{%
11765 Setting (or re-setting) the options `maintoctotoc' and\MessageBreak
11766 `localtoctotoc' to true as tocbibind was detected and\MessageBreak
11767 found to be configured for `TOC to toc'.\MessageBreak
11768 Reported at begin document}%
11769 \fi
11770 \if@dotoclof
11771 \ifEtoc@lof
11772 \etocsetup{localloftotoc}%
11773 \PackageInfo{etoc}{%
11774 Setting (or re-setting) `localloftotoc=true' as the\MessageBreak
11775 package tocbibind was detected and is configured for\MessageBreak
11776 `LOF to toc'. Reported at begin document}%
11777 \fi
11778 \fi
11779 \if@dotoclot
11780 \ifEtoc@lot
11781 \etocsetup{locallottotoc}%
11782 \PackageInfo{etoc}{%
11783 Setting (or re-setting) `locallottotoc=true' as the\MessageBreak
11784 package tocbibind was detected and is configured for\MessageBreak
11785 `LOT to toc'. Reported at begin document}%
11786 \fi
11787 \fi
11788 }% end of tocbibind branch
11789 {}%
11790 }% end of at begin document
11791 }% end of not with memoir branch
11792 % \end{macrocode}
11793 % \LaTeX\ 2021 fall release lets \csa{contentsline} always grab four
11794 % arguments, so with \etocrelease{1.09e} |2021/09/23| we make sure our
11795 % \csa{addtocontents} will always provide \csa{contentsline} with four
11796 % arguments. This extra |{}| is done without checking LaTeX's version by
11797 % laziness, as an impact on documents compiled with former LaTeX could be
11798 % visible only with very special contexts that only the author himself would
11799 % ever consider.
11800 %
11801 % Let's also add \csa{protected@file@percent} at \etocrelease{1.09e} although
11802 % this is a priori of no relevance as \etoc reads the toc file with
11803 % |\endlinechar=-1| regime.
11804 %
11805 % When using \csa{addcontentsline} nothing needs to be done as both things are
11806 % handled by \LaTeX\ upstream.
11807 %
11808 % \etocrelease{1.2} executes the \csbc{ifEtoc@hyperref} test inside the fourth
11809 % argument, rather than using one \csa{addtocontents} in each branch.
11810 % \begin{macrocode}
11811 \def\Etoc@addtocontents #1#2{%
11812 \addtocontents {toc}{%
11813 \protect\contentsline{#1}{#2}{\thepage}%
11814 {\ifEtoc@hyperref\@currentHref\fi}%
11815 \ifdefined\protected@file@percent\protected@file@percent\fi
11816 }%
11817 }
11818 \def\Etoc@addcontentsline@ #1#2#3{%
11819 \@namedef{toclevel@#1}{#3}\addcontentsline {toc}{#1}{#2}%
11820 }
11821 \DeclareRobustCommand*{\etoctoccontentsline}
11822 {\@ifstar{\Etoc@addcontentsline@}{\Etoc@addtocontents}}
11823 \def\Etoc@addtocontents@immediately#1#2{%
11824 \begingroup
11825 \let\Etoc@originalwrite\write
11826 \def\write{\immediate\Etoc@originalwrite}%
11827 \Etoc@addtocontents{#1}{#2}%
11828 \endgroup
11829 }
11830 \def\Etoc@addcontentsline@@immediately#1#2#3{%
11831 \begingroup
11832 \let\Etoc@originalwrite\write
11833 \def\write{\immediate\Etoc@originalwrite}%
11834 \Etoc@addcontentsline@{#1}{#2}{#3}%
11835 \endgoroup
11836 }
11837 \DeclareRobustCommand*{\etocimmediatetoccontentsline}
11838 {\@ifstar{\Etoc@addcontentsline@@immediately}{\Etoc@addtocontents@immediately}}
11839 % \end{macrocode}
11840 % Formerly a \LaTeX{} counter |etoc@tocdepth| was used but at
11841 % \etocrelease{1.2} it has been replaced by macro-storage.
11842 % \begin{macrocode}
11843 \def\Etoc@storetocdepth {\xdef\Etoc@savedtocdepth{\number\c@tocdepth}}
11844 \def\Etoc@restoretocdepth {\global\c@tocdepth\Etoc@savedtocdepth\relax}
11845 \def\etocobeytoctocdepth {\def\etoc@settocdepth
11846 {\afterassignment\Etoc@@nottoodeep \global\c@tocdepth}}
11847 \def\Etoc@@nottoodeep {\ifnum\Etoc@savedtocdepth<\c@tocdepth
11848 \global\c@tocdepth\Etoc@savedtocdepth\relax\fi }
11849 \def\etocignoretoctocdepth {\let\etoc@settocdepth\@gobble }
11850 \def\etocsettocdepth {\futurelet\Etoc@nexttoken\Etoc@set@tocdepth }
11851 \def\Etoc@set@tocdepth {\ifx\Etoc@nexttoken\bgroup
11852 \expandafter\Etoc@set@tocdepth@
11853 \else\expandafter\Etoc@set@toctocdepth
11854 \fi }
11855 \def\Etoc@set@tocdepth@ #1{\@ifundefined {Etoc@#1@@}
11856 {\PackageWarning{etoc}
11857 {Unknown sectioning unit #1, \protect\etocsettocdepth\space ignored}}
11858 {\global\c@tocdepth\csname Etoc@#1@@\endcsname}%
11859 }
11860 \def\Etoc@set@toctocdepth #1#{\Etoc@set@toctocdepth@ }
11861 \def\Etoc@set@toctocdepth@ #1{%
11862 \@ifundefined{Etoc@#1@@}%
11863 {\PackageWarning{etoc}
11864 {Unknown sectioning depth #1, \protect\etocsettocdepth.toc ignored}}%
11865 {\addtocontents {toc}
11866 {\protect\etoc@settocdepth\expandafter\protect\csname Etoc@#1@@\endcsname}}%
11867 }
11868 % \end{macrocode}
11869 % placeholder
11870 % \begin{macrocode}
11871 \def\etocimmediatesettocdepth #1#{\Etoc@set@toctocdepth@immediately}
11872 \def\Etoc@set@toctocdepth@immediately #1{%
11873 \@ifundefined{Etoc@#1@@}%
11874 {\PackageWarning{etoc}
11875 {Unknown sectioning depth #1, \protect\etocimmediatesettocdepth.toc ignored}}%
11876 {\begingroup
11877 \let\Etoc@originalwrite\write
11878 \def\write{\immediate\Etoc@originalwrite}%
11879 \addtocontents {toc}
11880 {\protect\etoc@settocdepth\expandafter\protect
11881 \csname Etoc@#1@@\endcsname}%
11882 \endgroup
11883 }%
11884 }
11885 % \end{macrocode}
11886 % placeholder
11887 % \begin{macrocode}
11888 \def\etocdepthtag #1#{\Etoc@depthtag }
11889 \def\Etoc@depthtag #1{\addtocontents {toc}{\protect\etoc@depthtag {#1}}}
11890 % \end{macrocode}
11891 % \etocrelease{1.09f} adds \csbc{etocimmediatedepthtag.toc}. This can serve in some
11892 % circumstances, see user documentation. Apologies for long delay to Norman
11893 % Ramsey who reported problem and his fix in July... 2016!
11894 % \begin{macrocode}
11895 \def\etocimmediatedepthtag #1#{\Etoc@depthtag@immediately }
11896 \def\Etoc@depthtag@immediately #1{%
11897 \begingroup
11898 \let\Etoc@originalwrite\write
11899 \def\write{\immediate\Etoc@originalwrite}%
11900 \addtocontents {toc}{\protect\etoc@depthtag {#1}}%
11901 \endgroup
11902 }
11903 \def\etocignoredepthtags {\let\etoc@depthtag \@gobble }
11904 \def\etocobeydepthtags {\let\etoc@depthtag \Etoc@depthtag@ }
11905 \def\Etoc@depthtag@ #1{\@ifundefined{Etoc@depthof@#1}%
11906 {}% ignore in silence if tag has no associated depth
11907 {\afterassignment\Etoc@@nottoodeep
11908 \global\c@tocdepth\csname Etoc@depthof@#1\endcsname}%
11909 }
11910 \def\etocsettagdepth #1#2{\@ifundefined{Etoc@#2@@}%
11911 {\PackageWarning{etoc}
11912 {Unknown sectioning depth #2, \protect\etocsettagdepth\space ignored}}%
11913 {\@namedef{Etoc@depthof@#1}{\@nameuse{Etoc@#2@@}}}%
11914 }
11915 % \end{macrocode}
11916 % We must cancel all \ctanpkg{tocvsec2} toc-related actions. But a check must be done
11917 % for the memoir class, as its \ctanpkg{tocvsec2} emulation does not have the
11918 % incompatible things etoc needs to revert.
11919 % \begin{macrocode}
11920 \def\Etoc@tocvsec@err #1{\PackageError {etoc}
11921 {The command \protect#1\space is incompatible with `etoc'}
11922 {Use \protect\etocsettocdepth.toc as replacement}%
11923 }%
11924 \AtBeginDocument {%
11925 \@ifclassloaded{memoir}
11926 {\PackageInfo {etoc}
11927 {Regarding `memoir' class command \protect\settocdepth, consider\MessageBreak
11928 \protect\etocsettocdepth.toc as a drop-in replacement with more\MessageBreak
11929 capabilities (see `etoc' manual). \space
11930 Also, \protect\etocsettocdepth\MessageBreak
11931 and \protect\etocsetnexttocdepth\space should be used in place of\MessageBreak
11932 `memoir' command \protect\maxtocdepth\@gobble}%
11933 }%
11934 {\@ifpackageloaded {tocvsec2}{%
11935 \def\maxtocdepth #1{\Etoc@tocvsec@err \maxtocdepth }%
11936 \def\settocdepth #1{\Etoc@tocvsec@err \settocdepth }%
11937 \def\resettocdepth {\@ifstar {\Etoc@tocvsec@err \resettocdepth }%
11938 {\Etoc@tocvsec@err \resettocdepth }%
11939 }%
11940 % \end{macrocode}
11941 % If \etoc is added to a \LaTeX{} document using already \ctanpkg{tocvsec2}.
11942 % \begin{macrocode}
11943 \def\save@tocdepth #1#2#3{}%
11944 \let\reset@tocdepth\relax
11945 \let\remax@tocdepth\relax
11946 \let\tableofcontents\etoctableofcontents
11947 \PackageWarningNoLine {etoc}
11948 {Package `tocvsec2' detected and its modification of\MessageBreak
11949 \protect\tableofcontents\space reverted. \space Use
11950 \protect\etocsettocdepth.toc\MessageBreak as a replacement
11951 for `tocvsec2' toc-related commands}%
11952 }% tocvsec2 loaded
11953 {}% tocvsec2 not loaded
11954 }%
11955 }%
11956 % \end{macrocode}
11957 % placeholder
11958 % \begin{macrocode}
11959 \def\invisibletableofcontents {\etocsetnexttocdepth {-3}\tableofcontents }%
11960 \def\invisiblelocaltableofcontents
11961 {\etocsetnexttocdepth {-3}\localtableofcontents }%
11962 \def\etocsetnexttocdepth #1{%
11963 \@ifundefined{Etoc@#1@@}
11964 {\PackageWarning{etoc}
11965 {Unknown sectioning unit #1, \protect\etocsetnextocdepth\space ignored}}
11966 {\Etoc@setnexttocdepth{\csname Etoc@#1@@\endcsname}}%
11967 }%
11968 \def\Etoc@setnexttocdepth#1{%
11969 \def\Etoc@tocdepthset{%
11970 \Etoc@tocdepthreset
11971 \edef\Etoc@tocdepthreset {%
11972 \global\c@tocdepth\the\c@tocdepth\space
11973 \global\let\noexpand\Etoc@tocdepthreset\noexpand\@empty
11974 }%
11975 \global\c@tocdepth#1%
11976 \global\let\Etoc@tocdepthset\@empty
11977 }%
11978 }%
11979 \let\Etoc@tocdepthreset\@empty
11980 \let\Etoc@tocdepthset \@empty
11981 \def\etocsetlocaltop #1#{\Etoc@set@localtop}%
11982 \def\Etoc@set@localtop #1{%
11983 \@ifundefined{Etoc@#1@@}%
11984 {\PackageWarning{etoc}
11985 {Unknown sectioning depth #1, \protect\etocsetlocaltop.toc ignored}}%
11986 {\addtocontents {toc}
11987 {\protect\etoc@setlocaltop\expandafter\protect\csname Etoc@#1@@\endcsname}}%
11988 }%
11989 % \end{macrocode}
11990 % placeholder
11991 % \begin{macrocode}
11992 \def\etocimmediatesetlocaltop #1#{\Etoc@set@localtop@immediately}%
11993 \def\Etoc@set@localtop@immediately #1{%
11994 \@ifundefined{Etoc@#1@@}%
11995 {\PackageWarning{etoc}
11996 {Unknown sectioning depth #1, \protect\etocimmediatesetlocaltop.toc ignored}}%
11997 {\begingroup
11998 \let\Etoc@originalwrite\write
11999 \def\write{\immediate\Etoc@originalwrite}%
12000 \addtocontents {toc}
12001 {\protect\etoc@setlocaltop\expandafter\protect
12002 \csname Etoc@#1@@\endcsname}%
12003 \endgroup
12004 }%
12005 }%
12006 % \end{macrocode}
12007 % \etocrelease{1.09i} would like to rename this to \csa{Etoc@setlocaltop}, for
12008 % consistency with internal macros, but too late it is already in user |.toc| files.
12009 % \begin{macrocode}
12010 \def\etoc@setlocaltop #1{%
12011 \ifnum#1=\Etoc@maxlevel
12012 \Etoc@skipthisonetrue
12013 \else
12014 \Etoc@skipthisonefalse
12015 % \end{macrocode}
12016 % MEMO: the \csbc{Etoc@level} thus continues receiving updates from various
12017 % \csbc{etoc@setlocaltop} present in the |.toc| file even once the local toc
12018 % is already done, but this has no importance, as the code in
12019 % \csbc{Etoc@toctoc} after executing the code contents is not influenced by
12020 % this but only by the final status of \csbc{Etoc@stackofends} remains the
12021 % same. And this gets updated via \csbc{Etoc@setlocaltop@doendsandbegin} (see
12022 % below).
12023 %
12024 % I should check if not worthwile to move the \csbc{ifEtoc@stoptoc} test
12025 % earlier.
12026 %
12027 % There should be two notions of local top. One for a potential barrier,
12028 % stopping a toc, the other for setting a local top. These two should be
12029 % distinct. Or at least additional to this one which does both. But then I
12030 % would have to document. And test. And implement first.
12031 % \begin{macrocode}
12032 \global\let\Etoc@level #1%
12033 \global\let\Etoc@virtualtop #1%
12034 \ifEtoc@localtoc
12035 \ifEtoc@stoptoc
12036 \Etoc@skipthisonetrue
12037 \else
12038 \ifEtoc@notactive
12039 \Etoc@skipthisonetrue
12040 \else
12041 \unless\ifnum\Etoc@level>\etoclocaltop
12042 \Etoc@skipthisonetrue
12043 \global\Etoc@stoptoctrue
12044 \fi
12045 \fi
12046 \fi
12047 \fi
12048 \fi
12049 \let\Etoc@next\@empty
12050 \ifEtoc@skipthisone
12051 \else
12052 \ifnum\Etoc@level>\c@tocdepth
12053 \else
12054 \ifEtoc@standardlines
12055 \else
12056 % \end{macrocode}
12057 % So here the \csbc{etocsetlocaltop}|.toc| will cause various starts and
12058 % finish parts to get executed, even for the somewhat fictitious levels. But
12059 % this may cause collaterals, in particular we have to be careful about the
12060 % \csbc{ifEtoc@skipprefix} Boolean, which may be set to \csa{iftrue} in
12061 % the \marg{start} part of the level style and thus needs to be reset to
12062 % \csa{iffalse}. This is done automatically in \csbc{Etoc@etoccontentsline@}
12063 % but here we are not executing it so we need to add somewhere a
12064 % |\global\Etoc@skipprefixfalse| (else we may impact rendering of subsequent
12065 % level). So we put it together with \csbc{Etoc@doendsandbegin} in a wrapper.
12066 % This wrapper is also there to avoid a problem when the TOC is checked for
12067 % emptiness, as we need then to be able to tell \csbc{etoc@setlocaltop} to
12068 % not execute anything.
12069 %
12070 % This also stresses
12071 % that the name of the macro is a bit of a misnomer, yes it serves to delimit
12072 % local table of contents, but really it is implemented as a ghost of a
12073 % sectioning unit which does have an impact (on the global TOC or local TOCs
12074 % from encompassing levels), as it triggers when encountered the \marg{finish}
12075 % portions of previous finer levels (and the \marg{finish} code of its own
12076 % level will be executed sooner or later), and the \marg{start} code of
12077 % subsequent finer levels (as well as its own \marg{start} code at least once,
12078 % depending on how levels are nested).
12079 % \begin{macrocode}
12080 \let\Etoc@next\Etoc@setlocaltop@doendsandbegin
12081 \fi
12082 \fi
12083 \fi
12084 \Etoc@next
12085 }%
12086 % \end{macrocode}
12087 % It is important to reset the \csbc{ifEtoc@skipprefix} boolean, as is done in
12088 % \csbc{Etoc@etoccontentsline@}.\par
12089 % \begin{macrocode}
12090 \def\Etoc@setlocaltop@doendsandbegin{%
12091 \Etoc@doendsandbegin
12092 \global\Etoc@skipprefixfalse
12093 }
12094 \addtocontents {toc}{\protect\@ifundefined{etoctocstyle}%
12095 {\let\protect\etoc@startlocaltoc\protect\@gobble
12096 \let\protect\etoc@settocdepth\protect\@gobble
12097 \let\protect\etoc@depthtag\protect\@gobble
12098 \let\protect\etoc@setlocaltop\protect\@gobble}{}}%
12099 % \end{macrocode}
12100 % Initializations.
12101 % \begin{macrocode}
12102 \def\etocstandardlines {\Etoc@standardlinestrue}
12103 \def\etoctoclines {\Etoc@standardlinesfalse}
12104 \etocfallbacklines
12105 \etocstandardlines
12106 \def\etocstandarddisplaystyle{%
12107 \PackageWarningNoLine{etoc}{%
12108 \string\etocstandarddisplaystyle \on@line\MessageBreak
12109 is deprecated. \space Please use \string\etocclasstocstyle}%
12110 }
12111 \expandafter\def\expandafter\etocclasstocstyle\expandafter{%
12112 \etocclasstocstyle
12113 \Etoc@classstyletrue
12114 }
12115 \def\etocetoclocaltocstyle{\Etoc@etocstyletrue}
12116 \def\etocusertocstyle{\Etoc@etocstylefalse}
12117 \etocclasstocstyle
12118 \etocetoclocaltocstyle
12119 \etocobeytoctocdepth
12120 \etocobeydepthtags
12121 \let\etocbeforetitlehook \@empty
12122 \let\etocaftertitlehook \@empty
12123 \let\etocaftercontentshook \@empty
12124 \let\etocaftertochook \@empty
12125 % \end{macrocode}
12126 % |listings| abuses \csa{tableofcontents} for its \csa{lstlistoflistings}. It
12127 % doesn't seem worth to let my version of \csbc{tableofcontents} have to check for
12128 % this special circumstance. So at \etocrelease{1.09d}, simply add this (the
12129 % boolean was added at \etocrelease{1.2}):
12130 % \begin{macrocode}
12131 \def\etockeeporiginaltableofcontents
12132 {\Etoc@keeporiginaltoctrue\let\tableofcontents\etocoriginaltableofcontents}%
12133 \endinput
12134 % \end{macrocode}
12135 % \MakePercentComment
12136 \Finale
12137 %%
12138 %% End of file `etoc.dtx'.