% -*- coding: utf-8; -*-
%<*none>
{\def\doctimestamp {Time-stamp: <17-09-2024 10:15:25 CEST>}%
 \def\getdtxtimestamp #1 <#2 #3 #4>{#2 at #3 #4}%
 \xdef\tofdtxtimestamp {\expandafter\getdtxtimestamp\doctimestamp }}%
%</none>
%%
%% Package: tableof
%% Version: 1.4d (2024/09/17)
%% License: LPPL 1.3c
%% Copyright (C) 2012, 2013, 2015, 2018, 2021, 2024 Jean-Francois Burnol <jfbu at free dot fr>
%%
% See README.md for installation instructions
%
%     This Work may be distributed and/or modified under the
%     conditions of the version 1.3c of the LaTeX Project Public License.
%     This version of this license is in 
%          http://www.latex-project.org/lppl/lppl-1-3c.txt
%     and version 1.3 or later is part of all distributions of
%     LaTeX version 2005/12/01 or later. 
%
% The Author of this Work is: Jean-Francois Burnol <jfbu at free dot fr> 
%<*none>
\def\pkgname        {tableof}
\def\pkgdate        {2024/09/17}
\def\pkgversion     {v1.4d}
\def\pkgdescription {Tables of tagged contents (JFB)}
\begingroup
\input docstrip.tex
\askforoverwritefalse
\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
\string\ProvidesPackage{\pkgname}^^J%
\space[\pkgdate\space\pkgversion\space\pkgdescription]}
\generate{\usepreamble\defaultpreamble
\file{\pkgname test.tex}{\from{\pkgname.dtx}{test}}
\usepreamble\pkgpreamble
\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}
\endgroup
\ifdefined\documentclass\else
\newlinechar13 \catcode13 12 \immediate\write128{%
********************************************************************
*
* To finish the installation you have to move the following
* file into a repertory searched by TeX:
*
* \space\space\space\space    tableof.sty
*
* To produce the tableof.pdf documentation, run "latexmk"
* on tableof.dtx then "dvipdfmx" on tableof.dvi
* (or latex thrice then dvipdfmx)
*
* Notice that this will again extract tableof.sty in the current
* repertory.
*
* Happy TeXing!
*
********************************************************************}%
\endinput\expandafter\end\fi%
\ProvidesFile{\pkgname.dtx}%
  [\pkgname source and documentation (\tofdtxtimestamp)]
