From 679b7aae1d05f86896ae878fc71b4b541fc57d9b Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Wed, 23 Oct 2013 00:12:59 +0000
Subject: etoc (21oct13)

git-svn-id: svn://tug.org/texlive/trunk@31965 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/etoc/etoc.dtx | 697 ++++++++++++++-------------
 1 file changed, 354 insertions(+), 343 deletions(-)

(limited to 'Master/texmf-dist/source/latex/etoc/etoc.dtx')

diff --git a/Master/texmf-dist/source/latex/etoc/etoc.dtx b/Master/texmf-dist/source/latex/etoc/etoc.dtx
index 161527f9037..6ee6770d15a 100644
--- a/Master/texmf-dist/source/latex/etoc/etoc.dtx
+++ b/Master/texmf-dist/source/latex/etoc/etoc.dtx
@@ -1,8 +1,8 @@
 % -*- coding: iso-latin-1; -*-
 %<*!package>
-\def\pkgname {etoc} \def\pkgdate {2013/10/16} \def\pkgversion {v1.07h}
+\def\pkgname {etoc} \def\pkgdate {2013/10/21} \def\pkgversion {v1.07i}
 \def\pkgdescription {Completely customisable TOCs (jfB)}
-\def\doctimestamp {Time-stamp <16-10-2013 22:11:00 CEST *>}
+\def\doctimestamp {Time-stamp <21-10-2013 18:35:52 CEST *>}
 %</!package>
 %%
 %% Package: etoc
@@ -612,83 +612,36 @@ pdfpagemode=UseOutlines}
   Simpler ones are given as examples in the documentation. The
   simplest usage will be to take advantage of the layout facilities
   of packages dealing with list environments.
+  
+   Regarding the \emph{global toc
+    display}, \etoc provides pre-defined styles based on a
+  multi-column format, with, optionally,  a ruled
+  title or framed contents.
+
+  The \csa{tableofcontents} command may be used arbitrarily many times and it
+  has a variant \csa{localtableofcontents} which prints tables of contents
+  `local' to the current surrounding document unit. An extension of the
+  \csa{label}/\csa{ref} syntax allows to reproduce (with another layout) a local
+  table of contents defined somewhere else in the document.
 
-  The \csa{tableofcontents} command may be used arbitrarily
-  many times and it has a variant \csa{localtableofcontents}
-  which prints tables of contents `local' to the current
-  surrounding document unit. An extension of the
-  \csa{label}/\csa{ref} syntax allows to reproduce (with another
-  layout) a TOC defined somewhere else in the document.
+  Via ``depth tags'', one gets an even finer control for each table of contents
+  of which sectioning units it should, or not, display.
 
   The formatting inherited (and possibly customized by other
-  packages) from the document class may also be used in
-  \emph{compatibility mode}. Regarding the \emph{global toc
-    display}, \etoc provides pre-defined styles based on a
-  multi-column format, optionally with a frame or a ruled
-  title.
-
-  As the assignment of levels to the sectioning units can be changed at any
-  time, \etoc can be used in a quite general manner to also create custom
-  ``lists of'', additionally to the tables of contents related to the document
-  sectioning units. No auxiliary file is used additionally to the standard
-  |.toc| file.
+  packages) from the document class will be used when in
+  \emph{compatibility mode}.
+
+  The assignment of levels to the sectioning units can be changed at any
+  time, and \etoc can thus be used in a quite general manner to
+  create custom ``lists of'', additionally to the tables of contents
+  related to the document sectioning units. No auxiliary file is used
+  additionally to the standard |.toc| file.
 \end{abstract}
 
 \small 
 
 \etocdepthtag.toc {preamble}
 
-\section{License, installation}
-
-\begin{verbatim}
-% Copyright (C) 2012-2013 by Jean-Francois Burnol <jfbu at free dot fr>
-%
-%     This Work may be distributed and/or modified under the
-%     conditions of the LaTeX Project Public License, either
-%     version 1.3c of this license or (at your option) any later
-%     version. This version of this license is in 
-%          http://www.latex-project.org/lppl/lppl-1-3c.txt
-%     and the latest version of this license is in
-%          http://www.latex-project.org/lppl.txt
-%     and version 1.3 or later is part of all distributions of
-%     LaTeX version 2005/12/01 or later. 
-%
-% This Work has the LPPL maintenance status Author-Maintained.
-%
-% The Author of this Work is 
-%        Jean-Francois Burnol <jfbu at free dot fr>. 
-% 
-% This Work consists of the main source file etoc.dtx and the 
-% derived files etoc.sty, etoc.dvi, etoc.pdf, etoc.ins, etoc.tex
-%
-% Extraction of the package (.sty) and driver (.tex) files:
-%  - if etoc.ins is present:   tex etoc.ins
-%  - without etoc.ins:         tex etoc.dtx 
-%
-% It is also possible to run latex/pdflatex directly on etoc.dtx
-%
-% At least three ways to produce etoc.pdf:
-%  (1) latex etoc.dtx (three times), then dvips, then ps2pdf
-%  (2) pdflatex etoc.dtx (three times)
-%  (3) latex etoc.tex (three times), then dvipdfmx
-%
-% Method (3) produces the smallest pdf files.
-% Options can be set in etoc.tex:
-%  - scrdoc class options (paper size, font size, ...) 
-%  - with or without source code, 
-%  - with dvipdfmx or with latex/pdflatex. 
-%
-% Installation: 
-%
-%   etoc.sty->TDS:tex/latex/etoc/etoc.sty
-%   etoc.dtx->TDS:source/latex/etoc/etoc.dtx
-%   etoc.pdf->TDS:doc/latex/etoc/etoc.pdf
-%
-% etoc.tex, etoc.ins, etoc.aux, etoc.toc, etc... may be discarded
-%
-\end{verbatim}
-
-\normalsize
 
 \section{Foreword}
 
@@ -762,13 +715,15 @@ with the customizing facilities of packages such as
 display the data fetched by \etoc from the |.toc| file. The data
 consists of the \emph{name} (\csb{etocname}), \emph{number}
 (\csb{etocnumber}), and \emph{page number} (\csb{etocpage}) as
-extracted\footnote{although \LaTeX{} has been promoted as
-  separating contents from form, there are some areas where its
-  real implementation is very far from this ideal. And the |.toc|
-  file is a case in point; not to mention the hard-coded
-  dimensions, with use of the @ sign,
-  in the macros responsible for constructing the typeset table of
-  contents.} from the |.toc| file.
+extracted
+% \footnote{although \LaTeX{} has been promoted as
+%   separating contents from form, there are some areas where its
+%   real implementation is very far from this ideal. And the |.toc|
+%   file is a case in point; not to mention the hard-coded
+%   dimensions, with use of the @ sign,
+%   in the macros responsible for constructing the typeset table of
+%   contents.} 
+from the |.toc| file.
 
 This is
 illustrated \hyperref[toc:a]{at the start} of
@@ -779,12 +734,17 @@ customizing! indeed, but the syntax and option names to memorize
 are in no way related only to matters of tables of contents, hence
 an economy of use of the poor brain.
 
