From 20f40b1b909d575836f8af15228fbbbc9566a0b5 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Wed, 4 Dec 2013 00:01:29 +0000
Subject: etoc (3dec13)

git-svn-id: svn://tug.org/texlive/trunk@32310 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/etoc/etoc.dtx | 462 +++++++++++++++++----------
 1 file changed, 295 insertions(+), 167 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 6ee6770d15a..37f616758e2 100644
--- a/Master/texmf-dist/source/latex/etoc/etoc.dtx
+++ b/Master/texmf-dist/source/latex/etoc/etoc.dtx
@@ -1,12 +1,14 @@
-% -*- coding: iso-latin-1; -*-
+% -*- coding: iso-latin-1; time-stamp-format: "%02d-%02m-%:y %02H:%02M:%02S %Z" -*-
+%<*none>
+\def\doctimestamp {Time-stamp: <03-12-2013 17:49:49 CET>}
+%</none>
 %<*!package>
-\def\pkgname {etoc} \def\pkgdate {2013/10/21} \def\pkgversion {v1.07i}
-\def\pkgdescription {Completely customisable TOCs (jfB)}
-\def\doctimestamp {Time-stamp <21-10-2013 18:35:52 CEST *>}
+\def\jfbpkgname {etoc} \def\jfbpkgdate {2013/12/03} \def\jfbpkgversion {v1.07j}
+\def\jfbpkgdescription {Completely customisable TOCs (jfB)}
 %</!package>
 %%
 %% Package: etoc
-%% Version: 2013/10/16 v1.07h
+%% Version: 2013/12/03 v1.07j
 %% Copyright (C) 2012-2013 by Jean-Francois Burnol <jfbu at free dot fr>
 %%
 %     This Work may be distributed and/or modified under the
@@ -61,7 +63,8 @@
 %% customize as desired the class options and the two toggles below.
 %%
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesFile{etoc.tex}[\pkgdate\space\pkgversion\space\pkgdescription]%
+\ProvidesFile{\jfbpkgname.tex}%
+   [\jfbpkgdate\space\jfbpkgversion\space\jfbpkgdescription]%
 \PassOptionsToClass{a4paper,11pt}{scrdoc}
 \chardef\Withdvipdfmx 1 % replace 1 by 0 for using latex/pdflatex, rather.
 \chardef\NoSourceCode 0 % replace 0 by 1 for the doc *without* the source code
@@ -91,13 +94,13 @@
 %%
 \input docstrip.tex
 \askforoverwritefalse
-\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
-\string\ProvidesPackage{\pkgname}^^J%
-\space[\pkgdate\space\pkgversion\space\pkgdescription]}%
+\def\jfbpkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
+\string\ProvidesPackage{\jfbpkgname}^^J%
+\space[\jfbpkgdate\space\jfbpkgversion\space\jfbpkgdescription]}%
 \generate{\nopreamble
-\file{\pkgname.tex}{\from{\pkgname.dtx}{driver}}%
-\usepreamble\pkgpreamble
-\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}%
+\file{\jfbpkgname.tex}{\from{\jfbpkgname.dtx}{driver}}%
+\usepreamble\jfbpkgpreamble
+\file{\jfbpkgname.sty}{\from{\jfbpkgname.dtx}{package}}}%
 \catcode32=13\relax% active space
 \let =\space%
 \Msg{************************************************************************}
@@ -118,9 +121,9 @@
 %<*none>------------------------------------------------------------------------
 \fi
 %
-\def\getdtxtimestamp #1 <#2 #3 #4 #5>{#2 at #3 #4}
+\def\getdtxtimestamp #1 <#2 #3 #4>{#2 at #3 #4}
+\def\getdocdate      #1 <#2-#3-#4 #5>{#4/#3/#2}
 \edef\dtxtimestamp {\expandafter\getdtxtimestamp\doctimestamp }
-\def\getdocdate      #1 <#2-#3-#4 #5 #6 #7>{#4/#3/#2}
 \edef\docdate      {\expandafter\getdocdate\doctimestamp }
 \chardef\noetex 0
 \expandafter\ifx\csname numexpr\endcsname\relax \chardef\noetex 1 \fi
@@ -131,8 +134,8 @@
     \expandafter\ifx\csname ProvidesFile\endcsname\relax
       \chardef\extractfiles 0 % etex etc.. on etoc.dtx
     \else % latex/pdflatex on etoc.tex or on etoc.dtx
-      \ProvidesFile{\pkgname.dtx}%
-        [`\pkgname' source and documentation (\dtxtimestamp)]%
+      \ProvidesFile{\jfbpkgname.dtx}%
+        [`\jfbpkgname' source and documentation (\dtxtimestamp)]%
       \expandafter\ifx\csname Withdvipdfmx\endcsname\relax
         % latex run is on etoc.dtx
         \chardef\extractfiles 1 % 1 = extract .sty, .ins, .tex and typeset
@@ -151,7 +154,7 @@
 \Msg{* To finish the installation you have to move the following^^J}%
 \Msg{* file into a directory searched by TeX:^^J}%
 \Msg{*^^J}%
-\Msg{*\space\space\space\space \pkgname.sty^^J}%
+\Msg{*\space\space\space\space \jfbpkgname.sty^^J}%
 \Msg{*^^J}%
 \Msg{* To produce the documentation with source code included run latex^^J}%
 \Msg{* thrice on file etoc.tex and then dvipdfmx on etoc.dvi^^J}%
@@ -163,14 +166,14 @@
 \begingroup
     \input docstrip.tex
     \askforoverwritefalse
-    \def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
-    \string\ProvidesPackage{\pkgname}^^J%
-    \space[\pkgdate\space\pkgversion\space\pkgdescription]}%
+    \def\jfbpkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
+    \string\ProvidesPackage{\jfbpkgname}^^J%
+    \space[\jfbpkgdate\space\jfbpkgversion\space\jfbpkgdescription]}%
     \generate{\nopreamble
-    \file{\pkgname.ins}{\from{\pkgname.dtx}{insfile}}%
-    \file{\pkgname.tex}{\from{\pkgname.dtx}{driver}}%
-    \usepreamble\pkgpreamble
-    \file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}%
+    \file{\jfbpkgname.ins}{\from{\jfbpkgname.dtx}{insfile}}%
+    \file{\jfbpkgname.tex}{\from{\jfbpkgname.dtx}{driver}}%
+    \usepreamble\jfbpkgpreamble
+    \file{\jfbpkgname.sty}{\from{\jfbpkgname.dtx}{package}}}%
 \endgroup
 \fi % end of file extraction
 \ifnum\extractfiles=0 % tex/etex/xetex/etc on etoc.dtx, files extracted, stop
