path: root/macros/latex/contrib/ms/multitoc.dtx

% \iffalse               
\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{multitoc}
%<package>        [1999/06/08 v2.01 MultiToc Package (MS)]
%
%<*driver>
\ProvidesFile{multitoc.drv}
      [1999/06/08 v2.01 Driver for MultiToc Package (MS)]
\documentclass{ltxdoc}
\usepackage{url}
\usepackage{ragged2e}
\usepackage[toc]{multitoc}
\GetFileInfo{multitoc.sty}
\setcounter{IndexColumns}{2}
\EnableCrossrefs
%%\DisableCrossrefs% Say \DisableCrossrefs if index is ready
\CodelineIndex    % Index code by line number
\OnlyDescription  % comment out for implementation details
%%\OldMakeIndex    % use if your MakeIndex is pre-v2.9
\setcounter{IndexColumns}{2}
\setlength{\IndexMin}{30ex}
\setlength{\premulticols}{\IndexMin}
\RaggedRight
\begin{document}
   \DocInput{multitoc.dtx}
\end{document}
%</driver>
%
% Copyright (c) [1998..1999] by Martin Schr\"oder.  All rights reserved.
%
% This program may be redistributed and/or modified under the terms
% of the LaTeX Project Public License, either version 1.0 of this
% license, or (at your option) any later version.
% The latest version of this license is in
%   CTAN:macros/latex/base/lppl.txt.
%
% Happy users are requested to send me a postcard. :-)
%
% For error reports in case of UNCHANGED versions see multitoc.ins
%
% \fi
%
% \CheckSum{83}
%
%% \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         \~}
%%
%% \iffalse meta-comment
%% ===================================================================
%%  @LaTeX-style-file{
%%     author          = {Martin Schr\"oder},
%%     version         = "2.01",
%%     date            = "8 June 1999",
%%     filename        = "multitoc.sty",
%%     address         = {Martin Schr\"oder
%%                        Cr\"usemannallee 3
%%                        D-28213 Bremen
%%     telephone       = "+49-421-2239425",
%%     email           = "Martin.Schroeder@ACM.org",
%%     pgp-Key         = "2048 bit / KeyID 292814E5",
%%     pgp-fingerprint = "7E86 6EC8 97FA 2995 82C3  FEA5 2719 090E",
%      checksum        = "62732 556 2216 19056",
%      codetable       = "ISO/ASCII",
%      keywords        = "LaTeX, multicol, toc, lof, lot",
%      dependences     = "multicol",
%      supported       = "yes",
%%     docstring       = "LaTeX package which automatically sets only 
%%                        the table of contents, list of figures and list
%%                        of tables in two or more columns.
%%                        The number of columns can be configured.
%%                        Uses the multicol package.
%
%                         The checksum field above contains a CRC-16
%                         checksum as the first value, followed by
%                         the equivalent of the standard UNIX wc
%                         (word count) utility output of lines,
%                         words, and characters.  This is produced
%                         by Robert Solovay's checksum utility."
%%  }
%% ===================================================================
%% \fi
%
%  \changes{v0.90}{1998/05/23}{New}
%  \changes{v1.00}{1998/08/09}{Documentation improved}
%  \changes{v2.00}{1998/08/23}{Redesign}
%  \changes{v2.01}{1999/06/08}{Moved to LPPL}
%
%  \newcommand*{\option}[1]{\textnormal{\sffamily#1}}
%  \newcommand*{\package}[1]{\textnormal{\sffamily#1}}
%  \newcommand*{\file}[1]{\textnormal{\texttt{.#1}}}
%  \newcommand*{\env}[1]{\textnormal{\texttt{#1}}}
%
%
% ^^A -----------------------------
%
%  \title{\unskip
%         The \textsf{multitoc} package^^A
%           \thanks{^^A
%              The version number of this file is \fileversion,
%              last revised \filedate.\protect\newline
%              The name \textsf{multitoc} is a tribute to the $8+3$ 
%              file-naming convention of certain ``operating 
%              systems''; strictly speaking it should be
%              \textsf{MulticolumnToc}.}
%        }
%  \author{Martin Schr\"oder\\[0.5ex]
%          \normalsize  Cr\"usemannallee 3\\
%          \normalsize  D-28213 Bremen\\
%          \normalsize  Martin.Schroeder@ACM.org\\
%          \scriptsize \texttt{PGP-Key: 2048 bit / KeyID 292814E5}\\[-0.5em]
%          \scriptsize \texttt{7E86 6EC8 97FA 2995~~82C3 FEA5 2719 090E}}
%  \date{\filedate}
%  \maketitle
%
% ^^A -----------------------------
%
%
%  \begin{abstract}
%     This package allows setting only the table of contents, list of 
%     figures and/or list of tables in two or more columns.
%     The number of columns can be configured via commands; the 
%     multicolumn toc(s) can be selected via package options.
%  \end{abstract}
%
%  \pagestyle{headings}
%
% ^^A -----------------------------
%
%  \tableofcontents
%
% ^^A -----------------------------
%
%  \section{Introduction}
%
%
% ^^A -----------------------------
%
%  \subsection{The problem\label{sec:sec:problem}}
%  ^^A
%  When you want to set only the table of contents of a document in two 
%  (or more columns), there is one known way^^A
%     \footnote{^^A
%        This was first used in the \package{doc} 
%        package\protect\cite{package:doc}.
%     }^^A
%  : Add an
%  \begin{quote}
%  |\addtocontents{toc}{\protect\begin{multicols}{2}}|
%  \end{quote}
%  before the \cs{tableofcontents} and an
%  \begin{quote}
%  |\addtocontents{toc}{\protect\end{multicols}}|
%  \end{quote}
%  at the end of the document.
%  This way your \file{toc} will start with |\begin{multicols}{2}|
%  and end with |\end{multicols}|.
%
%  This can be automised by using \cs{AtBeginDocument} and
%  \cs{AtEndDocument} but this has the drawback that it may
%  collide with other commands inserted using \cs{AtEndDocument} that
%  try to write information to the auxilary file (like the
%  \package{count1to} package\cite{package:count1to}).
%  This is because \TeX{} has two ways to write information to files 
%  \cite[p.\ 226--228]{KnuthTeXa}: immediately (when the \cs{write} is 
%  prefixed by \cs{immediate}) or deferred till the current page is 
%  finished and written out by \TeX{} (at the next \cs{shipout}).
%  \cs{addtocontents} does a deferred \cs{write}, \package{count1to}
%  does an immediate.
%
%  \begin{quote}
%     \small
%     Sidenote: \cs{addtocontents} writes a command to the \file{aux} file
%     to write its information to the \file{toc} file.
%     The \file{aux} is read in and executed by |\end{document}| and at
%     the next run by |\begin{document}|.
%     So the \file{toc} is written by |\end{document}| and at the
%     next run by |\begin{document}|.
%  \end{quote}
%
%  When you use the automised solution with \package{count1to} this may
%  happen:
%  \begin{enumerate}
%     \item The |\addtocontents{toc}{\protect\end{multicols}}| is inserted
%        using \cs{AtEndDocument} somewhere in the preamble.
%     \item \package{count1to} inserts this code
%        \begin{quote}
%        \hfuzz135pt
%        \small
%        |\clearpage|\\
%        |\immediate\write\@auxout{\string\newlabel{TotalPages}{{\the\count1}{\the\count1}}}|
%        \end{quote}
%        via an |\AtBeginDocument{\AtEndDocument{| so it can be sure that
%        this code is the \emph{last} code executed by \cs{AtEndDocument}.
%     \item At the |\end{document}| first the code from step~1 is executed
%        which adds the information to the current page to write the
%        |\@writefile{toc}{\end{multicols}}| to the auxilary file 
%        \emph{when the current page is finished}.
%
%        Then the code from step~2 is executed, which lets \LaTeX{} clear
%        the page (to force all pending writes to be written) and 
%        \emph{immediately} after that write the information for the 
%        |TotalPages| to the auxilary file.
%
%        Now suppose that the |\end{document}| is called \emph{just after}
%        \LaTeX{} has finished the last page.
%        The code from step~1 is never written to the file (since at the
%        \cs{clearpage} \LaTeX{} has no page to finish and so the code 
%        waits for the \cs{shipout} which won't come), but the code from 
%        step~2 is.
%        So you now have an \file{aux} which won't write the
%        |\end{multicols}| to the \file{toc}.
%        This of course produces an error at the next run.
%  \end{enumerate}
%
%
% ^^A -----------------------------
%
%  \subsection{A solution}
%  ^^A
%  \DescribeMacro{\@starttoc}
%  An easy way around this is to simply redefine \cs{@starttoc} from
%  \cite{package:ltsect} which reads in the \file{toc} to wrap a
%  \env{multicol} around it.\footnote{^^A
%     Thanks to Frank Mittelbach for reminding me of this.}^^A
%  $^{,}$^^A
%  \footnote{^^A
%     \raggedright
%     Version~1.00 of this package provided a more elaborate solution
%     to this using \cs{immediateaddtocontents}; this is no longer needed.
%     But the commands from version~1.00 are still provided (see
%     section~\ref{sec:sec:version100}).}
%
%
% ^^A -----------------------------
%
%  \section{Parameters}
%  ^^A
% \DescribeMacro{\multicolumntoc}
% \DescribeMacro{\multicolumnlot}
% \DescribeMacro{\multicolumnlof}
%  The number of columns for the table of contens, list of figures and
%  list of tables can be set by redefining the commands 
%  \cs{multicolumntoc}, \cs{multicolumnlot} and \cs{multicolumnlof}.
%  The default is two columns.
%
%
% ^^A -----------------------------
%
%  \section{Options}
%  ^^A
%  The package has the following options:
%  \nopagebreak
%  \begin{description}
%     \item[\normalfont\option{toc}]
%        The table of contents is set in \cs{multicolumntoc} columns.
%     \item[\normalfont\option{lof}]
%        The list of figures is set in \cs{multicolumnlof} columns.
%     \item[\normalfont\option{lot}]
%        The list of tables is set in \cs{multicolumnlot} columns.
%  \end{description}
%
%
% ^^A -----------------------------
%
%  \section{Required packages}
%  ^^A
%  The package requires the \package{multicol} and the 
%  \package{ifthen} packages.
%
%
% ^^A -----------------------------
%
%  \StopEventually{^^A
%
%
% ^^A -----------------------------
%
%  \begin{thebibliography}{1}
%     \raggedright
%     \bibitem{package:ltfiles}
%        Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport,
%        Frank Mittelbach, Chris Rowley and Rainer Sch\"opf.
%        \newblock \package{ltfiles.dtx}.
%        \newblock \texttt{CTAN: tex-archive/macros/latex/base/ltfiles.dtx}.
%        \newblock \LaTeXe{} kernel.
%     \bibitem{package:ltsect}
%        Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport,
%        Frank Mittelbach, Chris Rowley, Tobias Oetiker and Rainer Sch\"opf.
%        \newblock \package{ltsect.dtx}.
%        \newblock \url{CTAN: tex-archive/macros/latex/base/ltsect.dtx}.
%        \newblock \LaTeXe{} kernel.
%     \bibitem{KnuthTeXa}
%        Donald~E.\ Knuth.
%        \newblock \emph{The {\TeX}Book}, volume~A of \emph{Computers
%           and Typesetting}.
%        \newblock Addison-Wes\-ley, 1986.
%        \newblock Eleventh printing, revised, May 1991.
%     \bibitem{package:doc}
%        Frank Mittelbach.
%        \newblock The \package{doc} and \package{shortvrb} package.
%        \newblock \url{CTAN: tex-archive/macros/latex/base/doc.dtx}.
%        \newblock \LaTeXe{} package.
%     \bibitem{package:count1to}
%        Martin Schr\"oder.
%        \newblock The \package{count1to} package.
%        \newblock \url{CTAN: tex-archive/macros/latex/contrib/supported/ms/count1to.dtx}.
%        \newblock \LaTeXe{} package.
%  \end{thebibliography}
%
%     }
%
%
% ^^A -----------------------------
%
%  \section{The Implementation}
%  ^^A
%  \setlength{\parindent}{0pt}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%  We need the \package{multicol} and the \package{ifthen} packages.
%    \begin{macrocode}
\RequirePackage{multicol}
\RequirePackage{ifthen}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsection{The parameters}
%  ^^A
%  \begin{macro}{\multicolumntoc}
%  \begin{macro}{\multicolumnlot}
%  \begin{macro}{\multicolumnlof}
%  \mbox{}
%    \begin{macrocode}
\newcommand{\multicolumntoc}{2}
\newcommand{\multicolumnlot}{2}
\newcommand{\multicolumnlof}{2}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{Initial Code}
%  ^^A
%  \begin{macro}{@multitoc@toc}
%     \changes{v2.00}{1998/08/23}{new}
%  \cs{if@multitoc@toc} is used to flag the use of the \option{toc}
%  otion.
%    \begin{macrocode}
\newboolean{@multitoc@toc}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{@multitoc@lot}
%     \changes{v2.00}{1998/08/23}{new}
%  \cs{if@multitoc@lot} is used to flag the use of the \option{lot}
%  otion.
%    \begin{macrocode}
\newboolean{@multitoc@lot}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{@multitoc@lof}
%     \changes{v2.00}{1998/08/23}{new}
%  \cs{if@multitoc@lof} is used to flag the use of the \option{lof}
%  otion.
%    \begin{macrocode}
\newboolean{@multitoc@lof}
%    \end{macrocode}
%  \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{The options}
%  ^^A
%  The options simply set the corresponding flags.
%  \changes{v2.00}{1998/08/23}{Redesign}
%  \changes{v1.00}{1998/08/09}{\cs{clearpage}}
%    \begin{macrocode}
\DeclareOption{toc}{\setboolean{@multitoc@toc}{true}}
\DeclareOption{lot}{\setboolean{@multitoc@lot}{true}}
\DeclareOption{lof}{\setboolean{@multitoc@lof}{true}}
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsection{Executing options}
%  ^^A
%  There are no default options.
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
%
%
% ^^A -----------------------------
%
%  \subsection{Redefining \cs{@starttoc}}
%  ^^A
% \begin{macro}{\@starttoc}
%  From \cite{package:ltsect}:
%  \begin{quote}
% The |\@starttoc|\marg{ext} command is used to define the commands:\\
% |\tableofcontents|, |\listoffigures|, etc.
%
% For example:
% |\@starttoc{lof}| is used in |\listoffigures|.  This command
% reads the |.|\meta{ext} file and sets up to write the new
% |.|\meta{ext} file.
%
% \begin{oldcomments}
% \@starttoc{EXT} ==
%   BEGIN
%     \begingroup
%        \makeatletter
%        read file \jobname.EXT
%        IF @filesw = true
%          THEN  open \jobname.EXT as file \tf@EXT
%        FI
%        @nobreak :=G FALSE  %% added 24 May 89
%     \endgroup
%   END
% \end{oldcomments}
%  \end{quote}
%  We store the current definition in \cs{@multitoc@starttoc}
%  and wrap it in a \env{multicol} environment if the right 
%  option has been selected.
%  We also have to determine the number of columns to use.\footnote{^^A
%     This could probably be coded more effeciently, but this code
%     works\ldots}
%    \begin{macrocode}
\let\@multitoc@starttoc\@starttoc
\renewcommand*{\@starttoc}[1]{%
   \ifthenelse{\boolean{@multitoc@toc}\and\equal{#1}{toc}}{%
      \begin{multicols}{\multicolumntoc}%
         \@multitoc@starttoc{#1}%
      \end{multicols}%
      }{}%
   \ifthenelse{\boolean{@multitoc@lot}\and\equal{#1}{lot}}{%
      \begin{multicols}{\multicolumnlot}%
         \@multitoc@starttoc{#1}%
      \end{multicols}%
      }{}%
   \ifthenelse{\boolean{@multitoc@lof}\and\equal{#1}{lof}}{%
      \begin{multicols}{\multicolumnlof}%
         \@multitoc@starttoc{#1}%
      \end{multicols}%
      }{}%
   }
%    \end{macrocode}
% \end{macro}
%
%
% ^^A -----------------------------
%
%  \subsection{Code from Version~1.00\label{sec:sec:version100}}
%  ^^A
%  The first version of this package took a different approach to
%  solving the problem mentioned in section~\ref{sec:sec:problem} and
%  provided the commands \cs{protected@write@immediate} and 
%  \cs{immediateaddtocontents}.
%  Their code has been retained here for compatibilty reasons.
%
%  \DescribeMacro{\immediateaddtocontents}
%  \cs{immediateaddtocontents} is a version of \cs{addtocontents} which 
%  does just what the name implies: Write the information \cs{immediate}.
%
%  \begin{macro}{\protected@write@immediate}
%  This is a changed version of \cs{protected@write} 
%  from~\cite{package:ltfiles}.
%  It takes three arguments: an output stream, some initialization
%  code, and some text to write.
%  It then writes this \emph{immediately}, with
%  appropriate handling of |\protect| and |\thepage|.
%  \changes{v2.00}{1998/09/06}{retained}
%    \begin{macrocode}
\newcommand*{\protected@write@immediate}[3]{%
      \begingroup
       \let\thepage\relax
       #2%
       \let\protect\string
       \edef\reserved@a{\immediate\write#1{#3}}%
       \reserved@a
      \endgroup
      \if@nobreak\ifvmode\nobreak\fi\fi
   }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\immediateaddtocontents}
%  This is a changed version of \cs{addtocontents} 
%  from~\cite{package:ltsect}.
%  The |\immediateaddtocontents{|\meta{table}|}{|\meta{text}|}| command
%  \emph{immediately} adds \meta{text} to the |.|\meta{table} file, 
%  with no page number.
%  \changes{v2.00}{1998/09/06}{retained}
%    \begin{macrocode}
\newcommand*{\immediateaddtocontents}[2]{%
  \protected@write@immediate\@auxout
      {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
      {\string\@writefile{#1}{#2}}}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% ^^A -----------------------------
%
%  \Finale
%
%   \PrintIndex\PrintChanges
%   ^^A Make sure that the index is not printed twice
%   ^^A (ltxdoc.cfg might have a second \PrintIndex command)
%   \let\PrintChanges\relax
%   \let\PrintIndex\relax