summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/chappg/chappg.dtx
blob: 32457b5e055d4623f189bcff6def0271e0d25863 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
%\iffalse meta-comment, etc.
%% This is chappg.dtx, and it's -*-LaTeX-*- text
%
% We use the same body for the \cs{ProvidesFile} as for the
% \cs{ProvidesPackage} command.
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
%<*dtx>
\ProvidesFile{chappg.dtx}%
%</dtx>
%<package>\ProvidesPackage{chappg}%
        [2006/05/09 v2.1b page numbering by chapter
%<package>     number pages by chapter (or other unit)%
%<*dtx>
               chappg package source file%
%</dtx>
                   ]% $Id: chappg.dtx,v 1.4 2006/05/09 07:12:20 rf10 Exp rf10 $
%    \end{macrocode}
%
% Code to enable LaTeX processing of the file without the intervention
% of a driver file.
%    \begin{macrocode}
%<*driver>
\setcounter{errorcontextlines}{999}
\documentclass{ltxdoc}
%    \end{macrocode}
%
% we limit the things that we will index
%    \begin{macrocode}
\DoNotIndex{\#,\@MM,\@cclv,\@gobble,\@ifnextchar,\@ifundefined}
\DoNotIndex{\|,\advance,\begingroup,\bgroup,\box,\csname}
\DoNotIndex{\dagger,\ddagger,\def,\divide,\dp}
\DoNotIndex{\edef,\egroup,\ifx,\else,\fi,\endcsname,\endgroup,\end}
\DoNotIndex{\endinput,\ensuremath,\expandafter}
\DoNotIndex{\gdef,\global,\hbox,\hskip,\hss,\ht}
\DoNotIndex{\ifcase,\or,\ifdim,\ifhbox,\ifhmode,\ifnum,\ifvbox,
            \fi        ,\fi   ,\fi    ,\fi     ,\fi   ,\fi    }
\DoNotIndex{\ifvoid,\fi,\kern,\let,\long,\loop}
\DoNotIndex{\MessageBreak,\newbox,\newcommand,\newcounter}
\DoNotIndex{\newdimen,\newif,\newskip,\newtoks,\noexpand}
\DoNotIndex{\P,\p@,\par,\penalty,\protect,\providecommand}
\DoNotIndex{\relax,\renewcommand,\S,\setbox,\setcounter}
\DoNotIndex{\skip,\space,\the,\typeout,\vbox,\vskip}
\DoNotIndex{\wd,\xdef,\@}
\GetFileInfo{chappg.dtx}
\EnableCrossrefs
% to get documented source of the package, comment out the next line,
% and uncomment the following one; otherwise, create yourself
% (somewhere on your LaTeX input path) a file ltxdoc.cfg that contains
% simply          \AtBeginDocument{\AlsoImplementation}
\OnlyDescription
%\AlsoImplementation
\setcounter{StandardModuleDepth}{1}
\begin{document}
\DocInput{chappg.dtx}
\end{document}
%</driver>
%    \end{macrocode}
% \fi
%
% \CheckSum{201}
%
% \title{\texttt{chappg} --- a \LaTeX{} package for\\
%        numbering pages ``by chapter''\thanks{This file has
%          version number \fileversion, last revised \filedate}}
% \author{Robin Fairbairns\thanks{University of Cambridge Computer
%     Laboratory, William Gates Building, J.\,J. Thompson Avenue, 
%     Cambridge, CB2 0FD, UK
%     (\texttt{robin.fairbairns<commercial-rate-sign>cl.cam.ac.uk})}}
% \maketitle
%
% \section*{Support}
%
% Some support of this package is available \emph{for unchanged copies
%   of the package} via email to me at the address given in the
% footnote.  Support will remain available at least as long as the
% address remains valid.  I don't guarantee anything, but I will
% probably look at any bug reports you may submit, and may correct
% problems reported (either in my code or in yours\dots).
%
% \section*{Copyright statement}
%
% \noindent Program: \texttt{chappg.dtx}\par
% \noindent Copyright 2000, 2003 Robin Fairbairns
%
% This program may redistributed and/or modified under the terms
% of the LaTeX Project Public License in file \texttt{lppl.txt}
% (available from CTAN directory \texttt{macros/latex/base}; either
% version 1.3 of the License, or (at your option) any later version.
% The latest version of this license is in
%  \texttt{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.
%
% \section{User interface~--- package options}
%
% The package provides two options.
%
% \noindent|\usepackage[auto]{chappg}| causes the package to set
% pagenumbering according to its scheme, using the command
% |\pagenumbering{bychapter}|
%
% \smallskip\noindent|\usepackage[noauto]{chappg}| tells the package
% not to set pagenumbering; the user is then free to set up
% pagenumbering according to her own scheme of things.
%
% \smallskip\noindent In the absence of any package option, the
% package acts as if the user had given the \texttt{auto} option; this
% action is compatible with earlier versions of this package.
%
% \section{User interface~--- commands}
%
% The purpose of the package is to provide a page-numbering style
% ``\texttt{bychapter}'', for use with the \cs{pagenumbering} command.
% In simple use, the command
% \begin{verbatim}
% \pagenumbering{bychapter}
% \end{verbatim}
% will
% \begin{itemize}
% \item reset the \texttt{page} counter to \texttt{1},
% \item cause page numbers to display as
%   ``\meta{chapter}-\meta{page}'',
% \item cause page numbers to be reset to 1 at the start of each chapter.
% \end{itemize}
% Of course, none of this is useful (indeed, an error is provoked) if
% the document is not using the standard \textsf{report} or
% \textsf{book} class, or some other class that provides
% \cs{chapter}-level divisions.
%
% More complicated use of the package is possible, using the commands
% described below.
%
% The package modifies the \LaTeX{} kernel command \cs{pagenumbering}
% so that it has an optional argument; all the kernel-defined
% numbering styles ignore the optional argument, but if the numbering
% style is \texttt{bychapter}, the argument may be used to specify a
% means of numbering pages.  Thus, while
% \begin{verbatim}
% \pagenumbering{bychapter}
% \end{verbatim}
% gives page numbers in the form ``\meta{chapter}-\meta{page}'', so
% pages of chapter 3 will be numbered 3-1, 3-2, etc., and pages of
% appendix B will be numbered B-1, B-2, etc.
%
% With the optional argument form:
% \begin{verbatim}
% \pagenumbering[Index]{bychapter}
% \end{verbatim}
% page numbers will appear in the form ``Index-\meta{page}''.  One of
% the anticipated uses of this facility is just as indicated~---
% providing by-chapter numbering of the pages of chapters that don't
% have numbers (as index chapters don't in the standard classes).
% 
% The separator between the chapter and page numbers (hyphen above,
% but I can imagine people wanting it to be an en-dash) is
% \cs{chappgsep}, which en-dash-lovers may redefine (after loading the
% package); for example:
%\begin{verbatim}
%  \renewcommand{\chappgsep}{--}%
%\end{verbatim}
% Havoc is wreaked with this structure in the LaTeX \cs{frontmatter}
% and \cs{mainmatter} commands (which both explicitly use
% \cs{pagenumbering} and therefore destroy the changed definition of
% \cs{thepage}).
%
% My design decision, when converting this package for use under
% LaTeX~2e was to assume that \cs{frontmatter} is indeed to
% be in \cs{pagenumbering}|{roman}|, and to restore the
% chapter-numbering in \cs{mainmatter}.  Chapters in the frontmatter
% can not be numbered `by' their chapters, since the chapters don't
% actually have numbers.  If the author wishes to have some special
% treatment of part of the frontmatter, the analogue of the above is
%\begin{verbatim}
%  \chapter{Preface}
%  \pagenumbering[Preface]{bychapter}
%\end{verbatim}
%
% The conception breaks down again in \cs{backmatter}; again, the
% \cs{chapter} commands don't number the chapters, so that the pages
% will all be numbered as if they were `within' the last real chapter.
% Therefore, if by-chapter page numbering is still enabled while in
% the backmatter, and the user hasn't issued a new
% \cs{pagenumbering}|[prefix]{bychapter}| since the \cs{backmatter} command,
% the package rewrites the prefix as |{\bf??}|, and produces a warning
% at the end of the document.
%
% \section{User interface --- a caution}
%
% The \cs{appendix} command can confuse \texttt{bychapter} page
% numbering~--- unless you take some precautions, the last page or two
% of your last ``real'' chapter will not be be numbered ``by
% chapter''.  The solution is to issue a \cs{clearpage} (if
% \texttt{openany} class option is in effect), or \cs{cleardoublepage}
% (if \texttt{openright} class option is in effect).  By default,
% \textsf{report} class uses the \texttt{openany} option, so you would
% write:
% \begin{quote}
% \begin{verbatim}
% ... text at end of chapter.
% \clearpage
% \appendix
% \chapter{Title of first appendix}
% \end{verbatim}
% \end{quote}
% \noindent whereas the \textsf{book} class uses the
% \texttt{openright} option by default, so you would write:
% \begin{quote}
% \begin{verbatim}
% ... text at end of chapter.
% \cleardoublepage
% \appendix
% \chapter{Title of first appendix}
% \end{verbatim}
% \end{quote}
%
% \StopEventually{}
%
% \section{Code: Preliminaries}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% This package was
% largely reimplemented for use as a \LaTeXe{} package, taking account
% of \cs{mainmatter}, etc., and providing various extra capabilities,
% by Robin Fairbairns, from a \LaTeX\,2.09 style file by
% Max Hailperin, who first published the style in \texttt{TeXMaG}
% Vol. 5, No. 3 (part 1).
%
% This release provides typeset documentation of the first \LaTeXe{}
% version, for \TeX{} catalogue users' convenience.
%
% \begin{macro}{\if@chappg@auto}
% \begin{macro}{\if@chappg@resetting}
% Conditionals for control of page number resetting
%    \begin{macrocode}
\newif\if@chappg@auto      \@chappg@autofalse
\newif\if@chappg@resetting \@chappg@resettingfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% Deal with package options; we set option \texttt{auto} by default,
% for compatibility with the earlier versions of this package
%    \begin{macrocode}
\DeclareOption{auto}{\@chappg@autotrue}
\DeclareOption{noauto}{\@chappg@autofalse}
\ExecuteOptions{auto}
\ProcessOptions
%    \end{macrocode}
%
% \begin{macro}{\pagenumbering}
% \begin{macro}{\@chappg@prefix}
% Replace \cs{pagenumbering} so as to have the optional argument.
%    \begin{macrocode}
\renewcommand\pagenumbering[2][\@chappg@thechapter]{%
  \global\c@page\@ne
  \protected@xdef\thepage{%
    \expandafter\noexpand\csname @#2\endcsname
      \noexpand\c@page
  }%
  \gdef\@chappg@prefix{#1}%
%    \end{macrocode}
%
% And now make sure that page numbering resetting is in its right
% state
%    \begin{macrocode}
  \def\@tempa{#2}%
  \def\@tempb{bychapter}%
  \ifx\@tempa\@tempb
    \@chappg@checkloc
    \if@chappg@resetting
    \else
      \@addtoreset{page}{chapter}%
      \@chappg@resettingtrue
    \fi
  \else
    \if@chappg@resetting
      \@removefromreset{page}{chapter}%
      \@chappg@resettingfalse
    \fi
  \fi
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@bychapter}
% This is the command used by \cs{pagenumbering}\marg{bychapter} to
% actually create the page number
%    \begin{macrocode}
\newcommand\@bychapter[1]{%
  \@chappg@prefix\chappgsep\@arabic#1%
  \ifx\@chappg@prefix\@chappg@surprise
    \if@chappg@surprised\else
      \xdef\@chappg@surprise@line{\the\inputlineno}%
      \global\@chappg@surprisedtrue
    \fi
  \fi  
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@chappg@thechapter}
% Output a chapter number if there have been any chapters; otherwise
% gobble the following thing, which will be \cs{chappgsep}
%    \begin{macrocode}
\def\@chappg@thechapter{%
  \ifnum\c@chapter=0
    \expandafter\@gobble
  \else
    \thechapter
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\chappgsep}
% Separator in the above
%    \begin{macrocode}
\providecommand\chappgsep{-}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\mainmatter}
% \begin{macro}{\@@mainmatter}
% Hack at \cs{mainmatter} so that it restores bychapter numbering if
% there's been a \cs{frontmatter} command and it was there in the first place
%    \begin{macrocode}
\let\@@mainmatter\mainmatter
\def\mainmatter{\@@mainmatter
  \if@chappg@auto\pagenumbering{bychapter}\fi
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\backmatter}
% \begin{macro}{\@@backmatter}
% \begin{macro}{\@chappg@surprise}
% \begin{macro}{\if@chappg@surprised}
% Hack at \cs{backmatter} so that it warns the user of possibly surprising
% results if \cs{pagenumbering}\oarg{whatever}\marg{bychapter} hasn't
% been used 
%    \begin{macrocode}
\let\@@backmatter\backmatter
\def\backmatter{\@@backmatter
  \let\@chappg@prefix\@chappg@surprise
}
\def\@chappg@surprise{\textbf{??}}
\newif\if@chappg@surprised  \@chappg@surprisedfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% Generate a warning at end document if one of those ``surprised''
% things has been executed, or if a \cs{pagenumbering} command was
% given in a bad place.
%    \begin{macrocode}
\AtEndDocument{%
  \if@chappg@badloc
    \PackageWarningNoLine{chappg}{Bad location for
      \string\pagestyle{bychapter} command
      \MessageBreak
      \string\clearpage\space or \string\cleardoublepage\space
      \MessageBreak
      recommended before \string\pagestyle\space on line
      \@chappg@badloc@line
    }
  \fi
  \if@chappg@surprised
    \PackageWarningNoLine{chappg}{Possibly surprising page numbering in
      \string\backmatter
      \MessageBreak
      Use \string\pagenumbering[prefix]{bychapter}%
      \MessageBreak
      to select alternative before line \@chappg@surprise@line
    }
  \fi
}
%    \end{macrocode}
%
% \begin{macro}{\@chappg@checkloc}
% \begin{macro}{\if@chappg@badloc}
% Check that the current location is appropriate for a
% \texttt{bychapter} change.
%    \begin{macrocode}
\newif\if@chappg@badloc
\def\@chappg@checkloc{%
  \ifx\@onlypreamble\@notprerr
    \ifhmode
      \@chappg@badloctrue
      \xdef\@chappg@badloc@line{\the\inputlineno}%
    \else
      \ifdim\pagetotal>1sp
        \@chappg@badloctrue
        \xdef\@chappg@badloc@line{\the\inputlineno}%
      \fi
    \fi
  \fi % not in preamble
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \iffalse
% Experimental: work not yet completed
%
% command to hack at an environment to cause it to behave prettily
% \#1$\mapsto$environment name, \#2$\mapsto$prefix for page numbers
%    \begin{macrocode}
%\newcommand\bychapterenv[2]{%
%  \@ifundefined{@@#1}{%
%    \expandafter\let\csname @@#1\expandafter\endcsname
%      \csname#1\endcsname
%  }{}%
%  \expandafter\edef\csname#1\endcsname{%
%    \expandafter\noexpand\csname @@#1\endcsname
%    \global\let\noexpand\@@bychapter\noexpand\@bychapter
%    \noexpand\pagenumbering[\noexpand#2]{bychapter}%
%  }%
%  \@ifundefined{@@end#1}{%
%    \expandafter\let\csname @@end#1\expandafter\endcsname
%      \csname end#1\endcsname
%  }{}%
%  \expandafter\edef\csname end#1\endcsname{%
%    \expandafter\noexpand\csname @@end#1\endcsname
%    \global\let\noexpand\@bychapter\noexpand\@@bychapter
%  }%
%}
%    \end{macrocode}
%
% Specific cases: set up for dealing with bibliography, index, and (if
% it's defined) glossary
%    \begin{macrocode}
%\bychapterenv{thebibliography}\bibname
%\bychapterenv{theindex}\indexname
%\@ifundefined{theglossary}{}{%
%  \bychapterenv{theglossary}{Glossary}%
%}
%    \end{macrocode}
% \fi
%
%
% The next magic makes the page counter be reset to one rather than zero
%    \begin{macrocode}
\renewcommand\@stpelt[1]{%
  \global\csname c@#1\endcsname
    \expandafter\ifx \csname c@#1\endcsname \c@page
      \@ne
    \else
      \z@
    \fi
}
%    \end{macrocode}
%
% Finally, we select the bychapter as the default page style if the
% user so requires.  If the \texttt{noauto}
% option was given, the user has opted to execute the command hirself,
% but otherwise we behave backwards-compatibly.  The selection will be
% hacked by \cs{frontmatter}, if the author uses it.
%    \begin{macrocode}
\if@chappg@auto\pagenumbering{bychapter}\fi
%    \end{macrocode}
%
% \begin{macro}{\@removefromreset}
%% fragment included from\\
%% CTAN macros/latex/contrib/fragments/removefr.tex
%%
%Date: Sat, 30 Jul 1994 17:58:55 PST\\
%From: Donald Arseneau
%
% A utility macro:\\
%  \cs{@removefromreset}\marg{FOO}\marg{BAR} : Removes counter FOO
%    from the list of counters \cs{cl@BAR} to be reset when counter BAR is
%    stepped.  The opposite of \cs{@addtoreset}. 
%    \begin{macrocode}
\def\@removefromreset#1#2{\let\@tempb\@elt
   \expandafter\let\expandafter\@tempa\csname c@#1\endcsname
   \def\@elt##1{\expandafter\ifx\csname c@##1\endcsname\@tempa\else
         \noexpand\@elt{##1}\fi}%
   \expandafter\edef\csname cl@#2\endcsname{\csname cl@#2\endcsname}%
   \let\@elt\@tempb}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
%
%% \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         \~}