From 9715f1527c5152cccd38f7064161def1f06d9446 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 5 Jul 2021 20:50:36 +0000
Subject: tableof (5jul21)

git-svn-id: svn://tug.org/texlive/trunk@59837 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/tableof/tableof.dtx | 275 +++++++++++----------
 1 file changed, 145 insertions(+), 130 deletions(-)

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

diff --git a/Master/texmf-dist/source/latex/tableof/tableof.dtx b/Master/texmf-dist/source/latex/tableof/tableof.dtx
index 34a881d1e8a..bd7a435cefb 100644
--- a/Master/texmf-dist/source/latex/tableof/tableof.dtx
+++ b/Master/texmf-dist/source/latex/tableof/tableof.dtx
@@ -1,94 +1,65 @@
-% -*- coding: iso-latin-1; -*-
+% -*- coding: utf-8; -*-
 %<*none>
-{\def\doctimestamp {Time-stamp: <02-10-2018 11:43:43 CEST>}% 
+{\def\doctimestamp {Time-stamp: <05-07-2021 14:42:11 CEST>}%
  \def\getdtxtimestamp #1 <#2 #3 #4>{#2 at #3 #4}%
  \xdef\tofdtxtimestamp {\expandafter\getdtxtimestamp\doctimestamp }}%
-\def\docdate{2018/10/02}
 %</none>
 %%
 %% Package: tableof
-%% Version: 1.4b (2018/10/02)
+%% Version: 1.4c (2021/07/05)
 %% License: LPPL 1.3c
-%% Copyright (C) 2012-2018 Jean-Francois Burnol <jfbu at free dot fr>
+%% Copyright (C) 2012, 2013, 2015, 2018, 2021 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 LaTeX Project Public License, either
-%     version 1.3c of this license. This version of this license is in 
+%     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> 
-% 
-%  Installation:
-%  ============
-%
-%       latex tableof.dtx
-%
-% `tableof.sty`, `tableof.ins` and `tableoftest.tex` are generated
-% on the first latex run. Move `tableof.sty` to a suitable
-% location within the TeX installation:
-%
-%       tableof.sty -> <TDS>/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 see examples of tagged tables of contents.
-%
-% To generate the documentation, run once more latex on tableof.dtx,
-% then run dvipdfmx on tableof.dvi
-%
-%<*ins>
+%<*none>
 \def\pkgname        {tableof}
-\def\pkgdate        {2018/10/02}
-\def\pkgversion     {v1.4b}
+\def\pkgdate        {2021/07/05}
+\def\pkgversion     {v1.4c}
 \def\pkgdescription {Tables of tagged contents (JFB)}
-%</ins>
-%<*none>
-\ProvidesFile{\pkgname.dtx}%
-  [\pkgname source and documentation (\tofdtxtimestamp)]
 \begingroup
 \input docstrip.tex
 \askforoverwritefalse
 \def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
 \string\ProvidesPackage{\pkgname}^^J%
 \space[\pkgdate\space\pkgversion\space\pkgdescription]}
-\generate{\nopreamble
-\file{\pkgname.ins}{\from{\pkgname.dtx}{ins}}
-\usepreamble\defaultpreamble
+\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>
-%<*ins>
-%-------------------------------------------------------------------------------
-%% This file `tableof.ins' is provided for compatibility with TeX
-%% distributions expecting to find it for installation of `tableof.sty'.
-%%
-%% As usual `tex tableof.ins' produces `tableof.sty' from the source
-%% `tableof.dtx'
-%%
-%% (an already existing `tableof.sty' in the same repertory will be
-%% overwritten)
-%% 
-%% Move `tableof.sty' to a suitable location within the TeX installation:
-%% tableof.sty -> <TDS>/tex/latex/tableof/
-%%
-%% The generated auxiliary files may be discarded. 
-%%
-\input docstrip.tex
-\askforoverwritefalse
-\def\pkgpreamble{\defaultpreamble^^J\MetaPrefix^^J%
-\string\ProvidesPackage{\pkgname}^^J%
-\space[\pkgdate\space\pkgversion\space\pkgdescription]}
-\generate{\usepreamble\pkgpreamble
-\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}}
-\endbatchfile
-%-------------------------------------------------------------------------------
-%</ins>
 %<*test>
 %-------------------------------------------------------------------------------
 %% This file `tableoftest.tex' serves to demontrate the use of the
@@ -111,7 +82,7 @@
 \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)
+% 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}
@@ -262,12 +233,12 @@ A,B,C
    \PassOptionsToPackage{dvipdfm}{geometry}
    \PassOptionsToPackage{bookmarks=true}{hyperref}
    \PassOptionsToPackage{dvipdfmx-outline-open}{hyperref}
-   \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
+% obsolete
+%   \PassOptionsToPackage{dvipdfmx-outline-open}{bookmark}
    %
 \makeatother
 \documentclass[a4paper,fontsize=11pt,abstract]{scrdoc}
 \pagestyle{headings}
-\usepackage[latin1]{inputenc}
 \usepackage[T1]{fontenc}
 \usepackage[hscale=0.66,vscale=0.76]{geometry}
 
@@ -329,13 +300,14 @@ A,B,C
 
 \usepackage[english]{babel}
 
