diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex | 311 |
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 |