path: root/macros/latex/contrib/chappg/chappg.dtx

%\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         \~}