tableof (5mar13)

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

1 files changed, 299 insertions, 175 deletions

diff --git a/Master/texmf-dist/source/latex/tableof/tableof.dtx b/Master/texmf-dist/source/latex/tableof/tableof.dtx
index 82652c28446..a875d4f33f7 100644
--- a/Master/texmf-dist/source/latex/tableof/tableof.dtx
+++ b/Master/texmf-dist/source/latex/tableof/tableof.dtx
@@ -1,24 +1,23 @@
 % -*- coding: iso-latin-1; -*-
 %<*ins>
 \def\pkgname{tableof}
-\def\pkgdate{2012/12/13}
-\def\pkgversion{v1.1}
+\def\pkgdate{2013/03/04}
+\def\pkgversion{v1.2}
 \def\pkgdescription{tables of tagged contents (jfB)}
 %</ins>
 %%
 %% Package `tableof' by Jean-Francois Burnol
-%% Copyright (C) 2012 by Jean-Francois Burnol
+%% Copyright (C) 2012,2013 by Jean-Francois Burnol
 %%
 %<*none>
-\def\lasttimestamp{Time-stamp: <13-12-2012 23:59:02 CET jfb>}
-\def\docdate{2012/12/13}
+\def\lasttimestamp{Time-stamp: <04-03-2013 21:29:27 CET jfb>}
+\def\docdate{2013/03/04}
 \def\striptimestamp#1 <#2 #3 #4 #5>{#2 at #3 #4}
 \edef\dtxtimestamp{\expandafter\striptimestamp\lasttimestamp}
 \ProvidesFile{\pkgname.dtx}
   [`\pkgname' source and documentation (\dtxtimestamp)]
 %
-% The copyright at the top of this file applies to `tableof.dtx'
-% and to its derived files.
+% The copyright notice applies to `tableof.dtx' and to its derived files.
 % 
 %    They may be distributed and/or modified under the
 %    conditions of the LaTeX Project Public License,
@@ -40,13 +39,13 @@
 %  `tableof.sty', `tableof.ins' and `tableoftest.tex' are generated on
 %  the first latex run.
 %
-%  Put `tableof.sty' at a suitable location within the TeX installation:
+%  Move `tableof.sty' to a suitable location within the TeX installation:
 %          tableof.sty -> ..path..to../tex/latex/tableof/
 %
 %  `tableof.ins' is for TeX distributions expecting it.
 %
 %  `tableoftest.tex' is an example of use of the package commands. Run
-%  latex twice on it to get the tagged tables of contents.
+%  latex twice on it to get examples of tagged tables of contents.
 %
 \begingroup
 \input docstrip.tex
@@ -74,13 +73,13 @@
 %% (an already existing `tableof.sty' in the same repertory will be
 %% overwritten)
 %% 
-%% Put `tableof.sty' in a suitable location within the TeX installation:
+%% Move `tableof.sty' to a suitable location within the TeX installation:
 %% tableof.sty -> ................/tex/latex/tableof/
 %%
 %% The generated auxiliary files may be discarded. 
 %%
 %% See `tableof.dtx' for the statements of copyright and conditions of
-%% distribution or modification.
+%% distribution and/or modification.
 %%
 \input docstrip.tex
 \askforoverwritefalse
@@ -95,49 +94,58 @@
 %<*test>
 %-------------------------------------------------------------------------------
 %% This file `tableoftest.tex' serves to demontrate the use of the
-%% commands from package `tableof'.
+%% commands from the package `tableof'.
 %%
 %% (run on it `latex' or `pdflatex' twice.)
 %%
 \documentclass{article}
+\usepackage[T1]{fontenc}
 \usepackage[colorlinks,linkcolor=blue]{hyperref}
 \usepackage{tableof}
-%%\usepackage{etoc}
+%%\usepackage{etoc} % for testing
+\DeclareRobustCommand\lowast{\raisebox{-.25\height}{*}}
 \begin{document}
-%% \etoctoclines % (from package etoc)
+%% \etoctoclines % (if using package etoc)
 %%
 %% we don't need here \tofOpenTocFileForWrite
 %% as the document has \tableofcontents a few lines down.
-\section*{with (and)}
+%%
+\section*{\string\tableof\{\}}
 \tableof{}
-\section*{with (A or B or C or D or E or F)}
+\section*{\string\tableof\lowast\{A,B,C,D,E,F\}}
 \tableof*{A,B,C,D,E,F}
-\section*{with A (and)}
+\section*{\string\tableof\{A\}}
 \tableof{A}
-\section*{with A (or)}
+\section*{\string\tableof\lowast\{A\}}
 \tableof*{A}
