Debian Codegraph @

texmf-dist/source/latex/totcount/totcount.dtx

raw
1 \def\totcfileversion{1.2}
2 \def\totcfiledate{2011/01/25}
3 \def\totcdocdate{25 Jan 2011}
4 % ^^A**********************************************************************
5 % \iffalse
6 \NeedsTeXFormat{LaTeX2e}
7 %<*drv>
8 %% \CharacterTable
9 %% {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
10 %% 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
11 %% Digits \0\1\2\3\4\5\6\7\8\9
12 %% Exclamation \! Double quote \" Hash (number) \#
13 %% Dollar \$ Percent \% Ampersand \&
14 %% Acute accent \' Left paren \( Right paren \)
15 %% Asterisk \* Plus \+ Comma \,
16 %% Minus \- Point \. Solidus \/
17 %% Colon \: Semicolon \; Less than \<
18 %% Equals \= Greater than \> Question mark \?
19 %% Commercial at \@ Left bracket \[ Backslash \\
20 %% Right bracket \] Circumflex \^ Underscore \_
21 %% Grave accent \` Left brace \{ Vertical bar \|
22 %% Right brace \} Tilde \~}
23 %%
24 %
25 \ProvidesFile{totcount.drv}
26 [\totcfiledate \space v\totcfileversion \space Driver for the TotCount package]
27 \documentclass{ltxdoc}
28 \CheckSum{217}
29 \RequirePackage{hypdoc}
30 \RequirePackage{tocloft}
31 % use leader dots with section headers (by default, only the subsections had them
32 \renewcommand{\cftsecleader}{\cftdotfill{\cftdotsep}}
33 \RequirePackage[toc]{multitoc}
34 \RequirePackage{setspace}
35 \RequirePackage{totcount}
36 \EnableCrossrefs
37 \CodelineIndex
38 \setcounter{IndexColumns}{1}
39 \RecordChanges
40 %\OnlyDescription % uncomment for hiding implementation details
41 \setlength\hfuzz{15pt} % dont make so many
42 \hbadness=7000 % over and under full \box warnings
43 \newcommand*{\CTAN}[1]{%
44 \href{http://www.ctan.org/tex-archive/#1}{\nolinkurl{CTAN:#1}}}
45 \urldef\totcounturl\nolinkurl{CTAN:macros/latex/contrib/totcount/}
46 \def\CTANtotcount{\href{http://www.ctan.org/tex-archive/macros/latex/contrib/totcount/}{\totcounturl}}
47 \newcommand*{\xpackage}[1]{\textsf{#1}}
48 \begin{document}
49 \DocInput{totcount.dtx}
50 \end{document}
51 %</drv>
52 %
53 % ^^A**********************************************************************
54 %
55 % The TotCount package, version \totcfileversion, \totcfiledate
56 %
57 % Copyright (c) [2009] Vasileios Koutavas ([email protected])
58 %
59 % This program may be re-distributed and/or modified under the terms of the
60 % LaTeX Project Public License version 1.3c, or any later version.
61 % The latest version of this license is in
62 % CTAN:/macros/latex/base/lppl.txt
63 %
64 % \fi
65 %
66 % \changes{v1.1}{2009/07/09}{Fixes bug that mistakenly sets the date of any
67 % document using totcount}
68 % \changes{v1.0}{2009/04/10}{First release}
69 %
70 % \MakeShortVerb{\|}
71 %
72 % \DoNotIndex{\@ifnextchar,\@mainaux,\csname,\newcommand}
73 % \DoNotIndex{\def,\else,\endcsname,\expandafter}
74 % \DoNotIndex{\fi,\gdef,\ifnum,\ifx,\immediate,\documentclass}
75 % \DoNotIndex{\newwrite,\number,\begin,\section,\tt}
76 % \DoNotIndex{\relax,\sp,\space,\string,\end,\let}
77 %
78 % \title{The \xpackage{totcount} package^^A
79 % \thanks{Available at \CTANtotcount.}}
80 % \author{Vasileios Koutavas\\\normalsize\texttt{[email protected]}}
81 % \date{\totcdocdate}
82 %
83 % \maketitle
84 %
85 % \begin{abstract}
86 % This is the documentation for the \xpackage{totcount} package, a package for
87 % computing and displaying the last value assigned to counters inside
88 % a document. With this package one may count the total number of elements
89 % (e.g. sections, pages, citations, etc.) in a \LaTeX\ document by simply using
90 % standard \LaTeX\ counters.
91 % \end{abstract}
92 %
93 % \addtolength{\columnsep}{15pt}
94 % \tableofcontents
95 % \addtolength{\columnsep}{-15pt}
96 %
97 % \newtotcounter{citnum}
98 % \def\oldbibitem{}
99 % \let\oldbibitem=\bibitem
100 % \def\bibitem{\stepcounter{citnum}\oldbibitem}
101 %
102 % \newtotcounter{citesnum}
103 % \def\oldcite{}
104 % \let\oldcite=\cite
105 % \def\cite{\stepcounter{citesnum}\oldcite}
106 %
107 % \section{Introduction}
108 %
109 % Referring to the total number of sections, pages, citations, list items, or
110 % anything else in a document can be difficult to achieve. The difficulty
111 % arises when the reference is \emph{before} the definition of all the elements
112 % that need to be counted. In this case, abandoning the manual way requires
113 % the use of auxiliary files in much the same way that \LaTeX\ uses for
114 % references and citations.
115 %
116 % Special packages like \xpackage{totpages} \cite{totpages} and
117 % \xpackage{lastpage} \cite{lastpage} handle this issue for the total number of
118 % pages, but, to the best of my knowledge, there is no package that makes it
119 % easy to print the total number of arbitrary elements.
120 %
121 % The \xpackage{TotCount} package hopefully fills this gap. It enables the
122 % computation and display of the last number assigned to a counter inside a
123 % document (usually the maximum value of the counter). The user just has to
124 % include the \xpackage{TotCount} package, and \emph{register} a counter as a
125 % ``total counter''. Then, getting the maximum value of that counter is as easy
126 % as calling the macro |\total|\marg{counter} at the desired place, and running
127 % \LaTeX\ twice.
128 %
129 % As an early example, the commands
130 % \begin{macrocode}
131 %<*doc>
132 \regtotcounter{section}\total{section}
133 %</doc>
134 % \end{macrocode}
135 % inform the reader that there are \regtotcounter{section}\total{section}
136 % sections in this document. With only slightly more work (since there is no
137 % convenient counter already defined) we can write that this document has
138 % \total{citnum} citations, which it mentions \total{citesnum} times:
139 % \begin{macrocode}
140 %<*doc>
141 \newtotcounter{citnum}
142 \def\oldbibitem{} \let\oldbibitem=\bibitem
143 \def\bibitem{\stepcounter{citnum}\oldbibitem}
144 \total{citnum}
145
146 \newtotcounter{citesnum}
147 \def\oldcite{} \let\oldcite=\cite
148 \def\cite{\stepcounter{citesnum}\oldcite}
149 \total{citesnum}
150 %</doc>
151 % \end{macrocode}
152 %
153 %
154 % \section{User Interface}
155 %
156 % \DescribeMacro{\regtotcounter}
157 % To display the maximum value of a counter we first need to \emph{register}
158 % that counter as a ``total counter''. We can do this by calling the macro
159 % |\regtotcounter|\marg{counter} on an existing counter. We can register a
160 % counter in the preamble or inside the document, but in any case before
161 % calling |\total| or |\totvalue| on that counter.
162 %
163 % This macro will use the main auxiliary file to get the total number of the
164 % counter at the second time we run \LaTeX\ on the document.
165 %
166 % To use a file other than the main auxiliary file we need to pass an option to
167 % the macro: |\regtotcounter[auxfile=|\meta{file}|]|\marg{counter}. This way
168 % the last value of \meta{counter} will be stored in \meta{file}. This macro
169 % will also input \meta{file} the second time that \LaTeX\ runs (and every time
170 % after that) to get the right total value of the counter. The same auxiliary
171 % file can be used for many total counters and multiple auxiliary files can be
172 % used within the same document.
173 %
174 % \DescribeMacro{\newtotcounter}
175 % The macro |\newtotcounter| is a shorthand for creating a new counter and
176 % registering it as a total counter. Just like |\regtotcounter|, we can pass an
177 % |auxfile| option to this macro to make it use an alternative auxiliary file:
178 % |\newtotcounter[auxfile=|\meta{file}|]|\marg{counter}.
179 %
180 % \DescribeMacro{\total}
181 % To print the maximum value of \meta{counter} we can call the macro
182 % |\total|\marg{counter}. The first time \LaTeX\ runs on the document this
183 % macro will display the symbols ``$??$'' and output in the terminal the
184 % warning
185 % \begin{verbatim}
186 % Package totcount Warning: Rerun to get correct total counts on input line X
187 % \end{verbatim}
188 % where |X| is the line the |\total| macro was used. The second time
189 % \LaTeX\ runs on the same document (and every time after that) the macro will
190 % display the total count of \meta{counter} recorded in the auxiliary file.
191 %
192 % \DescribeMacro{\totvalue}
193 % We can obtain the numeric total value of \meta{counter} (in contrast to
194 % printing it using |\total|) by calling the macro |\totvalue|\marg{counter}.
195 % This is useful, for example, when we want to test the total value of the
196 % counter (see example in Section~\ref{sec:example}). The first time that
197 % \LaTeX\ runs on a document, where the total counts are not computed yet, this
198 % command returns |-1|.
199 %
200 % \DescribeMacro{\usetotcountfile}
201 % Sometimes we might want to use the total counters of an auxiliary file
202 % without recomputing (and overriding) their value. This is especially useful
203 % when the total counters have been computed by running \LaTeX\ on a
204 % different document. In this case, instead of registering a total
205 % counter with one of the commands |\regtotcounter| and |\newtotcounter| we can
206 % simply use the auxiliary file that contains the values of the desired total
207 % counters by calling the macro |\usetotcountfile|\marg{file}. This
208 % functionality is the main reason why total counters can be stored in
209 % alternative auxiliary files.
210 %
211 % \DescribeMacro{\newcounter}
212 % \DescribeMacro{\addtocounter}
213 % \DescribeMacro{\stepcounter}
214 % \DescribeMacro{\setcounter}
215 % \DescribeMacro{\value}
216 % Since this package uses regular \LaTeX\ counters, we can use all the usual
217 % commands to define, set, increment, and get the current (\emph{not the
218 % total}) value of counters. See The \LaTeX\ Companion \cite{latexcompanion}
219 % for an explanation of how to use \LaTeX\ counters, and
220 % Section~\ref{sec:example} for sample uses of these macros.
221 %
222 %
223 % \section{\label{sec:installation}Installation}
224 %
225 % To get the package file run
226 % \begin{verbatim}
227 %latex totcount.ins \end{verbatim}
228 % Then copy the |totcount.sty| file in a directory accessible by (pdf)\LaTeX\
229 % and re-hash the latex tree.
230 %
231 % To compile the documentation run
232 % \begin{verbatim}
233 %pdflatex totcount.drv
234 %makeindex -s gind.ist totcount.idx
235 %makeindex -s gglo.ist -o totcount.gls totcount.glo
236 %pdflatex totcount.drv \end{verbatim}
237 %
238 % To run the example do
239 % \begin{verbatim}
240 %pdflatex totcount-ex.tex
241 %pdflatex totcount-ex.tex \end{verbatim}
242 %
243 %
244 % \section{Required Packages}
245 % The \xpackage{TotCount} package requires the \xpackage{keyval} package
246 % \cite{keyval}.
247 %
248 % ^^A**********************************************************************
249 %
250 % \StopEventually{}
251 %
252 % \section{Implementation}
253 %
254 % \setlength{\parindent}{0pt}
255 %
256 % This section contains the source code of |totcount.sty|.
257 %
258 % \begin{macrocode}
259 %<*sty>
260 \ProvidesPackage{totcount}
261 [\totcfiledate \space v\totcfileversion \space package for getting%
262 the total value of LaTeX counters]
263 % \end{macrocode}
264 %%
265 %% Import of the \xpackage{keyval} package \cite{keyval}:
266 % \begin{macrocode}
267 \RequirePackage{keyval}
268 % \end{macrocode}
269 %%
270 % \begin{macro}{\newtotcounter}
271 %% Creates a new counter and registers it as a total counter. This is the
272 %% top-level dispatch of the macro, depending on whether there is an optional
273 %% argument or not.
274 % \begin{macrocode}
275 \def\newtotcounter{%
276 \@ifnextchar[\newtotcounter@newaux\newtotcounter@mainaux}
277 % \end{macrocode}
278 % \end{macro}
279 %%
280 % \begin{macro}{\newtotcounter@newaux}
281 %% This is the version of the |\newtotcounter| macro that uses a separate
282 %% auxiliary file. It first creates the counter (second argument) and then
283 %% calls the macro |\regtotcounter|.
284 % \begin{macrocode}
285 \def\newtotcounter@newaux[#1]#2{%
286 \newcounter{#2}%
287 \regtotcounter[#1]{#2}%
288 }
289 % \end{macrocode}
290 % \end{macro}
291 %%
292 % \begin{macro}{\newtotcounter@mainaux}
293 %% This is the version of the |\newtotcounter| macro that uses the main
294 %% auxiliary file. It first creates the counter (argument) and then calls
295 %% the macro |\regtotcounter|.
296 % \begin{macrocode}
297 \def\newtotcounter@mainaux#1{%
298 \newcounter{#1}%
299 % \end{macrocode}
300 %% Register the counter:
301 % \begin{macrocode}
302 \regtotcounter{#1}%
303 }
304 % \end{macrocode}
305 % \end{macro}
306 %%
307 % \begin{macro}{\regtotcounter}
308 %% Registers a counter as a total counter. This is the top-level dispatch of
309 %% the macro, depending on whether there is an optional argument or not.
310 % \begin{macrocode}
311 \def\regtotcounter{%
312 \@ifnextchar[\regtotcounter@newaux\regtotcounter@mainaux}
313 % \end{macrocode}
314 % \end{macro}
315 %%
316 %% The following is the definition of the |auxfile| key for specifying an
317 %% alternative auxiliary file when calling the macro |\regtotcounter| (see
318 %% \cite{keyval}).
319 % \begin{macrocode}
320 \define@key{totcounter}{auxfile}{\def\this@auxfile{#1}}
321 % \end{macrocode}
322 %%
323 % \begin{macro}{\regtotcounter@newaux}
324 %% This is the version of the |\regtotcounter| macro that uses a separate
325 %% auxiliary file. The auxiliary file is passed as a first argument in the
326 %% form of a key--value pair |[auxfile=|\meta{file}|]|, and the counter to be
327 %% registered is passed as the second argument.
328 %% \begin{macrocode}
329 \def\regtotcounter@newaux[#1]#2{%
330 \setkeys{totcounter}{#1}%
331 % \end{macrocode}
332 %% Try to load the contents of the file:
333 % \begin{macrocode}
334 \InputIfFileExists{\this@auxfile}{}{}%
335 % \end{macrocode}
336 %% Make sure that the auxiliary file is open; \LaTeX\ will close it at the end:
337 % \begin{macrocode}
338 \expandafter\ifx\csname \this@auxfile @open\endcsname\relax%
339 \expandafter\gdef\csname \this@auxfile @open\endcsname{}%
340 \expandafter\newwrite\csname \this@auxfile @stream\endcsname%
341 \immediate\expandafter\openout%
342 \csname \this@auxfile @stream\endcsname=\this@auxfile%
343 \fi%
344 % \end{macrocode}
345 %% Create a new counter holding the total number of the actual counter:
346 % \begin{macrocode}
347 \expandafter\ifx\csname c@#2@totc\endcsname\relax%
348 \newcounter{#2@totc}%
349 \setcounter{#2@totc}{-1}%
350 \fi%
351 % \end{macrocode}
352 %% At the end of the document write code in the auxiliary file to update the
353 %% total counter with the value of the actual counter:
354 % \begin{macrocode}
355 \AtEndDocument{%
356 \def\sp{ }%
357 \immediate\expandafter\write%
358 \csname \this@auxfile @stream\endcsname{%
359 \string\expandafter\string\ifx%
360 \string\csname\sp c@#2@totc\string\endcsname\string\relax%
361 \string\newcounter{#2@totc}%
362 \string\fi%
363 \string\setcounter{#2@totc}{\number\value{#2}}%
364 }%
365 }%
366 }
367 % \end{macrocode}
368 % \end{macro}
369 %%
370 % \begin{macro}{\regtotcounter@mainaux}
371 %% This is the version of the |\regtotcounter| macro that uses the main
372 %% auxiliary file. The counter to be registered is passed as the second
373 %% argument.
374 % \begin{macrocode}
375 \def\regtotcounter@mainaux#1{%
376 % \end{macrocode}
377 %% Create a new counter holding the total number of the actual counter:
378 % \begin{macrocode}
379 \expandafter\ifx\csname c@#1@totc\endcsname\relax%
380 \newcounter{#1@totc}%
381 \setcounter{#1@totc}{-1}%
382 \fi%
383 % \end{macrocode}
384 %% At the end of the document write code in the auxiliary file to update the
385 %% total counter with the value of the actual counter:
386 % \begin{macrocode}
387 \AtEndDocument{%
388 \def\sp{ }%
389 \immediate\write\@mainaux{%
390 \string\expandafter\string\ifx%
391 \string\csname\sp c@#1@totc\string\endcsname\string\relax%
392 \string\newcounter{\string #1@totc}%
393 \string\fi%
394 \string\setcounter{\string #1@totc}{\number\value{#1}}%
395 }%
396 }%
397 }
398 % \end{macrocode}
399 % \end{macro}
400 %%
401 % \begin{macro}{\total}
402 %% Prints the total value of a registered total counter that is passed as
403 %% argument. If the total value is yet to be computed (at the first time
404 %% \LaTeX\ runs on the document) then its value is |-1| and the output of the
405 %% command is $??$.
406 % \changes{v1.2}{2011/01/25}{Warnings are now reported using the
407 % PackageWarning command, which improves interoperability with editing
408 % environments such as LyX}
409 % \begin{macrocode}
410 \newcommand\total[1]{%
411 \def\tmp@val{\value{#1@totc}}%
412 \ifnum\tmp@val=-1%
413 \PackageWarning{totcount}{Rerun to get correct total counts}%
414 $??$%
415 \else%
416 \number\value{#1@totc}%
417 \fi%
418 }
419 % \end{macrocode}
420 % \end{macro}
421 %%
422 % \begin{macro}{\totvalue}
423 %% Returns the numeric total value of a registered total counter that is
424 %% passed as argument. Note that if the counter's value is not yet computed
425 %% (at the first time \LaTeX\ runs on the document) this macro returns |-1|.
426 % \begin{macrocode}
427 \newcommand\totvalue[1]{\value{#1@totc}}
428 % \end{macrocode}
429 % \end{macro}
430 %%
431 % \begin{macro}{\usetotcountfile}
432 %% Inputs an auxiliary file that should contain total-counter
433 %% definitions. It outputs a warning message in the terminal if the file
434 %% doesn't exist. This command should be used \emph{instead} of registering a
435 %% counter.
436 % \begin{macrocode}
437 \newcommand\usetotcountfile[1]{%
438 \InputIfFileExists{#1}{%
439 \message{TotCount inputs file '#1'}%
440 }{%
441 \PackageWarning{totcount}{File '#1' does not exist!}%
442 \message{\space\space\space\space\space\space\space\space\space%
443 \space\space\space\space\space\space\space\space\space%
444 Ignoring \string\usetotcountfile{#1}.}%
445 }%
446 }
447 %</sty>
448 % \end{macrocode}
449 % \end{macro}
450 %
451 % ^^A**********************************************************************
452 %
453 % \section{\label{sec:example}Simple Example}
454 %
455 % The following is a simple example of how to use the functionality of the
456 % \xpackage{TotCount} package. This example can be found in the file
457 % |totcount-ex.tex|, after running \LaTeX\ on the |totcount.ins| file (see
458 % Section~\ref{sec:installation}).
459 %
460 % \begin{macrocode}
461 %<*ex>
462 \ProvidesFile{totcount-ex.tex}
463 [\totcfiledate \space v\totcfileversion \space%
464 test file for the TotCount package]
465 \documentclass{article}
466 % \end{macrocode}
467 %%
468 %% Import the package
469 % \begin{macrocode}
470 \RequirePackage{totcount}
471 % \end{macrocode}
472 %%
473 %% Comment out the following line to use the previously stored total counts in
474 %% 'mycount.aux' (make sure it exists!) instead of computing them again:
475 % \begin{macrocode}
476 \def\computemycount{}
477 \expandafter\ifx\csname computemycount\endcsname\relax
478 \usetotcountfile{mycount.aux}
479 \newcounter{mycount} % so that increments of this counter don't break
480 \else
481 \newtotcounter[auxfile=mycount.aux]{mycount}
482 \fi
483 % \end{macrocode}
484 %%
485 %% Register the section and page counters as a total counters:
486 % \begin{macrocode}
487 \regtotcounter{section}
488 \regtotcounter{page}
489
490 \begin{document}
491 % \end{macrocode}
492 %%
493 %% A total counter can be declared/registered anywhere:
494 % \begin{macrocode}
495 \newtotcounter{yourcount}
496
497 \section{Total Counts}
498 % \end{macrocode}
499 %%
500 %% Increment counters as usual:
501 % \begin{macrocode}
502 \addtocounter{mycount}{5}
503 \addtocounter{yourcount}{5}
504 % \end{macrocode}
505 %%
506 %% Print the value of a total counter by using |\total|:
507 % \begin{macrocode}
508 The total value of the counter {\tt mycount} is \total{mycount} (should
509 be 10), and the total value of the counter {\tt yourcount} is
510 \total{yourcount} (should be 17).
511
512 % \end{macrocode}
513 %%
514 %% Get the numeric value of a total counter by using |\totvalue|:
515 % \begin{macrocode}
516 This document has \total{section}
517 \ifnum\totvalue{section}=1 section \else sections \fi
518 and \total{page}
519 \ifnum\totvalue{page}=1 page. \else pages. \fi
520
521 % \end{macrocode}
522 %%
523 %% The effect of incrementing the counters will be visible the second
524 %% time LaTeX runs:
525 % \begin{macrocode}
526 \addtocounter{yourcount}{5}
527 \addtocounter{mycount}{5}
528 \addtocounter{yourcount}{7}
529
530 \section{A Section}
531 \section{Another Section}
532 \section{Yet Another Section}
533
534 \end{document}
535 %</ex>
536 % \end{macrocode}
537 %
538 % ^^A**********************************************************************
539 %
540 % \section{Acknowledgments}
541 %
542 % Many thanks to Christoforos Moutafis for pointing me to the right direction
543 % when I first started looking for a way to display the maximum value of
544 % counters. Thanks also to everyone who submitted bug reports.
545 %
546 % \begin{thebibliography}{H\,1}
547 % \raggedright
548 % \bibitem[1]{keyval}
549 % David Carlisle,
550 % \newblock \emph{The \xpackage{keyval} package},
551 % \newblock \LaTeXe{} package.
552 % \newblock \CTAN{macros/latex/required/graphics/keyval.dtx}
553 % \bibitem[2]{lastpage}
554 % Jeff Goldberg,
555 % \newblock \emph{The \xpackage{lastpage} package},
556 % \newblock \LaTeXe{} package.
557 % \newblock \CTAN{macros/latex/contrib/lastpage/}
558 % \bibitem[3]{latexcompanion}
559 % Michel Goossens, Frank Mittelbach and Alexander Samarin,
560 % \newblock \emph{The \LaTeX\ Companion},
561 % \newblock Addison-Wesley, 1994.
562 % \bibitem[4]{totpages}
563 % Wilhelm M\"uller,
564 % \newblock \emph{The \xpackage{totpages} package},
565 % \newblock \LaTeXe{} package.
566 % \newblock \CTAN{macros/latex/contrib/totpages/}
567 % \end{thebibliography}
568 %
569 % \Finale
570 % \PrintIndex \PrintChanges
571 \endinput