@@ -178,7 +181,8 @@
 % no use of docstrip to extract files if latex run was on etoc.tex
 \ifdefined\MessageDeFin\AtEndDocument{\MessageDeFin}\fi
 %-------------------------------------------------------------------------------
-\documentclass[abstract]{scrdoc}
+% twoside option à partir de version du 3 déc 2013 (1.07j)
+\documentclass[abstract,twoside]{scrdoc}
 \ifnum\NoSourceCode=1 \OnlyDescription\fi
 
 \makeatletter
@@ -202,6 +206,7 @@
 \usepackage[hscale=0.66,vscale=0.75]{geometry}
 \pagestyle{headings}
 
+
 \makeatletter
 % 2013/03/07. 
 % This macro allows to conveniently center a line inside a paragraph and still
@@ -226,13 +231,12 @@
 
 
 % pour les environnements verbatim
-\def\MacroFont{\ttfamily\small\hyphenchar\font45 
-               \baselineskip12pt\relax}
+% uniformisé finalement, avec quelques exceptions, pour dtx du 3 déc 2013
+\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
 
 % mais \verb fait \ttfamily hardcoded!!! (contrairement au
 % \verbatim@font de latex)
 
-
 %----
 % better \verb pour doc.
 % 12 octobre 2013, importé de xint.dtx
@@ -241,8 +245,13 @@
 
 \def\MicroFont{\ttfamily\hyphenchar\font45 }
 % modif de \do@noligs: \char`#1} --> \char`#1 }
-
 \makeatletter 