-\section*{with A and with C}
+\section*{\string\tableof\{A,C\}}
 \tableof{A,C}
-\renewcommand\contentsname{with (A or D) and (without B or without F)}
-\nexttocwithtags*{A,D}*{B,F}\tableofcontents
+\section*{\string\tableof\lowast\{A,C\}}
+\tableof*{A,C}
+\section*{\string\tableoftaggedcontents\lowast\{A,D\}\{B,F\}}
+\tableoftaggedcontents*{A,D}{B,F}
+\renewcommand\contentsname{\string\nexttocwithtags\lowast\{A,D\}\lowast\{B,F\}\string\tableofcontents}
+\nexttocwithtags*{A,D}*{B,F}
+\tableofcontents
 %% requires package etoc 
-%% (or at least a class or package allowing multiple \tableofcontents): 
 %% \etoctocstyle{1}{with A and D and without B and without F}
 %% \nexttocwithtags{A,D}{B,F}\tableofcontents
 %% \etoctocstyle{1}{with (A or D) and without B and without F}
 %% \nexttocwithtags*{A,D}{B,F}\tableofcontents
 %% \etoctocstyle{1}{with A and D and (without B or without F)}
 %% \nexttocwithtags{A,D}*{B,F}\tableofcontents
-\section*{with B or with C}
+\section*{with B or with C (using \string\tableoftaggecontents)}
+\tableoftaggedcontents*{B,C}{}
+\section*{with B or with C (using \string\tableof\lowast)}
 \tableof*{B,C}
 \section*{with A and with B and with C}
 \tableof{A,B,C}
 \section*{with A or with B or with C}
 \tableof*{A,B,C}
-\section*{without B (and)}
-\tablenotof{B}
-\section*{without A and without B}
-\tablenotof{A,B}
+\section*{without B (and) (using \string\tableoftaggedcontents)}
+\tableoftaggedcontents{}{B}
+\section*{without A and without B (using \string\tableoftaggedcontents)}
+\tableoftaggedcontents{}{A,B}
 \section*{without A or without C}
 \tablenotof*{A,C}
 \section*{without A and without B and without C}
@@ -150,12 +158,12 @@
 \tableof{E}
 \section*{without D}
 \tablenotof{D}
-\section*{Ecology}
-\tableof{ecology}
-\section*{Rabbits}
-\tableof{rabbits}
-\section*{Kitchenware}
-\tableof{kitchenware}
+\section*{ecology and rabbits}
+\tableof{ecology,rabbits}
+\section*{rabbits and not ecology}
+\tableoftaggedcontents{rabbits}{ecology}
+\section*{kitchenware and not rabbits}
+\tableoftaggedcontents{kitchenware}{rabbits}
 \clearpage
 \section{no tag}
 nothing
@@ -252,15 +260,64 @@ A,B,C
 \pagestyle{headings}
 \usepackage[latin1]{inputenc}
 \usepackage[T1]{fontenc}
-\usepackage{geometry}
-\usepackage{verbatim}
+\usepackage[hscale=0.66,vscale=0.75]{geometry}
+
 \usepackage{txfonts}
+\DeclareFontFamily{T1}{txtt}{}
+\DeclareFontShape{T1}{txtt}{m}{n}{	%medium
+     <->s*[.96] t1xtt%
+}{}
+\DeclareFontShape{T1}{txtt}{m}{sc}{	%cap & small cap
+     <->s*[.96] t1xttsc%
+}{}
+\DeclareFontShape{T1}{txtt}{m}{sl}{	%slanted
+     <->s*[.96] t1xttsl%
+}{}
+\DeclareFontShape{T1}{txtt}{m}{it}{	%italic
+     <->ssub * txtt/m/sl%
+}{}
+\DeclareFontShape{T1}{txtt}{m}{ui}{   	%unslanted italic
+     <->ssub * txtt/m/sl%
+}{}
+\DeclareFontShape{T1}{txtt}{bx}{n}{	%bold extended
+     <->t1xbtt%
+}{}
+\DeclareFontShape{T1}{txtt}{bx}{sc}{	%bold extended cap & small cap
+     <->t1xbttsc%
+}{}
+\DeclareFontShape{T1}{txtt}{bx}{sl}{	%bold extended slanted
+     <->t1xbttsl%
+}{}
+\DeclareFontShape{T1}{txtt}{bx}{it}{	%bold extended italic
+     <->ssub * txtt/bx/sl%
+}{}
+\DeclareFontShape{T1}{txtt}{bx}{ui}{  	%bold extended unslanted italic
+     <->ssub * txtt/bx/sl%
+}{}
+\DeclareFontShape{T1}{txtt}{b}{n}{	%bold
+     <->ssub * txtt/bx/n%
+}{}
+\DeclareFontShape{T1}{txtt}{b}{sc}{	%bold cap & small cap
+     <->ssub * txtt/bx/sc%
+}{}
+\DeclareFontShape{T1}{txtt}{b}{sl}{	%bold slanted
+     <->ssub * txtt/bx/sl%
+}{}
+\DeclareFontShape{T1}{txtt}{b}{it}{   	%bold italic
+     <->ssub * txtt/bx/it%
+}{}
+\DeclareFontShape{T1}{txtt}{b}{ui}{   	%bold unslanted italic
+     <->ssub * txtt/bx/ui%
+}{}
+
 \usepackage{xspace}
 \usepackage{color}
 
 \definecolor{joli}{RGB}{225,95,0}
 \definecolor{JOLI}{RGB}{225,95,0}
 \definecolor{BLUE}{RGB}{0,0,255}
