diff options
author | Karl Berry <karl@freefriends.org> | 2013-10-17 22:47:11 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-10-17 22:47:11 +0000 |
commit | c3e9c063ce3006193da17016faabd349005f3d2e (patch) | |
tree | 8a76fa9defac469d26ae3fd5454dfcaac3bf2592 /Master/texmf-dist/source | |
parent | fd259506c0d13033500292bfd8c925bfb3de5d15 (diff) |
etoc (17oct13)
git-svn-id: svn://tug.org/texlive/trunk@31932 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/latex/etoc/etoc.dtx | 1665 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/etoc/etoc.ins | 6 |
2 files changed, 1008 insertions, 663 deletions
diff --git a/Master/texmf-dist/source/latex/etoc/etoc.dtx b/Master/texmf-dist/source/latex/etoc/etoc.dtx index df664fbf2e9..161527f9037 100644 --- a/Master/texmf-dist/source/latex/etoc/etoc.dtx +++ b/Master/texmf-dist/source/latex/etoc/etoc.dtx @@ -1,12 +1,12 @@ % -*- coding: iso-latin-1; -*- %<*!package> -\def\pkgname {etoc} \def\pkgdate {2013/10/13} \def\pkgversion {v1.07g} +\def\pkgname {etoc} \def\pkgdate {2013/10/16} \def\pkgversion {v1.07h} \def\pkgdescription {Completely customisable TOCs (jfB)} -\def\doctimestamp {Time-stamp <13-10-2013 23:44:43 CEST *>} +\def\doctimestamp {Time-stamp <16-10-2013 22:11:00 CEST *>} %</!package> %% %% Package: etoc -%% Version: 2013/10/13 v1.07g +%% Version: 2013/10/16 v1.07h %% Copyright (C) 2012-2013 by Jean-Francois Burnol <jfbu at free dot fr> %% % This Work may be distributed and/or modified under the @@ -243,12 +243,10 @@ % modif de \do@noligs: \char`#1} --> \char`#1 } \makeatletter -% le \allowbreak provoque un espace à la fin d'une ligne \def\dobackslash {% \catcode92 \active \begingroup \lccode `\~=92\relax -%% non \lowercase {\endgroup \def ~{\kern \z@ \allowbreak \char 92 }}% \lowercase {\endgroup \def ~{\kern \z@ \char 92 }}% }% \def\dobraces @@ -278,9 +276,10 @@ \catcode92 13 \catcode123 13 \catcode 125 13 \makestarlowast \@jfverb -}% -\def\@jfverb #1{\catcode`#1\active\lccode`\~`#1\lowercase{\let~\egroup}}% - +}% +\def\@jfverb #1{\catcode`#1\active + \lccode`\~`#1\lowercase{\def~{\egroup\unskip}}}% +% (\unskip ajouté le 14 octobre) % \lowast est défini plus loin \begingroup \catcode`* 13 @@ -353,7 +352,7 @@ \usepackage{xspace} \usepackage[dvipsnames]{xcolor} \usepackage{graphicx} -\usepackage{enumitem} +\usepackage[inline]{enumitem} \definecolor{joli}{RGB}{225,95,0} \definecolor{JOLI}{RGB}{225,95,0} @@ -433,14 +432,15 @@ pdfpagemode=UseOutlines} \etocsetlevel{dummysection}{6} %-------- % for "Another compatibility mode" (2013/02/21): -% attention au 5 qui est hard-coded (pour 1.07f c'était 3, maintenant 5) +% attention au 5 qui est hard-coded +% (pour 1.07f c'était 3, maintenant 5 pour 1.07g; et 4 maintenant pour 1.07h...) \makeatletter \newcommand*{\MyQuasiStandardTOC}[1]{% \begingroup \let\savedsectionline\l@section \let\savedsubsectionline\l@subsection \etocsetstyle{section}{} - {\ifnum\etocthenumber=5 + {\ifnum\etocthenumber=4 \etocsetstyle{subsection} {\par\nopagebreak\begingroup \leftskip1.5em \rightskip\@tocrmarg @@ -536,8 +536,6 @@ pdfpagemode=UseOutlines} \endgroup } -\newcommand\toc{\csa{table\-of\-contents}\xspace} -\newcommand\localtoc{\csa{local\-table\-of\-contents}\xspace} \newcommand\etoc{% \texorpdfstring{{\color{joli}\ttfamily\bfseries etoc}}{etoc}\xspace} @@ -552,8 +550,16 @@ pdfpagemode=UseOutlines} % {{\color{\linkcolor}\ttfamily\hyphenchar\font45 \char`\\ #1}} \newcommand\cshyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}} -%\newcommand\csbhyp[1]{\texorpdfstring{\csbnolk{#1}}{\textbackslash #1}} -\let\csbhyp\cshyp + +\newcommand\csbhyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}} + +% \makeatletter +% \newcommand\csaetoc[1]{\csaetoc@ #1.} +% \def\csaetoc@ etoc#1.{\csa{etoc\-#1}} % non empêche hyphénation après. +% \makeatother + +\newcommand\toc{\csa{table\-of\-contents}\xspace} +\newcommand\localtoc{\csa{local\-table\-of\-contents}\xspace} \newcommand\lowast{\raisebox{-.25\height}{*}} \newcommand\starit[1]{\csa{#1\lowast}} @@ -570,6 +576,7 @@ pdfpagemode=UseOutlines} \hyphenation{etoc-the-link} \hyphenation{etoc-skip-first-pre-fix etoc-the-page etoc-ruled-style etoc-mul-ti-col-style etoc-default-lines} +\hyphenation{etoc-local-ruled} \frenchspacing @@ -629,6 +636,8 @@ pdfpagemode=UseOutlines} \small +\etocdepthtag.toc {preamble} + \section{License, installation} \begin{verbatim} @@ -685,8 +694,8 @@ pdfpagemode=UseOutlines} Popular packages dealing with TOCs include |tocloft|, |titletoc| and |minitoc|. Why another one? I started \etoc -for my own use, and found out only later about the above mentioned -packages; and they did not accomplish what I was aiming at. +for my own use, and found out only later about these mentioned +packages. As is well explained in the |tocloft| package documentation, the standard \LaTeX{} layout for the Table of Contents is @@ -716,164 +725,7 @@ compatible with the |article|, |book|, |report|, |scrartcl|, |scrbook|, |scrreprt| and |memoir| classes. -\begingroup -\renewcommand\lowast{{\normalsize\raisebox{-.4\height}{*}}} - - \clearpage -\small - -\section{Change history} - -\setlength{\columnsep}{\etoccolumnsep} - -\makeatletter - -\def\jfverbatim{\@beginparpenalty \predisplaypenalty - \parindent \z@ - \parfillskip \@flushglue - \parskip \tw@\p@ plus 1fil\relax - \let \do \@makeother \dospecials - \catcode`\~\z@ - \footnotesize\normalfont\baselineskip10pt\relax - \frenchspacing \obeyspaces \jf@xverbatim } - -\begingroup -\catcode `|=0 \catcode `[= 1 \catcode`]=2 -\catcode `\{=12 \catcode `\}=12 \catcode`\\=12 -|long|gdef|jf@xverbatim#1\end{jfverbatim}[#1|end[jfverbatim]] -|endgroup - -\def\endjfverbatim{} - -\newdimen\jfverbadim - -\everypar{\leftskip\jfverbadim\bgroup - \def\par{\egroup\jfverbadim\z@\@@par}% - \def\jfverbaspace#1{\ifcat\noexpand#1\noexpand~\unskip\else\ \fi#1}} - -\begingroup\obeyspaces\def\x{\endgroup% -\def {\ifvmode\advance\jfverbadim.5em\relax\else\expandafter\jfverbaspace\fi}}\x - -\makeatother - -\begin{multicols}{2} -\begin{jfverbatim} -v1.07g [2013/10/13] - - new commands \etocsettocdepth, \etocsettocdepth.toc, - \etocobeytoctocdepth, \etoc~-ignoretoctocdepth which - emulate part of tocvsec2 functionality ; measures to - make tocvsec2 partially compatible with etoc. - - new commands \etocsetnexttocdepth, \invisibletableofcontents, - \invisiblelocaltableofcontents. - - switched from tikz-qtree to forest for the first `toc as - tree' example. - - command names are linked to their descriptions, and many - other changes in the documentation. - - removed printing of temporary message when the local toc - id is not yet stabilized; indeed \localtableofcontents - can have many use, such as filling up some token list - register and one may wish to not have anything typeset, - even in an intermediate run. - - all of tex etoc.dtx, etex etoc.dtx, xetex etoc.dtx, latex - etoc.dtx, pdflatex etoc.dtx are now possible, and the - extracted file etoc.tex allows easy customization of - compilation options for the documentation (default is via - dvipdfmx which produces the smallest file). - -~smallskip - -v1.07f [2013/03/07] - - new macros \etocthelinkedname, \etocthelinkednumber, - \etocthelinkedpage, and \etocthelink. - - -v1.07e [2013/03/01] - - improvements in the package own line styles with - regards to penalties and vertical spaces. - - addition to the documentation of an example of - a tree-like table of contents (uses tikz). - - more such examples added 2013/03/03. - - -v1.07d [2013/02/24] - - minor code improvements and new documentation - section "Another compatibility mode". - - -v1.07b [2013/02/02] - - removal of the \xspace from the macros \etocname, - \etocnumber, \etocpage. - - additional examples in the documentation. - - -v1.07 [2013/01/29] - - new commands: - - \etocthename, \etocthenumber, \etocthepage, \etoclink, - - \etoctoccontentsline, \etoctoccontentsline~lowast - - \etocnopar, \etocaftercontentshook - - modified command: \etocmulticolstyle - - new documentation section "Surprising uses of etoc" which - explains how to do "Lists of arbitrary things", in - addition to the tables of contents. - - -v1.06 [2012/12/07] - - the standard macros \l@section etc... are modified only - during the calls to \tableofcontents; they can thus be - customized as will by the user (with the help of a - package like tocloft) and this will be taken into account - by etoc for the TOCs typeset in compatibility mode. - - -v1.05 [2012/12/01] - - \localtableofcontents replaces \tableofcontents~lowast (for - compatibility with the memoir class). - - compatibility with KOMA-script and memoir document - classes. - - -v1.04 [2012/11/24] - - a (possibly local) table of contents can be labeled: - - \tableofcontents \label{toc:1} - - and reproduced elsewhere in the document (with a possibly - completely different layout): - - \tableofcontents \ref{toc:1} - - -v1.02 [2012/11/18] - - initial version. - -\end{jfverbatim} -\end{multicols} -\endgroup % group for modified verbatim printing of the changes log %---- % MAIN TOC @@ -892,7 +744,9 @@ v1.02 [2012/11/18] \tableofcontents \label{toc:main} \endgroup -%% \clearpage +% \clearpage + +\etocdepthtag.toc{overview} \part{Overview}\label{part:overview} @@ -926,7 +780,8 @@ are in no way related only to matters of tables of contents, hence an economy of use of the poor brain. Next in ease of use, perhaps, is the -method explained later in this part. For this some knowledge of +method explained \hyperref[sec:firstexample]{later in this part}. For this some +knowledge of |\leftskip|, |\rightskip|, etc... is necessary. Next, people who know the internals of \LaTeX2e well (which is not my case) will happily use directly a |\list| command. @@ -953,12 +808,12 @@ devoted to this, and some more is to be found in \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| file}! packages or methods -found on the internet which fiddle with |\addcontentsline| or write directly -to the |.toc| file often do not have the perspective that this |.toc| file -will be used again and again. The present documentation contains -\arabic{mycounti} visible tables of contents (and a few invisible ones) and -uses only one |.toc| file!\footnotemark +in the same document, \emph{using only one |.toc| file}! The present +documentation contains \arabic{mycounti} visible tables of contents (and a few +invisible ones) and uses only one |.toc| file!\footnotemark{} So one should +think +twice before adding manually extra commands to the |.toc| file (see +\autoref{sec:addingtotoc}). \end{framed} \footnotetext{and the counting itself has been achieved by a table of contents @@ -1074,6 +929,7 @@ display style'' level. It will be re-activated if use if made of \csb{etocstandarddisplaystyle}. \section{A first example} +\label{sec:firstexample} Let us present it a first example of specification for line styles. Immediately after the start of \autoref{part:overview} we inserted in the @@ -1084,7 +940,15 @@ 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. Here is one such clone: +elsewhere in the document. + +We could use 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|. + + \begingroup \parindent 0pt @@ -1095,34 +959,28 @@ elsewhere in the document. Here is one such clone: {} {\leavevmode\leftskip 0cm\relax} {\bfseries\normalsize\makebox[.5cm][l]{\etocnumber.}% - \etocname\hfill{}\rlap{\makebox[1cm]{\mdseries\etocpage}}\par} + \etocname\nobreak\hfill\nobreak + \rlap{\makebox[1cm]{\mdseries\etocpage}}\par} {} \etocsetstyle {subsection} {} {\leavevmode\leftskip .5cm\relax } {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}% - \etocname\hfill{}\rlap{\makebox[1cm]{\etocpage}}\par} + \etocname\nobreak\hfill\nobreak + \rlap{\makebox[1cm]{\etocpage}}\par} {} \etocsetstyle {subsubsection} {} {\leavevmode\leftskip 1.5cm\relax } {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}% - \etocname\hfill{}\rlap{\makebox[1cm]{\etocpage}}\par} + \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 -We could use the line styles defined by \etoc, with -\csb{etoctoclines}, 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|. The |\rightskip| on the other hand is shared by - all, and page numbers are printed there. - This is a simple design which does not make provisions for page breaks which should be discouraged in-between a section and a @@ -1130,7 +988,16 @@ 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. The two commands used are \csb{etocsetstyle} for specifying the line -styles, and \csb{etocruledstyle} for the TOC global style. +styles, and \csb{etocruledstyle} for the TOC global style. + +The |\rightskip| is shared by all, and creates space where the page numbers get +printed. We defined also a subsubsection line style but they are no +subsubsection in this part. See also +\autoref{ssec:tocwithdepthtags} which provides a TOC also including parts and +paragraphs and has a technique for putting the page numbers on the right which +is closer to what \LaTeX2e's |\@dottedtocline| macro does. + + \begin{verbatim} \begingroup\parindent 0pt \parfillskip 0pt \leftskip 0cm \rightskip 1cm @@ -1138,19 +1005,22 @@ styles, and \csb{etocruledstyle} for the TOC global style. {} {\leavevmode\leftskip 0cm\relax} {\bfseries\normalsize\makebox[.5cm][l]{\etocnumber.}% - \etocname\hfill{}\rlap{\makebox[1cm]{\mdseries\etocpage}}\par} + \etocname\nobreak\hfill\nobreak + \rlap{\makebox[1cm]{\mdseries\etocpage}}\par} {} \etocsetstyle {subsection} {} {\leavevmode\leftskip .5cm\relax } {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}% - \etocname\hfill{}\rlap{\makebox[1cm]{\etocpage}}\par} + \etocname\nobreak\hfill\nobreak + \rlap{\makebox[1cm]{\etocpage}}\par} {} \etocsetstyle {subsubsection} {} {\leavevmode\leftskip 1.5cm\relax } {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}% - \etocname\hfill{}\rlap{\makebox[1cm]{\etocpage}}\par} + \etocname\nobreak\hfill\nobreak + \rlap{\makebox[1cm]{\etocpage}}\par} {} \etocruledstyle[1]{\bfseries \Large My first \etoc: TOC of \autoref{part:overview} (\nameref{part:overview})} @@ -1159,9 +1029,68 @@ styles, and \csb{etocruledstyle} for the TOC global style. \end{verbatim} +\section{Linked list of the main package commands} +% 16 octobre + +\advance\linewidth18pt +\begin{multicols}{3}\parindent0pt\relax + \csb{etoctoclines}\par +\csb{etocstandardlines}\par +\csb{etocdefaultlines}\par + \csb{etocsetstyle}\par +\csb{etocname}\par +\csb{etocpage}\par +\csb{etocskipfirstprefix}\par + \csb{etocnumber}\par +\csb{etocifnumbered}\par +\csb{etocthename}\par +\csb{etocthenumber}\par + \csb{etocthepage}\par +\csb{etoclink}\par +\csb{etocthelinkedname}\par + \csb{etocthelinkednumber}\par +\csb{etocthelinkedpage}\par +\csb{etocthelink}\par + \csb{etocsetlevel}\par +\csb{etocsettocdepth}\par +\csb{etocsetnexttocdepth}\par + \csb{etocsettocdepth.toc}\par +\csb{etocobeytoctocdepth}\par + \csb{etocignoretoctocdepth}\par +\csb{etocdepthtag.toc}\par +\csb{etocsettagdepth}\par + \csb{etocobeydepthtags}\par +\csb{etocignoredepthtags}\par + \csb{etocstandarddisplaystyle}\par +\csb{etocsettocstyle}\par +\csb{etocmulticolstyle}\par + \csb{etocmulticol}\par +\csb{etoclocalmulticol}\par +% \csb{etoctocstyle}\par +% \csb{etoctocstylewithmarks}\par +% \csb{etoctocstylewithmarksnouc}\par + \csb{etocruledstyle}\par +\csb{etocruled}\par +\csb{etoclocalruled}\par + \csb{etocframedstyle}\par +\csb{etocframed}\par +\csb{etoclocalframed}\par +\csb{etocinline}\par + \csb{etocaftertitlehook}\par +\csb{etocaftercontentshook}\par +\csb{etocaftertochook}\par +\csb{etoctoccontentsline}\par +\vspace{5\baselineskip}\hrule height 0pt +\end{multicols} +\advance\linewidth-18pt + +\vspace{-\baselineskip} + +% 15 octobre, je teste les tags +\etocdepthtag.toc {arbitrarily} -% 13 octobre, ceci était une section avant \part{Arbitrarily many TOCs, and local ones too} +% 13 octobre, ceci était une section avant \thispartstats @@ -1192,9 +1121,9 @@ example the table of contents of \renewcommand{\etocbkgcolorcmd}{\color{green!5}} \renewcommand{\etocbelowtocskip}{0pt\relax} \fboxsep1ex - \etocframed[1]{\fbox{\makebox[.5\linewidth]{\etocfontminusone + \etocframedstyle [1]{\fbox{\makebox[.5\linewidth]{\etocfontminusone \hyperref[toc:c]{I am from far away}}}} - \label{toc:d} \ref{toc:c} + \tableofcontents \label{toc:d} \ref{toc:c} \endgroup %% \centeredline{The original is \hyperref[toc:c]{there}.} \end{figure*} @@ -1208,19 +1137,72 @@ We used this: \renewcommand{\etocbkgcolorcmd}{\color{green!5}} \renewcommand{\etocbelowtocskip}{0pt\relax} \fboxsep1ex - \etocframed[1]{\fbox{\makebox[.5\linewidth]{\etocfontminusone + \etocframedstyle [1]{\fbox{\makebox[.5\linewidth]{\etocfontminusone \hyperref[toc:c]{I am from far away}}}} - \label{toc:d} \ref{toc:c} + \tableofcontents \label{toc:d} \ref{toc:c} \endgroup \end{figure*} \end{verbatim} Important: one should not use elsewhere \toc|\ref{toc:d}|. To clone again, one -must use a reference to the original label: \toc|\ref{toc:c}|\unskip. +must use a reference to the original label: \toc|\ref{toc:c}|. + +\section{A powerful functionality of \etoc: the + re-assignment of levels with \csbhyp{etocsetlevel}} + +The intrinsic levels manipulated by \etoc are numeric: from +|-2| (which corresponds to |book| in the |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 \csbhyp{etocsettocdepth}, - \csbhyp{etocsetnexttocdepth} and \csbhyp{etocsettocdepth.toc} commands} + 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} + (|memoir| class) book&-2\\ part&-1\\ chapter&0 \\ + section&1\\ subsection&2 \\ + subsubsection&3 \\ paragraph&4 \\ subparagraph& 5 + \end{tabular}}} + +\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} + +\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} 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: in the @@ -1233,20 +1215,17 @@ and again each time a table of contents needs to be typeset. 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 special names |all| and |none| are recognized). +\csb{etocsetlevel} (the keywords |all| and |none| are recognized, although not +corresponding to a document division). This does the appropriate |\setcounter{tocdepth}{numeric_level}|. -\subsection{The \csbhyp{etocsetnexttocdepth} command} -\label{etocsetnexttocdepth} - As is explained in the next subsection, |tocdepth| is used by |hyperref|, and -one must take steps to prevent its changes to influence the bookmarks, too. So, -\etoc has \csb {etocsetnexttocdepth}\marg{level} whose influence ceases +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. Thus, |\invisibletableofcontents| -is -essentially |\etocsetnexttocdepth{none}\tableofcontents|. +is essentially |\etocsetnexttocdepth{none}\tableofcontents|. -The simplest course is thus to have after |\begin {document}| and before the +The simplest course is thus 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, @@ -1276,10 +1255,8 @@ 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. -\subsection{Further commands \csbhyp{etocsettocdepth.toc}, \csbhyp{etocobeytoctocdepth}, and \csbhyp{etocignoretoctocdepth}} +\section{The command \csbhyp{etocsettoc\-depth.toc}} \label{etocsettocdepth.toc} -\label{etocobeytoctocdepth} -\label{etocignoretoctocdepth} This command \csb{etocsettocdepth.toc} implements some functionality of |tocvsec2|\footnote{\url{http://ctan.org/pkg/tocvsec2}. I thank D.B. for drawing @@ -1294,7 +1271,7 @@ it adds a line to the |.toc| file which, when executed inside a table of contents will enact this change. The command \csb{etocsettocdepth.toc}, like -\csb{etocsettocdepth}\unskip, accepts both numeric and named +\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 @@ -1309,41 +1286,94 @@ tables of contents of the sub-sub-sections of a given chapter. This {\fbox{gets executed in ALL tables of contents.}} -So \csb{etocignoretoctocdepth} is provided to cancel this mechanism when + +\subsection{The commands \csbhyp{etocobeytoctocdepth}, and \csbhyp{etocignoretoctocdepth}} +\label{etocobeytoctocdepth} +\label{etocignoretoctocdepth} + + +So \csb{etocignoretoctocdepth} is provided to cancel the +\csa{etocsettocdepth.toc} mechanism when needed; and \csb{etocobeytoctocdepth} will -re-activate it. The package does \csb{etocobeytoctocdepth} when it is loaded. - - -Actually, with the \emph{shuffling abilities of \etoc}, one may never need nor -wish to do \csa{etoc\-ignoretoctocdepth} if one has used -\csb{etocsettocdepth.toc} in the following powerful way, illustrated on -an example, there are infinite variations. - -In the preamble one does \csb{etocsetlevel}|{partI}{6}|, -\csb{etocsetlevel}|{partII}{6}|, \dots, for as many parts as found in the -document. Then one inserts a command \csb{etocsettocdepth.toc}|{partI}|, just -before the first |\part|, and the same for all others. One may then decide, -individually for each part, what will be the finest level authorized to appear -in the next table of contents, through assignments -\csb{etocsetlevel}|{partI}{2}|, \csb{etocsetlevel}|{partII}{1}|, etc\dots each -time one prints a TOC, one decides on the levels for each part. One may exclude -entirely the part and all its sub-units by setting the level of its associated -tag -to |-2|. - -Important: \csb{etocsetlevel} only accept numeric levels, from |-3| to |6|, with -|-3| only accepted for such dummy level associations (one can not and one should -not try to associate a line style to a named level assigned a numeric value of -|-3|) allowing to exclude an entire |book| from inclusion in a TOC (|memoir| -allows this level |book|). I guess this might prove a rather rare instance, but -still I enlarged \csb{etocsetlevel} to accept it. - -\section{Adding commands to the - \texorpdfstring{\texttt{.toc}}{.toc} file} - -When displaying in that way many tables of contents in the same -document one should be cautious when adding -manually things +re-activate it. The package does initially \csb{etocobeytoctocdepth}. + + +\section{The commands \csbhyp{etocdepthtag.toc} and \csbhyp{etocsettagdepth}} +\label{etocdepthtag.toc} +\label{etocsettagdepth} + +As mentioned above, when the argument to \csb{etocsettocdepth.toc} isn't +numeric but a named level the actual numeric level used is decided at the time +the TOC gets typeset, thus with the \emph{shuffling abilities of \etoc}, one may +obtain a very flexible control in the following way: one first declares with +\csb{etocsetlevel} some +dummy named level, say |partIII|, assigning it the invisible numeric level |6|. +Then before the actual third |\part| command in the source one inserts +\csb{etocsettocdepth.toc}|{partIII}|. At the location where the effect should +cease one inserts in the source \csb{etocsettocdepth.toc}|{all}|. It is now +possible to specify, each time one wants to typeset a TOC, what will be the +finest level for the entries originating in the third part: one just has to do +\csa{etocsetlevel}|{partIII}{1}| for example. This will limit to sections +(if |tocdepth| was at least at that level at the time \toc is encountered). + +This method has some limitations: +\begin{enumerate*}[label={(\roman*)}] + \item the second argument to \csb{etocsetlevel} must be numeric, + \item it can not be set to |-3| (which would be necessary if one wanted to + exclude an entire Book from a TOC in a |memoir| document with multiple such + Books \dots admittedly a possibly rare case!), + \item it is a bit of a hack as |partIII| is not a real division unit, but just + a \emph{tag}. +\end{enumerate*} + +Release |1.07h| has a command \csb{etocdepthtag.toc} which +makes it easier to achieve this variable local control of the |tocdepth| at the +time of typesetting TOCs. + +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 effet of the tag inside the |.toc| file will then be to +set the |tocdepth| counter to the desired value, in real time (as mentioned +already, this can not get finer than the initial value of |tocdepth| at the +start of the TOC). + +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|. + +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}. + + +\subsection{The commands \csbhyp{etocobeydepthtags}, and \csbhyp{etocignoredepthtags}} +\label{etocobeydepthtags} +\label{etocignoredepthtags} + + +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{Adding commands to the \texorpdfstring{\texttt{.toc}}{.toc} file} +\label{sec:addingtotoc} + +We described above \csb{etocsettocdepth.toc} and \csb{etocdepthtag.toc} which +both inserts 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}|. + +One should be cautious when adding in this way +things to the |.toc| file. For example, inserting \csa{addtocontents}|{toc}{\string\clearpage}| just @@ -1376,7 +1406,8 @@ As the |memoir| class by itself allows multiple\toc manual. For this specific issue, the commands \csb{etocsettocdepth.toc}, -\csb{etocignoretoctocdepth} and \csb{etocobeytoctocdepth} are the way to go. +\csb{etocignoretoctocdepth} and \csb{etocobeytoctocdepth} are the way to go; or +their variants \csb{etocdepthtag.toc} and \csb{etocsettagdepth}. As an aside, any |\setcounter{tocdepth}{n}| command added directly to the |.toc| file sees its effect (since release |1.07g|) canceled at the end of each table @@ -1392,7 +1423,7 @@ 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!} + them to be links}? I use the following trick: either in the preamble using |\AtBeginDocument|, or right after |\begin{document}|, I @@ -1411,59 +1442,6 @@ I use the following trick: either in the preamble using indeed be set many times with |\hypersetup| (this is not the case of all |hyperref| options). -\section{A powerful functionality of \etoc: the - re-assignment of levels} - -The intrinsic levels manipulated by \etoc are numeric: from -|-2| (which corresponds to |book| in the |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 -\csa{etocsetlevel}\marg{level\_name}\marg{n}. 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. - - 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} - (|memoir| class) book&-2\\ part&-1\\ chapter&0 \\ - section&1\\ subsection&2 \\ - subsubsection&3 \\ paragraph&4 \\ subparagraph& 5 - \end{tabular}}} - -\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} - -\footnotetext{one has to issue \csa{etoctoclines}, or to set up at - least one style with \csa{etocsetstyle} to escape from the - compatibility mode, which would insist on printing the - paragraphs in the TOC as paragraphs, with a silly gigantic left margin.} \section{Two Examples} @@ -1500,7 +1478,7 @@ breaks. Also, they do not worry about potential multi-column use. \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par} {} -\def\tmptitle{My Very Beautiful Thesis} +\def\tmptitle{My Beautiful Thesis} \etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin \leavevmode\leaders\hrule height 1pt\hfill\ \huge\textit{\tmptitle}\par}{\bigskip} @@ -1629,19 +1607,22 @@ We wrap it up in a \hyperref[toc:floating]{figure environment} showing up \tableofcontents \label{toc:floating} \ref{toc:overview} \vspace{-\baselineskip} \centeredline{|\tableofcontents \ref{toc:overview}| -(\emph{cf.} \autoref{ssec:again} and \hyperref[toc:clone]{\color{niceone}this other toc})} +(\emph{cf.} \autoref{ssec:again} and \hyperref[toc:clone]{this other toc})} \end{figure*} The actual design is not pre-built in \etoc; it uses its `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. This design (with other colors) -is in use also for \hyperref[toc:clone]{\color{niceone}this other toc}, and the -reader is referred to \hyperref[toc:clone]{\color{niceone}its location} for the +is in use also for \hyperref[toc:clone]{this other toc}, and the +reader is referred to its \hyperref[ssec:tocclone]{subsection} for the coding used. -\vfill\eject +% \vfill\eject % \clearpage % 11 octobre 2013 ceci était une section avant: + +\etocdepthtag.toc {surprising} + \part{Surprising uses of \etoc} \label{part:surprising} @@ -1659,7 +1640,7 @@ coding used. \newcommand*{\thisspecialstats}{% \setcounter{mycounti}{0}% - \def\thisspecialstatsaux{% ou plus simple si on ne veut pas le lien. + \def\thisspecialstatsaux{% \let\firstsubname\etocthelinkedname \let\firstsubnumber\etocthelinkednumber \def\thisspecialstatsaux{}} @@ -1692,7 +1673,7 @@ coding used. \begingroup % \endgroup just after the \tableofcontents command \etocinline \etocsetlevel{part}{1} -\etocsetlevel{chapter}{1} +% \etocsetlevel{chapter}{1} \etocsetlevel{visibletoc}{0} \etocsetstyle{visibletoc} {\etocskipfirstprefix} @@ -1700,13 +1681,13 @@ coding used. {{\color{niceone}\etocname}} {} \etocsettocstyle{}{} -\etocsetnexttocdepth{0} +\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 appear in the document; but the numbering + 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 @@ -1792,12 +1773,12 @@ Here are the implementation details: \begingroup \etocinline \etocsetlevel{part}{1} - \etocsetlevel{chapter}{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{0} % display only the `visibletoc' entries from .toc + \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. @@ -2246,7 +2227,7 @@ section, for which the layout is completely modified: This example only has sections and subsections, and the code used in \csa{MyStandardTOC} was: \begin{verbatim} \etocsetstyle{section}{} - {\ifnum\etocthenumber=5 + {\ifnum\etocthenumber=4 \etocsetstyle{subsection} {\par\nopagebreak\begingroup \leftskip1.5em \rightskip\@tocrmarg \parfillskip\@flushglue @@ -2307,16 +2288,15 @@ pointer, not storable for later use; but the package provides whose contents contain the hyperlink in a form which can be stored and later reused. -The various \etoc styles for sections, subsections, \dots, use a -macro |\appendtotok| whose r\^ole is to append to a given token -list variable the once-expanded macro given as second argument. -The token list register used is called |\treetok|. All this will happen -in reaction to a |\tableofcontents| command, but \emph{nothing} is -yet 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 containing the contents -of |\treetok|. +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|. \newtoks\treetok \newtoks\tmptok @@ -2582,7 +2562,7 @@ contents of this (or another) document part, only a \csa{sectiontok} and a \hypersetup{hidelinks}% \begin{tikzpicture} [grow cyclic, - level 1/.style={level distance=4cm,sibling angle=120}, + level 1/.style={level distance=4cm,sibling angle=90}, 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] @@ -2613,7 +2593,7 @@ producing it: \hypersetup{hidelinks}% \begin{tikzpicture} [grow cyclic, - level 1/.style={level distance=4cm,sibling angle=120}, + level 1/.style={level distance=4cm,sibling angle=90}, 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] @@ -2676,7 +2656,9 @@ previous % \vfill\eject -\part{Package commands for the toc line styles} +\etocdepthtag.toc {linestyles} + +\part{Commands for the toc line styles} \label{part:linestyles} \thispartstats @@ -2794,14 +2776,11 @@ provided for use inside the \marg{prefix} and \marg{contents} parts of the \csa{etocsetstyle} specification. They represent of course, the name, number, and page number of the corresponding toc -entry.\footnote{\protect\fbox{% -\parbox{.9\textwidth}{up to version -\texttt{1.07a} the package put an \csa{xspace} in each of -\csa{etocname}, \csa{etocnumber}, and \csa{etocpage}, but this -wasn't such a great idea and has now been removed.}}} If package |hyperref| is +entry. If package |hyperref| is active in the document and has added hyperlinks to the TOC data, then these links are kept in the commands \csa{etocname}, \csa{etocnumber} and -\csa{etocpage} (this last one will have a link only if |hyperref| was passed option \emph{linktoc=all}.) +\csa{etocpage} (this last one will have a link only if |hyperref| was passed +option \emph{linktoc=all}.) \subsection{The \csbhyp{etocskipfirstprefix} command} \label{etocskipfirstprefix} @@ -2919,7 +2898,7 @@ either, but |\etoclink{\etocthepage}| does. The command \csa{etoclink} is robust. \subsection{The \csbhyp{etocthelinkedname}, \csbhyp{etocthelinkednumber}, -\csbhyp{etocthelinkedpage} and \csbhyp{etocthelink} commands.} +\csbhyp{etocthelinkedpage} and \csbhyp{etocthelink} commands} \label{etocthelinkedname} \label{etocthelinkednumber} \label{etocthelinkedpage} @@ -2948,7 +2927,8 @@ which allows to make a link with an arbitrary name. All these commands are fragile. -\section{The \csbhyp{etocsetlevel} command}\label{etocsetlevel} +\section{The \csbhyp{etocsetlevel} command} +\label{etocsetlevel} As already explained in \autoref{part:surprising}, one can inform \etoc of a level to associate to a given sectioning @@ -3046,9 +3026,9 @@ Let us switch to the color red, and also add this command to the |.toc| file: Actually, this title here was printed black, due to the way the |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]{\color{niceone}{main table of contents}} at the beginning of -this document, and also in the \hyperref[toc:a]{\color{niceone}{table of -contents for this part}}. Both entries obey as expected the +\hyperref[toc:main]{main table of contents} at the beginning of +this document, and also in the \hyperref[toc:a]{table of +contents for this part}. Both entries obey as expected the |\color{red!50}| command inserted in the |.toc| file. But let us now close this subsection and start a section. @@ -3057,8 +3037,8 @@ But let us now close this subsection and start a section. \section{Am I also red?} The question is about how it appears in the tables of contents: the answer is -that, yes it is red in the \hyperref[toc:main]{\color{niceone}main TOC}, and no -it is not red in the \hyperref[toc:a]{\color{niceone}local TOC for this part}. +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}|. @@ -3085,8 +3065,9 @@ language changes occurring in the document. % \clearpage +\etocdepthtag.toc {globalcmds} -\part{Package commands for the toc display style} +\part{Commands for the toc display style} \label{part:globalcmds} \begin{verbatim} @@ -3114,49 +3095,53 @@ shortcuts: \etocruled[1]{Title} (or \etoclocalruled[1]{Title}) \end{verbatim} -\subsection{The command \csbhyp{etocruledstyle}}\label{etocruledstyle} +\subsection{The command \csbhyp{etocsettocstyle}} +\label{etocsettocstyle} -The general format of \csa{etocruledstyle} is:\\ -\centerline{\color{blue}\csa{etocruledstyle}% -\oarg{number of columns}\marg{title of the toc}} -\noindent Note that the title is horizontal material, if it -does not fit on one line it should be put in a \csa{parbox} of -a given width. We did this and even enclosed the parboxes in -\csa{fbox}es to get frames around them. For the example with -the standard formatting we did not use an \csa{fbox} and got -rid of the horizontal rules via: -\begin{verbatim} -\renewcommand{\etoctoprule}{\hrule height 0pt} -\end{verbatim} -The green frame for the heading of the table of contents at -the \hyperref[toc:a]{% - \color{niceone} start of the second part of this - document} was obtained with: -\begin{verbatim} -\etocruledstyle[1]{\etocfontminusone\color{green}% - \fboxrule1pt\fboxsep1ex - \framebox[\linewidth] - {\normalcolor\hss Contents of this part\hss}} -\end{verbatim} +This is a command with two mandatory arguments:\\ +\centerline{\color{blue}\csa{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) +expect to start in `vertical mode'. +It 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. + +The commands to be described next \csb{etocmulticolstyle}, +\csb{etocruledstyle}, and \csb{etocframedstyle} all call +\csa{etocsettocstyle} as a lower-level routine, starting a +\texttt{multi\-cols} environment in \marg{before\_toc} to close it in +\marg{after\_toc}. -\subsection{The command \csbhyp{etocmulticolstyle}}\label{etocmulticolstyle} +\subsection{The commands \csbhyp{etocmulticolstyle}, \csbhyp{etocmulticol}, and \csbhyp{etoclocalmulticol}} +\label{etocmulticolstyle} +\label{etocmulticol} +\label{etoclocalmulticol} -This is also a command with one optional and one mandatory argument:\\ +This is a command with one optional and one mandatory argument:\\ \centerline{\color{blue}\csa{etocmulticolstyle}% \oarg{number\_of\_columns}\marg{heading}} The \meta{number\_of\_columns} can go from 1 to 10 (it defaults to 2, and from 2 on is passed to a |multicols| -environment). The \meta{heading} should be some `vertical' material like: +environment). The \meta{heading} will be typically be some `vertical' material +like: \begin{center} \meta{heading} = {\ttfamily\string\section\lowast}\marg{title} \end{center} -[\emph{New with 1.07}] An explicit |\par| not being accepted in the -\meta{heading} argument (this is actually a restriction -originating in the -|multicols| environment), an implicit one is automatically -added by \etoc at the end of the argument, as in this -example which shows how the main table of contents of this document was +but one may also have horizontal material like |\fbox{Hello World}| as \etoc +adds automatically a |\par| at the end of the ``heading'' argument to +\csb{etocmulticolstyle}. Here is for example +how the main table of contents of this document was configured: \begin{verbatim} \etocmulticolstyle{\noindent\bfseries\Large @@ -3164,15 +3149,15 @@ configured: \MakeUppercase{Table of Contents}} \end{verbatim} After \csa{etocmulticolstyle} all future \csa{tableofcontents} will use the -specified style, if not changed in-between. A shortcut for +specified style, if it does not get changed in-between. A shortcut for just one table of contents and -not affecting the styles of later TOCs is:\\ +no impact on the styles of later TOCs is:\\ \centerline{\csa{etocmulticol}\oarg{number\_of\_columns}\marg{heading}} And there is also \csa{etoclocalmulticol}\oarg{number\_of\_columns}\marg{heading}. - -\subsubsection{The command \csbhyp{etoctocstyle}}\label{etoctocstyle} +\subsubsection{The command \csbhyp{etoctocstyle}} +\label{etoctocstyle} \centeredline{\color{blue}\csa{etoctocstyle}\oarg{kind}% \marg{number\_of\_columns}\marg{title}} @@ -3201,10 +3186,29 @@ which does not uppercase. \paragraph{really?} -\subsection{The command \csbhyp{etocruled}} +\subsection{The commands \csbhyp{etocruledstyle}, \csbhyp{etocruled} and \csbhyp{etoclocal\-ruled}} +\label{etocruledstyle} \label{etocruled} \label{etoclocalruled} +The general format of \csa{etocruledstyle} is:\\ +\centerline{\color{blue}\csa{etocruledstyle}% +\oarg{number of columns}\marg{title of the toc}} +\noindent Note that the title is horizontal material, if it +does not fit on one line it should be put in a \csa{parbox} of +a given width. We did this and even enclosed the parboxes in +\csa{fbox}es to get frames around them. +The green frame for the heading of the table of contents at +the \hyperref[toc:a]{start of the second part of this + document} was obtained with: +\begin{verbatim} +\etocruledstyle[1]{\etocfontminusone\color{green}% + \fboxrule1pt\fboxsep1ex + \framebox[\linewidth] + {\normalcolor\hss Contents of this part\hss}} +\end{verbatim} + + As a shortcut to set the style with \csb{etocruledstyle} and then issue a \csa{tableofcontents}, all inside a group @@ -3213,8 +3217,10 @@ affected, there is:\\ \centerline{\csb{etocruled}\oarg{number\_of\_columns}\marg{title}} And the local form will be \csb{etoclocalruled}. -\subsection{The commands \csbhyp{etocframedstyle} and \csbhyp{etocframed}} -\label{etocframedstyle}\label{etocframed} +\subsection{The commands \csbhyp{etocframedstyle}, \csbhyp{etocframed}, and \csbhyp{etoclocal\-framed}} +\label{etocframedstyle} +\label{etocframed} +\label{etoclocalframed} Same mechanism:\\ \centerline{\color{blue}\csa{etocframedstyle}% @@ -3225,40 +3231,41 @@ Here the entire table of contents is framed, hence this can only work if it fits on a page. Note that the title itself is not framed, if one wants a frame one should set it up inside the \meta{title} argument to \csa{etocframedstyle} or -\csa{etocframed}. There is also \csa{etoc\-localframedstyle} and +\csa{etocframed}. There is also \csa{etoclocalframed}. -\subsection{Headings, titles, \csbhyp{etocinnertopsep}} +\subsection{Headings, titles, \csbhyp{etocoldpar}, \csbhyp{etocinnertopsep}} \label{etocinnertopsep} \label{etocoldpar} There is a slight difference between \csa{etocmulticolstyle} and \csa{etocruledstyle} or \csa{etocframedstyle}. For \csa{etocmulticolstyle} the mandatory -\meta{heading} argument can be something like: +\meta{heading} argument can be vertical mode material like: \starit{section}% |{|\emph{Table of Contents}|}|. On the contrary \csa{etocruledstyle} and \csa{etocframedstyle} expect an argument -``in LR mode'' (to use the terminology from the \emph{LaTeX, a +``in LR mode'' (to use the terminology from \emph{LaTeX, a document preparation system}). This means that multiline contents arguments to \csa{etocruledstyle} or \csa{etocframedstyle} must be enclosed in something like a \csa{parbox}. -The command \csa{etocmulticolstyle} now +The command \csa{etocmulticolstyle} also accepts horizontal mode material in its mandatory -argument \meta{heading}: it internally automatically adds a -closing |\par|. So one can use for example +argument \meta{heading}, so one can do for example |\etocmulticolstyle{Hello World}|. -As \csa{etocmulticolstyle} does not accept |\par| in is optional heading -argument, \etoc provides \csb{etocoldpar} as a substitute for |\par| (it does -|\let\etocoldpar\par| just before the |multicols| environment and -automatically adds it to close the heading, before the vertical skip of value -\csa{etocinnertopsep}).\footnote{this command \csa{etocoldpar} (= working - \csa{par} in the argument to \csa{etocmulticolstyle}) is not related to the - switch \csa{etocinline} whose purpose is to tell \etoc not to do a \csa{par} - before the table of contents.} The command \csb{etocoldpar} can also be used -explicitely in the mandatory argument to \csa{etocmulticolstyle}. +From restrictions of the |multicols| environment, no explicit |\par| or empty +line can be contained in the heading argument, but \etoc provides +\csb{etocoldpar} as a substitute: it does |\let\etocoldpar\par| just before the +|multicols| environment and automatically adds it to close the heading, before +the vertical skip of value \csa{etocinnertopsep}.\footnote{this command + \csa{etocoldpar} (= working \csa{par} in the argument to + \csa{etocmulticolstyle}) is not related to the switch \csa{etocinline} whose + purpose is to tell \etoc not to do a \csa{par} before the table of contents.} +The command \csb{etocoldpar} can also be used explicitely if needed in the +mandatory argument to \csa{etocmulticolstyle} (as a replacement to having an +empty line there). An important dimension used by all three of \csa{etocmulticolstyle}, @@ -3270,33 +3277,6 @@ value is |2ex| and it is changed by |\setlength|. -\subsection{The command \csbhyp{etocsettocstyle}} -\label{etocsettocstyle} - -This is a command with two mandatory arguments:\\ -\centerline{\color{blue}\csa{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) -expect to start in `vertical mode'. - -It 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. - -The previously described commands \csa{etocmulticolstyle}, -\csa{etocruledstyle}, and \csa{etocframedstyle} actually call -\csa{etocsettocstyle} as a lower-level routine, and start a -|multicols| environment in \marg{before\_toc} to close it in -\marg{after\_toc}. \subsection{The compatibility mode \csbhyp{etocstandarddisplaystyle}} \label{etocstandarddisplaystyle} @@ -3306,18 +3286,19 @@ done regarding the global display style of the table of contents, in its absence. All customizing from inside the class should be obeyed, too. -\subsection{The command \csbhyp{etocinline}} +\subsection{The command \csbhyp{etoc\-inline}} \label{etocinline} \label{etocnopar} -With |\etocinline|, or its synonym |\etocnopar|, the |\tableofcontents| -command and its variants do not first issue a |\par|. This way, the table of -contents can be printed in an inline style; or, if is is used only for -preparing some token list or macro, it will leave nothing in the token stream -on execution. +With |\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. -\section{Starred variants of the \csbhyp{tableofcontents} - etc... commands} +\section{Starred variants of the \csbhyp{tableofcontents} etc... commands} +\label{tableofcontents*} +\label{localtableofcontents*} \label{etocaftertitlehook} \label{etocaftercontentshook} \label{etocmemoirtoctotocfmt} @@ -3388,13 +3369,11 @@ beginning of this \autoref{part:globalcmds}. 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}).\footnote{for reasons currently mysterious to me, when I do - not de-activate the two-column mode in the figure with the |[1]| optional - argument to \csa{etocframedstyle}, there is a color leak from the - \csa{color}|\{red\}| line which was added to the |.toc|, not stopped by the - \csa{normalcolor} following it. This happens with all three \etoc styles using - a |multicols| environment, and has nothing to do with the other color - commands, for the frame or the background. |[2013/10/13] 1.07g|} +\vpageref{toc:b}).\footnote{inside the |figure*| environment and before the + framed toc, which uses |multicols|, we added \csa{normalcolor} as work-around + to an interaction bug (related to the \csa{color\{red\}} command we added to + the |.toc| file) between |multicols|, |color| and the |figure| + environment. This bug has nothing to do with \etoc.} \begin{verbatim} \etocdefaultlines @@ -3417,7 +3396,7 @@ line styles and some colors added (it has been put in a float which appears % use \fcolorbox to set up a colored frame for the title \fboxrule1pt \renewcommand{\etocbelowtocskip}{0pt\relax} -\etocframedstyle [1]{\normalsize\rmfamily\itshape +\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 @@ -3425,6 +3404,7 @@ line styles and some colors added (it has been put in a float which appears one page. It has the label |toc:b|.}}} \begin{figure*}[ht!] \centering +\normalcolor % work-around to a bug involving color and multicols (and figure) \tableofcontents \label{toc:b} \ref{toc:globalcmds} \end{figure*} \endgroup @@ -3451,7 +3431,7 @@ line styles and some colors added (it has been put in a float which appears % use \fcolorbox to set up a colored frame for the title \fboxrule1pt \renewcommand{\etocbelowtocskip}{-.5\baselineskip\relax} -\etocframedstyle [1]{\normalsize\rmfamily\itshape +\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 @@ -3459,17 +3439,25 @@ line styles and some colors added (it has been put in a float which appears one page. It has the label |toc:b|.}}} \begin{figure*}[ht!] \centering +\normalcolor % work-around to a bug involving color and multicols (and figure) \tableofcontents \label{toc:b} \ref{toc:globalcmds} \end{figure*} \endgroup % Il y a un color leak du framed mais uniquement lorsqu'il est mis dans le -% float. 2013/10/13, qui révèle un bug (??)) du style framed je vais regarder +% float. 2013/10/13, qui révèle un bug (?? NON) du style framed je vais regarder % mais bon. Le leak apparaît avec ruled aussi, et même avec juste multicolstyle % MAIS PAS EN UNE SEULE COLONNE (même framed ou ruled). il semble qu'il y aie % donc un problème d'interaction avec multicol là. à voir. Pas le temps % maintenant. +% 2013/10/14 +% il s'agit en fait d'un bug de color+multicols+figure qui n'a rien à voir avec +% etoc: +% http://tex.stackexchange.com/questions/138783/color-leak-from-multicols-within-a-figure +% J'ai trouvé le work-around qui consiste simplement à ajouter un \normalcolor +% _avant_ le multicols à l'intérieur de figure* + \subsection{A (crazy) inline display} Let us finally make some crazy inline display of the table of @@ -3515,6 +3503,8 @@ Here is the code which has been used:\footnote{as this new version of the %% \clearpage +\etocdepthtag.toc {custom} + \part{Using and customizing \etoc} \label{part:custom} @@ -3613,14 +3603,10 @@ both the line styles and the toc display style are the ones currently defined, not the ones from the cloned toc. -\subsection{The package default line styles: \csbhyp{etocdefaultlines}} +\section{The package default line styles: \csbhyp{etocdefaultlines}} \label{etocdefaultlines} -Activating the use of the package default line styles\footnote{they were written - at a very early stage in the development of the package, and version |1.07e| - has, among other things, modified the previous unsatisfactory use of penalties - and vertical spacing commands. This will cause differences to - documents having been compiled with earlier versions, apologies for that.} is +Activating the use of the package default line styles is done via \csa{etocdefaultlines}, or \csa{etoctoclines} if these styles have not been modified with \csa{etocsetstyle}. Sections and sub-sections are printed in essentially the same manner, except that the leading for sub-sections is a bit @@ -3647,7 +3633,8 @@ document had been done with a class having the \csa{chapter} command: we will print sections as chapters, and subsections as sections. We use \csa{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 \csa{etocfontone} command for that. +medium series; we modify the \csa{etocfontone} command for that. Also we use dot +leaders which are less spread out than in the package defautl. \begin{verbatim} @@ -3657,8 +3644,7 @@ medium series; we modify the \csa{etocfontone} command for that. \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 - being printed as chapters, and subsections as sections. + sections as chapters, and subsections as sections. }}} \etocdefaultlines \etocsetnexttocdepth{1} @@ -3666,6 +3652,9 @@ medium series; we modify the \csa{etocfontone} command for that. \etocsetlevel{section}{0} \etocsetlevel{subsection}{1} \renewcommand*{\etocfontone}{\normalfont \normalsize} +\renewcommand*{\etoctoclineleaders} + {\hbox{\normalfont\normalsize\hbox to 1ex {\hss.\hss}}} +\sloppy \tableofcontents \endgroup \end{verbatim} @@ -3676,8 +3665,7 @@ medium series; we modify the \csa{etocfontone} command for that. \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 - being printed as chapters, and subsections as sections. + sections as chapters, and subsections as sections. }}} \etocdefaultlines @@ -3687,14 +3675,151 @@ medium series; we modify the \csa{etocfontone} command for that. \etocsetlevel{section}{0} \etocsetlevel{subsection}{1} \renewcommand*{\etocfontone}{\normalfont \normalsize} - +\renewcommand*{\etoctoclineleaders} + {\hbox{\normalfont\normalsize\hbox to 1ex {\hss.\hss}}} +\sloppy \tableofcontents \endgroup -\subsection{One more example TOC layout} +\section{Customizing \etoc} + +\subsection{Customizing the \etoc pre-defined line styles} + +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} +\newcommand*\etocfonttwo{\normalfont \normalsize} +\newcommand*\etocfontthree{\normalfont \footnotesize} + +\newcommand*\etocsepminustwo{4ex plus .5ex minus .5ex} +\newcommand*\etocsepminusone{4ex plus .5ex minus .5ex} +\newcommand*\etocsepzero{2.5ex plus .4ex minus .4ex} +\newcommand*\etocsepone{1.5ex plus .3ex minus .3ex} +%%\newcommand*\etocseptwo{1ex plus .15ex minus .15ex} % modified in 1.07e +\newcommand*\etocseptwo{.5ex plus .1ex minus .1ex} +\newcommand*\etocsepthree{.25ex plus .05ex minus .05ex} + +\newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil} +\newcommand*\etocminustworightmargin{1.5em plus -0.5fil} +\newcommand*\etocminusoneleftmargin{1em} +\newcommand*\etocminusonerightmargin{1em} +\newcommand*\etocbaselinespreadminustwo{1} +\newcommand*\etocbaselinespreadminusone{1} +\newcommand*\etocbaselinespreadzero{1} +\newcommand*\etocbaselinespreadone{1} +\newcommand*\etocbaselinespreadtwo{1} +\newcommand*\etocbaselinespreadthree{.9} +\newcommand*\etoctoclineleaders + {\hbox{\normalfont\normalsize\hbox to 2ex {\hss.\hss}}} +\newcommand*\etocabbrevpagename{p.~} +\newcommand*\etocpartname{\partname} % utilisateurs de frenchb: attention + % car donne "partie" sans majuscule. +\newcommand*\etocbookname{Book} % to be modified according to language +\end{verbatim} -The \csa{etocframedstyle} puts the title on the top +No customizing of the standard line styles is possible from +within \etoc. As already explained, when +\csa{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 + KOMA-script classes, we noticed that + \csa{etocstandarddisplaystyle} was apparently needed for the + KOMA options |toc=left| to be active at the level of the line entries.} + + +The \csa{etocstandardlines} compatibility mode will work also with +sectioning commands made known to \etoc via \csa{etocsetlevel}, +under the condition of course that these sectioning commands +are accompanied with all the relevant definitions for +typesetting toc entries in the \LaTeX{} default manner +(existence of the macros \csa{l@something} . . .). + +Using the command \csa{etocsetstyle}, be it in the preamble or +in the body of the document, has the secondary effect of +switching off the compatibility mode. + +\subsection{Customizing the toc display styles} + + +Again we list the relevant macros, what they do should be +legible from their names. Note that \csa{renewcommand}'s and +not \csa{setlength}'s have to be used for what appear to be +lengths, and that color commands are not just color +specifications, they must include \csa{color}, and are canceled +by re-defining them to do \csa{relax}. +\begin{verbatim} +\newcommand*\etocabovetocskip{3.5ex plus 1ex minus .2ex} +\newcommand*\etocbelowtocskip{3.5ex plus 1ex minus .2ex} + +\newcommand*\etoccolumnsep{2em} +\newcommand*\etocmulticolsep{0ex} +\newcommand*\etocmulticolpretolerance{-1} +\newcommand*\etocmulticoltolerance{200} +\newcommand*\etocdefaultnbcol{2} +\newcommand*\etocinnertopsep{2ex} +\newcommand*\etoctoprule{\hrule} +\newcommand*\etoctoprulecolorcmd{\relax} + +% for the framed style only: +\newcommand*\etocinnerleftsep{2em} +\newcommand*\etocinnerrightsep{2em} +\newcommand*\etocinnerbottomsep{3.5ex} + +\newcommand*\etocleftrule{\vrule} +\newcommand*\etocrightrule{\vrule} +\newcommand*\etocbottomrule{\hrule} +\newcommand*\etocleftrulecolorcmd{\relax} +\newcommand*\etocrightrulecolorcmd{\relax} +\newcommand*\etocbottomrulecolorcmd{\relax} + +\newcommand*\etocbkgcolorcmd{\relax} + +% hooks +\newcommand\etocframedmphook{\relax} +\end{verbatim} + +The \csa{etocframedmphook} is positioned immediately +after the beginning of a minipage environment where the +contents of the framed TOC are typeset. + +The \csa{...colorcmd} things are initially set to be +\csa{relax}, so there is no need to do \csa{usepackage}|{color}| +if the document does not use colors. If the scope of a change +to a color command such as \csa{etocbkgcolorcmd} has not +been limited to a group and one then wishes to let it again be +\csa{relax} one must use a \csa{renewcommand} and not +\csa{let}\csa{etocbkgcolorcmd}\csa{relax}. + +Regarding the dimensions of the top rule they can be specified +in |ex|'s or |em|'s as in this example: +\centeredline{|\renewcommand{\etoctoprule}{\hrule height 1ex}|} +The package code is done in such a manner +that it is the font size in instance at the end of typesetting +the title argument to \csa{etocruledtoc} or +\csa{etocframedtoc} which will be used for the meaning of the +`1ex'. Of course also the other rule commands can have their +dimensions in font relative units, but their values are +decided on the basis of the font in effect just before the +table of contents. + +The top and bottom rules do not have to be rules and can be +horizontal \emph{leaders} (of a specified height) in the general +\TeX{} sense. However the left and right rules are not +used as (horizontal) leaders but as objects of a given specified +width. Note that \emph{only} the Plain \TeX{} syntax for rules is +accepted here. + +\section{One more example of colored TOC layout} +\label{ssec:tocclone} + +The command \csa{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} @@ -3865,143 +3990,11 @@ 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. -\section{Customizing \etoc} - -\subsection{Customizing the \etoc pre-defined line styles} - -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} -\newcommand*\etocfonttwo{\normalfont \normalsize} -\newcommand*\etocfontthree{\normalfont \footnotesize} - -\newcommand*\etocsepminustwo{4ex plus .5ex minus .5ex} -\newcommand*\etocsepminusone{4ex plus .5ex minus .5ex} -\newcommand*\etocsepzero{2.5ex plus .4ex minus .4ex} -\newcommand*\etocsepone{1.5ex plus .3ex minus .3ex} -%%\newcommand*\etocseptwo{1ex plus .15ex minus .15ex} % modified in 1.07e -\newcommand*\etocseptwo{.5ex plus .1ex minus .1ex} -\newcommand*\etocsepthree{.25ex plus .05ex minus .05ex} - -\newcommand*\etocminustwoleftmargin{1.5em plus 0.5fil} -\newcommand*\etocminustworightmargin{1.5em plus -0.5fil} -\newcommand*\etocminusoneleftmargin{1em} -\newcommand*\etocminusonerightmargin{1em} - -\newcommand*\etocbaselinespreadminustwo{1} -\newcommand*\etocbaselinespreadminusone{1} -\newcommand*\etocbaselinespreadzero{1} -\newcommand*\etocbaselinespreadone{1} -\newcommand*\etocbaselinespreadtwo{1} -\newcommand*\etocbaselinespreadthree{.9} -\newcommand*\etoctoclineleaders - {\hbox{\normalfont\normalsize\hbox to 2ex {\hss.\hss}}} -\newcommand*\etocabbrevpagename{p.~} -\newcommand*\etocpartname{\partname} % utilisateurs de frenchb: attention - % car donne "partie" sans majuscule. -\newcommand*\etocbookname{Book} % to be modified according to language -\end{verbatim} -No customizing of the standard line styles is possible from -within \etoc. As already explained, when -\csa{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 - KOMA-script classes, we noticed that - \csa{etocstandarddisplaystyle} was apparently needed for the - KOMA options |toc=left| to be active at the level of the line entries.} - - -The \csa{etocstandardlines} compatibility mode will work also with -sectioning commands made known to \etoc via \csa{etocsetlevel}, -under the condition of course that these sectioning commands -are accompanied with all the relevant definitions for -typesetting toc entries in the \LaTeX{} default manner -(existence of the macros \csa{l@something} . . .). - -Using the command \csa{etocsetstyle}, be it in the preamble or -in the body of the document, has the secondary effect of -switching off the compatibility mode. - -\subsection{Customizing the toc display styles} - - -Again we list the relevant macros, what they do should be -legible from their names. Note that \csa{renewcommand}'s and -not \csa{setlength}'s have to be used for what appear to be -lengths, and that color commands are not just color -specifications, they must include \csa{color}, and are canceled -by re-defining them to do \csa{relax}. -\begin{verbatim} -\newcommand*\etocabovetocskip{3.5ex plus 1ex minus .2ex} -\newcommand*\etocbelowtocskip{3.5ex plus 1ex minus .2ex} - -\newcommand*\etoccolumnsep{2em} -\newcommand*\etocmulticolsep{0ex} -\newcommand*\etocmulticolpretolerance{-1} -\newcommand*\etocmulticoltolerance{200} -\newcommand*\etocdefaultnbcol{2} -\newcommand*\etocinnertopsep{2ex} -\newcommand*\etoctoprule{\hrule} -\newcommand*\etoctoprulecolorcmd{\relax} - -% for the framed style only: -\newcommand*\etocinnerleftsep{2em} -\newcommand*\etocinnerrightsep{2em} -\newcommand*\etocinnerbottomsep{3.5ex} - -\newcommand*\etocleftrule{\vrule} -\newcommand*\etocrightrule{\vrule} -\newcommand*\etocbottomrule{\hrule} -\newcommand*\etocleftrulecolorcmd{\relax} -\newcommand*\etocrightrulecolorcmd{\relax} -\newcommand*\etocbottomrulecolorcmd{\relax} - -\newcommand*\etocbkgcolorcmd{\relax} - -% hooks -\newcommand\etocframedmphook{\relax} -\end{verbatim} - -The \csa{etocframedmphook} is positioned immediately -after the beginning of a minipage environment where the -contents of the framed TOC are typeset. - -The \csa{...colorcmd} things are initially set to be -\csa{relax}, so there is no need to do \csa{usepackage}|{color}| -if the document does not use colors. If the scope of a change -to a color command such as \csa{etocbkgcolorcmd} has not -been limited to a group and one then wishes to let it again be -\csa{relax} one must use a \csa{renewcommand} and not -\csa{let}\csa{etocbkgcolorcmd}\csa{relax}. - -Regarding the dimensions of the top rule they can be specified -in |ex|'s or |em|'s as in this example: -\centeredline{|\renewcommand{\etoctoprule}{\hrule height 1ex}|} -The package code is done in such a manner -that it is the font size in instance at the end of typesetting -the title argument to \csa{etocruledtoc} or -\csa{etocframedtoc} which will be used for the meaning of the -`1ex'. Of course also the other rule commands can have their -dimensions in font relative units, but their values are -decided on the basis of the font in effect just before the -table of contents. - -The top and bottom rules do not have to be rules and can be -horizontal \emph{leaders} (of a specified height) in the general -\TeX{} sense. However the left and right rules are not -used as (horizontal) leaders but as objects of a given specified -width. Note that \emph{only} the Plain \TeX{} syntax for rules is -accepted here. +% \clearpage +\etocdepthtag.toc {tips} -% \clearpage \part{Tips} \label{part:tipsandtricks} @@ -4013,6 +4006,7 @@ accepted here. \begin{verbatim} +\etocdefaultlines \renewcommand\etoctoprule{\hrule height 2pt depth 2pt} \etocruled{\color{green}\fboxrule2pt\fboxsep1ex \fbox{\raisebox{-\fontdimen22\textfont2} @@ -4023,6 +4017,8 @@ accepted here. \ref{toc:globalcmds} \end{verbatim} +\etocdefaultlines + \renewcommand\etoctoprule{\hrule height 2pt depth 2pt} \etocruled{\color{green}\fboxrule2pt\fboxsep1ex @@ -4154,7 +4150,7 @@ And now, the variant which was used for \newcommand*\thisspecialstatsaux{} \newcommand*{\thisspecialstats}{% \setcounter{mycounti}{0}% - \def\thisspecialstatsaux{% ou plus simple si on ne veut pas le lien. + \def\thisspecialstatsaux{% \let\firstsubname\etocthelinkedname \let\firstsubnumber\etocthelinkednumber \def\thisspecialstatsaux{}} @@ -4181,18 +4177,170 @@ And now, the variant which was used for \end{verbatim} \endgroup +\subsection{Using depth tags} +\label{ssec: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} up to paragraphs. So we simply added to this +source various \csb{etocdepthtag.toc} commands, and it is now just a matter to +set the levels for each one of these tags (as they were left undefined until +now, they were ignored in all previous 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} (the +way to put the page numbers into the column on the right is more like the method +used by \LaTeX2e's |\@dottedtocline|). And after a few minutes for choosing +lengths (now that this has been done once, it can be recycled easily) we get: + +\etocsetnexttocdepth {all} +\begingroup +\parindent 0pt +\leftskip 0cm +\rightskip 0.75cm +\parfillskip -\rightskip +% I used this before plagiarizing \@dottedtocline: +% \parfillskip 0pt +% \newcommand*{\PushintoRightMargin}[1] +% {\strut\vadjust{\vskip-\dp\strutbox +% \smash{\hbox to \linewidth {\hss \llap{#1}}} +% \vskip\dp\strutbox }} +\newcommand*{\EndParWithPagenoInMargin} + {\nobreak\hfill + \nobreak\makebox[0.75cm][r]{\mdseries\normalsize\etocpage}% + \par} +\renewcommand*\etoctoclineleaders + {\hbox{\normalfont\normalsize\hbox to .75ex {\hss.\hss}}} +\newcommand*{\EndParWithPagenoInMarginAndLeaders} + {\nobreak\leaders\etoctoclineleaders\hfill + \nobreak\makebox[0.75cm][r]{\mdseries\normalsize\etocpage}% + \par } +\etocsetstyle {part} + {} + {\leavevmode\leftskip 0cm\relax} + {\bfseries\large\makebox[1cm][r]{\etocnumber\ \ }% + \etocname\EndParWithPagenoInMargin\smallskip} + {} +\etocsetstyle {section} + {} + {\leavevmode\leftskip 1cm\relax} + {\bfseries\normalsize\makebox[.75cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsetstyle {subsection} + {} + {\leavevmode\leftskip 1.75cm\relax } + {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsetstyle {subsubsection} + {} + {\leavevmode\leftskip 2.75cm\relax } + {\mdseries\normalsize\makebox[1.25cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsetstyle {paragraph} + {} + {\leavevmode\leftskip 4cm\relax } + {\mdseries\normalsize\makebox[1.5cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsettagdepth {preamble} {none} +\etocsettagdepth {overview} {part} +\etocsettagdepth {arbitrarily}{part} +\etocsettagdepth {surprising} {part} +\etocsettagdepth {linestyles} {part} +\etocsettagdepth {globalcmds} {paragraph} +\etocsettagdepth {custom} {part} +\etocsettagdepth {tips} {part} +\etocsettagdepth {code} {none} +\renewcommand\etoctoprule {\hrule height 3pt\relax } +\renewcommand\etoctoprulecolorcmd {\color{blue}} +\renewcommand\etocaftercontentshook + {\medskip\begingroup \color{blue}\hrule height 3pt \endgroup } +\etocruledstyle [1]{\Large\bfseries \fbox{\makebox[8cm]{A TOC using depth tags}}} +\sloppy +\tableofcontents +\endgroup + +\begin{verbatim} +\etocsetnexttocdepth {all} +\begingroup +\parindent 0pt \leftskip 0cm \rightskip .75cm \parfillskip -\rightskip +\newcommand*{\EndParWithPagenoInMargin} + {\nobreak\hfill + \nobreak\makebox[0.75cm][r]{\mdseries\normalsize\etocpage}% + \par} +\renewcommand*\etoctoclineleaders + {\hbox{\normalfont\normalsize\hbox to .75ex {\hss.\hss}}} +\newcommand*{\EndParWithPagenoInMarginAndLeaders} + {\nobreak\leaders\etoctoclineleaders\hfill + \nobreak\makebox[0.75cm][r]{\mdseries\normalsize\etocpage}% + \par } +\etocsetstyle {part} + {} + {\leavevmode\leftskip 0cm\relax} + {\bfseries\large\makebox[1cm][r]{\etocnumber\ \ }% + \etocname\EndParWithPagenoInMargin\smallskip} + {} +\etocsetstyle {section} + {} + {\leavevmode\leftskip 1cm\relax} + {\bfseries\normalsize\makebox[.75cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsetstyle {subsection} + {} + {\leavevmode\leftskip 1.75cm\relax } + {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsetstyle {subsubsection} + {} + {\leavevmode\leftskip 2.75cm\relax } + {\mdseries\normalsize\makebox[1.25cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsetstyle {paragraph} + {} + {\leavevmode\leftskip 4cm\relax } + {\mdseries\normalsize\makebox[1.5cm][l]{\etocnumber}% + \etocname\EndParWithPagenoInMarginAndLeaders} + {} +\etocsettagdepth {preamble} {none} +\etocsettagdepth {overview} {part} +\etocsettagdepth {arbitrarily}{part} +\etocsettagdepth {surprising} {part} +\etocsettagdepth {linestyles} {part} +\etocsettagdepth {globalcmds} {paragraph} +\etocsettagdepth {custom} {part} +\etocsettagdepth {tips} {part} +\etocsettagdepth {code} {none} +\renewcommand\etoctoprule {\hrule height 3pt\relax } +\renewcommand\etoctoprulecolorcmd {\color{blue}} +\renewcommand\etocaftercontentshook + {\medskip\begingroup \color{blue}\hrule height 3pt \endgroup } +\etocruledstyle [1]{\Large\bfseries \fbox{\makebox[8cm]{A TOC using depth tags}}} +\sloppy +\tableofcontents +\endgroup +\end{verbatim} + \subsection{Compatibility with other packages} +\label{etocaftertochook} -\etoc loads the package |multicol|.\footnote{\protect\fbox{up to version -\texttt{1.07a} it also used package \texttt{xspace}, but this -has been removed from later versions.}} It is +\etoc loads the package |multicol|. It is |hyperref| aware and hopefully |hyperref| compatible! It doesn't matter whether \etoc or |hyperref| is loaded first. -The contents of the |.toc| file (if it exists) are read into -memory by \etoc once, at the time of \csa{usepackage\{etoc\}}. -The |.toc| file will be opened for write operations only at -the time of the first TOC displaying command. +The contents of the |.toc| file (if it already exists) are read into memory by +\etoc once, at the time of \csa{usepackage\{etoc\}}. The |.toc| file remains +available to other packages for read operations until the location of the first +table of contents at which time a write stream is opened by \etoc and from that +point the file is erased until its contents are again written to the disk by +\LaTeX{} at the end of the compilation. \etoc can not really cohabit with packages modifying the \csa{tableofcontents} command: some sort of truce can be achieved if \etoc is loaded last, hence is @@ -4203,12 +4351,16 @@ the time of the first TOC displaying command. \centeredline{|\let\oldtableofcontents\tableofcontents|} \centeredline{|\renewcommand\tableofcontents{\oldtableofcontents\mystuff}|} as this will make the |\label/\ref| mechanism impossible. Rather you may do - \centeredline{|\renewcommand\etocaftertochook{\mystuff}|} although this - could interfere with \csb{etocsetnexttocdepth} which uses this hook; also - available: |\etocaftercontentshook| which is executed a bit earlier (but - only if the |tocdepth| was not at the ``|none|'' level), just before the + \centeredline{|\renewcommand\etocaftertochook{\mystuff}|} and there is + also \csb{etocaftercontentshook} which is executed a bit + earlier\footnotemark{} + just before + the closing part of the toc display style (and thus still within a group.) \end{framed} +\footnotetext{contrarily to \csa{etocaftertochook}, + \csa{etocaftercontentshook} is not executed if the |tocdepth| did not + allow the printing of the TOC.} \etoc used to be incompatible with package |tocvsec2|\footnote{\url{http://ctan.org/pkg/tocvsec2}}; it now cohabits, sort @@ -4286,7 +4438,7 @@ groups. All TOCs are typeset inside groups. which are activated by \csa{etocdefaultlines}). One has to make sure that all levels needed for the next table of contents are mutually compatible: in particular the \etoc - default styles expect to start in ``vertical mode''. + default line styles expect each to be started in ``vertical mode''. When using multiple \toc commands in a document, one should beware from adding typesetting instructions directly in the |.toc| file, as they will be executed @@ -4308,8 +4460,170 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \texttt{\pkgversion}, of \texttt{\pkgdate}. +\etocdepthtag.toc {code} + \part{The code} +\begingroup +\renewcommand\lowast{{\normalsize\raisebox{-.4\height}{*}}} +\small + +\section{Change history} + +\setlength{\columnsep}{\etoccolumnsep} + +\makeatletter + +\def\jfverbatim{\@beginparpenalty \predisplaypenalty + \parindent \z@ + \parfillskip \@flushglue + \parskip \tw@\p@ plus 1fil\relax + \let \do \@makeother \dospecials + \catcode`\~\z@ + \footnotesize\normalfont\baselineskip10pt\relax + \frenchspacing \obeyspaces \jf@xverbatim } + +\begingroup +\catcode `|=0 \catcode `[= 1 \catcode`]=2 +\catcode `\{=12 \catcode `\}=12 \catcode`\\=12 +|long|gdef|jf@xverbatim#1\end{jfverbatim}[#1|end[jfverbatim]] +|endgroup + +\def\endjfverbatim{} + +\newdimen\jfverbadim + +\everypar{\leftskip\jfverbadim\bgroup + \def\par{\egroup\jfverbadim\z@\@@par}% + \def\jfverbaspace#1{\ifcat\noexpand#1\noexpand~\unskip\else\ \fi#1}} + +\begingroup\obeyspaces\def\x{\endgroup% +\def {\ifvmode\advance\jfverbadim.5em\relax\else\expandafter\jfverbaspace\fi}}\x + +\makeatother + +\begin{multicols}{2} +\begin{jfverbatim} +v1.07h [2013/10/16] + + new commands \etocdepthtag.toc, \etocsettagdepth, \etocobeydepthtags, + \etocignoredepthtags. + + +v1.07g [2013/10/13] + + new commands \etocsettocdepth, \etocsettocdepth.toc, + \etocobeytoctocdepth, \etoc~-ignoretoctocdepth which + emulate part of tocvsec2 functionality ; measures to + make tocvsec2 partially compatible with etoc. + + new commands \etocsetnexttocdepth, \invisibletableofcontents, + \invisiblelocaltableofcontents. + + switched from tikz-qtree to forest for the first `toc as + tree' example. + + command names are linked to their descriptions, and many + other changes in the documentation. + + removed printing of temporary message when the local toc + id is not yet stabilized; indeed \localtableofcontents + can have many uses, such as filling up some token list + register and one may wish to not have anything typeset, + even in an intermediate run. + + all of tex etoc.dtx, etex etoc.dtx, xetex etoc.dtx, latex + etoc.dtx, pdflatex etoc.dtx are now possible, and the + extracted file etoc.tex allows easy customization of + compilation options for the documentation (default is via + dvipdfmx which produces the smallest file). + + +v1.07f [2013/03/07] + + new macros \etocthelinkedname, \etocthelinkednumber, + \etocthelinkedpage, and \etocthelink. + + +v1.07e [2013/03/01] + + improvements in the package own line styles with + regards to penalties and vertical spaces. + + addition to the documentation of an example of + a tree-like table of contents (uses tikz). + + more such examples added 2013/03/03. + +v1.07d [2013/02/24] + + minor code improvements and new documentation + section "Another compatibility mode". + + +v1.07b [2013/02/02] + + removal of the \xspace from the macros \etocname, + \etocnumber, \etocpage. + + additional examples in the documentation. + + +v1.07 [2013/01/29] + + new commands: + + \etocthename, \etocthenumber, \etocthepage, \etoclink, + + \etoctoccontentsline, \etoctoccontentsline~lowast + + \etocnopar, \etocaftercontentshook + + modified command: \etocmulticolstyle + + new documentation section "Surprising uses of etoc" which + explains how to do "Lists of arbitrary things", in + addition to the tables of contents. + + +v1.06 [2012/12/07] + + the standard macros \l@section etc... are modified only + during the calls to \tableofcontents; they can thus be + customized as will by the user (with the help of a + package like tocloft) and this will be taken into account + by etoc for the TOCs typeset in compatibility mode. + + +v1.05 [2012/12/01] + + \localtableofcontents replaces \tableofcontents~lowast (for + compatibility with the memoir class). + + compatibility with KOMA-script and memoir document + classes. + + +v1.04 [2012/11/24] + + a (possibly local) table of contents can be labeled: + + \tableofcontents \label{toc:1} + + and reproduced elsewhere in the document (with a possibly + completely different layout): + + \tableofcontents \ref{toc:1} + + +v1.02 [2012/11/18] + + initial version. + +\end{jfverbatim} +\end{multicols} +\endgroup % group for modified verbatim printing of the changes log + \makeatletter \let\check@percent\original@check@percent @@ -4424,22 +4738,22 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \@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@@ +\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 +\chardef\Etoc@@six@@ 6 \let\Etoc@localtop\Etoc@@minustwo@@ \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@@zero@ {zero} +\def\Etoc@@one@ {one} +\def\Etoc@@two@ {two} +\def\Etoc@@three@ {three} +\def\Etoc@@four@ {four} +\def\Etoc@@five@ {five} % \end{macrocode} % |1.07g| % \begin{macrocode} @@ -4458,7 +4772,7 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is % \end{macrocode} % placeholder for comments % \begin{macrocode} -\def\Etoc@levellist{} +\let\Etoc@levellist\@empty \def\Etoc@newlevel#1{% \def\Etoc@levellist@elt{\noexpand\Etoc@levellist@elt\noexpand}% \edef\Etoc@levellist{\Etoc@levellist\Etoc@levellist@elt#1}} @@ -4493,15 +4807,11 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \expandafter\let \csname Etoc@#1@@\endcsname\Etoc@@minustwo@@ \expandafter\let \csname Etoc@#1@\endcsname\Etoc@@minustwo@ \else - \ifnum#2=-\thr@@ - \expandafter\let \csname Etoc@#1@@\expandafter\endcsname - \csname Etoc@-3@@\endcsname - \else \PackageWarning{etoc} {unexpected value `#2' in \string\etocsetlevel.^^J% Should be -2,-1, 0, 1, 2, 3, 4, 5, or 6. Set to 6 (=ignored)}% \expandafter\let\csname Etoc@#1@@\endcsname\Etoc@@six@@ -\fi\fi\fi\fi} +\fi\fi\fi} \etocsetlevel{book}{-2} \etocsetlevel{part}{-1} \etocsetlevel{chapter}{0} @@ -4718,7 +5028,7 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is % \begin{macrocode} \def\Etoc@lxyz #1#2{% \@namedef {etoclink }{\leavevmode}% fall-back - \def\etocthelink {}% fall-back + \let\etocthelink \@empty % fall-back \@namedef {etocname }{\leavevmode #1}% fall-back (perhaps linked) \def\etocthename {#1}% (if link, will be removed later) \def\etocthelinkedname {#1}% will probably get redefined @@ -4784,8 +5094,8 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \Etoc@getname #3\etoc@ \else % then \etocthename and \etocthelinkedname already defined \@namedef {etocnumber }{\leavevmode}% - \def\etocthenumber {}% - \def\etocthelinkednumber {}% + \let\etocthenumber \@empty + \let\etocthelinkednumber \@empty \Etoc@numberfalse \fi } @@ -4809,8 +5119,8 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \Etoc@getname ##3\etoc@ \else \@namedef {etocnumber }{\leavevmode}% - \def\etocthenumber {}% - \def\etocthelinkednumber {}% + \let\etocthenumber \@empty + \let\etocthelinkednumber \@empty \Etoc@numberfalse \def\etocthename {#4}% \toks@ {#4}% @@ -4992,15 +5302,15 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is % sometimes one uses |\localtableofcontents| to prepare something else, and one % does not want at any output of text at all even in an intermediate run. % -% Also |1.07g| has |\etocaftertochook| to help with +% Also |1.07g| adds |\etocaftertochook| to help with % |\invisiblelocaltableofcontents| (and then I did |\etocsetnexttocdepth|). +% |1.07h| makes the hook used by |\etocsetnexttocdepth| private. % \begin{macrocode} \def\Etoc@localtableofcontents#1{% \edef\Etoc@tmp{#1}% \ifnum\Etoc@tmp<\@ne \PackageWarning{etoc} {Unknown toc id: run LaTeX to get references right}% -%%\leavevmode --unknown etoc ref: run latex again--\par (REMOVED IN 1.07g) \let\Etoc@next\@gobble\else\let\Etoc@next\@firstofone\fi \Etoc@next {\edef\etoc@startlocaltoc##1{% @@ -5011,6 +5321,7 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \global\Etoc@notactivetrue \Etoc@tableofcontents}% \endgroup\ifEtoc@mustclosegroup\endgroup\fi + \Etoc@aftertochook % 1.07h \etocaftertochook % 1.07g } % \end{macrocode} @@ -5046,6 +5357,7 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \Etoc@tableofcontents \endgroup \ifEtoc@mustclosegroup\endgroup\fi + \Etoc@aftertochook % 1.07h \etocaftertochook % 1.07g }% \fi @@ -5142,7 +5454,6 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \def\etocsepminusone {4ex \@plus .5ex \@minus .5ex} \def\etocsepzero {2.5ex \@plus .4ex \@minus .4ex} \def\etocsepone {1.5ex \@plus .3ex \@minus .3ex} -%%\newcommand*\etocseptwo{1ex \@plus .15ex \@minus .15ex} % modified in 1.07e \def\etocseptwo {.5ex \@plus .1ex \@minus .1ex} \def\etocsepthree {.25ex \@plus .05ex \@minus .05ex} % \end{macrocode} @@ -5174,6 +5485,7 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is % \csa{addvspace}, as this was not satisfactory in the earlier versions, which % were written at a early stage in the development of the % package. Actually I am not fully satisfied with these line styles. +% % \begin{macrocode} \def\etocdefaultlines{\Etoc@standardfalse % %% `book' in memoir class: @@ -5695,46 +6007,73 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is % retain the stack idea, which does not convince me as useful. The empty % line in the |.toc| file is put there by |tocvsec2| (see its code line 143). % -% I take this opportunity to add to the toc file +% I take this opportunity to add to the start of the toc file % |\let\etoc@startlocaltoc\@gobble| in case |etoc| is not detected, I should % possibly have done that long ago (like I did in |tableof|). % -% +% In |1.07h| I decide that I should not have used |\Etoc@| but |\etoc@| for +% |\Etoc@settocdepth|. So I now use lowercase and add a temporary line for +% transition in the very improbable situation that someone actually did already +% use the just released |1.07g|. +% % \begin{macrocode} +\def\Etoc@settocdepth {\etoc@settocdepth }% for 1.07g->h, to be removed later. \def\Etoc@storetocdepth {\global\c@etoc@tocdepth\c@tocdepth } \def\Etoc@resettocdepth {\global\c@tocdepth\c@etoc@tocdepth } -\def\etocobeytoctocdepth - {\def\Etoc@settocdepth {\afterassignment\Etoc@@settocdepth\global\c@tocdepth}} -\def\Etoc@@settocdepth {\ifnum\c@tocdepth>\c@etoc@tocdepth - \global\c@tocdepth\c@etoc@tocdepth\fi } -\def\etocignoretoctocdepth {\let\Etoc@settocdepth\count@ } +\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 } +\def\etocignoretoctocdepth {\let\etoc@settocdepth\count@ } \def\etocsettocdepth {\futurelet\Etoc@nexttoken\Etoc@set@tocdepth } \def\Etoc@set@tocdepth {\ifx\Etoc@nexttoken\bgroup \expandafter\Etoc@set@tocdepth@ - \else\expandafter\Etoc@set@toctocdepth@ + \else\expandafter\Etoc@set@toctocdepth \fi } \def\Etoc@set@tocdepth@ #1{\@ifundefined {Etoc@#1@@} {\PackageWarning{etoc} {Unknown sectioning unit #1, \protect\etocsettocdepth\space ignored}} {\global\c@tocdepth\csname Etoc@#1@@\endcsname}% } -\def\Etoc@set@toctocdepth@ #1#{\Etoc@set@toctocdepth@@ }% % \end{macrocode} -% |1.07g| The |\expandafter\protect\csname | is because of |@@minustwo@@| which -% we don't -% want to expand to |-\tw@|, because we want alphabetical levels to remain so; -% and all others are non-expandable. I could have used a |\mathchardef| for -% |@@minustwo@@|. +% |1.07g| |\etocsettocdepth.toc|: the |\expandafter\protect\csname | is because +% of |@@minustwo@@| which we don't ant to expand to |-\tw@|, because we want +% alphabetical levels to not be converted immediately to numeric levels. % \begin{macrocode} -\def\Etoc@set@toctocdepth@@ #1{% - \@ifundefined{Etoc@#1@@} +\def\Etoc@set@toctocdepth #1#{\Etoc@set@toctocdepth@ } +\def\Etoc@set@toctocdepth@ #1{% + \@ifundefined{Etoc@#1@@}% {\PackageWarning{etoc} - {Unknown sectioning unit #1, \protect\etocsettocdepth.toc ignored}} + {Unknown sectioning depth #1, \protect\etocsettocdepth.toc ignored}}% {\addtocontents {toc} - {\protect\Etoc@settocdepth\expandafter\protect\csname Etoc@#1@@\endcsname}}% + {\protect\etoc@settocdepth\expandafter\protect\csname Etoc@#1@@\endcsname}}% } % \end{macrocode} -% placeholder for comments. +% |1.07h| adds the depth tags, and an even more general mechanism could be added +% at some point: we could insert `action' tags and have the user map them to +% arbitrary commands. For the time being we just provide +% |\etocdepthtag.toc {name}| and |\etocsettagdepth {tag_name}{level}| where +% level is numeric or +% alphabetical. The numeric +% level |-3| is now again not accepted by |\etocsetlevel|, it can be used with +% |\etocsettagdepth| (which accepts equivalently |none|). +% \begin{macrocode} +\def\etocdepthtag #1#{\Etoc@depthtag } % \etocdepthtag.toc {name} +\def\Etoc@depthtag #1{\addtocontents {toc}{\protect\etoc@depthtag {#1}}} +\def\etocignoredepthtags {\let\etoc@depthtag \@gobble } +\def\etocobeydepthtags {\let\etoc@depthtag \Etoc@depthtag@ } +\def\Etoc@depthtag@ #1{\@ifundefined{Etoc@depthof@#1}% + {}% ignore in silence if tag has no associated depth + {\afterassignment\Etoc@@nottoodeep + \global\c@tocdepth\csname Etoc@depthof@#1\endcsname}% +} +\def\etocsettagdepth #1#2{\@ifundefined{Etoc@#2@@}% + {\PackageWarning{etoc} + {Unknown sectioning depth #2, \protect\etocsettagdepth\space ignored}}% + {\@namedef{Etoc@depthof@#1}{\@nameuse{Etoc@#2@@}}}% +} +% \end{macrocode} +% We must cancel all |tocvsec2| toc-related actions. % \begin{macrocode} \def\Etoc@tocvsec@err #1{\PackageError {etoc} {the command \protect#1\space is incompatible with etoc} @@ -5757,9 +6096,6 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \protect\etocsettocdepth.toc as a replacement^^J for the tocvsec2 toc-related commands}}{}% }% -\addtocontents {toc}{\protect\@ifundefined{etocsetstyle}% - {\let\protect\Etoc@settocdepth\count@ - \let\protect\etoc@startlocaltoc\protect\@gobble }{}}% % \end{macrocode} % |1.07g| % \begin{macrocode} @@ -5770,11 +6106,18 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \@ifundefined{Etoc@#1@@} {\PackageWarning{etoc} {Unknown sectioning unit #1, \protect\etocsetnextocdepth\space ignored}} - {\edef\etocaftertochook {\global\c@tocdepth\the\c@tocdepth\space - \let\noexpand\etocaftertochook\noexpand\@empty }% + {\edef\Etoc@aftertochook {\global\c@tocdepth\the\c@tocdepth\space + \let\noexpand\Etoc@aftertochook\noexpand\@empty }% \global\c@tocdepth\csname Etoc@#1@@\endcsname}% }% % \end{macrocode} +% In order for the |.toc| file to be usable without error even without etoc. +% \begin{macrocode} +\addtocontents {toc}{\protect\@ifundefined{etoctocstyle}% + {\let\protect\etoc@startlocaltoc\protect\@gobble + \let\protect\etoc@settocdepth\count@ + \let\protect\etoc@depthtag\protect\@gobble }{}}% +% \end{macrocode} % Initializations. % \begin{macrocode} \def\etocstandardlines {\Etoc@standardtrue} @@ -5783,7 +6126,9 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is \etocstandardlines \etocstandarddisplaystyle \etocobeytoctocdepth -\let\etocaftertochook\@empty +\etocobeydepthtags +\let\Etoc@aftertochook\@empty % private for \etocsetnexttocdepth +\let\etocaftertochook \@empty % public for end user. \endinput % \end{macrocode} % \MakePercentComment @@ -5803,7 +6148,7 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is Grave accent \` Left brace \{ Vertical bar \| Right brace \} Tilde \~} -\CheckSum{2861} +\CheckSum{2902} \csname check@checksum\endcsname \Finale diff --git a/Master/texmf-dist/source/latex/etoc/etoc.ins b/Master/texmf-dist/source/latex/etoc/etoc.ins index 6f3018e1d79..0c88a2cd2c5 100644 --- a/Master/texmf-dist/source/latex/etoc/etoc.ins +++ b/Master/texmf-dist/source/latex/etoc/etoc.ins @@ -1,9 +1,9 @@ -\def\pkgname {etoc} \def\pkgdate {2013/10/13} \def\pkgversion {v1.07g} +\def\pkgname {etoc} \def\pkgdate {2013/10/16} \def\pkgversion {v1.07h} \def\pkgdescription {Completely customisable TOCs (jfB)} -\def\doctimestamp {Time-stamp <13-10-2013 23:44:43 CEST *>} +\def\doctimestamp {Time-stamp <16-10-2013 22:11:00 CEST *>} %% %% Package: etoc -%% Version: 2013/10/13 v1.07g +%% Version: 2013/10/16 v1.07h %% Copyright (C) 2012-2013 by Jean-Francois Burnol <jfbu at free dot fr> %% %% Run tex on this file to extract etoc.sty and etoc.tex from etoc.dtx |