-\usepackage[pdfencoding=pdfdoc]{hyperref}
+% pdfencoding = unicode maintenant dÃ©faut
+\usepackage{hyperref}
 
 \hypersetup{%
 linktoc=all,%
 breaklinks=true,%
 hidelinks,%
-pdfauthor={Jean-Fran\c cois Burnol},%
+pdfauthor={Jean-FranÃ§ois Burnol},%
 pdftitle={The tableof package},%
 pdfsubject={LaTeX, table of contents},%
 pdfkeywords={LaTeX, table of contents},%
@@ -368,7 +340,7 @@ pdfpagemode=UseOutlines}
     \texorpdfstring{{\color{niceone}\ttfamily\bfseries etoc}}
                    {etoc}\xspace}
 
-\frenchspacing
+%\frenchspacing
 
 \renewcommand\familydefault\sfdefault
 
@@ -379,33 +351,40 @@ pdfpagemode=UseOutlines}
 
 \begin{center}
   {\normalfont\Large The \tableof  package}\\
-  \textsc{Jean-François Burnol}\par
+  \bigskip
   \footnotesize \ttfamily 
-  jfbu (at) free (dot) fr\\
   Package version: \pkgversion\ (\pkgdate)\\
-  Documentation generated from the source file\\
-  with timestamp ``\tofdtxtimestamp''
+  Documentation generated from tableof.dtx
+  with timestamp \tofdtxtimestamp\\
+  \textcopyright 2012, 2013, 2015, 2018, 2021 Jean-FranÃ§ois Burnol
+  <jfbu (at) free (dot) fr>
 \end{center}
 
 \begin{abstract}
-The commands \csa{toftagstart}, \csa{toftagstop}, \csa{toftagthis},
-\csa{tofuntagthis} are used to tag chapters, sections or any other sectioning
-units destined to end up in the table(s) of contents. Then:
-\begin{quote}
-  \csa{nexttocwithtags}\{req. 1, req. 2, ...\}\{excl. 1,
-    excl. 2, ...\}\\
-  \csa{tableofcontents} |% or equivalent command|
-\end{quote}
-specifies which tags are to be required and which ones are to be
-excluded from the typeset TOC.
-
-For documents with classes where \csa{tableofcontents} is only single-use,
-the package provides:
-\begin{quote}
-  \csa{tableoftaggedcontents}\{req. 1, req. 2, ...\}\{excl. 1,
-    excl. 2, ...\}
-\end{quote}
-which does not have this restriction.
+  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
@@ -463,7 +442,7 @@ account.
 \subsection{Spaces}
 
 Spaces in tags and around commas in tag lists are transparently removed.
-(\emph{new with release} |1.3|). Tags may be macros, they are completely
+Tags may be macros, they are completely
 expanded before use.
 
 \section{Table of contents commands}
@@ -606,10 +585,17 @@ tables of contents, apart from
                                   \hangafter1 }
 \makeatother
 
+|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
+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
@@ -620,8 +606,7 @@ 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 (some
-|\edef|'s replaced by a bunch of |\expandafter|'s.)
+|2015/02/20 v1.4:  i. |some code efficiency improvements (perhaps...).
 
 |                 ii. |improved documentation.
 
@@ -649,19 +634,7 @@ document uses standard |\tableofcontents| or like commands.
 
 \endgroup
 
-\bigskip % pourquoi le faut-il?
-
-\section{Generating the package file and the test file}
-
-Running |latex| on |tableof.dtx| generates:
-{1})~the package file |tableof.sty| (which should be moved to a suitable
-location within the \TeX{} installation),
-{2})~|tableof.ins| for \TeX{} distributions expecting such a file,
-{3})~|tableoftest.tex| which demonstrates the package features (one should run
-|latex| twice on it), and
-{4})~the documentation itself. After running |latex| twice, use |dvipdfmx| to
-produce the pdf documentation.
-
+\bigskip
 
 \section{Implementation}
 
@@ -669,20 +642,28 @@ produce the pdf documentation.
 \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
+% % 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
@@ -724,7 +705,7 @@ produce the pdf documentation.
 % |1.3| codes this |\tof@readtoc| slightly better (copied from \etoc.dtx).
 %    \begin{macrocode}
 \def\tof@readtoc {%
-  \ifeof \tof@tf
+  \ifeof\tof@tf
   \else
      \read\tof@tf to \tof@buffer
      \tof@toctoks\expandafter\expandafter\expandafter
@@ -738,14 +719,33 @@ produce the pdf documentation.
 % 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}%
+        \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
@@ -767,6 +767,9 @@ produce the pdf documentation.
 % 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}%
@@ -775,8 +778,15 @@ produce the pdf documentation.
         \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}{}}
+        \global\let\string\tof@untagthis\string\@gobble}\relax}
     \addtocontents{toc}{\string\tof@begin}
+%    \end{macrocode}
+% \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.
+%    \begin{macrocode}
     \@ifpackageloaded{hyperref}
        {\def\tof@gobblethree@orfour#1#2#3#4{}%
         \ifx\hyper@last\@undefined\tof@toctoks{}\fi}
@@ -815,14 +825,19 @@ produce the pdf documentation.
 \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
-                    \tof@endgroup\global\let\tof@begin\relax
-                                 \global\let\tof@tags\@empty }
+                    \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@begingroup
         \tof@global\let\tof@tagthis  \tof@@tagthis
         \tof@global\let\tof@untagthis\tof@@untagthis
         \tof@global\let\tof@starttags\tof@@starttags
@@ -1000,7 +1015,7 @@ produce the pdf documentation.
   Grave accent  \`     Left brace    \{     Vertical bar  \|
   Right brace   \}     Tilde         \~}
 
-\CheckSum{557}
+\CheckSum{559}
 
 \Finale
 %%
-- 
cgit v1.2.3

