diff options
Diffstat (limited to 'macros/latex/contrib/etoc/etoc.dtx')
-rw-r--r-- | macros/latex/contrib/etoc/etoc.dtx | 625 |
1 files changed, 460 insertions, 165 deletions
diff --git a/macros/latex/contrib/etoc/etoc.dtx b/macros/latex/contrib/etoc/etoc.dtx index 1745aef818..09c808b774 100644 --- a/macros/latex/contrib/etoc/etoc.dtx +++ b/macros/latex/contrib/etoc/etoc.dtx @@ -2,20 +2,20 @@ % 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: <30-04-2023 at 21:53:47 CEST>}% +\def\etocdtxtimestamp {Time-stamp: <04-07-2023 at 22:33:21 CEST>}% %</none> %<*!readme> %% %% Package: etoc -%% Version: 1.2a +%% Version: 1.2b %% License: LPPL 1.3c %% Copyright (C) 2012-2023 Jean-Francois Burnol %% <jfbu at free dot fr> %</!readme> %<*none> -\def\etocpkgdate {2023/05/01} -\def\etocdocdate {2023/05/01} -\def\etocpkgversion {1.2a} +\def\etocpkgdate {2023/07/01} +\def\etocdocdate {2023/07/01} +\def\etocpkgversion {1.2b} \def\etocpkgdescription {Completely customisable TOCs (JFB)} %% 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. @@ -29,7 +29,7 @@ \catcode32=13\catcode`\\=12^^Brelax^^A ^^Bfirstofone{^^Bendgroup^^Bdef^^BetocLicense^^A {% Package: etoc -% Version: 1.2a +% Version: 1.2b % License: LPPL 1.3c % Copyright (C) 2012-2023 Jean-Francois Burnol <jfbu at free dot fr> % @@ -56,7 +56,7 @@ %<*readme> <!-- --> - Source: etoc.dtx (1.2a) + Source: etoc.dtx (1.2b) Author: Jean-Francois Burnol Info: Completely customisable TOCs License: LPPL 1.3c @@ -137,23 +137,26 @@ etoc.sty, etoc.tex, etoc.pdf, etoc.dvi. RECENT CHANGES ============== -This is `1.2a` of `2023/05/01`. +- `1.2b 2023/07/01` fixes a regression from `1.2` regarding concomitant + usage of the package with `tocloft`. Some documentation improvements, + in particular discussion of compatibility with `microtype`. -- `1.2a` lifted the requirement added at `1.1a` of a LaTeX kernel from - 2020-10-01 or later, and also the requirement added at `1.2` of - availability of the `\expanded` engine primitive. It also added a - `deeplevels` option. +- `1.2a 2023/05/01` lifts the requirement added at `1.1a` of a LaTeX + kernel from 2020-10-01 or later, and also the requirement added at + `1.2` of availability of the `\expanded` engine primitive. It also + adds a `deeplevels` option. -- `1.2` completed the core internal refactoring from `1.1a-d` and added - **experimental** `\locallistoffigures` and `\locallistoftables`. It also - let `\localtableofcontents` by default auto-select a heading style - adapted to location, and added options to control whether local TOCs - and Lists Of add an entry corresponding to their heading in the `.toc` - file. Compatibility with `tocbibind` package, too. +- `1.2 2023/03/01` completes the core internal refactoring from + `1.1a-d` and adds **experimental** `\locallistoffigures` and + `\locallistoftables`. It lets `\localtableofcontents` by default + auto-select a heading style adapted to its location inside the document + hierarchy, and adds options to control whether local TOCs and Lists Of + add an entry corresponding to their heading in the `.toc` file. + Compatibility with `tocbibind` package, too. -- `1.1a` up to `1.1d` were mainly about refactoring core legacy code. - In part, this is to prepare for future changes relative to how - hyperref and the LaTeX kernel will interact in the future. +- `1.1a 2023/01/14` up to `1.1d` are mainly about refactoring core + legacy code. In part, this is to prepare for future changes relative + to how hyperref and the LaTeX kernel will interact in the future. %</readme> %<*tex>------------------------------------------------------------------------- @@ -626,7 +629,7 @@ This is `1.2a` of `2023/05/01`. % Use the Bitter typeface for the romanfamily \usepackage[scale=0.87]{bitter} -\AddToHook{begin/document/after}{% +\AtBeginDocument{% \renewcommand{\familydefault}{\sfdefault}% \rmfamily } @@ -1158,12 +1161,16 @@ next-toc-with-tags \ifnum\Withdvipdfmx=1 \else % should I check for xetex/luatex ? -\usepackage{microtype} +\usepackage[nopatch=toc]{microtype} +\AtBeginDocument{\addtocontents{toc}{\protect\microtypesetup{protrusion=false}}} \fi \def\etocoption#1{{\color{optioncolor}\bfseries\texttt{#1}}} \begin{document} +% \normalsize % change rien à un parindent un peu grand si 4 +\parindent 3\fontcharwd\font`x\relax + \marginparsep 6bp \thispagestyle{empty} @@ -2357,6 +2364,7 @@ or the core \TeX |\begingroup/\endgroup| (or braces |{...}|) constructs. \begingroup \etocsettocstyle{}{} \etocstandardlines +\microtypesetup{protrusion=false} \DeclareTOCStyleEntry[numwidth=3em,indent=0em]{tocline}{subsection} \DeclareTOCStyleEntry[numwidth=3.5em,indent=3em]{tocline}{subsubsection} \localtableofcontents \label{toc:tocstyle} @@ -2801,7 +2809,7 @@ not above the title). % problème avec \xspace With this set-up issuing \localtoc\unskip|*| will ignore the \csb{etocaftertitlehook} -hence not send the local toc title to the |.toc| file. This mimicks the +hence not send the local toc title to the |.toc| file. This mimics the \ctanpkg{memoir} class behavior, and can also be used with it. For more on \ctanpkg{memoir} class with \etoc, see \autoref{ssec:memoir}. @@ -2841,6 +2849,9 @@ skip of one baseline, which is unwanted in our usage. \begingroup \etocsettocstyle{}{} +%\setuptoc{toc}{noprotrusion}% pas d'effet mais c'est normal car ce n'est pas +% % KOMA mais etoc qui fait le style global +\microtypesetup{protrusion=false} \DeclareTOCStyleEntry[numwidth=3.2em,indent=0em]{tocline}{subsection} \etocstandardlines \localtableofcontents \label{toc:linestyles} @@ -3517,6 +3528,7 @@ currently defined, not the ones from the cloned toc. % but then I probably need some extra KOMA stuff to % counteract the setspace effet \begingroup +\microtypesetup{protrusion=false} \DeclareTOCStyleEntry[numwidth=2em,indent=0pt]{tocline}{section} \DeclareTOCStyleEntry[numwidth=2.5em,indent=2em]{tocline}{subsection} \DeclareTOCStyleEntry[numwidth=3em,indent=4.5em]{tocline}{subsubsection} @@ -3584,6 +3596,7 @@ subsection, etc... (see also \csb{etocsetnexttocdepth}).% \section{Labeling and reusing elsewhere} \label{sec:labeling} +\label{invisiblelocaltableofcontents} \etoc allows to typeset at some location a local table of contents which is defined elsewhere. For this, two simple steps: @@ -3833,6 +3846,7 @@ re-activate it. The package does initially \csb{etocobeytoctocdepth}. \label{etocdepthtag.toc} \label{etocimmediatedepthtag.toc} \label{etocsettagdepth} +\label{sec:depthtags} @@ -4009,6 +4023,24 @@ I use the following trick: either in the preamble using indeed be set many times with |\hypersetup| (this is not the case of all \ctanpkg{hyperref} options). +\subsection{Disabling protrusion in all TOCs} +\label{ssec:disableprotrusion} + +If using \ctanpkg{microtype} it looks like a generally advisable counsel to +disable protrusion in particular for all TOCs (see however +\autoref{ssec:microtype} for further information if you don't want to do +that). To achieve this simply add +% +\centeredline{|\addtocontents{toc}{\protect\microtypesetup{protrusion=false}}|} +% +immediately after |\begin{document}| (or use |\AtBeginDocument|). We ended up +doing this for the present document after checking for a few of our TOCs that +it improved their looks. As \etoc always encloses the typesetting of tables of +contents inside scope limiting groups, the effect will be limited to tables of +contents only. Notice that adding the above command to an existing document will +have an effect only on second compilation. + + \section[The \csbhyp{etocsetlocaltop.toc} command] {The \csbhyp{etocsetlocaltop.toc} and \csbhyp{etocimmediatesetlocaltop.toc} commands} @@ -4258,26 +4290,11 @@ and \autoref{sec:tocstyle}. \section{A first example} \label{sec:firstexample} -\label{invisiblelocaltableofcontents} -Let us present a first example of specification for line styles. -Immediately after the start of \autoref{part:overview} we inserted in the -source file: -% -\centeredline{\csb{invisiblelocaltableofcontents} |\label{toc:overview}|} -% -This -sets-up the label |toc:overview|, and we can use it at any location in the -document: -% -\centeredline{|\tableofcontents \ref{toc:overview}|} -% -And as we used -|\invisible...|,\footnote{this is a shortcut for setting temporarily the - |tocdepth| to |-3|, which has the effect to tell \etoc not to print the TOC, - and not even the heading.} the local TOC will exist only through its clones -elsewhere in the document. +This section is called ``a first example'' due to legacy reasons of the +various defects of this documentation... +Let us present a ``first example'' (sort of) of specification for line styles: \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} \begingroup\parindent 0pt \parfillskip 0pt \leftskip 0cm \rightskip 1cm \etocsetstyle {section} @@ -4303,27 +4320,71 @@ elsewhere in the document. {} \etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of \autoref{part:overview} (\nameref{part:overview})} -\tableofcontents \ref {toc:overview} +\tableofcontents \ref{toc:overview} \endgroup \end{filecontentsdef} +\begin{verbatim} +\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} + {} +\etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of + \autoref{part:overview} (\nameref{part:overview})} +\tableofcontents \ref{toc:overview} +\endgroup +\end{verbatim} + +In the above verbatim there is a mysterious +\centeredline{|\ref{toc:overview}|} +which will be commented upon later. But let use first see what this code +produces (of course its output depends on the contents of the present +document, as applies to all other examples in this documentation). + \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. +This author always complicates things, so the above +example had one additional twist I now have to explain. The mysterious +% +\centeredline{|\tableofcontents \ref{toc:overview}|} +% +means that the contents which are displayed are those of a local table of +contents located somewhere else and labeled there via a +% +\centeredline{|\label{toc:overview}|} +% +Turns out that this was done via a \localtoc located at the start of +\autoref{part:overview}, here is how the code looked like overthere: +\begin{verbatim} +\part{Overview} +\etocdefaultlines +\etocsettocstyle{}{} +\localtableofcontents \label{toc:overview} +\end{verbatim} +For more explanations refer to \autoref{sec:labeling}. Notice in particular +that there is no relation whatsoever between the line styles used for the +original \localtoc and those applying here to the cloned one. Actually the +original one could even have been made invisible via usage of \invisiblelocaltoc! + +Regarding the line styles, we could have used those defined by \etoc, which +are activated via \csb{etocdefaultlines}, or the default document class styles +which are activated by \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|. + +Here is again the code used (now displayed more fully). Notice that we +defined styles for sections, subsections, and subsubsections, but actually +that \autoref{part:overview} only has sections! +\filecontentsprintviascan\foo +\marginattach + +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 @@ -4332,18 +4393,21 @@ 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: -\filecontentsprintviascan\foo -\marginattach \section{A second example} \label{sec:secondexample} -This second example displays only the contents from -\autoref{sec:linestyles} and \autoref{sec:tocstyle}. This selection -is done via the technique of \emph{depth tags}, described in -\autoref{etocsettagdepth} and \autoref{sec:tocwithdepthtags}. +This second example: +\begin{enumerate} +\item illustrates displaying subsections of a given section ``horizontally'' + in one single paragraph, +\item does a selection of contents via the technique of \emph{depth tags}, + described in \autoref{sec:depthtags}. +\end{enumerate} +Again the qualities +of the author innovative pedagogy skills are well illustrated by the +simplicity of the example. \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} \begingroup @@ -4385,20 +4449,37 @@ is done via the technique of \emph{depth tags}, described in \etocsettagdepth {control} {none} \etocsettagdepth {examples} {none} \etocsettagdepth {advanced} {none} -\etocsettagdepth {etocandworld}{none} +\etocsettagdepth {etocandworld}{subsection} \etocsettagdepth {code} {none} \etocsettocstyle {\centering\LARGE\textsc{\contentsname}\par\nobreak\medskip}{} -\etocsetnexttocdepth {subsection} +\etocsetnexttocdepth {all} % but depth tags will control the actual contents +\etocobeydepthtags % this is default anyhow, but may have been turned off \tableofcontents \endgroup \end{filecontentsdef} \filecontentsexec\foo -The code: +\medskip +The code looks like this. For more explanations relative to depth tags, and +especially how they were incorporated into the present document, see also +\autoref{sec:tocwithdepthtags}. \filecontentsprintviascan\foo \marginattach +One last remark: the code above uses \csb{etocsetstyle} only for parts, +sections and subsections. Non-styled levels would be displayed using +fall-back defaults which are incorporated into the package code. Those +fall-back defaults for |paragraph| and |subparagraph| display nothing at all +(deliberately). So even if the |tocdepth| counter setting allowed it, and +even if we had used +% +\centeredline{|\etocsettagdepth {code}{paragraph}|} +% +(as that \autoref{part:code} does contain \csa{paragraph}'s), no +paragraph entry would have been displayed here. + + \section{A Beautiful Thesis example} Here is a relatively simple example of use of the package @@ -4458,7 +4539,7 @@ class commands.} The original is the local table of contents of \begingroup % to keep in particular toc=left with local effect \KOMAoptions{toc=left} \etocclasstocstyle % necessary for the display to obey toc=left -\etocstandardlines +\etocstandardlines % use the document class built-in TOC line styles \tableofcontents \ref{toc:tocstyle} \endgroup \end{verbatim} @@ -4773,8 +4854,9 @@ using |pt| as dimensional unit. \marginattach Nota Bene: the code deliberately handles the non-numbered sectioning units -unlike the way of the standard document classes (particularly regarding the -alignment of multi-line headings.) +differently from what the standard document classes \texttt{article}, +\texttt{report}, \texttt{book} do, 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 @@ -6214,79 +6296,146 @@ stands here is for using within a section). \section{Using depth tags} \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{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 -earlier in this document, in \autoref{sec:secondexample}, within a -group hence it did not affect the other tables of contents). - -However, the package line styles do not display paragraphs, and the -standard line styles of the document class give too much vertical -spacing (in this context) when displaying a Part heading in the TOC. So -we cook up our own, quickly designed line styles, in the style of -\autoref{sec:firstexample} (but with a way to put page numbers on the -right which is more like the method used by \LaTeX2e's -|\@dottedtocline|; and multi-line headings now leave empty the area -underneath the numbers contrarily to the code from -\autoref{sec:firstexample}). And after a few minutes for choosing -lengths (now that this has been done once, it can be recycled easily) we -get: +\etoc provides via the concept of \emph{depth tags} the possibility to decide +that, for example, a table of contents will display sections and subsections +in a given chapter or part, but only sections, or nothing at all, for the +other chapters (or parts) included in the given table of contents. You will +find more explanations at \autoref{sec:depthtags} + +For this the user adds to the source usage in the document body of +\csb{etocdepthtag.toc} commands, located right before the |\part|, or +|\chapter|, or whatever division headings whose control is desired, for +example +% +\centeredline{|\etocdepthtag.toc{specialchapter}|} +% +and then when using +\toc or \localtoc, user will add some command such as +% +\centeredline{|\etocsettagdepth{specialchapter}{section}|} +% +which will have the effect that only sections but no subsections of that +chapter get displayed in that (possibly local, here to a Part) table of +contents. Actually, one also has to add a depth tag at end of the desired +scope of first one, something such as +% +\centeredline{|\etocdepthtag.toc{endofspecialchapter}|} +% +and one will then issue +% +\centeredline{|\etocsettagdepth{endofspecialchapter}{all}|} +% +to left further chapters again include in the so-configured table of contents +all of their sub-units (as limited by current |tocdepth|). The simplest way +thus is, if one decides to add a depth tag for one part or chapter to also add +depth tags to all other parts, respectively chapters, and configure them +appropriately. + +Think of this as a way to add \emph{inside} the |.toc| file some changes to +the |tocdepth| counter, except that those changes are dynamically +configurable, and also the whole thing can be ignored if +\csb{etocignoredepthtags} is used. + +As an example, one can imagine a document with various Parts, each part +displaying a table of contents of the \emph{complete} document, but which +shows regarding other parts only their title and no finer division, whereas +for the Part where it is located it will show all levels allowed by +|tocdepth|. This is a variant of a ``local'' table of contents, which does +display things external to the Part where it is located, but in a more limited +way than regarding that Part itself. + +The commands \csb{etocobeydepthtags} (which is default behavior) and +\csb{etocignoredepthtags} can be used to control which TOC obey depth tags. +If generally they should not, issue once \csb{etocignoredepthtags} in +preamble, and then use \csb{etocobeydepthtags} for specific TOCs, either +inside a scope-limiting group, or re-issue \csb{etocignoredepthtags} after +each such (local or not) table of contents. + +Here is a demonstration using the contents of this documentation. We want a +TOC which will have a heading for each |\part|, with two Parts being handle +especially: the \autoref{part:control} will show all its divisions down to +subsubsection (if present) and the \autoref{part:code} will even show +paragraphs (turns out that this document used there some |\paragraph| +mark-up). To achieve this we added various +\csb{etocdepthtag.toc} commands inside the source of this document prior to +each |\part| command. It only remains now to set appropriately the depth of +each such depth tag, which will be done like this: +\begin{verbatim} +\etocsettagdepth {preamble} {part} +\etocsettagdepth {overview} {part} +\etocsettagdepth {styling} {part} +\etocsettagdepth {control} {subsubsection} +\etocsettagdepth {examples} {part} +\etocsettagdepth {advanced} {part} +\etocsettagdepth {etocandworld}{part} +\etocsettagdepth {code} {paragraph} +\end{verbatim} + +As said, we want here to display even paragraph entries in a specific part. +The standard document class paragraph TOC line styles give too much vertical +spacing in this context. So we cook up our own, quickly designed, line +styles, a bit like what we did for \autoref{sec:firstexample}, but with a way +(see the command |\EndParWithPageNumberInMarginAndLeaders|) to put page +numbers on the right which is more like the method used by \LaTeX2e's +|\@dottedtocline|; headings occupying more than one line will now wrap in a +way achieving some hanging indentation relative to the entry number (but there +is no such long heading in this example). \begin{filecontentsdef}{etocsnippet-\snippetno.tex}{\foo} \etocsetnexttocdepth {all} \begingroup \parindent 0pt \leftskip 0cm \rightskip .75cm \parfillskip -\rightskip -\newcommand*{\EndParWithPagenoInMargin} +\newcommand*{\EndParWithPageNumberInMargin} {\nobreak\hfill - \makebox[0.75cm][r]{\mdseries\normalsize\etocpage}% + % I initially added \etocnoprotrusion after \etocpage, but + % finally switched to using monospace font for page number, + % and it seems to have deactivated the protrusion anyhow. + \makebox[0.75cm][r]{\mdseries\normalsize\ttfamily\etocpage}% \par} \renewcommand*\etoctoclineleaders {\hbox{\normalfont\normalsize\hbox to .75ex {\hss.\hss}}} -\newcommand*{\EndParWithPagenoInMarginAndLeaders} +\newcommand*{\EndParWithPageNumberInMarginAndLeaders} {\nobreak\leaders\etoctoclineleaders\hfill - \makebox[0.75cm][r]{\mdseries\normalsize\etocpage}% + \makebox[0.75cm][r]{\mdseries\normalsize\ttfamily\etocpage}% \par } \etocsetstyle {part} {} {\leavevmode\leftskip 1cm\relax} {\bfseries\large\llap{\makebox[1cm][r]{\etocnumber\ \ }}% - \etocname\EndParWithPagenoInMargin\smallskip} + \etocname\EndParWithPageNumberInMargin\smallskip} {} \etocsetstyle {section} {} {\leavevmode\leftskip 1.75cm\relax} {\bfseries\normalsize\llap{\makebox[.75cm][l]{\etocnumber}}% - \etocname\EndParWithPagenoInMarginAndLeaders} + \etocname\EndParWithPageNumberInMarginAndLeaders} {} \etocsetstyle {subsection} {} {\leavevmode\leftskip 2.75cm\relax } {\mdseries\normalsize\llap{\makebox[1cm][l]{\etocnumber}}% - \etocname\EndParWithPagenoInMarginAndLeaders} + \etocname\EndParWithPageNumberInMarginAndLeaders} {} \etocsetstyle {subsubsection} {} {\leavevmode\leftskip 4cm\relax } {\mdseries\normalsize\llap{\makebox[1.25cm][l]{\etocnumber}}% - \etocname\EndParWithPagenoInMarginAndLeaders} + \etocname\EndParWithPageNumberInMarginAndLeaders} {} \etocsetstyle {paragraph} {} {\leavevmode\leftskip 5.5cm\relax } {\mdseries\normalsize\llap{\makebox[1.5cm][l]{\etocnumber}}% - \etocname\EndParWithPagenoInMarginAndLeaders} + \etocname\EndParWithPageNumberInMarginAndLeaders} {} -\etocsettagdepth {preamble} {all} +\etocsettagdepth {preamble} {part} \etocsettagdepth {overview} {part} -\etocsettagdepth {styling} {subsection} +\etocsettagdepth {styling} {part} \etocsettagdepth {control} {subsubsection} \etocsettagdepth {examples} {part} \etocsettagdepth {advanced} {part} -\etocsettagdepth {etocandworld}{all} -\etocsettagdepth {code} {all} +\etocsettagdepth {etocandworld}{part} +\etocsettagdepth {code} {paragraph} \renewcommand\etoctoprule {\hrule height 3pt\relax } \renewcommand\etoctoprulecolorcmd {\color{blue}} \renewcommand\etocaftercontentshook @@ -6660,62 +6809,103 @@ given toc entry). For example, the tables of contents of the present document are all fully linked. It doesn't matter whether \etoc or \ctanpkg{hyperref} is loaded 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{Compatibility with \ctanpkg{microtype}} +\label{ssec:microtype} +\label{etocnoprotrusion} -\subsection{Compatibility with \ctanpkg{multicol}} +(this doc added at \etocrelease{1.2b}) -\etoc loads the package \ctanpkg{multicol}. +\ctanpkg{microtype} patches the \LaTeX{} \csa{numberline} command (which is +used in |.toc| file) to execute \csa{leftprotrusion}. The reason +\ctanpkg{microtype} does this patch to \csa{numberline} is that the default +\LaTeX{} contents line styles do some \csa{hskip} which inhibit left +protrusion of the (explicit digits or letters of the) argument of +\csa{numberline}, which is the first typeset material on the contents line. -\subsection{Compatibility with \ctanpkg{tocloft}}\label{subs:tocloft} +Some other contexts than a previous \csa{hskip} inhibit left protrusion, in +particular a non-zero paragraph indentation. -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}|. +One could imagine that \etoc user only has to add \csa{leftprotrusion} if so +desired at start of the defined line styles. But usage of the +\csa{leftprotrusion} command is delicate, it must be followed with an explicit +character or with a very limited set of \LaTeX{} commands. In particular, and +imagining here that the defined line style starts a paragraph with +\csb{etocnumber}, and that this paragraph is indented so that automatic left +protrusion does not apply, an attempt to force reactivation of left protrusion +via: % -As long as \etoc is left in compatibility mode the customization done by -\ctanpkg{tocloft} will be obeyed, for both the line styles and the TOC title. -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{etocclasstocstyle}. In this -compatibility mode \csb{etocsetlevel}\marg{division unit}|{|\csb{etocthemaxlevel}|}| will render -invisible the chosen division level, but exchanging levels is otherwise -not possible. - -\begin{framed} - One should load \etoc \emph{after} \ctanpkg{tocloft}. A warning is - issued if otherwise, because if \etoc is loaded before it will realize that at - the time of |\begin{document}| and trick \ctanpkg{tocloft} into believing - having been loaded with the |titles| option. -\end{framed} - -It is possible to modify midway in the document the macros \csa{l@section}, -\csa{l@subsection} ... but the effect will be seen only in table of contents -typeset by \etoc in compatibility mode (and of course after those -customizations). It will have no effect on true \etoc TOCs. +\centeredline{|\leftprotrusion\etocnumber|} +% +fails. One has to resort to use: +% +\centeredline{|\expandafter\leftprotrusion\etocthenumber|} +% +This +would not work with \csb{etocthelinkednumber}, so to get the protruding number +to also be hyperlinked one has to use +% +\centeredline{|\etoclink{\expandafter\leftprotrusion\etocthenumber}|} + +The package does not provide yet (nor is it planned in near future in absence +of user requests) extra support such as an option to insert internally +\csa{leftprotrusion} \emph{inside} \csb{etocnumber} which would avoid such +gymnastics. But the user can easily add a definition such as +% +\centeredline{|\newcommand\leftprotrudingetocnumber{\etoclink{\expandafter\leftprotrusion\etocthenumber}}|} +% +to the preamble, and use the defined wrapper or a variant built upon +\csb{etocthename} in custom \csb{etocsetstyle} line style definitions. + +If on the contrary you want to avoid left protrusion, it is coherent to load +\ctanpkg{microtype} this way: +% +\centeredline{|\usepackage[nopatch=toc]{microtype}|} +% +This avoids the \csa{leftprotrusion} addition done by \ctanpkg{microtype} to +\csa{numberline}; but this is of relevance only if you use \etoc in +compatibility mode, because user-defined \etoc line styles will not +execute \csa{numberline} except if explicitly added to the line style, and +even if they do, as explained above something such as +% +\centeredline{|\numberline{\etocnumber}|} +% +will inject a \csa{leftprotrusion} which will remain without effect. + +\etoc provides since \etocrelease{1.2b} a macro \csb{etocnoprotrusion} which +is a copy of the \LaTeX{} \csa{noprotrusion} command available since its +|2018/12/01| release, and is used since by \LaTeX{} default TOC code with page +numbers. You can use this if a style definition, perhaps modeled on the +standard \LaTeX{} layout from \csa{@dottedtocline}, also locates +\csb{etocpage} at right margin preceded on the line by some dot leaders. +Indeed protrusion may cause an extra dot, compared to other lines, which is +really ugly visually. Use \csa{noprotrusion} in the style after +\csb{etocpage} (or whatever is at end of the line style contents) if you can +assume that \LaTeX{} is recent enough, or use \csb{etocnoprotrusion} which +will work with all \LaTeX{} versions, even old ones. + +You may also consider turning protrusion off completely for tables of +contents. For this, see \autoref{ssec:disableprotrusion}. + +Notice that some problem with page number alignment look like +protrusion-related ones but may simply be caused by the fact that the font +used does not assign the same width to all digits, and the line style pushes +these digits to the right end of the line (to confirm this in case of +suspicion, temporarily make package \ctanpkg{microtype} inactive or remove it +from your document). If for example \texttt{20} is, in the used font, wider +than \texttt{27}, the latter will look shifted a bit to the right compared to +the former. Centering the page number in a fixed width box (itself +flushed-right to end of line) is one solution, but it may not be to everyone's +taste due to single-digit page number; in that case the line style code could +make a test on the page number (or its width, if it is not assumed it is +purely numerical) and make appropriate decisions. I will leave the matter to +your \LaTeX{} coding skills. Using a font with tabular lining figures fixes +such problem. -\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}} +\subsection{Compatibility with \ctanpkg{multicol}} - \etoc used to be incompatible with package - \ctanpkg{tocvsec2}; it now cohabits, sort - of, as it deactivates \ctanpkg{tocvsec2}'s modification of |\tableofcontents| - and also cancels its other |toc|-related macros, but - reimplements partially their functionality with \csb{etocsettocdepth.toc}. By - the way, at least two latex runs are necessary for new uses of this command in - a document to have an effect in tables of contents. +\etoc loads the package \ctanpkg{multicol}. \subsection{Compatibility with \ctanpkg{tableof}} @@ -6733,6 +6923,7 @@ 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{tocbasic}} \label{ssec:tocbasic} @@ -6772,6 +6963,59 @@ 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. +\subsection{Compatibility with \ctanpkg{tocloft}}\label{subs:tocloft} + +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}|. +% +As long as \etoc is left in compatibility mode the customization done by +\ctanpkg{tocloft} will be obeyed, for both the line styles and the TOC title. +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{etocclasstocstyle}. In this +compatibility mode \csb{etocsetlevel}\marg{division unit}|{|\csb{etocthemaxlevel}|}| will render +invisible the chosen division level, but exchanging levels is otherwise +not possible. + +\begin{framed} + One should load \etoc \emph{after} \ctanpkg{tocloft}. A warning is + issued if otherwise, because if \etoc is loaded before it will realize that at + the time of |\begin{document}| and trick \ctanpkg{tocloft} into believing + having been loaded with the |titles| option. + + Sadly, \etocrelease{1.2} and \etocrelease{1.2a} had a bug and loading + \ctanpkg{tocloft} before \etoc caused \toc to not be the \etoc one. One had + to use explicitly \csb{etoctableofcontents} (there was no issue with + \localtoc). The regression was fixed at \etocrelease{1.2b}. +\end{framed} + +It is possible to modify midway in the document the macros \csa{l@section}, +\csa{l@subsection} ... but the effect will be seen only in table of contents +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 + \ctanpkg{tocvsec2}; it now cohabits, sort + of, as it deactivates \ctanpkg{tocvsec2}'s modification of |\tableofcontents| + and also cancels its other |toc|-related macros, but + reimplements partially their functionality with \csb{etocsettocdepth.toc}. By + the way, at least two latex runs are necessary for new uses of this command in + a document to have an effect in tables of contents. + \section{\TeX nical matters} The \csb{etocname}, \csb{etocnumber}, \csb{etocpage} commands are protected @@ -6830,6 +7074,7 @@ contents will be displayed only on the second compilation. \etocdepthtag.toc {code} \normalmarginpar\marginparwidth72bp \part{The code} +\label{part:code} % return to single spacing \setstretch{1} @@ -6964,6 +7209,24 @@ version is \texttt{\etocpkgversion}, of \texttt{\etocpkgdate}. \makeatother \vskip-\baselineskip \begin{jfverbatim} +~1.2b [2023/07/01]^ + + bugfix: a refactoring at 1.2 accidentally removed a needed + \AtBeginDocument and as a result the tocloft redefinition + of \tableofcontents was not undone, if etoc got loaded after + tocloft, as is advised by the documentation. Thanks to + user691586 for report. + + Add section documenting compatibility aspects with usage of + package microtype. Add \etocnoprotrusion an alias to LaTeX + 2018/12/01 \noprotrusion and use it after \etocpage inside the + package built-in fallback section and subsection toc line styles. + + Fix some of the documentation (in particular the sections "A first + example" and "A second example") as some of its highly pedagogical + comments had lost sync with other changes. Don't hesitate getting + in touch with the author to obtain further improvements. + ~1.2a [2023/05/01]^ The requirements (added respectively at 1.1a and 1.2) of a LaTeX @@ -8181,7 +8444,7 @@ of real structure in a \LaTeX{} document body). % \csa{numexpr} or \csa{unexpanded} or maybe others yet that we use). % \begin{macrocode} \NeedsTeXFormat{LaTeX2e}[2003/12/01] -\ProvidesPackage{etoc}[2023/05/01 v1.2a Completely customisable TOCs (JFB)] +\ProvidesPackage{etoc}[2023/07/01 v1.2b Completely customisable TOCs (JFB)] % \end{macrocode} % Gentle Info message in the log to mention no testing is done of current % \etoc on old \LaTeX{} installations. @@ -8194,7 +8457,7 @@ of real structure in a \LaTeX{} document body). Since 1.1a (2023/01/14), etoc prefers LaTeX at least\MessageBreak as recent as 2020-10-01, for reasons of the .toc file,\MessageBreak and used to require it (from 1.1a to 1.2).\MessageBreak - This etoc (1.2a) does not *require* it, but has not been\MessageBreak + This etoc (1.2b) does not *require* it, but has not been\MessageBreak tested thoroughly on old LaTeX (especially if document\MessageBreak does not use hyperref) and retrofitting was done only\MessageBreak on basis of author partial remembrances of old context.\MessageBreak @@ -8995,8 +9258,13 @@ of real structure in a \LaTeX{} document body). % \begin{macrocode} \def\Etoc@lxyz@linktoc{% \ifcase\Hy@linktoc - % none: nothing to do - \or % section (aka name for etoc): link name and number +% \end{macrocode} +% none: nothing to do +% \begin{macrocode} + \or +% \end{macrocode} +% section (aka name for etoc): link name and number +% \begin{macrocode} \Etoc@global\expandafter\let\csname etocname \endcsname\etocthelinkedname \Etoc@global\expandafter\let\csname etocnumber \endcsname\etocthelinkednumber \or % page @@ -10490,6 +10758,13 @@ of real structure in a \LaTeX{} document body). \etocdefaultlines@setsubsubsection \etocdefaultlines@setdeeperones } +% \end{macrocode} +% \etocrelease{1.2b} adds \csb{etocnoprotrusion} as an alias to the +% \LaTeX{} kernel |2018/12/01| command \csa{noprotrusion} which is used since +% that release in \csa{@dottedtocline} after the page number. And it uses it +% in its own default line styles for section and subsection. +% \begin{macrocode} +\def\etocnoprotrusion{\leavevmode\kern-\p@\kern\p@} \@ifclassloaded{memoir}{% \def\etocdefaultlines@setbook{% \Etoc@setstyle@b @@ -10532,6 +10807,11 @@ of real structure in a \LaTeX{} document body). \endgroup} {}% } +% \end{macrocode} +% No need to worry about left protrusion activation and the delicacies of +% \csa{leftprotrusion} from \ctanpkg{microtype}, as the paragraph indentation +% here is nil. So, no changes at \etocrelease{1.2b}. +% \begin{macrocode} \def\etocdefaultlines@setchapter{% \Etoc@setstyle@b {0}% @@ -10547,6 +10827,13 @@ of real structure in a \LaTeX{} document body). \endgroup} {\addpenalty{-\@highpenalty}\addvspace{\etocsepminusone}}% } +% \end{macrocode} +% This is now very old code, dating back to earliest releases, and looks +% a bit too convoluted. There was probably a better way with suitable +% \csa{nobreak} and |\null| trick. But I am too old to revisit these things +% now. And, by the way, as paragraph indentation is zeroed, no need to worry +% about perhaps activating explictly protrusion on the left. +% \begin{macrocode} \def\etocdefaultlines@setsection{% \Etoc@setstyle@b {1}% @@ -10564,8 +10851,8 @@ of real structure in a \LaTeX{} document body). \setbox\z@=\etoctoclineleaders \advance\dimen\z@\wd\z@ \etocifnumbered - {\setbox\tw@\hbox{\etocnumber, \etocabbrevpagename\etocpage}} - {\setbox\tw@\hbox{\etocabbrevpagename\etocpage}}% + {\setbox\tw@\hbox{\etocnumber, \etocabbrevpagename\etocpage\etocnoprotrusion}} + {\setbox\tw@\hbox{\etocabbrevpagename\etocpage\etocnoprotrusion}}% \advance\dimen\z@\wd\tw@ \ifdim\dimen\z@ < \linewidth \vbox{\etocname~% @@ -10598,8 +10885,8 @@ of real structure in a \LaTeX{} document body). \setbox\z@=\etoctoclineleaders \advance\dimen\z@\wd\z@ \etocifnumbered - {\setbox\tw@\hbox{\etocnumber, \etocabbrevpagename\etocpage}} - {\setbox\tw@\hbox{\etocabbrevpagename\etocpage}}% + {\setbox\tw@\hbox{\etocnumber, \etocabbrevpagename\etocpage\etocnoprotrusion}} + {\setbox\tw@\hbox{\etocabbrevpagename\etocpage\etocnoprotrusion}}% \advance\dimen\z@\wd\tw@ \ifdim\dimen\z@ < \linewidth \vbox{\etocname~% @@ -10648,7 +10935,7 @@ of real structure in a \LaTeX{} document body). % \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 -% to mimick the standard TOC spacings in |article| class. +% to mimic the standard TOC spacings in |article| class. % \begin{macrocode} \def\etocabovetocskip{3.5ex \@plus 1ex \@minus .2ex} \def\etocbelowtocskip{3.5ex \@plus 1ex \@minus .2ex} @@ -11038,7 +11325,7 @@ of real structure in a \LaTeX{} document body). % |v3.7i| of memoir has moved the \csa{phantomsection} to a better location, % 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 +% mimic 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 @@ -11109,9 +11396,11 @@ of real structure in a \LaTeX{} document body). \fi \fi \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 +% \end{macrocode} +% Trying to mimic a section title but there is no \csa{sectionheadstart} +% there is no \csa{printsectiontitle} etc... Oh well I will be more +% radical then. +% \begin{macrocode} \@namedef{@\Etoc@currext maketitle}{% \@nameuse{etocclasslocal\Etoc@currext maketitle}% }% @@ -11438,6 +11727,12 @@ of real structure in a \LaTeX{} document body). }% \fi }% +% \end{macrocode} +% The \etocrelease{1.2} added a bug here in the non-\ctanpkg{memoir} +% \ctanpkg{tocloft} branch, the needed \csa{AtBeginDocument} was removed by +% accident and as a result the overwriting by \ctanpkg{tocloft} of +% \csbc{tableofcontents} was not undone. +% \begin{macrocode} \@ifclassloaded{memoir} {} {% memoir not loaded @@ -11445,7 +11740,7 @@ of real structure in a \LaTeX{} document body). {\if@cftnctoc\else \ifEtoc@keeporiginaltoc \else - \let\tableofcontents\etoctableofcontents + \AtBeginDocument{\let\tableofcontents\etoctableofcontents}% \fi \fi } {\AtBeginDocument |