From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/tableof/README.md | 81 +++ macros/latex/contrib/tableof/tableof.dtx | 1008 ++++++++++++++++++++++++++++++ macros/latex/contrib/tableof/tableof.ins | 35 ++ macros/latex/contrib/tableof/tableof.pdf | Bin 0 -> 56333 bytes 4 files changed, 1124 insertions(+) create mode 100644 macros/latex/contrib/tableof/README.md create mode 100644 macros/latex/contrib/tableof/tableof.dtx create mode 100644 macros/latex/contrib/tableof/tableof.ins create mode 100644 macros/latex/contrib/tableof/tableof.pdf (limited to 'macros/latex/contrib/tableof') diff --git a/macros/latex/contrib/tableof/README.md b/macros/latex/contrib/tableof/README.md new file mode 100644 index 0000000000..16bf9ca2d3 --- /dev/null +++ b/macros/latex/contrib/tableof/README.md @@ -0,0 +1,81 @@ +Abstract +======== + +- Package: tableof (Tables of tagged contents) +- Version: 1.4b (2018/10/02) +- License: LPPL 1.3c +- Copyright (C) 2012-2018 Jean-Francois Burnol + +The commands `\toftagstart`, `\toftagstop`, `\toftagthis`, `\tofuntagthis` +are used to tag chapters, sections or any other sectioning units destined +to end up in the table(s) of contents. Then: + + \nexttocwithtags{req. 1, req. 2, ... }{excl. 1, excl. 2, ... } + \tableofcontents % or equivalent command + +specifies which tags are to be required and which ones are to be +excluded from the typeset TOC. + +For documents with classes where `\tableofcontents` is only single-use, +the package provides: + + \tableoftaggedcontents{req. 1, req. 2, ... }{excl. 1, excl. 2, ... } + +which does not have this restriction. + + +Installation +============ + +For extracting the style file: + + latex tableof.dtx + +Files `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 -> /tex/latex/tableof/ + +To produce the documentation: + + latex tableof.dtx (a second time) + dvipdfmx tableof.dvi + +`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. + + +Change History +============== + +* v1.4b (2018/10/02) fix to bug when a document ended with `\clearpage` + before the `\end{document}`. `tableof` now requires `atveryend` package. + +* v1.4a (2015/03/10) changes for enhanced compatibility with `etoc`. + +* v1.4 (2015/02/20) under the hood code improvements. + +* v1.3 (2015/02/11) comma separated lists of tags now allow spaces. + +* v1.2 (2013/03/04) added command `\tableoftaggedcontents`. + +* v1.1 (2012/12/13) added command `\nexttocwithtags`. + +* v1.0 (2012/12/06) first release. + + +License +======= + + This Work may be distributed and/or modified under the + conditions of the LaTeX Project Public License, + version 1.3c. This version of this license is in + + + + The Author of this Work is: + Jean-Francois Burnol + diff --git a/macros/latex/contrib/tableof/tableof.dtx b/macros/latex/contrib/tableof/tableof.dtx new file mode 100644 index 0000000000..34a881d1e8 --- /dev/null +++ b/macros/latex/contrib/tableof/tableof.dtx @@ -0,0 +1,1008 @@ +% -*- coding: iso-latin-1; -*- +%<*none> +{\def\doctimestamp {Time-stamp: <02-10-2018 11:43:43 CEST>}% + \def\getdtxtimestamp #1 <#2 #3 #4>{#2 at #3 #4}% + \xdef\tofdtxtimestamp {\expandafter\getdtxtimestamp\doctimestamp }}% +\def\docdate{2018/10/02} +% +%% +%% Package: tableof +%% Version: 1.4b (2018/10/02) +%% License: LPPL 1.3c +%% Copyright (C) 2012-2018 Jean-Francois Burnol +%% +% 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 +% 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 +% +% 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 -> /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> +\def\pkgname {tableof} +\def\pkgdate {2018/10/02} +\def\pkgversion {v1.4b} +\def\pkgdescription {Tables of tagged contents (JFB)} +% +%<*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 +\file{\pkgname test.tex}{\from{\pkgname.dtx}{test}} +\usepreamble\pkgpreamble +\file{\pkgname.sty}{\from{\pkgname.dtx}{package}}} +\endgroup +\iffalse +% +%<*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 -> /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 +%------------------------------------------------------------------------------- +% +%<*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 +%------------------------------------------------------------------------------- +% +%<*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} + \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} + +\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[pdfencoding=pdfdoc]{hyperref} + +\hypersetup{% +linktoc=all,% +breaklinks=true,% +hidelinks,% +pdfauthor={Jean-Fran\c cois Burnol},% +pdftitle={The tableof package},% +pdfsubject={LaTeX, table of contents},% +pdfkeywords={LaTeX, table of contents},% +pdfstartview=FitH,% +pdfpagemode=UseOutlines} + +\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}\\ + \textsc{Jean-François Burnol}\par + \footnotesize \ttfamily + jfbu (at) free (dot) fr\\ + Package version: \pkgversion\ (\pkgdate)\\ + Documentation generated from the source file\\ + with timestamp ``\tofdtxtimestamp'' +\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. +\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. +(\emph{new with release} |1.3|). 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 checks if |hyperref| is loaded as |hyperref| modifies the format of the +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 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 + +|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 (some +|\edef|'s replaced by a bunch of |\expandafter|'s.) + +| 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 % 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. + + +\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 + +\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\relax +% \def<*package>{\catcode`\<=12 \catcode`\>=12 \catcode`\*=12 \catcode`\/=12} +% +% +%<*package> +% \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} +\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. +% \begin{macrocode} +\AtBeginDocument{\IfFileExists{\jobname.toc} + {{\endlinechar\m@ne + \makeatletter + \newread\tof@tf + \openin\tof@tf\@filef@und + \tof@readtoc + \global\tof@toctoks=\expandafter{\the\tof@toctoks}% + \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. +% \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}{}} + \addtocontents{toc}{\string\tof@begin} + \@ifpackageloaded{hyperref} + {\def\tof@gobblethree@orfour#1#2#3#4{}% + \ifx\hyper@last\@undefined\tof@toctoks{}\fi} + {\def\tof@gobblethree@orfour#1#2#3{}}} +% \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 +\def\tof@@finish {\tof@global\let\contentsline\tof@savedcontentsline + \tof@endgroup\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}} +\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 + \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 +\CharacterTable + {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z + Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z + Digits \0\1\2\3\4\5\6\7\8\9 + Exclamation \! Double quote \" Hash (number) \# + Dollar \$ Percent \% Ampersand \& + Acute accent \' Left paren \( Right paren \) + Asterisk \* Plus \+ Comma \, + Minus \- Point \. Solidus \/ + Colon \: Semicolon \; Less than \< + Equals \= Greater than \> Question mark \? + Commercial at \@ Left bracket \[ Backslash \\ + Right bracket \] Circumflex \^ Underscore \_ + Grave accent \` Left brace \{ Vertical bar \| + Right brace \} Tilde \~} + +\CheckSum{557} + +\Finale +%% +%% End of file `tableof.dtx'. + diff --git a/macros/latex/contrib/tableof/tableof.ins b/macros/latex/contrib/tableof/tableof.ins new file mode 100644 index 0000000000..0b0f091b8d --- /dev/null +++ b/macros/latex/contrib/tableof/tableof.ins @@ -0,0 +1,35 @@ +%% +%% Package: tableof +%% Version: 1.4b (2018/10/02) +%% License: LPPL 1.3c +%% Copyright (C) 2012-2018 Jean-Francois Burnol +%% +\def\pkgname {tableof} +\def\pkgdate {2018/10/02} +\def\pkgversion {v1.4b} +\def\pkgdescription {Tables of tagged contents (JFB)} +%% 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 -> /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 +\endinput +%% +%% End of file `tableof.ins'. diff --git a/macros/latex/contrib/tableof/tableof.pdf b/macros/latex/contrib/tableof/tableof.pdf new file mode 100644 index 0000000000..fe26b7b124 Binary files /dev/null and b/macros/latex/contrib/tableof/tableof.pdf differ -- cgit v1.2.3