+\definecolor{niceone}{RGB}{38,128,192}
+
 \usepackage[english]{babel}
 
 \usepackage[%dvipdfmx,%
@@ -277,27 +334,30 @@ pdfkeywords={LaTeX, table of contents},%
 pdfstartview=FitH,%
 pdfpagemode=UseOutlines}
 
-\MakeShortVerb{\|}
 
-\DeclareRobustCommand\cs[1]{{\ttfamily\hyphenchar\font45\char`\\#1}}
-\DeclareRobustCommand\csb[1]{{%
-\color{blue}\ttfamily\hyphenchar\font45\char`\\#1}}
+\DeclareRobustCommand\csa[1]{{\ttfamily\char`\\#1}}
+\DeclareRobustCommand\csb[1]{{\color{blue}\ttfamily\char`\\#1}}
 
-\newcommand\cshyp[1]{\texorpdfstring{\cs{#1}}{\textbackslash #1}}
+\newcommand\csahyp[1]{\texorpdfstring{\csa{#1}}{\textbackslash #1}}
 \newcommand\csbhyp[1]{\texorpdfstring{\csb{#1}}{\textbackslash #1}}
 \newcommand\lowast{\raisebox{-.25\height}{*}}
-\newcommand\starit[1]{\cs{#1\lowast}}
+\newcommand\starit[1]{\csa{#1\lowast}}
 \newcommand\staritb[1]{\csb{#1\lowast}}
 
-\newcommand\tof{\cs{tableof}\xspace}
-\newcommand\tnotof{\cs{tablenotof}\xspace}
-\newcommand\tofb{\csb{tableof}\xspace}
-\newcommand\tnotofb{\csb{tablenotof}\xspace}
+\makeatletter\let\check@percent\relax\makeatother
 
-\newcommand\tableof{%
-\texorpdfstring{{\color{joli}\ttfamily\bfseries tableof}}
-{tableof}\xspace}
+\def\MacroFont{\ttfamily\small\baselineskip12pt\relax\catcode`*\active}
 
+\begingroup
+\catcode`*\active
+\def\x{\endgroup\let*\lowast}\x
+
+\newcommand\tableof{%
+    \texorpdfstring{{\color{joli}\ttfamily\bfseries tableof}}
+                   {tableof}\xspace}
+\newcommand\etoc{%
+    \texorpdfstring{{\color{niceone}\ttfamily\bfseries etoc}}
+                   {etoc}\xspace}
 
 \frenchspacing
 
@@ -309,7 +369,7 @@ pdfpagemode=UseOutlines}
 
 \begin{center}
   {\normalfont\Large The \tableof  package}\\
-\textsc{Jean-François Burnol}\par
+  \textsc{Jean-François Burnol}\par
   \footnotesize \ttfamily 
   jfbu (at) free (dot) fr\\
   Package version: \pkgversion\ (\pkgdate)\\
@@ -318,162 +378,223 @@ pdfpagemode=UseOutlines}
 \end{center}
 
 \begin{abstract}
-  The \tableof package allows to tag table of contents entries.
-
-  The command \csb{tableof}\{{\color{blue}\emph{comma,separated,list,of,tags}}\}
-  displays a table of contents containing only the entries having all the listed
-  tags. There is a complementary command \csb{tablenotof}. They may be used
-  multiple times.
- 
-  The command
-  \csb{nexttocwithtags}\{{\color{blue}\emph{required\_tags}}\}\{{\color{blue}\emph{excluded\_tags}}\}
-  specifies which tags are to be obeyed by the next standard
-  \cs{tableofcontents} or equivalent command.
+  The package commands \csa{toftagstart}, \csa{toftagstop}, \csa{toftagthis},
+  \csa{tofuntagthis} are used to flag chapters or sections or anything ending up
+  in the |.toc| file following an (implicit or explicit)
+  \csa{addcontentsline}. Then\\
+  \hbox to
+  \linewidth{\hss\csa{nexttocwithtags}\marg{required1,required2,...}\marg{excluded1,excluded2,...}\hss}
+  specifies which tags are to be required and which ones are to be excluded by
+  the next \csa{tableofcontents} (or equivalent) document command. For document
+  with classes where \csa{tableofcontents} is only single-use, the package
+  provides:\\
+  \hbox to
+  \linewidth{\hss\csa{tableoftaggedcontents}\marg{required1,required2,...}\marg{excluded1,excluded2,...}\hss}
+  which removes this restriction.
 \end{abstract}
 
+\tableofcontents
 
-\section{Commands}
 
-\subsection{\csbhyp{toftagstart} and \csbhyp{toftagstop}}
+\section{Tagging commands}
+
+\subsection{\csbhyp{toftagstart\{csv,list\}} and \csbhyp{toftagstop\{csv,list\}}}
 
 These commands have a mandatory argument which is a comma separated list of
 tags. The tags need not have been predeclared.
 \begin{verbatim}
-\toftagstart{kitchenware,weaponry,gastronomy}
-\section{Dealing with knives}
-\subsection{This is tagged, too}
-\section{Hunting rabbits}
+\toftagstart{kitchenware,weaponry,gastronomy} 
+\section{Dealing with knives}    % tagged with kitchenware+weaponry+gastronomy
+
+\toftagstop{kitchenware}
+\section{Hunting rabbits}        % tagged with weaponry+gastronomy
+
+\toftagstart{tag1}
+\subsection{This is tagged, too} % tagged with weaponry+gastronomy+tag1
+
 \toftagstop{weaponry}
-\section{Eating rabbits}
+\section{Eating rabbits}         % tagged with gastronomy+tag1
 \end{verbatim}
 
-\subsection{\csbhyp{toftagthis} and \csbhyp{tofuntagthis}}
+\subsection{\csbhyp{toftagthis\{csv,list\}}  and \csbhyp{tofuntagthis\{csv,list\}}}
 
-The \cs{toftagthis} command tags with the values from its argument (a comma
-separated list) only the next object found in the |.toc| file. The command
-should be located \emph{before} and not \emph{after} the
-to-be-tagged TOC entry. The \cs{tofuntagthis}
-command untags the next entry.
+The \csa{toftagthis} command flags with the comma separated values from its list
+argument only the \emph{next} sectioning command. The \csa{tofuntagthis} command
+similarly untags only the \emph{next} entry.
 \begin{verbatim}
 \toftagstart{kitchenware,rabbits}
-\section{Knives and rabbits}
-    \tofuntagthis{kitchenware}
-\subsection{Hunting rabbits}
-\subsection{Best knives for cooking}
-\subsection{Eating rabbits}
+\section{Knives and rabbits}     % tagged with kitchenware and rabbits
+
+\tofuntagthis{kitchenware}
+\subsection{Hunting rabbits}     % tagged only with rabbits
+
+\subsection{Best knives for cooking} % tagged with kitchenware and rabbits
+
 \toftagstart{ecology}
-    \toftagthis{climate}
-\section{Knives and global climate}
+\toftagthis{climate}
+\section{Knives and global climate} % tagged with kitchenware+rabbits+ecology+climate
+
 \toftagstop{kitchenware}
-\section{The rabbit in the wild}
-    \toftagthis{climate}
-\subsection{Impact of the rabbit on global climate}
+\section{The rabbit in the wild}    % tagged with rabbits+ecology
 \end{verbatim}
 
-\subsection{\csbhyp{nexttocwithtags}}
-
-This command is new with version |1.1|. It has two \emph{mandatory} arguments
-(possibly empty): the first one is a comma separated list of required tags, the
-second one is a comma separated list of excluded tags. The command has no
-immediate effect but influences the next \cs{tableofcontents} (or equivalent
-command) in the document:\footnote{in documents with a class or package allowing
-  multiple uses of the command \cs{tableofcontents}, the command
-  \cs{nexttocwithtags} influences only the next use of \cs{tableofcontents}.}
-the TOC will contain only the entries having been tagged with all the required
-tags and none of the excluded tags. For example:
+\subsection{Spaces}
+
+Spaces in tags are significant (as usual with \TeX{} multiple spaces count for
+one). Do not use spaces after the opening brace or before the closing brace, do
+not use spaces before or after a comma: |\toftagthis{one tag with spaces}| is
+ok, |\toftagthis{tag1 }| or |\toftagthis{tag1, tag2}| are not.
+
+
+
+\section{Table of contents commands}
+
+\subsection{\csbhyp{tableoftaggedcontents\{required,csv,list\}\{excluded,csv,list\}}}
+
+This command is provided in case the document class allows only a single use of
+\csa{tableofcontents}: it can be used arbitrarily many times. However it does not
+typeset a heading. Example:
 \begin{verbatim}
-\nexttocwithtags{A,B}{C,D,E}
-\tableofcontents
+\section*{A table of tagged contents}  % <- needs to be explicitely added
+\tableoftaggedcontents{weaponry,hunting}{ecology,climate}
 \end{verbatim}
-will print only the division units having both tags |A| and |B| and none of |C|,
-|D|, or |E|. 
+This will limit the printed TOC entries to the ones which have been tagged with
+|weaponry| and also with |hunting|, but not with |ecology| and neither with
+|climate|.
+
+\subsubsection{starred variants}
 
 There are starred variants:
 \begin{verbatim}
-\nexttocwithtags{A,B}{C,D,E}   % A and B and neither C nor D nor E
-\nexttocwithtags*{A,B}{C,D,E}  % (A or B) and neither C nor D nor E
-\nexttocwithtags{A,B}*{C,D,E}  % A and B and (not C or not D or not E)
-\nexttocwithtags*{A,B}*{C,D,E} % (A or B) and (not C or not D or not E)
+\tableoftaggedcontents{A,B}{C,D,E}   % A and B and neither C nor D nor E
+\tableoftaggedcontents*{A,B}{C,D,E}  % (A or B) and neither C nor D nor E
+\tableoftaggedcontents{A,B}*{C,D,E}  % A and B and (not C or not D or not E)
+\tableoftaggedcontents*{A,B}*{C,D,E} % (A or B) and (not C or not D or not E)
 \end{verbatim}
 
+\subsection{\csbhyp{tableof\{required,csv,list\}}}
 
-\subsection{\csbhyp{tableof}}
-
-\tableof also provides commands to typeset on its own the tagged entries of
-the |.toc| file: \cs{tableof} has a mandatory argument which is a comma
-separated list of tags. It displays, exactly as would appear in the actual table
-of contents, the corresponding tagged entries from the |.toc| file. Its title
-needs to be explicitely set up by additional code.
+This is equivalent to |\tableoftaggedcontents{required,csv,list}{}|.
 \begin{verbatim}
-\section*{Table of entries tagged with weaponry AND with hunting}
-\tableof{weaponry,hunting}
+\tableof{weaponry,hunting}  % will print the entries tagged with weaponry 
+                                                             AND hunting
 \end{verbatim}
 There is a starred variant:
 \begin{verbatim}
-\section*{Table of entries tagged with weaponry OR with hunting}
-\tableof*{weaponry,hunting}
+\tableof*{weaponry,hunting} % will print the entries tagged with weaponry 
+                                                              OR hunting
 \end{verbatim}
 
-\subsection{\csbhyp{tablenotof}}
+\subsection{\csbhyp{tablenotof\{excluded,csv,list\}}}
 
-It has a mandatory argument which is a comma separated list of tags. It
-displays, exactly as would appear in the table of contents, the
-entries from the |.toc| file which are \emph{not} tagged:
+This is equivalent to |\tableoftaggedcontents{}{excluded,csv,list}|.
 \begin{verbatim}
-\section*{Table of entries NOT tagged with weaponry NEITHER with hunting}
-\tablenotof{weaponry,hunting}
+\tablenotof{weaponry,hunting}  % will print the entries NOT tagged with weaponry
+                                                        NEITHER with hunting
 \end{verbatim}
 There is a starred variant:
 \begin{verbatim}
-\section*{Table of entries NOT tagged with weaponry OR NOT tagged with hunting}
-\tablenotof*{weaponry,hunting}
+\tablenotof*{weaponry,hunting} % will print the entries NOT tagged with weaponry
+                                                     OR NOT tagged with hunting
+\end{verbatim}
+
+
+\subsection{\csbhyp{nexttocwithtags\{required,csv,list\}\{excluded,csv,list\}}}
+
+This command influences the next \csa{tableofcontents} (or equivalent) command:
+\begin{verbatim}
+\nexttocwithtags{A,B}{C,D,E}
+\tableofcontents
+\end{verbatim}
+will let \csa{tableofcontents} print only the sectioning units having been
+flagged with both |A| and |B| and none of |C|, |D|, or |E|.
+
+Do not forget the second pair of braces if you only want to require some tags:
+\csa{nexttocwithtags}|{tag1,tag2}{}|. 
+
+\subsubsection{starred variants}
+
+There are starred variants:
+\begin{verbatim}
+\nexttocwithtags{A,B}{C,D,E}   % A and B and neither C nor D nor E
+\nexttocwithtags*{A,B}{C,D,E}  % (A or B) and neither C nor D nor E
+\nexttocwithtags{A,B}*{C,D,E}  % A and B and (not C or not D or not E)
+\nexttocwithtags*{A,B}*{C,D,E} % (A or B) and (not C or not D or not E)
 \end{verbatim}
-Both \cs{tableof} and \cs{tablenotof} may be used arbitrarily many times
-(whether or not the document has somewhere a \cs{tableofcontents}).
 
 
 \subsection{\csbhyp{tofOpenTocFileForWrite}}
 
-The |.toc| file is read (if it exists) into memory by \tableof at the
-\cs{usepackage}, for use by \cs{tableof} and \cs{tablenotof}. But the creation
+The |.toc| file is read (if it exists) into memory by \tableof at the time
+of \csa{usepackage\{tableof\}}, for use by \csa{tableoftaggedcontents},
+\csa{tableof} and \csa{tablenotof}.
+
+But the creation
 of the |.toc| file is not dealt with by \tableof itself: either this will be
-done by a standard \cs{tableofcontents} command somewhere in the document, or,
-one may use the package provided command \cs{tofOpenTocFileForWrite} which does
+done by a standard \csa{tableofcontents} command somewhere in the document, or,
+one may use the package provided command \csa{tofOpenTocFileForWrite} which does
 not display anything and just does what its name indicates. This command can be
-used also in the preamble.\footnote{Note to people or packages wanting also to
-  access the |.toc| file: as happens with the standard \cs{tableofcontents}, the
-  |.toc| file becomes temporarily empty immediately after
-  \cs{tofOpenTocFileForWrite}.}
-
-Again: this command should \emph{not} be used when the document has its own
-\cs{tableofcontents} or equivalent.
+used also in the preamble.
 
+% \footnote{Note to people or packages wanting also to
+%   access the |.toc| file: as happens with the standard \csa{tableofcontents}, the
+%   |.toc| file becomes temporarily empty immediately after
+%   \csa{tofOpenTocFileForWrite}.}
 
+Again: this command should \emph{not} be used when the document makes use of its
+own \csa{tableofcontents} or equivalent. It is provided only for the case where
+the document uses exclusively \csa{tableoftaggedcontents}, \csa{tableof} and
+\csa{tablenotof}.
 
 \subsection{Compatibility with other packages}
 
 \tableof checks if |hyperref| is loaded as |hyperref| modifies the format of the
-|.toc| file. This check is done at the \cs{begin}|{document}| so the order
-of loading is not important.
+lines in the |.toc| file (and this must be taken into account). This check is
+done at the \csa{begin}|{document}| so the order of loading is not important.
+
+\tableof adds the tag data to the |.toc| file, but this data self-defines
+itself to do nothing when not activated by \tableof's own commands.
 
-\tableof adds the tag data to the |.toc| file, but this data is defined (within
-the |.toc| file) to do
-nothing. Hence the generated |.toc| file may be imported for use
-by other \TeX{} documents.\footnote{this import must do \cs{makeatletter} and
-  also the new document must use |hyperref| if the original did so.}
+% Hence the generated |.toc| file may be imported for use
+% by other \TeX{} documents.\footnote{this import must do \csa{makeatletter} and
+%   also the new document must use |hyperref| if the original did so.}
+
+No testing has actually been done of compatibility with packages manipulating
+tables of contents, apart from
+\etoc.\footnote{\url{http://www.ctan.org/pkg/etoc}} It went fine. 
 
 \subsection{TODO}
 
 Create a parser for arbitrary iterated boolean combinations of tags . . . but
 this kind of thing must have been done a zillion times already, as it belongs to
-the basics in computer science! . . . and it surely is no easy task in \TeX{}!
-so I cautiously retreated from such an endeavor.
+the basics in computer science! ... and it surely is no easy task in \TeX{}!
+so I cautiously retreated from re-doing something difficult which has already
+been done somewhere by someone ...
 
 \subsection{version history}
 
-|2012/12/13 v1.1: i.| new command \cs{nexttocwithtags},\\
-|                ii.| |.toc| remains usable from other \LaTeX{} source files.\\
-|2012/12/06 v1.0:| initial version.
+\begingroup
+\parindent0pt 
+\makeatletter
+\settowidth{\dimen@}{\ttfamily 2013/03/04 v1.2: i.\space}
+\everypar\expandafter{\expandafter\hangindent\the\dimen@
+                                  \hangafter1 }
+\makeatother
+
+|2013/03/04 v1.2: i. |added \csa{tableoftaggedcontents} as a wrapper for using
+\csa{nexttocwithtags} followed with |tableof|'s private copy of the |.toc| data.
+
+|                ii. |added \csa{if@filesw} test to \csa{tofOpenTocFileForWrite}.
+
+|2012/12/13 v1.1: i. |new command \csa{nexttocwithtags}.
+
+|                ii. ||.toc| may be input in another document not loading \tableof.
+
+|2012/12/06 v1.0:    |initial version.\par
+
+\endgroup
+
+\bigskip % pourquoi le faut-il?
 
 \section{Generating the package file and the test file}
 
@@ -498,12 +619,6 @@ bookmarks.)
 Writing-up source code comments is hopefully for a future
 release. 
 
-% I don't want to have to type at this location (far from the top of the file)
-% explicitly the package version or version date, as it is inconvenient to have
-% to remember to do this when updating the package. Also, I prefer not to add
-% macros to the |.sty| file macros with the package date, name, or version. So I
-% cut out the following from the real macrocode environment (leaving out the
-% \init@crossref.)
 \makeatletter
 \begingroup
 \topsep\MacrocodeTopsep
@@ -546,11 +661,11 @@ release.
 \def\tof@readtoc#1{%
   \ifeof #1
      \let\tof@nextread\@gobble
-     \global\tof@toctoks=\expandafter{\the\tof@toctoks}%
+     \global\tof@toctoks\expandafter{\the\tof@toctoks}%
   \else
      \let\tof@nextread\tof@readtoc
      \read #1 to \tof@buffer
-     \tof@toctoks=\expandafter\expandafter\expandafter
+     \tof@toctoks\expandafter\expandafter\expandafter
        {\expandafter\the\expandafter\tof@toctoks\tof@buffer}%
   \fi
   \tof@nextread{#1}}
@@ -564,15 +679,16 @@ release.
            \tof@readtoc\tof@tf
         \closein\tof@tf}}{}
 %    \end{macrocode}
+% 2013/03/04: \csa{string\{}->\{, idem with \}. And added \csa{if@filesw} test.
 %    \begin{macrocode}
 \AtBeginDocument{
-    \addtocontents{toc}{\string\@ifundefined\string{tof@begin\string}}
-    \addtocontents{toc}{\string{\let\string\tof@begin\string\relax%
+    \addtocontents{toc}{\string\@ifundefined{tof@begin}}
+    \addtocontents{toc}{{\let\string\tof@begin\string\relax%
         \string\let\string\tof@finish\string\relax%
         \string\let\string\tof@starttags\string\@gobble%
         \string\let\string\tof@stoptags\string\@gobble%
         \string\let\string\tof@tagthis\string\@gobble%
-        \string\let\string\tof@untagthis\string\@gobble\string}\string{\string}}
+        \string\let\string\tof@untagthis\string\@gobble}{}}
     \addtocontents{toc}{\string\tof@begin}
     \@ifpackageloaded{hyperref}
        {\def\tof@gobblethree@orfour#1#2#3#4{}%
@@ -580,9 +696,14 @@ release.
        {\def\tof@gobblethree@orfour#1#2#3{}}}
 \AtEndDocument{\addtocontents{toc}{\string\tof@finish}}
 \newcommand\tofOpenTocFileForWrite{%
-\expandafter\newwrite \csname tf@toc\endcsname
-\immediate \openout \csname tf@toc\endcsname \jobname .toc\relax}
+  \if@filesw 
+   \newwrite \tf@toc 
+   \immediate \openout \tf@toc \jobname .toc\relax 
+  \fi}
 %    \end{macrocode}
+% Creating our booleans is not the most economical, (one could have used a
+% single list macro) but heck, how many tags are there going to be anyhow in
+% normal use? a dozen at the very most I think.
 %    \begin{macrocode}
 \def\tof@tags{}
 \def\tof@tags@tmp{}
@@ -593,6 +714,10 @@ release.
                        \let\tof@next\@secondoftwo\fi}
 \def\tof@secondiffalse#1{\csname tofsw@#1\endcsname\else
                        \let\tof@next\@secondoftwo\fi}
+%    \end{macrocode}
+% Just using the \csa{@for} thing with no attempt at any more sophisticated
+% parsing (for spaces in particular).
+%    \begin{macrocode}
 \def\tof@setflags#1{\let\tof@next\@firstoftwo
         \@for\@tempa:=#1\do{\tof@true{\@tempa}}%
         \@for\@tempa:=\tof@tags\do{\tof@false{\@tempa}}%
@@ -629,30 +754,25 @@ release.
         \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}%
         \tof@next\tof@savedcontentsline\tof@gobblethree@orfour}%
     \the\tof@toctoks}
-%    \end{macrocode}
-%    \begin{macrocode}
 \def\tof@or#1{%
     \tof@init{\tof@setflags{#1}\def\tof@tags@tmp{}\def\tof@untags@tmp{}%
         \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}%
         \tof@next\tof@gobblethree@orfour\tof@savedcontentsline}%
     \the\tof@toctoks}
-%    \end{macrocode}
-%    \begin{macrocode}
 \def\tof@nor#1{%
     \tof@init{\tof@setflags{#1}\def\tof@tags@tmp{}\def\tof@untags@tmp{}%
         \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}%
         \tof@next\tof@savedcontentsline\tof@gobblethree@orfour}%
    \the\tof@toctoks}
-%    \end{macrocode}
-%    \begin{macrocode}
 \def\tof@nand#1{%
     \tof@init{\tof@setflags{#1}\def\tof@tags@tmp{}\def\tof@untags@tmp{}%
         \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}%
         \tof@next\tof@gobblethree@orfour\tof@savedcontentsline}%
     \the\tof@toctoks}
+\newcommand*\tableof{\@ifstar{\tof@or}{\tof@and}}
+\newcommand*\tablenotof{\@ifstar{\tof@nand}{\tof@nor}}
 %    \end{macrocode}
 %    \begin{macrocode}
-\newcommand\nexttocwithtags{\@ifstar{\tof@nextof@or}{\tof@nextof@and}}
 \def\tof@nextof@or#1{\toks\z@{\tof@setflags{#1}%
         \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}%
         \tof@next
@@ -668,25 +788,29 @@ release.
              {\tof@setflags{#1}\def\tof@tags@tmp{}\def\tof@untags@tmp{}%
               \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}%
               \tof@next\tof@savedcontentsline\tof@gobblethree@orfour}}%
-       \expandafter\tof@init\expandafter{\the\toks\z@}}
+       \expandafter\tof@init\expandafter{\the\toks\z@}%
+       \tof@printtoc}
 \def\tof@nextof@nand#1{%
        \toks\z@\expandafter{\the\toks\z@ 
              {\tof@setflags{#1}\def\tof@tags@tmp{}\def\tof@untags@tmp{}%
               \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}%
               \tof@next\tof@gobblethree@orfour\tof@savedcontentsline}}%
-       \expandafter\tof@init\expandafter{\the\toks\z@}}
-\newcommand\tableof{\@ifstar{\tof@or}{\tof@and}}
-\newcommand\tablenotof{\@ifstar{\tof@nand}{\tof@nor}}
+       \expandafter\tof@init\expandafter{\the\toks\z@}%
+       \tof@printtoc}
+\newcommand*{\nexttocwithtags}{\let\tof@printtoc\relax
+             \@ifstar{\tof@nextof@or}{\tof@nextof@and}}
+\newcommand*{\tableoftaggedcontents}{\def\tof@printtoc{\the\tof@toctoks}%
+             \@ifstar{\tof@nextof@or}{\tof@nextof@and}}
 %    \end{macrocode}
 %    \begin{macrocode}
 \newcommand*\toftagthis[1]{\addtocontents{toc}
-          {\string\tof@tagthis\string{#1\string}}}
+          {\string\tof@tagthis{#1}}}
 \newcommand*\tofuntagthis[1]{\addtocontents{toc}
-          {\string\tof@untagthis\string{#1\string}}}
+          {\string\tof@untagthis{#1}}}
 \newcommand*\toftagstart[1]{\addtocontents{toc}
-          {\string\tof@starttags\string{#1\string}}}
+          {\string\tof@starttags{#1}}}
 \newcommand*\toftagstop[1]{\addtocontents{toc}
-          {\string\tof@stoptags\string{#1\string}}}
+          {\string\tof@stoptags{#1}}}
 \endinput
 %    \end{macrocode}
 % \MakePercentComment
@@ -706,7 +830,7 @@ release.
   Grave accent  \`     Left brace    \{     Vertical bar  \|
   Right brace   \}     Tilde         \~}
 
-\CheckSum{474}
+\CheckSum{473}
 
 \Finale
 %%