Debian Codegraph @

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

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