% -*- coding: iso-latin-1; -*- %<*ins> \def\lasttimestamp{Time-stamp: <06-12-2012 22:11:56 CET jfb>} \def\pkgname{tableof} \def\pkgdate{2012/12/06} \def\pkgversion{v1.0} \def\pkgdescription{tables of tagged contents (jfB)} % %% %% Package `tableof' by Jean-Francois Burnol %% Copyright (C) 2012 by Jean-Francois Burnol %% %<*none> \def\docdate{2012/12/06} \def\striptimestamp#1 <#2 #3 #4 #5>{#2 at #3 #4} \edef\dtxtimestamp{\expandafter\striptimestamp\lasttimestamp} \ProvidesFile{\pkgname.dtx} [`\pkgname' source and documentation (\dtxtimestamp)] % % The copyright at the top of this file applies to `tableof.dtx' % and to its derived files. % % They may be distributed and/or modified under the % conditions of the LaTeX Project Public License, % either version 1.3 of this license or (at your % option) any later version. The latest version of % this license is in: % % http://www.latex-project.org/lppl.txt % % and version 1.3 or later is part of all distributions of % LaTeX version 2003/12/01 or later. % % Installation: % ============ % % `latex tableof.dtx' or `pdflatex tableof.dtx' % Run twice to get the bookmarks right. % % `tableof.sty', `tableof.ins' and `tableoftest.tex' are generated on % the first latex run. % % Put `tableof.sty' at a suitable location within the TeX installation: % tableof.sty -> ..path..to../tex/latex/tableof/ % % `tableof.ins' is for TeX distributions expecting it. % % `tableoftest.tex' is an example of use of the package commands. Run % latex twice on it to get the tagged tables of contents. % \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 `latex tableof.ins' produces `tableof.sty' from the source %% `tableof.dtx' %% %% (an already existing `tableof.sty' in the same repertory will be %% overwritten) %% %% Put `tableof.sty' in a suitable location within the TeX installation: %% tableof.sty -> ................/tex/latex/tableof/ %% %% The generated auxiliary files may be discarded. %% %% See `tableof.dtx' for the statements of copyright and conditions of %% distribution or modification. %% \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 package `tableof'. %% %% (run on it `latex' or `pdflatex' twice.) %% \documentclass{article} \usepackage[colorlinks,linkcolor=blue]{hyperref} \usepackage{tableof} \begin{document} \tofOpenTocFileForWrite \section*{with (and)} \tableof{} \section*{with (or)} \tableof*{} \section*{with A (and)} \tableof{A} \section*{with A (or)} \tableof*{A} \section*{with A and with C} \tableof{A,C} \section*{with B or with C} \tableof*{B,C} \section*{with A and with B and with C} \tableof{A,B,C} \section*{with A or with B or with C} \tableof*{A,B,C} \section*{without B (and)} \tablenotof{B} \section*{without A and without B} \tablenotof{A,B} \section*{without 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} \tableof{ecology} \section*{Rabbits} \tableof{rabbits} \section*{Kitchenware} \tableof{kitchenware} \clearpage \section{no tag} nothing \begin{verbatim} \toftagstart{D,E} \toftagthis{A} \end{verbatim} \toftagstart{D,E} \toftagthis{A} \section{A,D,E} A,D,E \begin{verbatim} \toftagthis{B} \end{verbatim} \toftagthis{B} \section{B,D,E} B,D,E \begin{verbatim} \toftagthis{C} \end{verbatim} \toftagthis{C} \section{C,D,E} C,D,E \begin{verbatim} \toftagstop{E,F} \toftagthis{A,B} \end{verbatim} \toftagstop{E,F} \toftagthis{A,B} \section{A,B,D} A,B,D \begin{verbatim} \toftagthis{B,C} \end{verbatim} \toftagthis{B,C} \section{B,C,D} B,C,D \begin{verbatim} \toftagthis{A,C} \end{verbatim} \toftagthis{A,C} \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} \toftagstart{kitchenware,rabbits} \end{verbatim} \toftagstop{A,B,C,D,E} \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 \documentclass[a4paper,11pt,abstract]{scrdoc} \pagestyle{headings} \usepackage[latin1]{inputenc} \usepackage[T1]{fontenc} \usepackage{geometry} \usepackage{verbatim} \usepackage{txfonts} \usepackage{xspace} \usepackage{color} \definecolor{joli}{RGB}{225,95,0} \definecolor{JOLI}{RGB}{225,95,0} \definecolor{BLUE}{RGB}{0,0,255} \usepackage[english]{babel} \usepackage[%dvipdfmx,% pdfencoding=pdfdoc,bookmarks=true]{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} \MakeShortVerb{\|} \DeclareRobustCommand\cs[1]{{\ttfamily\hyphenchar\font45\char`\\#1}} \DeclareRobustCommand\csb[1]{{% \color{blue}\ttfamily\hyphenchar\font45\char`\\#1}} \newcommand\cshyp[1]{\texorpdfstring{\cs{#1}}{\textbackslash #1}} \newcommand\csbhyp[1]{\texorpdfstring{\csb{#1}}{\textbackslash #1}} \newcommand\lowast{\raisebox{-.25\height}{*}} \newcommand\starit[1]{\cs{#1\lowast}} \newcommand\staritb[1]{\csb{#1\lowast}} \newcommand\tof{\cs{tableof}\xspace} \newcommand\tnotof{\cs{tablenotof}\xspace} \newcommand\tofb{\csb{tableof}\xspace} \newcommand\tnotofb{\csb{tablenotof}\xspace} \newcommand\tableof{% \texorpdfstring{{\color{joli}\ttfamily\bfseries tableof}} {tableof}\xspace} \frenchspacing \renewcommand\familydefault\sfdefault \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 ``\dtxtimestamp'' \end{center} \begin{abstract} The \tableof package allows to tag the table of contents entries. The \csb{tableof}\{{\color{blue}\emph{comma,separated,list,of,tags}}\} command displays a table of contents containing only the entries having all the listed tags. There is a complementary command \csb{tablenotof}. They may be used multiple times. \end{abstract} \section{Commands} \subsection{\csbhyp{toftagstart} and \csbhyp{toftagstop}} These commands have a mandatory argument which is a comma separated list of tags. The tags need not have been predeclared. \begin{verbatim} \toftagstart{kitchenware,weaponry,gastronomy} \section{Dealing with knives} \subsection{This is tagged, too} \section{Hunting rabbits} \toftagstop{weaponry} \section{Eating rabbits} \end{verbatim} \subsection{\csbhyp{toftagthis} and \csbhyp{tofuntagthis}} The \cs{toftagthis} command tags with the values from its argument (a comma separated list) only the next object found in the |.toc| file. The command should be located \emph{before} and not \emph{after} the to-be-tagged TOC entry. The \cs{tofuntagthis} command untags the next entry. \begin{verbatim} \toftagstart{kitchenware,rabbits} \section{Knives and rabbits} \tofuntagthis{kitchenware} \subsection{Hunting rabbits} \subsection{Best knives for cooking} \subsection{Eating rabbits} \toftagstart{ecology} \toftagthis{climate} \section{Knives and global climate} \toftagstop{kitchenware} \section{The rabbit in the wild} \toftagthis{climate} \subsection{Impact of the rabbit on global climate} \end{verbatim} \subsection{\csbhyp{tableof}} This command has a mandatory argument which is a comma separated list of tags. It displays, exactly as would appear in the table of contents, the corresponding tagged entries from the |.toc| file. Its title needs to be explicitely set up by additional code. \begin{verbatim} \section*{Table of entries tagged with weaponry AND with hunting} \tableof{weaponry,hunting} \end{verbatim} There is a starred variant: \begin{verbatim} \section*{Table of entries tagged with weaponry OR with hunting} \tableof*{weaponry,hunting} \end{verbatim} \subsection{\csbhyp{tablenotof}} It has a mandatory argument which is a comma separated list of tags. It displays, exactly as would appear in the table of contents, the entries from the |.toc| file which are \emph{not} tagged: \begin{verbatim} \section*{Table of entries NOT tagged with weaponry NEITHER with hunting} \tablenotof{weaponry,hunting} \end{verbatim} There is a starred variant: \begin{verbatim} \section*{Table of entries NOT tagged with weaponry OR NOT tagged with hunting} \tablenotof*{weaponry,hunting} \end{verbatim} \subsection{\csbhyp{tofOpenTocFileForWrite}} The |.toc| file is read into memory (if it exists) by \tableof at the \cs{usepackage}. But the creation of the |.toc| file is not dealt with by \tableof itself: either this will be done by a standard \cs{tableofcontents} command somewhere in the document, or, one may use the package provided command \cs{tofOpenTocFileForWrite} which does not display anything and just does what its name indicates. This command can be used also in the preamble.\footnote{Note to people or packages wanting also to access the |.toc| file: as happens with the standard \cs{tableofcontents}, the |.toc| file becomes temporarily empty immediately after \cs{tofOpenTocFileForWrite}.} \subsection{Compatibility with other packages} \tableof checks if the package |hyperref| is loaded as it modifies the format of the |.toc| file lines. This check is done at the \cs{begin}|{document}| so the order of loading is not important. \tableof adds the tag data to the |.toc| file, but this data is defined to do nothing except when it is used by \tableof itself. \subsection{TODO} Create a parser for arbitrary iterated boolean combinations of tags . . . but this kind of thing must have been done a zillion times already, as it belongs to the basics in computer science! . . . and it surely is no easy task in \TeX{}! so I cautiously retreated from such an endeavor. \section{Generating the package file and the test file} Running |latex| (or |pdflatex|) 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 (run |pdflatex| twice to get the bookmarks.) \section{Implementation} \makeatletter \StopEventually{\check@checksum\end{document}} \makeatother Writing-up source code comments is hopefully for a future release. % I don't want to have to type at this location (far from the top of the file) % explicitly the package version or version date, as it is inconvenient to have % to remember to do this when updating the package. Also, I prefer not to add % macros to the |.sty| file macros with the package date, name, or version. So I % cut out the following from the real macrocode environment (leaving out the % \init@crossref.) \makeatletter \begingroup \topsep\MacrocodeTopsep \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} \DeclareOption*{\PackageWarning{tableof}{Option `\CurrentOption' is unknown.}} \ProcessOptions\relax % \end{macrocode} % \begin{macrocode} \newtoks\tof@toctoks % \end{macrocode} % \begin{macrocode} \def\tof@readtoc#1{% \ifeof #1 \let\tof@nextread\@gobble \global\tof@toctoks=\expandafter{\the\tof@toctoks}% \else \let\tof@nextread\tof@readtoc \read #1 to \tof@buffer \tof@toctoks=\expandafter\expandafter\expandafter {\expandafter\the\expandafter\tof@toctoks\tof@buffer}% \fi \tof@nextread{#1}} % \end{macrocode} % \begin{macrocode} \IfFileExists{\jobname .toc} {{\endlinechar=-1 \makeatletter \newread\tof@tf \openin\tof@tf\@filef@und \tof@readtoc\tof@tf \closein\tof@tf}}{} % \end{macrocode} % \begin{macrocode} \AtBeginDocument{ \@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} % \begin{macrocode} \def\tof@tags{} \def\tof@tags@tmp{} \def\tof@untags@tmp{} \def\tof@true#1{\expandafter\let\csname if@tof#1.\endcsname\iftrue} \def\tof@false#1{\expandafter\let\csname if@tof#1.\endcsname\iffalse} \def\tof@secondiftrue#1{\csname if@tof#1.\endcsname \let\tof@next\@secondoftwo\fi} \def\tof@secondiffalse#1{\csname if@tof#1.\endcsname\else \let\tof@next\@secondoftwo\fi} \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}}% \def\tof@tags@tmp{}\def\tof@untags@tmp{}} % \end{macrocode} % \begin{macrocode} \def\tof@and#1{% \def\contentsline{% \tof@setflags{#1}% \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}% \tof@next\tof@savedcontentsline\tof@gobblethree@orfour} \the\tof@toctoks \endgroup} % \end{macrocode} % \begin{macrocode} \def\tof@or#1{% \def\contentsline{% \tof@setflags{#1}% \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}% \tof@next\tof@gobblethree@orfour\tof@savedcontentsline} \the\tof@toctoks \endgroup} % \end{macrocode} % \begin{macrocode} \def\tof@nor#1{% \def\contentsline{% \tof@setflags{#1}% \@for\@tempa:=#1\do{\tof@secondiffalse{\@tempa}}% \tof@next\tof@savedcontentsline\tof@gobblethree@orfour} \the\tof@toctoks \endgroup} % \end{macrocode} % \begin{macrocode} \def\tof@nand#1{% \def\contentsline{% \tof@setflags{#1}% \@for\@tempa:=#1\do{\tof@secondiftrue{\@tempa}}% \tof@next\tof@gobblethree@orfour\tof@savedcontentsline} \the\tof@toctoks \endgroup} % \end{macrocode} % \begin{macrocode} \def\tof@filter#1#2{\ifx#1#2\else \ifx\tof@tmptags\@empty\edef\tof@tmptags{#2}\else \edef\tof@tmptags{\tof@tmptags,#2}\fi\fi} \def\tof@@start#1{% \ifx\tof@tags\@empty\edef\tof@tags{#1}\else \edef\tof@tags{\tof@tags,#1}\fi} \def\tof@@stop#1{% \@for\@tempa:=#1\do{\def\tof@tmptags{}% \@for\@tempb:=\tof@tags\do{\tof@filter\@tempa\@tempb}% \edef\tof@tags{\tof@tmptags}}} % \end{macrocode} % \begin{macrocode} \let\tof@start\@gobble \let\tof@stop\@gobble \let\tof@tagthis\@gobble \let\tof@untagthis\@gobble \def\tof@init{\begingroup \let\tof@savedcontentsline\contentsline \let\tof@start\tof@@start \let\tof@stop\tof@@stop \def\tof@tagthis##1{\def\tof@tags@tmp{##1}}% \def\tof@untagthis##1{\def\tof@untags@tmp{##1}}} \newcommand\tableof{\tof@init\@ifstar{\tof@or}{\tof@and}} \newcommand\tablenotof{\tof@init\@ifstar{\tof@nand}{\tof@nor}} % \end{macrocode} % \begin{macrocode} \newcommand*\toftagthis[1]{\addtocontents{toc} {\string\tof@tagthis\string{#1\string}}} \newcommand*\tofuntagthis[1]{\addtocontents{toc} {\string\tof@untagthis\string{#1\string}}} \newcommand*\toftagstart[1]{\addtocontents{toc} {\string\tof@start\string{#1\string}}} \newcommand*\toftagstop[1]{\addtocontents{toc} {\string\tof@stop\string{#1\string}}} \newcommand\tofOpenTocFileForWrite{% \expandafter\newwrite \csname tf@toc\endcsname \immediate \openout \csname tf@toc\endcsname \jobname .toc\relax} \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{322} \Finale %% %% End of file `tableof.dtx'.