summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex311
1 files changed, 252 insertions, 59 deletions
diff --git a/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex b/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
index 866709ca404..6c1a330b496 100644
--- a/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
+++ b/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
@@ -1,109 +1,302 @@
\documentclass[10pt,a4paper]{article}
-\usepackage{lipsum}
-\usepackage{shortvrb}
-\usepackage{fancyvrb}
-\usepackage{parskip}
-\usepackage{paralist}
-\usepackage[acceptempty,hyperlink]{pagerange}
-\usepackage{hyperref}
-\hypersetup{colorlinks=true,linkcolor=red,pdfpagemode=UseThumbs,
- implicit=true,breaklinks=true,citecolor=purple,pdfview=FitH,
- pdfstartview=FitH}
+\InputIfFileExists{pagerange-guide.cfg}{}{%
+ \errmessage{No file pagerange-guide.cfg}}
+\pagestyle{fancyplain}
\begin{document}
\MakeShortVerb{\+}
-\title{The {\tt pagerange} Package}
+\title{\textbf{The {\tt pagerange} Package}\\[1ex] Version 0.2}
\author{Ahmed Musa\\[.5ex]University of Central Lancashire\\
- Preston, United Kingdom\\[1ex]\url{a.musa@rocketmail.com}
+ Preston, United Kingdom\\[1ex]\email{a.musa@rocketmail.com}
}
\maketitle
\section{Introduction}
This package emerged from my desire to resolve page ranges in the +draftmark+ package, but it may be useful to other \LaTeX{} enthusiasts.
-There is additional user guide in the comments within the package.
+\section{Usage}
+
+When a given page range +xx-yy+ (simple/plain characters) or +\pages+ (control sequence, \eg, +\def\pages{xx-yy}+) is submitted to the macro +\pagerange+ (\eg, +\pagerange{xx-yy}+ or +\pagerange\pages+), this package splits the range as +xx+ in the macro +\pagestart+ and +yy+ in +\pageend+. The counter equivalents of these are +\prg@cnta+ and +\prg@cntb+. The control sequence containing the page range (\eg, +\pages+) is fully expanded before the page range is split.
+
+If you specify a range consisting of a hyphen (or any tie) but with one or two empty page numbers, the following will happen:
+\begin{compactenum}[a)]
+\item a range of the form ``+-34+'' is taken to mean pages~1 to 34;
+\item a range of the form ``+12-+'' is taken to mean page~12 to last page;
+\item a range of the form ``+-+'' (\ie, only hyphen and no pages) is taken to mean page~1 to the last page.
+\end{compactenum}
+
+An empty or blank page range (\ie, containing no argument and no hyphen/tie) is taken to mean the range +1-1+ or it may prompt a fatal error, depending on whether the boolean +acceptempty+ is set true or false (respectively).
+
+Page ranges containing more than one hyphen/tie cause fatal error.
+
+If the upper limit of the page range is smaller than the lower limit, a fatal error is flagged.
+
+The tie between the pages in the page range can be any single non-active character; its default is the hyphen character ``+-+''. It can be changed in the call to the package (\eg, +\usepackage[tie=*]{pagerange}+) or at any moment through +\pagerangeoptions{tie=*}+. Of course, active characters can't be used as ties. The package easily terminates with a warning when an active character is passed as +tie+.
+
+Because of the need for the last page of the document, at least~2 runs/passes are needed to obtain the correct last page.
+
+This package has been tested with the +hyperref+ package, which redefines the label used by the +lastpage+ package. By default, the last page is not hyperlinked. If you want the last page to be hyperlinked, you should set the boolean option +hyperlink=true+ in +\usepackage{pagerange}+ or in +\pagerangeoptions+.
+
+\section{Package options}
+The package has only three options, namely,
+
+\begin{tabularx}{\linewidth}{m{2.5cm}m{2.0cm}X}
+\bf Option & \bf Default & \bf Meaning\\
++tie+ & hyphen (+-+) & The tie that show the breakpoint for the page range.\\
++acceptempty+ & +false+ & The boolean option that specifies if empty page ranges (\ie, no page numbers and no tie) submitted to the package should be accepted. If +true+, the page range is assumed to be from page~1 to the last page.\\
++hyperlink+& +false+& The boolean switch that determines if the last page (of the page range) should be hyperlinked.\\
+\end{tabularx}
\section{Examples}
+\pgexample{}
+The following
+\begin{pverbatim}
\pagerange{123-456}
-\par\medskip\noindent
Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+\pagerange{123-456}
+produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+
+The following
+
+\begin{pverbatim}
\pagerange{12345-67890}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+\pagerange{12345-67890}
+produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The following
+
+\begin{pverbatim}
\pagerange{123-4567}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+
+\pagerange{123-4567}
+produces \result{Pages~\pagestart\space to\space\pageend}.
+\pgexample{}
+The following
+
+\begin{pverbatim}
\pagerange{600-601}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+\pagerange{600-601}
+produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The following
+
+\begin{pverbatim}
\pagerange{-34}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+
+\pagerange{-34}
+produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{Hyperlinking of last page}
+
+The package was loaded as
+\par\medskip
+\centerline{\tt\string\usepackage[acceptempty,hyperlink]\{pagerange\},}
-\bigskip\noindent
-Hyperlinking of last page:
+in which both +acceptempty+ and +hyperlink+ are +true+. They can, of course, both be reversed (\ie, set as +false+). Since the prevailing value of +hyperlink+ is +true+, we see that
+
+\begin{pverbatim}
\pagerange{1-}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
-\pagerange{-}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\pagerange{1-}
+yields \result{Pages~\pagestart\space to\space\pageend}.
-\bigskip\noindent
-No hyperlinking of last page:
+\pgexample{No hyperlinking of last page}
+In the following the value of +hyperlink+ is +false+:
+
+\begin{pverbatim}
\pagerangeoptions{hyperlink=false}
\pagerange{1-}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+
+\pagerangeoptions{hyperlink=false}
+\pagerange{1-}
+which produces \result{Pages~\pagestart\space to\space\pageend}.
+\pgexample{No page numbers given}
+The following
+
+\begin{pverbatim}
+\pagerangeoptions{hyperlink=true}
\pagerange{-}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
-\pagerange{123-234}
+\pagerangeoptions{hyperlink=true}
+\pagerange{-}
\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+produces \result{Pages~\pagestart\space to\space\pageend}.
-\pagerange{} % This logs a warning message or issues fatal error.
-\par\medskip\noindent
-Page~\pagestart\space to\space\pageend
+\pgexample{}
+The following logs a warning message or issues fatal error, depending on the status of +acceptempty+ option:
-%\pagerange{123-456-789} % Uncomment this line to get fatal error.
+\begin{pverbatim}
+\pagerange{}
+\end{pverbatim}
-%\pagerange{34-12} % Uncomment this line to get fatal error.
+%\pagerange{}
+%Page~\pagestart\space to\space\pageend
-\par\medskip
+\pgexample{}
+The following fails because of multiple hyphens (ties):
+
+\begin{pverbatim}
+\pagerange{123-456-789}
+\end{pverbatim}
+
+%\pagerange{123-456-789}
+
+\pgexample{}
+The following fails because +\pagestart+ is larger than +\pageend+:
+
+\begin{pverbatim}
+\pagerange{34-12}
+\end{pverbatim}
+
+%\pagerange{34-12}
+
+\pgexample{}
+The following fails because +tie+ can't be active character:
+
+\begin{pverbatim}
+\pagerangeoptions{tie=~}
+\end{pverbatim}
+
+%\pagerangeoptions{tie=~}
+
+\pgexample{}
+For the same reason (\ie, the use of active character as +tie+), the following fails---although nested commands are permitted:
+
+\begin{pverbatim}
+\def\Xone{~}
+\def\Xtwo{\Xone}
+\pagerangeoptions{tie=\Xtwo}
+\end{pverbatim}
+
+%\def\Xone{~}
+%\def\Xtwo{\Xone}
+%\pagerangeoptions{tie=\Xtwo}
+
+\pgexample{}
+The following works because the +\pagerange+ is fully expanded before splitting:
+
+\begin{pverbatim}
+\def\Xone{-}
+\def\Xtwo{\Xone}
+\pagerange{22\Xtwo 23}
+\end{pverbatim}
+
+\def\Xone{-}
+\def\Xtwo{\Xone}
+\pagerange{22\Xtwo 23}
+This produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The following also works because the +\pagerange+ is fully expanded before splitting:
+
+\begin{pverbatim}
+\def\X{-}
+\def\Y{2222}
+\def\Z{3333}
+\pagerange{\Y\X\Z}
+\end{pverbatim}
+
+\def\X{-}
+\def\Y{2222}
+\def\Z{3333}
+\pagerange{\Y\X\Z}
+This produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The following also works because the +\pagerange+ and +tie+ are fully expanded before splitting page range:
+
+\begin{pverbatim}
+\def\X{-}
+\pagerangeoptions{tie=\X}
+\pagerange{123\X 234}
+\end{pverbatim}
+\def\X{-}
+\pagerangeoptions{tie=\X}
+\pagerange{123\X 234}
+This produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The following works because infinite nesting of +tie+ and +\pagerange+ are permitted:
+
+\begin{pverbatim}
+\def\Xone{-}
+\def\Xtwo{\Xone}
+\pagerangeoptions{tie=\Xtwo}
+\pagerange{444\Xtwo 555}
+\end{pverbatim}
+
+\def\Xone{-}
+\def\Xtwo{\Xone}
+\pagerangeoptions{tie=\Xtwo}
+\pagerange{444\Xtwo 555}
+This yields \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The following gives incorrect (in fact, weird) result because the prevailing +tie+ is not a star:
+
+\begin{pverbatim}
+\pagerange{33*44}
+\end{pverbatim}
+
+%\pagerange{33*44}
+%It produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+The +tie+ can be changed to a star (or any non-active character) as follows:
+
+\begin{pverbatim}
\pagerangeoptions{tie=*}
-\pagerange{123*234}
-\par\noindent
-Pages~\pagestart\space to\space\pageend
+\pagerange{2233*3344}
+\end{pverbatim}
+
+\pagerangeoptions{tie=*}
+\pagerange{2233*3344}
+This correctly produces \result{Pages~\pagestart\space to\space\pageend}.
+
+\pgexample{}
+In the following the +tie+ is changed to letter ``T'':
+\begin{pverbatim}
\pagerangeoptions{tie=T}
\pagerange{1234T1235}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
+
+\pagerangeoptions{tie=T}
+\pagerange{1234T1235}
+It produces \result{Pages~\pagestart\space to\space\pageend}.
+\pgexample{}
+The following
+
+\begin{pverbatim}
\pagerangeoptions{tie=X}
\pagerange{2034X2135}
-\par\medskip\noindent
-Pages~\pagestart\space to\space\pageend
+\end{pverbatim}
-\section{To-do}
+\pagerangeoptions{tie=X}
+\pagerange{2034X2135}
+correctly yields \result{Pages~\pagestart\space to\space\pageend}.
-\begin{compactenum}[a)]
-\item To provide for calls such as in {\tt\string\pagerange\{\string\pageref\{page:label\}-200\}}.
-\item Documentation.
-\end{compactenum}
+\section{To-do}
-\par\bigskip
-\centerline{\rule{.5\hsize}{.4pt}}
-\bigskip
-\lipsum[1-4]
+To provide for calls such as in +\pagerange{\pageref{page:label}-200}+.
\end{document} \ No newline at end of file