+\def\do@noligs #1%
+{%
+    \catcode `#1\active 
+    \begingroup \lccode `\~=`#1\relax 
+    \lowercase {\endgroup \def ~{\kern \z@ \char `#1 }}%
+}% 
 \def\dobackslash
 {%
     \catcode92 \active 
@@ -259,32 +268,25 @@
     \begingroup \lccode `\~=125\relax 
     \lowercase {\endgroup \def ~{\char 125 \hskip \z@\@plus.1pt\@minus.1pt }}%
 }% 
-\def\do@noligs #1%
-{%
-    \catcode `#1\active 
-    \begingroup \lccode `\~=`#1\relax 
-    \lowercase {\endgroup \def ~{\kern \z@ \char `#1 }}%
-}% 
 \def\verb 
 {%
   \relax \ifmmode\hbox\else\leavevmode\null\fi
   \bgroup \MicroFont
   \let\do\do@noligs  \verbatim@nolig@list
-  \dobackslash 
-  \dobraces
-  \let\do\@makeother \dospecials \catcode32 10 
-  \catcode92 13 
-  \catcode123 13 \catcode 125 13
-  \makestarlowast \@jfverb 
+  \let\do\@makeother \dospecials 
+  \catcode32 10 
+  \dobackslash \dobraces \makestarlowast 
+  \@jfverb 
 }% 
 \def\@jfverb #1{\catcode`#1\active
                 \lccode`\~`#1\lowercase{\def~{\egroup\unskip}}}%
 % (\unskip ajouté le 14 octobre)
 % \lowast est défini plus loin
 \begingroup
-   \catcode`* 13
-   \gdef\makestarlowast {\let*\lowast\catcode`\*\active}%
+   \lccode`\~=`\*
+\lowercase{%
 \endgroup
+\def\makestarlowast {\catcode`\*\active\let~\lowast}}%
 \makeatother
 %----
 \usepackage{txfonts} 
@@ -292,8 +294,7 @@
 % m'occuper de la taille de txtt:
 % au passage je supprime le \hyphenchar \font\m@ne
 
-
-% avril ?
+% avril 2013
 % ATTENTION ATTENTION ATTENTION Un changement de taille comme \small semble
 % déclencher (peut-être) la relecture de t1txtt.fd et quoi qu'il en soit le
 % \hyphenchar est REMIS à -1 !
@@ -353,6 +354,8 @@
 \usepackage[dvipsnames]{xcolor}
 \usepackage{graphicx}
 \usepackage[inline]{enumitem}
+\usepackage{array}
+\usepackage{longtable}
 
 \definecolor{joli}{RGB}{225,95,0}
 \definecolor{JOLI}{RGB}{225,95,0}
@@ -367,8 +370,8 @@
 
 \usepackage{tikz}
 \usetikzlibrary{trees}    % added for "cyclic" grow function 2013/03/02
-\usepackage{forest}       % switched from qtikz-tree to forest 2013/09/09
-% No problem with hyperlinks then, contrarily to qtikz-tree.
+\usepackage{forest}       % switched from tikz-qtree to forest 2013/09/09
+% No problem with hyperlinks then, contrarily to tikz-qtree.
 
 % NOTE: (12 octobre)
 %  - si compilation pour dvipdfmx, les arbres dans le dvi visualisés par xdvi
@@ -385,7 +388,8 @@
 \usepackage[pdfencoding=pdfdoc]{hyperref}
 \hypersetup{%
 linktoc=all,%      why is the important stuff
-%% bookmarksdepth=3,% in a *hard* to find README? anyhow, no need now 1.07g
+%% bookmarksdepth=3,% in a *hard* to find README? anyhow 
+%% (but not needeed anymore now, v1.07g)
 breaklinks=true,%
 colorlinks,%   
 linkcolor=RoyalBlue,% Orchid
@@ -398,13 +402,11 @@ pdfstartview=FitH,%
 pdfpagemode=UseOutlines}
 
 % added usage of package bookmark 2013/10/10
-%\usepackage[open,openlevel=1]{bookmark} 
 \usepackage{bookmark} 
 
 \usepackage{framed}
 \usepackage{varioref}
 
-
 \usepackage{etoc}  % loads multicol
 
 %--------
@@ -434,13 +436,14 @@ pdfpagemode=UseOutlines}
 % for "Another compatibility mode"  (2013/02/21):
 % attention au 5 qui est hard-coded 
 % (pour 1.07f c'était 3, maintenant 5 pour 1.07g; et 4 maintenant pour 1.07h...)
+% (et pour 1.07i.. à nouveau 3 faudra vraiment que je change cela)
 \makeatletter
 \newcommand*{\MyQuasiStandardTOC}[1]{%
   \begingroup
   \let\savedsectionline\l@section
   \let\savedsubsectionline\l@subsection 
   \etocsetstyle{section}{}
-    {\ifnum\etocthenumber=4
+    {\ifnum\etocthenumber=3
       \etocsetstyle{subsection}
         {\par\nopagebreak\begingroup
          \leftskip1.5em \rightskip\@tocrmarg
@@ -451,10 +454,10 @@ pdfpagemode=UseOutlines}
         {\allowbreak\,--\,}
         {\etocname\ \textup{(\etocnumber)}}
         {.\par\endgroup}%
-      \else
+     \else
         \etocsetstyle{subsection}{}{}
         {\savedsubsectionline{\numberline{\etocnumber}\etocname}{\etocpage}}{}%
-      \fi} 
+     \fi} 
     {\savedsectionline
       {\numberline{{\color{cyan}\etocthenumber}}\etocname}{\etocpage}}
     {}%
@@ -466,7 +469,6 @@ pdfpagemode=UseOutlines}
 %--------
 % Statistics on sections and subsections in a part \thispartstats:
 % 2 mars 2013
-% 7 mars je retire la phrase Click on the names or numbers to get confirmation!
 % cette version utilise des box, plutôt que des macros.
 % mais on ne peut plus alors changer de police etc...
 
@@ -546,18 +548,10 @@ pdfpagemode=UseOutlines}
 \DeclareRobustCommand\csb [1]
       {\hyperref[#1] {\ttfamily\hyphenchar\font45 \char`\\ #1}}
 
-% \DeclareRobustCommand\csbnolk[1]
-%         {{\color{\linkcolor}\ttfamily\hyphenchar\font45 \char`\\ #1}}
-
 \newcommand\cshyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}}
 
 \newcommand\csbhyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}}
 
-% \makeatletter
-% \newcommand\csaetoc[1]{\csaetoc@ #1.}
-% \def\csaetoc@ etoc#1.{\csa{etoc\-#1}} % non empêche hyphénation après.
-% \makeatother
-
 \newcommand\toc{\csa{table\-of\-contents}\xspace}
 \newcommand\localtoc{\csa{local\-table\-of\-contents}\xspace}
 
@@ -565,7 +559,6 @@ pdfpagemode=UseOutlines}
 \newcommand\starit[1]{\csa{#1\lowast}}
 \newcommand\staritb[1]{\csb{#1}\lowast}
 
-
 \hyphenation{toc-depth sec-num-depth etoc-framed-style etoc-ruled-style}
 \hyphenation{etoc-toc-style-with-marks etoc-ruled etoc-framed}
 \hyphenation{etoc-stan-dard-display-style}
@@ -591,16 +584,16 @@ pdfpagemode=UseOutlines}
 % 10 octobre 2013. 
 \bookmark[named=FirstPage,level=1]{Title page}
 
-      
 \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''\par
+  \textsc{Jean-François Burnol}\par
+  \footnotesize \ttfamily jfbu (at) free (dot) fr\\
+  Package version: \jfbpkgversion\ (\jfbpkgdate)
+  \let\thefootnote\empty
+  \footnote{Documentation generated from the source file
+  with timestamp ``\dtxtimestamp''.}\par
 \end{center}
+\setcounter{footnote}{0}
 
 \begin{abstract}
   The \etoc package gives to the user complete control on how
@@ -613,10 +606,9 @@ pdfpagemode=UseOutlines}
   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.
+  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
@@ -638,6 +630,8 @@ pdfpagemode=UseOutlines}
   additionally to the standard |.toc| file.
 \end{abstract}
 
+
+\begingroup
 \small 
 
 \etocdepthtag.toc {preamble}
@@ -673,11 +667,11 @@ found in a line of the |.toc| file) in a completely arbitrary
 manner: they are made available via the \csb{etocname},
 \csb{etocnumber}, and \csb{etocpage} commands. 
 
-\etoc appears to be
+\etoc appears to be (at least partially)
 compatible with the |article|, |book|, |report|, |scrartcl|,
 |scrbook|, |scrreprt| and |memoir| classes. 
 
-
+\endgroup
 \clearpage
 
 %----
@@ -691,12 +685,15 @@ compatible with the |article|, |book|, |report|, |scrartcl|,
       \noindent\bfseries\Large
       \leaders\hrule height1pt\hfill
       \MakeUppercase{Table of Contents}}
+
 \begingroup
   \etocsetlevel{subsection}{3}
   \etocsetlevel{subsubsection}{6}
 \tableofcontents \label{toc:main}
 \endgroup
 
+\etocsettocdepth {subsection}
+
 % \clearpage
 
 \etocdepthtag.toc{overview}
@@ -1059,6 +1056,9 @@ does).
 
 \thispartstats
 
+\etocsettocstyle{}{}
+\etocstandardlines
+\localtableofcontents
 
 \section{Labeling and reusing elsewhere}
 
@@ -1453,6 +1453,8 @@ breaks. Also, they do not worry about potential multi-column use.
 \endgroup
 \end{verbatim}
 
+% \clearpage
+
 \begingroup
 \newlength{\tocleftmargin}
 \setlength{\tocleftmargin}{5cm}
@@ -1604,7 +1606,7 @@ coding used.
 % 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}
+\etocstandardlines
 \etocsettocstyle {}{}
 \localtableofcontents
 
@@ -1818,7 +1820,7 @@ displayed the table of contents following:
     \etocsetlevel{dummypart}  {-1} \etocsetlevel{part}   {2}
     \etocsetlevel{dummychapter}{0} \etocsetlevel{chapter}{2}
     \etocsetlevel{dummysection}{1} \etocsetlevel{section}{2}
-                    \etocsetnexttocdepth{1}
+                    \etocsetnexttocdepth{dummysection}
 \end{verbatim}
 Each chapter displays the numbers of only the first and the last sections it
   contains. See the
@@ -1827,9 +1829,6 @@ source file |etoc.dtx| for the details of how this is done.
 Another technique for doing this kind of things is explained in 
   \autoref{ssec:statistics}.  
 
-
-
-
 %\clearpage
 
 \begingroup
@@ -1909,7 +1908,7 @@ Another technique for doing this kind of things is explained in
             \rule{.2\linewidth}{2pt}}%
     }
         
-    \etocsetnexttocdepth{1}
+    \etocsetnexttocdepth{dummysection}
 
     \tableofcontents
    
@@ -2100,8 +2099,6 @@ the document class defaults:
 \end{enumerate}
 
 Here is how to proceed. One puts in the preamble:
-\begingroup
-\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip11pt\relax}
 \begin{verbatim}
 \makeatletter
 \newcommand{\MyStandardTOC}{%
@@ -2166,7 +2163,7 @@ section, for which the layout is completely modified:
 This example only has sections and subsections, and the code used in \csa{MyStandardTOC} was:
 \begin{verbatim}
 \etocsetstyle{section}{}
-  {\ifnum\etocthenumber=4
+  {\ifnum\etocthenumber=3
       \etocsetstyle{subsection}
         {\par\nopagebreak\begingroup
          \leftskip1.5em \rightskip\@tocrmarg \parfillskip\@flushglue 
@@ -2188,7 +2185,6 @@ This example only has sections and subsections, and the code used in \csa{MyStan
   {\savedsectionline{\numberline{{\color{cyan}\etocthenumber}}\etocname}{\etocpage}}
   {}%
 \end{verbatim}
-\endgroup
 
 Notice the page head-mark added by this standard TOC. Sections and subsections
 are printed exactly as in the default (except for the subsections of one
@@ -2218,7 +2214,7 @@ then refer to, in a delayed execution?
 
 We need to store, not the macro names, but the macro contents. And also we wish
 to maintain the correct |hyperref| hyperlinks.\footnote{This manual up to the
-version of May 14, 2013 used package |qtikz-tree| but there were problems with
+version of May 14, 2013 used package |tikz-qtree| but there were problems with
 hyperlinks. No such problem arises either when using |forest| or the native
 |tikz| syntax for trees (which will be illustrated in the next section).} The
 hyperlink information put by \etoc inside \csa{etocname}, etc\dots, is just a
@@ -2294,7 +2290,7 @@ which will be given the contents of |\treetok|.
 % au plus près de l'environnement forest
 
 \begin{figure*}[th!]\centering
- \etocsetnexttocdepth{2}
+ \etocsetnexttocdepth{subsection}
      \tableofcontents \label{toc:forest}\ref{toc:overview}
      \hypersetup{hidelinks}%
      \bracketset{action character=@}
@@ -2317,9 +2313,6 @@ which will be given the contents of |\treetok|.
 The resulting tree has been put in a \hyperref[toc:forest]{float}, which
 appears \vpageref[above]{toc:forest}. Here is the 
 code used for its production:
-
-\begingroup
-\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip10pt\relax}
 \begin{verbatim}
 \newtoks\treetok
 \newtoks\tmptok
@@ -2363,7 +2356,7 @@ code used for its production:
 \treetok{[{run latex again}]}
 
 \begin{figure*}[th!]\centering
-     \etocsetnexttocdepth{2}
+     \etocsetnexttocdepth{subsection}
      \tableofcontents \label{toc:forest}\ref{toc:overview}
      \hypersetup{hidelinks}%
      \bracketset{action character=@}
@@ -2380,7 +2373,6 @@ code used for its production:
      \end{forest}
 \end{figure*}
 \end{verbatim}
-\endgroup
 
 Why |\hypersetup{hidelinks}|? as explained in
 \autoref{ssec:hidelinks}, I prefer the links in TOCs not to be
@@ -2402,11 +2394,16 @@ whatever conditions are desired. So here  it is necessary to re-issue
 
 There are some other examples in this documentation where
 |\tableofcontents| is used to prepare material for later
-typesetting, as for example (see \autoref{ssec:statistics}) for
-printing the statistics at the start of each Part: the code there
-uses save boxes, so the problem of the appearance of the links
-does not arise then, they will be stored as ready to be re-used
-boxes.
+typesetting:
+\begin{itemize}
+\item printing the statistics at the start of each Part (see
+  \autoref{ssec:statistics}) is done using save boxes (so the problem of the
+  appearance of the links does not arise then).
+\item the typesetting of the TOC as a table (see \autoref{ssec:tocastable});
+  there we also will have to issue |\hypersetup{hidelinks}| after having
+  collected the names, numbers and page numbers in a token list register.
+\item and the two additional tree examples in the next section.
+\end{itemize}
 
 
 \section{The TOC as a molecule}\label{ssec:molecule}
@@ -2426,8 +2423,6 @@ contents of this (or another) document part, only a \csa{sectiontok} and a
 \csa{subsectiontok} will be needed.
 
 
-\begingroup
-\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip10pt\relax}
 \begin{verbatim}
 % \newtoks\treetok % already done earlier
 \newtoks\sectiontok \newtoks\subsectiontok \newcommand*{\treenode}{}
@@ -2458,10 +2453,9 @@ contents of this (or another) document part, only a \csa{sectiontok} and a
   {\global\appendtotok\treetok{ ;}}
 
 % moved to the inside of the figure environment for correct \pageref{toc:molecule}
-% \etocsetnexttocdepth{2}
+% \etocsetnexttocdepth{subsection}
 % \tableofcontents \label{toc:molecule} \ref{toc:overview}
 \end{verbatim}
-\endgroup
 
 \newtoks\sectiontok
 \newtoks\subsectiontok
@@ -2496,7 +2490,7 @@ contents of this (or another) document part, only a \csa{sectiontok} and a
   {\global\appendtotok\treetok{ ;}}
 
 \begin{figure*}[th!]\centering
-\etocsetnexttocdepth{2}
+\etocsetnexttocdepth{subsection}
    \tableofcontents \label{toc:molecule}\ref{toc:overview}
    \hypersetup{hidelinks}%
    \begin{tikzpicture}
@@ -2523,11 +2517,9 @@ We thus get the table of contents as a ``\hyperref[toc:molecule]{molecule}'',
 which  
 appears \vpageref[above]{toc:molecule}. Here is the code actually
 producing it:
-\begingroup
-\def\MacroFont{\ttfamily\small\hyphenchar\font45 \baselineskip10pt\relax}
 \begin{verbatim}
 \begin{figure*}[th!]\centering
-   \etocsetnexttocdepth{2}
+   \etocsetnexttocdepth{subsection}
    \tableofcontents \label{toc:molecule} \ref{toc:overview}
    \hypersetup{hidelinks}%
    \begin{tikzpicture}
@@ -2541,7 +2533,6 @@ producing it:
    \end{tikzpicture}
 \end{figure*}
 \end{verbatim}
-\endgroup
 
 
 
@@ -3004,13 +2995,12 @@ language changes occurring in the document.
 \part{Commands for the toc display style}
 \label{part:globalcmds}
 
-\begin{verbatim}
-Code in the source: \invisiblelocaltableofcontents \label{toc:globalcmds}
-\end{verbatim}
+\thispartstats
 
-\invisiblelocaltableofcontents \label{toc:globalcmds}
+\etocsettocstyle{}{}
+\etocstandardlines
+\localtableofcontents \label{toc:globalcmds}
 
-\thispartstats
 
 \section{Specifying the toc display style}
 
@@ -3407,27 +3397,9 @@ Let us finally make some crazy inline display of the table of
 contents of this entire document. We will typeset the subsections as
 footnotes... This kind of style is suitable for a hyperlinked
 document, probably not for print! (although I like it, but my personal taste in
-such matters does not seem to be highly shared).
-
-\begingroup
-\newsavebox{\forsubsections}
-\etocsetstyle{part}{\upshape. \etocskipfirstprefix}{. \upshape}{\bfseries\etocname:~~}{}
-\etocsetstyle{section}{\itshape\etocskipfirstprefix}{, }{\mdseries\etocname}{}
-\etocsetstyle{subsection}
-   {\begin{lrbox}{\forsubsections}\upshape\etocskipfirstprefix}
-   {; }
-   {\etocname}
-   {\end{lrbox}\footnote{\unhbox\forsubsections.}}
-\etocsetstyle{subsubsection}{ (\itshape\etocskipfirstprefix}
-  {, }{\etocname}{\/\upshape)}
-\etocsettocstyle{Here is the inline table of contents. }{.\par}
-\tableofcontents \label{toc:crazyinline}
-\endgroup
-
+many matters does not seem to be widely shared).
 
-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|. }
+The code used:
 \begin{verbatim}
 \begingroup
 \newsavebox{\forsubsections}
@@ -3445,6 +3417,23 @@ Here is the code used:\footnote{as this new version of the
 \endgroup
 \end{verbatim}
 
+\clearpage
+\begingroup
+\newsavebox{\forsubsections}
+\etocsetstyle{part}{\upshape. \etocskipfirstprefix}{. \upshape}{\bfseries\etocname:~~}{}
+\etocsetstyle{section}{\itshape\etocskipfirstprefix}{, }{\mdseries\etocname}{}
+\etocsetstyle{subsection}
+   {\begin{lrbox}{\forsubsections}\upshape\etocskipfirstprefix}
+   {; }
+   {\etocname}
+   {\end{lrbox}\footnote{\unhbox\forsubsections.}}
+\etocsetstyle{subsubsection}{ (\itshape\etocskipfirstprefix}
+  {, }{\etocname}{\/\upshape)}
+\etocsettocstyle{Here is the inline table of contents. }{.\par}
+\tableofcontents \label{toc:crazyinline}
+\endgroup
+
+
 
 \etocdepthtag.toc {custom}
 
@@ -3768,8 +3757,6 @@ 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\def\MacroFont{\ttfamily\footnotesize\hyphenchar\font45 }%
-
 \begin{verbatim}
 \begingroup
 \definecolor{subsecnum}{RGB}{13,151,225}
@@ -3839,9 +3826,6 @@ the frame.
 \tableofcontents \label{toc:clone} \ref{toc:globalcmds}
 \endgroup
 \end{verbatim}
-\endgroup
-
-
 
 % \clearpage
 
@@ -3934,7 +3918,7 @@ Regarding colors, generally speaking all color commands inside
 use or not colors is left to the user.
 
 
-% \clearpage
+%\clearpage
 
 \etocdepthtag.toc {tips}
 
@@ -3943,6 +3927,12 @@ use or not colors is left to the user.
 
 \thispartstats
 
+%%%% \invisiblelocaltableofcontents \label{toc:tipsandtricks}
+
+\etocsettocstyle{}{}
+\etocstandardlines
+\localtableofcontents
+
 \section{... and tricks}
 
 \subsection{Hacking  framed parboxes}
@@ -4014,7 +4004,8 @@ this technique):
 \renewcommand{\etoccolumnsep}{2.75em}
 \renewcommand{\columnseprule}{1pt}
 
-\etocmarkbothnouc{List of all subsections}
+%%\etocmarkbothnouc{List of all subsections}
+%% le mark (\markright) est fait par \subsection
 
 \etocmulticol[3]{\subsection{All subsections of this document}\label{toc:allsubsections}}
 
@@ -4036,9 +4027,7 @@ 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
-\def\MacroFont{\footnotesize\ttfamily\hyphenchar\font45 \relax}
+But first, the code of \csa{thispartstats}:\par
 \begin{verbatim}
 \newsavebox\firstnamei  \newsavebox\firstnumberi
 \newsavebox\lastnamei   \newsavebox\lastnumberi
@@ -4077,14 +4066,13 @@ But first, the coding of \csa{thispartstats}:\par
     \unhbox\lastnumberi. The name of the first subsection is \unhbox\firstnameii{}
     and the corresponding number is \unhbox\firstnumberii. The name of the last
     subsection is \unhbox\lastnameii{} and its number is \unhbox\lastnumberii.}%
-  \etocinline % don't do a \par automatically (but this is not used, actually).
+  \etocinline % cancels the automatic \par automatically before the TOC
   \etocsettocstyle {}{}
   \etocsetnexttocdepth{2}%
   \localtableofcontents  % to be used at the top level of a Part.
   \endgroup
 }
 \end{verbatim}
-%\endgroup
 
 And now, the variant with macros rather than boxes (this variant as it
 stands here is for using within a section).
@@ -4120,7 +4108,6 @@ stands here is for using within a section).
 }
 \makeatother
 \end{verbatim}
-\endgroup
 
 \subsection{Using depth tags}
 \label{ssec:tocwithdepthtags}
@@ -4144,6 +4131,8 @@ underneath the numbers contrarily to the code from
 lengths (now that this has been done once, it can be recycled easily) we
 get:
 
+%\clearpage
+
 \etocsetnexttocdepth {all}
 \begingroup
 \parindent 0pt
@@ -4207,7 +4196,6 @@ get:
                     \fbox{\makebox[8cm]{A TOC using depth tags}}}
 \sloppy
 \tableofcontents
-\endgroup
 
 \begin{verbatim}
 \etocsetnexttocdepth {all}
@@ -4272,6 +4260,141 @@ get:
 \tableofcontents
 \endgroup
 \end{verbatim}
+\endgroup
+
+\subsection{Typesetting the TOC as a table}\label{ssec:tocastable}
+
+Tabular cells create groups; definitions of |\etocname|, |\etocnumber|,
+|\etocpage| made by \etoc are local, thus if the first cell of a row is
+where the |.toc| file line is read and |\etocname| and |\etocnumber|
+get defined, these definitions will be lost after the tabulation character |&|.
+The source code of \etoc does allow the ``begin'' and ``finish'' parts of
+the line styles to open or close groups, but the possibility of a group closed
+by  a |&| for
+example in the ``prefix'' part of the line style is not anticipated.
+ 
+Another, similar, matter regards the redefinition of |\contentsline| made by
+\etoc each time it typesets a TOC. It is done after the first argument to
+\csb{etocsettocstyle} has been executed, hence if this argument opens a tabular,
+the |etoc| redefinition of |\contentsline| will be done in the first cell of the
+first row and get lost thereafter.
+
+Thus one can not typeset a TOC directly as a tabular, with the opening and
+closing specified via |\etocsettocstyle|, and using |&| and |\\| inside the
+level styles.
+
+The \etoc source code could be modified to make some relevant definitions
+global, but I decided against it. Typesetting as a |tabular| (or, rather,
+|longtable|) will appeal only to advanced users, and advanced users can employ
+the technique explained in \autoref{tocastree}. Here is an example, giving again
+a fully hyperlinked table of contents. The code follows, after the table.
+
+\newtoks\toctabletok
+% \newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
+%   #1\expandafter\expandafter\expandafter
+%     {\expandafter\the\expandafter #1#2}}
+
+\newcommand*\PreparePart{%
+  \toks0 \expandafter{\etocthelinkednumber}%
+  \toks2 \expandafter{\etocthelinkedname}%
+  \toks4 \expandafter{\etocthelinkedpage}%
+  \edef\toctablepiece {\noexpand\hline
+                      \strut\the\toks0 &\noexpand\bfseries\the\toks2 
+                                 &\the\toks4 \noexpand\\ 
+                      \noexpand\hline}% 
+}
+
+\newcommand*\PrepareSection{%
+  \toks0 \expandafter{\etocthelinkednumber}%
+  \toks2 \expandafter{\etocthelinkedname}%
+  \toks4 \expandafter{\etocthelinkedpage}%
+  \edef\toctablepiece {\the\toks0 &\the\toks2 &\the\toks4 \noexpand\\}% 
+}
+
+\newcommand*{\PrepareSubsection}{%
+  \toks0 \expandafter{\etocthelinkednumber}%
+  \toks2 \expandafter{\etocthelinkedname}%
+  \toks4 \expandafter{\etocthelinkedpage}%
+  \edef\toctablepiece{\noexpand\centering
+                      \the\toks0 &\the\toks2 &\noexpand\itshape\the\toks4
+                      \noexpand\\}%
+}
+
+\etocsetstyle{part}{}{}
+  {\PreparePart \appendtotok\toctabletok\toctablepiece}
+  {}
+
+\etocsetstyle{section}{}{}
+  {\PrepareSection \appendtotok\toctabletok\toctablepiece}
+  {}
+
+\etocsetstyle{subsection}{}{}
+  {\toctabletok\expandafter
+     {\the\toctabletok &\small\begin{tabular}{@{}p{1cm}@{}p{5cm}r@{}}}%
+   \PrepareSubsection\appendtotok\toctabletok\toctablepiece
+   \toctabletok\expandafter{\the\toctabletok\end{tabular}&\\}}
+  {}
+
+\etocsettocstyle
+    {\toctabletok{\hypersetup{hidelinks}%
+                 \begin{longtable}{|>{\bfseries}c|p{7cm}|r|}\hline
+                 \multicolumn{3}{|c|}{\Large\bfseries\strut TABLE OF CONTENTS}%
+                 \\\hline\hline}}
+    {\global\toctabletok\expandafter{\the\toctabletok\hline\end{longtable}}}
+
+\etocsettocdepth {subsection}
+\tableofcontents
+\the\toctabletok
+
+\begin{verbatim}
+\newtoks\toctabletok
+\newcommand*\appendtotok[2]{% #1=toks variable, #2=macro, expands once #2
+  #1\expandafter\expandafter\expandafter {\expandafter\the\expandafter #1#2}}
+
+\newcommand*\PreparePart{%
+  \toks0 \expandafter{\etocthelinkednumber}%
+  \toks2 \expandafter{\etocthelinkedname}%
+  \toks4 \expandafter{\etocthelinkedpage}%
+  \edef\toctablepiece {\noexpand\hline
+                      \strut\the\toks0 &\noexpand\bfseries\the\toks2 
+                                 &\the\toks4 \noexpand\\ 
+                      \noexpand\hline}% 
+}
+\newcommand*\PrepareSection{%
+  \toks0 \expandafter{\etocthelinkednumber}%
+  \toks2 \expandafter{\etocthelinkedname}%
+  \toks4 \expandafter{\etocthelinkedpage}%
+  \edef\toctablepiece {\the\toks0 &\the\toks2 &\the\toks4 \noexpand\\}% 
+}
+\newcommand*{\PrepareSubsection}{%
+  \toks0 \expandafter{\etocthelinkednumber}%
+  \toks2 \expandafter{\etocthelinkedname}%
+  \toks4 \expandafter{\etocthelinkedpage}%
+  \edef\toctablepiece{\noexpand\centering\the\toks0 
+                      &\the\toks2 &\noexpand\itshape\the\toks4 \noexpand\\}%
+}
+\etocsetstyle{part}{}{}
+  {\PreparePart    \appendtotok\toctabletok\toctablepiece}{}
+\etocsetstyle{section}{}{}
+  {\PrepareSection \appendtotok\toctabletok\toctablepiece}{}
+\etocsetstyle{subsection}{}{}
+% each line does its own tabular, to allow page breaks in the long table
+  {\toctabletok\expandafter
+     {\the\toctabletok &\small\begin{tabular}{@{}p{1cm}@{}p{5cm}r@{}}}%
+   \PrepareSubsection\appendtotok\toctabletok\toctablepiece
+   \toctabletok\expandafter{\the\toctabletok\end{tabular}&\\}}
+  {}
+
+\etocsettocstyle
+    {\toctabletok{\hypersetup{hidelinks}%
+                 \begin{longtable}{|>{\bfseries}c|p{7cm}|r|}\hline
+                 \multicolumn{3}{|c|}{\Large\bfseries\strut TABLE OF CONTENTS}%
+                 \\\hline\hline}}
+    {\global\toctabletok\expandafter{\the\toctabletok\hline\end{longtable}}}
+\etocsettocdepth {subsection}
+\tableofcontents
+\the\toctabletok
+\end{verbatim}
 
 \subsection{Compatibility with other packages}
 \label{etocaftertochook}
@@ -4400,6 +4523,7 @@ groups. All TOCs are typeset inside groups.
 
 
 
+\clearpage
 \etocdepthtag.toc {code}
 
 \part{The code}
@@ -4408,7 +4532,7 @@ groups. All TOCs are typeset inside groups.
 
 This is the documentation as of \texttt{\docdate}, printed from the source file
 with the time stamp \texttt{\dtxtimestamp}. The package version is
-\texttt{\pkgversion}, of \texttt{\pkgdate}.
+\texttt{\jfbpkgversion}, of \texttt{\jfbpkgdate}.
 
 
 \section{License, installation}
@@ -4503,6 +4627,12 @@ with the time stamp \texttt{\dtxtimestamp}. The package version is
 
 \begin{multicols}{2}
 \begin{jfverbatim}
+v1.07j [2013/12/03]
+
+   some issues with the documentation formatting (now two-sided) have been
+   addressed, and a novel documentation section ``Typesetting the TOC as a
+   table'' has been added. Very minor code change (\Etoc@readtoc).
+
 v1.07i [2013/10/21]
 
    changes to the \etocmulticolstyle and \etocruledstyle codes 
@@ -4561,7 +4691,7 @@ v1.07e [2013/03/01]
 v1.07d [2013/02/24]
 
    minor code improvements and new documentation 
-   section "Another compatibility mode".
+   section ``Another compatibility mode''.
 
 
 v1.07b [2013/02/02]
@@ -4584,8 +4714,8 @@ v1.07 [2013/01/29]
 
    modified command: \etocmulticolstyle
 
-   new documentation section "Surprising uses of etoc" which
-   explains how to do "Lists of arbitrary things", in
+   new documentation section ``Surprising uses of etoc'' which
+   explains how to do  ``Lists of arbitrary things'', in
    addition to the tables of contents.
 
 
@@ -4634,8 +4764,7 @@ v1.02 [2012/11/18]
 
 \small
 
-\def\MacroFont{\ttfamily\hyphenchar\font45 
-               \baselineskip11pt\relax }
+% \def\MacroFont{\ttfamily\hyphenchar\font45 \baselineskip11pt\relax }
 
 \section{Implementation}
 
@@ -4672,8 +4801,8 @@ v1.02 [2012/11/18]
   \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
+\string\ProvidesPackage\string{\jfbpkgname\string}\par
+\noindent\space [\jfbpkgdate\space\jfbpkgversion\space\jfbpkgdescription]\par
 \nointerlineskip
 \global\@inlabelfalse
 \endtrivlist
@@ -5188,26 +5317,25 @@ v1.02 [2012/11/18]
 \DeclareRobustCommand*{\etocifnumbered}
    {\ifEtoc@number\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}
 %    \end{macrocode}
-% placeholder for comments
+% |1.07j| modifies |\Etoc@readtoc|.
 %    \begin{macrocode}
-\def\Etoc@readtoc#1{%
-  \ifeof #1
-     \let\Etoc@nextread\@gobble
-     \global\Etoc@toctoks=\expandafter{\the\Etoc@toctoks}%
+\def\Etoc@readtoc {%
+  \ifeof \Etoc@tf
   \else
-     \let\Etoc@nextread\Etoc@readtoc
-     \read #1 to \Etoc@buffer
+     \read \Etoc@tf to \Etoc@buffer
      \Etoc@toctoks=\expandafter\expandafter\expandafter
        {\expandafter\the\expandafter\Etoc@toctoks\Etoc@buffer}%
+     \expandafter\Etoc@readtoc
   \fi
-  \Etoc@nextread{#1}%
 }
+\Etoc@toctoks {}% (superfluous, but for clarity)
 \IfFileExists{\jobname .toc}
     {{\endlinechar=-1 
       \makeatletter
       \newread\Etoc@tf
       \openin\Etoc@tf\@filef@und
-      \Etoc@readtoc\Etoc@tf
+      \Etoc@readtoc
+      \global\Etoc@toctoks=\expandafter{\the\Etoc@toctoks}%
       \closein\Etoc@tf}}
     {\typeout{No file \jobname .toc.}}
 %    \end{macrocode}
@@ -5228,7 +5356,7 @@ v1.02 [2012/11/18]
    \newwrite \tf@toc 
    \immediate \openout \tf@toc \jobname .toc\relax 
   \fi 
-  \gdef\Etoc@openouttoc{}%
+  \global\let\Etoc@openouttoc\empty
 }
 %    \end{macrocode}
 % placeholder for comments
@@ -5399,7 +5527,7 @@ v1.02 [2012/11/18]
      {\def\Etoc@aftertitlehook{}\Etoc@localtable@fcontents}
      {\let\Etoc@aftertitlehook\etocaftertitlehook\Etoc@localtable@fcontents}}
 %    \end{macrocode}
-% placeholder for comments
+% placeholder for comments.
 %    \begin{macrocode}
 \newcommand\etocsettocstyle[2]{%
 \def\Etoc@tableofcontents
@@ -5411,7 +5539,7 @@ v1.02 [2012/11/18]
             #1\ifEtoc@parskip\parskip\z@skip\fi %1.07d
               \Etoc@aftertitlehook
               \let\Etoc@savedcontentsline\contentsline
-              \let\contentsline\Etoc@etoccontentsline
+              \let\contentsline\Etoc@etoccontentsline 
               \Etoc@toctoc
               \let\Etoc@@next\relax
               \ifEtoc@tocwithid\else
@@ -6159,7 +6287,7 @@ v1.02 [2012/11/18]
   Grave accent  \`     Left brace    \{     Vertical bar  \|
   Right brace   \}     Tilde         \~}
 
-\CheckSum{2910}
+\CheckSum{2909}
 
 \csname check@checksum\endcsname
 \Finale
-- 
cgit v1.2.3

