From c000ad35f0ce69cc0466ad24b0647c1e295c0259 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Fri, 3 Mar 2023 03:05:02 +0000 Subject: CTAN sync 202303030305 --- macros/jptex/latex/pxrubrica/LICENSE | 2 +- macros/jptex/latex/pxrubrica/README-ja.md | 2 + macros/jptex/latex/pxrubrica/README.md | 2 + macros/jptex/latex/pxrubrica/pxrubrica-en.pdf | Bin 56747 -> 56587 bytes macros/jptex/latex/pxrubrica/pxrubrica-en.tex | 4 +- macros/jptex/latex/pxrubrica/pxrubrica.dtx | 20 +- macros/jptex/latex/pxrubrica/pxrubrica.pdf | Bin 391048 -> 392897 bytes macros/latex/contrib/etoc/README.md | 233 +- macros/latex/contrib/etoc/etoc.dtx | 11685 ++++++++++++---------- macros/latex/contrib/etoc/etoc.pdf | Bin 857380 -> 940496 bytes macros/latex/contrib/pangram/README.md | 2 +- macros/latex/contrib/pangram/pangram.dtx | 97 +- macros/latex/contrib/pangram/pangram.ins | 4 +- macros/latex/contrib/pangram/pangram.pdf | Bin 100389 -> 105320 bytes macros/latex/contrib/qrbill/README.md | 8 +- macros/latex/contrib/qrbill/qrbill-qrencode.lua | 1351 +++ macros/latex/contrib/qrbill/qrbill.dtx | 21 +- macros/latex/contrib/qrbill/qrbill.ins | 6 +- macros/latex/contrib/qrbill/qrbill.pdf | Bin 86225 -> 86454 bytes macros/xetex/latex/xduts/xduts.dtx | 69 +- macros/xetex/latex/xduts/xduts.pdf | Bin 331879 -> 331681 bytes 21 files changed, 8162 insertions(+), 5344 deletions(-) create mode 100644 macros/latex/contrib/qrbill/qrbill-qrencode.lua (limited to 'macros') diff --git a/macros/jptex/latex/pxrubrica/LICENSE b/macros/jptex/latex/pxrubrica/LICENSE index 58cd49d31d..5cf6f6fb2d 100644 --- a/macros/jptex/latex/pxrubrica/LICENSE +++ b/macros/jptex/latex/pxrubrica/LICENSE @@ -1,6 +1,6 @@ The MIT License -Copyright (c) 2012-2021 Takayuki YATO (aka. "ZR") +Copyright (c) 2012-2023 Takayuki YATO (aka. "ZR") Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/macros/jptex/latex/pxrubrica/README-ja.md b/macros/jptex/latex/pxrubrica/README-ja.md index 4ee9954acb..162effe5c4 100644 --- a/macros/jptex/latex/pxrubrica/README-ja.md +++ b/macros/jptex/latex/pxrubrica/README-ja.md @@ -47,6 +47,8 @@ MITライセンスの下で配布される。 更新履歴 -------- + * Version 1.3e 〈2023/03/01〉 + - バグ修正 * Version 1.3d 〈2021/03/06〉 - バグ修正 * Version 1.3c 〈2018/08/16〉 diff --git a/macros/jptex/latex/pxrubrica/README.md b/macros/jptex/latex/pxrubrica/README.md index f343cb3087..7cdffd805c 100644 --- a/macros/jptex/latex/pxrubrica/README.md +++ b/macros/jptex/latex/pxrubrica/README.md @@ -50,6 +50,8 @@ This package is distributed under the MIT License. Revision History ---------------- + * Version 1.3e 〈2023/03/01〉 + - Bug fix. * Version 1.3d 〈2021/03/06〉 - Bug fix. * Version 1.3c 〈2018/08/16〉 diff --git a/macros/jptex/latex/pxrubrica/pxrubrica-en.pdf b/macros/jptex/latex/pxrubrica/pxrubrica-en.pdf index 9861dbf75f..f207e8dc5e 100644 Binary files a/macros/jptex/latex/pxrubrica/pxrubrica-en.pdf and b/macros/jptex/latex/pxrubrica/pxrubrica-en.pdf differ diff --git a/macros/jptex/latex/pxrubrica/pxrubrica-en.tex b/macros/jptex/latex/pxrubrica/pxrubrica-en.tex index 6ad593e02f..faf152e135 100644 --- a/macros/jptex/latex/pxrubrica/pxrubrica-en.tex +++ b/macros/jptex/latex/pxrubrica/pxrubrica-en.tex @@ -8,8 +8,8 @@ \newcommand*{\Eg}{E.\,g.\mbox{}} \newcommand*{\eg}{e.\,g.\mbox{}} \newcommand*{\ie}{i.\,e.\mbox{}} -\newcommand*{\myfileversion}{1.3d} -\newcommand*{\myfiledate}{2021/03/06} +\newcommand*{\myfileversion}{1.3e} +\newcommand*{\myfiledate}{2023/03/01} \newsavebox{\myexample} \begin{document} diff --git a/macros/jptex/latex/pxrubrica/pxrubrica.dtx b/macros/jptex/latex/pxrubrica/pxrubrica.dtx index f07e6b4966..0b8bca5737 100644 --- a/macros/jptex/latex/pxrubrica/pxrubrica.dtx +++ b/macros/jptex/latex/pxrubrica/pxrubrica.dtx @@ -3,7 +3,7 @@ % % This is file 'pxrubrica.dtx'. % -% Copyright (c) 2012-2021 Takayuki YATO (aka. "ZR") +% Copyright (c) 2012-2023 Takayuki YATO (aka. "ZR") % GitHub: https://github.com/zr-tex8r % Twitter: @zr_tex8r % @@ -20,7 +20,7 @@ %<*driver> \ProvidesFile{pxrubrica.dtx} % - [2021/03/06 v1.3d PX Japanese-style ruby] + [2023/03/01 v1.3e PX Japanese-style ruby] %<*driver> \documentclass[uplatex]{jsarticle} \usepackage{doc} @@ -2268,11 +2268,17 @@ % \end{macro} % % \begin{macro}{\ifpxrr@in@uptex} -% $B%(%s%8%s$,(B{\upTeX}$B7O$G$"$k$+!#(B -% |\enablecjktoken| $B$N%W%j%_%F%#%V%F%9%H$GH=Dj$9$k!#(B -% \begin{macrocode} -\pxrr@ifprimitive\enablecjktoken{% - \pxrr@csletcs{ifpxrr@in@uptex}{iftrue}% +% $B%(%s%8%s$,(B{\upTeX}$B7O$G$"$j$+$DFbIt4A;z%3!<%I$,(BUnicode$B$G$"$k$+!#(B +% $B%(%s%8%sH=Dj$O(B |\kchardef| $B$N%W%j%_%F%#%V%F%9%H$GH=Dj$9$k!#(B +% \Note $B%F%9%H$9$k%W%j%_%F%#%V$r(B |\enablecjktoken| $B$+$i(B |\kchardef| $B$K(B +% $BJQ99!J(B|\kchardef| $B$O 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>}% % %<*!readme> %% %% Package: etoc -%% Version: 1.1c +%% Version: 1.2 %% License: LPPL 1.3c %% Copyright (C) 2012-2023 Jean-Francois Burnol %% % %<*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 % @@ -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 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`. % %<*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,4015 +1836,4112 @@ 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} +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 + +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. + +So one should think twice before adding manually extra commands to the |.toc| +file. See \autoref{sec:addingtotoc} for further discussion. + + + -\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} +\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. -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}. +\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} -\section{A first example} -\label{sec:firstexample} -\label{invisiblelocaltableofcontents} +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). -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{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.} -\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} -\endgroup -\end{filecontentsdef} - -\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|. - -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{A second example} -\label{sec:secondexample} - -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. - -\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\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 -\localtableofcontents +\DeclareTOCStyleEntry[numwidth=3em,indent=0em]{tocline}{subsection} +\DeclareTOCStyleEntry[numwidth=3.5em,indent=3em]{tocline}{subsubsection} +\localtableofcontents \label{toc:tocstyle} +\endgroup -\section{The \csbhyp{tableofcontents}, \csbhyp{localtableofcontents} and - \csbhyp{localtableofcontentswithrelativedepths} commands} -\label{tableofcontents} -\label{etoctableofcontents} -\label{localtableofcontents} -\label{localtableofcontentswithrelativedepth} -\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}. -\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 -subsection, etc... (see also \csb{etocsetnexttocdepth}).% -% -\footnote{As is explained in \autoref{sec:labeling} the syntax allows to - create somewhere a local table of contents and to display it at some other - location either before or after its origin.}% -\textsuperscript{,}% -\footnote{As is explained in \autoref{sec:tocdepth} \etoc allows at anytime to - locally redefine the numeric levels associated to named ones, which brings - 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 - 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 +\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} -\section{This is a section} -\localtableofcontentswithrelativedepth{+2} +\etocsettocstyle + {\section*{Local table of contents}}% + {}% don't do anything special after the toc contents \end{verbatim} - will create a local table of contents taking into account the subsections - and subsubsections inside this section, independently of what is the value - 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.} -\end{description} -The macro \localtocwrdp is \textbf{new with |1.09|}.% -% -\footnote{Thanks to Tony \textsc{Roberts} for feature request.} -% +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. -\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}. -\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} -\begin{figure}[ht!] - \centering - \begingroup - \etocstandardlines - \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} - \endgroup -\end{figure} -\end{filecontentsdef} -\filecontentsexec\foo +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}. -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}|.% -% -\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}. +\subsubsection{The \csbhyp{etocarticlestyle}, \csbhyp{etocbookstyle}, + and others commands} +\label{etocarticlestyle} +\label{etocarticlestylenomarks} +\label{etocbookstyle} +\label{etocbookstylenomarks} +\label{etocreportstyle} +\label{etocreportstylenomarks} -\section{A powerful functionality of \etoc: the - re-assignment of levels with \csbhyp{etocsetlevel}} -\label{sec:tocdepth} +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. -The intrinsic levels manipulated by \etoc are numeric: from -|-2| (which corresponds to |book| in the \ctanpkg{memoir} class) -down (from the big to the small) -to |5| (|subparagraph|). But the assignment of a numeric level -to a given name can be modified at any time with the command -\csb{etocsetlevel}\marg{level\_name}\marg{number}. In conjunction -with the use of the \LaTeX{} |tocdepth| counter, this has -powerful applications: \meta{level\_name} does not have to -coincide with an actual document sectioning command, and \etoc -can be used to print arbitrary ``lists of things'', using no -other auxiliary file than the |.toc| file. This is -explained further in \autoref{part:surprising}. +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. -\begin{framed} - It is often said that in the standard classes, the sectioning - level of |\part| is |0| in the classes not having a |\chapter| - command, and |-1| in classes having a |\chapter| command. This - is \emph{correct} for what regards the \emph{automatic - numbering}, as is governed by the value of the |secnumdepth| - counter; but it is \emph{wrong} for what regards the effect of - the |tocdepth| counter: setting the |tocdepth| to |-1| in the - |article| class just before |\tableofcontents| does \emph{not} - prevent Parts from appearing in the Table of Contents. One has - to set it to |-2| for that, whether in the |article| or in the - |book| class. - The canonical levels, a priori known to \etoc, are those of - relevance to the \textbf{|tocdepth|} counter in the standard - classes and are recapitulated in this table: \centeredline{ - \fbox{\begin{tabular}{rc} - (\ctanpkg{memoir} class) book&-2\\ part&-1\\ chapter&0 \\ - section&1\\ subsection&2 \\ - subsubsection&3 \\ paragraph&4 \\ subparagraph& 5 - \end{tabular}}} +\subsubsection{The \csbhyp{etocinline} and \csbhyp{etocdisplay} commands} +\label{etocinline} +\label{etocnopar} +\label{etocdisplay} -\smallskip With \etoc, the user can easily print a local table of -contents inside a given subsection, where subsubsections will be -printed in the style of sections, paragraphs in the style of -subsections, and subparagraphs in the style of subsubsections, if -so desired. One can also decide to set everything to be at the level -|6| (never displayed by \etoc), except for example -paragraphs, promoted to be at level |1|, and then one obtains a nice -table of contents of all the paragraphs from the document! -(|tocdepth| at least |1|)\footnotemark -\end{framed} +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. -\footnotetext{and one should naturally not print this TOC of paragraphs in - compatibility mode, which would insist on inserting a gigantic left - margin.} +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. -\section{The \csbhyp{etocsettocdepth} and \csbhyp{etocsetnexttocdepth} commands} -\label{etocsettocdepth} -\label{etocsetnexttocdepth} -\label{invisibletableofcontents} +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} -The |tocdepth| counter has no bearing on what gets written to the |.toc| file; -its action is only on the actual typesetting of the table of -contents.\footnote{In the standard classes (at least), it also influences the - \csa{listoftables} and \csa{listoffigures}, via \csa{@dottedtocline}.} In the -standard classes there is only one |\tableofcontents| possible, whereas with -\etoc, arbitrarily many are allowed, so one may change |tocdepth| to the -appropriate value (which decides the finest sectioning level displayed) again -and again each time a table of contents needs to be typeset. +(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 -\etoc provides \csb {etocsettocdepth}\marg{level} whose mandatory argument is -either -numeric (from |-3| to |5|) or a division name such as |subsection| or -|subsubsection| or any name previously declared to \etoc with -\csb{etocsetlevel} (the keywords |all| and |none| are recognized, although not -corresponding to a document division). -This does the appropriate |\setcounter{tocdepth}{numeric_level}|. +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. -As is explained in the next subsection, |tocdepth| is used by \ctanpkg{hyperref}, and -one must take steps to prevent its changes from influencing the bookmarks, too. -So, \etoc has \csb {etocsetnexttocdepth}\marg{level} whose influence ceases -immediately after the next table of contents. The package defines -\csb{invisibletableofcontents} -essentially as -\centeredline{\csb{etocsetnexttocdepth}|{none}|\csb{tableofcontents}} +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}. -The simplest organization is probably to have after |\begin{document}| and before the - first |\tableofcontents| a single instance of the \csb{etocsettocdepth} - command, with argument the deepest level (or most commonly used deepest level) - among the tables of contents of the document, and to use locally, - where needed, \csb{etocsetnexttocdepth} before |\tableofcontents| or - |\localtableofcontents|. +\subsection{The \csbhyp{etocmulticolstyle}, \csbhyp{etocmulticol}, + and \csbhyp{etoclocalmulticol} commands} +\label{etocmulticolstyle} +\label{etocmulticol} +\label{etoclocalmulticol} -\begin{framed} - It is possible to use \csb{etocsettocdepth} inside the first argument of - \csb{etocsettocstyle} (possibly in conjunction with checking the - \csb{etoclocaltop} value, \emph{which however will be up-to-date there only if - \csb{etocchecksemptiness} was executed}). There is no worry then about - possible impact on hyperref bookmarks later on, because \etoc always resets - the |tocdepth| counter after typesetting a TOC to the value it had before - it. +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. - Since |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. +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. - Check \csb{localtableofcontentswithrelativedepth} for a simpler way to - control the depth of local tables of contents. This has the advantage of - working reliably whether or not the \csb{etocchecksemptiness} is used. -\end{framed} +And there is also +\csb{etocmulticol}\oarg{number\_of\_columns}\marg{heading} for global TOC. -\subsection{The hyperref option \emph{bookmarksdepth}} -\label{ssec:bookmarksdepth} +\subsection{The \csbhyp{etoctocstyle} command} +\label{etoctocstyle} -When modifying the counter |tocdepth| for the purposes of -multiple uses of \toc or \localtoc, one should be aware that -package \ctanpkg{hyperref} by default takes into account the -\emph{current} value of the |tocdepth| counter to decide -whether the |pdf| file will contain a bookmark corresponding -to sectioning commands encountered in the source file. Thus, -one typically needs to reset |tocdepth| to its previous -value after having temporarily modified it for a given table of -contents. +\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. -Or, there is the \emph{bookmarksdepth=n} option of package -\ctanpkg{hyperref}, with \emph{n} the desired document bookmarks -maximal depth, which can be numeric or the name of a level known to -\ctanpkg{hyperref}. This documentation previously passed |bookmarksdepth=3| as -option to \ctanpkg{hyperref}, so even if |tocdepth| was left to |1| -by inadvertance after printing a certain table of contents -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. +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. -\section[The command \csbhyp{etocsettocdepth.toc}]{The command - \csbhyp{etocsettocdepth.toc} and - \csbhyp{etocimmediatesettocdepth.toc}} -\label{etocsettocdepth.toc} -\label{etocimmediatesettocdepth.toc} +\subsubsection{The \csbhyp{etoctocstylewithmarks} command} +\label{etoctocstylewithmarks} +\label{etoctocstylewithmarksnouc} -This command \csb{etocsettocdepth.toc} implements some functionality of -\ctanpkg{tocvsec2}% +\centeredline{\csb{etoctocstylewithmarks}\oarg{kind}% + \marg{number\_of\_columns}\marg{title}\marg{mark}% + } % -\footnote{I thank Denis \textsc{Bitouzé} for drawing - my attention to the incompatibility of this package with \etoc.}, +is the exact equivalent of doing % -a package -which however was incompatible with \etoc (it can still be used for its -|secnumdepth|-related commands, but its |toc|-related activities will get -canceled by \etoc) and more-or-less designed for a single table of contents. +\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. -The action of \csb{etocsettocdepth.toc} is totally different than the one of -\csb{etocsettocdepth}. Rather than modifying the |tocdepth| counter immediately, -it adds a line to the |.toc| file which, when executed inside a table of -contents will enact this change. +\paragraph{Do we really want paragraph entries in the TOC?} -The command \csb{etocsettocdepth.toc}, like -\csb{etocsettocdepth}, accepts both numeric and named -arguments. In the case of a named argument, the actual numeric -value to be used is not yet decided at the time the |.toc| -file is created; it will be the value currently specified for -the named level at the time each table of contents (not having -done |\etocignoretoctocdepth|) is typeset. +\paragraph{really?} -The |tocdepth| counter will never be set to a value finer than its initial value -at the start of the table of contents: so adding commands -\csb{etocsettocdepth.toc} in the document is a way to \emph{restrict} locally -the depth of the table of contents. For example to prevent inclusion in the -tables of contents of the sub-sub-sections of a given chapter. +\subsection{The \csbhyp{etocruledstyle}, \csbhyp{etocruled} and + \csbhyp{etoclocalruled} commands} +\label{etocruledstyle} +\label{etocruled} +\label{etoclocalruled} -This -{\fbox{gets executed in ALL tables of contents.}} +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} -Also \csb{etocimmediatesettocdepth.toc} is provided. For explanations, -refer to the discussion of \csb{etocimmediatedepthtag.toc} in the -next section. +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 commands \csbhyp{etocobeytoctocdepth} and \csbhyp{etocignoretoctocdepth}} -\label{etocobeytoctocdepth} -\label{etocignoretoctocdepth} +\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). -So \csb{etocignoretoctocdepth} is provided to cancel the -\csb{etocsettocdepth.toc} mechanism when -needed; and \csb{etocobeytoctocdepth} will -re-activate it. The package does initially \csb{etocobeytoctocdepth}. +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}). -\section[The commands \csbhyp{etocdepthtag.toc} and \csbhyp{etocsettagdepth}]{The commands - \csbhyp{etocdepthtag.toc}, \csbhyp{etocimmediatedepthtag.toc} and - \csbhyp{etocsettagdepth}} -\label{etocdepthtag.toc} -\label{etocimmediatedepthtag.toc} -\label{etocsettagdepth} +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}. -Release |1.07h| has a command \csb{etocdepthtag.toc} which -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 -then set via \csb{etocsetlevel} according to what was locally needed, -but it was too hacky and I am not sure if it was understandable). +\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} -It is used as \csb{etocdepthtag.toc}\marg{tag\_name}, where the -\meta{tag\_name} is anything, and this will put the tag in the |.toc| -file. When typesetting a TOC, one issues a series of commands -\csb{etocsettagdepth}\marg{tag\_name}\marg{level} where the -\meta{level} may be either numeric (from |-3| to |5|) or the name of a -division unit known to \etoc, or |none| or |all|. The effect of the tag -inside the |.toc| file will then be to set the |tocdepth| counter to -the desired value, in real time (this can not get finer than the -initial value of |tocdepth| at the start of the TOC). +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} -The added flexibility is thus that \csb{etocsetlevel} has not been used in a -kind of hacky way, that one may use named level depths, and the -keywords |none| and |all|. +\newcommand*\etoccolumnsep{2em} +\newcommand*\etocmulticolsep{0ex} +\newcommand*\etocmulticolpretolerance{-1} +\newcommand*\etocmulticoltolerance{200} +\newcommand*\etocdefaultnbcol{2} +\newcommand*\etocinnertopsep{2ex} +\newcommand*\etoctoprule{\hrule} +\newcommand*\etoctoprulecolorcmd{\relax} -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}. +% for the framed style only: +\newcommand*\etocinnerleftsep{2em} +\newcommand*\etocinnerrightsep{2em} +\newcommand*\etocinnerbottomsep{3.5ex} -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 -this situation: -\begin{verbatim} - \clearpage % or anything ending up causing its presence here right before - % the \etocdepthtag.toc - \etocdepthtag.toc{sometag} - \include{some file containing sections} +\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 tag will end up in the |.toc| file \emph{after} all section headings from -the included file. The cause is that \LaTeX\ inserts immediately in the -main auxiliary file a command to input the auxiliary file of the included file -(which in turn, contains instructions to add data to the |.toc| file). But -\csb{etocdepthtag.toc} does not internally use such immediateness, as it uses -the same interface as |\section| and alike commands when they want to write -extra data to the |.toc| file. -So% -% -\footnote{Thanks to Norman \textsc{Ramsey} who reported this problem, together - 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 -immediately to the |.toc| file (well, rather immediately to the |.aux| file, -so before the inclusion of the auxiliary file of the included file). +The \csa{etocframedmphook} is positioned immediately +after the beginning of a minipage environment where the +contents of the framed TOC are typeset. -One should not use this variant systematically. For example if your document -looks like: -\begin{verbatim} -\clearpage +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}. -\section{bbbb} +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. -Some text +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. -\etocdepthtag.toc{sometag} -\etocimmediatedepthtag.toc{someimmediatetag} -\section{cccc} -Some text +\subsection{Headings, titles, \csbhyp{etocoldpar}, \csbhyp{etocinnertopsep}} +\label{etocinnertopsep} +\label{etocoldpar} -\end{document} -\end{verbatim} -then the |someimmediatetag| will end up being inserted in |.toc| file -\emph{before} the |bbbb| section. This is because \LaTeX's |\section| -uses a \emph{delayed} write, not an \emph{immediate} one. And -\csb{etocdepthtag.toc} wisely uses a \emph{delayed} write. +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}|. -As it seems very hard programmatically to identify automatically if the -\emph{immediate} variant of \csb{etocdepthtag.toc} should be used, the package -provides two separate commands and it is up to user to make the correct -choice. +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}. -\subsection{The commands \csbhyp{etocobeydepthtags} and \csbhyp{etocignoredepthtags}} -\label{etocobeydepthtags} -\label{etocignoredepthtags} +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|. -After \csb{etocignoredepthtags}, the |.toc| depth tags are ignored (but -\csb{etocdepthtag.toc} still works). The package does initially -\csb{etocobeydepthtags} which makes \etoc react to the found tags in the -|.toc| file. +\section{Starred variants and hooks} +\label{tableofcontents*} +\label{localtableofcontents*} +\label{etocbeforetitlehook} +\label{etocaftertitlehook} +\label{etocaftercontentshook} +\label{etocaftertochook} -\section{The commands \csbhyp{etocglobaldefs} and \csbhyp{etoclocaldefs}} -\label{etocglobaldefs} -\label{etoclocaldefs} +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. -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|. +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. -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}). +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). -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. +% 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}. -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. +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. -\section{Not displayed empty TOCs} +\begin{framed} + In recent years, the \LaTeX{} kernel has added a general ``hook'' mechanism + with a user interface of the type |\AddToHook{...}{...}|. -\subsection{The \csbhyp{etocchecksemptiness} command} -\label{etocchecksemptiness} -\label{etocdoesnotcheckemptiness} + 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. -The user needs to issue \csb{etocchecksemptiness} to tell \etoc to check whether -local tables of contents are empty and in case of emptiness to print nothing -at all.\footnote{Thanks to Paul Gaborit who asked for -such a feature.} This -can be useful to authors of \LaTeX{} classes who for example wish to have a -|\chapter| command doing systematically a \localtoc, or for -people producing files via automatic conversions and some of those might have -sectioning commands and others not. - -«Emptiness» means that no \csa{contentsline} command would get executed within -the scope of the local table of contents --- empty line styles by themselves do -not make the TOC empty. \etoc always executes the \csb{etocaftertochook} -command; and the test for emptiness itself executes everything else found in -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|.) -\end{enumerate} - -The suppression of the heading (more precisely of the toc display style -elements) may be effective only for the final \LaTeX{} runs. For example in -the situation of a \toc|\ref{foo}| where the label |foo| is -not yet recognized, the heading (but not the contents) is printed and the TOC -is declared non-empty. Or, if one adds a \localtoc to a document, on the next -run, the test for emptiness will in fact apply to the next one, and the last -local TOC of the document will have its contents temporarily unknown to \etoc, -hence will be declared non empty, and the heading will be printed. - -For a finalized document compiled with initially no auxiliary files, the first -\LaTeX{} run will declare all local TOCs non empty and print for each of them a -heading (and no contents naturally). The second \LaTeX{} run will then -correctly decide which local TOC is empty or not. + 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} -\subsection{The \csbhyp{etocnotocifnotoc} command} -\label{etocnotocifnotoc} +\section{The \csbhyp{etocsetstyle} and related commands} +\label{sec:linestyles} +\label{etocsetstyle} +\label{etocname} +\label{etocpage} -The user can then extend the emptiness-checking to the global TOCs with -\csb{etocnotocifnotoc}. May I respectfully give the advice then to rather do -none of |\usepackage{etoc}| nor \toc ? |;-)|. Well, there is always the case -of batch conversions of documents having or not sectioning units. +\begingroup +\etocsettocstyle{}{} +\DeclareTOCStyleEntry[numwidth=3.2em,indent=0em]{tocline}{subsection} +\etocstandardlines +\localtableofcontents \label{toc:linestyles} +\endgroup -\subsection{The \csbhyp{etocifwasempty} command} -\label{etocifwasempty} -\label{etocxifwasempty} +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 command \csb{etocifwasempty}\marg{YES}\marg{NO} executes \meta{YES} if -the previous TOC was found to be empty and \meta{NO} if its was not so. This -may serve to act appropriately after a truly empty TOC. If -\csb{etocchecksemptiness} has not been issued, this conditional always -executes the \meta{NO} branch. -This command is robust, and \csb{etocxifwasempty} is its expandable -version. +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.} -\fbox{Do not forget the second argument: at least an empty pair of braces |{}| - must be present.} +\begingroup\small +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +\etocsetstyle{section} +{\begin{enumerate}} +{\normalsize\bfseries\rmfamily\item} +{\etocname{} (page \etocpage)} +{\end{enumerate}} -This conditional may wrongly say that the local TOC is empty or not empty -until \LaTeX{} compilations stabilize. But if it says that a local TOC is -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|). +\etocsetstyle{subsection} +{\begin{enumerate}} +{\normalfont\item} +{\etocname{} (p.~\etocpage)} +{\end{enumerate}} -\section{Adding commands to the \texorpdfstring{\texttt{.toc}}{.toc} file} -\label{sec:addingtotoc} +\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 -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}|. +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. -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: +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} -\let\myclearpage\clearpage -\tableofcontents -\let\myclearpage\relax +\etocsetstyle{paragraph}{}{}{}{} +\etocsetstyle{subparagraph}{}{}{}{} \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. +This is also the situation with the default package line styles! -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. +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}. -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}. +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. -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. +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 hyperref option \emph{hidelinks}}\label{ssec:hidelinks} +\subsection{The \csbhyp{etocskipfirstprefix} and \csbhyp{etociffirst} commands} +\label{etocskipfirstprefix} +\label{etociffirst} +\label{etocxiffirst} -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}? +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. -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} +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). - 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). +The variant \csb{etocxiffirst} does the same, but is expandable. -\clearpage -\etocdepthtag.toc {examples} -\part{Examples}\label{part:examples} +\subsection{The \csbhyp{etocnumber} command} +\label{etocnumber} -\thispartstats %% (pas de sous-section) +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|. -\etocstandardlines -\etocsettocstyle {}{\medskip} -\localtableofcontents -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}. +\subsection{The \csbhyp{etocifnumbered} switch} +\label{etocifnumbered} +\label{etocxifnumbered} -\section{Testing the compatibility mode} +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}.} -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 -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}. +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} -\begingroup % to keep in particular toc=left with local effect -\KOMAoptions{toc=left} -\etocstandarddisplaystyle % necessary for the display to obey toc=left -\etocstandardlines -\tableofcontents \ref{toc:globalcmds} -\endgroup -\end{verbatim} -\begingroup -\KOMAoptions{toc=left} -\etocstandarddisplaystyle -\etocstandardlines -\tableofcontents \ref{toc:globalcmds} -\endgroup +\etocsetstyle{section} +{\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered + {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]} +{\normalsize\bfseries\rmfamily\item} +{\etocname{} (page \etocpage)} +{\end{enumerate}} -\section{Another compatibility mode}\label{sec:anothercompat} +\etocsetstyle{subsection} +{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]} +{\normalfont \item} +{\etocname{} (p.~\etocpage)} +{\end{enumerate}} +\end{verbatim} -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. +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}|. -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: -\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, -\item use the document class style for chapters and sections, but modify it only - for subsections, -\item do either of the above only for some portions of the table of contents. -\end{enumerate} +The command \csb{etocifnumbered} is robust; \csb{etocxifnumbered} +has the same effect but is expandable. -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|. +\subsection{The \csbhyp{etocthename}, \csbhyp{etocthenumber}, and +\csbhyp{etocthepage} commands} +\label{etocthename} +\label{etocthenumber} +\label{etocthepage} -You should use directly |\l@chapter|, etc... within suitable -|\makeatletter/\makeatother|. Here is an example. +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}. -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\makeatletter -\newcommand{\MyStandardTOC}{% - \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 - \endgroup} -\makeatother -\end{filecontentshere} -\marginattach{-A} +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. -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} -\makeatletter -\newcommand*{\MyQuasiStandardTOC}[1]{% - \begingroup - \etocsetstyle{section} - {} - {\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} +\subsection{The \csbhyp{etoclink} command} +\label{etoclink} -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). +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. -\section{Emulating the book class}\label{sec:thirdexample} +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}|. -As explained in \autoref{subs:compat}: without explicit use of an -\csb{etocsetstyle} command the package will leave to the document class the -hand regarding the ``toc line styles''. It is sometimes asked by users (for -example those using \etoc for its \csb{localtableofcontents}) how to stay -close to but not completely identical with the design implemented by the -standard classes, such as |book|. I can recommend package \ctanpkg{tocloft} for this, -as it is compatible with \etoc (see \autoref{subs:tocloft}) and thus \etoc will -obey the \ctanpkg{tocloft} customizations (as long as no use has been made of -\csb{etocsetstyle}). It is also possible to modify only the style for, say, -sections and leave the parts, chapters, subsections as in the document class, -via the technique from \autoref{sec:anothercompat}. +The command \csb{etoclink} is robust. -But for complete control, here is a translation of the |book| class code into -\etoc lingua. It is then easy to modify the relevant lengths or adjust the -used fonts. I thank \textsc{Denis Bitouzé} for prompting me to include this in -the \etoc manual, as it resulted from some conversation we had about this. The -code is not 100\% faithful to the |book| class, and particularly its rendering -of (multi-line) non-numbered units differs (... I think, as I copied pasted as -is the code from where I had stored it and did not do much thinking about it -again). Some proficiency in low-level \TeX\ and \LaTeX\ macros is needed to -understand what the code says, but for modifying fonts or some lengths such -in-depth understanding is not needed. +% 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. -With some extra code one can \emph{automatically adjust the widths} assigned -to typesetting sectioning numbers in order to prevent overflows, even with for -example \MakeUppercase{\romannumeral 38}; but this is a more advanced feature -which I have moved to \autoref{sec:thirdexampleextra}. -First we set up some lengths. I use macro registers, not real \LaTeX\ lengths. -When using |em|'s however, this means that one must pay attention to when the -actual dimension assignment is made, as this will then depend upon the current -font settings. In the code below, at the location where the \csa{TOCnumwidthB} -and \csa{TOCnumwidthC} will be used, the |1em| from their specification will -be matched to the normal medium series font, not the bold font; this is -deliberate so that one can compare more readily with the other dimensions; -besides, with the \csa{TOCcomputenumwidths} from -\autoref{sec:thirdexampleextra} these macros will actually hold a dimension -using |pt| as dimensional unit. -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -% it will be easy to globally shift the TOC horizontally if needed -\def\TOCleftmargin {0pt} -\def\TOCrightmargin {2.55em}% like LaTeX's \@tocrmarg -% this is for dotted leaders -\newbox\TOCleaderbox -\def\TOCleaderboxwidth {0.7777em}% about like what standard classes do +\makeatletter\scr@activate@xsection{1}\makeatother +% [] goes to head but {} to toc -% vertical spacing -\def\TOCverysmallvskip {0pt plus .2pt} -\def\TOCmedvskip {1em plus 1pt} -\def\TOCbigvskip {2.25em plus 1pt} +% 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} -% the ``numwidths'' for typesetting the numbering of division units. -% I don't recall exactly how (and for which fonts) these figures were chosen. -% They quickly prove too small if using Roman numerals (as do too the book -% class defaults even though they are a bit larger). -\def\TOCnumwidthB {1.5em} % chapter -\def\TOCnumwidthC {2.278em}% section, I think default is 2.3em -\def\TOCnumwidthD {3.056em}% analog in standard class is 3.2em -\def\TOCnumwidthE {3.833em}% analog in standard class is 4.1em -\def\TOCnumwidthF {4.611em}% analog in standard class is 5em -\def\TOCnumwidthG {5.389em}% analog in standard class is 6em +\makeatletter\scr@activate@xsection{0}\makeatother -% The code for the ``global toc style''. +The meanings of these commands +can be stored for delayed usage. For example this is +done in the \hyperref[tocastree]{examples with trees}. -\newcommand*\TOCglobalstyle {% -\etocsettocstyle - {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi - \parindent\z@ \leftskip\z@skip \rightskip \z@skip - \setbox\TOCleaderbox\hbox to \TOCleaderboxwidth{\hss.\hss}% - \chapter *{\noindent\kern\TOCleftmargin\relax % uses "pt"... - \contentsname - \@mkboth {\MakeUppercase \contentsname}{\MakeUppercase \contentsname}}% - \rightskip \TOCrightmargin\relax - \parfillskip -\rightskip % or a smaller value if desired - \leftskip \TOCleftmargin \relax } - {\if@restonecol \twocolumn \fi\cleardoublepage}% +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.% % -\etocsetstyle{part} - {} - {\addpenalty {-\@highpenalty}% - \addvspace \TOCbigvskip - \leavevmode - {\large \bfseries % use a group to limit font change - \interlinepenalty\@M - \etocifnumbered{\etocnumber\hspace{1em}}{}% - \etocname - \nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}}\par - \nobreak - } - {} - {}% +\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.} % -\etocsetstyle{chapter} - {\advance\leftskip\TOCnumwidthB\relax} - {\addpenalty {-\@highpenalty }% - \vskip \TOCmedvskip\relax - \leavevmode - {\interlinepenalty\@M - \etocifnumbered - {\llap{\makebox[\TOCnumwidthB][l]{\bfseries\etocnumber}}} - {\advance\leftskip-\TOCnumwidthB\relax}% - \bfseries\etocname - \nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}\par }% - \penalty \@highpenalty - } - {} - {\advance\leftskip-\TOCnumwidthB\relax}% +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% % - \TOCsetlinestyle {section} {\TOCnumwidthC}% - \TOCsetlinestyle {subsection} {\TOCnumwidthD}% - \TOCsetlinestyle {subsubsection}{\TOCnumwidthE}% - \TOCsetlinestyle {paragraph} {\TOCnumwidthF}% - \TOCsetlinestyle {subparagraph} {\TOCnumwidthG}% -}% end of \TOCglobalstyle +\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. -%The common code for line styles is abstracted into a macro: - -\newcommand\TOCsetlinestyle [2]{% #1= unit, #2= numwidth as macro -\etocsetstyle{#1} - {\advance\leftskip#2\relax} - {\vskip \TOCverysmallvskip\relax - \leavevmode - {\interlinepenalty\@M - \etocifnumbered - {\llap{\makebox[#2][l]{\etocnumber}}}{\advance\leftskip-#2\relax}% - \etocname - \nobreak\leaders \copy\TOCleaderbox - \hfil\makebox[-\parfillskip][r]{\etocpage}% - \par }% - } - {} - {\advance\leftskip-#2\relax}% -} -\makeatother -\end{filecontentshere} -\marginattach{-A} -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.) -The whole thing was encapsulated in \csa{TOCglobalstyle}, because we also want -a \csa{TOClocalstyle} for local tables of contents which typically will want -to use |\section*| rather than |\chapter*| and not insert page marks in the -headers. The \csa{TOClocalstyle} is to be issued once, after the main document -TOC, or rather before using \localtoc. If one wants a full -TOC at end of document one will naturally have to issue again -\csa{TOCglobalstyle} there. -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\makeatletter -\newcommand*\TOClocalstyle {% -\etocsettocstyle - {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi - \setbox\TOCleaderbox\hbox to \TOCleaderboxwidth{\hss.\hss}% - \parindent\z@ - \dimen@ 2.25em % for left indenting - \section *{\kern\dimen@ % use of \dimen@ works here by sheer luck - \contentsname - % un-comment this if marks are wanted: - %\@mkboth {\MakeUppercase \contentsname}{\MakeUppercase \contentsname}% - }% end of \section - \parskip \z@skip - \vspace{-1.25\baselineskip}% somewhat ad hoc - \leftskip 2.25em - \rightskip 4.5em - \advance\rightskip-\TOCrightmargin\relax - \leavevmode\leaders\hrule\@height\p@\hfill\kern\z@\par - \rightskip 4.5em - \parfillskip -\TOCrightmargin\relax } - {\nobreak\vskip-.5\baselineskip - \leavevmode\leaders\hrule\@height\p@\hfill\kern\z@\par - \bigskip - \if@restonecol \twocolumn \fi }% -% -\etocsetstyle{section} - {\advance\leftskip\TOCnumwidthC\relax} - {\addpenalty \@secpenalty - \etociffirst{}{\addvspace{\TOCmedvskip}}% - \leavevmode - {\interlinepenalty\@M - \bfseries\etocifnumbered - {\llap{\makebox[\TOCnumwidthC][l]{\etocnumber}}} - {\advance\leftskip-\TOCnumwidthC}% - \etocname\nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}\par }% - \penalty \@highpenalty } - {} - {\advance\leftskip-\TOCnumwidthC\relax}% -% the rest is identical with code for global tocs: - \TOCsetlinestyle {subsection} {\TOCnumwidthD}% - \TOCsetlinestyle {subsubsection}{\TOCnumwidthE}% - \TOCsetlinestyle {paragraph} {\TOCnumwidthF}% - \TOCsetlinestyle {subparagraph} {\TOCnumwidthG}% -}% end of \TOClocalstyle -\makeatother -\end{filecontentshere} -\marginattach{-B} -As mentioned previously, this handles non-numbered (multi-line) sectioning -units somewhat differently from what happens in the standard document classes. +\subsection{The \csbhyp{etocsetlevel} command} +\label{etocsetlevel} -For some reason this code has some hard-coded |2.25em| and |4.5em| which were -not abstracted into macros or lengths. The code inserts horizontal rules above -and below the TOC contents in a non-separable by pagebreak way. +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. -See \autoref{sec:thirdexampleextra} for more. +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}. -\section{A framed display} +These level assignments can be modified at anytime. See +\autoref{part:surprising} for various applications of this technique. -We now opt for a ``framed'' style, using the package default -line styles and some colors added (it has been put in a float which appears -\vpageref{toc:b}). -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\etocdefaultlines -\begingroup -\renewcommand{\etoccolumnsep}{2em} -\renewcommand{\etocinnerleftsep}{1.5em} -\renewcommand{\etocinnerrightsep}{1.5em} -% specify a background color for the toc contents -\renewcommand{\etocbkgcolorcmd}{\color{yellow!10}} -% set up the top and bottom rules -\renewcommand{\etoctoprule}{\hrule height 1pt} -\renewcommand{\etoctoprulecolorcmd}{\color{red!25}} -\renewcommand{\etocbottomrule}{\hrule height 1pt} -\renewcommand{\etocbottomrulecolorcmd}{\color{red!25}} -% set up the left and right rules -\renewcommand{\etocleftrule}{\vrule width 5pt} -\renewcommand{\etocrightrule}{\vrule width 5pt} -\renewcommand{\etocleftrulecolorcmd}{\color{red!25}} -\renewcommand{\etocrightrulecolorcmd}{\color{red!25}} -% use \fcolorbox to set up a colored frame for the title -\fboxrule1pt -\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 - one page. It has the label |toc:b|.}}} -\begin{figure}[ht!] - \centering -\tableofcontents \label{toc:b} \ref{toc:globalcmds} -\end{figure} -\endgroup -\end{filecontentshere} -\marginattach{-A} +\subsection{Using \texttt{enumerate} or \texttt{itemize} environments for + line styles} -\filecontentsexec\filecontentsheremacro +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}). -\section{Another TOC with a background color}\label{ssec:again} +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. -Let us now try out some more sophisticated line styles. The display will use -the \csb{etocframedstyle} package command, which requires that the produced -table of contents fits on a single page. We wrap it up in a -\hyperref[toc:floating]{figure environment} showing up -\vpageref{toc:floating}. +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. -This design uses the \etoc `framed' style with a background color. The frame -borders have been set to have the same color as the one serving as background -for the entire thing. It would be advantageous to use rather inside -\csb{etocsettocstyle} commands from a package like |tcolorbox| as this allows -sophisticated breakable boxes (with |TikZ/pgf| for decoration.) +\section{The \etoc fall-back line styles} +\label{sec:custom} -The details of the line styles used here are a bit involved, they were written -by the author at some early stage of this documentation and have only been -slightly revised to use more \LaTeX-commands and less \TeX-primitives. Similar -code is used also for \hyperref[toc:clone]{this other toc}. +\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|}}} -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\begin{figure}[htbp!]\centering -\colorlet{subsecnum}{black} -\colorlet{secbackground}{green!30} -\colorlet{tocbackground}{red!20!green!20} +\localtableofcontents \label{toc:c} -\renewcommand{\etocbkgcolorcmd}{\color{tocbackground}} -\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}} -\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}} -\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}} -\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}} +\subsection{A demo of a TOC using \csbhyp{etocdefaultlines}} +\label{etocdefaultlines} -\renewcommand{\etocleftrule}{\vrule width 3cm} -\renewcommand{\etocrightrule}{\vrule width 1cm} -\renewcommand{\etocbottomrule}{\hrule height 12pt} -\renewcommand{\etoctoprule}{\hrule height 12pt} +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. -\renewcommand{\etocinnertopsep}{0pt} -\renewcommand{\etocinnerbottomsep}{0pt} -\renewcommand{\etocinnerleftsep}{0pt} -\renewcommand{\etocinnerrightsep}{0pt} +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. -\newcommand\shiftedwhiterule[2]{% - \hbox to \linewidth{\color{white}% - \hskip#1\leaders\vrule height1pt\hfil}\nointerlineskip - \vskip#2} +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. -\etocsetstyle{subsubsection} -{\etocskipfirstprefix} -{\shiftedwhiterule{\leftskip}{6pt}} -{\sffamily\footnotesize - \leftskip2.3cm\hangindent1cm\rightskip.5cm\relax - \makebox[1cm][l]{\color{subsecnum}\etocnumber}% - \color{black}\etocname - \nobreak\leaders\hbox to.2cm{\hss.}\hfill - \rlap{\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}\par - \nointerlineskip\vskip3pt} -{} -\etocsetstyle{subsection} -{\etocskipfirstprefix} -{\shiftedwhiterule{1.5cm}{6pt}} -{\sffamily\small - \leftskip1.5cm\hangindent.8cm\rightskip.5cm\relax - \makebox[.75cm][l]{\color{subsecnum}\etocnumber}% - \color{black}\etocname - \nobreak\leaders\hbox to.2cm{\hss.}\hfill - \rlap{\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}\par - \nointerlineskip\vskip3pt} -{} - -\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{blue}{\hfil \bfseries\large Contents of Part One\hfil}} -{\vskip3pt\sffamily\small} -{\coloredstuff{blue} - {\leftskip1.5cm\rightskip.5cm\parfillskip-\rightskip - \makebox[0pt][r]{\makebox[.5cm][l]{\etocnumber}}% - \etocname\nobreak\hfill\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}% - \vskip6pt} -{} - -\etocframedstyle[1]{} -\tableofcontents \label{toc:floating} \ref{toc:overview} -\vspace{-\baselineskip} -\centeredline{|\tableofcontents \ref{toc:overview}| -(\emph{cf.} \hyperref[toc:clone]{this other toc})} -\end{figure} -\end{filecontentshere} -\marginattach{} +\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{A (crazy) inline display} +\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} -Let us finally make 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). -%%%% Note: 27 april 2014 +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} -%%%% except for a miraculous situation depending from the quantity of previous -%%%% material this TOC will have links extending accross pagebreaks, which -%%%% dvipdfmx does not know how to handle completely. Apart from that the output -%%%% is ok, thus no need to try seriously to avoid them. +\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} -\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} -\begingroup -\newsavebox{\forsubsections} -\etocsetstyle{part}{\upshape. \etocskipfirstprefix} - {. \upshape} - {\bfseries\etocname:~~} - {} -\etocsetstyle{section}{\itshape\etocskipfirstprefix} - {, } - {\mdseries\etocname} - {} -\etocsetstyle{subsection} - {\begin{lrbox}{\forsubsections}\footnotesize\upshape\etocskipfirstprefix} - {; } - {\etocname} - {.\end{lrbox}\footnote{\unhbox\forsubsections}} -\etocsetstyle{subsubsection} - { (\itshape\etocskipfirstprefix} - {, } - {\etocname} - {\/\upshape)} -\etocsettocstyle{Here is the inline table of contents. }{.\par} -\tableofcontents \label{toc:crazyinline} -\endgroup -\end{filecontentsdef} +\newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil} +\newcommand*\etocminustworightmargin{1.5em plus -0.5fil} +\newcommand*\etocminusoneleftmargin{1em} +\newcommand*\etocminusonerightmargin{1em} -\filecontentsexec\foo +\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} -The code used: -\filecontentsprint\foo -\marginattach{} +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.} -\clearpage -\etocdepthtag.toc {surprising} -\part{Surprising uses of \etoc} -\label{part:surprising} +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} . . .). -\thispartstats %% (pas de sous-section) +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. -\etocstandardlines -\etocsettocstyle {}{} -\localtableofcontents +\section{Summary of the main styling commands} -\section{The TOC of TOCs} +\subsection{Setting up local styles} -\begingroup % \endgroup just after the \tableofcontents command -\etocinline -\etocsetlevel{part}{1} -\etocsetlevel{visibletoc}{0} -\etocsetstyle{visibletoc} - {\etocskipfirstprefix} - {, } - {{\color{niceone}\etocname}} - {} -\etocsettocstyle{}{} -\etocsetnexttocdepth{visibletoc} +\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} -Here is the numbered and linked list of all tables of contents which are -displayed within this document:\footnote{The TOCs put in - floats may change the order: the numbers are listed - 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 -it here we just wrote:\par\smallskip -{\leftskip1cm\rightskip2cm - \ttfamily\small\baselineskip11pt \noindent Here is the - numbered and linked list of all tables of contents which are - displayed within this - document:~\string\tableofcontents.\par} +\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}}}} - The preparatory work was the following. First, we defined a - counter |visibletoc| whose vocation is to get incremented at - each displayed toc. \etoc has its own private counter but it - counts all TOCs, even those not displayed because the |tocdepth| - value was |-2| or |-3|. +\subsection{Displaying tables of contents} - We could have added manually |\refstepcounter{visibletoc}| - and |\label| commands at all suitable locations in the - document source, and we would then have used here |\ref| - commands, but this imposes heavy manual editing of the source. - There is a much better way: there is a hook - \csb{etocaftertitlehook} and we told it to increment the - |visibletoc| counter and to write a line to the |.toc| file, - in a manner analogous to what sectioning commands such as - |chapter|, |section|, or |subsection| do. As \etoc - increments its own private counter even before typesetting - the title of a table of contents, this provides (most of the - time) a better link destination than any counter manipulated - from inside \csb{etocaftertitlehook} (for which the link - would target the area just after the title). So, rather than - including |\refstepcounter{visibletoc}| inside - \csb{etocaftertitlehook}, we just put there - |\stepcounter{visibletoc}| followed by the command - \csb{etoctoccontentsline}|{visibletoc}{\thevisibletoc}|. This \etoc - command \csb{etoctoccontentsline}\marg{level\_name}\marg{name} has the same - effect as: - \centeredline{| ||\addcontentsline{toc}|\marg{level\_name}\marg{name}} - but its usefulness is to circumvent\footnote{using \csa{addtocontents} rather - than \csa{addcontentsline}} the patching for automatic creation - of bookmarks done to \csa{addcontentsline} by the \ctanpkg{hyperref} package, - as pdf bookmarks don't make - much sense here (and would elicit a complaint - of \ctanpkg{hyperref} that the bookmark level is `unknown').\footnote{% - The package provides a starred variant - \staritb{etoctoccontentsline}, which does allow the creation - of bookmarks and has a third mandatory argument which is the - Level to be used by these bookmarks; depending on the context - the starred as well as the non-starred variants may be - profitably preceded by \csa{phantomsection}.} +\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} + }}} - Finally, the preamble of the document did - |\etocsetlevel{visibletoc}{6}|. The level |6| (or anything - with a higher number) is ignored, even if |tocdepth| has - value |10| for example; this is independently of whether \etoc - uses the document class default line styles or its own line - styles, or the ones defined by the user with the - \csb{etocsetstyle} command. So there is no need to worry that - something could go wrong. +\subsection{Labels and references} +\label{ssec:labelref} - 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 - 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. - -Here are the implementation details: +The commands (starred or not) to actually display the table of contents +can be followed with optional labels or references:\par -\begingroup -\begin{filecontentshere}{etocsnippet-\snippetno.tex} - < in the preamble > -\newcounter{visibletoc} -\renewcommand{\etocaftertitlehook} - {\stepcounter{visibletoc}\etoctoccontentsline{visibletoc}{\thevisibletoc}} -\etocsetlevel{visibletoc}{6} -\begin{document} - < document body > -\subsection{Surprising uses of etoc} -\begingroup - \etocinline - \etocsetlevel{part}{1} - % \etocsetlevel{chapter}{1} % (no chapters in scrartcl class) - \etocsetlevel{visibletoc}{0} - \etocsetstyle{visibletoc} - {\etocskipfirstprefix}{, }{{\color{niceone}\etocname}}{} - \etocsettocstyle{}{} % don't set any title, rules or frame or multicol! - \etocsetnexttocdepth{visibletoc} % display only the `visibletoc' entries from .toc +\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 . . . } + }}} -Here is the numbered and linked list of all tables of contents which are -displayed within this document: \tableofcontents. -\endgroup -\end{filecontentshere} -\marginattach{} -\endgroup -After |\etocsetstyle{visibletoc}{..}{..}{..}{..}|, all future TOCs (not in -compatibility mode) will use the -defined style for level |0| (which is normally the level for -chapters). To keep these changes strictly local the simplest -manner is to put everything inside a group. +\medskip -The \autoref{subsec:interverting} gives another use of the -shuffling of levels. +\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. -\section[Arbitrary ``Lists Of...'', \csbhyp{etoctoccontentsline}]{% - Arbitrary ``Lists Of...'', \csbhyp{etoctoccontentsline} and - \csbhyp{etocimmediatetoccontentsline}} -\label{etoctoccontentsline} -\label{etocimmediatetoccontentsline} +\clearpage +\etocdepthtag.toc {control} +\part{Control of contents} +\label{part:control} -This idea of interverting the levels is very powerful and allows -to let \etoc display lists of arbitrary things contained in the -document. All of that still -using nothing else than the |.toc| file! -Example: imagine a document with dozens of -exercises, perhaps defined as |\newtheorem{exercise}{}[section]|. Let -us explain how to instruct \etoc to display an hyperlinked list -of all these exercises. For this we put in the preamble: -\begin{verbatim} - \newtheorem{exerci}{}[section] - % the exercice number will be recoverable via \etocname: v--here--v - \newcommand*{\exercisetotoc}{\etoctoccontentsline{exercise}{\theexerci}} - \newenvironment{exercise}{\begin{exerci}\exercisetotoc}{\end{exerci}} - \etocsetlevel{exercise}{6} -\end{verbatim} -In this way, \csb{etocname} will give the exercise number (but \csb{etocnumber} -will be empty). Had we used instead -\begin{verbatim} - \newcommand*{\exercisetotoc} - {\etoctoccontentsline{exercise}{\protect\numberline{\theexerci}}} -\end{verbatim} -the exercise number would then have been available via \csb{etocnumber}, and -\csb{etocname} would have been empty. It doesn't matter which one of the two -methods is used. The \etoc command \csb{etoctoccontentsline}|{..}{..}| is -provided as a substitute to \csa{addcon\-tentsline}|{toc}{..}{..}|: this is to -avoid the patching which is done by \ctanpkg{hyperref} to \csa{addcontentsline} in its -process of creation of bookmarks. If one wants to authorize \ctanpkg{hyperref} to create -bookmarks at a specific level \meta{n}, one can use (here with \meta{n}$=$|2|) -the starred variant \starit{etoctoccontentsline} which has an additional -argument: -\begin{verbatim} -\newcommand{\exercisetotoc}{\etoctoccontentsline*{exercise}{\theexerci}{2}} -\end{verbatim} +\thispartstats -The counter |exerci| is already -incremented by the |exerci| theorem environment, and -provides the correct destination for the link added by package -\ctanpkg{hyperref}. The command \csa{exercisetotoc} adds for each exercise a line -to the |.toc| file, corresponding to a fictitious document -unit with name `|exercise|'. A -four-column list, including the sections, can then be -typeset with the following code: -\begin{filecontentshere}{etocsnippet-\snippetno.tex} - \etocsetnexttocdepth{2} % sections are at level 1 and will show up +\etocsettocstyle{}{}% maybe I should use \etocclasstocstyle here ? + % but then I probably need some extra KOMA stuff to + % counteract the setspace effet \begingroup - \etocsetlevel{exercise}{2} % but: - \etocsetlevel{chapter}{3} % no chapters - \etocsetlevel{subsection}{3} % no subsections - \etocsetlevel{part}{3} % no parts - \etocsetstyle{exercise}{}{} % \etocname = exercise number - {\noindent\etocname\strut\leaders\etoctoclineleaders\hfill\etocpage\par} - {\pagebreak[2]\vskip\baselineskip} - \etocsetstyle{section}{}{} - {\noindent\strut{\bfseries\large\etocnumber\hskip.5em\etocname}\par - \nopagebreak[3]}{} - \etocruledstyle[4]{\Large\bfseries List of the exercises} - \setlength{\columnseprule}{.4pt} - \tableofcontents +\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{filecontentshere} -\marginattach{} - -A related command \csb{etocimmediatetoccontentsline} (and its starred version) -is also provided. For discussion and the meaning of ``immediate'', refer to -the analogous case of \csb{etocimmediatedepthtag.toc}. -\section{The TOC as a tree}\label{tocastree} +\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} -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? +\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. -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 -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.% + \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. % -\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.} - -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 -macro |\appendtotok| whose r\^ole is to append to a given token list variable -the contents of a macro given as second argument. All this will happen in -reaction to a |\tableofcontents| command, but \emph{nothing} has yet been -printed in the process.\footnote{There is always a \csa{par}, which here is not -a problem, but can be suppressed if need be via the command \csb{etocinline} or -its synonym \csb{etocnopar}.} This is the later job of a |forest| environment -which will be given the contents of |\treetok|. - +\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 +subsection, etc... (see also \csb{etocsetnexttocdepth}).% +% +\footnote{As is explained in \autoref{sec:labeling} the syntax allows to + create somewhere a local table of contents and to display it at some other + location either before or after its origin.}% +\textsuperscript{,}% +\footnote{As is explained in \autoref{sec:tocdepth} \etoc allows at anytime to + locally redefine the numeric levels associated to named ones, which brings + great flexibility to achieve special effects, all done using only a single + auxiliary file, the standard |.toc| file.} +% +\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 +\begin{verbatim} +\section{This is a section} +\localtableofcontentswithrelativedepth{+2} +\end{verbatim} + will create a local table of contents taking into account the subsections + and subsubsections inside this section, independently of what is the value + 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. +\end{description} -\let\appendtotok\relax +\section{Labeling and reusing elsewhere} +\label{sec:labeling} +\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} -% \newtoks\treetok % put this (uncommented) preferably in the preamble -% \newtoks\tmptok % (idem) - -\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2 - #1\expandafter\expandafter\expandafter - {\expandafter\the\expandafter #1#2}} - -\newcommand*\PrepareSectionNode{% - \tmptok {\centering\bfseries}% - \appendtotok\tmptok\etocthelinkedname - \edef\foresttreenode{ [{\noexpand\parbox{2cm}{\the\tmptok}}}% -} - -\newcommand*{\PrepareSubsectionNode}{% - \tmptok {\raggedright}% - \appendtotok\tmptok\etocthelinkedname - \edef\foresttreenode{ [{\noexpand\parbox{6cm}{\the\tmptok}}}% -} - -\etocsetstyle{section} - {\etocskipfirstprefix} - {\appendtotok\treetok{ ]}} - {\PrepareSectionNode \appendtotok\treetok\foresttreenode} - {\appendtotok\treetok{ ]}} - -\etocsetstyle{subsection} - {\etocskipfirstprefix} - {\appendtotok\treetok{ ]}} - {\PrepareSubsectionNode \appendtotok\treetok\foresttreenode} - {\appendtotok\treetok{ ]}} - -\etocsettocstyle - {\treetok{[{\hyperref[part:overview]{Overview}}}} - {\global\appendtotok\treetok{ ]}} - -% forest does not like @\the\treetok if \treetok is empty. On first latex -% run, this will be the case because the TOC style defined above will not -% have been executed, as the label {toc:overview} does not refer to a valid -% TOC yet. So we must give a safe default value to \treetok -\treetok{[{run latex again}]} - -\begin{figure}[th!]\centering - \etocsetnexttocdepth{subsection} - \tableofcontents \label{toc:forest}\ref{toc:overview} - \hypersetup{hidelinks}% - \bracketset{action character=@} - \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}}{}, - where={level()==2}{fill=red!5, - before computing xy={l=6cm}}{}, - rectangle, thick, fill=cyan!5, inner sep=6pt, - @\the\treetok - \end{forest} +\begin{figure}[ht!] + \centering + \begingroup + % 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 + 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: \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:part:styling}. -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{} -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 -%\csa{hypersetup}\texttt{\{hidelinks\}} % ok pour hyphénation -%\csa{hypersetup}|{hidelinks}| % pas ok -|\hypersetup{hidelinks}| % ok maintenant 12 octobre 2013 - in the |.toc| file. But at the time the -|\treetok| contents are unpacked the |\hyperlink| commands -originating in -|\etocthelinkedname|, etc\dots{} will be executed in the normal -environment for links (which, in this document, is to colorize -them). Rather than having \etoc's code try to guess what the current ``style'' -for links is (a concept not really provided by \ctanpkg{hyperref} it -seems) and store it in |\etocthelinkedname|, etc\dots, I opted for -the simpler solution to leave it up to the user to recreate -whatever conditions are desired. So here it is necessary to re-issue -|\hypersetup{hidelinks}| in the |figure| environment. +\section[\csbhyp{etocsetlevel}]{A powerful functionality of \etoc: the + re-assignment of levels with \csbhyp{etocsetlevel}} +\label{sec:tocdepth} -There are some other examples in this documentation where -|\tableofcontents| is used to prepare material for later -typesetting: -\begin{itemize} -\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. -\end{itemize} +The intrinsic levels manipulated by \etoc are numeric: from +|-2| (which corresponds to |book| in the \ctanpkg{memoir} class) +down (from the big to the small) +to |5| (|subparagraph|). But the assignment of a numeric level +to a given name can be modified at any time with the command +\csb{etocsetlevel}\marg{level\_name}\marg{number}. In conjunction +with the use of the \LaTeX{} |tocdepth| counter, this has +powerful applications: \meta{level\_name} does not have to +coincide with an actual document sectioning command, and \etoc +can be used to print arbitrary ``lists of things'', using no +other auxiliary file than the |.toc| file. This is +explained further in \autoref{part:surprising}. +\begin{framed} + It is often said that in the standard classes, the sectioning + level of |\part| is |0| in the classes not having a |\chapter| + command, and |-1| in classes having a |\chapter| command. This + is \emph{correct} for what regards the \emph{automatic + numbering}, as is governed by the value of the |secnumdepth| + counter; but it is \emph{wrong} for what regards the effect of + the |tocdepth| counter: setting the |tocdepth| to |-1| in the + |article| class just before |\tableofcontents| does \emph{not} + prevent Parts from appearing in the Table of Contents. One has + to set it to |-2| for that, whether in the |article| or in the + |book| class. -\section{The TOC as a molecule}\label{sec:molecule} + The canonical levels, a priori known to \etoc, are those of + relevance to the \textbf{|tocdepth|} counter in the standard + classes and are recapitulated in this table: \centeredline{ + \fbox{\begin{tabular}{rc} + (\ctanpkg{memoir} class) book&-2\\ part&-1\\ chapter&0 \\ + section&1\\ subsection&2 \\ + subsubsection&3 \\ paragraph&4 \\ subparagraph& 5 + \end{tabular}}} -It is also possible to construct a TOC tree obeying the TikZ -syntax for trees: but this is a more complicated task for the -\etoc line styles for reasons related to the way braces are -handled by \TeX{} (they need, when filling up the token list to be -always balanced at each step, else complicated tricks must be -employed.) +\smallskip With \etoc, the user can easily print a local table of +contents inside a given subsection, where subsubsections will be +printed in the style of sections, paragraphs in the style of +subsections, and subparagraphs in the style of subsubsections, if +so desired. One can also decide to set everything to be at the level +|6| (never displayed by \etoc), except for example +paragraphs, promoted to be at level |1|, and then one obtains a nice +table of contents of all the paragraphs from the document! +(|tocdepth| at least |1|)\footnotemark +\end{framed} -The simplest strategy is to allocate a token list (or use a macro) for each -level used: we may need a \csa{parttok}, a \csa{chaptertok}, a -\csa{sectiontok} and a \csa{subsectiontok}, to help in the task of filling -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. +\footnotetext{and one should naturally not print this TOC of paragraphs in + compatibility mode, which would insist on inserting a gigantic left + margin.} +\section{The \csbhyp{etocsettocdepth} and \csbhyp{etocsetnexttocdepth} commands} +\label{etocsettocdepth} +\label{etocsetnexttocdepth} +\label{invisibletableofcontents} -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -% \newtoks\treetok % put this (uncommented) preferably in the preamble -% \newtoks\sectiontok -% \newtoks\subsectiontok -\newcommand*{\treenode}{} +The |tocdepth| counter has no bearing on what gets written to the |.toc| file; +its action is only on the actual typesetting of the table of +contents.\footnote{In the standard classes (at least), it also influences the + \csa{listoftables} and \csa{listoffigures}, via \csa{@dottedtocline}.} In the +standard classes there is only one |\tableofcontents| possible, whereas with +\etoc, arbitrarily many are allowed, so one may change |tocdepth| to the +appropriate value (which decides the finest sectioning level displayed) again +and again each time a table of contents needs to be typeset. -\newcommand*{\appendchildtree}[2]{% token list t1 becomes: t1 child {t2} - \edef\tmp{\the#1 child {\the#2}}% - #1\expandafter{\tmp}% -} -\newcommand*{\preparetreenode}{% - \tmptok\expandafter{\etocthelinkednumber}% expanded one time (mandatory) - \edef\treenode{node {\the\tmptok}}% -} +\etoc provides \csb {etocsettocdepth}\marg{level} whose mandatory argument is +either +numeric (from |-3| to |5|) or a division name such as |subsection| or +|subsubsection| or any name previously declared to \etoc with +\csb{etocsetlevel} (the keywords |all| and |none| are recognized, although not +corresponding to a document division). +This does the appropriate |\setcounter{tocdepth}{numeric_level}|. -\etocsetstyle{section} - {\etocskipfirstprefix} - {\appendchildtree\treetok\sectiontok} - {\preparetreenode \sectiontok\expandafter{\treenode}} - {\appendchildtree\treetok\sectiontok} +As is explained in the next subsection, |tocdepth| is used by \ctanpkg{hyperref}, and +one must take steps to prevent its changes from influencing the bookmarks, too. +So, \etoc has \csb {etocsetnexttocdepth}\marg{level} whose influence ceases +immediately after the next table of contents. The package defines +\csb{invisibletableofcontents} +essentially as +\centeredline{\csb{etocsetnexttocdepth}|{none}|\csb{tableofcontents}} -\etocsetstyle{subsection} - {\etocskipfirstprefix} - {\appendchildtree\sectiontok\subsectiontok} - {\preparetreenode \subsectiontok\expandafter{\treenode}} - {\appendchildtree\sectiontok\subsectiontok} +The simplest organization is probably to have after |\begin{document}| and before the + first |\tableofcontents| a single instance of the \csb{etocsettocdepth} + command, with argument the deepest level (or most commonly used deepest level) + among the tables of contents of the document, and to use locally, + where needed, \csb{etocsetnexttocdepth} before |\tableofcontents| or + |\localtableofcontents|. -\etocsettocstyle - {\treetok{\node {\hyperref[part:overview]{Overview}}}} - {\global\appendtotok\treetok{ ;}} +\begin{framed} + It is possible to use \csb{etocsettocdepth} inside the first argument of + \csb{etocsettocstyle} (possibly in conjunction with checking the + \csb{etoclocaltop} value, \emph{which however will be up-to-date there only if + \csb{etocchecksemptiness} was executed}). There is no worry then about + possible impact on hyperref bookmarks later on, because \etoc always resets + the |tocdepth| counter after typesetting a TOC to the value it had before + it. -\begin{figure}[thbp!]\centering - \etocsetnexttocdepth{subsection} - \tableofcontents \label{toc:molecule} \ref{toc:overview} - \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} -\end{filecontentshere} -\marginattach{} + % 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. -\filecontentsexec\filecontentsheremacro + Check \csb{localtableofcontentswithrelativedepth} for a simpler way to + control the depth of local tables of contents. This has the advantage of + working reliably whether or not the \csb{etocchecksemptiness} is used. +\end{framed} +\subsection{The hyperref option \emph{bookmarksdepth}} +\label{ssec:bookmarksdepth} -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}. +When modifying the counter |tocdepth| for the purposes of +multiple uses of \toc or \localtoc, one should be aware that +package \ctanpkg{hyperref} by default takes into account the +\emph{current} value of the |tocdepth| counter to decide +whether the |pdf| file will contain a bookmark corresponding +to sectioning commands encountered in the source file. Thus, +one typically needs to reset |tocdepth| to its previous +value after having temporarily modified it for a given table of +contents. -This \hyperref[toc:molecule]{TikZ TOC} is fully hyperlinked, like the -previous -\hyperref[toc:forest]{Forest TOC}. +Or, there is the \emph{bookmarksdepth=n} option of package +\ctanpkg{hyperref}, with \emph{n} the desired document bookmarks +maximal depth, which can be numeric or the name of a level known to +\ctanpkg{hyperref}. This documentation previously passed |bookmarksdepth=3| as +option to \ctanpkg{hyperref}, so even if |tocdepth| was left to |1| +by inadvertance after printing a certain table of contents +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. -\etocsettocstyle - {\treetok{\node {\autoref{part:globalcmds}}}} - {\global\appendtotok\treetok{ ;}} +\section[The \csbhyp{etocsettocdepth.toc} command]{The + \csbhyp{etocsettocdepth.toc} and + \csbhyp{etocimmediatesettocdepth.toc} and commands} +\label{etocsettocdepth.toc} +\label{etocimmediatesettocdepth.toc} -\etocsetnexttocdepth {subsection} -\tableofcontents \ref{toc:globalcmds} +This command \csb{etocsettocdepth.toc} implements some functionality of +\ctanpkg{tocvsec2}% +% +\footnote{I thank Denis \textsc{Bitouzé} for drawing + my attention to the incompatibility of this package with \etoc.}, +% +a package +which however was incompatible with \etoc (it can still be used for its +|secnumdepth|-related commands, but its |toc|-related activities will get +canceled by \etoc) and more-or-less designed for a single table of contents. -\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}}% -\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} +The action of \csb{etocsettocdepth.toc} is totally different than the one of +\csb{etocsettocdepth}. Rather than modifying the |tocdepth| counter immediately, +it adds a line to the |.toc| file which, when executed inside a table of +contents will enact this change. -\section{The TOC as a TikZ mind map} -\label{sec:mindmap} +The command \csb{etocsettocdepth.toc}, like +\csb{etocsettocdepth}, accepts both numeric and named +arguments. In the case of a named argument, the actual numeric +value to be used is not yet decided at the time the |.toc| +file is created; it will be the value currently specified for +the named level at the time each table of contents (not having +done |\etocignoretoctocdepth|) is typeset. -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.} +The |tocdepth| counter will never be set to a value finer than its initial value +at the start of the table of contents: so adding commands +\csb{etocsettocdepth.toc} in the document is a way to \emph{restrict} locally +the depth of the table of contents. For example to prevent inclusion in the +tables of contents of the sub-sub-sections of a given chapter. +This +{\fbox{gets executed in ALL tables of contents.}} -\let\appendchildtree\relax -\let\childnode\relax -\let\appendtotok\relax -\expandafter\let\csname c@partco\endcsname\relax +Also \csb{etocimmediatesettocdepth.toc} is provided. For explanations, +refer to the discussion of \csb{etocimmediatedepthtag.toc} in the +next section. -\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} -\begingroup -% \newtoks\treetok % done in preamble -% \newtoks\parttok +\subsection{The \csbhyp{etocobeytoctocdepth} and + \csbhyp{etocignoretoctocdepth} commands} +\label{etocobeytoctocdepth} +\label{etocignoretoctocdepth} -\newcommand*\partnode {} % just to check we don't 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 +So \csb{etocignoretoctocdepth} is provided to cancel the +\csb{etocsettocdepth.toc} mechanism when +needed; and \csb{etocobeytoctocdepth} will +re-activate it. The package does initially \csb{etocobeytoctocdepth}. -\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2 - #1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}} +\section[The \csbhyp{etocdepthtag.toc} and \csbhyp{etocsettagdepth} commands]{The + \csbhyp{etocdepthtag.toc}, \csbhyp{etocimmediatedepthtag.toc} and + \csbhyp{etocsettagdepth} commands} +\label{etocdepthtag.toc} +\label{etocimmediatedepthtag.toc} +\label{etocsettagdepth} -\newcommand*{\appendchildtree}[3]{% -% this is to construct "t1 child [#3]{t2}" from #1=t1 and #2=t2 -% t1 and t2 are two toks variable (not macros) -% #3 = for example teal!60 - \edef\tmpstuff {\the#1 child [#3]{\the#2}}% - #1\expandafter {\tmpstuff }% -} - -\newcounter{partco} - -% 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} - -\etocsetstyle{part} - {\etocskipfirstprefix} -% This updates the global tree with the data from the previous -% part and all its children sections. Moved here because for some parts the -% sections are not displayed due to depth tags. - {\ifnum\value{partco}=3 - \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= yellow!80}% second - \else\appendchildtree\treetok\parttok {branch color= green!50}% third and next ... - \fi\fi - } - {\stepcounter{partco}% -% customize manually some TikZ set-up (should be done inside the TikZ thing I guess) - \def\tmpoption {}% - \def\tmprotate {}% first - %\ifnum\value{partco}=5 \def\tmprotate {[counterclockwise from =-40]}\fi - %\ifnum\value{partco}=8 \def\tmprotate {[counterclockwise from =-50]}\fi -% define the part node - \edef\partnode{node \tmpoption - {\unexpanded\expandafter{\etocthelinkednumber}. - \unexpanded\expandafter{\etocthelinkedname}}\tmprotate }% -% this is a starting point which will be filled it by the section children - \parttok\expandafter{\partnode}} - {\ifcase\pseudomodthree{\value{partco}}% - \or \appendchildtree\treetok\parttok {branch color= teal!60}% first - \or \appendchildtree\treetok\parttok {branch color= yellow!80}% second - \else\appendchildtree\treetok\parttok {branch color= green!50}% third and next ... - \fi - } - -\etocsetstyle{section} - {} - {} - {% define the section node - \edef\childnode{child {node {\unexpanded\expandafter{\etocthelinkednumber} - \unexpanded\expandafter{\etocthelinkedname}}}}% - % append it to the current \parttok - \appendtotok\parttok\childnode - } - {} -\etocsettocstyle - {\setcounter{partco}{0}% - \treetok{\node [root concept]{\textbf{The \etoc documentation}}}} - {\global\appendtotok\treetok{ ;}} -% 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} -\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 {etocandworld}{part} -\etocsettagdepth {code} {section} +% 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 +then set via \csb{etocsetlevel} according to what was locally needed, +but it was too hacky and I am not sure if it was understandable). -\tikzset{ - branch color/.style={ - concept color=#1!white, - every child/.append style={concept color=#1!white!30!white, font=\normalsize}, - } -}% +It is used as \csb{etocdepthtag.toc}\marg{tag\_name}, where the +\meta{tag\_name} is anything, and this will put the tag in the |.toc| +file. When typesetting a TOC, one issues a series of commands +\csb{etocsettagdepth}\marg{tag\_name}\marg{level} where the +\meta{level} may be either numeric (from |-3| to |5|) or the name of a +division unit known to \etoc, or |none| or |all|. The effect of the tag +inside the |.toc| file will then be to set the |tocdepth| counter to +the desired value, in real time (this can not get finer than the +initial value of |tocdepth| at the start of the TOC). -\begin{figure}[thp!] -\tableofcontents\label{toc:mindmap}% -\centeredline{\resizebox{.85\paperwidth}{!}% -{\begin{tikzpicture}[mindmap, - grow cyclic, - text width=2cm, - align=flush center, - 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 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 +The added flexibility is thus that \csb{etocsetlevel} has not been used in a +kind of hacky way, that one may use named level depths, and the +keywords |none| and |all|. -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}. +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{sec:tocwithdepthtags}. -\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 -document. Things written to the |.log| file get broken into lines. Here is a -technique to get non-broken output. Once the \csa{treetok} has been computed -by \etoc (as in the \hyperref[toc:molecule]{molecule} example, or the current -example), this demo will write it out to file with extension -|.toctree|: +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 +this situation: \begin{verbatim} - \newwrite\TOCasTree - \immediate\openout\TOCasTree=\jobname.toctree - \immediate\write\TOCasTree{\the\treetok}% + \clearpage % or anything ending up causing its presence here right before + % the \etocdepthtag.toc + \etocdepthtag.toc{sometag} + \include{some file containing sections} \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. +The tag will end up in the |.toc| file \emph{after} all section headings from +the included file. The cause is that \LaTeX\ inserts immediately in the +main auxiliary file a command to input the auxiliary file of the included file +(which in turn, contains instructions to add data to the |.toc| file). But +\csb{etocdepthtag.toc} does not internally use such immediateness, as it uses +the same interface as |\section| and alike commands when they want to write +extra data to the |.toc| file. +So% +% +\footnote{Thanks to Norman \textsc{Ramsey} who reported this problem, together + with a fix, in July\dots 2016. Sorry for long delay before updating + \etoc six years later\dots} +% +% \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). -\section{The TOC as a (long) table} -\label{sec:tocastable} +One should not use this variant systematically. For example if your document +looks like: +\begin{verbatim} +\clearpage -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: +\section{bbbb} -\begin{enumerate} -\item it is mandatory to issue \csb{etocglobaldefs} for \etoc's - definitions to have global scope, -\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}). -\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 - that at the end with the idea to close the \emph{current} row; - and when the TOC is a partial one (a \csa{localtableofcontents}) this - is (in almost all situations) mandatory. -\end{enumerate} +Some text -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. +\etocdepthtag.toc{sometag} +\etocimmediatedepthtag.toc{someimmediatetag} +\section{cccc} -\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} -\begingroup -\etocglobaldefs % necessary for \etocname etc... to survive & -\makeatletter -% hack into longtable \hline to avoid annoying (here) stray lines at top -\def\LT@@hline{% - \ifx\@let@token\hline - \global\let\@gtempa\@gobble - \global\let\@gtempb\@firstofone %%% ADDED - \gdef\LT@sep{\penalty-\@medpenalty\vskip\doublerulesep}% - \else - \global\let\@gtempa\@empty - \global\let\@gtempb\@gobble %%% ADDED - \gdef\LT@sep{\penalty-\@lowpenalty\vskip-\arrayrulewidth}% - \fi - \ifnum0=`{\fi}% - \multispan\LT@cols - \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr - \@gtempb{% %%% ADDED - \noalign{\LT@sep}% - \multispan\LT@cols - \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr - \noalign{\penalty\@M}% - }% %%% ADDED - \@gtempa} -\makeatother +Some text -% observe the locations of the \\ -\etocsetstyle{part} - {} - {} - {\\\hline\multicolumn{3}{c}{\bfseries\vrule height6ex depth3ex width0pt - \etocifnumbered{\etocnumber. }{}\etocname}} - {} +\end{document} +\end{verbatim} +then the |someimmediatetag| will end up being inserted in |.toc| file +\emph{before} the |bbbb| section. This is because \LaTeX's |\section| +uses a \emph{delayed} write, not an \emph{immediate} one. And +\csb{etocdepthtag.toc} wisely uses a \emph{delayed} write. -\etocsetstyle{section} - {} - {\etociffirst{\\\hline}{\\}} - {\etocnumber&\etocname &\etocpage } - {} +As it seems very hard programmatically to identify automatically if the +\emph{immediate} variant of \csb{etocdepthtag.toc} should be used, the package +provides two separate commands and it is up to user to make the correct +choice. -\etocsetstyle{subsection} - {} - {\\} - {&\makebox[1cm][c]{\etocnumber}% - \parbox[t]{\dimexpr6cm-\tabcolsep\relax}{\sloppy\itshape\etocname\strut}% - &\itshape\etocpage } - {} -\etocsettocstyle - {\hypersetup{hidelinks}% - \begin{longtable}{|>{\bfseries}c|p{7cm}|r|} - \hline - \multicolumn{3}{|c|}{\Large\bfseries\strut\strut TABLE OF CONTENTS}% - } - {\\\hline\end{longtable}} +\subsection{The \csbhyp{etocobeydepthtags} and \csbhyp{etocignoredepthtags} commands} +\label{etocobeydepthtags} +\label{etocignoredepthtags} -\etocsetnexttocdepth {subsection} -\tableofcontents -\endgroup -\end{filecontentsdef} +After \csb{etocignoredepthtags}, the |.toc| depth tags are ignored (but +\csb{etocdepthtag.toc} still works). The package does initially +\csb{etocobeydepthtags} which makes \etoc react to the found tags in the +|.toc| file. -\filecontentsexec\foo +\section{Adding commands to the \texorpdfstring{\texttt{.toc}}{.toc} file} +\label{sec:addingtotoc} -\filecontentsprint\foo -\marginattach{-A} -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 -for local tables of contents) one may indeed construct -TOC-as-tables with the |\\| located at the end of the style -specifications. The problem in the previous example was with the -positioning of the |\hline|'s. +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}|. -Due to technical aspects of how \TeX{} constructs alignments any -definition or assignment done after an |\\| starts a new row, and -thus makes |\hline| an illegal token (this shows as a |misplaced -\noalign| error.) Not only does \etoc have to do such definitions -to construct \csb{etocname} etc..., it is furthermore the case that -some packages put things in the |.toc| file and as a result there -is never any guarantee that between two \csa{contentsline} there -will not be such a token like |\relax| which in the contexts of -alignments forces \TeX{} to start a cell and thus makes it -impossible then to insert an |\hline|. - -The safest way is thus to start with an |\\| each line style -specification in order to close the \emph{previous} table row. We -had a little problem with the fact that we wanted parts not only -to have a rule above them (easy, they do |\\\hline|) but also -below them: after each part there is a section, and it is these -sections which are used to insert the missing |\hline| -(this is done with the help of the \csb{etociffirst} -conditional). +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. -Last technical note: because we put the |\\\hline| inside the branches, there -was no need to employ the expandable variants \csb{etocxiffirst} and -\csb{etocxifnumbered}. +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}. -For the hardliner's old way see \autoref{ssec:tocastableold}. +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. -Here is also a much simpler example. It is a local table of -contents. +\subsection{The hyperref option \emph{hidelinks}}\label{ssec:hidelinks} -\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} -\begin{center} -\etocsetstyle{section} - {} - {\etociffirst{\\\hline\hline}{\\\hline}} - {\etocname & \etocnumber & \etocpage } - {} +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}? -\etocsettocstyle - {\hypersetup{hidelinks}\begin{tabular}{|p{4cm}|c|c|}\hline - \multicolumn{1}{|c|}{\bfseries Section}& - \bfseries number& - \bfseries page} - {\\\hline\end{tabular}} +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}}|} -\etocglobaldefs % MANDATORY !! -\etocsetnexttocdepth{1} + \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} -\tableofcontents\ref{toc:overview} -\end{center} -\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 +\section[The \csbhyp{etocsetlocaltop.toc} command] + {The \csbhyp{etocsetlocaltop.toc} and + \csbhyp{etocimmediatesetlocaltop.toc} commands} +\label{etocsetlocaltop.toc} +\label{etocimmediatesetlocaltop.toc} -\filecontentsprint\foo -\marginattach{-B} +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} -\section{A TOC self-adjusting widths for its typesetting} -\label{sec:thirdexampleextra} +% 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: -This is a continuation of \autoref{sec:thirdexample}. The goal is to adjust -automatically the ``numwidths'' used for typesetting the unit numbers in the -(local) tables of contents. -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\makeatletter -\newcommand*\TOCcompute@numwidths [2]{% #1=empty/"local", #2=minimal indent - \begingroup - \def\TOCnumwidthB {0pt}% - \def\TOCnumwidthC {0pt}% - \def\TOCnumwidthD {0pt}% - \def\TOCnumwidthE {0pt}% - \def\TOCnumwidthF {0pt}% - \def\TOCnumwidthG {0pt}% - \etocsetstyle{part}{}{}{}{}% - \etocsetstyle{chapter}{} - {\setbox0\hbox{\bfseries\etocthenumber\kern#2}} - {\ifdim\wd0>\TOCnumwidthB\edef\TOCnumwidthB{\the\wd0}\fi}{}% - \etocsetstyle{section}{} - {\setbox0\hbox{\bfseries\etocthenumber\kern#2}} - {\ifdim\wd0>\TOCnumwidthC\edef\TOCnumwidthC{\the\wd0}\fi}{}% - \etocsetstyle{subsection}{} - {\setbox0\hbox{\etocthenumber\kern#2}} - {\ifdim\wd0>\TOCnumwidthD\edef\TOCnumwidthD{\the\wd0}\fi}{}% - \etocsetstyle{subsubsection}{} - {\setbox0\hbox{\etocthenumber\kern#2}} - {\ifdim\wd0>\TOCnumwidthE\edef\TOCnumwidthE{\the\wd0}\fi}{}% - \etocsetstyle{paragraph}{} - {\setbox0\hbox{\etocthenumber\kern#2}} - {\ifdim\wd0>\TOCnumwidthF\edef\TOCnumwidthF{\the\wd0}\fi}{}% - \etocsetstyle{subparagraph}{} - {\setbox0\hbox{\etocthenumber\kern#2}} - {\ifdim\wd0>\TOCnumwidthG\edef\TOCnumwidthG{\the\wd0}\fi}{}% - % - \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}% - \etocnopar - \csname #1tableofcontents\endcsname -\typeout{Next TOCs will use \TOCnumwidthB\space for chapter number width}% -\typeout{Next TOCs will use \TOCnumwidthC\space for section number width}% -\typeout{Next TOCs will use \TOCnumwidthD\space for subsection number width}% -\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 -}% -\newcommand*\TOCcomputenumwidths [1][0.5em]{% - \TOCcompute@numwidths {}{#1}% -}% -\newcommand*\TOCcomputelocalnumwidths [1][0.5em]{% - \TOCcompute@numwidths {local}{#1}% -}% -\makeatother -\end{filecontentshere} -\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 -\csa{TOCcomputelocalnumwidths} is provided. As the code makes global -assignments, either use (once) \csa{TOCcomputenumwidths} or do -\csa{TOCcomputelocalnumwidths} for each local table of contents. \begin{verbatim} - \TOCcomputelocalnumwidths % may use optional argument to replace 0.5em - \localtableofcontents +\part*{Extra unnumbered part} +\etocsetlocaltop.toc{part} +\localtableofcontents \end{verbatim} -Notes: -\begin{enumerate}[nosep] -\item naturally these are only suggestions. For example one could put - everything in single macros \csa{TOCtoc} and \csa{TOClocaltoc} to - simultaneously compute the numwidths and then typeset the (local) table of - contents. -\item if you want to adjust the |tocdepth| recall from - \autoref{ssec:bookmarksdepth} that it influences \ctanpkg{hyperref} hence you may - need to use a group |\begingroup...\endgroup|. Or, one can use - \csb{etocsetnexttocdepth}\marg{level} but (with the code as here) this must - then be issued twice, once for \csa{TOCcomputelocalnumwidths}, once for - \csa{localtableofcontents}. -\item the bold font serves above for both chapter and section numwidth - computations, but the code from \autoref{sec:thirdexample} uses |\bfseries| - only in local TOCs. Thus the \csa{TOCcomputenumwidth} will set the parameter - \csa{TOCnumwidthC} to a value slightly larger than needed in the main TOC. - Hence the section style in \csa{TOCcompute@numwidths} should possibly insert - the |\bfseries| in the box only after testing for the optional parameter - |local|. -\end{enumerate} - -\clearpage -\etocdepthtag.toc {linestyles} - -\part{Commands for the toc line styles} -\label{part:linestyles} -\thispartstats +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}|. -\etocsetstyle{section} -{\begin{enumerate}[leftmargin=.75cm, label=\etocifnumbered - {{\fboxrule1pt\fcolorbox{green}{white}{\etocnumber}}}{}]} -{\normalsize\bfseries\rmfamily\item} -{\etocname{} (page \etocpage)} -{\end{enumerate}} +As a (counter)-example consider this document: +\begin{verbatim} +\documentclass{article} +\usepackage{etoc} +\begin{document} +\tableofcontents -\etocsetstyle{subsection} -{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]} -{\normalfont \item} -{\etocname{} (p.~\etocpage)} -{\end{enumerate}} +\part*{A} +\etocsetlocaltop.toc{part} +\localtableofcontents -\etocsetstyle{subsubsection} -{\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix} -{\allowbreak\,--\,} -{\etocname} -{.\hfil\par\endgroup\pagebreak[3]} +\section{I} -% 27 janvier 2013 22:30 -% je définis les macros (non protégées) -% \etocthename, \etocthenumber, \etocthepage +\section{II} -\etocruledstyle[1]{\etocfontminusone\color{green}% - \fboxrule1pt\fboxsep1ex - \framebox[\linewidth] - {\normalcolor\hss Contents of \autoref{part:linestyles}\hss}} +\part*{B} -\localtableofcontents \label{toc:a} +\section{III} -\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. +\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). -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.} +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. -\begingroup\small -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\etocsetstyle{section} -{\begin{enumerate}} -{\normalsize\bfseries\rmfamily\item} -{\etocname{} (page \etocpage)} -{\end{enumerate}} +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). -\etocsetstyle{subsection} -{\begin{enumerate}} -{\normalfont\item} -{\etocname{} (p.~\etocpage)} -{\end{enumerate}} +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. -\etocsetstyle{subsubsection} -{\par\nobreak\begingroup\normalfont - \footnotesize\itshape\etocskipfirstprefix} -{\allowbreak\,--\,} -{\etocname} -{.\hfil\par\endgroup\pagebreak[3]} -\end{filecontentshere} -\marginattach{} -\endgroup +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.% +% -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. +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. -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! +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}. -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. +\section{The \csbhyp{etoclocaltop} command} +\label{etoclocaltop} -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. +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. -\section{The \csbhyp{etocskipfirstprefix} and \csbhyp{etociffirst} commands} -\label{etocskipfirstprefix} -\label{etociffirst} -\label{etocxiffirst} +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}). -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.} +%\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} -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). + 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. -The variant \csb{etocxiffirst} does the same, but is expandable. + 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{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{Checking TOCs for emptiness} -\section{The \csbhyp{etocifnumbered} switch} -\label{etocifnumbered} -\label{etocxifnumbered} +\subsection{The \csbhyp{etocchecksemptiness} command} +\label{etocchecksemptiness} +\label{etocdoesnotcheckemptiness} -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 user needs to issue \csb{etocchecksemptiness} to tell \etoc to check whether +local tables of contents are empty and in case of emptiness to print nothing +at all.\footnote{Thanks to Paul Gaborit who asked for +such a feature.} This +can be useful to authors of \LaTeX{} classes who for example wish to have a +|\chapter| command doing systematically a \localtoc, or for +people producing files via automatic conversions and some of those might have +sectioning commands and others not. -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}} +«Emptiness» means that no \csa{contentsline} command would get executed within +the scope of the local table of contents --- empty line styles by themselves do +not make the TOC empty. \etoc always executes the \csb{etocaftertochook} +command; and the test for emptiness itself executes everything else found in +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 \etocrelease{1.08i}.) +\end{enumerate} -\etocsetstyle{subsection} -{\begin{enumerate}[leftmargin=0cm, label=\etocnumber]} -{\normalfont \item} -{\etocname{} (p.~\etocpage)} -{\end{enumerate}} -\end{verbatim} +The suppression of the heading (more precisely of the toc display style +elements) may be effective only for the final \LaTeX{} runs. For example in +the situation of a \toc|\ref{foo}| where the label |foo| is +not yet recognized, the heading (but not the contents) is printed and the TOC +is declared non-empty. Or, if one adds a \localtoc to a document, on the next +run, the test for emptiness will in fact apply to the next one, and the last +local TOC of the document will have its contents temporarily unknown to \etoc, +hence will be declared non empty, and the heading will be printed. -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}|. +For a finalized document compiled with initially no auxiliary files, the first +\LaTeX{} run will declare all local TOCs non empty and print for each of them a +heading (and no contents naturally). The second \LaTeX{} run will then +correctly decide which local TOC is empty or not. -The command \csb{etocifnumbered} is robust; \csb{etocxifnumbered} -(new with |1.08|) has the same effect but is expandable. +\subsection{The \csbhyp{etocnotocifnotoc} command} +\label{etocnotocifnotoc} +The user can then extend the emptiness-checking to the global TOCs with +\csb{etocnotocifnotoc}. May I respectfully give the advice then to rather do +none of |\usepackage{etoc}| nor \toc ? |;-)|. Well, there is always the case +of batch conversions of documents having or not sectioning units. -\section{The \csbhyp{etocthename}, \csbhyp{etocthenumber}, and -\csbhyp{etocthepage} commands} -\label{etocthename} -\label{etocthenumber} -\label{etocthepage} +\subsection{The \csbhyp{etocifwasempty} command} +\label{etocifwasempty} +\label{etocxifwasempty} -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. +The command \csb{etocifwasempty}\marg{YES}\marg{NO} executes \meta{YES} if +the previous TOC was found to be empty and \meta{NO} if its was not so. This +may serve to act appropriately after a truly empty TOC. If +\csb{etocchecksemptiness} has not been issued, this conditional always +executes the \meta{NO} branch. -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}|. +This command is robust, and \csb{etocxifwasempty} is its expandable +version. -The command \csb{etoclink} is robust. +\fbox{Do not forget the second argument: at least an empty pair of braces |{}| + must be present.} -% 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. +This conditional may wrongly say that the local TOC is empty or not empty +until \LaTeX{} compilations stabilize. But if it says that a local TOC is +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|). +\clearpage +\etocdepthtag.toc {examples} +\part{Examples}\label{part:examples} +\thispartstats %% (pas de sous-section) -\makeatletter\scr@activate@xsection{1}\makeatother -% [] goes to head but {} to toc +\etocdefaultlines +\etocsettocstyle {}{} +\localtableofcontents -% 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} +To understand all code snippets in detail, +one will need to have first browsed through \autoref{sec:linestyles} +and \autoref{sec:tocstyle}. -\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}. +\section{A first example} +\label{sec:firstexample} +\label{invisiblelocaltableofcontents} -At |1.1a| it was decided that the commands should match their denominations.% +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: % -\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.} +\centeredline{\csb{invisiblelocaltableofcontents} |\label{toc:overview}|} % -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% +This +sets-up the label |toc:overview|, and we can use it at any location in the +document: % -\footnote{Prior to \texttt{1.1a}, there was a link added only if \ctanpkg{hyperref} option \texttt{linktoc} was not \texttt{none}.} +\centeredline{|\tableofcontents \ref{toc:overview}|} % -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} +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. -\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} +\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} -\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}. +\filecontentsexec\foo -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}. +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|. -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. +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. -\section{The \csbhyp{etocsetlevel} command} -\label{etocsetlevel} +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. -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. +Here is how it was produced: -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. +\filecontentsprintviascan\foo +\marginattach +\section{A second example} +\label{sec:secondexample} -\section{Scope of commands added to - the \texorpdfstring{\texttt{.toc}}{.toc} file} +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}. -\begingroup % pour \small et \MacroFont en particulier. -\small +\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} -\subsection{Testing the scope} +\etocsetstyle {part} +{\parindent 0pt + \nobreak + \etocskipfirstprefix} +{\pagebreak[3]\bigskip} +{\large\rmfamily\bfseries\centering %\scshape + \etocifnumbered{Part \etocnumber{} -- }{}\etocname\par} +{} -Let us switch to the color red, and also add this command to the |.toc| file: +\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 } -\color{red!50} -\addtocontents{toc}{\string\color{red!50}} +\etocsetstyle {subsection} +{\leftskip1cm\rightskip .75cm \parfillskip 0pt plus 1fil\relax + \nobreak\smallskip} +{} +{\footnotesize\sffamily\mdseries\itshape + \etocname{} (\etocnumber, p. \etocpage). } +{\par\medskip} -\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} +\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 -\subsection{This is a (pale) red subsection for illustrative purposes} +The code: +\filecontentsprintviascan\foo +\marginattach -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. +\section{A Beautiful Thesis example} -But let us now close this subsection and start a section. +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} -\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}|. +\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} +{} -This illustrates the discussion from \autoref{ssec:limitations}. +\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} +{} -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. +\def\tmptitle{My Beautiful Thesis} +\etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin + \leavevmode\leaders\hrule height 1pt\hfill\ + \huge\textit{\tmptitle}\par}{\bigskip} -\begin{verbatim} - \normalcolor - \addtocontents{toc}{\string\normalcolor} -\end{verbatim} +\tableofcontents \ref{toc:overview} \endgroup +\end{filecontentsdef} -\normalcolor -\addtocontents{toc}{\string\normalcolor} +\filecontentsexec\foo -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. +\filecontentsprintviascan\foo +\marginattach -\clearpage -\etocdepthtag.toc {globalcmds} +\section{Testing the compatibility mode}\label{sec:testingcompat} -\part{Commands for the toc display style} -\label{part:globalcmds} +As a further example we now print the local table of contents +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 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} +\etocclasstocstyle % necessary for the display to obey toc=left +\etocstandardlines +\tableofcontents \ref{toc:tocstyle} +\endgroup +\end{verbatim} +\begingroup +\KOMAoptions{toc=left} +\etocclasstocstyle +\etocstandardlines +\tableofcontents \ref{toc:tocstyle} +\endgroup -\thispartstats +\section{Another compatibility mode} +\label{sec:anothercompat} -\etocsettocstyle{}{} -\etocstandardlines -\localtableofcontents \label{toc:globalcmds} +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. -\section{Specifying the toc display style} +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: +\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, +\item use the document class style for chapters and sections, but modify it only + for subsections, +\item do either of the above only for some portions of the table of contents. +\end{enumerate} +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: -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} +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +\makeatletter +\newcommand{\MyLocalTOC}[1][section]{% + \begingroup + \etocsetstyle{section}{}{} + {\l@section{\numberline{\etocnumber}\etocname}{\etocpage}}{}% + \etocsetstyle{subsection}{}{} + {\l@subsection{\numberline{\etocnumber}\etocname}{\etocpage}}{}% + \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 -\subsection{The command \csbhyp{etocsettocstyle}} -\label{etocsettocstyle} +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.} -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: +One can add to the above arbitrary text formatting commands, for example +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} -\etocsettocstyle{\begin{enumerate}}{\end{enumerate}} -\etocsetstyle{section}{}{\item \sectionname}{}{} +\newcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.3em}} \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: +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 -\etocsettocstyle - {\begin{enumerate}} - {\if@newlist\item Please run \LaTeX\ again\fi - \end{enumerate}} +\etocsetstyle{subsection} + {] + {} + {\@dottedtocline{2}{1.5em}{2.3em}{\numberline{etocnumber}\etocname}{\etocpage}} + {} \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: +we then basically reconstitute the default rendering. Here is more careful +code: \begin{verbatim} -\etocmulticolstyle{\noindent\bfseries\Large - \leaders\hrule height1pt\hfill - \MakeUppercase{Table of Contents}} +\makeatletter +\etocsetstyle{subsection} + {] + {} + {\@dottedtocline{2}{1.5em}{2.3em}{\etocifnumbered{\numberline{etocnumber}}{}% + \etocname}{\etocpage}} + {} +\makeatother \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: +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} -\etocruledstyle[1]{\etocfontminusone\color{green}% - \fboxrule1pt\fboxsep1ex - \framebox[\linewidth] - {\normalcolor\hss Contents of this part\hss}} +\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} -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}|. +\section{Emulating the book class}\label{sec:thirdexample} -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). +As explained in \autoref{subs:compat}: without explicit use of an +\csb{etocsetstyle} command the package will leave to the document class the +hand regarding the ``toc line styles''. It is sometimes asked by users (for +example those using \etoc for its \csb{localtableofcontents}) how to stay +close to but not completely identical with the design implemented by the +standard classes, such as |book|. I can recommend package \ctanpkg{tocloft} for this, +as it is compatible with \etoc (see \autoref{subs:tocloft}) and thus \etoc will +obey the \ctanpkg{tocloft} customizations (as long as no use has been made of +\csb{etocsetstyle}). It is also possible to modify only the style for, say, +sections and leave the parts, chapters, subsections as in the document class, +via the technique from \autoref{sec:anothercompat}. -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}. +But for complete control, here is a translation of the |book| class code into +\etoc lingua. It is then easy to modify the relevant lengths or adjust the +used fonts. I thank \textsc{Denis Bitouzé} for prompting me to include this in +the \etoc manual, as it resulted from some conversation we had about this. The +code is not 100\% faithful to the |book| class, and particularly its rendering +of (multi-line) non-numbered units differs (... I think, as I copied pasted as +is the code from where I had stored it and did not do much thinking about it +again). Some proficiency in low-level \TeX\ and \LaTeX\ macros is needed to +understand what the code says, but for modifying fonts or some lengths such +in-depth understanding is not needed. +With some extra code one can \emph{automatically adjust the widths} assigned +to typesetting sectioning numbers in order to prevent overflows, even with for +example \MakeUppercase{\romannumeral 38}; but this is a more advanced feature +which I have moved to \autoref{sec:thirdexampleextra}. +First we set up some lengths. I use macro registers, not real \LaTeX\ lengths. +When using |em|'s however, this means that one must pay attention to when the +actual dimension assignment is made, as this will then depend upon the current +font settings. In the code below, at the location where the \csa{TOCnumwidthB} +and \csa{TOCnumwidthC} will be used, the |1em| from their specification will +be matched to the normal medium series font, not the bold font; this is +deliberate so that one can compare more readily with the other dimensions; +besides, with the \csa{TOCcomputenumwidths} from +\autoref{sec:thirdexampleextra} these macros will actually hold a dimension +using |pt| as dimensional unit. -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|. +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +% it will be easy to globally shift the TOC horizontally if needed +\def\TOCleftmargin {0pt} +\def\TOCrightmargin {2.55em}% like LaTeX's \@tocrmarg +% this is for dotted leaders +\newbox\TOCleaderbox +\def\TOCleaderboxwidth {0.7777em}% about like what standard classes do +% vertical spacing +\def\TOCverysmallvskip {0pt plus .2pt} +\def\TOCmedvskip {1em plus 1pt} +\def\TOCbigvskip {2.25em plus 1pt} -\subsection{The compatibility mode \csbhyp{etocstandarddisplaystyle}} -\label{etocstandarddisplaystyle} +% the ``numwidths'' for typesetting the numbering of division units. +% I don't recall exactly how (and for which fonts) these figures were chosen. +% They quickly prove too small if using Roman numerals (as do too the book +% class defaults even though they are a bit larger). +\def\TOCnumwidthB {1.5em} % chapter +\def\TOCnumwidthC {2.278em}% section, I think default is 2.3em +\def\TOCnumwidthD {3.056em}% analog in standard class is 3.2em +\def\TOCnumwidthE {3.833em}% analog in standard class is 4.1em +\def\TOCnumwidthF {4.611em}% analog in standard class is 5em +\def\TOCnumwidthG {5.389em}% analog in standard class is 6em -\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. +% The code for the ``global toc style''. -\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. +\newcommand*\TOCglobalstyle {% +\etocsettocstyle + {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi + \parindent\z@ \leftskip\z@skip \rightskip \z@skip + \setbox\TOCleaderbox\hbox to \TOCleaderboxwidth{\hss.\hss}% + \chapter *{\noindent\kern\TOCleftmargin\relax % uses "pt"... + \contentsname + \@mkboth {\MakeUppercase \contentsname}{\MakeUppercase \contentsname}}% + \rightskip \TOCrightmargin\relax + \parfillskip -\rightskip % or a smaller value if desired + \leftskip \TOCleftmargin \relax } + {\if@restonecol \twocolumn \fi\cleardoublepage}% +% +\etocsetstyle{part} + {} + {\addpenalty {-\@highpenalty}% + \addvspace \TOCbigvskip + \leavevmode + {\large \bfseries % use a group to limit font change + \interlinepenalty\@M + \etocifnumbered{\etocnumber\hspace{1em}}{}% + \etocname + \nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}}\par + \nobreak + } + {} + {}% +% +\etocsetstyle{chapter} + {\advance\leftskip\TOCnumwidthB\relax} + {\addpenalty {-\@highpenalty }% + \vskip \TOCmedvskip\relax + \leavevmode + {\interlinepenalty\@M + \etocifnumbered + {\llap{\makebox[\TOCnumwidthB][l]{\bfseries\etocnumber}}} + {\advance\leftskip-\TOCnumwidthB\relax}% + \bfseries\etocname + \nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}\par }% + \penalty \@highpenalty + } + {} + {\advance\leftskip-\TOCnumwidthB\relax}% +% + \TOCsetlinestyle {section} {\TOCnumwidthC}% + \TOCsetlinestyle {subsection} {\TOCnumwidthD}% + \TOCsetlinestyle {subsubsection}{\TOCnumwidthE}% + \TOCsetlinestyle {paragraph} {\TOCnumwidthF}% + \TOCsetlinestyle {subparagraph} {\TOCnumwidthG}% +}% end of \TOCglobalstyle -\subsection{The command \csbhyp{etocinline}} -\label{etocinline} -\label{etocnopar} -\label{etocdisplay} +%The common code for line styles is abstracted into a macro: + +\newcommand\TOCsetlinestyle [2]{% #1= unit, #2= numwidth as macro +\etocsetstyle{#1} + {\advance\leftskip#2\relax} + {\vskip \TOCverysmallvskip\relax + \leavevmode + {\interlinepenalty\@M + \etocifnumbered + {\llap{\makebox[#2][l]{\etocnumber}}}{\advance\leftskip-#2\relax}% + \etocname + \nobreak\leaders \copy\TOCleaderbox + \hfil\makebox[-\parfillskip][r]{\etocpage}% + \par }% + } + {} + {\advance\leftskip-#2\relax}% +} +\makeatother +\end{filecontentshere} +\marginattach -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. +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.) -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. +The whole thing was encapsulated in \csa{TOCglobalstyle}, because we also want +a \csa{TOClocalstyle} for local tables of contents which typically will want +to use |\section*| rather than |\chapter*| and not insert page marks in the +headers. The \csa{TOClocalstyle} is to be issued once, after the main document +TOC, or rather before using \localtoc. If one wants a full +TOC at end of document one will naturally have to issue again +\csa{TOCglobalstyle} there. -\section{Starred variants and hooks} -\label{tableofcontents*} -\label{localtableofcontents*} -\label{etocbeforetitlehook} -\label{etocaftertitlehook} -\label{etocaftercontentshook} -\label{etocaftertochook} +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +\makeatletter +\newcommand*\TOClocalstyle {% +\etocsettocstyle + {\if@twocolumn \@restonecoltrue \onecolumn \else \@restonecolfalse \fi + \setbox\TOCleaderbox\hbox to \TOCleaderboxwidth{\hss.\hss}% + \parindent\z@ + \dimen@ 2.25em % for left indenting + \section *{\kern\dimen@ % use of \dimen@ works here by sheer luck + \contentsname + % un-comment this if marks are wanted: + %\@mkboth {\MakeUppercase \contentsname}{\MakeUppercase \contentsname}% + }% end of \section + \parskip \z@skip + \vspace{-1.25\baselineskip}% somewhat ad hoc + \leftskip 2.25em + \rightskip 4.5em + \advance\rightskip-\TOCrightmargin\relax + \leavevmode\leaders\hrule\@height\p@\hfill\kern\z@\par + \rightskip 4.5em + \parfillskip -\TOCrightmargin\relax } + {\nobreak\vskip-.5\baselineskip + \leavevmode\leaders\hrule\@height\p@\hfill\kern\z@\par + \bigskip + \if@restonecol \twocolumn \fi }% +% +\etocsetstyle{section} + {\advance\leftskip\TOCnumwidthC\relax} + {\addpenalty \@secpenalty + \etociffirst{}{\addvspace{\TOCmedvskip}}% + \leavevmode + {\interlinepenalty\@M + \bfseries\etocifnumbered + {\llap{\makebox[\TOCnumwidthC][l]{\etocnumber}}} + {\advance\leftskip-\TOCnumwidthC}% + \etocname\nobreak\hfil\makebox[-\parfillskip][r]{\etocpage}\par }% + \penalty \@highpenalty } + {} + {\advance\leftskip-\TOCnumwidthC\relax}% +% the rest is identical with code for global tocs: + \TOCsetlinestyle {subsection} {\TOCnumwidthD}% + \TOCsetlinestyle {subsubsection}{\TOCnumwidthE}% + \TOCsetlinestyle {paragraph} {\TOCnumwidthF}% + \TOCsetlinestyle {subparagraph} {\TOCnumwidthG}% +}% end of \TOClocalstyle +\makeatother +\end{filecontentshere} +\marginattach -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. +As mentioned previously, this handles non-numbered (multi-line) sectioning +units somewhat differently from what happens in the standard document classes. -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. +For some reason this code has some hard-coded |2.25em| and |4.5em| which were +not abstracted into macros or lengths. The code inserts horizontal rules above +and below the TOC contents in a non-separable by pagebreak way. -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). +See \autoref{sec:thirdexampleextra} for more. -% 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}. +\section{A framed display} -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.} +We now opt for a ``framed'' style, using the package default +line styles and some colors added (it has been put in a float which appears +\vpageref{toc:b}). -\clearpage -\etocdepthtag.toc {custom} +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +\etocdefaultlines +\begingroup +\renewcommand{\etoccolumnsep}{2em} +\renewcommand{\etocinnerleftsep}{1.5em} +\renewcommand{\etocinnerrightsep}{1.5em} +% specify a background color for the toc contents +\renewcommand{\etocbkgcolorcmd}{\color{yellow!10}} +% set up the top and bottom rules +\renewcommand{\etoctoprule}{\hrule height 1pt} +\renewcommand{\etoctoprulecolorcmd}{\color{red!25}} +\renewcommand{\etocbottomrule}{\hrule height 1pt} +\renewcommand{\etocbottomrulecolorcmd}{\color{red!25}} +% set up the left and right rules +\renewcommand{\etocleftrule}{\vrule width 5pt} +\renewcommand{\etocrightrule}{\vrule width 5pt} +\renewcommand{\etocleftrulecolorcmd}{\color{red!25}} +\renewcommand{\etocrightrulecolorcmd}{\color{red!25}} +% use \fcolorbox to set up a colored frame for the title +\fboxrule1pt +\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 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:tocstyle} +\end{figure} +\endgroup +\end{filecontentshere} +\marginattach -\part{Using and customizing the \etoc own styles} -\label{part:custom} +\filecontentsexec\filecontentsheremacro -\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{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 +table of contents fits on a single page. We wrap it up in a +\hyperref[toc:floating]{figure environment} showing up +\vpageref{toc:floating}. -\section{Summary of the main style commands} +This design uses the \etoc `framed' style with a background color. The frame +borders have been set to have the same color as the one serving as background +for the entire thing. It would be advantageous to use rather inside +\csb{etocsettocstyle} commands from a package like |tcolorbox| as this allows +sophisticated breakable boxes (with |TikZ/pgf| for decoration.) -\subsection{Setting up local styles} +The details of the line styles used here are a bit involved, they were written +by the author at some early stage of this documentation and have only been +slightly revised to use more \LaTeX-commands and less \TeX-primitives. Similar +code is used also for \hyperref[toc:clone]{this other toc}. -\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} +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +\begin{figure}[htbp!]\centering +\colorlet{subsecnum}{black} +\colorlet{secbackground}{green!30} +\colorlet{tocbackground}{red!20!green!20} -\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}}}} +\renewcommand{\etocbkgcolorcmd}{\color{tocbackground}} +\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}} +\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}} +\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}} +\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}} -\subsection{Displaying tables of contents} +\renewcommand{\etocleftrule}{\vrule width 3cm} +\renewcommand{\etocrightrule}{\vrule width 1cm} +\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} -\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} - }}} +\etocsetstyle{subsubsection} +{\etocskipfirstprefix} +{\shiftedwhiterule{\leftskip}{6pt}} +{\sffamily\footnotesize + \leftskip2.3cm\hangindent1cm\rightskip.5cm\relax + \makebox[1cm][l]{\color{subsecnum}\etocnumber}% + \color{black}\etocname + \nobreak\leaders\hbox to.2cm{\hss.}\hfill + \rlap{\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}\par + \nointerlineskip\vskip3pt} +{} + +\etocsetstyle{subsection} +{\etocskipfirstprefix} +{\shiftedwhiterule{1.5cm}{6pt}} +{\sffamily\small + \leftskip1.5cm\hangindent.8cm\rightskip.5cm\relax + \makebox[.75cm][l]{\color{subsecnum}\etocnumber}% + \color{black}\etocname + \nobreak\leaders\hbox to.2cm{\hss.}\hfill + \rlap{\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}\par + \nointerlineskip\vskip3pt} +{} + +\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{blue}{\hfil \bfseries\large Contents of Part One\hfil}} +{\vskip3pt\sffamily\small} +{\coloredstuff{blue} + {\leftskip1.5cm\rightskip.5cm\parfillskip-\rightskip + \makebox[0pt][r]{\makebox[.5cm][l]{\etocnumber}}% + \etocname\nobreak\hfill\makebox[.5cm][r]{\etocpage\hspace{.1cm}}}% + \vskip6pt} +{} + +\etocframedstyle[1]{} +\tableofcontents \label{toc:floating} \ref{toc:part:styling} +\vspace{-\baselineskip} +\centeredline{|\tableofcontents \ref{toc:part:styling}| +(\emph{cf.} \hyperref[toc:clone]{this other toc})} +\end{figure} +\end{filecontentshere} +\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 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). + +%%%% Note: 27 april 2014 + +%%%% except for a miraculous situation depending from the quantity of previous +%%%% material this TOC will have links extending accross pagebreaks, which +%%%% dvipdfmx does not know how to handle completely. Apart from that the output +%%%% is ok, thus no need to try seriously to avoid them. + +\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} +\begingroup +\newsavebox{\forsubsections} +\etocsetstyle{part}{\upshape. \etocskipfirstprefix} + {. \upshape} + {\bfseries\etocname:~~} + {} +\etocsetstyle{section}{\itshape\etocskipfirstprefix} + {, } + {\mdseries\etocname} + {} +\etocsetstyle{subsection} + {\begin{lrbox}{\forsubsections}\footnotesize\upshape\etocskipfirstprefix} + {; } + {\etocname} + {.\end{lrbox}\footnote{\unhbox\forsubsections}} +\etocsetstyle{subsubsection} + { (\itshape\etocskipfirstprefix} + {, } + {\etocname} + {\/\upshape)} +\etocsettocstyle{Here is the inline table of contents. }{.\par} +\tableofcontents \label{toc:crazyinline} +\endgroup +\end{filecontentsdef} + +\filecontentsexec\foo + +The code used: +\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 {advanced} +\part{Advanced examples} +\label{part:surprising} + +\thispartstats %% (pas de sous-section) + +\etocdefaultlines +\etocsettocstyle {}{} +\localtableofcontents + +\section{The TOC of TOCs} +\label{sec:tocoftocs} + +\begingroup % \endgroup just after the \tableofcontents command +\etocinline +\etocsetlevel{part}{1} +\etocsetlevel{visibletoc}{0} +\etocsetstyle{visibletoc} + {\etocskipfirstprefix} + {, } + {{\color{niceone}\etocname}} + {} +\etocsettocstyle{}{} +\etocsetnexttocdepth{visibletoc} + + +Here is the numbered and linked list of all tables of contents which are +displayed within this document:\footnote{The TOCs put in + floats may change the order: the numbers are listed + 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 +it here we just wrote:\par\smallskip +{\leftskip1cm\rightskip2cm + \ttfamily\small\baselineskip11pt \noindent Here is the + numbered and linked list of all tables of contents which are + displayed within this + document:~\string\tableofcontents.\par} + + The preparatory work was the following. First, we defined a + counter |visibletoc| whose vocation is to get incremented at + each displayed toc. \etoc has its own private counter but it + counts all TOCs, even those not displayed because the |tocdepth| + value was |-2| or |-3|. + + We could have added manually |\refstepcounter{visibletoc}| + and |\label| commands at all suitable locations in the + document source, and we would then have used here |\ref| + commands, but this imposes heavy manual editing of the source. + + There is a much better way: there is a hook + \csb{etocaftertitlehook} and we told it to increment the + |visibletoc| counter and to write a line to the |.toc| file, + in a manner analogous to what sectioning commands such as + |chapter|, |section|, or |subsection| do. As \etoc + increments its own private counter even before typesetting + the title of a table of contents, this provides (most of the + time) a better link destination than any counter manipulated + from inside \csb{etocaftertitlehook} (for which the link + would target the area just after the title). So, rather than + including |\refstepcounter{visibletoc}| inside + \csb{etocaftertitlehook}, we just put there + |\stepcounter{visibletoc}| followed by the command + \csb{etoctoccontentsline}|{visibletoc}{\thevisibletoc}|. This \etoc + command \csb{etoctoccontentsline}\marg{level\_name}\marg{name} has the same + effect as: + \centeredline{| ||\addcontentsline{toc}|\marg{level\_name}\marg{name}} + but its usefulness is to circumvent\footnote{using \csa{addtocontents} rather + than \csa{addcontentsline}} the patching for automatic creation + of bookmarks done to \csa{addcontentsline} by the \ctanpkg{hyperref} package, + as pdf bookmarks don't make + much sense here (and would elicit a complaint + of \ctanpkg{hyperref} that the bookmark level is `unknown').\footnote{% + The package provides a starred variant + \staritb{etoctoccontentsline}, which does allow the creation + of bookmarks and has a third mandatory argument which is the + Level to be used by these bookmarks; depending on the context + the starred as well as the non-starred variants may be + profitably preceded by \csa{phantomsection}.} + + Finally, the preamble of the document did + |\etocsetlevel{visibletoc}{6}|. The level |6| (or anything + with a higher number) is ignored, even if |tocdepth| has + value |10| for example; this is independently of whether \etoc + uses the document class default line styles or its own line + styles, or the ones defined by the user with the + \csb{etocsetstyle} command. So there is no need to worry that + something could go wrong. + + 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% +% +\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. + +Here are the implementation details: + +\begingroup +\begin{filecontentshere}{etocsnippet-\snippetno.tex} + < in the preamble > +\newcounter{visibletoc} +\renewcommand{\etocaftertitlehook} + {\stepcounter{visibletoc}\etoctoccontentsline{visibletoc}{\thevisibletoc}} +\etocsetlevel{visibletoc}{6} +\begin{document} + < document body > +\subsection{Surprising uses of etoc} +\begingroup + \etocinline + \etocsetlevel{part}{1} + % \etocsetlevel{chapter}{1} % (no chapters in scrartcl class) + \etocsetlevel{visibletoc}{0} + \etocsetstyle{visibletoc} + {\etocskipfirstprefix}{, }{{\color{niceone}\etocname}}{} + \etocsettocstyle{}{} % don't set any title, rules or frame or multicol! + \etocsetnexttocdepth{visibletoc} % display only the `visibletoc' entries from .toc + +Here is the numbered and linked list of all tables of contents which are +displayed within this document: \tableofcontents. +\endgroup +\end{filecontentshere} +\marginattach +\endgroup + +After |\etocsetstyle{visibletoc}{..}{..}{..}{..}|, all future TOCs (not in +compatibility mode) will use the +defined style for level |0| (which is normally the level for +chapters). To keep these changes strictly local the simplest +manner is to put everything inside a group. + +The \autoref{subsec:interverting} gives another use of the +shuffling of levels. + + +\section[Arbitrary ``Lists Of...'', \csbhyp{etoctoccontentsline}]{% + Arbitrary ``Lists Of...'', \csbhyp{etoctoccontentsline} and + \csbhyp{etocimmediatetoccontentsline}} +\label{etoctoccontentsline} +\label{etocimmediatetoccontentsline} + +This idea of interverting the levels is very powerful and allows +to let \etoc display lists of arbitrary things contained in the +document. All of that still +using nothing else than the |.toc| file! +Example: imagine a document with dozens of +exercises, perhaps defined as |\newtheorem{exercise}{}[section]|. Let +us explain how to instruct \etoc to display an hyperlinked list +of all these exercises. For this we put in the preamble: +\begin{verbatim} + \newtheorem{exerci}{}[section] + % the exercice number will be recoverable via \etocname: v--here--v + \newcommand*{\exercisetotoc}{\etoctoccontentsline{exercise}{\theexerci}} + \newenvironment{exercise}{\begin{exerci}\exercisetotoc}{\end{exerci}} + \etocsetlevel{exercise}{6} +\end{verbatim} +In this way, \csb{etocname} will give the exercise number (but \csb{etocnumber} +will be empty). Had we used instead +\begin{verbatim} + \newcommand*{\exercisetotoc} + {\etoctoccontentsline{exercise}{\protect\numberline{\theexerci}}} +\end{verbatim} +the exercise number would then have been available via \csb{etocnumber}, and +\csb{etocname} would have been empty. It doesn't matter which one of the two +methods is used. The \etoc command \csb{etoctoccontentsline}|{..}{..}| is +provided as a substitute to \csa{addcon\-tentsline}|{toc}{..}{..}|: this is to +avoid the patching which is done by \ctanpkg{hyperref} to \csa{addcontentsline} in its +process of creation of bookmarks. If one wants to authorize \ctanpkg{hyperref} to create +bookmarks at a specific level \meta{n}, one can use (here with \meta{n}$=$|2|) +the starred variant \starit{etoctoccontentsline} which has an additional +argument: +\begin{verbatim} +\newcommand{\exercisetotoc}{\etoctoccontentsline*{exercise}{\theexerci}{2}} +\end{verbatim} + +The counter |exerci| is already +incremented by the |exerci| theorem environment, and +provides the correct destination for the link added by package +\ctanpkg{hyperref}. The command \csa{exercisetotoc} adds for each exercise a line +to the |.toc| file, corresponding to a fictitious document +unit with name `|exercise|'. A +four-column list, including the sections, can then be +typeset with the following code: +\begin{filecontentshere}{etocsnippet-\snippetno.tex} + \etocsetnexttocdepth{2} % sections are at level 1 and will show up +\begingroup + \etocsetlevel{exercise}{2} % but: + \etocsetlevel{chapter}{3} % no chapters + \etocsetlevel{subsection}{3} % no subsections + \etocsetlevel{part}{3} % no parts + \etocsetstyle{exercise}{}{} % \etocname = exercise number + {\noindent\etocname\strut\leaders\etoctoclineleaders\hfill\etocpage\par} + {\pagebreak[2]\vskip\baselineskip} + \etocsetstyle{section}{}{} + {\noindent\strut{\bfseries\large\etocnumber\hskip.5em\etocname}\par + \nopagebreak[3]}{} + \etocruledstyle[4]{\Large\bfseries List of the exercises} + \setlength{\columnseprule}{.4pt} + \tableofcontents +\endgroup +\end{filecontentshere} +\marginattach -\subsection{Labels and references} -\label{ssec:labelref} +A related command \csb{etocimmediatetoccontentsline} (and its starred version) +is also provided. For discussion and the meaning of ``immediate'', refer to +the analogous case of \csb{etocimmediatedepthtag.toc}. -The commands (starred or not) to actually display the table of contents -can be followed with optional labels or references:\par +\section{The TOC as a tree}\label{tocastree} -\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 . . . } - }}} +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? -\medskip +We need to store, not the macro names, but the macro contents. And also we wish +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 \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.} -%New with |1.08e|: +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 +macro |\appendtotok| whose r\^ole is to append to a given token list variable +the contents of a macro given as second argument. All this will happen in +reaction to a |\tableofcontents| command, but \emph{nothing} has yet been +printed in the process.\footnote{There is always a \csa{par}, which here is not +a problem, but can be suppressed if need be via the command \csb{etocinline} or +its synonym \csb{etocnopar}.} This is the later job of a |forest| environment +which will be given the contents of |\treetok|. -\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. +\let\appendtotok\relax +\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}} -\section{The package default line styles: \csbhyp{etocdefaultlines}} -\label{etocdefaultlines} +\newcommand*\PrepareSectionNode{% + \tmptok {\centering\bfseries}% + \appendtotok\tmptok\etocthelinkedname + \edef\foresttreenode{ [{\noexpand\parbox{2cm}{\the\tmptok}}}% +} -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. +\newcommand*{\PrepareSubsectionNode}{% + \tmptok {\raggedright}% + \appendtotok\tmptok\etocthelinkedname + \edef\foresttreenode{ [{\noexpand\parbox{6cm}{\the\tmptok}}}% +} -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. +\etocsetstyle{section} + {\etocskipfirstprefix} + {\appendtotok\treetok{ ]}} + {\PrepareSectionNode \appendtotok\treetok\foresttreenode} + {\appendtotok\treetok{ ]}} -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. +\etocsetstyle{subsection} + {\etocskipfirstprefix} + {\appendtotok\treetok{ ]}} + {\PrepareSubsectionNode \appendtotok\treetok\foresttreenode} + {\appendtotok\treetok{ ]}} -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. +\etocsettocstyle + {\treetok{[{\hyperref[part:styling]{The \etoc styling commands}}}} + {\global\appendtotok\treetok{ ]}} +% forest does not like @\the\treetok if \treetok is empty. On first latex +% run, this will be the case because the TOC style defined above will not +% have been executed, as the label {toc:overview} does not refer to a valid +% TOC yet. So we must give a safe default value to \treetok +\treetok{[{run latex again}]} -\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 +\begin{figure}[htbp!] +\centering + \etocsetnexttocdepth{subsection} + \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=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{filecontentshere} -\marginattach{} +\end{filecontentsdef} +\filecontentsexec\foo -\filecontentsexec\filecontentsheremacro +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: \filecontentsprintviascan\foo \marginattach -\section{Customizing \etoc} +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 +%\csa{hypersetup}\texttt{\{hidelinks\}} % ok pour hyphénation +%\csa{hypersetup}|{hidelinks}| % pas ok +|\hypersetup{hidelinks}| % ok maintenant 12 octobre 2013 + in the |.toc| file. But at the time the +|\treetok| contents are unpacked the |\hyperlink| commands +originating in +|\etocthelinkedname|, etc\dots{} will be executed in the normal +environment for links (which, in this document, is to colorize +them). Rather than having \etoc's code try to guess what the current ``style'' +for links is (a concept not really provided by \ctanpkg{hyperref} it +seems) and store it in |\etocthelinkedname|, etc\dots, I opted for +the simpler solution to leave it up to the user to recreate +whatever conditions are desired. So here it is necessary to re-issue +|\hypersetup{hidelinks}| in the |figure| environment. -\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} +There are some other examples in this documentation where +|\tableofcontents| is used to prepare material for later +typesetting: +\begin{itemize} +\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 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} -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} +\section{The TOC as a molecule}\label{sec:molecule} -\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} +It is also possible to construct a TOC tree obeying the TikZ +syntax for trees: but this is a more complicated task for the +\etoc line styles for reasons related to the way braces are +handled by \TeX{} (they need, when filling up the token list to be +always balanced at each step, else complicated tricks must be +employed.) -\newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil} -\newcommand*\etocminustworightmargin{1.5em plus -0.5fil} -\newcommand*\etocminusoneleftmargin{1em} -\newcommand*\etocminusonerightmargin{1em} +The simplest strategy is to allocate a token list (or use a macro) for each +level used: we may need a \csa{parttok}, a \csa{chaptertok}, a +\csa{sectiontok} and a \csa{subsectiontok}, to help in the task of filling +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. -\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} +\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\subsectiontok +% \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}} -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.} +% 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 once (needed) + \edef\treenode{node {\the\tmptok}}% +} +\etocsetstyle{subsection} + {\etocskipfirstprefix} + {\appendchildtree\treetok\subsectiontok} + {\preparetreenode + \subsectiontok\expandafter{\treenode}} + {\appendchildtree\treetok\subsectiontok} -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} . . .). +\etocsetstyle{subsubsection} + {\etocskipfirstprefix} + {\appendchildtree\subsectiontok\subsubsectiontok} + {\preparetreenode + \subsubsectiontok\expandafter{\treenode}} + {\appendchildtree\subsectiontok\subsubsectiontok} -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. +\etocsettocstyle + {\treetok{\node {\hyperref[sec:linestyles]{Line styles}}}} + {\global\appendtotok\treetok{ ;}} -\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} +\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{filecontentshere} +\marginattach -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} +\filecontentsexec\filecontentsheremacro -\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} +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}. -\newcommand*\etocbkgcolorcmd{\relax} +% 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] -% hooks -\newcommand\etocframedmphook{\relax} -\end{verbatim} +% ! Package varioref Error: \vref or \vpageref at page boundary 65-66 (may loop). -The \csa{etocframedmphook} is positioned immediately -after the beginning of a minipage environment where the -contents of the framed TOC are typeset. +% See the varioref package documentation for explanation. +% Type H for immediate help. +% ... + +% l.6114 appears \vpageref{toc:mindmap} -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}. +% mais ça n'a pas suffit. Bon 10 minutes de perdues je vais déplacer la ligne. -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. +\enlargethispage{3\baselineskip} +Another example: -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. +\etocsettocstyle + {\treetok{\node {\autoref{sec:tocstyle}}}} + {\global\appendtotok\treetok{ ;}} -\section{One more example of colored TOC layout} -\label{ssec:tocclone} +\etocsetnexttocdepth {subsubsection} +\tableofcontents \ref{toc:tocstyle} -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. +\centeredline{% +\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} +}% +% +The above is the fully hyperlinked table of contents of +\autoref{sec:tocstyle}. -\begin{filecontentshere}{etocsnippet-\snippetno.tex} -\begingroup -\definecolor{subsecnum}{RGB}{13,151,225} -\definecolor{secbackground}{RGB}{0,177,235} -\definecolor{tocbackground}{RGB}{212,237,252} +\section{The TOC as a TikZ mind map} +\label{sec:mindmap} -\renewcommand{\etocbkgcolorcmd}{\color{tocbackground}} -\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}} -\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}} -\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}} -\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}} +This is in the same spirit as the ``molecule'' example. The use of the \eTeX{} +primitive \csa{unexpanded} will simplify the code.% +% -\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} +\let\partnode\relax +\let\childnode\relax +\let\appendtotok\relax +\let\appendchildtree\relax +\expandafter\let\csname c@partco\endcsname\relax -\newcommand\shiftedwhiterule[2]{% - \hbox to \linewidth{\color{white}% - \hskip#1\leaders\vrule height1pt\hfil}\nointerlineskip\vskip#2} +\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} +% \newtoks\treetok % done in preamble +% \newtoks\parttok +\newcommand*\partnode {} % check with \newcommand we will not overwrite something +\newcommand*\childnode {} -\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} - {} +\newcommand*\tmprotate {} % (idem) +\newcommand*\tmpoption {} % +\newcommand*\tmpstuff {} % -\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*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2 + #1\expandafter\expandafter\expandafter{\expandafter\the\expandafter #1#2}} -\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} +\newcommand*{\appendchildtree}[3]{% +% this is to construct "t1 child [#3]{t2}" from #1=t1 and #2=t2 +% t1 and t2 are two toks variable (not macros) +% #3 = for example teal!60 + \edef\tmpstuff {\the#1 child [#3]{\the#2}}% + #1\expandafter {\tmpstuff }% +} + +\newcounter{partco} + +% 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} + +\etocsetstyle{part} + {\etocskipfirstprefix} +% This updates the global tree with the data from the previous +% part and all its children sections. Moved here because for some parts the +% sections are not displayed due to depth tags. + {\ifnum\value{partco}=3 + \appendchildtree\treetok\parttok {branch color= green!50,level distance=10cm}% + \else +\ifcase\pseudomodthree{\value{partco}}% + \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 + } + {\stepcounter{partco}% +% customize manually some TikZ set-up (should be done inside the TikZ thing I guess) + \def\tmpoption {}% + \def\tmprotate {}% first + %\ifnum\value{partco}=5 \def\tmprotate {[counterclockwise from =-40]}\fi + %\ifnum\value{partco}=8 \def\tmprotate {[counterclockwise from =-50]}\fi +% define the part node + \edef\partnode{node \tmpoption + {\unexpanded\expandafter{\etocthelinkednumber}. + \unexpanded\expandafter{\etocthelinkedname}}\tmprotate }% +% this is a starting point which will be filled it by the section children + \parttok\expandafter{\partnode}} + {\ifcase\pseudomodthree{\value{partco}}% + \or \appendchildtree\treetok\parttok {branch color= teal!60}% first + \or \appendchildtree\treetok\parttok {branch color= yellow!80}% second + \else\appendchildtree\treetok\parttok {branch color= green!50}% third and next ... + \fi + } \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 } -{} + {} + {} + {% define the section node + \edef\childnode{child {node {\unexpanded\expandafter{\etocthelinkednumber} + \unexpanded\expandafter{\etocthelinkedname}}}}% + % append it to the current \parttok + \appendtotok\parttok\childnode + } + {} -\etocframedstyle[1]{} -\tableofcontents \label{toc:clone} \ref{toc:globalcmds} -\endgroup -\end{filecontentshere} -\marginattach{} +\etocsettocstyle + {\setcounter{partco}{0}% + \treetok{\node [root concept]{\textbf{The \etoc documentation}}}} + {\global\appendtotok\treetok{ ;}} +% The \global above is mandatory because etoc always typesets TOC inside a group -\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. +\etocsetnexttocdepth{section} +% 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 {styling} {part} +\etocsettagdepth {control} {part} +\etocsettagdepth {examples} {part} +\etocsettagdepth {advanced} {part} +\etocsettagdepth {etocandworld}{part} +\etocsettagdepth {code} {section} -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. +\tikzset{ + branch color/.style={ + concept color=#1!white, + every child/.append style={concept color=#1!white!30!white, font=\normalsize}, + } +}% -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. +\begin{figure}[htbp!] +\etocobeydepthtags % obey the depth tags restrictions (which is default anyhow) +\tableofcontents\label{toc:mindmap}% +\centeredline{\resizebox{.85\paperwidth}{!}% +{\begin{tikzpicture}[mindmap, + grow cyclic, + text width=2cm, + align=flush center, + nodes={concept}, + concept color=orange!60, + root concept/.append style={text width=4cm, font=\Large}, + 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} +\end{filecontentsdef} +\filecontentsexec\foo -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. +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}. -\clearpage -\etocdepthtag.toc {tips} +% The fully hyperlinked TOC +% appears \vpageref{toc:mindmap}. -\part{Tips} -\label{part:tipsandtricks} +\filecontentsprintviascan\foo +\marginattach -\thispartstats +The fully hyperlinked TOC appears \vpageref{toc:mindmap}. -%%%% \invisiblelocaltableofcontents \label{toc:tipsandtricks} +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 +document. Things written to the |.log| file get broken into lines. Here is a +technique to get non-broken output. Once the \csa{treetok} has been computed +by \etoc (as in the \hyperref[toc:molecule]{molecule} example, or the current +example), this demo will write it out to file with extension +|.toctree|: +\begin{verbatim} + \newwrite\TOCasTree + \immediate\openout\TOCasTree=\jobname.toctree + \immediate\write\TOCasTree{\the\treetok}% +\end{verbatim} -\etocsettocstyle{}{} -\etocstandardlines -\localtableofcontents -%\section{... and tricks} +\section{The TOC as a (long) table} +\label{sec:tocastable} -% pas traduit -\section{The \csbhyp{etoclocaltop} command} -\label{etoclocaltop} +% 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 |\\|. -%\textbf{New with 1.09 (2019/03/09)}. +But there are some conditions and a few caveats: +\begin{enumerate} +\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}). +\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 + that at the end with the idea to close the \emph{current} row; + and when the TOC is a partial one (a \csa{localtableofcontents}) this + is (in almost all situations) mandatory. +\end{enumerate} -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. +Here is an example of a TOC as a |longtable|. Yes this is only \emph{one} table! +The code follows. -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{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} +\begingroup +\etocglobaldefs % necessary for \etocname etc... to survive & +\makeatletter +% hack into longtable \hline to avoid annoying (here) stray lines at top +\def\LT@@hline{% + \ifx\@let@token\hline + \global\let\@gtempa\@gobble + \global\let\@gtempb\@firstofone %%% ADDED + \gdef\LT@sep{\penalty-\@medpenalty\vskip\doublerulesep}% + \else + \global\let\@gtempa\@empty + \global\let\@gtempb\@gobble %%% ADDED + \gdef\LT@sep{\penalty-\@lowpenalty\vskip-\arrayrulewidth}% + \fi + \ifnum0=`{\fi}% + \multispan\LT@cols + \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr + \@gtempb{% %%% ADDED + \noalign{\LT@sep}% + \multispan\LT@cols + \unskip\leaders\hrule\@height\arrayrulewidth\hfill\cr + \noalign{\penalty\@M}% + }% %%% ADDED + \@gtempa} +\makeatother -\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. +% observe the locations of the \\ +\etocsetstyle{part} + {} + {} + {\\\hline\multicolumn{3}{c}{\bfseries\vrule height6ex depth3ex width0pt + \makebox[0pt]{\etocifnumbered{\etocnumber. }{}\etocname}}} + {} - For a global table of contents however, it will always keep the value |-3|. -\end{framed} +\etocsetstyle{section} + {} + {\etociffirst{\\\hline}{\\}} + {\etocnumber&\etocname &\etocpage } + {} -Attention! \cs{etoclocaltop} is only to be queried; modifying it is strictly -forbidden and falls under the most rigorous prosecution allowed by federal -law. +\etocsetstyle{subsection} + {} + {\\} + {&\makebox[1cm][c]{\etocnumber}% + \parbox[t]{\dimexpr6cm-\tabcolsep\relax}{\sloppy\itshape\etocname\strut}% + &\itshape\etocpage } + {} -\section[The \csbhyp{etocsetlocaltop.toc} command] - {The \csbhyp{etocsetlocaltop.toc} and - \csbhyp{etocimmediatesetlocaltop.toc} commands} -\label{etocsetlocaltop.toc} -\label{etocimmediatesetlocaltop.toc} +\etocsettocstyle + {\hypersetup{hidelinks}% + \begin{longtable}{|>{\bfseries}c|p{7cm}|r|} + \hline + \multicolumn{3}{|c|}{\Large\bfseries\strut\strut TABLE OF CONTENTS}% + } + {\\\hline\end{longtable}} -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} +\etocsetnexttocdepth {subsection} -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: +\tableofcontents +\endgroup +\end{filecontentsdef} -\begin{verbatim} -\part*{Extra unnumbered part} -\etocsetlocaltop.toc{part} -\localtableofcontents -\end{verbatim} +\filecontentsexec\foo -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}|. +\filecontentsprintviascan\foo +\marginattach -As a (counter)-example consider this document: -\begin{verbatim} -\documentclass{article} -\usepackage{etoc} -\begin{document} -\tableofcontents +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 +for local tables of contents) one may indeed construct +TOC-as-tables with the |\\| located at the end of the style +specifications. The problem in the previous example was with the +positioning of the |\hline|'s. -\part*{A} -\etocsetlocaltop.toc{part} -\localtableofcontents +Due to technical aspects of how \TeX{} constructs alignments any +definition or assignment done after an |\\| starts a new row, and +thus makes |\hline| an illegal token (this shows as a |misplaced +\noalign| error.) Not only does \etoc have to do such definitions +to construct \csb{etocname} etc..., it is furthermore the case that +some packages put things in the |.toc| file and as a result there +is never any guarantee that between two \csa{contentsline} there +will not be such a token like |\relax| which in the contexts of +alignments forces \TeX{} to start a cell and thus makes it +impossible then to insert an |\hline|. -\section{I} +The safest way is thus to start with an |\\| each line style +specification in order to close the \emph{previous} table row. We +had a little problem with the fact that we wanted parts not only +to have a rule above them (easy, they do |\\\hline|) but also +below them: after each part there is a section, and it is these +sections which are used to insert the missing |\hline| +(this is done with the help of the \csb{etociffirst} +conditional). -\section{II} -\part*{B} +Last technical note: because we put the |\\\hline| inside the branches, there +was no need to employ the expandable variants \csb{etocxiffirst} and +\csb{etocxifnumbered}. -\section{III} +For the hardliner's old way see \autoref{ssec:tocastableold}. -\part*{C} +Here is also a much simpler example. It is a local table of +contents. -\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). +\begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} +\begin{center} +\etocsetstyle{section} + {} + {\etociffirst{\\\hline\hline}{\\\hline}} + {\etocname & \etocnumber & \etocpage } + {} -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. +\etocsettocstyle + {\hypersetup{hidelinks}\begin{tabular}{|>{\RaggedRight}p{4.5cm}|c|c|}\hline + \multicolumn{1}{|c|}{\bfseries Section title}& + \bfseries number& + \bfseries page} + {\\\hline\end{tabular}} -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). +\etocglobaldefs % MANDATORY !! +\etocsetnexttocdepth{1} -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. +\tableofcontents\ref{toc:overview} +\end{center} +\end{filecontentsdef} -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.} +\filecontentsexec\foo -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. +\filecontentsprintviascan\foo +\marginattach -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{A TOC self-adjusting widths for its typesetting} +\label{sec:thirdexampleextra} -\section{Hacking framed parboxes} +This is a continuation of \autoref{sec:thirdexample}. The goal is to adjust +automatically the ``numwidths'' used for typesetting the unit numbers in the +(local) tables of contents. +\begin{filecontentshere}{etocsnippet-\snippetno.tex} +\makeatletter +\newcommand*\TOCcompute@numwidths [2]{% #1=empty/"local", #2=minimal indent + \begingroup + \def\TOCnumwidthB {0pt}% + \def\TOCnumwidthC {0pt}% + \def\TOCnumwidthD {0pt}% + \def\TOCnumwidthE {0pt}% + \def\TOCnumwidthF {0pt}% + \def\TOCnumwidthG {0pt}% + \etocsetstyle{part}{}{}{}{}% + \etocsetstyle{chapter}{} + {\setbox0\hbox{\bfseries\etocthenumber\kern#2}} + {\ifdim\wd0>\TOCnumwidthB\edef\TOCnumwidthB{\the\wd0}\fi}{}% + \etocsetstyle{section}{} + {\setbox0\hbox{\bfseries\etocthenumber\kern#2}} + {\ifdim\wd0>\TOCnumwidthC\edef\TOCnumwidthC{\the\wd0}\fi}{}% + \etocsetstyle{subsection}{} + {\setbox0\hbox{\etocthenumber\kern#2}} + {\ifdim\wd0>\TOCnumwidthD\edef\TOCnumwidthD{\the\wd0}\fi}{}% + \etocsetstyle{subsubsection}{} + {\setbox0\hbox{\etocthenumber\kern#2}} + {\ifdim\wd0>\TOCnumwidthE\edef\TOCnumwidthE{\the\wd0}\fi}{}% + \etocsetstyle{paragraph}{} + {\setbox0\hbox{\etocthenumber\kern#2}} + {\ifdim\wd0>\TOCnumwidthF\edef\TOCnumwidthF{\the\wd0}\fi}{}% + \etocsetstyle{subparagraph}{} + {\setbox0\hbox{\etocthenumber\kern#2}} + {\ifdim\wd0>\TOCnumwidthG\edef\TOCnumwidthG{\the\wd0}\fi}{}% + % + \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 + }% make the found maximal widths have global scope + \etocnopar + \csname #1tableofcontents\endcsname +\typeout{Next TOCs will use \TOCnumwidthB\space for chapter number width}% +\typeout{Next TOCs will use \TOCnumwidthC\space for section number width}% +\typeout{Next TOCs will use \TOCnumwidthD\space for subsection number width}% +\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 % matches \begingroup at start of definition +}% +\newcommand*\TOCcomputenumwidths [1][0.5em]{% + \TOCcompute@numwidths {}{#1}% +}% +\newcommand*\TOCcomputelocalnumwidths [1][0.5em]{% + \TOCcompute@numwidths {local}{#1}% +}% +\makeatother +\end{filecontentshere} +\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 +\csa{TOCcomputelocalnumwidths} is provided. As the code makes global +assignments, either use (once) \csa{TOCcomputenumwidths} or do +\csa{TOCcomputelocalnumwidths} for each local table of contents. \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} + \TOCcomputelocalnumwidths % may use optional argument to replace 0.5em + \localtableofcontents \end{verbatim} +Notes: +\begin{enumerate}[nosep] +\item naturally these are only suggestions. For example one could put + everything in single macros \csa{TOCtoc} and \csa{TOClocaltoc} to + simultaneously compute the numwidths and then typeset the (local) table of + contents. +\item if you want to adjust the |tocdepth| recall from + \autoref{ssec:bookmarksdepth} that it influences \ctanpkg{hyperref} hence you may + need to use a group |\begingroup...\endgroup|. Or, one can use + \csb{etocsetnexttocdepth}\marg{level} but (with the code as here) this must + then be issued twice, once for \csa{TOCcomputelocalnumwidths}, once for + \csa{localtableofcontents}. +\item the bold font serves above for both chapter and section numwidth + computations, but the code from \autoref{sec:thirdexample} uses |\bfseries| + only in local TOCs. Thus the \csa{TOCcomputenumwidth} will set the parameter + \csa{TOCnumwidthC} to a value slightly larger than needed in the main TOC. + Hence the section style in \csa{TOCcompute@numwidths} should possibly insert + the |\bfseries| in the box only after testing for the optional parameter + |local|. +\end{enumerate} -\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@} 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). % % %<*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 |@| as aliases to || 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} -% 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@@ +% 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} +% 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@| 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@| 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@| 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 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}. +% +% 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{% + \ifEtoc@localtoc + \ifnum #1=#2\relax + \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 + \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 } -% \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. -% -% 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. -% \begin{macrocode} -\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\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 +\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 } -\let\etoc@startlocaltoc\@gobble % \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}{}?\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 + }% } -\@ifclassloaded{memoir}{} -{\@ifpackageloaded{tocloft} +\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}% +} +\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} +% 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 |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. +% \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 Binary files a/macros/latex/contrib/etoc/etoc.pdf and b/macros/latex/contrib/etoc/etoc.pdf differ diff --git a/macros/latex/contrib/pangram/README.md b/macros/latex/contrib/pangram/README.md index c68863edef..e7e2ff36a2 100644 --- a/macros/latex/contrib/pangram/README.md +++ b/macros/latex/contrib/pangram/README.md @@ -12,4 +12,4 @@ either version 1.3c of this license or (at your option) any later version. ------ -Copyright (C) 2022 by Zhang Tingxuan . +Copyright (C) 2022--2023 by Zhang Tingxuan . diff --git a/macros/latex/contrib/pangram/pangram.dtx b/macros/latex/contrib/pangram/pangram.dtx index 8c33d97955..eadba37cef 100644 --- a/macros/latex/contrib/pangram/pangram.dtx +++ b/macros/latex/contrib/pangram/pangram.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2022 by Zhang Tingxuan +% Copyright (C) 2022--2023 by Zhang Tingxuan % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either @@ -41,7 +41,7 @@ either version 1.3c of this license or (at your option) any later version. ------ -Copyright (C) 2022 by Zhang Tingxuan . +Copyright (C) 2022--2023 by Zhang Tingxuan . % % %<*internal> @@ -58,7 +58,7 @@ Copyright (C) 2022 by Zhang Tingxuan . \preamble - Copyright (C) 2022 by Zhang Tingxuan + Copyright (C) 2022--2023 by Zhang Tingxuan This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either @@ -124,8 +124,8 @@ Copyright (C) 2022 by Zhang Tingxuan . % % %<*driver> -\ProvidesFile{pangram.dtx}[2022/10/9 (c) Copyright 2022 by Zhang Tingxuan] -\documentclass{ltxdoc} +\ProvidesFile{pangram.dtx}[2023/03/01 (c) Copyright 2022--2023 by Zhang Tingxuan] +\documentclass{l3doc} \usepackage[letterpaper,left=5cm,right=4cm,top=4cm,bottom=4cm, includeheadfoot]{geometry} @@ -147,7 +147,7 @@ Copyright (C) 2022 by Zhang Tingxuan . \title{\leavevmode\hbox to 0pt{\hss\huge The quick brown fox jumps over the lazy dog\hss}\\ --- The \pkg{pangram} package} \author{Zhang Tingxuan} -\long\date{2022/10/9\quad Version 0.0b\thanks{\url{https://github.com/AlphaZTX/pangram} +\long\date{2023/03/01\quad Version 0.0c\thanks{\url{https://github.com/AlphaZTX/pangram} If you want to maintain this package, just contact me through GitHub issues or pull a request.}} @@ -199,7 +199,7 @@ request.}} % \begin{abstract} % Pangram is a phrase or sentence containing all letters in an alphabet, % usually used for testing fonts. One famous pangram is ``The quick brown -% fox jumps over the lazy dog''. This package provide a (somewhat) simple +% fox jumps over the lazy dog''. This package provides a (somewhat) simple % way for font designers or users to test fonts. % \end{abstract} % @@ -304,17 +304,16 @@ request.}} % \section{The source code} % \begin{macrocode} %<*package> +%<@@=pangram> \NeedsTeXFormat{LaTeX2e}[2022/06/01] -\ProvidesPackage{pangram}[2022/10/09 Pangram, a tool for testing fonts] +\ProvidesExplPackage{pangram}{2023/03/01}{0.0c}{a tool for testing fonts} % \end{macrocode} % Use a \opt{clist} to restore the sizes for \cs{pangram}, -% and an integer for its index (here we use \opt{index} instead -% of \opt{int}). +% and an integer for its index. % \begin{macrocode} -\ExplSyntaxOn -\clist_new:N \l_pangram_sizes_clist -\int_new:N \l_pangram_size_index -\clist_set:Nn \l_pangram_sizes_clist +\clist_new:N \l_@@_sizes_clist +\int_new:N \l_@@_size_index_int +\clist_set:Nn \l_@@_sizes_clist { 5pt, 7pt, 8pt, 9pt, 10pt, 11pt, 12pt, 14pt, 16pt, 18pt, 20pt, 22pt, @@ -323,56 +322,59 @@ request.}} % \end{macrocode} % Three pre-defined text classes (token lists) for \cs{pangram}. % \begin{macrocode} -\tl_const:Nn \c_pangram_text_default_tl - { The~quick~brown~fox~jumps~over~the~lazy~dog. ~ 0123456789 } -\tl_const:Nn \c_pangram_text_uppercase_tl - { THE~QUICK~BROWN~FOX~JUMPS~OVER~THE~LAZY~DOG. ~ 0123456789 } -\tl_const:Nn \c_pangram_text_glass_tl - { I~can~eat~glass~and~it~doesn't~hurt~me. } +\tl_const:Nn \c_@@_text_default_tl + { The ~ quick ~ brown ~ fox ~ jumps ~ over ~ the ~ lazy ~ dog. ~ 0123456789 } +\tl_const:Nn \c_@@_text_uppercase_tl + { THE ~ QUICK ~ BROWN ~ FOX ~ JUMPS ~ OVER ~ THE ~ LAZY ~ DOG. ~ 0123456789 } +\tl_const:Nn \c_@@_text_glass_tl + { I ~ can ~ eat ~ glass ~ and ~ it ~ doesn't ~ hurt ~ me. } % \end{macrocode} % \DescribeMacro{\NewPangramClass} % Use way equivalent to \cs{csname}\dots\cs{endcsname} to define % new text classes. % \begin{macrocode} -\NewDocumentCommand \NewPangramClass { m m } +\NewDocumentCommand \NewPangramClass { m +m } { - \exp_after:wN \tl_const:Nn \cs:w c_pangram_text_#1_tl \cs_end: { #2 } + \tl_const:cn { c_@@_text_#1_tl } { #2 } } % \end{macrocode} % Inner function for \opt{sizes} option. Here use the \pkg{xparse}'s new % \cs{IfBlankTF} mechanism to judge if the sizes should be reset. % \begin{macrocode} -\NewDocumentCommand \pangram_resetsizes:n { m } +\cs_new:Npn \@@_resetsizes:n #1 { - \IfBlankF {#1} { \clist_set:Nn \l_pangram_sizes_clist { #1 } } + \tl_if_blank:nF { #1 } + { + \clist_set:Nn \l_@@_sizes_clist { #1 } + } } % \end{macrocode} % The keys. % \begin{macrocode} \keys_define:nn { pangram } { - textclass.tl_set:N = \l_pangram_textclass_tl , + textclass.tl_set:N = \l_@@_textclass_tl , textclass.default:n = default , textclass.initial:n = default , - sizes.code:n = \pangram_resetsizes:n { #1 } , - linegap.skip_set:N = \l_pangram_linegap_skip , + sizes.code:n = \@@_resetsizes:n { #1 } , + linegap.skip_set:N = \l_@@_linegap_skip , linegap.default:n = 5pt plus 3pt minus 2pt , linegap.initial:n = 5pt plus 3pt minus 2pt , - tagskip.skip_set:N = \l_pangram_tagskip_skip , + tagskip.skip_set:N = \l_@@_tagskip_skip , tagskip.default:n = 5pt , tagskip.initial:n = 5pt , - tagfont.tl_set:N = \l_pangram_tagfont_tl , + tagfont.tl_set:N = \l_@@_tagfont_tl , tagfont.default:n = \ttfamily \footnotesize , tagfont.initial:n = \ttfamily \footnotesize , - font.tl_set:N = \l_pangram_font_tl , - before.tl_set:N = \l_pangram_before_tl , - after.tl_set:N = \l_pangram_after_tl , + font.tl_set:N = \l_@@_font_tl , + before.tl_set:N = \l_@@_before_tl , + after.tl_set:N = \l_@@_after_tl , } % \end{macrocode} % \DescribeMacro{\PangramSetup} % Set up the package in preamble. % \begin{macrocode} -\NewDocumentCommand \PangramSetup { m } +\NewDocumentCommand \PangramSetup { +m } { \keys_set:nn { pangram } { #1 } } % \end{macrocode} % \DescribeMacro{\pangram} @@ -387,44 +389,43 @@ request.}} % \end{macrocode} % Use a loop to get all of the entries in the sizes \opt{clist}. % \begin{macrocode} - \int_set:Nn \l_pangram_size_index { 0 } - \tl_use:N \l_pangram_before_tl + \int_set:Nn \l_@@_size_index_int { 0 } + \tl_use:N \l_@@_before_tl \int_do_while:nNnn - { \l_pangram_size_index } < { \clist_count:N \l_pangram_sizes_clist } + { \l_@@_size_index_int } < { \clist_count:N \l_@@_sizes_clist } { \mode_leave_vertical: - \int_incr:N \l_pangram_size_index % index++; + \int_incr:N \l_@@_size_index_int \hbox_to_zero:n { \hss - \tl_use:N \l_pangram_tagfont_tl - \clist_item:Nn \l_pangram_sizes_clist { \l_pangram_size_index } - \skip_horizontal:N \l_pangram_tagskip_skip + \tl_use:N \l_@@_tagfont_tl + \clist_item:Nn \l_@@_sizes_clist { \l_@@_size_index_int } + \skip_horizontal:N \l_@@_tagskip_skip } \hbox_to_zero:n { - \tl_use:N \l_pangram_font_tl + \tl_use:N \l_@@_font_tl \fontsize - { \clist_item:Nn \l_pangram_sizes_clist { \l_pangram_size_index } } + { \clist_item:Nn \l_@@_sizes_clist { \l_@@_size_index_int } } { \c_zero_dim } % \z@ \selectfont - \tl_use:c { c_pangram_text_ \tl_use:N \l_pangram_textclass_tl _tl } + \tl_use:c { c_@@_text_ \tl_use:N \l_@@_textclass_tl _tl } \hss } \int_compare:nNnT - { \l_pangram_size_index } = { \clist_count:N \l_pangram_sizes_clist } - { \skip_set:Nn \l_pangram_linegap_skip {0pt} } + { \l_@@_size_index_int } = { \clist_count:N \l_@@_sizes_clist } + { \skip_set:Nn \l_@@_linegap_skip { \c_zero_dim } } \par - \skip_vertical:N \l_pangram_linegap_skip + \skip_vertical:N \l_@@_linegap_skip } % \end{macrocode} % The loop ends here. % \begin{macrocode} - \tl_use:N \l_pangram_after_tl + \tl_use:N \l_@@_after_tl \clearpage \group_end: } -\ExplSyntaxOff % % \end{macrocode} \endinput \ No newline at end of file diff --git a/macros/latex/contrib/pangram/pangram.ins b/macros/latex/contrib/pangram/pangram.ins index 1c300da357..3fd124ad8a 100644 --- a/macros/latex/contrib/pangram/pangram.ins +++ b/macros/latex/contrib/pangram/pangram.ins @@ -6,7 +6,7 @@ %% %% pangram.dtx (with options: `install') %% -%% Copyright (C) 2022 by Zhang Tingxuan +%% Copyright (C) 2022--2023 by Zhang Tingxuan %% %% This work may be distributed and/or modified under the %% conditions of the LaTeX Project Public License, either @@ -33,7 +33,7 @@ \preamble - Copyright (C) 2022 by Zhang Tingxuan + Copyright (C) 2022--2023 by Zhang Tingxuan This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either diff --git a/macros/latex/contrib/pangram/pangram.pdf b/macros/latex/contrib/pangram/pangram.pdf index 008be5a8f8..e85cd74f26 100644 Binary files a/macros/latex/contrib/pangram/pangram.pdf and b/macros/latex/contrib/pangram/pangram.pdf differ diff --git a/macros/latex/contrib/qrbill/README.md b/macros/latex/contrib/qrbill/README.md index 03eff67b34..3888da81b2 100644 --- a/macros/latex/contrib/qrbill/README.md +++ b/macros/latex/contrib/qrbill/README.md @@ -1,10 +1,10 @@ # qrbill – create QR-bills based on the swiss payment standard -Copyright (C) Marei Peischl (peiTeX) , 2020–2022 +Copyright (C) Marei Peischl (peiTeX) , 2020–2023 This work is part of a collaborative project of Marei Peischl (peiTeX) and Alex Antener (foobar LLC). -qrbill 2022/10/20 v1.07 +qrbill 2023/02/28 v2.00 *************************************************************************** @@ -79,4 +79,6 @@ For further information on l3build and other options please have a look at the c - add possibilities to ignore data fields if empty - allow the usage of commas within the billing info * v1.07 (2022-10-20) - - fix utf8 encoding für qrmode=package \ No newline at end of file + - fix utf8 encoding für qrmode=package + * v2.00 (2023-02-28) + - add luaqrcode to qrbill \ No newline at end of file diff --git a/macros/latex/contrib/qrbill/qrbill-qrencode.lua b/macros/latex/contrib/qrbill/qrbill-qrencode.lua new file mode 100644 index 0000000000..1df9a1e2fe --- /dev/null +++ b/macros/latex/contrib/qrbill/qrbill-qrencode.lua @@ -0,0 +1,1351 @@ +--- The qrcode library is licensed under the 3-clause BSD license (aka "new BSD") +--- To get in contact with the author, mail to . +--- +--- Please report bugs on the [github project page](http://speedata.github.io/luaqrcode/). +-- Copyright (c) 2012-2020, Patrick Gundlach and contributors, see https://github.com/speedata/luaqrcode +-- All rights reserved. +-- +-- Redistribution and use in source and binary forms, with or without +-- modification, are permitted provided that the following conditions are met: +-- * Redistributions of source code must retain the above copyright +-- notice, this list of conditions and the following disclaimer. +-- * Redistributions in binary form must reproduce the above copyright +-- notice, this list of conditions and the following disclaimer in the +-- documentation and/or other materials provided with the distribution. +-- * Neither the name of SPEEDATA nor the +-- names of its contributors may be used to endorse or promote products +-- derived from this software without specific prior written permission. +-- +-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +-- ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +-- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +-- DISCLAIMED. IN NO EVENT SHALL SPEEDATA GMBH BE LIABLE FOR ANY +-- DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +-- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +-- LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +-- ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +-- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +-- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +--- Overall workflow +--- ================ +--- The steps to generate the qrcode, assuming we already have the codeword: +--- +--- 1. Determine version, ec level and mode (=encoding) for codeword +--- 1. Encode data +--- 1. Arrange data and calculate error correction code +--- 1. Generate 8 matrices with different masks and calculate the penalty +--- 1. Return qrcode with least penalty +--- +--- Each step is of course more or less complex and needs further description + +--- Helper functions +--- ================ +--- +--- We start with some helper functions + +-- To calculate xor we need to do that bitwise. This helper table speeds up the num-to-bit +-- part a bit (no pun intended) +local cclxvi = {[0] = {0,0,0,0,0,0,0,0}, {1,0,0,0,0,0,0,0}, {0,1,0,0,0,0,0,0}, {1,1,0,0,0,0,0,0}, +{0,0,1,0,0,0,0,0}, {1,0,1,0,0,0,0,0}, {0,1,1,0,0,0,0,0}, {1,1,1,0,0,0,0,0}, +{0,0,0,1,0,0,0,0}, {1,0,0,1,0,0,0,0}, {0,1,0,1,0,0,0,0}, {1,1,0,1,0,0,0,0}, +{0,0,1,1,0,0,0,0}, {1,0,1,1,0,0,0,0}, {0,1,1,1,0,0,0,0}, {1,1,1,1,0,0,0,0}, +{0,0,0,0,1,0,0,0}, {1,0,0,0,1,0,0,0}, {0,1,0,0,1,0,0,0}, {1,1,0,0,1,0,0,0}, +{0,0,1,0,1,0,0,0}, {1,0,1,0,1,0,0,0}, {0,1,1,0,1,0,0,0}, {1,1,1,0,1,0,0,0}, +{0,0,0,1,1,0,0,0}, {1,0,0,1,1,0,0,0}, {0,1,0,1,1,0,0,0}, {1,1,0,1,1,0,0,0}, +{0,0,1,1,1,0,0,0}, {1,0,1,1,1,0,0,0}, {0,1,1,1,1,0,0,0}, {1,1,1,1,1,0,0,0}, +{0,0,0,0,0,1,0,0}, {1,0,0,0,0,1,0,0}, {0,1,0,0,0,1,0,0}, {1,1,0,0,0,1,0,0}, +{0,0,1,0,0,1,0,0}, {1,0,1,0,0,1,0,0}, {0,1,1,0,0,1,0,0}, {1,1,1,0,0,1,0,0}, +{0,0,0,1,0,1,0,0}, {1,0,0,1,0,1,0,0}, {0,1,0,1,0,1,0,0}, {1,1,0,1,0,1,0,0}, +{0,0,1,1,0,1,0,0}, {1,0,1,1,0,1,0,0}, {0,1,1,1,0,1,0,0}, {1,1,1,1,0,1,0,0}, +{0,0,0,0,1,1,0,0}, {1,0,0,0,1,1,0,0}, {0,1,0,0,1,1,0,0}, {1,1,0,0,1,1,0,0}, +{0,0,1,0,1,1,0,0}, {1,0,1,0,1,1,0,0}, {0,1,1,0,1,1,0,0}, {1,1,1,0,1,1,0,0}, +{0,0,0,1,1,1,0,0}, {1,0,0,1,1,1,0,0}, {0,1,0,1,1,1,0,0}, {1,1,0,1,1,1,0,0}, +{0,0,1,1,1,1,0,0}, {1,0,1,1,1,1,0,0}, {0,1,1,1,1,1,0,0}, {1,1,1,1,1,1,0,0}, +{0,0,0,0,0,0,1,0}, {1,0,0,0,0,0,1,0}, {0,1,0,0,0,0,1,0}, {1,1,0,0,0,0,1,0}, +{0,0,1,0,0,0,1,0}, {1,0,1,0,0,0,1,0}, {0,1,1,0,0,0,1,0}, {1,1,1,0,0,0,1,0}, +{0,0,0,1,0,0,1,0}, {1,0,0,1,0,0,1,0}, {0,1,0,1,0,0,1,0}, {1,1,0,1,0,0,1,0}, +{0,0,1,1,0,0,1,0}, {1,0,1,1,0,0,1,0}, {0,1,1,1,0,0,1,0}, {1,1,1,1,0,0,1,0}, +{0,0,0,0,1,0,1,0}, {1,0,0,0,1,0,1,0}, {0,1,0,0,1,0,1,0}, {1,1,0,0,1,0,1,0}, +{0,0,1,0,1,0,1,0}, {1,0,1,0,1,0,1,0}, {0,1,1,0,1,0,1,0}, {1,1,1,0,1,0,1,0}, +{0,0,0,1,1,0,1,0}, {1,0,0,1,1,0,1,0}, {0,1,0,1,1,0,1,0}, {1,1,0,1,1,0,1,0}, +{0,0,1,1,1,0,1,0}, {1,0,1,1,1,0,1,0}, {0,1,1,1,1,0,1,0}, {1,1,1,1,1,0,1,0}, +{0,0,0,0,0,1,1,0}, {1,0,0,0,0,1,1,0}, {0,1,0,0,0,1,1,0}, {1,1,0,0,0,1,1,0}, +{0,0,1,0,0,1,1,0}, {1,0,1,0,0,1,1,0}, {0,1,1,0,0,1,1,0}, {1,1,1,0,0,1,1,0}, +{0,0,0,1,0,1,1,0}, {1,0,0,1,0,1,1,0}, {0,1,0,1,0,1,1,0}, {1,1,0,1,0,1,1,0}, +{0,0,1,1,0,1,1,0}, {1,0,1,1,0,1,1,0}, {0,1,1,1,0,1,1,0}, {1,1,1,1,0,1,1,0}, +{0,0,0,0,1,1,1,0}, {1,0,0,0,1,1,1,0}, {0,1,0,0,1,1,1,0}, {1,1,0,0,1,1,1,0}, +{0,0,1,0,1,1,1,0}, {1,0,1,0,1,1,1,0}, {0,1,1,0,1,1,1,0}, {1,1,1,0,1,1,1,0}, +{0,0,0,1,1,1,1,0}, {1,0,0,1,1,1,1,0}, {0,1,0,1,1,1,1,0}, {1,1,0,1,1,1,1,0}, +{0,0,1,1,1,1,1,0}, {1,0,1,1,1,1,1,0}, {0,1,1,1,1,1,1,0}, {1,1,1,1,1,1,1,0}, +{0,0,0,0,0,0,0,1}, {1,0,0,0,0,0,0,1}, {0,1,0,0,0,0,0,1}, {1,1,0,0,0,0,0,1}, +{0,0,1,0,0,0,0,1}, {1,0,1,0,0,0,0,1}, {0,1,1,0,0,0,0,1}, {1,1,1,0,0,0,0,1}, +{0,0,0,1,0,0,0,1}, {1,0,0,1,0,0,0,1}, {0,1,0,1,0,0,0,1}, {1,1,0,1,0,0,0,1}, +{0,0,1,1,0,0,0,1}, {1,0,1,1,0,0,0,1}, {0,1,1,1,0,0,0,1}, {1,1,1,1,0,0,0,1}, +{0,0,0,0,1,0,0,1}, {1,0,0,0,1,0,0,1}, {0,1,0,0,1,0,0,1}, {1,1,0,0,1,0,0,1}, +{0,0,1,0,1,0,0,1}, {1,0,1,0,1,0,0,1}, {0,1,1,0,1,0,0,1}, {1,1,1,0,1,0,0,1}, +{0,0,0,1,1,0,0,1}, {1,0,0,1,1,0,0,1}, {0,1,0,1,1,0,0,1}, {1,1,0,1,1,0,0,1}, +{0,0,1,1,1,0,0,1}, {1,0,1,1,1,0,0,1}, {0,1,1,1,1,0,0,1}, {1,1,1,1,1,0,0,1}, +{0,0,0,0,0,1,0,1}, {1,0,0,0,0,1,0,1}, {0,1,0,0,0,1,0,1}, {1,1,0,0,0,1,0,1}, +{0,0,1,0,0,1,0,1}, {1,0,1,0,0,1,0,1}, {0,1,1,0,0,1,0,1}, {1,1,1,0,0,1,0,1}, +{0,0,0,1,0,1,0,1}, {1,0,0,1,0,1,0,1}, {0,1,0,1,0,1,0,1}, {1,1,0,1,0,1,0,1}, +{0,0,1,1,0,1,0,1}, {1,0,1,1,0,1,0,1}, {0,1,1,1,0,1,0,1}, {1,1,1,1,0,1,0,1}, +{0,0,0,0,1,1,0,1}, {1,0,0,0,1,1,0,1}, {0,1,0,0,1,1,0,1}, {1,1,0,0,1,1,0,1}, +{0,0,1,0,1,1,0,1}, {1,0,1,0,1,1,0,1}, {0,1,1,0,1,1,0,1}, {1,1,1,0,1,1,0,1}, +{0,0,0,1,1,1,0,1}, {1,0,0,1,1,1,0,1}, {0,1,0,1,1,1,0,1}, {1,1,0,1,1,1,0,1}, +{0,0,1,1,1,1,0,1}, {1,0,1,1,1,1,0,1}, {0,1,1,1,1,1,0,1}, {1,1,1,1,1,1,0,1}, +{0,0,0,0,0,0,1,1}, {1,0,0,0,0,0,1,1}, {0,1,0,0,0,0,1,1}, {1,1,0,0,0,0,1,1}, +{0,0,1,0,0,0,1,1}, {1,0,1,0,0,0,1,1}, {0,1,1,0,0,0,1,1}, {1,1,1,0,0,0,1,1}, +{0,0,0,1,0,0,1,1}, {1,0,0,1,0,0,1,1}, {0,1,0,1,0,0,1,1}, {1,1,0,1,0,0,1,1}, +{0,0,1,1,0,0,1,1}, {1,0,1,1,0,0,1,1}, {0,1,1,1,0,0,1,1}, {1,1,1,1,0,0,1,1}, +{0,0,0,0,1,0,1,1}, {1,0,0,0,1,0,1,1}, {0,1,0,0,1,0,1,1}, {1,1,0,0,1,0,1,1}, +{0,0,1,0,1,0,1,1}, {1,0,1,0,1,0,1,1}, {0,1,1,0,1,0,1,1}, {1,1,1,0,1,0,1,1}, +{0,0,0,1,1,0,1,1}, {1,0,0,1,1,0,1,1}, {0,1,0,1,1,0,1,1}, {1,1,0,1,1,0,1,1}, +{0,0,1,1,1,0,1,1}, {1,0,1,1,1,0,1,1}, {0,1,1,1,1,0,1,1}, {1,1,1,1,1,0,1,1}, +{0,0,0,0,0,1,1,1}, {1,0,0,0,0,1,1,1}, {0,1,0,0,0,1,1,1}, {1,1,0,0,0,1,1,1}, +{0,0,1,0,0,1,1,1}, {1,0,1,0,0,1,1,1}, {0,1,1,0,0,1,1,1}, {1,1,1,0,0,1,1,1}, +{0,0,0,1,0,1,1,1}, {1,0,0,1,0,1,1,1}, {0,1,0,1,0,1,1,1}, {1,1,0,1,0,1,1,1}, +{0,0,1,1,0,1,1,1}, {1,0,1,1,0,1,1,1}, {0,1,1,1,0,1,1,1}, {1,1,1,1,0,1,1,1}, +{0,0,0,0,1,1,1,1}, {1,0,0,0,1,1,1,1}, {0,1,0,0,1,1,1,1}, {1,1,0,0,1,1,1,1}, +{0,0,1,0,1,1,1,1}, {1,0,1,0,1,1,1,1}, {0,1,1,0,1,1,1,1}, {1,1,1,0,1,1,1,1}, +{0,0,0,1,1,1,1,1}, {1,0,0,1,1,1,1,1}, {0,1,0,1,1,1,1,1}, {1,1,0,1,1,1,1,1}, +{0,0,1,1,1,1,1,1}, {1,0,1,1,1,1,1,1}, {0,1,1,1,1,1,1,1}, {1,1,1,1,1,1,1,1}} + +-- Return a number that is the result of interpreting the table tbl (msb first) +local function tbl_to_number(tbl) + local n = #tbl + local rslt = 0 + local power = 1 + for i = 1, n do + rslt = rslt + tbl[i]*power + power = power*2 + end + return rslt +end + +-- Calculate bitwise xor of bytes m and n. 0 <= m,n <= 256. +local function bit_xor(m, n) + local tbl_m = cclxvi[m] + local tbl_n = cclxvi[n] + local tbl = {} + for i = 1, 8 do + if(tbl_m[i] ~= tbl_n[i]) then + tbl[i] = 1 + else + tbl[i] = 0 + end + end + return tbl_to_number(tbl) +end + +-- Return the binary representation of the number x with the width of `digits`. +local function binary(x,digits) + local s=string.format("%o",x) + local a={["0"]="000",["1"]="001", ["2"]="010",["3"]="011", + ["4"]="100",["5"]="101", ["6"]="110",["7"]="111"} + s=string.gsub(s,"(.)",function (d) return a[d] end) + -- remove leading 0s + s = string.gsub(s,"^0*(.*)$","%1") + local fmtstring = string.format("%%%ds",digits) + local ret = string.format(fmtstring,s) + return string.gsub(ret," ","0") +end + +-- A small helper function for add_typeinfo_to_matrix() and add_version_information() +-- Add a 2 (black by default) / -2 (blank by default) to the matrix at position x,y +-- depending on the bitstring (size 1!) where "0"=blank and "1"=black. +local function fill_matrix_position(matrix,bitstring,x,y) + if bitstring == "1" then + matrix[x][y] = 2 + else + matrix[x][y] = -2 + end +end + + +--- Step 1: Determine version, ec level and mode for codeword +--- ======================================================== +--- +--- First we need to find out the version (= size) of the QR code. This depends on +--- the input data (the mode to be used), the requested error correction level +--- (normally we use the maximum level that fits into the minimal size). + +-- Return the mode for the given string `str`. +-- See table 2 of the spec. We only support mode 1, 2 and 4. +-- That is: numeric, alaphnumeric and binary. +local function get_mode( str ) + if string.match(str,"^[0-9]+$") then + return 1 + elseif string.match(str,"^[0-9A-Z $%%*./:+-]+$") then + return 2 + else + return 4 + end + assert(false,"never reached") -- luacheck: ignore + return nil +end + + + +--- Capacity of QR codes +--- -------------------- +--- The capacity is calculated as follow: \\(\text{Number of data bits} = \text{number of codewords} * 8\\). +--- The number of data bits is now reduced by 4 (the mode indicator) and the length string, +--- that varies between 8 and 16, depending on the version and the mode (see method `get_length()`). The +--- remaining capacity is multiplied by the amount of data per bit string (numeric: 3, alphanumeric: 2, other: 1) +--- and divided by the length of the bit string (numeric: 10, alphanumeric: 11, binary: 8, kanji: 13). +--- Then the floor function is applied to the result: +--- $$\Big\lfloor \frac{( \text{#data bits} - 4 - \text{length string}) * \text{data per bit string}}{\text{length of the bit string}} \Big\rfloor$$ +--- +--- There is one problem remaining. The length string depends on the version, +--- and the version depends on the length string. But we take this into account when calculating the +--- the capacity, so this is not really a problem here. + +-- The capacity (number of codewords) of each version (1-40) for error correction levels 1-4 (LMQH). +-- The higher the ec level, the lower the capacity of the version. Taken from spec, tables 7-11. +local capacity = { + { 19, 16, 13, 9},{ 34, 28, 22, 16},{ 55, 44, 34, 26},{ 80, 64, 48, 36}, + { 108, 86, 62, 46},{ 136, 108, 76, 60},{ 156, 124, 88, 66},{ 194, 154, 110, 86}, + { 232, 182, 132, 100},{ 274, 216, 154, 122},{ 324, 254, 180, 140},{ 370, 290, 206, 158}, + { 428, 334, 244, 180},{ 461, 365, 261, 197},{ 523, 415, 295, 223},{ 589, 453, 325, 253}, + { 647, 507, 367, 283},{ 721, 563, 397, 313},{ 795, 627, 445, 341},{ 861, 669, 485, 385}, + { 932, 714, 512, 406},{1006, 782, 568, 442},{1094, 860, 614, 464},{1174, 914, 664, 514}, + {1276, 1000, 718, 538},{1370, 1062, 754, 596},{1468, 1128, 808, 628},{1531, 1193, 871, 661}, + {1631, 1267, 911, 701},{1735, 1373, 985, 745},{1843, 1455, 1033, 793},{1955, 1541, 1115, 845}, + {2071, 1631, 1171, 901},{2191, 1725, 1231, 961},{2306, 1812, 1286, 986},{2434, 1914, 1354, 1054}, + {2566, 1992, 1426, 1096},{2702, 2102, 1502, 1142},{2812, 2216, 1582, 1222},{2956, 2334, 1666, 1276}} + + +--- Return the smallest version for this codeword. If `requested_ec_level` is supplied, +--- then the ec level (LMQH - 1,2,3,4) must be at least the requested level. +-- mode = 1,2,4,8 +local function get_version_eclevel(len,mode,requested_ec_level) + local local_mode = mode + if mode == 4 then + local_mode = 3 + elseif mode == 8 then + local_mode = 4 + end + assert( local_mode <= 4 ) + + local bits, digits, modebits, c + local tab = { {10,9,8,8},{12,11,16,10},{14,13,16,12} } + local minversion = 40 + local maxec_level = requested_ec_level or 1 + local min,max = 1, 4 + if requested_ec_level and requested_ec_level >= 1 and requested_ec_level <= 4 then + min = requested_ec_level + max = requested_ec_level + end + for ec_level=min,max do + for version=1,#capacity do + bits = capacity[version][ec_level] * 8 + bits = bits - 4 -- the mode indicator + if version < 10 then + digits = tab[1][local_mode] + elseif version < 27 then + digits = tab[2][local_mode] + elseif version <= 40 then + digits = tab[3][local_mode] + end + modebits = bits - digits + if local_mode == 1 then -- numeric + c = math.floor(modebits * 3 / 10) + elseif local_mode == 2 then -- alphanumeric + c = math.floor(modebits * 2 / 11) + elseif local_mode == 3 then -- binary + c = math.floor(modebits * 1 / 8) + else + c = math.floor(modebits * 1 / 13) + end + if c >= len then + if version <= minversion then + minversion = version + maxec_level = ec_level + end + break + end + end + end + return minversion, maxec_level +end + +-- Return a bit string of 0s and 1s that includes the length of the code string. +-- The modes are numeric = 1, alphanumeric = 2, binary = 4, and japanese = 8 +local function get_length(str,version,mode) + local i = mode + if mode == 4 then + i = 3 + elseif mode == 8 then + i = 4 + end + assert( i <= 4 ) + local tab = { {10,9,8,8},{12,11,16,10},{14,13,16,12} } + local digits + if version < 10 then + digits = tab[1][i] + elseif version < 27 then + digits = tab[2][i] + elseif version <= 40 then + digits = tab[3][i] + else + assert(false, "get_length, version > 40 not supported") + end + local len = binary(#str,digits) + return len +end + +--- If the `requested_ec_level` or the `mode` are provided, this will be used if possible. +--- The mode depends on the characters used in the string `str`. It seems to be +--- possible to split the QR code to handle multiple modes, but we don't do that. +local function get_version_eclevel_mode_bistringlength(str,requested_ec_level,mode) + local local_mode + if mode then + assert(false,"not implemented") + -- check if the mode is OK for the string + local_mode = mode + else + local_mode = get_mode(str) + end + local version, ec_level + version, ec_level = get_version_eclevel(#str,local_mode,requested_ec_level) + local length_string = get_length(str,version,local_mode) + return version,ec_level,binary(local_mode,4),local_mode,length_string +end + +--- Step 2: Encode data +--- =================== + +--- There are several ways to encode the data. We currently support only numeric, alphanumeric and binary. +--- We already chose the encoding (a.k.a. mode) in the first step, so we need to apply the mode to the +--- codeword. +--- +--- **Numeric**: take three digits and encode them in 10 bits +--- **Alphanumeric**: take two characters and encode them in 11 bits +--- **Binary**: take one octet and encode it in 8 bits + +local asciitbl = { + -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -- 0x01-0x0f + -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -- 0x10-0x1f + 36, -1, -1, -1, 37, 38, -1, -1, -1, -1, 39, 40, -1, 41, 42, 43, -- 0x20-0x2f + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 44, -1, -1, -1, -1, -1, -- 0x30-0x3f + -1, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, -- 0x40-0x4f + 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, -1, -1, -1, -1, -1, -- 0x50-0x5f + } + +-- Return a binary representation of the numeric string `str`. This must contain only digits 0-9. +local function encode_string_numeric(str) + local bitstring = "" + local int + string.gsub(str,"..?.?",function(a) + int = tonumber(a) + if #a == 3 then + bitstring = bitstring .. binary(int,10) + elseif #a == 2 then + bitstring = bitstring .. binary(int,7) + else + bitstring = bitstring .. binary(int,4) + end + end) + return bitstring +end + +-- Return a binary representation of the alphanumeric string `str`. This must contain only +-- digits 0-9, uppercase letters A-Z, space and the following chars: $%*./:+-. +local function encode_string_ascii(str) + local bitstring = "" + local int + local b1, b2 + string.gsub(str,"..?",function(a) + if #a == 2 then + b1 = asciitbl[string.byte(string.sub(a,1,1))] + b2 = asciitbl[string.byte(string.sub(a,2,2))] + int = b1 * 45 + b2 + bitstring = bitstring .. binary(int,11) + else + int = asciitbl[string.byte(a)] + bitstring = bitstring .. binary(int,6) + end + end) + return bitstring +end + +-- Return a bitstring representing string str in binary mode. +-- We don't handle UTF-8 in any special way because we assume the +-- scanner recognizes UTF-8 and displays it correctly. +local function encode_string_binary(str) + local ret = {} + string.gsub(str,".",function(x) + ret[#ret + 1] = binary(string.byte(x),8) + end) + return table.concat(ret) +end + +-- Return a bitstring representing string str in the given mode. +local function encode_data(str,mode) + if mode == 1 then + return encode_string_numeric(str) + elseif mode == 2 then + return encode_string_ascii(str) + elseif mode == 4 then + return encode_string_binary(str) + else + assert(false,"not implemented yet") + end +end + +-- Encoding the codeword is not enough. We need to make sure that +-- the length of the binary string is equal to the number of codewords of the version. +local function add_pad_data(version,ec_level,data) + local count_to_pad, missing_digits + local cpty = capacity[version][ec_level] * 8 + count_to_pad = math.min(4,cpty - #data) + if count_to_pad > 0 then + data = data .. string.rep("0",count_to_pad) + end + if math.fmod(#data,8) ~= 0 then + missing_digits = 8 - math.fmod(#data,8) + data = data .. string.rep("0",missing_digits) + end + assert(math.fmod(#data,8) == 0) + -- add "11101100" and "00010001" until enough data + while #data < cpty do + data = data .. "11101100" + if #data < cpty then + data = data .. "00010001" + end + end + return data +end + + + +--- Step 3: Organize data and calculate error correction code +--- ======================================================= +--- The data in the qrcode is not encoded linearly. For example code 5-H has four blocks, the first two blocks +--- contain 11 codewords and 22 error correction codes each, the second block contain 12 codewords and 22 ec codes each. +--- We just take the table from the spec and don't calculate the blocks ourself. The table `ecblocks` contains this info. +--- +--- During the phase of splitting the data into codewords, we do the calculation for error correction codes. This step involves +--- polynomial division. Find a math book from school and follow the code here :) + +--- ### Reed Solomon error correction +--- Now this is the slightly ugly part of the error correction. We start with log/antilog tables +-- https://codyplanteen.com/assets/rs/gf256_log_antilog.pdf +local alpha_int = { + [0] = 1, + 2, 4, 8, 16, 32, 64, 128, 29, 58, 116, 232, 205, 135, 19, 38, 76, + 152, 45, 90, 180, 117, 234, 201, 143, 3, 6, 12, 24, 48, 96, 192, 157, + 39, 78, 156, 37, 74, 148, 53, 106, 212, 181, 119, 238, 193, 159, 35, 70, + 140, 5, 10, 20, 40, 80, 160, 93, 186, 105, 210, 185, 111, 222, 161, 95, + 190, 97, 194, 153, 47, 94, 188, 101, 202, 137, 15, 30, 60, 120, 240, 253, + 231, 211, 187, 107, 214, 177, 127, 254, 225, 223, 163, 91, 182, 113, 226, 217, + 175, 67, 134, 17, 34, 68, 136, 13, 26, 52, 104, 208, 189, 103, 206, 129, + 31, 62, 124, 248, 237, 199, 147, 59, 118, 236, 197, 151, 51, 102, 204, 133, + 23, 46, 92, 184, 109, 218, 169, 79, 158, 33, 66, 132, 21, 42, 84, 168, + 77, 154, 41, 82, 164, 85, 170, 73, 146, 57, 114, 228, 213, 183, 115, 230, + 209, 191, 99, 198, 145, 63, 126, 252, 229, 215, 179, 123, 246, 241, 255, 227, + 219, 171, 75, 150, 49, 98, 196, 149, 55, 110, 220, 165, 87, 174, 65, 130, + 25, 50, 100, 200, 141, 7, 14, 28, 56, 112, 224, 221, 167, 83, 166, 81, + 162, 89, 178, 121, 242, 249, 239, 195, 155, 43, 86, 172, 69, 138, 9, 18, + 36, 72, 144, 61, 122, 244, 245, 247, 243, 251, 235, 203, 139, 11, 22, 44, + 88, 176, 125, 250, 233, 207, 131, 27, 54, 108, 216, 173, 71, 142, 0, 0 +} + +local int_alpha = { + [0] = 256, -- special value + 0, 1, 25, 2, 50, 26, 198, 3, 223, 51, 238, 27, 104, 199, 75, 4, + 100, 224, 14, 52, 141, 239, 129, 28, 193, 105, 248, 200, 8, 76, 113, 5, + 138, 101, 47, 225, 36, 15, 33, 53, 147, 142, 218, 240, 18, 130, 69, 29, + 181, 194, 125, 106, 39, 249, 185, 201, 154, 9, 120, 77, 228, 114, 166, 6, + 191, 139, 98, 102, 221, 48, 253, 226, 152, 37, 179, 16, 145, 34, 136, 54, + 208, 148, 206, 143, 150, 219, 189, 241, 210, 19, 92, 131, 56, 70, 64, 30, + 66, 182, 163, 195, 72, 126, 110, 107, 58, 40, 84, 250, 133, 186, 61, 202, + 94, 155, 159, 10, 21, 121, 43, 78, 212, 229, 172, 115, 243, 167, 87, 7, + 112, 192, 247, 140, 128, 99, 13, 103, 74, 222, 237, 49, 197, 254, 24, 227, + 165, 153, 119, 38, 184, 180, 124, 17, 68, 146, 217, 35, 32, 137, 46, 55, + 63, 209, 91, 149, 188, 207, 205, 144, 135, 151, 178, 220, 252, 190, 97, 242, + 86, 211, 171, 20, 42, 93, 158, 132, 60, 57, 83, 71, 109, 65, 162, 31, + 45, 67, 216, 183, 123, 164, 118, 196, 23, 73, 236, 127, 12, 111, 246, 108, + 161, 59, 82, 41, 157, 85, 170, 251, 96, 134, 177, 187, 204, 62, 90, 203, + 89, 95, 176, 156, 169, 160, 81, 11, 245, 22, 235, 122, 117, 44, 215, 79, + 174, 213, 233, 230, 231, 173, 232, 116, 214, 244, 234, 168, 80, 88, 175 +} + +-- We only need the polynomial generators for block sizes 7, 10, 13, 15, 16, 17, 18, 20, 22, 24, 26, 28, and 30. Version +-- 2 of the qr codes don't need larger ones (as opposed to version 1). The table has the format x^1*ɑ^21 + x^2*a^102 ... +local generator_polynomial = { + [7] = { 21, 102, 238, 149, 146, 229, 87, 0}, + [10] = { 45, 32, 94, 64, 70, 118, 61, 46, 67, 251, 0 }, + [13] = { 78, 140, 206, 218, 130, 104, 106, 100, 86, 100, 176, 152, 74, 0 }, + [15] = {105, 99, 5, 124, 140, 237, 58, 58, 51, 37, 202, 91, 61, 183, 8, 0}, + [16] = {120, 225, 194, 182, 169, 147, 191, 91, 3, 76, 161, 102, 109, 107, 104, 120, 0}, + [17] = {136, 163, 243, 39, 150, 99, 24, 147, 214, 206, 123, 239, 43, 78, 206, 139, 43, 0}, + [18] = {153, 96, 98, 5, 179, 252, 148, 152, 187, 79, 170, 118, 97, 184, 94, 158, 234, 215, 0}, + [20] = {190, 188, 212, 212, 164, 156, 239, 83, 225, 221, 180, 202, 187, 26, 163, 61, 50, 79, 60, 17, 0}, + [22] = {231, 165, 105, 160, 134, 219, 80, 98, 172, 8, 74, 200, 53, 221, 109, 14, 230, 93, 242, 247, 171, 210, 0}, + [24] = { 21, 227, 96, 87, 232, 117, 0, 111, 218, 228, 226, 192, 152, 169, 180, 159, 126, 251, 117, 211, 48, 135, 121, 229, 0}, + [26] = { 70, 218, 145, 153, 227, 48, 102, 13, 142, 245, 21, 161, 53, 165, 28, 111, 201, 145, 17, 118, 182, 103, 2, 158, 125, 173, 0}, + [28] = {123, 9, 37, 242, 119, 212, 195, 42, 87, 245, 43, 21, 201, 232, 27, 205, 147, 195, 190, 110, 180, 108, 234, 224, 104, 200, 223, 168, 0}, + [30] = {180, 192, 40, 238, 216, 251, 37, 156, 130, 224, 193, 226, 173, 42, 125, 222, 96, 239, 86, 110, 48, 50, 182, 179, 31, 216, 152, 145, 173, 41, 0}} + + +-- Turn a binary string of length 8*x into a table size x of numbers. +local function convert_bitstring_to_bytes(data) + local msg = {} + string.gsub(data,"(........)",function(x) + msg[#msg+1] = tonumber(x,2) + end) + return msg +end + +-- Return a table that has 0's in the first entries and then the alpha +-- representation of the generator polynominal +local function get_generator_polynominal_adjusted(num_ec_codewords,highest_exponent) + local gp_alpha = {[0]=0} + for i=0,highest_exponent - num_ec_codewords - 1 do + gp_alpha[i] = 0 + end + local gp = generator_polynomial[num_ec_codewords] + for i=1,num_ec_codewords + 1 do + gp_alpha[highest_exponent - num_ec_codewords + i - 1] = gp[i] + end + return gp_alpha +end + +--- These converter functions use the log/antilog table above. +--- We could have created the table programatically, but I like fixed tables. +-- Convert polynominal in int notation to alpha notation. +local function convert_to_alpha( tab ) + local new_tab = {} + for i=0,#tab do + new_tab[i] = int_alpha[tab[i]] + end + return new_tab +end + +-- Convert polynominal in alpha notation to int notation. +local function convert_to_int(tab) + local new_tab = {} + for i=0,#tab do + new_tab[i] = alpha_int[tab[i]] + end + return new_tab +end + +-- That's the heart of the error correction calculation. +local function calculate_error_correction(data,num_ec_codewords) + local mp + if type(data)=="string" then + mp = convert_bitstring_to_bytes(data) + elseif type(data)=="table" then + mp = data + else + assert(false,string.format("Unknown type for data: %s",type(data))) + end + local len_message = #mp + + local highest_exponent = len_message + num_ec_codewords - 1 + local gp_alpha,tmp + local he + local gp_int, mp_alpha + local mp_int = {} + -- create message shifted to left (highest exponent) + for i=1,len_message do + mp_int[highest_exponent - i + 1] = mp[i] + end + for i=1,highest_exponent - len_message do + mp_int[i] = 0 + end + mp_int[0] = 0 + + mp_alpha = convert_to_alpha(mp_int) + + while highest_exponent >= num_ec_codewords do + gp_alpha = get_generator_polynominal_adjusted(num_ec_codewords,highest_exponent) + + -- Multiply generator polynomial by first coefficient of the above polynomial + + -- take the highest exponent from the message polynom (alpha) and add + -- it to the generator polynom + local exp = mp_alpha[highest_exponent] + for i=highest_exponent,highest_exponent - num_ec_codewords,-1 do + if exp ~= 256 then + if gp_alpha[i] + exp >= 255 then + gp_alpha[i] = math.fmod(gp_alpha[i] + exp,255) + else + gp_alpha[i] = gp_alpha[i] + exp + end + else + gp_alpha[i] = 256 + end + end + for i=highest_exponent - num_ec_codewords - 1,0,-1 do + gp_alpha[i] = 256 + end + + gp_int = convert_to_int(gp_alpha) + mp_int = convert_to_int(mp_alpha) + + + tmp = {} + for i=highest_exponent,0,-1 do + tmp[i] = bit_xor(gp_int[i],mp_int[i]) + end + -- remove leading 0's + he = highest_exponent + for i=he,0,-1 do + -- We need to stop if the length of the codeword is matched + if i < num_ec_codewords then break end + if tmp[i] == 0 then + tmp[i] = nil + highest_exponent = highest_exponent - 1 + else + break + end + end + mp_int = tmp + mp_alpha = convert_to_alpha(mp_int) + end + local ret = {} + + -- reverse data + for i=#mp_int,0,-1 do + ret[#ret + 1] = mp_int[i] + end + return ret +end + +--- #### Arranging the data +--- Now we arrange the data into smaller chunks. This table is taken from the spec. +-- ecblocks has 40 entries, one for each version. Each version entry has 4 entries, for each LMQH +-- ec level. Each entry has two or four fields, the odd files are the number of repetitions for the +-- folowing block info. The first entry of the block is the total number of codewords in the block, +-- the second entry is the number of data codewords. The third is not important. +local ecblocks = { + {{ 1,{ 26, 19, 2} }, { 1,{26,16, 4}}, { 1,{26,13, 6}}, { 1, {26, 9, 8} }}, + {{ 1,{ 44, 34, 4} }, { 1,{44,28, 8}}, { 1,{44,22,11}}, { 1, {44,16,14} }}, + {{ 1,{ 70, 55, 7} }, { 1,{70,44,13}}, { 2,{35,17, 9}}, { 2, {35,13,11} }}, + {{ 1,{100, 80,10} }, { 2,{50,32, 9}}, { 2,{50,24,13}}, { 4, {25, 9, 8} }}, + {{ 1,{134,108,13} }, { 2,{67,43,12}}, { 2,{33,15, 9}, 2,{34,16, 9}}, { 2, {33,11,11}, 2,{34,12,11}}}, + {{ 2,{ 86, 68, 9} }, { 4,{43,27, 8}}, { 4,{43,19,12}}, { 4, {43,15,14} }}, + {{ 2,{ 98, 78,10} }, { 4,{49,31, 9}}, { 2,{32,14, 9}, 4,{33,15, 9}}, { 4, {39,13,13}, 1,{40,14,13}}}, + {{ 2,{121, 97,12} }, { 2,{60,38,11}, 2,{61,39,11}}, { 4,{40,18,11}, 2,{41,19,11}}, { 4, {40,14,13}, 2,{41,15,13}}}, + {{ 2,{146,116,15} }, { 3,{58,36,11}, 2,{59,37,11}}, { 4,{36,16,10}, 4,{37,17,10}}, { 4, {36,12,12}, 4,{37,13,12}}}, + {{ 2,{ 86, 68, 9}, 2,{ 87, 69, 9}}, { 4,{69,43,13}, 1,{70,44,13}}, { 6,{43,19,12}, 2,{44,20,12}}, { 6, {43,15,14}, 2,{44,16,14}}}, + {{ 4,{101, 81,10} }, { 1,{80,50,15}, 4,{81,51,15}}, { 4,{50,22,14}, 4,{51,23,14}}, { 3, {36,12,12}, 8,{37,13,12}}}, + {{ 2,{116, 92,12}, 2,{117, 93,12}}, { 6,{58,36,11}, 2,{59,37,11}}, { 4,{46,20,13}, 6,{47,21,13}}, { 7, {42,14,14}, 4,{43,15,14}}}, + {{ 4,{133,107,13} }, { 8,{59,37,11}, 1,{60,38,11}}, { 8,{44,20,12}, 4,{45,21,12}}, { 12, {33,11,11}, 4,{34,12,11}}}, + {{ 3,{145,115,15}, 1,{146,116,15}}, { 4,{64,40,12}, 5,{65,41,12}}, { 11,{36,16,10}, 5,{37,17,10}}, { 11, {36,12,12}, 5,{37,13,12}}}, + {{ 5,{109, 87,11}, 1,{110, 88,11}}, { 5,{65,41,12}, 5,{66,42,12}}, { 5,{54,24,15}, 7,{55,25,15}}, { 11, {36,12,12}, 7,{37,13,12}}}, + {{ 5,{122, 98,12}, 1,{123, 99,12}}, { 7,{73,45,14}, 3,{74,46,14}}, { 15,{43,19,12}, 2,{44,20,12}}, { 3, {45,15,15}, 13,{46,16,15}}}, + {{ 1,{135,107,14}, 5,{136,108,14}}, { 10,{74,46,14}, 1,{75,47,14}}, { 1,{50,22,14}, 15,{51,23,14}}, { 2, {42,14,14}, 17,{43,15,14}}}, + {{ 5,{150,120,15}, 1,{151,121,15}}, { 9,{69,43,13}, 4,{70,44,13}}, { 17,{50,22,14}, 1,{51,23,14}}, { 2, {42,14,14}, 19,{43,15,14}}}, + {{ 3,{141,113,14}, 4,{142,114,14}}, { 3,{70,44,13}, 11,{71,45,13}}, { 17,{47,21,13}, 4,{48,22,13}}, { 9, {39,13,13}, 16,{40,14,13}}}, + {{ 3,{135,107,14}, 5,{136,108,14}}, { 3,{67,41,13}, 13,{68,42,13}}, { 15,{54,24,15}, 5,{55,25,15}}, { 15, {43,15,14}, 10,{44,16,14}}}, + {{ 4,{144,116,14}, 4,{145,117,14}}, { 17,{68,42,13}}, { 17,{50,22,14}, 6,{51,23,14}}, { 19, {46,16,15}, 6,{47,17,15}}}, + {{ 2,{139,111,14}, 7,{140,112,14}}, { 17,{74,46,14}}, { 7,{54,24,15}, 16,{55,25,15}}, { 34, {37,13,12} }}, + {{ 4,{151,121,15}, 5,{152,122,15}}, { 4,{75,47,14}, 14,{76,48,14}}, { 11,{54,24,15}, 14,{55,25,15}}, { 16, {45,15,15}, 14,{46,16,15}}}, + {{ 6,{147,117,15}, 4,{148,118,15}}, { 6,{73,45,14}, 14,{74,46,14}}, { 11,{54,24,15}, 16,{55,25,15}}, { 30, {46,16,15}, 2,{47,17,15}}}, + {{ 8,{132,106,13}, 4,{133,107,13}}, { 8,{75,47,14}, 13,{76,48,14}}, { 7,{54,24,15}, 22,{55,25,15}}, { 22, {45,15,15}, 13,{46,16,15}}}, + {{ 10,{142,114,14}, 2,{143,115,14}}, { 19,{74,46,14}, 4,{75,47,14}}, { 28,{50,22,14}, 6,{51,23,14}}, { 33, {46,16,15}, 4,{47,17,15}}}, + {{ 8,{152,122,15}, 4,{153,123,15}}, { 22,{73,45,14}, 3,{74,46,14}}, { 8,{53,23,15}, 26,{54,24,15}}, { 12, {45,15,15}, 28,{46,16,15}}}, + {{ 3,{147,117,15}, 10,{148,118,15}}, { 3,{73,45,14}, 23,{74,46,14}}, { 4,{54,24,15}, 31,{55,25,15}}, { 11, {45,15,15}, 31,{46,16,15}}}, + {{ 7,{146,116,15}, 7,{147,117,15}}, { 21,{73,45,14}, 7,{74,46,14}}, { 1,{53,23,15}, 37,{54,24,15}}, { 19, {45,15,15}, 26,{46,16,15}}}, + {{ 5,{145,115,15}, 10,{146,116,15}}, { 19,{75,47,14}, 10,{76,48,14}}, { 15,{54,24,15}, 25,{55,25,15}}, { 23, {45,15,15}, 25,{46,16,15}}}, + {{ 13,{145,115,15}, 3,{146,116,15}}, { 2,{74,46,14}, 29,{75,47,14}}, { 42,{54,24,15}, 1,{55,25,15}}, { 23, {45,15,15}, 28,{46,16,15}}}, + {{ 17,{145,115,15} }, { 10,{74,46,14}, 23,{75,47,14}}, { 10,{54,24,15}, 35,{55,25,15}}, { 19, {45,15,15}, 35,{46,16,15}}}, + {{ 17,{145,115,15}, 1,{146,116,15}}, { 14,{74,46,14}, 21,{75,47,14}}, { 29,{54,24,15}, 19,{55,25,15}}, { 11, {45,15,15}, 46,{46,16,15}}}, + {{ 13,{145,115,15}, 6,{146,116,15}}, { 14,{74,46,14}, 23,{75,47,14}}, { 44,{54,24,15}, 7,{55,25,15}}, { 59, {46,16,15}, 1,{47,17,15}}}, + {{ 12,{151,121,15}, 7,{152,122,15}}, { 12,{75,47,14}, 26,{76,48,14}}, { 39,{54,24,15}, 14,{55,25,15}}, { 22, {45,15,15}, 41,{46,16,15}}}, + {{ 6,{151,121,15}, 14,{152,122,15}}, { 6,{75,47,14}, 34,{76,48,14}}, { 46,{54,24,15}, 10,{55,25,15}}, { 2, {45,15,15}, 64,{46,16,15}}}, + {{ 17,{152,122,15}, 4,{153,123,15}}, { 29,{74,46,14}, 14,{75,47,14}}, { 49,{54,24,15}, 10,{55,25,15}}, { 24, {45,15,15}, 46,{46,16,15}}}, + {{ 4,{152,122,15}, 18,{153,123,15}}, { 13,{74,46,14}, 32,{75,47,14}}, { 48,{54,24,15}, 14,{55,25,15}}, { 42, {45,15,15}, 32,{46,16,15}}}, + {{ 20,{147,117,15}, 4,{148,118,15}}, { 40,{75,47,14}, 7,{76,48,14}}, { 43,{54,24,15}, 22,{55,25,15}}, { 10, {45,15,15}, 67,{46,16,15}}}, + {{ 19,{148,118,15}, 6,{149,119,15}}, { 18,{75,47,14}, 31,{76,48,14}}, { 34,{54,24,15}, 34,{55,25,15}}, { 20, {45,15,15}, 61,{46,16,15}}} +} + +-- The bits that must be 0 if the version does fill the complete matrix. +-- Example: for version 1, no bits need to be added after arranging the data, for version 2 we need to add 7 bits at the end. +local remainder = {0, 7, 7, 7, 7, 7, 0, 0, 0, 0, 0, 0, 0, 3, 3, 3, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4, 4, 3, 3, 3, 3, 3, 3, 3, 0, 0, 0, 0, 0, 0} + +-- This is the formula for table 1 in the spec: +-- function get_capacity_remainder( version ) +-- local len = version * 4 + 17 +-- local size = len^2 +-- local function_pattern_modules = 192 + 2 * len - 32 -- Position Adjustment pattern + timing pattern +-- local count_alignemnt_pattern = #alignment_pattern[version] +-- if count_alignemnt_pattern > 0 then +-- -- add 25 for each aligment pattern +-- function_pattern_modules = function_pattern_modules + 25 * ( count_alignemnt_pattern^2 - 3 ) +-- -- but substract the timing pattern occupied by the aligment pattern on the top and left +-- function_pattern_modules = function_pattern_modules - ( count_alignemnt_pattern - 2) * 10 +-- end +-- size = size - function_pattern_modules +-- if version > 6 then +-- size = size - 67 +-- else +-- size = size - 31 +-- end +-- return math.floor(size/8),math.fmod(size,8) +-- end + + +--- Example: Version 5-H has four data and four error correction blocks. The table above lists +--- `2, {33,11,11}, 2,{34,12,11}` for entry [5][4]. This means we take two blocks with 11 codewords +--- and two blocks with 12 codewords, and two blocks with 33 - 11 = 22 ec codes and another +--- two blocks with 34 - 12 = 22 ec codes. +--- Block 1: D1 D2 D3 ... D11 +--- Block 2: D12 D13 D14 ... D22 +--- Block 3: D23 D24 D25 ... D33 D34 +--- Block 4: D35 D36 D37 ... D45 D46 +--- Then we place the data like this in the matrix: D1, D12, D23, D35, D2, D13, D24, D36 ... D45, D34, D46. The same goes +--- with error correction codes. + +-- The given data can be a string of 0's and 1' (with #string mod 8 == 0). +-- Alternatively the data can be a table of codewords. The number of codewords +-- must match the capacity of the qr code. +local function arrange_codewords_and_calculate_ec( version,ec_level,data ) + if type(data)=="table" then + local tmp = "" + for i=1,#data do + tmp = tmp .. binary(data[i],8) + end + data = tmp + end + -- If the size of the data is not enough for the codeword, we add 0's and two special bytes until finished. + local blocks = ecblocks[version][ec_level] + local size_datablock_bytes, size_ecblock_bytes + local datablocks = {} + local final_ecblocks = {} + local count = 1 + local pos = 0 + local cpty_ec_bits = 0 + for i=1,#blocks/2 do + for _=1,blocks[2*i - 1] do + size_datablock_bytes = blocks[2*i][2] + size_ecblock_bytes = blocks[2*i][1] - blocks[2*i][2] + cpty_ec_bits = cpty_ec_bits + size_ecblock_bytes * 8 + datablocks[#datablocks + 1] = string.sub(data, pos * 8 + 1,( pos + size_datablock_bytes)*8) + local tmp_tab = calculate_error_correction(datablocks[#datablocks],size_ecblock_bytes) + local tmp_str = "" + for x=1,#tmp_tab do + tmp_str = tmp_str .. binary(tmp_tab[x],8) + end + final_ecblocks[#final_ecblocks + 1] = tmp_str + pos = pos + size_datablock_bytes + count = count + 1 + end + end + local arranged_data = "" + pos = 1 + repeat + for i=1,#datablocks do + if pos < #datablocks[i] then + arranged_data = arranged_data .. string.sub(datablocks[i],pos, pos + 7) + end + end + pos = pos + 8 + until #arranged_data == #data + -- ec + local arranged_ec = "" + pos = 1 + repeat + for i=1,#final_ecblocks do + if pos < #final_ecblocks[i] then + arranged_ec = arranged_ec .. string.sub(final_ecblocks[i],pos, pos + 7) + end + end + pos = pos + 8 + until #arranged_ec == cpty_ec_bits + return arranged_data .. arranged_ec +end + +--- Step 4: Generate 8 matrices with different masks and calculate the penalty +--- ========================================================================== +--- +--- Prepare matrix +--- -------------- +--- The first step is to prepare an _empty_ matrix for a given size/mask. The matrix has a +--- few predefined areas that must be black or blank. We encode the matrix with a two +--- dimensional field where the numbers determine which pixel is blank or not. +--- +--- The following code is used for our matrix: +--- 0 = not in use yet, +--- -2 = blank by mandatory pattern, +--- 2 = black by mandatory pattern, +--- -1 = blank by data, +--- 1 = black by data +--- +--- +--- To prepare the _empty_, we add positioning, alingment and timing patters. + +--- ### Positioning patterns ### +local function add_position_detection_patterns(tab_x) + local size = #tab_x + -- allocate quite zone in the matrix area + for i=1,8 do + for j=1,8 do + tab_x[i][j] = -2 + tab_x[size - 8 + i][j] = -2 + tab_x[i][size - 8 + j] = -2 + end + end + -- draw the detection pattern (outer) + for i=1,7 do + -- top left + tab_x[1][i]=2 + tab_x[7][i]=2 + tab_x[i][1]=2 + tab_x[i][7]=2 + + -- top right + tab_x[size][i]=2 + tab_x[size - 6][i]=2 + tab_x[size - i + 1][1]=2 + tab_x[size - i + 1][7]=2 + + -- bottom left + tab_x[1][size - i + 1]=2 + tab_x[7][size - i + 1]=2 + tab_x[i][size - 6]=2 + tab_x[i][size]=2 + end + -- draw the detection pattern (inner) + for i=1,3 do + for j=1,3 do + -- top left + tab_x[2+j][i+2]=2 + -- top right + tab_x[size - j - 1][i+2]=2 + -- bottom left + tab_x[2 + j][size - i - 1]=2 + end + end +end + +--- ### Timing patterns ### +-- The timing patterns (two) are the dashed lines between two adjacent positioning patterns on row/column 7. +local function add_timing_pattern(tab_x) + local line,col + line = 7 + col = 9 + for i=col,#tab_x - 8 do + if math.fmod(i,2) == 1 then + tab_x[i][line] = 2 + else + tab_x[i][line] = -2 + end + end + for i=col,#tab_x - 8 do + if math.fmod(i,2) == 1 then + tab_x[line][i] = 2 + else + tab_x[line][i] = -2 + end + end +end + + +--- ### Alignment patterns ### +--- The alignment patterns must be added to the matrix for versions > 1. The amount and positions depend on the versions and are +--- given by the spec. Beware: the patterns must not be placed where we have the positioning patterns +--- (that is: top left, top right and bottom left.) + +-- For each version, where should we place the alignment patterns? See table E.1 of the spec +local alignment_pattern = { + {},{6,18},{6,22},{6,26},{6,30},{6,34}, -- 1-6 + {6,22,38},{6,24,42},{6,26,46},{6,28,50},{6,30,54},{6,32,58},{6,34,62}, -- 7-13 + {6,26,46,66},{6,26,48,70},{6,26,50,74},{6,30,54,78},{6,30,56,82},{6,30,58,86},{6,34,62,90}, -- 14-20 + {6,28,50,72,94},{6,26,50,74,98},{6,30,54,78,102},{6,28,54,80,106},{6,32,58,84,110},{6,30,58,86,114},{6,34,62,90,118}, -- 21-27 + {6,26,50,74,98 ,122},{6,30,54,78,102,126},{6,26,52,78,104,130},{6,30,56,82,108,134},{6,34,60,86,112,138},{6,30,58,86,114,142},{6,34,62,90,118,146}, -- 28-34 + {6,30,54,78,102,126,150}, {6,24,50,76,102,128,154},{6,28,54,80,106,132,158},{6,32,58,84,110,136,162},{6,26,54,82,110,138,166},{6,30,58,86,114,142,170} -- 35 - 40 +} + +--- The alignment pattern has size 5x5 and looks like this: +--- XXXXX +--- X X +--- X X X +--- X X +--- XXXXX +local function add_alignment_pattern( tab_x ) + local version = (#tab_x - 17) / 4 + local ap = alignment_pattern[version] + local pos_x, pos_y + for x=1,#ap do + for y=1,#ap do + -- we must not put an alignment pattern on top of the positioning pattern + if not (x == 1 and y == 1 or x == #ap and y == 1 or x == 1 and y == #ap ) then + pos_x = ap[x] + 1 + pos_y = ap[y] + 1 + tab_x[pos_x][pos_y] = 2 + tab_x[pos_x+1][pos_y] = -2 + tab_x[pos_x-1][pos_y] = -2 + tab_x[pos_x+2][pos_y] = 2 + tab_x[pos_x-2][pos_y] = 2 + tab_x[pos_x ][pos_y - 2] = 2 + tab_x[pos_x+1][pos_y - 2] = 2 + tab_x[pos_x-1][pos_y - 2] = 2 + tab_x[pos_x+2][pos_y - 2] = 2 + tab_x[pos_x-2][pos_y - 2] = 2 + tab_x[pos_x ][pos_y + 2] = 2 + tab_x[pos_x+1][pos_y + 2] = 2 + tab_x[pos_x-1][pos_y + 2] = 2 + tab_x[pos_x+2][pos_y + 2] = 2 + tab_x[pos_x-2][pos_y + 2] = 2 + + tab_x[pos_x ][pos_y - 1] = -2 + tab_x[pos_x+1][pos_y - 1] = -2 + tab_x[pos_x-1][pos_y - 1] = -2 + tab_x[pos_x+2][pos_y - 1] = 2 + tab_x[pos_x-2][pos_y - 1] = 2 + tab_x[pos_x ][pos_y + 1] = -2 + tab_x[pos_x+1][pos_y + 1] = -2 + tab_x[pos_x-1][pos_y + 1] = -2 + tab_x[pos_x+2][pos_y + 1] = 2 + tab_x[pos_x-2][pos_y + 1] = 2 + end + end + end +end + +--- ### Type information ### +--- Let's not forget the type information that is in column 9 next to the left positioning patterns and on row 9 below +--- the top positioning patterns. This type information is not fixed, it depends on the mask and the error correction. + +-- The first index is ec level (LMQH,1-4), the second is the mask (0-7). This bitstring of length 15 is to be used +-- as mandatory pattern in the qrcode. Mask -1 is for debugging purpose only and is the 'noop' mask. +local typeinfo = { + { [-1]= "111111111111111", [0] = "111011111000100", "111001011110011", "111110110101010", "111100010011101", "110011000101111", "110001100011000", "110110001000001", "110100101110110" }, + { [-1]= "111111111111111", [0] = "101010000010010", "101000100100101", "101111001111100", "101101101001011", "100010111111001", "100000011001110", "100111110010111", "100101010100000" }, + { [-1]= "111111111111111", [0] = "011010101011111", "011000001101000", "011111100110001", "011101000000110", "010010010110100", "010000110000011", "010111011011010", "010101111101101" }, + { [-1]= "111111111111111", [0] = "001011010001001", "001001110111110", "001110011100111", "001100111010000", "000011101100010", "000001001010101", "000110100001100", "000100000111011" } +} + +-- The typeinfo is a mixture of mask and ec level information and is +-- added twice to the qr code, one horizontal, one vertical. +local function add_typeinfo_to_matrix( matrix,ec_level,mask ) + local ec_mask_type = typeinfo[ec_level][mask] + + local bit + -- vertical from bottom to top + for i=1,7 do + bit = string.sub(ec_mask_type,i,i) + fill_matrix_position(matrix, bit, 9, #matrix - i + 1) + end + for i=8,9 do + bit = string.sub(ec_mask_type,i,i) + fill_matrix_position(matrix,bit,9,17-i) + end + for i=10,15 do + bit = string.sub(ec_mask_type,i,i) + fill_matrix_position(matrix,bit,9,16 - i) + end + -- horizontal, left to right + for i=1,6 do + bit = string.sub(ec_mask_type,i,i) + fill_matrix_position(matrix,bit,i,9) + end + bit = string.sub(ec_mask_type,7,7) + fill_matrix_position(matrix,bit,8,9) + for i=8,15 do + bit = string.sub(ec_mask_type,i,i) + fill_matrix_position(matrix,bit,#matrix - 15 + i,9) + end +end + +-- Bits for version information 7-40 +-- The reversed strings from https://www.thonky.com/qr-code-tutorial/format-version-tables +local version_information = {"001010010011111000", "001111011010000100", "100110010101100100", "110010110010010100", + "011011111101110100", "010001101110001100", "111000100001101100", "101100000110011100", "000101001001111100", + "000111101101000010", "101110100010100010", "111010000101010010", "010011001010110010", "011001011001001010", + "110000010110101010", "100100110001011010", "001101111110111010", "001000110111000110", "100001111000100110", + "110101011111010110", "011100010000110110", "010110000011001110", "111111001100101110", "101011101011011110", + "000010100100111110", "101010111001000001", "000011110110100001", "010111010001010001", "111110011110110001", + "110100001101001001", "011101000010101001", "001001100101011001", "100000101010111001", "100101100011000101" } + +-- Versions 7 and above need two bitfields with version information added to the code +local function add_version_information(matrix,version) + if version < 7 then return end + local size = #matrix + local bitstring = version_information[version - 6] + local x,y, bit + local start_x, start_y + -- first top right + start_x = size - 10 + start_y = 1 + for i=1,#bitstring do + bit = string.sub(bitstring,i,i) + x = start_x + math.fmod(i - 1,3) + y = start_y + math.floor( (i - 1) / 3 ) + fill_matrix_position(matrix,bit,x,y) + end + + -- now bottom left + start_x = 1 + start_y = size - 10 + for i=1,#bitstring do + bit = string.sub(bitstring,i,i) + x = start_x + math.floor( (i - 1) / 3 ) + y = start_y + math.fmod(i - 1,3) + fill_matrix_position(matrix,bit,x,y) + end +end + +--- Now it's time to use the methods above to create a prefilled matrix for the given mask +local function prepare_matrix_with_mask( version,ec_level, mask ) + local size + local tab_x = {} + + size = version * 4 + 17 + for i=1,size do + tab_x[i]={} + for j=1,size do + tab_x[i][j] = 0 + end + end + add_position_detection_patterns(tab_x) + add_timing_pattern(tab_x) + add_version_information(tab_x,version) + + -- black pixel above lower left position detection pattern + tab_x[9][size - 7] = 2 + add_alignment_pattern(tab_x) + add_typeinfo_to_matrix(tab_x,ec_level, mask) + return tab_x +end + +--- Finally we come to the place where we need to put the calculated data (remember step 3?) into the qr code. +--- We do this for each mask. BTW speaking of mask, this is what we find in the spec: +--- Mask Pattern Reference Condition +--- 000 (y + x) mod 2 = 0 +--- 001 y mod 2 = 0 +--- 010 x mod 3 = 0 +--- 011 (y + x) mod 3 = 0 +--- 100 ((y div 2) + (x div 3)) mod 2 = 0 +--- 101 (y x) mod 2 + (y x) mod 3 = 0 +--- 110 ((y x) mod 2 + (y x) mod 3) mod 2 = 0 +--- 111 ((y x) mod 3 + (y+x) mod 2) mod 2 = 0 + +-- Return 1 (black) or -1 (blank) depending on the mask, value and position. +-- Parameter mask is 0-7 (-1 for 'no mask'). x and y are 1-based coordinates, +-- 1,1 = upper left. tonumber(value) must be 0 or 1. +local function get_pixel_with_mask( mask, x,y,value ) + x = x - 1 + y = y - 1 + local invert = false + -- test purpose only: + if mask == -1 then -- luacheck: ignore + -- ignore, no masking applied + elseif mask == 0 then + if math.fmod(x + y,2) == 0 then invert = true end + elseif mask == 1 then + if math.fmod(y,2) == 0 then invert = true end + elseif mask == 2 then + if math.fmod(x,3) == 0 then invert = true end + elseif mask == 3 then + if math.fmod(x + y,3) == 0 then invert = true end + elseif mask == 4 then + if math.fmod(math.floor(y / 2) + math.floor(x / 3),2) == 0 then invert = true end + elseif mask == 5 then + if math.fmod(x * y,2) + math.fmod(x * y,3) == 0 then invert = true end + elseif mask == 6 then + if math.fmod(math.fmod(x * y,2) + math.fmod(x * y,3),2) == 0 then invert = true end + elseif mask == 7 then + if math.fmod(math.fmod(x * y,3) + math.fmod(x + y,2),2) == 0 then invert = true end + else + assert(false,"This can't happen (mask must be <= 7)") + end + if invert then + -- value = 1? -> -1, value = 0? -> 1 + return 1 - 2 * tonumber(value) + else + -- value = 1? -> 1, value = 0? -> -1 + return -1 + 2*tonumber(value) + end +end + + +-- We need up to 8 positions in the matrix. Only the last few bits may be less then 8. +-- The function returns a table of (up to) 8 entries with subtables where +-- the x coordinate is the first and the y coordinate is the second entry. +local function get_next_free_positions(matrix,x,y,dir,byte) + local ret = {} + local count = 1 + local mode = "right" + while count <= #byte do + if mode == "right" and matrix[x][y] == 0 then + ret[#ret + 1] = {x,y} + mode = "left" + count = count + 1 + elseif mode == "left" and matrix[x-1][y] == 0 then + ret[#ret + 1] = {x-1,y} + mode = "right" + count = count + 1 + if dir == "up" then + y = y - 1 + else + y = y + 1 + end + elseif mode == "right" and matrix[x-1][y] == 0 then + ret[#ret + 1] = {x-1,y} + count = count + 1 + if dir == "up" then + y = y - 1 + else + y = y + 1 + end + else + if dir == "up" then + y = y - 1 + else + y = y + 1 + end + end + if y < 1 or y > #matrix then + x = x - 2 + -- don't overwrite the timing pattern + if x == 7 then x = 6 end + if dir == "up" then + dir = "down" + y = 1 + else + dir = "up" + y = #matrix + end + end + end + return ret,x,y,dir +end + +-- Add the data string (0's and 1's) to the matrix for the given mask. +local function add_data_to_matrix(matrix,data,mask) + local size = #matrix + local x,y,positions + local _x,_y,m + local dir = "up" + local byte_number = 0 + x,y = size,size + string.gsub(data,".?.?.?.?.?.?.?.?",function ( byte ) + byte_number = byte_number + 1 + positions,x,y,dir = get_next_free_positions(matrix,x,y,dir,byte) + for i=1,#byte do + _x = positions[i][1] + _y = positions[i][2] + m = get_pixel_with_mask(mask,_x,_y,string.sub(byte,i,i)) + if debugging then + matrix[_x][_y] = m * (i + 10) + else + matrix[_x][_y] = m + end + end + end) +end + + +--- The total penalty of the matrix is the sum of four steps. The following steps are taken into account: +--- +--- 1. Adjacent modules in row/column in same color +--- 1. Block of modules in same color +--- 1. 1:1:3:1:1 ratio (dark:light:dark:light:dark) pattern in row/column +--- 1. Proportion of dark modules in entire symbol +--- +--- This all is done to avoid bad patterns in the code that prevent the scanner from +--- reading the code. +-- Return the penalty for the given matrix +local function calculate_penalty(matrix) + local penalty1, penalty2, penalty3 = 0,0,0 + local size = #matrix + -- this is for penalty 4 + local number_of_dark_cells = 0 + + -- 1: Adjacent modules in row/column in same color + -- -------------------------------------------- + -- No. of modules = (5+i) -> 3 + i + local last_bit_blank -- < 0: blank, > 0: black + local is_blank + local number_of_consecutive_bits + -- first: vertical + for x=1,size do + number_of_consecutive_bits = 0 + last_bit_blank = nil + for y = 1,size do + if matrix[x][y] > 0 then + -- small optimization: this is for penalty 4 + number_of_dark_cells = number_of_dark_cells + 1 + is_blank = false + else + is_blank = true + end + if last_bit_blank == is_blank then + number_of_consecutive_bits = number_of_consecutive_bits + 1 + else + if number_of_consecutive_bits >= 5 then + penalty1 = penalty1 + number_of_consecutive_bits - 2 + end + number_of_consecutive_bits = 1 + end + last_bit_blank = is_blank + end + if number_of_consecutive_bits >= 5 then + penalty1 = penalty1 + number_of_consecutive_bits - 2 + end + end + -- now horizontal + for y=1,size do + number_of_consecutive_bits = 0 + last_bit_blank = nil + for x = 1,size do + is_blank = matrix[x][y] < 0 + if last_bit_blank == is_blank then + number_of_consecutive_bits = number_of_consecutive_bits + 1 + else + if number_of_consecutive_bits >= 5 then + penalty1 = penalty1 + number_of_consecutive_bits - 2 + end + number_of_consecutive_bits = 1 + end + last_bit_blank = is_blank + end + if number_of_consecutive_bits >= 5 then + penalty1 = penalty1 + number_of_consecutive_bits - 2 + end + end + for x=1,size do + for y=1,size do + -- 2: Block of modules in same color + -- ----------------------------------- + -- Blocksize = m × n -> 3 × (m-1) × (n-1) + if (y < size - 1) and ( x < size - 1) and ( (matrix[x][y] < 0 and matrix[x+1][y] < 0 and matrix[x][y+1] < 0 and matrix[x+1][y+1] < 0) or (matrix[x][y] > 0 and matrix[x+1][y] > 0 and matrix[x][y+1] > 0 and matrix[x+1][y+1] > 0) ) then + penalty2 = penalty2 + 3 + end + + -- 3: 1:1:3:1:1 ratio (dark:light:dark:light:dark) pattern in row/column + -- ------------------------------------------------------------------ + -- Gives 40 points each + -- + -- I have no idea why we need the extra 0000 on left or right side. The spec doesn't mention it, + -- other sources do mention it. This is heavily inspired by zxing. + if (y + 6 < size and + matrix[x][y] > 0 and + matrix[x][y + 1] < 0 and + matrix[x][y + 2] > 0 and + matrix[x][y + 3] > 0 and + matrix[x][y + 4] > 0 and + matrix[x][y + 5] < 0 and + matrix[x][y + 6] > 0 and + ((y + 10 < size and + matrix[x][y + 7] < 0 and + matrix[x][y + 8] < 0 and + matrix[x][y + 9] < 0 and + matrix[x][y + 10] < 0) or + (y - 4 >= 1 and + matrix[x][y - 1] < 0 and + matrix[x][y - 2] < 0 and + matrix[x][y - 3] < 0 and + matrix[x][y - 4] < 0))) then penalty3 = penalty3 + 40 end + if (x + 6 <= size and + matrix[x][y] > 0 and + matrix[x + 1][y] < 0 and + matrix[x + 2][y] > 0 and + matrix[x + 3][y] > 0 and + matrix[x + 4][y] > 0 and + matrix[x + 5][y] < 0 and + matrix[x + 6][y] > 0 and + ((x + 10 <= size and + matrix[x + 7][y] < 0 and + matrix[x + 8][y] < 0 and + matrix[x + 9][y] < 0 and + matrix[x + 10][y] < 0) or + (x - 4 >= 1 and + matrix[x - 1][y] < 0 and + matrix[x - 2][y] < 0 and + matrix[x - 3][y] < 0 and + matrix[x - 4][y] < 0))) then penalty3 = penalty3 + 40 end + end + end + -- 4: Proportion of dark modules in entire symbol + -- ---------------------------------------------- + -- 50 ± (5 × k)% to 50 ± (5 × (k + 1))% -> 10 × k + local dark_ratio = number_of_dark_cells / ( size * size ) + local penalty4 = math.floor(math.abs(dark_ratio * 100 - 50)) * 2 + return penalty1 + penalty2 + penalty3 + penalty4 +end + +-- Create a matrix for the given parameters and calculate the penalty score. +-- Return both (matrix and penalty) +local function get_matrix_and_penalty(version,ec_level,data,mask) + local tab = prepare_matrix_with_mask(version,ec_level,mask) + add_data_to_matrix(tab,data,mask) + local penalty = calculate_penalty(tab) + return tab, penalty +end + +-- Return the matrix with the smallest penalty. To to this +-- we try out the matrix for all 8 masks and determine the +-- penalty (score) each. +local function get_matrix_with_lowest_penalty(version,ec_level,data) + local tab, penalty + local tab_min_penalty, min_penalty + + -- try masks 0-7 + tab_min_penalty, min_penalty = get_matrix_and_penalty(version,ec_level,data,0) + for i=1,7 do + tab, penalty = get_matrix_and_penalty(version,ec_level,data,i) + if penalty < min_penalty then + tab_min_penalty = tab + min_penalty = penalty + end + end + return tab_min_penalty +end + +--- The main function. We connect everything together. Remember from above: +--- +--- 1. Determine version, ec level and mode (=encoding) for codeword +--- 1. Encode data +--- 1. Arrange data and calculate error correction code +--- 1. Generate 8 matrices with different masks and calculate the penalty +--- 1. Return qrcode with least penalty +-- If ec_level or mode is given, use the ones for generating the qrcode. (mode is not implemented yet) +local function qrcode( str, ec_level, _mode ) -- luacheck: no unused args + local arranged_data, version, data_raw, mode, len_bitstring + version, ec_level, data_raw, mode, len_bitstring = get_version_eclevel_mode_bistringlength(str,ec_level) + data_raw = data_raw .. len_bitstring + data_raw = data_raw .. encode_data(str,mode) + data_raw = add_pad_data(version,ec_level,data_raw) + arranged_data = arrange_codewords_and_calculate_ec(version,ec_level,data_raw) + if math.fmod(#arranged_data,8) ~= 0 then + return false, string.format("Arranged data %% 8 != 0: data length = %d, mod 8 = %d",#arranged_data, math.fmod(#arranged_data,8)) + end + arranged_data = arranged_data .. string.rep("0",remainder[version]) + local tab = get_matrix_with_lowest_penalty(version,ec_level,arranged_data) + return true, tab +end + + +if testing then + return { + encode_string_numeric = encode_string_numeric, + encode_string_ascii = encode_string_ascii, + qrcode = qrcode, + binary = binary, + get_mode = get_mode, + get_length = get_length, + add_pad_data = add_pad_data, + get_generator_polynominal_adjusted = get_generator_polynominal_adjusted, + get_pixel_with_mask = get_pixel_with_mask, + get_version_eclevel_mode_bistringlength = get_version_eclevel_mode_bistringlength, + remainder = remainder, + --get_capacity_remainder = get_capacity_remainder, + arrange_codewords_and_calculate_ec = arrange_codewords_and_calculate_ec, + calculate_error_correction = calculate_error_correction, + convert_bitstring_to_bytes = convert_bitstring_to_bytes, + bit_xor = bit_xor, + } +end + +return { + qrcode = qrcode +} diff --git a/macros/latex/contrib/qrbill/qrbill.dtx b/macros/latex/contrib/qrbill/qrbill.dtx index 6d169404d5..c7739d81d3 100644 --- a/macros/latex/contrib/qrbill/qrbill.dtx +++ b/macros/latex/contrib/qrbill/qrbill.dtx @@ -2,7 +2,7 @@ % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % -% Copyright (C) 2020–2022 by Marei Peischl (peiTeX) +% Copyright (C) 2020–2023 by Marei Peischl (peiTeX) % % This work is a collaboration of % Marei Peischl (peiTeX) and Alex Antener (foobar LLC). @@ -54,7 +54,7 @@ % \fi % \iffalse %<*driver> -\ProvidesFile{qrbill.dtx}[2022/10/20 v1.07 \ create QR-bills based on the Swiss standard] +\ProvidesFile{qrbill.dtx}[2023/02/28 v2.00 \ create QR-bills based on the Swiss standard] \documentclass[english, parskip=half-]{scrartcl} \usepackage{iftex} \ifPDFTeX @@ -284,8 +284,8 @@ % \changes{v1.06}{2022/10/18}{Add ignore-if-empty option} % % \item[qrmode (package/lua) (package)] Selects the mechanism for QRcode generation. +% \changes{v2.00}{2023/02/28}{qrencode.lua now is part of the qrbill package} % With Version 2.0 the package supports usage of the the luaqrcode library \cite{luaqrcode}. This can be enabled by using the \latexinline{qmode=lua} option. -% In that case the luaqrcode libary has to be installed within the \verb+$LUAINPUTS+. % % \item[qrscheme (Name of a custom QRbill scheme) (swiss)] % Loads the definitions for the QRcode and the BillingInformation. Currently only the @@ -514,7 +514,7 @@ % \section{Implementation} % \begin{macrocode} \RequirePackage{expl3} -\ProvidesExplPackage{qrbill}{2022/10/20}{1.07}{ +\ProvidesExplPackage{qrbill}{2023/02/28}{2.00}{ Template for QR-bills based on the Swiss Payment Standards } \RequirePackage{iftex} @@ -866,7 +866,7 @@ \skip_vertical:n {\c_qrbill_sep_dim-\g__qrbill_rule_dim} \skip_horizontal:n {\c_qrbill_sep_dim-\g__qrbill_rule_dim} \begin{minipage}[c][95mm][t]{52mm} - \vbox_to_ht:nn {7mm} {\qrbill_title_font:\qrbillreceiptname} + \vbox_to_ht:nn {7mm} {\qrbill_title_font:\qrbillreceiptname\vfill} \par\nointerlineskip \vbox_to_ht:nn {56mm}{ {\qrbill_headingR_font:\qrbillaccountname\par} @@ -896,6 +896,7 @@ \par } } + \vfill } \par\nointerlineskip \vbox_to_ht:nn {14mm}{ @@ -918,12 +919,13 @@ \par\nointerlineskip \vbox_to_ht:nn {18mm} { \makebox[\linewidth][r]{\qrbill_headingR_font:\qrbillacceptantname}\par + \vfill } \end{minipage}% \skip_horizontal:n {2\c_qrbill_sep_dim} \begin{minipage}[c][95mm][t]{138mm} \begin{minipage}[c][85mm][t]{51mm} - \parbox[t][7mm][t]{\linewidth}{\qrbill_title_font:\qrbillpaymentpartname} + \parbox[t][7mm][t]{\linewidth}{\qrbill_title_font:\qrbillpaymentpartname\vfill} \par\nointerlineskip \skip_vertical:n {\c_qrbill_sep_dim} \qrcode_setup_QRcode: @@ -950,9 +952,10 @@ \tl_if_empty:NTF \l_qrbill_data_Amount_tl { \hfill \raisebox{\dimexpr-\height+\ht\strutbox}[\z@]{ - \llap{\__qrbill_placeholder:nn {40mm} {15mm} - }} + \llap{\__qrbill_placeholder:nn {40mm} {15mm}} + } } + \vfill } \end{minipage} \begin{minipage}[c][85mm][t]{87mm} @@ -964,6 +967,7 @@ \qrbill_insert_address:N \g__qrbill_creditorprefix_tl \par\vskip\baselineskip } + \raggedright \tl_if_empty:NF \l_qrbill_data_Reference_tl { {\qrbill_headingP_font:\qrbillreferencename\par} {\qrbill_valueP_font: @@ -1017,6 +1021,7 @@ {\rule{\g__qrbill_rule_dim}{\c_qrbill_height_dim}} {\rule{\g__qrbill_rule_dim}{\c_zero_dim}} } + \vfill } } \endgroup diff --git a/macros/latex/contrib/qrbill/qrbill.ins b/macros/latex/contrib/qrbill/qrbill.ins index 00a8697623..1fe8b6669e 100644 --- a/macros/latex/contrib/qrbill/qrbill.ins +++ b/macros/latex/contrib/qrbill/qrbill.ins @@ -2,17 +2,17 @@ \preamble -Copyright (C) 2020–2022 by Marei Peischl (peiTeX) +Copyright (C) 2020–2023 by Marei Peischl (peiTeX) This work is a collaboration of Marei Peischl (peiTeX) and Alex Antener (foobar LLC). This work may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either version 1.3 +conditions of the LaTeX Project Public License, either version 1.3c of this license or (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt -and version 1.3 or later is part of all distributions of LaTeX +and version 1.3c or later is part of all distributions of LaTeX version 2005/12/01 or later. This work has the LPPL maintenance status `maintained'. diff --git a/macros/latex/contrib/qrbill/qrbill.pdf b/macros/latex/contrib/qrbill/qrbill.pdf index 3684e2c948..1125e6cddc 100644 Binary files a/macros/latex/contrib/qrbill/qrbill.pdf and b/macros/latex/contrib/qrbill/qrbill.pdf differ diff --git a/macros/xetex/latex/xduts/xduts.dtx b/macros/xetex/latex/xduts/xduts.dtx index dd3b3a0706..b296c67b8e 100644 --- a/macros/xetex/latex/xduts/xduts.dtx +++ b/macros/xetex/latex/xduts/xduts.dtx @@ -1,7 +1,7 @@ % \iffalse %<*driver> \ProvidesFile{xduts.dtx} -[2023/03/01 v5.6.0.0 Xidian University TeX Suite] +[2023/03/02 v6.0.0.0 Xidian University TeX Suite] % %\NeedsTeXFormat{LaTeX2e} %\RequirePackage{expl3} @@ -9,7 +9,7 @@ %\ProvidesExplClass{xduugtp} %\ProvidesExplClass{xdupgthesis} %\ProvidesExplClass{xduugthesis} -% {2023/03/01}{5.6.0.0} +% {2023/03/02}{6.0.0.0} % {Xidian University Font package} % {Xidian University Undergraduate Thesis Proposal class} % {Xidian University Postgraduate Thesis document class} @@ -666,8 +666,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \opt{style/title-bold-math} = true|(false) % \end{syntax} % 是否自动加粗如下位置中的数学字体: -% 中文研究生学位论文中,封面和提名页中英文标题,正文所有级别标题和目录一级标题; -% 英文研究生学位论文中,封面和提名页中英文标题,正文二三四五六级标题和中文目录一级标题; +% 中文研究生学位论文中,封面和题名页中英文标题,正文所有级别标题和目录一级标题; +% 英文研究生学位论文中,封面和题名页中英文标题,正文二三四五六级标题和中文目录一级标题; % 本科生毕业设计论文中,封面标题,中英文关键词,目录一级标题和正文一级标题。 % 目前仅支持Computer Modern数学字体。 % \end{function} @@ -1634,15 +1634,16 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \setlength\parindent{2em} % \subsection{页面和信息移除} % \label{页面和信息移除} +% \changes{v6.0.0.0}{2023/03/02}{修正题名页键值} % \changes{v2.12.1.0}{2022/07/03}{页面和信息移除选项增加分组} -% \begin{function}[added=2022-06-26]{style/remove-page} +% \begin{function}[added=2022-06-26,updated=2023-03-02]{style/remove-page} % \begin{syntax} -% \opt{style/remove-page} = \marg{封面|提名页|声明页|摘要|索引|对照表|目录|附录|参考文献|致谢|作者简介} +% \opt{style/remove-page} = \marg{封面|题名页|声明页|摘要|索引|对照表|目录|附录|参考文献|致谢|作者简介} % \end{syntax} % 设置移除的页面,可多选,多个值之间需要使用英文半角逗号隔开。 % \end{function} % \begin{optdesc} -% \item[提名页] 中英文提名页。 +% \item[题名页] 中英文题名页。 % \item[摘要] 中英文摘要。 % \item[索引] 图片索引和表格索引。 % \item[对照表] 符号对照表和缩略语对照表。 @@ -3458,7 +3459,7 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \begin{macrocode} \bool_new:N \l_@@_rm_cover_bool % \end{macrocode} -% 中英文提名页。 +% 中英文题名页。 % \begin{macrocode} \bool_new:N \l_@@_rm_title_page_bool % \end{macrocode} @@ -3510,6 +3511,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} { \bool_set_true:N \l_@@_rm_cover_bool } \clist_if_in:NnT \l_@@_rm_page_clist { 提名页 } { \bool_set_true:N \l_@@_rm_title_page_bool } + \clist_if_in:NnT \l_@@_rm_page_clist { 题名页 } + { \bool_set_true:N \l_@@_rm_title_page_bool } \clist_if_in:NnT \l_@@_rm_page_clist { 声明页 } { \bool_set_true:N \l_@@_rm_statement_bool } \clist_if_in:NnT \l_@@_rm_page_clist { 摘要 } @@ -6143,8 +6146,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \end{variable} % \begin{macro}{\@@_cover_i:nnnnn} % \changes{v1.16.0.0}{2022/05/22}{绘制研究生封面单行内容} -% \changes{v1.17.0.0}{2022/05/28}{绘制研究生封面和提名页单行内容} -% 绘制研究生封面和提名页单行内容。 +% \changes{v1.17.0.0}{2022/05/28}{绘制研究生封面和题名页单行内容} +% 绘制研究生封面和题名页单行内容。 % \begin{arguments} % \item 盒子高度。 % \item 字体族。 @@ -6205,8 +6208,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \end{macrocode} % \end{macro} % \begin{macro}{\@@_cover_iii:nnnn} -% \changes{v1.17.0.0}{2022/05/28}{绘制研究生中文提名页顶部信息} -% 绘制研究生中文提名页顶部信息。 +% \changes{v1.17.0.0}{2022/05/28}{绘制研究生中文题名页顶部信息} +% 绘制研究生中文题名页顶部信息。 % \begin{arguments} % \item 标签宽度。 % \item 标签名称。 @@ -6320,7 +6323,7 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \end{macrocode} % \end{macro} % \begin{macro}{\@@_cover_author_info:} -% \changes{v2.18.1.0}{2022/12/01}{修正专业博士封面和提名页信息} +% \changes{v2.18.1.0}{2022/12/01}{修正专业博士封面和题名页信息} % \changes{v1.26.4.0}{2022/06/10}{研究生封面底部作者信息} % 研究生封面底部作者信息。 % \begin{macrocode} @@ -6394,15 +6397,15 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} } % \end{macrocode} % \end{macro} -% \paragraph{中文提名页} +% \paragraph{中文题名页} % \begin{macro}{\@@_zh_title_page_info:} -% \changes{v1.26.7.0}{2022/06/11}{拆分研究生中文提名页底部信息} -% 中文提名页底部信息。 +% \changes{v1.26.7.0}{2022/06/11}{拆分研究生中文题名页底部信息} +% 中文题名页底部信息。 % \begin{macrocode} \cs_new:Npn \@@_zh_title_page_info: { % \end{macrocode} -% \changes{v1.26.6.0}{2022/06/11}{研究生中文提名页底部信息宽度测量} +% \changes{v1.26.6.0}{2022/06/11}{研究生中文题名页底部信息宽度测量} % 底部信息宽度测量。 % \begin{macrocode} \rmfamily \zihao { 4 } @@ -6448,8 +6451,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} \@@_str_max_dim:Nn \l_@@_zh_title_page_info_dim { 提交日期:\@@_zh_submit_date: } % \end{macrocode} -% \changes{v1.26.6.0}{2022/06/11}{研究生中文提名页底部信息自动居中} -% \changes{v1.26.10.0}{2022/06/17}{修正中文提名页底部信息字体系列} +% \changes{v1.26.6.0}{2022/06/11}{研究生中文题名页底部信息自动居中} +% \changes{v1.26.10.0}{2022/06/17}{修正中文题名页底部信息字体系列} % 底部信息。 % \begin{macrocode} \dim_new:N \l_@@_zh_title_page_info_skip_dim @@ -6509,8 +6512,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \end{macrocode} % \end{macro} % \begin{macro}{\@@_zh_title_page:} -% \changes{v1.17.0.0}{2022/05/28}{中文提名页} -% 中文提名页。 +% \changes{v1.17.0.0}{2022/05/28}{中文题名页} +% 中文题名页。 % \begin{macrocode} \cs_new:Npn \@@_zh_title_page: { @@ -6540,8 +6543,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} \@@_cover_i:nnnnn { 100pt } { sf } { 1 } { bf } { 西安电子科技大学 } \@@_cover_i:nnnnn { 85pt } { rm } { -1 } { bf } { \l_@@_gr_type_tl 学位论文 } % \end{macrocode} -% \changes{v4.4.0.0}{2023/02/03}{研究生中文提名页标题中数学字体加粗} -% \changes{v1.18.1.0}{2022/05/30}{不拆分研究生中文提名页标题} +% \changes{v4.4.0.0}{2023/02/03}{研究生中文题名页标题中数学字体加粗} +% \changes{v1.18.1.0}{2022/05/30}{不拆分研究生中文题名页标题} % 论文标题。 % \begin{macrocode} \skip_vertical:n { 87.5pt } @@ -6561,10 +6564,10 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} } % \end{macrocode} % \end{macro} -% \paragraph{中文提名页} +% \paragraph{中文题名页} % \begin{macro}{\@@_en_title_supv:n} -% \changes{v1.18.0.0}{2022/05/29}{英文提名页底部导师姓名拼音盒子} -% 英文提名页底部导师姓名拼音盒子。 +% \changes{v1.18.0.0}{2022/05/29}{英文题名页底部导师姓名拼音盒子} +% 英文题名页底部导师姓名拼音盒子。 % \begin{macrocode} \dim_new:N \l_@@_supv_dim \dim_new:N \l_@@_supv_max_dim @@ -6596,8 +6599,8 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \end{macrocode} % \end{macro} % \begin{macro}{\@@_en_title_supv_t:n} -% \changes{v1.18.0.0}{2022/05/29}{英文提名页底部导师英文职称盒子} -% 英文提名页底部导师英文职称盒子。 +% \changes{v1.18.0.0}{2022/05/29}{英文题名页底部导师英文职称盒子} +% 英文题名页底部导师英文职称盒子。 % \begin{macrocode} \dim_new:N \l_@@_supv_t_dim \dim_new:N \l_@@_supv_t_max_dim @@ -6629,11 +6632,11 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} % \end{macrocode} % \end{macro} % \begin{macro}{\@@_en_title_page:} -% \changes{v4.4.0.0}{2023/02/03}{研究生英文提名页标题中数学字体加粗} -% \changes{v1.18.0.0}{2022/05/29}{英文提名页} +% \changes{v4.4.0.0}{2023/02/03}{研究生英文题名页标题中数学字体加粗} +% \changes{v1.18.0.0}{2022/05/29}{英文题名页} % \changes{v1.26.1.0}{2022/06/07}{修复作者拼音为空无法编译} -% \changes{v1.26.11.0}{2022/06/17}{修复非专业硕士英文提名页英文一级学科} -% 英文提名页。 +% \changes{v1.26.11.0}{2022/06/17}{修复非专业硕士英文题名页英文一级学科} +% 英文题名页。 % \begin{macrocode} \cs_new:Npn \@@_en_title_page: { @@ -7278,7 +7281,7 @@ literate = {\$}{{\textcolor{purple3}{\$}}}{1} \cleardoublepage } % \end{macrocode} -% 中英文提名页。 +% 中英文题名页。 % \begin{macrocode} \bool_if:NF \l_@@_rm_title_page_bool { diff --git a/macros/xetex/latex/xduts/xduts.pdf b/macros/xetex/latex/xduts/xduts.pdf index fb8da7ce64..065431c812 100644 Binary files a/macros/xetex/latex/xduts/xduts.pdf and b/macros/xetex/latex/xduts/xduts.pdf differ -- cgit v1.2.3