-Next in ease of use, perhaps, is the
-method explained \hyperref[sec:firstexample]{later in this part}. For this some
-knowledge of 
-|\leftskip|, |\rightskip|, etc... is necessary. Next, people who
-know the internals of \LaTeX2e well (which is not my case) will
-happily use directly a |\list| command.
+% People who
+% know the internals of \LaTeX2e well (which is not my case) could
+% happily use directly a |\list| command;  
+
+Next in ease of use, perhaps, is the method explained
+\hyperref[sec:firstexample]{later in this part} (\autoref{sec:firstexample}).
+For this some knowledge of |\leftskip|, |\rightskip|, etc... is necessary. And a
+slight elaboration of this method, whose code is to be found in
+\autoref{ssec:tocwithdepthtags}, allows to mimick very well, if so desired, the
+standard looks (but one would need to add to these line styles some suitably
+chosen penalties to reduce the possibilities for bad page breaks in TOCs).
 
 As will be amply illustrated in this manual, \etoc is quite
 versatile (especially as it allows to re-define at any point in
@@ -834,11 +794,13 @@ TOCs, some other commands, such as language changing
 commands, which do not expect to see their scope limited in
 this way inside a group (\LaTeX's environments create groups).
 
-Therefore the built-in ``line styles'' proposed by \etoc as an
-example (and which are illustrated\footnote{with a twist,
-  subsections having been downgraded to the subsubsection
-  style\dots} by the \hyperref[toc:main]{main table of contents}
-in this document) do not make use of environments.
+Therefore the built-in ``line styles'' proposed by \etoc as an example (and
+which are illustrated\footnote{with a twist, subsections having been downgraded
+  to the subsubsection style\dots} by the \hyperref[toc:main]{main table of
+  contents} in this document) do not make use of environments. Actually, in this
+user manual, only the \hyperref[toc:a]{table of contents} at the start of
+\autoref{part:linestyles} and the \autoref{toc:allsubsections} (which is a TOC!)
+have their line styles expressed in terms of enumerate environments.
 
 \section{Line styles and toc display style}
 
@@ -931,7 +893,7 @@ made of \csb{etocstandarddisplaystyle}.
 \section{A first example}
 \label{sec:firstexample}
 
-Let us present it a first example of specification for line styles.
+Let us present a first example of specification for line styles.
 Immediately after the start of \autoref{part:overview} we inserted in the
 source file:
 \centeredline{|\invisiblelocaltableofcontents \label{toc:overview}|} This
@@ -982,20 +944,22 @@ it is responsible for setting its own |\leftskip|.
 \endgroup
 
 
-This is a simple design which does not make provisions for page
-breaks which should be discouraged in-between a section and a
-subsection etc\dots  as we only used it for the table of contents of this part,
-thus with sections as top levels,
-there was no need to specify a style for parts too. The two
-commands used are \csb{etocsetstyle} for specifying the line
-styles, and \csb{etocruledstyle} for the TOC global style. 
+This is a simple design which does not make provisions for page breaks
+which should be discouraged in-between a section and a subsection
+etc\dots{} as we only used it for the table of contents of this part, thus
+with sections as top levels, there was no need to specify a style for
+parts too (we defined a subsubsection line style but as it turns
+out there are no subsubsections in this part). The two commands used are
+\csb{etocsetstyle} for specifying the line styles, and
+\csb{etocruledstyle} for the TOC global style.
 
-The |\rightskip| is shared by all, and creates space where the page numbers get
-printed. We defined also a subsubsection line style but they are no
-subsubsection in this part. See also
-\autoref{ssec:tocwithdepthtags} which provides a TOC also including parts and
-paragraphs and has a technique for putting the page numbers on the right which
-is closer to what \LaTeX2e's |\@dottedtocline| macro does.
+The |\rightskip| is shared by all, and creates space where the page
+numbers get printed. See also
+\autoref{ssec:tocwithdepthtags} which provides a TOC with parts and
+paragraphs, with  multi-line headings as in the standard classes
+layout (and the technique for setting there the page numbers on the right
+is closer than here to what \LaTeX2e's |\@dottedtocline| macro
+does).
 
 
 
@@ -1032,11 +996,12 @@ is closer to what \LaTeX2e's |\@dottedtocline| macro does.
 \section{Linked list of the main package commands}
 % 16 octobre
 
+\begingroup\raggedcolumns
 \advance\linewidth18pt
 \begin{multicols}{3}\parindent0pt\relax
-  \csb{etoctoclines}\par
 \csb{etocstandardlines}\par
 \csb{etocdefaultlines}\par
+  \csb{etoctoclines}\par
   \csb{etocsetstyle}\par
 \csb{etocname}\par
 \csb{etocpage}\par
@@ -1080,11 +1045,11 @@ is closer to what \LaTeX2e's |\@dottedtocline| macro does.
 \csb{etocaftercontentshook}\par
 \csb{etocaftertochook}\par
 \csb{etoctoccontentsline}\par
-\vspace{5\baselineskip}\hrule height 0pt
+%\vspace{5\baselineskip}\hrule height 0pt
 \end{multicols}
-\advance\linewidth-18pt
+\endgroup
+
 
-\vspace{-\baselineskip}
 
 % 15 octobre, je teste les tags
 \etocdepthtag.toc {arbitrarily}
@@ -1094,6 +1059,9 @@ is closer to what \LaTeX2e's |\@dottedtocline| macro does.
 
 \thispartstats
 
+
+\section{Labeling and reusing elsewhere}
+
 \etoc allows arbitrarily many \csa{tableofcontents} commands in
 your document. The line styles and the toc display style may of
 course be changed in-between. Furthermore 
@@ -1102,8 +1070,6 @@ contents: \emph{i.e.} all sections and sub-units inside a
 given chapter, or all subsubsections and lower inside a given
 subsection, etc . . .
 
-\section{Labeling and reusing elsewhere}
-
 \etoc allows the labeling of a TOC with (for example)
 \csa{label\{toc:A\}} and will redisplay it elsewhere when
 told \csa{tableofcontents}\csa{ref\{toc:A\}}. The actual
@@ -1287,7 +1253,7 @@ tables of contents of the sub-sub-sections of a given chapter.
 This
 {\fbox{gets executed in ALL tables of contents.}}
 
-\subsection{The commands \csbhyp{etocobeytoctocdepth}, and \csbhyp{etocignoretoctocdepth}}
+\subsection{The commands \csbhyp{etocobeytoctocdepth} and \csbhyp{etocignoretoctocdepth}}
 \label{etocobeytoctocdepth}
 \label{etocignoretoctocdepth}
 
@@ -1335,7 +1301,7 @@ is anything, and this will put the tag in the |.toc| file. When typesetting a
 TOC, one issues a series of commands
 \csb{etocsettagdepth}\marg{tag\_name}\marg{level} where the \meta{level} may be
 either numeric (from |-3| to |5|) or the name of a division unit known to \etoc,
-or |none| or |all|. The effet of the tag inside the |.toc| file will then be to
+or |none| or |all|. The effect of the tag inside the |.toc| file will then be to
 set the |tocdepth| counter to the desired value, in real time (as mentioned
 already, this can not get finer than the initial value of |tocdepth| at the
 start of the TOC).
@@ -1350,7 +1316,7 @@ surrounding
 environment. For an example, see \autoref{ssec:tocwithdepthtags}.
 
 
-\subsection{The commands \csbhyp{etocobeydepthtags}, and \csbhyp{etocignoredepthtags}}
+\subsection{The commands \csbhyp{etocobeydepthtags} and \csbhyp{etocignoredepthtags}}
 \label{etocobeydepthtags}
 \label{etocignoredepthtags}
 
@@ -1368,7 +1334,7 @@ After \csb{etocignoredepthtags}, the |.toc| depth tags are ignored (but
 \label{sec:addingtotoc}
 
 We described above \csb{etocsettocdepth.toc} and \csb{etocdepthtag.toc} which
-both inserts commands inside the |.toc| file. An even more general mechanism of
+both insert commands inside the |.toc| file. An even more general mechanism of
 adding ``action tags'' to the |.toc| file could be envisioned, but this would
 just be a wrapper for direct use of |\addtocontents{toc}{\something}|.
 
@@ -1528,8 +1494,7 @@ breaks. Also, they do not worry about potential multi-column use.
 Let us now try out some more sophisticated line styles. The
 display will use the \csa{etocframedstyle} package command, which
 requires that the produced table of contents fits on a single
-page.\footnote{using \url{http://ctan.org/pkg/mdframed} one may
-  do similar constructs compatible with pagebreaks.} 
+page.
 We wrap it up in a \hyperref[toc:floating]{figure environment} showing up
 \vpageref{toc:floating}. 
 
@@ -1617,63 +1582,37 @@ is in use also for \hyperref[toc:clone]{this other toc}, and the
 reader is referred to its \hyperref[ssec:tocclone]{subsection} for the
 coding used.
 
-% \vfill\eject
-% \clearpage
 % 11 octobre 2013 ceci était une section avant:
+% (17 octobre, je m'aperçois qu'à cause des différents chgts, des
+% sous-sections devenant des sections etc... \thisspecialstats ici ne
+% faisait pas du tout des statistiques; vaut mieux supprimer et faire
+% simplement \localtableofcontents pour maintenir le même layout.)
 
-\etocdepthtag.toc {surprising}
-
-\part{Surprising uses of \etoc}
-\label{part:surprising}
-
-\thispartstats
-%% (pas de sous-section)
+% les \clearpage sont embêtants; surtout si je prétends qu'on peut
+% recompiler facilement sous d'autres conditions...
 
-% This variant uses macros rather than boxes, which allows greater flexibility.
+% on va plutôt faire un \vspace suffisant, cela sera un moindre mal
 
-\makeatletter
-\newcommand*\firstsubname       {}
-\newcommand*\lastsubname        {}
-\newcommand*\firstsubnumber     {}
-\newcommand*\lastsubnumber      {}
-\newcommand*\thisspecialstatsaux{}
+\vspace{1cm}
 
-\newcommand*{\thisspecialstats}{%
-  \setcounter{mycounti}{0}%
-  \def\thisspecialstatsaux{%
-         \let\firstsubname\etocthelinkedname
-         \let\firstsubnumber\etocthelinkednumber
-         \def\thisspecialstatsaux{}}
-  \begingroup
-  \etocsetstyle{subsection} {} {}
-    {\thisspecialstatsaux
-     \stepcounter{mycounti}%
-     \let\lastsubname\etocthelinkedname
-     \let\lastsubnumber\etocthelinkednumber }
-    {Here are some statistics for this part. It contains \arabic{mycounti}
-      sections. The name of 
-	 its first is 
-     \emph{\firstsubname{}} and the corresponding number is 
-     {\firstsubnumber}. The name of the last section is 
-     \emph{\lastsubname{}} and its number is 
-     {\lastsubnumber}.}% 
-   \etocsettocstyle {}{}
-   \etocinline
-   \etocsetnexttocdepth {1}%
-   \localtableofcontents
-  \endgroup
-}
-\makeatother
+\etocdepthtag.toc {surprising}
+\part{Surprising uses of \etoc}
+\label{part:surprising}
 
+\thispartstats %% (pas de sous-section)
 
-\thisspecialstats
+% in dtx of release 1.07h there was here a \thisspecialstats, but it
+% originated from the period when this \part was only a \section. So its
+% effect was not the intended one, basically it had the same effect as this:
+\etocsetnexttocdepth {section}
+\etocsettocstyle {}{}
+\localtableofcontents
 
 \section{The TOC of TOCs}
 
 \begingroup % \endgroup just after the \tableofcontents command
 \etocinline
 \etocsetlevel{part}{1}
-% \etocsetlevel{chapter}{1}
 \etocsetlevel{visibletoc}{0}
 \etocsetstyle{visibletoc}
     {\etocskipfirstprefix}
@@ -2835,7 +2774,7 @@ contents via an \csa{addcontentsline} command).\footnote{as
   \csa{fbox} (and not used |hyperref|) we would have needed
   \csa{protect}\csa{fbox}.}
 
-The \csa{etocifnumbered}\marg{A}\marg{B} command executes
+The \csb{etocifnumbered}\marg{A}\marg{B} command executes
 \meta{A} if the number exists, and \meta{B} if not. So we use
 it in the code which was finally chosen for the |section| level:
 \begin{verbatim}
@@ -2866,13 +2805,13 @@ this: |{...(page \etocpage)\par}|.
 \label{etocthenumber}
 \label{etocthepage}
 
-It is sometimes desirable to have access to the name, number
-and page number without the hyperref link data: something
-similar to the starred variant of the \csa{ref} command, when
-package |hyperref| is used. For example one may wish to use
-the unit or page number in some kind of numeric context, or
-change its formatting. This is provided by the |\etocthe...|
-commands.
+It is sometimes desirable to have access to the name, number and page
+number without the hyperref link data: something similar to the starred
+variant of the \csa{ref} command, when package |hyperref| is used. For
+example one may wish to use the unit or page number in some kind of
+numeric context, or change its formatting. This is provided by
+\csb{etocthename}, \csb{etocthenumber}, and \csb{etocthepage}.
+
 
 These commands are not protected, so in moving argument
 contexts (for example in a label specification) they should be
@@ -2906,7 +2845,6 @@ The command \csa{etoclink} is robust.
 
 
 This is for advanced uses by advanced users. 
-
 The \csa{etocthename} macro has
 been mentioned before; using it in instructions such as
 |\global\let\lastone\etocthename| in an \etoc line style will
@@ -2949,11 +2887,7 @@ has already been done (and it has been done by the package
 itself in its definition of its own line styles).
  
 The accepted levels run from |-2| to |6| inclusive.  Anything else is
-mapped to |6|, which is a dummy level, never displayed\footnote{as explained in
-\autoref{etocsettocdepth.toc}, this is not quite true as associating a unit name
-to the numeric level |-3| is 
-allowed for special tricks, but one should not assign a line style to any name
-with numeric level |-3|.}. The package
+mapped to |6|, which is a dummy level, never displayed. The package
 does:
 \begin{verbatim}
 \etocsetlevel{book}{-2}
@@ -3071,7 +3005,7 @@ language changes occurring in the document.
 \label{part:globalcmds}
 
 \begin{verbatim}
-\invisiblelocaltableofcontents \label{toc:globalcmds}
+Code in the source: \invisiblelocaltableofcontents \label{toc:globalcmds}
 \end{verbatim}
 
 \invisiblelocaltableofcontents \label{toc:globalcmds}
@@ -3089,29 +3023,27 @@ should be put in a frame. For example, to opt for a ruled
 heading and single column layout, one issues commands of the
 following type:
 \begin{verbatim}
-\etocruledstyle[1]{Title}
-    \tableofcontents (or \localtableofcontents)
-shortcuts:
-    \etocruled[1]{Title}  (or  \etoclocalruled[1]{Title})
+\etocruledstyle[1]{Title} \tableofcontents    (or \localtableofcontents)
+shortcuts:         \etocruled[1]{Title}  (or  \etoclocalruled[1]{Title})
 \end{verbatim}
 
 \subsection{The command \csbhyp{etocsettocstyle}}
 \label{etocsettocstyle}
 
 This is a command with two mandatory arguments:\\
-\centerline{\color{blue}\csa{etocsettocstyle}\marg{before\_toc}%
+\centerline{\csb{etocsettocstyle}\marg{before\_toc}%
 \marg{after\_toc}}
 The \marg{before\_toc} part is responsible for typesetting the
 heading, for example it can be something like
 \starit{section}|{\contentsname}|. 
 
 Generally speaking this heading
-should leave \TeX{} in vertical mode when the actual
+should leave \TeX{} in ``vertical mode'' when the actual
 typesetting of the contents will start: the line styles (either
 from the standard classes or the package default line styles)
-expect to start in `vertical mode'.
+all expect to get started in `vertical mode'.
 
-It can also contain
+The first argument to \csb{etocsettocstyle} can also contain
 instructions to mark the page headings.  Or
 it could check (book class) to see if two-column mode is on,
 and switch to one-column style, and the \meta{after\_toc} part
@@ -3119,8 +3051,8 @@ would then reenact the two-column mode.
 
 The commands to be described next \csb{etocmulticolstyle},
 \csb{etocruledstyle}, and \csb{etocframedstyle} all call
-\csa{etocsettocstyle} as a lower-level routine, starting a 
-\texttt{multi\-cols} environment in \marg{before\_toc} to close it in
+\csa{etocsettocstyle} as a lower-level routine, to start a 
+\texttt{multi\-cols} environment in \marg{before\_toc} and close it in
 \marg{after\_toc}. 
 
 \subsection{The commands \csbhyp{etocmulticolstyle}, \csbhyp{etocmulticol}, and \csbhyp{etoclocalmulticol}}
@@ -3129,18 +3061,15 @@ The commands to be described next \csb{etocmulticolstyle},
 \label{etoclocalmulticol}
 
 This is a command with one optional and one mandatory argument:\\
-\centerline{\color{blue}\csa{etocmulticolstyle}%
-\oarg{number\_of\_columns}\marg{heading}}
-The \meta{number\_of\_columns} can go from 1 to 10 (it
-defaults to 2, and from 2 on is passed to a |multicols|
-environment). The \meta{heading} will be typically be some `vertical' material
-like: 
-\begin{center}
-  \meta{heading} = {\ttfamily\string\section\lowast}\marg{title}
-\end{center}
-but one may also have horizontal material like |\fbox{Hello World}| as \etoc
-adds automatically a |\par| at the end of the ``heading'' argument to
-\csb{etocmulticolstyle}. Here is for example
+\centerline{\csb{etocmulticolstyle}%
+  \oarg{number\_of\_columns}\marg{heading}} The
+\meta{number\_of\_columns} can go from 1 to 10 (it defaults to 2; if its
+value is 1, naturally no |multicols| environment is then created). The
+\meta{heading} will typically be some `vertical' material like:
+  \meta{heading} = |\section*|\marg{title}
+but one may also have horizontal material like |\fbox{Hello World}| (\etoc
+adds automatically a |\par| at the end of this ``heading'' argument to
+\csb{etocmulticolstyle}). Here is for example
 how the main table of contents of this document was
 configured:
 \begin{verbatim}
@@ -3159,10 +3088,10 @@ And there is also
 \subsubsection{The command \csbhyp{etoctocstyle}}
 \label{etoctocstyle}
 
-\centeredline{\color{blue}\csa{etoctocstyle}\oarg{kind}%
+\centeredline{\csb{etoctocstyle}\oarg{kind}%
 \marg{number\_of\_columns}\marg{title}}
 \centeredline{=
-\csa{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
+\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
 |{\kind*{|\itshape title\upshape|}}|}
 where |kind| is one of |chapter|, |section|, . . . and defaults
 to |chapter| or |section| depending on the document class.
@@ -3173,7 +3102,7 @@ to |chapter| or |section| depending on the document class.
 \label{etoctocstylewithmarksnouc}
 
 \centeredline
-{=\csa{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
+{=\csb{etocmulticolstyle}|[|{\itshape number\_of\_columns}|]|%
 |{\kind*{|\itshape title \ttfamily\upshape\string\markboth%
 |{\MakeUppercase{|{\rmfamily\itshape mark}|}}}}|} 
 where |kind| is one of |chapter|, |section|, ... The
@@ -3192,12 +3121,13 @@ which does not uppercase.
 \label{etoclocalruled}
 
 The general format of \csa{etocruledstyle} is:\\
-\centerline{\color{blue}\csa{etocruledstyle}%
+\centerline{\csb{etocruledstyle}%
 \oarg{number of columns}\marg{title of the toc}}
-\noindent Note that the title is horizontal material, if it
-does not fit on one line it should be put in a \csa{parbox} of
-a given width. We did this and even enclosed the parboxes in
-\csa{fbox}es to get frames around them.
+\noindent 
+The title is horizontal material (the |LR| mode of 
+\emph{\LaTeX{}, a document preparation system}): if it
+does not fit on one line it should be put in a \csa{parbox}  of
+a given width.
 The green frame for the heading of the table of contents at
 the \hyperref[toc:a]{start of the second part of this
   document} was obtained with:
@@ -3223,56 +3153,70 @@ And the local form will be \csb{etoclocalruled}.
 \label{etoclocalframed}
 
 Same mechanism:\\
-\centerline{\color{blue}\csa{etocframedstyle}%
+\centerline{\csb{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. Note that the title itself is
-not framed, if one wants a frame one should set it up
-inside the \meta{title} argument to \csa{etocframedstyle} or
-\csa{etocframed}. There is also 
-\csa{etoclocalframed}.
+\centerline{\csb{etocframed}\oarg{number\_of\_columns}\marg{title}} The
+shortcut is used if one does not want to modify the style of the next
+TOCs (the other way is to put the whole thing inside braces or a
+|\begingroup...\endgroup|; there is also \csa{etoclocalframed} for a
+local table of contents).
+
+The entire table of contents is framed. The title itself is not framed:
+if one wants a frame one should set it up inside the \meta{title}
+argument to \csa{etocframedstyle} or \csa{etocframed}. The colors for
+the background and for the components (top, left, right, bottom) of the
+border are specified via suitable |\renewcommand|'s (see
+\autoref{ssec:customdisplay}).
+
+A |minipage| is used, hence the produced table of contents isn't
+compatible with a page break. For allowing page breaks, use of
+the commands of
+\href{http://ctan.org/pkg/mdframed}{mdframed}\footnote{\url{http://ctan.org/pkg/mdframed}}
+or 
+\href{http://ctan.org/pkg/tcolorbox}{tcolorbox}\footnote{\url{http://ctan.org/pkg/tcolorbox}}
+in the arguments of \csb{etocsettocstyle}  
+is recommended.
+
+Examples in this document are on pages \pageref{toc:d},
+\pageref{toc:floating}, \pageref{toc:b}, and \pageref{toc:clone}.
+
 
 \subsection{Headings, titles, \csbhyp{etocoldpar}, \csbhyp{etocinnertopsep}}
 \label{etocinnertopsep}
 \label{etocoldpar}
 
-There is a slight difference
-between \csa{etocmulticolstyle} and \csa{etocruledstyle} or
-\csa{etocframedstyle}. For \csa{etocmulticolstyle} the mandatory
-\meta{heading} argument can be vertical mode material like:
-\starit{section}%
-|{|\emph{Table of Contents}|}|.  On the contrary  \csa{etocruledstyle} and
-\csa{etocframedstyle} expect an argument
-``in LR mode'' (to use the terminology from \emph{LaTeX, a
-document preparation system}). This means that multiline
-contents arguments to \csa{etocruledstyle} or
-\csa{etocframedstyle} must be enclosed in something like a \csa{parbox}.
-
-The command \csa{etocmulticolstyle} 
-also accepts horizontal mode material in its mandatory
-argument \meta{heading}, so one can do for example
-|\etocmulticolstyle{Hello World}|.   
-
-From restrictions of the |multicols| environment, no explicit |\par| or empty
-line can be contained in the heading argument, but \etoc provides
-\csb{etocoldpar} as a substitute: it does |\let\etocoldpar\par| just before the
-|multicols| environment and automatically adds it to close the heading, before
-the vertical skip of value \csa{etocinnertopsep}.\footnote{this command
+For \csb{etocmulticolstyle} the mandatory \meta{heading} argument can be
+either 
+vertical mode material like |\section*{\emph{Table of Contents}}| or
+horizontal mode material like in the simple |\etocmulticolstyle{Hello World}|.
+
+No explicit |\par| or empty line can be inserted in the mandatory
+argument of \csb{etocmulticolstyle}, but \etoc provides \csb{etocoldpar}
+as a substitute: it does |\let\etocoldpar\par| before the |multicols|
+environment and inserts this |\etocoldpar|\footnote{this command
   \csa{etocoldpar} (= working \csa{par} in the argument to
-  \csa{etocmulticolstyle}) is not related to the switch \csa{etocinline} whose
-  purpose is to tell \etoc not to do a \csa{par} before the table of contents.}
-The command \csb{etocoldpar} can also be used explicitely if needed in the
-mandatory argument to \csa{etocmulticolstyle} (as a replacement to having an
-empty line there).
+  \csa{etocmulticolstyle}) is not related to the switch \csb{etocinline}
+  whose purpose is to tell \etoc not to do a \csa{par} before the table
+  of contents.} at the end of the heading, then does a vertical skip of
+value \csa{etocinnertopsep}. The command \csb{etocoldpar} can also be
+used explicitely if needed in the mandatory argument to
+\csa{etocmulticolstyle} (it is not allowed to insert an empty line
+in this argument).
 
+On the other hand the commands \csb{etocruledstyle} and
+\csb{etocframedstyle} expect an argument ``in LR mode'' (to use the
+terminology from \emph{LaTeX, a document preparation system}). This
+means that multiline titles are only possible if enclosing
+them inside something like a \csa{parbox}.
 
-An important dimension used by all three of \csa{etocmulticolstyle},
-\csa{etocruledstyle} and \csa{etocframedstyle} is
+
+
+An important dimension used by all three of \csb{etocmulticolstyle},
+\csb{etocruledstyle} and \csb{etocframedstyle} is
 \csb{etocinnertopsep}. It gives the amount of separation
 between the heading and the start of the contents. Its default
-value is |2ex| and it is changed by
+value is |2ex| and it is changed with
 |\renewcommand*{\etocinnertopsep}|\marg{new\_value}, not with
 |\setlength|. 
 
@@ -3290,11 +3234,11 @@ class should be obeyed, too.
 \label{etocinline}
 \label{etocnopar}
 
-With |\etocinline|, or its synonym |\etocnopar|, the |\tableofcontents| command
-and its variants do \emph{not} first issue a |\par| to close the previous
-paragraph. Hence, the table of contents can be printed in an inline style; or,
-if used only for preparing some token list or macro, it will leave nothing in
-the token stream on execution.
+With \csb{etocinline}, or its synonym |\etocnopar|, the
+|\tableofcontents| command and its variants do \emph{not} first issue a
+|\par| to close the previous paragraph. Hence, the table of contents can
+be printed in an inline style; or, if used only for preparing some token
+list or macro, it will leave nothing in the token stream on execution.
 
 \section{Starred variants of the \csbhyp{tableofcontents}  etc... commands}
 \label{tableofcontents*}
@@ -3303,13 +3247,12 @@ the token stream on execution.
 \label{etocaftercontentshook}
 \label{etocmemoirtoctotocfmt}
 
-The \toc, \localtoc, \csa{etocmulticol}, etc... have starred
-variants (the star must be before the other arguments). For
-all but the |memoir| class, they are like the original. For
-the |memoir| class, the original prints an entry in the |.toc|
-file, as is the usage for the original \toc command in that
-class, whereas the starred variants do not, as is the habit in
-that class.
+The \toc, \localtoc, \csa{etocmulticol}, and all their cousins and
+variants have starred variants (the star must be before the other
+arguments). For all but the |memoir| class, they are like the original.
+For the |memoir| class, the original prints an entry in the |.toc| file,
+as is the usage for the original \toc command in that class, whereas the
+starred variants do not, as is the habit in that class.
 
 As soon as one starts using local table of contents one
 discovers that the default |memoir| thing which is to create a
@@ -3481,7 +3424,8 @@ such matters does not seem to be highly shared).
 \tableofcontents \label{toc:crazyinline}
 \endgroup
 
-Here is the code which has been used:\footnote{as this new version of the
+
+Here is the code used:\footnote{as this new version of the
   documentation has some sections before the first part, we had to take special
   measures in the \emph{begin} code for level |part|. }
 \begin{verbatim}
@@ -3501,7 +3445,6 @@ Here is the code which has been used:\footnote{as this new version of the
 \endgroup
 \end{verbatim}
 
-%% \clearpage
 
 \etocdepthtag.toc {custom}
 
@@ -3746,7 +3689,7 @@ in the body of the document, has the secondary effect of
 switching off the compatibility mode.
 
 \subsection{Customizing the toc display styles}
-
+\label{ssec:customdisplay}
 
 Again we list the relevant macros, what they do should be
 legible from their names. Note that \csa{renewcommand}'s and
@@ -4073,23 +4016,25 @@ this technique):
 
 \etocmarkbothnouc{List of all subsections}
 
-\etocmulticol[3]{\subsection{All subsections of this document}}
+\etocmulticol[3]{\subsection{All subsections of this document}\label{toc:allsubsections}}
+
 
 \endgroup
 
 \subsection{Displaying statistics}\label{ssec:statistics}
 
-Each part of this document starts with a paragraph telling how many sections and
-subsections it has. Well, each one of this paragraph is a table of contents! We
-designed a macro \csa{thispartstats} to do that. It uses ``storage'' boxes to
-keep the information about the first and last section or subsection. Using boxes
-is the simplest manner to encapsulate the |hyperref| link for later use (whether
-there is one or none). However, one cannot modify then the font or the color
-(using the \TeX{} primitive \csa{setbox} rather than the \LaTeX{} \csa{sbox}
-would allow to change the color of the un-boxed saved box). If such a need
-arises, one must switch from boxes to macros, and store the |hyperref| data for
-later use as was done in the code presented in \autoref{ssec:molecule}. We
-did this for the first paragraph of \autoref{part:surprising}.
+Each part of this document starts with a paragraph telling how many
+sections and subsections it has. Well, each one of this paragraph is a
+table of contents! We designed a macro \csa{thispartstats} to do that.
+It uses ``storage'' boxes to keep the information about the first and
+last section or subsection. Using boxes is the simplest manner to
+encapsulate the |hyperref| link for later use (whether there is one or
+none). However, one cannot modify then the font or the color (using the
+\TeX{} primitive \csa{setbox} rather than the \LaTeX{} \csa{sbox} would
+allow to change the color of the un-boxed saved box). If such a need
+arises, one must switch from using boxes to using macros, and store the
+|hyperref| data for later use as was done in the code presented in
+\autoref{ssec:molecule}. We present also this second method.
 
 But first, the coding of \csa{thispartstats}:\par
 \begingroup
@@ -4141,8 +4086,8 @@ But first, the coding of \csa{thispartstats}:\par
 \end{verbatim}
 %\endgroup
 
-And now, the variant  which was used for
-  \autoref{part:surprising}, with macros rather than boxes: 
+And now, the variant with macros rather than boxes (this variant as it
+stands here is for using within a section).
 \begin{verbatim}
 \makeatletter
 \newcommand*\firstsubname   {}  \newcommand*\lastsubname    {}
@@ -4160,17 +4105,17 @@ And now, the variant  which was used for
      \stepcounter{mycounti}%
      \let\lastsubname\etocthelinkedname
      \let\lastsubnumber\etocthelinkednumber }
-    {Here are some statistics for this part. It contains \arabic{mycounti}
-      sections. The name of 
+    {Here are some statistics for this section. It contains \arabic{mycounti}
+      subsections. The name of 
 	 its first is 
      \emph{\firstsubname{}} and the corresponding number is 
-     {\firstsubnumber}. The name of the last section is 
+     {\firstsubnumber}. The name of the last subsection is 
      \emph{\lastsubname{}} and its number is 
      {\lastsubnumber}.}% 
    \etocsettocstyle {}{}
    \etocinline
    \etocsetnexttocdepth {1}%
-   \localtableofcontents
+   \localtableofcontents % to be used within a section
   \endgroup
 }
 \makeatother
@@ -4187,13 +4132,17 @@ source various \csb{etocdepthtag.toc} commands, and it is now just a matter to
 set the levels for each one of these tags (as they were left undefined until
 now, they were ignored in all previous tables of contents).
 
-However, the package line styles do not display paragraphs, and the standard
-line styles of the document class give too much vertical spacing (in this
-context) when displaying a Part heading in the TOC. So we cook up our own,
-quickly designed line styles, in the style of \autoref{sec:firstexample} (the
-way to put the page numbers into the column on the right is more like the method
-used by \LaTeX2e's |\@dottedtocline|). And after a few minutes for choosing
-lengths (now that this has been done once, it can be recycled easily) we get:
+However, the package line styles do not display paragraphs, and the
+standard line styles of the document class give too much vertical
+spacing (in this context) when displaying a Part heading in the TOC. So
+we cook up our own, quickly designed line styles, in the style of
+\autoref{sec:firstexample} (but with a way to put page numbers on the
+right which is more like the method used by \LaTeX2e's
+|\@dottedtocline|; and multi-line headings now leave empty the area
+underneath the numbers contrarily to the code from
+\autoref{sec:firstexample}). And after a few minutes for choosing
+lengths (now that this has been done once, it can be recycled easily) we
+get:
 
 \etocsetnexttocdepth {all}
 \begingroup
@@ -4201,12 +4150,6 @@ lengths (now that this has been done once, it can be recycled easily) we get:
 \leftskip 0cm
 \rightskip 0.75cm
 \parfillskip -\rightskip
-% I used this before plagiarizing \@dottedtocline:
-% \parfillskip 0pt
-% \newcommand*{\PushintoRightMargin}[1]
-%             {\strut\vadjust{\vskip-\dp\strutbox
-%             \smash{\hbox to \linewidth {\hss \llap{#1}}}
-%             \vskip\dp\strutbox }}
 \newcommand*{\EndParWithPagenoInMargin}
     {\nobreak\hfill
      \nobreak\makebox[0.75cm][r]{\mdseries\normalsize\etocpage}%
@@ -4219,32 +4162,32 @@ lengths (now that this has been done once, it can be recycled easily) we get:
      \par }
 \etocsetstyle {part}
               {}
-              {\leavevmode\leftskip 0cm\relax}
-              {\bfseries\large\makebox[1cm][r]{\etocnumber\ \ }%
+              {\leavevmode\leftskip 1cm\relax}
+              {\bfseries\large\llap{\makebox[1cm][r]{\etocnumber\ \ }}%
                \etocname\EndParWithPagenoInMargin\smallskip}
               {}
 \etocsetstyle {section}
               {}
-              {\leavevmode\leftskip 1cm\relax}
-              {\bfseries\normalsize\makebox[.75cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 1.75cm\relax}
+              {\bfseries\normalsize\llap{\makebox[.75cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsetstyle {subsection}
               {}
-              {\leavevmode\leftskip 1.75cm\relax }
-              {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 2.75cm\relax }
+              {\mdseries\normalsize\llap{\makebox[1cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsetstyle {subsubsection}
               {}
-              {\leavevmode\leftskip 2.75cm\relax }
-              {\mdseries\normalsize\makebox[1.25cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 4cm\relax }
+              {\mdseries\normalsize\llap{\makebox[1.25cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsetstyle {paragraph}
               {}
-              {\leavevmode\leftskip 4cm\relax }
-              {\mdseries\normalsize\makebox[1.5cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 5.5cm\relax }
+              {\mdseries\normalsize\llap{\makebox[1.5cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsettagdepth {preamble}   {none}
@@ -4260,7 +4203,8 @@ lengths (now that this has been done once, it can be recycled easily) we get:
 \renewcommand\etoctoprulecolorcmd {\color{blue}}
 \renewcommand\etocaftercontentshook 
    {\medskip\begingroup \color{blue}\hrule height 3pt \endgroup }
-\etocruledstyle [1]{\Large\bfseries \fbox{\makebox[8cm]{A TOC using depth tags}}}
+\etocruledstyle [1]{\Large\bfseries 
+                    \fbox{\makebox[8cm]{A TOC using depth tags}}}
 \sloppy
 \tableofcontents
 \endgroup
@@ -4281,32 +4225,32 @@ lengths (now that this has been done once, it can be recycled easily) we get:
      \par }
 \etocsetstyle {part}
               {}
-              {\leavevmode\leftskip 0cm\relax}
-              {\bfseries\large\makebox[1cm][r]{\etocnumber\ \ }%
+              {\leavevmode\leftskip 1cm\relax}
+              {\bfseries\large\llap{\makebox[1cm][r]{\etocnumber\ \ }}%
                \etocname\EndParWithPagenoInMargin\smallskip}
               {}
 \etocsetstyle {section}
               {}
-              {\leavevmode\leftskip 1cm\relax}
-              {\bfseries\normalsize\makebox[.75cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 1.75cm\relax}
+              {\bfseries\normalsize\llap{\makebox[.75cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsetstyle {subsection}
               {}
-              {\leavevmode\leftskip 1.75cm\relax }
-              {\mdseries\normalsize\makebox[1cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 2.75cm\relax }
+              {\mdseries\normalsize\llap{\makebox[1cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsetstyle {subsubsection}
               {}
-              {\leavevmode\leftskip 2.75cm\relax }
-              {\mdseries\normalsize\makebox[1.25cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 4cm\relax }
+              {\mdseries\normalsize\llap{\makebox[1.25cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsetstyle {paragraph}
               {}
-              {\leavevmode\leftskip 4cm\relax }
-              {\mdseries\normalsize\makebox[1.5cm][l]{\etocnumber}%
+              {\leavevmode\leftskip 5.5cm\relax }
+              {\mdseries\normalsize\llap{\makebox[1.5cm][l]{\etocnumber}}%
                \etocname\EndParWithPagenoInMarginAndLeaders}
               {}
 \etocsettagdepth {preamble}   {none}
@@ -4322,7 +4266,8 @@ lengths (now that this has been done once, it can be recycled easily) we get:
 \renewcommand\etoctoprulecolorcmd {\color{blue}}
 \renewcommand\etocaftercontentshook 
    {\medskip\begingroup \color{blue}\hrule height 3pt \endgroup }
-\etocruledstyle [1]{\Large\bfseries \fbox{\makebox[8cm]{A TOC using depth tags}}}
+\etocruledstyle [1]{\Large\bfseries 
+                    \fbox{\makebox[8cm]{A TOC using depth tags}}}
 \sloppy
 \tableofcontents
 \endgroup
@@ -4331,6 +4276,7 @@ lengths (now that this has been done once, it can be recycled easily) we get:
 \subsection{Compatibility with other packages}
 \label{etocaftertochook}
 
+
 \etoc loads the package |multicol|. It is
 |hyperref| aware and hopefully |hyperref| compatible! It
 doesn't matter whether \etoc or |hyperref| is loaded first.
@@ -4364,7 +4310,7 @@ point the file is erased until its contents are again written to the disk by
 
   \etoc used to be incompatible with package
   |tocvsec2|\footnote{\url{http://ctan.org/pkg/tocvsec2}}; it now cohabits, sort
-  of, as it deactivates |tovsec2|'s modification of |\tableofcontents| (done in
+  of, as it deactivates |tocvsec2|'s modification of |\tableofcontents| (done in
   the style above) and also cancels its other |toc|-related macros, but
   reimplements partially their functionality with \csb{etocsettocdepth.toc}. By
   the way, at least two latex runs are necessary for new uses of this command in
@@ -4391,7 +4337,7 @@ example) throughout the document the macros \csa{l@section},
 table of contents typeset by \etoc in compatibility mode.
 
 It is possible to use simultaneously \etoc and 
-{\color{niceone}|tableof|}\footnote{\url{http://www.ctan.org/pkg/tableof}}. For the
+{\color{niceone}|tableof|}\footnote{\url{http://ctan.org/pkg/tableof}}. For the
 advanced uses such as what is done in \autoref{ssec:molecule} it is
   important 
 to know that |tableof| adds one level of grouping inside the |.toc| file itself.
@@ -4453,6 +4399,11 @@ groups. All TOCs are typeset inside groups.
   document get its final appearance (at least twice).\par
 
 
+
+\etocdepthtag.toc {code}
+
+\part{The code}
+
 \section{Timestamp}
 
 This is the documentation as of \texttt{\docdate}, printed from the source file
@@ -4460,9 +4411,57 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is
 \texttt{\pkgversion}, of \texttt{\pkgdate}.
 
 
-\etocdepthtag.toc {code}
+\section{License, installation}
+
+\begin{verbatim}
+% Copyright (C) 2012-2013 by Jean-Francois Burnol <jfbu at free dot fr>
+%
+%     This Work may be distributed and/or modified under the
+%     conditions of the LaTeX Project Public License, either
+%     version 1.3c of this license or (at your option) any later
+%     version. This version of this license is in 
+%          http://www.latex-project.org/lppl/lppl-1-3c.txt
+%     and the latest version of this license is in
+%          http://www.latex-project.org/lppl.txt
+%     and version 1.3 or later is part of all distributions of
+%     LaTeX version 2005/12/01 or later. 
+%
+% This Work has the LPPL maintenance status Author-Maintained.
+%
+% The Author of this Work is 
+%        Jean-Francois Burnol <jfbu at free dot fr>. 
+% 
+% This Work consists of the main source file etoc.dtx and the 
+% derived files etoc.sty, etoc.dvi, etoc.pdf, etoc.ins, etoc.tex
+%
+% Extraction of the package (.sty) and driver (.tex) files:
+%  - if etoc.ins is present:   tex etoc.ins
+%  - without etoc.ins:         tex etoc.dtx 
+%
+% It is also possible to run latex/pdflatex directly on etoc.dtx
+%
+% At least three ways to produce etoc.pdf:
+%  (1) latex etoc.dtx (three times), then dvips, then ps2pdf
+%  (2) pdflatex etoc.dtx (three times)
+%  (3) latex etoc.tex (three times), then dvipdfmx
+%
+% Method (3) produces the smallest pdf files.
+% Options can be set in etoc.tex:
+%  - scrdoc class options (paper size, font size, ...) 
+%  - with or without source code, 
+%  - with dvipdfmx or with latex/pdflatex. 
+%
+% Installation: 
+%
+%   etoc.sty->TDS:tex/latex/etoc/etoc.sty
+%   etoc.dtx->TDS:source/latex/etoc/etoc.dtx
+%   etoc.pdf->TDS:doc/latex/etoc/etoc.pdf
+%
+% etoc.tex, etoc.ins, etoc.aux, etoc.toc, etc... may be discarded
+%
+\end{verbatim}
+
 
-\part{The code}
 
 \begingroup
 \renewcommand\lowast{{\normalsize\raisebox{-.4\height}{*}}}
@@ -4504,12 +4503,16 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is
 
 \begin{multicols}{2}
 \begin{jfverbatim}
+v1.07i [2013/10/21]
+
+   changes to the \etocmulticolstyle and \etocruledstyle codes 
+   to lessen the risk of a page break after the title (in the one-column case).
+
 v1.07h [2013/10/16]
 
    new commands \etocdepthtag.toc, \etocsettagdepth, \etocobeydepthtags,
    \etocignoredepthtags. 
 
-
 v1.07g [2013/10/13]
 
    new commands \etocsettocdepth, \etocsettocdepth.toc,
@@ -4997,11 +5000,9 @@ v1.02 [2012/11/18]
 % Up to |1.06| \etoc defined only \csa{etocname}, \csa{etocnumber} and
 % \csa{etocpage}. The |hyperref| added data is recycled in the simplest manner,
 % prefixing it with \csa{leavevmode}. The included \csa{Hy@tocdestname} is left
-% unexpanded. Due to the initial (enormously incredible and opposite to the
-% credo of separating the content from the form) \LaTeX{} flaw of mixing (Parts
-% having their own format, not to mention other classes) in the |.toc| file the
-% number and the name we have to spend some time with delimited macros to
-% dis-entangle this, and reconstruct the possible |hyperref| data. Note that if
+% unexpanded. We have to spend some time with delimited macros to
+% dis-entangle the |.toc| data, and reconstruct the possible |hyperref|
+% data. If
 % the page number is not hyperlinked, \csa{etocpage} does \emph{not} add the
 % link found possibly in the name.
 %
@@ -5622,7 +5623,9 @@ v1.02 [2012/11/18]
 \etoc@setstyle{@five}{}{}{}{}%
 } % end of \etocdefaultlines!
 %    \end{macrocode}
-% placeholder for comments
+% The |\etocinnertopsep| default value is too big as well as |\etocbelowtocskip|
+% and |\etocabovetocskip|, I guess, but if I am remember correctly I chose them
+% to mimick the standard TOC spacings in |article| class.
 %    \begin{macrocode}
 \def\etocabovetocskip{3.5ex \@plus 1ex \@minus .2ex} 
 \def\etocbelowtocskip{3.5ex \@plus 1ex \@minus .2ex}
@@ -5633,7 +5636,9 @@ v1.02 [2012/11/18]
 \def\etocdefaultnbcol{2}
 \def\etocinnertopsep{2ex}
 %    \end{macrocode}
-% placeholder for comments
+% |1.07i| adds a |\nobreak| before the |\etocinnertopsep| and a test of vertical
+% mode to see if truly adding a |\par| is a reasonable idea, in the
+% case of single-column mode.
 %    \begin{macrocode}
 \newcommand\etocmulticolstyle[2][\etocdefaultnbcol]{%
 \etocsettocstyle
@@ -5647,7 +5652,10 @@ v1.02 [2012/11/18]
     \setlength{\columnsep}{\etoccolumnsep}%
     \setlength{\multicolsep}{\etocmulticolsep}%
     \begin{multicols}{#1}[#2\etocoldpar\addvspace{\etocinnertopsep}]}
-    {#2\par\addvspace{\etocinnertopsep}%
+    {#2\ifvmode\else\begingroup\interlinepenalty\@M\parskip\z@skip
+                    \@@par\endgroup
+       \fi
+       \nobreak\addvspace{\etocinnertopsep}%
        \pretolerance\etocmulticolpretolerance
        \tolerance\etocmulticoltolerance}}
    {\ifnum #1>\@ne\let\Etoc@next\@firstofone
@@ -5669,7 +5677,8 @@ v1.02 [2012/11/18]
 \def\etocleftrulecolorcmd{\relax}
 \def\etocrightrulecolorcmd{\relax}
 %    \end{macrocode}
-% placeholder for comments
+% |1.07i| moves the |\nobreak| to before the |\vskip\etocinnertopsep|
+% (especially important for the single column case).
 %    \begin{macrocode}
 \def\etoc@ruledheading #1{%
    \hb@xt@\linewidth{\color@begingroup
@@ -5677,10 +5686,7 @@ v1.02 [2012/11/18]
           \etoctoprulecolorcmd\leaders\etoctoprule\hss
           \phantom{#1}%
           \leaders\etoctoprule\hss\color@endgroup}%
-          \nointerlineskip\vskip\etocinnertopsep}
-%    \end{macrocode}
-% placeholder for comments
-%    \begin{macrocode}
+          \nointerlineskip\nobreak\vskip\etocinnertopsep}
 \newcommand*\etocruledstyle[2][\etocdefaultnbcol]{%
 \etocsettocstyle
    {\addvspace{\etocabovetocskip}%
@@ -5692,7 +5698,7 @@ v1.02 [2012/11/18]
         \setlength{\columnsep}{\etoccolumnsep}%
         \setlength{\multicolsep}{\etocmulticolsep}%
         \begin{multicols}{#1}[\etoc@ruledheading{#2}]}
-       {\etoc@ruledheading{#2}\nobreak
+       {\etoc@ruledheading{#2}%
          \pretolerance\etocmulticolpretolerance
          \tolerance\etocmulticoltolerance}} 
    {\ifnum #1>\@ne\let\Etoc@next\@firstofone
@@ -6001,11 +6007,12 @@ v1.02 [2012/11/18]
 \DeclareRobustCommand*{\etoctoccontentsline}
     {\@ifstar{\Etoc@addcontentsline@}{\Etoc@addtocontents}}
 %    \end{macrocode}
-% Added for version |1.07g [2013/10/13]|. Motivated by a demand about
-% |tovsec2|. But it is impossible to make |tocvsec2| compatible, if not
-% re-doing all `toc' macros in |tocvsec2| (|v1.3, 2011/08/07|). I do not
-% retain the stack idea, which does not convince me as useful. The empty
-% line in the |.toc| file is put there by |tocvsec2| (see its code line 143).
+% All the following added for version |1.07g [2013/10/13]|. Motivated by
+% a demand about  |tovsec2|. But it is impossible to make |tocvsec2|
+% compatible, if not re-doing all `toc' macros in |tocvsec2| 
+% (|v1.3, 2011/08/07|). I do not retain the stack idea, which does not convince
+% me as useful. The empty line in the |.toc| file is put there by
+% |tocvsec2| (see its code line 143). 
 % 
 % I take this opportunity to add to the start of the toc file 
 % |\let\etoc@startlocaltoc\@gobble| in case |etoc| is not detected, I should
@@ -6016,15 +6023,23 @@ v1.02 [2012/11/18]
 % transition in the very improbable situation that someone actually did already
 % use the just released |1.07g|.
 %
+% In |1.07i| the deactivation of |\etoc@settocdepth| done at the start
+% of the |.toc| file (for the case this file is used after having
+% removed |etoc| from the document, or imported in another document) is
+% done via letting it to |\@gobble| rather than |\count@| (which would
+% not be ok, as what follows would be undefined too). The reason for the
+% |\count@| also used originally in |\etocignoretoctocdepth| is that
+% when I first worked on |1.07g| I possibly had more than one token
+% after |\etoc@settocdepth|, but I changed that later.
+%
 %    \begin{macrocode}
-\def\Etoc@settocdepth   {\etoc@settocdepth }% for 1.07g->h, to be removed later.
 \def\Etoc@storetocdepth {\global\c@etoc@tocdepth\c@tocdepth }
 \def\Etoc@resettocdepth {\global\c@tocdepth\c@etoc@tocdepth }
 \def\etocobeytoctocdepth {\def\etoc@settocdepth 
         {\afterassignment\Etoc@@nottoodeep \global\c@tocdepth}}
 \def\Etoc@@nottoodeep {\ifnum\c@tocdepth>\c@etoc@tocdepth
                           \global\c@tocdepth\c@etoc@tocdepth\fi }
-\def\etocignoretoctocdepth {\let\etoc@settocdepth\count@ }
+\def\etocignoretoctocdepth {\let\etoc@settocdepth\@gobble } 
 \def\etocsettocdepth   {\futurelet\Etoc@nexttoken\Etoc@set@tocdepth }
 \def\Etoc@set@tocdepth {\ifx\Etoc@nexttoken\bgroup
                             \expandafter\Etoc@set@tocdepth@
@@ -6035,11 +6050,6 @@ v1.02 [2012/11/18]
           {Unknown sectioning unit #1, \protect\etocsettocdepth\space ignored}}
       {\global\c@tocdepth\csname Etoc@#1@@\endcsname}%
 }
-%    \end{macrocode}
-% |1.07g| |\etocsettocdepth.toc|: the |\expandafter\protect\csname | is because
-% of |@@minustwo@@| which we don't ant to expand to |-\tw@|, because we want
-% alphabetical levels to not be converted immediately to numeric levels.
-%    \begin{macrocode}
 \def\Etoc@set@toctocdepth  #1#{\Etoc@set@toctocdepth@ }
 \def\Etoc@set@toctocdepth@ #1{%
   \@ifundefined{Etoc@#1@@}%
@@ -6111,11 +6121,12 @@ v1.02 [2012/11/18]
        \global\c@tocdepth\csname Etoc@#1@@\endcsname}%
 }%
 %    \end{macrocode}
-% In order for the |.toc| file to be usable without error even without etoc.
+% |1.07h|. In order for the |.toc| file to be usable without error even
+% without etoc. In |1.07i| use of |\@gobble| for |\etoc@settocdepth|.
 %    \begin{macrocode}
 \addtocontents {toc}{\protect\@ifundefined{etoctocstyle}%
            {\let\protect\etoc@startlocaltoc\protect\@gobble 
-            \let\protect\etoc@settocdepth\count@
+            \let\protect\etoc@settocdepth\protect\@gobble
             \let\protect\etoc@depthtag\protect\@gobble }{}}%
 %    \end{macrocode}
 % Initializations.
@@ -6148,7 +6159,7 @@ v1.02 [2012/11/18]
   Grave accent  \`     Left brace    \{     Vertical bar  \|
   Right brace   \}     Tilde         \~}
 
-\CheckSum{2902}
+\CheckSum{2910}
 
 \csname check@checksum\endcsname
 \Finale
-- 
cgit v1.2.3

