path: root/Master/texmf-dist/source/latex/totcount/totcount.dtx

\def\totcfileversion{1.2}
\def\totcfiledate{2011/01/25}
\def\totcdocdate{25 Jan 2011}
% ^^A**********************************************************************
% \iffalse
\NeedsTeXFormat{LaTeX2e}
%<*drv>
%% \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         \~}
%%
%
\ProvidesFile{totcount.drv}
      [\totcfiledate \space v\totcfileversion \space Driver for the TotCount package]
\documentclass{ltxdoc}
\CheckSum{217}
\RequirePackage{hypdoc}
\RequirePackage{tocloft}
% use leader dots with section headers (by default, only the subsections had them
\renewcommand{\cftsecleader}{\cftdotfill{\cftdotsep}}
\RequirePackage[toc]{multitoc}
\RequirePackage{setspace}
\RequirePackage{totcount}
\EnableCrossrefs
\CodelineIndex
\setcounter{IndexColumns}{1}
\RecordChanges
%\OnlyDescription  % uncomment for hiding implementation details
\setlength\hfuzz{15pt} % dont make so many
\hbadness=7000         % over and under full \box warnings
\newcommand*{\CTAN}[1]{%
  \href{http://www.ctan.org/tex-archive/#1}{\nolinkurl{CTAN:#1}}}
\urldef\totcounturl\nolinkurl{CTAN:macros/latex/contrib/totcount/}
\def\CTANtotcount{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/totcount/}{\totcounturl}}
\newcommand*{\xpackage}[1]{\textsf{#1}}
\begin{document}
  \DocInput{totcount.dtx}
\end{document}
%</drv>
%
% ^^A**********************************************************************
%
% The TotCount package, version \totcfileversion, \totcfiledate 
%
% Copyright (c) [2009] Vasileios Koutavas (Vasileios.Koutavas@scss.tcd.ie)
%
% This program may be re-distributed and/or modified under the terms of the
% LaTeX Project Public License version 1.3c, or any later version.
% The latest version of this license is in
%   CTAN:/macros/latex/base/lppl.txt
%
% \fi
%
% \changes{v1.1}{2009/07/09}{Fixes bug that mistakenly sets the date of any
% document using totcount}
% \changes{v1.0}{2009/04/10}{First release}
%
% \MakeShortVerb{\|}
%
% \DoNotIndex{\@ifnextchar,\@mainaux,\csname,\newcommand}
% \DoNotIndex{\def,\else,\endcsname,\expandafter}
% \DoNotIndex{\fi,\gdef,\ifnum,\ifx,\immediate,\documentclass}
% \DoNotIndex{\newwrite,\number,\begin,\section,\tt}
% \DoNotIndex{\relax,\sp,\space,\string,\end,\let}
%
% \title{The \xpackage{totcount} package^^A
%              \thanks{Available at \CTANtotcount.}}
% \author{Vasileios Koutavas\\\normalsize\texttt{Vasileios.Koutavas@scss.tcd.ie}}
% \date{\totcdocdate}
%
% \maketitle
%
% \begin{abstract}
% This is the documentation for the \xpackage{totcount} package, a package for
% computing and displaying the last value assigned to counters inside
% a document.  With this package one may count the total number of elements
% (e.g. sections, pages, citations, etc.) in a \LaTeX\ document by simply using
% standard \LaTeX\ counters.
% \end{abstract}
%
% \addtolength{\columnsep}{15pt}
% \tableofcontents
% \addtolength{\columnsep}{-15pt}
%
% \newtotcounter{citnum}
% \def\oldbibitem{}
% \let\oldbibitem=\bibitem
% \def\bibitem{\stepcounter{citnum}\oldbibitem}
%
% \newtotcounter{citesnum}
% \def\oldcite{}
% \let\oldcite=\cite
% \def\cite{\stepcounter{citesnum}\oldcite}
%
% \section{Introduction}
%
% Referring to the total number of sections, pages, citations, list items, or
% anything else in a document can be difficult to achieve. The difficulty
% arises when the reference is \emph{before} the definition of all the elements
% that need to be counted. In this case, abandoning the manual way  requires
% the use of auxiliary files in much the same way that \LaTeX\ uses for
% references and citations.
%
% Special packages like \xpackage{totpages} \cite{totpages} and
% \xpackage{lastpage} \cite{lastpage} handle this issue for the total number of
% pages, but, to the best of my knowledge, there is no package that makes it
% easy to print the total number of arbitrary elements.
%
% The \xpackage{TotCount} package hopefully fills this gap. It enables the
% computation and display of the last number assigned to a counter inside a
% document (usually the maximum value of the counter).  The user just has to
% include the \xpackage{TotCount} package, and \emph{register} a counter as a
% ``total counter''. Then, getting the maximum value of that counter is as easy
% as calling the macro |\total|\marg{counter} at the desired place, and running
% \LaTeX\ twice.
%
% As an early example, the commands
%    \begin{macrocode}
%<*doc>
\regtotcounter{section}\total{section}
%</doc>
%    \end{macrocode}
% inform the reader that there are \regtotcounter{section}\total{section}
% sections in this document. With only slightly more work (since there is no
% convenient counter already defined) we can write that this document has
% \total{citnum} citations, which it mentions \total{citesnum} times:
%    \begin{macrocode}
%<*doc>
\newtotcounter{citnum}
\def\oldbibitem{} \let\oldbibitem=\bibitem
\def\bibitem{\stepcounter{citnum}\oldbibitem}
\total{citnum}

\newtotcounter{citesnum}
\def\oldcite{} \let\oldcite=\cite
\def\cite{\stepcounter{citesnum}\oldcite}
\total{citesnum}
%</doc>
%    \end{macrocode}
%
%
% \section{User Interface}
%
% \DescribeMacro{\regtotcounter}
% To display the maximum value of a counter we first need to \emph{register}
% that counter as a ``total counter''. We can do this by calling the macro
% |\regtotcounter|\marg{counter} on an existing counter. We can register a
% counter in the preamble or inside the document, but in any case before
% calling |\total| or |\totvalue| on that counter.
%
% This macro will use the main auxiliary file to get the total number of the
% counter at the second time we run \LaTeX\ on the document.
%
% To use a file other than the main auxiliary file we need to pass an option to
% the macro: |\regtotcounter[auxfile=|\meta{file}|]|\marg{counter}. This way
% the last value of \meta{counter} will be stored in \meta{file}. This macro
% will also input \meta{file} the second time that \LaTeX\ runs (and every time
% after that) to get the right total value of the counter.  The same auxiliary
% file can be used for many total counters and multiple auxiliary files can be
% used within the same document.
%
% \DescribeMacro{\newtotcounter}
% The macro |\newtotcounter| is a shorthand for creating a new counter and
% registering it as a total counter. Just like |\regtotcounter|, we can pass an
% |auxfile| option to this macro to make it use an alternative auxiliary file:
% |\newtotcounter[auxfile=|\meta{file}|]|\marg{counter}.
%
% \DescribeMacro{\total}
% To print the maximum value of \meta{counter} we can call the macro
% |\total|\marg{counter}. The first time \LaTeX\ runs on the document this
% macro will display the symbols ``$??$'' and output in the terminal the
% warning 
% \begin{verbatim}
% Package totcount Warning: Rerun to get correct total counts on input line X
% \end{verbatim}
% where |X| is the line the |\total| macro was used. The second time
% \LaTeX\ runs on the same document (and every time after that) the macro will
% display the total count of \meta{counter} recorded in the auxiliary file.
%
% \DescribeMacro{\totvalue}
% We can obtain the numeric total value of \meta{counter} (in contrast to
% printing it using |\total|) by calling the macro |\totvalue|\marg{counter}.
% This is useful, for example, when we want to test the total value of the
% counter (see example in Section~\ref{sec:example}). The first time that
% \LaTeX\ runs on a document, where the total counts are not computed yet, this
% command returns |-1|.
%
% \DescribeMacro{\usetotcountfile}
% Sometimes we might want to use the total counters of an auxiliary file
% without recomputing (and overriding) their value. This is especially useful
% when the total counters have been computed by running \LaTeX\ on a
% different document. In this case, instead of registering a total
% counter with one of the commands |\regtotcounter| and |\newtotcounter| we can
% simply use the auxiliary file that contains the values of the  desired total
% counters by calling the macro |\usetotcountfile|\marg{file}. This
% functionality is the main reason why total counters can be stored in
% alternative auxiliary files.
%
% \DescribeMacro{\newcounter}
% \DescribeMacro{\addtocounter}
% \DescribeMacro{\stepcounter}
% \DescribeMacro{\setcounter}
% \DescribeMacro{\value}
% Since this package uses regular \LaTeX\ counters, we can use all the usual
% commands to define, set, increment, and get the current (\emph{not the
% total}) value of counters. See The \LaTeX\ Companion \cite{latexcompanion}
% for an explanation of how to use \LaTeX\ counters, and
% Section~\ref{sec:example} for sample uses of these macros.
%
%
% \section{\label{sec:installation}Installation}
%
% To get the package file run
% \begin{verbatim}
%latex totcount.ins \end{verbatim}
% Then copy the |totcount.sty| file in a directory accessible by (pdf)\LaTeX\
% and re-hash the latex tree.
% 
% To compile the documentation run
% \begin{verbatim}
%pdflatex totcount.drv
%makeindex -s gind.ist totcount.idx
%makeindex -s gglo.ist -o totcount.gls totcount.glo
%pdflatex totcount.drv  \end{verbatim}
%
% To run the example do
% \begin{verbatim}
%pdflatex totcount-ex.tex
%pdflatex totcount-ex.tex  \end{verbatim}
%
%
% \section{Required Packages}
% The \xpackage{TotCount} package requires the \xpackage{keyval} package
% \cite{keyval}.
%
% ^^A**********************************************************************
%
% \StopEventually{}
%
% \section{Implementation}
%
% \setlength{\parindent}{0pt}
%
% This section contains the source code of |totcount.sty|.
%
%    \begin{macrocode}
%<*sty>
\ProvidesPackage{totcount}
  [\totcfiledate \space v\totcfileversion \space package for getting%
   the total value of LaTeX counters]
%    \end{macrocode}
%%
%%   Import of the \xpackage{keyval} package \cite{keyval}:
%    \begin{macrocode}
\RequirePackage{keyval}
%    \end{macrocode}
%%
%    \begin{macro}{\newtotcounter}
%%   Creates a new counter and registers it as a total counter. This is the
%%   top-level dispatch of the macro, depending on whether there is an optional
%%   argument or not.
%    \begin{macrocode}
\def\newtotcounter{%
  \@ifnextchar[\newtotcounter@newaux\newtotcounter@mainaux}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\newtotcounter@newaux}
%%   This is the version of the |\newtotcounter| macro that uses a separate
%%   auxiliary file. It first creates the counter (second argument) and then
%%   calls the macro |\regtotcounter|.
%    \begin{macrocode}
\def\newtotcounter@newaux[#1]#2{%
  \newcounter{#2}%
  \regtotcounter[#1]{#2}%
}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\newtotcounter@mainaux}
%%   This is the version of the |\newtotcounter| macro that uses the main
%%   auxiliary file.  It first creates the counter (argument) and then calls
%%   the macro |\regtotcounter|.
%    \begin{macrocode}
\def\newtotcounter@mainaux#1{%
  \newcounter{#1}%
%    \end{macrocode}
%% Register the counter:
%    \begin{macrocode}
  \regtotcounter{#1}%
}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\regtotcounter}
%%   Registers a counter as a total counter. This is the top-level dispatch of
%%   the macro, depending on whether there is an optional argument or not.
%    \begin{macrocode}
\def\regtotcounter{%
  \@ifnextchar[\regtotcounter@newaux\regtotcounter@mainaux}
%    \end{macrocode}
%    \end{macro}
%%
%%   The following is the definition of the |auxfile| key for specifying an
%%   alternative auxiliary file when calling the macro |\regtotcounter| (see
%%   \cite{keyval}).
%    \begin{macrocode}
\define@key{totcounter}{auxfile}{\def\this@auxfile{#1}}
%    \end{macrocode}
%%
%    \begin{macro}{\regtotcounter@newaux}
%%   This is the version of the |\regtotcounter| macro that uses a separate
%%   auxiliary file. The auxiliary file is passed as a first argument in the
%%   form of a key--value pair |[auxfile=|\meta{file}|]|, and the counter to be
%%   registered is passed as the second argument.
%%   \begin{macrocode}
\def\regtotcounter@newaux[#1]#2{%
  \setkeys{totcounter}{#1}%
%    \end{macrocode}
%% Try to load the contents of the file:
%    \begin{macrocode}
  \InputIfFileExists{\this@auxfile}{}{}%
%    \end{macrocode}
%% Make sure that the auxiliary file is open; \LaTeX\ will close it at the end:
%    \begin{macrocode}
  \expandafter\ifx\csname \this@auxfile @open\endcsname\relax%
    \expandafter\gdef\csname \this@auxfile @open\endcsname{}%
    \expandafter\newwrite\csname \this@auxfile @stream\endcsname%
    \immediate\expandafter\openout%
      \csname \this@auxfile @stream\endcsname=\this@auxfile%
  \fi%
%    \end{macrocode}
%% Create a new counter holding the total number of the actual counter:
%    \begin{macrocode}
  \expandafter\ifx\csname c@#2@totc\endcsname\relax%
      \newcounter{#2@totc}%
      \setcounter{#2@totc}{-1}%
  \fi%
%    \end{macrocode}
%% At the end of the document write code in the auxiliary file to update the
%% total counter with the value of the actual counter:
%    \begin{macrocode}
  \AtEndDocument{%
     \def\sp{ }%
     \immediate\expandafter\write%
     \csname \this@auxfile @stream\endcsname{%
       \string\expandafter\string\ifx%
         \string\csname\sp c@#2@totc\string\endcsname\string\relax%
       \string\newcounter{#2@totc}%
       \string\fi%
       \string\setcounter{#2@totc}{\number\value{#2}}%
     }%
  }%
}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\regtotcounter@mainaux}
%%   This is the version of the |\regtotcounter| macro that uses the main
%%   auxiliary file. The counter to be registered is passed as the second
%%   argument.
%    \begin{macrocode}
\def\regtotcounter@mainaux#1{%
%    \end{macrocode}
%% Create a new counter holding the total number of the actual counter:
%    \begin{macrocode}
  \expandafter\ifx\csname c@#1@totc\endcsname\relax%
      \newcounter{#1@totc}%
      \setcounter{#1@totc}{-1}%
  \fi%
%    \end{macrocode}
%% At the end of the document write code in the auxiliary file to update the
%% total counter with the value of the actual counter:
%    \begin{macrocode}
  \AtEndDocument{%
    \def\sp{ }%
    \immediate\write\@mainaux{%
      \string\expandafter\string\ifx%
        \string\csname\sp c@#1@totc\string\endcsname\string\relax%
      \string\newcounter{\string #1@totc}%
      \string\fi%
      \string\setcounter{\string #1@totc}{\number\value{#1}}%
    }%
  }%
}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\total}
%%   Prints the total value of a registered total counter that is passed as
%%   argument. If the total value is yet to be computed (at the first time
%%   \LaTeX\ runs on the document) then its value is |-1| and the output of the
%%   command is $??$.
%          \changes{v1.2}{2011/01/25}{Warnings are now reported using the
%          PackageWarning command, which improves interoperability with editing
%          environments such as LyX}
%    \begin{macrocode}
\newcommand\total[1]{%
  \def\tmp@val{\value{#1@totc}}%
  \ifnum\tmp@val=-1%
    \PackageWarning{totcount}{Rerun to get correct total counts}%
    $??$%
  \else%
    \number\value{#1@totc}%
  \fi%
}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\totvalue}
%%   Returns the numeric total value of a registered total counter that is
%%   passed as argument. Note that if the counter's value is not yet computed
%%   (at the first time \LaTeX\ runs on the document) this macro returns |-1|.
%    \begin{macrocode}
\newcommand\totvalue[1]{\value{#1@totc}}
%    \end{macrocode}
%    \end{macro}
%%
%    \begin{macro}{\usetotcountfile}
%%   Inputs an auxiliary file that should contain total-counter
%%   definitions. It outputs a warning message in the terminal if the file
%%   doesn't exist. This command should be used \emph{instead} of registering a
%%   counter.
%    \begin{macrocode}
\newcommand\usetotcountfile[1]{%
  \InputIfFileExists{#1}{%
    \message{TotCount inputs file '#1'}%
  }{%
    \PackageWarning{totcount}{File '#1' does not exist!}%
    \message{\space\space\space\space\space\space\space\space\space%
             \space\space\space\space\space\space\space\space\space%
             Ignoring \string\usetotcountfile{#1}.}%
  }%
}
%</sty>
%    \end{macrocode}
%    \end{macro}
%
% ^^A**********************************************************************
%
% \section{\label{sec:example}Simple Example}
%
% The following is a simple example of how to use the functionality of the
% \xpackage{TotCount} package. This example can be found in the file
% |totcount-ex.tex|, after running \LaTeX\ on the |totcount.ins| file (see
% Section~\ref{sec:installation}).
%
%    \begin{macrocode}
%<*ex>
\ProvidesFile{totcount-ex.tex}
      [\totcfiledate \space v\totcfileversion \space%
       test file for the TotCount package]
\documentclass{article}
%    \end{macrocode}
%%
%% Import the package
%    \begin{macrocode}
\RequirePackage{totcount}
%    \end{macrocode}
%%
%%  Comment out the following line to use the previously stored total counts in
%%  'mycount.aux' (make sure it exists!) instead of computing them again:
%    \begin{macrocode}
\def\computemycount{} 
\expandafter\ifx\csname computemycount\endcsname\relax
  \usetotcountfile{mycount.aux}
  \newcounter{mycount} % so that increments of this counter don't break
\else
  \newtotcounter[auxfile=mycount.aux]{mycount}
\fi
%    \end{macrocode}
%%
%% Register the section and page counters as a total counters:
%    \begin{macrocode}
\regtotcounter{section}
\regtotcounter{page}

\begin{document}
%    \end{macrocode}
%%
%% A total counter can be declared/registered anywhere:
%    \begin{macrocode}
\newtotcounter{yourcount}

\section{Total Counts}
%    \end{macrocode}
%%
%% Increment counters as usual:
%    \begin{macrocode}
\addtocounter{mycount}{5}
\addtocounter{yourcount}{5}
%    \end{macrocode}
%%
%% Print the value of a total counter by using |\total|:
%    \begin{macrocode}
The total value of the counter {\tt mycount} is \total{mycount} (should
be 10), and the total value of the counter {\tt yourcount} is
\total{yourcount} (should be 17).

%    \end{macrocode}
%%
%% Get the numeric value of a total counter by using |\totvalue|:
%    \begin{macrocode}
This document has \total{section}
\ifnum\totvalue{section}=1 section \else sections \fi
and \total{page}
\ifnum\totvalue{page}=1 page. \else pages. \fi

%    \end{macrocode}
%%
%% The effect of incrementing the counters will be visible the second
%% time LaTeX runs:
%    \begin{macrocode}
\addtocounter{yourcount}{5}
\addtocounter{mycount}{5}
\addtocounter{yourcount}{7}

\section{A Section}
\section{Another Section}
\section{Yet Another Section}

\end{document}
%</ex>
%    \end{macrocode}
%
% ^^A**********************************************************************
%
% \section{Acknowledgments}
%
% Many thanks to Christoforos Moutafis for pointing me to the right direction
% when I first started looking for a way to display the maximum value of
% counters. Thanks also to everyone who submitted bug reports.
%
% \begin{thebibliography}{H\,1}
%   \raggedright
%     \bibitem[1]{keyval}
%        David Carlisle,
%        \newblock \emph{The \xpackage{keyval} package},
%        \newblock \LaTeXe{} package.
%        \newblock \CTAN{macros/latex/required/graphics/keyval.dtx}
%     \bibitem[2]{lastpage}
%        Jeff Goldberg,
%        \newblock \emph{The \xpackage{lastpage} package},
%        \newblock \LaTeXe{} package.
%        \newblock \CTAN{macros/latex/contrib/lastpage/}
%     \bibitem[3]{latexcompanion}
%        Michel Goossens, Frank Mittelbach and Alexander Samarin,
%        \newblock \emph{The \LaTeX\ Companion}, 
%        \newblock Addison-Wesley, 1994.
%     \bibitem[4]{totpages} 
%        Wilhelm M\"uller,
%        \newblock \emph{The \xpackage{totpages} package},
%        \newblock \LaTeXe{} package.
%        \newblock \CTAN{macros/latex/contrib/totpages/}
% \end{thebibliography}
%
%  \Finale
%  \PrintIndex \PrintChanges
\endinput