pagerange 0.3 (16dec09)

git-svn-id: svn://tug.org/texlive/trunk@16438 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 37 insertions, 47 deletions

diff --git a/Master/texmf-dist/doc/latex/pagerange/README b/Master/texmf-dist/doc/latex/pagerange/README
index b80be0a1d74..878888e88d7 100644
--- a/Master/texmf-dist/doc/latex/pagerange/README
+++ b/Master/texmf-dist/doc/latex/pagerange/README
@@ -1,4 +1,4 @@
-This is the README file for 'pagerange' package, version 0.2.
+This is the README file for 'pagerange' package, version 0.3.
 
 When a given page range xx-yy (simple/plain characters) or
 \pages (command token, eg, \def\pages{xx-yy}) is submitted to the macro
diff --git a/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.pdf b/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.pdf
index c73d3c0168a..c0e5e1e1767 100644
--- a/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.pdf
+++ b/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.pdf
diff --git a/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex b/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
index 6c1a330b496..db78f40c054 100644
--- a/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
+++ b/Master/texmf-dist/doc/latex/pagerange/pagerange-guide.tex
@@ -2,9 +2,12 @@
 \InputIfFileExists{pagerange-guide.cfg}{}{%
   \errmessage{No file pagerange-guide.cfg}}
 \pagestyle{fancyplain}
+
 \begin{document}
+\label{page:first}
+
 \MakeShortVerb{\+}
-\title{\textbf{The {\tt pagerange} Package}\\[1ex] Version 0.2}
+\title{\textbf{The {\tt pagerange} Package}\\[1ex] Version 0.3}
 \author{Ahmed Musa\\[.5ex]University of Central Lancashire\\
   Preston, United Kingdom\\[1ex]\email{a.musa@rocketmail.com}
 }
@@ -19,31 +22,32 @@ When a given page range +xx-yy+ (simple/plain characters) or +\pages+ (control s
 
 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.
+\item A range of the form ``+-34+'' is taken to mean pages +defaultfirstpage+ to 34. The default value of +defaultfirstpage+ is 1; it can be changed via +\pagerangeoptions+.
+\item A range of the form ``+12-+'' is taken to mean page~12 to +defaultlastpage+, where the default value of +defaultlastpage+ is the document's last page.
+\item A range of the form ``+-+'' (\ie, only hyphen and no pages) is taken to mean from +defaultfirstpage+ to +defaultlastpage+.
+\item An empty or blank page range (\ie, containing no argument and no hyphen/tie) is taken to mean the range +defaultfirstpage+ to +defaultlastpage+, or it may prompt a fatal error, depending on whether the boolean +acceptempty+ is set true or false (respectively).
 \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+.
+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=*}+. Active characters can't, unfortunately, be used as ties. The package easily terminates with a warning when an active character is passed as +tie+. It wouldn't be safe to change the catcode of an active character submitted as +tie+ through +\pagerangeoptions+, since at the time the macro +\pagerangeoptions+ is invoked, the page may already be in the process of being built.
 
 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+.
+This package has been tested with the +hyperref+ package, which redefines the label used by the +lastpage+ package.
 
-\section{Package options}
-The package has only three options, namely,
+\section{Package options}\label{sec:package-options}
+The package options are as follows:
 
-\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.\\
+\begin{tabularx}{\linewidth}{p{3cm}p{2.0cm}X}
+\hline
+\bf Option & \bf Default & \bf Meaning\\\hline
++tie+ & hyphen (+-+) & The tie that show the breakpoint for the page range.\\\hline
++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.\\\hline
++defaultfirstpage+ & +1+ & The default start page number, used as the starting page when no starting page number is specified by the user.\\\hline
++defaultlastpage+ & document's last page & The default last page number, used as the last page when no last page number is specified by the user.\\\hline
 \end{tabularx}
 
 \section{Examples}
@@ -99,42 +103,13 @@ The following
 \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\},}
-
-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-}
-\end{pverbatim}
-
-\pagerange{1-}
-yields \result{Pages~\pagestart\space to\space\pageend}.
-
-\pgexample{No hyperlinking of last page}
-In the following the value of +hyperlink+ is +false+:
-
-\begin{pverbatim}
-\pagerangeoptions{hyperlink=false}
-\pagerange{1-}
-\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{-}
 \end{pverbatim}
 
-\pagerangeoptions{hyperlink=true}
 \pagerange{-}
 \par\medskip\noindent
 produces \result{Pages~\pagestart\space to\space\pageend}.
@@ -146,6 +121,7 @@ The following logs a warning message or issues fatal error, depending on the sta
 \pagerange{}
 \end{pverbatim}
 
+%\pagerangeoptions{acceptempty}
 %\pagerange{}
 %Page~\pagestart\space to\space\pageend
 
@@ -295,8 +271,22 @@ The following
 \pagerange{2034X2135}
 correctly yields \result{Pages~\pagestart\space to\space\pageend}.
 
-\section{To-do}
+\section{Using page labels}
+
+From version 0.3 of the package, it has been possible to obtain page ranges from \LaTeX{} references, \eg, as in
+
+\begin{pverbatim}
+\label{page:label}
+\pagerangeoptions{tie=-}
+\let\getpage\getpagenumber
+\pagerange{\getpage{page:first}-\getpage{page:last}},
+\end{pverbatim}
+
+\label{page:last}
+\pagerangeoptions{tie=-}
+\pagerange{\getpagenumber{page:first}-\getpagenumber{page:last}}
+which yields \result{Pages~\pagestart\space to\space\pageend}.
 
-To provide for calls such as in +\pagerange{\pageref{page:label}-200}+.
+The command +\getpagenumber+ is provided in the package and may, in general, be used to convert page labels into page numbers even in expansion contexts, where +\pageref+ will normally fail. If the page label or reference is undefined, the default start page number (+defaultfirstpage+) is used. The +defaultfirstpage+ is a package option (see Section~\ref{sec:package-options}).
 
 \end{document} 
\ No newline at end of file