summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/etoc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-03-03 03:05:02 +0000
committerNorbert Preining <norbert@preining.info>2023-03-03 03:05:02 +0000
commitc000ad35f0ce69cc0466ad24b0647c1e295c0259 (patch)
tree6c64b429a374b5d60b67c2f728c71acb110c775c /macros/latex/contrib/etoc
parentfe8af26a7b8f32a0cc1b761e3ffb95ed0867a845 (diff)
CTAN sync 202303030305
Diffstat (limited to 'macros/latex/contrib/etoc')
-rw-r--r--macros/latex/contrib/etoc/README.md233
-rw-r--r--macros/latex/contrib/etoc/etoc.dtx9443
-rw-r--r--macros/latex/contrib/etoc/etoc.pdfbin857380 -> 940496 bytes
3 files changed, 5561 insertions, 4115 deletions
diff --git a/macros/latex/contrib/etoc/README.md b/macros/latex/contrib/etoc/README.md
index b452990b34..ed067af271 100644
--- a/macros/latex/contrib/etoc/README.md
+++ b/macros/latex/contrib/etoc/README.md
@@ -1,6 +1,6 @@
<!-- -->
- Source: etoc.dtx (1.1c)
+ Source: etoc.dtx (1.2)
Author: Jean-Francois Burnol
Info: Completely customisable TOCs
License: LPPL 1.3c
@@ -10,68 +10,49 @@
ABSTRACT
========
-The etoc package gives to the user complete control on how the entries
-of the table of contents should be constituted from the *name*,
-*number*, and *page number* of each sectioning unit. This goes via the
-definition of *line styles* for each sectioning level used in the
-document. The package provides its own custom line styles. Simpler
-ones are given as examples in the documentation. The simplest usage
-will be to take advantage of the layout facilities of packages dealing
-with list environments.
-
-Regarding the *global toc display*, etoc provides pre-defined styles
-based on a multi-column format, with, optionally, a ruled title or
-framed contents.
-
-The `\tableofcontents` command may be used arbitrarily many times and
-it has a variant `\localtableofcontents` which prints tables of
-contents 'local' to the current surrounding document unit. An
-extension of the `\label/\ref` syntax allows to reproduce (with
-another layout) a local table of contents defined somewhere else in
-the document.
-
-Via *depth tags*, one gets an even finer control for each table of
-contents of which sectioning units it should, or not, display.
-
-The formatting inherited (and possibly customized by other packages)
-from the document class will be used when in compatibility mode.
-
-The assignment of levels to the sectioning units can be changed at any
-time, and etoc can thus be used in a quite general manner to create
-custom ''lists of'', additionally to the tables of contents related to
-the document sectioning units. No auxiliary file is used additionally
-to the standard `.toc` file.
+With `etoc` loaded, `\tableofcontents` can be used multiple times and
+an added command `\localtableofcontents` allows to typeset "local"
+tables of contents, i.e. having their scope limited to the last
+sectioning command encountered.
+
+No auxiliary file is used additionally to the standard `.toc` file.
+Release 1.2 provides experimental additions `\locallistoffigures` and
+`\locallistoftables` which also use only the `.toc` file.
+
+Such local TOCs or "Lists Of" typically need to adopt a "display
+style" (i.e. the way the title is rendered, whether it should add
+itself an entry in the `.toc` file, ...) somewhat distinct from the
+global TOC. The release 1.2 default adapts automatically the titles
+of local TOCs to their depths in the sectioning hierarchy. Should the
+need arise to customize such "display style", full control is allowed
+by package commands.
+
+Regarding how the individual "contents lines" are handled, here again
+complete control is given to the user to define from the ground-up how
+to use the *name*, *number*, and *page number* for each entry,
+according to their "levels" (i.e. part, chapter, section, subsection,
+...). As this requires some LaTeX fluency, many examples which can
+serve as starting points are attached to the PDF documentation as
+extractible files.
+
+Loading `etoc` per itself modifies nothing to "contents lines"
+rendering from the class default or changes from other packages. But
+full usage of the package allows spectacular effects such as displaying
+TOCs as trees or mind maps.
INSTALLATION
============
-To extract the package (.sty) and driver (.tex) files from etoc.dtx,
-execute `etex etoc.dtx`.
-
-It is also possible to execute latex or pdflatex directly on etoc.dtx.
-
-To produce etoc.pdf one can run pdflatex directly on etoc.dtx or on
-the file etoc.tex which was extracted from `etex etoc.dtx` step.
-
-Options can be set in etoc.tex:
-
-- scrartcl class options (paper size, font size, ...)
-- with or without source code,
-- with dvipdfmx or with latex+dvips or pdflatex.
-
-Since release 1.08h pdflatex is the default in etoc.tex (prior it
-was latex+dvipdfmx as it produces smaller PDFs) in order to allow
-inclusion via the use of package `attachfile` of about 25 code
-samples as file attachment annotations.
-
-Installation:
+For manual installation do `etex etoc.dtx` to extract files then move
+`etoc.sty` to a place where TeX can find it.
etoc.sty -> TDS:tex/latex/etoc/etoc.sty
etoc.dtx -> TDS:source/latex/etoc/etoc.dtx
etoc.pdf -> TDS:doc/latex/etoc/etoc.pdf
README.md -> TDS:doc/latex/etoc/README.md
-The other files may be discarded.
+To produce `etoc.pdf` run pdflatex on the extracted file `etoc.tex`
+sufficiently many times (`latexmk -pdf etoc` is recommended).
LICENSE
=======
@@ -97,123 +78,29 @@ etoc.sty, etoc.tex, etoc.pdf, etoc.dvi.
RECENT CHANGES
==============
-1.1c \[2023/01/20\]
--------------------
-
-Fix a brace removal bug in the construction of `\etocname`. It
-remained without visible effects in documents using `hyperref` and
-default settings, thanks to the hyperlink wrapper, but e.g.
-`\section{{\color{blue}Blue}}` in a document not using `hyperref`,
-and not using etoc only in "compatibility mode", could cause a
-color leak in the table of contents.
-
-With the KOMA-script numberline toc feature, unnumbered entries in
-TOCs typeset via etoc user-defined or package provided line styles
-but using compatibility mode for the global display style were
-(knowingly) considered to be numbered with an empty number. They
-are now considered by `\etocifnumbered` to be not numbered and the
-empty `\etocnumber` will carry no hyperlink.
-
-Fix a 1.1a regression in the context of KOMA-script unnumbered TOC
-entries: `\etocthelinkedname` could lose its hyperlink.
-
-Continue internal trimming of old code branches which became
-un-needed after the 1.1a refactoring. Add relatively decent
-code comments to accompany the 1.1a-c refactoring. Update
-warning messages to use more consistently LaTeX's templates.
-
-1.1b \[2023/01/15\]
--------------------
-
-Documentation fix, 1.1a forgot to mention the following change:
-`\etocthelinkedname`, `\etocthelinkednumber`, `\etocthelinkedpage`
-are now always hyperlinks independently of linktoc status.
-
-1.1a \[2023/01/14\]
--------------------
-
-This version brings no new functionality, despite the number bump.
-It implements a complete rewrite of old legacy core internals.
-Formerly, etoc waited for
-[hyperref](https://ctan.org/pkg/hyperref)
-(if present) to have added hyperlinks via its patch to LaTeX's
-`\contentsline`. etoc examined the arguments of `\l@section` and
-other commands to extract hyperlinking information, if any.
-With this release etoc decides earlier according to
-[hyperref](https://ctan.org/pkg/hyperref)
-linktoc status whether section names and page numbers
-should be hyperlinked, and adds links itself via `\hyperlink`.
-etoc is thus now immune to the details of how hyperref patches
-the `\contentsline` command, which is not executed anymore.
-Overall, the code is greatly simplified.
-
-`\etoclink` now wraps its argument in an hyperlink even if
-[hyperref](https://ctan.org/pkg/hyperref) is configured via
-`linktoc=none`. Formerly no hyperlink was added then.
-
-Deprecation of `\etocsavedsectiontocline` and similarly named
-commands. They are not needed as `\l@section` et al. are with this
-release left unmodified during the table of contents typesetting.
-
-LaTeX kernel from `2020/10/01` or later is required (to allow
-assuming the `\contentsline` entries in the TOC file always have
-four arguments).
-
-1.09i \[2022/11/21\]
---------------------
-
-Fix bug showing when a document uses both `\etocchecksemptiness` and
-`\etocsetlocaltop.toc`: the `start` and `finish` parts of some levels
-were executed possibly causing extra printed output.
-
-More hyperlinking in the implementation part of the documentation.
-
-1.09h \[2022/11/20\]
---------------------
-
-Documentation improvements. In particular, attached code snippets
-are now visible via their filenames in the page margins. Also,
-command names are doubly hyperlinked: first half links to the devoted
-part of the user manual, second half links to the implementation part.
-
-1.09g \[2022/11/17\]
---------------------
-
-Compatibility hotfix with recent hyperref `7.00u` of `2022-11-13`.
-Thanks to Denis Bitouzé for signaling the breakage to the author.
-
-1.09f \[2022/08/30\]
---------------------
-
-No more shipping of a German translation of the documentation, as
-it was last updated in April 2015.
-
-(etoc.pdf) User level commands hyperlink from their code source
-definitions to their descriptions in the documentation part. Macros
-used in the code source hyperlink to where they first got defined
-there.
-
-Wrap the `\etocpartname` (from etoc's package provided toc line style)
-together with the part number in a potential common hyperlink.
-
-Try to sync the emulation of the global display style with KOMA-script
-`v3.37` (in particular regarding the `noparskipfake` KOMA toc feature).
-
-Improve documentation of some aspects under `memoir` class.
-
-Remove the `\nonumberline` token, even though empty, from the meaning of
-`\etocthename` (KOMA-script classes).
-
-Add `\etocimmediatedepthtag.toc` to work around problems related to
-`\include` (see user doc). Thanks to Norman Ramsey who reported the problem
-and proposed a work-around in July 2016. Apologies for the somewhat longish
-delay in incorporating it...
-
-Also add `\etocimmediatesettocdepth.toc`.
-
-Also add `\etocimmediatetoccontentsline` and its starred variant.
-
-Also add `\etocimmediatesetlocaltop.toc`.
-
-Fix an obscure bug (see source code comments) in the `\etocsetlocaltop.toc`
-mechanism.
+This is `1.2` of `2023/03/01`.
+
+`1.1a` up to `1.1d` were mainly about refactoring core legacy code
+dating back to the earliest versions of the package. The initial
+stimulus came from the necessity to prepare for changes to how
+hyperref and the LaTeX kernel will interact in the future.
+
+`1.2` added `\locallistoffigures` and `\locallistoftables`. One must
+pass options `lof` and `lot` to the package to activate these
+experimental features.
+
+The initial default rendering of the titles of tables of contents now
+uses the emulated document class code only for the global ones
+(`\tableofcontents`); for local ones (`localtableofcontents` and the
+new "local lists of") it uses by default a context aware title
+(such as `\subsection*` if local to a section). Thus, usage of
+`\etocsettocstyle` is now purely optional. Regarding the
+"line styles", the package has always used the unaltered rendering
+from the document class, so using the other core customization command
+`\etocsetstyle` to truly unleash the package powers has always been
+optional.
+
+Shoud they dare to go check the PDF documentations, users will
+discover that it has been completely restructured at release `1.2`, to
+the extent allowed by random permutations of topics, and that many
+commands have been added to facilitate usage of `\etocsettocstyle`.
diff --git a/macros/latex/contrib/etoc/etoc.dtx b/macros/latex/contrib/etoc/etoc.dtx
index 98ed8726ab..8dd0df588a 100644
--- a/macros/latex/contrib/etoc/etoc.dtx
+++ b/macros/latex/contrib/etoc/etoc.dtx
@@ -1,30 +1,26 @@
-% -*- coding: utf-8; time-stamp-format: "%02d-%02m-%:y at %02H:%02M:%02S %Z" -*-
-% N.B.: this dtx file is NOT for use with \DocInput. The latex source of the
-% user manual is not prefixed with percent signs.
+% -*- coding: utf-8; time-stamp-format: "%02d-%02m-%:y at %02H:%02M:%02S %Z" ; time-stamp-active: nil -*-
+% N.B.: this dtx file does NOT use \DocInput. It does NOT prefix the user
+% manual part with percent characters.
%<*none>
-\def\etocdtxtimestamp {Time-stamp: <20-01-2023 at 21:03:03 CET>}%
+\def\etocdtxtimestamp {Time-stamp: <01-03-2023 at 23:38:38 CET>}%
%</none>
%<*!readme>
%%
%% Package: etoc
-%% Version: 1.1c
+%% Version: 1.2
%% License: LPPL 1.3c
%% Copyright (C) 2012-2023 Jean-Francois Burnol
%% <jfbu at free dot fr>
%</!readme>
%<*none>
-\def\etocpkgdate {2023/01/20}
-\def\etocdocdate {2023/01/20}
-\def\etocpkgversion {1.1c}
+\def\etocpkgdate {2023/03/01}
+\def\etocdocdate {2023/03/01}
+\def\etocpkgversion {1.2}
\def\etocpkgdescription {Completely customisable TOCs (JFB)}
-%% German translation was last udpated on April 2015 and all new material
-%% was included since in English. During 2020/2021/2022 emerged a still
-%% unresolved texdoc problem which always displays etoc-DE.pdf preferentially.
-%% On 2022/08/26, decision is made to stop shipping this etoc-DE.pdf.
-%% The dtx gets purged from its soure as well.
-%% Not sure if I will make pdf available for download from some web site,
-%% but this can always be done if requests emerge; but I hesitate for
-%% the location.
+%% Formerly this etoc.dtx also included source for a German translation
+%% etoc-DE.pdf. But all additions since April 2015 had been only in English.
+%% Since 1.09f of 2022/08/30 etoc-DE.pdf is not produced anymore and the
+%% existing translated sections have been removed from this etoc.dtx.
% Definition of \etocLicense
% --------------------------
\begingroup
@@ -33,7 +29,7 @@
\catcode32=13\catcode`\\=12^^Brelax^^A
^^Bfirstofone{^^Bendgroup^^Bdef^^BetocLicense^^A
{% Package: etoc
-% Version: 1.1c
+% Version: 1.2
% License: LPPL 1.3c
% Copyright (C) 2012-2023 Jean-Francois Burnol <jfbu at free dot fr>
%
@@ -60,7 +56,7 @@
%<*readme>
<!-- -->
- Source: etoc.dtx (1.1c)
+ Source: etoc.dtx (1.2)
Author: Jean-Francois Burnol
Info: Completely customisable TOCs
License: LPPL 1.3c
@@ -70,68 +66,51 @@
ABSTRACT
========
-The etoc package gives to the user complete control on how the entries
-of the table of contents should be constituted from the *name*,
-*number*, and *page number* of each sectioning unit. This goes via the
-definition of *line styles* for each sectioning level used in the
-document. The package provides its own custom line styles. Simpler
-ones are given as examples in the documentation. The simplest usage
-will be to take advantage of the layout facilities of packages dealing
-with list environments.
-
-Regarding the *global toc display*, etoc provides pre-defined styles
-based on a multi-column format, with, optionally, a ruled title or
-framed contents.
-
-The `\tableofcontents` command may be used arbitrarily many times and
-it has a variant `\localtableofcontents` which prints tables of
-contents 'local' to the current surrounding document unit. An
-extension of the `\label/\ref` syntax allows to reproduce (with
-another layout) a local table of contents defined somewhere else in
-the document.
-
-Via *depth tags*, one gets an even finer control for each table of
-contents of which sectioning units it should, or not, display.
-
-The formatting inherited (and possibly customized by other packages)
-from the document class will be used when in compatibility mode.
-
-The assignment of levels to the sectioning units can be changed at any
-time, and etoc can thus be used in a quite general manner to create
-custom ''lists of'', additionally to the tables of contents related to
-the document sectioning units. No auxiliary file is used additionally
-to the standard `.toc` file.
+With `etoc` loaded, `\tableofcontents` can be used multiple times and
+an added command `\localtableofcontents` allows to typeset "local"
+tables of contents, i.e. having their scope limited to the last
+sectioning command encountered.
+
+No auxiliary file is used additionally to the standard `.toc` file.
+Release 1.2 provides experimental additions `\locallistoffigures` and
+`\locallistoftables` which also use only the `.toc` file.
+
+Such local TOCs or "Lists Of" typically need to adopt a "display
+style" (i.e. the way the title is rendered, whether it should add
+itself an entry in the `.toc` file, ...) somewhat distinct from the
+global TOC. The release 1.2 default adapts automatically the titles
+of local TOCs to their depths in the sectioning hierarchy. Should the
+need arise to customize such "display style", full control is allowed
+by package commands.
+
+Regarding how the individual "contents lines" are handled, here again
+complete control is given to the user to define from the ground-up how
+to use the *name*, *number*, and *page number* for each entry,
+according to their "levels" (i.e. part, chapter, section, subsection,
+...). As this requires some LaTeX fluency, many examples which can
+serve as starting points are attached to the PDF documentation as
+extractible files.
+
+Loading `etoc` per itself modifies nothing to "contents lines"
+rendering from the class default or changes from other packages. But
+full usage of the package allows spectacular effects such as displaying
+TOCs as trees or mind maps.
+
INSTALLATION
============
-To extract the package (.sty) and driver (.tex) files from etoc.dtx,
-execute `etex etoc.dtx`.
-
-It is also possible to execute latex or pdflatex directly on etoc.dtx.
-
-To produce etoc.pdf one can run pdflatex directly on etoc.dtx or on
-the file etoc.tex which was extracted from `etex etoc.dtx` step.
-
-Options can be set in etoc.tex:
-
-- scrartcl class options (paper size, font size, ...)
-- with or without source code,
-- with dvipdfmx or with latex+dvips or pdflatex.
-
-Since release 1.08h pdflatex is the default in etoc.tex (prior it
-was latex+dvipdfmx as it produces smaller PDFs) in order to allow
-inclusion via the use of package `attachfile` of about 25 code
-samples as file attachment annotations.
-
-Installation:
+For manual installation do `etex etoc.dtx` to extract files then move
+`etoc.sty` to a place where TeX can find it.
etoc.sty -> TDS:tex/latex/etoc/etoc.sty
etoc.dtx -> TDS:source/latex/etoc/etoc.dtx
etoc.pdf -> TDS:doc/latex/etoc/etoc.pdf
README.md -> TDS:doc/latex/etoc/README.md
-The other files may be discarded.
+To produce `etoc.pdf` run pdflatex on the extracted file `etoc.tex`
+sufficiently many times (`latexmk -pdf etoc` is recommended).
+
LICENSE
=======
@@ -154,141 +133,48 @@ The Author of this Work is Jean-Francois Burnol <jfbu at free dot fr>
This Work consists of the main source file etoc.dtx and the derived files
etoc.sty, etoc.tex, etoc.pdf, etoc.dvi.
+
RECENT CHANGES
==============
-1.1c \[2023/01/20\]
--------------------
-
-Fix a brace removal bug in the construction of `\etocname`. It
-remained without visible effects in documents using `hyperref` and
-default settings, thanks to the hyperlink wrapper, but e.g.
-`\section{{\color{blue}Blue}}` in a document not using `hyperref`,
-and not using etoc only in "compatibility mode", could cause a
-color leak in the table of contents.
-
-With the KOMA-script numberline toc feature, unnumbered entries in
-TOCs typeset via etoc user-defined or package provided line styles
-but using compatibility mode for the global display style were
-(knowingly) considered to be numbered with an empty number. They
-are now considered by `\etocifnumbered` to be not numbered and the
-empty `\etocnumber` will carry no hyperlink.
-
-Fix a 1.1a regression in the context of KOMA-script unnumbered TOC
-entries: `\etocthelinkedname` could lose its hyperlink.
-
-Continue internal trimming of old code branches which became
-un-needed after the 1.1a refactoring. Add relatively decent
-code comments to accompany the 1.1a-c refactoring. Update
-warning messages to use more consistently LaTeX's templates.
-
-1.1b \[2023/01/15\]
--------------------
-
-Documentation fix, 1.1a forgot to mention the following change:
-`\etocthelinkedname`, `\etocthelinkednumber`, `\etocthelinkedpage`
-are now always hyperlinks independently of linktoc status.
-
-1.1a \[2023/01/14\]
--------------------
-
-This version brings no new functionality, despite the number bump.
-It implements a complete rewrite of old legacy core internals.
-Formerly, etoc waited for
-[hyperref](https://ctan.org/pkg/hyperref)
-(if present) to have added hyperlinks via its patch to LaTeX's
-`\contentsline`. etoc examined the arguments of `\l@section` and
-other commands to extract hyperlinking information, if any.
-With this release etoc decides earlier according to
-[hyperref](https://ctan.org/pkg/hyperref)
-linktoc status whether section names and page numbers
-should be hyperlinked, and adds links itself via `\hyperlink`.
-etoc is thus now immune to the details of how hyperref patches
-the `\contentsline` command, which is not executed anymore.
-Overall, the code is greatly simplified.
-
-`\etoclink` now wraps its argument in an hyperlink even if
-[hyperref](https://ctan.org/pkg/hyperref) is configured via
-`linktoc=none`. Formerly no hyperlink was added then.
-
-Deprecation of `\etocsavedsectiontocline` and similarly named
-commands. They are not needed as `\l@section` et al. are with this
-release left unmodified during the table of contents typesetting.
-
-LaTeX kernel from `2020/10/01` or later is required (to allow
-assuming the `\contentsline` entries in the TOC file always have
-four arguments).
-
-1.09i \[2022/11/21\]
---------------------
-
-Fix bug showing when a document uses both `\etocchecksemptiness` and
-`\etocsetlocaltop.toc`: the `start` and `finish` parts of some levels
-were executed possibly causing extra printed output.
-
-More hyperlinking in the implementation part of the documentation.
-
-1.09h \[2022/11/20\]
---------------------
-
-Documentation improvements. In particular, attached code snippets
-are now visible via their filenames in the page margins. Also,
-command names are doubly hyperlinked: first half links to the devoted
-part of the user manual, second half links to the implementation part.
-
-1.09g \[2022/11/17\]
---------------------
-
-Compatibility hotfix with recent hyperref `7.00u` of `2022-11-13`.
-Thanks to Denis Bitouzé for signaling the breakage to the author.
-
-1.09f \[2022/08/30\]
---------------------
-
-No more shipping of a German translation of the documentation, as
-it was last updated in April 2015.
-
-(etoc.pdf) User level commands hyperlink from their code source
-definitions to their descriptions in the documentation part. Macros
-used in the code source hyperlink to where they first got defined
-there.
-
-Wrap the `\etocpartname` (from etoc's package provided toc line style)
-together with the part number in a potential common hyperlink.
-
-Try to sync the emulation of the global display style with KOMA-script
-`v3.37` (in particular regarding the `noparskipfake` KOMA toc feature).
-
-Improve documentation of some aspects under `memoir` class.
-
-Remove the `\nonumberline` token, even though empty, from the meaning of
-`\etocthename` (KOMA-script classes).
-
-Add `\etocimmediatedepthtag.toc` to work around problems related to
-`\include` (see user doc). Thanks to Norman Ramsey who reported the problem
-and proposed a work-around in July 2016. Apologies for the somewhat longish
-delay in incorporating it...
-
-Also add `\etocimmediatesettocdepth.toc`.
-
-Also add `\etocimmediatetoccontentsline` and its starred variant.
-
-Also add `\etocimmediatesetlocaltop.toc`.
-
-Fix an obscure bug (see source code comments) in the `\etocsetlocaltop.toc`
-mechanism.
+This is `1.2` of `2023/03/01`.
+
+`1.1a` up to `1.1d` were mainly about refactoring core legacy code
+dating back to the earliest versions of the package. The initial
+stimulus came from the necessity to prepare for changes to how
+hyperref and the LaTeX kernel will interact in the future.
+
+`1.2` added `\locallistoffigures` and `\locallistoftables`. One must
+pass options `lof` and `lot` to the package to activate these
+experimental features.
+
+The initial default rendering of the titles of tables of contents now
+uses the emulated document class code only for the global ones
+(`\tableofcontents`); for local ones (`localtableofcontents` and the
+new "local lists of") it uses by default a context aware title
+(such as `\subsection*` if local to a section). Thus, usage of
+`\etocsettocstyle` is now purely optional. Regarding the
+"line styles", the package has always used the unaltered rendering
+from the document class, so using the other core customization command
+`\etocsetstyle` to truly unleash the package powers has always been
+optional.
+
+Shoud they dare to go check the PDF documentations, users will
+discover that it has been completely restructured at release `1.2`, to
+the extent allowed by random permutations of topics, and that many
+commands have been added to facilitate usage of `\etocsettocstyle`.
%</readme>
%<*tex>-------------------------------------------------------------------------
%% To produce the documentation etoc.pdf with source code included:
%% latexmk -pdf etoc.tex
-%% Or
-%% pdflatex etoc.tex
-%% enough times. For customizations see comments and classe options below.
+%% (or sufficiently many times pdflatex etoc.tex)
+%% For customizations see comments and classe options below.
+\tracinglostchars3
\chardef\Withdvipdfmx 0 % replace 0 by 1 for using latex+dvipdfmx
\chardef\NoSourceCode 0 % replace 0 by 1 for the doc *without* the source code
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile {etoc.tex}[Driver for etoc documentation]%
-\PassOptionsToClass {a4paper,fontsize=11pt,twoside}{scrartcl}
+\PassOptionsToClass {a4paper,fontsize=10pt,twoside}{scrartcl}
\PassOptionsToPackage {ngerman,english}{babel}
\input etoc.dtx
%%% Local Variables:
@@ -311,7 +197,7 @@ mechanism.
\chardef\Withdvipdfmx 0 % 0 = pdflatex or latex+dvips, 1 = dvipdfmx
\chardef\NoSourceCode 1 % 0 = include source code, 1 = do not
\NeedsTeXFormat {LaTeX2e}%
- \PassOptionsToClass {a4paper,fontsize=11pt,twoside}{scrartcl}%
+ \PassOptionsToClass {a4paper,fontsize=10pt,twoside}{scrartcl}%
\PassOptionsToPackage {ngerman,english}{babel}%
\else % latex run is on etoc.tex
\chardef\extractfiles 2 % do not extract files, only typeset
@@ -329,8 +215,8 @@ mechanism.
\Msg{*^^J}%
\Msg{*\space\space\space\space etoc.sty^^J}%
\Msg{*^^J}%
-\Msg{* To produce the documentation with source code included run pdflatex^^J}%
-\Msg{* thrice on file etoc.tex^^J}%
+\Msg{* To produce the documentation with source code included execute^^J}%
+\Msg{* latexmk -pdf etoc.tex^^J}%
\Msg{*^^J}%
\Msg{* Happy TeXing!^^J}%
\Msg{*^^J}%
@@ -362,7 +248,7 @@ mechanism.
\ifdefined\MessageDeFin\AtEndDocument{\MessageDeFin}\fi
%-------------------------------------------------------------------------------
% START OF USER MANUAL TEX SOURCE
-\documentclass[abstract]{scrartcl}
+\documentclass{scrartcl}
\makeatletter
%%% START OF CUSTOM doc.sty LOADING (May 21, 2022 in xint.dtx)
@@ -492,6 +378,17 @@ mechanism.
%%% copied over almost verbatim to etoc.dtx on 2022/08/26.
%%% See after \StopEventually for doc.sty hacks.
+\makeatletter
+% pour maintenir les % en début de ligne dans les blocs verbatim
+ \let\original@check@percent\check@percent
+ \let\check@percent\relax
+\makeatother
+
+
+% We got sensible result with attachfile or attachfile2
+% only with pdflatex. So this is remnant of earlier
+% times when etoc.pdf was produced via latex+dvipdfmx
+
\usepackage{ifpdf}
\ifpdf\chardef\Withdvipdfmx 0 \fi
@@ -512,19 +409,20 @@ mechanism.
\makeatother
\usepackage[T1]{fontenc}
-\usepackage[utf8]{inputenc}
\usepackage[hscale=0.66,vscale=0.75]{geometry}
+
+% Some problems with headers
\pagestyle{headings}
% \sectionmark uses \markboth in twoside but
% with an empty right mark! As a result if a section starts
% on an odd page, it does not appear in the header mark.
% Perhaps there was a subsection of 3 lines on that page
% and it is the subsection which decides what is in the header.
-\makeatletter
% Some custom \sectionmark to get headers more to my taste.
% But it is hard to find algorithm giving satisfaction in all cases.
+\makeatletter
\renewcommand *{\sectionmark }[1]{%
% Que c'est pénible cette syntaxe \markboth/\markright de LaTeX !
% Pourquoi est-ce que \markright n'a pas été définie comme #1#2-> truc avec #2 ??
@@ -561,23 +459,13 @@ mechanism.
% peut-être serait-ce mieux de mettre le \thispagestyle après mon \clearpage,
% explicitement dans la source
\def\part{\thispagestyle{mypartheadings}\scr@startpart {part}}
-
-\makeatother
-
-\usepackage{centeredline}% replaces the 2013/03/07 original code
-
-\makeatletter
-% pour maintenir les % en début de ligne dans les blocs verbatim
-%
-
- \let\original@check@percent\check@percent
- \let\check@percent\relax
\makeatother
-
% pour les environnements verbatim
% uniformisé finalement, avec quelques exceptions, pour dtx du 3 déc 2013
-\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
+%\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
+% Je supprime le small finalement 2023/02/28 mais passe en 10pt
+\def\MacroFont{\ttfamily\hyphenchar\font45\relax\setstretch{1}}
%----
@@ -635,15 +523,15 @@ mechanism.
\def\makestarlowast {\catcode`\*\active\let~\lowast}}%
\makeatother
%
-\usepackage{txfonts}
-
-
-% -start- font adjustment 2013
-
+%%%% FONT CONFIGURATION
+\usepackage{txfonts}
+% (2013) rescale the monospace font to 92% and allow hyphenation
+% (2023) fix the missing rescaling of bold series of txttt
\DeclareFontFamily{T1}{txtt}{\hyphenchar\font 45\relax}
+%\DeclareFontFamily{T1}{txtt}{\hyphenchar\font -1\relax}
\DeclareFontShape{T1}{txtt}{m}{n}{ %medium
<->s*[.96] t1xtt%
}{}
@@ -659,7 +547,7 @@ mechanism.
\DeclareFontShape{T1}{txtt}{m}{ui}{ %unslanted italic
<->ssub * txtt/m/sl%
}{}
-% ---- /added scale factor 2023
+% ---- /added here missing scale factor 2023
\DeclareFontShape{T1}{txtt}{bx}{n}{ %bold extended
<->s*[.96] t1xbtt%
}{}
@@ -670,7 +558,7 @@ mechanism.
\DeclareFontShape{T1}{txtt}{bx}{sl}{ %bold extended slanted
<->s*[.96] t1xbttsl%
}{}
-% ---- /end of 2023 change
+% ---- /end of 2023 fix
\DeclareFontShape{T1}{txtt}{bx}{it}{ %bold extended italic
<->ssub * txtt/bx/sl%
}{}
@@ -692,8 +580,8 @@ mechanism.
\DeclareFontShape{T1}{txtt}{b}{ui}{ %bold unslanted italic
<->ssub * txtt/bx/ui%
}{}
-% -end- font adjustment 2013
-% -start- font adjustment 2023
+
+% (2023) also rescale the txss sans serif (Helvetica)
\DeclareFontFamily{T1}{txss}{}
\DeclareFontShape{T1}{txss}{m}{n}{ %medium
<->s * [0.89]t1xss%
@@ -740,7 +628,16 @@ mechanism.
\DeclareFontShape{T1}{txss}{b}{ui}{ %bold unslanted italic
<->ssub * txss/bx/ui%
}{}
-% -end- font adjustment 2023
+%
+
+
+% Use the Bitter typeface for the romanfamily
+\usepackage[scale=0.87]{bitter}
+
+\AddToHook{begin/document/after}{%
+ \renewcommand{\familydefault}{\sfdefault}%
+ \rmfamily
+}
\usepackage{xspace}
% added svgnames 2022/08/26 on occasion of transfer from xint colouring scheme
@@ -754,22 +651,44 @@ mechanism.
\definecolor{JOLI}{RGB}{225,95,0}
\definecolor{BLUE}{RGB}{0,0,255}
\colorlet{niceone}{green!35!blue!75}
+\colorlet{optioncolor}{Maroon}
+
+% These colours mostly used only after stopeventually
+\definecolor{etocnamecolor}{RGB}{228,57,0}
+\colorlet{verbcolor}{Maroon}
+\colorlet{privatecommentcolor}{cyan}
+\colorlet{macrocodecommentcolor}{gray}
+\colorlet{macrocodenewmacrocolor}{verbcolor}
+\colorlet{macrocodelinktouserdoccolor}{etocnamecolor}% and bold face
+\colorlet{macrocodelinktosectioncolor}{DarkBlue}% and bold face
+\colorlet{macrocodelinktocodelinecolor}{Blue}
+\colorlet{macrocodenoncscolor}{Green}
\usepackage {babel} % ngerman and english options have been passed to babel
-\AtBeginDocument {
+\AtBeginDocument {%
+% this may be obsolete as I don't use scrdoc or ltxdoc classes anymore
\renewcommand\partname{Part}%
\addto\captionsenglish {\renewcommand\partname{Part}}
}
\usepackage{tikz}
\usetikzlibrary{trees} % added for "cyclic" grow function 2013/03/02
-
\usepackage{forest}[2015/05/04]
+% switched from tikz-qtree to forest 2013/09/09
+% No problem with hyperlinks then, contrarily to tikz-qtree.
% 12 mars 2015, pour 1.08a, see http://tex.stackexchange.com/a/232584/4686
\usetikzlibrary{mindmap}
+% Vendredi 13 mars 2015 à 18:10:40
+% POUR LA TOC DE TITLE PAGE
+\usepackage{eso-pic}
+\usepackage{picture}
+\usepackage{ragged2e}
+% setspace usage added February 2023... (to accompany change of document font)
+% It must be loaded before hyperref
+\usepackage{setspace}
\usepackage{hyperref}% I had used [pdfencoding=pdfdoc] until 1.09f
\hypersetup{%
@@ -787,14 +706,145 @@ pdfkeywords={LaTeX, table of contents},%
pdfstartview=FitH,%
%%pdfpagemode=UseOutlines,% commented-out for 1.09h
}
-
% added usage of package bookmark 2013/10/10
\usepackage{bookmark}
-
-\usepackage{framed}
\usepackage{varioref}
-\usepackage{etoc} % loads multicol
+% Vendredi 16 septembre 2016
+% pour rendre accessibles les exemples
+% Fait package filecontentsdef le Samedi 17.
+\usepackage{filecontentsdef}
+
+%\ifnum\Withdvipdfmx=1
+%% Attempts to use attachfile2 for latex+dvipdfmx fail:
+%%
+%% - 2016: (I did not record which version of attachfile2 was used)
+%% (this \the\value comment presumably refers to how I was using
+%% \attachfile at that time)
+%%
+%% I have an issue that with \thesubsection or \the\value{section} in code
+%% snippet filename, the file is not correctly attached, it appears in the
+%% pdf interface but with a wrong filename and one can not obtain the file
+%% from the pdf (tested on Acrobat Reader 11 Vendredi 16 septembre 2016).
+%%
+%% - 2023 (January, 1.2, with 2019/11/26 v2.11):
+%%
+%% I had to comment-out the mimetype, created and modified key settings.
+%% Then latex run passed but dvipdfmx complained with a dozen of
+%% dvipdfmx:warning: Object @atfi_obj_67 used, but not defined. Replaced by null.
+%% The Adobe Reader (same as in 2016...) Attachment panel lists a dozen of
+%% Inconnu in section 39
+%% lines clearly matching the dvipdfmx warnings.
+%%
+%% The panel of Comments does display the list. From there or from the
+%% Attachment panels one can recover the snippets. The «etocsnippet» name
+%% is displayed in a strange greyed-out rendering, and one has to guess that
+%% CTRL-click gives access to the file. (not different from pdflatex route)
+%%
+%% I also tried with attachfile2.dtx from github at commit 660cea7 of May
+%% 19, 2022, and the same problem with the Attachment panel was there. Only
+%% difference I saw with attachfile2 from TL2022 was the ordering in the
+%% Attachment panel (with TL2022 attachfile2, the «Inconnu» lines were all
+%% grouped together).
+%%
+%% So I can still not go via latex+dvipdfmx in 2023. But the size reduction
+%% which is motivation for dvipdfmx was modest in this renewed testing,
+%% roughly 740Kb vs 840Kb with pdflatex.
+%%
+% \usepackage[dvipdfmx]{attachfile2}
+%% MEMO: I use \widthof in Linked list of the main package commands in
+%% a \makebox, since August 30, 2022, for 1.09f release.
+%% This requires calc, which is loaded only by attachfile among
+%% used packages; and calc is not loaded by attachfile2.
+% \usepackage{calc}
+%\else
+ \usepackage{attachfile}% no op with dvipdfmx
+%\fi
+%
+\def\CEST{+02'00'}\def\CET{+01'00'}
+\def\ExtractDateStamp #1<#2-#3-#4 at #5:#6:#7 #8>%
+ {D:#4#3#2#5#6#7\csname#8\endcsname}
+\edef\DateForSamples {\expandafter\ExtractDateStamp\etocdtxtimestamp}
+\attachfilesetup{%icon=Paperclip,% attention Paperclip pas PaperClip !!
+ mimetype=application/x-tex,
+ %appearance=false,
+% These comments and next are from November 19, 2022
+% author={Jean-François Burnol},
+% author={\pdfescapestring{Jean-François Burnol}},
+% TODO: resolve this at some point in my future life
+ author={Jean-Francois Burnol},
+% doing this has fixed the date shown in Acrobat annotation panel
+% but now some strange seemingly unrelated date is printed in
+% the "Comment panel"
+ created=\DateForSamples,
+ modified=\DateForSamples,
+% allright this one next sets the dates shown in the "Comment Panel",
+% whereas the above two (or only modified) impacts the panel of
+% annotations on the left in my (very old) Adobe Reader. Not yet
+% tested with evince
+ date=\DateForSamples
+ }%
+
+\colorlet{etocsnippet}{blue}
+\newcommand\marginattach{%
+ \noindent Depending on the PDF viewer\normalmarginpar
+% syntaxe pénible n'y-a-t-il pas un moyen plus commode
+% j'hésite à tester \value{page}
+ \marginpar
+ [% left
+ {\hfill
+ \textattachfile[description={in section \the\value{section}}]%
+ {etocsnippet-\snippetno.tex}%
+ {\textcolor{etocsnippet}{etocsnippet-\snippetno.tex}}%
+ }%
+ ]%
+ {% right
+ \textattachfile[description={in section \the\value{section}}]%
+ {etocsnippet-\snippetno.tex}%
+ {\textcolor{etocsnippet}{etocsnippet-\snippetno.tex}}%
+ \hfill
+ }%
+ \stepcounter{snippet},
+ a click (or CTRL-click) on the filename in the margin may allow to extract
+ it. Or check if an ``attachments'' or ``comments'' panel is available.
+}
+% Sadly, on non-attachement supporting viewers such as Skim.app,
+% the filename is not even searchable : entering "etocsnippet"
+% in the PDF viewer search form does not find the margin texts.
+
+% But I did not want to add to the filename the section number,
+% or perhaps even the page number (which could have been perilous
+% and I did not want to have to test and experiment, as I have
+% done enough for today with these code snippets).
+
+% In Acrobat the description field gives rise to some "tooltip"
+% display on hover, which displays the description field.
+
+\newcounter{snippet}%[section]
+\stepcounter{snippet}
+\makeatletter
+\newcommand\snippetno{%
+ \ifnum\value{snippet}<10 0\fi\the\value{snippet}%
+%%% emulating former manual mark-up (with reset at each section) but I drop this
+%%% \ifnum\value{snippet}>0 -\@Alph{\numexpr\value{snippet}+\@ne\relax}\fi
+}
+\makeatother
+
+\usepackage{colorframed}% fix color issues with framed.sty (JFB 2022)
+\colorlet{shadecolor}{gray!10}
+\usepackage{centeredline}% custom macro now in public package
+\usepackage{xinttools}% for easier construction of the doubly hyperlinked cs names
+
+\usepackage{etoc} % (loads multicol)
+% There is clearly a bug of \singlespacing to do this \vskip\baselineskip.
+% What then if one goes from double to onehalf spacing? no such adjustment
+% in \onehalfspacing? Not coherent. And caused me a lost of half an hour
+% to first spot the problem (with "inline" TOCs first), then understand
+% that it originated into the setspace.sty commands, then waste time
+% canceling the hook locally and finally do this after going into checking
+% setspace.sty.
+\def\etocbeforetitlehook{\setstretch{1}}
+
% for etoc's own default line styles. <1.08b had \partname by default but this
% does not work well with babel+frenchb hence the default is now simply Part.
% Here we can use \partname as we do (did) the documentation for English or German.
@@ -802,52 +852,19 @@ pdfstartview=FitH,%
\renewcommand{\etocpartname}{\partname}
% see the \AtBeginDocument with \addto\captionsngerman etc...
-
%--------
% 10 octobre 2013:
\AtBeginDocument{\addtocontents{toc}{\protect\hypersetup{hidelinks}}}
%--------
% add-ons for the new section `surprising uses of etoc' (2013/01/24)
+% use of \the\value rather than \arabic due to paranoia in 2023.
\newcounter{visibletoc}
\renewcommand{\etocaftertitlehook}
{\stepcounter{visibletoc}%
\phantomsection
- \etoctoccontentsline{visibletoc}{\thevisibletoc}}
+ \etoctoccontentsline{visibletoc}{\the\value{visibletoc}}}
\etocsetlevel{visibletoc}{6}
-\makeatletter
-\newcommand*{\MyQuasiStandardTOC}[1]{%
- \begingroup
- \etocsetstyle{section}
- {}
- {\ifnum\etocthenumber=4 % <- check this if new sections added to user manual
- \etocsetstyle{subsection}
- {\par\nopagebreak\begingroup
- \leftskip1.5em \rightskip\@tocrmarg
- \parfillskip \@flushglue
- \parindent 0pt
- \normalfont\normalsize\rmfamily\itshape
- \etocskipfirstprefix}
- {\allowbreak\,--\,}
- {\etocname\ \textup{(\etocnumber)}}
- {.\par\endgroup}%
- \else
- \etocsetstyle{subsection}
- {}%
- {}%
- {\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}%
- {}%
- \fi
- }% prefix for section sets the style dynamically for subsections!
- % direct usage of \l@subsection, \l@section allowed here since 1.1a
- {\l@section{\numberline{{\color{cyan}\etocthenumber}}\etocname}{\etocpage}}%
- {}%
- \etocstandarddisplaystyle
- \etocsetnexttocdepth {2}%
- \tableofcontents #1
- \endgroup
-}
-\makeatother
%--------
% Statistics on sections and subsections in a part \thispartstats:
% 2 mars 2013
@@ -901,7 +918,8 @@ pdfstartview=FitH,%
{{\footnotesize\itshape
Here are some statistics for this part: it contains \arabic{mycounti}
section\ifnum\value{mycounti}>1 s\fi{} and
- \arabic{mycountii} subsection\ifnum\value{mycountii}>1 s\fi. The name of
+ \ifnum\value{mycountii}>1 \arabic{mycountii} \else no \fi
+ subsection\ifnum\value{mycountii}>1 s\fi. The name of
the first section is
``\unhbox\firstnamei{}'' and the corresponding number is
``\unhbox\firstnumberi''. The name of the last section is
@@ -921,38 +939,8 @@ pdfstartview=FitH,%
\localtableofcontents
\endgroup
}
-%%
-% pour les TOC à la TikZ
-\newtoks\treetok
-\newtoks\parttok
-\newtoks\sectiontok
-\newtoks\subsectiontok
-\newtoks\tmptok
-
-\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
- #1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}}
-
-% 12 et 13 mars 2015 pour la mind map de title page
-% pour les Mindmap avec branch color
-\def\appendpart #1#2#3{%
- \edef\tmpstuff {\the#1 child [branch color = #3]{\the#2}}%
- #1\expandafter {\tmpstuff }%
-}
-% for 1.09f mind map on title page
-\def\prependpart #1#2#3{%
- \edef\tmpstuff {child [branch color = #3]{\the#2} \the#1}%
- #1\expandafter {\tmpstuff }%
-}
-
-% Vendredi 13 mars 2015 à 18:10:40
-% POUR LA TOC DE TITLE PAGE
-\usepackage{eso-pic}
-\usepackage{picture}
-
-\newcommand\etoc{%
- \texorpdfstring{{\color{joli}\ttfamily\bfseries etoc}}{etoc}\xspace}
-
-
+%--------
+% add-ons pour les TOC comme TikZ mind map, tree ou molécules
% hyperlinks to source code... added November 20, 2022
% works in sync with macrocode hacks explained after \StopEventually
% which were added in August 2022
@@ -961,30 +949,58 @@ pdfstartview=FitH,%
% FINALLY, after many hesitations and great suffering with \marginpar
% I decide to simply divide the name into two parts and use two
% distinct hyperlinks, so as to not render the reading to painful.
-\usepackage{xinttools}
-
% use a slightly different colour for second half?
% MEMO: we can change \ttfamily as hyperref uses a scope limiting group.
+% Modified 2023/03/20 to devote the left two-thirds to linking to the user manual.
+\makeatletter % for \on@line
\DeclareRobustCommand\csb[1]{%
- \edef\nbmoitie{\the\numexpr\xintLength{#1}/2}%
+ \edef\nbforuser{\the\numexpr2*\xintLength{#1}/3}%
\ifcsname r@#1\endcsname
- \hyperref[#1]{\ttfamily\hyphenchar\font45 \char`\\ \xintKeepUnbraced{\nbmoitie}{#1}}%
+ \hyperref[#1]{\ttfamily\hyphenchar\font45 \char`\\ \xintKeepUnbraced{\nbforuser}{#1}}%
\ifcsname r@etocmacro-#1\endcsname
- \hyperref[etocmacro-#1]{\ttfamily\hyphenchar\font45 \xintTrim{\nbmoitie}{#1}}%
+ \hyperref[etocmacro-#1]{\ttfamily\hyphenchar\font45 \xintTrim{\nbforuser}{#1}}%
\else
% for .toc suffixed macros
\ifcsname r@etocmacro-\xintTrimUnbraced{-4}{#1}\endcsname
\hyperref[etocmacro-\xintTrimUnbraced{-4}{#1}]{\ttfamily\hyphenchar\font45
- \xintTrim{\nbmoitie}{#1}}%
+ \xintTrim{\nbforuser}{#1}}%
\else
- \hyperref[#1]{\ttfamily\hyphenchar\font45 \xintTrim{\nbmoitie}{#1}}%
+% 2023/02/27 also catch non existing destinations in source code
+ {\fboxsep-\fboxrule\color{Orchid}%
+ \fbox{\ttfamily\hyphenchar\font45 \xintTrim{\nbforuser}{#1}#1}%
+ }%
+ \ifcsname r@etocname\endcsname
+ \expanded{\noexpand\AtEndDocument
+ {\noexpand\PackageError{etoc}{Pas de référence dans
+ le code à #1\on@line}%
+ {Corriger!}
+ }%
+ }%
+ \fi
+% \hyperref[#1]{\ttfamily\hyphenchar\font45 \xintTrim{\nbforuser}{#1}}%
\fi
\fi
\else
- \textcolor{red}{\ttfamily\hyphenchar\font45 \char`\\ #1}%
+% 1.1a, updated 2023/01/22 1.2
+ {\fboxsep-\fboxrule\color{Orchid}%
+ \fbox{\ttfamily\hyphenchar\font45 \char`\\ #1}%
+ }%
+% make second run of compilation raise an error if macro name has been
+% misspelled so target (in the documentation) does not exist ; but this will
+% trigger error first time the documentation is added, one has to make
+% one compilation after adding the label and before continuing doc edits
+% 2023/01/22 1.2
+ \ifcsname r@etocname\endcsname
+ \expanded{\noexpand\AtEndDocument
+ {\noexpand\PackageError{etoc}{Pas de référence à #1\on@line}%
+ {Corriger!}
+ }%
+ }%
+ \fi
\fi
}
+\makeatother
\DeclareRobustCommand\csa [1]
{{\ttfamily\hyphenchar\font45 \char`\\ #1}}
@@ -993,26 +1009,38 @@ pdfstartview=FitH,%
\newcommand\csbhyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}}
-\DeclareRobustCommand\ctanpkg[1]
- {\texorpdfstring{\href{https://ctan.org/pkg/#1}{#1}}{#1}}
-
+\newcommand\etoc{%
+ \texorpdfstring{{\color{joli}\ttfamily\bfseries etoc}}{etoc}\xspace}
\newcommand\toc{\csb{tableofcontents}\xspace}
\newcommand\localtoc{\csb{localtableofcontents}\xspace}
+\newcommand\invisiblelocaltoc{\csb{invisiblelocaltableofcontents}\xspace}
\newcommand\localtocwrdp{\csb{localtableofcontentswithrelativedepth}\xspace}
\newcommand\lowast{\raisebox{-.25\height}{*}}
\newcommand\starit[1]{\csa{#1\lowast}}
\newcommand\staritb[1]{\csb{#1}\lowast}
+% 2023/01/23, mais pas la peine de s'embêter avec robust et texorpdfstring
+\newcommand\etocrelease[1]{\hyperlink{v#1}{\texttt{#1}}}
+
+\DeclareRobustCommand\ctanpkg[1]
+ {\texorpdfstring{\href{https://ctan.org/pkg/#1}{#1}}{#1}}
+
+
\hyphenation{
table-of-con-tents
local-table-of-con-tents
local-table-of-con-tents-with-rel-a-tive-depth
-}
-
-\hyphenation{toc-depth sec-num-depth con-tents-line}
-
-\hyphenation{etoc-stan-dard-lines
+etoc-local-list-of-ta-bles-hook
+etoc-local-list-of-fig-ures-hook
+local-list-of-fig-ures
+local-list-of-ta-bles
+%
+toc-depth
+sec-num-depth
+con-tents-line
+%
+etoc-stan-dard-lines
etoc-de-fault-lines
etoc-toc-lines
etoc-set-style
@@ -1070,9 +1098,7 @@ etoc-af-ter-con-tents-hook
etoc-af-ter-toc-hook
etoc-skip-first-pre-fix
etoc-only-on-first
-}
-
-\hyphenation{
+%
etoc-font-mi-nus-two
etoc-font-mi-nus-one
etoc-font-zero
@@ -1125,148 +1151,93 @@ etoc-im-me-di-ate-set-toc-dep-th
etoc-im-me-di-ate-depth-tag
etoc-im-me-di-ate-toc-con-tents-line
etoc-im-me-di-ate-set-local-top
+%
+next-toc-with-tags
}
-\hyphenation{next-toc-with-tags}
-% removed, 2022/08/26
-% \frenchspacing
-
-\renewcommand\familydefault\sfdefault
+% no more \frenchspacing since 2022/08/26
% for illustration only. Not to be recommended in general.
\setcounter{secnumdepth}{4}
-% Vendredi 16 septembre 2016
-% pour rendre accessibles les exemples
-% Fait package filecontentsdef le Samedi 17.
-\usepackage{filecontentsdef}
+% Usage of microtype added for 1.2 release; now that for some time
+% due to the business of attachfile I am tied with pdflatex.
+\ifnum\Withdvipdfmx=1
+\else
+% should I check for xetex/luatex ?
+\usepackage{microtype}
+\fi
-%\ifnum\Withdvipdfmx=1
-%% I have an issue that with \thesubsection or \the\value{section} in code
-%% snippet filename, the file is not correctly attached, it appears in the pdf
-%% interface but with a wrong filename and one can not obtain the file from
-%% the pdf (tested on Acrobat Reader 11 Vendredi 16 septembre 2016).
-% \usepackage[dvipdfmx]{attachfile2}
-%\else
- \usepackage{attachfile}% no op with dvipdfmx
-%\fi
-%
-\def\CEST{+02'00'}\def\CET{+01'00'}
-\def\ExtractDateStamp #1<#2-#3-#4 at #5:#6:#7 #8>%
- {D:#4#3#2#5#6#7\csname#8\endcsname}
-\edef\DateForSamples {\expandafter\ExtractDateStamp\etocdtxtimestamp}
-\attachfilesetup{%icon=Paperclip,% attention Paperclip pas PaperClip !!
- mimetype=application/x-tex,
- %appearance=false,
-% author={Jean-François Burnol},
-% author={\pdfescapestring{Jean-François Burnol}},
-% TODO: resolve this at some point in my future life
- author={Jean-Francois Burnol},
-% doing this has fixed the date shown in Acrobat annotation panel
-% but now some strange seemingly unrelated date is printed in
-% the "Comment panel"
- created=\DateForSamples,
- modified=\DateForSamples,
-% allright this one next sets the dates shown in the "Comment Panel",
-% whereas the above two (or only modified) impacts the panel of
-% annotations on the left in my (very old) Adobe Reader. Not yet
-% tested with evince
- date=\DateForSamples
- }%
+\def\etocoption#1{{\color{optioncolor}\bfseries\texttt{#1}}}
-\colorlet{etocsnippet}{blue}
-\newcommand\marginattach[1]{% #1 is from some legacy mark-up and is ignored
- \noindent Depending on your PDF viewer\normalmarginpar
-% syntaxe pénible n'y-a-t-il pas un moyen plus commode
-% j'hésite à tester \value{page}
- \marginpar
- [% left
- {\hfill
- \textattachfile[description={in section \the\value{section}}]%
- {etocsnippet-\snippetno.tex}%
- {\textcolor{etocsnippet}{etocsnippet-\snippetno.tex}}%
- }%
- ]%
- {% right
- \textattachfile[description={in section \the\value{section}}]%
- {etocsnippet-\snippetno.tex}%
- {\textcolor{etocsnippet}{etocsnippet-\snippetno.tex}}%
- \hfill
- },
- clicking on the margin filename may allow to extract it.%
- \stepcounter{snippet}%
-}
-% Sadly, on non-attachement supporting viewers such as Skim.app,
-% the filename is not even searchable : entering "etocsnippet"
-% in the PDF viewer search form does not find the margin texts.
+\begin{document}
+\marginparsep 6bp
+\thispagestyle{empty}
-% But I did not want to add to the filename the section number,
-% or perhaps even the page number (which could have been perilous
-% and I did not want to have to test and experiment, as I have
-% done enough for today with these code snippets).
+\bookmark[named=FirstPage,level=1]{Title page}
+% depth tags for title page toc
+\etocsettagdepth {preamble} {part}
+\etocsettagdepth {overview} {section}
+\etocsettagdepth {styling} {section}
+\etocsettagdepth {control} {section}
+\etocsettagdepth {examples} {section}
+\etocsettagdepth {advanced} {section}
+\etocsettagdepth {etocandworld}{part}
+\etocsettagdepth {code} {section}
-% In Acrobat the description field gives rise to some "tooltip"
-% display on hover, which displays the description field.
+% pour les TOC à la TikZ
+\newtoks\treetok
+\newtoks\parttok
+\newtoks\sectiontok
+\newtoks\subsectiontok
+\newtoks\subsubsectiontok
+\newtoks\tmptok
-\newcounter{snippet}%[section]
-\stepcounter{snippet}
-\makeatletter
-\newcommand\snippetno{%
- \ifnum\value{snippet}<10 0\fi\the\value{snippet}%
-%%% emulating former manual mark-up (with reset at each section) but I drop this
-%%% \ifnum\value{snippet}>0 -\@Alph{\numexpr\value{snippet}+\@ne\relax}\fi
-}
-\makeatother
-%\usepackage{layout}
+\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
+ #1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}}
-\usepackage{ragged2e}
-\begin{document}%\normalmarginpar\layout %marginparwidth is 96pt
-\marginparsep 6bp
-\rmfamily
-\thispagestyle{empty}
+% 12 et 13 mars 2015 pour la mind map de title page
+% pour les Mindmap avec branch color
+\def\appendpart #1#2#3{%
+ \edef\tmpstuff {\the#1 child [branch color = #3]{\the#2}}%
+ #1\expandafter {\tmpstuff }%
+}
+% for 1.09f mind map on title page
+\def\prependpart #1#2#3{%
+ \edef\tmpstuff {child [branch color = #3]{\the#2} \the#1}%
+ #1\expandafter {\tmpstuff }%
+}
-% START ENGLISH VERSION
-\bookmark[named=FirstPage,level=1]{Title page}
-\begingroup
+% TOC MIND MAP ON TITLE PAGE
\newcount\tikznumberofcurrentgrandchild
-\newcount\tikzdeltaofcurrentgrandchild
-%\newcount\tikzoffset
-% copié de http://tex.stackexchange.com/a/232914
-% THIS WAS NOT USED FOR 1.08a--1.09e RELEASES AND IS NOW AGAIN USED AT 1.09f,
-% BUT IS MANUALLY ADJUSTED TO HANDLE ESPECIALLY THE "Surprising"
-% (now rather "Examples") AND "Tip" PARTS
-% AND FALL-BACK FOR THEM TO CIRCULAR GROWTH FUNCTION
-% hence stuff is hard-coded and interacts with other hard-coded things
-% further down; in particular with the configuration of depth tags,
-% here all sections are included (except the first two, "Foreword" and "License",
-% which are not in any part).
-% But etoc documentation is not likely to receive new sections soon.
+
+% copied originally from http://tex.stackexchange.com/a/232914
+%
+
+% \newcount\tikzdeltaofcurrentgrandchild % not needed at 1.2
+
+% 1.2 causes quite a few adjustments as the parts have been modified, there
+% are now only 8 of them, and it is not same number of sections too.
+% As I don't read TikZ well, I had some trouble, but I take this opportunity
+% to clean up some complications from recent layouts which handled some
+% sections to lie on circular arcs, as exception to the general rectangular
+% rule. This was because not everything could fit, but I could find
+% satisfactorily layout this time, simply inhibiting via depth tags a few
+% sections.
+
\def\tikzmycustomgrowth {%
\pgftransformreset
\ifnum\tikztreelevel=1
- \pgftransformrotate{-65.4545+((\pgfkeysvalueof{/tikz/sibling angle})*(1+\tikznumberofcurrentchild)}%
+ \pgftransformrotate{(\pgfkeysvalueof{/tikz/sibling angle})
+ *
+ (\tikznumberofcurrentchild-2)}%
\pgftransformxshift{\the\tikzleveldistance}%
\fi
\ifnum\tikztreelevel=2
- % hard-coded section numbers for branching
- % il y a un décalage de 3 avec les numéros de sections numérotées
- \if1\ifnum\tikznumberofcurrentgrandchild>2
- \ifnum\tikznumberofcurrentgrandchild<6 0%
- \else
- \ifnum\tikznumberofcurrentgrandchild>20 % était 21 mais
- % \etocsetlocaltop déplacé
- \ifnum\tikznumberofcurrentgrandchild<27 0% était 28 mais
- % \etocsetlocaltop déplacé
- \else
- \ifnum\tikznumberofcurrentgrandchild>50 % était 51
- \ifnum\tikznumberofcurrentgrandchild<58 0%
- \fi\fi\fi\fi\fi\fi
- 1%
- % ceci correspond aux sections qui seront sur le bord rectangulaire
- % le "9+" choisi manuellement jusqu'à obtenir quelque chose de bien
- \pgfmathsetmacro\tikzoffsetofcurrentchild{(\tikzsiblingdistance)*(7+\tikznumberofcurrentgrandchild
- +\tikzdeltaofcurrentgrandchild)}%
+ \pgfmathsetmacro\tikzoffsetofcurrentchild{%
+ (\tikzsiblingdistance)*(\tikznumberofcurrentgrandchild)
+ }%
\ifdim\tikzoffsetofcurrentchild pt<\tikzlevelheight
\pgftransformxshift{\tikzlevelwidth/2}
\pgftransformyshift{-\tikzlevelheight/2+\tikzoffsetofcurrentchild}
@@ -1288,38 +1259,17 @@ etoc-im-me-di-ate-set-local-top
\pgftransformyshift{-\tikzlevelheight/2}
\else
\pgfmathsetmacro\tikzoffsetofcurrentchild{\tikzoffsetofcurrentchild-\tikzlevelwidth}%
- %\ifdim\tikzoffsetofcurrentchild pt<\tikzlevelheight
\pgftransformxshift{\tikzlevelwidth/2}
\pgftransformyshift{-\tikzlevelheight/2+\tikzoffsetofcurrentchild}
- %\fi
\fi\fi\fi\fi
- \else
- % les sections spéciales pas mises sur bord rectangulaires mais à
- % distance constante du parent
- % NEW BRANCH ADDED AT 1.09f
- \ifnum\tikznumberofcurrentgrandchild<6
- \tikzset{level distance=8cm}% TikZ est tout de même assez génial dans l'interface
- \fi
- \pgftransformrotate {\ifnum\tikznumberofcurrentgrandchild<6 -12
- \else\ifnum\tikznumberofcurrentgrandchild<27 180
- \else0\fi\fi +
- \pgfkeysvalueof{/tikz/sibling angle}*\tikznumberofcurrentgrandchild}%
- \pgftransformxshift {\the\tikzleveldistance}%
- \ifnum\tikznumberofcurrentgrandchild=5
- \global\advance\tikzdeltaofcurrentgrandchild by-3
- \fi
- \ifnum\tikznumberofcurrentgrandchild=26 % était 27 mais déplacement \etoclocaltop
- \global\advance\tikzdeltaofcurrentgrandchild by-6
- \fi
- \ifnum\tikznumberofcurrentgrandchild=57
- \global\advance\tikzdeltaofcurrentgrandchild by-7 % était -6
- \fi
- \fi
+ \pgftransformrotate {\pgfkeysvalueof{/tikz/sibling angle}
+ *
+ \tikznumberofcurrentgrandchild}%
\global\advance\tikznumberofcurrentgrandchild by1
\fi
}
-%version circulaire utilisée avec les versions 1.08a--1.09e du manuel.
+% % % version circulaire utilisée avec les versions 1.08a--1.09e du manuel.
% \def\tikzmycustomgrowth {%
% \pgftransformreset
% \ifnum\tikztreelevel=1
@@ -1336,18 +1286,15 @@ etoc-im-me-di-ate-set-local-top
% 1,2,3,4,5,... -> 1,2,3,1,2,3,1,2,3
\def\pseudomodthree #1{\numexpr #1 + 3 - 3*((#1+1)/3)\relax}
-% For etoc.toctree file was used to test the Mind map separately
-%\newwrite\TOCasTree
\newbox\TitlePageMindmapTOC
-
\etocsetstyle{part}
{\etocskipfirstprefix}
{\ifcase\pseudomodthree{\value{partco}}%
- \or \appendpart\treetok\parttok {teal!30}% first (60 avant 1.09f)
- \or \appendpart\treetok\parttok {yellow!80}% second
- \else\appendpart\treetok\parttok {green!50}% third
+ \or \appendpart\treetok\parttok {Dandelion!50}% first (was teal!60 until 1.09f)
+ \or \appendpart\treetok\parttok {teal!40}% second (was yellow!80 until 1.2)
+ \else\appendpart\treetok\parttok {green!40}% third
\fi
}
{\stepcounter{partco}%
@@ -1355,11 +1302,12 @@ etoc-im-me-di-ate-set-local-top
{\noexpand\textbf{\etocifnumbered{\unexpanded\expandafter{\etocthelinkednumber}.}{}
\unexpanded\expandafter{\etocthelinkedname}}}}%
\parttok\expandafter{\treenode}}
- {% 1.09f prepends...
+ {% 1.09f used \prependpart for the last... reverted at 1.2,
+ % better to append, avoids overlaps by rays of some balls
\ifcase\pseudomodthree{\value{partco}}%
- \or \prependpart\treetok\parttok {teal!30}% first (60 avant 1.09f)
- \or \prependpart\treetok\parttok {yellow!80}% second
- \else\prependpart\treetok\parttok {green!50}% third
+ \or \appendpart\treetok\parttok {Dandelion!50}% first
+ \or \appendpart\treetok\parttok {teal!40}% second
+ \else\appendpart\treetok\parttok {green!40}% third
\fi
}
@@ -1367,78 +1315,74 @@ etoc-im-me-di-ate-set-local-top
{}
{}
{% define the section node
- \edef\childnode{child {node
- {\noexpand\itshape\noexpand\bfseries
+ \edef\childnode{child {node
+% The Bitter font does not have bold italic
+% Adding \baselineskip setting, and \endgraf to activate because \par causes
+% ! Paragraph ended before \tikz@collect@child@code was complete.
+% There must be some way to configure the TikZ node but I don't have
+% the time to go into its documentation.
+ {\baselineskip10pt\noexpand\itshape%\noexpand\bfseries
\unexpanded\expandafter{\etocthelinkedname}\hfil\break
- p. \unexpanded\expandafter{\etocthelinkedpage}}}
- }%
+ p. \unexpanded\expandafter{\etocthelinkedpage}\noexpand\endgraf
+ }%
+ }%
+ }%
\appendtotok\parttok\childnode
}
{}
-\etocsetnexttocdepth{section}
-
% title page toc
-% 1.09f uses a prepend for last part so we need to delay
-% start of tree construction in \treetok
-\treetok{}
-\makeatletter
-\etocsettocstyle
- {\setcounter{partco}{0}%
- }
- {%
- \toks@{\node [root concept]{\normalfont{The \etoc package}\par {\normalsize\textsc
+% 1.09f used a prepend for last part so we needed to delay
+% the insertion of the root node to after the treetok had
+% been finished.
+% 1.2 uses append always so we can initialize here
+\treetok{\node [root concept]{\normalfont{The \etoc package}\par {\normalsize\textsc
{Jean-François Burnol}\par \ttfamily jfbu (at) free (dot) fr}\par
- {\normalsize Package version:\par \etocpkgversion{} (\etocpkgdate )\par}}%
- }%
- \global\treetok\expandafter\expandafter\expandafter{\expandafter\the\expandafter\toks@\the\treetok;}%
- }
+ {\normalsize
+ Package version:\par \hyperref[changelog]{\etocpkgversion{} (\etocpkgdate )}\par}}%
+ }
-% depth tags for title page toc
-\etocsettagdepth {preamble}{section}
-\etocsettagdepth {overview}{section}
-\etocsettagdepth {arbitrarily}{section}
-\etocsettagdepth {examples}{section}
-\etocsettagdepth {surprising}{section}
-\etocsettagdepth {linestyles}{section}
-\etocsettagdepth {globalcmds}{section}
-\etocsettagdepth {custom}{section}
-\etocsettagdepth {tips}{section}
-\etocsettagdepth {etocandworld}{section}
-\etocsettagdepth {code}{all}
+\etocsettocstyle
+ {\setcounter{partco}{0}}
+ {\global\treetok\expandafter{\the\treetok;}}
+
+\etocsetnexttocdepth{section}
% fill in the \treetok
-\etocinline\tableofcontents\label{toc:mindmaptitlepage}
+\etocinline
+\tableofcontents\label{toc:mindmaptitlepage}
+% For debugging
+% \newwrite\TOCasTree
% \immediate\openout\TOCasTree=\jobname.toctree
% \immediate\write\TOCasTree{\the\treetok}%
-
+% \immediate\closeout\TOCasTree
\tikzset {branch color/.style={concept color=#1!white,
every child/.append style={concept color=#1!white!30!white,
opacity=0.3, text opacity=1},
},
-% ajout pour version de 1.08g
+ % ajout pour versions depuis 1.08g
level width/.store in=\tikzlevelwidth,
- level height/.store in=\tikzlevelheight
+ level height/.store in=\tikzlevelheight,
}%
-
-\global
-\setbox\TitlePageMindmapTOC\hbox {%
-\resizebox{\dimexpr\paperwidth-1cm\relax}!{%
+\global\setbox\TitlePageMindmapTOC\hbox {%
+\resizebox{\dimexpr\paperwidth-1cm\relax}!{
\begin{tikzpicture}[mindmap,
text width=2cm,
align = flush center,
-% pour 1.09 je reviens à version circulaire simplifiée
-% pour 1.09f je reviens à version rectangulaire
+ % pour 1.09 je reviens à version circulaire simplifiée
+ % pour 1.09f je reviens à version rectangulaire
growth function=\tikzmycustomgrowth,
nodes={concept},
- concept color=orange!60,
+% trying cyan I get some surprising brutal color change
+% much more visible than with orange
+ concept color=yellow!50,% orange!60 until 1.2
% root concept/.append style={font=\huge, text width = 6cm},
root concept/.append style={font=\Large, text width = 5cm},
% level 1/.append style={level distance=7cm, sibling
level 1/.append style={level distance=6cm,
- sibling angle=360/11},% une partie de plus
+ sibling angle=360/8},% 8 parties
% level 1 concept/.append style={font=\Large, text width = 3cm},
% ancienne version circulaire
% level 2/.append style={level distance=12.5cm, sibling angle=360/39},%
@@ -1447,12 +1391,11 @@ etoc-im-me-di-ate-set-local-top
% a tout de même pris pas mal de temps...)
level 2/.append style={level width=21cm,
level height=30cm,
- sibling distance=2.22cm,% ajusté à la
- % main... dépend de ce qui qu'on conserve par
- % les depth tags...
- % 1.09f pour essayer certaines parties en circulaire
- level distance=10cm,% DISTANCE DEPUIS LE CENTRE !
- sibling angle=12,% ajusté manuellement
+ sibling distance=2.12cm,% à ajuster manuellement
+ % 1.09f pour essayer certaines parties en
+ % circulaire; plus besoin pout 1.2
+ % level distance=10cm,% distance depuis le centre !
+ % sibling angle=12,% à ajuster manuellement
},
level 2 concept/.append style={text width=2cm},
]
@@ -1460,256 +1403,426 @@ etoc-im-me-di-ate-set-local-top
\end{tikzpicture}%
}%
}% end of \hbox
-\endgroup% fin de la défintion de la mind map pour la page de titre
-
-\noindent\null\par\vskip-5cm\hbox{\hypertarget{FRONTPAGE}{}}\vskip5cm
-
% On l'envoie au shipout
\AddToShipoutPictureFG*{\put(.5\paperwidth,.5\paperheight)
{\makebox(0,0){\box\TitlePageMindmapTOC}}}
+% trigger first page
+\noindent\null\par\vskip-5cm\hbox{\hypertarget{FRONTPAGE}{}}\vskip5cm
-\clearpage
+% % for standard TOC
+% \etocstandardlines
+% \etocclasstocstyle
+% \tableofcontents
+
+% reset toc global to class default and line styles to etoc default
+\etocdefaultlines
+\etocclasstocstyle
+\clearpage
\etocdepthtag.toc {preamble}
%----
% MAIN TOC
-%
-\etocsettocdepth {subsubsection}
-\etoctoclines
-\etocmarkboth\contentsname
-\etocmulticolstyle[1]
- {\noindent
- \bfseries\Large
- \leaders\hrule height1pt\hfill
- TABLE OF CONTENTS\let\thefootnote\empty
- \footnote{Documentation (\etocdocdate) generated from the source file
- with timestamp ``\etocdtxtimestamp''.}\setcounter{footnote}{0}%
-}
-
-\pdfbookmark[1]{Table of contents}{MAINTOC}%
-
-%\begin{framed}
-\begingroup\footnotesize\itshape
- Starting with 1.08h, about 25 code samples (especially the longer ones)
- are incorporated into the PDF file (thanks to \textsc{Scott
- Pakin}'s \href{http://www.ctan.org/pkg/attachfile}{attachfile} package) as
- \textbf{file attachement annotations}. Each file is represented by its
- filename in the margin after the verbatim rendering of the corresponding
- code. Clicking on this filename will on supporting viewers trigger some
- dialog for extracting the file, or perhaps even will extract it
- automatically and open it in some text editor. This is much better than
- copy-paste which often loses indentation.
-At 1.09h the formerly used icon in the text body has been replaced by the
-filename itself, placed in the page margin.
+% made invisible at 1.2
+\invisibletableofcontents \label{toc:main}
- In some PDF viewers side panels may provide a convenient clickable list of
- all these \textbf{attachments annotations}.
+\part*{\etoc}
+\addcontentsline{toc}{part}{\etoc (read this first)}
+
+\onehalfspacing
+
+\begin{shaded}\small
+ Since \etocrelease{1.08h} (2016/09/25), about 25 code samples
+ (especially the longer ones) are incorporated into the PDF file (thanks to
+ \textsc{Scott Pakin}'s \href{http://www.ctan.org/pkg/attachfile}{attachfile}
+ package) as \textit{file attachement annotations}. Each file is represented
+ by its filename in the margin after the verbatim rendering of the
+ corresponding code. Clicking on this filename will on supporting viewers
+ trigger some dialog for extracting the file, or perhaps even will extract it
+ automatically and open it in some text editor. This is much better than
+ copy-paste which often loses indentation. In some PDF viewers side panels
+ may provide a convenient clickable list of all these \textit{attachments
+ annotations}.
+ % https://helpx.adobe.com/acrobat/using/comments.html
+
+ \medskip
+
+ Since \etocrelease{1.09h} (2022/11/20), the command names throughout
+ the user documentation which are displayed
+ {\textcolor{RoyalBlue}{with this colour}} are doubly hyperlinked:
+ their left parts hyperlink to the user documentation, their right
+ parts hyperlink to the source code. You can try it out now:
+ \csb{localtableofcontents}. But read this first: if you get lost
+ inside the source code, clicking on control sequences displayed
+ {\textcolor{macrocodelinktouserdoccolor}{with this colour}} brings
+ you back to the part of the user manual discussing that specific
+ command. \ifnum\NoSourceCode=1 (but this PDF does not include the
+ source code) \fi As of \etocrelease{1.2} (2023/03/01), the left
+ \emph{two-third} of the command name hyperlinks to its user documentation,
+ not only the left \emph{half}, as landing by accident in the midst
+ of the source code is not recommended for the general public, so the
+ dangerous area was made smaller.
+\end{shaded}
+
+
+\section*{Abstract}
+
+%\renewcommand\abstractname{}
+
+%\begin{abstract}
+\begingroup
+\leftskip1cm
+\rightskip1cm
+
+With \etoc loaded, \csb{tableofcontents} can be used multiple times and
+an added command \csb{localtableofcontents} allows to typeset ``local''
+tables of contents, i.e. having their scope limited to the last
+sectioning command encountered.
+
+No auxiliary file is used additionally to the standard \texttt{.toc}
+file. Release \etocrelease{1.2} provides experimental additions
+\csb{locallistoffigures} and \csb{locallistoftables} which also use
+only the \texttt{.toc} file.
+
+Such local TOCs or ``Lists Of'' typically need to adopt a ``display
+style'' (i.e. the way the title is rendered, whether it should add
+itself an entry in the \texttt{.toc} file, ...) somewhat distinct from
+the global TOC. The release \etocrelease{1.2} default adapts
+automatically the titles of local TOCs to their depths in the
+sectioning hierarchy. Should the need arise to customize such
+``display style'', full control is allowed by package commands.
+
+Regarding how the individual ``contents lines'' are handled, here again
+complete control is given to the user to define from the ground-up how
+to use the \emph{name}, \emph{number}, and \emph{page number} for each
+entry, according to their ``levels'' (i.e. part, chapter, section,
+subsection, ...). As this requires some \LaTeX{} fluency, many examples
+which can serve as starting points are attached to the PDF
+documentation as extractible files.
+
+Loading \etoc per itself modifies nothing to ``contents lines''
+rendering from the class default or changes from other packages. But
+full usage of the package allows spectacular effects such as displaying
+TOCs as trees or mind maps.
+
+%\end{abstract}
\endgroup
-%\end{framed}
-% https://helpx.adobe.com/acrobat/using/comments.html
-% I move colours mostly used only after stopeventually
-\definecolor{etocnamecolor}{RGB}{228,57,0}
-\colorlet{verbcolor}{Maroon}
-\colorlet{privatecommentcolor}{cyan}
-\colorlet{macrocodecommentcolor}{gray}
-\colorlet{macrocodenewmacrocolor}{verbcolor}
-\colorlet{macrocodelinktouserdoccolor}{etocnamecolor}% and bold face
-\colorlet{macrocodelinktosectioncolor}{DarkBlue}% and bold face
-\colorlet{macrocodelinktocodelinecolor}{Blue}
-\colorlet{macrocodenoncscolor}{Green}
+\clearpage
-%\ifnum\NoSourceCode=0
-\begin{framed}
- Throughout the documentation the command names displayed
- {\textcolor{RoyalBlue}{with this colour}} are doubly hyperlinked: the left
- half of the name links to the user documentation, the second half links to
- the source code. You can try it out now: \csb{localtableofcontents}. But
- read this first: if you get lost inside the source code, clicking on control
- sequences displayed {\textcolor{macrocodelinktouserdoccolor}{with this
- colour}} brings you back to the part of the user manual discussing that
- specific command. \ifnum\NoSourceCode=1 (but this PDF does not include the source code)\fi
-\end{framed}
-%\fi
+\setstretch{1}
+
+\section*{License}
+\addcontentsline{toc}{section}{License}
\begingroup
- \etocsetlevel{subsection}{3}
- \etocsetlevel{subsubsection}{6}
- \tableofcontents \label{toc:main}
-\endgroup
+\ttfamily
+\hyphenchar\font -1
+ \parindent0pt
+ \obeyspaces\obeylines %
+\etocLicense\endgroup
-% ATTENTION Vendredi 09 septembre 2016 à 21:46:51
+\onehalfspacing
\clearpage
+\onehalfspacing
+\etocignoredepthtags
+\etocsettocdepth {subsubsection}
-% refactoring 2022/08/30 via ajout de ce \part* et déplacement de l'abstract
-% pour avoir une TOC mindmap plus complète
-\part*{\etoc}
-\addcontentsline{toc}{part}{\etoc}
-
-\phantomsection\addcontentsline{toc}{section}{\abstractname}
-
-\begin{abstract}
- The \etoc package gives to the user complete control on how
- the entries of the table of contents should be constituted
- from the \emph{name}, \emph{number}, and \emph{page number}
- of each sectioning unit. This goes via the definition of
- \emph{line styles} for each sectioning level used in the
- document. The package provides its own custom line styles.
- Simpler ones are given as examples in the documentation. The
- simplest usage will be to take advantage of the layout facilities
- of packages dealing with list environments.
-
- Regarding the \emph{global toc display}, \etoc provides pre-defined styles
- based on a multi-column format, with, optionally, a ruled title or framed
- contents.
+\etocdepthtag.toc{overview}
+\part{Overview}\label{part:overview}
+
+\thispartstats
- The \toc command may be used arbitrarily many times%
+\etocdefaultlines
+\etocsettocstyle{}{}
+\localtableofcontents \label{toc:overview}
+
+\section[\csbhyp{(local)\-tableofcontents}]{The \csbhyp{tableofcontents},
+ \csbhyp{localtableofcontents} and other main package commands}
+
+\begin{description}
+\item [\csb{tableofcontents}] can be used arbitrarily many times in the
+ document,
+
+\item [\csb{localtableofcontents}] produces tables of contents which are
+ limited in scope by the nearest preceding sectioning command,%
%
-\footnote{\label{etockeeporiginaltableofcontents}%
- If \csb{etockeeporiginaltableofcontents} is issued in the preamble
- after package loading, then \toc keeps the non-\etoc meaning and one must
- use \csb{etoctableofcontents} in its place to get the \etoc features. This
- was added to fix a compatiblity issue with \ctanpkg{listings}'s
- \texttt{\string\lstlistoflistings}, as it needs the
- \texttt{\string\tableofcontents} macro to keep its original meaning.}
+\footnote{After adding a \localtoc in-between existing ones, the first
+ compilation will typeset at its location a pre-existing next one; only at
+ second compilation will the contents match the location. Hence often a
+ third compilation is needed for document to stabilize. And if the ``to toc''
+ mechanism is active (see the discussion of \csb{etocsetup} option
+ \etocoption{localtoctotoc} and
+ similar options), only on second compilation is a new entry made in the
+ \texttt{.toc} file so three compilations is always a minimum. If one
+ starts compilations from a given source, and no auxiliary files, the first
+ compilation prepares the |.toc| file, the second typesets the main and local
+ TOCs, possibly changing page numbers due to added contents, and only at the
+ third compilation will things perhaps stabilize, and this third step is
+ surely needed in case of \etocoption{localtoctotoc}. \ctanpkg{latexmk} is highly
+ recommended.}
+
+
+\item [\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}] defines
+ (from the ground up, completely) the TOC titles, or more generally
+ everything either before or after the actual TOC contents,
+
+\item [\csb{etocsetstyle}\marg{levelname}%
+ \marg{start}\marg{prefix}\marg{contents}\marg{finish}] defines (completely,
+ from the ground up) arbitrarily the way the \csa{contentsline} entries in
+ the |.toc| file are rendered, depending on their first argument, which is a
+ `level name' such as |part|, |chapter|, |section|, |subsection|, \dots
+
+ It is possible to create new levels or re-assign the numerical level of a
+ named one via \csb{etocsetlevel}\marg{levelname}\marg{number}, thus opening
+ the way for sophisticated (ab)-uses of the data stored in the |.toc| file.
+
+\item [\csb{etocname}, \csb{etocnumber}, \csb{etocpage}] are free to use
+ arbitrarily in the \csb{etocsetstyle} \marg{prefix} and \marg{contents}
+ arguments for a given contents line level name, they stand for what will be
+ extracted by \etoc from the actual data which is stored in the |.toc| file
+ and is a bit entangled there (for the first two).
+\end{description}
+
+%% \vskip-\baselineskip\vskip0pt % sigh LaTeX spaces !
+
+Throughout this documentation ``layout'', ``display'', ``TOC style'' always are
+synonyms and refer roughly to how the TOC title is typeset. And ``line
+styles'' refer to how each individual entry in the TOC will be rendered
+according to its ``level''. Whenever ``TOC style'' is mentioned it is for the
+title related things, else the documentation will say ``line styles''.
+
+\csb{etocsetstyle} is for line styles and it requires \LaTeX{} fluency. It is
+however absolutely not required to use it: by default \etoc does not intervene
+at all into the rendering of the contents lines. For example, one can use
+packages such as \ctanpkg{tocloft} to customize these contents lines as wished.
+
+\csb{etocsettocstyle} is for styling the titles (and all things related to
+material before and after the actual TOC contents). It was originally
+conceived mainly for being used after the main document TOC (assuming it comes
+first). By default \etoc renders the main TOC as specified by the class it
+knows about. But for example in a |book|-class document, one does not want to
+use a chapter-like heading for a local TOC in a section. Hence the need for
+\csb{etocsettocstyle}. But if used in the preamble it will apply to the main
+TOC too (if it comes first in the document body), hence its usage has to be
+delayed or stored into some command, else one has to insert branches in the
+original definition to query the kind of TOC it is applied to.
+
+With \etocrelease{1.2} some utilities facilitate using
+\csb{etocsettocstyle} only once in the preamble and branch according to
+whether it is handling a main document TOC or a local one. But the macro was
+really initially conceived to be used for local TOCs once the main TOC was
+typeset (commands are provided to restore the default configuration in time
+for a main TOC at end of document). There is no command to customize the
+titles only for local TOCs from the preamble.
+
+With \etocrelease{1.2} an effort has been made to make using
+\csb{etocsettocstyle} for local TOCs purely an option: by default the package
+adopts a style for local headings which takes into account the local top
+level. This corresponds to the command \csb{etocetoclocaltocstyle}, which is emitted
+by default by the package.
+
+Furthermore \etocrelease{1.2} detects \ctanpkg{tocbibind}%
+%
+\footnote{Support for \ctanpkg{tocloft} customization of contents lines was
+ already in place for many years; the compatibility with \ctanpkg{tocbibind}
+ was added only at \etocrelease{1.2} and required to update the
+ \ctanpkg{tocloft} related code.}
+%
+and executes a compatilibity layer so that this package can be used with
+hopefully the same result as in the main document classes. Package options
+\etocoption{maintoctotoc}, \etocoption{localtoctotoc},
+\etocoption{localloftotoc} and \etocoption{locallottotoc} trigger ``to toc''
+mechanisms even without \ctanpkg{tocbibind} if desired, directly at \etoc
+level. The starred variants of the table of contents and ``list of'' commands
+will ignore the status of these options, as in the \ctanpkg{memoir} class.
+
+
+\section[\csbhyp{locallistof\-(figures\textbar\-tables)}]{The \protect\etocrelease{1.2}
+ \csbhyp{locallistoffigures} and \csbhyp{locallistoftables} commands}
+\label{locallistoffigures}
+\label{locallistoftables}
+\label{etocsetup}
+
+The major novelty with \etocrelease{1.2} is the addition of
+\csb{locallistoffigures} and \csb{locallistoftables}.
+
+Please read this:
+\begin{itemize}
+\item This is experimental code and the user interface as well as the
+ output may change.
+\item It is mandatory to load \etoc with option \etocoption{lof} for
+ \csb{locallistoffigures} and \etocoption{lot} for \csb{locallistoftables}.
+\item \etoc does not interfere whatsoever with \csa{listoffigures} and
+ \csa{listoftables}, and can not customize them in any way.
+\item \etoc still uses no additional auxiliary file, it uses only the
+ |.toc| file.
+\item This is experimental code and the user interface as well as the
+ output may change.
+\item The new command \csb{etocsetup} allows to configure at any
+ location in the preamble or in the document body the boolean options
+ \etocoption{maintoctotoc}, \etocoption{localtoctotoc},
+ \etocoption{localloftotoc}, \etocoption{locallottotoc}, and
+ \etocoption{ouroboros} which can also be issued as package options.
+ The first four default to |false|, except with the \ctanpkg{memoir}
+ class, in which case they are set to |true|, or when
+ \ctanpkg{tocbibind} is detected, in which case they are set to
+ |true| depending on the setting of the \ctanpkg{tocbibind} options.
+\item The \etocoption{ouroboros} option defaults to |true|. When set
+ to |false|, local TOCs which have been added to the |.toc| file due
+ to \etocoption{localtoctotoc} will \emph{not} list themselves (they
+ will still list entries from local TOCs at deeper levels in their
+ scope, and the ``lists of'' at their same level, and are listed in
+ the main TOC, the only thing is that they don't show themselves in
+ themselves).%
+%
+\footnote{It is complex to try to anticipate all scenarii, but in general, it
+ is expected this behavior may cause the |.toc| file to need more time to
+ stabilize when a new local TOC is added in the midst of a document having
+ already a bunch of them.}
+%
+The default is that they \emph{do} list themselves, hence the name
+\etocoption{ouroboros}. It has no impact on the main TOCs, use their
+starred variant to inhibit the self-display, but then why have issued
+\etocoption{maintoctotoc} in the first place?
+\item An effort has been made to facilitate as much as possible
+ customization by the user, i.e. via commands without |@| letter.
+ However this documentation will only list their names with very
+ brief comments at the appropriate place and the reader is expected
+ to check in the source code to understand better what they are for.
+\item This is experimental code and the user interface as well as the
+ output may change.
+\item For example, the actual figure entries or table entries use by
+ default the code from the main LOF or LOT; but one may prefer to
+ render them in a way taking into account the local ``list of''
+ scope: for example in a section, perhaps use the same style as
+ subsections. This is possible and is explained briefly later.
+\item Although the default ``\etoc'' choices for local titles should
+ be hopefully satisfactory in most cases, it is also possible to tell
+ \etoc to try to use emulation from the document class via the
+ command \csb{etocclasstocstyle}. An effort has been made to obtain
+ something which works at one level deeper than the ones under
+ \csa{part}. For example with \ctanpkg{KOMA-script}, we use the
+ option |leveldown|. However this will not really work for deeper
+ local ``lists of''.%
%
- and it
- has a variant \csa{localtableofcontents} which prints tables of contents
- `local' to the current surrounding document unit. An extension of the
- \csa{label}/\csa{ref} syntax allows to reproduce (with another layout) a local
- table of contents defined somewhere else in the document.
+\footnote{And with \ctanpkg{KOMA-script} at version \texttt{3.30} or later the
+ fact that unnumbered sections reset the subsection counter will cause bad
+ problems in a \texttt{scrbook} document if a TOC, local to a \csa{subsection}
+ uses a title which is un unnumbered section!}
+%
+But for some document using local ``lists of'' only for chapters or
+for sections in classes without chapters, this \csb{etocclasstocstyle}
+may be appropriate as it may allow the user to use the class interface
+for advanced control of the marks or other details.
+\item The \etoc document class agnostic default, from
+ \csb{etocetoclocaltocstyle} which is automatically issued at package
+ loading time, is completely customizable.
+\item This is experimental code and the user interface as well as the
+ output may change.
+\item If using for example all three of \csb{localtableofcontents},
+ \csb{locallistoffigures} and \csb{locallistoftables}, in the same
+ location after a division heading, and if the ``to toc'' related
+ options either from \etoc or from \ctanpkg{tocbibind} are used, then
+ \csb{localtableofcontents} must be the first one in order to be able
+ to list the other two (and itself). It can not see the ``lists of''
+ coming before itself at the same division level.
+\item Regarding the TOC title style, \etoc knows the standard classes,
+ the \ctanpkg{KOMA-script} main classes and the \ctanpkg{memoir}
+ class. In an unknown class it will use the code from the |article|
+ class emulation. For the local TOCs and local ``lists of'' it uses
+ as with the known classes its own class-independent code from
+ \csb{etocetoclocaltocstyle}.
+\item One can tell \etoc to not replace the original
+ \csa{tableofcontents} via \csb{etockeeporiginaltableofcontents} (it
+ will still be possible to use \csb{etoctableofcontents}), but the
+ non-etoc \csa{tableofcontents} is usable only if document does not
+ use \csb{locallistoffigures} or \csb{locallistoftables} as the
+ latter two insert entries for figures, resp.\@ tables, in the main
+ |.toc| file and only \etoc's \csb{tableofcontents} knows to ignore
+ them.
+\item This is experimental code and the user interface as well as the
+ output may change.
+\end{itemize}
- Via ``depth tags'', one gets an even finer control for each table of contents
- of which sectioning units it should, or not, display.
+\section{The \csbhyp{etocsettocstyle} command}
+\label{etocsettocstyleintro}
- The formatting inherited (and possibly customized by other
- packages) from the document class will be used when in
- \emph{compatibility mode}.
+This is a command with two mandatory arguments:
+\centeredline{\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}
+The \marg{before\_toc} part is responsible for typesetting the
+heading, for example it can be something like
+\starit{section}|{\contentsname}|. Here is an example of input:
+\begin{verbatim}
+\etocsettocstyle
+ {\section*{Local table of contents}}%
+ {}% don't do anything special after the toc contents
+\end{verbatim}
- The assignment of levels to the sectioning units can be changed at any
- time, and \etoc can thus be used in a quite general manner to
- create custom ``lists of'', additionally to the tables of contents
- related to the document sectioning units. No auxiliary file is used
- additionally to the standard |.toc| file.
-\end{abstract}
+Once issued it will have an impact on all next usages of \localtoc (or \toc)
+until it is used again (or some related command).
-\section{Foreword}
+Generally speaking the \marg{before\_toc} part should leave \TeX{} in
+``vertical mode'': the line styles (either from the standard classes or the
+package default ones) all expect to get started in `vertical mode'.
-%\ifnum\NoSourceCode=0
-\begin{framed}
- Throughout the documentation the command names displayed
- {\textcolor{RoyalBlue}{with this colour}} are doubly hyperlinked: the left
- half of the name links to the user documentation, the second half links to
- the source code. You can try it out now: \csb{localtableofcontents}. But
- read this first: if you get lost inside the source code, clicking on control
- sequences displayed {\textcolor{macrocodelinktouserdoccolor}{with this
- colour}} brings you back to the part of the user manual discussing that
- specific command. \ifnum\NoSourceCode=1 (but this PDF does not include the source code)\fi
-\end{framed}
-%\fi
+For more documentation of this and related commands see first
+\autoref{sec:compatoverview} then
+\autoref{sec:tocstyle} for the more detailed pre-\etocrelease{1.2} documentation.
-Popular packages dealing with TOCs include \ctanpkg{tocloft}, \ctanpkg{titletoc}
-and \ctanpkg{minitoc}. Why another one? I started \etoc
-for my own use, and found out only later about these mentioned
-packages.
-
-As is well explained in the \ctanpkg{tocloft} package documentation,
-the standard \LaTeX{} layout for the Table of Contents is
-buried in the class definitions. In particular, most of the
-lengths therein are hardcoded, and the only way for the user
-to change them is to recopy the class definitions into the
-document and then change them to obtain what is desired
-(within suitable \csa{makeatletter} and \csa{makeatother}).
-The more reasonable alternative is to use a dedicated package such as
-\ctanpkg{tocloft} or to use another flexible document class.
-
-However, although now things are hopefully not hard-coded, one
-still has to go through the package or class interface. This
-means one has to memorize a (possibly large) number of macros
-which will serve only to this task, and one will always be
-constrained to customizing one initially given layout.
-
-The spirit of \etoc is something else. The user will deal with
-the \emph{name}, the \emph{number} and the \emph{page number}
-corresponding to each document sectional division (and
-found in a line of the |.toc| file) in a completely arbitrary
-manner: they are made available via the \csb{etocname},
-\csb{etocnumber}, and \csb{etocpage} commands.
-
-\etoc appears to be (at least partially) compatible with the
-|article|, |book|, |report|, \ctanpkg{scrartcl}, \ctanpkg{scrbook}, \ctanpkg{scrreprt} and
-\ctanpkg{memoir} classes.
-
-\section{License}
-
-\begingroup\ttfamily\small\hyphenchar\font -1
- \parindent0pt
- \obeyspaces\obeylines %
-\etocLicense\endgroup
+Only daring people will continue reading documentation as it now starts
+telling how to truly activate \etoc power.
+\section{The \csbhyp{etocsetstyle} command}
+\label{etocsetstyleintro}
-\clearpage
+A distinction must be made between the \emph{line styles}, \emph{i.e.} the way
+the name, number and page numbers (aka \etoc-provided \csb{etocname},
+\csb{etocnumber}, and \csb{etocpage}) are used at each level, and the \emph{toc
+ display style} (for lack of a better name) which tells how the title should
+be set, whether an entry in the |.toc| file should be made, whether the
+contents should be typeset with multiple columns, etc... the latter is governed
+by the command \csb{etocsettocstyle} (and related commands) which has already
+been mentioned, and the former by the command \csb{etocsetstyle} with is the
+core of \etoc functionality.
-\etocsettocdepth {subsection}
+It has five mandatory arguments.
+%
+\centeredline
+{\csb{etocsetstyle}\color{blue}\marg{levelname}%
+ \marg{start}\marg{prefix}\marg{contents}\marg{finish}}
+%
+The first one is the name of the sectional unit: a priori known names are
+|book|, |part|, |chapter|, |section|, |subsection|, |subsubsection|,
+|paragraph|, and |subparagraph|. Any other name can be declared and
+assigned to a (numeric) level via the \csb{etocsetlevel} command.%
+%
+\footnote{\etoc issues automatically
+ \csb{etocsetlevel}\texttt{\string{appendix\string}\string{0\string}} (or wit
+ h |1| if the document has no \csa{chapter} command), since
+ \etocrelease{1.2}. Formerly this was done only with class
+ \ctanpkg{memoir}.}
-\etocdepthtag.toc{overview}
+The four other arguments of \csb{etocsetstyle} specify: 1) \emph{what to do
+ when this level is first encountered, down from a more general one,} then 2)
+\& 3) (two arguments, a `prefix' and a `contents') \emph{how to use for this
+ level the \csb{etocname}, \csb{etocnumber} and \csb{etocpage} parsed data,}
+and 4) \emph{the last argument is the code to execute when a division unit of
+ higher importance than the defined level style is encountered.}
-\part{Overview}\label{part:overview}
+Notice that this means that virtually \etoc manages a kind of tree-like
+substratum which is abstracted from the `flat' structure of the |.toc| data.
-\thispartstats
+You should now read \autoref{sec:linestyles} for the detailed documentation.
-\invisiblelocaltableofcontents \label{toc:overview}
-
-\section{Do I need to be a geek to use \etoc?}
-
-Not quite. The simplest way is to use |enumerate| environments,
-with the customizing facilities of packages such as
-\ctanpkg{enumitem}, to
-display the data fetched by \etoc from the |.toc| file. The data
-consists of the \emph{name} (\csb{etocname}), \emph{number}
-(\csb{etocnumber}), and \emph{page number} (\csb{etocpage}) as
-extracted
-% \footnote{although \LaTeX{} has been promoted as
-% separating contents from form, there are some areas where its
-% real implementation is very far from this ideal. And the |.toc|
-% file is a case in point; not to mention the hard-coded
-% dimensions, with use of the @ sign,
-% in the macros responsible for constructing the typeset table of
-% contents.}
-from the |.toc| file.
-
-This is
-illustrated \hyperref[toc:a]{at the start} of
-\autoref{part:linestyles}. More
-sophisticated examples would use more sophisticated |enumitem|
-options. One may say then that again the user has to memorize some
-customizing! indeed, but the syntax and option names to memorize
-are in no way related only to matters of tables of contents, hence
-an economy of use of the poor brain.
-
-% People who
-% know the internals of \LaTeX2e well (which is not my case) could
-% happily use directly a |\list| command;
-
-Next in ease of use, perhaps, is the method explained
-\hyperref[sec:firstexample]{later in this part}
-(\autoref{sec:firstexample}). For this some knowledge of |\leftskip|,
-|\rightskip|, etc... is necessary. And a slight elaboration of this
-method, whose code is to be found in \autoref{ssec:tocwithdepthtags},
-allows to mimick very well, if so desired, the standard looks. An even
-closer emulation of the |book| class design is now included in this
-documentation as \autoref{sec:thirdexample}.
-
-As will be amply illustrated in this manual, \etoc is quite
-versatile (especially as it allows to re-define at any point in
-the document the hierarchy of sectioning units) and one can
-achieve surprising effects with it: \autoref{part:surprising} is
-devoted to this, and some more is to be found in
-\autoref{part:tipsandtricks}.
+\section{No auxiliary file is used beyond the TOC file}
+\label{sec:compatoverview}
-\begin{framed}
+An important characteristic of \etoc is that it is allows many different TOCs
+in the same document, \emph{using only one} |.toc| \emph{file}!
+
+\begingroup
\setcounter{mycounti}{0}%
\etocinline
\etocsetlevel{part}{1}
@@ -1723,457 +1836,1601 @@ devoted to this, and some more is to be found in
\etocsettocstyle{}{}
\etocsetnexttocdepth{0}
\tableofcontents
-A very important aspect of \etoc is that it is geared towards making many TOCs
-in the same document, \emph{using only one} |.toc| \emph{file}! The present
-documentation contains \arabic{mycounti} visible tables of contents (and a few
-invisible ones) and uses only one |.toc| file!\footnotemark{} So one should
-think
-twice before adding manually extra commands to the |.toc| file (see
-\autoref{sec:addingtotoc}).
-\end{framed}
-
-\footnotetext{and the counting itself has been achieved by a table of contents
- which was inserted in the framed paragraph! \dots the technique for this kind
- of effect will be explained later.}
-
-
-\subsection{Limitations in the use of list environments for
- tables of contents}
-\label{ssec:limitations}
-
-There are some limitations to the use of list environments
-for typesetting TOCs. One of them is intrinsic to the scope
-limitations created by the groups associated to the
-environments: the |.toc| file
-may contain, besides the information to be typeset in the
-TOCs, some other commands, such as language changing
-commands, which do not expect to see their scope limited in
-this way inside a group (\LaTeX's environments create scope limiting groups).
-
-Therefore the built-in ``line styles'' proposed by \etoc as an example
-(and which are illustrated\footnote{with a twist, subsections having
- been downgraded to the subsubsection style\dots} by the
-\hyperref[toc:main]{main table of contents} in this document) do not
-make use of environments. Actually, in this user manual, only the
-\hyperref[toc:a]{table of contents} at the start of
-\autoref{part:linestyles}, the \autoref{toc:allsubsections} (which is a
-TOC!) and examples from \autoref{etocthelink} have their line
-styles expressed in terms of enumerate or itemize environments.
-
-\section{Line styles and toc display style}
-
-A distinction shall be made between the \emph{line styles},
-\emph{i.e.} the way the name, number and page numbers are
-used at each level, and the \emph{toc display style} (for
-lack of a better name) which tells how the title should be
-set, whether an entry in the |.toc| file should be made,
-whether the contents should be typeset with multiple columns,
-etc... the latter is governed by the command
-\csb{etocsettocstyle} (or some higher-level commands) and the
-former by the command \csb{etocsetstyle}.
-
-
-\subsection{\csbhyp{etocsetstyle} for the line styles}
-
-The command to inform \etoc of what to do with \csb{etocname}, \csb{etocnumber},
-and \csb{etocpage} is called \csb{etocsetstyle}. It has five mandatory
-arguments. The first one is the name of the sectional unit: a priori known names
-are |book|, |part|, |chapter|, |section|, |subsection|, |subsubsection|,
-|paragraph|, and |subparagraph|, and any other name can be declared and assigned
-to a (numeric) level via the \csb{etocsetlevel} command.\footnote{under the
- \texttt{memoir} class, \etoc knows \texttt{appendix} as a sectioning
- name.}
-
-The four other arguments of \csb{etocsetstyle} specify: 1) \emph{what to do when
- this level is first encountered, down from a more general one,} then 2) \& 3)
-(two arguments, a `prefix' and a `contents') \emph{what to do when a new entry
- of that type is found,} and 4) \emph{the last argument is the code to execute
- when a division unit of higher importance is again hit upon.}
-
-\subsection{\csbhyp{etocsettocstyle} for the toc display}
-
-The \csb{etocsettocstyle} command allows to specify what
-should be done before and after the line entries of the TOC
-are typeset, and in particular how the title should be
-printed. It has two arguments, the first one is executed
-before the TOC contents (typically it will print
-``Contents'' and define suitable marks for the page headings) and
-the second is executed after the TOC contents.
-
-\etoc provides four (customizable) higher level toc styles:
-\csb{etocmulticolstyle}, \csb{etoctocstyle},
-\csb{etocruledstyle}, and \csb{etocframedstyle}. All use the
-\ctanpkg{multicol} package with a default of two columns
-(single-column mode is obtained with the optional argument |[1]|).
-
-These commands must be followed either by \toc or \localtoc.
-
-\subsection{Compatibility mode}\label{subs:compat}
-\label{etoctoclines}
-\label{etocstandardlines}
-
-Both for the ``line styles'' and the ``toc display style'', \etoc defaults to
-a compatibility mode which uses the defaults from the document
-class.%
-%
-\footnote{\label{fn:compat}for the ``toc display style'' \etoc checks if it knows the class,
- and then uses emulation code which was added manually to its source, and
- if not it defaults to the |article| class layout. No automated way to recover
- the global toc display for arbitrary document classes is implemented. But \etoc
- will detect if \ctanpkg{tocloft} has customized the TOC title.}
-%
-This can always be re-activated by:\\
-% \makebox[5.2cm][l]{\csb{etocstandardlines}}
-% |% `line entries' as without \usepackage{etoc}|\\
-% \makebox[5.2cm][l]{\csb{etocstandarddisplaystyle}}
-% |% `toc display' as without \usepackage{etoc}|
-\csb{etocstandardlines}\hfill
-|% `line entries' as without \usepackage{etoc}|\\
-\csb{etocstandarddisplaystyle}\hfill
-|% `toc display' as without \usepackage{etoc}|
-
-
-If the command \csb{etocsetstyle} has \emph{not been used in the
-preamble} the package will be at |\begin{document}| in this
- compatibility mode: hence just adding \csa{usepackage\{etoc\}}
- should hopefully not change anything to the look of a
- previously existing document, under the |article|, |book|,
- |report|, \ctanpkg{scrartcl}, \ctanpkg{scrbook}, \ctanpkg{scrreprt} and \ctanpkg{memoir}
- classes.
-
- Any use of \csb{etocsetstyle} in the \emph{preamble or body} of
- the document turns off from that point on the compatibility mode
- for line styles, but maintains the compatibility mode for the
- TOC title. One re-activates the compatibility mode for line
- styles with \csb{etocstandardlines}; and
- \csb{etoctoclines} will re-activate the line styles as defined
- with the help of \csb{etocsetstyle}, if their scope was not
- limited to a group or environment.
-
- The command \csb{etocdefaultlines} sets the line styles to custom ones
- pre-defined internally by \etoc and described in
- \autoref{etocdefaultlines}.
-
-Even if \csb{etocsetstyle} has been used, the global display style
-remains initially as defined by the document class or the
-\ctanpkg{tocloft} package (but see footnote\footref{fn:compat}); one needs to use the command
-\csb{etocsettocstyle} or its variants to exit from this
-compatibility mode at the ``toc display style'' level. It will be
-re-activated if use if made of \csb{etocstandarddisplaystyle}.
-
-See further \autoref{sec:anothercompat}.
-
-\section{A first example}
-\label{sec:firstexample}
-\label{invisiblelocaltableofcontents}
-
-Let us present a first example of specification for line styles.
-Immediately after the start of \autoref{part:overview} we inserted in the
-source file:
-\centeredline{\csb{invisiblelocaltableofcontents} |\label{toc:overview}|} This
-sets-up the label |toc:overview|, and we can use it at any location in the
-document: \centeredline{|\tableofcontents \ref{toc:overview}|} And as we used
-|\invisible...|,\footnote{this is a shortcut for setting temporarily the
- |tocdepth| to |-3|, which has the effect to tell \etoc not to print the TOC,
- and not even the heading.} the local TOC will exist only through its clones
-elsewhere in the document.
-
-\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
-\begingroup\parindent 0pt \parfillskip 0pt \leftskip 0cm \rightskip 1cm
-\etocsetstyle {section}
- {}
- {\leavevmode\leftskip 0cm\relax}
- {\bfseries\normalsize\makebox[.5cm][l]{\etocnumber.}%
- \etocname\nobreak\hfill\nobreak
- \rlap{\makebox[1cm]{\mdseries\etocpage}}\par}
- {}
-\etocsetstyle {subsection}
- {}
- {\leavevmode\leftskip .5cm\relax }
- {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
- \etocname\nobreak\hfill\nobreak
- \rlap{\makebox[1cm]{\etocpage}}\par}
- {}
-\etocsetstyle {subsubsection}
- {}
- {\leavevmode\leftskip 1.5cm\relax }
- {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
- \etocname\nobreak\hfill\nobreak
- \rlap{\makebox[1cm]{\etocpage}}\par}
- {}
-\etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of
- \autoref{part:overview} (\nameref{part:overview})}
-\tableofcontents \ref {toc:overview}
+The present documentation contains \arabic{mycounti} visible tables of
+contents (and a few invisible ones) and uses only one |.toc| file!%
+%
+\footnote{and the counting itself has been achieved by a table of contents
+ which was inserted in this paragraph! See \autoref{sec:tocoftocs}.}
\endgroup
-\end{filecontentsdef}
-\filecontentsexec\foo
+However, each \localtoc or \toc command will trigger the execution of the
+\emph{full contents} from the |.toc| file. The effect of \localtoc as well as
+the enforcement of the line styles as defined via \csb{etocsetstyle} are
+achieved via suitable redefinition of the \csa{contentsline} \LaTeX{} macro.
+But everything else present in the |.toc| file will be executed, as it is not
+possible for \etoc to control in any way what is present in the |.toc|
+file beyond \csa{contentsline} entries.
-We could have used the line styles defined by \etoc, with
-\csb{etocdefaultlines}, or the default document class styles with
-\csb{etocstandardlines}, but we were a bit more ambitious here and wanted to
-design our own. The technique is a simple one: each heading is in its own
-paragraph, which may extend on multiple lines; it is responsible for setting
-its own |\leftskip|.
+So one should think twice before adding manually extra commands to the |.toc|
+file. See \autoref{sec:addingtotoc} for further discussion.
-This is a simple design which does not make provisions for page breaks
-which should be discouraged in-between a section and a subsection
-etc\dots{} as we only used it for the table of contents of this part, thus
-with sections as top levels, there was no need to specify a style for
-parts too (we defined a subsubsection line style but as it turns
-out there are no subsubsections in this part). The two commands used are
-\csb{etocsetstyle} for specifying the line styles, and
-\csb{etocruledstyle} for the TOC global style.
-The |\rightskip| is shared by all, and creates space where the page
-numbers get printed. For an elaboration of this technique see the next
-\autoref{sec:secondexample} as well as \autoref{ssec:tocwithdepthtags}
-which provides a TOC with parts and paragraphs. Both allow multi-line
-headings and employ a technique for putting page numbers in the right margin
-which was inspired from what \LaTeX2e's |\@dottedtocline| macro does.
-Here is how it was produced:
-\filecontentsprint\foo
-\marginattach{}
+\section{Compatibility mode}\label{subs:compat}
+\label{etoctoclines}
+\label{etocstandardlines}
+\label{etocclasstocstyle}
+\label{etocetoclocaltocstyle}
+\label{etocusertocstyle}
+\label{etoclocallistoffigureshook}
+\label{etoclocallistoftableshook}
+
+\etoc starts in a ``compatibility mode'', which means that it does not at all
+interfere with how the commands from the |.toc| file get executed as long as
+it has not been told explicitly to do so.%
+%
+\footnote{\label{fn:compat}for the ``toc display style'', by this we mean the
+ aspects independant from the contents of the \texttt{.toc} file, \etoc checks
+ if it knows the class, and then uses emulation code which was added manually
+ to its source, and if not it defaults to the |article| class layout. No
+ automated way to recover the global toc display for arbitrary document
+ classes is implemented. But \etoc will detect if \ctanpkg{tocloft} has
+ customized the TOC title.}
+
+This ``compatibility mode'' stops for matters of the ``toc display style'' as
+soon as \csb{etocsettocstyle} is made use of, and for matters of the ``toc
+line styles'' as soon as \csb{etocsetstyle} is used for \emph{any} level
+(part, chapter, section, ...). Levels not receiving explicit configurations
+will use some pre-defined defaults which are in \etoc source code.
-\section{A second example}
-\label{sec:secondexample}
+\begin{description}
+\item[\csb{etocclasstocstyle}] sets the `main toc layout' to be as without
+ |\usepackage{|\etoc\unskip|}|. Local TOCs will also obey the document class
+ style but with an attempt to use a heading one level down. This tries to
+ adapt to being in the top level below \csa{part} (i.e. in a \csa{chapter} or
+ \csa{section}) but is not adapted to deeper local TOCs.
+
+ At \etocrelease{1.2}, previously existing \csa{etocstandarddisplaystyle}
+ was made into a deprecated synonym to this (the version from earlier
+ releases made no attempt to adapt the style of the local TOCs to the level
+ where it is located).
+
+\item [\csb{etocetoclocaltocstyle}] (package default) Activates a heading
+ style for local tables of contents (and ``lists of'') which tries to adapt
+ automatically to the surrounding level. It thus by-passes the configuration
+ done by \csb{etocsettocstyle} which will then apply only to the main TOC.
+ Using again \csb{etocsettocstyle} de-activates this behavior.
+
+\item [\csb{etocusertocstyle}] means to obey the \csb{etocsettocstyle}
+ configuration as previously in place, not only for the main TOC but also for
+ local ones. If \csb{etocsettocstyle} has never been used, this means that
+ we return to the situation from \csb{etocclasstocstyle}.
+
+\item [\csb{etocstandardlines}] (package default) Sets the `content lines' to be as without
+ |\usepackage{|\etoc\unskip|}|.
+
+\item [\csb{etoctoclines}] sets the `content lines' to match the last encountered
+ \csb{etocsetstyle} specs.
+
+\item [\csb{etocdefaultlines}] sets the `content lines' to use \etoc pre-defined
+ ones. The denomination is a bit confusing as `default' here means that
+ these line styles are the ones defined by default, but not used by
+ default\dots{} perhaps \csa{etocfallbacklines} would have been a better name.
+\end{description}
-This second example displays only the contents from
-\autoref{part:linestyles} and \autoref{part:globalcmds}. This selection
-is done via the technique of \emph{depth tags}, described in
-\autoref{etocsettagdepth} and \autoref{ssec:tocwithdepthtags}. Its
-layout is a bit like the one of the \hyperref[toc:main]{main document
- TOC}, although the line styles are coded very differently.
+Naturally \csb{etocsettocstyle} and \csb{etocsetstyle} can be used arbitrarily
+many times in the document body (or already in the preamble but there one can
+not typeset a TOC; however one can prepare commands which will be activated
+later from inside the document body). And they obey the scope-limiting effect
+of \LaTeX{} environments.
+
+For an illustration of using \etoc in compatibility mode see
+\autoref{sec:testingcompat}. And see \autoref{sec:anothercompat} for some
+ways to let the line styles use the code from the document class but with some
+custom changes.
+
+During expansion of \csb{locallistoffigures} or
+\csb{locallistoftables}, the macros \csb{etoclocallistoffigureshook} resp.\@
+\csb{etoclocallistoftableshook} are executed right before typesetting
+the entries. (Click on ``hook'' in previous sentence for advices on their usage).
+\begin{verbatim}
+\def\etoclocallistoffigureshook{\etocstandardlines}
+\def\etoclocallistoftableshook {\etocstandardlines}
+\end{verbatim}
+Let's simply say here
+that if you redefine them to do nothing, the lines will use the style as
+appropriate for entries at numerical level one deeper than the ``local top'':
+i.e. in a section they will be typeset as if being subsections. If
+you have both \csb{locallistoffigures} and a \localtoc, this may align
+better vertically than the \LaTeX{} line style from the global ``Lists Of''.
+
+
+Note that ``hook'' is used here in a very naive meaning of some macro which is
+pre-located somewhere and that one can redefine to obtains various effects.
+
+\section{A list of the commands added at \protect\etocrelease{1.2}}
+\label{etocstoretocstyleinto}
+\label{etocstorelinestylesinto}
+\label{etocstorethislinestyleinto}
+\label{etocifislocal}
+\label{etocifislocaltoc}
+\label{etocifislocallof}
+\label{etocifislocallot}
+%%\label{etocsettocstyle}
+\label{etocifmaintoctotoc}
+\label{etociflocaltoctotoc}
+\label{etociflocalloftotoc}
+\label{etociflocallottotoc}
+\label{etocifisstarred}
+\label{etoclevel}
+\label{etocifunknownlevelTF}
+\label{etocdivisionnameatlevel}
+\label{etoclocalheadtotoc}
+\label{etocglobalheadtotoc}
+\label{etocetoclocaltocmaketitle}
+%%\label{etocetoclocaltocstyle}
+\label{localcontentsname}
+\label{locallistfigurename}
+\label{locallisttablename}
+\label{etocetoclistoffiguresmaketitle}
+\label{etocetoclistoftablesmaketitle}
+\label{etocclasslocaltocmaketitle}
+\label{etocclasslocallofmaketitle}
+\label{etocclasslocallotmaketitle}
+\label{etocclassmaintocaddtotoc}
+\label{etocclasslocaltocaddtotoc}
+\label{etocclasslocallofaddtotoc}
+\label{etocclasslocallotaddtotoc}
+
+\begin{shaded}\footnotesize
+%\setstretch{1}
+ One pre-existing command has been modified: \csa{etocstandarddisplaystyle}
+ which is now deprecated and replaced by \csb{etocetoclocaltocstyle}. The
+ former behavior was to set also local TOCs to apply the style from the main
+ TOC, which basically never works really well. As explained already one can
+ use \csb{etocclasstocstyle} to try to get for top local TOCs a suitable
+ behavior, for example in the case of \ctanpkg{KOMA-script} classes, a
+ behavior using their |leveldown| option. But this will not be satisfactory
+ for deeper local TOCs or ``lists of''.
+\end{shaded}
+
+With \csb{etocsettocstyle} one has complete decision about how the TOCs
+typeset their titles. Thus, this also means that supporting the options such
+as \etocoption{localtoctotoc} is entirely up to the provided code. There is
+no real reason for the user to go into this but \etoc does provide
+nevertheless generic utilities allowing to write very general styles,
+supporting the options if so desired. We now turn to their descriptions. The
+first few are accompanied with more details, but all hyperlink to their source
+code via the right third of their names (some are defined in batches and
+receive initial dummy definitions only to provide hyperlink targets).
-\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
-\begingroup
-\newcommand*{\DotsAndPage}
-{\nobreak\leaders\hbox{\bfseries\normalsize\hbox to .75ex {\hss.\hss}}%
- \hfill\nobreak
- \makebox[\rightskip][r]{\bfseries\normalsize\etocpage}\par}
+\begin{description}
+\item [\csb{etocstoretocstyleinto}\marg{control\_sequence}] This is a command
+ with one mandatory argument which must be a control sequence such as
+ \csa{foo}. The macro \csa{foo} is then overwritten with no check if it
+ exists already. Its effect is to store inside \csa{foo} the data configured
+ by the last \csb{etocsettocstyle}. Then inserting \csa{foo} in the document
+ will restore the saved toc style.%
+%
+\footnote{It is impossible to store the style used by the
+ \csb{etocetoclocaltocstyle} for local TOCs. Only the one for main TOCs,
+ which was configured by last usage of \csb{etocsettocstyle} is saved in
+ \csa{foo}. After \csa{foo} is executed, one needs to again issue
+ \csb{etocetoclocaltocstyle} if one wants the latter to be active.}
+
+\item [\csb{etocstorelinestylesinto}\marg{control\_sequence}] Same principle
+ but now \csa{foo} will store the line styles for all levels. And inserting
+ \csa{foo} will have the same effect as re-doing all \csb{etocsetstyle} for
+ all levels.
+
+\item [\csb{etocstorethislinestyleinto}\marg{name or
+ number}\marg{control\_sequence}] Same principle but now \csa{foo} will
+ store the line style for the specified level, which can be numerical or a
+ name. And then executing \csa{foo} will have the same effect as re-doing the
+ \csb{etocsetstyle} for this level.%
+%
+\footnote{Absolutely no error check is done on the first argument. There is no
+ interface for re-assigning the style to another level, although it would not
+ be difficult to code it. But the \etoc powers about re-assigning levels are
+ things better left to unearthly entities such as the author.}
-\etocsetstyle {part}
-{\parindent 0pt
- \nobreak
- \etocskipfirstprefix}
-{\pagebreak[3]\bigskip}
-{\large\rmfamily\bfseries\scshape\centering
- \etocifnumbered{Part \etocnumber{} -- }{}\etocname\par}
-{}
+\DeleteShortVerb\|
+
+\item [\csb{etocsetup}\marg{key[=true|false],...}] was already mentioned
+ earlier. Only usable with the five boolean options. But everywhere in the
+ document after the package loading.
+\end{description}
-\etocsetstyle {section}
-{\leftskip 0pt \rightskip .75cm \parfillskip-\rightskip
- \nobreak\medskip
- \etocskipfirstprefix}
-{\leftskip 0pt \rightskip .75cm \parfillskip-\rightskip
- \pagebreak[1]\smallskip}
-{\normalsize\rmfamily\bfseries\scshape
- \etocnumber. \etocname\DotsAndPage }
-{\parfillskip 0pt plus 1fil\relax }
+\MakeShortVerb\|
-\etocsetstyle {subsection}
-{\leftskip1cm\rightskip .75cm \parfillskip 0pt plus 1fil\relax
- \nobreak\smallskip}
-{}
-{\footnotesize\sffamily\mdseries\itshape
- \etocname{} (\etocnumber, p. \etocpage). }
-{\par\medskip}
+Those next will be more briefly described.
+\begin{itemize}
+\item \csb{etocifislocal}, \csb{etocifislocaltoc}, \csb{etocifislocallof},
+ \csb{etocifislocallot} can be used from inside the \csb{etocsettocstyle}
+ first or second argument to select either one of the \marg{True} and \marg{False}
+ branches.
+
+\item \csb{etocifmaintoctotoc}, \csb{etociflocaltoctotoc},
+ \csb{etociflocalloftotoc}, \csb{etociflocallottotoc}, are conditionals
+ matching the options and selecting one of the \marg{True} or \marg{False} branches.
+
+\item \csb{etocifisstarred}\marg{True}\marg{False} says from inside the
+ \csb{etocsettocstyle} arguments if the toc or `list of' command was in
+ starred form.
+
+ The \csb{etocetoclocaltocstyle} and \csb{etocclasstocstyle} have been configured so
+ that when a |*| follows a \toc or \localtoc or local ``lists of'', its ``to
+ toc'' behavior (if active from \ctanpkg{tocbibind} or \etoc own options) is
+ canceled. They use \csb{etocifisstarred} to this effect.
+
+\item \csb{etoclocalheadtotoc}\marg{levelname}\marg{text} is a synonym for
+ \centeredline{\csa{addcontentsline}|{toc}|\marg{@levelname}\marg{text}}
+%
+ Pay
+ attention to automatically added |@| character.%
+%
+\footnote{Without this syntax, it would not be possible to have all three of
+ \localtoc, \csb{locallistoffigures} and \csb{locallistoftables} one after
+ the other following a given document heading, due to deep internals of the
+ local TOC \etoc mechanism. Notice that these internal details are
+ susceptible to change with no advance notice and the actual implementation
+ of \csb{etoclocalheadtotoc} may change.}
-\etocsettagdepth {preamble} {none}
-%\etocsettagdepth {overview} {none}% not needed explicitely, keeps value
-%\etocsettagdepth {arbitrarily}{none}
-%\etocsettagdepth {examples} {none}
-%\etocsettagdepth {surprising} {none}
-\etocsettagdepth {linestyles} {subsection}
-\etocsettagdepth {globalcmds} {subsection}
-\etocsettagdepth {custom} {none}
-%\etocsettagdepth {tips} {none}
-%\etocsettagdepth {etocandworld}{none}
-%\etocsettagdepth {code} {none}
-\etocsettocstyle {\centering\LARGE\textsc{\contentsname}\par\nobreak\medskip}{}
-\etocsetnexttocdepth {subsection}
-\tableofcontents
-\endgroup
-\end{filecontentsdef}
-\filecontentsexec\foo
+ Use this for example in the second argument of \csb{etoclocalmulticol}.%
+%
+\footnote{There is currently no analog of \csb{etoclocalmulticol} and similar
+ commands which would be related to \csb{locallistoffigures} or
+ \csb{locallistoftables} as \csb{etoclocalmulticol} is to \localtoc.}
-The code:
-\filecontentsprint\foo
-\marginattach{}
+\item \csb{etocglobalheadtotoc}\marg{levelname}\marg{text} is a synonym for
+ \centeredline{\csa{addcontentsline}|{toc}|\marg{levelname}\marg{text}}
+%
+ We
+ have so many commands we can define another useless one\dots{} for aesthetic
+ reasons of coherent names\dots{}
-\section{A Beautiful Thesis example}
+\item \csb{etoclevel}\marg{levelname} expands to a numeric quantity giving
+ the level of a given string argument. For example \csb{etoclevel}|{section}|
+ will usually produce a \TeX{} number denotation of value one. It must be
+ prefixed by something such as the \TeX{} primitive \csa{number} to give an
+ explicit digit with perhaps a minus sign, but can serve as is in \csa{ifnum}
+ tests.
-Here is a relatively simple example of use of the package
-functionalities.
-Let us set up some line styles. We choose a style for sections and
-sub-sections which would be suitable for, respectively, sections and
-sub-sections in an average length memoir. The line style specifications have
-some redundancy for clarity, and do not care about what to do at possible page
-breaks. Also, they do not worry about potential multi-column use.
+\item \csb{etocifunknownlevelTF}\marg{levelname}\marg{True}\marg{False} is a
+ conditional to test if a level is known to \etoc.
-\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
-\begingroup % we start a group to keep the style changes local
-\newlength{\tocleftmargin} \setlength{\tocleftmargin}{5cm}
-\newlength{\tocrightmargin} \setlength{\tocrightmargin}{1cm}
+\item \csb{etocdivisionnameatlevel}\marg{number} is an expandable construct
+ which starts from a numerical level from |-2| to |5| and produces one of
+ |book|, |part|, ..., up to |subparagraph|.
-\etocsetstyle{section} % will pretend to be a Chapter
-{\addvspace{1ex}\parfillskip0pt
- \leftskip\tocleftmargin % (already done in title)
- \rightskip\the\tocrightmargin plus 1fil
- \parindent0pt\color{cyan}} % (already done)
-{\bfseries\LARGE\upshape\addvspace{1ex}\leavevmode}
-{\llap{Chapter\hspace{.5em}{\etocnumber}\hspace{.75cm}}\etocname
- \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
-{}
+\item \csb{etocetoclocaltocmaketitle} is the command used by
+ \csb{etocetoclocaltocstyle} which typesets a local ``list of'' title using
+ an un-numbered sectioning appropriate to its scope. See the source code for
+ how it looks.
-\etocsetstyle{subsection} % will pretend to be a Section
-{}
-{\mdseries\large\addvspace{.5ex}\leavevmode}
-{\llap{\etocnumber\hspace{.75cm}}\textit{\etocname}%
- \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
-{}
+\item \csb{etocetoclistoffiguresmaketitle} and
+ \csb{etocetoclistoftablesmaketitle} are similar, see the source code.
-\def\tmptitle{My Beautiful Thesis}
-\etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin
- \leavevmode\leaders\hrule height 1pt\hfill\
- \huge\textit{\tmptitle}\par}{\bigskip}
+\item \csb{localcontentsname}, \csb{locallistfigurename}, \csb{locallisttablename}
+ are self-explanatory.
-\tableofcontents \ref{toc:overview}
-\endgroup
-\end{filecontentsdef}
+\item \csb{etocclasslocaltocmaketitle}, \csb{etocclasslocallofmaketitle},
+ \csb{etocclasslocallotmaketitle}, \csb{etocclassmaintocaddtotoc},
+ \csb{etocclasslocaltocaddtotoc}, \csb{etocclasslocallofaddtotoc},
+ \csb{etocclasslocallotaddtotoc}, well again see source code.
-\filecontentsexec\foo
-\filecontentsprint\foo
-\marginattach{}
+\end{itemize}
+% {\footnotesize (clearing this page as next display must be on one page
+% only)\par}
+% \clearpage
-\section{Linked list of the main package commands}
+\section{A partial list of the package commands}
+%\enlargethispage{2\baselineskip}
+%\vskip-\baselineskip\vskip0pt
-\begin{framed}\multicolsep0pt\relax
- \begin{multicols}{3}\parindent0pt\relax
-\flushleft
- \csb{tableofcontents}\par
- (optional \csa{ref} or \csa{label})\par
- \csb{localtableofcontents}\par\columnbreak
- \csb{etocsettocstyle}\par
- \mbox{}\par
- \csb{etocsetnexttocdepth}\par\columnbreak
-\flushright
- \makebox[\widthof{\csa{etocnumber}}][l]{\csb{etocname}}\par
-% \llap does not trigger horizontal mode?
- \noindent
- \llap{\csb{etocsetstyle}
-% \smash is not \long!
- \smash{$\left\{\parbox{0pt}{\mbox{}\endgraf
- %\mbox{}\endgraf
- \mbox{}\endgraf
- \mbox{}\endgraf
- \mbox{}\endgraf}\right.$}
- }%
- \csb{etocnumber}\par
- \makebox[\widthof{\csa{etocnumber}}][l]{\csb{etocpage}}\par
- \end{multicols}
-\end{framed}
%\parshape 1 -1.5cm \dimexpr\linewidth+3cm\relax
%\begin{minipage}{\dimexpr\linewidth+3cm\relax}
-\begin{multicols}{2}\parindent0pt\relax
- \csb{etocaftercontentshook}\par
+\begin{multicols}{2}\parindent0pt\relax\setstretch{1}%
+ \csb{etocbeforetitlehook}\par
\csb{etocaftertitlehook}\par
+ \csb{etocaftercontentshook}\par
\csb{etocaftertochook}\par
- \csb{etocbeforetitlehook}\par
- \csb{etocdefaultlines}\par
- \csb{etocdepthtag.toc}\par
- \csb{etocdisplay}\par
- \csb{etocframedstyle}\par
- \csb{etocframed}\par
- \csb{etociffirst}\par
- \csb{etocifnumbered}\par
- \csb{etocignoredepthtags}\par
- \csb{etocignoretoctocdepth}\par
- \csb{etocimmediatedepthtag.toc}\par
- \csb{etocimmediatesettocdepth.toc}\par
- \csb{etocimmediatetoccontentsline}\par
- \csb{etocinline}\par
- \csb{etoclink}\par
- \csb{etoclocalframed}\par
- \csb{etoclocalmulticol}\par
- \csb{etoclocalruled}\par
- \csb{etocmulticolstyle}\par
+ \csb{etocsettocstyle}\par
+ \csb{etocclasstocstyle}\par
+ \csb{etocetoclocaltocstyle}\par
\csb{etocmulticol}\par
- \csb{etocname}\par
- \csb{etocnumber}\par
- \csb{etocobeydepthtags}\par\columnbreak
-\flushright
- \csb{etocobeytoctocdepth}\par
- \csb{etocpage}\par
- \csb{etocruledstyle}\par
+ \csb{etocframed}\par
\csb{etocruled}\par
- \csb{etocsetlevel}\par
- \csb{etocsetnexttocdepth}\par
- \csb{etocsetstyle}\par
- \csb{etocsettagdepth}\par
\csb{etocsettocdepth}\par
\csb{etocsettocdepth.toc}\par
- \csb{etocsettocstyle}\par
- \csb{etocskipfirstprefix}\par
- \csb{etocstandarddisplaystyle}\par
+ \csb{etocsetnexttocdepth}\par
+ \csb{etocdepthtag.toc}\par
+ \csb{etocsettagdepth}\par
+ \csb{etocobeydepthtags}\par
+ \csb{etocdefaultlines}\par
\csb{etocstandardlines}\par
- \csb{etocthelinkedname}\par
- \csb{etocthelinkednumber}\par
- \csb{etocthelinkedpage}\par
+ \csb{etoctoclines}\par
+ \csb{etocsetlevel}\par\columnbreak
+\flushright
+ \csb{etocsetstyle}\par
+ \csb{etocskipfirstprefix}\par
+ \csb{etocifnumbered}\par
+ \csb{etociffirst}\par
+ \csb{etoclink}\par
\csb{etocthelink}\par
+ \csb{etocname}\par
+ \csb{etocnumber}\par
+ \csb{etocpage}\par
\csb{etocthename}\par
\csb{etocthenumber}\par
\csb{etocthepage}\par
- \csb{etoctoccontentsline}\par
- \csb{etoctoclines}\par
+ \csb{etocthelinkedname}\par
+ \csb{etocthelinkednumber}\par
+ \csb{etocthelinkedpage}\par
+% \csb{etocdisplay}\par
+% \csb{etocframedstyle}\par
+% \csb{etocignoredepthtags}\par
+% \csb{etocignoretoctocdepth}\par
+% \csb{etocimmediatedepthtag.toc}\par
+% \csb{etocimmediatesettocdepth.toc}\par
+% \csb{etocimmediatetoccontentsline}\par
+% \csb{etocinline}\par
+% \csb{etoclocalframed}\par
+% \csb{etoclocalmulticol}\par
+% \csb{etoclocalruled}\par
+% \csb{etocmulticolstyle}\par
+% \csb{etocobeytoctocdepth}\par
+% \csb{etocruledstyle}\par
+% \csb{etoctoccontentsline}\par
+%\flushright
\csb{localtableofcontents}\par
\mbox{}\llap{\csb{localtableofcontentswithrelativedepth}}\par
+ \csb{locallistoffigures}\par
+ \csb{locallistoftables}\par
\csb{tableofcontents}\par
%\vspace{5\baselineskip}\hrule height 0pt
\end{multicols}
%\end{minipage}\par
-The above is not an exhaustive list of all the package user commands. And
-for legacy arbitrary reasons some of the more obscure commands are included
-here.
+
+{\footnotesize\setstretch{1}
+The above is not an exhaustive list of all the package user commands.
+For example, it does not include most of those added at \etocrelease{1.2}
+and which were listed in the previous section.\par
+}
\clearpage
-% 15 octobre, je teste les tags
-\etocdepthtag.toc {arbitrarily}
-\part{Arbitrarily many TOCs, and local ones too}
-% 13 octobre, ceci était une section avant
+
+\etocdepthtag.toc {styling}
+\part{The \etoc styling commands}
+\label{part:styling}
\thispartstats
+\etocsetstyle{section}
+{\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered
+ {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname{} (page \etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsection}
+{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]}
+{\normalfont \item}
+{\etocname{} (p.~\etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsubsection}
+{\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix}
+{\allowbreak\,--\,}
+{\etocname}
+{.\hfil\par\endgroup\pagebreak[3]}
+
+% 27 janvier 2013 22:30
+% je définis les macros (non protégées)
+% \etocthename, \etocthenumber, \etocthepage
+
+\etocruledstyle[1]{\etocfontminusone\color{green}%
+ \fboxrule1pt\fboxsep1ex
+ \framebox[\linewidth]
+ {\normalcolor\hss Contents of \autoref{part:styling}\hss}}
+
+\localtableofcontents \label{toc:part:styling}
+
+The two main commands \csb{etocsettocstyle} and \csb{etocsetstyle} can be used
+anywhere in the document. Typically one will render the main global TOC in
+one style and local tables of contents in another. So the commands to style
+the local tables of contents will be executed after the main \toc (if it is
+first in document) either by direct injection in the document source, or
+encapsulated in user commands defined in the preamble.
+
+All commands obey the scope limiting effect induced by \LaTeX{} environments
+or the core \TeX |\begingroup/\endgroup| (or braces |{...}|) constructs.
+
+\section{The \csbhyp{etocsettocstyle} and related commands}
+\label{sec:tocstyle}
+
+\begingroup
+\etocsettocstyle{}{}
+\etocstandardlines
+\DeclareTOCStyleEntry[numwidth=3em,indent=0em]{tocline}{subsection}
+\DeclareTOCStyleEntry[numwidth=3.5em,indent=3em]{tocline}{subsubsection}
+\localtableofcontents \label{toc:tocstyle}
+\endgroup
+
+
+
+\subsection{The \csbhyp{etocsettocstyle} command}
+\label{etocsettocstyle}
+
+The basics are explained in \autoref{etocsettocstyleintro}. Recall that the
+syntax is
+\centeredline{\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}} and
+here is a typical example of use:
+\begin{verbatim}
+\etocsettocstyle
+ {\section*{Local table of contents}}%
+ {}% don't do anything special after the toc contents
+\end{verbatim}
+
+The first argument to \csb{etocsettocstyle} can also contain instructions to
+mark the page headings. Or it could check to see if two-column mode is on,
+and switch to one-column style, and the \meta{after\_toc} part would then
+reenact the two-column mode.
+
+
+The commands to be described next \csb{etocmulticolstyle},
+\csb{etocruledstyle}, and \csb{etocframedstyle} all call \csb{etocsettocstyle}
+as a lower-level routine, to initiate a \texttt{multi\-cols} environment in
+\marg{before\_toc} and close it in \marg{after\_toc}.
+
+\subsubsection{The \csbhyp{etocarticlestyle}, \csbhyp{etocbookstyle},
+ and others commands}
+\label{etocarticlestyle}
+\label{etocarticlestylenomarks}
+\label{etocbookstyle}
+\label{etocbookstylenomarks}
+\label{etocreportstyle}
+\label{etocreportstylenomarks}
+
+These are the commands used internally by \etoc in compatibility mode
+depending on the document class. For example \csb{etocarticlestyle} instructs
+\etoc to use |\section*{\contentsname}| (with marks on the page) and
+\csb{etocbookstyle} says to use |\chapter*{\contentsname}|. It can prove
+useful to issue \csb{etocarticlestyle} for a \csa{localtableofcontents} inside
+a chapter, in |book| class and compatibility mode for the global TOC display
+style.
+
+Here is the current list:
+\begin{itemize}[nosep]
+\item \csb{etocarticlestyle}
+\item \csb{etocarticlestylenomarks}
+\item \csb{etocreportstyle}
+\item \csb{etocreportstylenomarks}
+\item \csb{etocbookstyle}
+\item \csb{etocbookstylenomarks}
+\item \csb{etocmemoirstyle}
+\item \csb{etocscrartclstyle}
+\item \csb{etocscrreprtstyle}
+\item \csb{etocscrbookstyle}
+\end{itemize}
+The command \csb{etocclasstocstyle} will adapt to the document class.
+One can not use the \ctanpkg{KOMA-script} related commands or the
+\ctanpkg{memoir} one in standard classes.
+
+
+\subsubsection{The \csbhyp{etocinline} and \csbhyp{etocdisplay} commands}
+\label{etocinline}
+\label{etocnopar}
+\label{etocdisplay}
+
+With \csb{etocinline}, or its synonym |\etocnopar|, the \localtoc command and
+its variants do \emph{not} first issue a |\par| to close the previous
+paragraph. Hence, the table of contents can be printed in an inline style; or,
+if used only for preparing some token list or macro, it will leave nothing in
+the token stream on execution.
+
+Issue \csb{etocdisplay} to return to the default situation that \localtoc and
+variants issue a |\par| to switch to vertical mode before typesetting the TOC
+title and contents.
+
+Here is an example of an \emph{inline} table of contents, which has only
+subsections and uses the |itemize*| environment from \ctanpkg{enumitem} for
+them. The code used is
+\begin{verbatim}
+And the output is:
+\begingroup
+ \etocglobaldefs
+ \etocsetstyle {subsection}
+ {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
+ {}
+ {\item [{\bfseries\etocnumber.}] \etocname\ (\emph{p. \etocpage })}
+ {\end{itemize*}.}%
+ \etocsetnexttocdepth {subsection}%
+ \etocsettocstyle {a clone of a local table of contents, originally defined in
+ \autoref{sec:tocstyle}, but here rendered completely
+ differently via an inline \ctanpkg{enumitem} list: }{}%
+ \etocinline\tableofcontents \ref{toc:tocstyle}
+\endgroup
+\end{verbatim}
+
+(observe that on executing the above there is no extra space after the colon
+beyond what is intended, and the current paragraph is simply continued)
+And the output is:
+\begingroup
+ \etocglobaldefs
+ \etocsetstyle {subsection}
+ {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
+ {}
+ {\item [{\bfseries\etocnumber.}] \etocname\ (\emph{p. \etocpage })}
+ {\end{itemize*}.}%
+ \etocsetnexttocdepth {subsection}%
+ \etocsettocstyle {a clone of a local table of contents, originally defined in
+ \autoref{sec:tocstyle}, but here rendered completely
+ differently via an inline \ctanpkg{enumitem} list: }{}%
+ \etocinline\tableofcontents \ref{toc:tocstyle}
+\endgroup
+
+It was needed to use \csb{etocglobaldefs} because the \csa{item} command,
+as modified by \ctanpkg{enumitem} closes a group, hence the meaning
+of \csb{etocname}, \csb{etocnumber} and \csb{etocpage} would have been lost
+after it.
+
+A more impressive example of an inline table of contents (containing the full
+contents of this document, which subsections rendered as page footnotes...) is
+to be found in \autoref{sec:crazy}.
+
+\subsection{The \csbhyp{etocmulticolstyle}, \csbhyp{etocmulticol},
+ and \csbhyp{etoclocalmulticol} commands}
+\label{etocmulticolstyle}
+\label{etocmulticol}
+\label{etoclocalmulticol}
+
+This is a command with one optional and one mandatory argument:
+\centeredline{\csb{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}}
+The
+\meta{number\_of\_columns} can go from 1 to 10 (it defaults to 2; if its
+value is 1, naturally no |multicols| environment is then created). The
+\meta{heading} will typically be some `vertical' material like:
+ \meta{heading} = |\section*|\marg{title}
+but one may also have horizontal material like |\fbox{Hello World}| (\etoc
+adds automatically a |\par| at the end of this ``heading'' argument to
+\csb{etocmulticolstyle}). Here is an example:
+\begin{verbatim}
+\etocmulticolstyle{\noindent\bfseries\Large
+ \leaders\hrule height1pt\hfill
+ \MakeUppercase{Table of Contents}}
+\localtableofcontents
+\end{verbatim}
+After \csb{etocmulticolstyle} all future \csa{tableofcontents} will use the
+specified style until modified by renewed usage of \csb{etocsettocstyle} or variants.
+
+A shortcut combining the style specification and the table of contents and not
+impacting the styles of later TOCs is:%
+%
+\centeredline{\csb{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}}
+%
+So the above example can be also obtained using:
+\begin{verbatim}
+\etoclocalmulticol{\noindent\bfseries\Large
+ \leaders\hrule height1pt\hfill
+ \MakeUppercase{Table of Contents}}
+\end{verbatim}
+%
+It has the advantage that the TOC styling as specified applies only to this
+sole local TOC.
+
+And there is also
+\csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading} for global TOC.
+
+\subsection{The \csbhyp{etoctocstyle} command}
+\label{etoctocstyle}
+
+\centeredline{\csb{etoctocstyle}\oarg{kind}\marg{number\_of\_columns}\marg{title}%
+}
+%
+is the exact equivalent of doing
+%
+\centeredline{%
+\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
+|{\kind*{|\itshape title\upshape|}}|}
+%
+where |kind| is one of |chapter|, |section|, . . . and defaults
+to |chapter| or |section| depending on the document class.
+
+As explained above one still has to issue \localtoc to typeset the TOC. And
+the styling, if not enclosed in a scope-limiting group or environment, applies
+to subsequent local TOCs.
+
+\subsubsection{The \csbhyp{etoctocstylewithmarks} command}
+\label{etoctocstylewithmarks}
+\label{etoctocstylewithmarksnouc}
+
+\centeredline{\csb{etoctocstylewithmarks}\oarg{kind}%
+ \marg{number\_of\_columns}\marg{title}\marg{mark}%
+ }
+%
+is the exact equivalent of doing
+%
+\centeredline
+{\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
+|{\kind*{|\itshape title \ttfamily\upshape\string\markboth%
+|{\MakeUppercase{|{\rmfamily\itshape mark}|}}}}|}
+%
+where |kind| is one of |chapter|, |section|, ... The
+actual display of the marks depends on the settings of the
+page style. There is variant \csb{etoctocstylewithmarksnouc}
+which does not uppercase.
+
+\paragraph{Do we really want paragraph entries in the TOC?}
+
+\paragraph{really?}
+
+\subsection{The \csbhyp{etocruledstyle}, \csbhyp{etocruled} and
+ \csbhyp{etoclocalruled} commands}
+\label{etocruledstyle}
+\label{etocruled}
+\label{etoclocalruled}
+
+The general format of \csb{etocruledstyle} is:
+%
+\centeredline{\csb{etocruledstyle}%
+ \oarg{number of columns}\marg{title of the toc}%
+}%
+\noindent
+The title is horizontal material (the |LR| mode of
+\emph{\LaTeX{}, a document preparation system}): if it
+does not fit on one line it should be put in a \csa{parbox} of
+a given width.
+The green frame for the heading of the table of contents at
+the \hyperref[toc:part:styling]{the start of this part} was obtained with:
+\begin{verbatim}
+\etocruledstyle[1]{\etocfontminusone\color{green}%
+ \fboxrule1pt\fboxsep1ex
+ \framebox[\linewidth]
+ {\normalcolor\hss Contents of this part\hss}}
+\localtableofcontents
+\end{verbatim}
+
+As a shortcut to set the style with \csb{etocruledstyle} and then issue a
+\localtoc, all inside a group so that future table of contents will not be
+affected, there is:
+%
+\centeredline{\csb{etoclocalruled}\oarg{number\_of\_columns}\marg{title}}
+%
+And there is also \csb{etocruled} for the global TOC.
+
+\subsection{The \csbhyp{etocframedstyle}, \csbhyp{etocframed}, and
+ \csbhyp{etoclocalframed} commands}
+\label{etocframedstyle}
+\label{etocframed}
+\label{etoclocalframed}
+
+Same mechanism:
+%
+\centeredline{\csb{etocframedstyle}\oarg{number\_of\_columns}\marg{title}}
+%
+and the accompanying shortcut:
+%
+\centeredline{\csb{etoclocalframed}\oarg{number\_of\_columns}\marg{title}}
+%
+The
+shortcut is used if one does not want to modify the style of the next
+TOCs (the other way is to put the whole thing inside braces or a
+|\begingroup...\endgroup|; there is also \csb{etocframed} for a
+global table of contents).
+
+The entire table of contents is framed. The title itself is not framed:
+if one wants a frame one should set it up inside the \meta{title}
+argument to \csb{etocframedstyle} or \csb{etocframed}. The colors for
+the background and for the components (top, left, right, bottom) of the
+border are specified via suitable |\renewcommand|'s (see
+\autoref{ssec:customdisplay}).
+
+A |minipage| is used, hence the produced table of contents isn't compatible
+with a page break. For allowing page breaks, use of the commands of
+\ctanpkg{mdframed} or \ctanpkg{tcolorbox} in the arguments of
+\csb{etocsettocstyle} is recommended.
+
+Examples in this document are on pages \pageref{toc:d},
+\pageref{toc:floating}, \pageref{toc:b}, and \pageref{toc:clone}.
+
+
+\subsection{Customizing the pre-defined toc display styles}
+\label{ssec:customdisplay}
+\label{etocabovetocskip}
+\label{etocbelowtocskip}
+\label{etoccolumnsep}
+\label{etocmulticolsep}
+\label{etocmulticolpretolerance}
+\label{etocmulticoltolerance}
+\label{etocdefaultnbcol}
+%\label{etocinnertopsep}% déjà défini
+\label{etoctoprule}
+\label{etoctoprulecolorcmd}
+\label{etocinnerleftsep}
+\label{etocinnerrightsep}
+\label{etocinnerbottomsep}
+\label{etocleftrule}
+\label{etocrightrule}
+\label{etocbottomrule}
+\label{etocleftrulecolorcmd}
+\label{etocrightrulecolorcmd}
+\label{etocbottomrulecolorcmd}
+\label{etocbkgcolorcmd}
+\label{etocframedmphook}
+
+We list the relevant macros, what they do should be legible from their
+names. Note that dimensions are stored in macros so are modifed using
+\csa{renewcommand}'s and not \csa{setlength}'s. And color related commands
+are not color definitions, they execute \csa{color}, and their effect gets canceled
+by re-defining them to do \csa{relax} or \csa{empty}.
+\begin{verbatim}
+\newcommand*\etocabovetocskip{3.5ex plus 1ex minus .2ex}
+\newcommand*\etocbelowtocskip{3.5ex plus 1ex minus .2ex}
+
+\newcommand*\etoccolumnsep{2em}
+\newcommand*\etocmulticolsep{0ex}
+\newcommand*\etocmulticolpretolerance{-1}
+\newcommand*\etocmulticoltolerance{200}
+\newcommand*\etocdefaultnbcol{2}
+\newcommand*\etocinnertopsep{2ex}
+\newcommand*\etoctoprule{\hrule}
+\newcommand*\etoctoprulecolorcmd{\relax}
+
+% for the framed style only:
+\newcommand*\etocinnerleftsep{2em}
+\newcommand*\etocinnerrightsep{2em}
+\newcommand*\etocinnerbottomsep{3.5ex}
+
+\newcommand*\etocleftrule{\vrule}
+\newcommand*\etocrightrule{\vrule}
+\newcommand*\etocbottomrule{\hrule}
+\newcommand*\etocleftrulecolorcmd{\relax}
+\newcommand*\etocrightrulecolorcmd{\relax}
+\newcommand*\etocbottomrulecolorcmd{\relax}
+
+\newcommand*\etocbkgcolorcmd{\relax}
+
+% hooks
+\newcommand\etocframedmphook{\relax}
+\end{verbatim}
+
+The \csa{etocframedmphook} is positioned immediately
+after the beginning of a minipage environment where the
+contents of the framed TOC are typeset.
+
+The \csa{...colorcmd} commands are initially set to expand to
+\csa{relax} (hence do not require package |color| or |xcolor|
+to be loaded). If one has modified a command such as
+\csa{etocbkgcolorcmd} to expand to a color command and wants
+to reset it to do nothing, one \emph{must} use
+|\renewcommand{\etocbkgcolorcmd}{\relax}| and not
+\csa{let}\csa{etocbkgcolorcmd}\csa{relax}.
+
+Regarding the dimensions of the top rule they can be specified
+in |ex|'s or |em|'s as in this example:
+\centeredline{|\renewcommand{\etoctoprule}{\hrule height 1ex}|}
+The package code is done in such a manner
+that it is the font size in instance at the end of typesetting
+the title argument to \csb{etocruled} or
+\csb{etocframed} which will be used for the meaning of the
+`1ex'. Of course also the other rule commands can have their
+dimensions in font relative units, but their values are
+decided on the basis of the font in effect just before the
+table of contents.
+
+The top and bottom rules do not have to be rules and can be
+horizontal \emph{leaders} (of a specified height) in the general
+\TeX{} sense. However the left and right rules are not
+used as (horizontal) leaders but as objects of a given specified
+width. Note that \emph{only} the Plain \TeX{} syntax for rules is
+accepted here.
+
+
+\subsection{Headings, titles, \csbhyp{etocoldpar}, \csbhyp{etocinnertopsep}}
+\label{etocinnertopsep}
+\label{etocoldpar}
+
+For \csb{etocmulticolstyle} the mandatory \meta{heading} argument can be
+either
+vertical mode material like |\section*{\emph{Table of Contents}}| or
+horizontal mode material like in the simple |\etocmulticolstyle{Hello World}|.
+
+No explicit |\par| or empty line can be inserted in the mandatory
+argument of \csb{etocmulticolstyle}, but \etoc provides \csb{etocoldpar}
+as a substitute: it does |\let\etocoldpar\par| before the |multicols|
+environment and inserts this |\etocoldpar|\footnote{this command
+ \csb{etocoldpar} (= working \csa{par} in the argument to
+ \csb{etocmulticolstyle}) is not related to the switch \csb{etocinline}
+ whose purpose is to tell \etoc not to do a \csa{par} before the table
+ of contents.} at the end of the heading, then does a vertical skip of
+value \csb{etocinnertopsep}. The command \csb{etocoldpar} can also be
+used explicitely if needed in the mandatory argument to
+\csb{etocmulticolstyle} (it is not allowed to insert an empty line
+in this argument).
+
+On the other hand the commands \csb{etocruledstyle} and
+\csb{etocframedstyle} expect an argument ``in LR mode'' (to use the
+terminology from \emph{LaTeX, a document preparation system}). This
+means that multiline titles are only possible if enclosing
+them inside something like a \csa{parbox}.
+
+An important dimension used by all three of \csb{etocmulticolstyle},
+\csb{etocruledstyle} and \csb{etocframedstyle} is
+\csb{etocinnertopsep}. It gives the amount of separation
+between the heading and the start of the contents. Its default
+value is |2ex| and it is changed with
+|\renewcommand*{\etocinnertopsep}|\marg{new\_value}, not with
+|\setlength|.
+
+
+\section{Starred variants and hooks}
+\label{tableofcontents*}
+\label{localtableofcontents*}
+\label{etocbeforetitlehook}
+\label{etocaftertitlehook}
+\label{etocaftercontentshook}
+\label{etocaftertochook}
+
+The \toc, \localtoc, \csb{etocmulticol}, and all their cousins have starred
+variants (the star must be before the other arguments). The non-starred
+variants execute the \csb{etocaftertitlehook}, whose default definition is to
+do nothing. The starred variants do not execute this hook.
+
+For example, imagine you are using |book| class and want \localtoc to use a
+section-like title, but unnumbered. Assuming the main \toc comes first in the
+document, you can insert this after it:
+\begin{verbatim}
+ \etocarticlestyle
+ \renewcommand{\etocaftertitlehook}{\addcontentsline{toc}{section}{\contentsname}}
+\end{verbatim}
+This configures the way \localtoc will behave (or \toc) from now on in the
+document.
+
+The first line tells essentially to use |\section*{\contentsname}|, and the
+second line says to insert the title in the |.toc| file itself (thus to be
+displayed by the main table of contents). Notice that \ctanpkg{hyperref} package will
+then automatically create suitable anchor and one should \emph{not} use
+explicitly \cs{phantomsection} here (it would let the anchor be located below
+not above the title).
+
+% problème avec \xspace
+With this set-up issuing \localtoc\unskip|*| will ignore the \csb{etocaftertitlehook}
+hence not send the local toc title to the |.toc| file. This mimicks the
+\ctanpkg{memoir} class behavior, and can also be used with it. For more on \ctanpkg{memoir}
+class with \etoc, see \autoref{ssec:memoir}.
+
+There are further hook macros:
+\csb{etocaftercontentshook}, \csb{etocbeforetitlehook} and
+\csb{etocaftertochook} which are initially defined to do nothing and can be
+used for some special effects. They are executed whether or not the table of
+contents command was starred.
+
+For example, the present document executed
+\begin{verbatim}
+\renewcommand{\etocbeforetitlehook}{\setstretch{1}}
+\end{verbatim}
+as it is globally using the \ctanpkg{setspace} command \csa{onehalfspacing}.
+Not using \csa{singlespacing} in the hook as it does a systematic vertical
+skip of one baseline, which is unwanted in our usage.
+
+\begin{framed}
+ In recent years, the \LaTeX{} kernel has added a general ``hook'' mechanism
+ with a user interface of the type |\AddToHook{...}{...}|.
+
+ The \etoc macros with `hook' ending their names are much simpler things
+ which are supposed to be manipulated only via \csa{renewcommand} or
+ \csa{def} direct overwrites.
+
+ In future, and to the extent the author has time for that addition, with its
+ costly documentation updates collaterals, and thoughts about backward
+ compatibility, \etoc should arguably tap into the general tools provided by
+ recent \LaTeX{} kernels.
+\end{framed}
+
+\section{The \csbhyp{etocsetstyle} and related commands}
+\label{sec:linestyles}
+\label{etocsetstyle}
+\label{etocname}
+\label{etocpage}
+
+\begingroup
\etocsettocstyle{}{}
+\DeclareTOCStyleEntry[numwidth=3.2em,indent=0em]{tocline}{subsection}
+\etocstandardlines
+\localtableofcontents \label{toc:linestyles}
+\endgroup
+
+Let us explain how \etoc was used to produce the table of contents displayed
+at the beginning of this \autoref{part:styling}. This is a local table of
+contents, and we used the command \localtoc.
+
+
+The line styles were (essentially) obtained in the following manner:%
+\footnote{the present document has {\ttfamily\string\renewcommand\string{%
+ \string\familydefault\string}\string{\string\sfdefault\string}} in its
+ preamble, hence \csa{normalfont} switches to the |sans| typeface; so in the
+ section line-style, I wrote \csa{rmfamily} instead.}
+
+\begingroup\small
+\begin{filecontentshere}{etocsnippet-\snippetno.tex}
+\etocsetstyle{section}
+{\begin{enumerate}}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname{} (page \etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsection}
+{\begin{enumerate}}
+{\normalfont\item}
+{\etocname{} (p.~\etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsubsection}
+{\par\nobreak\begingroup\normalfont
+ \footnotesize\itshape\etocskipfirstprefix}
+{\allowbreak\,--\,}
+{\etocname}
+{.\hfil\par\endgroup\pagebreak[3]}
+\end{filecontentshere}
+\endgroup
+% Note 2023/02/22: pour une raison que je ne vais pas chercher à comprendre
+% le etocsnippet-01 était mis du mauvais côté (dans la marge intérieure, pas
+% extérieure) lorsque ce \marginattach était avant le \endgroup
+\marginattach
+
+These provisory style definitions rely on the automatic
+numbering generated by the |enumerate| environments but it is
+much better to use the further command \csb{etocnumber} inside
+the item label, which gives the real thing. The improved
+definitions will thus be explained later.
+
+With this style, one would have
+to be imaginative to design something then for paragraph and
+subparagraph entries! perhaps as superscripts? Well, usually
+one does not need paragraphs and subparagraphs numbered and
+listed in the TOC, so our putative user here chose a design
+where no provision is made for them and added the definitive:
+\begin{verbatim}
+\etocsetstyle{paragraph}{}{}{}{}
+\etocsetstyle{subparagraph}{}{}{}{}
+\end{verbatim}
+This is also the situation with the default package line styles!
+
+Each \csb{etocsetstyle} command has five mandatory arguments:
+%
+\centeredline{\csb{etocsetstyle}\color{blue}\marg{levelname}\marg{start}\marg{prefix}\marg{contents}\marg{finish}}
+%
+The initially recognized \meta{levelname}'s are the sectioning
+levels of the standard document classes: from \emph{part} (or
+\emph{book} which is used by the \ctanpkg{memoir} class) down to
+\emph{subparagraph}.
+
+The \meta{start} code is executed when a toc entry of that level is
+encountered and the previous one was at a higher level. The
+\meta{finish} code is executed when one again encounters a higher
+level toc entry. In the meantime all entries for that level are
+typeset by executing first the \meta{prefix} code and then the
+\meta{contents} code.
+
+The (robust) commands \csb{etocname}, \csb{etocnumber} and \csb{etocpage} are
+provided for use inside the \meta{prefix} and \meta{contents} parts of the
+\csb{etocsetstyle} specification. They represent of course, the name, number,
+and page number of the corresponding toc entry. If package \ctanpkg{hyperref} is
+active in the document and has added hyperlinks to the TOC data, then these
+links are kept in the commands \csb{etocname}, \csb{etocnumber} and
+\csb{etocpage} (this last one will have a link only if \ctanpkg{hyperref} was passed
+either option \emph{linktoc=all} or option \emph{linktoc=page}.)%
+%
+\footnote{As expected, in case of \emph{linktoc=page}, only \csb{etocpage} is
+an hyperlink, not \csb{etocname} nor \csb{etocnumber}. See \csb{etoclink} on
+how to create hyperlinks with the entry target.}
+%
+In accordance with the \ctanpkg{hyperref} native behavior, no
+link gets incorporated into \csb{etocpage} if the page number is empty.
+
+\subsection{The \csbhyp{etocskipfirstprefix} and \csbhyp{etociffirst} commands}
+\label{etocskipfirstprefix}
+\label{etociffirst}
+\label{etocxiffirst}
+
+The chosen |subsubsection| style made use of the command
+\csb{etocskipfirstprefix}, which instructs \etoc to \emph{not} use
+for the first item the specified \meta{prefix} code.
+
+
+The command \csb{etociffirst}\marg{YES CODE}\marg{NO CODE}
+is a more flexible way to customize the \meta{prefix}
+(and \meta{contents}) specifications. It executes the \meta{YES
+CODE} branch if this is the first unit at that level (inside a
+lower level) and the \meta{NO CODE} if not. This is a robust
+command which survives to expansion (for example in an |enumitem| label).
+
+The variant \csb{etocxiffirst} does the same, but is expandable.
+
+
+\subsection{The \csbhyp{etocnumber} command}
+\label{etocnumber}
+
+So far, our specifications would use the numbering generated
+by the |enumerate| environments, but of course we generally want
+the actual numbers as found in the |.toc| file. This is
+available via the \csb{etocnumber} command. To get the labels
+in the |enumerate| list to use it we can proceed with the
+syntax {\ttfamily label=\char32} from the package |enumitem|:
+\begin{verbatim}
+\etocsetstyle{section}
+{\begin{enumerate}[label=\etocnumber]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname{} (page \etocpage)}
+{\end{enumerate}}
+\end{verbatim}
+Rather than just \csb{etocnumber} we then used something like
+|\fbox{\etocnumber}|. Note that \csb{etocnumber} is a robust
+command which explains why it can be used inside the label specification
+without needing an added |\protect|.
+
+
+\subsection{The \csbhyp{etocifnumbered} switch}
+\label{etocifnumbered}
+\label{etocxifnumbered}
+
+The \csa{fbox} would give an unaesthetic result in the case of
+an unnumbered section (which ended up in the table of
+contents via an \csa{addcontentsline} command).\footnote{as
+ seen we use \csa{fcolorbox} rather than \csa{fbox}. Due
+ to some redefinition made by package |xcolor|, had we used
+ \csa{fbox} (and not used \ctanpkg{hyperref}) we would have needed
+ \csa{protect}\csa{fbox}.}
+
+The \csb{etocifnumbered}\marg{A}\marg{B} command executes
+\meta{A} if the number exists, and \meta{B} if not. So we use
+it in the code which was finally chosen for the |section| level:
+\begin{verbatim}
+\etocsetstyle{section}
+{\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered
+ {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname{} (page \etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsection}
+{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]}
+{\normalfont \item}
+{\etocname{} (p.~\etocpage)}
+{\end{enumerate}}
+\end{verbatim}
+
+If we had changed only the |section| level, and not the
+|subsection| level, an error on compilation would have occurred
+because the package style for subsections expects to start `in
+vertical mode'. An additional \csa{par} token in the
+\meta{contents} part of the |section| level would have fixed
+this: |{...(page \etocpage)\par}|.
+
+The command \csb{etocifnumbered} is robust; \csb{etocxifnumbered}
+has the same effect but is expandable.
+
+
+\subsection{The \csbhyp{etocthename}, \csbhyp{etocthenumber}, and
+\csbhyp{etocthepage} commands}
+\label{etocthename}
+\label{etocthenumber}
+\label{etocthepage}
+
+It is sometimes desirable to have access to the name, number and page
+number without the hyperref link data: something similar to the starred
+variant of the \csa{ref} command, when package \ctanpkg{hyperref} is used. For
+example one may wish to use the unit or page number in some kind of
+numeric context, or change its formatting. This is provided by
+\csb{etocthename}, \csb{etocthenumber}, and \csb{etocthepage}.
+
+These commands are not ``robust'', in fact it is expected they will be often
+submitted to one expansion step so that their contents can easily be recovered
+and stored perhaps for delayed usage.
+
+\subsection{The \csbhyp{etoclink} command}
+\label{etoclink}
+
+The command \csb{etoclink}\marg{text} can be used in the line style
+specifications in a manner analogous to \csb{etocname}, \csb{etocnumber} and
+\csb{etocpage}. It creates a link (if \ctanpkg{hyperref} is present%
+%
+\footnote{Prior to \etocrelease{1.1a}, no such link was added if the \texttt{.toc}
+ file entry was encountered
+ with \ctanpkg{hyperref}'s option \texttt{linktoc} set to \texttt{none}.})
+%
+whose target is the corresponding document unit and
+whose name is the given \meta{text} mandatory argument.
+
+Hence |\etoclink{\etocthename}| is under default conditions of \ctanpkg{hyperref} like
+the original \csb{etocname}, because the latter is already hyperlinked. Under
+\emph{linktoc=page} context |\etoclink{\etocthename}| adds the hyperlink which
+is missing from \csb{etocname}. Similarly under the default \ctanpkg{hyperref}
+condition (i.e.\@ \emph{linktoc=section}) \csb{etocpage} is not an hyperlink, but one
+can use |\etoclink{\etocthepage}|.
+
+The command \csb{etoclink} is robust.
+
+% Since |etoc 1.08j| it contains the link
+% destination in an already expanded form, so for example can be used even after
+% a |&| in a tabular construction, if \csb{etocglobaldefs} was issued.
+
+
+
+
+\makeatletter\scr@activate@xsection{1}\makeatother
+% [] goes to head but {} to toc
+
+% What would really be useful is an option for the length of {} to be measured
+% and opt for [] only if does not fit on one header line
+\subsection[The \csbhyp{etocthelinkedname} et al.\protect\@{} commands]
+ {The \csbhyp{etocthelinkedname}, \csbhyp{etocthelinkednumber},
+ \csbhyp{etocthelinkedpage} and \csbhyp{etocthelink} commands}
+\label{etocthelinkedname}
+\label{etocthelinkednumber}
+\label{etocthelinkedpage}
+\label{etocthelink}
+
+\makeatletter\scr@activate@xsection{0}\makeatother
+
+The meanings of these commands
+can be stored for delayed usage. For example this is
+done in the \hyperref[tocastree]{examples with trees}.
+
+There has been a \textbf{breaking change} at \etocrelease{1.1a}. Here is the behavior
+\emph{prior} to this release:
+\begin{itemize}[noitemsep]
+\item \csb{etocthelinkedname} and \csb{etocthelinkednumber} were hyperlinks
+ only if \ctanpkg{hyperref} was configured via |linktoc=all| or
+ |linktoc=section| (the default),
+\item \csb{etocthelinkedpage} was an hyperlink only if \ctanpkg{hyperref} was
+ configured via |linktoc=all| or |linktoc=page| and the page number was not empty.
+\end{itemize}
+This behavior was coherent with the commands \csb{etocname}, \csb{etocnumber},
+and \csb{etocpage} being the robust variants of \csb{etocthelinkedname},
+\csb{etocthelinkednumber}, and \csb{etocthelinkedpage}.
+
+At \etocrelease{1.1a} it was decided that the commands should match their denominations.%
+%
+\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.}
+%
+So they are now \emph{always} hyperlinks independently of |linktoc| \ctanpkg{hyperref}
+option (\csb{etocthelinkedpage} has no hyperlink if the page number is empty,
+to match \ctanpkg{hyperref} behavior):
+\begin{itemize}[noitemsep]
+\item \csb{etocthelinkedname} and \csb{etocthelinkednumber} and
+ \csb{etocthelinkedpage} are always (in presence of \ctanpkg{hyperref})
+ hyperlinks (for \csb{etocthelinkedpage} the page number must not be empty).
+\end{itemize}
+
+
+A further command is provided: \csb{etocthelink}, which wraps%
+%
+\footnote{Prior to \etocrelease{1.1a}, there was a link added only if \ctanpkg{hyperref} option \texttt{linktoc} was not \texttt{none}.}
+%
+an hyperlink around its argument: |\etocthelink|\marg{foo} hyperlinks an
+arbitrary text \meta{foo} to the target sectioning unit in the document.
+The command \csb{etoclink} is its robust variant.
+
+
+
+\subsection{The \csbhyp{etocsetlevel} command}
+\label{etocsetlevel}
+
+One
+can inform \etoc of a level to associate to a given sectioning
+command with \csb{etocsetlevel}. For example:
+\begin{verbatim}
+\etocsetlevel{cell}{0}
+\etocsetlevel{molecule}{1}
+\etocsetlevel{atom}{2}
+\etocsetlevel{nucleus}{3}
+\end{verbatim}
+In compatibility mode, it will be assumed that the commands |\l@cell|,
+|\l@molecule|, ..., have been defined somewhere either by the user or a class:
+doing only |\etocsetlevel| is not enough for the corresponding level to work
+out-of-the-box in compatibility mode.
+
+However, if no table of contents is typeset in compatibility mode, then all that
+matters is that the various line styles have been set. If, for example
+|section| is at level |1|, then there is no need to do some
+\csb{etocsetstyle}|{molecule}{..}{..}{..}{..}| after
+\csb{etocsetlevel}|{molecule}{1}| if
+\csb{etocsetstyle}|{section}{..}{..}{..}{..}| has already been done (and it has
+been done by the package itself in its definition of its own line styles).
+
+The accepted levels run from |-2| to |6| inclusive. Anything else is
+mapped to |6|, which is a dummy level, never displayed. The package
+does:
+\begin{verbatim}
+\etocsetlevel{book}{-2}
+\etocsetlevel{part}{-1}
+\etocsetlevel{chapter}{0}
+\etocsetlevel{appendix}{0}% or 1 if document has no \chapter
+\etocsetlevel{section}{1}
+\etocsetlevel{subsection}{2}
+\etocsetlevel{subsubsection}{3}
+\etocsetlevel{paragraph}{4}
+\etocsetlevel{subparagraph}{5}
+\end{verbatim}
+\etoc own custom styles are activated by \csb{etocdefaultlines}.
+
+These level assignments can be modified at anytime. See
+\autoref{part:surprising} for various applications of this technique.
+
+
+
+\subsection{Using \texttt{enumerate} or \texttt{itemize} environments for
+ line styles}
+
+The code for the line styles of the \localtoc of this part was already
+reproduced in \autoref{sec:linestyles}. It is very simple and uses
+\texttt{enumerate} environments for sections and subsections, then an
+``inline'' paragraph style for subsubsection titles.
+
+Actually, the very first version of \etoc from 2012 was originally motivated
+by the aim to do exactly this kind of things, which necessitates to be aware
+of when for example after a series of subsections, a section line appears in
+the |.toc| file.%
+%
+\footnote{At the source code level, the legacy method dating back to the
+ origins in 2012 was replaced
+ by a completely new one at release \etocrelease{1.2}.}
+%
+Indeed, this should trigger the emission of an |\end{enumerate}|.
+
+With the \marg{start} and \marg{finish} arguments of \csb{etocsetstyle}, \etoc
+provides an easy systematic interface to accomplish this kind of task.
+
+But there are some limitations to the use of list environments for typesetting
+TOCs. One of them is intrinsic to the scope limitations created by the groups
+associated to the environments: the |.toc| file may contain, besides the
+information to be typeset in the TOCs, some other commands, such as language
+changing commands from \ctanpkg{babel}, and some such commands do not expect
+to see their scope limited in this way by the presence of an environment
+(which will not be visible in the |.toc| file itself but enacted dynamically
+by the user-specified line styles).
+
+The built-in ``default line styles'' provided with \etoc (see
+\autoref{sec:custom}) do not make use of environments. Actually, in this
+user manual, only the \hyperref[toc:part:styling]{table of contents} at the start of this
+\autoref{part:styling}, the \autoref{toc:allsubsections} (which is a TOC!) and
+examples from \autoref{etocthelink} have their line styles expressed in terms
+of \texttt{enumerate} or \texttt{itemize} environments.
+
+\subsection{The\csbhyp{etocglobaldefs} and \csbhyp{etoclocaldefs} commands}
+\label{etocglobaldefs}
+\label{etoclocaldefs}
+
+In \LaTeX{} the meaning of a command defined via |\newcommand\foo{...}| inside
+an environment (or group) vanishes from \TeX's memory on exit from this
+environment (or group). At times however it is needed to make definitions with
+global scope, for this \TeX{} has the primitive prefix |\global|.
+
+By default \etoc's definitions of \csb{etocname} etc... are local. This causes
+problems in certain contexts such as TOC as tables (\autoref{sec:tocastable},
+\autoref{ssec:tocastableold}) and also with |enumitem| \emph{inline} variants
+of its standard environments, because the command |\item| then closes a group
+(see \autoref{etocthelink}).
+
+After \csb{etocglobaldefs} has been issued, the \csb{etocname},
+\csb{etocnumber} and \csb{etocpage} will be defined during execution of \toc
+and \localtoc with global scope. For normal use this is not necessary. It
+does not hurt either to activate it systematically.
+
+To return to the default, which lets \etoc only define them locally to the
+context in place where the \csa{contentsline} is encountered, execute
+\csb{etoclocaldefs}. Both \csb{etocglobaldefs} and \csb{etoclocaldefs} have
+an effect only locally to the environment or group where they are used.
+
+\section{The \etoc fall-back line styles}
+\label{sec:custom}
+
+\etocdefaultlines
+\renewcommand{\etoctoprule}{\hrule height2pt depth0pt}
+\renewcommand{\etoctoprulecolorcmd}{\color{red}}
+
+\etocruledstyle{\normalfont\normalsize\rmfamily\fboxrule1pt\color{red}%
+ \fbox{\parbox{.8\linewidth}{\centering\normalcolor This is a table of
+ contents for the (few) subsections of this section. It carries the label |toc:c|}}}
+
+\localtableofcontents \label{toc:c}
+
+\subsection{A demo of a TOC using \csbhyp{etocdefaultlines}}
+\label{etocdefaultlines}
+
+These line styles were written at an early stage in the
+development of the package; although the next section explains how
+to customize the font choicess or vertical spaces, etc\dots, used
+by these line styles, most other changes would require copying
+them from the sources and modify them directly. Admittedly they
+have been written at a rather scary low-\TeX{} level, and will not
+serve as a very friendly starting point.
+
+Activating their use is done via \csb{etocdefaultlines}, or
+\csb{etoctoclines} if the line styles have not been modified with
+\csb{etocsetstyle}. Sections and sub-sections are printed in
+essentially the same manner, except that the leading for
+sub-sections is a bit smaller (with document classes lacking a
+\csa{chapter} command, the sections are printed in bold typeface;
+this is the case in the present document). Sub-sub-sections are
+printed inline, in one paragraph, with no numbers or page numbers.
+This style was designed and tested with documents having lots of
+sub-sub-sections, and should be used on a two-column layout: it
+provides (only in that situation with many sub-sub-sections) a
+more compact presentation than what is achieved by the \LaTeX{}
+default.\footnote{and there will never be a Part or Chapter entry
+ alone at the bottom of a column or page (except if it has no
+ sub-unit).} On the other hand, used with a one-column layout,
+and with few sub-sub-sections, the style is a bit more spread out
+vertically than the \LaTeX{} default, sub-sections are not
+visually much different from sections (especially for document
+classes with a \csa{chapter} command), so the result is less
+hierarchical in appearance than in the \LaTeX{} default.
+
+Let us typeset the global table of contents of the present document as if it
+had been done with a class having the \csa{chapter} command: we will print
+sections as chapters, and subsections as sections. We use \csb{etocsetlevel}
+for that, and also we need to change the font style of ``sections'' (which in
+truth are our subsections) to use not the bold but the medium series; we
+modify the \csb{etocfontone} command for that. Also we use dot leaders which
+are less spread out than in the package default.
+
+
+\begin{filecontentshere}{etocsnippet-\snippetno.tex}
+\etocruledstyle[2]{\normalfont\normalsize\rmfamily\itshape
+ \fbox{\parbox{.6\linewidth}{
+ \leftskip 0pt plus .5fil
+ \rightskip 0pt plus -.5fil
+ \parfillskip 0pt plus 1fil This is the global table of
+ contents on two columns, using \etoc default line styles, but with
+ sections as chapters, and subsections as sections.
+ }}}
+\etocdefaultlines
+\etocsetnexttocdepth{1}
+\begingroup
+\etocsetlevel{section}{0}
+\etocsetlevel{subsection}{1}
+\renewcommand*{\etocfontone}{\normalfont \normalsize}
+\renewcommand*{\etoctoclineleaders}
+ {\hbox{\normalfont\normalsize\hbox to 1ex {\hss.\hss}}}
+\sloppy
+\tableofcontents
+\endgroup
+\end{filecontentshere}
+\marginattach
+
+\filecontentsexec\filecontentsheremacro
+
+\subsection{Customizing the \etoc pre-defined line styles}
+\label{etocfontminustwo}
+\label{etocfontminusone}
+\label{etocfontzero}
+\label{etocfontone}
+\label{etocfonttwo}
+\label{etocfontthree}
+\label{etocsepminustwo}
+\label{etocsepminusone}
+\label{etocsepzero}
+\label{etocsepone}
+\label{etocseptwo}
+\label{etocsepthree}
+\label{etocminustwoleftmargin}
+\label{etocminustworightmargin}
+\label{etocminusoneleftmargin}
+\label{etocminusonerightmargin}
+\label{etocbaselinespreadminustwo}
+\label{etocbaselinespreadminusone}
+\label{etocbaselinespreadzero}
+\label{etocbaselinespreadone}
+\label{etocbaselinespreadtwo}
+\label{etocbaselinespreadthree}
+\label{etoctoclineleaders}
+\label{etocabbrevpagename}
+\label{etocpartname}
+\label{etocbookname}
+
+
+We will simply list the relevant commands as defined in the
+package. Customizing them goes through suitable
+\csa{renewcommand}s:
+\begin{verbatim}
+\newcommand*\etocfontminustwo{\normalfont \LARGE \bfseries}
+\newcommand*\etocfontminusone{\normalfont \large \bfseries}
+\newcommand*\etocfontzero{\normalfont \large \bfseries}
+\newcommand*\etocfontone{\normalfont \normalsize \bfseries}
+% (in classes with chapter, \etocfontone does not do \bfseries)
+\newcommand*\etocfonttwo{\normalfont \normalsize}
+\newcommand*\etocfontthree{\normalfont \footnotesize}
+
+\newcommand*\etocsepminustwo{4ex plus .5ex minus .5ex}
+\newcommand*\etocsepminusone{4ex plus .5ex minus .5ex}
+\newcommand*\etocsepzero{2.5ex plus .4ex minus .4ex}
+\newcommand*\etocsepone{1.5ex plus .3ex minus .3ex}
+\newcommand*\etocseptwo{.5ex plus .1ex minus .1ex}
+\newcommand*\etocsepthree{.25ex plus .05ex minus .05ex}
+
+\newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil}
+\newcommand*\etocminustworightmargin{1.5em plus -0.5fil}
+\newcommand*\etocminusoneleftmargin{1em}
+\newcommand*\etocminusonerightmargin{1em}
+
+\newcommand*\etocbaselinespreadminustwo{1}
+\newcommand*\etocbaselinespreadminusone{1}
+\newcommand*\etocbaselinespreadzero{1}
+\newcommand*\etocbaselinespreadone{1}
+\newcommand*\etocbaselinespreadtwo{1}
+\newcommand*\etocbaselinespreadthree{.9}
+\newcommand*\etoctoclineleaders
+ {\hbox{\normalfont\normalsize\hbox to 2ex {\hss.\hss}}}
+\newcommand*\etocabbrevpagename{p.~} % initial of "page"
+\newcommand*\etocpartname{Part} % prior to 1.08b, was \partname
+% but this didn't make sense e.g. with babel+frenchb whose \frenchpartname
+% takes into account the value of the part counter.
+\newcommand*\etocbookname{Book} % to be modified according to language
+\end{verbatim}
+
+No customizing of the standard line styles is possible from
+within \etoc. As already explained, when
+\csb{etocstandardlines} has been issued, the package just makes
+itself very discrete and acts only at the global level, and
+the TOC entries are (hopefully) formatted as would have
+happened in the absence of \etoc.\footnote{with the
+ \ctanpkg{KOMA-script} classes, we noticed that
+ \csb{etocclasstocstyle} was apparently needed for the
+ KOMA options |toc=left| to be active at the level of the line entries.}
+
+
+The \csb{etocstandardlines} compatibility mode will work also with
+sectioning commands made known to \etoc via \csb{etocsetlevel},
+under the condition of course that these sectioning commands
+are accompanied with all the relevant definitions for
+typesetting toc entries in the \LaTeX{} default manner
+(existence of the macros \csa{l@something} . . .).
+
+Using the command \csb{etocsetstyle}, be it in the preamble or
+in the body of the document, has the secondary effect of
+switching off the compatibility mode.
+
+\section{Summary of the main styling commands}
+
+\subsection{Setting up local styles}
+
+\hbox{\color{green}\fboxrule1pt\fboxsep1em
+\setbox0\hbox{\csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}, \csb{etoclink}\marg{linkname}}%
+\framebox[\linewidth][c]
+{\vbox{\hsize\wd0\normalcolor\noindent
+\csb{etocsetstyle}\marg{levelname}%
+ \marg{start}\marg{prefix}\marg{contents}\marg{finish}\\
+\csb{etocname}, \csb{etocnumber}, \csb{etocpage},
+\csb{etocifnumbered}\marg{A}\marg{B}\\
+\csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}, \csb{etoclink}\marg{linkname}
+}}}
+
+\subsection{Setting up toc display styles}
+
+\medskip
+\hbox{\color{green}\fboxrule1pt\fboxsep1em
+\setbox0\hbox{\csb{etoctocstylewithmarksnouc}\oarg{kind}%
+\marg{number\_of\_columns}\marg{title}\marg{mark}}%
+\framebox[\linewidth][c]
+{\vbox{\hsize\wd0
+\normalcolor\noindent
+\csb{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}\\
+\csb{etoctocstyle}\oarg{kind}\marg{number\_of\_columns}\marg{title}\\
+\csb{etoctocstylewithmarks}\oarg{kind}\marg{number\_of\_columns}%
+\marg{title}\marg{mark}\\
+\csb{etoctocstylewithmarksnouc}\oarg{kind}\marg{number\_of\_columns}%
+\marg{title}\marg{mark}\\
+\csb{etocruledstyle}\oarg{number\_of\_columns}\marg{title}\\
+\csb{etocframedstyle}\oarg{number\_of\_columns}\marg{title}\\
+\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}}}
+
+\subsection{Displaying tables of contents}
+
+
+\medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
+ \setbox0\hbox{\csb{etocname}, \csb{etocnumber},
+ \csb{etocpage}, \csb{etocifnumbered}\marg{A}\marg{B}}%
+ \framebox[\linewidth][c]
+ {\vbox{\hsize\wd0\normalcolor\noindent
+ \toc\\
+ \localtoc\\
+ \csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading}\\
+ \csb{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}\\
+ \csb{etocruled}\oarg{number\_of\_columns}\marg{title}\\
+ \csb{etoclocalruled}\oarg{number\_of\_columns}\marg{title}\\
+ \csb{etocframed}\oarg{number\_of\_columns}\marg{title}\\
+ \csb{etoclocalframed}\oarg{number\_of\_columns}\marg{title}\\
+ \hbox{}{\itshape\ttfamily\ \ \ \ and their starred variants}
+ }}}
+
+\subsection{Labels and references}
+\label{ssec:labelref}
+
+The commands (starred or not) to actually display the table of contents
+can be followed with optional labels or references:\par
+
+\medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
+ \setbox0\hbox{\csb{etocname}, \csb{etocnumber},
+ \csb{etocpage}, \csb{etocifnumbered}\marg{A}\marg{B}}%
+ \framebox[\linewidth][c]
+ {\vbox{\hsize\wd0\normalcolor\noindent
+ \toc \csa{label}|\{toc:here\}|\\
+ \toc \csa{ref}|\{toc:far\}| \\
+ \toc \csa{label}|\{toc:here\}| \csa{ref}|\{toc:far\}| \\
+ \localtoc \csa{label}|\{toc:here\}|\\
+ \localtoc \csa{ref}|\{toc:far\}| \\
+ \localtoc \csa{label}|\{toc:here\}| \csa{ref}|\{toc:far\}| \\
+ \hbox{}{\itshape\ttfamily\ \ \ \ similarly with\ }%
+ \csb{etocmulticol}{\itshape\ttfamily\ etc . . . }
+ }}}
+
+
+\medskip
+
+\localtoc \csa{ref}|{toc:far}| acts the same as \toc
+\csa{ref}|{toc:far}|.
+% <--- car à 1.2 cela permet d'éviter une page quasi vide...
+When re-displaying another toc, only its contents are transferred:
+both the line styles and the toc display style are the ones
+currently defined, not the ones from the cloned toc.
+
+
+\clearpage
+\etocdepthtag.toc {control}
+\part{Control of contents}
+\label{part:control}
+
+\thispartstats
+
+\etocsettocstyle{}{}% maybe I should use \etocclasstocstyle here ?
+ % but then I probably need some extra KOMA stuff to
+ % counteract the setspace effet
+\begingroup
+\DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
+\DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection}
+\DeclareTOCStyleEntry[numwidth=3em,indent=4.5em]{tocline}{subsubsection}
\etocstandardlines
\localtableofcontents
+\endgroup
-\section{The \csbhyp{tableofcontents}, \csbhyp{localtableofcontents} and
- \csbhyp{localtableofcontentswithrelativedepths} commands}
+\section[The \csbhyp{tableofcontents} et al. commands]{The
+ \csbhyp{tableofcontents}, \csbhyp{localtableofcontents} and
+ \csbhyp{localtableofcontentswithrelativedepths} commands}
\label{tableofcontents}
\label{etoctableofcontents}
\label{localtableofcontents}
\label{localtableofcontentswithrelativedepth}
+\label{etockeeporiginaltableofcontents}
\begin{description}
\item[\toc] can be used arbitrarily many times in the document. Styling either
globally the TOC or its individual entries is customizable at any time in
the document.
- \csb{etoctableofcontents} is a synonym to \etoc's \toc. See
- footnote\footref{etockeeporiginaltableofcontents} on page \pageref{etockeeporiginaltableofcontents}.
+ \csb{etoctableofcontents} is a synonym to \etoc's \toc. The \toc command
+ reverts to its non-\etoc definition if \csa{etockeeporiginaltableofcontents}
+ is issued after loading the package.
+%
+\footnote{%
+ This
+ was added to fix a compatiblity issue with \ctanpkg{listings}'s
+ \texttt{\string\lstlistoflistings}, as it needs the
+ \texttt{\string\tableofcontents} macro to keep its original meaning.}
+
\item[\localtoc] will print local tables of
contents: \emph{i.e.} all sections and sub-units inside a
given chapter, or all subsubsections and lower inside a given
@@ -2188,7 +3445,11 @@ subsection, etc... (see also \csb{etocsetnexttocdepth}).%
great flexibility to achieve special effects, all done using only a single
auxiliary file, the standard |.toc| file.}
%
-\item[\localtocwrdp\marg{number}] can be used to override the document or
+\item[\localtocwrdp\marg{number}]
+%
+\mbox{}\footnote{Thanks to Tony \textsc{Roberts} for feature request.}
+%
+ can be used to override the document or
current tocdepth setting (see \autoref{sec:tocdepth} for a discussion of
tocdepth) to become relative to where the local TOC originates. For example,
assuming the default numeric level assignments to standard sectioning units
@@ -2201,65 +3462,67 @@ subsection, etc... (see also \csb{etocsetnexttocdepth}).%
of the |tocdepth| counter at this position in the document. If the numeric
argument had been |3|, the local TOC would have displayed also paragraphs.
If the section had been a chapter, and again for a relative tocdepth of |2|,
- the taken into account levels would have been sections and subsections.%
-%
-\footnote{The situation may be more complex, as the |.toc| file itself may
- well contain \texttt{\string\setcounter\{tocdepth\}\{...\}} commands. This
- is not recommended pratice with \etoc. See the discussion of
- \csb{etocsettocdepth.toc} and \csb{etocdepthtag.toc} for more on this.}
+ the taken into account levels would have been sections and subsections.
\end{description}
-The macro \localtocwrdp is \textbf{new with |1.09|}.%
-%
-\footnote{Thanks to Tony \textsc{Roberts} for feature request.}
-%
-
\section{Labeling and reusing elsewhere}
\label{sec:labeling}
-\etoc allows the labeling of a TOC with (for example)
-\csa{label\{toc:A\}} and will redisplay it elsewhere when
-told \csa{tableofcontents}\csa{ref\{toc:A\}}. The actual
-layout (title inclusive) used for the cloned TOC will be
-decided locally. The line styles and toc display style
-(including the title) will be the current ones and the
-current value of the |tocdepth| counter is obeyed. As an
-example the table of contents of
-\autoref{part:custom} is in a \hyperref[toc:d]{float} which appears
-\vpageref{toc:d}.
+\etoc allows to typeset at some location a local table of contents which is
+defined elsewhere. For this, two simple steps:
+\begin{enumerate}
+\item insert \localtoc at the distant place, and follow it by some
+ |\label{foo}|.
+\item insert \toc|\ref{foo}| (or \localtoc|\ref{foo}|, it does the same) at the
+ place where you want this distant table of contents to appear.
+\item in step \textbf{1}, if you use \invisiblelocaltoc in place of \localtoc,
+ there will be no typesetting at its place of definition.
+\end{enumerate}
+At the place of use of \toc|\ref{foo}|, the layout and looks is entirely
+configurable locally. It may be completely different from how the same
+contents are rendered elsewhere by another \toc|\ref{foo}| or by the original
+label-decorated \localtoc|\label{foo}|. The current value of the |tocdepth|
+counter is obeyed.
+
+As an example the table of contents corresponding to \autoref{part:styling}
+has been cloned here in a
+\hyperref[toc:d]{float} which appears \vpageref{toc:d}.
\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
\begin{figure}[ht!]
\centering
\begingroup
- \etocstandardlines
+ % this is a KOMA-script specific customization
+ \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
+ \DeclareTOCStyleEntry[numwidth=3.2em,indent=2em]{tocline}{subsection}
+ \etocstandardlines % <-- use the defaults from the document class
\renewcommand{\etocbkgcolorcmd}{\color{green!5}}
\renewcommand{\etocbelowtocskip}{0pt\relax}
\fboxsep1ex
\etocframedstyle [1]{\fbox{\makebox[.5\linewidth]{\etocfontminusone
- \hyperref[toc:c]{I am from far away}}}}
- \tableofcontents \label{toc:d} \ref{toc:c}
+ I am from \hyperref[toc:part:styling]{far away}}}}
+ \etocsetnexttocdepth{subsection}
+ \tableofcontents \label{toc:d} \ref{toc:part:styling}
\endgroup
\end{figure}
\end{filecontentsdef}
\filecontentsexec\foo
-
-We used this: \filecontentsprint\foo
-\marginattach{}
-In the above example, not
-only did we use |\ref{toc:c}| to print here the distant (local) table of
-contents which has been labeled |toc:c| but we added a (possibly confusing)
-|\label{toc:d}|. This is done for the down-to-earth reason of being able
-to use, as we did in the previous paragraph, |\vpageref{toc:d}|.
-But if one wants to clone
-again the original local table of contents, one must reference its original
-label: \toc|\ref{toc:c}|.%
+We used this: \filecontentsprintviascan\foo
+\marginattach
+
+In the above example, not only did we use |\ref{toc:part:styling}| to print
+here the distant (local) table of contents which has been labeled |toc:part:styling| but
+we added a (possibly confusing) |\label{toc:d}|. This is done for the
+down-to-earth reason of being able to use, as we did in the previous
+paragraph, |\vpageref{toc:d}|. But if one wants to clone again the original
+local table of contents, one must reference its original label:
+\toc|\ref{toc:part:styling}|.%
%
\footnote{Why does this author always give
complicated examples rather than down-to-earth ones?}
%
-This original local table of contents is to be found \vpageref{toc:c}.
+This original local table of contents is to be found \vpageref{toc:part:styling}.
-\section{A powerful functionality of \etoc: the
+\section[\csbhyp{etocsetlevel}]{A powerful functionality of \etoc: the
re-assignment of levels with \csbhyp{etocsetlevel}}
\label{sec:tocdepth}
@@ -2359,7 +3622,8 @@ The simplest organization is probably to have after |\begin{document}| and befor
the |tocdepth| counter after typesetting a TOC to the value it had before
it.
- Since |1.09| the macro \csb{etocsetnexttocdepth} works also if located in
+ % Since \etocrelease{1.09}
+ The macro \csb{etocsetnexttocdepth} works also if located in
first argument of \csb{etocsettocstyle}, but there is no reason to use it
there as \csb{etocsettocdepth} has no durable effet on the |tocdepth|
counter if executed there.
@@ -2392,9 +3656,9 @@ this did not modify the bookmark tree of the |pdf| file. Now that
\csb{etocsetnexttocdepth} has been added to the package, we have used it
systematically and there was no need for |bookmarksdepth=3| anymore.
-\section[The command \csbhyp{etocsettocdepth.toc}]{The command
+\section[The \csbhyp{etocsettocdepth.toc} command]{The
\csbhyp{etocsettocdepth.toc} and
- \csbhyp{etocimmediatesettocdepth.toc}}
+ \csbhyp{etocimmediatesettocdepth.toc} and commands}
\label{etocsettocdepth.toc}
\label{etocimmediatesettocdepth.toc}
@@ -2435,7 +3699,8 @@ Also \csb{etocimmediatesettocdepth.toc} is provided. For explanations,
refer to the discussion of \csb{etocimmediatedepthtag.toc} in the
next section.
-\subsection{The commands \csbhyp{etocobeytoctocdepth} and \csbhyp{etocignoretoctocdepth}}
+\subsection{The \csbhyp{etocobeytoctocdepth} and
+ \csbhyp{etocignoretoctocdepth} commands}
\label{etocobeytoctocdepth}
\label{etocignoretoctocdepth}
@@ -2445,16 +3710,17 @@ So \csb{etocignoretoctocdepth} is provided to cancel the
needed; and \csb{etocobeytoctocdepth} will
re-activate it. The package does initially \csb{etocobeytoctocdepth}.
-\section[The commands \csbhyp{etocdepthtag.toc} and \csbhyp{etocsettagdepth}]{The commands
+\section[The \csbhyp{etocdepthtag.toc} and \csbhyp{etocsettagdepth} commands]{The
\csbhyp{etocdepthtag.toc}, \csbhyp{etocimmediatedepthtag.toc} and
- \csbhyp{etocsettagdepth}}
+ \csbhyp{etocsettagdepth} commands}
\label{etocdepthtag.toc}
\label{etocimmediatedepthtag.toc}
\label{etocsettagdepth}
-Release |1.07h| has a command \csb{etocdepthtag.toc} which
+% Release \etocrelease{1.07h} has a
+The command \csb{etocdepthtag.toc}
allows to control dynamically the which contents end up included in the
displayed TOCs (this documentation also decribed formerly a way
using \csb{etocsettocdepth.toc} with some dummy level name, which got
@@ -2478,7 +3744,7 @@ keywords |none| and |all|.
As usual, once the tag depths have been set, they remain in effect until getting
redefined or seeing their scope expire via the closing of a group or of a
surrounding
-environment. For an example, see \autoref{ssec:tocwithdepthtags}.
+environment. For an example, see \autoref{sec:tocwithdepthtags}.
When using \csb{etocdepthtag.toc} in combination with \LaTeX's |\include|,
data may not end up in the |.toc| file in the correct order. For example in
@@ -2503,7 +3769,8 @@ So%
with a fix, in July\dots 2016. Sorry for long delay before updating
\etoc six years later\dots}
%
-|1.09f| adds \csb{etocimmediatedepthtag.toc} which will force the tag to be written
+% \etocrelease{1.09f} adds
+there is \csb{etocimmediatedepthtag.toc} which will force the tag to be written
immediately to the |.toc| file (well, rather immediately to the |.aux| file,
so before the inclusion of the auxiliary file of the included file).
@@ -2535,7 +3802,7 @@ provides two separate commands and it is up to user to make the correct
choice.
-\subsection{The commands \csbhyp{etocobeydepthtags} and \csbhyp{etocignoredepthtags}}
+\subsection{The \csbhyp{etocobeydepthtags} and \csbhyp{etocignoredepthtags} commands}
\label{etocobeydepthtags}
\label{etocignoredepthtags}
@@ -2545,30 +3812,246 @@ After \csb{etocignoredepthtags}, the |.toc| depth tags are ignored (but
\csb{etocobeydepthtags} which makes \etoc react to the found tags in the
|.toc| file.
-\section{The commands \csbhyp{etocglobaldefs} and \csbhyp{etoclocaldefs}}
-\label{etocglobaldefs}
-\label{etoclocaldefs}
+\section{Adding commands to the \texorpdfstring{\texttt{.toc}}{.toc} file}
+\label{sec:addingtotoc}
-In \LaTeX{} the meaning of a command defined via |\newcommand\foo{...}| inside
-an environment (or group) vanishes from \TeX's memory on exit from this
-environment (or group). At times however it is needed to make definitions with
-global scope, for this \TeX{} has the primitive prefix |\global|.
+We described above \csb{etocsettocdepth.toc} and \csb{etocdepthtag.toc} which
+both insert commands inside the |.toc| file. An even more general mechanism of
+adding ``action tags'' to the |.toc| file could be envisioned, but this would
+just be a wrapper for direct use of |\addtocontents{toc}{\something}|.
-By default \etoc's definitions of \csb{etocname} etc... are local. This causes
-problems in certain contexts such as TOC as tables (\autoref{sec:tocastable}, \autoref{ssec:tocastableold}) and also
-with |enumitem| \emph{inline} variants of its standard environments, because
-the command |\item| then closes a group (see \autoref{etocthelink}).
+One should be cautious when adding in this way
+things
+to the |.toc| file. For example, inserting
+\csa{addtocontents}|{toc}{\string\clearpage}|
+just
+before a \csa{part} to fix the problem when some part entry (in
+the table of contents) is isolated at the bottom of one page,
+will cause problems with multiple TOCs: this \csa{clearpage}
+will be executed by \etoc each time a \toc or \localtoc
+command is encountered! The more prudent thing is to do
+rather: {\csa{addtocontents}|{toc}{\string\myclearpage}|,}
+to have a |\let\myclearpage\relax| at the top level of the
+document and to use where needed something like:
+\begin{verbatim}
+\let\myclearpage\clearpage
+\tableofcontents
+\let\myclearpage\relax
+\end{verbatim}
+The \ctanpkg{memoir} class has the command \csa{settocdepth} which
+writes a \csa{changetoc\-depth} command inside the |.toc| file.
+This will impact the typesetting by \etoc of \emph{all} tables
+of contents, with (possibly) unexpected results: imagine the
+document has \csa{settocdepth}|{chapter}| at some point to
+avoid having the sections from subsequent chapters be listed
+in the main table of contents. Then a local table of contents
+in one of these chapters will print a title but will be
+without any entry.
+
+As the \ctanpkg{memoir} class by itself allows multiple\toc
+ these issues already arise there,
+ independently of \etoc, see page 170 of the \ctanpkg{memoir}
+ manual.
-After \csb{etocglobaldefs}, \etoc will make its definitions of \csb{etocname}
-etc... have global scope. For normal use this is not necessary. It does not hurt
-either to activate it systematically.
+For this specific issue, the commands \csb{etocsettocdepth.toc},
+\csb{etocignoretoctocdepth} and \csb{etocobeytoctocdepth} are the way to go; or
+their variants \csb{etocdepthtag.toc} and \csb{etocsettagdepth}.
+
+As an aside, any |\setcounter{tocdepth}{n}| command added directly to the |.toc|
+file will see its effect
+% (since release \etocrelease{1.07g})
+cease when the end of a table of contents is reached, as \etoc executes a
+|\setcounter{tocdepth}{previous_value}| there, to reste the \texttt{tocdepth}
+counter to the value it had on entering the table of contents.
+
+\subsection{The hyperref option \emph{hidelinks}}\label{ssec:hidelinks}
+
+The colored links (and also the rectangle links) are a bit
+annoying when used in tables of contents, especially when
+the document uses \etoc and has plenty of them! One may wish
+for having colored links, \emph{except} for those within
+table of contents!
+Indeed, why would things in TOCs need to be either framed in
+rectangles or colored, when the user \emph{already expects
+ them to be links}?
+
+I use the following trick: either in the preamble using
+|\AtBeginDocument|, or right after |\begin{document}|, I
+ have the command
+ \centeredline{|\addtocontents{toc}{\protect\hypersetup{hidelinks}}|}
+
+ \begin{framed}
+ All TOCs typeset by \etoc have their contents done
+ within a group (as if enclosed in an environment). So
+ the command \csa{hypersetup}|{hidelinks}| will be
+ executed by \emph{each} TOC, but its effect will be
+ limited to that TOC.
+ \end{framed}
+
+ I found out experimentally that the option |hidelinks| could
+ indeed be set many times with |\hypersetup| (this is not the
+ case of all \ctanpkg{hyperref} options).
+
+\section[The \csbhyp{etocsetlocaltop.toc} command]
+ {The \csbhyp{etocsetlocaltop.toc} and
+ \csbhyp{etocimmediatesetlocaltop.toc} commands}
+\label{etocsetlocaltop.toc}
+\label{etocimmediatesetlocaltop.toc}
+
+It is important to understand that \csb{localtableofcontents} works entirely
+from data \emph{in the |.toc| file}. If the document, say with |article|
+class, contains starred sectioning commands, which are not accompanied
+by suitable \csa{addcontentsline}, then these units are completely
+transparent to \csb{localtableofcontents}:
+\begin{itemize}
+\item If \localtoc is issued before |\section*{Foo}|, say locally to a |\section|,
+ then the local TOC will include not only the |subsection|s between the
+ |\section| and the |\section*{Foo}| but also those following, and it will
+ stop only at encountering a later |\section| or |\part| from the document's body.
+\item If the command is issued right after |\section*{Foo}| and the later was
+ itself subsequent to a (numbered) |\subsection|, then \etoc will think it
+ must display a TOC local to the \emph{subsection}.
+\end{itemize}
+
+% Since release \etocrelease{1.08k}, \etoc provides the one-argument
+There is the command
+\csb{etocsetlocaltop.toc} to insert into the |.toc| file a kind
+of ``ghost'' of a given sectioning unit. Here is an example:
+
+\begin{verbatim}
+\part*{Extra unnumbered part}
+\etocsetlocaltop.toc{part}
+\localtableofcontents
+\end{verbatim}
+
+So with no |\part| heading inserted into the table of contents via an
+|\addcontentsline|, still \localtoc will know it is local to a part. In this
+example the local contents will be delimited by the next numbered |\part|, or
+|\part*| with |\addcontentsline|, or also by a later, second,
+|\etocsetlocaltop.toc{part}|.
+
+As a (counter)-example consider this document:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{etoc}
+\begin{document}
+\tableofcontents
+
+\part*{A}
+\etocsetlocaltop.toc{part}
+\localtableofcontents
+
+\section{I}
+
+\section{II}
+
+\part*{B}
+
+\section{III}
+
+\part*{C}
+
+\section{IV}
+\end{document}
+\end{verbatim}
+It uses only |\part*|. Thanks to the \csb{etocsetlocaltop.toc} the \localtoc
+knows it should report only sections. But the other |\part*| are invisible to
+it as nothing is recorded in the |.toc| file. So the local table of contents
+in this example will list \emph{all} sections not only |I| and |II|. To fix thix one may
+e.g.\@ insert another |\etocsetlocaltop.toc{part}|, this time after |\part*{B}|
+(or make this a numbered part, or use |\addcontentsline| for it).
+
+The above document amended with added |\etocsetlocaltop.toc{part}| after each
+unnumbered part will thus have its main TOC without any |Part| heading, but
+each |\part| can show a correct \localtoc. The simpler
+approach would be to use |\addcontentsline| with each unnumbered |\part| so
+that it ends up in the |.toc| file, but \etoc is keen on allowing the most
+diverse point of views.
-To return to the default, use \csb{etoclocaldefs}. Note that both
-\csb{etocglobaldefs} and \csb{etoclocaldefs} actions are local to the
-environment or group where they are used.
+It should be stressed that the various |\etocsetlocaltop.toc|\marg{sect. unit}
+do impact the global \toc: they really act like actual sectioning units,
+except for not inducing any typesetting. In usual document classes, this
+would appear to mean that they are completely transparent to the global \toc.
+Not the case with \etoc, which adds a virtual assembly of levels: the |.toc|
+data originating in |\etocsetlocaltop.toc|\marg{sect. unit} will trigger the
+execution of the \marg{finish} parts of the line styles of finer sectioning
+units encountered before (either in the global \toc or in an active
+\localtoc); and it triggers the \marg{start} parts of the line styles of finer
+units encountered after it (again in the global \toc, but also in any
+\localtoc which is already activated at a coarser lever).
+Depending on how the toc line styles are configured this may translate into
+some visual effect; for example with the \etoc own line styles the
+\marg{start} and \marg{finish} mostly insert penalties or vertical spaces.
-\section{Not displayed empty TOCs}
+It is a matter of debate if this is good design; a variant serving purely to
+influence boundaries of local table of contents with no collateral effects
+could be provided. And the name of the macro was perhaps not so well chosen
+as it suggests it acts as would such an hypothetical variant. In absence of
+feature requests we leave the matter standing for now.%
+%
+
+Usage of \csb{etocsetlocaltop.toc} interacts with
+\csb{etocchecksemptiness} in the expected way: it modifies (as explained
+above) the selection made by \csb{localtableofcontents}, hence the decision
+whether this local TOC will end up empty or not.
+
+There is also \csb{etocimmediatesetlocaltop.toc}. This may be useful in some
+very special circumstances involving |\include|. For related discussion see
+the documentation of \csb{etocimmediatedepthtag.toc}.
+
+
+\section{The \csbhyp{etoclocaltop} command}
+\label{etoclocaltop}
+
+Within either the TOC style
+(\csb{etocsettocstyle}) or the local title styles (\csb{etocsetstyle}), the
+control sequence \csb{etoclocaltop} is made equivalent for the duration of
+\csb{localtableofcontents} to a numeric (self-delimiting) denotation of the
+current top level.
+
+Thus: it will in numeric contexts (|\ifnum|, |\ifcase|, ...) represent zero
+for a local TOC corresponding to chapter, or one if in a section, or two if in
+a subsection, etc..., assuming of course here that the default levels are
+obeyed (see \autoref{sec:tocdepth}).
+
+%\begin{framed}
+ \csb{etoclocaltop} from inside the TOC heading (first argument of
+ \csb{etocsettocstyle}) has the correct value \emph{only under
+ \csb{etocchecksemptiness} regime}. Special circumstances correspond to
+ some special values:
+ \begin{description}[nolistsep]
+ \item[|-3|] (|-\thr@@|)\newline
+ signals that \etoc considers the local TOC to be
+ ``unknown''; this happens at the last local TOC, for the first \LaTeX\ run
+ after adding a new \localtoc to the document. In doubt, \etoc assumes the
+ TOC will prove non empty, hence it prints (independently of whether the
+ check for emptiness was activated or not) the heading as specified by
+ \csb{etocsettocstyle}. Thus, check if \csb{etoclocaltop} gives |-3| as a
+ a \meta{number} to detect that situation from within the first argument of
+ \csb{etocsettocstyle}, if desired.
+ \item[|-1000|](|-\@m|)\newline is in case of a \localtoc
+ being considered ``known'' (although it may still refer to the data in the
+ |.toc| file from the previous run) but without the check for emptiness
+ having been executed.
+ \item[|-10000|](|-\@M|)\newline is the value when accessed from the title
+ of a global TOCs.
+ \end{description}
+%\end{framed}
+%\begin{framed}
+
+ When executed from within a local table of contents \textbf{line styles}
+ (\csb{etocsetstyle}), \csb{etoclocaltop} always will hold the correct value,
+ whether or not the emptiness check was executed.
+
+ For a global table of contents however, it will always keep the value |-3|.
+%\end{framed}
+
+Attention! \cs{etoclocaltop} is only to be queried not set.
+
+
+
+\section{Checking TOCs for emptiness}
\subsection{The \csbhyp{etocchecksemptiness} command}
\label{etocchecksemptiness}
@@ -2591,7 +4074,8 @@ the |.toc| file. See \autoref{sec:addingtotoc} in this context.
\begin{enumerate}
\item the \csb{etocifwasempty} command discussed below can be used from inside
\csb{etocaftertochook}, and even from inside \csb{etocbeforetitlehook}.
-\item there is also \csb{etocdoesnotcheckemptiness} (since |1.08i|.)
+\item there is also \csb{etocdoesnotcheckemptiness}.%
+% (since \etocrelease{1.08i}.)
\end{enumerate}
The suppression of the heading (more precisely of the toc display style
@@ -2638,138 +4122,257 @@ empty, this does mean that \etoc considered the just encountered local table
of contents to be empty (for that run) and thus printed nothing (not even a
|\par|).
-\section{Adding commands to the \texorpdfstring{\texttt{.toc}}{.toc} file}
-\label{sec:addingtotoc}
-We described above \csb{etocsettocdepth.toc} and \csb{etocdepthtag.toc} which
-both insert commands inside the |.toc| file. An even more general mechanism of
-adding ``action tags'' to the |.toc| file could be envisioned, but this would
-just be a wrapper for direct use of |\addtocontents{toc}{\something}|.
+\clearpage
+\etocdepthtag.toc {examples}
+\part{Examples}\label{part:examples}
-One should be cautious when adding in this way
-things
-to the |.toc| file. For example, inserting
-\csa{addtocontents}|{toc}{\string\clearpage}|
-just
-before a \csa{part} to fix the problem when some part entry (in
-the table of contents) is isolated at the bottom of one page,
-will cause problems with multiple TOCs: this \csa{clearpage}
-will be executed by \etoc each time a \toc or \localtoc
-command is encountered! The more prudent thing is to do
-rather: {\csa{addtocontents}|{toc}{\string\myclearpage}|,}
-to have a |\let\myclearpage\relax| at the top level of the
-document and to use where needed something like:
-\begin{verbatim}
-\let\myclearpage\clearpage
-\tableofcontents
-\let\myclearpage\relax
-\end{verbatim}
-The \ctanpkg{memoir} class has the command \csa{settocdepth} which
-writes a \csa{changetoc\-depth} command inside the |.toc| file.
-This will impact the typesetting by \etoc of \emph{all} tables
-of contents, with (possibly) unexpected results: imagine the
-document has \csa{settocdepth}|{chapter}| at some point to
-avoid having the sections from subsequent chapters be listed
-in the main table of contents. Then a local table of contents
-in one of these chapters will print a title but will be
-without any entry.
+\thispartstats %% (pas de sous-section)
-As the \ctanpkg{memoir} class by itself allows multiple\toc
- these issues already arise there,
- independently of \etoc, see page 170 of the \ctanpkg{memoir}
- manual.
+\etocdefaultlines
+\etocsettocstyle {}{}
+\localtableofcontents
-For this specific issue, the commands \csb{etocsettocdepth.toc},
-\csb{etocignoretoctocdepth} and \csb{etocobeytoctocdepth} are the way to go; or
-their variants \csb{etocdepthtag.toc} and \csb{etocsettagdepth}.
+To understand all code snippets in detail,
+one will need to have first browsed through \autoref{sec:linestyles}
+and \autoref{sec:tocstyle}.
-As an aside, any |\setcounter{tocdepth}{n}| command added directly to the |.toc|
-file sees its effect (since release |1.07g|) canceled at the end of each table
-of contents, which automatically does a |\setcounter{tocdepth}{previous_value}|
-with the value active on entering the table of contents.
-\subsection{The hyperref option \emph{hidelinks}}\label{ssec:hidelinks}
-The colored links (and also the rectangle links) are a bit
-annoying when used in tables of contents, especially when
-the document uses \etoc and has plenty of them! One may wish
-for having colored links, \emph{except} for those within
-table of contents!
-Indeed, why would things in TOCs need to be either framed in
-rectangles or colored, when the user \emph{already expects
- them to be links}?
+\section{A first example}
+\label{sec:firstexample}
+\label{invisiblelocaltableofcontents}
-I use the following trick: either in the preamble using
-|\AtBeginDocument|, or right after |\begin{document}|, I
- have the command
- \centeredline{|\addtocontents{toc}{\protect\hypersetup{hidelinks}}|}
+Let us present a first example of specification for line styles.
+Immediately after the start of \autoref{part:overview} we inserted in the
+source file:
+%
+\centeredline{\csb{invisiblelocaltableofcontents} |\label{toc:overview}|}
+%
+This
+sets-up the label |toc:overview|, and we can use it at any location in the
+document:
+%
+\centeredline{|\tableofcontents \ref{toc:overview}|}
+%
+And as we used
+|\invisible...|,\footnote{this is a shortcut for setting temporarily the
+ |tocdepth| to |-3|, which has the effect to tell \etoc not to print the TOC,
+ and not even the heading.} the local TOC will exist only through its clones
+elsewhere in the document.
- \begin{framed}
- All TOCs typeset by \etoc have their contents done
- within a group (as if enclosed in an environment). So
- the command \csa{hypersetup}|{hidelinks}| will be
- executed by \emph{each} TOC, but its effect will be
- limited to that TOC.
- \end{framed}
+\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
+\begingroup\parindent 0pt \parfillskip 0pt \leftskip 0cm \rightskip 1cm
+\etocsetstyle {section}
+ {}
+ {\leavevmode\leftskip 0cm\relax}
+ {\bfseries\normalsize\makebox[.5cm][l]{\etocnumber.}%
+ \etocname\nobreak\hfill\nobreak
+ \rlap{\makebox[1cm][r]{\mdseries\etocpage}}\par}
+ {}
+\etocsetstyle {subsection}
+ {}
+ {\leavevmode\leftskip .5cm\relax }
+ {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
+ \etocname\nobreak\hfill\nobreak
+ \rlap{\makebox[1cm][r]{\etocpage}}\par}
+ {}
+\etocsetstyle {subsubsection}
+ {}
+ {\leavevmode\leftskip 1.5cm\relax }
+ {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
+ \etocname\nobreak\hfill\nobreak
+ \rlap{\makebox[1cm][r]{\etocpage}}\par}
+ {}
+\etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of
+ \autoref{part:overview} (\nameref{part:overview})}
+\tableofcontents \ref {toc:overview}
+\endgroup
+\end{filecontentsdef}
- I found out experimentally that the option |hidelinks| could
- indeed be set many times with |\hypersetup| (this is not the
- case of all \ctanpkg{hyperref} options).
+\filecontentsexec\foo
+We could have used the line styles defined by \etoc, with
+\csb{etocdefaultlines}, or the default document class styles with
+\csb{etocstandardlines}, but we were a bit more ambitious here and wanted to
+design our own. The technique is a simple one: each heading is in its own
+paragraph, which may extend on multiple lines; it is responsible for setting
+its own |\leftskip|.
-\clearpage
-\etocdepthtag.toc {examples}
-\part{Examples}\label{part:examples}
+This is a simple design which does not make provisions for page breaks
+which should be discouraged in-between a section and a subsection
+etc\dots{} as we only used it for the table of contents of this part, thus
+with sections as top levels, there was no need to specify a style for
+parts too (we defined a subsubsection line style but as it turns
+out there are no subsubsections in this part). The two commands used are
+\csb{etocsetstyle} for specifying the line styles, and
+\csb{etocruledstyle} for the TOC global style.
-\thispartstats %% (pas de sous-section)
+The |\rightskip| is shared by all, and creates space where the page
+numbers get printed. For an elaboration of this technique see the next
+\autoref{sec:secondexample} as well as \autoref{sec:tocwithdepthtags}
+which provides a TOC with parts and paragraphs. Both allow multi-line
+headings and employ a technique for putting page numbers in the right margin
+which was inspired from what \LaTeX2e's |\@dottedtocline| macro does.
-\etocstandardlines
-\etocsettocstyle {}{\medskip}
-\localtableofcontents
+Here is how it was produced:
+
+\filecontentsprintviascan\foo
+\marginattach
+
+\section{A second example}
+\label{sec:secondexample}
+
+This second example displays only the contents from
+\autoref{sec:linestyles} and \autoref{sec:tocstyle}. This selection
+is done via the technique of \emph{depth tags}, described in
+\autoref{etocsettagdepth} and \autoref{sec:tocwithdepthtags}.
+
+\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
+\begingroup
+\newcommand*{\DotsAndPage}
+{\nobreak\leaders\hbox{\bfseries\normalsize\hbox to .75ex {\hss.\hss}}%
+ \hfill\nobreak
+ \makebox[\rightskip][r]{\bfseries\normalsize\etocpage}\par}
+
+\etocsetstyle {part}
+{\parindent 0pt
+ \nobreak
+ \etocskipfirstprefix}
+{\pagebreak[3]\bigskip}
+{\large\rmfamily\bfseries\centering %\scshape
+ \etocifnumbered{Part \etocnumber{} -- }{}\etocname\par}
+{}
+
+\etocsetstyle {section}
+{\leftskip 0pt \rightskip .75cm \parfillskip-\rightskip
+ \nobreak\medskip
+ \etocskipfirstprefix}
+{\leftskip 0pt \rightskip .75cm \parfillskip-\rightskip
+ \pagebreak[1]\smallskip}
+{\normalsize\rmfamily\bfseries %\scshape
+ \etocnumber. \etocname\DotsAndPage }
+{\parfillskip 0pt plus 1fil\relax }
+
+\etocsetstyle {subsection}
+{\leftskip1cm\rightskip .75cm \parfillskip 0pt plus 1fil\relax
+ \nobreak\smallskip}
+{}
+{\footnotesize\sffamily\mdseries\itshape
+ \etocname{} (\etocnumber, p. \etocpage). }
+{\par\medskip}
+
+\etocsettagdepth {preamble} {none}
+\etocsettagdepth {overview} {none}
+\etocsettagdepth {styling} {subsection}
+\etocsettagdepth {control} {none}
+\etocsettagdepth {examples} {none}
+\etocsettagdepth {advanced} {none}
+\etocsettagdepth {etocandworld}{none}
+\etocsettagdepth {code} {none}
+
+\etocsettocstyle {\centering\LARGE\textsc{\contentsname}\par\nobreak\medskip}{}
+\etocsetnexttocdepth {subsection}
+\tableofcontents
+\endgroup
+\end{filecontentsdef}
+\filecontentsexec\foo
+
+The code:
+\filecontentsprintviascan\foo
+\marginattach
+
+\section{A Beautiful Thesis example}
+
+Here is a relatively simple example of use of the package
+functionalities.
+Let us set up some line styles. We choose a style for sections and
+sub-sections which would be suitable for, respectively, sections and
+sub-sections in an average length memoir. The line style specifications have
+some redundancy for clarity, and do not care about what to do at possible page
+breaks. Also, they do not worry about potential multi-column use.
+
+\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
+\begingroup % we start a group to keep the style changes local
+\newlength{\tocleftmargin} \setlength{\tocleftmargin}{4cm}
+\newlength{\tocrightmargin} \setlength{\tocrightmargin}{1cm}
+
+\etocsetstyle{section} % will pretend to be a Chapter
+{\addvspace{1ex}\parfillskip0pt
+ \leftskip\tocleftmargin % (already done in title)
+ \rightskip\the\tocrightmargin plus 1fil
+ \parindent0pt\color{cyan}} % (already done)
+{\bfseries\LARGE\upshape\addvspace{1ex}\leavevmode}
+{\llap{Chapter\hspace{.5em}{\etocnumber}\hspace{.75cm}}\etocname
+ \nobreak\hfill\kern1em\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
+{}
+
+\etocsetstyle{subsection} % will pretend to be a Section
+{}
+{\mdseries\large\addvspace{.5ex}\leavevmode}
+{\llap{\etocnumber\hspace{.75cm}}\textit{\etocname}%
+ \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
+{}
+
+\def\tmptitle{My Beautiful Thesis}
+\etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin
+ \leavevmode\leaders\hrule height 1pt\hfill\
+ \huge\textit{\tmptitle}\par}{\bigskip}
+
+\tableofcontents \ref{toc:overview}
+\endgroup
+\end{filecontentsdef}
+
+\filecontentsexec\foo
+
+\filecontentsprintviascan\foo
+\marginattach
-We present some additional examples. To understand all code snippets in detail,
-one will possibly need to have first browsed through \autoref{part:linestyles}
-and \autoref{part:globalcmds}.
-\section{Testing the compatibility mode}
+\section{Testing the compatibility mode}\label{sec:testingcompat}
As a further example we now print the local table of contents
-of \autoref{part:globalcmds}. First we will test the compatibility mode.\footnote{the
+of \autoref{sec:tocstyle}. First we will test the compatibility mode.\footnote{the
present document uses the \ctanpkg{scrartcl} class, and we check here that
the \etoc compatibility mode does respect the customizing done via the
-class commands.} The original was invisibly defined with a label at the
-beginning of \autoref{part:globalcmds}.
+class commands.} The original is the local table of contents of
+\autoref{sec:tocstyle}, to which we allocated the label |toc:tocstyle|.
\begin{verbatim}
\begingroup % to keep in particular toc=left with local effect
\KOMAoptions{toc=left}
-\etocstandarddisplaystyle % necessary for the display to obey toc=left
+\etocclasstocstyle % necessary for the display to obey toc=left
\etocstandardlines
-\tableofcontents \ref{toc:globalcmds}
+\tableofcontents \ref{toc:tocstyle}
\endgroup
\end{verbatim}
\begingroup
\KOMAoptions{toc=left}
-\etocstandarddisplaystyle
+\etocclasstocstyle
\etocstandardlines
-\tableofcontents \ref{toc:globalcmds}
+\tableofcontents \ref{toc:tocstyle}
\endgroup
-\section{Another compatibility mode}\label{sec:anothercompat}
+\section{Another compatibility mode}
+\label{sec:anothercompat}
-As explained in \autoref{subs:compat}, the commands
-\csb{etocstandardlines} and \csb{etocstandarddisplaystyle} tell \etoc to,
-essentially, act as an observer. The document class layout for the table of
-contents is then perfectly obeyed. There is no way to customize this standard
-layout (change fonts, margins, vertical spacings, etc...) from within the
-package. For this, use some package dedicated to this task; because \etoc either
-is (temporarily perhaps) in compatibility mode with no customization on its part
-possible, or the user has specified the layout in \csb{etocsetstyle} commands
-(and \csb{etocsettocstyle}) and is (supposedly...) in complete control.
+As explained in \autoref{subs:compat}, the commands \csb{etocstandardlines}
+and \csb{etocetoclocaltocstyle} tell \etoc to, essentially, act as an
+observer. And it starts in this state initially. The document class layout
+for the table of contents is then perfectly obeyed (well, hopefully). There
+is no way \emph{if remaining in this compatibility mode} to customize this
+standard layout (change fonts, margins, vertical spacings, etc...) from within
+the package.
+
+For customizing \emph{while remaining in the compatibility mode}, use some
+package dedicated to this task; because \etoc either is (temporarily perhaps)
+in compatibility mode with no customization on its part possible, or the user
+has specified the layout in \csb{etocsetstyle} commands (and
+\csb{etocsettocstyle}) and is supposedly in complete control.
Well, there is actually an alternative. It is possible to use the
\csb{etocsetstyle} commands to recreate an artificial compatibility mode, in
-order to achieve effects like the following, all things being otherwise equal to
-the document class defaults:
+order to achieve effects like the following, all things being otherwise equal
+to the document class defaults:
\begin{enumerate}[noitemsep]
\item get the \ctanpkg{hyperref} link to encapsulate only the names, but not the numbers
of each entry of the table of contents,
@@ -2778,123 +4381,138 @@ the document class defaults:
\item do either of the above only for some portions of the table of contents.
\end{enumerate}
-One only needs%
-%
-\marginpar{\normalfont\footnotesize\itshape Modified at \texttt{1.1a}}
-%
-to use the \LaTeX{} standard \csa{l@chapter}, \csa{l@section},
-etc... commands inside the TOC line style definitions via \csb{etocsetstyle},
-re-constituting their arguments using \csb{etocname}, \csb{etocnumber},
-\csb{etocpage} as one wishes.
-
-The aliases \csb{etocsavedsectiontocline}, \csb{etocsavedchaptertocline}
-etc... are set to have the exact same meanings as the \LaTeX{} |\l@chapter|,
-|\l@section|, etc... commands each time a TOC is typeset. They are
-\fbox{DEPRECATED} as the latter \LaTeX\ commands are not modified (nor used) by
-\etoc since release |1.1a|.
-
-You should use directly |\l@chapter|, etc... within suitable
-|\makeatletter/\makeatother|. Here is an example.
+One only needs
+to use within the arguments of \csb{etocsetstyle} the \LaTeX{} standard
+\csa{l@chapter}, \csa{l@section}, etc... re-constituting their arguments using
+\csb{etocname}, \csb{etocnumber}, \csb{etocpage} as one wishes.
+Here is an example. Include in the preamble:
\begin{filecontentshere}{etocsnippet-\snippetno.tex}
\makeatletter
-\newcommand{\MyStandardTOC}{%
+\newcommand{\MyLocalTOC}[1][section]{%
\begingroup
- % for the book or article classes:
- %\etocsetstyle{part}{}{}
- % {\l@part{\etocnumber\hspace{1em}\etocname}{\etocpage}}{}%
- % for the scrbook or scrartcl classes:
- \etocsetstyle{part}{}{}
- {\l@part{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
- % following is identical in book/article/scrbook/scrartcl classes:
- \etocsetstyle{chapter}{}{} %%% only for book and scrbook
- {\l@chapter{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
\etocsetstyle{section}{}{}
{\l@section{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
\etocsetstyle{subsection}{}{}
{\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
- % etc... if further sectioning units are used
- \etocstandarddisplaystyle % this is for the title, page-marks, etc...
- \tableofcontents
+ \etocsetstyle{subsubsection}{}{}
+ {\l@subsubsection{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
+ % etc... if further sectioning units are needed
+ % (i.e. not excluded by tocdepth and actually there in document)
+ % Here #1 defaults to section, meaning this is appropriate
+ % for local TOC in a chapter
+ \etocsettocstyle{\@nameuse{#1}*{Local contents}}
+ {}
+ %
+ \localtableofcontents
\endgroup}
\makeatother
\end{filecontentshere}
-\marginattach{-A}
+\marginattach
+
+Then use \csa{MyLocalTOC} in the document body. It is prepared
+for being local to a \csa{chapter}'s as it typesets the heading of the TOC
+by default as un unnumbered section.%
+%
+\footnote{Parts are handled somewhat differently according to whether
+one uses the standard or other classes; please check the source of these
+classes for what is to emulate here.}
One can add to the above arbitrary text formatting commands, for example
-replace |\etocpage| by |\textcolor{blue}{\etocpage}|.
-
-If the document has only one table of contents then there is no need
-to put the commands inside a macro, or even inside a group.\footnote{and if
-moreover one just wants to keep the same layout as in the default, one may
-question why using \etoc... there is \emph{one} good reason: numbers and names
-are separately \ctanpkg{hyperref} links, whereas normally there is only one link
-holding both the number and the name corresponding to one toc entry.} With these
-commands
-\etoc will construct a TOC completely identical to what would have been done by
-one of the document class: |article|, |book|, \ctanpkg{scrartcl}, \ctanpkg{scrbook}.\footnote{For the
-\ctanpkg{memoir} class, one needed prior to \etoc |1.08k| a bit more: each of the command \csa{booknumberline},
-\csa{partnumberline} and \csa{chapternumberline} had to be saved. They can now
-be used directly in the line styles, because their meanings are not modified
-anymore by \etoc during its TOC typesetting.}
-The number and the name of each entry are each separately an \ctanpkg{hyperref} link, as
-is always the case with \etoc, when not in compatibility mode. Replacing
-\csb{etocnumber} with \csb{etocthenumber} will give a TOC where the numbers are
-not links anymore, but the names still are. Or one may decide to use \csb{etocthename}
-and keep an hyperlinked number with
-\csb{etocnumber}.
-
-Here is a subtler example where one only marginally modifies the
-sections (adding color to the number and removing the \ctanpkg{hyperref} link) and keeps
-the subsections as in the default, \emph{except} for those of one specific
-section, for which the layout is completely modified:
-\MyQuasiStandardTOC{\ref{toc:overview}}
-\bigskip
-This example only has sections and subsections (assumed to be numbered), and
-the code used was:
-\begin{filecontentshere}{etocsnippet-\snippetno.tex}
+one can replace |\etocpage| in the code above by |\textcolor{blue}{\etocpage}|.
+
+Only pay attention to using |\makeatletter/\makeatother| as we are handling
+\LaTeX{} macros with the dangerous sign |@| in their names.
+
+To give another example, one sees in \texttt{article.cls} the following
+definition:
+\begin{verbatim}
+\newcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.3em}}
+\end{verbatim}
+The first argument is the level, the second the indent, and the third the
+numwidth (see the \ctanpkg{tocloft} documentation). So if we issue in a
+document using the \texttt{article} class:
+\begin{verbatim}
\makeatletter
-\newcommand*{\MyQuasiStandardTOC}[1]{%
- \begingroup
- \etocsetstyle{section}
+\etocsetstyle{subsection}
+ {]
+ {}
+ {\@dottedtocline{2}{1.5em}{2.3em}{\numberline{etocnumber}\etocname}{\etocpage}}
{}
- {\ifnum\etocthenumber=4
- \etocsetstyle{subsection}
- {\par\nopagebreak\begingroup
- \leftskip1.5em \rightskip\@tocrmarg
- \parfillskip \@flushglue
- \parindent 0pt
- \normalfont\normalsize\rmfamily\itshape
- \etocskipfirstprefix}
- {\allowbreak\,--\,}
- {\etocname\ \textup{(\etocnumber)}}
- {.\par\endgroup}%
- \else
- \etocsetstyle{subsection}
- {}%
- {}%
- {\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}%
- {}%
- \fi
- }% prefix for section sets the style dynamically for subsections!
- {\l@section{\numberline{{\color{cyan}\etocthenumber}}\etocname}{\etocpage}}%
- {}%
- \etocstandarddisplaystyle
- \etocsetnexttocdepth {2}%
- \tableofcontents #1
- \endgroup
-}
\makeatother
-\end{filecontentshere}
-\marginattach{-B}
+\end{verbatim}
+we then basically reconstitute the default rendering. Here is more careful
+code:
+\begin{verbatim}
+\makeatletter
+\etocsetstyle{subsection}
+ {]
+ {}
+ {\@dottedtocline{2}{1.5em}{2.3em}{\etocifnumbered{\numberline{etocnumber}}{}%
+ \etocname}{\etocpage}}
+ {}
+\makeatother
+\end{verbatim}
+Hence one can very easily without any (additional...) package modify the
+hard-coded indent |1.5em| and numwidth |2.3em|. But in general one has to do
+this in a synchronized way also for subsubsections, and for sections. The
+definition of |\l@section| in the \texttt{article} class source is a bit more
+complex.
+
+Nevertheless this technique is probably the fastest (but see the example at
+start of \autoref{sec:linestyles}) to get going with \etoc even if one is
+primarily interested only in its \localtoc, as typesetting local tables of
+contents exactly as global tables of contents is not ideal. For example for a
+local TOC in a section, it looks appropriate to modify the above into
+\begin{verbatim}
+\makeatletter
+\etocsetstyle{subsection}
+ {]
+ {}
+ {\@dottedtocline{2}{0}{2.3em}{\etocifnumbered{\numberline{etocnumber}}{}%
+ \etocname}{\etocpage}}
+ {}
+\makeatother
+\end{verbatim}
+to cancel the indentation. One will have to keep the indents and numwidths in
+sync with similar changes to other line styles, if \csa{contentsline}'s of
+various levels are to be executed.
+
+%
+%
+The number and the name of each entry are each separately an \ctanpkg{hyperref}
+links, as is always the case with \etoc, when not in compatibility
+mode. Replacing \csb{etocnumber} with \csb{etocthenumber} will give a TOC where
+the numbers are not links anymore, but the names still are. Or one may decide
+to use \csb{etocthename} and keep an hyperlinked number with \csb{etocnumber}.
+
+For a more sophisticated example see \autoref{sec:anothercompatadvanced}.
+
+\begin{shaded}\footnotesize\itshape
+ \textcolor{red}{Attention Please!} The \LaTeX{} kernel is moving towards
+ adding \emph{tagging} to the PDF, in a way mostly automated and transparent
+ to user. \etoc will in due time accompany that evolution but this may mean
+ that it will use for its own the hooks that \LaTeX{} will place for example
+ in \emph{\csa{@dottedtocline}}. So, if the user explicitly also requires
+ usage of \emph{\csa{@dottedtocline}}, this \emph{may} mean that some tagging
+ code would be executed twice, possibly causing some havoc.
+
+ My remark is \emph{purely hypothetical}, as a.t.t.o.w.\@ (2023/02/22) I have
+ only started looking in the matter, and the \LaTeX{} and \ctanpkg{hyperref}
+ TOC related changes have started being visible to developers only a few days
+ ago.
+
+ It may be however, that activating tagging could mean that the simple-minded
+ recycling techniques described in this section will not work. I guess \etoc
+ will always have the possibility to let the user specify that \etoc should
+ not take care itself of the tagging (which it has to do in general, because
+ the \LaTeX{} hooks are located in places such as \emph{\csa{@dottedtocline}}
+ which \etoc does not execute, except if asked to do so as in the example
+ above), so perhaps the techniques here will still work but require some
+ \emph{\csa{etocnotagging}} or some \emph{noetoctagging} option to the
+ \localtoc or \toc commands.\par
+\end{shaded}
-The page heading (on the page where this TOC appears) may have been modified
-as is expected from usage of \csb{etocstandarddisplaystyle} in the code.
-Sections and subsections are printed exactly as in the default, \emph{except}
-for the subsections of one specific user-chosen section and except for the
-color of the section numbers. We had to examine the \ctanpkg{scrartcl} sources
-to determine what to use for \csa{leftskip} and \csa{rightskip} for our
-customized section entry (the one wih number 4).
\section{Emulating the book class}\label{sec:thirdexample}
@@ -3035,7 +4653,8 @@ using |pt| as dimensional unit.
}
\makeatother
\end{filecontentshere}
-\marginattach{-A}
+\marginattach
+
Nota Bene: the code deliberately handles the non-numbered sectioning units
unlike the way of the standard document classes (particularly regarding the
alignment of multi-line headings.)
@@ -3095,7 +4714,8 @@ TOC at end of document one will naturally have to issue again
}% end of \TOClocalstyle
\makeatother
\end{filecontentshere}
-\marginattach{-B}
+\marginattach
+
As mentioned previously, this handles non-numbered (multi-line) sectioning
units somewhat differently from what happens in the standard document classes.
@@ -3135,24 +4755,24 @@ line styles and some colors added (it has been put in a float which appears
\renewcommand{\etocbelowtocskip}{0pt\relax}
\etocframedstyle {\normalsize\rmfamily\itshape
\fcolorbox{red}{white}{\parbox{.8\linewidth}{\centering
- This is a table of contents \`a la \etoc, but just for
- the sections and subsections in this part. As it is put
- in a frame, it has to be small enough to fit on
+ This is a table of contents \`a la \etoc, but for
+ the subsections and subsubsections of \autoref{sec:tocstyle}.
+ As it is put in a frame, it has to be small enough to fit on
one page. It has the label |toc:b|.}}}
\begin{figure}[ht!]
\centering
-\tableofcontents \label{toc:b} \ref{toc:globalcmds}
+\tableofcontents \label{toc:b} \ref{toc:tocstyle}
\end{figure}
\endgroup
\end{filecontentshere}
-\marginattach{-A}
+\marginattach
\filecontentsexec\filecontentsheremacro
-\section{Another TOC with a background color}\label{ssec:again}
+\section{Another TOC with background color}\label{ssec:again}
Let us now try out some more sophisticated line styles. The display will use
the \csb{etocframedstyle} package command, which requires that the produced
@@ -3244,20 +4864,22 @@ code is used also for \hyperref[toc:clone]{this other toc}.
{}
\etocframedstyle[1]{}
-\tableofcontents \label{toc:floating} \ref{toc:overview}
+\tableofcontents \label{toc:floating} \ref{toc:part:styling}
\vspace{-\baselineskip}
-\centeredline{|\tableofcontents \ref{toc:overview}|
+\centeredline{|\tableofcontents \ref{toc:part:styling}|
(\emph{cf.} \hyperref[toc:clone]{this other toc})}
\end{figure}
\end{filecontentshere}
-\marginattach{}
+\marginattach
\filecontentsexec\filecontentsheremacro
+The table of contents produced by this code appears on \vpageref{toc:floating}.
\section{A (crazy) inline display}
+\label{sec:crazy}
-Let us finally make some crazy inline display of the table of
-contents of this entire document. We will typeset the subsections as
+Let us construct some crazy inline display of the table of
+contents of this entire document. We will typeset the subsections as
footnotes... This kind of style is suitable for a hyperlinked
document, probably not for print! (although I like it, but my personal tastes in
many matters do not seem to be widely shared).
@@ -3298,22 +4920,130 @@ many matters do not seem to be widely shared).
\filecontentsexec\foo
The code used:
-\filecontentsprint\foo
-\marginattach{}
+\filecontentsprintviascan\foo
+\marginattach
+
+\section{One more example of colored TOC layout}
+\label{ssec:tocclone}
+
+The command \csb{etocframedstyle} puts the title on the top
+rule in a centered position. This is not very convenient for
+this example so we included the title as part of the
+\meta{start} code at section level, to get it \emph{inside}
+the frame.
+
+\begin{filecontentshere}{etocsnippet-\snippetno.tex}
+\begingroup
+\definecolor{subsecnum}{RGB}{13,151,225}
+\definecolor{secbackground}{RGB}{0,177,235}
+\definecolor{tocbackground}{RGB}{212,237,252}
+
+\renewcommand{\etocbkgcolorcmd}{\color{tocbackground}}
+\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
+
+\renewcommand{\etocleftrule}{\vrule width 1cm}
+\renewcommand{\etocrightrule}{\vrule width .5cm}
+\renewcommand{\etocbottomrule}{\hrule height 12pt}
+\renewcommand{\etoctoprule}{\hrule height 12pt}
+
+\renewcommand{\etocinnertopsep}{0pt}
+\renewcommand{\etocinnerbottomsep}{0pt}
+\renewcommand{\etocinnerleftsep}{0pt}
+\renewcommand{\etocinnerrightsep}{0pt}
+
+\newcommand\shiftedwhiterule[2]{%
+ \hbox to \linewidth{\color{white}%
+ \hskip#1\leaders\vrule height1pt\hfil}\nointerlineskip\vskip#2}
+\etocsetstyle{subsubsection}{\etocskipfirstprefix}
+ {\shiftedwhiterule{\leftskip}{6pt}}
+ {\sffamily\footnotesize
+ \leftskip2.5cm\hangindent1cm\rightskip1cm\noindent
+ \hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
+ \color{black}\etocname\leaders\hbox to .2cm{\hss.}\hfill
+ \rlap{\hbox to 1cm{\hss\etocpage\hskip.2cm}}\par
+ \nointerlineskip\vskip3pt}
+ {}
+
+\etocsetstyle{subsection}{\etocskipfirstprefix}
+ {\shiftedwhiterule{1.5cm}{6pt}}
+ {\sffamily\small
+ \leftskip1.5cm\hangindent1cm\rightskip1cm\noindent
+ \hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
+ \color{black}\etocname\leaders\hbox to .2cm{\hss.}\hfill
+ \rlap{\hbox to 1cm{\hss\etocpage\hskip.2cm}}\par
+ \nointerlineskip\vskip6pt}
+ {}
+
+\newcommand{\coloredstuff}[2]{%
+ \leftskip0pt\rightskip0pt\parskip0pt
+ \fboxsep0pt % \colorbox uses \fboxsep also when no frame!
+ \noindent\colorbox{secbackground}
+ {\parbox{\linewidth}{%
+ \vskip5pt
+ {\noindent\color{#1}#2\par}\nointerlineskip
+ \vskip3pt}}%
+ \par\nointerlineskip}
+
+\etocsetstyle{section}
+{\coloredstuff{white}
+ {\hfil \hyperref[toc:b]{\bfseries\large I am a twin of
+ that other TOC (click me!)}\hfil}}
+{\vskip3pt\sffamily\small}
+{\coloredstuff{white}
+ {\leftskip1.5cm\rightskip.5cm\parfillskip-\rightskip
+ \makebox[0pt][r]{\makebox[.5cm][r]{\etocnumber\hspace{.2cm}}}%
+ \etocname\hfill\makebox[.5cm][r]{\etocpage\hspace{.2cm}}}%
+ \vskip6pt }
+{}
+
+\etocframedstyle[1]{}
+\tableofcontents \label{toc:clone} \ref{toc:tocstyle}
+\endgroup
+\end{filecontentshere}
+\marginattach
+
+\filecontentsexec\filecontentsheremacro
+% 1.07l on the occasion of traduction into German documentation
+ % APRIL 26, 2014 Improvement in the section style for better placement of
+ % page number when the section name is more than one line long. Use of
+ % \makebox rather than \hbox, to be more LaTeX like.
+
+The TOC has been put in a \hyperref[toc:clone]{float} which appears
+\vpageref{toc:clone}. The coding is a bit involved\footnote{and reveals the
+ author's preference for the \TeX{} syntax...} as it does not use any
+additional package. Also, it was written at some early stage and I have not
+revised it since.
+
+A better solution would be to use some package to set
+up a background color possibly extending accross pages, as the
+framed style (which we used to get this background
+color) can only deal with material short enough to fit on one
+page.
+
+% 1.2 doc: commenté out to avoid a new page
+% ah non finalement car cause TOC as a tree d'être sur page impaire,
+% ce qui est moins bien à cause des overlap.
+Regarding colors, generally speaking all color commands inside
+\etoc are initially defined to do nothing, and the choice to
+use or not colors is left to the user.
\clearpage
-\etocdepthtag.toc {surprising}
-\part{Surprising uses of \etoc}
+\etocdepthtag.toc {advanced}
+\part{Advanced examples}
\label{part:surprising}
\thispartstats %% (pas de sous-section)
-\etocstandardlines
+\etocdefaultlines
\etocsettocstyle {}{}
\localtableofcontents
\section{The TOC of TOCs}
+\label{sec:tocoftocs}
\begingroup % \endgroup just after the \tableofcontents command
\etocinline
@@ -3334,7 +5064,8 @@ displayed within this document:\footnote{The TOCs put in
in the order the TOCs are typeset in the document; but the numbering
itself is from the order of the TOCs in the \emph{source} of
this document... }
-\tableofcontents\endgroup. And to obtain
+\tableofcontents
+\endgroup. And to obtain
it here we just wrote:\par\smallskip
{\leftskip1cm\rightskip2cm
\ttfamily\small\baselineskip11pt \noindent Here is the
@@ -3395,8 +5126,12 @@ it here we just wrote:\par\smallskip
Then, only here we have set |\etocsetlevel{visibletoc}{0}|. And to display
only this kind of entries we assign temporarily to |part| and |chapter| level
|1| (or anything higher than zero) and set |tocdepth| to the value |0|. We
- also did \csa{etocsetstyle\{visibletoc\}\{\string\etocskipfirstprefix\}\{,
- \}\{\string\etocname\}\{\}} which defines an inline display with the comma
+ also did%
+%
+\centeredline{\csb{etocsetstyle}\{visibletoc\}\{\csb{etocskipfirstprefix}\}%
+ \{, \}\{\string\etocname\}\{\}}
+%
+ which defines an inline display with the comma (plus space)
as separator. Finally, as \etoc issues |\par| automatically by default just
before typesetting a table of contents, we used the command \csb{etocinline}
(also known as \cs{etocnopar}) which turns off this behavior.
@@ -3427,7 +5162,7 @@ Here is the numbered and linked list of all tables of contents which are
displayed within this document: \tableofcontents.
\endgroup
\end{filecontentshere}
-\marginattach{}
+\marginattach
\endgroup
After |\etocsetstyle{visibletoc}{..}{..}{..}{..}|, all future TOCs (not in
@@ -3506,7 +5241,7 @@ typeset with the following code:
\tableofcontents
\endgroup
\end{filecontentshere}
-\marginattach{}
+\marginattach
A related command \csb{etocimmediatetoccontentsline} (and its starred version)
is also provided. For discussion and the meaning of ``immediate'', refer to
@@ -3514,31 +5249,30 @@ the analogous case of \csb{etocimmediatedepthtag.toc}.
\section{The TOC as a tree}\label{tocastree}
-Using \ctanpkg{tikz} and the package
-\ctanpkg{forest} we shall display the table
-of contents of this part as a tree. The technique is to
-use the \etoc modified command \toc not for typesetting, but to
-prepare a macro, or rather here a \emph{token list} variable, with all the
-instructions to be executed later. \textsc{Leslie Lamport}'s book has no mention
-whatsoever of token lists, and \LaTeX{} gives the impression to not really
-expect the general user to ever hear about them (or delimited macros); this
-whole section and the next are thus for
-advanced users.
-
-Putting the \csb{etocnumber} and \csb{etocname}
-commands in \csa{treetok} would be of no use: to which number or name would they
-then refer to, in a delayed execution?
+Using \ctanpkg{tikz} and the package \ctanpkg{forest} we shall display the
+table of contents of \autoref{part:styling} as a tree. The technique is to use
+the \etoc modified command \toc not for typesetting, but to prepare a macro,
+or rather here a \csa{toks} variable, with all the instructions to be executed
+later. \textsc{Leslie Lamport}'s book has no mention whatsoever of such token
+lists registers, and \LaTeX{} gives the impression to not really expect the
+general user to ever hear about them (or delimited macros); this whole section
+and the next are thus for advanced users.
+
+Putting the \csb{etocnumber} and \csb{etocname} commands in \csa{treetok}
+would be of no use: to which number or name would they then refer to, in a
+delayed execution?
We need to store, not the macro names, but the macro contents. And also we wish
-to maintain the correct \ctanpkg{hyperref} hyperlinks.\footnote{This manual up to the
-version of May 14, 2013 used package |tikz-qtree| but there were problems with
-hyperlinks. No such problem arises either when using |forest| or the native
-|tikz| syntax for trees (which will be illustrated in the next section).} The
+to maintain the correct \ctanpkg{hyperref} hyperlinks.
+The
commands \csb{etocname}, etc\dots, are robust, it is easier to work with
\csb{etocthelinkednumber}, \csb{etocthelinkedname}, and \csb{etocthelinkedpage}
which contain the same information in an easier accessible form.%
%
-\normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight At \texttt{1.1a} the commands \csa{etocthelinkedname}, etc\dots, are always providing an hyperlink, so it is not true that \csb{etocname}, etc\dots, are always simply their robust variants.}
+\normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
+At \etocrelease{1.1a} the commands \csa{etocthelinkedname}, etc\dots, are
+always providing an hyperlink, so it is not true that \csb{etocname}, etc\dots,
+are always simply their robust variants.}
For this |forest| tree we have designed very special \etoc styles for sections
and subsections. They use a token list register called |\treetok| and a
@@ -3557,7 +5291,7 @@ which will be given the contents of |\treetok|.
\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
% \newtoks\treetok % put this (uncommented) preferably in the preamble
% \newtoks\tmptok % (idem)
-
+\begingroup
\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
#1\expandafter\expandafter\expandafter
{\expandafter\the\expandafter #1#2}}
@@ -3587,7 +5321,7 @@ which will be given the contents of |\treetok|.
{\appendtotok\treetok{ ]}}
\etocsettocstyle
- {\treetok{[{\hyperref[part:overview]{Overview}}}}
+ {\treetok{[{\hyperref[part:styling]{The \etoc styling commands}}}}
{\global\appendtotok\treetok{ ]}}
% forest does not like @\the\treetok if \treetok is empty. On first latex
@@ -3596,31 +5330,35 @@ which will be given the contents of |\treetok|.
% TOC yet. So we must give a safe default value to \treetok
\treetok{[{run latex again}]}
-\begin{figure}[th!]\centering
+\begin{figure}[htbp!]
+\centering
\etocsetnexttocdepth{subsection}
- \tableofcontents \label{toc:forest}\ref{toc:overview}
+ \tableofcontents \label{toc:forest}\ref{toc:part:styling}
\hypersetup{hidelinks}%
\bracketset{action character=@}
+% manual adjustments to fit the printed page
+% \kern-1cm
+\noindent\kern-3cm
\begin{forest}
for tree={anchor=center,child anchor=west,
grow'=east,draw,thick,
edge={draw,thick,dashed,color=teal}},
where={level()==1}{circle,thick,fill=blue!5,
- before computing xy={l=3cm}}{},
+ before computing xy={l=6cm}}{},
where={level()==2}{fill=red!5,
before computing xy={l=6cm}}{},
rectangle, thick, fill=cyan!5, inner sep=6pt,
@\the\treetok
\end{forest}
\end{figure}
+\endgroup
\end{filecontentsdef}
\filecontentsexec\foo
The resulting tree has been put in a \hyperref[toc:forest]{float}, which
-appears \vpageref[above]{toc:forest}. Here is the
-code used for its production:
-\filecontentsprint\foo
-\marginattach{}
+appears \vpageref[above]{toc:forest}. Here is the code used for its
+production: \filecontentsprintviascan\foo \marginattach
+
Why |\hypersetup{hidelinks}|? as explained in
\autoref{ssec:hidelinks}, I prefer the links in TOCs not to be
colorized, nor framed, so this document inserts a command
@@ -3646,11 +5384,9 @@ typesetting:
\item printing the statistics at the start of each Part (see
\autoref{ssec:statistics}) is done using save boxes (so the problem of the
appearance of the links does not arise then).
-\item the typesetting of the TOC as a table in the pre-|1.08| way (see
- \autoref{ssec:tocastableold}); there we also have to issue
- |\hypersetup{hidelinks}| after having collected the names, numbers and
- page numbers in a token list register.
-\item and the two additional tree examples in the next section.
+\item typesetting of the TOC as a table without benefiting from
+ \csb{etocglobaldefs} (see \autoref{ssec:tocastableold}).
+\item and the examples in the next section.
\end{itemize}
@@ -3670,79 +5406,110 @@ up the total \csa{treetok}. As we are interested here in the table of
contents of this (or another) document part, only a \csa{sectiontok} and a
\csa{subsectiontok} will be needed.
-
+\let\appendtotok\relax
+\let\treenode\relax
+\let\appendchildtree\relax
+\let\preparetreenode\relax
\begin{filecontentshere}{etocsnippet-\snippetno.tex}
% \newtoks\treetok % put this (uncommented) preferably in the preamble
-% \newtoks\sectiontok
% \newtoks\subsectiontok
-\newcommand*{\treenode}{}
+% \newtoks\subsubsectiontok
+% Attention: this code has been prepared only for subsections
+% and subsubsections.
+
+\newcommand*{\treenode}{}% only to make sure our \edef's do not overwrite
+ % an existing command
+
+% expands 2nd argument (macro) and appends it to 1st argument (toks)
+\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
+ #1\expandafter\expandafter\expandafter
+ {\expandafter\the\expandafter #1#2}}
+% appends 2nd argument contents (toks) as child of first argument (toks)
\newcommand*{\appendchildtree}[2]{% token list t1 becomes: t1 child {t2}
\edef\tmp{\the#1 child {\the#2}}%
#1\expandafter{\tmp}%
}
+% prepare the (hyperlinked) number in the "node (number)" shape
\newcommand*{\preparetreenode}{%
- \tmptok\expandafter{\etocthelinkednumber}% expanded one time (mandatory)
+ \tmptok\expandafter{\etocthelinkednumber}% expanded once (needed)
\edef\treenode{node {\the\tmptok}}%
}
-\etocsetstyle{section}
+\etocsetstyle{subsection}
{\etocskipfirstprefix}
- {\appendchildtree\treetok\sectiontok}
- {\preparetreenode \sectiontok\expandafter{\treenode}}
- {\appendchildtree\treetok\sectiontok}
+ {\appendchildtree\treetok\subsectiontok}
+ {\preparetreenode
+ \subsectiontok\expandafter{\treenode}}
+ {\appendchildtree\treetok\subsectiontok}
-\etocsetstyle{subsection}
+\etocsetstyle{subsubsection}
{\etocskipfirstprefix}
- {\appendchildtree\sectiontok\subsectiontok}
- {\preparetreenode \subsectiontok\expandafter{\treenode}}
- {\appendchildtree\sectiontok\subsectiontok}
+ {\appendchildtree\subsectiontok\subsubsectiontok}
+ {\preparetreenode
+ \subsubsectiontok\expandafter{\treenode}}
+ {\appendchildtree\subsectiontok\subsubsectiontok}
\etocsettocstyle
- {\treetok{\node {\hyperref[part:overview]{Overview}}}}
+ {\treetok{\node {\hyperref[sec:linestyles]{Line styles}}}}
{\global\appendtotok\treetok{ ;}}
-\begin{figure}[thbp!]\centering
- \etocsetnexttocdepth{subsection}
- \tableofcontents \label{toc:molecule} \ref{toc:overview}
- \hypersetup{hidelinks}%
+\centeredline{% from package centeredline (limits scope of \hypersetup)
+ \etocsetnexttocdepth{subsubsection}
+ \etocinline\tableofcontents \label{toc:molecule} \ref{toc:tocstyle}
+ \hypersetup{hidelinks}%
\begin{tikzpicture}
[grow cyclic,
level 1/.style={level distance=4cm,sibling angle=72},
level 2/.style={level distance=2cm,sibling angle=60},
every node/.style={ball color=red,circle,text=SkyBlue},
edge from parent path={[dashed,very thick,color=cyan]
- (\tikzparentnode) --(\tikzchildnode)}]
- \the\treetok
- \end{tikzpicture}
-\end{figure}
+ (\tikzparentnode) --(\tikzchildnode)}]
+ \the\treetok
+ \end{tikzpicture}%
+}
\end{filecontentshere}
-\marginattach{}
+\marginattach
\filecontentsexec\filecontentsheremacro
-The |\tableofcontents| command appears just above the
-|tikzpicture| environment in a figure float (to make sure that the label of the
-table of contents
-refers to the same page as the one where the picture will actually be printed).
-We thus get the table of contents as a ``\hyperref[toc:molecule]{molecule}'',
-which
-appears \vpageref[above]{toc:molecule}.
-This \hyperref[toc:molecule]{TikZ TOC} is fully hyperlinked, like the
-previous
+The |\tableofcontents| command is executed prior to the |tikzpicture|
+environment which will actually typeset it via insertion of the accumulated
+data in the \csa{toks} register \csa{treetok}. This
+\hyperref[toc:molecule]{TikZ TOC} is fully hyperlinked, like the previous
\hyperref[toc:forest]{Forest TOC}.
+% Mercredi 01 mars 2023 à 23:27:29
+% arrrrrrgggghhh
+% desperate attempt to avoid an annoying varioref "may loop" error.
+% at last minute, arose from a suppression of a paragraph a few
+% dozen pages earlier.
+% [76]
+
+% ! Package varioref Error: \vref or \vpageref at page boundary 65-66 (may loop).
+
+% See the varioref package documentation for explanation.
+% Type H <return> for immediate help.
+% ...
+
+% l.6114 appears \vpageref{toc:mindmap}
+
+% mais ça n'a pas suffit. Bon 10 minutes de perdues je vais déplacer la ligne.
+
+\enlargethispage{3\baselineskip}
+Another example:
+
\etocsettocstyle
- {\treetok{\node {\autoref{part:globalcmds}}}}
+ {\treetok{\node {\autoref{sec:tocstyle}}}}
{\global\appendtotok\treetok{ ;}}
-\etocsetnexttocdepth {subsection}
-\tableofcontents \ref{toc:globalcmds}
+\etocsetnexttocdepth {subsubsection}
+\tableofcontents \ref{toc:tocstyle}
-\noindent
-\parbox{4cm}{\hypersetup{hidelinks}%
+\centeredline{%
+\hypersetup{hidelinks}
\begin{tikzpicture}
[grow cyclic,
level 1/.style={level distance=2.5cm,sibling angle=60},
@@ -3751,60 +5518,35 @@ previous
edge from parent path={[very thick,color=cyan]
(\tikzparentnode) --(\tikzchildnode)}]
\the\treetok
- \end{tikzpicture}}%
-\begin{minipage}{\dimexpr\linewidth-4cm\relax}
- On the side, the (fully hyperlinked) table of contents of
- \autoref{part:globalcmds}.
- \def\MacroFont{\ttfamily\small\hyphenchar\font-1 \baselineskip10pt\relax}%
-\begin{verbatim}
-\etocsettocstyle
- {\treetok{\node {\autoref{part:globalcmds}}}}
- {\global\appendtotok\treetok{ ;}}
-\etocsetnexttocdepth {subsection}
-\tableofcontents \ref{toc:globalcmds}
-\noindent
-\parbox{4cm}{\hypersetup{hidelinks}%
- \begin{tikzpicture}
- [grow cyclic,
- level 1/.style={level distance=2.5cm,sibling angle=60},
- level 2/.style={level distance=1cm,sibling angle=45},
- every node/.style={ball color=red!50,circle,text=black},
- edge from parent path={[very thick,color=cyan]
- (\tikzparentnode) --(\tikzchildnode)}]
- \the\treetok
- \end{tikzpicture}}%
-...
-\end{verbatim}
-\end{minipage}
+ \end{tikzpicture}
+}%
+%
+The above is the fully hyperlinked table of contents of
+\autoref{sec:tocstyle}.
\section{The TOC as a TikZ mind map}
\label{sec:mindmap}
This is in the same spirit as the ``molecule'' example. The use of the \eTeX{}
-primitive \csa{unexpanded} will simplify the code.\footnote{The ``molecule''
-example was added to this documentation on |2013/03/03|. The ``mindmap''
-example was motivated on |2015/03/11| by
-\url{http://tex.stackexchange.com/a/232584/4686}. Further help was then obtained via
-\url{http://tex.stackexchange.com/q/232816/4686} and this led to the
-\hyperref[toc:mindmaptitlepage]{title page} which is a further example.}
+primitive \csa{unexpanded} will simplify the code.%
+%
-\let\appendchildtree\relax
+\let\partnode\relax
\let\childnode\relax
\let\appendtotok\relax
+\let\appendchildtree\relax
\expandafter\let\csname c@partco\endcsname\relax
\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
-\begingroup
% \newtoks\treetok % done in preamble
% \newtoks\parttok
-
-\newcommand*\partnode {} % just to check we don't overwrite something
+\newcommand*\partnode {} % check with \newcommand we will not overwrite something
\newcommand*\childnode {}
-\newcommand*\tmprotate {} % just to check we don't overwrite something
-\newcommand*\tmpoption {} % just to check we don't overwrite something
-\newcommand*\tmpstuff {} % just to check we don't overwrite something
+\newcommand*\tmprotate {} % (idem)
+\newcommand*\tmpoption {} %
+\newcommand*\tmpstuff {} %
\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
#1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}}
@@ -3831,7 +5573,7 @@ example was motivated on |2015/03/11| by
\appendchildtree\treetok\parttok {branch color= green!50,level distance=10cm}%
\else
\ifcase\pseudomodthree{\value{partco}}%
- \or \appendchildtree\treetok\parttok {branch color= teal!60}% first
+ \or \appendchildtree\treetok\parttok {branch color= teal!30}% first
\or \appendchildtree\treetok\parttok {branch color= yellow!80}% second
\else\appendchildtree\treetok\parttok {branch color= green!50}% third and next ...
\fi\fi
@@ -3873,16 +5615,14 @@ example was motivated on |2015/03/11| by
% The \global above is mandatory because etoc always typesets TOC inside a group
\etocsetnexttocdepth{section}
-% use of depth tags to cut out some sections.
-\etocsettagdepth {preamble} {none}
+% use of depth tags to cut out sections for most parts, the sections
+% are too numerous to fit well with the circular growth
+\etocsettagdepth {preamble} {part}
\etocsettagdepth {overview} {part}
-\etocsettagdepth {arbitrarily}{part}
-\etocsettagdepth {examples} {section}
-\etocsettagdepth {surprising} {part}
-\etocsettagdepth {linestyles} {part}
-\etocsettagdepth {globalcmds} {part}
-\etocsettagdepth {custom} {section}
-\etocsettagdepth {tips} {part}
+\etocsettagdepth {styling} {part}
+\etocsettagdepth {control} {part}
+\etocsettagdepth {examples} {part}
+\etocsettagdepth {advanced} {part}
\etocsettagdepth {etocandworld}{part}
\etocsettagdepth {code} {section}
@@ -3893,7 +5633,8 @@ example was motivated on |2015/03/11| by
}
}%
-\begin{figure}[thp!]
+\begin{figure}[htbp!]
+\etocobeydepthtags % obey the depth tags restrictions (which is default anyhow)
\tableofcontents\label{toc:mindmap}%
\centeredline{\resizebox{.85\paperwidth}{!}%
{\begin{tikzpicture}[mindmap,
@@ -3903,25 +5644,29 @@ example was motivated on |2015/03/11| by
nodes={concept},
concept color=orange!60,
root concept/.append style={text width=4cm, font=\Large},
- level 1/.append style={level distance=5cm,sibling angle=40, text width=3cm},
+ level 1/.append style={level distance=5cm,sibling angle=45, text width=3cm},
level 2/.append style={level distance=7cm,sibling angle=30, text width=3cm},
level 1 concept/.append style={font=\normalsize},
]
\the\treetok
\end{tikzpicture}}}
\end{figure}
-\endgroup
\end{filecontentsdef}
\filecontentsexec\foo
It is difficult to get everything to fit on one page. However \csa{resizebox}
comes to the rescue. And it preserves hyperlinks. Nevertheless for this
example I excluded some sections from the display, using the technique of the
-\etoc \hyperref[etocdepthtag.toc]{depth tags}. The fully hyperlinked TOC
-appears \vpageref{toc:mindmap}.
+\etoc \hyperref[etocdepthtag.toc]{depth tags}.
+
+% The fully hyperlinked TOC
+% appears \vpageref{toc:mindmap}.
+
+\filecontentsprintviascan\foo
+\marginattach
+
+The fully hyperlinked TOC appears \vpageref{toc:mindmap}.
-\filecontentsprint\foo
-\marginattach{}
An interesting alternative is to use \etoc rather to convert the entire TOC
into a TikZ tree (perhaps excluding some parts) and print it out to a file
from which it can be recovered and manipulated directly by the author of the
@@ -3935,30 +5680,28 @@ example), this demo will write it out to file with extension
\immediate\openout\TOCasTree=\jobname.toctree
\immediate\write\TOCasTree{\the\treetok}%
\end{verbatim}
-The author can then copy it from there and customize it manually to get a
-suitable tikz picture. See also
-\centeredline{\url{http://tex.stackexchange.com/a/232792}}
-for an elaboration of this.
\section{The TOC as a (long) table}
\label{sec:tocastable}
-With release |1.08| it is easier to typeset a TOC as a table. It is
-possible to open a tabular in the title part of the TOC (first argument
-to \csb{etocsettocstyle}) and then close it after the contents (second
-argument to \csb{etocsettocstyle}), and specify in the line styles how
-to use the tabulation |&| and tabular end of row |\\|. There are some
-conditions and a few caveats:
+% With release \etocrelease{1.08} it is easier to typeset a TOC as a table.
+It is possible to open a \texttt{tabular} (or \texttt{longtable}) in the title part of the TOC
+(first argument to \csb{etocsettocstyle}) and then close it after the contents
+(second argument to \csb{etocsettocstyle}), and specify in the line styles how
+to use the tabulation |&| and tabular end of row |\\|.
+But there are some conditions and a few caveats:
\begin{enumerate}
-\item it is mandatory to issue \csb{etocglobaldefs} for \etoc's
- definitions to have global scope,
+\item it is \textbf{mandatory} to issue \csb{etocglobaldefs} for \etoc's
+ definitions of \csb{etocname} et al. to have global scope, i.e. not be
+ extinguished on encountering a |&|,
\item it is impossible to start one of the \meta{start}, \meta{prefix},
\meta{contents} or \meta{finish} specification with a sole |\hline|,
- \emph{i.e.} one not preceded by a |\\| (it is however possible to put
- |\\| at the end of \meta{prefix} and the |\hline| at the start of
- \meta{contents}).
+ \emph{i.e.} one not preceded by a |\\|,
+ % (it is however possible to put
+ % |\\| at the end of \meta{prefix} and the |\hline| at the start of
+ % \meta{contents}).
\item as is explained next, it is recommended to put the
|\\| at the start of the \meta{prefix} or \meta{contents}
specifications in order to close the \emph{previous} row, rather
@@ -3967,8 +5710,8 @@ conditions and a few caveats:
is (in almost all situations) mandatory.
\end{enumerate}
-Here is an example of a TOC as a |longtable| (yes this is only \emph{one} table),
-as is possible relatively simply now with |1.08|. The code follows.
+Here is an example of a TOC as a |longtable|. Yes this is only \emph{one} table!
+The code follows.
\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo}
\begingroup
@@ -4002,7 +5745,7 @@ as is possible relatively simply now with |1.08|. The code follows.
{}
{}
{\\\hline\multicolumn{3}{c}{\bfseries\vrule height6ex depth3ex width0pt
- \etocifnumbered{\etocnumber. }{}\etocname}}
+ \makebox[0pt]{\etocifnumbered{\etocnumber. }{}\etocname}}}
{}
\etocsetstyle{section}
@@ -4035,8 +5778,9 @@ as is possible relatively simply now with |1.08|. The code follows.
\filecontentsexec\foo
-\filecontentsprint\foo
-\marginattach{-A}
+\filecontentsprintviascan\foo
+\marginattach
+
Examining the code above the reader will wonder why the |\\| are
always given first in \meta{prefix+contents} and not, as is more
intuitive, rather last. In some favorable cases (but almost never
@@ -4084,8 +5828,8 @@ contents.
{}
\etocsettocstyle
- {\hypersetup{hidelinks}\begin{tabular}{|p{4cm}|c|c|}\hline
- \multicolumn{1}{|c|}{\bfseries Section}&
+ {\hypersetup{hidelinks}\begin{tabular}{|>{\RaggedRight}p{4.5cm}|c|c|}\hline
+ \multicolumn{1}{|c|}{\bfseries Section title}&
\bfseries number&
\bfseries page}
{\\\hline\end{tabular}}
@@ -4099,8 +5843,8 @@ contents.
\filecontentsexec\foo
-\filecontentsprint\foo
-\marginattach{-B}
+\filecontentsprintviascan\foo
+\marginattach
\section{A TOC self-adjusting widths for its typesetting}
\label{sec:thirdexampleextra}
@@ -4138,13 +5882,15 @@ automatically the ``numwidths'' used for typesetting the unit numbers in the
{\setbox0\hbox{\etocthenumber\kern#2}}
{\ifdim\wd0>\TOCnumwidthG\edef\TOCnumwidthG{\the\wd0}\fi}{}%
%
- \etocsettocstyle{}
+ \etocsettocstyle
+ {}
{\global\let\TOCnumwidthB\TOCnumwidthB
\global\let\TOCnumwidthC\TOCnumwidthC
\global\let\TOCnumwidthD\TOCnumwidthD
\global\let\TOCnumwidthE\TOCnumwidthE
\global\let\TOCnumwidthF\TOCnumwidthF
- \global\let\TOCnumwidthG\TOCnumwidthG}%
+ \global\let\TOCnumwidthG\TOCnumwidthG
+ }% make the found maximal widths have global scope
\etocnopar
\csname #1tableofcontents\endcsname
\typeout{Next TOCs will use \TOCnumwidthB\space for chapter number width}%
@@ -4153,7 +5899,7 @@ automatically the ``numwidths'' used for typesetting the unit numbers in the
\typeout{Next TOCs will use \TOCnumwidthE\space for subsubsection number width}%
\typeout{Next TOCs will use \TOCnumwidthF\space for paragraph number width}%
\typeout{Next TOCs will use \TOCnumwidthG\space for subparagraph number width}%
- \endgroup
+ \endgroup % matches \begingroup at start of definition
}%
\newcommand*\TOCcomputenumwidths [1][0.5em]{%
\TOCcompute@numwidths {}{#1}%
@@ -4163,7 +5909,8 @@ automatically the ``numwidths'' used for typesetting the unit numbers in the
}%
\makeatother
\end{filecontentshere}
-\marginattach{}
+\marginattach
+
The optional parameter to \csa{TOCcomputenumwidths} specifies the minimal
indent. In case nothing is numbered you may wish a higher value than |0.5em|.
For each local table of contents to have its own width computations, the macro
@@ -4195,1543 +5942,6 @@ Notes:
|local|.
\end{enumerate}
-\clearpage
-\etocdepthtag.toc {linestyles}
-
-\part{Commands for the toc line styles}
-\label{part:linestyles}
-
-\thispartstats
-
-\etocsetstyle{section}
-{\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered
- {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]}
-{\normalsize\bfseries\rmfamily\item}
-{\etocname{} (page \etocpage)}
-{\end{enumerate}}
-
-\etocsetstyle{subsection}
-{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]}
-{\normalfont \item}
-{\etocname{} (p.~\etocpage)}
-{\end{enumerate}}
-
-\etocsetstyle{subsubsection}
-{\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix}
-{\allowbreak\,--\,}
-{\etocname}
-{.\hfil\par\endgroup\pagebreak[3]}
-
-% 27 janvier 2013 22:30
-% je définis les macros (non protégées)
-% \etocthename, \etocthenumber, \etocthepage
-
-\etocruledstyle[1]{\etocfontminusone\color{green}%
- \fboxrule1pt\fboxsep1ex
- \framebox[\linewidth]
- {\normalcolor\hss Contents of \autoref{part:linestyles}\hss}}
-
-\localtableofcontents \label{toc:a}
-
-\section{The \csbhyp{etocsetstyle}, \csbhyp{etocname} and \csbhyp{etocpage} commands}\label{sec:etocsetstyle}
-\label{etocsetstyle}
-\label{etocname}
-\label{etocpage}
-
-Let us explain how \etoc was used to produce the table of
-contents displayed at the beginning of this \autoref{part:linestyles}.
-This
-is a local table of contents, and we used the command \localtoc.
-
-
-We shall distinguish between the \emph{line styles} and the
-\emph{toc display style}. The line styles were (essentially)
-obtained in the following manner:%
-\footnote{the present document has
- {\ttfamily\string\renewcommand\string{%
- \string\familydefault\string}\string{\string\sfdefault\string}}
- in its preamble, hence \csa{normalfont} switches to the
- |sans| typeface; so in the section line-style, I wrote
- \csa{rmfamily} instead.}
-
-\begingroup\small
-\begin{filecontentshere}{etocsnippet-\snippetno.tex}
-\etocsetstyle{section}
-{\begin{enumerate}}
-{\normalsize\bfseries\rmfamily\item}
-{\etocname{} (page \etocpage)}
-{\end{enumerate}}
-
-\etocsetstyle{subsection}
-{\begin{enumerate}}
-{\normalfont\item}
-{\etocname{} (p.~\etocpage)}
-{\end{enumerate}}
-
-\etocsetstyle{subsubsection}
-{\par\nobreak\begingroup\normalfont
- \footnotesize\itshape\etocskipfirstprefix}
-{\allowbreak\,--\,}
-{\etocname}
-{.\hfil\par\endgroup\pagebreak[3]}
-\end{filecontentshere}
-\marginattach{}
-\endgroup
-
-These provisory style definitions rely on the automatic
-numbering generated by the |enumerate| environments but it is
-much better to use the further command \csb{etocnumber} inside
-the item label, which gives the real thing. The improved
-definitions will thus be explained later.
-
-With this style, one would have
-to be imaginative to design something then for paragraph and
-subparagraph entries! perhaps as superscripts? Well, usually
-one does not need paragraphs and subparagraphs numbered and
-listed in the TOC, so our putative user here chose a design
-where no provision is made for them and added the definitive:
-\begin{verbatim}
-\etocsetstyle{paragraph}{}{}{}{}
-\etocsetstyle{subparagraph}{}{}{}{}
-\end{verbatim}
-This is also the situation with the default package line styles!
-
-Each \csb{etocsetstyle} command has five mandatory arguments:
-\centeredline
-{\csb{etocsetstyle}\color{blue}\marg{levelname}%
- \marg{start}\marg{prefix}\marg{contents}\marg{finish}}
-The initially recognized \meta{levelname}'s are the sectioning
-levels of the standard document classes: from \emph{part} (or
-\emph{book} which is used by the \ctanpkg{memoir} class) down to
-\emph{subparagraph}.
-
-The \meta{start} code is executed when a toc entry of that level is
-encountered and the previous one was at a higher level. The
-\meta{finish} code is executed when one again encounters a higher
-level toc entry. In the meantime all entries for that level are
-typeset by executing first the \meta{prefix} code and then the
-\meta{contents} code.
-
-The (robust) commands \csb{etocname}, \csb{etocnumber} and \csb{etocpage} are
-provided for use inside the \meta{prefix} and \meta{contents} parts of the
-\csb{etocsetstyle} specification. They represent of course, the name, number,
-and page number of the corresponding toc entry. If package \ctanpkg{hyperref} is
-active in the document and has added hyperlinks to the TOC data, then these
-links are kept in the commands \csb{etocname}, \csb{etocnumber} and
-\csb{etocpage} (this last one will have a link only if \ctanpkg{hyperref} was passed
-either option \emph{linktoc=all} or option \emph{linktoc=page}.)%
-%
-\footnote{As expected, in case of \emph{linktoc=page}, only \csb{etocpage} is
-an hyperlink, not \csb{etocname} nor \csb{etocnumber}. See \csb{etoclink} on
-how to create hyperlinks with the entry target.}
-%
-In accordance with the \ctanpkg{hyperref} native behavior, no
-link gets incorporated into \csb{etocpage} if the page number is empty.
-
-\section{The \csbhyp{etocskipfirstprefix} and \csbhyp{etociffirst} commands}
-\label{etocskipfirstprefix}
-\label{etociffirst}
-\label{etocxiffirst}
-
-The chosen |subsubsection| style made use of the command
-\csb{etocskipfirstprefix}, which instructs \etoc to \emph{not} use
-for the first item the specified \meta{prefix} code.\footnote{With
-versions earlier than |1.08| it had to be the very last token in
-the \meta{start} code. It may now appear anywhere therein.}
-
-The command \csb{etociffirst}\marg{YES CODE}\marg{NO CODE} (new
-with |1.08|) is a more flexible way to customize the \meta{prefix}
-(and \meta{contents}) specifications. It executes the \meta{YES
-CODE} branch if this is the first unit at that level (inside a
-lower level) and the \meta{NO CODE} if not. This is a robust
-command which survives to expansion (for example in an |enumitem| label).
-
-The variant \csb{etocxiffirst} does the same, but is expandable.
-
-
-\section{The \csbhyp{etocnumber} command}
-\label{etocnumber}
-
-So far, our specifications would use the numbering generated
-by the |enumerate| environments, but of course we generally want
-the actual numbers as found in the |.toc| file. This is
-available via the \csb{etocnumber} command. To get the labels
-in the |enumerate| list to use it we can proceed with the
-syntax {\ttfamily label=\char32} from the package |enumitem|:
-\begin{verbatim}
-\etocsetstyle{section}
-{\begin{enumerate}[label=\etocnumber]}
-{\normalsize\bfseries\rmfamily\item}
-{\etocname{} (page \etocpage)}
-{\end{enumerate}}
-\end{verbatim}
-Rather than just \csb{etocnumber} we then used something like
-|\fbox{\etocnumber}|. Note that \csb{etocnumber} is a robust
-command which explains why it can be used inside the label specification
-without needing an added |\protect|.
-
-
-\section{The \csbhyp{etocifnumbered} switch}
-\label{etocifnumbered}
-\label{etocxifnumbered}
-
-The \csa{fbox} would give an unaesthetic result in the case of
-an unnumbered section (which ended up in the table of
-contents via an \csa{addcontentsline} command).\footnote{as
- seen we use \csa{fcolorbox} rather than \csa{fbox}. Due
- to some redefinition made by package |xcolor|, had we used
- \csa{fbox} (and not used \ctanpkg{hyperref}) we would have needed
- \csa{protect}\csa{fbox}.}
-
-The \csb{etocifnumbered}\marg{A}\marg{B} command executes
-\meta{A} if the number exists, and \meta{B} if not. So we use
-it in the code which was finally chosen for the |section| level:
-\begin{verbatim}
-\etocsetstyle{section}
-{\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered
- {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]}
-{\normalsize\bfseries\rmfamily\item}
-{\etocname{} (page \etocpage)}
-{\end{enumerate}}
-
-\etocsetstyle{subsection}
-{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]}
-{\normalfont \item}
-{\etocname{} (p.~\etocpage)}
-{\end{enumerate}}
-\end{verbatim}
-
-If we had changed only the |section| level, and not the
-|subsection| level, an error on compilation would have occurred
-because the package style for subsections expects to start `in
-vertical mode'. An additional \csa{par} token in the
-\meta{contents} part of the |section| level would have fixed
-this: |{...(page \etocpage)\par}|.
-
-The command \csb{etocifnumbered} is robust; \csb{etocxifnumbered}
-(new with |1.08|) has the same effect but is expandable.
-
-
-\section{The \csbhyp{etocthename}, \csbhyp{etocthenumber}, and
-\csbhyp{etocthepage} commands}
-\label{etocthename}
-\label{etocthenumber}
-\label{etocthepage}
-
-It is sometimes desirable to have access to the name, number and page
-number without the hyperref link data: something similar to the starred
-variant of the \csa{ref} command, when package \ctanpkg{hyperref} is used. For
-example one may wish to use the unit or page number in some kind of
-numeric context, or change its formatting. This is provided by
-\csb{etocthename}, \csb{etocthenumber}, and \csb{etocthepage}.
-
-These commands are not protected, so in moving argument
-contexts (for example in a label specification) they should be
-preceded by |\protect|.
-
-\section{The \csbhyp{etoclink} command}
-\label{etoclink}
-
-The command \csb{etoclink}\marg{text} can be used in the line style
-specifications in a manner analogous to \csb{etocname}, \csb{etocnumber} and
-\csb{etocpage}. It creates a link (if \ctanpkg{hyperref} is present%
-%
-\footnote{Prior to \texttt{1.1a}, no such link was added if the \texttt{.toc}
- file entry was encountered
- with \ctanpkg{hyperref}'s option \texttt{linktoc} set to \texttt{none}.})
-%
-whose target is the corresponding document unit and
-whose name is the given \meta{text} mandatory argument.
-
-Hence |\etoclink{\etocthename}| is under default conditions of \ctanpkg{hyperref} like
-the original \csb{etocname}, because the latter is already hyperlinked. Under
-\emph{linktoc=page} context |\etoclink{\etocthename}| adds the hyperlink which
-is missing from \csb{etocname}. Similarly under the default \ctanpkg{hyperref}
-condition (i.e.\@ \emph{linktoc=section}) \csb{etocpage} is not an hyperlink, but one
-can use |\etoclink{\etocthepage}|.
-
-The command \csb{etoclink} is robust.
-
-% Since |etoc 1.08j| it contains the link
-% destination in an already expanded form, so for example can be used even after
-% a |&| in a tabular construction, if \csb{etocglobaldefs} was issued.
-
-
-
-
-\makeatletter\scr@activate@xsection{1}\makeatother
-% [] goes to head but {} to toc
-
-% What would really be useful is an option for the length of {} to be measured
-% and opt for [] only if does not fit on one header line
-\section[The \csbhyp{etocthelinkedname} et al.\protect\@{} commands]
- {The \csbhyp{etocthelinkedname}, \csbhyp{etocthelinkednumber},
- \csbhyp{etocthelinkedpage} and \csbhyp{etocthelink} commands}
-\label{etocthelinkedname}
-\label{etocthelinkednumber}
-\label{etocthelinkedpage}
-\label{etocthelink}
-
-\makeatletter\scr@activate@xsection{0}\makeatother
-
-The meanings of these commands
-can be stored for delayed usage. For example this is
-done in the \hyperref[tocastree]{examples with trees}.
-
-There has been a \textbf{breaking change} at |1.1a|. Here is the behavior
-\emph{prior} to this release:
-\begin{itemize}[noitemsep]
-\item \csb{etocthelinkedname} and \csb{etocthelinkednumber} were hyperlinks
- only if \ctanpkg{hyperref} was configured via |linktoc=all| or
- |linktoc=section| (the default),
-\item \csb{etocthelinkedpage} was an hyperlink only if \ctanpkg{hyperref} was
- configured via |linktoc=all| or |linktoc=page| and the page number was not empty.
-\end{itemize}
-This behavior was coherent with the commands \csb{etocname}, \csb{etocnumber},
-and \csb{etocpage} being the robust variants of \csb{etocthelinkedname},
-\csb{etocthelinkednumber}, and \csb{etocthelinkedpage}.
-
-At |1.1a| it was decided that the commands should match their denominations.%
-%
-\footnote{To tell the whole truth, the author in refactoring the code completely at \texttt{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.}
-%
-So they are now \emph{always} hyperlinks independently of |linktoc| \ctanpkg{hyperref}
-option (\csb{etocthelinkedpage} has no hyperlink if the page number is empty,
-to match \ctanpkg{hyperref} behavior):
-\begin{itemize}[noitemsep]
-\item \csb{etocthelinkedname} and \csb{etocthelinkednumber} and
- \csb{etocthelinkedpage} are always (in presence of \ctanpkg{hyperref})
- hyperlinks (for \csb{etocthelinkedpage} the page number must not be empty).
-\end{itemize}
-
-
-A further command is provided: \csb{etocthelink}, which wraps%
-%
-\footnote{Prior to \texttt{1.1a}, there was a link added only if \ctanpkg{hyperref} option \texttt{linktoc} was not \texttt{none}.}
-%
-an hyperlink around its argument: |\etocthelink|\marg{foo} hyperlinks an
-arbitrary text \meta{foo} to the target sectioning unit in the document.
-The command \csb{etoclink} is its robust variant.
-
-
-Obsolete example of \begingroup
- \etocsetstyle {section}
- {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
- {\global\let\TmpEtocNumber\etocthelinkednumber
- \global\let\TmpEtocName\etocthelinkedname
- \global\let\TmpEtocPage\etocthelinkedpage }
- {\item [{\bfseries\TmpEtocNumber.}]\TmpEtocName\
- (\emph{p. \TmpEtocPage})}
- {\end{itemize*}.}%
- \etocsetnexttocdepth {section}%
- \etocsettocstyle {a table of contents done as an inline
- \ctanpkg{enumitem} environment: }{}%
- \etocinline\tableofcontents \ref{toc:globalcmds}
-\endgroup
-
-\begin{verbatim}
-Obsolete example of \begingroup
- \etocsetstyle {section}
- {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
- {\global\let\TmpEtocNumber\etocthelinkednumber
- \global\let\TmpEtocName\etocthelinkedname
- \global\let\TmpEtocPage\etocthelinkedpage }
-% (the above needed as \item closes a group in enumitem inline environments)
- {\item [{\bfseries\TmpEtocNumber.}]\TmpEtocName\
- (\emph{p. \TmpEtocPage})}
- {\end{itemize*}.}%
- \etocsetnexttocdepth {section}%
- \etocsettocstyle {a table of contents done as an inline
- \texttt{enumitem} environment: }{}%
- \etocinline\tableofcontents \ref{toc:globalcmds}
-\endgroup
-\end{verbatim}
-
-\etoc |1.08a| offers a simpler way to the same result: thanks to
-\csb{etocglobaldefs} there is no need
-anymore here for \csb{etocthelinkedname}, as \csb{etocname} works.
-\begin{verbatim}
-Example of
-\begingroup\etocglobaldefs % <-- NEW mit etoc 1.08.
- \etocsetstyle {section}
- {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
- {}
- {\item [{\bfseries\etocnumber.}] \etocname\ (\emph{p. \etocpage })}
- {\end{itemize*}.}%
- \etocsetnexttocdepth {section}%
- \etocsettocstyle {a table of contents done as an inline
- \texttt{enumitem} environment: }{}%
- \etocinline\tableofcontents \ref{toc:globalcmds}
-\endgroup
-\end{verbatim}
-Example of
-\begingroup\etocglobaldefs % <-- NEW mit etoc 1.08.
- \etocsetstyle {section}
- {\begin{itemize*}[itemjoin={{; }}, itemjoin*={{, and }}]}
- {}
- {\item [{\bfseries\etocnumber.}]
- \etocname\ (\emph{p. \etocpage })}
- {\end{itemize*}.}%
- \etocsetnexttocdepth {section}%
- \etocsettocstyle {a table of contents done as an inline
- \ctanpkg{enumitem} environment: }{}%
- \etocinline\tableofcontents \ref{toc:globalcmds}
-\endgroup
-
-\section{DEPRECATED \csbhyp{etocsavedsectiontocline}, etc... commands.}
-\label{etocsavedsectiontocline}
-\label{etocsavedchaptertocline}
-
-Prior to |1.1a|, \etoc modified (locally) at each \csb{tableofcontents} or
-\csb{localtableofcontents} encountered the meaning of the \LaTeX\ internal
-commands |\l@part|, |\l@chapter|, |\l@section|, etc... It stored (since |1.08k|)
-their original meanings (at the time of the encountered TOC), into
-\csb{etocsavedchaptertocline}, \csb{etocsavedsectiontocline}, etc... commands,
-which allowed to do some simple changes via \etoc of the rendering via the
-technique explained in \autoref{sec:anothercompat}.
-
-This is all obsolete at |1.1a| because \etoc does not modify anymore (even
-locally) |\l@part|, |\l@chapter|, |\l@section|, etc... so they can be used
-directly in the context of the techniques of \autoref{sec:anothercompat}.
-
-Thus \csb{etocsavedchaptertocline}, \csb{etocsavedsectiontocline},
-etc... raise some warning that they will be removed at some later release and
-that you should stop using them.
-
-\section{The \csbhyp{etocsetlevel} command}
-\label{etocsetlevel}
-
-As already explained in \autoref{part:surprising}, one
-can inform \etoc of a level to associate to a given sectioning
-command with \csb{etocsetlevel}. For example:
-\begin{verbatim}
-\etocsetlevel{cell}{0}
-\etocsetlevel{molecule}{1}
-\etocsetlevel{atom}{2}
-\etocsetlevel{nucleus}{3}
-\end{verbatim}
-In compatibility mode, it will be assumed that the commands |\l@cell|,
-|\l@molecule|, ..., have been defined somewhere either by the user or a class:
-doing only |\etocsetlevel| is not enough for the corresponding level to work
-out-of-the-box in compatibility mode.
-
-However, if no table of contents is typeset in compatibility mode, then all that
-matters is that the various line styles have been set. If, for example
-|section| is at level |1|, then there is no need to do some
-\csb{etocsetstyle}|{molecule}{..}{..}{..}{..}| after
-\csb{etocsetlevel}|{molecule}{1}| if
-\csb{etocsetstyle}|{section}{..}{..}{..}{..}| has already been done (and it has
-been done by the package itself in its definition of its own line styles).
-
-The accepted levels run from |-2| to |6| inclusive. Anything else is
-mapped to |6|, which is a dummy level, never displayed. The package
-does:
-\begin{verbatim}
-\etocsetlevel{book}{-2}
-\etocsetlevel{part}{-1}
-\etocsetlevel{chapter}{0}
-\etocsetlevel{section}{1}
-\etocsetlevel{subsection}{2}
-\etocsetlevel{subsubsection}{3}
-\etocsetlevel{paragraph}{4}
-\etocsetlevel{subparagraph}{5}
-\end{verbatim}
-\etoc own custom styles are activated by \csb{etocdefaultlines}. They
-are illustrated by the main table of contents of this
-document.
-
-These level assignments can be modified at anytime: see
-\autoref{part:surprising} for various applications of this
-technique. As one
-further example, let's mention here that the \hyperref[toc:main]{main table of
-contents} of this document was typeset following these instructions:
-\begin{filecontentshere}{etocsnippet-\snippetno.tex}
-\etocsettocdepth {subsubsection} % set the initial tocdepth
-\etocdefaultlines % use the package default line styles. At this early stage in
- % the document they had not yet been modified by \etocsetstyle
- % commands, so \etoctoclines could have been used, too.
-\etocmarkboth\contentsname
-\etocmulticolstyle[1] % one-column display
- {\pdfbookmark[1]{Table of contents}{MAINTOC}% create a bookmark in the pdf
- \noindent\bfseries\Large
- \leaders\hrule height1pt\hfill
- \MakeUppercase{Table of Contents}}
-\begingroup % use a group to limit the scope of the
- \etocsetlevel{subsection}{3} % subsection level change.
- \etocsetlevel{subsubsection}{4} % anything > tocdepth=3.
- \tableofcontents \label{toc:main}
-\endgroup
-\end{filecontentshere}
-\marginattach{}
-In this way, the subsections used the style originally designed for
-subsubsections, the subsubsections were not printed. Without this modification,
-the appearance would have been very different: the package line styles were
-targeted to be employed in documents with many many sub-sub-sections, in a
-two-column layout, giving thus a more compact output that what is achieved by
-the default \LaTeX{} table of contents. But here, we have few sub-sub-sections
-and it is more interesting to drop them and print in a visually different manner
-sections and subsections.
-
-
-\section{Scope of commands added to
- the \texorpdfstring{\texttt{.toc}}{.toc} file}
-
-\begingroup % pour \small et \MacroFont en particulier.
-\small
-
-\subsection{Testing the scope}
-
-Let us switch to the color red, and also add this command to the |.toc| file:
-
-\color{red!50}
-\addtocontents{toc}{\string\color{red!50}}
-
-\def\MacroFont{\ttfamily \footnotesize\hyphenchar\font45 }
-\begin{verbatim}
- \color{red!50} % changing text color
- \addtocontents{toc}{\string\color{red!50}} % and also in the .toc file
-\end{verbatim}
-
-
-\subsection{This is a (pale) red subsection for illustrative purposes}
-
-Actually, this title here was printed black, due to the way the \ctanpkg{scrartcl} class
-works (it would have been red in the |article| class), but we are more
-interested in how it looks in the tables of contents: it does appear red in the
-\hyperref[toc:main]{main table of contents} at the beginning of
-this document, and also in the \hyperref[toc:a]{table of
-contents for this part}. Both entries obey as expected the
-|\color{red!50}| command inserted in the |.toc| file.
-
-But let us now close this subsection and start a section.
-
-
-\section{Am I also red?}
-
-The question is about how it appears in the tables of contents: the answer is
-that, yes it is red in the \hyperref[toc:main]{main TOC}, and no
-it is not red in the \hyperref[toc:a]{local TOC for this part}.
-The reason is that the \meta{finish} code for the subsection level closed a
-group, as it used |\end{enumerate}|.
-
-This illustrates the discussion from \autoref{ssec:limitations}.
-
-The default package line styles do not contain group opening and closing
-instructions: the influence of a command added to the |.toc| file will propagate
-until cancelled by another explicit such command inserted in the |.toc|
-file.
-
-\begin{verbatim}
- \normalcolor
- \addtocontents{toc}{\string\normalcolor}
-\end{verbatim}
-\endgroup
-
-\normalcolor
-\addtocontents{toc}{\string\normalcolor}
-
-Back to black. Note that this scope problem arises in real life in a
-multi-lingual document, as the \ctanpkg{babel} package writes to the |.toc| file the
-language changes occurring in the document.
-
-
-\clearpage
-\etocdepthtag.toc {globalcmds}
-
-\part{Commands for the toc display style}
-\label{part:globalcmds}
-
-\thispartstats
-
-\etocsettocstyle{}{}
-\etocstandardlines
-\localtableofcontents \label{toc:globalcmds}
-
-
-\section{Specifying the toc display style}
-
-
-The \emph{toc display} style says whether the TOC appears with
-multiple columns or just one, whether the title is typeset as
-in the |article| or |book| class, or should be centered above
-the entries, with rules on its sides, or if the entire TOC
-should be put in a frame. For example, to opt for a ruled
-heading and single column layout, one issues commands of the
-following type:
-\begin{verbatim}
-\etocruledstyle[1]{Title} \tableofcontents (or \localtableofcontents)
-shortcuts: \etocruled[1]{Title} (or \etoclocalruled[1]{Title})
-\end{verbatim}
-
-\subsection{The command \csbhyp{etocsettocstyle}}
-\label{etocsettocstyle}
-
-This is a command with two mandatory arguments:\\
-\centeredline{\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}
-The \marg{before\_toc} part is responsible for typesetting the
-heading, for example it can be something like
-\starit{section}|{\contentsname}|.
-
-Generally speaking this heading
-should leave \TeX{} in ``vertical mode'' when the actual
-typesetting of the contents will start: the line styles (either
-from the standard classes or the package default line styles)
-all expect to get started in `vertical mode'.
-
-The first argument to \csb{etocsettocstyle} can also contain
-instructions to mark the page headings. Or
-it could check (book class) to see if two-column mode is on,
-and switch to one-column style, and the \meta{after\_toc} part
-would then reenact the two-column mode.
-
-\textbf{\TeX\ hacker note:} We have seen in the previous chapter some examples
-of using |\begin{enumerate}| and |\end{enumerate}| within TOC line styles.
-There is a real difficulty with doing however something like this:
-\begin{verbatim}
-\etocsettocstyle{\begin{enumerate}}{\end{enumerate}}
-\etocsetstyle{section}{}{\item \sectionname}{}{}
-\end{verbatim}
-Indeed for example on first compilation of a document, the |.toc| file is
-empty and there will be the typical ``Something's wrong--perhaps a missing
-\string\item''. Using \csb{etocchecksemptiness} does not help, because as is
-explained there, on first encountering a new TOC added at end of a document,
-\etoc considers it non-empty, hence querying \csb{etocifwasempty} serves
-nothing. No, one must do something like this:
-\begin{verbatim}
-\makeatletter
-\etocsettocstyle
- {\begin{enumerate}}
- {\if@newlist\item Please run \LaTeX\ again\fi
- \end{enumerate}}
-\makeatother
-\etocsetstyle{section}{}{\item \sectionname}{}{}
-\end{verbatim}
-
-The commands to be described next \csb{etocmulticolstyle},
-\csb{etocruledstyle}, and \csb{etocframedstyle} all call
-\csb{etocsettocstyle} as a lower-level routine, to start a
-\texttt{multi\-cols} environment in \marg{before\_toc} and close it in
-\marg{after\_toc}.
-
-\subsection{The commands \csbhyp{etocmulticolstyle}, \csbhyp{etocmulticol}, and \csbhyp{etoclocalmulticol}}
-\label{etocmulticolstyle}
-\label{etocmulticol}
-\label{etoclocalmulticol}
-
-This is a command with one optional and one mandatory argument:
-\centeredline{\csb{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}}
-The
-\meta{number\_of\_columns} can go from 1 to 10 (it defaults to 2; if its
-value is 1, naturally no |multicols| environment is then created). The
-\meta{heading} will typically be some `vertical' material like:
- \meta{heading} = |\section*|\marg{title}
-but one may also have horizontal material like |\fbox{Hello World}| (\etoc
-adds automatically a |\par| at the end of this ``heading'' argument to
-\csb{etocmulticolstyle}). Here is for example
-how the main table of contents of this document was
-configured:
-\begin{verbatim}
-\etocmulticolstyle{\noindent\bfseries\Large
- \leaders\hrule height1pt\hfill
- \MakeUppercase{Table of Contents}}
-\end{verbatim}
-After \csb{etocmulticolstyle} all future \csa{tableofcontents} will use the
-specified style, if it does not get changed in-between. A shortcut for
-just one table of contents and
-no impact on the styles of later TOCs is:
-\centeredline{\csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading}}
-And there is also
-\csb{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}.
-
-\subsection{The command \csbhyp{etoctocstyle}}
-\label{etoctocstyle}
-
-\centeredline{\csb{etoctocstyle}\oarg{kind}%
-\marg{number\_of\_columns}\marg{title}}
-\centeredline{=
-\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
-|{\kind*{|\itshape title\upshape|}}|}
-where |kind| is one of |chapter|, |section|, . . . and defaults
-to |chapter| or |section| depending on the document class.
-
-\subsubsection{The command \csbhyp{etoctocstylewithmarks}}
-\label{etoctocstylewithmarks}
-\label{etoctocstylewithmarksnouc}
-
-\centeredline{\csb{etoctocstylewithmarks}\oarg{kind}%
-\marg{number\_of\_columns}\marg{title}\marg{mark}}
-\centeredline
-{=\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
-|{\kind*{|\itshape title \ttfamily\upshape\string\markboth%
-|{\MakeUppercase{|{\rmfamily\itshape mark}|}}}}|}
-where |kind| is one of |chapter|, |section|, ... The
-actual display of the marks depends on the settings of the
-page style. There is variant \csb{etoctocstylewithmarksnouc}
-which does not uppercase.
-
-\paragraph{Do we really want paragraph entries in the TOC?}
-
-\paragraph{really?}
-
-\subsection{The commands \csbhyp{etocruledstyle}, \csbhyp{etocruled} and \csbhyp{etoclocalruled}}
-\label{etocruledstyle}
-\label{etocruled}
-\label{etoclocalruled}
-
-The general format of \csb{etocruledstyle} is:\\
-\centeredline{\csb{etocruledstyle}%
-\oarg{number of columns}\marg{title of the toc}}
-\noindent
-The title is horizontal material (the |LR| mode of
-\emph{\LaTeX{}, a document preparation system}): if it
-does not fit on one line it should be put in a \csa{parbox} of
-a given width.
-The green frame for the heading of the table of contents at
-the \hyperref[toc:a]{start of the second part of this
- document} was obtained with:
-\begin{verbatim}
-\etocruledstyle[1]{\etocfontminusone\color{green}%
- \fboxrule1pt\fboxsep1ex
- \framebox[\linewidth]
- {\normalcolor\hss Contents of this part\hss}}
-\end{verbatim}
-
-
-As a shortcut to set the style with \csb{etocruledstyle} and
-then issue a
-\toc, all inside a group
-so that future table of contents will not be
-affected, there is:
-\centeredline{\csb{etocruled}\oarg{number\_of\_columns}\marg{title}}
-And the local form will be \csb{etoclocalruled}.
-
-\subsection{The commands \csbhyp{etocframedstyle}, \csbhyp{etocframed}, and \csbhyp{etoclocalframed}}
-\label{etocframedstyle}
-\label{etocframed}
-\label{etoclocalframed}
-
-Same mechanism:
-\centeredline{\csb{etocframedstyle}%
- \oarg{number\_of\_columns}\marg{title}}
-and the accompanying shortcut:
-\centeredline{\csb{etocframed}\oarg{number\_of\_columns}\marg{title}} The
-shortcut is used if one does not want to modify the style of the next
-TOCs (the other way is to put the whole thing inside braces or a
-|\begingroup...\endgroup|; there is also \csb{etoclocalframed} for a
-local table of contents).
-
-The entire table of contents is framed. The title itself is not framed:
-if one wants a frame one should set it up inside the \meta{title}
-argument to \csb{etocframedstyle} or \csb{etocframed}. The colors for
-the background and for the components (top, left, right, bottom) of the
-border are specified via suitable |\renewcommand|'s (see
-\autoref{ssec:customdisplay}).
-
-A |minipage| is used, hence the produced table of contents isn't
-compatible with a page break. For allowing page breaks, use of
-the commands of
-\ctanpkg{mdframed}
-or
-\ctanpkg{tcolorbox}
-in the arguments of \csb{etocsettocstyle}
-is recommended.
-
-Examples in this document are on pages \pageref{toc:d},
-\pageref{toc:floating}, \pageref{toc:b}, and \pageref{toc:clone}.
-
-
-\subsection{Headings, titles, \csbhyp{etocoldpar}, \csbhyp{etocinnertopsep}}
-\label{etocinnertopsep}
-\label{etocoldpar}
-
-For \csb{etocmulticolstyle} the mandatory \meta{heading} argument can be
-either
-vertical mode material like |\section*{\emph{Table of Contents}}| or
-horizontal mode material like in the simple |\etocmulticolstyle{Hello World}|.
-
-No explicit |\par| or empty line can be inserted in the mandatory
-argument of \csb{etocmulticolstyle}, but \etoc provides \csb{etocoldpar}
-as a substitute: it does |\let\etocoldpar\par| before the |multicols|
-environment and inserts this |\etocoldpar|\footnote{this command
- \csb{etocoldpar} (= working \csa{par} in the argument to
- \csb{etocmulticolstyle}) is not related to the switch \csb{etocinline}
- whose purpose is to tell \etoc not to do a \csa{par} before the table
- of contents.} at the end of the heading, then does a vertical skip of
-value \csb{etocinnertopsep}. The command \csb{etocoldpar} can also be
-used explicitely if needed in the mandatory argument to
-\csb{etocmulticolstyle} (it is not allowed to insert an empty line
-in this argument).
-
-On the other hand the commands \csb{etocruledstyle} and
-\csb{etocframedstyle} expect an argument ``in LR mode'' (to use the
-terminology from \emph{LaTeX, a document preparation system}). This
-means that multiline titles are only possible if enclosing
-them inside something like a \csa{parbox}.
-
-
-
-An important dimension used by all three of \csb{etocmulticolstyle},
-\csb{etocruledstyle} and \csb{etocframedstyle} is
-\csb{etocinnertopsep}. It gives the amount of separation
-between the heading and the start of the contents. Its default
-value is |2ex| and it is changed with
-|\renewcommand*{\etocinnertopsep}|\marg{new\_value}, not with
-|\setlength|.
-
-
-
-\subsection{The compatibility mode \csbhyp{etocstandarddisplaystyle}}
-\label{etocstandarddisplaystyle}
-
-\etoc will then emulate what the document class would have
-done regarding the global display style of the table of
-contents, in its absence. All customizing from inside the
-class should be obeyed, too.
-
-\subsubsection{The commands \csbhyp{etocarticlestyle}, \csbhyp{etocbookstyle},
- \dots}
-\label{etocarticlestyle}
-\label{etocbookstyle}
-
-These are the commands used internally by \etoc in compatibility mode
-depending on the document class. For example \csb{etocarticlestyle} instructs
-\etoc to use |\section*{\contentsname}| (with marks on the page) and
-\csb{etocbookstyle} says to use |\chapter*{\contentsname}|. It can prove
-useful to issue \csb{etocarticlestyle} for a \csa{localtableofcontents} inside
-a chapter, in |book| class and compatibility mode for the global TOC display
-style.
-
-\subsection{The command \csbhyp{etocinline}}
-\label{etocinline}
-\label{etocnopar}
-\label{etocdisplay}
-
-With \csb{etocinline}, or its synonym |\etocnopar|, the
-|\tableofcontents| command and its variants do \emph{not} first issue a
-|\par| to close the previous paragraph. Hence, the table of contents can
-be printed in an inline style; or, if used only for preparing some token
-list or macro, it will leave nothing in the token stream on execution.
-
-Issue \csb{etocdisplay} to return to the default situation that
-|\tableofcontents| and variants issue a |\par| to switch to vertical
-mode before typesetting the TOC title and contents.
-
-\section{Starred variants and hooks}
-\label{tableofcontents*}
-\label{localtableofcontents*}
-\label{etocbeforetitlehook}
-\label{etocaftertitlehook}
-\label{etocaftercontentshook}
-\label{etocaftertochook}
-
-The \toc, \localtoc, \csb{etocmulticol}, and all their cousins have starred
-variants (the star must be before the other arguments). The non-starred
-variants execute the \csb{etocaftertitlehook}, whose default definition is to
-do nothing. The starred variants do not execute this hook.
-
-For example, imagine you are using |book| class and want \localtoc to use a
-section-like title, but unnumbered. Assuming the main \toc comes first in the
-document, you can insert this after it:
-\begin{verbatim}
- \etocarticlestyle
- \renewcommand{\etocaftertitlehook}{\addcontentsline{toc}{section}{\contentsname}}
-\end{verbatim}
-This configures the way \localtoc will behave (or \toc) from now on in the
-document.
-
-The first line tells essentially to use |\section*{\contentsname}|, and the
-second line says to insert the title in the |.toc| file itself (thus to be
-displayed by the main table of contents). Notice that \ctanpkg{hyperref} package will
-then automatically create suitable anchor and one should \emph{not} use
-explicitly \cs{phantomsection} here (it would let the anchor be located below
-not above the title).
-
-% problème avec \xspace
-With this set-up issuing \localtoc\unskip|*| will ignore the \csb{etocaftertitlehook}
-hence not send the local toc title to the |.toc| file. This mimicks the
-\ctanpkg{memoir} class behavior, and can also be used with it. For more on \ctanpkg{memoir}
-class with \etoc, see \autoref{ssec:memoir}.
-
-There are further hook macros:
-\csb{etocaftercontentshook}, \csb{etocbeforetitlehook} and
-\csb{etocaftertochook} which are initially defined to do nothing and can be
-used for some special effects. They are executed whether or not the table of
-contents command was starred.%
-%
-\footnote{Hackers can test within these hooks if the context is starred or not
- via an \cs{ifx}\cs{Etoc@aftertitlehook}\cs{@empty} conditional. Perhaps a
- future release will provide \cs{etociftocisstarred} wrapper.}
-
-
-\clearpage
-\etocdepthtag.toc {custom}
-
-\part{Using and customizing the \etoc own styles}
-\label{part:custom}
-
-\thispartstats
-
-\etocdefaultlines
-\renewcommand{\etoctoprule}{\hrule height2pt depth0pt}
-\renewcommand{\etoctoprulecolorcmd}{\color{red}}
-
-\etocruledstyle{\normalfont\normalsize\rmfamily\fboxrule1pt\color{red}%
- \fbox{\parbox{.8\linewidth}{\centering\normalcolor This is a table of
- contents for the sections and
- subsections in this part. It carries the label |toc:c|}}}
-
-\localtableofcontents \label{toc:c}
-
-
-\section{Summary of the main style commands}
-
-\subsection{Setting up local styles}
-
-\hbox{\color{green}\fboxrule1pt\fboxsep1em
-\setbox0\hbox{\csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}, \csb{etoclink}\marg{linkname}}%
-\framebox[\linewidth][c]
-{\vbox{\hsize\wd0\normalcolor\noindent
-\csb{etocsetstyle}\marg{levelname}%
- \marg{start}\marg{prefix}\marg{contents}\marg{finish}\\
-\csb{etocname}, \csb{etocnumber}, \csb{etocpage},
-\csb{etocifnumbered}\marg{A}\marg{B}\\
-\csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}, \csb{etoclink}\marg{linkname}
-}}}
-
-\subsection{Setting up toc display styles}
-
-\medskip
-\hbox{\color{green}\fboxrule1pt\fboxsep1em
-\setbox0\hbox{\csb{etoctocstylewithmarksnouc}\oarg{kind}%
-\marg{number\_of\_columns}\marg{title}\marg{mark}}%
-\framebox[\linewidth][c]
-{\vbox{\hsize\wd0
-\normalcolor\noindent
-\csb{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}\\
-\csb{etoctocstyle}\oarg{kind}\marg{number\_of\_columns}\marg{title}\\
-\csb{etoctocstylewithmarks}\oarg{kind}\marg{number\_of\_columns}%
-\marg{title}\marg{mark}\\
-\csb{etoctocstylewithmarksnouc}\oarg{kind}\marg{number\_of\_columns}%
-\marg{title}\marg{mark}\\
-\csb{etocruledstyle}\oarg{number\_of\_columns}\marg{title}\\
-\csb{etocframedstyle}\oarg{number\_of\_columns}\marg{title}\\
-\csb{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}}}
-
-\subsection{Displaying tables of contents}
-
-
-\medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
- \setbox0\hbox{\csb{etocname}, \csb{etocnumber},
- \csb{etocpage}, \csb{etocifnumbered}\marg{A}\marg{B}}%
- \framebox[\linewidth][c]
- {\vbox{\hsize\wd0\normalcolor\noindent
- \toc\\
- \localtoc\\
- \csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading}\\
- \csb{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}\\
- \csb{etocruled}\oarg{number\_of\_columns}\marg{title}\\
- \csb{etoclocalruled}\oarg{number\_of\_columns}\marg{title}\\
- \csb{etocframed}\oarg{number\_of\_columns}\marg{title}\\
- \csb{etoclocalframed}\oarg{number\_of\_columns}\marg{title}\\
- \hbox{}{\itshape\ttfamily\ \ \ \ and their starred variants}
- }}}
-
-\subsection{Labels and references}
-\label{ssec:labelref}
-
-The commands (starred or not) to actually display the table of contents
-can be followed with optional labels or references:\par
-
-\medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
- \setbox0\hbox{\csb{etocname}, \csb{etocnumber},
- \csb{etocpage}, \csb{etocifnumbered}\marg{A}\marg{B}}%
- \framebox[\linewidth][c]
- {\vbox{\hsize\wd0\normalcolor\noindent
- \toc \csa{label}|\{toc:here\}|\\
- \toc \csa{ref}|\{toc:far\}| \\
- \toc \csa{label}|\{toc:here\}| \csa{ref}|\{toc:far\}| \\
- \localtoc \csa{label}|\{toc:here\}|\\
- \localtoc \csa{ref}|\{toc:far\}| \\
- \localtoc \csa{label}|\{toc:here\}| \csa{ref}|\{toc:far\}| \\
- \hbox{}{\itshape\ttfamily\ \ \ \ similarly with\ }%
- \csb{etocmulticol}{\itshape\ttfamily\ etc . . . }
- }}}
-
-
-\medskip
-
-%New with |1.08e|:
-
-\localtoc \csa{ref}|{toc:far}| acts the same as \toc
-\csa{ref}|{toc:far}|.
-
-
-When re-displaying another toc, only its contents are transferred:
-both the line styles and the toc display style are the ones
-currently defined, not the ones from the cloned toc.
-
-
-\section{The package default line styles: \csbhyp{etocdefaultlines}}
-\label{etocdefaultlines}
-
-These line styles were written at an early stage in the
-development of the package; although the next section explains how
-to customize the font choicess or vertical spaces, etc\dots, used
-by these line styles, most other changes would require copying
-them from the sources and modify them directly. Admittedly they
-have been written at a rather scary low-\TeX{} level, and will not
-serve as a very friendly starting point.
-
-Activating their use is done via \csb{etocdefaultlines}, or
-\csb{etoctoclines} if the line styles have not been modified with
-\csb{etocsetstyle}. Sections and sub-sections are printed in
-essentially the same manner, except that the leading for
-sub-sections is a bit smaller (with document classes lacking a
-\csa{chapter} command, the sections are printed in bold typeface;
-this is the case in the present document). Sub-sub-sections are
-printed inline, in one paragraph, with no numbers or page numbers.
-This style was designed and tested with documents having lots of
-sub-sub-sections, and should be used on a two-column layout: it
-provides (only in that situation with many sub-sub-sections) a
-more compact presentation than what is achieved by the \LaTeX{}
-default.\footnote{and there will never be a Part or Chapter entry
- alone at the bottom of a column or page (except if it has no
- sub-unit).} On the other hand, used with a one-column layout,
-and with few sub-sub-sections, the style is a bit more spread out
-vertically than the \LaTeX{} default, sub-sections are not
-visually much different from sections (especially for document
-classes with a \csa{chapter} command), so the result is less
-hierarchical in appearance than in the \LaTeX{} default.
-
-In this document, for the \hyperref[toc:main]{main table of contents}, we did
-|\etocsetlevel{subsection}{3}| hence the sub-sections were printed with the
-sub-sub-section inline style.
-
-Let us, to the contrary, typeset now this main table of contents as if the
-document had been done with a class having the \csa{chapter} command: we will
-print sections as chapters, and subsections as sections. We use
-\csb{etocsetlevel} for that, and also we need to change the font style of
-``sections'' (which in truth are our subsections) to use not the bold but the
-medium series; we modify the \csb{etocfontone} command for that. Also we use dot
-leaders which are less spread out than in the package default.
-
-
-\begin{filecontentshere}{etocsnippet-\snippetno.tex}
-\etocruledstyle[2]{\normalfont\normalsize\rmfamily\itshape
- \fbox{\parbox{.6\linewidth}{
- \leftskip 0pt plus .5fil
- \rightskip 0pt plus -.5fil
- \parfillskip 0pt plus 1fil This is the global table of
- contents on two columns, using \etoc default line styles, but with
- sections as chapters, and subsections as sections.
- }}}
-\etocdefaultlines
-\etocsetnexttocdepth{1}
-\begingroup
-\etocsetlevel{section}{0}
-\etocsetlevel{subsection}{1}
-\renewcommand*{\etocfontone}{\normalfont \normalsize}
-\renewcommand*{\etoctoclineleaders}
- {\hbox{\normalfont\normalsize\hbox to 1ex {\hss.\hss}}}
-\sloppy
-\tableofcontents
-\endgroup
-\end{filecontentshere}
-\marginattach{}
-
-\filecontentsexec\filecontentsheremacro
-
-\section{Customizing \etoc}
-
-\subsection{Customizing the \etoc pre-defined line styles}
-\label{etocfontminustwo}
-\label{etocfontminusone}
-\label{etocfontzero}
-\label{etocfontone}
-\label{etocfonttwo}
-\label{etocfontthree}
-\label{etocsepminustwo}
-\label{etocsepminusone}
-\label{etocsepzero}
-\label{etocsepone}
-\label{etocseptwo}
-\label{etocsepthree}
-\label{etocminustwoleftmargin}
-\label{etocminustworightmargin}
-\label{etocminusoneleftmargin}
-\label{etocminusonerightmargin}
-\label{etocbaselinespreadminustwo}
-\label{etocbaselinespreadminusone}
-\label{etocbaselinespreadzero}
-\label{etocbaselinespreadone}
-\label{etocbaselinespreadtwo}
-\label{etocbaselinespreadthree}
-\label{etoctoclineleaders}
-\label{etocabbrevpagename}
-\label{etocpartname}
-\label{etocbookname}
-
-
-We will simply list the relevant commands as defined in the
-package. Customizing them goes through suitable
-\csa{renewcommand}s:
-\begin{verbatim}
-\newcommand*\etocfontminustwo{\normalfont \LARGE \bfseries}
-\newcommand*\etocfontminusone{\normalfont \large \bfseries}
-\newcommand*\etocfontzero{\normalfont \large \bfseries}
-\newcommand*\etocfontone{\normalfont \normalsize \bfseries}
-% (in classes with chapter, \etocfontone does not do \bfseries)
-\newcommand*\etocfonttwo{\normalfont \normalsize}
-\newcommand*\etocfontthree{\normalfont \footnotesize}
-
-\newcommand*\etocsepminustwo{4ex plus .5ex minus .5ex}
-\newcommand*\etocsepminusone{4ex plus .5ex minus .5ex}
-\newcommand*\etocsepzero{2.5ex plus .4ex minus .4ex}
-\newcommand*\etocsepone{1.5ex plus .3ex minus .3ex}
-\newcommand*\etocseptwo{.5ex plus .1ex minus .1ex}
-\newcommand*\etocsepthree{.25ex plus .05ex minus .05ex}
-
-\newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil}
-\newcommand*\etocminustworightmargin{1.5em plus -0.5fil}
-\newcommand*\etocminusoneleftmargin{1em}
-\newcommand*\etocminusonerightmargin{1em}
-
-\newcommand*\etocbaselinespreadminustwo{1}
-\newcommand*\etocbaselinespreadminusone{1}
-\newcommand*\etocbaselinespreadzero{1}
-\newcommand*\etocbaselinespreadone{1}
-\newcommand*\etocbaselinespreadtwo{1}
-\newcommand*\etocbaselinespreadthree{.9}
-\newcommand*\etoctoclineleaders
- {\hbox{\normalfont\normalsize\hbox to 2ex {\hss.\hss}}}
-\newcommand*\etocabbrevpagename{p.~} % initial of "page"
-\newcommand*\etocpartname{Part} % prior to 1.08b, was \partname
-% but this didn't make sense e.g. with babel+frenchb whose \frenchpartname
-% takes into account the value of the part counter.
-\newcommand*\etocbookname{Book} % to be modified according to language
-\end{verbatim}
-
-No customizing of the standard line styles is possible from
-within \etoc. As already explained, when
-\csb{etocstandardlines} has been issued, the package just makes
-itself very discrete and acts only at the global level, and
-the TOC entries are (hopefully) formatted as would have
-happened in the absence of \etoc.\footnote{with the
- \ctanpkg{KOMA-script} classes, we noticed that
- \csb{etocstandarddisplaystyle} was apparently needed for the
- KOMA options |toc=left| to be active at the level of the line entries.}
-
-
-The \csb{etocstandardlines} compatibility mode will work also with
-sectioning commands made known to \etoc via \csb{etocsetlevel},
-under the condition of course that these sectioning commands
-are accompanied with all the relevant definitions for
-typesetting toc entries in the \LaTeX{} default manner
-(existence of the macros \csa{l@something} . . .).
-
-Using the command \csb{etocsetstyle}, be it in the preamble or
-in the body of the document, has the secondary effect of
-switching off the compatibility mode.
-
-\subsection{Customizing the toc display styles}
-\label{ssec:customdisplay}
-\label{etocabovetocskip}
-\label{etocbelowtocskip}
-\label{etoccolumnsep}
-\label{etocmulticolsep}
-\label{etocmulticolpretolerance}
-\label{etocmulticoltolerance}
-\label{etocdefaultnbcol}
-%\label{etocinnertopsep}% déjà défini
-\label{etoctoprule}
-\label{etoctoprulecolorcmd}
-\label{etocinnerleftsep}
-\label{etocinnerrightsep}
-\label{etocinnerbottomsep}
-\label{etocleftrule}
-\label{etocrightrule}
-\label{etocbottomrule}
-\label{etocleftrulecolorcmd}
-\label{etocrightrulecolorcmd}
-\label{etocbottomrulecolorcmd}
-\label{etocbkgcolorcmd}
-\label{etocframedmphook}
-
-Again we list the relevant macros, what they do should be
-legible from their names. Note that \csa{renewcommand}'s and
-not \csa{setlength}'s have to be used for what appear to be
-lengths, and that color commands are not just color
-specifications, they must include \csa{color}, and are canceled
-by re-defining them to do \csa{relax}.
-\begin{verbatim}
-\newcommand*\etocabovetocskip{3.5ex plus 1ex minus .2ex}
-\newcommand*\etocbelowtocskip{3.5ex plus 1ex minus .2ex}
-
-\newcommand*\etoccolumnsep{2em}
-\newcommand*\etocmulticolsep{0ex}
-\newcommand*\etocmulticolpretolerance{-1}
-\newcommand*\etocmulticoltolerance{200}
-\newcommand*\etocdefaultnbcol{2}
-\newcommand*\etocinnertopsep{2ex}
-\newcommand*\etoctoprule{\hrule}
-\newcommand*\etoctoprulecolorcmd{\relax}
-
-% for the framed style only:
-\newcommand*\etocinnerleftsep{2em}
-\newcommand*\etocinnerrightsep{2em}
-\newcommand*\etocinnerbottomsep{3.5ex}
-
-\newcommand*\etocleftrule{\vrule}
-\newcommand*\etocrightrule{\vrule}
-\newcommand*\etocbottomrule{\hrule}
-\newcommand*\etocleftrulecolorcmd{\relax}
-\newcommand*\etocrightrulecolorcmd{\relax}
-\newcommand*\etocbottomrulecolorcmd{\relax}
-
-\newcommand*\etocbkgcolorcmd{\relax}
-
-% hooks
-\newcommand\etocframedmphook{\relax}
-\end{verbatim}
-
-The \csa{etocframedmphook} is positioned immediately
-after the beginning of a minipage environment where the
-contents of the framed TOC are typeset.
-
-The \csa{...colorcmd} commands are initially set to expand to
-\csa{relax} (hence do not require package |color| or |xcolor|
-to be loaded). If one has modified a command such as
-\csa{etocbkgcolorcmd} to expand to a color command and wants
-to reset it to do nothing, one \emph{must} use
-|\renewcommand{\etocbkgcolorcmd}{\relax}| and not
-\csa{let}\csa{etocbkgcolorcmd}\csa{relax}.
-
-Regarding the dimensions of the top rule they can be specified
-in |ex|'s or |em|'s as in this example:
-\centeredline{|\renewcommand{\etoctoprule}{\hrule height 1ex}|}
-The package code is done in such a manner
-that it is the font size in instance at the end of typesetting
-the title argument to \csb{etocruled} or
-\csb{etocframed} which will be used for the meaning of the
-`1ex'. Of course also the other rule commands can have their
-dimensions in font relative units, but their values are
-decided on the basis of the font in effect just before the
-table of contents.
-
-The top and bottom rules do not have to be rules and can be
-horizontal \emph{leaders} (of a specified height) in the general
-\TeX{} sense. However the left and right rules are not
-used as (horizontal) leaders but as objects of a given specified
-width. Note that \emph{only} the Plain \TeX{} syntax for rules is
-accepted here.
-
-\section{One more example of colored TOC layout}
-\label{ssec:tocclone}
-
-The command \csb{etocframedstyle} puts the title on the top
-rule in a centered position. This is not very convenient for
-this example so we included the title as part of the
-\meta{start} code at section level, to get it \emph{inside}
-the frame.
-
-\begin{filecontentshere}{etocsnippet-\snippetno.tex}
-\begingroup
-\definecolor{subsecnum}{RGB}{13,151,225}
-\definecolor{secbackground}{RGB}{0,177,235}
-\definecolor{tocbackground}{RGB}{212,237,252}
-
-\renewcommand{\etocbkgcolorcmd}{\color{tocbackground}}
-\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
-\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
-\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
-\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
-
-\renewcommand{\etocleftrule}{\vrule width 1cm}
-\renewcommand{\etocrightrule}{\vrule width .5cm}
-\renewcommand{\etocbottomrule}{\hrule height 12pt}
-\renewcommand{\etoctoprule}{\hrule height 12pt}
-
-\renewcommand{\etocinnertopsep}{0pt}
-\renewcommand{\etocinnerbottomsep}{0pt}
-\renewcommand{\etocinnerleftsep}{0pt}
-\renewcommand{\etocinnerrightsep}{0pt}
-
-\newcommand\shiftedwhiterule[2]{%
- \hbox to \linewidth{\color{white}%
- \hskip#1\leaders\vrule height1pt\hfil}\nointerlineskip\vskip#2}
-
-\etocsetstyle{subsubsection}{\etocskipfirstprefix}
- {\shiftedwhiterule{\leftskip}{6pt}}
- {\sffamily\footnotesize
- \leftskip2.5cm\hangindent1cm\rightskip1cm\noindent
- \hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
- \color{black}\etocname\leaders\hbox to .2cm{\hss.}\hfill
- \rlap{\hbox to 1cm{\hss\etocpage\hskip.2cm}}\par
- \nointerlineskip\vskip3pt}
- {}
-
-\etocsetstyle{subsection}{\etocskipfirstprefix}
- {\shiftedwhiterule{1.5cm}{6pt}}
- {\sffamily\small
- \leftskip1.5cm\hangindent1cm\rightskip1cm\noindent
- \hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
- \color{black}\etocname\leaders\hbox to .2cm{\hss.}\hfill
- \rlap{\hbox to 1cm{\hss\etocpage\hskip.2cm}}\par
- \nointerlineskip\vskip6pt}
- {}
-
-\newcommand{\coloredstuff}[2]{%
- \leftskip0pt\rightskip0pt\parskip0pt
- \fboxsep0pt % \colorbox uses \fboxsep also when no frame!
- \noindent\colorbox{secbackground}
- {\parbox{\linewidth}{%
- \vskip5pt
- {\noindent\color{#1}#2\par}\nointerlineskip
- \vskip3pt}}%
- \par\nointerlineskip}
-
-\etocsetstyle{section}
-{\coloredstuff{white}
- {\hfil \hyperref[toc:b]{\bfseries\large I am a twin of
- that other TOC (click me!)}\hfil}}
-{\vskip3pt\sffamily\small}
-{\coloredstuff{white}
- {\leftskip1.5cm\rightskip.5cm\parfillskip-\rightskip
- \makebox[0pt][r]{\makebox[.5cm][r]{\etocnumber\hspace{.2cm}}}%
- \etocname\hfill\makebox[.5cm][r]{\etocpage\hspace{.2cm}}}%
- \vskip6pt }
-{}
-
-\etocframedstyle[1]{}
-\tableofcontents \label{toc:clone} \ref{toc:globalcmds}
-\endgroup
-\end{filecontentshere}
-\marginattach{}
-
-\filecontentsexec\filecontentsheremacro
-% 1.07l on the occasion of traduction into German documentation
- % APRIL 26, 2014 Improvement in the section style for better placement of
- % page number when the section name is more than one line long. Use of
- % \makebox rather than \hbox, to be more LaTeX like.
-
-The TOC has been put in a \hyperref[toc:clone]{float} which appears
-\vpageref{toc:clone}. The coding is a bit involved\footnote{and reveals the
- author's preference for the \TeX{} syntax...} as it does not use any
-additional package. Also, it was written at some early stage and I have not
-revised it since.
-
-A better solution would be to use some package to set
-up a background color possibly extending accross pages, as the
-framed style (which we used to get this background
-color) can only deal with material short enough to fit on one
-page.
-
-Regarding colors, generally speaking all color commands inside
-\etoc are initially defined to do nothing, and the choice to
-use or not colors is left to the user.
-
-\clearpage
-\etocdepthtag.toc {tips}
-
-\part{Tips}
-\label{part:tipsandtricks}
-
-\thispartstats
-
-%%%% \invisiblelocaltableofcontents \label{toc:tipsandtricks}
-
-\etocsettocstyle{}{}
-\etocstandardlines
-\localtableofcontents
-
-%\section{... and tricks}
-
-% pas traduit
-\section{The \csbhyp{etoclocaltop} command}
-\label{etoclocaltop}
-
-%\textbf{New with 1.09 (2019/03/09)}.
-
-Within either the TOC style
-(\csb{etocsettocstyle}) or the local title styles (\csb{etocsetstyle}), the
-control sequence \csb{etoclocaltop} is made equivalent for the duration of
-\csb{localtableofcontents} to a numeric (self-delimiting) denotation of the
-current top level.
-
-Thus: it will in numeric contexts (|\ifnum|, |\ifcase|, ...) represent zero
-for a local TOC corresponding to chapter, or one if in a section, or two if in
-a subsection, etc..., assuming of course here that the default levels are
-obeyed (see \autoref{sec:tocdepth}).
-
-\begin{framed}
- \csb{etoclocaltop} from inside the TOC heading (first argument of
- \csb{etocsettocstyle}) has the correct value \emph{only under
- \csb{etocchecksemptiness} regime}. Special circumstances correspond to
- some special values:
- \begin{description}[nolistsep]
- \item[|-3|] (|-\thr@@|)\newline
- signals that \etoc considers the local TOC to be
- ``unknown''; this happens at the last local TOC, for the first \LaTeX\ run
- after adding a new \localtoc to the document. In doubt, \etoc assumes the
- TOC will prove non empty, hence it prints (independently of whether the
- check for emptiness was activated or not) the heading as specified by
- \csb{etocsettocstyle}. Thus, check if \csb{etoclocaltop} gives |-3| as a
- a \meta{number} to detect that situation from within the first argument of
- \csb{etocsettocstyle}, if desired.
- \item[|-1000|](|-\@m|)\newline is in case of a \localtoc
- being considered ``known'' (although it may still refer to the data in the
- |.toc| file from the previous run) but without the check for emptiness
- having been executed.
- \item[|-10000|](|-\@M|)\newline is the value when accessed from the title
- of a global TOCs.
- \end{description}
-\end{framed}
-\begin{framed}
- When executed from within a local table of contents \textbf{line styles}
- (\csb{etocsetstyle}), \csb{etoclocaltop} always will hold the correct value,
- whether or not the emptiness check was executed.
-
- For a global table of contents however, it will always keep the value |-3|.
-\end{framed}
-
-Attention! \cs{etoclocaltop} is only to be queried; modifying it is strictly
-forbidden and falls under the most rigorous prosecution allowed by federal
-law.
-
-\section[The \csbhyp{etocsetlocaltop.toc} command]
- {The \csbhyp{etocsetlocaltop.toc} and
- \csbhyp{etocimmediatesetlocaltop.toc} commands}
-\label{etocsetlocaltop.toc}
-\label{etocimmediatesetlocaltop.toc}
-
-It is important to understand that \csb{localtableofcontents} works entirely
-from data \emph{in the |.toc| file}. If the document, say with |article|
-class, contains starred sectioning commands, which are not accompanied
-by suitable \csa{addcontentsline}, then these units are completely
-transparent to \csb{localtableofcontents}:
-\begin{itemize}
-\item If \localtoc is issued before |\section*{Foo}|, say locally to a |\section|,
- then the local TOC will include not only the |subsection|s between the
- |\section| and the |\section*{Foo}| but also those following, and it will
- stop only at encountering a later |\section| or |\part| from the document's body.
-\item If the command is issued right after |\section*{Foo}| and the later was
- itself subsequent to a (numbered) |\subsection|, then \etoc will think it
- must display a TOC local to the \emph{subsection}.
-\end{itemize}
-
-Since release |1.08k|, \etoc provides the one-argument command
-\csb{etocsetlocaltop.toc} to insert into the |.toc| file a kind
-of ``ghost'' of a given sectioning unit. Here is an example:
-
-\begin{verbatim}
-\part*{Extra unnumbered part}
-\etocsetlocaltop.toc{part}
-\localtableofcontents
-\end{verbatim}
-
-So with no |\part| heading inserted into the table of contents via an
-|\addcontentsline|, still \localtoc will know it is local to a part. In this
-example the local contents will be delimited by the next numbered |\part|, or
-|\part*| with |\addcontentsline|, or also by a later, second,
-|\etocsetlocaltop.toc{part}|.
-
-As a (counter)-example consider this document:
-\begin{verbatim}
-\documentclass{article}
-\usepackage{etoc}
-\begin{document}
-\tableofcontents
-
-\part*{A}
-\etocsetlocaltop.toc{part}
-\localtableofcontents
-
-\section{I}
-
-\section{II}
-
-\part*{B}
-
-\section{III}
-
-\part*{C}
-
-\section{IV}
-\end{document}
-\end{verbatim}
-It uses only |\part*|. Thanks to the \csb{etocsetlocaltop.toc} the \localtoc
-knows it should report only sections. But the other |\part*| are invisible to
-it as nothing is recorded in the |.toc| file. So the local table of contents
-in this example will list \emph{all} sections not only |I| and |II|. To fix thix one may
-e.g.\@ insert another |\etocsetlocaltop.toc{part}|, this time after |\part*{B}|
-(or make this a numbered part, or use |\addcontentsline| for it).
-
-The above document amended with added |\etocsetlocaltop.toc{part}| after each
-unnumbered part will thus have its main TOC without any |Part| heading, but
-each |\part| can show a correct \localtoc. The simpler
-approach would be to use |\addcontentsline| with each unnumbered |\part| so
-that it ends up in the |.toc| file, but \etoc is keen on allowing the most
-diverse point of views.
-
-It should be stressed that the various |\etocsetlocaltop.toc|\marg{sect. unit}
-do impact the global \toc: they really act like actual sectioning units,
-except for not inducing any typesetting. In usual document classes, this
-would appear to mean that they are completely transparent to the global \toc.
-Not the case with \etoc, which adds a virtual assembly of levels: the |.toc|
-data originating in |\etocsetlocaltop.toc|\marg{sect. unit} will trigger the
-execution of the \marg{finish} parts of the line styles of finer sectioning
-units encountered before (either in the global \toc or in an active
-\localtoc); and it triggers the \marg{start} parts of the line styles of finer
-units encountered after it (again in the global \toc, but also in any
-\localtoc which is already activated at a coarser lever).
-
-Depending on how the toc line styles are configured this may translate into
-some visual effect; for example with the \etoc own line styles the
-\marg{start} and \marg{finish} mostly insert penalties or vertical spaces.
-
-It is a matter of debate if this is good design; a variant serving purely to
-influence boundaries of local table of contents with no collateral effects
-could be provided. And the name of the macro was perhaps not so well chosen
-as it suggests it acts as would such an hypothetical variant. In absence of
-feature requests we leave the matter standing for now.%
-%
-\footnote{This documentation was updated and this paragraph added for the
- |1.09f| release.}
-
-Usage of \csb{etocsetlocaltop.toc} interacts with
-\csb{etocchecksemptiness} in the expected way: it modifies (as explained
-above) the selection made by \csb{localtableofcontents}, hence the decision
-whether this local TOC will end up empty or not.
-
-There is also \csb{etocimmediatesetlocaltop.toc}. This may be useful in some
-very special circumstances involving |\include|. For related discussion see
-the documentation of \csb{etocimmediatedepthtag.toc}.
-
-\section{Hacking framed parboxes}
-
-\begin{verbatim}
-\etocdefaultlines
-\renewcommand\etoctoprule{\hrule height 2pt depth 2pt}
-\etocruled{\color{green}\fboxrule2pt\fboxsep1ex
- \fbox{\raisebox{-\fontdimen22\textfont2}
- {\color{blue}\parbox{.5\linewidth}
- {\normalfont This text is perfectly centered
- vertically with respect to the
- surrounding horizontal rules.}}}}
-\ref{toc:globalcmds}
-\end{verbatim}
-
-\etocdefaultlines
-
-\renewcommand\etoctoprule{\hrule height 2pt depth 2pt}
-
-\etocruled{\color{green}\fboxrule2pt\fboxsep1ex
- \fbox{\raisebox{-\fontdimen22\textfont2}
- {\color{blue}\parbox{.5\linewidth}
- {\normalfont This text is perfectly centered
- vertically with respect to the
- surrounding horizontal rules.}}}}
- \ref{toc:globalcmds}
\section{Interverting the levels}
@@ -5760,7 +5970,7 @@ this technique):
\begingroup
\etocdefaultlines
-\etocstandarddisplaystyle
+\etocclasstocstyle
\etocsetlevel{book}{3}
\etocsetlevel{part}{3}
\etocsetlevel{chapter}{3}
@@ -5845,7 +6055,8 @@ But first, the code of \csa{thispartstats}:\par
\endgroup
}
\end{filecontentshere}
-\marginattach{-A}
+\marginattach
+
And now, the variant with macros rather than boxes (this variant as it
stands here is for using within a section).
\begin{filecontentshere}{etocsnippet-\snippetno.tex}
@@ -5877,14 +6088,14 @@ stands here is for using within a section).
}
\makeatother
\end{filecontentshere}
-\marginattach{-B}
+\marginattach
\section{Using depth tags}
-\label{ssec:tocwithdepthtags}
+\label{sec:tocwithdepthtags}
We want a TOC which will have a heading for each |\part| (except
the last part with the code source, which we decide not to
-include), and will additionally open up \autoref{part:globalcmds}
+include), and will additionally open up \autoref{sec:tocstyle}
up to paragraphs. To achieve this we added to this source various
\csb{etocdepthtag.toc} commands, and it remains now to set the
levels for each tag using \csb{etocsettagdepth} (this was used
@@ -5947,17 +6158,14 @@ get:
{\mdseries\normalsize\llap{\makebox[1.5cm][l]{\etocnumber}}%
\etocname\EndParWithPagenoInMarginAndLeaders}
{}
-\etocsettagdepth {preamble} {none}
-\etocsettagdepth {overview} {part}
-%\etocsettagdepth {arbitrarily}{part}% not needed explicitely, keeps value
-%\etocsettagdepth {examples} {part}
-%\etocsettagdepth {surprising} {part}
-%\etocsettagdepth {linestyles} {part}
-\etocsettagdepth {globalcmds} {paragraph}
-\etocsettagdepth {custom} {part}
-%\etocsettagdepth {tips} {part}
-%\etocsettagdepth {etocandworld}{part}
-\etocsettagdepth {code} {none}
+\etocsettagdepth {preamble} {all}
+\etocsettagdepth {overview} {part}
+\etocsettagdepth {styling} {subsection}
+\etocsettagdepth {control} {subsubsection}
+\etocsettagdepth {examples} {part}
+\etocsettagdepth {advanced} {part}
+\etocsettagdepth {etocandworld}{all}
+\etocsettagdepth {code} {all}
\renewcommand\etoctoprule {\hrule height 3pt\relax }
\renewcommand\etoctoprulecolorcmd {\color{blue}}
\renewcommand\etocaftercontentshook
@@ -5965,22 +6173,126 @@ get:
\etocruledstyle [1]{\Large\bfseries
\fbox{\makebox[8cm]{A TOC using depth tags}}}
\sloppy
+\etocobeydepthtags % let's not forget to activate this (default anyhow)
\tableofcontents
\endgroup
\end{filecontentsdef}
\filecontentsexec\foo
-\filecontentsprint\foo
-\marginattach{}
+\filecontentsprintviascan\foo
+\marginattach
+
+\section{Sections styling subsections}
+\label{sec:anothercompatadvanced}
+
+Here is a subtler example where one only marginally modifies the sections
+(adding color to the number, removing the \ctanpkg{hyperref} link, changing
+the color for one specific section) but let them decide almost one by one
+of the style which will be followed by their subsections. Furthermore one
+configures some sections to decide they will not display subsections at all or
+only count how many there are!
+
+% modified for 1.2 doc to make the argument optional and update number
+% of exceptional section
+
+\begin{filecontentshere}{etocsnippet-\snippetno.tex}
+\makeatletter
+\newcommand*{\MyQuasiStandardTOC}[2][]{%
+ % #1 is an optional "\ref{somelabeltoanothertoc}"
+ % #2 is the number of some exceptional section
+ \begingroup
+ \etocsetstyle{section}
+ {}
+ {\etociffirst{% Suppress display of subsections for the first section!
+ \etocsetlevel{subsection}{6}}
+ {\etocsetlevel{subsection}{2}}%
+ \ifnum\etocthenumber=#2 % Handle especially section number #2 !
+ \etocsetstyle{subsection}
+ {\def\foo{}\par\nopagebreak\begingroup
+ \leftskip2em \rightskip\@tocrmarg
+ \parfillskip \@flushglue
+ \parindent 0pt
+ \normalfont\normalsize\rmfamily\itshape
+ \etocskipfirstprefix}
+ {\allowbreak\,--\,}
+ {\edef\foo{\the\numexpr\foo+1}\etocname\ \textup{(\etocnumber)}}
+ {.\par \upshape My AI counted circa \foo\space subsections,
+ was it right?\par\endgroup}%
+ \else
+ \ifnum\etocthenumber>#2 % Only count subsections in those sections !
+ \etocsetstyle{subsection}
+ {\def\foo{}}%
+ {\edef\foo{\the\numexpr\foo+1}}%
+ {}%
+ {\leftskip2em \emph{There are \foo\space subsections here,
+ but I will need payment to display them.}\par}%
+ \else
+ \etocsetstyle{subsection}
+ {}%
+ {}%
+ {\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}%
+ {}%
+ \fi
+ \fi
+ }%
+ {% Display in a special color the number of the special section!
+ \l@section{\numberline{{\ifnum\etocthenumber=#2
+ \color{red}\else\color{cyan}\fi\etocthenumber}}%
+ \etociffirst{\etocname\space (SUBSECTIONS SKIPPED)}{\etocname}}
+ {\etocpage}}%
+ {}%
+ \etocclasstocstyle % will use the ambient document class
+ % special KOMA-script customization as this document uses scrartcl
+ % and we need to enlarge numwidth for some subsections
+ \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
+ \DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection}
+ \etocsetnexttocdepth {subsection}%
+ \tableofcontents #1
+ \endgroup
+}
+\makeatother
+\end{filecontentshere}
+
+\marginattach
+\filecontentsexec\filecontentsheremacro
+
+The optional argument stands for a suitable |\ref|, see \autoref{sec:labeling}.
+Here is what
+\begin{verbatim}
+\MyQuasiStandardTOC[\ref{toc:part:styling}]{11}% treat especially section 11
+\end{verbatim}
+gives:
+\MyQuasiStandardTOC[\ref{toc:part:styling}]{11}%
+
+\vskip.5\baselineskip
+
+The page heading (on the page where this TOC appears) may have been modified
+as is expected from usage of \csb{etocclasstocstyle} in the code.
+
+Sections are printed exactly as in the default, \emph{except} that a special
+section number is displayed especially and that its subsections are then
+displayed inline! And other sections may only count subsections or
+ignore them altogether!
+
+Note: for this code to work the macro \csa{thesection} \emph{must} not have
+been modified from its default which produces simply arabic digits. In other
+terms it must be usable as \TeX{} number denotation. Typically this would
+fail if we were handling subsections as their number in the |.toc| file will
+be typically something like |3.7| which does not work in a \TeX{} integer-only
+context. But it is possible to use a counter and configure the line styles to
+increment it, and use its value.
+
+
-\section{Typesetting the TOC as a table (the old way)}
+\section{The TOC as a (long) table (alternative)}
\label{ssec:tocastableold}
Due to, among other things, the fact that alignment cells create and close
groups, and that by default definitions of \csb{etocname}, \csb{etocnumber},
\csb{etocpage} made by \etoc are local, it was not easy to typeset a TOC as
-table with \etoc, prior to release |1.08|.
+table with \etoc, prior to release to the addition of \csb{etocglobaldefs} at
+\etocrelease{1.08}.
Not only \csb{etocname} etc... caused a problem, but also the basic
redefinition of \csa{contentsline} was made by \etoc only after the
@@ -5996,9 +6308,10 @@ which was then displayed later.
For the record, here is how the TOC from \autoref{sec:tocastable} was
coded in the old days.%
%
-\footnote{At release |1.09f| the design of the TOC from
- \autoref{sec:tocastable} was modified; the code here reproduces
- the former looks.}
+\footnote{At release \etocrelease{1.09f} the design anb contents of the TOC
+ from \autoref{sec:tocastable} were modified; the code here, if executed,
+ which will not, reproduces the
+ former looks.}
%
We don't have here the problems with the
positioning of |\hline|'s we face with the newer method; on the other
@@ -6016,6 +6329,10 @@ external macros inserted in the |.toc| file by other packages.
Note: rather than |\toks| registers it would be easier here to use \eTeX{}
\csa{unexpanded} primitive. See for example \autoref{sec:mindmap}.
+\let\appendtotok\relax
+\let\PreparePart\relax
+\let\PrepareSection\relax
+\let\PrepareSubsection\relax
\begin{filecontentshere}{etocsnippet-\snippetno.tex}
\newtoks\toctabletok
\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
@@ -6035,7 +6352,7 @@ Note: rather than |\toks| registers it would be easier here to use \eTeX{}
\toks4 \expandafter{\etocthelinkedpage}%
\edef\toctablepiece {\the\toks0 &\the\toks2 &\the\toks4 \noexpand\\}%
}
-% new version for 1.07k, 2014/03/06
+%
\newcommand*{\PrepareSubsection}{%
\toks0 \expandafter{\etocthelinkednumber}%
\toks2 \expandafter{\expandafter\itshape\etocthelinkedname\strut}%
@@ -6064,18 +6381,23 @@ Note: rather than |\toks| registers it would be easier here to use \eTeX{}
\the\toctabletok
\endgroup
\end{filecontentshere}
-\marginattach{}
+\marginattach
\clearpage
\etocdepthtag.toc {etocandworld}
+\part{\etoc and the world}
-\part{\etoc and the outside world}
+\etocsettocstyle{}{}
+\etocdefaultlines % etoc own default
+\localtableofcontents
\section{Constraints on the \texttt{.toc} file constitution}
The contents of the |.toc| file (if it already exists) are read into memory by
-\etoc once, at the time of |\begin{document}|.\footnote{%
- Versions earlier than |1.07m| read the |.toc| file at the time of
+\etoc once, at the time of |\begin{document}|.%
+%
+\footnote{%
+ Versions earlier than \etocrelease{1.07m} read the |.toc| file at the time of
\csa{usepackage\{etoc\}}. Thanks to Denis Bitouzé who signaled a Babel
related problem, which turned out to be caused by this.}
@@ -6116,28 +6438,38 @@ Also a |\else| immediately following \csa{tableofcontents} or
non-recommendable) patches. Patching after |\begin{document}| is
naturally possible but I feel almost a rebel to mention this to \LaTeX{} users!
\end{framed}
-\footnotetext{contrarily to \csb{etocaftertochook},
+\footnotetext{Contrarily to \csb{etocaftertochook},
\csb{etocaftercontentshook} is not executed if the |tocdepth| did not
allow the printing of the TOC.}
\etoc \textbf{requires} the |.toc| file to use the \csa{contentsline}
macro. It \textbf{can not} work if there is no |.toc| file or if the
- |.toc| file does not contain the relevant data or if the |.toc| file does
+ |.toc| file does
not use the \csa{contentsline} macro or if the \csa{contentsline} macro
- does not invoke the \csa{l@<divisionunit>} macros.
+ second argument mixes number and name in a manner unexpected by \etoc.%
+%
+\footnote{Prior to \etocrelease{1.1a}, \etoc required the \csa{contentsline} macro
+ expansion to invoke \csa{l@section} et al. It now does not expand
+ \csa{contentsline} hence is immune to whatever would happen during this
+ expansion, and does not use nor modify the \csa{l@section} et al.\@ macros.}
\section{Compatibility with document classes}
\etoc has mainly been tested with the |article| and |book| standard classes.
Some compatibility layer with the \ctanpkg{KOMA-script} and \ctanpkg{memoir} classes was added at
-|1.05| of |2012/12/01|. Such compatibilty layer regards what this
-documentation calls the global display style: when \etoc gets activated
-because the user employed some \csb{etocsetstyle}|{section}| (etc), i.e.\@ it
-is not used purely in compatibility mode (which happens I guess for
-\csb{localtableofcontents} functionality as it does not require reading the
-user manual), \etoc tries in absence of usage by the user of
-\csb{etocsettocstyle} to create itself a ``TOC display style'' emulating the
-default behaviour of the document class. There does not seem to be an easy
+\etocrelease{1.05} of |2012/12/01|.%
+%
+\footnote{That this is still in the doc on \texttt{2023/02/22} shows
+ the frequency of \etoc syncing with upstream changes... but let me reassure
+ the reader there has
+ been indeed some occasional, although admittedly rare, internal updates
+ in the more than ten years elapsed since.}
+%
+A compatibility layer is required for what this
+document designates as the ``global display style'': \etoc tries to emulate the
+default behaviour of the document class when \csb{etocsettocstyle} has not
+been used, so that it is still in ``compatibility mode''. There does not seem
+to be an easy
way to extract this in an automated manner dynamically, so it is basically
some manual work which the author initiated in 2012 and which got sporadically
updated since.
@@ -6151,19 +6483,18 @@ Not really tested... well, tested by this document with its dozens of \etoc
TOCs and which uses \ctanpkg{scrartcl}! The package code contains
\begin{verbatim}
\@ifclassloaded{scrartcl}
- {\renewcommand*\etocstandarddisplaystyle{\etocscrartclstyle}}{}
+ {\renewcommand*\etocclasstocstyle{\etocscrartclstyle}}{}
\end{verbatim}
with \cs{etocscrartclstyle} trying to emulate the global display style of the
\cs{tableofcontents} within the class \ctanpkg{scrartcl}. Thus \etoc is ready
-for basic usage in compatibility mode (last updated
-at |1.09f|).
+for basic usage in compatibility mode. See further \autoref{ssec:tocbasic}.
\subsection{Compatibility with the \ctanpkg{memoir} class}
\label{ssec:memoir}
\label{etocmemoirtoctotocfmt}
\label{etocmemoirstyle}
-Release |1.07l| has also improved the compatibility with the \ctanpkg{memoir} class: its
+Release \etocrelease{1.07l} has also improved the compatibility with the \ctanpkg{memoir} class: its
|appendix| level has been made known to \etoc. It is at the same level as
|chapter|, thus the chapter line style should possibly do a test for some user
defined boolean whose activation may be added to the |.toc| file at the suitable
@@ -6173,50 +6504,10 @@ kinds of divisions.
The \ctanpkg{memoir} mechanism relative to \toc versus \toc|*| is obeyed
automatically, and applies with \localtoc too.
-But, attention, this means that \localtoc should preferentially be used with
-the |*|. Else the \ctanpkg{memoir} mechanism will insert a specific line in the
-|.toc| file, using by default the |chapter| sectioning level. But \etoc has
-already written to the |.toc| file an instruction that the user wants a local
-table of contents. As a result, the fake |chapter| will let \etoc consider
-that the \localtoc has empty contents, except if it used in a |\part| or
-|\book|.
-
-This may even cause successive document builds to never stabilize if
-\csb{etocchecksemptiness} was issued in the preamble: as the local TOC is
-empty, on next run the extra entry in |.toc| is absent, so the local TOC is
-not empty and is typeset, but then |.toc| changes, so the rerunfilecheck
-mechanism instructs to compile once more, and we end in a never stabilizing
-conundrum.
-
-Thus we see that the fact that \localtoc by default use like the global \toc a
-chapter style is inconvenient. One can use the \ctanpkg{memoir} macros to modify this:
-according to \ctanpkg{memoir} documentation, |\tocheadstart| and |\printtoctitle| seem
-to be the most relevant. If you do that you will probably want the added line
-in |.toc| file to use |{section}| not |{chapter}|. \etoc provides to this
-effect \csb{etocmemoirtoctotocfmt}\marg{kind}\marg{name} whose first argument
-\meta{kind} is |chapter|, |section|, |subsection|, etc... and the second
-argument stands for the title and thus \csa{contentsname} is
-appropriate. Hence
-\begin{verbatim}
- \etocmemoirtoctotocfmt{section}{\contentsname}
-\end{verbatim}
-seems the natural choice in this context as an addition to the customizing the
-\ctanpkg{memoir} toc related macros to achieve a section like rendering (for more
-details on the latter, please refer to \ctanpkg{memoir} manual). This is appropriate
-for local TOCs in chapters. Adapt to finer sectioning levels.
-
-Another approach is to overrule the \etoc
-default under \ctanpkg{memoir} like this
-\begin{verbatim}
- \etocarticlestyle % means to use \section*{\contentsname} (and marks)
- \renewcommand{\etocaftertitlehook}{\addcontentsline{toc}{section}{\contentsname}}
-\end{verbatim}
-exactly as one would do with |book| class for example. This emulates the
-default under memoir that table of contents write a line to the |.toc| file representing
-themselves, except that |chapter| has been replaced by |section|. So we can
-use \localtoc after a \csa{chapter}. But if you want one after a
-\csa{section}, you should modify \csb{etocaftertitlehook} to assign
-|subsection| level to the \localtoc own styling.
+With release \etocrelease{1.2} some issues which were previously described here
+when the ``to toc'' feature of \ctanpkg{memoir} was left acting on local TOCs
+have been resolved, as an after-effect of the support for
+\etocoption{localtoctotoc} etc..., see \csb{etocsetup}.
\subsection{Compatibility with \ctanpkg{beamer}}
@@ -6251,14 +6542,15 @@ first.
% 2015/11/12
% Pour une raison que j'ignore dans la TOC principale j'ai un problème avec
% cette sous-section.
+% \subsection{Com\-pat\-i\-bil\-ity with \ctanpkg{multicol}}
-\subsection{Com\-pat\-i\-bil\-ity with \ctanpkg{multicol}}
+\subsection{Compatibility with \ctanpkg{multicol}}
\etoc loads the package \ctanpkg{multicol}.
\subsection{Compatibility with \ctanpkg{tocloft}}\label{subs:tocloft}
-Release |1.07k| added compatibility with package
+Release \etocrelease{1.07k} added compatibility with package
\ctanpkg{tocloft}: steps are
taken to prevent the redefinition of |\tableofcontents| done by
\ctanpkg{tocloft} at |\begin{document}|.
@@ -6269,7 +6561,7 @@ One may still benefit from the \emph{depth tags} management by \etoc,
from its |\localtableofcontents|, from its |\label+\ref| mechanism. One
may use |\etocsetstyle| to define via \etoc the layout for one TOC and
then use rather \ctanpkg{tocloft} for another one, if |\tableofcontents| follows
-\csb{etocstandardlines} and \csb{etocstandarddisplaystyle}. In this
+\csb{etocstandardlines} and \csb{etocclasstocstyle}. In this
compatibility mode |\etocsetlevel{division unit}{6}| will render
invisible the chosen division level, but exchanging levels is otherwise
not possible.
@@ -6286,6 +6578,14 @@ It is possible to modify midway in the document the macros \csa{l@section},
typeset by \etoc in compatibility mode (and of course after those
customizations). It will have no effect on true \etoc TOCs.
+\subsection{Compatibility with \ctanpkg{tocbibind}}\label{subs:tocbibind}
+
+Added at \etocrelease{1.2}. See also \csb{etocsetup} for a discussion of the
+ package options which are all related to this (they will achieve the
+ \ctanpkg{tocbibind} ``to toc'' features without requiring the package).
+
+Thanks to Denis Bitouzé for feature request.
+
\subsection{Compatibility with \ctanpkg{tocvsec2}}
\etoc used to be incompatible with package
@@ -6300,7 +6600,7 @@ customizations). It will have no effect on true \etoc TOCs.
It is possible to use simultaneously \etoc and
\ctanpkg{tableof}. Release
-|1.08| of \etoc requires at least version |1.4a| of \ctanpkg{tableof}. If
+\etocrelease{1.08} of \etoc requires at least version |1.4a| of \ctanpkg{tableof}. If
\csb{etocglobaldefs} is put in the preamble, this must be after the loading of
package \ctanpkg{tableof}. {\color{niceone}\ctanpkg{tableof}} command \csa{nexttocwithtags}
should work as expected.
@@ -6312,10 +6612,44 @@ documentation they do not typeset a TOC title. They should \emph{not} be used
in case \csb{etocglobaldefs} was issued before, except if its scope has been
terminated since then, or \csb{etoclocaldefs} has cancelled its influence.
-\subsection{Compatibility with \ctanpkg{tocstyle}}
+\subsection{Compatibility with \ctanpkg{tocbasic}}
+\label{ssec:tocbasic}
-Unknown. (not tested a.t.t.o.w).
+(doc last updated for \etocrelease{1.2})
+This has only been tested to the extent of production of this PDF file (which
+does have dozens of TOCs, among them a few in compatibility mode). I
+noticed that some things required the global display style to also be set
+to compatiblity mode for some \ctanpkg{KOMA-script} user interface to produce
+the desired effect. As an example, the local table of contents of
+\autoref{sec:testingcompat} uses |\KOMAoptions{toc=left}| and
+\csb{etocstandardlines} but it had to use also \csb{etocclasstocstyle}:
+\begin{verbatim}
+\begingroup % to keep in particular toc=left with local effect
+\KOMAoptions{toc=left}
+\etocclasstocstyle % necessary for the display to obey toc=left
+\etocstandardlines
+\tableofcontents \ref{toc:tocstyle}
+\endgroup
+\end{verbatim}
+On the other hand I could use some other interface without having to activate
+the compatibility for the global display style. See \hyperref[toc:d]{the example} from
+\autoref{sec:labeling} or the one from the \autoref{part:control} which uses
+\begin{verbatim}
+\begingroup
+\etocsettocstyle{}{}
+\DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section}
+\DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection}
+\DeclareTOCStyleEntry[numwidth=3em,indent=4.5em]{tocline}{subsubsection}
+\etocstandardlines
+\localtableofcontents
+\endgroup
+\end{verbatim}
+and demonstrates that this interface works also when not using the
+compatibility mode from \csb{etocclasstocstyle}. Of course, here the
+display style is a bit plain... but the \hyperref[toc:d]{example} of
+\autoref{sec:labeling} less so; it uses about the same TOCStyleEntry lines as
+above with some more width for the numbers of subsections.
\section{\TeX nical matters}
@@ -6328,7 +6662,7 @@ number.
On the other hand \csb{etocthename}, \csb{etocthenumber}, \csb{etocthepage}
are \emph{not} protected against expansion. And neither are
\csb{etocthelinkedname}, \csb{etocthelinkednumber}, \csb{etocthelinkedpage}.
-They were modified at |1.1a| and now are always hyperlinks (except for the
+They were modified at \etocrelease{1.1a} and now are always hyperlinks (except for the
latter if the page number is empty), if
\ctanpkg{hyperref} is present, independently of |linktoc| status.
@@ -6376,6 +6710,12 @@ contents will be displayed only on the second compilation.
\normalmarginpar\marginparwidth72bp
\part{The code}
+% return to single spacing
+\setstretch{1}
+
+\etocdefaultlines
+\etocsettocstyle{}{}
+
\localtableofcontents
% IL FAUT METTRE AVANT \section{Timestamps} SINON FOUTU
@@ -6418,6 +6758,7 @@ contents will be displayed only on the second compilation.
}
\fi
\makeatother
+
\section{Timestamp}
This is the documentation as of \texttt{\etocdocdate}, printed from the
@@ -6446,7 +6787,10 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
\parindent \z@
\parfillskip \@flushglue
\parskip \tw@\p@ plus 1fil\relax
- \let \do \@makeother \dospecials \makestarlowast \catcode`$ \active
+ \let \do \@makeother
+ \dospecials
+ \makestarlowast
+ \catcode`$ \active
\begingroup\lccode`~`$
\lowercase{\endgroup\def~[##1]{\foreignlanguage{ngerman}{##1}}}%
\catcode`^ \active
@@ -6455,9 +6799,12 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
% plus de mark-up cependant
\catcode`\~\z@
\footnotesize\normalfont\baselineskip10pt\relax
-% 2022/08/30, I remove all "v"'s from version numbers.
% \def\v{\vskip\baselineskip v}% ajouté 2015/05/09; faudra trouver mieux.
- \def\1{\vskip\baselineskip 1}% ajouté 2015/05/09; faudra trouver mieux.
+% 2022/08/30, I remove all "v"'s from version numbers.
+% 2023/01/25, creating hypertargets
+ \begingroup\lccode`~32
+ \lowercase{\endgroup
+ \def\1##1~{\vskip\baselineskip\hypertarget{v1##1}{1##1}~}}%
% 2022/08/26, stop using \frenchspacing
% \frenchspacing
% 2023/01/14
@@ -6483,6 +6830,8 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
\makeatother
\begin{multicols}{2}
+% un \raggedcolumns ne fonctionne pas vraiment pour faire de l'alignement
+% de grid à cause du \parskip
\makeatletter
\everypar{\leftskip\jfverbadim\bgroup
\def\par{\egroup\jfverbadim\z@\@@par}%
@@ -6492,8 +6841,84 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
\begingroup\obeyspaces\def\x{\endgroup%
\def {\ifvmode\advance\jfverbadim.5em\relax\else\expandafter\jfverbaspace\fi}}\x
\makeatother
+\vskip-\baselineskip
\begin{jfverbatim}
-1.1c [2023/01/20]^
+~1.2 [2023/03/01]^
+
+ \locallistoffigures and \locallistoftables.
+
+ It is for time being required to pass options `lof', resp. `lot'
+ at package loading time to activate these features. Whether or
+ not these features are enabled, etoc interferes in absolutely no
+ way with \listoffigures and \listoftables and their respective
+ auxiliary files.
+
+ Boolean options (and utility \etocsetup) `maintoctotoc',
+ `localtoctotoc', `localloftotoc', `locallottotoc', and
+ `ouroboros'. For above reasons, no `mainloftotoc' or
+ `mainlottotoc'. With `ouroboros=false` local TOCs whose heading
+ has been added to the `.toc' file due to `localtoctotoc` will show
+ deeper ones and the local `lists of' from their own level, but not
+ themselves.
+
+ Compatibility layer with `tocbibind'. Thanks to Denis Bitouzé for
+ feature request many years ago. Sorry for the delay!
+
+ New feature (and breaking change): local tables of contents
+ in the default package configuration auto-adapt their titles
+ to use the appropriate unnumbered division heading (for example
+ a \subsection* if inside a \section).
+
+ Formerly, it was intended one would use \etocsettocstyle (or
+ higher level commands), else local TOCs were rendered using the
+ same emulation of the document class as for the main TOC. One can
+ still require this document class emulation but then etoc tries at
+ least to adapt to the division unit one level below \part (i.e.
+ \chapter or \section). E.g., for KOMA-script the option
+ `leveldown' is used. But this is not appropriate for deeper
+ levels in general.
+
+ Ultimate control of toc titling can still be achieved via
+ \etocsettocstyle. Many commands have been added to ease its
+ usage. It is also possible to customize the default behavior
+ without \etocsettocstyle.
+
+ Details of the user interface and produced output from these novel
+ commands and options are susceptible to change. Use at own risk.
+
+ Bugfix: the emptiness check could fail for
+ \localtableofcontentswithrelativedepth as it ignored tocdepth changes
+ originating from inside the .toc file, contrarily to the actual
+ typesetting (and behavior with other local tocs)
+
+ Bugfix: the \tableofcontents\ref{foo} syntax caused a
+ ``Missing number'' after \vpageref{foo} from package varioref
+ in certain circumstances due to \r@foo having then acquired a
+ value with an unexpected non-numerical first chunk.
+
+ Breaking change: the \etocsavedsectiontocline et al. macros
+ which raised a deprecation warning since 1.1a now use an
+ error message.
+
+ \expanded primitive is required.
+
+~1.1d (not released, part of 1.2)^
+
+ Complete internal refactoring of the legacy core code behind
+ the concept of ``start'' and ``finish'' parts for line styles.
+
+ \etocifunknownlevelTF and \etoclevel abstract away some
+ internals and may be useful for class or package authors.
+
+ \etocsetlevel filters out forbidden keywords `all', `none' and
+ others. Its second argument can be an expression.
+
+ \etocsetstyle checks and warns appropriately if the level is
+ unknown to etoc or has a non-accepted numerical value.
+
+ Extensive refactoring of the documentation.
+
+~1.1c [2023/01/20]^
Fix a brace removal bug in the construction of \etocname. It
remained without visible effects in documents using hyperref and
@@ -6628,7 +7053,8 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
Syncs with KOMA-script deprecation of \iftocfeature.
-~1.09a, 1.09b [2019/11/17]^
+~1.09b [2019/11/17]^~par~nobreak~vskip-~parskip~vskip-~baselineskip
+~1.09a ^
Sync with memoir v3.7i which has a better location of the TOC
hyperref anchor. The \etocaftertitlehook can now freely be
@@ -6648,9 +7074,9 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
~1.08p [2018/07/04]^
Fixed bug surfacing in case of linktoc=page option of hyperref.
- Thanks to Denis Bitouzé for report (cf.
- https://github.com/ho-tex/hyperref/issues/65,
- https://github.com/dbitouze/yathesis/issues/61).
+ Thanks to Denis Bitouzé for report. Cf:~\
+ https://github.com/ho-tex/hyperref/issues/65~\
+ https://github.com/dbitouze/yathesis/issues/61
~1.08o [2018/06/15]^
@@ -6902,7 +7328,7 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
grateful thanks to all!
-~1.07l [2014/04/22]^
+~vskip~baselineskip1.07l [2014/04/22]^
Fixes a bug with the 1.07k compatibility layer with tocloft which had broken
the 1.07k (sic) compatibility with memoir (yes, memoir class 1.07k testing
@@ -7125,7 +7551,13 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
% 9 mars 2015
% Pour rappel on avait dans le préambule:
% \def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
+% 28 février 2023
+% Mis à jour
+% \def\MacroFont{\ttfamily\hyphenchar\font45\relax\setstretch{1}}
% ce qui donne donc le \macro@font qui sera utilisé.
+% J'ai déjà fait \setstretch{1} au déput de la partie The code, donc
+% je peux le supprimer ici
+\def\macro@font{\ttfamily\hyphenchar\font45\relax}
% 26 septembre 2021
\catcode1 14 % pour pouvoir utiliser ^^A, car je l'avais mis à \active
@@ -7354,6 +7786,10 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
% let code line numbers really be fully in the margin
\MacroIndent\z@
+% 2023/02/22, 1.2 uses setspace
+% 2023/02/27, I return to single line spacing finally
+%\AddToHook{env/macrocode/before}{\vskip.5\baselineskip}
+
\makeatother
% 18 janvier 2023 fix d'un problème de guillements courbes et d'inutilité de upquote,
@@ -7370,6 +7806,7 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
% will be used in code comments
% I could re-define \csb, but perhaps better as the mark-up is not yet there
% when I define this to opt for a new name
+\makeatletter
\DeclareRobustCommand\csbc[1]{{\hypersetup{linkcolor=macrocodelinktocodelinecolor}%
\ifcsname r@etocmacro-#1\endcsname
\hyperref[etocmacro-#1]{\ttfamily\hyphenchar\font45 \char`\\ #1}%
@@ -7379,17 +7816,31 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}.
\hyperref[etocmacro-\xintTrimUnbraced{-4}{#1}]
{\ttfamily\hyphenchar\font45 \char`\\ #1}%
\else
- \textcolor{red}{\ttfamily\hyphenchar\font45 \char`\\ #1}%
+% red color was not enough for me to identify misspelled macro names
+% but I should have a warning mechanism, the problem is how to
+% have it activated only at right time?
+ {\fboxsep-\fboxrule\color{Orchid}%
+ %\fbox{\textcolor{red}{\ttfamily\hyphenchar\font45 \char`\\ #1}}%
+ \fbox{\ttfamily\hyphenchar\font45 \char`\\ #1}%
+ }%
+% ah ok let's do this (2023/01/22, 1.2)
+ \ifcsname r@etocmacro-etocname\endcsname
+ \expanded{\noexpand\AtEndDocument
+ {\noexpand\PackageError{etoc}{Pas de référence à #1\on@line}%
+ {Corriger!}
+ }%
+ }%
+ \fi
\fi
\fi }%
}
-
+\makeatother
\setcounter{secnumdepth}{3}
\paragraph{About the syntax highlighting of the code:}
Control\normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
- The ``syntax highlighting'' was added at release 1.09f of 2022/08/30.\par}
+ The ``syntax highlighting'' was added at release \etocrelease{1.09f} of 2022/08/30.\par}
sequences are mostly hyperlinks. When a user level command gets defined it
hyperlinks to the user documentation with bold face and
\textbf{\textcolor{macrocodelinktouserdoccolor}{using this colour}}. Further
@@ -7401,7 +7852,7 @@ And such non-user level macros, at the location of
their first definitions will have their names displayed using bold face and
\textbf{\textcolor{macrocodenewmacrocolor}{this colour}} (it is not
an hyperlink then). Comments located \emph{inside} the code source (very little are
-left at |1.1a|) have been configured
+left at \etocrelease{1.1a}) have been configured
\textcolor{macrocodecommentcolor}{to be rendered in their own colour}, and
\textcolor{macrocodenoncscolor}{non commented-out and non-control sequences
tokens use this colour}. Other tokens use the fall-back normal colour.
@@ -7428,21 +7879,21 @@ Known limitations:
\paragraph{An apology:}
the code comments served mainly as a record for the author's benefit
of the historical evolution of the package and rarely as a description of what
-the macros do. At |1.1a| I have removed almost all code comments which had
+the macros do. At \etocrelease{1.1a} I have removed almost all code comments which had
accumulated as in a palimpsest. As a result, very few comments actually
-remain. |1.1c| re-added comments to those parts of the code which
-got refactored at and since |1.1a|, revigorating the palimpsest stratification.
+remain. \etocrelease{1.1c} re-added comments to those parts of the code which
+got refactored at and since \etocrelease{1.1a}, revigorating the palimpsest stratification.
\paragraph{About \etoc and the processing of \texttt{.toc} file data:}
\etoc,%
%
\normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
This paragraph and the next were added very late in the history of the
- package, at 1.09h and later.\par}
+ package, at \etocrelease{1.09h} and later.\par}
%
when not left in compatibility mode, hijacks the \csa{contentsline} expansion
so as to not execute \csa{l@chapter}, \csa{l@section} etc..., but rather to
-parse the date and extract from it the \emph{name}, \emph{number}, and
+parse the data and extract from it the \emph{name}, \emph{number}, and
\emph{page number}.
%
The \LaTeX{} |.toc| data
@@ -7458,15 +7909,15 @@ there. Things would have been much easier for \etoc in 2012 if the
of things with which \TeX\ can compute, in general) separately, each providing
an argument to \csa{contentsline}. But some mix is prepared, which may depend
on the document class also, and besides usually handles \csa{part} levels very
-differently. Fortunately upstream changes happen rarely.
+differently. Fortunately upstream changes happen rarely.%
%
\normalmarginpar\marginpar{\footnotesize\rmfamily\itshape\RaggedRight
- Prior to \texttt{1.1a}, \etoc aliased \csa{l@chapter},
+ Prior to \etocrelease{1.1a}, \etoc aliased \csa{l@chapter},
\csa{l@section}, etc... (at the time of TOC typesetting only)
to its own \csbc{Etoc@lxyz} in order to leave time to
\ctanpkg{hyperref} to add its mark-up. Thus the disentangling
of name from number
- was more complex than it is now. With \texttt{1.1a}, \etoc
+ was more complex than it is now. With \etocrelease{1.1a}, \etoc
leaves \csa{l@chapter} etc... unmodified (and unused) and
only hijacks \csa{contentsline}.}
%
@@ -7537,17 +7988,84 @@ of real structure in a \LaTeX{} document body).
%
%</none>
%<*package>
-% |1.1a| implements a radical change to legacy core internals for compatibility
+% \etocrelease{1.1a} implements a radical change to legacy core internals for compatibility
% with some (future) \ctanpkg{hyperref} changes. In order to facilitate this
% overhaul, we require \LaTeX{} 2020/10/01 for the fourth argument to
% \cs{contentsline} lines in the |.toc| file to be always present.
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[2020/10/01]
\ProvidesPackage{etoc}
-[2023/01/20 v1.1c Completely customisable TOCs (JFB)]
+[2023/03/01 v1.2 Completely customisable TOCs (JFB)]
+% \end{macrocode}
+% \etocrelease{1.2} adds experimental support (only tested with standard
+% classes and few packages) for \csbc{locallistoffigures} and
+% \csbc{locallistoftables}. Did I say this is experimental? When \LaTeX{}
+% will have added official hook to \csa{addcontentsline}, I will probably
+% revise the way \etoc hacks into it for this \emph{experimental}
+% functionality.
+%
+% As it is \textbf{experimental}, I think we can all agree I don't have
+% to spend too much space documenting it in user manual. So I shall be
+% brief when I will get to it. And I will remain brief here too.
+%
+% Now that \etoc uses package options, I will use \ctanpkg{kvoptions} as I am
+% familiar with it. I understand upstream \LaTeX{} now has support for
+% key-value input, put I simply have had no time to read the interface.
+% Besides not sure it was there for the |2020/10/01| required release.
+% \begin{macrocode}
+\RequirePackage{kvoptions}
+\SetupKeyvalOptions{prefix=Etoc@}
+\newif\ifEtoc@lof
+\DeclareVoidOption{lof}{\Etoc@loftrue
+ \PackageInfo{etoc}{Experimental support for \string\locallistoffigures.\MessageBreak
+ Barely tested, use at own risk}%
+}
+\newif\ifEtoc@lot
+\DeclareVoidOption{lot}{\Etoc@lottrue
+ \PackageInfo{etoc}{Experimental support for \string\locallistoftables.\MessageBreak
+ Barely tested, use at own risk}%
+}
+\@ifclassloaded{memoir}{
+\PackageInfo{etoc}
+ {As this is with memoir class, all `...totoc' options\MessageBreak
+ are set true by default. Reported}
+\DeclareBoolOption[true]{maintoctotoc}
+\DeclareBoolOption[true]{localtoctotoc}
+\DeclareBoolOption[true]{localloftotoc}
+\DeclareBoolOption[true]{locallottotoc}
+}{
+\DeclareBoolOption[false]{maintoctotoc}
+\DeclareBoolOption[false]{localtoctotoc}
+\DeclareBoolOption[false]{localloftotoc}
+\DeclareBoolOption[false]{locallottotoc}
+}
+\DeclareBoolOption[true]{ouroboros}
+\DeclareDefaultOption{\PackageWarning{etoc}{Option `\CurrentOption' is unknown.}}
+\ProcessKeyvalOptions*
+\DisableKeyvalOption[action=error,package=etoc]{etoc}{lof}
+\DisableKeyvalOption[action=error,package=etoc]{etoc}{lot}
+\def\etocsetup#1{\setkeys{etoc}{#1}}
+\def\etocifmaintoctotoc{\ifEtoc@maintoctotoc
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi}
+\def\etociflocaltoctotoc{\ifEtoc@localtoctotoc
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi}
+\def\etociflocalloftotoc{\ifEtoc@localloftotoc
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi}
+\def\etociflocallottotoc{\ifEtoc@locallottotoc
+ \expandafter\@firstoftwo
+ \else
+ \expandafter\@secondoftwo
+ \fi}
\RequirePackage{multicol}
-\DeclareOption*{\PackageWarning{etoc}{Option `\CurrentOption' is unknown.}}
-\ProcessOptions\relax
\def\etoc@{\etoc@}
\long\def\Etoc@gobtoetoc@ #1\etoc@{}
\newtoks\Etoc@toctoks
@@ -7563,19 +8081,22 @@ of real structure in a \LaTeX{} document body).
\let\Etoc@global\@empty
\def\etocglobaldefs{\let\Etoc@global\global\let\tof@global\global}
\def\etoclocaldefs {\let\Etoc@global\@empty\let\tof@global\@empty}
-\newif\ifEtoc@jj % book
-\newif\ifEtoc@j % part
-\newif\ifEtoc@ % chapter
-\newif\ifEtoc@i % section
-\newif\ifEtoc@ii % subsection
-\newif\ifEtoc@iii % subsubsection
-\newif\ifEtoc@iv % paragraph
-\newif\ifEtoc@v % subparagraph
-\newif\ifEtoc@number
+% \end{macrocode}
+% Some have been renamed at \etocrelease{1.2}.
+% \begin{macrocode}
+\newif\ifEtoc@numbered
\newif\ifEtoc@hyperref
\newif\ifEtoc@parskip
\newif\ifEtoc@tocwithid
-\newif\ifEtoc@standard
+\newif\ifEtoc@standardlines
+% \end{macrocode}
+% These next three added at \etocrelease{1.2}. The latter two for handling
+% compatibility layer with \ctanpkg{tocloft}
+% and \ctanpkg{tocbibind}.\par^^A encore ce problème de ligne supp si plein!
+% \begin{macrocode}
+\newif\ifEtoc@etocstyle
+\newif\ifEtoc@classstyle
+\newif\ifEtoc@keeporiginaltoc
\newif\ifEtoc@skipprefix
\newif\ifEtoc@isfirst
\newif\ifEtoc@localtoc
@@ -7583,93 +8104,149 @@ of real structure in a \LaTeX{} document body).
\newif\ifEtoc@stoptoc
\newif\ifEtoc@notactive
\newif\ifEtoc@mustclosegroup
-\newif\ifEtoc@emptytoc
+\newif\ifEtoc@isemptytoc
\newif\ifEtoc@checksemptiness
\def\etocchecksemptiness {\Etoc@checksemptinesstrue }
\def\etocdoesnotcheckemptiness {\Etoc@checksemptinessfalse }
\newif\ifEtoc@notocifnotoc
\def\etocnotocifnotoc {\Etoc@checksemptinesstrue\Etoc@notocifnotoctrue }
\newcounter{etoc@tocid}
-\newcounter{etoc@tocdepth}
-\@ifclassloaded{memoir}{\def\Etoc@minf{-\thr@@}}{\def\Etoc@minf{-\tw@}}
-\def\Etoc@@minustwo@@{-\tw@}
-\let\Etoc@@minusone@@\m@ne
-\let\Etoc@@zero@@ \z@
-\let\Etoc@@one@@ \@ne
-\let\Etoc@@two@@ \tw@
-\let\Etoc@@three@@ \thr@@
-\chardef\Etoc@@four@@ 4
-\chardef\Etoc@@five@@ 5
-\chardef\Etoc@@six@@ 6
-\def\Etoc@@minustwo@{minustwo}
-\def\Etoc@@minusone@{minusone}
-\def\Etoc@@zero@ {zero}
-\def\Etoc@@one@ {one}
-\def\Etoc@@two@ {two}
-\def\Etoc@@three@ {three}
-\def\Etoc@@four@ {four}
-\def\Etoc@@five@ {five}
+\def\Etoc@tocext{toc}
+\def\Etoc@lofext{lof}
+\def\Etoc@lotext{lot}
+\let\Etoc@currext\Etoc@tocext
+\def\etocifislocal{\ifEtoc@localtoc\expandafter\@firstoftwo\else
+ \expandafter\@secondoftwo\fi
+ }
+\def\etocifislocaltoc{\etocifislocal{\ifx\Etoc@currext\Etoc@tocext
+ \expandafter\@firstoftwo\else
+ \expandafter\@secondoftwo\fi}%
+ {\@secondoftwo}%
+ }
+\def\etocifislocallof{\etocifislocal{\ifx\Etoc@currext\Etoc@lofext
+ \expandafter\@firstoftwo\else
+ \expandafter\@secondoftwo\fi}%
+ {\@secondoftwo}%
+ }
+\def\etocifislocallot{\etocifislocal{\ifx\Etoc@currext\Etoc@lotext
+ \expandafter\@firstoftwo\else
+ \expandafter\@secondoftwo\fi}%
+ {\@secondoftwo}%
+ }
+% \end{macrocode}
+% Formerly a \LaTeX{} counter |etoc@tocdepth| was declared here but at
+% \etocrelease{1.2} it has been replaced by macro storage.
+% \begin{macrocode}
\expandafter\def\csname Etoc@-3@@\endcsname {-\thr@@}
-\expandafter\let\csname Etoc@-2@@\endcsname \Etoc@@minustwo@@
-\expandafter\let\csname Etoc@-1@@\endcsname \Etoc@@minusone@@
-\expandafter\let\csname Etoc@0@@\endcsname \Etoc@@zero@@
-\expandafter\let\csname Etoc@1@@\endcsname \Etoc@@one@@
-\expandafter\let\csname Etoc@2@@\endcsname \Etoc@@two@@
-\expandafter\let\csname Etoc@3@@\endcsname \Etoc@@three@@
-\expandafter\let\csname Etoc@4@@\endcsname \Etoc@@four@@
-\expandafter\let\csname Etoc@5@@\endcsname \Etoc@@five@@
-\expandafter\let\csname Etoc@6@@\endcsname \Etoc@@six@@
-\let\Etoc@all@@ \Etoc@@five@@
+\expandafter\def\csname Etoc@-2@@\endcsname {-\tw@}
+\expandafter\let\csname Etoc@-1@@\endcsname \m@ne
+\expandafter\let\csname Etoc@0@@\endcsname \z@
+\expandafter\let\csname Etoc@1@@\endcsname \@ne
+\expandafter\let\csname Etoc@2@@\endcsname \tw@
+\expandafter\let\csname Etoc@3@@\endcsname \thr@@
+\expandafter\chardef\csname Etoc@4@@\endcsname 4
+\expandafter\chardef\csname Etoc@5@@\endcsname 5
+\expandafter\chardef\csname Etoc@6@@\endcsname 6
+\expandafter\let\expandafter\Etoc@@six@@\csname Etoc@6@@\endcsname
+\@ifclassloaded{memoir}{\def\Etoc@minf{-\thr@@}}{\def\Etoc@minf{-\tw@}}
\let\Etoc@none@@ \Etoc@minf
+\expandafter\let\expandafter\Etoc@all@@ \csname Etoc@5@@\endcsname
+\let\Etoc@dolevels\@empty
+\def\Etoc@newlevel #1{\expandafter\def\expandafter\Etoc@dolevels\expandafter
+ {\Etoc@dolevels\Etoc@do{#1}}}
+% \end{macrocode}
+% \etocrelease{1.2} has done some refactoring here (and above), reducing
+% the number of definitions. Formerly each defined sectioning level got two
+% macros assigned to it: one holding the numerical level (as chardef or count,
+% or even tokens for |-\tw@|), the other in a textual representation such as
+% |minusone|. The latter do not get defined anymore.
+%
+% MEMO: the name space here is poor and I should definitely have used
+% something such as \csa{Etoc@level@section}, not \csa{Etoc@section@@}.
+%
+% So \etocrelease{1.2} adds here \csbc{etocifunknownlevelTF} and
+% \csbc{etoclevel} for a higher level interface, which may be used by third
+% parties such as the \ctanpkg{yathesis} class and will allow \etoc at some
+% point to modify its internal naming conventions.
+%
+% The |-\tw@| case needed for \csbc{Etoc@minf} (or for \ctanpkg{memoir}) means
+% that two expansions of \csbc{etoclevel} do not always deliver a single
+% token, it is at any rate always self-delimiting in assignments and
+% \csa{ifnum} tests. I hesitated using only explicit digit tokens by the way.
+%
+% The dummy sectioning levels ``all'' and ``none'' play a special role and
+% will be declared by \csbc{etocifunknownlevelTF} as ``known''. They should
+% not be used as first argument of \csbc{etocsetlevel}...\par^^A TO FIX WHITELINE
+% \begin{macrocode}
+\def\etocsetlevel#1#2{\expanded{\noexpand\etoc@setlevel{#1}{#2}}}%
+\def\etoc@setlevel#1#2{%
+ \edef\Etoc@tmp{\the\numexpr#2}%
+ \if1\ifnum\Etoc@tmp>\Etoc@@six@@0\fi\ifnum\Etoc@tmp<-\tw@0\fi1%
+ \in@{.#1,}{.none,.all,.figure,.table,.-3,.-2,.-1,.0,.1,.2,.3,.4,.5,.6,}%
+% \end{macrocode}
+% Letter or other agnostic test. First time I ever use \csa{@car} as I never
+% paid attention to its existence and in more macro-coding intensive context
+% such as \ctanpkg{xint} I use my own.
+% \begin{macrocode}
+ \ifin@\else\if\@car#1\@nil @\in@true\fi\fi
+ \ifin@
+ \PackageWarning{etoc}
+ {Sorry, but `#1' is forbidden as level name.\MessageBreak
+ \if\@car#1\@nil @%
+ (because of the @, especially as first character)\MessageBreak\fi
+ Reported}%
+ \else
+ \etocifunknownlevelTF{#1}{\Etoc@newlevel{#1}}{}%
+ \expandafter\let\csname Etoc@#1@@\expandafter\endcsname
+ \csname Etoc@\Etoc@tmp @@\endcsname
+% \end{macrocode}
+% This is a mechanism to allow ``to toc'' entries to not break the core
+% mechanism for local tables of contents (now also lists of) to correctly
+% know their scope, when for example we have in a row
+% \csbc{localtableofcontents}, \csbc{locallistoffigures},
+% \csbc{locallistoftables} and each has created its ``to toc'' entry:
+% main TOC will handle the |@<division>| as aliases to |<division>| and local
+% TOCs and Lists Of will ignoer them.
+% \begin{macrocode}
+ \expandafter\edef\csname Etoc@@#1@@\endcsname
+ {\expandafter\noexpand\csname Etoc@#1@@\endcsname}%
+% \end{macrocode}
+% As ``to toc'' will use some \csa{addcontentsline}, we must make
+% \ctanpkg{hyperref} happy.
+% \begin{macrocode}
+ \expandafter\edef\csname toclevel@@#1\endcsname
+ {\expandafter\noexpand\csname toclevel@#1\endcsname}%
% \end{macrocode}
-% At |1.1a|, the \csa{etocsavedsectiontocline} and cousins are deprecated and
-% when they will be removed, \csbc{Etoc@levelist} will be too as it now serves
-% only for their definitions.
-% \begin{macrocode}
-\let\Etoc@levellist\@empty
-\def\Etoc@newlevel #1{\expandafter\def\expandafter\Etoc@levellist\expandafter
- {\Etoc@levellist\Etoc@levellist@elt{#1}}}
-\def\etocsetlevel#1#2{%
- \@ifundefined{Etoc@#1@@}{\Etoc@newlevel{#1}}{}%
- \ifcase#2\relax
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@zero@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@zero@
- \or
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@one@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@one@
- \or
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@two@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@two@
- \or
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@three@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@three@
- \or
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@four@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@four@
- \or
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@five@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@five@
- \or
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@six@@
+% But we don't let \csa{toclevel\string#1} to \csa{Etoc@tmp}, with some
+% hesitation. The level defined by \csbc{etocsetlevel} should only be
+% for interpretation for the contents of the |.toc| file. If for some reason
+% user wants to set all levels to six (i.e. not taken into account) except for
+% some special ones, then modifying \csa{toclevel\string#1} could prevent the
+% local TOC title to find a place in the bookmarks.
+% \begin{macrocode}
+ \fi
\else
- \ifnum#2=\m@ne
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@minusone@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@minusone@
- \else
- \ifnum#2=-\tw@
- \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@minustwo@@
- \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@minustwo@
- \else
\PackageWarning{etoc}
- {Unexpected value `#2' in \string\etocsetlevel.\MessageBreak
- It must be one of -2,-1, 0, 1, 2, 3, 4, 5, or 6 and\MessageBreak
- will be set to 6: the \string\contentsline\space entries of type\MessageBreak
- `#1' will be ignored by `etoc'.\MessageBreak Reported}%
+ {Argument `\detokenize{#2}' of \string\etocsetlevel\space should
+ represent\MessageBreak
+ -2, -1, 0, 1, 2, 3, 4, 5, or 6 but evaluates to \Etoc@tmp.\MessageBreak
+ The level of `#1' will be set to 6.\MessageBreak
+ Tables of contents will ignore `#1' as long\MessageBreak
+ as its level is 6.\MessageBreak
+ Reported}%
+ \etocifunknownlevelTF{#1}{\Etoc@newlevel{#1}}{}%
\expandafter\let\csname Etoc@#1@@\endcsname\Etoc@@six@@
- \fi
- \fi
\fi
}
+% \end{macrocode}
+% Maybe let it first use \csbc{etocifunknownlevelTF} and raise in the
+% ``unknown'' branch a suitable expandable error message (and return say |-3|)?
+%
+% I may also need for internal usage a variant for only numerical |#1| which be
+% submitted to a \csa{the}\csa{numexpr}. Not so far.
+% \begin{macrocode}
+\def\etoclevel#1{\csname Etoc@#1@@\endcsname}
+\def\etocifunknownlevelTF#1{\@ifundefined{Etoc@#1@@}}
\etocsetlevel{book}{-2}
\etocsetlevel{part}{-1}
\etocsetlevel{chapter}{0}
@@ -7679,220 +8256,146 @@ of real structure in a \LaTeX{} document body).
\etocsetlevel{paragraph}{4}
\etocsetlevel{subparagraph}{5}
% \end{macrocode}
-% |1.09g| adapts to \ctanpkg{hyperref} depending on
-% whether the latter is at |7.00u| or earlier. Indeed internal changes to
-% \ctanpkg{hyperref} at |7.00u| broke \etoc. Thanks to Denis~\textsc{Bitouzé} for
-% reporting the issue.
+% Prior to \etocrelease{1.2}, only under class \ctanpkg{memoir} was
+% \csbc{etocsetlevel} used with |appendix|. It does not seem to hurt to do it
+% generally, with a check whether document class provides chapters.
+% \begin{macrocode}
+\ifdefined\c@chapter
+ \etocsetlevel{appendix}{0}
+\else
+ \etocsetlevel{appendix}{1}
+\fi
+\def\Etoc@do#1{\@namedef{l@@#1}{\csname l@#1\endcsname}}
+\Etoc@dolevels
+% \end{macrocode}
+% We do not do a formal \csbc{etocsetlevel}|{figure}{6}| and anyhow the user
+% level interface forbids |figure| and |table| as first argument.
+% \begin{macrocode}
+\let\Etoc@figure@@\Etoc@@six@@
+\let\Etoc@table@@\Etoc@@six@@
+% \end{macrocode}
+% \etocrelease{1.09g} adapts to \ctanpkg{hyperref} depending on whether the
+% latter is at |7.00u| or earlier. Indeed internal changes to
+% \ctanpkg{hyperref} at |7.00u| broke \etoc. Thanks to Denis~\textsc{Bitouzé}
+% for reporting the issue.
%
-% |1.1a| radically simplifies matters at \etoc core, and with this in
-% place there would have been no incompatibility with the \ctanpkg{hyperref}
-% |7.00u| internal changes.
+% \etocrelease{1.1a} radically simplifies matters at \etoc core, and if these
+% changes had been in place earlier there would have been no incompatibility
+% with the \ctanpkg{hyperref} |7.00u| release.
% \begin{macrocode}
\AtBeginDocument{%
\@ifpackageloaded{parskip}{\Etoc@parskiptrue}{}%
\@ifpackageloaded{hyperref}{\Etoc@hyperreftrue}{}%
}
+\def\etocskipfirstprefix {\global\Etoc@skipprefixtrue }
% \end{macrocode}
-% |2015/03/08| One has to be careful about the |Etoc@end@<level>| user
-% defined macros which may close groups. This has always been the reason
-% for the |\global|'s here and elsewhere.
-%
-% Attention that \csbc{Etoc@setflags} must not modify \csa{Etoc@next}!
-% \begin{macrocode}
-\def\Etoc@setflags {%
- \ifcase \Etoc@level
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iifalse
- \global\Etoc@ifalse
- \global\Etoc@true
- \or
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iifalse
- \global\Etoc@itrue
- \or
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iitrue
- \or
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiitrue
- \or
- \global\Etoc@vfalse
- \global\Etoc@ivtrue
- \or
- \global\Etoc@vtrue
- \else
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iifalse
- \global\Etoc@ifalse
- \global\Etoc@false
- \ifnum\Etoc@level=\m@ne
- \global\Etoc@jtrue
- \else
- \global\Etoc@jfalse
- \global\Etoc@jjtrue
- \fi
- \fi
-}
-% \end{macrocode}
-% One has to be careful that this may close
-% groups. The conditionals are all global. The \csbc{Etoc@level} has been
-% |\global\let| to a |\chardef| variable. The final |\else| of the
-% |\ifcase| assumes none of the \csa{Etoc@end@..} routines modify it,
-% naturally.
-% \begin{macrocode}
-\def\Etoc@doends {%
- \ifcase \Etoc@level
- \ifEtoc@v \Etoc@end@five \fi
- \ifEtoc@iv \Etoc@end@four \fi
- \ifEtoc@iii\Etoc@end@three\fi
- \ifEtoc@ii \Etoc@end@two \fi
- \ifEtoc@i \Etoc@end@one \fi
- \or
- \ifEtoc@v \Etoc@end@five \fi
- \ifEtoc@iv \Etoc@end@four \fi
- \ifEtoc@iii\Etoc@end@three\fi
- \ifEtoc@ii \Etoc@end@two \fi
- \or
- \ifEtoc@v \Etoc@end@five \fi
- \ifEtoc@iv \Etoc@end@four \fi
- \ifEtoc@iii\Etoc@end@three\fi
- \or
- \ifEtoc@v \Etoc@end@five \fi
- \ifEtoc@iv \Etoc@end@four \fi
- \or
- \ifEtoc@v \Etoc@end@five \fi
- \or
- \else
- \ifEtoc@v \Etoc@end@five \fi
- \ifEtoc@iv \Etoc@end@four \fi
- \ifEtoc@iii\Etoc@end@three\fi
- \ifEtoc@ii \Etoc@end@two \fi
- \ifEtoc@i \Etoc@end@one \fi
- \ifEtoc@ \Etoc@end@zero \fi
- \ifnum \Etoc@level =-\tw@
- \ifEtoc@j \Etoc@end@minusone\fi
- \fi
- \fi
-}
-% \end{macrocode}
-% Calls \csbc{Etoc@setflags} which must not modify \csa{Etoc@next}.
+% Start of heart of \etoc's hacks into the execution of the |.toc| file
+% commands. It goes via a redefinition of \csa{contentsline} which will
+% launch an extraction process leading to the construction of \csbc{etocname},
+% \csbc{etocnumber}, and \csbc{etocpage}, then the styles as defined by user
+% via \csbc{etocsetstyle} get executed in accordance to the levels.
+%
+% In passing \etoc is witness to the linear succession of sectioning levels
+% and executes the \marg{start} and \marg{finish} parts of each used level at
+% the right time (they are rather called ``|begin|'' and ``|end|'' in the code
+% though).
+%
+% \etocrelease{1.2} did a complete rewrite of how \etoc creates virtually
+% a nesting structure out of the flat succession of the \csa{contentsline}'s
+% for various levels. Ever since the first release this was based on using
+% boolean flags, one for each level. The flag was on if the level had been
+% seen, hence its ``begin'' macro executed, but not yet its ``end'' macro.
+% This is now replaced by a stack storage \csbc{Etoc@stackofends} which is
+% simply, e.g. |{2}{0}{-3}{}|, to mean that first a chapter (|0|) was seen
+% then a subsection (|2|). The |{-3}{}| trail is for matters of avoiding
+% brace removal in the implementation next (I could have replaced it by a
+% single token being numerically |-3|).
+%
+% When a new level is encountered and set in \csbc{Etoc@level}, it is compared
+% to the left most entry in the stack. If higher, the ``begin'' macro is
+% executed and the \csbc{Etoc@level} is pushed (as a digit with possibly a
+% minus sign) to the left of the stack to record that the ``end'' macro is now
+% on the queue for execution (sic). If equal, nothing has to be done, if
+% lower, the ``end'' macro of the left-most stored level is executed then this
+% level is removed, and one proceeds with the next one, etc... legacy code was
+% using a bunch of TeX conditionals rather, and I recall how in 2012 I was
+% unfamiliar with its strange syntax and had lots of troubles; once I got
+% something working it got frozen and basically did not change since then.
+% The \etocrelease{1.2} implementation has replaced all of this by
+% maintenance of a single ``stack'', which is more economical in terms of
+% used macros and potentially more scalable too.
+%
+% About \csbc{Etoc@level} I have hesitated using only digit and sign tokens,
+% but it is currently let to some \csa{chardef} (in exceptional
+% \ctanpkg{memoir} case of |book| level it can expand to |-\tw@|, and there is
+% also the \csa{m@ne} count). \etocrelease{1.2} thus keeps defining such
+% \csa{chardef}'s but has at least dropped auxiliary macros (see the
+% definitions prior to \csbc{etocsetlevel}) which held some alphabetical
+% denotations such as ``minusone'' or ``zero'', and the \emph{begin},
+% \emph{prefix}, \emph{content} and \emph{end} macros associated with each
+% level now use a digit (and sign perhaps) (see \csbc{etocsetstyle}). With
+% \csbc{Etoc@level} already storing directly such a digit, one would avoid a
+% \csa{number} or \csa{the}\csa{numexpr} at some places, but would have to be
+% more careful in the various \csa{ifnum}.
+%
+% This (always globally defined) \csbc{Etoc@level} must now never be set to
+% the numerical value \texttt{6}: it is legal to add to the |.toc| file dummy
+% sectioning levels associated to the numerical level \texttt{6} (such dummy
+% sectioning will be ignored but can be assigned locally a non-ignored level
+% for special effects) and if \csbc{Etoc@level} was, as prior to
+% \etocrelease{1.2}, systematically set to the numerical level of the
+% last seen \csa{contentsline}, this could cause \csbc{Etoc@@startlocaltoc} to
+% fail to correctly set the ``local top''. Indeed it now only has
+% \csbc{Etoc@level} at his disposal, the legacy boolean flags being gone.
+%
+% The \csa{Etoc@isfirsttrue} was formally incorporated as last token of the
+% ``begin'' macros as defined by \csbc{etocsetstyle}, but has been displaced
+% by \etocrelease{1.2} to the code below.
% \begin{macrocode}
-\def\Etoc@dobegins{%
- \let\Etoc@next\@empty
- \Etoc@global\Etoc@isfirstfalse
- \ifcase\Etoc@level
- \ifEtoc@
- \else
- \def\Etoc@next{\Etoc@begin@zero}%
- \fi
- \or
- \ifEtoc@i
- \else
- \def\Etoc@next{\Etoc@begin@one}%
- \fi
- \or
- \ifEtoc@ii
- \else
- \def\Etoc@next{\Etoc@begin@two}%
- \fi
- \or
- \ifEtoc@iii
- \else
- \def\Etoc@next{\Etoc@begin@three}%
- \fi
- \or
- \ifEtoc@iv
- \else
- \def\Etoc@next{\Etoc@begin@four}%
- \fi
- \or
- \ifEtoc@v
- \else
- \def\Etoc@next{\Etoc@begin@five}%
- \fi
- \else
- \ifnum\Etoc@level=\m@ne
- \ifEtoc@j
- \else
- \def\Etoc@next{\Etoc@begin@minusone}%
- \fi
- \else
- \ifEtoc@jj
- \else
- \def\Etoc@next{\Etoc@begin@minustwo}%
- \fi
- \fi
- \fi
- \Etoc@setflags
- \Etoc@next
+\def\Etoc@updatestackofends#1\etoc@{\gdef\Etoc@stackofends{#1}}
+\def\Etoc@stackofends{{-3}{}}
+\def\Etoc@doendsandbegin{%
+ \expandafter\Etoc@traversestackofends\Etoc@stackofends\etoc@
}
-\def\etocskipfirstprefix {\global\Etoc@skipprefixtrue }
% \end{macrocode}
-% Heart of \etoc's hacks into the execution of the |.toc| file commands.
+% We compare the new level with those for which the \marg{start} parts of the
+% \csbc{etocsetstyle} declarations have been executed to decide if it is time
+% to execute their \marg{finish} parts. In passing we set the boolean
+% \csbc{ifEtoc@isfirst} which is needed for \csbc{etociffirst} and
+% \csbc{etocxiffirst}.
% \begin{macrocode}
-\def\Etoc@etoccontentsline #1{%
- \global\expandafter\let\expandafter\Etoc@level\csname Etoc@#1@@\endcsname
- \Etoc@skipthisonefalse
- \ifnum\Etoc@level=\Etoc@@six@@
- \Etoc@skipthisonetrue
- \else
- \ifEtoc@localtoc
- \ifEtoc@stoptoc
- \Etoc@skipthisonetrue
- \else
- \ifEtoc@notactive\Etoc@setflags
- \Etoc@skipthisonetrue
- \else
- \unless\ifnum\Etoc@level>\etoclocaltop
- \Etoc@skipthisonetrue
- \global\Etoc@stoptoctrue
- \fi
- \fi
- \fi
- \fi
- \fi
- \let\Etoc@next\@gobblefour
- \ifEtoc@skipthisone
- \else
- \unless\ifnum\c@tocdepth<\Etoc@level
- \ifEtoc@standard
- \let\Etoc@next\Etoc@savedcontentsline
- \else
- \let\Etoc@next\Etoc@etoccontentsline@
- \fi
+\def\Etoc@traversestackofends#1{%
+ \ifnum#1>\Etoc@level\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi
+ {\csname Etoc@end@#1\endcsname
+ \Etoc@traversestackofends
+ }%
+ {\ifnum#1<\Etoc@level
+ \csname Etoc@begin@\the\numexpr\Etoc@level\endcsname
+ \Etoc@global\Etoc@isfirsttrue
+ \edef\Etoc@tmp{{\the\numexpr\Etoc@level}}%
+ \else
+ \Etoc@global\Etoc@isfirstfalse
+ \let\Etoc@tmp\@empty
\fi
- \fi
- \Etoc@next{#1}%
+ \expandafter\Etoc@updatestackofends\Etoc@tmp{#1}%
+ }%
}
% \end{macrocode}
-% Ever since the first release of \etoc, the code has
-% to be careful that the |\Etoc@end@<level>| user defined macros may
-% close groups. This is the reason why some assignments have to be done
-% globally (|2015/03/08|).
-%
-% |1.1a| of |2023/01/14| implements a radical change to legacy core internals for
-% compatibility with (attow future) \ctanpkg{hyperref}. Formerly
-% \csbc{Etoc@etoccontentsline@} fetched only the first argument.
-% It now also fetches all four (the fourth argument of
-% \csa{contentsline} is always present since \LaTeX{}
-% |2020/10/01|). The \csbc{Etoc@lxyz} used to receive only the two
-% arguments (possibly hacked by \ctanpkg{hyperref})
-% of \csa{l@chapter}, \csa{l@section}, etc..., (these macros had
-% been |\let| to \csbc{Etoc@lxyz}), and examined them to see if they
-% were carrying hyperlinking data. The |1.1a| and later
-% version receives as third
-% argument the fourth one of \csa{contentsline}, i.e.\@ the
-% hyperlinking target, and
-% adds the hyperlinking according to the status of
+% Ever since the first release of \etoc, the code has to be careful that the
+% |\Etoc@end@<level>| user defined macros may close groups. This is the reason
+% why some assignments have to be done globally (|2015/03/08|).
+%
+% \etocrelease{1.1a} of |2023/01/14| implements a radical change to legacy
+% core internals for compatibility with (attow future) \ctanpkg{hyperref}.
+% Formerly \csbc{Etoc@etoccontentsline@} fetched only the first argument. It
+% now also fetches all four (the fourth argument of \csa{contentsline} is
+% always present since \LaTeX{} |2020/10/01|). The \csbc{Etoc@lxyz} used to
+% receive only the two arguments (possibly hacked by \ctanpkg{hyperref}) of
+% \csa{l@chapter}, \csa{l@section}, etc..., (these macros had been |\let| to
+% \csbc{Etoc@lxyz}), and examined them to see if they were carrying
+% hyperlinking data. The \etocrelease{1.1a} and later version receives as
+% third argument the fourth one of \csa{contentsline}, i.e.\@ the hyperlinking
+% target, and adds the hyperlinking according to the status of
% \ctanpkg{hyperref}'s \csa{Hy@linktoc}.
%
% This is a breaking change if a user hacked \csa{contentsline} to do some
@@ -7921,48 +8424,101 @@ of real structure in a \LaTeX{} document body).
% empty. This maintains backwards-compatibility with earlier releases of
% \etoc.
% \begin{macrocode}
+\def\Etoc@etoccontentsline #1{%
+ \let\Etoc@next\@gobblefour
+ \ifnum\csname Etoc@#1@@\endcsname=\Etoc@@six@@
+ \else
+ \Etoc@skipthisonefalse
+% \end{macrocode}
+% MEMO: the mechanism added to make
+% added toc entries from ``list of'' titles invisible to the local tocs,
+% will be with |#1| starting with an |@|. In that case \csa{Etoc@\string#1@@}
+% is not a \csa{chardef} but expands to one (or to a count or |-\tw@| perhaps,
+% or a |\numexpr...\relax|).
+% \begin{macrocode}
+ \global\expandafter\let\expandafter\Etoc@level\csname Etoc@#1@@\endcsname
+% \end{macrocode}
+% The trick goes through a slight overhead here to filter out such special
+% level names and do not make them update what will serve as top level for
+% local tocs or listsof. Formerly this was managed by booleans, then for
+% \etocrelease{1.1d} (released as \etocrelease{1.2}) it got replaced by
+% sole usage of \csbc{Etoc@level}, and finally a specific
+% \csbc{Etoc@virtualtop} which gets its updates here.
+% \begin{macrocode}
+ \if @\@car#1\@nil\else\global\let\Etoc@virtualtop\Etoc@level\fi
+ \ifEtoc@localtoc
+ \ifEtoc@stoptoc
+ \Etoc@skipthisonetrue
+ \else
+ \ifEtoc@notactive
+ \Etoc@skipthisonetrue
+ \else
+ \unless\ifnum\Etoc@level>\etoclocaltop
+ \Etoc@skipthisonetrue
+ \global\Etoc@stoptoctrue
+ \fi
+ \fi
+ \fi
+ \fi
+ \ifEtoc@skipthisone
+ \else
+ \unless\ifnum\Etoc@level>\c@tocdepth
+ \ifEtoc@standardlines
+ \let\Etoc@next\Etoc@savedcontentsline
+ \else
+ \let\Etoc@next\Etoc@etoccontentsline@
+ \fi
+ \fi
+ \fi
+ \fi
+ \Etoc@next{#1}%
+}
+% \end{macrocode}
+% Hesitation at \etocrelease{1.2} about having \csbc{Etoc@level} being
+% always explicit digit and perhaps negative sign. For now is a
+% \csa{chardef} or \csa{m@ne} \csa{count} (perhaps |-\tw@| also).
+% \begin{macrocode}
\def\Etoc@etoccontentsline@ #1#2#3#4{%
- \Etoc@doends
- \Etoc@dobegins
+ \Etoc@doendsandbegin
\Etoc@global\edef\Etoc@prefix {\expandafter\noexpand
- \csname Etoc@prefix@\csname Etoc@#1@\endcsname\endcsname }%
+ \csname Etoc@prefix@\the\numexpr\Etoc@level\endcsname }%
\Etoc@global\edef\Etoc@contents{\expandafter\noexpand
- \csname Etoc@contents@\csname Etoc@#1@\endcsname\endcsname }%
- \ifEtoc@skipprefix \Etoc@global\let\Etoc@prefix\@empty\fi
+ \csname Etoc@contents@\the\numexpr\Etoc@level\endcsname }%
+ \ifEtoc@skipprefix \Etoc@global\def\Etoc@prefix{\@empty}\fi
\global\Etoc@skipprefixfalse
\Etoc@lxyz{#2}{#3}{#4}%
- \Etoc@prefix\Etoc@contents
+ \Etoc@prefix
+ \Etoc@contents
}
% \end{macrocode}
-% A \textbf{breaking change} is made at |1.1a|: \csbc{etoclink} will always
-% create an hyperlink, even in case of \ctanpkg{hyperref} being (possibly
-% locally) configured to obey |linktoc=none|. Formerly, in such case,
-% \csbc{etoclink} added no hyperlink because \etoc identified the hyperlink
-% target from
-% the \ctanpkg{hyperref} hacked arguments of \csa{l@section} et al, rather
-% than picking it from the fourth argument of \csa{contentsline}.
-%
-% Another \textbf{breaking change} (documented only at |1.1b|): all three
-% of \csbc{etocthelinkedname}, \csbc{etocthelinkednumber}, and
-% \csbc{etocthelinkedpage} are always hyperlinks (for the latter, only if
-% page number is not empty to match \ctanpkg{hyperref} ways).
-% Formerly they obeyed the |linktoc| status,
-% somewhat counterintuitively, but this meant that \csbc{etocname} etc...
-% were their robust variants, which meant one could store easily for later
-% usage (see the documentation examples with ``treetoks'') their precise
-% meaning. The breaking change happened in part because I was fooled myself
-% by the macro names, and refactored the code in two steps separated by months
-% so in second step I forgot I had only provisory code. And I decided finally
-% to keep the breaking change.
-%
-% Under |linktoc=page| option, \ctanpkg{hyperref} has a ``feature'' to
-% add one level of bracing to first argument of the \csa{l@section} etc
-% macros. So for \etoc |<1.1a| this meant some extra work to dig into such a
-% possible brace pair to check if the entry was numbered. At |1.1a|, the
+% A \textbf{breaking change} is made at \etocrelease{1.1a}: \csbc{etoclink}
+% will always create an hyperlink, even in case of \ctanpkg{hyperref} being
+% (possibly locally) configured to obey |linktoc=none|. Formerly, in such
+% case, \csbc{etoclink} added no hyperlink because \etoc identified the
+% hyperlink target from the \ctanpkg{hyperref} hacked arguments of
+% \csa{l@section} et al, rather than picking it from the fourth argument of
+% \csa{contentsline}.
+%
+% Another \textbf{breaking change} (documented only at \etocrelease{1.1b}):
+% all three of \csbc{etocthelinkedname}, \csbc{etocthelinkednumber}, and
+% \csbc{etocthelinkedpage} are always hyperlinks (for the latter, only if page
+% number is not empty to match \ctanpkg{hyperref} ways). Formerly they obeyed
+% the |linktoc| status, somewhat counterintuitively, but this meant that
+% \csbc{etocname} etc... were their robust variants, which meant one could
+% store easily for later usage (see the documentation examples with
+% ``treetoks'') their precise meaning. The breaking change happened in part
+% because I was fooled myself by the macro names, and refactored the code in
+% two steps separated by months so in second step I forgot I had only
+% provisory code. And I decided finally to keep the breaking change.
+%
+% Under |linktoc=page| option, \ctanpkg{hyperref} has a ``feature'' to add one
+% level of bracing to first argument of the \csa{l@section} etc macros. So
+% for \etoc |<1.1a| this meant some extra work to dig into such a possible
+% brace pair to check if the entry was numbered. At \etocrelease{1.1a}, the
% \ctanpkg{hyperref} modified \csa{contentsline} is not executed, hence there
-% is no such complication. But the trimming of the now unneeded branches
-% was not yet done at |1.1a/b| and got completed only at |1.1c|, together
-% with some renamings and refactoring.
+% is no such complication. But the trimming of the now unneeded branches was
+% not yet done at \etocrelease{1.1a}, \etocrelease{1.1b}, and got completed
+% only at \etocrelease{1.1c}, together with some renamings and refactoring.
% \begin{macrocode}
\def\Etoc@lxyz #1#2#3{%
\ifEtoc@hyperref
@@ -7972,10 +8528,11 @@ of real structure in a \LaTeX{} document body).
\fi
\Etoc@global\def\etocthepage {#2}%
% \end{macrocode}
-% Prior to |1.1a| an hyperlink was incorporated into \csbc{etocthelinkedpage}
-% only if \ctanpkg{hyperref} added an hyperlink to the page number, i.e.\@
-% under |linktoc=page| or |linktoc=all| (and a non empty page number). With
-% |1.1a|, the hyperlink is always added (if a non empty page number).
+% Prior to \etocrelease{1.1a} an hyperlink was incorporated into
+% \csbc{etocthelinkedpage} only if \ctanpkg{hyperref} added an hyperlink to
+% the page number, i.e.\@ under |linktoc=page| or |linktoc=all| (and a non
+% empty page number). With \etocrelease{1.1a}, the hyperlink is always added
+% (if a non empty page number).
% \begin{macrocode}
\ifEtoc@hyperref
\ifx\etocthepage\@empty
@@ -7987,15 +8544,16 @@ of real structure in a \LaTeX{} document body).
\Etoc@global\let\etocthelinkedpage\etocthepage
\fi
% \end{macrocode}
-% Define \csbc{etocthename} but this will perhaps be adjusted later if it is found
-% out that the entry was numbered.
+% Define \csbc{etocthename} but this will perhaps be adjusted later if it is
+% found out that the entry was numbered.
% \begin{macrocode}
\Etoc@global\def\etocthename{#1}%
% \end{macrocode}
% Now we check if the entry is numbered and disentangle the number from the
-% name to define correctly \csbc{etocthename} and \csbc{etocthenumber}.
-% The delimiter tokens were modified at |1.1c| for a slight optimization.
-% And secondary macros have less to do since the |1.1a| initiated refactoring.
+% name to define correctly \csbc{etocthename} and \csbc{etocthenumber}. The
+% delimiter tokens were modified at \etocrelease{1.1c} for a slight
+% optimization. And secondary macros have less to do since the
+% \etocrelease{1.1a} initiated refactoring.
% \begin{macrocode}
\futurelet\Etoc@getnb@token\Etoc@@getnb #1\hspace\etoc@
% \end{macrocode}
@@ -8006,18 +8564,18 @@ of real structure in a \LaTeX{} document body).
%
% In presence of \ctanpkg{hyperref} we let always \csbc{etocthelinkedname} and
% \csbc{etocthelinkednumber} (for a numbered entry) carry an hyperlink. This
-% is a \textbf{breaking change} at |1.1a|: formerly if the TOC (or the
-% specific entry in the |.toc| file, as it is always possibly to inject
+% is a \textbf{breaking change} at \etocrelease{1.1a}: formerly if the TOC (or
+% the specific entry in the |.toc| file, as it is always possibly to inject
% \csa{hypersetup}) was typeset under |linktoc=none| or |linktoc=page| status,
% then no hyperlinks were incorporated. This is how \csbc{etocthename} and
% \csbc{etocthenumber} are configured, but \csbc{etocthelinkedname} and
-% \csbc{etocthelinkednumber} will since |1.1a| always be hyperlinked in
-% presence of \ctanpkg{hyperref}.
+% \csbc{etocthelinkednumber} will since \etocrelease{1.1a} always be
+% hyperlinked in presence of \ctanpkg{hyperref}.
% \begin{macrocode}
\ifEtoc@hyperref
\def\Etoc@tmp##1##2{\Etoc@global\def##2{\hyperlink{#3}{##1}}}%
\expandafter\Etoc@tmp\expandafter{\etocthename}\etocthelinkedname
- \ifEtoc@number
+ \ifEtoc@numbered
\expandafter\Etoc@tmp\expandafter{\etocthenumber}\etocthelinkednumber
\else
\Etoc@global\let\etocthelinkednumber\@empty
@@ -8039,15 +8597,28 @@ of real structure in a \LaTeX{} document body).
\fi
}
% \end{macrocode}
-% In presence of \ctanpkg{hyperref}, \etoc |1.1a| imports the
+% In presence of \ctanpkg{hyperref}, \etoc \etocrelease{1.1a} imports the
% \ctanpkg{hyperref} own logic and tests \csa{Hy@linktoc} to decide if
% \emph{name}, \emph{number} and \emph{page} get hyperlinks. This adds a
% dependency that \csa{Hy@linktoc} should exist and have the expected
% interpretation.
-% \begin{framed}
+% \begin{shaded}
+% \setstretch{1}%
% \textbf{MEMO:} \emph{Matters of tagging will have to wait for \LaTeX\ itself
% to show me what it does in \csa{l@section} etc... so that I can imitate.}
-% \end{framed}
+%
+% Updated 2023/02/26: this is now partly available and gave me an idea of
+% what will be needed here. As the \etoc way goes through none of the
+% \LaTeX{} hook points, I will have to add the suitable \csa{UseHook} at
+% various places, after having stored the \csa{contentsline} original
+% arguments in the same macros as the \LaTeX{} new kernel code will do.
+%
+% Some difficulties though in perspective as \etoc separates name and number
+% and has no concept akin to \csa{@dottedtocline}. Also if the user employs
+% \csbc{etocsetstyle} with \csa{l@section}, hooks may be executed twice if I
+% put them not in \csbc{etocname} but in the \marg{prefix} and \marg{content}
+% parts for each level.\par
+% \end{shaded}
% \begin{macrocode}
\def\Etoc@lxyz@linktoc{%
\ifcase\Hy@linktoc
@@ -8071,18 +8642,18 @@ of real structure in a \LaTeX{} document body).
% But this step can cause brace removal so we \csa{futurelet} to
% peek ahead.
%
-% Prior to |1.1a| it could be possible that the first token following
+% Prior to \etocrelease{1.1a} it could be possible that the first token following
% \csbc{Etoc@@getnb} was an opening brace and nevertheless the entry was
% numbered, because of a \ctanpkg{hyperref} ``feature'' in case of
-% |linktoc=page| option. But at |1.1a|, \etoc handles directly the argument
+% |linktoc=page| option. But at \etocrelease{1.1a}, \etoc handles directly the argument
% of \csa{contentsline} so the presence of an opening brace implies the entry
-% is not numbered. For some reason |1.1a| kept the extra code to check in
+% is not numbered. For some reason \etocrelease{1.1a} kept the extra code to check in
% case the next token was an opening brace whether the whole entry was braced,
-% which would have been indicative in the past (but not at |1.1a|) of a
-% |linktoc=page| context (\etoc prior to |1.1a| never tested the value of
+% which would have been indicative in the past (but not at \etocrelease{1.1a}) of a
+% |linktoc=page| context (\etoc prior to \etocrelease{1.1a} never tested the value of
% \csa{Hy@linktoc} as it did not want to be dependent on details of
% \ctanpkg{hyperref} handling of options). This legacy, now superfluous, code
-% branch is removed at |1.1c|, bringing some simplification here, in
+% branch is removed at \etocrelease{1.1c}, bringing some simplification here, in
% particular the removal of an \csa{ifEtoc@bracedname} boolean. Also, when
% branching from here to the \csbc{Etoc@getnb@nonbr}, we won't need to check
% if the entry had a special ``Part'' syntax, which is another simplification.
@@ -8099,27 +8670,27 @@ of real structure in a \LaTeX{} document body).
\Etoc@next
}
% \end{macrocode}
-% |1.08n| tries to handle reasonably the \csa{nonumberline} of
+% \etocrelease{1.08n} tries to handle reasonably the \csa{nonumberline} of
% \ctanpkg{KOMA-script}. If it expands to |\numberline{}|, \etoc will
% consider the line numbered with an empty number (afaict, the meaning of
% \csa{nonumberline} is either empty or \csa{numberline}|{}|). This got
-% modified at |1.1c| (see below).
+% modified at \etocrelease{1.1c} (see below).
%
-% At |1.09f| we get rid of the \csa{nonumberline} from inside
+% At \etocrelease{1.09f} we get rid of the \csa{nonumberline} from inside
% \csbc{etocthename} when it has empty meaning, so the expansion of the latter
% can safely be delayed by custom section styles (for example if the build up
-% some token list to be executed later not immediately). |1.1c| fixes a
-% regression committed at |1.1a|: for a \csa{nonumberline} with empty
+% some token list to be executed later not immediately). \etocrelease{1.1c} fixes a
+% regression committed at \etocrelease{1.1a}: for a \csa{nonumberline} with empty
% meaning the \csbc{etocthelinkedname} did not end up hyperlinked.
%
% A change, almost a bug fix, but the former behavior was actually
-% deliberate, at |1.1c| regarding the KOMA-script \csa{nonumberline}
+% deliberate, at \etocrelease{1.1c} regarding the KOMA-script \csa{nonumberline}
% token: formerly, when it expanded to \csa{numberline}|{}| (this
% can happen only when the TOC is typeset in compatibility mode for
-% the global display) then \csbc{ifEtoc@number} was set to true.
+% the global display) then \csbc{ifEtoc@numbered} was set to true.
% But this is only a KOMA-script typesetting thing, and should not
% have influenced \etoc's decisions when its (user or package) own
-% line styles are used: at |1.1c| it is thus decided that in such
+% line styles are used: at \etocrelease{1.1c} it is thus decided that in such
% circumstances the \csbc{etocifnumbered} will pick the false
% branch, and the empty \csbc{etocthelinkednumber} will not be
% hyperlinked.
@@ -8129,7 +8700,7 @@ of real structure in a \LaTeX{} document body).
% opening brace.
%
% The \csbc{Etoc@@getit} branch for ``Parts'' used to be executed from inside
-% \csbc{Etoc@lxyz}. At |1.1c| we jump directly to it from here.
+% \csbc{Etoc@lxyz}. At \etocrelease{1.1c} we jump directly to it from here.
% \begin{macrocode}
\def\Etoc@getnb #1{%
\in@{#1}{\numberline\chapternumberline\partnumberline\booknumberline}%
@@ -8143,7 +8714,7 @@ of real structure in a \LaTeX{} document body).
\fi
% \end{macrocode}
% Remove a KOMA-script \csa{nonumberline} token if present and process the
-% entry always as not numbered (see above comments). Prior to |1.1c|, the
+% entry always as not numbered (see above comments). Prior to \etocrelease{1.1c}, the
% code branched according to the meaning of the \csa{nonumberline} token,
% which was a bit silly.
% \begin{macrocode}
@@ -8155,15 +8726,15 @@ of real structure in a \LaTeX{} document body).
\Etoc@next #1%
}
% \end{macrocode}
-% Prior to |1.1a|, \csbc{etocthelinkedname} and \csbc{etocthelinkednumber}
+% Prior to \etocrelease{1.1a}, \csbc{etocthelinkedname} and \csbc{etocthelinkednumber}
% (for a numberd entry) were defined to carry links only if an hyperlink was
% actually found, now they are defined in \csbc{Etoc@lxyz} to always provide
% the hyperlinking to the target title in the document.
%
-% |1.1a| and |1.1b| still had here some superfluous code which was trimmed at
-% |1.1c|.
+% \etocrelease{1.1a} and \etocrelease{1.1b} still had here some superfluous code which was trimmed at
+% \etocrelease{1.1c}.
%
-% Also, |1.1c| fixes here a brace removal bug (which had always been there I
+% Also, \etocrelease{1.1c} fixes here a brace removal bug (which had always been there I
% guess): if the numbered heading title was braced one level of bracing was
% removed. The bug had no effect in a document using \ctanpkg{hyperref} (and
% its default |linktoc| setting) as the \csa{hyperlink} wrapper limited the
@@ -8171,7 +8742,7 @@ of real structure in a \LaTeX{} document body).
% input such as |\section{{\color{blue}Stuff}}|.
% \begin{macrocode}
\def\Etoc@getnb@nmbrd #1#2{%
- \Etoc@global\Etoc@numbertrue
+ \Etoc@global\Etoc@numberedtrue
\Etoc@global\def\etocthenumber {#2}%
\Etoc@getnb@nmbrd@getname\@empty
}%
@@ -8185,27 +8756,27 @@ of real structure in a \LaTeX{} document body).
% Not numbered entry.
% \begin{macrocode}
\def\Etoc@getnb@nonbr #1\etoc@ {%
- \Etoc@global\Etoc@numberfalse
+ \Etoc@global\Etoc@numberedfalse
\Etoc@global\let\etocthenumber \@empty
}
% \end{macrocode}
-% Special KOMA branch: |#1| starts with \csa{nonumberline} (prior to |1.1c|
+% Special KOMA branch: |#1| starts with \csa{nonumberline} (prior to \etocrelease{1.1c}
% the |#1| would have already lost this token, and this branch was executed
% only in case \csa{nonumberline} had empty meaning). We need to remove this
% token from |#1| and redefine \csbc{etocthename}.
%
-% |1.1a| code still had here some complications with a ``braced name'' branch
-% which was in fact never executed at |1.1a|, as the \ctanpkg{hyperref} hacks
+% \etocrelease{1.1a} code still had here some complications with a ``braced name'' branch
+% which was in fact never executed at \etocrelease{1.1a}, as the \ctanpkg{hyperref} hacks
% into the expansion of \csa{contentsline} were not executed. These now
-% unneeded complications got removed at |1.1c|.
+% unneeded complications got removed at \etocrelease{1.1c}.
%
-% |1.1c| also fixes a regression caused by |1.1a| in this branch: the
+% \etocrelease{1.1c} also fixes a regression caused by \etocrelease{1.1a} in this branch: the
% \csbc{etocthelinkedname} had lost its hyperlink.
%
% The \csa{nonumberline} extra token guarantees no brace stripping here.
% \begin{macrocode}
\def\Etoc@getnb@nonumberline #1\hspace\etoc@ {%
- \Etoc@global\Etoc@numberfalse
+ \Etoc@global\Etoc@numberedfalse
\Etoc@global\let\etocthenumber \@empty
\Etoc@global\expandafter\def\expandafter\etocthename\expandafter{\@gobble#1}%
}
@@ -8214,7 +8785,7 @@ of real structure in a \LaTeX{} document body).
% possible here when grabbing |#1|, due to previous checks that it does
% not start by a space token or an opening brace.
%
-% |1.1c| handles this as a sub-branch from \csbc{Etoc@@getnb} which brings
+% \etocrelease{1.1c} handles this as a sub-branch from \csbc{Etoc@@getnb} which brings
% simplifications. Also the code has been somewhat strengthened so as to
% avoid in later processing a brace removal issue on the name (which was a bug
% of legacy earlier code), when it turns our we are handling a numbered Part
@@ -8226,18 +8797,18 @@ of real structure in a \LaTeX{} document body).
% \begin{macrocode}
\def\Etoc@@getit #1\hspace#2{%
\ifx\etoc@#2%
- \Etoc@global\Etoc@numberfalse
+ \Etoc@global\Etoc@numberedfalse
\Etoc@global\let\etocthenumber \@empty
\else
- \Etoc@global\Etoc@numbertrue
+ \Etoc@global\Etoc@numberedtrue
\Etoc@global\def\etocthenumber {#1}%
\expandafter\Etoc@getit@getname \expandafter\@empty
\fi
}
% \end{macrocode}
% Chain of \csa{expandafter}'s to get rid of the added \csa{@empty} token to
-% avoid a brace removal. And this is the end of the |1.1a| refactoring,
-% completed at |1.1c|.
+% avoid a brace removal. And this is the end of the \etocrelease{1.1a} refactoring,
+% completed at \etocrelease{1.1c}.
% \begin{macrocode}
\def\Etoc@getit@getname #1\hspace\etoc@ {%
\Etoc@global\expandafter\def\expandafter\etocthename\expandafter{#1}%
@@ -8257,7 +8828,7 @@ of real structure in a \LaTeX{} document body).
\DeclareRobustCommand*{\etocpage} {}
\DeclareRobustCommand*{\etoclink} {\@firstofone}
\DeclareRobustCommand*{\etocifnumbered}
- {\ifEtoc@number\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
+ {\ifEtoc@numbered\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
\expandafter\let\expandafter\etocxifnumbered\csname etocifnumbered \endcsname
\DeclareRobustCommand*{\etociffirst}
{\ifEtoc@isfirst\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
@@ -8272,7 +8843,7 @@ of real structure in a \LaTeX{} document body).
\fi
}
% \end{macrocode}
-% |1.07m| moves the reading of the toc file At Begin Document. Needed for
+% \etocrelease{1.07m} moves the reading of the toc file At Begin Document. Needed for
% Babel activated characters.\par^^A extra \par needed to avoid empty line...
% \begin{macrocode}
\Etoc@toctoks {}% (superfluous, but for clarity)
@@ -8302,64 +8873,407 @@ of real structure in a \LaTeX{} document body).
\fi
\global\let\Etoc@openouttoc\empty
}
+% \end{macrocode}
+% The |\gdef\Etoc@stackofends{{-3}{}}| is in theory superfluous as normally
+% this stack should always have been restored on exit to its initial state,
+% but...
+%
+% It would perhaps be better to issue here \csa{Etoc@notactivetrue}, prior to
+% |\the\Etoc@toctoks| but it is up to the caller macros to do it.
+% \csbc{Etoc@minf} is a level which is lower (i.e. more encompassing than all
+% others), so numerically \texttt{-2} for standard classes and \texttt{-3} for
+% \ctanpkg{memoir} class.
+%
+% The \csbc{Etoc@doendsandbegin} will not try to execute a (non-existing)
+% ``begin'' macro for the level \texttt{-3}.
+% \begin{macrocode}
\def\Etoc@toctoc{%
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iifalse
- \global\Etoc@ifalse
- \global\Etoc@false
- \global\Etoc@jfalse
- \global\Etoc@jjfalse
+ \gdef\Etoc@stackofends{{-3}{}}%
+ \global\let\Etoc@level\Etoc@minf
+ \global\let\Etoc@virtualtop\Etoc@minf
\the\Etoc@toctoks
\ifEtoc@notactive
\else
- \ifEtoc@v \Etoc@end@five\fi
- \ifEtoc@iv \Etoc@end@four\fi
- \ifEtoc@iii \Etoc@end@three\fi
- \ifEtoc@ii \Etoc@end@two\fi
- \ifEtoc@i \Etoc@end@one\fi
- \ifEtoc@ \Etoc@end@zero\fi
- \ifEtoc@j \Etoc@end@minusone\fi
- \ifEtoc@jj \Etoc@end@minustwo\fi
+ \gdef\Etoc@level{-\thr@@}%
+ \Etoc@doendsandbegin
\fi
}
% \end{macrocode}
-% Memo: \csbc{etoclocaltop} has only
-% meaningful meaning when the local toc has its "active" flag set. Except that
-% I used a "notactive" flag to torture myself, so: has the "notactive" flag
-% off.
+% Memo: \csbc{etoclocaltop} has only meaningful meaning when the toc is local
+% and is ``active''. Except that I used a "notactive" flag to torture myself,
+% so: has the \csbc{ifEtoc@notactive} flag set to |false|.
+%
+% The \etocrelease{1.2} removal of usage of boolean flags associated to
+% the levels has made the next definition more succinct. Their former r\^ole is
+% picked up by \csbc{Etoc@level}.
%
-% Also attention |1.09| now sets the \csa{c@tocdepth} there in relation to
-% implementation of \localtocwrdp. This is needed for line styles in
-% compatibility mode as the code from standard classes checks the tocdepth
-% counter.
+% MEMO: the \csbc{etoclocaltableofcontentshook} has been added during development
+% \etocrelease{1.2} probably for reasons of symmetry with handling of the
+% local ``lists of'' code, but at time of release I can't remember clearly.
+% Hesitation where to put it exactly.
+%
+% \etocrelease{1.2} adds a \csbc{Etoc@@startlocaltochook} for a refactoring of
+% \csbc{localtableofcontentswithrelativedepth}. It also serves to make the
+% emptiness check with local ``lists of'', as will be seen further down.
% \begin{macrocode}
-\def\etoc@@startlocaltoc#1#2{%
+\def\Etoc@@startlocaltoc#1#2{%
\ifEtoc@localtoc
\ifnum #1=#2\relax
- \ifEtoc@jj \global\let\etoclocaltop\Etoc@@minustwo@@\fi
- \ifEtoc@j \global\let\etoclocaltop\Etoc@@minusone@@\fi
- \ifEtoc@ \global\let\etoclocaltop\Etoc@@zero@@ \fi
- \ifEtoc@i \global\let\etoclocaltop\Etoc@@one@@ \fi
- \ifEtoc@ii \global\let\etoclocaltop\Etoc@@two@@ \fi
- \ifEtoc@iii \global\let\etoclocaltop\Etoc@@three@@ \fi
- \ifEtoc@iv \global\let\etoclocaltop\Etoc@@four@@ \fi
- \ifEtoc@v \global\let\etoclocaltop\Etoc@@five@@ \fi
- \global\c@tocdepth\Etoc@localtocdepth
+ \global\let\etoclocaltop\Etoc@virtualtop
+ \Etoc@@startlocaltochook
+ \etoclocaltableofcontentshook
+% \end{macrocode}
+% The \csbc{ifEtoc@etocstyle} boolean is true when \etoc is left in its default
+% mode (no usage of \csbc{etocsettocstyle} or \csbc{etocclasstocstyle}). It
+% inhibits \csbc{Etoc@tableofcontents} from using the specified
+% \marg{before\string_toc} and \marg{after\string_toc} from usage of
+% \csbc{etocsettocstyle}. And here we can insert the code we wish to do the
+% title.
+%
+% \begin{shaded}
+% \setstretch{1}%
+% \textbf{MEMO}: for legacy reason \etoc shares a lot of code between global TOC and
+% local TOCs. But it would probably have been better to separate the two and
+% provide an \csa{etocsetlocaltocstyle} that the user can use in preamble.
+% As it stands \csbc{etocsettocstyle} if used in preamble also influences the
+% global TOC, so basically one has to use it again after it (if it comes first
+% in the document).
+% \end{shaded}
+%
+% The \csa{ifEtoc@ouroboros} mechanism when it is set to false appears rather
+% audacious.
+% \begin{macrocode}
+ \ifEtoc@etocstyle
+ \etocetoclocaltocmaketitle
+ \fi
+ \ifx\Etoc@aftertitlehook\@empty
+ \else
+ \ifEtoc@localtoctotoc
+ \ifEtoc@ouroboros
+ \else
+ \let\Etoc@tmp\contentsline
+ \def\contentsline{\let\contentsline\Etoc@tmp\@gobblefour}%
+ \fi
+ \fi
+ \fi
\global\Etoc@notactivefalse
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iifalse
- \global\Etoc@ifalse
- \global\Etoc@false
- \global\Etoc@jfalse
- \global\Etoc@jjfalse
\fi
\fi
}
\let\etoc@startlocaltoc\@gobble
+\let\Etoc@@startlocaltoc@toc\Etoc@@startlocaltoc
+\let\Etoc@@startlocaltochook\@empty
+\def\etocdivisionnameatlevel#1{%
+ \ifcase\numexpr#1\relax
+ \ifdefined\c@chapter chapter\else section\fi%
+ \or section%
+ \or subsection%
+ \or subsubsection%
+ \or paragraph%
+ \or subparagraph%
+ \or empty%
+ \else\ifnum\numexpr#1<\m@ne
+ book%
+ \else
+ part%
+ \fi
+ \fi
+}
+\def\etoclocalheadtotoc#1#2{\addcontentsline{toc}{@#1}{#2}}
+\def\etocglobalheadtotoc{\addcontentsline{toc}}
+% \end{macrocode}
+% I have coded this so that it can be copied pasted to a user document and
+% customized at will. The \csa{par} is in case of a local TOC in a
+% subsubsection or deeper, the heading will then be rendered as a paragraph
+% heading...\par^^A sigh with extra line if full here
+% \begin{macrocode}
+\providecommand*\UseName{\@nameuse}
+\def\etocetoclocaltocmaketitle{%
+ \UseName{\etocdivisionnameatlevel{\etoclocaltop+1}}*{\localcontentsname}%
+ \ifnum\etoclocaltop>\tw@\mbox{}\par\fi
+ \etociflocaltoctotoc
+ {\etocifisstarred
+ {}% star variant, do not add to toc
+ {\etoclocalheadtotoc
+ {\etocdivisionnameatlevel{\etoclocaltop+1}}%
+ {\localcontentsname}%
+ }%
+ }%
+ {}%
+}%
+% \end{macrocode}
+% In dev, I used \csa{etoc} prefix for the next two, but I
+% decided to drop it for release.
+% \begin{macrocode}
+\def\localcontentsname {\contentsname}%
+\let\etoclocaltableofcontentshook\@empty
+% \end{macrocode}
+% The big thing at \etocrelease{1.2}: experimental support code for
+% \csbc{locallistoffigures} and \csbc{locallistoftables}! There were two
+% possibilities to implement the `localtoc' mechanism: either add some extra
+% things to the |.lof| and |.lot| files, or get their data duplicated in the
+% |.toc| file. I have chosen for time being the latter path, hence this goes
+% via hacking into \csa{addcontentsline} and it must be the case that the
+% document class uses it (from \csa{caption}). If some package has modified
+% the implementation of captions of figures and tables and insertes data in
+% the |.lof| or |.lot| files directly via \csa{addtocontents} for example
+% and not via \csa{addcontentsline}, then the \etoc mechanism will fail.
+% \begin{macrocode}
+\if1\ifEtoc@lof0\fi\ifEtoc@lot0\fi1%
+\else
+\AtBeginDocument{%
+ \let\Etoc@originaladdcontentsline\addcontentsline
+ \def\addcontentsline{\Etoc@hackedaddcontentsline}%
+}%
+\fi
+% \end{macrocode}
+% \csa{expanded} is by now available in all engines, I think.
+% \begin{macrocode}
+\def\Etoc@hackedaddcontentsline#1{%
+ \expanded{\noexpand\in@{.#1,}{\ifEtoc@lof.lof,\fi\ifEtoc@lot.lot,\fi}}%
+ \ifin@\expandafter\Etoc@hackedaddcontentsline@i
+ \else\expandafter\Etoc@originaladdcontentsline
+ \fi
+ {#1}%
+}
+% \end{macrocode}
+% This business of \csa{protected@file@percent} is not really needed as anyhow
+% \etoc reads the |.toc| file with no space token from end of lines.
+
+% \begin{macrocode}
+\def\Etoc@hackedaddcontentsline@i#1#2#3{%
+ \expanded{\noexpand\in@{.#1;#2,}}{.lof;figure,.lot;table,}%
+ \ifin@
+ \addtocontents {toc}{%
+ \protect\contentsline{#2}{#3}{\thepage}{\ifEtoc@hyperref\@currentHref\fi}%
+ \ifdefined\protected@file@percent\protected@file@percent\fi
+ }%
+ \fi
+ \Etoc@originaladdcontentsline{#1}{#2}{#3}%
+}
+% \end{macrocode}
+% We will simply let \csbc{locallistoffigures} and \csbc{locallistoftables}
+% use \csbc{localtableofcontents}. We need some dedicated variant of
+% \csbc{Etoc@@startlocaltoc}. Hesitation where to put
+% \csbc{Etoc@@startlocaltochook} which has multiple usages.
+% \begin{macrocode}
+\def\Etoc@@startlocallistof#1#2#3{%
+ \ifEtoc@localtoc
+ \ifnum #2=#3\relax
+ \global\let\etoclocaltop\Etoc@virtualtop
+ \global\Etoc@notactivefalse
+ \Etoc@@startlocaltochook
+ \csname etoclocallistof#1shook\endcsname
+ \ifEtoc@etocstyle
+ \csname etocetoclistof#1smaketitle\endcsname
+ \fi
+ \fi
+ \fi
+}
+\def\Etoc@@startlocallistof@setlevels#1{%
+% \end{macrocode}
+% |#1| is |figure| or |table|.
+%
+% \csbc{etoclocaltop} represents the level which will stop the local ``list
+% of'' contents. I hesitated whether local ``lists of'' should obey the
+% |tocdepth|, especially a varying one. Finally at last minute I opted for
+% ``Yes'', so in the end no alteration of |tocdepth| will be done here. We
+% will set the level to have value
+% \centeredline{|min(1, |\csbc{etoclocaltop}|+1)|}
+% At least |1|, because it really would not make
+% sense to show figure entries as chapter entries for a local list of figures
+% in a Part (if the user has for example set the
+% \csbc{etoclocallistoffigureshook} to do nothing, so that the line styles as
+% configured via \csbc{etocsetstyle} are not avoided). And it must be greater
+% than \csbc{etoclocaltop} else such an entry would terminate the scope of the
+% local contents.
+%
+% In the default context which has issued via
+% \csbc{etoclocallistoffigureshook} a local \csbc{etocstandardlines}, the
+% actual value of the level only has a ``all or nothing'' meaning: if it is
+% greater than |tocdepth| then the \csbc{Etoc@etoccontentsline} will not call
+% \csa{contentsline}, else it will and then the code from document class will
+% kick in. The |article| class defines \csa{l@figure} as
+% \centeredline{|\@dottedtocline {1}{1.5em}{2.3em}|}
+% And we are here in a context where necessarily |tocdepth| is at least |1|
+% (if it was |0| or less, as the level has been set to at least |1|, the entry
+% would have been filtered out earlier by \csbc{Etoc@etoccontentsline}), so
+% the line will show. And if \csbc{etoclocallistoffigureshook} was modified
+% and did not issue \csbc{etocstandardlines} and we are in this situation that
+% the |tocdepth| comparison did not inhibit the entry, then it will show too,
+% at least if the line style does not say to do nothing (notice that the \etoc
+% fall-back line styles are configured to do nothing for paragraph and
+% subparagraph entries).
+%
+% On the other hand if the |tocdepth| inhibits entries of level
+% \csbc{etoclocaltop}|+1|, then a \csbc{localtableofcontents} at this level
+% would display no contents, so why should it not also mute
+% \csbc{locallistoffigures}?
+%
+% This change to the level \csbc{Etoc@figure@@} or \csbc{Etoc@table@@} is done
+% only locally, no need to worry about collaterals after the ``List of''.
+% \begin{macrocode}
+ \ifnum\etoclocaltop<\z@
+ \expandafter\let\csname Etoc@#1@@\endcsname\@ne
+ \else
+ \expandafter\let\csname Etoc@#1@@\expandafter\endcsname
+ \csname Etoc@\the\numexpr\etoclocaltop+\@ne @@\endcsname
+ \fi
+% \end{macrocode}
+% We now make invisible all level names whose numerical level would have
+% allowed them to show in these contents. |figure| and |table| are never
+% included in the \csbc{Etoc@dolevels} no danger to cancel them out. The
+% special level names |@section| etc... which are inserted by headings of
+% local ``lists of'' or local TOCs under \etocoption{localloftotoc} and other
+% options have been made invisible by \csbc{Etoc@listofhook}, no need to do
+% anything about them here.
+% \begin{macrocode}
+ \def\Etoc@do##1{%
+ \ifnum\etoclevel{##1}>\etoclocaltop
+ \expandafter\let\csname Etoc@##1@@\endcsname\Etoc@@six@@
+ \fi}%
+ \Etoc@dolevels
+}
+% \end{macrocode}
+% Let's for time being configure the figure and table lines to be rendered as
+% in class default.
+%
+% Ah, I remember why I added \csbc{etoclocaltableofcontentshook} above. It is
+% by symmetry as I had defined those next two already.
+% \begin{macrocode}
+\def\etoclocallistoffigureshook{\etocstandardlines}
+\def\etoclocallistoftableshook {\etocstandardlines}
+% \end{macrocode}
+% Here is some info about usage of \csbc{etoclocallistoffigureshook}, for
+% those who end up here from having clicked on the name from the user
+% manual. Its default as above means to use the class default for lines in
+% \csa{listoffigures}. If you redefine it to be empty, the effect is that
+% (except of course if \csbc{etocstandardlines} has been issued globally) the
+% figure lines will adopt the style configured for level
+% \csbc{etoclocaltop}|+1| (or more precisely the minimum of that and of |1|).
+% You can definitely put into the hook some
+% \centeredline{\csbc{etocsetstyle}|{\number\etoclevel{figure}}{}{}{...}{}|}
+% where the dots represent some code with \csbc{etocnumber}, \csbc{etocname},
+% \csbc{etocpage}, itself possibly querying \csbc{etoclevel}|{figure}|, or
+% perhaps \csbc{etoclocaltop} to know the actual depth (which may the one of a
+% Part which can thus be distinguished from being in a Chapter, whereas
+% \csa{number}\csbc{etoclevel}|{figure}| will give |1| in both cases).
+%
+% There is variant which is to maintain the default \csbc{etocstandardlines}
+% in the hook and then re-define the kernel macro \csa{l@figure} to do the
+% desired thing. For example the default with |article| is for \csa{l@figure}
+% to do {|\@dottedtocline {1}{1.5em}{2.3em}|} so you can do some
+% variant where the second and third argument (numwidth and indent) are set
+% according to \csbc{etoclocaltop}.
+%
+% I hope the above explanations help, they appear too advanced for inclusion
+% in the user manual so I give them here.
+%
+% In dev, I used \csa{etoc} prefix here, but I decided to drop it for release.
+% \begin{macrocode}
+\def\locallistfigurename{\listfigurename}
+\def\locallisttablename {\listtablename}
+% \end{macrocode}
+% Same observations as for \csbc{etocetoclocaltocmaketitle}.
+% \begin{macrocode}
+\def\etocetoclistoffiguresmaketitle{%
+ \UseName{\etocdivisionnameatlevel{\etoclocaltop+1}}*{\locallistfigurename}%
+ \ifnum\etoclocaltop>\tw@\mbox{}\par\fi
+ \etociflocalloftotoc
+ {\etocifisstarred
+ {}% star variant, do not add to toc
+ {\etoclocalheadtotoc
+ {\etocdivisionnameatlevel{\etoclocaltop+1}}%
+ {\locallistfigurename}%
+ }%
+ }%
+ {}%
+}%
+\def\etocetoclistoftablesmaketitle{%
+ \UseName{\etocdivisionnameatlevel{\etoclocaltop+1}}*{\locallisttablename}%
+ \ifnum\etoclocaltop>\tw@\mbox{}\par\fi
+ \etociflocallottotoc
+ {\etocifisstarred
+ {}% star variant, do not add to toc
+ {\etoclocalheadtotoc
+ {\etocdivisionnameatlevel{\etoclocaltop+1}}%
+ {\locallisttablename}%
+ }%
+ }%
+ {}%
+}%
+% \end{macrocode}
+% The local lists of do support the |\label/\ref| syntax as we are careful
+% here to position \csbc{localtableofcontents} as last token.
+%
+% The reset to \csa{@empty} of the \csa{Etoc@listofreset} is not strictly
+% needed as the other things can always be done with no harm.
+% \begin{macrocode}
+\let\Etoc@listofreset\@empty
+% \end{macrocode}
+% Memo: \csa{ext@toc} defined in KOMA and memoir but not in the standard classes.
+% \begin{macrocode}
+\def\locallistoffigures{%
+ \ifEtoc@lof
+ \def\Etoc@listofreset{%
+ \let\Etoc@currext\Etoc@tocext
+ \let\Etoc@@startlocaltoc\Etoc@@startlocaltoc@toc
+ \let\Etoc@@startlocaltochook\@empty
+ \let\Etoc@listofreset\@empty
+% \end{macrocode}
+% The \csbc{Etoc@listofhook} is executed by \csbc{localtableofcontents}. It
+% will be used here to let local ``lists of'' ignore all the special |.toc|
+% entries whose level names start with a |@|. This is to avoid the scope
+% limiting detection of the local list of figures or tables from being
+% influenced by another list of, such as a list of tables following a list of
+% figures which has put its title inside the |.toc| due to |locallottotoc|
+% option of \etoc.
+% \begin{macrocode}
+ \let\Etoc@listofhook\@empty
+ }%
+ \let\Etoc@currext\Etoc@lofext
+ \def\Etoc@@startlocaltoc{\Etoc@@startlocallistof{figure}}%
+ \def\Etoc@@startlocaltochook{\Etoc@@startlocallistof@setlevels{figure}}%
+ \def\Etoc@listofhook{%
+ \def\Etoc@do####1{%
+ \expandafter\let\csname Etoc@@####1@@\endcsname\Etoc@@six@@
+ }%
+ \Etoc@dolevels
+ }%
+ \expandafter\localtableofcontents
+ \else
+ \PackageError{etoc}{%
+ \string\locallistoffigures \on@line\space but\MessageBreak
+ package was loaded without `lof' option}%
+ {Try again with \string\usepackage[lof]{etoc}}%
+ \fi
+}
+\def\locallistoftables{%
+ \ifEtoc@lot
+ \def\Etoc@listofreset{%
+ \let\Etoc@currext\Etoc@tocext
+ \let\Etoc@@startlocaltoc\Etoc@@startlocaltoc@toc
+ \let\Etoc@@startlocaltochook\@empty
+ \let\Etoc@listofreset\@empty
+ \let\Etoc@listofhook\@empty
+ }%
+ \let\Etoc@currext\Etoc@lotext
+ \def\Etoc@@startlocaltoc{\Etoc@@startlocallistof{table}}%
+ \def\Etoc@@startlocaltochook{\Etoc@@startlocallistof@setlevels{table}}%
+ \def\Etoc@listofhook{%
+ \def\Etoc@do####1{%
+ \expandafter\let\csname Etoc@@####1@@\endcsname\Etoc@@six@@
+ }%
+ \Etoc@dolevels
+ }%
+ \expandafter\localtableofcontents
+ \else
+ \PackageError{etoc}{%
+ \string\locallistoftable \on@line\space but\MessageBreak
+ package was loaded without `lot' option}%
+ {Try again with \string\usepackage[lot]{etoc}}%
+ \fi
+}
% \end{macrocode}
% \csbc{Etoc@tocid} is the number of the toc (possibly gotten via a |\ref|
% following a \csbc{tableofcontents}), or it is |\z@| if the emptiness test is
@@ -8367,68 +9281,87 @@ of real structure in a \LaTeX{} document body).
% printed at wrong locations naturally and emptiness tests can not be trusted
% either.
%
-% Note: (|1.08i 2016/09/29|) the code has to handle both local and total toc.
-% Hence the flag \csbc{ifEtoc@notactive} has to be set prior to it. For a
-% global toc, the \csbc{Etoc@tocid} was set to |\z@|, and the |\ifnum| in
-% \csbc{etoc@startlocaltoc} did always fail, but I now prefer to simply
-% nullify the \csbc{etoc@startlocaltoc}. As its default fallback is
+% Note: (\etocrelease{1.08i} |2016/09/29|) the code has to handle both local
+% and total toc. Hence the flag \csbc{ifEtoc@notactive} has to be set prior
+% to it. For a global toc, the \csbc{Etoc@tocid} was set to |\z@|, and the
+% |\ifnum| in \csbc{etoc@startlocaltoc} did always fail, but I now prefer to
+% simply nullify the \csbc{etoc@startlocaltoc}. As its default fallback is
% |\@gobble| I simply test here for the \csbc{ifEtoc@localtoc} flag. The
% \csbc{Etoc@tocid} will be undefined for a global toc but it is not tested
% anymore.
%
-% Note: the mechanism for recognizing the level when a local toc is
-% encountered is different from the one in \csbc{etoc@@startlocaltoc} which uses
-% the level flags. Here we just record in \csbc{Etoc@level} where we last stood.
-% The initialization |\global\let\Etoc@level\Etoc@minf| is thus needed in case
-% the |.toc| file contains an \csbc{etoc@startlocaltoc} before any
+% The initialization such as |\global\let\Etoc@level\Etoc@minf| is needed in
+% case the |.toc| file contains an \csbc{etoc@startlocaltoc} before any
% \csa{contentsline}.
+%
+% Local list of figures and tables set especially the tocdepth and a hook is
+% added here for emptiness check to work correctly with them.
+%
+% MEMO: Should I also execute \csbc{etoclocaltableofcontentshook}?
+% Then I would need to set \csbc{etoclocallistoffigureshook} to redefine it,
+% rather than be inserted as itself.
% \begin{macrocode}
-\def\Etoc@setemptytocbool {%
- \global\Etoc@emptytoctrue
+\def\Etoc@checkifempty {%
+ \global\Etoc@isemptytoctrue
\global\Etoc@stoptocfalse
\global\let\Etoc@level\Etoc@minf
+ \global\let\Etoc@virtualtop\Etoc@minf
+ \gdef\Etoc@stackofends{{-3}{}}%
\begingroup
\ifEtoc@localtoc
\def\etoc@startlocaltoc##1{%
\ifnum##1=\Etoc@tocid\relax
- \global\let\etoclocaltop\Etoc@level
+ \global\let\etoclocaltop\Etoc@virtualtop
+ \Etoc@@startlocaltochook
\global\Etoc@notactivefalse
- \fi }%
+ \fi
+ }%
+% \end{macrocode}
+% The mechanism is to check if any \csa{contentsline} triggers execution.
+% For this we replace the \etoc replacement by another replacement.
+% \begin{macrocode}
\let\contentsline\Etoc@testingcontentslinelocal
\else
\let\contentsline\Etoc@testingcontentsline
\fi
\Etoc@storetocdepth
% \end{macrocode}
-% |1.09i| fixes a bug arising when document has used \csbc{etocsetlocaltop.toc}.
+% This here is a \etocrelease{1.09i} added work-around to avoid usage of
+% \csbc{etocsetlocaltop.toc} which could cause the test of emptiness of a
+% global TOC to actually execute some start and finish parts in some cases.
% \begin{macrocode}
- \let\Etoc@setlocaltop@doends@dobegins\@empty
+ \let\Etoc@setlocaltop@doendsandbegin\@empty
\the\Etoc@toctoks
\Etoc@restoretocdepth
\endgroup
}
\DeclareRobustCommand*\etocifwasempty
- {\ifEtoc@emptytoc\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi }
-\expandafter
-\let\expandafter\etocxifwasempty\csname etocifwasempty \endcsname
+ {\ifEtoc@isemptytoc\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi }
+\expandafter\let\expandafter\etocxifwasempty\csname etocifwasempty \endcsname
\def\Etoc@testingcontentslinelocal #1{%
\ifEtoc@stoptoc
\else
\ifnum\csname Etoc@#1@@\endcsname=\Etoc@@six@@
\else
\global\expandafter\let\expandafter\Etoc@level\csname Etoc@#1@@\endcsname
-% \end{macrocode}
-% \csbc{ifEtoc@notactive} set to False by \csbc{etoc@startlocaltoc} with right id. It
-% that happened, check level of hit against unit. Will decide if empty or not.
-% Set \csbc{ifEtoc@stoptoc} flag afterwards in all cases. \csa{Etoc@localtop} will have been
-% initialized by \csbc{etoc@@startlocaltoc} as \csbc{ifEtoc@notactive} flag can be
-% false only then.
-% \begin{macrocode}
+ \if @\@car#1\@nil\else\global\let\Etoc@virtualtop\Etoc@level\fi
\ifEtoc@notactive
\else
+% \end{macrocode}
+% \csbc{ifEtoc@notactive} is \csa{iffalse} in case of a local TOC once it has
+% encountered the \csbc{etoc@startlocaltoc} with matching id. So here
+% \csbc{etoclocaltop} has been set by \csbc{Etoc@@startlocaltoc} and we
+% compare to the new level encountered. If the latter is at most equal to
+% \csbc{etoclocaltop} this means the local TOC ends there and is empty, so we
+% set the \csbc{ifEtoc@stoptoc} to true, which will cause the subsequent
+% parsing to abort immediately. If it is greater we check how it compares to
+% the local required toc depth. If lower or equal we conclude the toc is not
+% empty, and toggle the flag to stop the parsing; if greater, we are still in
+% doubt and must continue.
+% \begin{macrocode}
\ifnum\Etoc@level>\etoclocaltop
- \unless\ifnum\Etoc@level>\Etoc@localtocdepth
- \global\Etoc@emptytocfalse
+ \unless\ifnum\Etoc@level>\c@tocdepth
+ \global\Etoc@isemptytocfalse
\global\Etoc@stoptoctrue
\fi
\else
@@ -8437,25 +9370,39 @@ of real structure in a \LaTeX{} document body).
\fi
\fi
\fi
- \@gobblefour\relax
+% \end{macrocode}
+% The \csa{@gobblethree} was added to the \LaTeX{} kernel for its 2020-02-02
+% PL 5 release and we require 2020-10-01 since \etocrelease{1.1a}.
+% \begin{macrocode}
+ \@gobblethree
}
+% \end{macrocode}
+% Test of emptiness of the global TOC (according to current setting of the
+% levels and a possibly evolving tocdepth).
+% \begin{macrocode}
\def\Etoc@testingcontentsline #1{%
\ifEtoc@stoptoc
\else
\ifnum\csname Etoc@#1@@\endcsname=\Etoc@@six@@
\else
\unless\ifnum\csname Etoc@#1@@\endcsname>\c@tocdepth
- \global\Etoc@emptytocfalse
+ \global\Etoc@isemptytocfalse
\global\Etoc@stoptoctrue
\fi
\fi
\fi
- \@gobblefour\relax
+ \@gobblethree
}
% \end{macrocode}
-% |2015/03/16|: |1.08e| lets \csbc{localtableofcontents} do a first scan of the
-% |.toc| file (as stored in \csbc{Etoc@toctoks}) to determine if the table of
-% contents will in fact end up empty. In that case, nothing is typeset. The
+% |2015/03/16|: \etocrelease{1.08e} lets \csbc{localtableofcontents} do a
+% first scan of the |.toc| file (as stored in \csbc{Etoc@toctoks}) to
+% determine if the table of contents will in fact end up empty.
+%
+% Update (|2023/02/26|): the actual \etocrelease{1.08e} of |2015/04/17| had
+% \csbc{etocchecksemptiness} to tell \etoc to do the emptiness check, it is
+% not done automatically.
+%
+% In that case, nothing is typeset. The
% command \csbc{etocaftertochook} is still executed though. Other ways were
% envisioned (like delimited macros) to determine this potential emptiness, but
% in the end I opted for execution of the |.toc| file with suitable definitions
@@ -8471,14 +9418,14 @@ of real structure in a \LaTeX{} document body).
%
% The flag \csbc{ifEtoc@tocwithid} discriminates between a \localtoc and a
% \toc|\ref{foo}|; the latter could so far possibly refer to a local or also to
-% a global table of contents but release |1.08e| has deprecated the latter use
+% a global table of contents but release \etocrelease{1.08e} has deprecated the latter use
% as it complicated the code, for something truly silly. Thus |\ref{foo}| must
% now be with |foo| a label of a local TOC. As a result \csbc{ifEtoc@tocwithid} is
% less used now.
%
% In the case of a |\ref|ed-to toc whose label was just added hence is not yet
% in the |.aux| file, \csbc{Etoc@tocid} is |0|. \etoc used to issue a warning to
-% run latex again and did no printing at all. Release |1.08e| in such cases
+% run latex again and did no printing at all. Release \etocrelease{1.08e} in such cases
% prints the heading (this may gain one compilation step). Emptiness test is
% not executed as it would necessarily turn out positive and can not be
% trusted anyhow. The TOC is declared non empty, which it probably is...
@@ -8496,20 +9443,20 @@ of real structure in a \LaTeX{} document body).
% TOC needing more compilations. The emptiness status is undecided, the code
% declares the TOC non empty.
%
-% |1.08i-2016/09/29| now does \csa{Etoc@localtoctrue} right at the start (the
+% \etocrelease{1.08i} |2016/09/29| now does \csa{Etoc@localtoctrue} right at the start (the
% earlier code could have to handle table of contents which were actually
% global, via the |\label/\ref| mechanism.) It does not rely on the |\ifnum|
-% automatically false in \csbc{etoc@@startlocaltoc} due to the special values |0|
+% automatically false in \csbc{Etoc@@startlocaltoc} due to the special values |0|
% or |\z@| for \csbc{Etoc@tocid}, but simply leaves \csbc{etoc@startlocaltoc} to its
-% default |\@gobble|. The \csa{Etoc@emptytocfalse} is upfront in case some
+% default |\@gobble|. The \csa{Etoc@isemptytocfalse} is upfront in case some
% code using \csbc{etocifwasempty} is in user hooks. The default is to assume the
% TOC non-empty as its contents are actually still unknown. Under the
% \csa{Etoc@stoptoctrue} flag, the \csbc{Etoc@etoccontentsline} is more efficient now.
%
% The \csbc{ifEtoc@notactive} flag needs to be set before calling
-% \csbc{Etoc@setemptytocbool}.
+% \csbc{Etoc@checkifempty}.
%
-% I hesitated with |1.08i| to write something to aux file in order to let
+% I hesitated with \etocrelease{1.08i} to write something to aux file in order to let
% \LaTeX\ prompt the user for extra pass, after insertion of some new
% \csa{localtableofcontents}, but finally I prefer to only trick \LaTeX\ into
% telling about undefined references.
@@ -8534,7 +9481,7 @@ of real structure in a \LaTeX{} document body).
\def\Etoc@localtableofcontents#1{%
\gdef\etoclocaltop{-\@m}%
\Etoc@localtoctrue
- \global\Etoc@emptytocfalse
+ \global\Etoc@isemptytocfalse
\edef\Etoc@tocid{#1}%
\ifnum\Etoc@tocid<\@ne
\setbox0\hbox{\ref{Unknown toc ref \@secondoftwo#1. \space Rerun LaTeX}}%
@@ -8548,15 +9495,15 @@ of real structure in a \LaTeX{} document body).
\fi
\global\Etoc@notactivetrue
\ifEtoc@checksemptiness
- \Etoc@setemptytocbool
+ \Etoc@checkifempty
\fi
- \ifEtoc@emptytoc
+ \ifEtoc@isemptytoc
\ifEtoc@notactive
\setbox0\hbox{\ref{Unknown toc ID \number\Etoc@tocid. \space Rerun LaTeX}}%
% \end{macrocode}
% Assume real one will be non-empty and print only heading for this pass.
% \begin{macrocode}
- \global\Etoc@emptytocfalse
+ \global\Etoc@isemptytocfalse
\global\Etoc@stoptoctrue
\gdef\etoclocaltop{-\thr@@}%
\Etoc@tableofcontents
@@ -8572,20 +9519,14 @@ of real structure in a \LaTeX{} document body).
% For the latter case \csbc{etoclocaltop} has setting |-\@m|.
% \begin{macrocode}
\edef\etoc@startlocaltoc##1%
- {\noexpand\etoc@@startlocaltoc{##1}{\Etoc@tocid}}%
+ {\noexpand\Etoc@@startlocaltoc{##1}{\Etoc@tocid}}%
\Etoc@tableofcontents
\fi
\@gobble\etoc@
\endgroup\ifEtoc@mustclosegroup\endgroup\fi
\Etoc@tocdepthreset
+ \Etoc@listofreset
\etocaftertochook
-% \end{macrocode}
-% |1.09| hesitates about putting this before of after the
-% \csbc{etocaftertochook}. The information of the used tocdepth is lost if
-% puuting it first. The usage of \csbc{etocaftertochook} may be broken if
-% unexpected tokens follows.
-% \begin{macrocode}
- \let\Etoc@localtocdepth\c@tocdepth
}% \Etoc@localtableofcontents
% \end{macrocode}
% |2013/03/07|: I discover a \csa{@namedef} trick to construct the
@@ -8593,11 +9534,36 @@ of real structure in a \LaTeX{} document body).
% | \@namedef {Etoc@again} {...stuff...}|\\
% Original version was (copied from analogous stuff in |source2e|):\\
% | {\def\1{\Etoc@again}\expandafter\gdef\1 {...stuff...}}|\\
-% and in the end (now that I think about it) I simply use \csa{@firstofone}.\par
+% and in the end (now that I think about it) I simply use \csa{@firstofone}.
+%
+% \etocrelease{1.2} has a removed a \csa{Etoc@getrefno} as the author now
+% knows about \csa{@car} so need to define a similar utility here!
+%
+% Much more importantly (and embarrassingly) \etocrelease{1.2} fixes a bug
+% which had been here for ever. The code in its innocence 2012 birth year
+% assumed that the first entry of \csa{r@foo}, if the latter is defined, is
+% always numerical! But this is broken by \ctanpkg{varioref} if one used for
+% example \csa{vpageref}|{foo}| before! The first brace pair will then be
+% |{??}|... causing in \etoc a ``Missing number'' error.
+%
+% About the current fixed code, there is no strong reason that
+% \csbc{Etoc@getref} should work expandably. Later
+% \csbc{Etoc@localtableofcontents} does
+% \centeredline{|\edef\Etoc@tocid{#1}\iffnum\Etoc@tocid<\@ne|} but I certainly
+% could organize things differently.
+%
+% Maybe I should investigate more on what nasty things car be in
+% first argument. Or submit it to an \csa{expanded}?
% \begin{macrocode}
-\def\Etoc@getrefno #1#2\etoc@ {#1}
-\def\Etoc@getref #1{\@ifundefined{r@#1}{0}{\expandafter\expandafter\expandafter
- \Etoc@getrefno\csname r@#1\endcsname\relax\etoc@}}
+\def\Etoc@getref #1{%
+ \@ifundefined{r@#1}
+ {0}
+ {\expandafter\Etoc@getref@i\romannumeral-`0%
+ \expandafter\expandafter\expandafter
+ \@car\csname r@#1\endcsname0\@nil\@etoc
+ }%
+}
+\def\Etoc@getref@i#1#2\@etoc{\ifnum9<1\string#1 #1#2\else 0\fi}
\def\Etoc@ref#1{\Etoc@localtableofcontents{\Etoc@getref{#1}}}
\def\Etoc@label#1{\label{#1}\futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
\@firstofone{\def\Etoc@again} {\futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
@@ -8624,26 +9590,29 @@ of real structure in a \LaTeX{} document body).
% \end{macrocode}
% From now on we are handling a global TOC. Earlier, I used the trick of
% setting \csbc{Etoc@tocid} to |\z@| for compatibility with expansion of
-% \csbc{etoc@startlocaltoc}. But since |1.08i| \csbc{etoc@startlocaltoc} is left to be
+% \csbc{etoc@startlocaltoc}. But since \etocrelease{1.08i} \csbc{etoc@startlocaltoc} is left to be
% |\@gobble|, and \csbc{Etoc@tocid} is never tested. We don't need to set the
% \csbc{ifEtoc@notactive} flag as now \csbc{Etoc@testingcontentsline} tests first the
% \csbc{ifEtoc@localtoc} flag (was already the case of \csbc{Etoc@etoccontentsline}). I change
% a bit the style of conditionals here for clarity of code.
% \begin{macrocode}
- \global\Etoc@emptytocfalse\ifEtoc@checksemptiness\Etoc@setemptytocbool\fi
- \ifEtoc@emptytoc
+ \global\Etoc@isemptytocfalse
+ \ifEtoc@checksemptiness\Etoc@checkifempty\fi
+ \ifEtoc@isemptytoc
\ifEtoc@notocifnotoc
\expandafter\expandafter\expandafter\@gobble
\fi
\fi
\Etoc@tableofcontents
- \endgroup\ifEtoc@mustclosegroup\endgroup\fi
+ \endgroup
+ \ifEtoc@mustclosegroup\endgroup\fi
\Etoc@tocdepthreset
+ \Etoc@listofreset
\etocaftertochook
\@gobble\etoc@
}% \Etoc@t@bleofcontents
% \end{macrocode}
-% |1.08c| does not use |\arabic| in the \csa{addtocontents} since I have seen
+% \etocrelease{1.08c} does not use |\arabic| in the \csa{addtocontents} since I have seen
% that in some circumstances (for some right to left languages with
% polyglossia or babel), one can not rely on |\arabic| having its default
% definition. As the number written here will be used later in an \csa{ifnum}, I
@@ -8652,14 +9621,14 @@ of real structure in a \LaTeX{} document body).
\def\Etoc@table@fcontents{%
\refstepcounter{etoc@tocid}%
\Etoc@tocwithidfalse
- \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
+ \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents
+}
\def\Etoc@localtable@fcontents{%
\refstepcounter{etoc@tocid}%
\addtocontents{toc}{\string\etoc@startlocaltoc{\the\c@etoc@tocid}}%
\Etoc@tocwithidtrue
- \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
-\let\etocaftertitlehook \@empty
-\let\etocaftercontentshook \@empty
+ \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents
+}
% \end{macrocode}
% Attention that there could be a |\ref| following, thus we don't yet know
% whether this is a local or global table of contents.
@@ -8675,12 +9644,12 @@ of real structure in a \LaTeX{} document body).
% \csbc{Etoc@localtableofcontents}.
%
% Prior to its release |1.4c|, \ctanpkg{tableof} added a group pair via \csa{tof@begin}
-% and \csa{tof@finish}. This was removed at |1.4c|. So no need to do anything now
+% and \csa{tof@finish}. It was removed at |1.4c|, so no need to do anything now
% here about silencing \csa{tof@begingroup} and \csa{tof@endgroup}: they are
% inserted only in the \ctanpkg{tableof} private copy of the |.toc| file which is
% used by its own table of contents typesetting command.
%
-% |1.09b| uses a |\def| in non-starred variant for allowing tricks to
+% \etocrelease{1.09b} uses a |\def| in non-starred variant for allowing tricks to
% recognize later on if we are in a starred or non-starred case, whatever the
% user definition of \csbc{etocaftertitlehook} may be.
% \begin{macrocode}
@@ -8688,93 +9657,167 @@ of real structure in a \LaTeX{} document body).
{\let\Etoc@aftertitlehook\@empty\Etoc@table@fcontents}
{\def\Etoc@aftertitlehook{\etocaftertitlehook}\Etoc@table@fcontents}%
}% \etoctableofcontents
-% \end{macrocode}
-% See at end of this file for the explanation of this |1.09d| added saving
-% of original meaning at package loading time.
-% \begin{macrocode}
+\def\etocifisstarred{\ifx\Etoc@aftertitlehook\@empty
+ \expandafter\@firstoftwo\else
+ \expandafter\@secondoftwo
+ \fi}
\let\etocoriginaltableofcontents\tableofcontents
\let\tableofcontents\etoctableofcontents
+% \end{macrocode}
+% The \csbc{Etoc@listofhook} is configured by \csbc{locallistoffigures} and
+% \csbc{locallistoftables}. The latter two use hooks rather than
+% |\begingroup...\endgroup| to manage local configuration, in part because
+% they want to support the |\label/\ref| special \etoc mechanism, so need to
+% issue \csbc{localtableofcontents} last for it to be able to pick up a
+% following |\label| or |\ref|.
+% \begin{macrocode}
+\let\Etoc@listofhook\@empty
\newcommand*\localtableofcontents{%
\Etoc@openouttoc
\Etoc@tocdepthset
- \begingroup
% \end{macrocode}
% This group closed in \csbc{Etoc@t@bleofcontents} or \csbc{Etoc@localtableofcontents}.
% Same comment relative to \ctanpkg{tableof}. No need to do anything here.
% \begin{macrocode}
+ \begingroup
+ \Etoc@listofhook
\@ifstar
{\let\Etoc@aftertitlehook\@empty\Etoc@localtable@fcontents}
{\def\Etoc@aftertitlehook{\etocaftertitlehook}\Etoc@localtable@fcontents}%
}% \localtableofcontents
% \end{macrocode}
-% |1.09| adds \localtocwrdp. The motivation is that it is impossible to set
-% in a completely satisfactory way the tocdepth from the first argument of
-% \csbc{etocsettocstyle} because the emptiness check does not execute that
-% argument. If one does not care about emptiness check, one can of course set
-% the tocdepth from the first argument of \csbc{etocsettocstyle}. One can even
-% use \csbc{etocsetnexttocdepth} for that since |1.09| but anyway direct usage
-% of \csbc{etocsettocdepth} (or |\setcounter{tocdepth}{...}| is easier as its
-% effet when executed there is automatically limited to duration of the TOC.
+% \etocrelease{1.09} adds \localtocwrdp. Note that changes to the tocdepth
+% from inside the |.toc| file during duration of local toc will remain without
+% effect as a substitute is used which gets a frozen non-dynamical value.
+%
+% It seems \etocrelease{1.09} actually forgot a change to
+% \csbc{Etoc@etoccontentsline} and the previous sentence was false and
+% described only what happened during the emptiness check which thus could
+% give false positives or false negatives. But if I had done the needed
+% change in \csbc{Etoc@etoccontentsline} to keep the two in sync, even if
+% |tocdepth| evolves from the |.toc| file, I would have created a divergence
+% between local TOCs (not only the
+% \csbc{localtableofcontentswithrelativedepth} ones) under
+% \csbc{etocstandardlines} and those not with standard lines.
+%
+% Redoing the whole thing at \etocrelease{1.2}. I needed to insert a suitable
+% hook in \csbc{Etoc@@startlocaltoc} (and also in the version used by
+% \csbc{Etoc@checkifempty}). And I have now at my disposal
+% \csbc{Etoc@listofreset} to reset it (it will be expanded after both the
+% emptiness check and the typesetting are completed, and at same grouping
+% level as the trigger command defined here). I do not want to add tokens
+% after \csbc{localtableofcontents} to not break the |\label/\ref| thing,
+% which is one reason for this way of proceeding.
% \begin{macrocode}
\newcommand*\localtableofcontentswithrelativedepth[1]{%
- \edef\Etoc@localtocdepth
- {\numexpr\noexpand\etoclocaltop+\the\numexpr#1\relax\relax}%
+ \def\Etoc@@startlocaltochook{%
+ \global\c@tocdepth\numexpr\etoclocaltop+#1\relax
+ }%
+ \def\Etoc@listofreset{\let\Etoc@@startlocaltochook\@empty
+ \let\Etoc@listofreset\@empty}%
\localtableofcontents
}% \localtableofcontentswithrelativedepth
-\let\Etoc@localtocdepth\c@tocdepth
% \end{macrocode}
-% The code does only expandable things after
-% \csbc{Etoc@toctoc}, in order to allow opening of an alignment in the first
-% argument and closing in the second.
+% Prior to \etocrelease{1.2}, \csbc{Etoc@tableofcontents} was constructed
+% by \csbc{etocsettocstyle} as one big macro where |#1| and |#2| had been
+% inserted. It now simply stores |#1| and |#2| each in a macro and
+% \csbc{Etoc@tableofcontents} is defined once and for all. Also the boolean
+% \csbc{ifEtoc@etocstyle} is added which helps keeping the emulation of
+% the document class only for the global document TOC but use a better choice
+% for local tables of contents (especially those in deeper sub-levels),
+% which is activated via \csbc{etocetoclocaltocstyle} (near end of code).
+%
+% \csbc{etocstoretocstyleinto} added at \etocrelease{1.2}. Too lazy
+% to check if |#1| pre-exists. Well, rather, too annoying to do this check
+% as one may want to redefine |#1| without further ado.
% \begin{macrocode}
\newcommand\etocsettocstyle[2]{%
-\def\Etoc@tableofcontents
-{%
+ \Etoc@etocstylefalse
+ \Etoc@classstylefalse
+ \def\Etoc@tableofcontents@user@before{#1}%
+ \def\Etoc@tableofcontents@user@after {#2}%
+}%
+\def\etocstoretocstyleinto#1{%
+%% \@ifdefinable#1{%
+ \edef#1{\noexpand\Etoc@etocstylefalse\noexpand\Etoc@classstylefalse
+ \def\noexpand\Etoc@tableofcontents@user@before{%
+ \unexpanded\expandafter{\Etoc@tableofcontents@user@before}%
+ }%
+ \def\noexpand\Etoc@tableofcontents@user@after{%
+ \unexpanded\expandafter{\Etoc@tableofcontents@user@after}%
+ }%
+ }%
+%% }%
+}%
+% \end{macrocode}
+% The macro names added here at \etocrelease{1.2} are provisory. Next
+% release will probably do a complete renaming of various internals because
+% this is currently a complete mess with some names differing only by an |@|
+% versus a voyel, but not necessarily being at a deeper level of expansion the
+% more |@|'s they have... the deepest one being this \csbc{Etoc@tableofcontents}...
+% \begin{macrocode}
+\def\Etoc@tableofcontents {%
+ \Etoc@tableofcontents@etoc@before
+ \ifEtoc@localtoc\ifEtoc@etocstyle\expandafter\expandafter\expandafter\@gobble\fi\fi
+ \Etoc@tableofcontents@user@before
+ \Etoc@tableofcontents@contents
+ \ifEtoc@localtoc\ifEtoc@etocstyle\expandafter\expandafter\expandafter\@gobble\fi\fi
+ \Etoc@tableofcontents@user@after
+ \Etoc@tableofcontents@etoc@after
+ \@gobble\etoc@
+}
+\def\Etoc@tableofcontents@etoc@before{%
\ifnum\c@tocdepth>\Etoc@minf
\else
\expandafter\Etoc@gobtoetoc@
\fi
\Etoc@par
+ \Etoc@beforetitlehook
\etocbeforetitlehook
\Etoc@storetocdepth
\let\Etoc@savedcontentsline\contentsline
\let\contentsline\Etoc@etoccontentsline
- \ifEtoc@standard
+ \ifEtoc@standardlines
\else
% \end{macrocode}
-% |1.1a|'s \csbc{Etoc@lxyz} now fetches 3 not 2 arguments and the
+% \etocrelease{1.1a}'s \csbc{Etoc@lxyz} now fetches 3 not 2 arguments and the
% \csa{l@section} etc... are not |\let| to it anymore, as they used to be here
-% formerly. For backwards compatibility the \csa{etocsavedchaptertocline}
-% etc... are still defined, but raise a deprecation warning.
-% \begin{macrocode}
- \def\Etoc@levellist@elt####1{%
- \expandafter\def\csname etocsaved####1tocline\endcsname
- {\PackageWarning{etoc}{%
- \expandafter\string\csname etocsaved####1tocline\endcsname\space
- has been deprecated at 1.1a.\MessageBreak
- It will be removed from `etoc' in near feature. \space Use\MessageBreak
- \expandafter\string\csname l@####1\endcsname\space directly. \space
- Reported}%
- \expandafter\let\csname etocsaved####1tocline\expandafter\endcsname
- \csname l@####1\endcsname
- \csname l@####1\endcsname
- }%
+% formerly.
+%
+% For backwards compatibility the \csa{etocsavedchaptertocline}
+% etc... are still defined but issue a warning since \etocrelease{1.1a}
+% and an error since \etocrelease{1.2}.
+% \begin{macrocode}
+ \def\Etoc@do##1{%
+ \expandafter\def\csname etocsaved##1tocline\endcsname
+ {\PackageError{etoc}{%
+ \expandafter\string\csname etocsaved##1tocline\endcsname\space
+ has been deprecated\MessageBreak
+ at 1.1a and is removed at 1.2.\MessageBreak
+ Use \expandafter\string\csname l@##1\endcsname\space directly.\MessageBreak
+ Reported \on@line}%
+ {I will use \expandafter\string
+ \csname l@##1\endcsname\space myself for this time.%
+ }%
+ \csname l@##1\endcsname
+ }%
}%
- \Etoc@levellist
+ \Etoc@dolevels
\fi
+}%
% \end{macrocode}
-% |1.09| makes \csbc{etocsetnexttocdepth} usable in |#1| (but this is not 100\%
-% compatible with the emptiness check).
+% \etocrelease{1.09} makes \csbc{etocsetnexttocdepth} usable in |#1| (but this
+% is not 100\% compatible with the emptiness check). It makes an
+% \csbc{etoclocaltop} usable in |#1| if under checksemptiness regime.
%
-% |1.09| makes an \csbc{etoclocaltop} usable in |#1| if under checksemptiness
-% regime.
+% (|#1| above now means \csbc{Etoc@tableofcontents@user@before} since \etocrelease{1.2})
% \begin{macrocode}
- #1%
+\def\Etoc@tableofcontents@contents{%
\Etoc@tocdepthset
\ifEtoc@parskip\parskip\z@skip\fi
\Etoc@aftertitlehook
% \end{macrocode}
-% |1.09| has replaced former \csa{Etoc@localtop} (\emph{minus one}) by
+% \etocrelease{1.09} has replaced former \csa{Etoc@localtop} (\emph{minus one}) by
% \csbc{etoclocaltop}. Under checksemptinesstrue regime its value is already
% known, but it will be obtained again from the toc file execution. As it is
% used only if TOC is active, resetting it here this way is decorative and
@@ -8783,12 +9826,14 @@ of real structure in a \LaTeX{} document body).
\gdef\etoclocaltop{-\thr@@}%
\Etoc@toctoc
\etocaftercontentshook
- #2\@nobreakfalse
+}%
+\def\Etoc@tableofcontents@etoc@after{%
+ \@nobreakfalse
\Etoc@restoretocdepth
% \end{macrocode}
% \csa{contentsline} was set to \csbc{Etoc@etoccontentsline} by a non-global |\let|,
% and it will recover its normal value from exiting a scope limiting group.
-% But \ctanpkg{tableof} (since |1.4a|) under \csa{etocglobaldefstrue} does a global
+% But \ctanpkg{tableof} (since |1.4a|) under \csbc{etocglobaldefs} does a global
% redefinition of \csa{contentsline}. Its \csa{tof@finish} then does a global
% restore of \csa{contentsline}, but it will be to the \etoc set
% value. \csa{tof@finish} is active only if either the table of contents was
@@ -8796,7 +9841,7 @@ of real structure in a \LaTeX{} document body).
% \csa{nextocwithtags} was used. If not active it is either undefined (no
% package \ctanpkg{tableof}) or |\@empty|. Prior to \ctanpkg{tableof} |1.4c|, the
% \csa{tof@finish} closed a group and could be undefined as well, but not if
-% \csa{etocglobaldefstrue}.
+% \csbc{etocglobaldefs}.
%
% If rather than |\@empty| the \csa{tof@finish} fall-back was |\relax| we could
% use here \csa{@ifundefined} to check in one go (matters of speaking because
@@ -8813,21 +9858,78 @@ of real structure in a \LaTeX{} document body).
\fi
}%
\fi
- \@gobble\etoc@
-}% end of \Etoc@tableofcontents definition by \etocsettocstyle
}
-\def\etocsetstyle{\Etoc@standardfalse\etoc@setstyle}
-\long\def\etoc@setstyle#1#2#3#4#5{%
- \expandafter\def
- \csname Etoc@begin@\csname Etoc@#1@\endcsname\endcsname
- {#2\Etoc@global\Etoc@isfirsttrue}%
- \expandafter\def
- \csname Etoc@prefix@\csname Etoc@#1@\endcsname\endcsname {#3}%
- \expandafter\def
- \csname Etoc@contents@\csname Etoc@#1@\endcsname\endcsname {#4}%
- \expandafter\def
- \csname Etoc@end@\csname Etoc@#1@\endcsname\endcsname {#5}%
+% \end{macrocode}
+% Refactored at \etocrelease{1.2} to check if the style is actually known
+% and its level is from |-1| (|-2| in memoir class) to |5| inclusive.
+% If not raise a warning.
+% \begin{macrocode}
+\def\etocsetstyle#1{\ifcsname Etoc@#1@@\endcsname
+ \expandafter\Etoc@setstyle@a
+ \else
+ \expandafter\Etoc@setstyle@error
+ \fi {#1}%
+}
+\def\Etoc@setstyle@error #1{%
+ \PackageWarning{etoc}{`#1' is unknown to etoc. \space Did you\MessageBreak
+ forget some \string\etocsetlevel{#1}{<level>}?\MessageBreak
+ Reported}%
+ \@gobblefour
+}
+\def\Etoc@setstyle@a #1{%
+ \edef\Etoc@tmp{\the\numexpr\csname Etoc@#1@@\endcsname}%
+ \if1\unless\ifnum\Etoc@tmp<\Etoc@@six@@ 0\fi\unless\ifnum\Etoc@tmp>\Etoc@minf 0\fi1%
+ \Etoc@standardlinesfalse
+ \expandafter\Etoc@setstyle@b\expandafter\Etoc@tmp
+ \else
+ \PackageWarning{etoc}{Sorry, but you can not set the style of `#1',\MessageBreak
+ as its level \Etoc@tmp\space is either \number\Etoc@minf\space
+ or 6.\MessageBreak
+ Consider using \string\etocsetlevel\space first, but note
+ that `all',\MessageBreak
+ `none', `figure' and `table' are forbidden there. \space
+ Check\MessageBreak
+ the documentation about how to proceed for customizing\MessageBreak
+ figure and table entries in \string\listoffigures/tables.\MessageBreak
+ Reported}%
+ \expandafter\@gobblefour
+ \fi
+}
+% \end{macrocode}
+% Prior to \etocrelease{1.2} the |#1| here was some alphabetical string
+% such as |minusone|. We now use digit tokens (and minus sign) in the macro
+% names. The ``begin'' macros formerly incorporated
+% \csa{Etoc@global}\csa{Etoc@isfirsttrue}. They are now located in
+% \csbc{Etoc@traversestackofends}.
+%
+% \etocrelease{1.2} adds \csbc{etocstorelinestylesinto}. And
+% \csbc{etocstorethislinestyleinto}. No error check on the level.
+% \begin{macrocode}
+\long\def\Etoc@setstyle@b#1#2#3#4#5{%
+ \expandafter\def\csname Etoc@begin@#1\endcsname {#2}%
+ \expandafter\def\csname Etoc@prefix@#1\endcsname {#3}%
+ \expandafter\def\csname Etoc@contents@#1\endcsname {#4}%
+ \expandafter\def\csname Etoc@end@#1\endcsname {#5}%
+}
+\def\Etoc@storelines@a#1{%
+ \noexpand\Etoc@setstyle@b{#1}%
+ {\expandafter\Etoc@expandonce\csname Etoc@begin@#1\endcsname}%
+ {\expandafter\Etoc@expandonce\csname Etoc@prefix@#1\endcsname}%
+ {\expandafter\Etoc@expandonce\csname Etoc@contents@#1\endcsname}%
+ {\expandafter\Etoc@expandonce\csname Etoc@end@#1\endcsname}%
+}
+\def\Etoc@expandonce#1{\unexpanded\expandafter{#1}}
+\def\etocstorelinestylesinto#1{%
+ \edef#1{\Etoc@storelines@a{-2}\Etoc@storelines@a{-1}\Etoc@storelines@a{0}%
+ \Etoc@storelines@a {1}\Etoc@storelines@a {2}\Etoc@storelines@a{3}%
+ \Etoc@storelines@a {4}\Etoc@storelines@a {5}}%
}
+\def\etocstorethislinestyleinto#1#2{%
+ \edef#2{\expandafter\Etoc@storelines@a\expandafter{\number\etoclevel{#1}}}%
+}%
+% \end{macrocode}
+% Customization macros of the package default line styles.
+% \begin{macrocode}
\def\etocfontminustwo {\normalfont \LARGE \bfseries}
\def\etocfontminusone {\normalfont \large \bfseries}
\def\etocfontzero {\normalfont \large \bfseries}
@@ -8863,7 +9965,7 @@ of real structure in a \LaTeX{} document body).
{\hbox{\normalfont\normalsize\hb@xt@2ex {\hss.\hss}}}
\def\etocabbrevpagename {p.~}
% \end{macrocode}
-% Versions earlier than |1.08b| (and since |1.05 2012/12/01|) defined
+% Versions earlier than \etocrelease{1.08b} (and since \etocrelease{1.05} |2012/12/01|) defined
% \csbc{etocpartname} (for use by \etoc's own line styles) to expand to
% \csa{partname}. But this didn't make sense in the context for example of
% \ctanpkg{babel} and \ctanpkg{babel-french}, because \csa{frenchpartname} does things depending on
@@ -8880,15 +9982,16 @@ of real structure in a \LaTeX{} document body).
\def\etocbookname {Book}
% \end{macrocode}
% The macro \csbc{etocdefaultlines} was initially called \csbc{etoctoclines}. Now
-% \csbc{etoctoclines} just does \csa{Etoc@standardfalse}.
+% \csbc{etoctoclines} just does \csa{Etoc@standardlinesfalse}.
%
-% Version |1.09f| wraps \csbc{etocbookname}, respectively
+% Version \etocrelease{1.09f} wraps \csbc{etocbookname}, respectively
% \csbc{etocpartname}, in the book, resp. part, line styles inside a
% (potential) hyperlink together with the number.
% \begin{macrocode}
-\def\etocdefaultlines{\Etoc@standardfalse
+\def\etocdefaultlines{\Etoc@standardlinesfalse
%% `book':
-\etoc@setstyle{@minustwo}
+\Etoc@setstyle@b
+ {-2}%
{\addpenalty\@M\etocskipfirstprefix}
{\addpenalty\@secpenalty}
{\begingroup
@@ -8906,7 +10009,8 @@ of real structure in a \LaTeX{} document body).
\endgroup}
{}%
%% `part':
-\etoc@setstyle{@minusone}
+\Etoc@setstyle@b
+ {-1}%
{\addpenalty\@M\etocskipfirstprefix}
{\addpenalty\@secpenalty}
{\begingroup
@@ -8924,7 +10028,8 @@ of real structure in a \LaTeX{} document body).
\endgroup}
{}%
%% `chapter':
-\etoc@setstyle{@zero}
+\Etoc@setstyle@b
+ {0}%
{\addpenalty\@M\etocskipfirstprefix}
{\addpenalty\@itempenalty}
{\begingroup
@@ -8937,7 +10042,8 @@ of real structure in a \LaTeX{} document body).
\endgroup}
{\addpenalty{-\@highpenalty}\addvspace{\etocsepminusone}}%
%% `section':
-\etoc@setstyle{@one}
+\Etoc@setstyle@b
+ {1}%
{\addpenalty\@M\etocskipfirstprefix}
{\addpenalty\@itempenalty}
{\begingroup
@@ -8970,7 +10076,8 @@ of real structure in a \LaTeX{} document body).
\endgroup}
{\addpenalty\@secpenalty\addvspace{\etocsepzero}}%
%% `subsection':
-\etoc@setstyle{@two}
+\Etoc@setstyle@b
+ {2}%
{\addpenalty\@medpenalty\etocskipfirstprefix}
{\addpenalty\@itempenalty}
{\begingroup
@@ -9002,7 +10109,8 @@ of real structure in a \LaTeX{} document body).
\endgroup}
{\addpenalty\@secpenalty\addvspace{\etocsepone}}%
%% `subsubsection':
-\etoc@setstyle{@three}
+\Etoc@setstyle@b
+ {3}%
{\addpenalty\@M
\etocfontthree
\vspace{\etocsepthree}%
@@ -9019,9 +10127,9 @@ of real structure in a \LaTeX{} document body).
% \end{macrocode}
% placeholder for comments
% \begin{macrocode}
-\etoc@setstyle{@four}{}{}{}{}%
-\etoc@setstyle{@five}{}{}{}{}%
-}
+\Etoc@setstyle@b{4}{}{}{}{}%
+\Etoc@setstyle@b{5}{}{}{}{}%
+}% end of \etocdefaultlines definition
% \end{macrocode}
% The \csbc{etocinnertopsep} default value is too big as well as \csbc{etocbelowtocskip}
% and \csbc{etocabovetocskip}, I guess, but if I am remember correctly I chose them
@@ -9200,7 +10308,15 @@ of real structure in a \LaTeX{} document body).
\leaders\etocbottomrule\hss\color@endgroup}}
\addvspace{\etocbelowtocskip}}}
% \end{macrocode}
-% placeholder for comments
+% For time being I will not however add the versions for ``lists of'', as
+% anyhow probably nobody apart myself ever uses these things.
+%
+% It is impossible to know what kind of division heading |#2| uses, so there
+% is not much I can do here at \etocrelease{1.2} apart from providing a
+% user interface for adding the suitable thing to the |.toc| file. And I
+% discover at time of writing (finishing the \etocrelease{1.2}
+% documentation) that I already have \csbc{etoclocalheadtotoc}. I only need to
+% add \csbc{etocglobalheadtotoc}.
% \begin{macrocode}
\newcommand\etoc@multicoltoc[2][\etocdefaultnbcol]{%
\etocmulticolstyle[#1]{#2}%
@@ -9278,134 +10394,365 @@ of real structure in a \LaTeX{} document body).
{\etoc@local@framedtoci}
{\etoc@local@framedtoc}}
% \end{macrocode}
-% placeholder for comments
+% \etocrelease{1.2} makes local TOCs in compatibility display style use
+% |\subsection*| rather than |\section*|. This is not good for local TOCs to
+% a |\part| but anyhow the default is via \csbc{etocetoclocaltocstyle} which
+% will do the right thing and the change here is irrelevant. More comments
+% below about handling \ctanpkg{memoir} and \ctanpkg{KOMA-script}.
+%
+% The macros next will be modified if under |book| or \ctanpkg{memoir} class.
+% The \ctanpkg{KOMA-script} case uses rather the |leveldown| mechanism.
+% These local TOCs things are used only under \csbc{etocclasstocstyle}.
+% With \csbc{etocetoclocaltocstyle}, they are not used.
+% \begin{macrocode}
+\def\etocmemoirtoctotocfmt #1#2{%
+ \PackageWarning{etoc}
+ {\string\etocmemoirtoctotocfmt\space is deprecated.\MessageBreak
+ Use in its place \string\etocsettoclineforclasstoc,\MessageBreak
+ and \string\etocsettoclineforclasslistof{toc} (or {lof}, {lot}).
+ I will do this now.\MessageBreak
+ Reported}%
+ \etocsettoclineforclasstoc{#1}{#2}%
+ \etocsettoclineforclasslistof{toc}{#1}{#2}%
+}
+\def\etocsettoclineforclasstoc #1#2{%
+ \def\etocclassmaintocaddtotoc{\etocglobalheadtotoc{#1}{#2}}%
+}
+\def\etocsettoclineforclasslistof #1#2#3{%
+ \@namedef{etocclasslocal#1addtotoc}{\etoclocalheadtotoc{#2}{#3}}%
+}
+\let\etocclasslocaltocaddtotoc\@empty
+\let\etocclasslocallofaddtotoc\@empty
+\let\etocclasslocallotaddtotoc\@empty
+\ifdefined\c@chapter
+ \def\etocclasslocaltocmaketitle{\section*{\localcontentsname}}
+ \def\etocclasslocallofmaketitle{\section*{\locallistfigurename}}
+ \def\etocclasslocallotmaketitle{\section*{\locallisttablename}}
+ \etocsettoclineforclasstoc {chapter}{\contentsname}
+ \etocsettoclineforclasslistof{toc}{section}{\localcontentsname}
+ \etocsettoclineforclasslistof{lof}{section}{\locallistfigurename}
+ \etocsettoclineforclasslistof{lot}{section}{\locallisttablename}
+\else
+ \def\etocclasslocaltocmaketitle{\subsection*{\localcontentsname}}%
+ \def\etocclasslocallofmaketitle{\subsection*{\locallistfigurename}}%
+ \def\etocclasslocallotmaketitle{\subsection*{\locallisttablename}}%
+ \etocsettoclineforclasstoc {section}{\contentsname}
+ \etocsettoclineforclasslistof{toc}{subsection}{\localcontentsname}
+ \etocsettoclineforclasslistof{lof}{subsection}{\locallistfigurename}
+ \etocsettoclineforclasslistof{lot}{subsection}{\locallisttablename}
+\fi
+% \end{macrocode}
+% This is moved to a macro to localize complications with conditionals.
+% \begin{macrocode}
+\def\etocclasslocalperhapsaddtotoc #1{%
+ \etocifisstarred
+ {}
+ {\csname ifEtoc@local#1totoc\endcsname
+ \csname etocclasslocal#1addtotoc\endcsname
+ \fi
+ }%
+}
+% \end{macrocode}
+% No need for a \csa{phantomsection} if the \csa{addcontentsline} is after
+% |\section*|. For the standard classes, I make no effort to adjust level
+% used for the local heading if it is local to a \csa{part}, not a
+% \csa{section}. Anyhow this code will not be used by default for
+% local TOCs due to \csbc{etocetoclocaltocstyle}.
% \begin{macrocode}
\def\etocarticlestyle{%
\etocsettocstyle
- {\section *{\contentsname
- \@mkboth {\MakeUppercase \contentsname}
- {\MakeUppercase \contentsname}}}
- {}}
+ {\ifEtoc@localtoc
+ \@nameuse{etocclasslocal\Etoc@currext maketitle}%
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \else
+ \section *{\contentsname
+ \@mkboth {\MakeUppercase \contentsname}
+ {\MakeUppercase \contentsname}}%
+ \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
+ \fi
+ }
+ {}%
+}
\def\etocarticlestylenomarks{%
\etocsettocstyle
- {\section *{\contentsname}}
- {}}
+ {\ifEtoc@localtoc
+ \@nameuse{etocclasslocal\Etoc@currext maketitle}%
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \else
+ \section *{\contentsname}%
+ \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
+ \fi
+ }
+ {}%
+}
% \end{macrocode}
-% placeholder for comments
+% Make definitions with |book| in the macro names or redefine them
+% for |book|? Chose the latter.
% \begin{macrocode}
\def\etocbookstyle{%
\etocsettocstyle
{\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi
- \chapter *{\contentsname
- \@mkboth {\MakeUppercase \contentsname}
- {\MakeUppercase \contentsname}}}
- {\if@restonecol \twocolumn \fi}}
+ \ifEtoc@localtoc
+ \@nameuse{etocclasslocal\Etoc@currext maketitle}%
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \else
+ \chapter *{\contentsname
+ \@mkboth {\MakeUppercase \contentsname}
+ {\MakeUppercase \contentsname}}%
+ \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
+ \fi
+ }%
+ {\if@restonecol \twocolumn \fi}%
+}
\def\etocbookstylenomarks{%
\etocsettocstyle
{\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi
- \chapter *{\contentsname}}
- {\if@restonecol \twocolumn \fi}}
+ \ifEtoc@localtoc
+ \@nameuse{etocclasslocal\Etoc@currext maketitle}%
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \else
+ \chapter *{\contentsname}%
+ \etocifisstarred{}{\etocifmaintoctotoc{\etocclassmaintocaddtotoc}{}}%
+ \fi
+ }%
+ {\if@restonecol \twocolumn \fi}%
+}
\let\etocreportstyle\etocbookstyle
\let\etocreportstylenomarks\etocbookstylenomarks
% \end{macrocode}
% |v3.7i| of memoir has moved the \csa{phantomsection} to a better location,
-% before typesetting the title and we follow suit at |1.09a|, and less rashly
-% at |1.09b|. Formerly \etoc used \csbc{etocaftertitlehook} to mimick the
-% memoir code but as its name indicate, it is supposedly executed after the
-% title... and this also had the defect of making \csbc{etocaftertitlehook} not
-% anymore a user command. Thus we here use some refactoring of the
-% \csbc{Etoc@aftertitlehook} internal mechanism to help recognize if we are
-% in the starred case or not.
+% before typesetting the title and we follow suit at \etocrelease{1.09a}, and
+% at \etocrelease{1.09b}. Formerly \etoc used \csbc{etocaftertitlehook} to
+% mimick the memoir code but as its name indicate, it is supposedly executed
+% after the title... and this also had the defect of making
+% \csbc{etocaftertitlehook} not anymore a user command. Thus we here use some
+% refactoring of the \csbc{Etoc@aftertitlehook} internal mechanism to help
+% recognize if we are in the starred case or not.
%
% \csa{phantomsection} is always defined by memoir, empty if hyperref absent.
+%
+% Updates at \etocrelease{1.2} for the standard display style inherited
+% from the class to actually be usable with local table of contents.
+% Unfortunately the printing of the title rigidly hard-codes a
+% |\thispagestyle{chapter}|:
+% \begin{verbatim}
+% \@lofmaketitle ->\@nameuse {lofheadstart} {\parindent \z@ \parskip \z@ \interli
+% nepenalty \@M \@nameuse {printlofnonum}\@nameuse {printloftitle}{\listfigurenam
+% e }\@nameuse {lofmark}\thispagestyle {chapter}\@nameuse {afterloftitle} } \@aft
+% erheading
+% \end{verbatim}
+% \vskip-\baselineskip
+% Oh well I discover there is a \csa{chapterheadstart} but not
+% \csa{sectionheadstart}...
+%
+% Actually now \etoc will by default not use the class inherited style for the
+% local TOC titles, so maybe I should have not wasted time on this. From the
+% \csbc{etocsettocstyle} arguments one can know if this is for a local TOC,
+% but one can not know the level, which is inferred from the actual execution
+% of the TOC data. There is a problem though that the \ctanpkg{memoir}
+% default would be usable for a local TOC in a |\part|. Although one can
+% argue if it makes sense to display a TOC as prominently as a chapter anyway.
+% Again, the default with \etoc will anyhow not use this as
+% \csbc{etocetoclocaltocstyle} deactivates the \csbc{etocsettocstyle} for
+% local TOCs.
+%
+% MEMO: would it make sense to have an \csa{etocsetlocaltocstyle}? As
+% explained above this would however induced dramatic internal \etoc changes as one
+% would have to wait for title insertion until the time one knows the local
+% level. Which is exactly what \csbc{etocetoclocaltocstyle} via the
+% \csbc{ifEtoc@etocstyle} does.
+%
+% Update at \etocrelease{1.2} to account for \csbc{locallistoffigures} and
+% \csbc{locallistoftables}.
% \begin{macrocode}
-\def\etocmemoirtoctotocfmt #1#2{%
- \def\Etoc@addsuitablecontentsline{\addcontentsline {toc}{#1}{#2}}%
-}
\def\etocmemoirstyle{%
\etocsettocstyle
{\ensureonecol \par \begingroup \phantomsection
\ifx\Etoc@aftertitlehook\@empty
\else
% \end{macrocode}
-% non-starred variant
+% This branch executed for the non-starred variant
% \begin{macrocode}
\ifmem@em@starred@listof
\else
- \Etoc@addsuitablecontentsline
+% \end{macrocode}
+% Global case is only for \csa{tableofcontents} as \etoc does not hack into
+% \csa{listofpictures} and \csa{listoftables}.
+%
+% Local case will not be executed in default configurations (cf
+% \csbc{etocetoclocaltocstyle}).
+%
+% \csbc{etocclasslocalperhapsaddtotoc} is to avoid worries with conditionals.
+% \begin{macrocode}
+ \ifEtoc@localtoc
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \else
+ \ifEtoc@maintoctotoc
+ \etocclassmaintocaddtotoc
+ \fi
+ \fi
\fi
\fi
- \@nameuse {@tocmaketitle} %<< space token here from memoir code
+ \ifEtoc@localtoc
+ % trying to mimick a section title but there is no \sectionheadstart
+ % there is no \printsectiontitle etc... Oh well I will be more
+ % radical then
+ \@namedef{@\Etoc@currext maketitle}{%
+ \@nameuse{etocclasslocal\Etoc@currext maketitle}%
+ }%
+ \fi
+ \@nameuse {@\Etoc@currext maketitle} %<< space token here from memoir code
\ifx\Etoc@aftertitlehook\@empty
\else
% \end{macrocode}
% Execute etoc hook before the \csa{cfttocbeforelisthook} and keep distinction
-% between starred and non-starred contexts for other hooks. Notice that the
-% memoir class way of implementing \csbc{tableofcontents} leaves no way for code
-% executed by the TOC code to know if it is executed in starred or non-starred
-% context.
+% between starred and non-starred contexts for other hooks (by testing if
+% \csbc{Etoc@aftertitlehook} is empty or not). Notice that the memoir class
+% way of implementing \csbc{tableofcontents} leaves no way for code executed
+% by the TOC code to know if it is executed in starred or non-starred context.
% \begin{macrocode}
\Etoc@aftertitlehook \let \Etoc@aftertitlehook \relax
\fi
- \parskip \cftparskip \@nameuse {cfttocbeforelisthook}}
- {\@nameuse {cfttocafterlisthook}\endgroup\restorefromonecol}}
+ \parskip \cftparskip \@nameuse {cft\Etoc@currext beforelisthook}%
+ }%
+ {\@nameuse {cft\Etoc@currext afterlisthook}%
+ \endgroup\restorefromonecol
+ }%
+}
+% \end{macrocode}
+% Compatibility layer for the \ctanpkg{KOMA-script} classes:
+%
+% \etocrelease{1.09c} (|2020/05/15|) did an update as \ctanpkg{KOMA-script}
+% deprecated \csa{iftocfeature}. Thanks to Bilel Omrani for report. I
+% did not check if cloning of KOMA code required some further updates.
+% \etocrelease{1.09f} added more updates.
+%
+% At \etocrelease{1.2} this is further updated to be usable also for list
+% of figures and tables. However, this update is somewhat theoretical because
+% \etoc does not interfere at all with \csa{listoffigures} and
+% \csa{listoftables}: the update is useful only to make \etoc's
+% \csbc{locallistoffigures} and \csbc{locallistoftables} usable in display
+% style compatibility mode.
+%
+% But during development on this I became aware that \ctanpkg{KOMA-script}
+% since its |3.30| release has the feature that an unnumbered section resets
+% the counters of subsections. This creates a problem (whose description I
+% have moved to the user manual) which can be alleviated for local TOCs at the
+% highest level below global one by using KOMA's |\setuptoc{toc}{leveldown}|.
+% So I decided to do this systematically, as in the code next via a new
+% private hook, but the problem will remain for local TOCs at lower levels,
+% and there does not seem to be any way to tell KOMA to use say
+% |\subsubsection*|, barring, from what I understand from the manual, usage of
+% its \csa{deftocheading}. So in a second stage I decided that per default
+% \etoc would rather use for local TOCs, and not only for KOMA classes but all
+% classes, an adaptive heading fitted to the ``local top''. As this ``local
+% top'' can only be determined from inside the expansion of \csbc{Etoc@toctoc}
+% which contains the |.toc| file data, the boolean \csbc{ifEtoc@etocstyle}
+% was added which will make \csbc{etocsettocstyle} configuration ignored. In
+% this way, with \csbc{etocetoclocaltocstyle}, the document class emulation
+% will apply to the global TOC whereas local TOCs will use the adaptive
+% scheme. To avoid duplication other relevant info is moved to the user
+% manual.
+%
+% We put the trigger of |leveldown| for KOMA classes in
+% \csbc{Etoc@beforetitlehook}. So there will be no test with
+% \csbc{ifEtoc@localtoc} here contrarily to the case of standard classes
+% and memoir. Again, all of this normally is not relevant as by default \etoc
+% \etocrelease{1.2} will use its \csbc{etocetoclocaltocstyle} which
+% for local TOCs ignores the emulation code of the main TOC.
+% \begin{macrocode}
+\let\Etoc@beforetitlehook\@empty
+\if1\@ifclassloaded{scrartcl}0{\@ifclassloaded{scrbook}0{\@ifclassloaded{scrreprt}01}}%
+\expandafter\@gobble
+\else
% \end{macrocode}
-% |1.09c| (|2020/05/15|) does an update as \ctanpkg{KOMA-script} has deprecated
-% \csa{iftocfeature}. Thanks to Bilel Omrani for report. I did not check
-% if cloning of KOMA code required some further updates.
+% Surely paranoid here but I don't have time to go through KOMA documentation
+% (I am not really familiar with these classes).
%
-% Finally |1.09f| added some such updates.
+% MEMO: I do not know if \ctanpkg{KOMA-script}'s \csa{setuptoc} sets options
+% locally or globally. If globally the code below must be modifed to unset
+% the |totoc| option depending on at time of use status of the \etoc own
+% |totoc| options.
% \begin{macrocode}
+ \ifdefined\setuptoc
+ \def\Etoc@beforetitlehook{%
+ \ifEtoc@localtoc
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \setuptoc{\Etoc@currext}{leveldown}%
+ \else
+ \etocifisstarred{}{\etocifmaintoctotoc{\setuptoc{toc}{totoc}}}%
+ \fi
+ }%
+ \fi
+\expandafter\@firstofone
+\fi
+{\def\etocclasslocalperhapsaddtotoc #1{%
+ \etocifisstarred
+ {}%
+ {\csname ifEtoc@local#1totoc\endcsname
+ \setuptoc{\Etoc@currext}{totoc}%
+ \fi
+ }%
+ }%
+}
\ifdefined\Iftocfeature
\def\etoc@Iftocfeature{\Iftocfeature}%
\else
\def\etoc@Iftocfeature{\iftocfeature}%
\fi
+% \end{macrocode}
+% Peut-être en fait je devrais toujours faire |\let\if@dynlist\if@tocleft|?
+% Mais je ne l'ai pas vu dans le code de KOMA pour les LOF et LOT (globales,
+% évidemment). Mais cela m'obligerait à lire vraiment le code source de KOMA.
+% Pas le temps.
+% \begin{macrocode}
\def\etocscrartclstyle{%
\etocsettocstyle
- {\let\if@dynlist\if@tocleft
- \def\@currext{toc}%
-% \end{macrocode}
-% |1.09f| adds this \csa{list@fname} definition hunk although
-% \csa{listoftocname} is presumably always defined. Only to match
-% closely \ctanpkg{KOMA-script} code.
-% \begin{macrocode}
- \@ifundefined{listoftocname}%
- {\def\list@fname{\listofname~toc}}%
- {\expandafter\let\expandafter\list@fname\csname listoftocname\endcsname}%
- \etoc@Iftocfeature {toc}{onecolumn}
- {\etoc@Iftocfeature {toc}{leveldown}
+ {\ifx\Etoc@currext\Etoc@tocext
+ \expandafter\@firstofone
+ \else
+ \expandafter\@gobble
+ \fi
+ {\let\if@dynlist\if@tocleft}%
+ \edef\@currext{\Etoc@currext}%
+ \@ifundefined{listof\@currext name}%
+ {\def\list@fname{\listofname~\@currext}}%
+ {\expandafter\let\expandafter\list@fname
+ \csname listof\@currext name\endcsname}%
+ \etoc@Iftocfeature {\@currext}{onecolumn}
+ {\etoc@Iftocfeature {\@currext}{leveldown}
{}
{\if@twocolumn \aftergroup \twocolumn \onecolumn \fi }}
{}%
- \etoc@Iftocfeature {toc}{numberline}{\def \nonumberline {\numberline {}}}{}%
+ \etoc@Iftocfeature {\@currext}{numberline}%
+ {\def \nonumberline {\numberline {}}}{}%
\expandafter\tocbasic@listhead\expandafter {\list@fname}%
\begingroup \expandafter \expandafter \expandafter
\endgroup \expandafter
\ifx
\csname microtypesetup\endcsname \relax
\else
- \etoc@Iftocfeature {toc}{noprotrusion}{}
+ \etoc@Iftocfeature {\@currext}{noprotrusion}{}
{\microtypesetup {protrusion=false}%
\PackageInfo {tocbasic}%
- {character protrusion at toc deactivated}}%
+ {character protrusion at \@currext\space deactivated}}%
\fi
-% \end{macrocode}
-% |1.09f| adds this hunk with the noparskipfalse test to match current
-% scrartcl (testing done with scrbook |2022/07/04 v3.37|).
-% \begin{macrocode}
- \etoc@Iftocfeature{toc}{noparskipfake}{}{%
+ \etoc@Iftocfeature{\@currext}{noparskipfake}{}{%
\ifvmode \@tempskipa\lastskip \vskip-\lastskip
\addtolength{\@tempskipa}{\parskip}\vskip\@tempskipa\fi
- }%
+ }%
\setlength {\parskip }{\z@ }%
\setlength {\parindent }{\z@ }%
\setlength {\parfillskip }{\z@ \@plus 1fil}%
\csname tocbasic@@before@hook\endcsname
- \csname tb@toc@before@hook\endcsname}
- {%
+ \csname tb@\@currext @before@hook\endcsname
+ }% end of before_toc
+ {% start of after_toc
% \end{macrocode}
-% At |1.09f| I considered adding this \csa{BeforeClosingMainAux} hunk
+% (This next discussion has not been revised at \etocrelease{1.2} so let's
+% hope it is fine).
+%
+% At \etocrelease{1.09f} I considered adding this \csa{BeforeClosingMainAux} hunk
% to the second argument of \csbc{etocsettocstyle}-emulation of \ctanpkg{KOMA-script}.
% But:
% \begin{itemize}
@@ -9433,14 +10780,19 @@ of real structure in a \LaTeX{} document body).
% \string\tocbasic@end@toc@file}%
% }%
\providecommand\tocbasic@end@toc@file{}\tocbasic@end@toc@file
- \csname tb@toc@after@hook\endcsname
- \csname tocbasic@@after@hook\endcsname}}
+ \edef\@currext{\Etoc@currext}%
+ \csname tb@\@currext @after@hook\endcsname
+ \csname tocbasic@@after@hook\endcsname
+ }% end of after_toc
+}
\let\etocscrbookstyle\etocscrartclstyle
\let\etocscrreprtstyle\etocscrartclstyle
% \end{macrocode}
-% placeholder for comments
+% The \csbc{etocclasstocstyle} will be redefined according to document
+% class. Then, later, it will be extended with an
+% \csa{Etoc@classstyletrue}.
% \begin{macrocode}
-\def\etocstandarddisplaystyle{\etocarticlestyle}
+\def\etocclasstocstyle{\etocarticlestyle}
\newcommand*\etocmarkboth[1]{%
\@mkboth{\MakeUppercase{#1}}{\MakeUppercase{#1}}}
\newcommand*\etocmarkbothnouc[1]{\@mkboth{#1}{#1}}
@@ -9450,54 +10802,136 @@ of real structure in a \LaTeX{} document body).
{\csname #1\endcsname *{#3\etocmarkboth{#4}}}}
\newcommand\etoctocstylewithmarksnouc[4][section]{\etocmulticolstyle[#2]%
{\csname #1\endcsname *{#3\etocmarkbothnouc{#4}}}}
-% \end{macrocode}
-% placeholder for comments
-% \begin{macrocode}
-\def\Etoc@redefetocstyle#1{%
- \renewcommand\etoctocstylewithmarks[4][#1]
- {\etocmulticolstyle[##2]%
- {\csname ##1\endcsname *{##3\etocmarkboth{##4}}}}
- \renewcommand\etoctocstylewithmarksnouc[4][#1]
- {\etocmulticolstyle[##2]%
- {\csname ##1\endcsname *{##3\etocmarkbothnouc{##4}}}}
- \renewcommand\etoctocstyle[3][#1]{%
- \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3}}}}
+\def\Etoc@redefetocstylesforchapters{%
+ \renewcommand\etoctocstylewithmarks[4][chapter]{%
+ \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3\etocmarkboth{##4}}}%
+ }
+ \renewcommand\etoctocstylewithmarksnouc[4][chapter]{%
+ \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3\etocmarkbothnouc{##4}}}%
+ }
+ \renewcommand\etoctocstyle[3][chapter]{%
+ \etocmulticolstyle[##2]{\csname ##1\endcsname *{##3}}
+ }
+}
\@ifclassloaded{scrartcl}
- {\renewcommand*\etocstandarddisplaystyle{\etocscrartclstyle}}{}
+ {\renewcommand*\etocclasstocstyle{\etocscrartclstyle}}{}
\@ifclassloaded{book}
{\renewcommand*\etocfontone{\normalfont\normalsize}
- \renewcommand*\etocstandarddisplaystyle{\etocbookstyle}
- \Etoc@redefetocstyle{chapter}}{}
+ \renewcommand*\etocclasstocstyle{\etocbookstyle}
+ \Etoc@redefetocstylesforchapters}{}
\@ifclassloaded{report}
{\renewcommand*\etocfontone{\normalfont\normalsize}
- \renewcommand*\etocstandarddisplaystyle{\etocreportstyle}
- \Etoc@redefetocstyle{chapter}}{}
+ \renewcommand*\etocclasstocstyle{\etocreportstyle}
+ \Etoc@redefetocstylesforchapters}{}
\@ifclassloaded{scrbook}
{\renewcommand*\etocfontone{\normalfont\normalsize}
- \renewcommand*\etocstandarddisplaystyle{\etocscrbookstyle}
- \Etoc@redefetocstyle{chapter}}{}
+ \renewcommand*\etocclasstocstyle{\etocscrbookstyle}
+ \Etoc@redefetocstylesforchapters}{}
\@ifclassloaded{scrreprt}
{\renewcommand*\etocfontone{\normalfont\normalsize}
- \renewcommand*\etocstandarddisplaystyle{\etocscrreprtstyle}
- \Etoc@redefetocstyle{chapter}}{}
+ \renewcommand*\etocclasstocstyle{\etocscrreprtstyle}
+ \Etoc@redefetocstylesforchapters}{}
\@ifclassloaded{memoir}
- {\etocsetlevel{appendix}{0}%
- \renewcommand*\etocfontone{\normalfont\normalsize}
- \etocmemoirtoctotocfmt{chapter}{\contentsname}%
- \renewcommand*\etocstandarddisplaystyle{\etocmemoirstyle}
- \Etoc@redefetocstyle{chapter}}{}
+ {\renewcommand*\etocfontone{\normalfont\normalsize}
+ \renewcommand*\etocclasstocstyle{\etocmemoirstyle}
+ \Etoc@redefetocstylesforchapters}{}
\def\etoctocloftstyle {%
- \etocsettocstyle
- {\@cfttocstart\par\begingroup
- \parindent\z@ \parskip\cftparskip \@cftmaketoctitle
- \if@cfttocbibind\@cftdobibtoc\fi }%
- {\endgroup\@cfttocfinish }%
+ \etocsettocstyle{%
+ \@cfttocstart
+ \par
+ \begingroup
+ \parindent\z@ \parskip\cftparskip
+% \end{macrocode}
+% I don't feel like redefining \csa{@cftmaketoctitle} etc to apply ``level
+% down''. Up to the user to use the tocloft interface after the main TOC
+% to do appropriate actions. I consider emitting a warning, but then if
+% the user has customize \csa{@cftmaketoctitle} or variant, how to know?
+% (apart from numerous ifx tests).
+% \begin{macrocode}
+ \@nameuse{@cftmake\Etoc@currext title}%
+% \end{macrocode}
+% But for adding an appropriate entry to the toc file I can intervene silently.
+% I can remove the test \csa{if@cfttocbibind} here as anyhow I have to test
+% status of \etoc `to toc' options.
+% \begin{macrocode}
+ \ifEtoc@localtoc
+ \etoctocloftlocalperhapsaddtotoc\Etoc@currext
+ \else
+ \etocifisstarred {}{\ifEtoc@maintoctotoc\@cftdobibtoc\fi}%
+ \fi
+ }%
+ {%
+ \endgroup
+ \@cfttocfinish
+ }%
+}
+\def\etoctocloftlocalperhapsaddtotoc#1{%
+ \etocifisstarred
+ {}%
+ {\csname ifEtoc@local#1totoc\endcsname
+ \ifdefined\c@chapter\def\@tocextra{@section}\else\def\@tocextra{@subsection}\fi
+ \csname @cftdobib#1\endcsname
+ \fi
+ }%
+}
+% \end{macrocode}
+% This is active only if \ctanpkg{tocbibind} boolean \csa{if@dotoctoc} is found
+% true at begin document and there was no use of \csbc{etocsettocstyle} in the
+% preamble. The part on local TOC also applies to local LOF and LOT but is
+% executed only if \csbc{etocclasstocstyle} was present in the preamble. Under
+% the default \csbc{etocetoclocaltocstyle}, only the global TOC is under
+% influence of this (assuming thus that \ctanpkg{tocbibind} was loaded without
+% its |nottoc| or |none| option).
+% \begin{macrocode}
+\def\etoctocbibindstyle {%
+ \etocsettocstyle {%
+ \toc@start
+ \ifEtoc@localtoc
+ \@nameuse{etocclasslocal\Etoc@currext maketitle}%
+ \etocclasslocalperhapsaddtotoc\Etoc@currext
+ \else
+ \etoc@tocbibind@dotoctitle
+ \fi
+ }%
+ {\toc@finish}%
}
-\@ifclassloaded{memoir}{}
-{\@ifpackageloaded{tocloft}
+\def\etoc@tocbibind@dotoctitle {%
+% \end{macrocode}
+% If \ctanpkg{tocbibind} is loaded but later between |\begin{document}| and
+% \csa{tableofcontents} the user does \csbc{etocsetup}|{maintoctotoc=afalse}|
+% we have to catch this.
+% \begin{macrocode}
+ \if@bibchapter
+ \etocifisstarred
+ {\chapter*{\contentsname}\prw@mkboth{\contentsname} % id.
+ }%
+ {\ifEtoc@maintoctotoc
+ \toc@chapter{\contentsname} %<-space from original
+ \else
+ \chapter*{\contentsname}\prw@mkboth{\contentsname} % id.
+ \fi
+ }%
+ \else
+ \etocifisstarred
+ {\@nameuse{\@tocextra}*{\contentsname\prw@mkboth{\contentsname}} %<-space
+ }
+ {\ifEtoc@maintoctotoc
+ \toc@section{\@tocextra}{\contentsname} %<-space from original
+ \else
+ \@nameuse{\@tocextra}*{\contentsname\prw@mkboth{\contentsname}} % id.
+ \fi
+ }%
+ \fi
+}%
+\@ifclassloaded{memoir}
+{}
+{% memoir not loaded
+ \@ifpackageloaded{tocloft}
{\if@cftnctoc\else
- \renewcommand*\etocstandarddisplaystyle{\etoctocloftstyle}
- \AtBeginDocument{\let\tableofcontents\etoctableofcontents}
+ \ifEtoc@keeporiginaltoc
+ \else
+ \let\tableofcontents\etoctableofcontents
+ \fi
\fi }
{\AtBeginDocument
{\@ifpackageloaded{tocloft}
@@ -9506,7 +10940,10 @@ of real structure in a \LaTeX{} document body).
{Package `tocloft' was loaded after `etoc'.\MessageBreak
To prevent it from overwriting \protect\tableofcontents, it will\MessageBreak
be tricked into believing to have been loaded with its\MessageBreak
- option `titles'. \space Please load `tocloft' before `etoc'}%
+ option `titles'. \space But this will cause the `tocloft'\MessageBreak
+ customization of the titles of the main list of figures\MessageBreak
+ and list of tables to not apply either.\MessageBreak
+ You should load `tocloft' before `etoc'.}%
\AtEndDocument{\PackageWarning{etoc}
{Please load `tocloft' before `etoc'!\@gobbletwo}}%
\fi
@@ -9515,34 +10952,121 @@ of real structure in a \LaTeX{} document body).
}%
}%
}
+\@ifclassloaded{memoir}
+{}
+{% memoir not loaded
+ \AtBeginDocument{%
+ \@ifpackageloaded{tocloft}
+ {%
+ \def\etocclasstocstyle{%
+ \etoctocloftstyle
+ \Etoc@classstyletrue
+ }%
+ \ifEtoc@etocstyle
+ \ifEtoc@classstyle
+ \etocclasstocstyle
+ \Etoc@etocstyletrue
+ \fi
+ \else
+ \ifEtoc@classstyle
+ \etocclasstocstyle
+ \fi
+ \fi
+ }%
+ {% no tocloft
+ \@ifpackageloaded {tocbibind}
+ {\if@dotoctoc
+ \def\etocclasstocstyle{%
+ \etoctocbibindstyle
+ \Etoc@classstyletrue
+ }%
+ \ifEtoc@etocstyle
+ \ifEtoc@classstyle
+ \etocclasstocstyle
+ \Etoc@etocstyletrue
+ \fi
+ \else
+ \ifEtoc@classstyle
+ \etocclasstocstyle
+ \fi
+ \fi
+% \end{macrocode}
+% Not clear if I should interpret \csa{Etoc@keeporiginaltoctrue} in this sense
+% to not modify \ctanpkg{tocbibind} overwrite of \csbc{tableofcontents}. But
+% let's obey this interpretation.
+% \begin{macrocode}
+ \ifEtoc@keeporiginaltoc
+ \else
+ \let\tableofcontents\etoctableofcontents
+ \fi
+ }%
+ {}%
+ }%
% \end{macrocode}
-% \LaTeX\ 2021 fall release lets \csa{contentsline} always grab four arguments,
-% so with |1.09e 2021/09/23| we make sure our \csa{addtocontents} will always
-% provide \csa{contentsline} with four arguments. This extra |{}| is done
-% without checking LaTeX's version by laziness, as an impact on documents
-% compiled with former LaTeX could be visible only with very special contexts
-% that only the author himself would ever consider.
+% Maybe I should check if the options were already set. I will simply
+% make the message more generic.
+% \begin{macrocode}
+ \@ifpackageloaded{tocbibind}
+ {% tocbibind, perhaps with tocloft
+ \if@dotoctoc
+ \ifEtoc@keeporiginaltoc
+ \else
+ \let\tableofcontents\etoctableofcontents
+ \fi
+ \etocsetup{maintoctotoc,localtoctotoc}%
+ \PackageInfo{etoc}{%
+ Setting (or re-setting) the options `maintoctotoc' and\MessageBreak
+ `localtoctotoc' to true as tocbibind was detected and\MessageBreak
+ found to be configured for `TOC to toc'.\MessageBreak
+ Reported at begin document}%
+ \fi
+ \if@dotoclof
+ \ifEtoc@lof
+ \etocsetup{localloftotoc}%
+ \PackageInfo{etoc}{%
+ Setting (or re-setting) `localloftotoc=true' as the\MessageBreak
+ package tocbibind was detected and is configured for\MessageBreak
+ `LOF to toc'. Reported at begin document}%
+ \fi
+ \fi
+ \if@dotoclot
+ \ifEtoc@lot
+ \etocsetup{locallottotoc}%
+ \PackageInfo{etoc}{%
+ Setting (or re-setting) `locallottotoc=true' as the\MessageBreak
+ package tocbibind was detected and is configured for\MessageBreak
+ `LOT to toc'. Reported at begin document}%
+ \fi
+ \fi
+ }% end of tocbibind branch
+ {}%
+ }% end of at begin document
+}% end of not with memoir branch
+% \end{macrocode}
+% \LaTeX\ 2021 fall release lets \csa{contentsline} always grab four
+% arguments, so with \etocrelease{1.09e} |2021/09/23| we make sure our
+% \csa{addtocontents} will always provide \csa{contentsline} with four
+% arguments. This extra |{}| is done without checking LaTeX's version by
+% laziness, as an impact on documents compiled with former LaTeX could be
+% visible only with very special contexts that only the author himself would
+% ever consider.
%
-% Let's also add \csa{protected@file@percent} at |1.09e| although this is a
-% priori of no relevance as \etoc reads the toc file with |\endlinechar=-1|
-% regime.
+% Let's also add \csa{protected@file@percent} at \etocrelease{1.09e} although
+% this is a priori of no relevance as \etoc reads the toc file with
+% |\endlinechar=-1| regime.
%
% When using \csa{addcontentsline} nothing needs to be done as both things are
% handled by \LaTeX\ upstream.
+%
+% \etocrelease{1.2} executes the \csbc{ifEtoc@hyperref} test inside the fourth
+% argument, rather than using one \csa{addtocontents} in each branch.
% \begin{macrocode}
-\def\Etoc@addtocontents #1#2%
- {\ifEtoc@hyperref
- \addtocontents {toc}{\protect\contentsline
- {#1}{#2}%
- {\thepage }{\@currentHref }%
- \ifdefined\protected@file@percent\protected@file@percent\fi
- }%
- \else
- \addtocontents {toc}{\protect\contentsline
- {#1}{#2}{\thepage }{}%
- \ifdefined\protected@file@percent\protected@file@percent\fi
- }%
- \fi}
+\def\Etoc@addtocontents #1#2{%
+ \addtocontents {toc}{%
+ \protect\contentsline{#1}{#2}{\thepage}{\ifEtoc@hyperref\@currentHref\fi}%
+ \ifdefined\protected@file@percent\protected@file@percent\fi
+ }%
+}
\def\Etoc@addcontentsline@ #1#2#3{%
\@namedef{toclevel@#1}{#3}\addcontentsline {toc}{#1}{#2}%
}
@@ -9565,14 +11089,15 @@ of real structure in a \LaTeX{} document body).
\DeclareRobustCommand*{\etocimmediatetoccontentsline}
{\@ifstar{\Etoc@addcontentsline@@immediately}{\Etoc@addtocontents@immediately}}
% \end{macrocode}
-% placeholder
+% Formerly a \LaTeX{} counter |etoc@tocdepth| was used but at
+% \etocrelease{1.2} it has been replaced by macro-storage.
% \begin{macrocode}
-\def\Etoc@storetocdepth {\global\c@etoc@tocdepth\c@tocdepth }
-\def\Etoc@restoretocdepth {\global\c@tocdepth\c@etoc@tocdepth }
+\def\Etoc@storetocdepth {\xdef\Etoc@savedtocdepth{\number\c@tocdepth}}
+\def\Etoc@restoretocdepth {\global\c@tocdepth\Etoc@savedtocdepth\relax}
\def\etocobeytoctocdepth {\def\etoc@settocdepth
- {\afterassignment\Etoc@@nottoodeep \global\c@tocdepth}}
-\def\Etoc@@nottoodeep {\ifnum\c@tocdepth>\c@etoc@tocdepth
- \global\c@tocdepth\c@etoc@tocdepth\fi }
+ {\afterassignment\Etoc@@nottoodeep \global\c@tocdepth}}
+\def\Etoc@@nottoodeep {\ifnum\Etoc@savedtocdepth<\c@tocdepth
+ \global\c@tocdepth\Etoc@savedtocdepth\relax\fi }
\def\etocignoretoctocdepth {\let\etoc@settocdepth\@gobble }
\def\etocsettocdepth {\futurelet\Etoc@nexttoken\Etoc@set@tocdepth }
\def\Etoc@set@tocdepth {\ifx\Etoc@nexttoken\bgroup
@@ -9615,7 +11140,7 @@ of real structure in a \LaTeX{} document body).
\def\etocdepthtag #1#{\Etoc@depthtag }
\def\Etoc@depthtag #1{\addtocontents {toc}{\protect\etoc@depthtag {#1}}}
% \end{macrocode}
-% |1.09f| adds \csbc{etocimmediatedepthtag.toc}. This can serve in some
+% \etocrelease{1.09f} adds \csbc{etocimmediatedepthtag.toc}. This can serve in some
% circumstances, see user documentation. Apologies for long delay to Norman
% Ramsey who reported problem and his fix in July... 2016!
% \begin{macrocode}
@@ -9649,7 +11174,7 @@ of real structure in a \LaTeX{} document body).
{Use \protect\etocsettocdepth.toc as replacement}%
}%
\AtBeginDocument {%
- \@ifclassloaded{memoir}
+ \@ifclassloaded{memoir}
{\PackageInfo {etoc}
{Regarding `memoir' class command \protect\settocdepth, consider\MessageBreak
\protect\etocsettocdepth.toc as a drop-in replacement with more\MessageBreak
@@ -9658,8 +11183,8 @@ of real structure in a \LaTeX{} document body).
and \protect\etocsetnexttocdepth\space should be used in place of\MessageBreak
`memoir' command \protect\maxtocdepth\@gobble}%
}%
- {\@ifpackageloaded {tocvsec2}
- {\def\maxtocdepth #1{\Etoc@tocvsec@err \maxtocdepth }%
+ {\@ifpackageloaded {tocvsec2}{%
+ \def\maxtocdepth #1{\Etoc@tocvsec@err \maxtocdepth }%
\def\settocdepth #1{\Etoc@tocvsec@err \settocdepth }%
\def\resettocdepth {\@ifstar {\Etoc@tocvsec@err \resettocdepth }%
{\Etoc@tocvsec@err \resettocdepth }%
@@ -9675,9 +11200,10 @@ of real structure in a \LaTeX{} document body).
{Package `tocvsec2' detected and its modification of\MessageBreak
\protect\tableofcontents\space reverted. \space Use
\protect\etocsettocdepth.toc\MessageBreak as a replacement
- for `tocvsec2' toc-related commands}}% tocvsec2 loaded
- {}% not loaded
- }%
+ for `tocvsec2' toc-related commands}%
+ }% tocvsec2 loaded
+ {}% tocvsec2 not loaded
+ }%
}%
% \end{macrocode}
% placeholder
@@ -9730,27 +11256,40 @@ of real structure in a \LaTeX{} document body).
}%
}%
% \end{macrocode}
-% |1.09i| would like to rename this to \csa{Etoc@setlocaltop}, for
+% \etocrelease{1.09i} would like to rename this to \csa{Etoc@setlocaltop}, for
% consistency with internal macros, but too late it is already in user |.toc| files.
% \begin{macrocode}
\def\etoc@setlocaltop #1{%
- \global\let\Etoc@level #1%
- \Etoc@skipthisonefalse
- \ifnum\Etoc@level=\Etoc@@six@@
+ \ifnum#1=\Etoc@@six@@
\Etoc@skipthisonetrue
\else
+ \Etoc@skipthisonefalse
+% \end{macrocode}
+% MEMO: the \csbc{Etoc@level} thus continues receiving updates from various
+% \csbc{etoc@setlocaltop} present in the |.toc| file even once the local toc
+% is already done, but this has no importance, as the code in
+% \csbc{Etoc@toctoc} after executing the code contents is not influenced by
+% this but only by the final status of \csbc{Etoc@stackofends} remains the
+% same. And this gets updated via \csbc{Etoc@setlocaltop@doendsandbegin} (see
+% below).
+%
+% I should check if not worthwile to move the \csbc{ifEtoc@stoptoc} test
+% earlier.
+%
+% There should be two notions of local top. One for a potential barrier,
+% stopping a toc, the other for setting a local top. These two should be
+% distinct. Or at least additional to this one which does both. But then I
+% would have to document. And test. And implement first.
+% \begin{macrocode}
+ \global\let\Etoc@level #1%
+ \global\let\Etoc@virtualtop #1%
\ifEtoc@localtoc
- \ifEtoc@stoptoc\Etoc@skipthisonetrue
+ \ifEtoc@stoptoc
+ \Etoc@skipthisonetrue
\else
\ifEtoc@notactive
- \Etoc@setflags
\Etoc@skipthisonetrue
\else
-% \end{macrocode}
-% Attention, |1.09| has \csbc{etoclocaltop} which is former \csa{Etoc@localtop}
-% \emph{minus one}. Hence the shape of the conditional. Memo: it makes sense
-% only for code executed under "active" status of the TOC.
-% \begin{macrocode}
\unless\ifnum\Etoc@level>\etoclocaltop
\Etoc@skipthisonetrue
\global\Etoc@stoptoctrue
@@ -9762,42 +11301,48 @@ of real structure in a \LaTeX{} document body).
\let\Etoc@next\@empty
\ifEtoc@skipthisone
\else
- \ifnum\c@tocdepth<\Etoc@level
+ \ifnum\Etoc@level>\c@tocdepth
\else
- \ifEtoc@standard
+ \ifEtoc@standardlines
\else
- \let\Etoc@next\Etoc@setlocaltop@doends@dobegins
- \fi
- \fi
- \fi
% \end{macrocode}
-% At |1.09f| the |\global\Etoc@skipprefixfalse| is added. This fixes a
-% weird problem that an \csbc{etocskipfirstprefix} from this level (which a priori
-% only serves to delimit the local contents) impacted (in the global TOC for
-% example) the rendering of the first finer subsequent heading. Not resetting
-% the boolean was an oversight, and it shows in context of the package
-% built-in level styles as they do use \csbc{etocskipfirstprefix}. But this also
-% stresses that the name of the macro is a bit of a misnomer, yes it serves to
-% delimit local table of contents, but really it is implemented as a ghost of
-% a sectioning unit which does have an impact (on the global TOC or local TOCs
+% So here the \csbc{etocsetlocaltop}|.toc| will cause various starts and
+% finish parts to get executed, even for the somewhat fictitious levels. But
+% this may cause collaterals, in particular we have to be careful about the
+% \csbc{ifEtoc@skipprefix} Boolean, which may be set to \csa{iftrue} in
+% the \marg{start} part of the level style and thus needs to be reset to
+% \csa{iffalse}. This is done automatically in \csbc{Etoc@etoccontentsline@}
+% but here we are not executing it so we need to add somewhere a
+% |\global\Etoc@skipprefixfalse| (else we may impact rendering of subsequent
+% level). So we put it together with \csbc{Etoc@doendsandbegin} in a wrapper.
+% This wrapper is also there to avoid a problem when the TOC is checked for
+% emptiness, as we need then to be able to tell \csbc{etoc@setlocaltop} to
+% not execute anything.
+%
+% This also stresses
+% that the name of the macro is a bit of a misnomer, yes it serves to delimit
+% local table of contents, but really it is implemented as a ghost of a
+% sectioning unit which does have an impact (on the global TOC or local TOCs
% from encompassing levels), as it triggers when encountered the \marg{finish}
% portions of previous finer levels (and the \marg{finish} code of its own
% level will be executed sooner or later), and the \marg{start} code of
% subsequent finer levels (as well as its own \marg{start} code at least once,
% depending on how levels are nested).
-%
-% |1.09i| fixes a bad behaviour of \etoc in \csbc{etocchecksemptiness} regime
-% when \csbc{etocsetlocaltop.toc} has been made use of in the document. Indeed
-% the execution of \csbc{Etoc@toctoks} for the emptiness check thus triggered
-% execution of \marg{start} and \marg{finish} parts of the line styles. So
-% we abstract an \csbc{Etoc@setlocaltop@doends@dobegins} which will be made a no-op
-% in emptiness-checking contexts. Also, the code lines above have been edited
-% now that \csa{Etoc@next} here is not followed by tokens within a brace pair.
% \begin{macrocode}
+ \let\Etoc@next\Etoc@setlocaltop@doendsandbegin
+ \fi
+ \fi
+ \fi
\Etoc@next
}%
-\def\Etoc@setlocaltop@doends@dobegins
- {\Etoc@doends\Etoc@dobegins\global\Etoc@skipprefixfalse}%
+% \end{macrocode}
+% It is important to reset the \csbc{ifEtoc@skipprefix} boolean, as is done in
+% \csbc{Etoc@etoccontentsline@}.\par
+% \begin{macrocode}
+\def\Etoc@setlocaltop@doendsandbegin{%
+ \Etoc@doendsandbegin
+ \global\Etoc@skipprefixfalse
+}
\addtocontents {toc}{\protect\@ifundefined{etoctocstyle}%
{\let\protect\etoc@startlocaltoc\protect\@gobble
\let\protect\etoc@settocdepth\protect\@gobble
@@ -9806,23 +11351,37 @@ of real structure in a \LaTeX{} document body).
% \end{macrocode}
% Initializations.
% \begin{macrocode}
-\def\etocstandardlines {\Etoc@standardtrue}
-\def\etoctoclines {\Etoc@standardfalse}
+\def\etocstandardlines {\Etoc@standardlinestrue}
+\def\etoctoclines {\Etoc@standardlinesfalse}
\etocdefaultlines
\etocstandardlines
-\etocstandarddisplaystyle
+\def\etocstandarddisplaystyle{%
+ \PackageWarningNoLine{etoc}{%
+ \string\etocstandarddisplaystyle \on@line\MessageBreak
+ is deprecated. \space Please use \string\etocclasstocstyle}%
+}
+\expandafter\def\expandafter\etocclasstocstyle\expandafter{%
+ \etocclasstocstyle
+ \Etoc@classstyletrue
+}
+\def\etocetoclocaltocstyle{\Etoc@etocstyletrue}
+\def\etocusertocstyle{\Etoc@etocstylefalse}
+\etocclasstocstyle
+\etocetoclocaltocstyle
\etocobeytoctocdepth
\etocobeydepthtags
-\let\etocaftertochook \@empty
-\let\etocbeforetitlehook \@empty
+\let\etocbeforetitlehook \@empty
+\let\etocaftertitlehook \@empty
+\let\etocaftercontentshook \@empty
+\let\etocaftertochook \@empty
% \end{macrocode}
% |listings| abuses \csa{tableofcontents} for its \csa{lstlistoflistings}. It
% doesn't seem worth to let my version of \csbc{tableofcontents} have to check for
-% this special circumstance. So at |1.09d|, simply add this (and induced
-% annoying updates to documentation at at least two locations):
+% this special circumstance. So at \etocrelease{1.09d}, simply add this (the
+% boolean was added at \etocrelease{1.2}):
% \begin{macrocode}
\def\etockeeporiginaltableofcontents
- {\let\tableofcontents\etocoriginaltableofcontents}%
+ {\Etoc@keeporiginaltoctrue\let\tableofcontents\etocoriginaltableofcontents}%
\endinput
% \end{macrocode}
% \MakePercentComment
diff --git a/macros/latex/contrib/etoc/etoc.pdf b/macros/latex/contrib/etoc/etoc.pdf
index 8029b61f1f..667b79b3ad 100644
--- a/macros/latex/contrib/etoc/etoc.pdf
+++ b/macros/latex/contrib/etoc/etoc.pdf
Binary files differ
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-26 01:41:35 +0000