\iffalse
%</none>
%<*test>
%-------------------------------------------------------------------------------
%% This file `tableoftest.tex' serves to demontrate the use of the
%% 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} % for testing
\DeclareRobustCommand\lowast{\raisebox{-.25\height}{*}}
\begin{document}
%% \etoctoclines % (if using package etoc)
%%
%% we don't need here \tofOpenTocFileForWrite
%% as the document has \tableofcontents a few lines down.
%%
\section*{\string\tableof\{\}}
\tableof{}
\section*{\string\tableof\lowast\{A,B,C,D,E,F\}}
% vérifions que c'est bon avec les espaces: (1.3 de 2015/02/11)
\tableof*{  A, B,C , D , E, F  }
\section*{\string\tableof\{A\}}
\tableof{A}
\section*{\string\tableof\lowast\{A\}}
\tableof*{A}
\section*{\string\tableof\{A,C\}}
\tableof{  A ,C }
\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 
%% \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 (using \string\tableoftaggedcontents)}
\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) (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}
\tablenotof{ A  ,  B , C}
\section*{without A or without B or without C}
\tablenotof*{A,  B,C   }
\section*{with D and with E}
\tableof{D,E}
\section*{with E}
\tableof{E}
\section*{without D}
\tablenotof{D}
\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
\begin{verbatim}
\toftagstart{D,E,F}
\toftagthis{A}
\end{verbatim}
\toftagstart{   D,  E,  F }
\toftagthis{A}
\section{A,D,E,F}
A,D,E,F
\begin{verbatim}
\toftagthis{B}
\end{verbatim}
\toftagthis{B}
\section{B,D,E,F}
B,D,E,F
\begin{verbatim}
\toftagthis{C}
\end{verbatim}
\toftagthis{  C  }
\section{C,D,E,F}
C,D,E,F
\begin{verbatim}
\toftagstop{F}
\toftagthis{A,B}
\end{verbatim}
\toftagstop{F}
\toftagthis{      A,B}
\section{A,B,D,E}
A,B,D,E
\begin{verbatim}
\toftagthis{B,C}
\end{verbatim}
\toftagthis{B,       C}
\section{B,C,D,E}
B,C,D
\begin{verbatim}
\toftagthis{A,C}
\toftagstop{E}
\end{verbatim}
\toftagthis{   A,   C}
\toftagstop{     E}
\section{A,C,D}
A,C,D
\begin{verbatim}
\toftagstop{D}
\toftagthis{A,B,C}
\end{verbatim}
\toftagstop{D     }
\toftagthis{A,B,C     }
\section{A,B,C}
A,B,C
\begin{verbatim}
\toftagstop{A,B,C,D,E,F}
\toftagstart{kitchenware,rabbits}
\end{verbatim}
\toftagstop{A,B,       C,D,E,F}
\toftagstart{       kitchenware,rabbits}
\section{Knives and rabbits}
\begin{verbatim}
\tofuntagthis{kitchenware}
\end{verbatim}
\tofuntagthis{kitchenware}
\subsection{Hunting rabbits}
\begin{verbatim}
\tofuntagthis{rabbits}
\end{verbatim}
\tofuntagthis{rabbits}
\subsection{Best knives for cooking}
\subsection{Eating rabbits}
\begin{verbatim}
\toftagstart{ecology}\tofuntagthis{rabbits}
\end{verbatim}
\toftagstart{ecology}\tofuntagthis{        rabbits}
\section{Knives and global climate}
\begin{verbatim}
\toftagstop{kitchenware}
\end{verbatim}
\toftagstop{kitchenware      }
\section{The rabbit in the wild}
\subsection{Impact of the rabbit on global climate}
\begin{verbatim}
\toftagstop{rabbits}
\end{verbatim}
\toftagstop{      rabbits}
\section{Other species of interest for cooking}
\end{document}\endinput
%-------------------------------------------------------------------------------
%</test>
%<*none>
\fi
\makeatletter
   \@for\@tempa:=hyperref,bookmark,graphicx,color\do
            {\PassOptionsToPackage{dvipdfmx}\@tempa}
   %
   \PassOptionsToPackage{dvipdfm}{geometry}
   \PassOptionsToPackage{bookmarks=true}{hyperref}
   \PassOptionsToPackage{dvipdfmx-outline-open}{hyperref}
% obsolete
%   \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
   %
\makeatother
\documentclass[a4paper,fontsize=11pt,abstract]{scrartcl}
\makeatletter
%%% START OF CUSTOM doc.sty LOADING (May 21, 2022 in xint.dtx)
%%% (August 26, 2022 in etoc.dtx, comments trimmed)
%%% (September 17, 2024 here, some unneeded stuff removed,
%%%  I do not have time to do the syntax coloring as in etoc.pdf,
%%%  and in particular there is here no reason to use doc=v2)


% At 1.4d I wanted to use doc v3, but hypdoc is causing too much trouble.
% - a warning in the log about hyperref already loaded,
% - an overwrite of my hidelinks option,
% - an impact on placement of codeline numbers in implementation part.
\usepackage{doc}[=v2]
% As explained above I was formerly using scrdoc hence ltxdoc indirectly.
% Let's emulate here the little I appear to need from ltxdoc.cls and
% srcdoc.cls.
%
\AtBeginDocument{\MakeShortVerb{\|}}
\DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{}
\DeclareFontFamily{OMS}{cmtt}{\skewchar\font 48}  % '60
\DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{}
\DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{}
\DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{}
\CodelineNumbered
% \EnableCrossrefs  % but this will be hacked
% \setcounter{StandardModuleDepth}{1} % we don't use this mechanism currently
\def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
\def\cmd@to@cs#1#2{\char\number`#2\relax}
% Here I am loading doc=v2 but formerly I was using ltxdoc via scrdoc
% which I dropped at release 1.4l (2022-05-29) and without much
% thinking I had kept this.
\DeclareRobustCommand\cs[1]{\texttt{\bslash#1}}
% As I may have the * active, or macro names with _ or ^, I should
% add \detokenize.  But see below for a redefinition anyhow.
%
% More urgent is that I am also using hyperref and this definition gives wrong
% bookmarks if \cs is used in section titles.  As I had very very few usags of
% \cs in the whole of xint.dtx, it took me a while to realize the problem
% here.  Turns out that doc=v3 by default loads hypdoc which includes this
% configuration for hyperref compatibility:
\AtBeginDocument{%
\pdfstringdefDisableCommands{\def\cs#1{\textbackslash\detokenize{#1}}}%
}%
% As I have not loaded hyperref yet I must delay it to AtBeginDocument.
\providecommand\marg[1]{%
  {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
\providecommand\oarg[1]{%
  {\ttfamily[}\meta{#1}{\ttfamily]}}
\providecommand\parg[1]{%
  {\ttfamily(}\meta{#1}{\ttfamily)}}
% \@addtoreset{CodelineNo}{part}% No need for this here
% \def\partname{File}% \partname is "fixed" somewhere further down anyhow
% No need for this, anyhow I don't build the indices
% \gdef\codeline@wrindex#1{\if@filesw
%       \begingroup
%         \let\protect\noexpand
%         \immediate\write\@indexfile
%             {\string\indexentry{#1}%
%             {\filesep\number\c@CodelineNo}}%
%       \endgroup\fi}
% \let\filesep\@empty

% There is very little we seem to need from the scrdoc extras: page geometry
% is set by geometry package and a4paper option from xint.tex file.  So it
% seems I only need the hologo loading:
\usepackage{hologo}
%\DeclareRobustCommand*{\eTeX}{\hologo{eTeX}}%
%\DeclareRobustCommand*{\LuaTeX}{\hologo{LuaTeX}}%
%
\makeatother
%%% end of ltxdoc+srcdoc emulation from June 2022 xint.dtx,
%%% copied over almost verbatim to etoc.dtx on 2022/08/26,
%%% and copied and trimmed for tableof.dtx 2024/09/17.

\pagestyle{headings}
\usepackage[T1]{fontenc}
\usepackage[hscale=0.66,vscale=0.76]{geometry}
\usepackage{centeredline}
\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}

% pdfencoding = unicode maintenant défaut
\usepackage{hyperref}

\hypersetup{%
linktoc=all,%
breaklinks=true,%
hidelinks,%
pdfauthor={Jean-François Burnol},%
pdftitle={The tableof package},%
pdfsubject={LaTeX, table of contents},%
pdfkeywords={LaTeX, table of contents},%
pdfstartview=FitH,%
pdfpagemode=UseOutlines}


% Finally 1.4d uses doc=v2
% % Attention que hypdoc fait
% % Package hyperref Info: Option `colorlinks' set `true' on input line 75.
% % Package hyperref Info: Option `plainpages' set `false' on input line 75.
% % Package hyperref Info: Option `bookmarksopen' set `true' on input line 75.
% % Package hyperref Info: Option `bookmarksnumbered' set `true' on input line 75.
% \AtBeginDocument{\hypersetup{hidelinks}}% fix de l'effet de hypdoc

\usepackage{bookmark}

\DeclareRobustCommand\csa[1]{{\ttfamily\char`\\#1}}
\DeclareRobustCommand\csb[1]{{\color{blue}\ttfamily\char`\\#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]{\csa{#1\lowast}}
\newcommand\staritb[1]{\csb{#1\lowast}}

\makeatletter\let\check@percent\relax\makeatother

\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

\renewcommand\familydefault\sfdefault

\usepackage{framed}
\begin{document}
\thispagestyle{empty}
\rmfamily

\begin{center}
  {\normalfont\Large The \tableof  package}\\
  \bigskip
  \footnotesize \ttfamily 
  Package version: \pkgversion\ (\pkgdate)\\
  Documentation generated from tableof.dtx
  with timestamp \tofdtxtimestamp\\
  \textcopyright 2012, 2013, 2015, 2018, 2021, 2024 Jean-François Burnol
  <jfbu (at) free (dot) fr>
\end{center}

\begin{abstract}
  Provides |\toftagstart{}|, |\toftagstop{}|, |\toftagthis{}|,
  |\tofuntagthis{}| to tag chapters, sections or any other sectioning units
  destined to end up in the table(s) of contents. Then each one of
\begin{verbatim}
  \tableof{required tags}
  or \tablenotof{excluded tags}
  or \tableoftaggedcontents{required tags}{excluded tags}
\end{verbatim}
  typesets a table of contents (with no heading) obeying the conditions. These
  macros can each be used multiple times in the document with varying
  arguments.

  If the document contains no usage of |\tableofcontents|, the preamble should
  also contain an additional |\AtBeginDocument{\tofOpenTocFileForWrite}|.

  The main |\tableofcontents| can also be influenced by tags like this:
\begin{verbatim}
  \nexttocwithtags{required tags}{excluded tags}
  \tableofcontents
\end{verbatim}

  Depending on the document class and packages, |\tableofcontents| however may
  be usable only once, contrarily to the |\tableof{}| et al.\@ package macros.

\end{abstract}

\tableofcontents


\section{Tagging commands}

\subsection{\csbhyp{toftagstart \{tag1, tag2, ...\}} and
  \csbhyp{toftagstop \{tag1, tag2, ...\}}}

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}    % 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}         % tagged with gastronomy+tag1
\end{verbatim}

\subsection{\csbhyp{toftagthis \{tag1, tag2, ...\}}  and
  \csbhyp{tofuntagthis \{tag1, tag2, ...\}}}

The \csa{toftagthis} command flags with the comma separated values from its
list argument only the \emph{next} sectioning command. The effect is not
cumulative: it is the last use of \csa{toftagthis} which counts; use it for
all the needed tags at once.

The \csa{tofuntagthis} command similarly untags only the \emph{next} entry.
Similarly, only the tags in the last call of \csa{tofuntagthis} are taken into
account.
\begin{verbatim}
\toftagstart{kitchenware, 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} % tagged with kitchenware+rabbits+ecology+climate

\toftagstop{kitchenware}
\section{The rabbit in the wild}    % tagged with rabbits+ecology
\end{verbatim}

\subsection{Spaces}

Spaces in tags and around commas in tag lists are transparently removed.
Tags may be macros, they are completely
expanded before use.

\section{Table of contents commands}

\subsection{\csbhyp{nexttocwithtags \{required tag1, required tag2,
    ...\}\{excluded tag1, excluded tag2, ...\}}}

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|.

\begin{framed}
  \noindent\textbf{DO NOT FORGET THE SECOND PAIR OF BRACES EVEN IF YOU ONLY
    WANT TO REQUIRE SOME TAGS:} \csa{nexttocwithtags}|{tag1, tag2}{}|.
\end{framed}

\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}

\subsection{\csbhyp{tableoftaggedcontents \{required tag1, required tag2,
    ...\}\{excluded tag1, excluded tag2, ... \}}}

This command is provided in case the document class allows only a single use
of \csa{tableofcontents}, indeed \csa{tableoftaggedcontents} can be used
arbitrarily many times. \textbf{However it does not typeset a heading}. Example:
\begin{verbatim}
\section*{A table of tagged contents}  % <- needs to be explicitely added
\tableoftaggedcontents{weaponry, hunting}{ecology, climate}
\end{verbatim}
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}
\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 tag1, required tag2, ...\}}}

This is equivalent to |\tableoftaggedcontents{required tag1, ...}{}|.
\begin{verbatim}
\tableof{weaponry,hunting}  % will print the entries tagged with weaponry 
                                                             AND hunting
\end{verbatim}
There is a starred variant:
\begin{verbatim}
\tableof*{weaponry, hunting} % will print the entries tagged with weaponry 
                                                              OR hunting
\end{verbatim}

\subsection{\csbhyp{tablenotof \{excluded tag1, excluded tag2, ...\}}}

This is equivalent to |\tableoftaggedcontents{}{excluded tag1, ...}|.
\begin{verbatim}
\tablenotof{weaponry, hunting}  
% will print the entries NOT tagged with weaponry NEITHER with hunting
\end{verbatim}
There is a starred variant:
\begin{verbatim}
\tablenotof*{weaponry, hunting} 
% will print the entries NOT tagged with weaponry OR NOT tagged with hunting
\end{verbatim}


\subsection{\csbhyp{tofOpenTocFileForWrite}}

The contents of the |.toc| file (if it already exists) are read into memory by
\tableof once, at the time of |\begin{document}|.\footnote{New with |1.3|.
    Earlier versions read the |.toc| file at the time of
    \csa{usepackage\{tableof\}}. But this could cause a problem if the |.toc|
    file used characters not yet activated by Babel.} 
Notice that this reading of the |.toc| file into memory is only of relevance
if the document makes use of one of the \csa{tableoftaggedcontents},
\csa{tableof} or \csa{tablenotof} commands.

The creation of the |.toc| file is \emph{not} dealt with by \tableof itself:
either this will be 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 should \textbf{not} be used in the
preamble, however
\begin{verbatim}
    \usepackage{tableof}
    \AtBeginDocument{\tofOpenTocFileForWrite}
\end{verbatim}
is possible.

Please consider: this command should \emph{not} be used when the
  document makes use of its own \csa{tableofcontents} or equivalent. It is
  provided \emph{only} for the case where the document uses \emph{exclusively}
  \csa{tableoftaggedcontents}, \csa{tableof} and \csa{tablenotof}.

\section{Compatibility with other packages}

\tableof requires the document |.toc| file to use the |\contentsline| macro
(possibly patched by other packages). It is thus incompatible with the
|beamer| class. However, if |beamer| is used in an article mode, i.e., with
the article class in conjunction with the |beamerarticle| package, then \tableof
should work.

\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. Since
release |1.3|, these redefinitions are done in \emph{one single} line of the
|.toc| file to circumvent interference of |biblatex| which adds
commands to the |.toc| line on every other line (thus, potentially right in
the middle of multi-line commands \verb+:-(+.)

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. 

\section{Version History}

\begingroup
\parindent0pt 
\makeatletter
\settowidth{\dimen@}{\ttfamily 2015/03/10 v1.4a: i.\space}
\everypar\expandafter{\expandafter\hangindent\the\dimen@
                                  \hangafter1 }
\makeatother

|2024/09/17 v1.4d:    |reestablish compatibility with |hyperref|,
which got broken at the latter |v7.01c| release.  The package now
requires \LaTeX{} |2020-10-01|.  Thanks to Ekkart Kleinod for report.

|2021/07/05 v1.4c:    |ensure the added scope-limiting group for |\tableof{}|
and alike macros encompasses all contents of the |.toc| file even in presence
of packages hacking into these contents (in particular |biblatex|).
%! https://tex.stackexchange.com/questions/603540/tableof-package-erases-citations/

|2018/10/02 v1.4b:    |fix for situations when a |\clearpage| before
the |\end{document}| resulted in the loss of the |\tof@finish| token from |.toc|
file, causing the package to misbehave.
%! (cf.
%! \url{https://tex.stackexchange.com/q/358014/4686}).
The package
|atveryend| is now required.\footnote{\url{http://www.ctan.org/pkg/atveryend}}

|2015/03/10 v1.4a: i. |changes in the code to make it more easily patchable by
other packages (I have especially the next release of \etoc in mind): changes
to the way |\tof@begin|, |\tof@finish| are set up, new |\tof@global| which
defaults to nothing but may be set to be |\global| (this is in view of doing
TOCs as tabulars of longtables, in the way \etoc |1.08| will permit).

|                 ii. |improved sectioning of the documentation.

|2015/02/20 v1.4:  i. |some code efficiency improvements (perhaps...).

|                 ii. |improved documentation.

|2015/02/11 v1.3:  i. |comma separated lists of tags now allow spaces.

|                 ii. |only one line used for the |.toc| code silently
unactivating |tableof| if its |\usepackage{tableof}| has been removed from the
document source. (needed due to aggressive |biblatex| interference with |.toc|
files.)

|                iii. |reading of .toc file is delayed to |\begin{document}| to
account for possible Babel active characters used therein. Not relevant if
document uses standard |\tableofcontents| or like commands.

|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

\section{Implementation}

\makeatletter
\StopEventually{\check@checksum\end{document}}
\makeatother

% % Suite à mésaventure le 9 mars 2015 dans etoc.dtx:
%
% % ATTENTION QU'AVANT DE COMMENCER DES MACROCODE IL FAUT OBLIGATOIREMENT UN
% % PARAGRAPHE APRÈS \section (SINON ESPACEMENTS VERTICAUX POST MACROCODE
% % SUPPRIMÉS :((((( )
%
% % ceci faisait donc l'affaire :
%
% % Writing-up source code comments is hopefully for a future
% % release. 
%
% % maintenant je fais:
% %
% \indent
%
% Finalement, j'ai fait un bug report en 2021 et trouvé un
% workaround
% https://github.com/latex3/latex2e/issues/563
\makeatletter
\AddToHook{env/macrocode/begin}{\partopsep0pt\relax}
\AddToHook{env/macrocode/after}{\@nobreakfalse}
\makeatother

\makeatletter
\begingroup
\topsep\MacrocodeTopsep
\trivlist\parskip\z@\item[]
\macro@font
\leftskip\@totalleftmargin  \advance\leftskip\MacroIndent
\rightskip\z@  \parindent\z@  \parfillskip\@flushglue
\global\@newlistfalse \global\@minipagefalse
\ifcodeline@index
  \everypar{\global\advance\c@CodelineNo\@ne
  \llap{\theCodelineNo\ \hskip\@totalleftmargin}}%
\fi
\string\ProvidesPackage\string{\pkgname\string}\par
\noindent\space [\pkgdate\space\pkgversion\space\pkgdescription]\par
\nointerlineskip
\global\@inlabelfalse
\endtrivlist
\endgroup
\makeatother
% The catcode hackery next is to avoid to have <*package> to be listed
% in the commented source code...
% (c) 2012/11/19 jf burnol ;-)
\MakePercentIgnore
%
% \catcode`\<=0 \catcode`\>=11 \catcode`\*=11 \catcode`\/=11
% \let</none>\relax
% \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12}
%
%</none>
%<*package>
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[2020/10/01]
\RequirePackage{atveryend}
\DeclareOption*{\PackageWarning{tableof}{Option `\CurrentOption' is unknown.}}
\ProcessOptions\relax
\newtoks\tof@toctoks
%    \end{macrocode}
% |1.3| codes this |\tof@readtoc| slightly better (copied from \etoc.dtx).
%    \begin{macrocode}
\def\tof@readtoc {%
  \ifeof\tof@tf
  \else
     \read\tof@tf to \tof@buffer
     \tof@toctoks\expandafter\expandafter\expandafter
       {\expandafter\the\expandafter\tof@toctoks\tof@buffer}%
     \expandafter\tof@readtoc
  \fi }
%    \end{macrocode}
% |1.3| of |2015/02/11| moves the reading of the toc file to At Begin
% Document. This is needed for Babel activated characters. I also re-use
% |\endlinechar-1| which I had commented out since release |1.1|. Notice
% though that this is irrelevant if the document uses |tableof| only via its
% tagging abilities, and has standard |\tableofcontents| command to print the
% TOC.
%
% |1.4c| injects |\tof@begingroup| and |\tof@endgroup| to wrap the gathered
% the contents of the toc file, rather than having them arise from expansion
% of |\tof@begin| and respectively |\tof@finish|. This avoids a problem with
% |biblatex| additions to the |.toc| file happening before |\tof@begin|. They
% need to have their scope limited. The |\tableof{}| macro and variants will
% thus achieve this automatically via the |\tof@begingroup/\tof@endgroup| pair
% now explicitly added to |\tof@toctoks| contents.
%
% \etoc (a.t.t.o.w |1.09c 2020/05/15|) has some handling of
% |\tof@begingroup/\tof@endgroup| which as far as I understand can
% currently remain as it is. But there is something weird in \etoc with
% a test of |\tof@finish| which probably is in need of revision (even
% independently of changes here).
%
% These changes however mean for usage of |\nexttocwithtags| that whatever
% macro is used to typeset the TOC, it is now the one bearing the
% responsability for creating the scope-limiting group.
%    \begin{macrocode}
\AtBeginDocument{%
  \IfFileExists{\jobname.toc}
    {{\endlinechar\m@ne
        \makeatletter
        \newread\tof@tf
        \openin\tof@tf\@filef@und
        \tof@toctoks{\tof@begingroup}%
        \tof@readtoc
        \global\tof@toctoks=\expandafter{\the\tof@toctoks\tof@endgroup}%
        \closein\tof@tf}}
    {}%
}
%    \end{macrocode}
% The trick is that |\@ifundefined| chooses the undefined branch if the
% meaning is |\relax|. Thus it is possible for \tableof to define and use
% |\tof@begin| and later set it to |\relax|, the entire influence of \tableof
% will then be turned off.
%
% |1.2| of |2013/03/04|: \csa{string\{}->\{, idem with
% \}. And added \csa{if@filesw} test.
%
% |1.3| of |2015/02/11|: to circumvent aggressive biblatex manipulation of the
% |.toc| file, I put things to the |.toc| file in one-go; else weird commands
% might get inserted right in the middle of arguments to a multi-line macro!
% also removed a bunch of |\string|'s: when I first wrote this package I had
% still limited understanding of \TeX's macros.
%
% |1.4a| uses |\@empty| for the default |\tof@finish| rather than |\relax|,
% for no special reason. Also the |\let|'s in case |\tof@begin| is undefined
% or |\relax| are all made global, because for compatibility with the fancy
% things \etoc |1.08| will allow for TOC as table we need a global mode, and
% the simplest is here to do the things global by default.
%
% |1.4c| replaces |{}| (last argument of |\@ifundefined|) by |\relax|. No
% strong reason. We and \etoc use |\endlinechar-1| anyhow.
%    \begin{macrocode}
\AtBeginDocument{%
    \addtocontents{toc}{\string\@ifundefined{tof@begin}%
       {\global\let\string\tof@begin\relax
        \global\let\string\tof@finish\string\@empty
        \global\let\string\tof@starttags\string\@gobble
        \global\let\string\tof@stoptags\string\@gobble
        \global\let\string\tof@tagthis\string\@gobble
        \global\let\string\tof@untagthis\string\@gobble}\relax}%
    \addtocontents{toc}{\string\tof@begin}%
}
%    \end{macrocode}
% \textbf{Now obsolete hyperref-related remark (see next paragraph)}:
% {\itshape\LaTeX\ of 2020 or 2021 always has |\contentsline| with four arguments.
% So an update should be done here to always gobble four, else in absence
% of |hyperref| some |{}| are left. Does not seem to matter a lot except
% if all is executed in math mode... thanks to \etoc for example.
% No urgency here, only mentioning for the record.}
%
% |hyperref| stopped defining its |\hyper@last| at its |7.01c| release in fall
% of 2023, but \tableof tested for it, if |hyperref| was found to be present,
% in case a document previously not using |hyperref| started using it on
% second compilation, hence with a wrong |.toc| file format (in earlier
% years).  As \tableof was doing
% \centeredline{|\ifx\hyper@last\@undefined\tof@toctoks{}\fi|} it now
% unconditionally emptied |\tof@toctoks| in presence of |hyperref|.  This is
% the same problem which impacted \etoc and got fixed at its |1.2c| release
% but unfortunately \tableof was not updated then.  Belatedly fixed at |1.4d|
% of |2024/09/17|.
%
% Formerly this was a short macro, but it doesn't look like a problem
% to simply alias it to the long |\@gobblefour|.
%    \begin{macrocode}
\let\tof@gobblethree@orfour\@gobblefour
%    \end{macrocode}
% |1.4b| (belatedly) fixes issue with |\tof@finish| getting lost due
% to a final |\clearpage| before |\end{document}|. Indeed, formerly
% code did:
%
% {\centering|\AtEndDocument{\addtocontents{toc}{\string\tof@finish}}|\par}
%
% But we can't replace this by some |\immediate\write\@auxout| at end
% document, because it would act \emph{before} the writes triggered by
% the |\clearpage| from inside |\end{document}|, if no such
% |\clearpage| ended the document body. Thus |\AfterLastShipout| comes
% to the rescue, from package |atveryend|.
%    \begin{macrocode}
\AfterLastShipout
    {\immediate\write\@auxout{\string\@writefile{toc}{\string\tof@finish}}}
%    \end{macrocode}
% |1.4a| makes the things more easily patchable by other packages, especially
% I have \etoc in mind.
%
% |\tof@@starttags| and |\tof@@stoptags| are defined a bit later in the code.
% And we use |\tof@global|. And we need |\tof@@finish| to reset |\tof@tags| to
% empty, just in case |\tof@global| was |\global|. And also |\contentsline| !!
% But here it is a problem redefining it globally. In normal use of \tableof,
% nothing needs to be done, because the |\tof@endgroup| closes the scope. In
% global mode (triggered only by \etoc with |\etocglobaldefs| for tabulars),
% it needed to globally modify |\contentsline|, thus it or \etoc has to
% globally unmodify it. \etoc |1.08| by itself without \tableof doesn't have
% to reset |\contentsline| because it re-defined it \emph{before} an eventual
% tabular. But as it forced \tableof to do global things, in such case \etoc
% will have to proceed globally as well.
%    \begin{macrocode}
\let\tof@global     \@empty
\let\tof@begingroup \begingroup
\let\tof@endgroup   \endgroup
%    \end{macrocode}
% No more |\tof@endgroup| here at |1.4c|. See above explanations.
%    \begin{macrocode}
\def\tof@@finish   {\tof@global\let\contentsline\tof@savedcontentsline
                    \global\let\tof@begin\relax
                    \global\let\tof@tags\@empty }
\def\tof@@tagthis   #1{\def\tof@tags@tmp{#1}}
\def\tof@@untagthis #1{\def\tof@untags@tmp{#1}}
%    \end{macrocode}
% No more |\tof@begingroup| here at |1.4c|. See above explanations.
%    \begin{macrocode}
\def\tof@init#1{%
    \def\tof@begin{%
        \tof@global\let\tof@tagthis  \tof@@tagthis
        \tof@global\let\tof@untagthis\tof@@untagthis
        \tof@global\let\tof@starttags\tof@@starttags
        \tof@global\let\tof@stoptags \tof@@stoptags
        \tof@global\let\tof@finish   \tof@@finish
        \tof@global\let\tof@savedcontentsline\contentsline
        \tof@global\def\contentsline {#1}}}
%    \end{macrocode}
% place holder for comments
%    \begin{macrocode}
\newcommand\tofOpenTocFileForWrite{%
  \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.
%
% |1.4a|: fortunately no need for the |\tof@global| thing! However, careful
% with |\tof@tags| it will have to be reset to empty by |\tof@finish| in case
% |\tof@global| is |\global|.
%    \begin{macrocode}
\let\tof@tags      \@empty
\let\tof@tags@tmp  \@empty
\let\tof@untags@tmp\@empty
\def\tof@true #1{\expandafter\let\csname tofsw@#1\endcsname\iftrue}
\def\tof@false#1{\expandafter\let\csname tofsw@#1\endcsname\iffalse}
\def\tof@secondiftrue#1%
   {\csname tofsw@#1\endcsname \let\tof@next\@secondoftwo\fi}
\def\tof@secondiffalse#1%
   {\csname tofsw@#1\endcsname\else\let\tof@next\@secondoftwo\fi}
%    \end{macrocode}
% |1.4a|: fortunately no need for the |\tof@global| thing; the |\tof@setflags|
% is used at \emph{each} |\contentsline|. Quite useful design, congrats to the
% original architect !
%    \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}}%
        \@for\@tempa:=\tof@tags@tmp\do  {\tof@false{\@tempa}}%
        \@for\@tempa:=\tof@untags@tmp\do{\tof@true {\@tempa}}}  
%    \end{macrocode}
% Release |1.4| uses here a bunch of |\expandafter|'s in place of some
% |\edef|'s.
%    \begin{macrocode}
\def\tof@filter#1#2{\ifx#1#2\else
    \ifx\tof@tmptags\@empty
         \expandafter\def\expandafter\tof@tmptags\expandafter{#2}%
    \else
         \expandafter\expandafter\expandafter\def
         \expandafter\expandafter\expandafter\tof@tmptags
         \expandafter\expandafter\expandafter{\expandafter
         \tof@tmptags\expandafter,#2}%
    \fi\fi}
%    \end{macrocode}
% |1.4a| needs the |\tof@global| in the hope for \tableof to be compatible with
% future \etoc |1.08| when employed in the delicate art of TOC as a table !
%    \begin{macrocode}
\def\tof@@starttags#1{%
    \ifx\tof@tags\@empty
      \tof@global\def\tof@tags{#1}%
    \else
      \tof@global
      \expandafter\def\expandafter\tof@tags\expandafter{\tof@tags,#1}%
    \fi }
\def\tof@@stoptags#1{%
    \@for\@tempa:=#1\do{%
          \def\tof@tmptags{}%
          \@for\@tempb:=\tof@tags\do{\tof@filter\@tempa\@tempb}%
          \tof@global
          \expandafter\def\expandafter\tof@tags\expandafter{\tof@tmptags}%
         }%
    }
%    \end{macrocode}
% Until |1.3|, I was just using the \csa{@for} thing with no attempt at any
% extra parsing, for spaces in particular. With |1.3| of |2015/02/11| I use an
% |\edef| to remove all spaces first, using a |\zapspaces| macro pioneered in
% |xintkernel.sty|. Thus, comma separated lists of tags can have spaces. They
% will be removed if not protected by braces.
%    \begin{macrocode}
\def\tof@zapspaces #1 #2{#1#2\tof@zapspaces }%
\def\tof@cleanspaces #1#2{\edef\tof@tmp {{\tof@zapspaces #2 \@gobble}}%
    \expandafter #1\tof@tmp } 
%    \end{macrocode}
% placeholder for comments
%    \begin{macrocode}
\def\tof@and  #1{%
    \tof@init{\tof@setflags{#1}\def\tof@tags@tmp{}\def\tof@untags@tmp{}%
        \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}%
        \tof@next\tof@savedcontentsline\tof@gobblethree@orfour}%
    \the\tof@toctoks }
\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 }
\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 }
\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@cleanspaces\tof@or}
                             {\tof@cleanspaces\tof@and}}
\newcommand*\tablenotof{\@ifstar{\tof@cleanspaces\tof@nand}
                                {\tof@cleanspaces\tof@nor}}
%    \end{macrocode}
% placeholder for comments
%    \begin{macrocode}
\def\tof@nextof@or #1{\toks@{\tof@setflags{#1}%
        \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}%
        \tof@next
        {\def\tof@tags@tmp{}\def\tof@untags@tmp{}\tof@gobblethree@orfour}}%
        \@ifstar{\tof@cleanspaces\tof@nextof@nand}
                {\tof@cleanspaces\tof@nextof@nor}}
\def\tof@nextof@and #1{\toks@{\tof@setflags{#1}%
             \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}%
             \tof@next\@secondoftwo\@firstoftwo
             {\def\tof@tags@tmp{}\def\tof@untags@tmp{}\tof@gobblethree@orfour}}%
        \@ifstar{\tof@cleanspaces\tof@nextof@nand}
                {\tof@cleanspaces\tof@nextof@nor}}
\def\tof@nextof@nor #1{%
       \toks@\expandafter{\the\toks@ 
             {\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@}%
       \tof@printtoc }
\def\tof@nextof@nand #1{%
       \toks@\expandafter{\the\toks@ 
             {\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@}%
       \tof@printtoc }
\newcommand*{\nexttocwithtags}{\let\tof@printtoc\relax
             \@ifstar{\tof@cleanspaces\tof@nextof@or}
                     {\tof@cleanspaces\tof@nextof@and}}
\newcommand*{\tableoftaggedcontents}{\def\tof@printtoc{\the\tof@toctoks}%
             \@ifstar{\tof@cleanspaces\tof@nextof@or}
                     {\tof@cleanspaces\tof@nextof@and}}
%    \end{macrocode}
% placeholder for comments
%    \begin{macrocode}
\newcommand*\toftagthis[1]
  {\addtocontents{toc}{\string\tof@tagthis  {\tof@zapspaces #1 \@gobble }}}
\newcommand*\tofuntagthis[1]
  {\addtocontents{toc}{\string\tof@untagthis{\tof@zapspaces #1 \@gobble }}}
\newcommand*\toftagstart[1]
  {\addtocontents{toc}{\string\tof@starttags{\tof@zapspaces #1 \@gobble }}}
\newcommand*\toftagstop[1]
  {\addtocontents{toc}{\string\tof@stoptags {\tof@zapspaces #1 \@gobble }}}
\endinput
%    \end{macrocode}
% \MakePercentComment
\Finale
%%
%% End of file `tableof.dtx'.

