summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/etoc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-11-23 22:45:17 +0000
committerKarl Berry <karl@freefriends.org>2012-11-23 22:45:17 +0000
commit1bcc012dc9ee137c9349ef3925bd98c933567a33 (patch)
tree7c6fb69d4813259ee3e6045d200d38559f1419f9 /Master/texmf-dist/source/latex/etoc
parent53ef995986cf28c61e47d976d1a2b681ef9e1d7b (diff)
etoc (23nov12)
git-svn-id: svn://tug.org/texlive/trunk@28343 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/etoc')
-rw-r--r--Master/texmf-dist/source/latex/etoc/etoc.dtx2874
-rw-r--r--Master/texmf-dist/source/latex/etoc/etoc.ins43
2 files changed, 1841 insertions, 1076 deletions
diff --git a/Master/texmf-dist/source/latex/etoc/etoc.dtx b/Master/texmf-dist/source/latex/etoc/etoc.dtx
index 3a4ee52d1b5..c2484aa3c1c 100644
--- a/Master/texmf-dist/source/latex/etoc/etoc.dtx
+++ b/Master/texmf-dist/source/latex/etoc/etoc.dtx
@@ -1,124 +1,107 @@
-% ^^A -*- coding: iso-latin-1; -*-
-% \iffalse meta-comment
+% -*- coding: iso-latin-1; -*-
+%% Package `etoc' by Jean-Francois Burnol
+%% Copyright (C) 2012 by Jean-Francois Burnol
+%<*ins>
+\def\pkgname{etoc}
+\def\pkgdate{2012/11/23}
+\def\pkgversion{v1.03}
+\def\pkgdescription{easily customizable TOCs (jfB)}
+%</ins>
+%<*none>
+\def\lasttimestamp{Time-stamp: <23-11-2012 12:02:17 CET jfb>}
+\def\docdate{2012/11/23}
+\def\striptimestamp#1 <#2 #3 #4 #5>{#2 at #3 #4}
+\edef\dtxtimestamp{\expandafter\striptimestamp\lasttimestamp}
+\ProvidesFile{\pkgname.dtx}
+ [`\pkgname' source and documentation (\dtxtimestamp)]
+%
+% The copyright statement at the top of this file applies to `etoc.dtx'
+% and to its derived files.
%
-% This file may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either
-% version 1.2 of this license or (at your option) any later
-% version. The latest version of this license is in:
+% They may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License,
+% either version 1.3 of this license or (at your
+% option) any later version. The latest version of
+% this license is in:
%
-% http://www.latex-project.org/lppl.txt
+% http://www.latex-project.org/lppl.txt
%
-% and version 1.2 or later is part of all distributions of
-% LaTeX version 1999/12/01 or later.
+% and version 1.3 or later is part of all distributions of
+% LaTeX version 2003/12/01 or later.
%
-%% Copyright (C) 2012 by Jean-Francois Burnol
-%
-% Time-stamp: <18-11-2012 19:35:19 CET jfb>
+% Installation:
+% ============
%
-% Installation
+% `latex etoc.dtx'
+% `latex etoc.dtx' (again) finishes producing the documentation
%
-% `latex etoc.dtx' creates (among others) the file `etoc.sty'.
-% `latex etoc.dtx' (again) finishes producing the documentation.
+% The file `etoc.sty' was generated in the first latex run.
%
% Put `etoc.sty' in a suitable location within the TeX installation:
-% etoc.sty -> ..suitable..path..to../tex/latex/etoc/
+% etoc.sty -> ..path..to../tex/latex/etoc/
%
-% The other generated files may be discarded.
+% The generated auxiliary files may be discarded.
%
-% \fi
-%
-% \CheckSum{1873}
-%
-% \CharacterTable
-% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
-% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
-% Digits \0\1\2\3\4\5\6\7\8\9
-% Exclamation \! Double quote \" Hash (number) \#
-% Dollar \$ Percent \% Ampersand \&
-% Acute accent \' Left paren \( Right paren \)
-% Asterisk \* Plus \+ Comma \,
-% Minus \- Point \. Solidus \/
-% Colon \: Semicolon \; Less than \<
-% Equals \= Greater than \> Question mark \?
-% Commercial at \@ Left bracket \[ Backslash \\
-% Right bracket \] Circumflex \^ Underscore \_
-% Grave accent \` Left brace \{ Vertical bar \|
-% Right brace \} Tilde \~}
-%
-%
-% \iffalse
-%
-%<*driver>
-\def\pkgdate{2012/11/18}%
-\def\pkgversion{v1.02}%
-%</driver>
-%
-%<*batchfile>
-\begin{filecontents*}{etoc.ins}
-%% Package `etoc' by Jean-Francois Burnol
-%%
-%% This file `etoc.ins' is provided for compatibility reasons with
-%% TeX installations expecting to find an .ins file
-%%
-%% It can be used as usual:
-%%
-%% `latex etoc.ins' extracts `etoc.sty' from `etoc.dtx'
-%%
-%% But doing directly `latex etoc.dtx' already creates `etoc.sty'
+\begingroup
+\input docstrip.tex
+\askforoverwritefalse
+\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
+\string\ProvidesPackage{\pkgname}^^J%
+\space[\pkgdate\space\pkgversion\space\pkgdescription]}
+\generate{\nopreamble
+\file{\pkgname.ins}{\from{\pkgname.dtx}{ins}}
+\usepreamble\pkgpreamble
+\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}
+\endgroup
+\iffalse
+%</none>
+%<*ins>
+%-------------------------------------------------------------------------------
%%
-%% `latex etoc.dtx' generates `etoc.sty' (and also `etoc.ins')
-%% `latex etoc.dtx' finishes generating the documentation
+%% This file `etoc.ins' is provided for compatibility with TeX distributions
+%% expecting to find it for installation of `etoc.sty'.
%%
-%% In all cases, put the generated `etoc.sty' file in a suitable
-%% location within the TeX installation:
-%% etoc.sty -> ................/tex/latex/etoc/
+%% As usual `latex etoc.ins' produces `etoc.sty' from the source `etoc.dtx'
+%% (an already existing etoc.sty in the same repertory will be overwritten)
+%%
+%% Put the `etoc.sty' file in a suitable location within the TeX installation:
+%% etoc.sty -> ................/tex/latex/etoc/
%%
-%% Generated auxiliary files may then be discarded.
+%% The generated auxiliary files may be discarded. See `etoc.dtx' for the
+%% statements of copyright and conditions of distribution or modification.
%%
-\def\batchfile{etoc.ins}
\input docstrip.tex
\askforoverwritefalse
-\def\jfpreamble{\defaultpreamble^^J\MetaPrefix^^J%
-\string\ProvidesPackage{etoc}^^J%
-\space[2012/11/18\space v1.02\space easily customizable TOCs (jfB)]}
-\def\jfpostamble{\MetaPrefix\space End of file `\outFileName'.}
-\generate{\usepreamble\jfpreamble
-\file{etoc.sty}{\from{etoc.dtx}{package}}
-\usepostamble\jfpostamble}
+\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
+\string\ProvidesPackage{\pkgname}^^J%
+\space[\pkgdate\space\pkgversion\space\pkgdescription]}
+\generate{\usepreamble\pkgpreamble
+\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}
\endbatchfile
-\end{filecontents*}
-\begingroup
-\input docstrip.tex
-\askforoverwritefalse
-\def\jfpreamble{\defaultpreamble^^J\MetaPrefix^^J%
-\string\ProvidesPackage{etoc}^^J%
-\space[\pkgdate\space\pkgversion\space easily customizable TOCs (jfB)]}
-\def\jfpostamble{\MetaPrefix\space End of file `\outFileName'.}
-\generate{\usepreamble\jfpreamble
-\file{etoc.sty}{\from{etoc.dtx}{package}}
-\usepostamble\jfpostamble}
-\endgroup
-%</batchfile>
-%
-%<*driver>
-\ProvidesFile{etoc.dtx}[\pkgdate\space\pkgversion\space
- etoc source and documentation (jfB)]
+%-------------------------------------------------------------------------------
+%</ins>
+%<*none>
+\fi
\documentclass[a4paper,12pt]{ltxdoc}
-%\OnlyDescription
+
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[hscale=0.66,vscale=0.75]{geometry}
+\usepackage{verbatim}
\usepackage{txfonts}
+
\usepackage{xspace}
\usepackage{multicol}
+
\usepackage{enumitem}
-\usepackage{color}
+
+\usepackage{xcolor}
\definecolor{joli}{RGB}{225,95,0}
\renewcommand\partname{Part}
-\usepackage[%dvipdfmx,%
-pdfencoding=pdfdoc,%
-bookmarks=true,%
-]{hyperref}
+
+\usepackage[%dvipdfmx,%
+pdfencoding=pdfdoc,bookmarks=true]{hyperref}
+
\hypersetup{%
linktoc=all,%
breaklinks=true,%
@@ -129,853 +112,1444 @@ pdfsubject={LaTeX, table of contents},%
pdfkeywords={LaTeX, table of contents},%
pdfstartview=FitH,%
pdfpagemode=UseOutlines}
+
+% \makeatletter % for use when \usepackage{hyperref} is commented out
+% \let\texorpdfstring\@firstoftwo
+% \def\hyperref[#1]#2{{#2}}
+% \def\href#1#2{{#2}}
+% \makeatother
+
\usepackage{etoc}
\newcommand\etoc{%
\texorpdfstring{{\color{joli}\ttfamily\bfseries etoc}\xspace}
{\textbackslash etoc\xspace}}
-\renewcommand\cs[1]{\texorpdfstring{\csi{#1}}{\textbackslash #1}}
-\newcommand\csb[1]{\texorpdfstring{\csbi{#1}}{\textbackslash #1}}
+
\newcommand\csi[1]{{\ttfamily\hyphenchar\font45\char92#1}}
\newcommand\csbi[1]{{\color{blue}\ttfamily\hyphenchar\font45\char92#1}}
-\renewcommand\star{{\ttfamily \raisebox{-.25\height}{*}}}
-\newcommand\starit[1]{\csi{#1}\star}
-\newcommand\staritb[1]{{\color{blue}\csi{#1}\star}}
+\newcommand\csa[1]{\texorpdfstring{\csi{#1}}{\textbackslash #1}}
+\newcommand\csb[1]{\texorpdfstring{\csbi{#1}}{\textbackslash #1}}
+\newcommand\lowast{{\ttfamily \raisebox{-.25\height}{*}}}
+\newcommand\starit[1]{\csi{#1}\lowast}
+\newcommand\staritb[1]{{\color{blue}\csi{#1}\lowast}}
+\newcommand\toc{\csa{tableofcontents}\xspace}
+\newcommand\tocb{\csb{tableofcontents}\xspace}
\newcommand\tocstar{\starit{tableofcontents}\xspace}
\newcommand\tocstarb{\staritb{tableofcontents}\xspace}
+
\hyphenation{sec-num-depth toc-num-depth etoc-set-style etoc-set-level
etoc-set-toc-style etoc-if-num-bered etoc-name etoc-page etoc-number
etoc-framed-style etoc-multi-col-style etoc-ruled-style
-etoc-skip-first-pre-fix}
+etoc-skip-first-pre-fix etoc-ref}
+
\frenchspacing
+
\renewcommand\familydefault\sfdefault
+
\begin{document}
-\DocInput{etoc.dtx}
-\end{document}
-%</driver>
-%
-% \fi
-% \rmfamily
-% \begin{center}
-% {\normalfont\Large The \etoc package}\\
-% \textsc{Jean-François Burnol}\par
-% \small \ttfamily
-% jfbu (at) free (dot) fr\\
-% Package version: \pkgversion\ (\pkgdate).
-% \end{center}
-% \vskip1cm
-% \begin{abstract}
-% The \etoc package gives the user complete control on
-% how the entries of the table of contents should be
-% constituted from the \emph{name}, \emph{number}, and
-% \emph{page number} of each sectioning unit. This goes via
-% the definition of \emph{line styles} for each sectioning
-% level used in the document. The package provides its own
-% custom line styles as an example, next to the standard
-% formatting inherited from the \LaTeX{} document classes. But
-% the idea is to give the means to the user to delegate the
-% details to packages dealing with list making environments
-% (such as |enumitem|). Regarding the \emph{global style},
-% \etoc typesets by default tables of contents in a
-% multi-column format, with either a standard heading, or a
-% ruled title, optionally with a frame around the table of
-% contents. The \cs{tableofcontents} command can be used
-% arbitrarily many times in the same document, and comes with
-% a starred variant which gives local table of contents.
-% \end{abstract}
-%
-% \vskip1cm
-% \tableofcontents
-%
-% \part{Although this is a short document, we are going to use many sectioning commands}
-%
-% \section{Overview}
-%
-% Popular packages dealing with TOCs include |tocloft|,
-% |titletoc| and |minitoc|. Why another one? well, I started
-% \etoc for my own use, and only later found out about the above
-% mentioned packages . . . I realize (to some extent, as I still
-% haven't read closely the documentations) that most if not all
-% of the \etoc functionality could well be already available in
-% the above mentioned packages.
-%
-% \subsection{Initial motivation}
-%
-% The specific initial impetus was to transform the `flat' data
-% contained in the |.toc| file into a nested structure which
-% could be given to list making environments. For example,
-% typesetting the line corresponding to the first sub-section in
-% a given section would open a group which would be closed only
-% when a section, chapter, or part line entry in the |.toc| file
-% would be encountered. Package \etoc allows to do this very
-% easily and the opening and closing of the groups can for
-% example be |\begin{enumerate}| and |\end{enumerate}| pairs,
-% will all the customizing allowed by packages such as
-% |enumitem|. Although there is a limitation to this method (the
-% |.toc| file may contain other commands, such as language
-% changing commands, which do not expect to see their scope
-% limited in this way inside a group), I believe this procedure
-% will be found the most convenient in many cases. However the
-% own package custom line styles (illustrated by the main table
-% of contents in this document) do not make use of environments
-% to avoid that problem.
-%
-% \subsection{Line styles}
-%
-% To implement the above idea, the command \csb{etocsetstyle}
-% will inform \etoc of what it should do at each sectioning
-% level, from |part| downto |subparagraph|. Other sectioning
-% names can be used too, if present in the document.
-%
-% \subsubsection{\csb{etocetoclines} vs \csb{etocstandardlines}}
-%
-% The \csb{etocetoclines} command selects the package predefined
-% line styles, and \csb{etocstandardlines} uses the standard
-% default formatting from the |article|, |book|, |report|, or
-% also |scrartcl| classes. For any document class proceeding (as
-% does |scrartcl|) in a manner analogous as does the |article|
-% class in its typesetting of the table of contents, the
-% \csb{etocstandardlines} should be functional: indeed nothing
-% is hard-coded into the package code; rather, when
-% \csb{etocstandardlines} is issued by the user, the package
-% cancels its own mechanism and gives back the leadership to the
-% class layer. Note though that this means that \etoc does not
-% provide utilities to change this or that length from the
-% \LaTeX{} default formatting of TOC entries. But if some other
-% package has done it, then this should work correctly also when
-% \etoc is in use (for its other aspects described below).
-%
-% \subsubsection{Instructing \etoc about sectioning command names}
-%
-% If the document class uses other names, such as \emph{atom},
-% or \emph{particle}, then the command \csb{etocsetlevel} is
-% provided to instruct \etoc about it.
-%
-% \subsection{Global style: multiple columns, ruled heading, framed TOC}
-%
-% At the global level, the default of \etoc is to typeset the
-% TOC on two columns, using the package |multicol|.
-% Additionally, the heading can be formatted as in the default
-% manner, or as a ruled heading, or the entire TOC can be
-% encapsulated in a frame (if it fits on the current page). And
-% the user can specify to use a single column output, or three
-% columns, etc . . .
-%
-% \subsection{Local table of contents}
-%
-% With \etoc, the \csb{tableofcontents} command can be used
-% arbitrarily many times and it has a starred variant \tocstarb
-% which prints a local table of contents (i.e. all subsections
-% etc . . . inside a given section, or all subsubsections and
-% lower inside a given subsection, etc . . . ).
-%
-% \part{Package commands for line styles}
-%
-% \etocsetstyle{section}
-% {\begin{enumerate}[leftmargin=0pt,label=]}
-% {\normalsize\bfseries\rmfamily\item}
-% {\etocifnumbered{\makebox[1cm][c]{\color{green}\fboxrule1pt
-% \fbox{\protect\normalcolor\etocnumber}}}{\hspace{1cm}}%
-% \etocname (page \etocpage)}
-% {\end{enumerate}}
-%
-% \etocsetstyle{subsection}
-% {\begin{enumerate}[label=\etocnumber, leftmargin=1cm]}
-% {\normalfont \item}
-% {\etocname (p.~\etocpage)}
-% {\end{enumerate}}
-%
-% \etocsetstyle{subsubsection}
-% {\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix}
-% {\allowbreak\,--\,}
-% {\etocname}
-% {\unskip.\hfil\par\endgroup\pagebreak[3]}
-%
-% \etocruledstyle[1]{\etocfontminusone\color{green}%
-% \fboxrule1pt\fboxsep1ex%
-% \framebox[\linewidth]
-% {\normalcolor\hfil Contents of this second part\hfil}}
-%
-% \tableofcontents*
-%
-% \section{The \csb{etocsetstyle} command}
-%
-% \subsection{An example}
-%
-% Let us explain how \etoc was used to produce the (local) table
-% of contents of this second part. We distinguish between the
-% \emph{line styles}, and the \emph{global style}. The global
-% style here is on one column, and has a heading of a certain
-% sort, but first we describe the line styles. Essentially they
-% were obtained via the following set-up:^^A
-% \footnote{the present document has
-% {\ttfamily\string\renewcommand\string{^^A
-% \string\familydefault\string}\string{\string\sfdefault\string}}
-% in its preamble, hence \cs{normalfont} switches to the
-% |sans| typeface; so in the section line-style, I wrote
-% \cs{rmfamily} instead.} \footnote{\etoc uses the |xspace|
-% package, and there is no need to write
-% \cs{etocname\string{\string} text} rather than just
-% \cs{etocname text} for example. However, this forced us to
-% add the mysterious \cs{unskip} before the dot in the
-% subsubsection style.}
-% \begin{verbatim}
-% \etocsetstyle{section}
-% {\begin{enumerate}}
-% {\normalsize\bfseries\rmfamily\item}
-% {\etocname (page \etocpage)}
-% {\end{enumerate}}
-%
-% \etocsetstyle{subsection}
-% {\begin{enumerate}}
-% {\normalfont\item}
-% {\etocname (p.~\etocpage)}
-% {\end{enumerate}}
-%
-% \etocsetstyle{subsubsection}
-% {\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix}
-% {\allowbreak\,--\,}
-% {\etocname}
-% {\unskip.\hfil\par\endgroup\pagebreak[3]}
-% \end{verbatim}
-% Each \csb{etocsetstyle} command has five mandatory arguments:\\
-% \hbox to \linewidth
-% {\hfil\cs{etocsetstyle}\color{blue}\marg{levelname}^^A
-% \marg{start}\marg{prefix}\marg{contents}\marg{finish}\hfil}
-% The initially recognized \marg{levelname}'s are the sectioning
-% levels of the standard document classes (from \emph{part}
-% downto \emph{subparagraph}).
-%
-% The \marg{start} code is executed when a toc entry of that level is
-% encountered and the previous one was at a higher level. The
-% \marg{finish} code is executed when one again encounters a higher
-% level toc entry. In the mean-time all entries for that level are
-% typeset by executing first the \marg{prefix} code and then the
-% \marg{contents} code.
-%
-% \subsubsection{\csb{etocname} and \csb{etocpage}}
-%
-% The line styles specifications use the commands \csb{etocname}
-% and \csb{etocpage} to get the name, respectively the page
-% number for each entry. The numbering here would be the one
-% generated by the |enumerate| environment, we will shortly
-% explain how we got the actual numbering from the data in the
-% |.toc| file.
-%
-%
-% \subsubsection{The \csb{etocskipfirstprefix} command}
-%
-% The |subsubsection| code specifies to list the names of the
-% subsubsections from a given subsection in an inline manner,
-% with -- as a separator. The command \csb{etocskipfirstprefix},
-% which, if present, \emph{must} be the very last one in the
-% \emph{start} code, instructs to not use that separator of the
-% first item. With this style, one has to be imaginative to
-% design something then for paragraph and subparagraph entries!
-% perhaps as superscripts? Well, usually one does not need
-% paragraphs and subparagraphs numbered and listed in the TOC,
-% so our putative user here chose a design where no provision is
-% made for them and added the definitive:
-% \begin{verbatim}
-% \etocsetstyle{paragraph}{}{}{}{}
-% \etocsetstyle{subparagraph}{}{}{}{}
-% \end{verbatim}
-% This is also the situation with the default line styles from the package!
-%
-% \subsubsection{secnumdepth and tocdepth}
-%
-% Alternatively, the \LaTeX{} counters |secnumdepth| (which
-% decides down to which levels things are numbered and
-% automatically written to the |.toc| file) or |tocdepth| (which
-% decides the finest level displayed in the table of contents)
-% could be used, as they are obeyed by \etoc.
-%
-%
-% \subsection{The \csb{etocsetlevel} command}
-%
-% If your document uses other sectioning names, such as, for
-% example \emph{molecule}, or \emph{atom}, one informs \etoc of
-% this via:
-% \begin{verbatim}
-% \etocsetlevel{cell}{0}
-% \etocsetlevel{molecule}{1}
-% \etocsetlevel{atom}{2}
-% \etocsetlevel{nucleus}{3}
-% \end{verbatim}
-% The accepted numbers range from -1 to 5 inclusive. The package code
-% does:
-% \begin{verbatim}
-% \etocsetlevel{part}{-1}
-% \etocsetlevel{chapter}{0}
-% \etocsetlevel{section}{1}
-% \etocsetlevel{subsection}{2}
-% \etocsetlevel{subsubsection}{3}
-% \etocsetlevel{paragraph}{4}
-% \etocsetlevel{subparagraph}{5}
-% \end{verbatim}
-%
-% \subsection{Further informations and let's make this a very long title to see how it will look like}
-%
-%
-% \subsubsection{The \csb{etocnumber} command}
-% So far, our specifications would use the numbering generated
-% by the |enumerate| environments, but it would be nicer to use
-% the actual numbers as found in the |.toc| file. This is
-% available via the \csb{etocnumber} command. To get the labels
-% in the |enumerate| list to use it we can proceed with the
-% syntax {\ttfamily label=\char32} from the package |enumitem|:
-% \begin{verbatim}
-% \etocsetstyle{section}
-% {\begin{enumerate}[label=\etocnumber]}
-% {\normalsize\bfseries\rmfamily\item}
-% {\etocname (page \etocpage)}
-% {\end{enumerate}}
-% \end{verbatim}
-% Rather than just\cs{etocnumber} we then used something like
-% |\fbox{\etocnumber}|.
-%
-%
-% \subsubsection{The \csb{etocifnumbered} switch}
-%
-% The \cs{fbox} would give an unaesthetic result in the case of an unnumbered
-% section (which ended up in the table of contents via an \cs{addcontentsline}
-% command). The \cs{etocifnumbered}\marg{A}\marg{B} command executes \meta{A} if
-% the number exists, and \meta{B} if not. So our final code could be:
-% \begin{verbatim}
-% \etocsetstyle{section}
-% {\begin{enumerate}[label=\etocifnumbered{\etocnumber}{}]}
-% {\normalsize\bfseries\rmfamily\item}
-% {\etocname (page \etocpage)}
-% {\end{enumerate}}
-% \end{verbatim}
-% \vskip-.5cm
-% We used, actually:
-% \begin{verbatim}
-% \etocsetstyle{section}
-% {\begin{enumerate}[leftmargin=0pt,label=]}
-% {\normalsize\bfseries\rmfamily\item}
-% {\etocifnumbered{\makebox[1cm][c]{\color{green}\fboxrule1pt
-% \fbox{\protect\normalcolor\etocnumber}}{\hspace{1cm}}%
-% \etocname (page \etocpage)}
-% {\end{enumerate}}
-%
-% \etocsetstyle{subsection}
-% {\begin{enumerate}[label=\etocnumber, leftmargin=1cm]}
-% {\normalfont \item}
-% {\etocname (p.~\etocpage)}
-% {\end{enumerate}}
-% \end{verbatim}
-%
-% If we had changed only the |section| level, and not the
-% |subsection| level, an error on compilation would have occurred
-% because the package style for subsections expects to start `in
-% vertical mode'. An additional \cs{par} token in the
-% \meta{contents} part of the |section| level would have fixed
-% this: |{...(page \etocpage)\par}|.
-%
-%
-% \color{red}
-% \addtocontents{toc}{\string\color{red}}
-%
-% \subsubsection{This is a red subsubsection for illustrative purposes}
-%
-% Just before this subsubsection we inserted in the |.tex| file:
-% \begin{verbatim}
-% \color{red}
-% \addtocontents{toc}{\string\color{red}}
-% \end{verbatim}
-% This entire subsubsection and its title is printed in red, as
-% well as the title of the next section (we cancel the color
-% change only after it). But what about its entry in the table
-% of contents? well it is red in the main table of contents at
-% the beginning of this document, which uses the package line
-% styles, and it is not red in the table of contents at the
-% beginning of this second document part. The reason is that the
-% \meta{finish} code for the subsubsection level closed a group,
-% whereas the \meta{start} and \meta{finish} code of the package
-% line styles do not contain group opening and closing
-% instructions. So here the group was closed while reading the
-% |.toc| file and this explains why the next entry in the local
-% TOC was not typeset in red.
-%
-% In the present case the group at the subsubsection level is
-% there to confine the font changes, but this could be made
-% superfluous via adding a \cs{normalsize} to the
-% |subsection| specification. I take this opportunity to mention
-% that \etoc always typesets the entire table of contents inside
-% a group, hence no font change therein can propagate to the outside.
-%
-%
-% \section{Am I also in red?}
-%
-% \begin{verbatim}
-% \normalcolor
-% \addtocontents{toc}{\string\normalcolor}
-% \end{verbatim}
-%
-% \normalcolor
-% \addtocontents{toc}{\string\normalcolor}
-%
-% Back to black. Note that this scope problem arises in real
-% life in a multi-lingual document, as the |babel| package
-% writes to the |.toc| file the language changes occurring in
-% the document. There is no easy general solution\footnote{one
-% can insert by hand the language changes in each concerned
-% sectioning command.} to this problem, which probably will
-% concern only a minority of cases. Again, the line styles
-% defined by \etoc do not use groups.
-%
-% \section*{An unnumbered section}
-% \addcontentsline{toc}{section}{An unnumbered section}
-%
-% I don't have much to say here. I just added an unnumbered
-% section, and made it appear in the |.toc| file.
-%
-% \begin{verbatim}
-% \section*{An unnumbered section}
-% \addcontentsline{toc}{section}{An unnumbered section}
-% \end{verbatim}
-%
-% \part{Package commands for global styles}
-%
-% We compare here various line styles: the standard formatting
-% provided by the document class, the package line styles, and
-% the custom line styles we defined above which use enumerate
-% environments. We added some paragraphs, which are not taken
-% into account by the \etoc style, nor by our enumerate styles.
-%
-% \begin{verbatim}
-% \setcounter{secnumdepth}{4}
-% \setcounter{tocdepth}{4}
-% \end{verbatim}
-%
-% \setcounter{secnumdepth}{4}
-% \setcounter{tocdepth}{4}
-%
-% \etocruledstyle[2]{\normalfont\normalsize\rmfamily\itshape
-% \fbox{\parbox{.8\linewidth}{This is the
-% table of contents defined with enumerate environments for the part,
-% section and subsection levels, and an inline italic style for
-% subsubsections.}}}
-%
-% First let us use again our set-up from the previous part. We add to it
-% \begin{verbatim}
-% \etocsetstyle{part}
-% {\begin{enumerate}[label=\etocnumber,leftmargin=1em]}
-% {\etocfontminusone\item}
-% {\etocname}
-% {\end{enumerate}}
-% \end{verbatim}
-%
-% \etocsetstyle{part}
-% {\begin{enumerate}[label=\etocnumber,leftmargin=1em]}
-% {\etocfontminusone\item}
-% {\etocname}
-% {\end{enumerate}}
-%
-% \tableofcontents
-%
-% Then we switch to the standard formatting of entries, as
-% provided by the document class, but here on two columns:
-% \begin{verbatim}
-% \etocstandardlines
-% \tableofcontents
-% \end{verbatim}
-% (let's clear the present page) \clearpage
-% \etocstandardlines
-% \etocruledstyle[2]{\renewcommand{\etoctoprule}{\hrule height0pt}^^A
-% \normalfont\normalsize\rmfamily\itshape
-% \parbox{.8\linewidth}{\centering
-% This is the table of contents with standard
-% entries (on 2 columns!)}}
-%
-% \tableofcontents
-%
-% Finally we use the package line styles, but restrict the table
-% of contents to this third part, and as it is short we opted
-% for a frame around it.
-% \begin{verbatim}
-% \etocetoclines
-% \tableofcontents*
-% \end{verbatim}
-% How the frame and title were set up will be described later. Also,
-% we reduced the package default left and right inner margins from 2em to 2ex.
-%
-% \etocframedstyle{\normalfont\normalsize\rmfamily\itshape
-% \fbox{\parbox{.8\linewidth}{\centering This is the table of
-% contents \`a la \etoc, but just for this part. As it is
-% put in a frame, it has to be small enough to fit on one
-% page.}}} \etocetoclines
-%
-% \begingroup \renewcommand{\etocinnerleftsep}{2ex}
-% \renewcommand{\etocinnerrightsep}{2ex}
-% \tableofcontents*
-% \endgroup
-%
-% \section{Specifying the global style}
-%
-% The \emph{global} style says whether the TOC appears with
-% multiple columns or just one, whether the title is typeset as
-% in the |article| or |book| class, or should be centered above
-% the entries, with rules on its sides, or if the entire TOC
-% should be put in a frame. For example, to opt for a ruled
-% heading and single column layout, one issues commands of the
-% following type:
-% \begin{verbatim}
-% \etocruledstyle[1]{\etocfontminusone This is the table of contents}
-% \tableofcontents or \tableofcontents*
-% \end{verbatim}
-%
-% \subsection{The \csb{etocfontxxx...} commands}
-%
-% The \cs{etocfontminusone} gives the font specification for the
-% top (i.e. part) level. The package predefines:
-% \begin{verbatim}
-% \newcommand\etocfontminusone{\normalfont \large \bfseries}
-% \newcommand\etocfontzero{\normalfont \normalsize \bfseries}
-% \newcommand\etocfontone{\normalfont \normalsize \bfseries}
-% \newcommand\etocfonttwo{\normalfont \normalsize}
-% \newcommand\etocfontthree{\normalfont \footnotesize}
-% \newcommand\etocfontfour{\normalfont \footnotesize}
-% \newcommand\etocfontfive{\normalfont \footnotesize}
-% \end{verbatim}
-% This has no impact under the \cs{etocstandardlines} regime.
-% And, let us recall, levels four (paragraph) and five
-% (subparagraphs) are not displayed in TOCs by the package
-% default line styles.
-%
-%
-% \subsection{The command \csb{etocruledstyle}}
-%
-% The general format of \cs{etocruledstyle} is:\\
-% \centerline{\color{blue}\cs{etocruledstyle}^^A
-% \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 can be put in a \cs{parbox} of a given width. We did this and even
-% enclosed the parboxes in \cs{fbox}es to get frames around them. For the example
-% with the standard formatting we did not use an \cs{fbox} and got rid of the
-% horizontal rules via:
-% \begin{verbatim}
-% \renewcommand{\etoctoprule}{\hrule height 0pt}
-% \end{verbatim}
-% The green frame for the table of contents heading at the start of the second
-% part of this document was obtained with
-% \begin{verbatim}
-% \etocruledstyle[1]{\etocfontminusone\color{green}%
-% \fboxrule1pt\fboxsep1ex%
-% \framebox[\linewidth]
-% {\normalcolor\hfil Contents of this second part\hfil}}
-% \end{verbatim}
-%
-%
-% \subsection{The command \csb{etocmulticolstyle}}
-%
-% This is also a command with one optional and one mandatory argument:\\
-% \centerline{\color{blue}\cs{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}}
-% The \oarg{number\_of\_columns} can go from 1 to 10 (it defaults to 2, and from 2
-% on is passed to a |multicols| environment). The \marg{heading} can be something like:
-% \begin{center}
-% {\ttfamily\string\chapter\star}\marg{title},\\
-% or\\
-% \cs{etocstandardheading}\marg{title},\\
-% or\\
-% \cs{etocstandardheadingnomarks}\marg{title}.
-% \end{center}
-% These last two commands do either \starit{section} or
-% \starit{chapter} depending on the document class, and the
-% first one puts the marks for the page headings. To emulate the
-% standard formatting one can thus use:\\
-% \centerline{\ttfamily\string\etocmulticolstyle[1]\string{^^A
-% \string\etocstandardheading\string{\string\contentsname\string}\string}}
-% After such a command, future \cs{tableofcontents} will use the
-% specified style. A shortcut for just one table of contents and
-% not affecting the styles of later TOCs is:\\
-% \centerline{\cs{etocmulticol}\oarg{number\_of\_columns}\marg{heading}}
-% And the starred form will be
-% \starit{etocmulticol}\oarg{number\_of\_columns}\marg{heading}.
-%
-% \subsubsection{A point of some importance}
-%
-% There is an important difference between the
-% \cs{etocmulticolstyle} and \cs{etocruledstyle} commands. The
-% mandatory argument of the former can not be just some
-% \emph{naked text}. It should rather be something like
-% |\hbox{naked text}| or |\vbox{naked text}|.
-% ^^A
-% More conveniently, one can use things such as:\\
-% \hbox to \linewidth{\hss |\section*{some not so naked text}|\hss}
-% Else, you will get an error:\\
-% \hbox to \linewidth{\hss |ERROR: LaTeX Error: Something's wrong--perhaps a missing \item.|\hss}
-% In the special case where the command was
-% also given the optional argument |[1]|,
-% it is possible to feed it with `|naked text\par|'.
-% %
-%
-% On the other hand, it is exactly the opposite for \cs{etocruledstyle} which
-% expects things which fit inside a horizontal box, hence it will gladly accepts a
-% \emph{naked text} as argument.
-%
-%
-% \paragraph{Do we really want paragraph entries in the TOC?}
-%
-% \paragraph{really?}
-%
-% \subsection{The command \csb{etocruledstyle} (cont.)}
-%
-%
-% As a shortcut to set the style with this command and then make a
-% \cs{tableofcontents} or \tocstar call (in a group, so that the
-% style for future table of contents is not affected) we have: \\
-% \centerline{\csb{etocruled}\oarg{number\_of\_columns}\marg{title}}
-% And the starred form will be with \staritb{etocruled}.
-%
-% \subsection{The command \csb{etocframedstyle}}
-%
-% Same mechanism:\\
-% \centerline{\color{blue}\cs{etocframedstyle}\oarg{number\_of\_columns}\marg{title}}
-% and the accompanying shortcut:\\
-% \centerline{\csb{etocframed}\oarg{number\_of\_columns}\marg{title}}
-% Here the entire table of contents is framed, hence this can only work if it fits
-% on a page. Again the starred variant starts with \staritb{etocframed}.
-%
-% \subsection{The command \csb{etocsettocstyle}}
-%
-% This is a command with two mandatory arguments:\\
-% \centerline{\color{blue}\cs{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}|. It can also contain
-% instructions to mark the page headings.\footnote{\etoc
-% provides the command \cs{etocmarkboth}\oarg{optional\_name}, with an
-% optional argument which defaults to \cs{contentsname}.} 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.\footnote{In our
-% testing, we had some difficulties, when using the |multicol|
-% package in a book class document with the two-column global
-% option. So, as we use |multicol| by default we decided
-% against trying to automatize a check for such a possible
-% |twocolumn| class option. It is up to the user to decide (or
-% not) to switch back and forth from two-column to one-column
-% when typesettings table of contents.}
-%
-% The three commands \cs{etocmulticolstyle}, \cs{etocruledstyle}, and
-% \cs{etocframedstyle} actually call \cs{etocsettocstyle} as a
-% lower-level routine.
-% \clearpage
-% \section{Summary of the main local and global style
-% commands}
-%
-% {\color{green}\fboxrule1pt\fboxsep1em
-% \setbox0\hbox{\cs{etocname}, \cs{etocnumber}, \cs{etocpage},
-% \cs{etocifnumbered}\marg{A}\marg{B}}^^A
-% \framebox[\linewidth][c]{^^A
-% \vbox{\hsize\wd0\normalcolor\noindent
-% \cs{etocsetstyle}\marg{levelname}^^A
-% \marg{start}\marg{prefix}\marg{contents}\marg{finish}\\
-% \cs{etocname}, \cs{etocnumber}, \cs{etocpage},
-% \cs{etocifnumbered}\marg{A}\marg{B}\\
-% \cs{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}\\
-% \cs{etocruledstyle}\oarg{number\_of\_columns}\marg{title}\\
-% \cs{etocframedstyle}\oarg{number\_of\_columns}\marg{title}\\
-% \cs{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}\\
-% \cs{tableofcontents}\\
-% \tocstar\\
-% \cs{etocmulticol}\oarg{number\_of\_columns}\marg{heading}\\
-% \cs{etocmulticol}\star\oarg{number\_of\_columns}\marg{heading}\\
-% \cs{etocruled}\oarg{number\_of\_columns}\marg{title}\\
-% \cs{etocruled}\star\oarg{number\_of\_columns}\marg{title}\\
-% \cs{etocframed}\oarg{number\_of\_columns}\marg{title}\\
-% \cs{etocframed}\star\oarg{number\_of\_columns}\marg{title}}}}
-%
-%
-%
-% \part{Customizing \etoc}
-%
-% \section{Customizing the \etoc line styles}
-%
-% We will simply list the relevant commands as defined in the package. Customizing
-% them goes through suitable \cs{renewcommand}s:
-%
-% \begin{verbatim}
-% \newcommand\etocfontminusone{\normalfont \large \bfseries}
-% \newcommand\etocfontzero{\normalfont \normalsize \bfseries}
-% \newcommand\etocfontone{\normalfont \normalsize \bfseries}
-% \newcommand\etocfonttwo{\normalfont \normalsize}
-% \newcommand\etocfontthree{\normalfont \footnotesize}
-% \newcommand\etocfontfour{\normalfont \footnotesize}
-% \newcommand\etocfontfive{\normalfont \footnotesize}
-%
-% \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}
-% \newcommand\etocsepthree{.25ex plus .05ex minus .05ex}
-% \newcommand\etocminusonelrmargins{1em}
-%
-% \newcommand\etocbaselinespreadminusone{1}
-% \newcommand\etocbaselinespreadzero{1}
-% \newcommand\etocbaselinespreadone{1}
-% \newcommand\etocbaselinespreadtwo{1}
-% \newcommand\etocbaselinespreadthree{.9}
-%
-% \newcommand\etoctoclineleaders
-% {\hbox{\normalfont\normalsize\hbox to 2ex {\hfil.\hfil}}}
-%
-% \newcommand\etocabbrevpagename{p.~}
-% \end{verbatim}
-%
-% No customizing of the standard line styles is possible from
-% within \etoc. As already explained, when
-% \cs{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. In this mode the
-% \cs{etocsetstyle} commands will have an effect only after the
-% document encounters again an \cs{etocetoclines} command.
-%
-% The \cs{etocstandardlines} mechanism will work also with
-% sectioning commands made known to \etoc via \cs{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 \cs{l@something} . . .).
-%
-% \section{Customizing the global styles}
-%
-% Again we list the relevant macros, what they do should be legible from their
-% names:
-% \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\etocinnertopsep{2ex}
-% \newcommand\etocinnerbottomsep{3.5ex}
-% \newcommand\etocinnerleftsep{2em}
-% \newcommand\etocinnerrightsep{2em}
-%
-% \newcommand\etoctoprule{\hrule}
-% \newcommand\etocleftrule{\vrule}
-% \newcommand\etocrightrule{\vrule}
-% \newcommand\etocbottomrule{\hrule}
-%
-% \newcommand\etoctoprulecolorcmd{\relax}
-% \newcommand\etocbottomrulecolorcmd{\relax}
-% \newcommand\etocleftrulecolorcmd{\relax}
-% \newcommand\etocrightrulecolorcmd{\relax}
-% \end{verbatim}
-%
-% Regarding the dimensions of the top rule they can be specified
-% in |ex|'s or |em|'s as for example:\\
-% \hbox to \linewidth{\hss |\renewcommand{\etoctoprule}{\hrule height 1ex}|\hss}
-% The package code is done in such a way that it is the font
-% size in instance at the end of typesetting the title argument
-% to \cs{etocruledtoc} or \cs{etocframedtoc} which will be used
-% for the meaning of the `1ex'. However for the side rules and
-% bottom rule in the framed case, their dimensions, if specified
-% with such font relative units, are decided on the basis of the
-% font in effect just before the table of contents.
-%
-% The top, bottom, left, right rules do not have to be rules: they can be
-% \emph{leaders} in the general \TeX{} sense.
-%
-% \subsection{Hacking framed parboxes}
-%
-% \begin{verbatim}
-% \renewcommand\etoctoprule{\hrule height 2pt depth 2pt}
-% \etocruled*[3]{\color{green}\fboxrule2pt\fboxsep1ex%
-% \fbox{\raisebox{-\fontdimen22\textfont2}
-% {\color{blue}\parbox{.5\linewidth}
-% {\normalfont This text is perfectly centered
-% vertically with respect to the
-% surrounding horizontal rules, but as
-% there are no subsubsections here, it
-% sits above an empty (3-column) local toc.}}}}
-% \end{verbatim}
-%
-% \renewcommand\etoctoprule{\hrule height 2pt depth 2pt}
-% \etocruled*[3]{\color{green}\fboxrule2pt\fboxsep1ex^^A
-% \fbox{\raisebox{-\fontdimen22\textfont2}
-% {\color{blue}\parbox{.5\linewidth}
-% {\normalfont This text is perfectly centered
-% vertically with respect to the
-% surrounding horizontal rules, but as
-% there are no subsubsections here, it
-% sits above an empty (3-column)
-% local toc.}}}}
-%
-% \subsection{Interverting the levels}
-%
-% Let us display and count all subsections occurring in this document.
-% \begin{verbatim}
-% \setcounter{tocdepth}{2}
-% \etocsetlevel{part}{3}
-% \etocsetlevel{section}{3}
-% \etocsetstyle{subsection}{\begin{enumerate}[itemsep=0pt,%
-% label=,leftmargin=0pt]}
-% {\normalfont\bfseries\item}
-% {\roman{enumi}. \normalfont\etocname (\etocnumber, p.~\etocpage)}
-% {\end{enumerate}}
-% \renewcommand{\etoccolumnsep}{2.75em}
-% \renewcommand{\columnseprule}{1pt}
-% \etocmulticol[3]{\subsection{All subsections of this document}}
-% \end{verbatim}
-%
-% \setcounter{tocdepth}{2}
-% \etocsetlevel{part}{3}
-% \etocsetlevel{section}{3}
-% \etocsetstyle{subsection}{\begin{enumerate}[itemsep=0pt,^^A
-% label=,leftmargin=0pt]}
-% {\normalfont\bfseries\item}
-% {\roman{enumi}. \normalfont\etocname (\etocnumber, p.~\etocpage)}
-% {\end{enumerate}}
-% \renewcommand{\etoccolumnsep}{2.75em}
-% \renewcommand{\columnseprule}{1pt}
-% \etocmulticol[3]{\subsection{All subsections of this document}}
-%
-%
-% \subsection{Compatibility with other packages}
-%
-% \etoc uses the packages |multicol| and |xspace|. It is
-% |hyperref| aware and hopefully |hyperref| compatible! The
-% macros \cs{etocname}, \cs{etocnumber}, and \cs{etocpage}
-% contain the |hyperref| links, if present (note that the
-% |linktoc=all| option of |hyperref| tells it to put a link also
-% in the page number corresponding to a given toc entry). The
-% table of contents of the present document are fully linked.
-%
-% \etoc has not been tested with other packages than those
-% cited. It has been tested to work as expected with the
-% |article|, |book| and |scrartcl| document classes.
-%
-%
-% \subsection{\TeX nical matters}
-%
-% The \cs{etocname}, \cs{etocnumber}, \cs{etocpage} and
-% \cs{etocifnumbered} macros are protected against premature
-% expansion. The macro \cs{etocsetstyle}, as well as \cs{etocsetlevel}
-% and the global style commands \cs{etocmulticolstyle},
-% \cs{etocruledstyle} and \cs{etocframedstyle} obey \LaTeX{}'s groups.
-%
-% \part{The code}
-%
-% \section{Implementation}
-%
-% Source code commenting is hopefully for a future release. Sorry.
-% \StopEventually{}
-% \begin{macrocode}
+
+\rmfamily
+
+\begin{center}
+ {\normalfont\Large The \etoc package}\\
+\textsc{Jean-François Burnol}\par
+ \footnotesize \ttfamily
+ jfbu (at) free (dot) fr\\
+ Package version: \pkgversion\ (\pkgdate)\\
+ Documentation generated from the source file\\
+ with timestamp ``\dtxtimestamp''
+\end{center}
+
+
+\begin{abstract}
+ The \etoc package gives to the user complete control on
+ how the entries of the table of contents should be
+ constituted from the \emph{name}, \emph{number}, and
+ \emph{page number} of each sectioning unit. This goes via
+ the definition of \emph{line styles} for each sectioning
+ level used in the document. The package provides its own
+ custom line styles as an example, next to the standard
+ formatting inherited from the \LaTeX{} document classes. But
+ the idea is to give the means to the user to delegate the
+ details to packages dealing with list making environments
+ (such as |enumitem|). Regarding the \emph{global style},
+ \etoc typesets by default tables of contents in a
+ multi-column format, with either a standard heading, or a
+ ruled title, optionally with a frame around the table of
+ contents. The \csa{tableofcontents} command can be used
+ arbitrarily many times in the same document, and comes with
+ a starred variant which gives local table of contents.
+\end{abstract}
+
+\tableofcontents
+
+
+\part{Although this is a short document, we are going to use
+ many sectioning commands}
+
+\setcounter{tocdepth}{-2}
+
+\tableofcontents* \label{toc:partone}
+
+\setcounter{tocdepth}{3}
+
+\section{Overview}
+
+Popular packages dealing with TOCs include |tocloft|,
+|titletoc| and |minitoc|. Why another one? well, I started
+\etoc for my own use, and only later found out about the above
+mentioned packages . . . I realize (to some extent, as I still
+haven't read closely the documentations) that most if not all
+of the \etoc functionality could well be already available in
+the above mentioned packages.
+
+\subsection{Initial motivation}
+
+The specific initial impetus was to transform the `flat' data
+contained in the |.toc| file into a nested structure which
+could be given to list making environments.\footnote{I got
+ started about this through reading this question on the
+ \TeX{} Stackexchange site:\\
+\href{http://tex.stackexchange.com/questions/79682/can-i-get-a-list-of-all-sections-as-a-simple-enumerate-list}{tex.stackexchange.com/questions/79682}}
+For example, typesetting
+the line corresponding to the first sub-section in a given
+section would open a group which would be closed only when a
+section, chapter, or part line entry in the |.toc| file would
+be encountered. Package \etoc allows to do this very easily
+and the opening and closing of the groups can be for example
+|\begin{enumerate}| and |\end{enumerate}| pairs, will all the
+customizing allowed by packages such as |enumitem|.
+
+Although there is a limitation to this method (the |.toc| file
+may contain other commands, such as language changing
+commands, which do not expect to see their scope limited in
+this way inside a group), I believe this procedure will be
+found the most convenient in many cases. However the own
+package custom line styles (illustrated by the main table of
+contents in this document) do not make use of environments to
+avoid that problem.
+
+\subsection{Line styles}
+
+To implement the above idea, the command \csb{etocsetstyle}
+will inform \etoc of what it should do at each sectioning
+level, from |part| down to |subparagraph|. Other sectioning
+names can be used too, if present in the document.
+
+\subsubsection{\csb{etocetoclines} vs \csb{etocstandardlines}}
+
+The \csb{etocetoclines} command selects the package predefined
+line styles, and \csb{etocstandardlines} uses the standard
+default formatting from the |article|, |book|, |report|, or
+also |scrartcl| classes. For any document class proceeding in
+a manner compatible to the |article| class in its
+typesetting of the table of contents, the
+\csb{etocstandardlines} should be functional: indeed nothing
+is hard-coded into the package code; rather, when
+\csb{etocstandardlines} is issued by the user, the package
+cancels its own mechanism and gives back the leadership to the
+class layer. Note though that this means that \etoc does not
+provide utilities to change this or that length from the
+\LaTeX{} default formatting of TOC entries. But if some other
+package has done it, then this should work correctly also when
+\etoc is in use (for its other aspects as will be described below).
+
+\subsubsection{Instructing \etoc about sectioning command names}
+
+If the document class uses other names, such as \emph{atom},
+or \emph{particle}, the command \csb{etocsetlevel} will
+instruct \etoc about it.
+
+\subsection{Global style: multiple columns, ruled heading, framed table of contents}
+
+At the global level, the default of \etoc is to typeset the
+TOC on two columns, using the package |multicol|.
+Additionally, the heading can be formatted as in the default
+manner, or as a ruled heading, or the entire TOC can be
+encapsulated in a frame (if it fits on the current page). And
+the user can specify to use a single column output, or three
+columns, etc . . .
+
+\subsection{Local tables of contents}
+
+With \etoc, the \csb{tableofcontents} command can be used
+arbitrarily many times and it has a starred variant \tocstarb
+which will print a local table of contents: i.e. all subsections
+etc . . . inside a given section, or all subsubsections and
+lower inside a given subsection, etc . . .
+
+\subsection{Displaying tables of contents defined
+ elsewhere in the document}
+
+A \LaTeX{} counter is associated with the successive tables of
+contents. To set a reference point (which will become an
+anchor if package |hyperref| is loaded) one just uses the
+\cs{label} command as usual.
+For example:\\
+\hbox to \linewidth{\hss
+ \tocstarb\space\csbi{label}\csbi{\string{my\_nice\_toc\string}}\hss}
+
+Then, elsewhere in the document, doing:\\
+\hbox to \linewidth{\hss \tocb\space\csbi{ref\string{my\_nice\_toc\string}}\hss}
+will display again the same contents. However, the line styles
+and global style (including the title) will be the current one and the
+current value of the |tocdepth| counter is obeyed. As an example here is
+the table of contents of Part \ref{part:custom}:
+
+
+\begingroup
+\etocstandardlines
+\renewcommand{\etoctoprule}{\hrule height 0pt}
+\etocruled[1]{\framebox[\linewidth]{\etocfontminusone I am from
+ \hyperref[toc:c]{far away}}}
+\label{toc:d}
+\ref{toc:c}
+\endgroup
+
+We actually did something like:\\
+\hbox to \linewidth{\hss
+ \toc\space\cs{label}|{toc:1}|\cs{ref}|{toc:2}|\hss} Hence
+\hyperref[toc:d]{\color{green!50!blue!50}the present location}
+can itself now be referred to via |\ref{toc:1}|: this gives
+the number of this TOC (\emph{i.e}
+{\color{green!50!blue!50}\ref{toc:d}}) in the sequence of
+document TOCs, will be a link if package |hyperref| is used,
+and can be used elsewhere as \toc|\ref{toc:1}| (which is now
+equivalent to \toc|\ref{toc:2}|).
+
+For info, the \hyperref[toc:c]{\color{green!50!blue!50}distant toc}
+is the one which has number {\color{green!50!blue!50}\ref{toc:c}}...
+
+The \cs{label} command should come before the reference via
+\cs{ref} to the other TOC. A \cs{label} detected by \etoc
+immediately (skipping spaces) after the command \toc will be
+activated immediately after the update to the toc counter. A
+\cs{label} after the \cs{ref} will not be treated by \etoc
+itself and will refer to the latest reference point (possibly
+to some counter updated in the title of the TOC or, although
+this would require the user to have done a suitable set-up in the
+line styles, even inside the TOC).
+
+As another example let us now display a table of contents for
+this first part of the document. Indeed, immediately after the
+line in the source file starting with the first
+\cs{part} we wrote:
+\begin{verbatim}
+\setcounter{tocdepth}{-2}
+\tableofcontents* \label{toc:partone}
+\setcounter{tocdepth}{3}
+\end{verbatim}
+The |tocdepth| being -2, nothing at
+all was inserted in the page, but now that |tocdepth| has
+been reset to 3, we can display the TOC with the simple
+command:
+\begin{verbatim}
+\tableofcontents \ref{toc:partone}
+\end{verbatim}
+As explained above we could also add a label to refer to this
+table of contents. The actual design is not pre-built in
+\etoc: it combines the \etoc `framed' style (with a dummy
+empty title, the actual title having been put inside the frame
+as part of the \marg{start} code of the section `line
+style'). The frame borders have been set to have the same
+color as the one which serves as background for the entire
+thing. This design (with other colors) is used also for
+\hyperref[toc:clone]{\color{green!50!blue!50}this other toc} (the coding
+used is reproduced there).
+
+\setcounter{tocdepth}{3}
+
+\begingroup
+\colorlet{subsecnum}{black}
+\colorlet{secbackground}{green!30}
+\colorlet{tocbackground}{red!20!green!20}
+
+\renewcommand{\etocframedbkgcolorcmd}{\color{tocbackground}}
+\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
+
+\renewcommand{\etocleftrule}{\vrule width 2.5cm}
+\renewcommand{\etocrightrule}{\vrule width 1cm}
+\renewcommand{\etocbottomrule}{\hrule height 12pt}
+\renewcommand{\etoctoprule}{\hrule height 12pt}
+
+\renewcommand{\etocinnertopsep}{0pt}
+\renewcommand{\etocinnerbottomsep}{0pt}
+\renewcommand{\etocinnerleftsep}{0pt}
+\renewcommand{\etocinnerrightsep}{0pt}
+
+\newcommand\shiftedwhiterule[1]{%
+\hbox to \linewidth{\color{white}%
+\hskip\leftskip\leaders\vrule height1pt\hfil}\nointerlineskip
+\vskip#1}
+
+\etocsetstyle{subsubsection}{}
+{\shiftedwhiterule{6pt}}
+{\sffamily\footnotesize
+\leftskip2.25cm\noindent
+\hbox to 1cm{\color{subsecnum}\etocnumber\hss}%
+\color{black}\etocname\hfill\hbox{\etocpage\hskip.2cm}\par
+\nointerlineskip\vskip3pt}
+{}
+
+\etocsetstyle{subsection}{\etocskipfirstprefix}
+{\shiftedwhiterule{6pt}}
+{\sffamily\small
+\leftskip1.5cm\noindent
+\hbox to .75cm{\color{subsecnum}\etocnumber\hss}%
+\color{black}\etocname\hfill\hbox{\etocpage\hskip.2cm}\par
+\nointerlineskip\vskip3pt}
+{}
+
+\newcommand{\coloredstuff}[2]{%
+ \leftskip0pt\rightskip0pt\parskip0pt
+ \fboxsep0pt % \colorbox uses \fboxsep also when no frame!
+ \noindent\colorbox{secbackground}
+ {\parbox{\linewidth}{%
+ \vskip5pt
+ {\noindent\color{#1}#2\par\nointerlineskip}
+ \vskip3pt}}%
+ \par\nointerlineskip}
+
+\etocsetstyle{section}{\coloredstuff{blue}
+ {\hfil \bfseries\large Contents of Part One\hfil}}
+{\vskip3pt\sffamily\small}
+{\coloredstuff{blue}{\kern1cm\hbox to .5cm{\etocnumber\hss}%
+ \etocname\hfill\hbox{\etocpage\hskip.2cm}}%
+ \vskip6pt}
+{}
+
+\etocframedstyle[1]{}
+
+\tableofcontents \ref{toc:partone}
+
+\endgroup
+
+
+
+\part{Package commands for line styles}
+
+\etocsetstyle{section}
+{\begin{enumerate}[leftmargin=0pt,label=]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocifnumbered{\makebox[1cm][c]{\color{green}\fboxrule1pt
+ \fbox{\protect\normalcolor\etocnumber}}}{\hspace{1cm}}
+\etocname (page \etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsection}
+{\begin{enumerate}[label=\etocnumber, leftmargin=1cm]}
+{\normalfont \item}
+{\etocname (p.~\etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsubsection}
+{\par\nobreak\begingroup\normalfont\footnotesize\itshape\etocskipfirstprefix}
+{\allowbreak\,--\,}
+{\etocname}
+{\unskip.\hfil\par\endgroup\pagebreak[3]}
+
+\etocruledstyle[1]{\etocfontminusone\color{green}
+ \fboxrule1pt\fboxsep1ex
+ \framebox[\linewidth]
+ {\normalcolor\hfil Contents of this second part\hfil}}
+
+\tableofcontents* \label{toc:a}
+
+\section{The \csb{etocsetstyle} command}
+
+
+\subsection{An example}
+
+Let us explain how \etoc was used to produce the table of
+contents displayed at the beginning of this second part (this
+is a local table of contents, we used the command \tocstar).
+
+
+We shall distinguish between the \emph{line styles} and the
+\emph{global style}. First we describe how to set-up the
+line styles. Essentially they were obtained in the following
+manner%
+\footnote{the present document has
+ {\ttfamily\string\renewcommand\string{%
+ \string\familydefault\string}\string{\string\sfdefault\string}}
+ in its preamble, hence \csa{normalfont} switches to the
+ |sans| typeface; so in the section line-style, I wrote
+ \csa{rmfamily} instead.} \footnote{\etoc uses the |xspace|
+ package, and there is no need to write
+ \csa{etocname\string{\string} text} rather than just
+ \csa{etocname text} for example. However, this forced us to
+ add the mysterious \csa{unskip} before the dot in the
+ subsubsection style.}
+
+\begingroup\small
+\begin{verbatim}
+\etocsetstyle{section}
+{\begin{enumerate}}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname (page \etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsection}
+{\begin{enumerate}}
+{\normalfont\item}
+{\etocname (p.~\etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsubsection}
+{\par\nobreak\begingroup\normalfont
+ \footnotesize\itshape\etocskipfirstprefix}
+{\allowbreak\,--\,}
+{\etocname}
+{\unskip.\hfil\par\endgroup\pagebreak[3]}
+\end{verbatim}
+\endgroup
+
+Each \csb{etocsetstyle} command has five mandatory arguments:\\
+\hbox to \linewidth
+{\hfil\csa{etocsetstyle}\color{blue}\marg{levelname}%
+ \marg{start}\marg{prefix}\marg{contents}\marg{finish}\hfil}
+The initially recognized \marg{levelname}'s are the sectioning
+levels of the standard document classes (from \emph{part}
+down to \emph{subparagraph}).
+
+The \marg{start} code is executed when a toc entry of that level is
+encountered and the previous one was at a higher level. The
+\marg{finish} code is executed when one again encounters a higher
+level toc entry. In the mean-time all entries for that level are
+typeset by executing first the \marg{prefix} code and then the
+\marg{contents} code.
+
+\subsubsection{\csb{etocname} and \csb{etocpage}}
+
+The line styles specifications use the commands \csb{etocname}
+and \csb{etocpage} as synonyms for the name, respectively the
+page number of the current entry. Temporarily, we relied on
+the automatic numbering of the |enumerate| environments but
+there is also a command \csb{etocnumber} to get the real thing
+from the |.toc| file.
+
+
+\subsubsection{The \csb{etocskipfirstprefix} command}
+
+The chosen |subsubsection| style specifies to list the names of
+the subsubsections from a given subsection in an in-line
+manner, with -- as a separator. The command
+\csb{etocskipfirstprefix}, which, if present, \emph{must} be
+the very last one in the \emph{start} code, instructs to not
+use that separator of the first item.
+
+With this style, one would have
+to be imaginative to design something then for paragraph and
+subparagraph entries! perhaps as superscripts? Well, usually
+one does not need paragraphs and subparagraphs numbered and
+listed in the TOC, so our putative user here chose a design
+where no provision is made for them and added the definitive:
+\begin{verbatim}
+\etocsetstyle{paragraph}{}{}{}{}
+\etocsetstyle{subparagraph}{}{}{}{}
+\end{verbatim}
+This is also the situation with the default package line styles!
+
+\subsubsection{secnumdepth and tocdepth}
+
+The \LaTeX{} counter |secnumdepth|
+decides (from part down to subparagraph) which levels are numbered and
+automatically written to the |.toc| file. Its functioning
+is completely independent from the \etoc package. The counter
+|tocdepth|
+decides the finest level displayed in the table of contents: it
+is obeyed by \etoc, and as \toc can now be used arbitrarily
+times, this is an important customization lever.
+
+
+\subsection{The \csb{etocsetlevel} command}
+
+If your document uses other sectioning names, such as, for
+example \emph{molecule}, or \emph{atom}, it should inform \etoc of
+this in the following way:
+\begin{verbatim}
+\etocsetlevel{cell}{0}
+\etocsetlevel{molecule}{1}
+\etocsetlevel{atom}{2}
+\etocsetlevel{nucleus}{3}
+\end{verbatim}
+The accepted numbers range from -1 to 5 inclusive. The package code
+does:
+\begin{verbatim}
+\etocsetlevel{part}{-1}
+\etocsetlevel{chapter}{0}
+\etocsetlevel{section}{1}
+\etocsetlevel{subsection}{2}
+\etocsetlevel{subsubsection}{3}
+\etocsetlevel{paragraph}{4}
+\etocsetlevel{subparagraph}{5}
+\end{verbatim}
+
+\subsection{Further informations and let's make this a very long title to see how it will look like}
+
+
+\subsubsection{The \csb{etocnumber} command}
+So far, our specifications would use the numbering generated
+by the |enumerate| environments, but it would be nicer to use
+the actual numbers as found in the |.toc| file. This is
+available via the \csb{etocnumber} command. To get the labels
+in the |enumerate| list to use it we can proceed with the
+syntax {\ttfamily label=\char32} from the package |enumitem|:
+\begin{verbatim}
+\etocsetstyle{section}
+{\begin{enumerate}[label=\etocnumber]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname (page \etocpage)}
+{\end{enumerate}}
+\end{verbatim}
+Rather than just\csa{etocnumber} we then used something like
+|\fbox{\etocnumber}|.
+
+
+\subsubsection{The \csb{etocifnumbered} switch}
+
+The \csa{fbox} would give an unaesthetic result in the case of an unnumbered
+section (which ended up in the table of contents via an \csa{addcontentsline}
+command). The \csa{etocifnumbered}\marg{A}\marg{B} command executes \meta{A} if
+the number exists, and \meta{B} if not. So our final code could be:
+\begin{verbatim}
+\etocsetstyle{section}
+{\begin{enumerate}[label=\etocifnumbered{\etocnumber}{}]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocname (page \etocpage)}
+{\end{enumerate}}
+\end{verbatim}
+We used, actually:
+\begin{verbatim}
+\etocsetstyle{section}
+{\begin{enumerate}[leftmargin=0pt,label=]}
+{\normalsize\bfseries\rmfamily\item}
+{\etocifnumbered{\makebox[1cm][c]{\color{green}\fboxrule1pt
+ \fbox{\protect\normalcolor\etocnumber}}{\hspace{1cm}}
+\etocname (page \etocpage)}
+{\end{enumerate}}
+
+\etocsetstyle{subsection}
+{\begin{enumerate}[label=\etocnumber, leftmargin=1cm]}
+{\normalfont \item}
+{\etocname (p.~\etocpage)}
+{\end{enumerate}}
+\end{verbatim}
+
+If we had changed only the |section| level, and not the
+|subsection| level, an error on compilation would have occurred
+because the package style for subsections expects to start `in
+vertical mode'. An additional \csa{par} token in the
+\meta{contents} part of the |section| level would fixed
+this: |{...(page \etocpage)\par}|.
+
+
+\subsection{The \csb{etocfontxxx...} commands}
+
+The package predefines for use in its default line styles:
+\begin{verbatim}
+\newcommand\etocfontminusone{\normalfont \large \bfseries}
+\newcommand\etocfontzero{\normalfont \normalsize \bfseries}
+\newcommand\etocfontone{\normalfont \normalsize \bfseries}
+\newcommand\etocfonttwo{\normalfont \normalsize}
+\newcommand\etocfontthree{\normalfont \footnotesize}
+\newcommand\etocfontfour{\normalfont \footnotesize}
+\newcommand\etocfontfive{\normalfont \footnotesize}
+\end{verbatim}
+This only impact the package default line styles and does
+nothing under the \csa{etocstandardlines} regime.
+And, let us recall, levels four (paragraph) and five
+(subparagraphs) are not displayed by the package
+default line styles.
+
+
+
+\color{red!50}
+\addtocontents{toc}{\string\color{red!50}}
+
+\subsubsection{This is a red subsubsection for illustrative purposes}
+
+Just before this subsubsection we inserted in the |.tex| file:
+\begin{verbatim}
+\color{red}
+\addtocontents{toc}{\string\color{red!50}}
+\end{verbatim}
+This entire subsubsection and its title is printed in red, as
+well as the title of the next section (we cancel the color
+change only after it). But what about its entry in the table
+of contents? well it is red in the main table of contents at
+the beginning of this document, which uses the package line
+styles, and it is not red in the table of contents at the
+beginning of this second document part. The reason is that the
+\meta{finish} code for the subsubsection level closed a group,
+whereas the \meta{start} and \meta{finish} code of the package
+line styles do not contain group opening and closing
+instructions. So here the group was closed while reading the
+|.toc| file and this explains why the next entry in the local
+TOC was not typeset in red.
+
+In the present case the group at the subsubsection level is
+there to confine the font changes, but this could be made
+superfluous via adding a \csa{normalsize} to the
+|subsection| specification. I take this opportunity to mention
+that \etoc always typesets the entire table of contents inside
+a group, hence no font change therein can propagate to the outside.
+
+
+\section{Am I also in red?}
+
+\begin{verbatim}
+\normalcolor
+\addtocontents{toc}{\string\normalcolor}
+\end{verbatim}
+
+\normalcolor
+\addtocontents{toc}{\string\normalcolor}
+
+Back to black. Note that this scope problem arises in real
+life in a multi-lingual document, as the |babel| package
+writes to the |.toc| file the language changes occurring in
+the document. There is no easy general solution\footnote{one
+ can insert by hand the language changes in each concerned
+ sectioning command.} to this problem, which probably will
+concern only a minority of cases. Again, the line styles
+defined by \etoc do not use groups.
+
+\section*{An unnumbered section}
+\addcontentsline{toc}{section}{An unnumbered section}
+
+I don't have much to say here. I just added an unnumbered
+section, and made it appear in the |.toc| file.
+
+\begin{verbatim}
+\section*{An unnumbered section}
+\addcontentsline{toc}{section}{An unnumbered section}
+\end{verbatim}
+
+
+\part{Package commands for global styles}
+
+
+We shall illustrate the package functionalities through
+comparing here various line styles: the standard formatting as
+provided by the |article| class, the custom line styles we
+defined above using enumerate environments, and the package
+line styles.
+
+\begin{verbatim}
+\setcounter{secnumdepth}{4}
+\setcounter{tocdepth}{4}
+\end{verbatim}
+
+\setcounter{secnumdepth}{4}
+\setcounter{tocdepth}{4}
+
+\etocruledstyle[2]{\normalfont\normalsize\rmfamily\itshape
+ \fbox{\parbox{.8\linewidth}{This is the
+ table of contents using enumerate environments for part,
+ section and subsection, and an in-line italic style for
+ subsubsections.}}}
+
+First let us use again our set-up from the previous part. We add to it
+\begin{verbatim}
+\etocsetstyle{part}
+{\begin{enumerate}[label=\etocnumber,leftmargin=1em]}
+{\etocfontminusone\item}
+{\etocname}
+{\end{enumerate}}
+\end{verbatim}
+
+\etocsetstyle{part}
+{\begin{enumerate}[label=\etocnumber,leftmargin=1.5em]}
+{\etocfontminusone\item}
+{\etocname}
+{\end{enumerate}}
+
+\tableofcontents \label{toc:test}
+
+Then we switch to the standard formatting of entries, as is
+provided by the document class, but displayed here on two columns:
+\begin{verbatim}
+\etocstandardlines
+\tableofcontents
+\end{verbatim}
+
+\etocstandardlines
+
+\etocruledstyle[2]{%
+\renewcommand{\etoctoprule}{\hrule height0pt}%
+\normalfont\normalsize\rmfamily\itshape
+\parbox{.8\linewidth}{\centering
+This is the table of contents with standard
+ entries (on 2 columns!).\\ Contrarily to
+ \hyperref[toc:test]{\color{green!50!blue!50}the previous TOC} it
+ displays the paragraph entries.}}
+
+\tableofcontents
+
+For the third example, we will use the starred variant
+\tocstar to restrict its contents to this document part.
+Furthermore we opt for a ``framed'' style, and specify some
+colors (including a background color). We modify various
+things from the package defaults. And we have also to cancel
+this background color in the title (by default it applies both
+to the title and to the contents).
+
+
+\etocetoclines
+
+\begingroup
+\renewcommand{\etocinnerleftsep}{2ex}
+\renewcommand{\etocinnerrightsep}{2ex}
+% specify a background color for the toc contents and its title
+\renewcommand{\etocframedbkgcolorcmd}{\color{yellow!10}}
+% set up the top and bottom rules
+\renewcommand{\etoctoprule}{\hrule height 1pt}
+\renewcommand{\etoctoprulecolorcmd}{\color{red!25}}
+\renewcommand{\etocbottomrule}{\hrule height 1pt}
+\renewcommand{\etocbottomrulecolorcmd}{\color{red!25}}
+% set up the left and right rules
+\renewcommand{\etocleftrule}{\vrule width 5pt}
+\renewcommand{\etocrightrule}{\vrule width 5pt}
+\renewcommand{\etocleftrulecolorcmd}{\color{red!25}}
+\renewcommand{\etocrightrulecolorcmd}{\color{red!25}}
+% use \fcolorbox to set up a colored frame for the title, and cancel
+% the background color there.
+\fboxrule1pt
+\etocframedstyle{\normalsize\rmfamily\itshape
+ \fcolorbox{red}{white}{\parbox{.8\linewidth}{\centering
+ This is a table of contents \`a la \etoc, but just for
+ the sections and subsections in this part. As it is put
+ in a frame, it has to be small enough to fit on the
+ current page.}}}
+% set up a label for future (or earlier...) reference
+\tableofcontents* \label{toc:b}
+\endgroup
+
+\begingroup
+\baselineskip10pt
+\footnotesize
+\begin{verbatim}
+\etocetoclines
+\begingroup % we use a group to limit the scope of the next commands
+\renewcommand{\etocinnerleftsep}{2ex}
+\renewcommand{\etocinnerrightsep}{2ex}
+% specify a background color for the toc contents and its title
+\renewcommand{\etocframedbkgcolorcmd}{\color{yellow!10}}
+% set up the top and bottom rules
+\renewcommand{\etoctoprule}{\hrule height 1pt}
+\renewcommand{\etoctoprulecolorcmd}{\color{red!25}}
+\renewcommand{\etocbottomrule}{\hrule height 1pt}
+\renewcommand{\etocbottomrulecolorcmd}{\color{red!25}}
+% set ut the left and right rules
+\renewcommand{\etocleftrule}{\vrule width 5pt}
+\renewcommand{\etocrightrule}{\vrule width 5pt}
+\renewcommand{\etocleftrulecolorcmd}{\color{red!25}}
+\renewcommand{\etocrightrulecolorcmd}{\color{red!25}}
+% use \fcolorbox to set up a colored frame for the title, and cancel
+% the background color there.
+\fboxrule1pt
+\etocframedstyle{\normalsize\rmfamily\itshape
+ \fcolorbox{red}{white}{\parbox{.8\linewidth}{\centering
+ This is a table of contents \`a la \etoc, but just for
+ the sections and subsections in this part. As it is put
+ in a frame, it has to be small enough to fit on the
+ current page.}}}
+% set up a label for future (or earlier...) reference
+\tableofcontents* \label{toc:b}
+\endgroup
+\end{verbatim}
+\endgroup
+
+\setcounter{tocdepth}{3}
+
+\section{Specifying the global style}
+
+
+The \emph{global} style says whether the TOC appears with
+multiple columns or just one, whether the title is typeset as
+in the |article| or |book| class, or should be centered above
+the entries, with rules on its sides, or if the entire TOC
+should be put in a frame. For example, to opt for a ruled
+heading and single column layout, one issues commands of the
+following type:
+\begin{verbatim}
+\etocruledstyle[1]{Title}
+\tableofcontents (or \tableofcontents*)
+or the shortcuts:
+ \etocruled[1]{Title} or \etocruled*[1]{Title}
+\end{verbatim}
+
+\subsection{The command \csb{etocruledstyle}}
+
+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 can 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 table of contents heading at the start of the second
+part of this document was obtained with
+\begin{verbatim}
+\etocruledstyle[1]{\etocfontminusone\color{green}
+ \fboxrule1pt\fboxsep1ex
+ \framebox[\linewidth]
+ {\normalcolor\hfil Contents of this second part\hfil}}
+\end{verbatim}
+
+
+\subsection{The command \csb{etocmulticolstyle}}
+
+This is also a command with one optional and one mandatory argument:\\
+\centerline{\color{blue}\csa{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}}
+The \oarg{number\_of\_columns} can go from 1 to 10 (it defaults to 2, and from 2
+on is passed to a |multicols| environment). The \marg{heading} can be something like:
+\begin{center}
+ {\ttfamily\string\chapter\lowast}\marg{title},\\
+ or\\
+\csa{etocstandardheading}\marg{title},\\
+or\\
+ \csa{etocstandardheadingnomarks}\marg{title}.
+\end{center}
+These last two commands do either \starit{section} or
+\starit{chapter} depending on the document class, and the
+first one puts the marks for the page headings. To emulate the
+standard formatting one can thus use:\\
+\centerline{\ttfamily\string\etocmulticolstyle[1]\string{%
+\string\etocstandardheading\string{\string\contentsname\string}\string}}
+After such a command, future \csa{tableofcontents} will use the
+specified style. A shortcut for just one table of contents and
+not affecting the styles of later TOCs is:\\
+\centerline{\csa{etocmulticol}\oarg{number\_of\_columns}\marg{heading}}
+And the starred form will be
+\starit{etocmulticol}\oarg{number\_of\_columns}\marg{heading}.
+
+\subsubsection{A point of some importance}
+
+There is an important difference between the
+\csa{etocmulticolstyle} and \csa{etocruledstyle} commands. The
+mandatory argument of the former can not be just some
+\emph{naked text}. It should rather be something like
+|\hbox{naked text}| or |\vbox{naked text}|.
+%
+More conveniently, one can use things such as:\\
+\hbox to \linewidth{\hss |\section*{some not so naked text}|\hss}
+Else, you will get an error:\\
+\hbox to \linewidth{\hss
+|ERROR: LaTeX Error: Something's wrong--perhaps a missing \item.|\hss}
+In the special case where the command was
+also given the optional argument |[1]|,
+it is possible to feed it with `|naked text\par|'.
+
+
+On the other hand, it is exactly the \emph{opposite} for
+\csa{etocruledstyle} which expects things which fit inside a
+horizontal box, hence it will gladly accepts a \emph{naked
+ text} as argument, but will choke on things such as \cs{par}.
+
+
+\paragraph{Do we really want paragraph entries in the TOC?}
+
+\paragraph{really?}
+
+\subsection{The command \csb{etocruledstyle} (cont.)}
+
+
+As a shortcut to set the style with this command and then make a
+\csa{tableofcontents} or \tocstar call (in a group, so that the
+style for future table of contents is not affected) we have: \\
+\centerline{\csb{etocruled}\oarg{number\_of\_columns}\marg{title}}
+And the starred form will be with \staritb{etocruled}.
+
+\subsection{The command \csb{etocframedstyle}}
+
+Same mechanism:\\
+\centerline{\color{blue}\csa{etocframedstyle}\oarg{number\_of\_columns}\marg{title}}
+and the accompanying shortcut:\\
+\centerline{\csb{etocframed}\oarg{number\_of\_columns}\marg{title}}
+Here the entire table of contents is framed, hence this can only work if it fits
+on a page. Again the starred variant starts with \staritb{etocframed}.
+
+\subsection{The command \csb{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}|. It can also contain
+instructions to mark the page headings.\footnote{\etoc
+ provides the command \csa{etocmarkboth}\oarg{optional\_name}, with an
+ optional argument which defaults to \csa{contentsname}.} 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.\footnote{In our
+ testing, we had some difficulties, when using the |multicol|
+ package in a book class document with the two-column global
+ option. So, as we use |multicol| by default we decided
+ against trying to automatize a check for such a possible
+ |twocolumn| class option. It is up to the user to decide (or
+ not) to switch back and forth from two-column to one-column
+ when typesetting table of contents.}
+
+The three commands \csa{etocmulticolstyle}, \csa{etocruledstyle}, and
+\csa{etocframedstyle} actually call \csa{etocsettocstyle} as a
+lower-level routine.
+
+\section{Summary of the main local and global style
+ commands}
+
+\subsection{Setting up local styles}
+
+\hbox{\color{green}\fboxrule1pt\fboxsep1em
+\setbox0\hbox{\csa{etocname}, \csa{etocnumber}, \csa{etocpage},
+\csa{etocifnumbered}\marg{A}\marg{B}}%
+\framebox[\linewidth][c]
+{\vbox{\hsize\wd0\normalcolor\noindent
+\csa{etocsetstyle}\marg{levelname}%
+ \marg{start}\marg{prefix}\marg{contents}\marg{finish}\\
+\csa{etocname}, \csa{etocnumber}, \csa{etocpage},
+\csa{etocifnumbered}\marg{A}\marg{B}%
+}}}
+
+\subsection{Setting up global styles}
+
+\medskip
+\hbox{\color{green}\fboxrule1pt\fboxsep1em
+\setbox0\hbox{\csa{etocname}, \csa{etocnumber}, \csa{etocpage},
+\csa{etocifnumbered}\marg{A}\marg{B}}%
+\framebox[\linewidth][c]
+{\vbox{\hsize\wd0\normalcolor\noindent
+\csa{etocmulticolstyle}\oarg{number\_of\_columns}\marg{heading}\\
+\csa{etocruledstyle}\oarg{number\_of\_columns}\marg{title}\\
+\csa{etocframedstyle}\oarg{number\_of\_columns}\marg{title}\\
+\csa{etocsettocstyle}\marg{before\_toc}\marg{after\_toc}}}}
+
+\subsection{Displaying Tables of Contents}
+
+
+\medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
+ \setbox0\hbox{\csa{etocname}, \csa{etocnumber},
+ \csa{etocpage}, \csa{etocifnumbered}\marg{A}\marg{B}}%
+ \framebox[\linewidth][c]
+ {\vbox{\hsize\wd0\normalcolor\noindent
+ \toc\\
+ \tocstar\\
+ \csa{etocmulticol}\oarg{number\_of\_columns}\marg{heading}\\
+ \csa{etocmulticol}\lowast\oarg{number\_of\_columns}\marg{heading}\\
+ \csa{etocruled}\oarg{number\_of\_columns}\marg{title}\\
+ \csa{etocruled}\lowast\oarg{number\_of\_columns}\marg{title}\\
+ \csa{etocframed}\oarg{number\_of\_columns}\marg{title}\\
+ \csa{etocframed}\lowast\oarg{number\_of\_columns}\marg{title}%
+ }}}
+
+\subsection{Labels and references}
+
+The commands to actually display the table of contents
+can be followed with optional labels or references:\par
+
+\medskip \hbox{\color{green}\fboxrule1pt\fboxsep1em
+ \setbox0\hbox{\csa{etocname}, \csa{etocnumber},
+ \csa{etocpage}, \csa{etocifnumbered}\marg{A}\marg{B}}%
+ \framebox[\linewidth][c]
+ {\vbox{\hsize\wd0\normalcolor\noindent
+ \toc\\
+ \toc \cs{label}|\{toc:here\}|\\
+ \toc \cs{ref}|\{toc:far\}| \\
+ \toc \cs{label}|\{toc:here\}| \cs{ref}|\{toc:far\}| \\
+ \tocstar\\
+ \tocstar \cs{label}|\{toc:here\}|
+ }}}
+
+
+\medskip The starred form displaying a local table of
+contents, it will not react to a \cs{ref} following it. When
+re-displaying another toc, only its contents are transferred:
+both the line styles and the global style are the ones
+currently defined, not the ones from the cloned toc.
+
+The shortcuts for setting up and using in one go the multicol,
+ruled, and framed global styles can be followed in the
+similar manner by a label and/or a reference.
+
+
+% The command \csb{etocref} when given a label |toc:x| as
+% argument produces the number of the corresponding TOC:
+% \emph{i.e.} 1 for the first in the document etc... this is the
+% same information as in \cs{ref}|{toc:x}| or \cs{ref*}|{toc:x}|
+% but without any hyperlink or other extraneous data. It is
+% mainly used internally by \etoc, but can be used as a perhaps
+% more robust command than \cs{ref} or \cs{ref*} when
+% typesetting the number of the TOC.
+
+\subsection{Example of a cloned local TOC}
+
+
+We try out |\tableofcontents \ref{toc:b}|.
+First we have to specify the design.
+I got motivated by a
+question\footnote{\href{http://tex.stackexchange.com/questions/83184/how-to-change-style-and-color-of-table-of-content}{tex.stackexchange.com/questions/83184}}
+I saw on the \TeX{} StackExchange site. I copied the color RGB
+specifications from an answer which had been provided to the
+question. The \cs{etocframedstyle} puts the title
+on the top rule in a centered position. This is not very
+convenient for this example so we included the title as part of the
+\meta{start} code at section level, to get it \emph{inside}
+the frame.
+
+\begingroup
+\baselineskip10pt
+\footnotesize
+\begin{verbatim}
+\setcounter{tocdepth}{3}
+\begingroup
+\definecolor{subsecnum}{RGB}{13,151,225}
+\definecolor{secbackground}{RGB}{0,177,235}
+\definecolor{tocbackground}{RGB}{212,237,252}
+
+\renewcommand{\etocframedbkgcolorcmd}{\color{tocbackground}}
+\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
+
+\renewcommand{\etocleftrule}{\vrule width 1.5cm}
+\renewcommand{\etocrightrule}{\vrule width .5cm}
+\renewcommand{\etocbottomrule}{\hrule height 12pt}
+\renewcommand{\etoctoprule}{\hrule height 12pt}
+
+\renewcommand{\etocinnertopsep}{0pt}
+\renewcommand{\etocinnerbottomsep}{0pt}
+\renewcommand{\etocinnerleftsep}{0pt}
+\renewcommand{\etocinnerrightsep}{0pt}
+
+\newcommand\shiftedwhiterule[1]{%
+\hbox to \linewidth{\color{white}%
+\hskip\leftskip\leaders\vrule height1pt\hfil}\nointerlineskip
+\vskip#1}
+
+\etocsetstyle{subsubsection}{}
+{\shiftedwhiterule{6pt}}
+{\sffamily\footnotesize
+\leftskip2.5cm\noindent
+\hbox to 1cm{\color{subsecnum}\etocnumber\hskip.2cm}%
+\color{black}\etocname\hfill\hbox{\etocpage\hskip.2cm}\par
+\nointerlineskip\vskip3pt}
+{}
+
+\etocsetstyle{subsection}{\etocskipfirstprefix}
+{\shiftedwhiterule{6pt}}
+{\sffamily\small
+\leftskip1.5cm\noindent
+\hbox to 1cm{\color{subsecnum}\etocnumber\hskip.2cm}%
+\color{black}\etocname\hfill\hbox{\etocpage\hskip.2cm}\par
+\nointerlineskip\vskip3pt}
+{}
+
+\newcommand{\coloredstuff}[2]{%
+ \leftskip0pt\rightskip0pt\parskip0pt
+ \fboxsep0pt % \colorbox uses \fboxsep!
+ \noindent\colorbox{secbackground}
+ {\parbox{\linewidth}{%
+ \vskip5pt
+ {\noindent\color{#1}#2\par\nointerlineskip}
+ \vskip3pt}}%
+ \par\nointerlineskip}
+
+\etocsetstyle{section}{\coloredstuff{white}
+ {\hfil \hyperref[toc:b]{\bfseries\large I am a clone of
+ that other TOC (click me!)}\hfil}}
+{\vskip3pt\sffamily\small}
+{\coloredstuff{white}{\hbox to 1.5cm{\hss\etocnumber\hskip.2cm}%
+ \etocname\hfill\hbox{\etocpage\hskip.2cm}}%
+ \vskip6pt}
+{}
+\etocframedstyle[1]{} % title is not there!
+\tableofcontents \label{toc:clone} \ref{toc:b}
+\endgroup
+\end{verbatim}
+\endgroup
+
+\setcounter{tocdepth}{3}
+
+\begingroup
+\definecolor{subsecnum}{RGB}{13,151,225}
+\definecolor{secbackground}{RGB}{0,177,235}
+\definecolor{tocbackground}{RGB}{212,237,252}
+
+\renewcommand{\etocframedbkgcolorcmd}{\color{tocbackground}}
+\renewcommand{\etocleftrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocrightrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etocbottomrulecolorcmd}{\color{tocbackground}}
+\renewcommand{\etoctoprulecolorcmd}{\color{tocbackground}}
+
+\renewcommand{\etocleftrule}{\vrule width 1.5cm}
+\renewcommand{\etocrightrule}{\vrule width .5cm}
+\renewcommand{\etocbottomrule}{\hrule height 12pt}
+\renewcommand{\etoctoprule}{\hrule height 12pt}
+
+\renewcommand{\etocinnertopsep}{0pt}
+\renewcommand{\etocinnerbottomsep}{0pt}
+\renewcommand{\etocinnerleftsep}{0pt}
+\renewcommand{\etocinnerrightsep}{0pt}
+
+\newcommand\shiftedwhiterule[1]{%
+\hbox to \linewidth{\color{white}%
+\hskip\leftskip\leaders\vrule height1pt\hfil}\nointerlineskip
+\vskip#1}
+
+\etocsetstyle{subsubsection}{}
+{\shiftedwhiterule{6pt}}
+{\sffamily\footnotesize
+\leftskip2.5cm\noindent
+\hbox to 1cm{\color{subsecnum}\etocnumber\hskip.2cm}%
+\color{black}\etocname\hfill\hbox{\etocpage\hskip.2cm}\par
+\nointerlineskip\vskip3pt}
+{}
+
+\etocsetstyle{subsection}{\etocskipfirstprefix}
+{\shiftedwhiterule{6pt}}
+{\sffamily\small
+\leftskip1.5cm\noindent
+\hbox to 1cm{\color{subsecnum}\etocnumber\hskip.2cm}%
+\color{black}\etocname\hfill\hbox{\etocpage\hskip.2cm}\par
+\nointerlineskip\vskip3pt}
+{}
+
+\newcommand{\coloredstuff}[2]{%
+ \leftskip0pt\rightskip0pt\parskip0pt
+ \fboxsep0pt % \colorbox uses \fboxsep
+% si j'utilise des \hrule à l'intérieur de la parbox je suis
+% obligé de mettre ici
+% \color{secbackground}
+% de plus il y a un filet infinitésimal après ou avant les \hrule dont
+% je ne comprends pas l'origine [erreurs d'arrondis pour des
+% conversions en arithmétique interne?]
+ \noindent\colorbox{secbackground}
+ {\parbox{\linewidth}{%
+ \vskip5pt
+ {\noindent\color{#1}#2\par\nointerlineskip}
+ \vskip3pt}}%
+ \par\nointerlineskip}
+
+\etocsetstyle{section}{\coloredstuff{white}
+ {\hfil \hyperref[toc:b]{\bfseries\large I am a clone of
+ that other TOC (click me!)}\hfil}}
+{\vskip3pt\sffamily\small}
+{\coloredstuff{white}{\hbox to 1.5cm{\hss\etocnumber\hskip.2cm}%
+ \etocname\hfill\hbox{\etocpage\hskip.2cm}}%
+ \vskip6pt}
+{}
+
+\etocframedstyle[1]{}
+
+\tableofcontents \label{toc:clone} \ref{toc:b}
+
+\endgroup
+
+
+The coding is a bit involved as it does not use any additional
+package. The framed style allowed us to specify a background
+color. Generally speaking all color commands inside \etoc are
+initially defined to do nothing, so the choice to use or not
+color packages is left to the user.
+
+
+
+\part{Customizing \etoc}
+\label{part:custom}
+
+
+\etocetoclines
+\renewcommand{\etoctoprule}{\hrule height2pt depth0pt}
+\renewcommand{\etoctoprulecolorcmd}{\color{red}}
+
+\etocruledstyle{\normalfont\normalsize\rmfamily\fboxrule1pt\color{red}%
+ \fbox{\parbox{.8\linewidth}{\centering\normalcolor This is a table of
+ contents for the sections and
+ subsections in this part. It carries the label |toc:c|}}}
+
+\tableofcontents* \label{toc:c}
+
+
+\section{Customizing the \etoc 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\etocfontminusone{\normalfont \large \bfseries}
+\newcommand\etocfontzero{\normalfont \normalsize \bfseries}
+\newcommand\etocfontone{\normalfont \normalsize \bfseries}
+\newcommand\etocfonttwo{\normalfont \normalsize}
+\newcommand\etocfontthree{\normalfont \footnotesize}
+\newcommand\etocfontfour{\normalfont \footnotesize}
+\newcommand\etocfontfive{\normalfont \footnotesize}
+
+\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}
+\newcommand\etocsepthree{.25ex plus .05ex minus .05ex}
+\newcommand\etocminusonelrmargins{1em}
+
+\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.~}
+\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. In this mode the
+\csa{etocsetstyle} commands will have an effect only after the
+document encounters again an \csa{etocetoclines} command.
+
+The \csa{etocstandardlines} mechanism 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} . . .).
+
+\section{Customizing the global styles}
+
+
+Again we list the relevant macros, what they do should be legible from their
+names:
+\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\etocinnertopsep{2ex}
+\newcommand\etocinnerbottomsep{3.5ex}
+\newcommand\etocinnerleftsep{2em}
+\newcommand\etocinnerrightsep{2em}
+
+\newcommand\etoctoprule{\hrule}
+\newcommand\etocleftrule{\vrule}
+\newcommand\etocrightrule{\vrule}
+\newcommand\etocbottomrule{\hrule}
+
+\newcommand\etoctoprulecolorcmd{\relax}
+\newcommand\etocbottomrulecolorcmd{\relax}
+\newcommand\etocleftrulecolorcmd{\relax}
+\newcommand\etocrightrulecolorcmd{\relax}
+\newcommand\etocframedbkgcolorcmd{\relax}
+
+\newcommand\etocframedmphook{\relax}
+\end{verbatim}
+
+This last command is a hook, it is positioned immediately
+after the beginning of a minipage environment where the
+contents of the framed TOC are typeset.
+
+Regarding the dimensions of the top rule they can be specified
+in |ex|'s or |em|'s as for example:\\
+\hbox to \linewidth{\hss
+|\renewcommand{\etoctoprule}{\hrule height 1ex}|\hss}
+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.
+
+\subsection{Hacking framed parboxes}
+
+
+\begin{verbatim}
+\renewcommand\etoctoprule{\hrule height 2pt depth 2pt}
+\etocruled{\color{green}\fboxrule2pt\fboxsep1ex
+ \fbox{\raisebox{-\fontdimen22\textfont2}
+ {\color{blue}\parbox{.5\linewidth}
+ {\normalfont This text is perfectly centered
+ vertically with respect to the
+ surrounding horizontal rules.}}}}
+\ref{toc:b}
+\end{verbatim}
+
+\renewcommand\etoctoprule{\hrule height 2pt depth 2pt}
+
+\etocruled{\color{green}\fboxrule2pt\fboxsep1ex
+ \fbox{\raisebox{-\fontdimen22\textfont2}
+ {\color{blue}\parbox{.5\linewidth}
+ {\normalfont This text is perfectly centered
+ vertically with respect to the
+ surrounding horizontal rules.}}}}
+ \ref{toc:b}
+
+
+\subsection{Interverting the levels}
+
+Let us display and count all subsections occurring in this document.
+\begin{verbatim}
+\setcounter{tocdepth}{2}
+\etocsetlevel{part}{3}
+\etocsetlevel{section}{3}
+\etocsetstyle{subsection}{\begin{enumerate}[itemsep=0pt,%
+label=,leftmargin=0pt]}
+{\normalfont\bfseries\item}
+{\roman{enumi}. \normalfont\etocname (\etocnumber, p.~\etocpage)}
+{\end{enumerate}}
+\renewcommand{\etoccolumnsep}{2.75em}
+\renewcommand{\columnseprule}{1pt}
+\etocmulticol[3]{\subsection{All subsections of this document}}
+\end{verbatim}
+
+\setcounter{tocdepth}{2}
+
+\begingroup
+\etocsetlevel{part}{3}
+\etocsetlevel{section}{3}
+\etocsetstyle{subsection}{%
+\begin{enumerate}[itemsep=0pt,label=,leftmargin=0pt]}
+{\normalfont\bfseries\item}
+{\roman{enumi}. \normalfont\etocname (\etocnumber, p.~\etocpage)}
+{\end{enumerate}}
+\renewcommand{\etoccolumnsep}{2.75em}
+\renewcommand{\columnseprule}{1pt}
+
+\etocmulticol[3]{\subsection{All subsections of this document}}
+
+\endgroup
+
+\subsection{Compatibility with other packages}
+
+\etoc uses the packages |multicol| and |xspace|. It is
+|hyperref| aware and hopefully |hyperref| compatible!
+
+The
+macros \csa{etocname}, \csa{etocnumber}, and \csa{etocpage}
+contain the |hyperref| links, if present (note that the
+|linktoc=all| option of |hyperref| tells it to put a link also
+in the page number corresponding to a given toc entry). The
+table of contents of the present document are fully linked.
+
+\etoc has not been tested with other packages than those
+cited. It has been tested to work as expected with the
+|article|, |book| and |scrartcl| document classes.
+
+
+
+\subsection{\TeX nical matters}
+
+The \csa{etocname}, \csa{etocnumber}, \csa{etocpage} and
+\csa{etocifnumbered} macros are protected against premature
+expansion. The macro \csa{etocsetstyle}, as well as
+\csa{etocsetlevel} and the global style commands
+\csa{etocmulticolstyle}, \csa{etocruledstyle} and
+\csa{etocframedstyle} obey \LaTeX{}'s groups.
+
+
+\subsection{Errors and catastrophes}
+
+After adding TOCs here and there, with plenty of labels and
+references, perhaps the \LaTeX{} compilation will complain.
+Try running once more to see what happens, the problem could
+go away. In certain extreme cases (\emph{e.g.}, removing the
+use of package |hyperref| from the document), one must trash
+the previous |.aux| and |.toc| files. And as usual with toc
+and labels, after each change, one has to run latex a
+certain number of times to let the produced document get its
+final appearance.
+
+
+\part{The code}
+
+
+This source file |etoc.dtx| outputs \emph{directly and
+ systematically} the package file |etoc.sty| when one does
+|latex etoc.dtx| or |pdflatex etoc.dtx| (an |etoc.ins| file is
+also produced, for distributions expecting it for
+installation). Two more runs are necessary to finish producing
+the documentation. The |etoc.sty| file should be moved to a
+suitable location within the \TeX{} distribution.
+
+\section{Implementation}
+
+\makeatletter
+\StopEventually{\check@checksum\end{document}}
+\makeatother
+
+Writing-up source code comments is hopefully for a future
+release.
+
+% I don't want to have to type explicitly the package version number
+% and version date. I cut out this from the real macrocode environment,
+% leaving out for example the \init@crossref.
+\makeatletter
+\begingroup
+\topsep\MacrocodeTopsep
+\trivlist\parskip\z@\item[]
+\macro@font
+\leftskip\@totalleftmargin \advance\leftskip\MacroIndent
+\rightskip\z@ \parindent\z@ \parfillskip\@flushglue
+\global\@newlistfalse \global\@minipagefalse
+\ifcodeline@index
+ \everypar{\global\advance\c@CodelineNo\@ne
+ \llap{\theCodelineNo\ \hskip\@totalleftmargin}}%
+\fi
+\string\ProvidesPackage\string{\pkgname\string}\par
+\noindent\space [\pkgdate\space\pkgversion\space\pkgdescription]\par
+\nointerlineskip
+\global\@inlabelfalse
+\endtrivlist
+\endgroup
+\makeatother
+
+% The catcode hackery next is to avoid to have <*package> to be listed
+% in the commented source code...
+% (c) 2012/11/19 jf burnol ;-)
+
+\MakePercentIgnore
+
+%
+% \catcode`\<=0 \catcode`\>=11 \catcode`\*=11 \catcode`\/=11
+% \let</none>\relax
+% \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12}
+%
+%</none>
%<*package>
+% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
-%
\RequirePackage{multicol}
\RequirePackage{xspace}
\DeclareOption*{\PackageWarning{etoc}{Option `\CurrentOption' is unknown.}}
\ProcessOptions\relax
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newtoks\Etoc@toctoks
\newif\ifEtoc@j % part
\newif\ifEtoc@ % chapter
@@ -989,13 +1563,18 @@ etoc-skip-first-pre-fix}
\newif\ifEtoc@star
\newif\ifEtoc@standard
\newif\ifEtoc@part
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newif\ifEtoc@localtoc
\newif\ifEtoc@skipthisone
\newif\ifEtoc@stoptoc
\newif\ifEtoc@notactive
-\newcounter{etoc@localtocid}
-%
+\newcounter{etoc@tocid}
+\newif\ifEtoc@mustclosegroup
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\let\Etoc@@minusone@@\m@ne
\chardef\Etoc@@zero@@\z@
\chardef\Etoc@@one@@\@ne
@@ -1012,12 +1591,16 @@ etoc-skip-first-pre-fix}
\def\Etoc@@three@{three}
\def\Etoc@@four@{four}
\def\Etoc@@five@{five}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@Lazarus{%
\def\Etoc@Lazarus@elta##1\Etoc@Lazarus@eltb##2{\let##1##2}%
\Etoc@Lazaruslist}
\def\Etoc@Lazaruslist{}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@newdisciple#1#2{%
\def\Etoc@Lazarus@elta{\noexpand\Etoc@Lazarus@elta\noexpand}%
\def\Etoc@Lazarus@eltb{\noexpand\Etoc@Lazarus@eltb\noexpand}%
@@ -1073,7 +1656,9 @@ etoc-skip-first-pre-fix}
\etocsetlevel{subsubsection}{3}
\etocsetlevel{paragraph}{4}
\etocsetlevel{subparagraph}{5}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\AtBeginDocument{%
\def\Etoc@Lazarus@elta#1\Etoc@Lazarus@eltb#2{\let#2#1\let#1\Etoc@lxyz}%
\Etoc@Lazaruslist
@@ -1084,7 +1669,9 @@ etoc-skip-first-pre-fix}
\def\Etoc@et@hop#1#2#3#4#5{#1{#3}{#4}{#5}#2}}
{\Etoc@hyperreffalse
\def\Etoc@et@hop#1#2#3#4{#1{#3}{#4}#2}}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@swa#1{%
\Etoc@et@hop
{\Etoc@savedcontentsline{#1}}
@@ -1094,31 +1681,9 @@ etoc-skip-first-pre-fix}
{\Etoc@savedcontentsline{#1}}
{\Etoc@contents}}
\let\etocskipfirstprefix\@thirdofthree
-%
-\def\etoc@startlocaltoc#1{%
-\let\Etoc@next\relax
- \ifEtoc@localtoc
- \ifEtoc@notactive
- \ifnum #1<\c@etoc@localtocid\relax
- \else
- \ifEtoc@j \global\let\Etoc@localtop\Etoc@@zero@@ \fi
- \ifEtoc@ \global\let\Etoc@localtop\Etoc@@one@@ \fi
- \ifEtoc@i \global\let\Etoc@localtop\Etoc@@two@@ \fi
- \ifEtoc@ii \global\let\Etoc@localtop\Etoc@@three@@ \fi
- \ifEtoc@iii \global\let\Etoc@localtop\Etoc@@four@@ \fi
- \ifEtoc@iv \global\let\Etoc@localtop\Etoc@@five@@ \fi
- \ifEtoc@v \global\let\Etoc@localtop\Etoc@@six@@ \fi
- \def\Etoc@next{\global\Etoc@notactivefalse
- \global\Etoc@vfalse
- \global\Etoc@ivfalse
- \global\Etoc@iiifalse
- \global\Etoc@iifalse
- \global\Etoc@ifalse
- \global\Etoc@false
- \global\Etoc@jfalse}%
- \fi
- \fi\fi
-\Etoc@next}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@setflags #1{%
\ifcase #1\relax
\global\Etoc@vfalse
@@ -1156,6 +1721,9 @@ etoc-skip-first-pre-fix}
\global\Etoc@false
\global\Etoc@jtrue
\fi}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@etoccontentsline#1{%
\global\expandafter\let\expandafter\Etoc@tmp\csname Etoc@#1@@\endcsname
\global\Etoc@partfalse
@@ -1238,27 +1806,35 @@ etoc-skip-first-pre-fix}
\fi\fi
\Etoc@next
\@firstoftwo{\Etoc@swa{#1}}{\Etoc@swb{#1}}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@lxyz #1#2{\global\@namedef{etocname }{\leavevmode #1\xspace}%
\global\@namedef{etocpage }{\leavevmode #2\xspace}%
\Etoc@getnb #1\relax\relax\etoc@
\ifEtoc@number\else\ifEtoc@part
\Etoc@getit #1\hspace\relax\etoc@\fi\fi}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@getnb #1{\let\Etoc@next\Etoc@getnb@nohyp
\ifEtoc@hyperref\ifx #1\hyper@linkstart
\let\Etoc@next\Etoc@getnb@hyp\fi\fi\Etoc@next #1}
\def\Etoc@getit #1{\let\Etoc@next\Etoc@getit@nohyp
\ifEtoc@hyperref\ifx #1\hyper@linkstart
\let\Etoc@next\Etoc@getit@hyp\fi\fi\Etoc@next #1}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@getnb@nohyp #1#2#3\etoc@{%
\ifx #1\numberline
\global\@namedef{etocnumber }{\leavevmode #2\xspace}\global\Etoc@numbertrue
\else
\global\@namedef{etocnumber }{\leavevmode\xspace}\global\Etoc@numberfalse
\fi}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@getnb@hyp #1#2#3#4#5#6\etoc@{%
\def\Etoc@getnbr ##1##2##3\etoc@{%
\ifx ##1\numberline
@@ -1269,7 +1845,9 @@ etoc-skip-first-pre-fix}
\global\Etoc@numberfalse
\fi}%
\Etoc@getnbr #4\relax\relax\etoc@}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@getit@nohyp #1\hspace#2#3\etoc@{%
\def\Etoc@getname ##1\hspace\relax\etoc@{%
\global\@namedef{etocname }{\leavevmode ##1\xspace}}%
@@ -1277,7 +1855,9 @@ etoc-skip-first-pre-fix}
\global\@namedef{etocnumber }{\leavevmode #1\xspace}%
\global\Etoc@numbertrue
\Etoc@getname #3\etoc@\fi}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@getit@hyp #1#2#3#4#5#6\etoc@{%
\def\Etoc@getname ##1\hspace\relax\etoc@{%
\global\@namedef{etocname }{\leavevmode #1{#2}{#3}{##1}#5}\xspace}%
@@ -1287,20 +1867,28 @@ etoc-skip-first-pre-fix}
\global\Etoc@numbertrue
\Etoc@getname ##3\etoc@\fi}%
\Etoc@getnbr #4\hspace\relax\etoc@}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\edef\etocpage{\noexpand\protect\expandafter\noexpand
\csname etocpage \endcsname}
\edef\etocname{\noexpand\protect\expandafter\noexpand
\csname etocname \endcsname}
\edef\etocnumber{\noexpand\protect\expandafter\noexpand
\csname etocnumber \endcsname}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\@namedef{etocifnumbered }{\ifEtoc@number
\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\edef\etocifnumbered{\noexpand\protect\expandafter\noexpand
\csname etocifnumbered \endcsname}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@readtoc#1{%
\ifeof #1
\let\Etoc@nextread\@gobble
@@ -1312,7 +1900,9 @@ etoc-skip-first-pre-fix}
\fi
\Etoc@nextread{#1}%
}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\Etoc@starttoc{%
\begingroup
\makeatletter
@@ -1334,7 +1924,9 @@ etoc-skip-first-pre-fix}
\if@filesw \newwrite \tf@toc \immediate
\openout \tf@toc \jobname .toc\relax \fi
\endgroup}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\AtBeginDocument{\Etoc@starttoc}
\def\Etoc@toctoc{%
\ifEtoc@standard
@@ -1366,27 +1958,109 @@ etoc-skip-first-pre-fix}
\global\Etoc@ifalse
\global\Etoc@false
\global\Etoc@jfalse}
-%
-\def\tableofcontents{\@ifstar{%
-\stepcounter{etoc@localtocid}%
-\global\Etoc@localtoctrue
-\global\let\Etoc@localtop\m@ne
-\global\Etoc@stoptocfalse
-\global\Etoc@notactivetrue
-\addtocontents{toc}{\string\etoc@startlocaltoc
-\string{\arabic{etoc@localtocid}\string}}%
-\Etoc@tableofcontents
-\global\Etoc@notactivefalse
-\global\Etoc@stoptocfalse
-\global\Etoc@localtocfalse}
-{\Etoc@tableofcontents}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
+\def\etoc@@startlocaltoc#1#2{%
+\let\Etoc@next\relax
+ \ifEtoc@localtoc
+ \ifEtoc@notactive
+ \ifnum #1=#2\relax
+ \ifEtoc@j \global\let\Etoc@localtop\Etoc@@zero@@ \fi
+ \ifEtoc@ \global\let\Etoc@localtop\Etoc@@one@@ \fi
+ \ifEtoc@i \global\let\Etoc@localtop\Etoc@@two@@ \fi
+ \ifEtoc@ii \global\let\Etoc@localtop\Etoc@@three@@ \fi
+ \ifEtoc@iii \global\let\Etoc@localtop\Etoc@@four@@ \fi
+ \ifEtoc@iv \global\let\Etoc@localtop\Etoc@@five@@ \fi
+ \ifEtoc@v \global\let\Etoc@localtop\Etoc@@six@@ \fi
+ \def\Etoc@next{\global\Etoc@notactivefalse
+ \global\Etoc@vfalse
+ \global\Etoc@ivfalse
+ \global\Etoc@iiifalse
+ \global\Etoc@iifalse
+ \global\Etoc@ifalse
+ \global\Etoc@false
+ \global\Etoc@jfalse}%
+ \fi
+ \fi\fi
+\Etoc@next}
+\def\etoc@startlocaltoc#1{\etoc@@startlocaltoc{#1}{\c@etoc@tocid}}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
+\def\Etoc@getrefno #1#2\etoc@{#1}
+\def\Etoc@getref #1{\@ifundefined{r@#1}{0}{\expandafter\expandafter\expandafter
+ \Etoc@getrefno\csname r@#1\endcsname\relax\etoc@}}
+\def\Etoc@ref#1{\Etoc@localtoctrue
+ \Etoc@localtableofcontents{\Etoc@getref{#1}}}
+\def\Etoc@label#1{\label{#1}\futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
+{\def\1{\Etoc@again}\expandafter
+\gdef\1 {\futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
+\def\Etoc@t@bleofcontents{%
+ \ifx\Etoc@nexttoken\label
+ \def\Etoc@next{\expandafter\Etoc@label\@gobble}\else
+ \ifx\Etoc@nexttoken\@sptoken
+ \let\Etoc@next\Etoc@again\else
+ \ifEtoc@localtoc
+ \def\Etoc@next{\Etoc@localtableofcontents{\c@etoc@tocid}}%
+ \else
+ \ifx\Etoc@nexttoken\ref
+ \def\Etoc@next{\expandafter\Etoc@ref\@gobble}%
+ \else
+ \def\Etoc@next{\begingroup\Etoc@tableofcontents
+ \ifEtoc@mustclosegroup\expandafter\endgroup\fi
+ \endgroup\Etoc@mustclosegroupfalse}%
+ \fi
+ \fi\fi\fi\Etoc@next}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
+\long\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
+ \let\Etoc@next\@gobble\else\let\Etoc@next\@firstofone\fi
+ \Etoc@next
+ {\begingroup
+ \edef\etoc@startlocaltoc##1{%
+ \noexpand\etoc@@startlocaltoc{##1}{#1}}
+ \Etoc@localtoctrue
+ \let\Etoc@localtop\m@ne
+ \Etoc@stoptocfalse
+ \Etoc@notactivetrue
+ \Etoc@tableofcontents
+ \endgroup}%
+ \ifEtoc@mustclosegroup\expandafter\endgroup\fi
+ \Etoc@mustclosegroupfalse}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
+\def\tableofcontents{\par\refstepcounter{etoc@tocid}%
+ \@ifstar {\addtocontents{toc}
+ {\string\etoc@startlocaltoc\string{\arabic{etoc@tocid}\string}}%
+ \Etoc@localtoctrue
+ \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}
+ {\Etoc@localtocfalse
+ \futurelet\Etoc@nexttoken\Etoc@t@bleofcontents}}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocsettocstyle[2]{%
\long\def\Etoc@tableofcontents
{\ifnum\c@tocdepth>-2\let\Etoc@@next\@firstofone\else
\let\Etoc@@next\@gobble\fi
-\Etoc@@next{\begingroup #1\Etoc@toctoc #2\endgroup}}}
-%
+\Etoc@@next{#1\Etoc@toctoc
+ \Etoc@localtocfalse
+ \ifEtoc@notactive \expandafter\Etoc@toctoc\fi
+ #2}}}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocsetstyle[5]{%
\long\expandafter\def
\csname Etoc@begin@\csname Etoc@#1@\endcsname\endcsname {#2}%
@@ -1396,9 +2070,13 @@ etoc-skip-first-pre-fix}
\csname Etoc@contents@\csname Etoc@#1@\endcsname\endcsname {#4}%
\long\expandafter\def
\csname Etoc@end@\csname Etoc@#1@\endcsname\endcsname {#5}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\etocstandardlines{\Etoc@standardtrue}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocfontminusone{\normalfont \large \bfseries}
\newcommand\etocfontzero{\normalfont \normalsize \bfseries}
\newcommand\etocfontone{\normalfont \normalsize \bfseries}
@@ -1406,26 +2084,36 @@ etoc-skip-first-pre-fix}
\newcommand\etocfontthree{\normalfont \footnotesize}
\newcommand\etocfontfour{\normalfont \footnotesize}
\newcommand\etocfontfive{\normalfont \footnotesize}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\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}
\newcommand\etocsepthree{.25ex \@plus .05ex \@minus .05ex}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocbaselinespreadminusone{1}
\newcommand\etocbaselinespreadzero{1}
\newcommand\etocbaselinespreadone{1}
\newcommand\etocbaselinespreadtwo{1}
\newcommand\etocbaselinespreadthree{.9}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocminusonelrmargins{1em}
\newcommand\etoctoclineleaders
-{\hbox{\normalfont\normalsize\hbox to 2ex {\hfil.\hfil}}}
+{\hbox{\normalfont\normalsize\hbox to 2ex {\hss.\hss}}}
\newcommand\etocabbrevpagename{p.~}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\etocetoclines{\Etoc@standardfalse
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocsetstyle{@minusone}{\addpenalty\@highpenalty}{}
{\begingroup \etocfontminusone
\addvspace{\etocsepminusone}%
@@ -1449,7 +2137,9 @@ etoc-skip-first-pre-fix}
\addvspace{\etocsepone}\addpenalty\@itempenalty
\endgroup}
{\addpenalty\@secpenalty}%
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocsetstyle{@one}
{\addpenalty\@medpenalty}
{}
@@ -1479,7 +2169,9 @@ etoc-skip-first-pre-fix}
\addvspace{\etocseptwo}\addpenalty\@itempenalty
\endgroup}
{\addpenalty\@secpenalty}%
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocsetstyle{@two}
{\addpenalty\@medpenalty}
{}
@@ -1509,7 +2201,9 @@ etoc-skip-first-pre-fix}
\addvspace{\etocsepthree}\addpenalty\@itempenalty
\endgroup}
{\addpenalty\@secpenalty}%
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocsetstyle{@three}
{\nobreak
\etocfontthree
@@ -1522,12 +2216,18 @@ etoc-skip-first-pre-fix}
\baselineskip\etocbaselinespreadthree\baselineskip
\par\endgroup
\addpenalty{-\@highpenalty}}%
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocsetstyle{@four}{}{}{}{}%
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocsetstyle{@five}{}{}{}{}%
}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocmarkboth[1][\contentsname]{%
\@mkboth {\MakeUppercase #1}
{\MakeUppercase #1}}
@@ -1547,7 +2247,9 @@ etoc-skip-first-pre-fix}
\@ifclassloaded{report}{%
\let\etoc@standard@tochead\etoc@book@tochead
\let\etoc@standard@tochead@nomarks\etoc@book@tochead@nomarks}{}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocstandardheading[1]{%
\etoc@standard@tochead{#1}}
\newcommand\etocstandardheadingnomarks[1]{%
@@ -1559,7 +2261,9 @@ etoc-skip-first-pre-fix}
\newcommand\etocmulticolsep{0ex}
\newcommand\etocmulticolpretolerance{-1}
\newcommand\etocmulticoltolerance{200}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocmulticolstyle[2][2]{%
\etocsettocstyle
{\addvspace{\etocabovetocskip}%
@@ -1577,7 +2281,9 @@ etoc-skip-first-pre-fix}
\else \let\Etoc@next\@gobble\fi
\Etoc@next{\end{multicols}}%
\addvspace{\etocbelowtocskip}}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocinnertopsep{2ex}
\newcommand\etocinnerbottomsep{3.5ex}
\newcommand\etocinnerleftsep{2em}
@@ -1590,15 +2296,19 @@ etoc-skip-first-pre-fix}
\newcommand\etocbottomrulecolorcmd{\relax}
\newcommand\etocleftrulecolorcmd{\relax}
\newcommand\etocrightrulecolorcmd{\relax}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etoc@ruledheading[1]{%
- \hbox to \linewidth{%
- \hfil #1\hfil\hskip-\linewidth
- {\etoctoprulecolorcmd\leaders\etoctoprule\hfil}%
+ \hbox to \linewidth{\color@begingroup
+ \hss #1\hss\hskip-\linewidth
+ \etoctoprulecolorcmd\leaders\etoctoprule\hfil
\phantom{#1}%
- {\etoctoprulecolorcmd\leaders\etoctoprule\hfil}}%
+ \leaders\etoctoprule\hss\color@endgroup}%
\nointerlineskip\vskip\etocinnertopsep}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etocruledstyle[2][2]{%
\etocsettocstyle
{\addvspace{\etocabovetocskip}%
@@ -1617,31 +2327,39 @@ etoc-skip-first-pre-fix}
\else \let\Etoc@next\@gobble\fi
\Etoc@next{\end{multicols}}%
\addvspace{\etocbelowtocskip}}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
+\newcommand\etocframedmphook{\relax}
+\newcommand\etocframedbkgcolorcmd{\relax}
+\newbox\etoc@framed@titlebox
+\newbox\etoc@framed@contentsbox
\newcommand\etocframedstyle[2][2]{%
\etocsettocstyle{%
\addvspace{\etocabovetocskip}%
- \sbox\z@{#2}\dimen\z@\dp\z@
- \ifdim\wd\z@<\linewidth\dp\z@\z@\else\dimen\z@\z@\fi
- \hbox to \linewidth{%
- \hfil\copy\z@\hfil\hskip-\linewidth
- {\etoctoprulecolorcmd\leaders\etoctoprule\hfil}%
- \phantom{\box\z@}%
- {\etoctoprulecolorcmd\leaders\etoctoprule\hfil}}%
- \nointerlineskip\nobreak
- \hbox to \linewidth
- \bgroup
- {\etocleftrulecolorcmd\etocleftrule}%
- \kern\etocinnerleftsep
- \vbox\bgroup
+ \setbox\z@\hbox{#2}%
+ \dimen\z@\dp\z@
+ \ifdim\wd\z@<\linewidth \dp\z@\z@ \else \dimen\z@\z@ \fi
+ \setbox\etoc@framed@titlebox=\hbox to \linewidth{\color@begingroup
+ \hss{\etocframedbkgcolorcmd
+ \vrule\@width\wd\z@\@height\ht\z@\@depth\dp\z@}%
+ \hskip-\wd\z@
+ \copy\z@\hss
+ \hskip-\linewidth
+ \etoctoprulecolorcmd\leaders\etoctoprule\hss%
+ \hskip\wd\z@
+ \etoctoprulecolorcmd\leaders\etoctoprule\hss\color@endgroup}%
+ \setbox\z@\hbox{\etocleftrule\etocrightrule}%
+ \dimen\tw@\linewidth\advance\dimen\tw@-\wd\z@
+ \advance\dimen\tw@-\etocinnerleftsep
+ \advance\dimen\tw@-\etocinnerrightsep
+ \setbox\etoc@framed@contentsbox=\vbox\bgroup
+ \hsize\dimen\tw@
\kern\dimen\z@
\vskip\etocinnertopsep
\hbox\bgroup
- \setbox\z@\hbox{\etocleftrule\etocrightrule}%
- \dimen\z@\linewidth\advance\dimen\z@-\wd\z@
- \advance\dimen\z@-\etocinnerleftsep
- \advance\dimen\z@-\etocinnerrightsep
- \begin{minipage}{\dimen\z@}
+ \begin{minipage}{\hsize}%
+ \etocframedmphook
\ifnum #1>\@ne\let\Etoc@next\@firstoftwo
\else \let\Etoc@next\@secondoftwo\fi
\Etoc@next
@@ -1649,71 +2367,119 @@ etoc-skip-first-pre-fix}
\multicoltolerance\etocmulticoltolerance
\setlength{\columnsep}{\etoccolumnsep}%
\setlength{\multicolsep}{\etocmulticolsep}%
- \begin{multicols}{#1}}
+ \begin{multicols}{#1}}
{\pretolerance\etocmulticolpretolerance
\tolerance\etocmulticoltolerance}}
{\ifnum #1>\@ne\let\Etoc@next\@firstofone
\else \let\Etoc@next\@gobble\fi
\Etoc@next{\end{multicols}\unskip}%
- \end{minipage}\egroup
+ \end{minipage}%<- indispensable (horizontal mode here)
+ \egroup
\vskip\etocinnerbottomsep
- \egroup\kern\etocinnerrightsep
- \etocrightrulecolorcmd\etocrightrule\egroup
- \nointerlineskip\nobreak
- \hbox to \linewidth{\etocbottomrulecolorcmd
- \leaders\etocbottomrule\hfill}
+ \egroup
+ \vskip\ht\etoc@framed@titlebox
+ \vskip\dp\etoc@framed@titlebox
+ \hbox to \linewidth{\color@begingroup
+ \etocleftrulecolorcmd\etocleftrule
+ \etocframedbkgcolorcmd
+ \leaders\vrule
+ \@height\ht\etoc@framed@contentsbox
+ \@depth\dp\etoc@framed@contentsbox
+ \hss
+ \etocrightrulecolorcmd\etocrightrule
+ \color@endgroup}
+ \nointerlineskip
+ \vskip-\dp\etoc@framed@contentsbox
+ \vskip-\ht\etoc@framed@contentsbox
+ \vskip-\dp\etoc@framed@titlebox
+ \vskip-\ht\etoc@framed@titlebox
+ \box\etoc@framed@titlebox\nointerlineskip
+ \hbox to \linewidth{\color@begingroup
+ {\etocleftrulecolorcmd\etocleftrule}%
+ \hss\box\etoc@framed@contentsbox\hss
+ \etocrightrulecolorcmd\etocrightrule\color@endgroup}
+ \nointerlineskip
+ \vskip\ht\etoc@framed@contentsbox
+ \vskip\dp\etoc@framed@contentsbox
+ \hbox to \linewidth{\color@begingroup\etocbottomrulecolorcmd
+ \leaders\etocbottomrule\hss\color@endgroup}
\addvspace{\etocbelowtocskip}}}
-%
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etoc@multicoltoc[2][2]{%
\begingroup
-\ifnum\c@tocdepth>-2\relax
\etocmulticolstyle[#1]{#2}%
\ifEtoc@star
\def\Etoc@next{\tableofcontents*}%
- \else\def\Etoc@next{\tableofcontents}%
+ \else
+ \def\Etoc@next{\tableofcontents}%
\fi
-\Etoc@next
-\fi\endgroup}
-%
+\Etoc@mustclosegrouptrue
+\Etoc@next}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etoc@ruledtoc[2][2]{%
\begingroup
-\ifnum\c@tocdepth>-2\relax
\etocruledstyle[#1]{#2}%
\ifEtoc@star
\def\Etoc@next{\tableofcontents*}%
\else
\def\Etoc@next{\tableofcontents}%
\fi
-\Etoc@next
-\fi\endgroup}
-%
+\Etoc@mustclosegrouptrue
+\Etoc@next}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\newcommand\etoc@framedtoc[2][2]{%
\begingroup
-\ifnum\c@tocdepth>-2\relax
\etocframedstyle[#1]{#2}%
\ifEtoc@star
\def\Etoc@next{\tableofcontents*}%
\else
\def\Etoc@next{\tableofcontents}%
\fi
-\Etoc@next
-\fi\endgroup}
-%
+\Etoc@mustclosegrouptrue
+\Etoc@next}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\def\etocmulticol{\@ifstar{\global\Etoc@startrue\etoc@multicoltoc}
-{\global\Etoc@starfalse\etoc@multicoltoc}}
+{\Etoc@starfalse\etoc@multicoltoc}}
\def\etocruled{\@ifstar{\global\Etoc@startrue\etoc@ruledtoc}
-{\global\Etoc@starfalse\etoc@ruledtoc}}
+{\Etoc@starfalse\etoc@ruledtoc}}
\def\etocframed{\@ifstar{\global\Etoc@startrue\etoc@framedtoc}
-{\global\Etoc@starfalse\etoc@framedtoc}}
-%
+{\Etoc@starfalse\etoc@framedtoc}}
+% \end{macrocode}
+% placeholder for comments
+% \begin{macrocode}
\etocetoclines
\etocmulticolstyle{\etocstandardheading\contentsname}
\endinput
-%</package>
% \end{macrocode}
-% \clearpage
-% \Finale
-% \endinput
-\endinput
+% \MakePercentComment
+%</package>
+\CharacterTable
+ {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+ Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+ Digits \0\1\2\3\4\5\6\7\8\9
+ Exclamation \! Double quote \" Hash (number) \#
+ Dollar \$ Percent \% Ampersand \&
+ Acute accent \' Left paren \( Right paren \)
+ Asterisk \* Plus \+ Comma \,
+ Minus \- Point \. Solidus \/
+ Colon \: Semicolon \; Less than \<
+ Equals \= Greater than \> Question mark \?
+ Commercial at \@ Left bracket \[ Backslash \\
+ Right bracket \] Circumflex \^ Underscore \_
+ Grave accent \` Left brace \{ Vertical bar \|
+ Right brace \} Tilde \~}
+
+\CheckSum{2056}
+
+\Finale
%%
%% End of file `etoc.dtx'.
+
diff --git a/Master/texmf-dist/source/latex/etoc/etoc.ins b/Master/texmf-dist/source/latex/etoc/etoc.ins
index 08cae55ff24..fec7217a6a3 100644
--- a/Master/texmf-dist/source/latex/etoc/etoc.ins
+++ b/Master/texmf-dist/source/latex/etoc/etoc.ins
@@ -1,31 +1,30 @@
%% Package `etoc' by Jean-Francois Burnol
+%% Copyright (C) 2012 by Jean-Francois Burnol
+\def\pkgname{etoc}
+\def\pkgdate{2012/11/23}
+\def\pkgversion{v1.03}
+\def\pkgdescription{easily customizable TOCs (jfB)}
%%
-%% This file `etoc.ins' is provided for compatibility reasons with
-%% TeX installations expecting to find an .ins file
+%% This file `etoc.ins' is provided for compatibility with TeX distributions
+%% expecting to find it for installation of `etoc.sty'.
%%
-%% It can be used as usual:
+%% As usual `latex etoc.ins' produces `etoc.sty' from the source `etoc.dtx'
+%% (an already existing etoc.sty in the same repertory will be overwritten)
%%
-%% `latex etoc.ins' extracts `etoc.sty' from `etoc.dtx'
+%% Put the `etoc.sty' file in a suitable location within the TeX installation:
+%% etoc.sty -> ................/tex/latex/etoc/
%%
-%% But doing directly `latex etoc.dtx' already creates `etoc.sty'
+%% The generated auxiliary files may be discarded. See `etoc.dtx' for the
+%% statements of copyright and conditions of distribution or modification.
%%
-%% `latex etoc.dtx' generates `etoc.sty' (and also `etoc.ins')
-%% `latex etoc.dtx' finishes generating the documentation
-%%
-%% In all cases, put the generated `etoc.sty' file in a suitable
-%% location within the TeX installation:
-%% etoc.sty -> ................/tex/latex/etoc/
-%%
-%% Generated auxiliary files may then be discarded.
-%%
-\def\batchfile{etoc.ins}
\input docstrip.tex
\askforoverwritefalse
-\def\jfpreamble{\defaultpreamble^^J\MetaPrefix^^J%
-\string\ProvidesPackage{etoc}^^J%
-\space[2012/11/18\space v1.02\space easily customizable TOCs (jfB)]}
-\def\jfpostamble{\MetaPrefix\space End of file `\outFileName'.}
-\generate{\usepreamble\jfpreamble
-\file{etoc.sty}{\from{etoc.dtx}{package}}
-\usepostamble\jfpostamble}
+\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
+\string\ProvidesPackage{\pkgname}^^J%
+\space[\pkgdate\space\pkgversion\space\pkgdescription]}
+\generate{\usepreamble\pkgpreamble
+\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}
\endbatchfile
+\endinput
+%%
+%% End of file `etoc.ins'.