etoc (4mar13)

git-svn-id: svn://tug.org/texlive/trunk@29289 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 771 insertions, 209 deletions

diff --git a/Master/texmf-dist/source/latex/etoc/etoc.dtx b/Master/texmf-dist/source/latex/etoc/etoc.dtx
index aaee5430715..f89033663b1 100644
--- a/Master/texmf-dist/source/latex/etoc/etoc.dtx
+++ b/Master/texmf-dist/source/latex/etoc/etoc.dtx
@@ -10,12 +10,12 @@
 %% Copyright (C) 2012, 2013 by Jean-Francois Burnol
 %%
 %<*none>
-\def\lasttimestamp{Time-stamp: <01-03-2013 15:31:43 CET jfb>}
-\def\docdate{2013/03/01}
+\def\lasttimestamp{Time-stamp: <03-03-2013 22:08:48 CET jfb>}
+\def\docdate{2013/03/03}
 \def\striptimestamp#1 <#2 #3 #4 #5>{#2 at #3 #4}
 \edef\dtxtimestamp{\expandafter\striptimestamp\lasttimestamp}
 \ProvidesFile{\pkgname.dtx}
-  [`\pkgname' source and documentation (\dtxtimestamp)]
+ [`\pkgname' source and documentation (\dtxtimestamp)]
 %
 % The copyright statement at the top of this file applies to `etoc.dtx'
 % and to its derived files.
@@ -86,6 +86,8 @@
 %<*none>
 \fi
 \documentclass[a4paper,11pt,abstract]{scrdoc}
+%%\OnlyDescription
+
 \usepackage[T1]{fontenc}
 \usepackage[latin1]{inputenc}
 \usepackage[hscale=0.66,vscale=0.75]{geometry}
@@ -95,7 +97,7 @@
 \def\MacroFont{\ttfamily\small\baselineskip12pt\relax}
 
 \usepackage{txfonts} % m'occuper de la taille de txtt:
-% au passage je supprime \hyphenchar \font\m@ne
+% au passage je supprime le \hyphenchar \font\m@ne
 
 \DeclareFontFamily{T1}{txtt}{}
 \DeclareFontShape{T1}{txtt}{m}{n}{	%medium
@@ -150,10 +152,12 @@
 \usepackage{graphicx}
 \usepackage{enumitem}
 
+
 % ok il faut ceci pour dvipdfmx:
 %\def\pgfsysdriver{pgfsys-dvipdfm.def}
 
 \usepackage{tikz}
+\usetikzlibrary{trees}    % added for "cyclic" grow function 2013/03/02
 \usepackage{tikz-qtree}
 
 % I have tried this (2013/03/01) to fix the problem with hyperlinks
@@ -166,7 +170,12 @@
 % ** WARNING ** Annotation: [94.3997 1200.33 146.512 1209.98]
 % ** WARNING ** Maybe incorrect paper size specified.
 
-% cependant j'ai un autre problème avec dvipdfmx qui donne aussi:
+% UPDATE: 2013/03/03. This problem actually seems to be specific of the
+% tikz-qtree, it miraculously went away when I constructed trees with the
+% original TikZ syntax!! and there was no need of hopgf.sty (or was it a
+% problem of final resizing?). And ok for dvipdfmx as well as pdflatex.
+
+% cependant j'ai un autre problème avec dvipdfmx qui donne par ailleurs:
 % ** WARNING ** Obsolete four arguments of "endchar" will be used for Type 1
 % "seac" operator. 
 % ce qui semble lié à txtt, même après avoir retiré mon inclusion modifiée de
@@ -277,6 +286,103 @@ pdfpagemode=UseOutlines}
   \tableofcontents #1
   \endgroup}
 \makeatother
+%--------
+% 2 mars \thispartstats macro:
+
+\newsavebox\firstnamei
+\newsavebox\firstnumberi
+\newsavebox\lastnamei
+\newsavebox\lastnumberi
+\newsavebox\firstnameii
+\newsavebox\firstnumberii
+\newsavebox\lastnameii
+\newsavebox\lastnumberii
+\newcounter{mycounti}
+\newcounter{mycountii}
+
+\newcommand*{\thispartstatsauxi}{}
+\newcommand*{\thispartstatsauxii}{}
+\newcommand*{\oldtocdepth}{}
+
+\newcommand*{\thispartstats}{%
+  \edef\oldtocdepth{\arabic{tocdepth}}%
+  \setcounter{tocdepth}{2}%
+  \setcounter{mycounti}{0}%
+  \setcounter{mycountii}{0}%
+  \def\thispartstatsauxi{%
+         \sbox{\firstnamei}{\color{cyan}\etocname}%
+         \sbox{\firstnumberi}{\color{cyan}\etocnumber}%
+         \def\thispartstatsauxi{}}%
+  \def\thispartstatsauxii{%
+         \sbox{\firstnameii}{\color{cyan}\etocname}%
+         \sbox{\firstnumberii}{\color{cyan}\etocnumber}%
+         \def\thispartstatsauxii{}}%
+  \begingroup
+  \etocsetstyle{subsection}
+    {}
+    {}
+    {\thispartstatsauxii
+     \stepcounter{mycountii}%
+     \sbox{\lastnameii}{\color{teal}\etocname}%
+     \sbox{\lastnumberii}{\color{teal}\etocnumber}}
+    {}
+  \etocsetstyle{section}
+    {}
+    {}
+    {\thispartstatsauxi
+     \stepcounter{mycounti}%
+     \sbox{\lastnamei}{\color{teal}\etocname}%
+     \sbox{\lastnumberi}{\color{teal}\etocnumber}}
+    {Here are some statistics for this part: it contains \arabic{mycounti}
+      section\ifnum\value{mycounti}>1 s\fi{} and
+      \arabic{mycountii} subsection\ifnum\value{mycountii}>1 s\fi. The name of
+	 the first section is 
+     \unhbox\firstnamei{} and the corresponding number is 
+     \unhbox\firstnumberi. The name of the last section is 
+     \unhbox\lastnamei{} and its number is \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. 
+     Click on the names or numbers to get confirmation!}% 
+  \etocinline % don't do a \par automatically
+  \etocsettocstyle {}{}
+  \localtableofcontents
+  \endgroup
+  \setcounter{tocdepth}{\oldtocdepth}%
+}
+
+% \makeatletter
+% \newcommand*{\restoretocdepth}{}%
+% \newcommand*{\thispartstats}[1][{part}{section}]{%
+% \edef\restoretocdepth{\noexpand\setcounter{tocdepth}{\arabic{tocdepth}}}%
+% \setcounter{tocdepth}{\csname Etoc@\@secondoftwo#1@@\endcsname}%
+% \begingroup
+% \etocsetstyle{\@secondoftwo#1}
+%     {\setcounter{mycount}{0}%
+%      \def\thispartstatsaux{%
+%          \sbox\firstname{\color{cyan}\etocname}%
+%          \sbox\firstnumber{\color{cyan}\etocnumber}%
+%          \def\thispartstatsaux{}}}
+%     {}
+%     {\thispartstatsaux
+%      \stepcounter{mycount}%
+%      \sbox\lastname{\color{teal}\etocname}%
+%      \sbox\lastnumber{\color{teal}\etocnumber}}
+%     {this \@firstoftwo#1 has \arabic{mycount}
+%       \@secondoftwo#1\ifnum\c@mycount>1 s\fi. The name of
+% 	   its first is 
+%      \unhbox\firstname{} and the corresponding number is 
+%      \unhbox\firstnumber. The name of the last \@secondoftwo#1 is 
+%      \unhbox\lastname{} and its number is \unhbox\lastnumber. 
+%      Click on the names or numbers to get confirmation!}% 
+% \etocsettocstyle{Here are some statistics for this \@firstoftwo#1: }{\par}%
+% %\etocinline
+% \localtableofcontents
+% \endgroup
+% \restoretocdepth}
+% \makeatother
+
 
 
 \newcommand\toc{\csa{table\-of\-contents}\xspace}
@@ -295,13 +401,13 @@ pdfpagemode=UseOutlines}
 \hyphenation{etoc-link etoc-stan-dard-lines etoc-toc-lines}
 \hyphenation{etoc-in-ner-top-sep}
 
-
-
 \frenchspacing
 
 \renewcommand\familydefault\sfdefault
 
-\setcounter{secnumdepth}{3}
+\setcounter{secnumdepth}{4}
+
+%% \usepackage{tableof}  % was for testing only.
 
 \begin{document}
 
@@ -443,6 +549,9 @@ v1.07e [2013/03/01]
    addition to the documentation of an example of
    a tree-like table of contents (uses tikz).
 
+   more such examples added 2013/03/03.
+
+
 v1.07d [2013/02/24]
 
    minor code improvements and new documentation 
@@ -522,15 +631,27 @@ v1.02 [2012/11/18]
 \begingroup
   \etocsetlevel{subsection}{3}
   \etocsetlevel{subsubsection}{6}
+
+%% essai de tableof:
+%%\nexttocwithtags{ESSAI}{}
+
   \tableofcontents \label{toc:main}
+
+%%\tableof{ESSAI}
+
 \endgroup
 
+\clearpage
+
 \part{Overview}\label{part:one}
 
+\thispartstats
+
 \setcounter{tocdepth}{-3}
 \localtableofcontents \label{toc:partone}
 \setcounter{tocdepth}{3}
 
+%%\toftagthis{ESSAI}
 \section{Initial motivation: nested lists}
 
 The initial impetus was to feed nested list environments
@@ -683,10 +804,6 @@ contents\footnote{Up to version |1.04| we called this
 given chapter, or all subsubsections and lower inside a given
 subsection, etc . . .
 
-
-
-
-
 \subsection{Labeling and reusing elsewhere}
 
 \etoc allows the labeling of a TOC with \csa{label\{toc:A\}}
@@ -718,7 +835,8 @@ We actually did something like:\\
 can itself now be referred to via |\ref{toc:d}|: it gives
 the id of this TOC\footnote{\emph{i.e}
 {\color{niceone}\ref{toc:d}}, there was an invisible
-TOC with id 2 at the beginning of this part.} in the sequence of
+TOC with id 2 and another one whose identity is left to the reader's sagacity.}
+  in the sequence of 
 document TOCs, and will be a link if package |hyperref| is
 used.
 
@@ -803,9 +921,8 @@ explained further in the section \ref{sec:surprising}.
 
 \subsection{Local table of contents for this part}
 
-Immediately after the
-line in the source file starting with the first
-\csa{part} we wrote:
+Immediately after the |\part{Overview}|
+line in the source file we inserted:
 %
 % The \csa{label} command should follow \toc  before the reference via
 % \csa{ref} to the other TOC. Indeed a \csa{label} following it is
@@ -818,20 +935,23 @@ line in the source file starting with the first
 \begin{verbatim}
     \setcounter{tocdepth}{-3}
     \localtableofcontents \label{toc:partone}
-\end{verbatim}
-The |tocdepth| being set to -3, nothing at all was typeset in the page
-(\etoc 
-cancels printing even the heading of the TOC if the |tocdepth| is -2 or
-less, except for the |memoir| class for which it needs to be -3 or less).
-We can then display here this TOC with:
-\begin{verbatim}
     \setcounter{tocdepth}{3}
-    \tableofcontents \ref{toc:partone}
 \end{verbatim}
+The |tocdepth| having been  set to -3, nothing at all was typeset, as
+\etoc 
+cancels printing even the heading of the TOC if the |tocdepth| is -3 or
+less (and it is even ``-2 or less'', except for the |memoir| class).
+We could then display here this TOC with:\par
+\hbox to \linewidth{\hss|\tableofcontents \ref{toc:partone}|\hss}
+But we have decided to use the \csa{etocframedstyle} package command, and the
+  produced table of contents has to fit on a single page. With all the recent
+  additions to the documentation there is not enough room here, so we wrap it up
+  in a figure environment and it will show on next page.
+
 
 \setcounter{tocdepth}{3}
 
-\begingroup
+\begin{figure*}[t!]\centering
 \colorlet{subsecnum}{black}
 \colorlet{secbackground}{green!30}
 \colorlet{tocbackground}{red!20!green!20}
@@ -897,10 +1017,9 @@ We can then display here this TOC with:
 {}
 
 \etocframedstyle[1]{}
-
+\hbox to \linewidth{\hss|\tableofcontents \ref{toc:partone}|\hss}
 \tableofcontents \ref{toc:partone}
-
-\endgroup
+\end{figure*}
 
 The actual design is not pre-built in \etoc; it uses the \etoc
 `framed' style with a background color and a dummy empty
@@ -912,92 +1031,83 @@ which serves as background for the entire thing. This design
 \hyperref[toc:clone]{\color{niceone}this other toc},
 and the coding used is to be found at its location. 
 
-Here is now a far simpler design.
-
-
 \section{A simple example}
 
-Here is a simple example of use of the package
+Here is a simpler example of use of the package
 functionalities. We display again the local table of contents
 for this part but
 choose font sizes and style which would be used rather
 for, respectively, chapters and sections in an average length
 memoir. 
 
-\begingroup
-\newlength{\tocleftmargin}
-\setlength{\tocleftmargin}{5cm}
-\newlength{\tocrightmargin}
-\setlength{\tocrightmargin}{1cm}
 
-\etocsetstyle{section}
+First, the line style specifications. They have some
+redundancy for clarity, and do not care about what to do at
+possible page breaks. Also, this does not care about potential 
+multi-column use.
+
+\begin{verbatim}
+\begingroup % we start a group to keep the style changes local
+\newlength{\tocleftmargin}    \setlength{\tocleftmargin}{5cm}
+\newlength{\tocrightmargin}   \setlength{\tocrightmargin}{1cm}
+
+\etocsetstyle{section}              % will pretend to be a Chapter
 {\addvspace{1ex}\parfillskip0pt
- \leftskip\tocleftmargin
+ \leftskip\tocleftmargin            % (already done in title)
  \rightskip\the\tocrightmargin plus 1fil
- \parindent0pt\color{cyan}}
+ \parindent0pt\color{cyan}}         % (already done)
 {\bfseries\LARGE\upshape\addvspace{1ex}\leavevmode}
 {\llap{Chapter\hspace{.5em}{\etocnumber}\hspace{.75cm}}\etocname
  \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
 {}
 
-\etocsetstyle{subsection}
+\etocsetstyle{subsection}           % will pretend to be a Section
 {}
 {\mdseries\large\addvspace{.5ex}\leavevmode}
 {\llap{\etocnumber\hspace{.75cm}}\textit{\etocname}%
  \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
 {}
 
-\etocsettocstyle{\color{cyan}\parindent0pt\leftskip\tocleftmargin
+% \color{cyan}\parindent0pt and \leftskip\tocleftmargin were repeated
+% in the <start> code of the ``section style'', for clarity of code.
+
+\etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin
   \leavevmode\leaders\hrule height 1pt\hfill\ 
   \huge\textit{My Beautiful Thesis}\par}{\bigskip}
 
-% \color{cyan}\parindent0pt is repeated in the <start> code
-% of the section style, for clarity of code.
-
 \tableofcontents \ref{toc:partone}
 \endgroup
+\end{verbatim}
 
-And now, the line style specifications. They have some
-redundancy for clarity, and do not care about what to do at
-possible page breaks. Also, this does not care about potential 
-multi-column use.
-
-\begin{verbatim}
-\begingroup % we start a group to keep the style changes local
-% the changes to paragraph layout parameters done in the style
-% specifications would anyhow have been kept local as the TOCs are 
-% always typeset by the package in a group. 
-\newlength{\tocleftmargin}    \setlength{\tocleftmargin}{5cm}
-\newlength{\tocrightmargin}   \setlength{\tocrightmargin}{1cm}
+\begingroup
+\newlength{\tocleftmargin}
+\setlength{\tocleftmargin}{5cm}
+\newlength{\tocrightmargin}
+\setlength{\tocrightmargin}{1cm}
 
-\etocsetstyle{section}              % would be chapter in real life
+\etocsetstyle{section}
 {\addvspace{1ex}\parfillskip0pt
- \leftskip\tocleftmargin            % was already done in title
+ \leftskip\tocleftmargin
  \rightskip\the\tocrightmargin plus 1fil
- \parindent0pt\color{cyan}}         % again this was already done
+ \parindent0pt\color{cyan}}
 {\bfseries\LARGE\upshape\addvspace{1ex}\leavevmode}
 {\llap{Chapter\hspace{.5em}{\etocnumber}\hspace{.75cm}}\etocname
  \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
 {}
 
-\etocsetstyle{subsection}           % would be section in real life
+\etocsetstyle{subsection}
 {}
 {\mdseries\large\addvspace{.5ex}\leavevmode}
 {\llap{\etocnumber\hspace{.75cm}}\textit{\etocname}%
  \hfill\makebox[-\tocrightmargin][l]{\makebox[0pt]{\etocpage}}\par}
 {}
 
-% \color{cyan}\parindent0pt and \leftskip\tocleftmargin
-% were repeated in the <start> code of the ``section style'', 
-% for clarity of code.
-
-\etocsettocstyle{\color{cyan}\parindent0pt \leftskip\tocleftmargin
+\etocsettocstyle{\color{cyan}\parindent0pt\leftskip\tocleftmargin
   \leavevmode\leaders\hrule height 1pt\hfill\ 
   \huge\textit{My Beautiful Thesis}\par}{\bigskip}
 
 \tableofcontents \ref{toc:partone}
 \endgroup
-\end{verbatim}
 
 As one can see, the code uses the basic commands from
 \TeX/\LaTeX{} for paragraph layouts and an efficient mix of
@@ -1028,9 +1138,107 @@ signification.
 \section{Surprising uses of \etoc}
 \label{sec:surprising}
 
+% This variant uses macros rather than boxes, which allows greater flexibility.
+
+\makeatletter
+\newcommand*\firstsubname       {}
+\newcommand*\lastsubname        {}
+\newcommand*\firstsubnumber     {}
+\newcommand*\lastsubnumber      {}
+\newcommand*\thissectionstatsaux{}
+
+\newcommand*{\thissectionstats}{%
+  \edef\oldtocdepth{\arabic{tocdepth}}%
+  \setcounter{tocdepth}{2}%
+  \setcounter{mycounti}{0}%
+  \def\thissectionstatsaux{% ou plus simple si on ne veut pas le lien.
+         \toks@\expandafter{\etocthename}%
+         \edef\firstsubname{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+         \toks@\expandafter{\etocthenumber}%
+         \edef\firstsubnumber{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+         \def\thissectionstatsaux{}}
+  \begingroup
+  \etocsetstyle{subsection}
+    {}
+    {}
+    {\thissectionstatsaux
+     \stepcounter{mycounti}%
+     \toks@\expandafter{\etocthename}%
+     \edef\lastsubname{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+     \toks@\expandafter{\etocthenumber}%
+     \edef\lastsubnumber{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+    }
+    {Here are some statistics for this section. It contains \arabic{mycounti}
+      subsections. The name of 
+	 its first is 
+     \emph{\color{cyan}\firstsubname{}} and the corresponding number is 
+     {\color{cyan}\firstsubnumber}. The name of the last subsection is 
+     \emph{\color{teal}\lastsubname{}} and its number is 
+     {\color{teal}\lastsubnumber}.}% 
+   \etocsettocstyle {}{}
+   \etocinline
+   \localtableofcontents
+  \endgroup
+  \setcounter{tocdepth}{\oldtocdepth}%
+}
+\makeatother
+
+% more general version:
+% \makeatletter
+% \newcommand*\firstsubname{}
+% \newcommand*\lastsubname{}
+% \newcommand*\firstsubnumber{}
+% \newcommand*\lastsubnumber{}
+% \renewcommand*{\thispartstats}[1][section]{%
+% \edef\oldtocdepth{\arabic{tocdepth}}%
+% \setcounter{tocdepth}{\csname Etoc@#1@@\endcsname}%
+% \begingroup
+% \etocsetstyle{book}{}{}{}{}%
+% \etocsetstyle{part}{}{}{}{}%
+% \etocsetstyle{chapter}{}{}{}{}%
+% \etocsetstyle{section}{}{}{}{}%
+% \etocsetstyle{subsection}{}{}{}{}%
+% \etocsetstyle{subsubsection}{}{}{}{}%
+% \etocsetstyle{paragraph}{}{}{}{}%
+% \etocsetstyle{subparagraph}{}{}{}{}%
+% \setcounter{mycounti}{0}%
+% \def\thispartstatsaux{% ou plus simple si on ne veut pas le lien.
+%        \toks@\expandafter{\etocthename}%
+%        \edef\firstsubname{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+%        \toks@\expandafter{\etocthenumber}%
+%        \edef\firstsubnumber{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+%        \def\thispartstatsaux{}}
+% \etocsetstyle{#1}
+%     {}
+%     {}
+%     {\thispartstatsaux
+%      \stepcounter{mycounti}%
+%      \toks@\expandafter{\etocthename}%
+%      \edef\lastsubname{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+%      \toks@\expandafter{\etocthenumber}%
+%      \edef\lastsubnumber{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+%     }
+%     {}% 
+% \etocsettocstyle{}
+% {\arabic{mycounti}
+%       #1\ifnum\c@mycounti>1 s\fi. The name of
+% 	its first is 
+%      \emph{\color{cyan}\firstsubname{}} and the corresponding number is 
+%      {\color{cyan}\firstsubnumber}. The name of the last #1 is 
+%      \emph{\color{teal}\lastsubname{}} and its number is 
+%      {\color{teal}\lastsubnumber}. 
+%      Click on the names or numbers to get confirmation!}%
+% \etocinline
+% Here are some statistics for this unit: it has\localtableofcontents\par
+% \endgroup
+% \setcounter{tocdepth}{\oldtocdepth}}
+% \makeatother
+
+\thissectionstats
+
 \subsection{The TOC of TOCs}
 
-\begingroup
+\begingroup % \endgroup just after the \tableofcontents command
 \etocinline
 \etocsetlevel{part}{1}
 \etocsetlevel{chapter}{1}
@@ -1048,7 +1256,9 @@ Here is the numbered and linked list of all tables of contents which are
 displayed within this document: 
 \tableofcontents\endgroup. And to obtain
 it here we just wrote:\footnote{click the `\protect\thevisibletoc'
-  in the list to get confirmation...}\par\smallskip
+  in the list to get confirmation... and click on the previous `\number
+  \numexpr\csname c@visibletoc\endcsname-1\relax' for a surprise...
+}\par\smallskip 
 {\leftskip1cm\rightskip5cm
   \ttfamily\small\baselineskip11pt \noindent Here is the
   numbered and linked list of all tables of contents which are
@@ -1094,7 +1304,7 @@ it here we just wrote:\footnote{click the `\protect\thevisibletoc'
   The package provides a starred variant
   \staritb{etoctoccontentsline}, which will allow the creation
   of bookmarks and has a third mandatory argument which is the
-  level to be used by these bookmarks.
+  Level to be used by these bookmarks.
 
   Finally, the preamble of the document did
   |\etocsetlevel{visibletoc}{6}|. The level |6| (or anything
@@ -1234,24 +1444,12 @@ Another question (numbered |61297|) on the \TeX{} StackExchange
 site was about using \LaTeX{} to obtain a table of contents where
 the sections from a given chapter would be represented by a number
 range (like 18--22 for a given chapter, 42--49 for another one ...
-of course to be inserted automatically in the TOC). The next page
-is the result of my effort at using \etoc for this problem. How
+of course to be inserted automatically in the TOC). Here is
+the result of my effort at using \etoc for this specific problem. How
 this was done will be found on the above cited site.
 
-This is not an image inclusion, the TOC is produced from its original
-|tex| source inserted in this document after replacement of 
-|part|, |chapter| or |section| with |dummypart|, |dummychapter| and
-|dummysection| (and there is also a dummy page count).  We
-copied the line styles used in the original and
-displayed the table of contents following:
-\begin{verbatim}
-    \etocsetlevel{dummypart}  {-1} \etocsetlevel{part}   {2}
-    \etocsetlevel{dummychapter}{0} \etocsetlevel{chapter}{2}
-    \etocsetlevel{dummysection}{1} \etocsetlevel{section}{2}
-                    \setcounter{tocdepth}{1}
-\end{verbatim}
 
-% \clearpage
+%\clearpage
 
 \begingroup
 
@@ -1331,9 +1529,9 @@ displayed the table of contents following:
     }
         
     \setcounter{tocdepth}{1}
-    \leavevmode\vfil
+
     \tableofcontents
-    \vfil\clearpage
+   
 
 \makeatletter
     \def\adddummysection {\stepcounter{dummysection}%
@@ -1495,6 +1693,22 @@ displayed the table of contents following:
     \ifnum\tempcount<100
     \repeat
 \endgroup
+This is not an image inclusion, the TOC is produced from its original
+|tex| source inserted in this document after replacement of 
+|part|, |chapter| or |section| with |dummypart|, |dummychapter| and
+|dummysection| (and there is also a dummy page count).  We
+copied the line styles used in the original and
+displayed the table of contents following:
+\begin{verbatim}
+    \etocsetlevel{dummypart}  {-1} \etocsetlevel{part}   {2}
+    \etocsetlevel{dummychapter}{0} \etocsetlevel{chapter}{2}
+    \etocsetlevel{dummysection}{1} \etocsetlevel{section}{2}
+                    \setcounter{tocdepth}{1}
+\end{verbatim}
+Each chapter displays the numbers of only the first and the last sections it
+  contains. A technique for doing this is explained in the
+  \autoref{ssec:statistics}.  
+
 
 \subsection{Another compatibility mode}
 
@@ -1623,13 +1837,13 @@ Also, a fancier layout has been commented out.
 
 \subsection{The TOC as a tree}\label{tocastree}
 
-Using |tikz| and the package
-|tikz-qtree|\footnote{\url{http://ctan.org/pkg/pgf}, resp. \url{http://ctan.org/pkg/tikz-qtree}} we shall display the
+Using |tikz|\footnote{\url{http://ctan.org/pkg/pgf}} and the package
+|tikz-qtree|\footnote{\url{http://ctan.org/pkg/tikz-qtree}} we shall display the
 table of contents of this part as a tree. The technique (this whole subsection
 perhaps should have double dangerous-bend signs) is to use the \etoc modified
 command \csa{tableofcontents} not for typesetting, but to prepare a
 macro, or rather here a token list with name \csa{treetok}, with all the
-instructions to be executed lated. Putting \csa{etocnumber} or \csa{etocname}
+instructions to be executed later. Putting \csa{etocnumber} or \csa{etocname}
 commands in \csa{treetok} would be of no use: to which number or name would they
 refer to, in such a delayed execution? Rather the \emph{contents} of
 \csa{etocthenumber} or \csa{etocthename} are added with suitable decoration to
@@ -1637,37 +1851,12 @@ refer to, in such a delayed execution? Rather the \emph{contents} of
 \csa{etocthename} (for example) at the time of the execution and then add the
 outcome to \csa{treetok} for later execution in a |tikzpicture|.
 
-It is perfectly possible to do the same with the |hyperref| link: rather than
-trying to do things with \csa{etoclink} (which is a robust command, but one
-could access the contents of |\csname etoclink \endcsname|),\footnote{warning:
-it contains \csa{Hy@tocdestname} \emph{unexpanded}.} I mention
-to the advanced users that the simpler method is to store
-|\hyperlink{A}{B}| in \csa{treetok} where |A| stands for the \emph{expansion} of
-\cs{Hy@tocdestname}, 
-and |B| stands for the (one time) \emph{expansion} of \csa{etocthename}. 
-
-This being said, here in our use of |tikz-qtree| we have been confronted with
-the problem that the hyperlinks, even if correctly added to the \csa{treetok}
-token list, appeared in the final document in (most of the time) completely
-wrong locations.\footnote{|dvipdfmx| gives me errors:\quad
-|** WARNING ** Annotation out of page boundary.|\quad
-|Current page's MediaBox: [0 0 595.276 841.89]|\quad
-|Annotation: [94.3997 1200.33 146.512 1209.98]|\\
-Using |hopgf.sty [2012/12/16 v1.1]| of \textsc{Heiko Oberdiek} did not fix it.
- I read on the internet that there is some problem with |pgf|
-with regards to hyperlinks, but I don't know if this is the same issue here or
-something specific to the \cs{pgftree} TikZ command, or if the way
-I tried to put the links in the nodes was just completely wrong (as this is my
-first ever use of TikZ).}
-
-\makeatletter
-
 \newtoks\treetok
 \newtoks\tmptok
 
-\begingroup
+\newcommand*\qtreenode{}
 
-\def\appendtotok #1#2{% #1=token list, #2=macro, expands once #2
+\newcommand*\appendtotok[2]{% #1=token list, #2=macro, expands once #2
   #1\expandafter\expandafter\expandafter
     {\expandafter\the\expandafter #1#2}}
 
@@ -1693,42 +1882,53 @@ first ever use of TikZ).}
 % Et ceci en ayant utilisé \usepackage{hopgf}
 % [2012/12/16 v1.1 Some fixes for pgf (HO)]
 
-\def\PrepareSectionNode{%
+% UPDATE: mais ça marche avec des arbres dans la syntaxe de TikZ!
+
+\newcommand*\PrepareSectionNode{%
   \tmptok {\centering\bfseries}%
   \appendtotok\tmptok\etocthename
-  \edef\qtreenode {[.{\noexpand\parbox{2cm}{\the\tmptok}} }%
-  \show\qtreenode
+  \edef\qtreenode{ [.{\noexpand\parbox{2cm}{\the\tmptok}}}%
 }
-
-\def\PrepareSubsectionNode{%
-  \tmptok {\raggedright}%
+%%%%% ne marche pas, mais finalement le problème semble être avec
+%%%%% tikz-qtree, car l'analogue avec des arbres dans la syntaxe
+%%%%% de TikZ fonctionne!!! (3 mars)
+% \makeatletter
+% \newcommand*\PrepareSubsectionNode{%
+%   \tmptok\expandafter{\etocthename}%
+%   \edef\qtreenode{ [.{\noexpand\parbox{6cm}{\noexpand\raggedright
+%              \noexpand\hyperlink{\Hy@tocdestname}{\the\tmptok}}}}%
+% }
+% \makeatother
+\newcommand*{\PrepareSubsectionNode}{%
+  \tmptok {\raggedright}%  j'ai essayé aussi avec \sloppy
   \appendtotok\tmptok\etocthename
-  \edef\qtreenode{[.{\noexpand\parbox{4cm}{\the\tmptok}} }%
+  \edef\qtreenode{ [.{\noexpand\parbox{6cm}{\the\tmptok}}}%
 }
 
 \etocsetstyle{section}
-  {\treetok{\Tree [.Overview }\etocskipfirstprefix}
-  {\appendtotok\treetok{] }}  % ] not active!
+  {\etocskipfirstprefix}
+  {\appendtotok\treetok{ ]}}
   {\PrepareSectionNode \appendtotok\treetok\qtreenode}
-  {\appendtotok\treetok{] ]}\global\treetok\expandafter{\the\treetok}}
-
+  {\appendtotok\treetok{ ]}}
 
 \etocsetstyle{subsection}
   {\etocskipfirstprefix}
-  {\appendtotok\treetok{] }}
+  {\appendtotok\treetok{ ]}}
   {\PrepareSubsectionNode \appendtotok\treetok\qtreenode}
-  {\appendtotok\treetok{] }}
+  {\appendtotok\treetok{ ]}}
+
+\etocsettocstyle
+    {\treetok{\Tree [.{\hyperref[part:one]{Overview}}}}
+    {\global\appendtotok\treetok{ ]}}
 
 \setcounter{tocdepth}{2}
-\etocsettocstyle{}{}
+\smallskip
 \tableofcontents \ref{toc:partone}
 
-\endgroup
-
-\vfil
-\begin{tikzpicture}[grow'=right]
-\tikzset{sibling distance=1ex,
-         level 1/.style={level distance=4cm},
+{\centering
+  \begin{tikzpicture}[grow'=right]
+  \tikzset{sibling distance=1ex,
+         level 1/.style={level distance=3cm},
          level 2/.style={level distance=6cm},
          every level 0 node/.style={draw,fill=cyan!5,inner sep=6pt},
          every level 1 node/.style={draw,circle,thick,fill=blue!5},
@@ -1737,62 +1937,89 @@ first ever use of TikZ).}
              draw, thick, color=teal,
              edge from parent path=
                 {[dashed](\tikzparentnode.east) -- (\tikzchildnode.west)}}
-         }
-\the\treetok
-\end{tikzpicture}
-\vfil
+         } 
+  \the\treetok
+  \end{tikzpicture}
+\par
+}
+\smallskip
+
+It would be perfectly possible to tell \etoc to insert in the argument to the
+  \csa{Tree} command from package |tikz-qtree| the |hyperref| links. The
+  technique for doing that will be explained in the next section. But here in
+  our use of |tikz-qtree| we have been confronted with the problem that the
+  hyperlinks, even if correctly added to the \csa{treetok} token list, appeared
+  in the final document in completely wrong locations.
+\footnote{|dvipdfmx| gives me errors:\quad
+|** WARNING ** Annotation out of page boundary.|\quad
+|Current page's MediaBox: [0 0 595.276 841.89]|\quad
+|Annotation: [94.3997 1200.33 146.512 1209.98]|\\
+I read on the internet that there is some problem with |pgf| with regards to
+hyperlinks, but I don't know if this is the same issue (as this is my first
+ever use of TikZ). [2013/03/01]\\
+Update [2013/03/03]: it \emph{does} work when using the regular TikZ syntax
+for trees, so perhaps there is here some interaction with |tikz-qtree|. See next section.}
+
+% Using |hopgf.sty [2012/12/16 v1.1]| of \textsc{Heiko Oberdiek} did not fix it.
+% I read on the internet that there is some problem with |pgf|
+% with regards to hyperlinks, but I don't know if this is the same issue here or
+% something specific to the \cs{pgftree} TikZ command, or if the way
+% I tried to put the links in the nodes was just completely wrong (as this is my
+% first ever use of TikZ).\\
 
-As this whole thing is with double dangerous-bend signs, I shall now include the
-code used, with not much commenting:
+
+Here is the code used, the whole thing being with double dangerous-bend
+signs, I shall not comment much the actual \LaTeX{} programming used
+therein:
 
 \begingroup
 \def\MacroFont{\small\ttfamily\baselineskip10pt\relax}
 \begin{verbatim}
-\makeatletter
-\newtoks\treetok  \newtoks\tmptok
-
-\begingroup
-\def\appendtotok #1#2{% #1=token list, #2=macro, expands once #2
+\newtoks\treetok  \newtoks\tmptok  \newcommand*\qtreenode{}
+\newcommand*{\appendtotok}[2]{% #1=token list, #2=macro, expands once #2
   #1\expandafter\expandafter\expandafter
     {\expandafter\the\expandafter #1#2}}
 
-\def\PrepareSectionNode{%
+\newcommand*{\PrepareSectionNode}{%
   \tmptok {\centering\bfseries}%
   \appendtotok\tmptok\etocthename
-  \edef\qtreenode {[.{\noexpand\parbox{2cm}{\the\tmptok}} }%
+  \edef\qtreenode{ [.{\noexpand\parbox{2cm}{\the\tmptok}}}%
 }
-
-\def\PrepareSubsectionNode{%
+\newcommand*{\PrepareSubsectionNode}{%
   \tmptok {\raggedright}%
   \appendtotok\tmptok\etocthename
-  \edef\qtreenode{[.{\noexpand\parbox{4cm}{\the\tmptok}} }%
+  \edef\qtreenode{ [.{\noexpand\parbox{6cm}{\the\tmptok}}}% 
 }
-
-% See the tikz-qtree documentation for the syntax of trees.
-%    (the space at the end of \qtreenode is important)
-% The whole command is constructed inside the token list \treetok
-
+%%%% only sections and subsections:
 \etocsetstyle{section}
-  {\treetok{\Tree [.Overview }\etocskipfirstprefix}
-  {\appendtotok\treetok{] }}  % ] not active!
+  {\etocskipfirstprefix}
+  {\appendtotok\treetok{ ]}}
   {\PrepareSectionNode \appendtotok\treetok\qtreenode}
-  {\appendtotok\treetok{] ]}\global\treetok\expandafter{\the\treetok}}
-
+  {\appendtotok\treetok{ ]}}
 \etocsetstyle{subsection}
   {\etocskipfirstprefix}
-  {\appendtotok\treetok{] }}
+  {\appendtotok\treetok{ ]}}
   {\PrepareSubsectionNode \appendtotok\treetok\qtreenode}
-  {\appendtotok\treetok{] }}
-
-\setcounter{tocdepth}{2}
-\etocsettocstyle{}{}
-% the whole effect of \tableofcontents will be to fill \treetok
-% according to the syntax expected by tikz-qtree. 
-% This is always in a group, so we used \global in the section-finish code.
-% Also, there is a \par, but we are already in vertical mode.
-\tableofcontents \ref{toc:partone}
-\endgroup
+  {\appendtotok\treetok{ ]}}
 
+\etocsettocstyle
+    {\treetok{\Tree [.Overview}}
+    {\global\appendtotok\treetok{ ]}}
+% See the tikz-qtree (David Chiang) documentation for the Qtree syntax of
+% Alexis Dimitriadis (the spaces at various places before the square
+% brackets are important).
+
+% The whole effect of \tableofcontents will be to fill the token list
+% \treetok according to the syntax expected by tikz-qtree. The opening
+% portion of \etocsettocstyle initializes \treetok, and the closing portion
+% adds a final square bracket. A \global is needed as etoc always creates a
+% group when typesetting a TOC.
+
+% This QTree syntax has the advantage to use square brackets and not braces,
+% which eases things quite a bit in a TeX context. The next section explains
+% how to create a token list with the original TikZ syntax for trees.
+
+\tableofcontents \ref{toc:partone} 
 % Time now to display the tree (see tikz-qtree documentation)
 \begin{tikzpicture}[grow'=right]
 \tikzset{sibling distance=1ex,
@@ -1811,8 +2038,196 @@ code used, with not much commenting:
 \end{verbatim}
 \endgroup
 
+
+\subsection{The TOC as a molecule}\label{ssec:molecule}
+
+It is also possible to construct a TOC tree obeying the TikZ syntax for
+trees: this is a more complicated task for the \etoc line styles for reasons
+related to the importance of braces in \TeX{}, they need, when filling up the
+  token list (and if not using very tricky tricks) to be
+always balanced at each step.
+
+The simplest strategy is to allocate a token list (or use a macro) for each
+level used: we may need a \csa{parttok}, a \csa{chaptertok}, a
+\csa{sectiontok} and a \csa{subsectiontok}, to help in the task of filling
+up the total \csa{treetok}. As we are interested here in the table of
+contents of this (or another) document part, only a \csa{sectiontok} and a
+\csa{subsectiontok} will be needed.
+
+And the nice thing is that now, our hyperlinks do work. To tell \etoc to insert
+  the correct hyperlinks,  rather than
+trying to do things with \csa{etoclink} (which is a robust command\footnote{one
+could access the contents of \csa{csname etoclink }\csa{endcsname} but
+it contains \csa{Hy@tocdestname} \emph{unexpanded}, so it is easier to do as
+shown in the sequel.}) the
+simpler method\footnote{this paragraph and much of the details of the code
+snippets will be understood only by users knowledgeable in advanced \LaTeX{}
+programming.} is to store
+|\hyperlink{A}{B}| in \csa{treetok} where |A| stands for the \emph{expansion} of
+\cs{Hy@tocdestname}, 
+and |B| stands for the (one time) \emph{expansion} of \csa{etocthename}.
+ 
+\begingroup
+\def\MacroFont{\small\ttfamily\baselineskip10pt\relax}
+\begin{verbatim}
+\newtoks\sectiontok \newtoks\subsectiontok \newcommand*{\treenode}{}
+
+\newcommand*{\appendchildtree}[2]{% token list t1 becomes: t1 child {t2}
+   \edef\tmp{\the#1 child {\the#2}}%
+   #1\expandafter{\tmp}%
+}
+\makeatletter
+\newcommand*{\preparetreenode}{%
+  \tmptok\expandafter{\etocthenumber}%   takes less space than the name!
+  %% \edef\treenode{node {\the\tmptok}}% <-- for unlinked version
+  \edef\treenode{node {\noexpand\hyperlink{\Hy@tocdestname}{\the\tmptok}}}%
+}
+\makeatother
+\etocsetstyle{section}
+  {\etocskipfirstprefix}
+  {\appendchildtree\treetok\sectiontok}
+  {\preparetreenode \sectiontok\expandafter{\treenode}}
+  {\appendchildtree\treetok\sectiontok}
+
+\etocsetstyle{subsection}
+  {\etocskipfirstprefix}
+  {\appendchildtree\sectiontok\subsectiontok}
+  {\preparetreenode \subsectiontok\expandafter{\treenode}}
+  {\appendchildtree\sectiontok\subsectiontok}
+
+\setcounter{tocdepth}{2}
+
+\etocsettocstyle
+  {\treetok{\node {\hyperref[part:one]{Overview}}}}
+  {\global\appendtotok\treetok{ ;}}
+
+\tableofcontents \ref{toc:partone}
+\end{verbatim}
+
+
+At this stage, \cs{treetok} has been prepared, and a TikZ picture can be
+created (it uses the TikZ library |trees| for its ``cyclic'' grow method):
+\begin{verbatim}
+\begin{center}   
+   \begin{tikzpicture}
+              [grow cyclic,
+               level 1/.style={level distance=4cm,sibling angle=60},
+               level 2/.style={level distance=2cm,sibling angle=60},
+               every node/.style={ball color=red,circle,text=cyan},
+               edge from parent path={[dashed,very thick,color=cyan]
+                           (\tikzparentnode) --(\tikzchildnode)}] 
+     \the\treetok
+   \end{tikzpicture}%
+\end{center}
+\end{verbatim}
+\endgroup
+
+
+\newtoks\sectiontok
+\newtoks\subsectiontok
+\newcommand*\treenode {}
+
+\newcommand*{\appendchildtree}[2]{% token list t1 becomes: t1 child {t2}
+   \edef\tmp{\the#1 child {\the#2}}%
+   #1\expandafter{\tmp}%
+}
+
+\makeatletter
+\newcommand*{\preparetreenode}{%
+  \tmptok\expandafter{\etocthenumber}%
+  %% \edef\treenode{node {\the\tmptok}}% unlinked version
+  \edef\treenode{node {\noexpand\hyperlink{\Hy@tocdestname}{\the\tmptok}}}%
+}
+\makeatother
+
+\etocsetstyle{section}
+  {\etocskipfirstprefix}
+  {\appendchildtree\treetok\sectiontok}
+  {\preparetreenode
+   \sectiontok\expandafter{\treenode}}
+  {\appendchildtree\treetok\sectiontok}
+
+\etocsetstyle{subsection}
+  {\etocskipfirstprefix}
+  {\appendchildtree\sectiontok\subsectiontok}
+  {\preparetreenode
+   \subsectiontok\expandafter{\treenode}}
+  {\appendchildtree\sectiontok\subsectiontok}
+
+\setcounter{tocdepth}{2}
+
+\etocsettocstyle
+  {\treetok{\node {\hyperref[part:one]{Overview}}}}
+  {\global\appendtotok\treetok{ ;}}
+
+\tableofcontents \ref{toc:partone}
+
+\begin{center}  
+   \begin{tikzpicture}
+              [grow cyclic,
+               level 1/.style={level distance=4cm,sibling angle=60},
+               level 2/.style={level distance=2cm,sibling angle=60},
+               every node/.style={ball color=red,circle,text=cyan},
+               edge from parent path={[dashed,very thick,color=cyan]
+                           (\tikzparentnode) --(\tikzchildnode)}] 
+     \the\treetok
+   \end{tikzpicture}
+\end{center}
+
+This is nice, and especially so as this ``molecule TOC'' is fully hyperlinked!
+I don't know what went wrong for the trees
+constructed with the \cs{Tree} command of package |tikz-qtree|, rather than
+being coded as here with the original ``child'' TikZ syntax.
+
+\clearpage
+
+
+\etocsettocstyle
+  {\treetok{\node {\autoref{part:globalcmds}}}}
+  {\global\appendtotok\treetok{ ;}}
+
+\tableofcontents \ref{toc:globalcmds}
+
+\noindent  
+\parbox{4cm}{\begin{tikzpicture}
+              [grow cyclic,
+               level 1/.style={level distance=2.5cm,sibling angle=60},
+               level 2/.style={level distance=1cm,sibling angle=50},
+               every node/.style={ball color=red,circle,text=cyan},
+               edge from parent path={[very thick,color=cyan]
+                       (\tikzparentnode) --(\tikzchildnode)}] 
+     \the\treetok
+   \end{tikzpicture}}%
+\begin{minipage}{\dimexpr\linewidth-4cm\relax}
+  On the side, the (fully hyperlinked) table of contents of
+  \autoref{part:globalcmds}.
+  \def\MacroFont{\small\ttfamily\hyphenchar\font-1 \baselineskip10pt\relax}%
+\begin{verbatim}
+\etocsettocstyle
+  {\treetok{\node {\autoref{part:globalcmds}}}}
+  {\global\appendtotok\treetok{ ;}}
+\tableofcontents \ref{toc:globalcmds}
+\noindent  
+\parbox{4cm}{%
+   \begin{tikzpicture}
+      [grow cyclic,
+       level 1/.style={level distance=2.5cm,sibling angle=60},
+       level 2/.style={level distance=1cm,sibling angle=50},
+       every node/.style={ball color=red,circle,text=cyan},
+       edge from parent path={[very thick,color=cyan]
+               (\tikzparentnode) --(\tikzchildnode)}] 
+     \the\treetok
+   \end{tikzpicture}}%
+...
+\end{verbatim}
+\end{minipage}
+
+% \clearpage
+
 \part{Package commands for line styles}
 
+\thispartstats
+
 \setcounter{tocdepth}{3}
 
 \etocsetstyle{section}
@@ -2085,7 +2500,7 @@ are illustrated by the main table of contents of this
 document. 
 
 These level assignments can be modified at anytime: see the
-section\ref{sec:surprising} for various applications of this technique. As one
+section \ref{sec:surprising} for various applications of this technique. As one
 further example, let's mention here that the \hyperref[toc:main]{main table of
 contents} of this document was typeset following these instructions:
 \begin{verbatim}
@@ -2117,7 +2532,7 @@ sections and subsections.
 \section{Scope of commands added to 
          the \texorpdfstring{\texttt{.toc}}{.toc} file}
 
-\begingroup
+\begingroup % pour \small et \MacroFont en particulier.
 \small
 
 \subsection{Testing the scope}
@@ -2176,9 +2591,16 @@ multi-lingual document, as the |babel| package writes to the |.toc| file the
 language changes occurring in the document. 
 
 
+%\clearpage
+
+
 \part{Package commands for toc display styles}
 \label{part:globalcmds}
 
+
+\thispartstats
+
+
 \begin{verbatim}
 \setcounter{tocdepth}{-3}
 \localtableofcontents \label{toc:globalcmds}
@@ -2480,17 +2902,14 @@ We now opt for a ``framed'' style, using the package default
 line styles and some colors added. 
 
 % \clearpage
-\begingroup
-\def\MacroFont{\footnotesize\ttfamily}%
-\begin{verbatim}
+
 \etocdefaultlines
-\begingroup % we use a group to limit the scope of the next commands
+\begingroup 
 \renewcommand{\etoccolumnsep}{2em}
 \renewcommand{\etocinnerleftsep}{1.5em}
 \renewcommand{\etocinnerrightsep}{1.5em}
 % specify a background color for the toc contents
 \renewcommand{\etocbkgcolorcmd}{\color{yellow!10}}
-%\renewcommand{\etocbkgcolorcmd}{\relax}
 % set up the top and bottom rules 
 \renewcommand{\etoctoprule}{\hrule height 1pt}
 \renewcommand{\etoctoprulecolorcmd}{\color{red!25}}
@@ -2510,19 +2929,18 @@ line styles and some colors added.
       in a frame, it has to be small enough to fit on the 
       current page. It has the label |toc:b|.}}}
 % set up a label for future (or earlier...) reference
-\setcounter{tocdepth}{3}
 \tableofcontents \label{toc:b} \ref{toc:globalcmds}
 \endgroup
-\end{verbatim}
-\endgroup
 
+\begin{verbatim}
 \etocdefaultlines
-\begingroup 
+\begingroup % we use a group to limit the scope of the next commands
 \renewcommand{\etoccolumnsep}{2em}
 \renewcommand{\etocinnerleftsep}{1.5em}
 \renewcommand{\etocinnerrightsep}{1.5em}
 % specify a background color for the toc contents
 \renewcommand{\etocbkgcolorcmd}{\color{yellow!10}}
+%\renewcommand{\etocbkgcolorcmd}{\relax}
 % set up the top and bottom rules 
 \renewcommand{\etoctoprule}{\hrule height 1pt}
 \renewcommand{\etoctoprulecolorcmd}{\color{red!25}}
@@ -2542,9 +2960,10 @@ line styles and some colors added.
       in a frame, it has to be small enough to fit on the 
       current page. It has the label |toc:b|.}}}
 % set up a label for future (or earlier...) reference
+\setcounter{tocdepth}{3}
 \tableofcontents \label{toc:b} \ref{toc:globalcmds}
 \endgroup
-
+\end{verbatim}
 
 \subsection{A (crazy) inline display}
 
@@ -2553,8 +2972,9 @@ contents of this entire document. We will typeset the subsections as
 footnotes... This kind of style is suitable for a hyperlinked
 document, not for print! 
 
-Here is the code which will be used:
-\begin{verbatim}
+
+%\clearpage
+
 \begingroup
 \setcounter{tocdepth}{3}
 \newsavebox{\forsubsections}
@@ -2570,11 +2990,9 @@ Here is the code which will be used:
 \etocsettocstyle{Here is the inline table of contents. }{.\par}
 \tableofcontents
 \endgroup
-\end{verbatim}
-
-
-%\clearpage
 
+Here is the code which has been used:
+\begin{verbatim}
 \begingroup
 \setcounter{tocdepth}{3}
 \newsavebox{\forsubsections}
@@ -2590,14 +3008,14 @@ Here is the code which will be used:
 \etocsettocstyle{Here is the inline table of contents. }{.\par}
 \tableofcontents
 \endgroup
+\end{verbatim}
 
-
-
-\clearpage
+% \clearpage
 
 \part{Using and customizing \etoc}
 \label{part:custom}
 
+\thispartstats
 
 \etocdefaultlines
 \renewcommand{\etoctoprule}{\hrule height2pt depth0pt}
@@ -2873,6 +3291,7 @@ Regarding colors, generally speaking all color commands inside
 \etoc are initially defined to do nothing, and the choice to
 use or not colors is left to the user.
 
+% \clearpage
 \setcounter{tocdepth}{3}
 
 \begingroup
@@ -2968,7 +3387,7 @@ package. Customizing them goes through suitable
 \newcommand*\etocsepminusone{4ex plus .5ex minus .5ex}
 \newcommand*\etocsepzero{2.5ex plus .4ex minus .4ex}
 \newcommand*\etocsepone{1.5ex plus .3ex minus .3ex}
-%%\newcommand*\etocseptwo{1ex \@plus .15ex \@minus .15ex} % modified in 1.07e
+%%\newcommand*\etocseptwo{1ex plus .15ex minus .15ex} % modified in 1.07e
 \newcommand*\etocseptwo{.5ex plus .1ex minus .1ex}
 \newcommand*\etocsepthree{.25ex plus .05ex minus .05ex}
 
@@ -3086,9 +3505,11 @@ width. Note that \emph{only} the Plain \TeX{} syntax for rules is
 accepted here. 
 
 
-%\clearpage
+% \clearpage
 \part{Tips}
 
+\thispartstats
+
 \section{... and tricks}
 
 \subsection{Hacking  framed parboxes}
@@ -3162,6 +3583,116 @@ section \ref{sec:surprising} for other uses of this technique):
 
 \setcounter{tocdepth}{3}
 
+
+\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 the \autoref{ssec:molecule}. We
+did this for the first paragraph of the \autoref{sec:surprising}.
+
+But first, the coding of \csa{thispartstats}:\par
+\begingroup
+\def\MacroFont{\footnotesize\ttfamily\relax}
+\begin{verbatim}
+\newsavebox\firstnamei  \newsavebox\firstnumberi
+\newsavebox\lastnamei   \newsavebox\lastnumberi
+\newsavebox\firstnameii \newsavebox\firstnumberii
+\newsavebox\lastnameii  \newsavebox\lastnumberii
+\newcounter{mycounti}   \newcounter{mycountii}
+\newcommand*{\thispartstatsauxi}{} \newcommand*{\thispartstatsauxii}{}
+\newcommand*{\oldtocdepth}{}
+\newcommand*{\thispartstats}{%
+  \edef\oldtocdepth{\arabic{tocdepth}}%
+  \setcounter{tocdepth}{2}%
+  \setcounter{mycounti}{0}%
+  \setcounter{mycountii}{0}%
+  \def\thispartstatsauxi{%
+         \sbox{\firstnamei}{\color{cyan}\etocname}%
+         \sbox{\firstnumberi}{\color{cyan}\etocnumber}%
+         \def\thispartstatsauxi{}}%
+  \def\thispartstatsauxii{%
+         \sbox{\firstnameii}{\color{cyan}\etocname}%
+         \sbox{\firstnumberii}{\color{cyan}\etocnumber}%
+         \def\thispartstatsauxii{}}%
+  \begingroup
+  \etocsetstyle{subsection} {} {}
+    {\thispartstatsauxii
+     \stepcounter{mycountii}%
+     \sbox{\lastnameii}{\color{teal}\etocname}%
+     \sbox{\lastnumberii}{\color{teal}\etocnumber}} {}%
+  \etocsetstyle{section} {} {}
+    {\thispartstatsauxi
+     \stepcounter{mycounti}%
+     \sbox{\lastnamei}{\color{teal}\etocname}%
+     \sbox{\lastnumberi}{\color{teal}\etocnumber}}
+    {Here are some statistics for this part: it contains \arabic{mycounti}
+    section\ifnum\value{mycounti}>1 s\fi{} and \arabic{mycountii}
+    subsection\ifnum\value{mycountii}>1 s\fi. The name of the first section is
+    \unhbox\firstnamei{} and the corresponding number is \unhbox\firstnumberi. 
+    The name of the last section is \unhbox\lastnamei{} and its number is
+    \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.
+    Click on the names or numbers to get confirmation!}%
+  \etocinline % don't do a \par automatically (but this is not used, actually).
+  \etocsettocstyle {}{}
+  \localtableofcontents  % to be used at the top level of a Part.
+  \endgroup
+  \setcounter{tocdepth}{\oldtocdepth}%
+}
+\end{verbatim}
+%\endgroup
+
+And now, the variant  which was used for
+  \autoref{sec:surprising}, with macros rather than boxes: 
+\begin{verbatim}
+\makeatletter
+\newcommand*\firstsubname   {}  \newcommand*\lastsubname    {}
+\newcommand*\firstsubnumber {}  \newcommand*\lastsubnumber  {}
+\newcommand*\thissectionstatsaux{}
+
+\newcommand*{\thissectionstats}{%
+  \edef\oldtocdepth{\arabic{tocdepth}}%
+  \setcounter{tocdepth}{2}%
+  \setcounter{mycounti}{0}%
+  \def\thissectionstatsaux{% ou plus simple si on ne veut pas le lien.
+         \toks@\expandafter{\etocthename}%
+         \edef\firstsubname{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+         \toks@\expandafter{\etocthenumber}%
+         \edef\firstsubnumber{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+         \def\thissectionstatsaux{}}
+  \begingroup
+  \etocsetstyle{subsection} {} {}
+    {\thissectionstatsaux
+     \stepcounter{mycounti}%
+     \toks@\expandafter{\etocthename}%
+     \edef\lastsubname{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+     \toks@\expandafter{\etocthenumber}%
+     \edef\lastsubnumber{\noexpand\hyperlink{\Hy@tocdestname}{\the\toks@}}%
+    }
+    {Here are some statistics for this section. It contains \arabic{mycounti}
+     subsections. The name of its first is \emph{\color{cyan}\firstsubname{}}
+     and the corresponding number is {\color{cyan}\firstsubnumber}. The name of
+     the last subsection is \emph{\color{teal}\lastsubname{}} and its number is 
+     {\color{teal}\lastsubnumber}.}% (with boxes, \emph would have done nothing) 
+   \etocsettocstyle {}{}
+   \etocinline
+   \localtableofcontents
+  \endgroup
+  \setcounter{tocdepth}{\oldtocdepth}%
+}
+\makeatother
+\end{verbatim}
+\endgroup
+
 \subsection{Compatibility with other packages}
 
 \etoc loads the package |multicol|.\footnote{\protect\fbox{up to version
@@ -3170,14 +3701,15 @@ has been removed.}} It is
 |hyperref| aware and hopefully |hyperref| compatible! It
 doesn't matter whether \etoc or |hyperref| is loaded first.
 
-
-
-
 The contents of the |.toc| file (if it exists) are read into
 memory by \etoc once, at the time of \csa{usepackage\{etoc\}}.
 The |.toc| file will be opened for write operations only at
 the time of the first TOC displaying command. 
 
+\etoc can not really cohabit with packages modifying the \csa{tableofcontents}
+  command: some sort of truce can be achieved if \etoc is loaded last, hence is
+  the winner. 
+
 When a \localtoc is inserted by the user in the document, a
 line containing an \etoc inner command and an identification
 number is added to the |.toc| file. The correct local table of
@@ -3199,13 +3731,37 @@ arguments. The macros \csa{etocname}, \csa{etocnumber}, and
 that the \emph{linktoc=all} option of |hyperref| tells it to
 put a link also in the page number corresponding to a given
 toc entry). For example, the tables of contents of the present document are
-fully linked.\footnote{except the \hyperref[tocastree]{tree TOC} ...}
+all fully linked.\footnote{except the \hyperref[tocastree]{Qtree TOC} ...}
 
 It is possible to customize (using package |tocloft| for
 example) throughout the document the macros \csa{l@section},
 \csa{l@subsection} ... and the effect will be seen in the next
 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
+advanced uses such as what is done in the \autoref{ssec:molecule} it is
+  important 
+to know that |tableof| adds one level of grouping inside the |.toc| file itself.
+So when one needs to make some information \csa{global}, one can not wait to be
+at the level of the second argument of \csa{etocsettocstyle}, as
+|tableof| will already have closed the group then. The \csa{global} things must
+be done at the latest in the \meta{finish} part of the top (or last) sectioning
+  level used. 
+This only applies of course to \csa{tableofcontents} or
+  \csa{localtableofcontents} following the 
+  \csa{nexttocwithtags}|{required}||{forbidden}| command from |tableof|.
+
+And when the commands
+  \csa{tableof} or \csa{tablenotof} of package 
+  |tableof| are used,
+  they typeset the table of contents according to the document class defaults:
+  to benefit from the \etoc styles, it is mandatory to use either
+  \csa{tableofcontents}, or \csa{localtableofcontents} or one of the other \etoc
+  commands, and |tableof (v1.1)| will influence the outcome only if 
+  \csa{nexttocwithtags}|{required}||{forbidden}| was added before the table of
+  contents typesetting command.
+
 \subsection{\TeX nical matters}
 
 The \csa{etocname}, \csa{etocnumber}, \csa{etocpage} commands are protected against
@@ -3232,15 +3788,13 @@ groups. All TOCs are typeset inside groups.
   contents are mutually compatible: in particular the \etoc
   default styles expect to start in ``vertical mode''.
 
-  When using multiple \toc commands in a document, one should
-  beware from adding typesetting instructions directly in the
-  |.toc| file, as they will be executed by \etoc for all TOCs:
-  even for a \localtoc it doesn't matter if that instruction
-  seems to concern material outside of its scope, it will get
-  executed nevertheless. If absolutely necessary these
-  instructions should be done in such a way that they can be
-  activated or deactivated easily from the document source, as
-  need be.
+  When using multiple \toc commands in a document, one should beware from adding
+  typesetting instructions directly in the |.toc| file, as they will be executed
+  by \etoc for all TOCs: even for a \localtoc it doesn't matter if that
+  instruction seems to concern material outside of its scope, it will get
+  executed nevertheless. If absolutely necessary (but this should never be)
+  these instructions should be done in such a way that they can be activated or
+  deactivated easily from the document source, as need be.
 
   % Do not clone a clone but produce rather twins by cloning the
   % same original local table of contents.
@@ -3248,6 +3802,14 @@ groups. All TOCs are typeset inside groups.
   As is usual with toc and labels, after each change, one has
   to run latex a certain number of times to let the produced
   document get its final appearance (at least twice).\par
+
+\bigskip
+
+This is the documentation as of \docdate, printed from the source file with the
+time stamp ``\dtxtimestamp''. The package version is \pkgversion, of
+  \pkgdate. See the source for copyright and license information.\par 
+
+
 \end{small}