diff options
author | Karl Berry <karl@freefriends.org> | 2006-08-27 22:38:54 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-08-27 22:38:54 +0000 |
commit | 2607d53137ede06e9780342b225218743e100bb4 (patch) | |
tree | c6c88c805dd21a5bbb6ad6f26d3d53c517f4b866 /Master/texmf-dist/source/latex/oberdiek/zref.dtx | |
parent | fb0d58de45c0fc32bab09a839c186de46f75628e (diff) |
oberdiek update from tds zip (28aug06)
git-svn-id: svn://tug.org/texlive/trunk@2054 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/oberdiek/zref.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/oberdiek/zref.dtx | 3261 |
1 files changed, 3261 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/oberdiek/zref.dtx b/Master/texmf-dist/source/latex/oberdiek/zref.dtx new file mode 100644 index 00000000000..999d3372bfd --- /dev/null +++ b/Master/texmf-dist/source/latex/oberdiek/zref.dtx @@ -0,0 +1,3261 @@ +% \iffalse meta-comment +% +% Copyright (C) 2006 by Heiko Oberdiek <oberdiek@uni-freiburg.de> +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either +% version 1.3 of this license or (at your option) any later +% version. The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of +% LaTeX version 2005/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% +% This Current Maintainer of this work is Heiko Oberdiek. +% +% This work consists of the main source file zref.dtx +% and the derived files +% zref.sty, zref.pdf, zref.ins, zref.drv, +% zref-base.sty, zref-abspage.sty, zref-counter.sty, +% zref-dotfill.sty, zref-hyperref.sty, zref-lastpage.sty, +% zref-perpage.sty, zref-savepos.sty, zref-titleref.sty, +% zref-totpages.sty, zref-user.sty, zref-xr.sty, +% zref-example.tex. +% +% Distribution: +% CTAN:macros/latex/contrib/oberdiek/zref.dtx +% CTAN:macros/latex/contrib/oberdiek/zref.pdf +% +% Unpacking: +% (a) If zref.ins is present: +% tex zref.ins +% (b) Without zref.ins: +% tex zref.dtx +% (c) If you insist on using LaTeX +% latex \let\install=y\input{zref.dtx} +% (quote the arguments according to the demands of your shell) +% +% Documentation: +% (a) If zref.drv is present: +% latex zref.drv +% (b) Without zref.drv: +% latex zref.dtx; ... +% The class ltxdoc loads the configuration file ltxdoc.cfg +% if available. Here you can specify further options, e.g. +% use A4 as paper format: +% \PassOptionsToClass{a4paper}{article} +% +% Programm calls to get the documentation (example): +% pdflatex zref.dtx +% makeindex -s gind.ist zref.idx +% pdflatex zref.dtx +% makeindex -s gind.ist zref.idx +% pdflatex zref.dtx +% +% Installation: +% TDS:tex/latex/oberdiek/zref.sty +% TDS:tex/latex/oberdiek/zref-base.sty +% TDS:tex/latex/oberdiek/zref-abspage.sty +% TDS:tex/latex/oberdiek/zref-counter.sty +% TDS:tex/latex/oberdiek/zref-dotfill.sty +% TDS:tex/latex/oberdiek/zref-hyperref.sty +% TDS:tex/latex/oberdiek/zref-lastpage.sty +% TDS:tex/latex/oberdiek/zref-perpage.sty +% TDS:tex/latex/oberdiek/zref-savepos.sty +% TDS:tex/latex/oberdiek/zref-titleref.sty +% TDS:tex/latex/oberdiek/zref-totpages.sty +% TDS:tex/latex/oberdiek/zref-user.sty +% TDS:tex/latex/oberdiek/zref-xr.sty +% TDS:doc/latex/oberdiek/zref.pdf +% TDS:doc/latex/oberdiek/zref-example.tex +% TDS:source/latex/oberdiek/zref.dtx +% +%<*ignore> +\begingroup + \def\x{LaTeX2e} +\expandafter\endgroup +\ifcase 0\ifx\install y1\fi\expandafter + \ifx\csname processbatchFile\endcsname\relax\else1\fi + \ifx\fmtname\x\else 1\fi\relax +\else\csname fi\endcsname +%</ignore> +%<*install> +\input docstrip.tex +\Msg{************************************************************************} +\Msg{* Installation} +\Msg{* Package: zref 2006/05/25 v1.2 New reference scheme for LaTeX2e (HO)} +\Msg{************************************************************************} + +\keepsilent +\askforoverwritefalse + +\preamble + +This is a generated file. + +Copyright (C) 2006 by Heiko Oberdiek <oberdiek@uni-freiburg.de> + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either +version 1.3 of this license or (at your option) any later +version. The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of +LaTeX version 2005/12/01 or later. + +This work has the LPPL maintenance status "maintained". + +This Current Maintainer of this work is Heiko Oberdiek. + +This work consists of the main source file zref.dtx +and the derived files + zref.sty, zref.pdf, zref.ins, zref.drv, + zref-base.sty, zref-abspage.sty, zref-counter.sty, + zref-dotfill.sty, zref-hyperref.sty, zref-lastpage.sty, + zref-perpage.sty, zref-savepos.sty, zref-titleref.sty, + zref-totpages.sty, zref-user.sty, zref-xr.sty, + zref-example.tex. + +\endpreamble + +\generate{% + \file{zref.ins}{\from{zref.dtx}{install}}% + \file{zref.drv}{\from{zref.dtx}{driver}}% + \usedir{tex/latex/oberdiek}% + \file{zref.sty}{\from{zref.dtx}{package}}% + \file{zref-base.sty}{\from{zref.dtx}{base}}% + \file{zref-abspage.sty}{\from{zref.dtx}{abspage}}% + \file{zref-counter.sty}{\from{zref.dtx}{counter}}% + \file{zref-dotfill.sty}{\from{zref.dtx}{dotfill}}% + \file{zref-hyperref.sty}{\from{zref.dtx}{hyperref}}% + \file{zref-lastpage.sty}{\from{zref.dtx}{lastpage}}% + \file{zref-perpage.sty}{\from{zref.dtx}{perpage}}% + \file{zref-savepos.sty}{\from{zref.dtx}{savepos}}% + \file{zref-titleref.sty}{\from{zref.dtx}{titleref}}% + \file{zref-totpages.sty}{\from{zref.dtx}{totpages}}% + \file{zref-user.sty}{\from{zref.dtx}{user}}% + \file{zref-xr.sty}{\from{zref.dtx}{xr}}% + \usedir{doc/latex/oberdiek}% + \file{zref-example.tex}{\from{zref.dtx}{example}}% +} + +\obeyspaces +\Msg{************************************************************************} +\Msg{*} +\Msg{* To finish the installation you have to move the following} +\Msg{* files into a directory searched by TeX:} +\Msg{*} +\Msg{* zref.sty, zref-base.sty, zref-abspage.sty, zref-counter.sty,} +\Msg{* zref-dotfill.sty, zref-hyperref.sty, zref-lastpage.sty,} +\Msg{* zref-perpage.sty, zref-savepos.sty, zref-titleref.sty,} +\Msg{* zref-totpages.sty, zref-user.sty, zref-xr.sty} +\Msg{*} +\Msg{* To produce the documentation run the file `zref.drv'} +\Msg{* through LaTeX.} +\Msg{*} +\Msg{* Happy TeXing!} +\Msg{*} +\Msg{************************************************************************} + +\endbatchfile +%</install> +%<*ignore> +\fi +%</ignore> +%<*driver> +\NeedsTeXFormat{LaTeX2e} +\ProvidesFile{zref.drv}% + [2006/05/25 v1.2 New reference scheme for LaTeX2e (HO)] +\documentclass{ltxdoc} +\usepackage{holtxdoc} +\begin{document} + \DocInput{zref.dtx} +\end{document} +%</driver> +% \fi +% +% \CheckSum{1452} +% +% \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 \~} +% +% \GetFileInfo{zref.drv} +% +% \title{The \xpackage{zref} package} +% \date{2006/05/25 v1.2} +% \author{Heiko Oberdiek\\\xemail{oberdiek@uni-freiburg.de}} +% +% \maketitle +% +% \begin{abstract} +% Package \xpackage{zref} tries to get rid of the restriction +% in \LaTeX's reference system that only two properties are +% supported. The package implements an extensible referencing +% system, where properties are handled in a more flexible way. +% It offers an interface for macro programmers for the access +% to the system and some applications that uses the new +% reference scheme. +% \end{abstract} +% +% \tableofcontents +% +% \newcommand*{\metacs}[1]{\texttt{\itshape #1}} +% +% \newcommand{\markexp}{^^A +% \textsuperscript{exp}^^A +% \space +% } +% \newcommand{\markrobust}{^^A +% \textsuperscript{robust}^^A +% \space +% } +% \newcommand{\marknowarn}{^^A +% \textsuperscript{nowarn}^^A +% \space +% } +% \newcommand{\markbabel}{^^A +% \textsuperscript{babel}^^A +% \space +% } +% +% \section{Introduction} +% +% Standard \LaTeX's reference system with \cs{label}, \cs{ref}, +% and \cs{pageref} supports two properties, the apperance of +% the counter that is last incremented by \cs{refstepcounter} and +% the page with the \cs{label} command. +% +% Unhappily \LaTeX\ does not provide an interface for adding +% another properties. Packages such as \xpackage{hyperref}, +% \xpackage{nameref}, or \xpackage{titleref} are forced to +% use ugly hacks to extend the reference system. +% These ugly hacks are one of the causes for \xpackage{hyperref}'s +% difficulty regarding compatibility with other packages. +% +% \subsection{Standard \LaTeX\ behaviour} +% +% References are created by the \cs{label} command: +% \begin{quote} +% |\chapter{Second chapter}|\\ +% |\section{First section on page 7} % section 2.1|\\ +% |\label{myref}| +% \end{quote} +% Now \LaTeX\ records the section number |2.1| and the page |7| +% in the reference. Internally the reference is a list with +% two entries: +% \begin{quote} +% |\r@myref| $\rightarrow$ |{2.1}{7}| +% \end{quote} +% The length of the list if fixed in the \LaTeX\ kernel, +% An interface for adding new properties is missing. +% +% There are several tries to add new properties: +% \begin{description} +% \item[\xpackage{hyperref}] uses a list of five +% properties instead of the standard list with two entries. +% This causes many compatibility problems with \LaTeX\ and +% other packages. +% \item[\xpackage{titleref}] stores its title data into the +% first entry in the list. \LaTeX\ is happy because it +% does only see its list with two entries. The situation +% becomes more difficult, if more properties are added +% this way. Then the macros form a nested structure +% inside the first reference argument for the label. +% Expandable extractions will then become painful. +% \end{description} +% +% \subsection{Basic idea} +% +% Some time ago Morten H\o gholm sent me an experimental +% cross referencing mechanism as ``expl3'' code. His +% idea is: +% \begin{quote} +% |\g_xref_mylabel_plist| $\rightarrow$\\ +% \mbox{}\qquad|\xref_dance_key{salsa}\xref_name_key{Morten}|\dots +% \end{quote} +% The entries have the following format: +% \begin{quote} +% |\xref_|\meta{your key}|_key{|\meta{some text}|}| +% \end{quote} +% This approach is much more flexible: +% \begin{itemize} +% \item New properties can easily be added, just use a new key. +% \item The length of the list is not fixed. A reference +% can use a subset of the keys. +% \item The order of the entries does not matter. +% \end{itemize} +% Unhappily I am not familiar with the experimental code +% for \LaTeX3 that will need some time before its first release. +% Thus I have implemented it as \LaTeXe\ package without disturbing +% the existing \LaTeX\ reference system. +% +% \subsection{Interfaces} +% +% The package provides a generic \emph{interface for programmers}. +% Commands of this interface are prefixed by \cs{zref@}. +% +% Option \xoption{user} enabels the \emph{user interface}. +% Here the commands are prefixed by \cs{z} to avoid name +% clashes with existing macros. +% +% Then the packages provides some \emph{modules}. They +% are applications for the reference system and can also be +% considered as examples how to use the reference system. +% +% The modules can be loaded as packages. The package +% name is prefixed with |zref-|, for example: +%\begin{quote} +%\begin{verbatim} +%\RequirePackage{zref-abspage} +%\end{verbatim} +%\end{quote} +% This is the preferred way if the package is loaded from +% within other packages to avoid option clashes. +% +% As alternative package |zref| can be used and the modules +% are given as options: +%\begin{quote} +%\begin{verbatim} +%\usepackage[perpage,user]{zref} +%\end{verbatim} +%\end{quote} +% +% \section{Interface for programmers} +% +% The user interface is described in the next section \ref{sec:user}. +% +% \subsection{Entities} +% +% \paragraph{Reference.} +% Internally a reference is a list of key value pairs: +% \begin{quote} +% |\Z@R@myref| $\rightarrow$ +% |\default{2.1}\page{7}| +% \end{quote} +% The generic format of a entry is: +% \begin{quote} +% |\Z@R@|\meta{refname} $\rightarrow$ +% |\|\meta{propname}|{|\meta{value}|}| +% \end{quote} +% \meta{refname} is the name that denoted references +% (the name used in \cs{label} and \cs{ref}). \meta{propname} +% is the name of the property or key. The property key macro +% is never executed, it is used in parameter text matching only. +% +% \paragraph{Property.} +% Because the name of a property is used in a macro name +% that must survive the \xfile{.aux} file, the name is +% restricted to letters and `@'. +% +% \paragraph{Property list.} +% Often references are used for special purposes. Thus it +% saves memory if just the properties are used in this +% reference that are necessary for its purpose. +% +% Therefore this package uses the concept of \emph{property lists}. +% A property list is a set of properties. The set of properties +% that is used by the default \cs{label} command is the +% \emph{main property list}. +% +% \subsection{Property list} +% +% \markexp means that the implementation of the +% marked macro is expandable. +% +% \begin{declcs}{zref@newlist} +% \M{listname} +% \end{declcs} +% Declares a new empty property list. +% +% \begin{declcs}{zref@addprop} +% \M{listname} \M{propname} +% \end{declcs} +% Adds the property \meta{propname} to the property list \meta{listname}. +% The property and list must exist. +% +% \begin{declcs}{zref@listexists} +% \M{listname} \M{then} +% \end{declcs} +% Executes \meta{then} if the property list \meta{listname} exists +% or raise an error otherwise. +% +% \begin{declcs}{zref@iflistundefined}\markexp \M{listname} +% \M{then} \M{else} +% \end{declcs} +% Executes \meta{then} if the list exists or \meta{else} +% otherwise. +% +% \begin{declcs}{zref@iflistcontainsprop} +% \M{listname} \M{propname} \M{then} \M{else} +% \end{declcs} +% Executes \meta{then} if the property \meta{propname} is part +% of property list \meta{listname} or otherwise it +% runs the \meta{else} part. +% +% \subsection{Property} +% +% \begin{declcs}{zref@newprop} +% \* \M{propname} |[|\meta{default}|]| \M{value} +% \end{declcs} +% This command declares and configures a new property with +% name \meta{propname}. +% +% In case of unknown references +% or the property does not exist in the reference, the +% \meta{default} is used as value. If it is not specified +% here, a global default is used, see \cs{zref@setdefault}. +% +% The correct values of some properties are not known +% immediately but at page shipout time. Prominent example +% is the page number. These properties are declared with +% the star form of the command. +% +% \begin{declcs}{zref@setcurrent} +% \M{propname} \M{value} +% \end{declcs} +% This sets the current value of the property \meta{propname}. +% It is a generalization of setting \LaTeX's \cs{currentlabel}. +% +% \begin{declcs}{zref@propexists} +% \M{propname} \M{then} +% \end{declcs} +% Calls \meta{then} if the property \meta{propname} is available +% or generates an error message otherwise. +% +% \begin{declcs}{zref@ifpropundefined}\markexp +% \M{propname} \M{then} \M{else} +% \end{declcs} +% Calls \meta{then} or \meta{else} depending on the existence +% of property \meta{propname}. +% +% \subsection{Reference generation} +% +% \begin{declcs}{zref@label} +% \M{refname} +% \end{declcs} +% This works similar to \cs{label}. The reference \meta{refname} is +% created and put into the \xfile{.aux} file with the +% properties of the main property list. +% +% \begin{declcs}{zref@labelbylist} +% \M{refname} \M{listname} +% \end{declcs} +% Same as \cs{zref@label} except that the properties are +% taken from the specified property list \meta{listname}. +% +% \begin{declcs}{zref@labelbyprops} +% \M{refname} |{|\meta{propnameA}|,|\meta{propnameB}|,|\dots|}| +% \end{declcs} +% Same as \cs{zref@label} except that these properties +% are used that are given as comma separated list in the +% second argument. +% +% \begin{declcs}{zref@newlabel} +% \M{refname} |{|\dots|}| +% \end{declcs} +% This is the macro that is used in the \xfile{.aux} file. +% It is basically the same as \cs{newlabel} apart from +% the format of the data in the second argument. +% +% \subsection{Data extraction} +% +% \begin{declcs}{zref@extractdefault}\markexp +% \M{refname} \M{propname} \M{default} +% \end{declcs} +% This is the basic command that refernces the value of a +% property \meta{propname} for the reference \meta{refname}. +% In case of errors such as undefined reference the \meta{default} +% is used instead. +% +% \begin{declcs}{zref@extract}\markexp +% \M{refname} \M{propname} +% \end{declcs} +% The command is an abbreviation for \cs{zref@extractdefault}. +% As default the default of the property is taken, otherwise +% the global default. +% +% Example for page references: +% \begin{quote} +% \begin{tabular}{@{}ll} +% \LaTeX:& |\pageref{foobar}|\\ +% \xpackage{zref}:& |\zref@extract{foobar}{page}| +% \end{tabular} +% \end{quote} +% Both \cs{zref@extract} and \cs{zref@extractdefault} are +% expandable. That means, these macros can directly +% be used in expandable calculations, see the example file. +% On the other side, babel's shorthands are not supported, +% there are no warnings in case of undefined references. +% +% If an user interface doesn't need expandable macros +% then it can use \cs{zref@used} and \cs{zref@wrapper@babel} +% for its user macros. +% +% \begin{declcs}{zref@used} +% \M{refname} +% \end{declcs} +% This command is not expandable. It causes the warnings if +% the reference \meta{refname} is not defined. Use the +% \cs{zref@extract} commands inside expandable contexts and +% mark their use outside by \cs{zref@used}, see the example +% file. +% +% \begin{declcs}{zref@ifrefundefined}\markexp +% \M{refname} \M{then} \M{else} +% \end{declcs} +% A possibility to check whether a reference exists. +% +% \begin{declcs}{zref@ifrefcontainsprop}\markexp +% \M{refname} \M{propname} \M{then} \M{else} +% \end{declcs} +% Test whether a reference provides a property. +% +% \subsection{Setup} +% +% \begin{declcs}{zref@default} +% \end{declcs} +% Holds the global default for unknown values. +% +% \begin{declcs}{zref@setdefault} +% |{|\meta{value}|}| +% \end{declcs} +% Sets the global default for unknown values. +% The global default is used, if a property does not specify +% an own default and the value for a property +% cannot be extracted. This can happen if the reference is +% unknown or the reference does not have the property. +% +% \begin{declcs}{zref@setmainlist} +% |{|\meta{value}|}| +% \end{declcs} +% Sets the name of the main property list. The package +% sets and uses |main|. +% +% \subsection{Declared properties} +% +% \begin{quote} +% \renewcommand*{\arraystretch}{1.05} +% \setlength{\tabcolsep}{2\tabcolsep} +% \def\VV{\vphantom{\large \"Ag}} +% \def\EMPTY{{\itshape\textless empty\textgreater}} +% \begin{tabular}{@{}>{\sffamily}l|>{\ttfamily}l|>{\ttfamily}l|>{\ttfamily}l@{}} +% \rmfamily Modul& +% \rmfamily Property& +% \rmfamily Property list& +% \rmfamily Default\\ +% \hline +% & default & main & \EMPTY\\ +% & page & main & \EMPTY\\ +% \hline +% abspage\textrm{, }totpages & abspage & main & 0\\ +% \hline +% perpage & pagevalue & perpage & 0\\ +% & page & perpage & \EMPTY\\ +% & abspage & perpage & 0\\ +% \hline +% counter & counter & main & \EMPTY\\ +% \hline +% titleref & title & main & \EMPTY\\ +% \hline +% savepos & posx & savepos & 0\\ +% & posy & savepos & 0\\ +% \hline +% hyperref & anchor & main & \EMPTY\\ +% & url & & \EMPTY\\ +% \hline +% xr & url & & \EMPTY\\ +% \end{tabular} +% \end{quote} +% +% \subsection{Wrapper for advanced situations} +% +% \begin{declcs}{zref@wrapper@babel} +% |{|\dots|}| \M{name} +% \end{declcs} +% This macro helps to add shorthand support. The second +% argument is protected, then the code of the first argument +% is called with the protected name appended. Examples +% are in the sources. +% +% \begin{declcs}{zref@wrapper@immediate} +% |{|\dots|}| +% \end{declcs} +% There are situations where a label must be written instantly +% to the \xfile{.aux} file, for example after the last page. +% If the \cs{label} command is put inside this wrapper, +% immediate writing is enabled. See the implementation for +% option \xoption{lastpage}. +% +% \begin{declcs}{zref@wrapper@unexpanded} +% |{|\dots|}| +% \end{declcs} +% Assuming someone wants to extract a value for property |bar| +% and store the result in a macro |\foo| without traces of +% the expanding macros and without expanding the value. +% This (theoretical?) problem can be solved by this wrapper: +% \begin{quote} +%\begin{verbatim} +%\edef\foo{% +% \zref@wrapper@unexpanded{% +% \zref@extract{someref}{bar}% +% }% +%} +%\end{verbatim} +% \end{quote} +% The \cs{edef} forces the expansion of \cs{zref@extract}, +% but the extraction of the value is prevented by +% the wrapper that uses \eTeX'\ \cs{unexpanded} for this +% purpose. +% +% \subsection{Counter for unique names} +% +% Some modules (\xoption{titleref} and \xoption{dotfillmin}) +% need unique names for automatically generated label names. +% +% \begin{declcs}{zref@require@unique} +% \end{declcs} +% This command creates the unique counter |zref@unique| if the +% counter does not already exist. +% +% \begin{declcs}{thezref@unique} +% \end{declcs} +% This command is used to generate unique label names. +% +% \section{User interface}\label{sec:user} +% +% \subsection{Module \xoption{user}} +% +% The user interface for this package and its modules +% is enabled by \xpackage{zref}'s package option \xoption{user} +% or package \xpackage{zref-user}. +% The names of user commands are prefixed by |z| in order +% to avoid name clashes with existing macros of the same +% functionality. Thus the package does not disturb the +% traditional reference scheme, both can be used together. +% +% The syntax descriptions contain the following markers +% that are intended as hints for programmers: +% \begin{quote} +% \begin{tabular}{@{}ll@{}} +% \markbabel\unskip & Babel shorthands are allowed.\\ +% \markrobust\unskip & Robust macro.\\ +% \markexp\unskip & Expandable version:\\ +% & \textbullet\ robust, +% unless the extracted values are fragile,\\ +% & \textbullet\ no babel shorthand suport. +% \end{tabular} +% \end{quote} +% +% The basic user interface of the package without modules +% are commands that mimic the standard \LaTeX\ behaviour +% of \cs{label}, \cs{ref}, and \cs{pageref}: +% +% \begin{declcs}{zlabel} +% \M{refname}\markbabel +% \end{declcs} +% Similar to \cs{label}. It generates a label with name +% \meta{refname} in the new reference scheme. +% +% \begin{declcs}{zref} +% |[|\meta{propname}|]| \M{refname}\markbabel +% \end{declcs} +% Without optional argument similar to \cs{ref}, it returns +% the default reference property. This property is named +% |default|: +% \[ +% |\zref{|x|}| \equiv |\zref[default]{|x|}| +% \] +% +% \begin{declcs}{zpageref} +% \M{refname}\markbabel +% \end{declcs} +% Convenience macro, similar to \cs{pageref}. +% \[ +% |\zpageref{|x|}| \equiv |\zref[page]{|x|}| +% \] +% +% \begin{declcs}{zrefused} +% \M{refname}\markbabel +% \end{declcs} +% Some of the user commands in the modules are expandable. +% The use of such commands do not cause any undefined +% reference warnings, because inside of expandable +% contexts this is not possible. However, if there is +% a place outside of expandable contexts, \cs{refused} +% is strongly recommended. The reference \meta{refname} +% is marked as used, undefined ones will generate +% warnings. +% +% \subsection{Module \xoption{abspage}} +% +% With the help of package \xpackage{everyshi} (\cite{everyshi}) +% a new counter |abspage| with absolute page numbers is provided. +% Also a new property |abspage| is defined and added to the +% main property list. Thus you can reference the absolute +% page number: +% \begin{quote} +% |Section \zref{foo} is on page \zpageref{foo}.|\\ +% |This is page \zref[abspage]{foo} of \zref[abspage]{LastPage}.| +% \end{quote} +% The example also makes use of option \xoption{lastpage}. +% +% \subsection{Module \xoption{lastpage}} +% +% Provides the functionality of package \xpackage{lastpage} +% (\cite{lastpage}) in the new reference scheme. +% The label |LastPage| is put at the end of the document. +% You can refer the last page number with: +% \begin{quote} +% |\zpageref{LastPage}| +% \end{quote} +% +% \subsection{Module \xoption{totpages}} +% +% For the total number of pages of a document you need to +% know the absolute page number of the last page. +% Both options \xoption{abspage} and \xoption{lastpage} +% are necessary and automatically enabled. +% +% \begin{declcs}{ztotpages}\markexp +% \end{declcs} +% Prints the total number of pages or |0| if this +% number is not yet known. This command can also used +% in calculations or counter assignments. +% +% \subsection{Module \xoption{perpage}} +% +% With \cs{@addtoreset} or \cs{numberwithin} a counter can be +% reset if another counter is incremented. This do not work +% well if the other counter is the page counter. The page counter is +% incremented in the output routine that is often called asynchronous +% somewhere on the next page. A reference mechanism costs at least +% two \LaTeX\ runs, but ensures correct page counter values. +% +% \begin{declcs}{zmakeperpage} +% |[|\meta{reset}|]| \M{counter} +% \end{declcs} +% At the of a new page counter \meta{counter} starts +% counting with value \meta{reset} (default is \texttt{1}). +% The macro has the same +% syntax and semantics as \cs{MakePerPage} of package +% \xpackage{perpage} (\cite{perpage}). +% Also \xoption{perpage} of package \xpackage{footmisc} (\cite{footmisc}) +% can easily be simulated by +% \begin{quote} +% |\zmakeperpage{footnote}| \itshape |% \usepackage[perpage]{footmisc}| +%\end{quote} +% If footnote symbols are used, some people dislike the +% first symbol \ensuremath{\dagger}. It can easily be skipped: +% \begin{quote} +% |\zmakeperpage[2]{footnote}| +% \end{quote} +% +% \begin{declcs}{thezpage}\\ +% counter |zpage| +% \end{declcs} +% If the formatted counter value of the counter that is reset at +% a new page contains the page value, then you can use \cs{thezpage}, +% the page number of the current page. Or counter |zpage| can be +% used, if the page number should be formatted differently from +% the current page number. Example: +%\begin{quote} +%\begin{verbatim} +%\newcounter{foobar} +%\zmakeperpage{foobar} +%\renewcommand*{\thefoobar}{\thezpage-\arabic{foobar}} +% % or +%\renewcommand*{\thefoobar}{\roman{zpage}-\arabic{foobar}} +%\end{verbatim} +%\end{quote} +% +% \begin{declcs}{zunmakeperpage} +% \M{counter} +% \end{declcs} +% The reset mechanism for this counter is deactivated. +% +% +% \subsection{Module \xoption{counter}} +% +% This option just add the property |counter| to the main +% property list. The property stores the counter name, +% that was responsible for the reference. This is the +% property \xpackage{hyperref}'s \cs{autoref} feature +% uses. Thus this property |counter| may be useful +% for a reimplementation of the autoref feature, +% see the section \ref{sec:todo} with the todo list. +% +% \subsection{Module \xoption{titleref}} +% +% This option makes section and caption titles available +% to the reference system similar to packages \xpackage{titleref} +% or \xpackage{nameref}. +% +% \begin{declcs}{ztitleref} +% \M{refname}\markbabel +% \end{declcs} +% Print the section or caption title of reference \meta{refname}, +% similar to \cs{nameref} or \cs{titleref}. +% +% \begin{declcs}{ztitlerefsetup} +% |{|\textit{key$_1$=value$_1$, key$_2$=value$_2$, \dots}|}| +% \end{declcs} +% This command allows to configure the behaviour of modul +% \xoption{titleref}. The following keys are available: +% \begin{description} +% \let\bfseries\relax +% \item[\texttt{title=}\meta{value}]\mbox{}\\* +% Sets the current title. +% \item[\texttt{stripperiod=true\string|false}]\mbox{}\\* +% Follow package \xpackage{nameref} that +% removes a last period. Default: |true|. +% \item[\texttt{expand=true\string|false}]\mbox{}\\* +% Package \cs{titleref} expands the title first. This way +% garbage and dangerous commands can be removed, e.g. +% \cs{label}, \cs{index}\dots. See implementation section +% for more details. Default is |false|. +% \item[\texttt{cleanup=\{}\textrm{\dots}\texttt{\}}]\mbox{}\\* +% Hook to add own cleanup code, if method |expand| is used. +% See implementation section for more details. +% \end{description} +% +% \subsection{Module \xoption{savepos}} +% +% This option supports a feature that \pdfTeX\ provides. +% \pdfTeX\ is able to tell the current position on the +% page. The page position is not instantly known. First the +% page must be constructed by \TeX's asynchronous output +% routine. Thus the time where the position is known is +% the page shipout time. Thus a reference system where the +% information is recorded in the first run and made available +% for use in the second run comes in handy. +% +% \begin{declcs}{zsavepos} +% \M{refname} +% \end{declcs} +% It generates a reference with name \meta{refname} to +% the location where the command is executed. +% +% \begin{declcs}{zposx}\markexp +% \M{refname}\\ +% \SpecialUsageIndex{\zposy}\cs{zposy}\markexp \M{refname} +% \end{declcs} +% Get the position as number. Unit is sp. Horizontal +% positions by \cs{zposx} increase from left to right. +% Vertical positions by \cs{zposy} from bottom to top. +% +% Do not rely on absolute page numbers. Because of problems +% with the origin the numbers may differ in DVI or PDF mode +% of \pdfTeX. Therefore work with relative values by comparisons. +% +% Both \cs{zposx} and \cs{zposy} are expandable and can be +% used inside calculations (\cs{setcounter}, \cs{addtocounter}, +% package \xpackage{calc}, \cs{numexpr}). However this property +% prevents from notifying \LaTeX\ that the reference is actually +% used (the notifying is not expandable). Therefore you should +% mark the reference as used by \cs{zrefused}. +% +% This module uses \pdfTeX's \cs{pdfsavepos}, \cs{pdflastxpos}, +% and \cs{pdflastypos}. They are available in PDF mode and +% since version 1.40.0 also in DVI mode. +% +% \subsection{Module \xoption{dotfill}} +% +% \begin{declcs}{zdotfill} +% \end{declcs} +% This package provides the command \cs{zdotfill} that works +% similar to \cs{dotfill}, but can be configured. Especially +% it suppresses the dots if a minimum number of dots cannot be set. +% +% \begin{declcs}{zdotfillsetup} +% |{|\textit{key$_1$=value$_1$, key$_2$=value$_2$, \dots}|}| +% \end{declcs} +% This command allows to configure the behaviour of \cs{zdotfill}. +% The following keys are available: +% \begin{description} +% \let\bfseries\relax +% \item[\texttt{min=}\meta{count value}]\mbox{}\\* +% If the actual number of dots are smaller than \meta{count value}, +% then the dots are suppressed. Default: |2|. +% \item[\texttt{unit=}\meta{dimen value}]\mbox{}\\* +% The width of a dot unit is given by \meta{dimen value}. +% Default: |0.44em| (same as the unit in \cs{dotfill}). +% \item[\texttt{dot=}\meta{value}]\mbox{}\\* +% The dot itself is given by \meta{value}. Default: |.| (dot, same as +% the dot in \cs{dotfill}). +% \end{description} +% +% \subsection{Module \xoption{xr}} +% +% This package provides the functionality of package \xpackage{xr}, +% see \cite{xr}. It also supports the syntax of \xpackage{xr-hyper}. +% +% \begin{declcs}{zexternaldocument} +% \* |[|\meta{prefix}|]|\markbabel \M{external document} +% |[|\meta{url}|]| +% \end{declcs} +% See \cs{externaldocument} for a description of this option. +% The standard reference scheme and the scheme of this +% package use different name spaces for reference names. +% If the external document uses both systems. Then one +% import statement would put the names in one namespace +% and probably causing problems with multiple references +% of the same name. Thus the star form only looks for +% \cs{newlabel} in the \xfile{.aux} files, whereas without +% star only \cs{zref@newlabel}s are used. +% +% In the star form it tries to detect labels from +% \xpackage{hyperref}, \xpackage{titleref}, and \xpackage{ntheorem}. +% If such an extended property from the packages before cannot +% be found or are empty, they are not included in the +% imported reference. +% +% Warnings are given if a reference name is already in use +% and the item is ignored. Unknown properties will automatically +% be declared. +% +% If the external references contain |anchor| properties, +% then we need also a url to be able to address the external +% file. As default the filename is taken with a default +% extension. +% +% \begin{declcs}{zxrsetup} +% |{|\textit{key$_1$=value$_1$, key$_2$=value$_2$, \dots}|}| +% \end{declcs} +% Currently the key |ext| is defined, this sets the +% url default extension. +% +% \begin{declcs}{zref@xr@ext} +% \end{declcs} +% If the \meta{url} is not specified in \cs{zref@externaldocument}, +% then the url will be constructed with the file name and +% this macro as extension. \cs{XR@ext} is used if +% \xpackage{hyperref} is loaded, otherwise |pdf|. +% +% +% \section{ToDo}\label{sec:todo} +% +% Among other things the following issues are left for future work: +% \begin{itemize} +% \item +% The user land macros are not checked for robustness yet. +% They can be fragile. If this happens, use \cs{protect} +% until a later version of this package. The \cs{protect} +% will not disturb, if the protected macro become robust +% in the future. +% \item Other applications: autoref, hyperref, \dots +% \end{itemize} +% +% \section{Example} +% +% \begin{macrocode} +%<*example> +% \end{macrocode} +% +% \begin{macrocode} +\documentclass{book} + +\usepackage[ngerman]{babel}% + +\usepackage[savepos,totpages,titleref,dotfill,counter,user]{zref} + +% \end{macrocode} +% +% Chapters are wrapped inside \cs{ChapterStart} and +% \cs{ChapterStop}. The first argument \verb|#1| of \cs{ChapterStart} +% is used to form a label id \verb|chap:#1|. At the end of +% the chapter another label is set by \cs{zref@wrapper@immediate}, because +% otherwise at the end of document a deferred write would not +% be written, because there is no page for shipout. +% +% Also this example shows how chapter titles can be recorded. +% A new property \verb|chaptitle| is declared and added to the +% main property list. In \cs{ChapterStart} the current value +% of the property is updated. +% \begin{macrocode} +\makeatletter +\zref@newprop{chaptitle}{} +\zref@addprop{main}{chaptitle} + +\newcommand*{\ChapterStart}[2]{% + \cleardoublepage + \def\current@chapid{#1}% + \zref@setcurrent{chaptitle}{#2}% + \chapter{#2}% + \zlabel{chap:#1}% +} +\newcommand*{\ChapterStop}{% + \cleardoublepage + \zref@wrapper@immediate{% + \zref@labelbyprops{chapend:\current@chapid}{abspage}% + }% +} +% \end{macrocode} +% \cs{ChapterPages} calculates and returns the number of pages of the +% referenced chapter. +% \begin{macrocode} +\newcommand*{\ChapterPages}[1]{% + \zrefused{chap:#1}% + \zrefused{chapend:#1}% + \number\numexpr + \zref@extract{chapend:#1}{abspage}% + -\zref@extract{chap:#1}{abspage}% + +1\relax +} +\makeatother +% \end{macrocode} +% \begin{macrocode} +\begin{document} +% \end{macrocode} +% As exception we use \cs{makeatletter} here, because +% this is just an example file that also should show some of +% programmer's interface. +% \begin{macrocode} +\makeatletter + +\frontmatter +\zlabel{documentstart} + +\begin{itemize} +\item + The frontmatter part has + \number\numexpr\zref@extract{chap:first}{abspage}-1\relax~pages. +\item + Chapter \zref{chap:first} has \ChapterPages{first} page(s). +\item + Section \zref{hello} is on the + \ifcase\numexpr + \zref@extractdefault{hello}{page}{0}% + -\zref@extractdefault{chap:first}{page}{0}% + +1\relax + ??\or first\or second\or third\or forth\fi + ~page inside its chapter. +\item + The document has + \zref[abspage]{LastPage} pages. + This number is \ifodd\ztotpages odd\else even\fi. +\item + The last page is labeled with \zpageref{LastPage}. +\item + The title of chapter \zref{chap:next} is ``\zref[chaptitle]{chap:next}''. +\end{itemize} + +\tableofcontents + +\mainmatter +\ChapterStart{first}{First chapter} + +% \end{macrocode} +% The user level commands should protect babel shorthands +% where possible. On the other side, expandable extracting +% macros are useful in calculations, see above the +% examples with \cs{numexpr}. +% \begin{macrocode} +\section{Test} +\zlabel{a"o} +Section \zref{a"o} on page +\zref@wrapper@babel\zref@extract{a"o}{page}. + +Text. +\newpage + +\section{Hello World} +\zlabel{hello} + +\ChapterStop + +\ChapterStart{next}{Next chapter with \emph{umlauts}: "a"o"u"s} + +% \end{macrocode} +% +% Here an example follows that makes use of \pdfTeX's ``savepos'' +% feature. The position on the page is not known before the +% page is constructed and shipped out. Therefore the position +% ist stored in references and are available for calculations +% in the next \LaTeX\ compile run. +% \begin{macrocode} +The width of the first column is + \the\dimexpr \zposx{secondcol}sp - \zposx{firstcol}sp\relax,\\ +the height difference of the two baselines is + \the\dimexpr \zposy{firstcol}sp - \zposy{secondline}sp\relax:\\ +\begin{tabular}{ll} +\zsavepos{firstcol}Hello&\zsavepos{secondcol}World\\ +\zsavepos{secondline}Second line&foobar\\ +\end{tabular} + +% \end{macrocode} +% With \cs{zrefused} \LaTeX\ is notified, if the references +% are not yet available and \LaTeX\ can generate the rerun +% hint. +% \begin{macrocode} +\zrefused{firstcol} +\zrefused{secondcol} +\zrefused{secondline} + +\ChapterStop +% \end{macrocode} +% Test for module \cs{dotfill}. +% \begin{macrocode} +\ChapterStart{dotfill}{Test for dotfill feature} +\newcommand*{\dftest}[1]{% + #1& + [\makebox[#1]{\dotfill}]& + [\makebox[#1]{\zdotfill}]\\ +} +\begin{tabular}{rll} +& [\verb|\dotfill|] & [\verb|\zdotfill|]\\ +\dftest{0.43em} +\dftest{0.44em} +\dftest{0.45em} +\dftest{0.87em} +\dftest{0.88em} +\dftest{0.89em} +\dftest{1.31em} +\dftest{1.32em} +\dftest{1.33em} +\end{tabular} +\ChapterStop +\end{document} +% \end{macrocode} +% +% \begin{macrocode} +%</example> +% \end{macrocode} +% +% \StopEventually{ +% } +% +% \section{Implementation} +% +% \subsection{Package \xpackage{zref}} +% +% \subsubsection{Identification} +% +% \begin{macrocode} +%<*package> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref} + [2006/05/25 v1.2 New reference scheme for LaTeX2e (HO)] +% \end{macrocode} +% +% \subsubsection{Load basic module} +% +% \begin{macrocode} +\RequirePackage{zref-base}[2006/05/25] +% \end{macrocode} +% Abort package loading if \xpackage{zref-base} could not be +% loaded successfully. +% \begin{macrocode} +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% \subsubsection{Process options} +% +% Known modules are loaded and the release date is checked. +% \begin{macrocode} +\def\ZREF@temp#1{% + \DeclareOption{#1}{% + \AtEndOfPackage{% + \RequirePackage{zref-#1}[2006/05/25]% + }% + }% +} +\ZREF@temp{abspage} +\ZREF@temp{counter} +\ZREF@temp{dotfill} +\ZREF@temp{hyperref} +\ZREF@temp{lastpage} +\ZREF@temp{perpage} +\ZREF@temp{savepos} +\ZREF@temp{titleref} +\ZREF@temp{totpages} +\ZREF@temp{user} +\ZREF@temp{xr} +% \end{macrocode} +% \begin{macrocode} +\ProcessOptions\relax +%</package> +% \end{macrocode} +% +% +% \subsection{Module base} +% +% \subsubsection{Prefixes} +% +% This package uses the following prefixes for macro names: +% \begin{description} +% \item[\cs{zref@}:] Macros of the programmer's interface. +% \item[\cs{ZREF@}:] Internal macros. +% \item[\cs{Z@L@}\metacs{listname}:] +% The properties of the list \meta{listname}. +% \item[\cs{Z@D@}\metacs{propname}:] +% The default value for property \meta{propname}. +% \item[\cs{Z@E@}\metacs{propname}:] +% Extract function for property \meta{propname}. +% \item[\cs{Z@X@}\metacs{propname}:] +% Information whether a property value for property +% \meta{propname} is expanded +% immediately or at shipout time. +% \item[\cs{Z@C@}\metacs{propname}:] +% Current value of the property \meta{propname}. +% \item[\cs{Z@R@}\metacs{labelname}:] +% Data for reference \meta{labelname}. +% \item[\cs{ZREF@org@}:] Original versions of patched commands. +% \item[\cs{z}:] For macros in user land, defined if +% option \xoption{user} is set. +% \end{description} +% The following family names are used for keys defined +% according to the \xpackage{keyval} package: +% \begin{description} +% \item[\texttt{ZREF@TR}:] Setup for \xoption{titleref}. +% \end{description} +% +% \subsubsection{Identification} +% +% \begin{macrocode} +%<*base> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-base}% + [2006/05/25 Module base for zref (HO)] +% \end{macrocode} +% +% \subsubsection{Utilities} +% +% \begin{macro}{\ZREF@name} +% Several times the package name is used, thus we store it +% in \cmd{\ZREF@name}. +% \begin{macrocode} +\def\ZREF@name{zref} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@ErrorNoLine} +% An error message for this package without line information is +% generated by \cs{ZREF@ErrorNoLine} +% \begin{macrocode} +\def\ZREF@ErrorNoLine#1#2{% + \begingroup + \let\on@line\@empty + \PackageError\ZREF@name{#1}{#2}% + \endgroup +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@UpdatePdfTeX} +% \cs{ZREF@UpdatePdfTeX} is used as help message text in +% error messages. +% \begin{macrocode} +\def\ZREF@UpdatePdfTeX{Update pdfTeX.} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ifZREF@found} +% The following switch is usded in list processing. +% \begin{macrocode} +\newif\ifZREF@found +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@patch} +% Macro \cs{ZREF@patch} first checks the existence of +% the command and safes it. +% \begin{macrocode} +\def\ZREF@patch#1{% + \begingroup\expandafter\expandafter\expandafter\endgroup + \expandafter\ifx\csname #1\endcsname\relax + \expandafter\@gobble + \else + \expandafter\let\csname ZREF@org@#1\expandafter\endcsname + \csname #1\endcsname + \expandafter\@firstofone + \fi +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Check for \eTeX} +% +% The use of \eTeX\ should be standard nowadays for \LaTeX. +% We test for \eTeX\ in order to use its features later. +% \begin{macrocode} +\begingroup + \@ifundefined{eTeXversion}{% + \ZREF@ErrorNoLine{% + Missing support for eTeX; package is abandoned% + }{% + Use a TeX compiler that support eTeX and enable eTeX % + in the format.% + }% + \endgroup + \endinput + }{} +\endgroup +% \end{macrocode} +% +% \subsubsection{Auxiliary file stuff} +% +% We are using some commands in the \xfile{.aux} files. +% However sometimes these auxiliary files are interpreted +% by \LaTeX\ processes that haven't loaded this package +% (e.g. package \xpackage{xr}). +% Therefore we provide dummy definitions. +% \begin{macrocode} +\RequirePackage{auxhook} +\AddLineBeginAux{% + \string\providecommand\string\zref@newlabel[2]{}% +} +% \end{macrocode} +% \begin{macro}{\zref@newlabel} +% For the implementation of \cs{zref@newlabel} we call +% the same internal macro \cs{@newl@bel} that is used +% in \cs{newlabel}. Thus we have for free: +% \begin{itemize} +% \item \cs{Z@R@}\metacs{labelname} is defined. +% \item \LaTeX's check for multiple references. +% \item \LaTeX's check for changed references. +% \end{itemize} +% \begin{macrocode} +\def\zref@newlabel{% + \@newl@bel{Z@R}% +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Property lists} +% +% \begin{macro}{\zref@newlist} +% Property lists are stored as list of property names +% enclosed in curly braces. \cs{zref@newlist} +% creates a new list as empty list. Assignments to +% property lists are global. +% \begin{macrocode} +\def\zref@newlist#1{% + \zref@iflistundefined{#1}{% + \@ifdefinable{Z@L@#1}{% + \global\expandafter\let\csname Z@L@#1\endcsname\@empty + \PackageInfo{zref}{New property list: #1}% + }% + }{% + \PackageError\ZREF@name{% + Property list `#1' already exists% + }\@ehc + }% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@iflistundefined} +% \cs{zref@iflistundefined} checks the existence of the +% property list \verb|#1|. If the property list is present, +% then \verb|#2| is executed and \verb|#3| otherwise. +% \begin{macrocode} +\def\zref@iflistundefined#1{% + \expandafter\ifx\csname Z@L@#1\endcsname\relax + \expandafter\@firstoftwo + \else + \expandafter\@secondoftwo + \fi +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@listexists} +% \cs{zref@listexists} only executes \verb|#2| if the +% property list \verb|#1| exists and raises an error +% message otherwise. +% \begin{macrocode} +\def\zref@listexists#1{% + \zref@iflistundefined{#1}{% + \PackageError\ZREF@name{% + Property list `#1' does not exist% + }\@ehc + }% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@listcontainsprop} +% \cs{zref@listcontainsprop} checks, whether a property \verb|#2| is +% already present in a property list \verb|#1|. +% \begin{macrocode} +\def\zref@listcontainsprop#1{% + \expandafter\ZREF@listcontainsprop\csname Z@L@#1\endcsname +} +\def\ZREF@listcontainsprop#1#2{% + \begingroup + \ZREF@foundfalse + \edef\y{#2}% + \@tfor\x:=#1\do{% + \edef\x{\x}% + \ifx\x\y + \ZREF@foundtrue + \fi + }% + \expandafter\endgroup + \ifZREF@found + \expandafter\@firstoftwo + \else + \expandafter\@secondoftwo + \fi +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@addprop} +% \cs{zref@addprop} adds the property \verb|#2| to the property +% list \verb|#1|, if the property is not already in the list. +% Otherwise a warning is given. +% \begin{macrocode} +\def\zref@addprop#1#2{% + \zref@listexists{#1}{% + \zref@propexists{#2}{% + \zref@listcontainsprop{#1}{#2}{% + \PackageWarning\ZREF@name{% + Property `#2' is already in list `#1'% + }% + }{% + \expandafter\g@addto@macro\csname Z@L@#1\endcsname{{#2}}% + }% + }% + }% +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Properties} +% +% \begin{macro}{\zref@ifpropundefined} +% \cs{zref@ifpropundefined} checks the existence of the +% property \verb|#1|. If the property is present, +% then \verb|#2| is executed and \verb|#3| otherwise. +% \begin{macrocode} +\def\zref@ifpropundefined#1{% + \expandafter\ifx\csname Z@E@#1\endcsname\relax + \expandafter\@firstoftwo + \else + \expandafter\@secondoftwo + \fi +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@propexists} +% Some macros rely on the existence of a property. +% \cs{zref@propexists} only executes \verb|#2| if the +% property \verb|#1| exists and raises an error +% message otherwise. +% \begin{macrocode} +\def\zref@propexists#1{% + \zref@ifpropundefined{#1}{% + \PackageError\ZREF@name{% + Property `#1' does not exist% + }\@ehc + }% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@newprop} +% A new property is declared by \cs{zref@newprop}, the +% property name \meta{propname} is given in \verb|#1|. The +% property is created and configured. If the star form +% is given, then the expansion of the property value +% is delayed to page shipout time, when the reference +% is written to the \xfile{.aux} file. +% \begin{description} +% \item[\cs{Z@D@}\metacs{propname}:] +% Stores the default value for this property. +% \item[\cs{Z@E@}\metacs{propname}:] +% Extract function. +% \item[\cs{Z@X@}\metacs{propname}:] +% Information whether the expansion of the property value +% is delayed to shipout time. +% \item[\cs{Z@C@}\metacs{propname}:] +% Current value of the property. +% \end{description} +% \begin{macrocode} +\def\zref@newprop{% + \@ifstar{% + \let\ZREF@X\noexpand + \ZREF@newprop + }{% + \let\ZREF@X\@empty + \ZREF@newprop + }% +} +\def\ZREF@newprop#1{% + \PackageInfo{zref}{New property: #1}% + \def\ZREF@P{#1}% + \@ifnextchar[\ZREF@@newprop{\ZREF@@newprop[\zref@default]}% +} +\def\ZREF@@newprop[#1]{% + \global\@namedef{Z@D@\ZREF@P}{#1}% + \global\expandafter\let\csname Z@X@\ZREF@P\endcsname\ZREF@X + \expandafter\ZREF@@@newprop\csname\ZREF@P\endcsname + \zref@setcurrent\ZREF@P +} +\def\ZREF@@@newprop#1{% + \expandafter\gdef\csname Z@E@\ZREF@P\endcsname##1#1##2##3\ZREF@nil{##2}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@setcurrent} +% \cs{zref@setcurrent} sets the current value for a property. +% \begin{macrocode} +\def\zref@setcurrent#1{% + \expandafter\def\csname Z@C@#1\endcsname +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Reference generation} +% +% \begin{macro}{\zref@label} +% Label macro that uses the main property list. +% \begin{macrocode} +\def\zref@label#1{% + \zref@labelbylist{#1}\ZREF@mainlist +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@labelbylist} +% Label macro that stores the properties, specified in the +% property list \verb|#2|. +% \begin{macrocode} +\def\zref@labelbylist#1#2{% + \@bsphack + \zref@listexists{#2}{% + \expandafter\expandafter\expandafter\ZREF@label + \expandafter\expandafter\expandafter{% + \csname Z@L@#2\endcsname + }{#1}% + }% + \@esphack +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@labelbyprops} +% The properties are directly specified in a comma separated list. +% \begin{macrocode} +\def\zref@labelbyprops#1#2{% + \@bsphack + \begingroup + \edef\l{#2}% + \toks@{}% + \@for\x:=#2\do{% + \zref@ifpropundefined{\x}{% + \PackageWarning\ZREF@name{% + Property `\x' is not known% + }% + }{% + \toks@\expandafter\expandafter\expandafter{% + \expandafter\the\expandafter\toks@\expandafter{\x}% + }% + }% + }% + \expandafter\endgroup + \expandafter\ZREF@label\expandafter{\the\toks@}{#1}% + \@esphack +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ifZREF@immediate} +% The switch \cs{ifZREF@immediate} tells us, whether the +% label should be written immediately or at page shipout time. +% \cs{ZREF@label} need to be notified about this, because +% it must disable the deferred execution of property values, +% if the label is written immediately. +% \begin{macrocode} +\newif\ifZREF@immediate +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@wrapper@immediate} +% The argument of \cs{zref@wrapper@immediate} is executed inside +% a group where \cs{write} is redefined by adding +% \cs{immediate} before its execution. Also \cs{ZREF@label} +% is notified via the switch \cs{ifZREF@immediate}. +% \begin{macrocode} +\long\def\zref@wrapper@immediate#1{% + \begingroup + \ZREF@immediatetrue + \let\ZREF@org@write\write + \def\write{\immediate\ZREF@org@write}% + #1% + \endgroup +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@label} +% \cs{ZREF@label} writes the data in the \xfile{.aux} file. +% \verb|#1| contains the list of valid properties, +% \verb|#2| the name of the reference. In case of immediate +% writing, the deferred execution of property values is +% disabled. Also \thepage is made expandable in this case. +% \begin{macrocode} +\def\ZREF@label#1#2{% + \if@filesw + \begingroup + \ifZREF@immediate + \let\ZREF@org@thepage\thepage + \fi + \protected@write\@auxout{% + \ifZREF@immediate + \let\thepage\ZREF@org@thepage + \fi + \let\ZREF@temp\@empty + \@tfor\ZREF@P:=#1\do{% + \expandafter\ifx + \csname\ifZREF@immediate relax\else Z@X@\ZREF@P\fi\endcsname + \noexpand + \expandafter\let\csname Z@C@\ZREF@P\endcsname\relax + \fi + \toks@\expandafter{\ZREF@temp}% + \edef\ZREF@temp{% + \the\toks@ + \expandafter\string\csname\ZREF@P\endcsname{% + \expandafter\noexpand\csname Z@C@\ZREF@P\endcsname + }% + }% + }% + }{% + \string\zref@newlabel{#2}{\ZREF@temp}% + }% + \endgroup + \fi +} +\def\ZREF@addtoks#1{% + \toks@\expandafter\expandafter\expandafter{% + \expandafter\the\expandafter\toks@#1% + }% +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Reference querying and extracting} +% +% Design goal for the extracting macros is that the extraction +% process is full expandable. Thus these macros can be used +% in expandable contexts. But there are problems that cannot +% be solved by full expandable macros: +% \begin{itemize} +% \item In standard \LaTeX\ undefined references sets a flag +% and generate a warning. Both actions are not expandable. +% \item Babel's support for its shorthand uses commands that +% use non-expandable assignments. However currently there +% is hope, that primitives are added to \pdfTeX\ that +% allows the detection of contexts. Then the shorthand +% can detect, if they are executed inside \cs{csname} +% and protect themselves automatically. +% \end{itemize} +% \begin{macro}{\zref@ifrefundefined} +% If a reference \verb|#1| is undefined, then macro +% \cs{zref@ifrefundefined} calls \verb|#2| and \verb|#3| otherwise. +% \begin{macrocode} +\def\zref@ifrefundefined#1{% + \expandafter\ifx\csname Z@R@#1\endcsname\relax + \expandafter\@firstoftwo + \else + \expandafter\@secondoftwo + \fi +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@refused} +% The problem with undefined references is addressed by +% the macro \cs{zref@refused}. This can be used outside +% the expandable context. In case of an undefined reference +% the flag is set to notify \LaTeX\ and a warning is given. +% \begin{macrocode} +\def\zref@refused#1{% + \begingroup + \csname @safe@activestrue\endcsname + \zref@ifrefundefined{#1}{% + \protect\G@refundefinedtrue + \@latex@warning{% + Reference `#1' on page \thepage \space undefined% + }% + }{}% + \endgroup +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@extract} +% \cs{zref@extract} is an abbreviation for the case +% that the default of the property is used as default +% value. +% \begin{macrocode} +\def\zref@extract#1#2{% + \expandafter\expandafter\expandafter\ZREF@extract + \expandafter\expandafter\expandafter{% + \csname Z@D@#2\endcsname + }{#1}{#2}% +} +\def\ZREF@extract#1#2#3{% + \zref@extractdefault{#2}{#3}{#1}% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@ifrefcontainsprop} +% \cs{zref@ifrefcontainsprop} looks, if the reference \verb|#1| +% has the property \verb|#2| and calls then \verb|#3| and +% \verb|#4| otherwise. +% \begin{macrocode} +\def\zref@ifrefcontainsprop#1#2{% + \zref@ifrefundefined{#1}{% + \@secondoftwo + }{% + \expandafter\ZREF@ifrefcontainsprop + \csname Z@E@#2\expandafter\endcsname + \csname#2\expandafter\expandafter\expandafter\endcsname + \expandafter\expandafter\expandafter{% + \csname Z@R@#1\endcsname + }% + }% +} +\def\ZREF@ifrefcontainsprop#1#2#3{% + \expandafter\ifx\expandafter\ZREF@novalue + #1#3#2\ZREF@novalue\ZREF@nil\@empty + \expandafter\@secondoftwo + \else + \expandafter\@firstoftwo + \fi +} +\def\ZREF@novalue{\ZREF@NOVALUE} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@extractdefault} +% The basic extracting macro is \cs{zref@extractdefault} with +% the reference name in \verb|#1|, the property in \verb|#2| and +% the default value in \verb|#3| in case for problems. +% \begin{macrocode} +\def\zref@extractdefault#1#2#3{% + \zref@ifrefundefined{#1}{% + \ZREF@unexpanded{#3}% + }{% + \expandafter\expandafter\expandafter\ZREF@unexpanded + \expandafter\expandafter\expandafter{% + \csname Z@E@#2\expandafter\expandafter\expandafter\endcsname + \csname Z@R@#1\expandafter\endcsname + \csname#2\endcsname{#3}\ZREF@nil + }% + }% +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@wrapper@unexpanded} +% \begin{macrocode} +\long\def\zref@wrapper@unexpanded#1{% + \let\ZREF@unexpanded\unexpanded + #1% + \let\ZREF@unexpanded\@firstofone +} +\let\ZREF@unexpanded\@firstofone +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Compatibility with \xpackage{babel}} +% +% \begin{macro}{\zref@wrapper@babel} +% \begin{macrocode} +\long\def\zref@wrapper@babel#1#2{% + \begingroup + \csname @safe@activestrue\endcsname + \edef\x{#2}% + \expandafter\endgroup + \expandafter\ZREF@wrapper@babel\expandafter{\x}{#1}% +} +\def\ZREF@wrapper@babel#1#2{% + #2{#1}% +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Unique counter support} +% +% \begin{macro}{\zref@require@unique} +% Generate the counter |zref@unique| if the counter does not +% already exist. +% \begin{macrocode} +\def\zref@require@unique{% + \@ifundefined{c@zref@unique}{% + \newcounter{zref@unique}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\thezref@unique} +% \cs{thezref@unique} is used for automatically generated unique +% labelnames. +% \begin{macrocode} + \renewcommand*{\thezref@unique}{% + zref@\number\c@zref@unique + }% + }{}% +} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Setup} +% +% \begin{macro}{\zref@setdefault} +% Standard \LaTeX\ prints ``??'' in bold face if a reference +% is not known. \cs{zref@default} holds the text that is +% printed in case of unknown references and is used, if +% the default was not specified during the definition +% of the new property by \cs{ref@newprop}. +% The global default value can be set by \cs{zref@setdefault}. +% \begin{macrocode} +\def\zref@setdefault#1{% + \def\zref@default{#1}% +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@default} +% Now we initialize \cs{zref@default} with the same value +% that \LaTeX\ uses for its undefined references. +% \begin{macrocode} +\zref@setdefault{% + \nfss@text{\reset@font\bfseries ??}% +} +% \end{macrocode} +% \end{macro} +% +% \paragraph{Main property list.} +% +% \begin{macro}{\zref@setmainlist} +% The name of the default property list is stored in +% \cs{ZREF@mainlist} and can be set by \cs{zref@setmainlist}. +% \begin{macrocode} +\def\zref@setmainlist#1{% + \def\ZREF@mainlist{#1}% +} +\zref@setmainlist{main} +% \end{macrocode} +% \end{macro} +% Now we create the list. +% \begin{macrocode} +\zref@newlist\ZREF@mainlist +% \end{macrocode} +% +% \paragraph{Main properties.} +% +% The two properties \texttt{default} and \texttt{page} +% are created and added to the main property list. +% They store the data that +% standard \LaTeX\ uses in its references created by +% \cs{label}. +% \begin{description} +% \item[\texttt{default}] the apperance of the latest +% counter that is incremented by \cs{refstepcounter} +% \item[\texttt{page}] the apperance of the page counter +% \end{description} +% \begin{macrocode} +\zref@newprop{default}{\@currentlabel} +\zref@newprop*{page}{\thepage} +\zref@addprop\ZREF@mainlist{default} +\zref@addprop\ZREF@mainlist{page} +% \end{macrocode} +% +% \paragraph{Mark successful loading} +% +% \begin{macrocode} +\let\ZREF@baseok\@empty +%</base> +% \end{macrocode} +% +% +% \subsection{Module \xoption{user}} +% +% \begin{macrocode} +%<*user> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-user}% + [2006/05/25 v1.2 Module user for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% Option \xoption{zuser} enables a small user interface. +% All macros are prefixed by \cs{z}. +% +% First we define the pendants to the standard \LaTeX\ referencing +% commands \cs{label}, \cs{ref}, and \cs{pageref}. +% +% \begin{macro}{\zlabel} +% Similar to \cs{label} the macro \cs{zlabel} writes a reference +% entry in the \xfile{.aux} file. The main property list is used. +% Also we add the babel patch. The \cs{label} command can also be +% used inside section titles, but it must not go into the +% table of contents. Therefore we have to check this situation. +% \begin{macrocode} +\newcommand*\zlabel{% + \ifx\label\@gobble + \expandafter\@gobble + \else + \expandafter\zref@wrapper@babel\expandafter\zref@label + \fi +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref} +% Macro \cs{zref} is the corresponding macro for \cs{ref}. +% Also it provides an optional argument in order to +% select another property. +% \begin{macrocode} +\newcommand*{\zref}[2][default]{% + \zref@propexists{#1}{% + \zref@wrapper@babel\ZREF@zref{#2}{#1}% + }% +}% +\def\ZREF@zref#1{% + \zref@refused{#1}% + \zref@extract{#1}% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zpageref} +% For macro \cs{zpageref} we just call \cs{zref} +% with property \verb|page|. +% \begin{macrocode} +\newcommand*\zpageref{% + \zref[page]% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zrefused} +% For the following expandible user macros \cs{zrefused} +% should be used to notify \LaTeX\ in case of undefined +% references. +% \begin{macrocode} +\newcommand*{\zrefused}{\zref@refused}% +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</user> +% \end{macrocode} +% +% +% \subsection{Module \xoption{abspage}} +% +% \begin{macrocode} +%<*abspage> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-abspage}% + [2006/05/25 v1.2 Module abspage for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% Module \xoption{abspage} adds a new property \verb|abspage| +% to the \verb|main| property list for absolute page numbers. +% These are recorded by the help of package \xpackage{everyshi}. +% \begin{macrocode} +\RequirePackage{everyshi}% +\newcounter{abspage}% +\setcounter{abspage}{0}% +\EveryShipout{% + \stepcounter{abspage}% +}% +\zref@newprop*{abspage}[0]{\the\c@abspage}% +\zref@addprop\ZREF@mainlist{abspage}% +% \end{macrocode} +% Note that counter \verb|abspage| shows the +% previous page during page processing. Before +% shipout the counter is incremented. +% Thus the property is correctly written with +% deferred writing. If the counter is written +% using \cs{zref@wrapper@immediate}, then the number +% is too small by one. +% +% \begin{macrocode} +%</abspage> +% \end{macrocode} +% +% +% \subsection{Module \xoption{counter}} +% +% \begin{macrocode} +%<*counter> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-counter}% + [2006/05/25 v1.2 Module counter for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% For features such as \xpackage{hyperref}'s \cs{autoref} +% we need the name of the counter. The property +% \verb|counter| is defined and added to the main property +% list. +% \begin{macrocode} +\zref@newprop{counter}{} +\zref@addprop\ZREF@mainlist{counter} +% \end{macrocode} +% +% \cs{refstepcounter} is the central macro where we know +% which counter is responsible for the reference. +% \begin{macrocode} +\AtBeginDocument{% + \ZREF@patch{refstepcounter}{% + \def\refstepcounter#1{% + \zref@setcurrent{counter}{#1}% + \ZREF@org@refstepcounter{#1}% + }% + }% +} +% \end{macrocode} +% \begin{macrocode} +%</counter> +% \end{macrocode} +% +% +% \subsection{Module \xoption{lastpage}} +% +% \begin{macrocode} +%<*lastpage> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-lastpage}% + [2006/05/25 v1.2 Module lastpage for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% The Module \xoption{lastpage} implements the service +% of package \xpackage{lastpage} by setting a reference +% \verb|LastPage| at the end of the document. +% If option \xoption{abspage} is given, also the absolute +% page number is available, because the properties of +% the main property list are used. +% \begin{macrocode} +\AtBeginDocument{% + \AtEndDocument{% + \if@filesw + \clearpage + \begingroup + \advance\c@page\m@ne + \zref@wrapper@immediate{\zref@label{LastPage}}% + \endgroup + \fi + }% +} +% \end{macrocode} +% \begin{macrocode} +%</lastpage> +% \end{macrocode} +% +% \subsection{Module \xoption{totpages}} +% +% \begin{macrocode} +%<*totpages> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-totpages}% + [2006/05/25 v1.2 Module totpages for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% The absolute page number of the last page is the total +% page number. +% \begin{macrocode} +\RequirePackage{zref-abspage}[2006/05/25] +\RequirePackage{zref-lastpage}[2006/05/25] +% \end{macrocode} +% +% \begin{macro}{\ztotpages} +% Macro \cs{ztotpages} contains the number of pages. It can be +% used inside expandable calculations. It expands to zero if +% the reference is not yet available. +% \begin{macrocode} +\newcommand*{\ztotpages}{% + \zref@extractdefault{LastPage}{abspage}{0}% +} +% \end{macrocode} +% \end{macro} +% Also we mark the reference |LastPage| as used: +% \begin{macrocode} +\AtBeginDocument{% + \zref@refused{LastPage}% +} +% \end{macrocode} +% \begin{macrocode} +%</totpages> +% \end{macrocode} +% +% +% \subsection{Module \xoption{perpage}} +% +% \begin{macrocode} +%<*perpage> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-perpage}% + [2006/05/25 v1.2 Module perpage for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% This module resets a counter at page boundaries. +% Because of the asynchronous output routine +% page counter properties cannot be asked directly, +% references are necessary. +% +% For detecting changed pages module \xoption{abspage} +% is loaded. +% \begin{macrocode} +\RequirePackage{zref-abspage}[2006/05/25] +% \end{macrocode} +% +% We group the properties for the needed references +% in the property list |perpage|. The property |pagevalue| +% records the correct value of the page counter. +% \begin{macrocode} +\zref@newprop*{pagevalue}[0]{\number\c@page} +\zref@newlist{perpage} +\zref@addprop{perpage}{abspage} +\zref@addprop{perpage}{page} +\zref@addprop{perpage}{pagevalue} +% \end{macrocode} +% The page value, known by the reference mechanism, will be +% stored in counter |zpage|. +% \begin{macrocode} +\newcounter{zpage} +% \end{macrocode} +% Counter |zref@unique| helps in generating unique reference +% names. +% \begin{macrocode} +\zref@require@unique +% \end{macrocode} +% In order to be able to reset the counter, we hook here +% into \cs{stepcounter}. In fact two nested hooks are used +% to allow other packages to use the first hook at the beginning +% of \cs{stepcounter}. +% \begin{macrocode} +\let\ZREF@org@stepcounter\stepcounter +\def\stepcounter#1{% + \ifcsname @stepcounterhook@#1\endcsname + \csname @stepcounterhook@#1\endcsname + \fi + \ZREF@org@stepcounter{#1}% +} +% \end{macrocode} +% +% \begin{macro}{\zmakeperpage} +% Makro \cs{zmakeperpage} resets a counter at each page +% break. It uses the same syntax and semantics as +% \cs{MakePerPage} from package \xpackage{perpage} (\cite{perpage}). +% The initial start value can be given by the optional +% argument. Default is one that means after the first +% \cs{stepcounter} on a new page the counter starts with +% one. +% \begin{macrocode} +\newcommand*{\zmakeperpage}{% + \@ifnextchar[\ZREF@makeperpage@opt{\ZREF@@makeperpage[\z@]}% +} +% \end{macrocode} +% \end{macro} +% We hook before the counter is incremented in \cs{stepcounter}, +% package \xpackage{perpage} afterwards. Thus a little +% calculation is necessary. +% \begin{macrocode} +\def\ZREF@makeperpage@opt[#1]{% + \begingroup + \edef\x{\endgroup + \noexpand\ZREF@@makeperpage[\number\numexpr#1-1\relax]% + }% + \x +} +% \end{macrocode} +% \begin{macrocode} +\def\ZREF@@makeperpage[#1]#2{% + \@ifundefined{@stepcounterhook@#2}{% + \expandafter\gdef\csname @stepcounterhook@#2\endcsname{}% + }{}% + \expandafter\gdef\csname ZREF@perpage@#2\endcsname{% + \ZREF@@perpage@step{#2}{#1}% + }% + \expandafter\g@addto@macro\csname @stepcounterhook@#2\endcsname{% + \ifcsname ZREF@perpage@#2\endcsname + \csname ZREF@perpage@#2\endcsname + \fi + }% +} +% \end{macrocode} +% \begin{macro}{\ZREF@@perpage@step} +% The heart of this module follows. +% \begin{macrocode} +\def\ZREF@@perpage@step#1#2{% +% \end{macrocode} +% First the reference is generated. +% \begin{macrocode} + \global\advance\c@zref@unique\@ne + \begingroup + \expandafter\zref@labelbylist\expandafter{\thezref@unique}{perpage}% +% \end{macrocode} +% The \cs{expandafter} commands are necessary, because \cs{ZREF@temp} +% is also used inside of \cs{zref@labelbylist}. +% +% The evaluation of the reference follows. If the reference +% is not yet kwown, we use the page counter as approximation. +% \begin{macrocode} + \zref@ifrefundefined\thezref@unique{% + \global\c@zpage=\c@page + \global\let\thezpage\thepage + \expandafter\xdef\csname ZREF@abspage@#1\endcsname{\number\c@abspage}% + }{% +% \end{macrocode} +% The reference is used to set \cs{thezpage} and counter |zpage|. +% \begin{macrocode} + \global\c@zpage=\zref@extract\thezref@unique{pagevalue}\relax + \xdef\thezpage{\noexpand\zref@extract{\thezref@unique}{page}}% + \expandafter\xdef\csname ZREF@abspage@#1\endcsname{% + \zref@extractdefault\thezref@unique{abspage}{\number\c@abspage}% + }% + }% +% \end{macrocode} +% Page changes are detected by a changed absolute page number. +% \begin{macrocode} + \expandafter\ifx\csname ZREF@abspage@#1\expandafter\endcsname + \csname ZREF@currentabspage@#1\endcsname + \else + \global\csname c@#1\endcsname=#2\relax + \global\expandafter\let + \csname ZREF@currentabspage@#1\expandafter\endcsname + \csname ZREF@abspage@#1\endcsname + \fi + \endgroup +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zunmakeperpage} +% Macro \cs{zunmakeperpage} cancels the effect of \cs{zmakeperpage}. +% \begin{macrocode} +\newcommand*{\zunmakeperpage}[1]{% + \global\expandafter\let\csname ZREF@perpage@#1\endcsname\@undefined +} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</perpage> +% \end{macrocode} +% +% +% \subsection{Module \xoption{titleref}} +% +% \begin{macrocode} +%<*titleref> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-titleref}% + [2006/05/25 v1.2 Module titleref for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% \subsubsection{Implementation} +% \begin{macrocode} +\RequirePackage{keyval} +% \end{macrocode} +% +% This module makes section and caption titles available +% for the reference system. It uses some of the ideas +% of package \xpackage{nameref} and \xpackage{titleref}. +% +% \begin{macro}{\zref@titleref@current} +% Later we will redefine the section and caption macros +% to catch the current title and remember the value in +% \cs{zref@titleref@current}. +% \begin{macrocode} +\let\zref@titleref@current\@empty +% \end{macrocode} +% \end{macro} +% Now we can add the property \verb|title| is added to +% the main property list. +% \begin{macrocode} +\zref@newprop{title}{\zref@titleref@current}% +\zref@addprop\ZREF@mainlist{title}% +% \end{macrocode} +% +% The title strings go into the \xfile{.aux} file, thus +% they need some kind of protection. +% Package \xpackage{titleref} uses a protected expansion +% method. The advantage is that this can be used to +% cleanup the string and to remove \cs{label}, \cs{index} +% and other macros unwanted for referencing. +% But there is the risk that fragile stuff can break. +% +% Therefore package \xpackage{nameref} does not expand +% the string. Thus the entries can safely be written to +% the \xfile{.aux} file. But potentially dangerous +% macros such as \cs{label} remain in the string and +% can cause problems when using the string in references. +% +% \begin{macro}{\ifzref@titleref@expand} +% The switch \cs{ifzref@titleref@expand} distinguishes +% between the both methods. Package \xpackage{nameref}'s +% behaviour is achieved by setting the switch to false, +% otherwise \xpackage{titleref}'s expansion is used. +% Default is false. +% \begin{macrocode} +\newif\ifzref@titleref@expand +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@titleref@hook} +% The hook \cs{ZREF@titleref@hook} allows to extend +% the cleanup for the expansion method. Thus +% unnecessary macros can be removed or dangerous commands +% removed. The hook is executed before the expansion of +% \cs{zref@titleref@current}. +% \begin{macrocode} +\let\ZREF@titleref@hook\@empty +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zref@titleref@cleanup} +% The hook should not be used directly, instead we provide the +% macro \cs{zref@titleref@cleanup} to add stuff to the hook +% and prevents that a previous non-empty content is not discarded +% accidently. +% \begin{macrocode} +\def\zref@titleref@cleanup#1{% + \begingroup + \toks@\expandafter{% + \ZREF@titleref@hook + #1% + }% + \expandafter\endgroup + \expandafter\def\expandafter\ZREF@titleref@hook\expandafter{% + \the\toks@ + }% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ifzref@titleref@stripperiod} +% Sometimes a title contains a period at the end. +% Package \xpackage{nameref} removes this. This behaviour +% is controlled by the switch \cs{ifzref@titleref@stripperiod} +% and works regardless of the setting of option \xoption{expand}. +% Period stripping is the default. +% \begin{macrocode} +\newif\ifzref@titleref@stripperiod +\zref@titleref@stripperiodtrue +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zref@titleref@setcurrent} +% Macro \cs{zref@titleref@setcurrent} sets a new current title +% stored in \cs{zref@titleref@current}. Some cleanup and +% expansion is performed that can be controlled by the +% previous switches. +% \begin{macrocode} +\def\zref@titleref@setcurrent#1{% + \def\zref@titleref@current{#1}% + \ifzref@titleref@expand + \begingroup + \let\label\@gobble + \let\index\@gobble + \let\glossary\@gobble + \let\markboth\@gobbletwo + \let\@mkboth\@gobbletwo + \let\markright\@gobble + \let\protect\@unexpandable@protect + \ZREF@titleref@hook + \edef\x{\endgroup + \noexpand\def\noexpand\zref@titleref@current{% + \zref@titleref@current + }% + }% + \x + \fi + \edef\zref@titleref@current{% + \detokenize\expandafter{\zref@titleref@current}% + }% + \ifzref@titleref@stripperiod + \edef\zref@titleref@current{% + \expandafter\ZREF@stripperiod\zref@titleref@current + \@empty.\@empty\@nil + }% + \fi +}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\ZREF@stripperiod} +% If \cs{ZREF@stripperiod} is called, the argument consists of +% space tokens and tokens with catcode 12 (other), because +% of \eTeX's \cs{detokenize}. +% \begin{macrocode} +\def\ZREF@stripperiod#1.\@empty#2\@nil{#1}% +% \end{macrocode} +% \end{macro} +% +% \subsubsection{User interface} +% +% \begin{macro}{\ztitlerefsetup} +% The behaviour of option \xoption{titleref} is controlled +% by switches and a hook. They can be set by \cs{ztitlerefsetup} +% with a key value interface, provided by package \xpackage{keyval}. +% Also the current title can be given explicitly by the key +% \verb|title|. +% \begin{macrocode} +\define@key{ZREF@TR}{expand}[true]{% + \csname zref@titleref@expand#1\endcsname +}% +\define@key{ZREF@TR}{stripperiod}[true]{% + \csname zref@titleref@stripperiod#1\endcsname +}% +\define@key{ZREF@TR}{cleanup}{% + \zref@titleref@cleanup{#1}% +}% +\define@key{ZREF@TR}{title}{% + \def\zref@titleref@current{#1}% +}% +\newcommand*{\ztitlerefsetup}{% + \setkeys{ZREF@TR}% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ztitleref} +% The user command \cs{ztitleref} references the title. +% For safety \cs{label} is disabled to prevent multiply +% defined references. +% \begin{macrocode} +\newcommand*{\ztitleref}{% + \zref@wrapper@babel\ZREF@titleref +}% +\def\ZREF@titleref#1{% + \begingroup + \zref@refused{#1}% + \let\label\@gobble + \zref@extract{#1}{title}% + \endgroup +}% +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Patches for section and caption commands} +% +% The section and caption macros are patched to extract the +% title data. +% +% Captions of figures and tables. +% \begin{macrocode} +\AtBeginDocument{% + \ZREF@patch{@caption}{% + \long\def\@caption#1[#2]{% + \zref@titleref@setcurrent{#2}% + \ZREF@org@@caption{#1}[{#2}]% + }% + }% +% \end{macrocode} +% +% Section commands without star. The title version for the +% table of contents is used because it is usually shorter and +% more robust. +% \begin{macrocode} + \ZREF@patch{@part}{% + \def\@part[#1]{% + \zref@titleref@setcurrent{#1}% + \ZREF@org@@part[{#1}]% + }% + }% + \ZREF@patch{@chapter}{% + \def\@chapter[#1]{% + \zref@titleref@setcurrent{#1}% + \ZREF@org@@chapter[{#1}]% + }% + }% + \ZREF@patch{@sect}{% + \def\@sect#1#2#3#4#5#6[#7]{% + \zref@titleref@setcurrent{#7}% + \ZREF@org@@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]% + }% + }% +% \end{macrocode} +% The star versions of the section commands. +% \begin{macrocode} + \ZREF@patch{@spart}{% + \def\@spart#1{% + \zref@titleref@setcurrent{#1}% + \ZREF@org@@spart{#1}% + }% + }% + \ZREF@patch{@schapter}{% + \def\@schapter#1{% + \zref@titleref@setcurrent{#1}% + \ZREF@org@@schapter{#1}% + }% + }% + \ZREF@patch{@ssect}{% + \def\@ssect#1#2#3#4#5{% + \zref@titleref@setcurrent{#5}% + \ZREF@org@@ssect{#1}{#2}{#3}{#4}{#5}% + }% + }% +% \end{macrocode} +% +% Package \xpackage{titlesec}. +% \begin{macrocode} + \@ifpackageloaded{titlesec}{% + \ZREF@patch{ttl@sect@i}{% + \def\ttl@sect@i#1#2[#3]#4{% + \zref@titlesec@setcurrent{#4}% + \ZREF@org@ttl@sect@i{#1}{#2}[{#3}]{#4}% + }% + }% + }{}% +}% +% \end{macrocode} +% +% \begin{macrocode} +%</titleref> +% \end{macrocode} +% +% +% \subsection{Module \xoption{xr}} +% +% \begin{macrocode} +%<*xr> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-xr}% + [2006/05/25 v1.2 Module xr for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% \begin{macrocode} +\RequirePackage{keyval} +% \end{macrocode} +% +% We declare property |url|, because this is added, +% if a reference is imported and has not already set this field. +% Or if |hyperref| is used, then this property can be asked. +% \begin{macrocode} +\zref@newprop{url}{}% +% \end{macrocode} +% +% +% Most code, especially the handling of the \xfile{.aux} +% files are taken from David Carlisle's \xpackage{xr} package. +% Therefore I drop the documentation for these macros here. +% +% \begin{macro}{\zref@xr@ext} +% If the URL is not specied, then assume +% processed file with a guessed extension. +% Use the setting of \xpackage{hyperref} if available. +% \begin{macrocode} +\providecommand*{\zref@xr@ext}{% + \@ifundefined{XR@ext}{pdf}{\XR@ext}% +}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\ifZREF@xr@zreflabel} +% The use of the star form of \cs{zexternaldocument} +% is remembered in the switch \cs{ifZREF@xr@zreflabel}. +% \begin{macrocode} +\newif\ifZREF@xr@zreflabel +% \end{macrocode} +% \end{macro} +% \begin{macro}{\zexternaldocument} +% In its star form it looks for \cs{newlabel}, +% otherwise for \cs{zref@newlabel}. +% Later we +% will read \xfile{.aux} files that expects +% |@| to have catcode 11 (letter). +% \begin{macrocode} +\newcommand*{\zexternaldocument}{% + \begingroup + \csname @safe@actives@true\endcsname + \makeatletter + \@ifstar{% + \ZREF@xr@zreflabelfalse + \@testopt\ZREF@xr@externaldocument{}% + }{% + \ZREF@xr@zreflabeltrue + \@testopt\ZREF@xr@externaldocument{}% + }% +}% +% \end{macrocode} +% \end{macro} +% +% If the \cs{include} featuer was used, there can be +% several \xfile{.aux} files. These files are read +% one after another, especially they are not recursively +% read in order to save read registers. Thus it can +% happen that the read order of the newlabel commands +% differs from \LaTeX's order using \cs{input}. +% +% \begin{macro}{\ZREF@xr@externaldocument} +% It reads the remaining arguments. \cs{newcommand} +% comes in handy for the optional argument. +% \begin{macrocode} +\def\ZREF@xr@externaldocument[#1]#2{% + \def\ZREF@xr@prefix{#1}% + \let\ZREF@xr@filelist\@empty + \edef\ZREF@xr@file{#2.aux}% + \filename@parse{#2}% + \@testopt\ZREF@xr@graburl{#2.\zref@xr@ext}% +}% +\def\ZREF@xr@graburl[#1]{% + \edef\ZREF@xr@url{#1}% + \ZREF@xr@checkfile + \endgroup +}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\ZREF@xr@processfile} +% We follow \xpackage{xr} here, \cs{IfFileExists} offers +% a nicer test, but we have to open the file anyway. +% \begin{macrocode} +\def\ZREF@xr@checkfile{% + \openin\@inputcheck\ZREF@xr@file\relax + \ifeof\@inputcheck + \PackageWarning{zref/xr}{% + File `\ZREF@xr@file' not found or empty,\MessageBreak + labels not imported% + }% + \else + \PackageInfo{zref/xr}{% + Label \ifZREF@xr@zreflabel (zref) \fi import from `\ZREF@xr@file'% + }% + \def\ZREF@xr@found{0}% + \def\ZREF@xr@ignored{0}% + \ZREF@xr@processfile + \closein\@inputcheck + \begingroup + \let\on@line\@empty + \PackageInfo{zref/xr}{% + Statistics for `\ZREF@xr@file': + \ZREF@xr@found\space found, % + \ZREF@xr@ignored\space ignored% + }% + \endgroup + \fi + \ifx\ZREF@xr@filelist\@empty + \else + \edef\ZREF@xr@file{\expandafter\@car\ZREF@xr@filelist\@nil}% + \edef\ZREF@xr@filelist{\expandafter\@cdr\ZREF@xr@filelist\@nil}% + \expandafter\ZREF@xr@checkfile + \fi +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@xr@processfile} +% \begin{macrocode} +\def\ZREF@xr@processfile{% + \read\@inputcheck to\ZREF@xr@line + \expandafter\ZREF@xr@processline\ZREF@xr@line..\ZREF@nil + \ifeof\@inputcheck + \else + \expandafter\ZREF@xr@procesfile + \fi +}% +% \end{macrocode} +% \end{macro} +% \begin{macro}{\ZREF@xr@processline} +% The most work must be done for analyzing the +% arguments of \cs{newlabel}. +% \begin{macrocode} +\long\def\ZREF@xr@processline#1#2#3\ZREF@nil{% + \def\x{#1}% + \toks@{#2}% + \ifZREF@xr@zreflabel + \ifx\x\ZREF@xr@zref@newlabel + \expandafter\ZREF@xr@process@zreflabel\ZREF@xr@line...\ZREF@nil + \fi + \else + \ifx\x\ZREF@xr@newlabel + \expandafter\ZREF@xr@process@label\ZREF@xr@line...[]\ZREF@nil + \fi + \fi + \ifx\x\ZREF@xr@@input + \edef\ZREF@xr@filelist{% + \unexpanded\expandafter{\ZREF@xr@filelist}% + {\filename@area\the\toks@}% + }% + \fi + \ifeof\@inputcheck + \else + \expandafter\ZREF@xr@processfile + \fi +}% +\def\ZREF@xr@process@zreflabel\zref@newlabel#1#2#3\ZREF@nil{% + \def\ZREF@xr@refname{Z@R@\ZREF@xr@prefix#1}% + \edef\ZREF@xr@found{\the\numexpr\ZREF@xr@found+1\relax}% + \def\x{#2}% + \@ifundefined{\ZREF@xr@refname}{% + \let\ZREF@xr@list\x + \ifx\ZREF@xr@list\@empty + \PackageWarningNoLine{zref/xr}{% + Label `#1' without properties ignored\MessageBreak + in file `\ZREF@xr@file'% + }% + \edef\ZREF@xr@ignored{\the\numexpr\ZREF@xr@ignored+1\relax}% + \else + \expandafter\ZREF@xr@checklist\x\ZREF@nil + \expandafter\global\expandafter\let + \csname \ZREF@xr@refname\endcsname\x + \fi + \ZREF@xr@urlcheck{\ZREF@xr@prefix#1}% + }{% + \ZREF@xr@ignorewarning{\ZREF@xr@prefix#1}% + }% +}% +\def\ZREF@xr@process@label\newlabel#1#2#3[#4]#5\ZREF@nil{% + \def\ZREF@xr@refname{Z@R@\ZREF@xr@prefix#1}% + \edef\ZREF@xr@found{\the\numexpr\ZREF@xr@found+1\relax}% + \def\x{#2}% + \@ifundefined{\ZREF@xr@refname}{% + \expandafter\ZREF@xr@scanparams + \csname\ZREF@xr@refname\expandafter\endcsname + \x{}{}{}{}{}\ZREF@nil + \ifx\\#4\\% + \else + % ntheorem knows an optional argument at the end of \newlabel + \zref@ifpropundefined{theotype}{% + \zref@newprop{theotype}{}% + }{}% + \expandafter\g@addto@macro + \csname\ZREF@xr@refname\endcsname{\theotype{#4}}% + \fi + \ZREF@xr@urlcheck{\ZREF@xr@prefix#1}% + }{% + \ZREF@xr@ignorewarning{\ZREF@xr@prefix#1}% + }% +} +\def\ZREF@xr@zref@newlabel{\zref@newlabel}% +\def\ZREF@xr@newlabel{\newlabel}% +\def\ZREF@xr@@input{\@input}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@xr@ignorewarning} +% \begin{macrocode} +\def\ZREF@xr@ignorewarning#1{% + \PackageWarningNoLine{zref/xr}{% + Label `#1' is already in use\MessageBreak + in file `\ZREF@xr@file'% + }% + \edef\ZREF@xr@ignored{\the\numexpr\ZREF@xr@ignored+1\relax}% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@xr@checklist} +% \begin{macrocode} +\def\ZREF@xr@checklist#1#2#3\ZREF@nil{% + \ifx\@undefined#1\relax + \expandafter\ZREF@xr@checkkey\string#1\@nil + \fi + \ifx\\#3\\% + \else + \@ReturnAfterFi{% + \ZREF@xr@checklist#3\ZREF@nil + }% + \fi +}% +\long\def\@ReturnAfterFi#1\fi{\fi#1}% +\def\ZREF@xr@checkkey#1#2\@nil{% + \zref@ifpropundefined{#2}{% + \zref@newprop{#2}{}% + }{}% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@xr@scanparams} +% \begin{macrocode} +\def\ZREF@xr@scanparams#1#2#3#4#5#6#7\ZREF@nil{% + \global\let#1\@empty + \ZREF@foundfalse + \ZREF@xr@scantitleref#1#2\TR@TitleReference{}{}\ZREF@nil + \ifZREF@found + \else + \g@addto@macro#1{\default{#2}}% + \fi + % page + \g@addto@macro#1{\page{#3}}% + % nameref title + \ifZREF@found + \else + \ifx\\#4\\% + \else + \zref@ifpropundefined{title}{% + \zref@newprop{title}{}% + }{}% + \g@addto@macro#1{\title{#4}}% + \fi + \fi + % anchor + \ifx\\#5\\% + \else + \zref@ifpropundefined{anchor}{% + \zref@newprop{anchor}{}% + }{}% + \g@addto@macro#1{\anchor{#5}}% + \fi + \ifx\\#6\\% + \else + \zref@ifpropundefined{url}{% + \zref@newprop{url}{}% + }{}% + \g@addto@macro#1{\url{#6}}% + \fi +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@xr@scantitleref} +% \begin{macrocode} +\def\ZREF@xr@scantitleref#1#2\TR@TitleReference#3#4#5\ZREF@nil{% + \ifx\\#5\\% + \else + \g@addto@macro#1{% + \default{#3}% + \title{#4}% + }% + \ZREF@foundtrue + \fi +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\ZREF@xr@urlcheck}% +% \begin{macrocode} +\def\ZREF@xr@urlcheck#1{% + \zref@ifrefcontainsprop{#1}{anchor}{% + \zref@ifrefcontainsprop{#1}{url}{% + }{% + \expandafter\g@addto@macro\csname Z@R@#1\expandafter\endcsname + \expandafter{% + \expandafter\url\expandafter{\ZREF@xr@url}% + }% + }% + }{% + }% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zxrsetup} +% Just one key for setting the default extension is currently used. +% \begin{macrocode} +\define@key{ZREF@XR}{ext}{% + \def\zref@xr@ext{#1}% +}% +\newcommand*{\zxrsetup}{% + \setkeys{ZREF@XR}% +}% +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</xr> +% \end{macrocode} +% +% +% \subsection{Module \xoption{hyperref}} +% +% UNFINISHED :-( +% +% \begin{macrocode} +%<*hyperref> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-hyperref}% + [2006/05/25 v1.2 Module hyperref for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% \begin{macrocode} +\zref@newprop{anchor}[]{% + \@ifundefined{@currentHref}{}{\@currentHref}% +}% +\zref@addprop\ZREF@mainlist{anchor}% +% \end{macrocode} +% +% \begin{macrocode} +%</hyperref> +% \end{macrocode} +% +% +% \subsection{Module \xoption{savepos}} +% +% Option \xoption{savepos} provides an interface for +% \pdfTeX's \cmd{\pdfsavepos}, see the manual for +% \pdfTeX. +% +% \subsubsection{Identification} +% +% \begin{macrocode} +%<*savepos> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-savepos}% + [2006/05/25 v1.2 Module savepos for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% \subsubsection{Availability} +% +% First we check, whether the feature is available. +% \begin{macrocode} +\begingroup + \@ifundefined{pdfsavepos}{% + \ZREF@ErrorNoLine{% + \string\pdfsavepos\space is not supported\MessageBreak + in this pdfTeX version% + }\ZREF@UpdatePdfTeX + \endgroup + \endinput + }{}% +\endgroup +% \end{macrocode} +% In PDF mode we are done. However support for DVI mode +% was added later in version 1.40.0. In earlier versions +% \cs{pdfsavepos} is defined, but its execution raises +% an error. +% \begin{macrocode} +\RequirePackage{ifpdf} +\ifpdf +\else + \ifnum\pdftexversion<140 % + \ZREF@ErrorNoLine{% + \string\pdfsavepos\space is not supported in DVI mode\MessageBreak + of this pdfTeX version% + }\ZREF@UpdatePdfTeX + \expandafter\expandafter\expandafter\endinput + \fi +\fi +% \end{macrocode} +% +% \subsubsection{Setup} +% +% \begin{macrocode} +\zref@newlist{savepos} +\zref@newprop*{posx}[0]{\the\pdflastxpos} +\zref@newprop*{posy}[0]{\the\pdflastypos} +\zref@addprop{savepos}{posx} +\zref@addprop{savepos}{posy} +% \end{macrocode} +% +% \subsubsection{User macros} +% +% \begin{macro}{\zsavepos} +% The current location is stored in a reference with the +% given name. +% \begin{macrocode} +\def\zsavepos#1{% + \@bsphack + \if@filesw + \pdfsavepos + \zref@labelbylist{#1}{savepos}% + \fi + \@esphack +} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zposx} +% \begin{macro}{\zposy} +% The horizontal and vertical position are available by +% \cs{zposx} and \cs{zposy}. Do not rely on absolute +% positions. They differ in DVI and PDF mode of \pdfTeX. +% Use differences instead. The unit of the position numbers +% is sp. +% \begin{macrocode} +\newcommand*{\zposx}[1]{% + \zref@extract{#1}{posx}% +}% +\newcommand*{\zposy}[1]{% + \zref@extract{#1}{posy}% +}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% Typically horizontal and vertical positions are used +% inside calculations. Therefore the extracting macros +% should be expandable and babel's patch is not applyable. +% +% Also it is in the responsibility of the user to marked +% used positions by \cs{zrefused} +% in order to notify \LaTeX\ about undefined references. +% +% \begin{macrocode} +%</savepos> +% \end{macrocode} +% +% +% \subsection{Module \xoption{dotfill}} +% +% \begin{macrocode} +%<*dotfill> +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{zref-dotfill}% + [2006/05/25 v1.2 Module dotfill for zref (HO)] +\RequirePackage{zref-base}[2006/05/25] +\@ifundefined{ZREF@baseok}{\endinput}{} +% \end{macrocode} +% +% For measuring the width of \cs{zdotfill} we use the features +% provided by module \xoption{savepos}. +% \begin{macrocode} +\RequirePackage{zref-savepos}[2006/05/25] +% \end{macrocode} +% For automatically generated label names we use the unique +% counter of module \xoption{base}. +% \begin{macrocode} +\zref@require@unique +% \end{macrocode} +% Configuration is done by the key value interface of package +% \xpackage{keyval}. +% \begin{macrocode} +\RequirePackage{keyval} +% \end{macrocode} +% The definitions of the keys follow. +% \begin{macrocode} +\define@key{ZREF@DF}{unit}{% + \def\ZREF@df@unit{#1}% +} +\define@key{ZREF@DF}{min}{% + \def\ZREF@df@min{#1}% +} +\define@key{ZREF@DF}{dot}{% + \def\ZREF@df@dot{#1}% +} +% \end{macrocode} +% Defaults are set, see user interface. +% \begin{macrocode} +\providecommand\ZREF@df@min{2} +\providecommand\ZREF@df@unit{.44em} +\providecommand\ZREF@df@dot{.} +% \end{macrocode} +% \begin{macro}{\zdotfillsetup} +% Configuration of \cs{zdotfill} is done by \cs{zdotfillsetup}. +% \begin{macrocode} +\newcommand*{\zdotfillsetup}{\setkeys{ZREF@DF}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\zdotfill} +% \cs{zdotfill} sets labels at the left and the right to get +% the horizontal position. \cs{zsavepos} is not used, because +% we do not need the vertical position. +% \begin{macrocode} +\newcommand*{\zdotfill}{% + \leavevmode + \global\advance\c@zref@unique\@ne + \begingroup + \def\ZREF@temp{zref@\number\c@zref@unique}% + \pdfsavepos + \zref@labelbyprops{\thezref@unique L}{posx}% + \setlength{\dimen@}{\ZREF@df@unit}% + \zref@ifrefundefined{\thezref@unique R}{% + \ZREF@dotfill + }{% + \ifnum\numexpr\zposx{\thezref@unique R}-\zposx{\thezref@unique L}\relax + <\dimexpr\ZREF@df@min\dimen@\relax + \hfill + \else + \ZREF@dotfill + \fi + }% + \pdfsavepos + \zref@labelbyprops{\thezref@unique R}{posx}% + \endgroup + \kern\z@ +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\ZREF@dotfill} +% Help macro that actually sets the dots. +% \begin{macrocode} +\def\ZREF@dotfill{% + \cleaders\hb@xt@\dimen@{\hss\ZREF@df@dot\hss}\hfill +} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</dotfill> +% \end{macrocode} +% \section{Installation} +% +% \paragraph{CTAN.} This package is available on +% CTAN\footnote{\url{ftp://ftp.ctan.org/tex-archive/}}: +% \begin{description} +% \item[\CTAN{macros/latex/contrib/oberdiek/zref.dtx}] The source file. +% \item[\CTAN{macros/latex/contrib/oberdiek/zref.pdf}] Documentation. +% \end{description} +% +% \paragraph{Unpacking.} The \xfile{.dtx} file is a self-extracting +% \docstrip\ archive. The files are extracted by running the +% \xfile{.dtx} through \plainTeX: +% \begin{quote} +% \verb|tex zref.dtx| +% \end{quote} +% +% \paragraph{TDS.} Now the different files must be moved into +% the different directories in your installation TDS tree +% (also known as \xfile{texmf} tree): +% \begin{quote} +% \sbox0{^^A +% \begin{tabular}{@{}>{\ttfamily}l@{$\quad\rightarrow\quad$}>{\ttfamily}l@{}} +% zref.sty & tex/latex/oberdiek/zref.sty\\ +% zref-base.sty & tex/latex/oberdiek/zref-base.sty\\ +% zref-abspage.sty & tex/latex/oberdiek/zref-abspage.sty\\ +% zref-counter.sty & tex/latex/oberdiek/zref-counter.sty\\ +% zref-dotfill.sty & tex/latex/oberdiek/zref-dotfill.sty\\ +% zref-hyperref.sty & tex/latex/oberdiek/zref-hyperref.sty\\ +% zref-lastpage.sty & tex/latex/oberdiek/zref-lastpage.sty\\ +% zref-perpage.sty & tex/latex/oberdiek/zref-perpage.sty\\ +% zref-savepos.sty & tex/latex/oberdiek/zref-savepos.sty\\ +% zref-titleref.sty & tex/latex/oberdiek/zref-titleref.sty\\ +% zref-totpages.sty & tex/latex/oberdiek/zref-totpages.sty\\ +% zref-user.sty & tex/latex/oberdiek/zref-user.sty\\ +% zref-xr.sty & tex/latex/oberdiek/zref-xr.sty\\ +% zref.pdf & doc/latex/oberdiek/zref.pdf\\ +% zref-example.tex & doc/latex/oberdiek/zref-example.tex\\ +% zref.dtx & source/latex/oberdiek/zref.dtx\\ +% \end{tabular}^^A +% }% +% \ifdim\wd0>\linewidth +% \mbox{}\nobreak\hskip0pt minus\leftmargin +% \usebox0 +% \nobreak\hskip0pt minus\rightmargin +% \else +% \usebox0 +% \fi +% \end{quote} +% If you have a \xfile{docstrip.cfg} that configures and enables \docstrip's +% TDS installing feature, then some files can already be in the right +% place, see the documentation of \docstrip. +% +% \paragraph{Refresh file databases.} If your \TeX~distribution +% (\teTeX, \mikTeX, \dots) rely on file databases, you must refresh +% these. For example, \teTeX\ users run \verb|texhash| or +% \verb|mktexlsr|. +% +% \subsection{Some details for the interested} +% +% \paragraph{Attached source.} +% +% The PDF documentation on CTAN also includes the +% \xfile{.dtx} source file. It can be extracted by +% AcrobatReader 6 or higher. Another option is \textsf{pdftk}, +% e.g. unpack the file into the current directory: +% \begin{quote} +% \verb|pdftk zref.pdf unpack_files output .| +% \end{quote} +% +% \paragraph{Unpacking with \LaTeX.} +% The \xfile{.dtx} chooses its action depending on the format: +% \begin{description} +% \item[\plainTeX:] Run \docstrip\ and extract the files. +% \item[\LaTeX:] Generate the documentation. +% \end{description} +% If you insist on using \LaTeX\ for \docstrip\ (really, +% \docstrip\ does not need \LaTeX), then inform the autodetect routine +% about your intension: +% \begin{quote} +% \verb|latex \install=y\input{zref.dtx}| +% \end{quote} +% Do not forget to quote the argument according to the demands +% of your shell. +% +% \paragraph{Generating the documentation.} +% You can use both the \xfile{.dtx} or the \xfile{.drv} to generate +% the documentation. The process can be configured by the +% configuration file \xfile{ltxdoc.cfg}. For instance, put this +% line into this file, if you want to have A4 as paper format: +% \begin{quote} +% \verb|\PassOptionsToClass{a4paper}{article}| +% \end{quote} +% An example follows how to generate the +% documentation with pdf\LaTeX: +% \begin{quote} +%\begin{verbatim} +%pdflatex zref.dtx +%makeindex -s gind.ist zref.idx +%pdflatex zref.dtx +%makeindex -s gind.ist zref.idx +%pdflatex zref.dtx +%\end{verbatim} +% \end{quote} +% +% \newcommand*{\bibpackage}[4]{^^A +% \bibitem{#1} +% Package \xpackage{#1}, #2, #3.^^A +% \ifx\\#4\\\else#4\fi\par +% } +% +% \begin{thebibliography}{99} +% \bibpackage{everyshi}{Martin Schr\"oder}{2001/05/15 v3.00} +% {\CTAN{macros/latex/contrib/ms/everyshi.dtx}} +% \bibpackage{footmisc}{Robin Fairbairns}{2004/01/23 v5.3a} +% {\CTAN{macros/latex/contrib/footmisc/footmisc.dtx}} +% \bibpackage{hyperref}{Sebastian Rahtz, Heiko Oberdiek}{2006/08/16 v6.75c} +% {\CTAN{macros/latex/contrib/hyperref/}} +% \bibpackage{lastpage}{Jeff Goldberg}{1994/06/25 v0.1b} +% {\CTAN{macros/latex/contrib/lastpage/}} +% \bibpackage{nameref}{Sebastian Rahtz, Heiko Oberdiek}{2006/02/12 v2.24} +% {\CTAN{macros/latex/contrib/hyperref/nameref.dtx}} +% \bibpackage{perpage}{David Kastrup}{2002/12/20 v1.0} +% {\CTAN{macros/latex/contrib/bigfoot/perpage.dtx}} +% \bibpackage{titleref}{Donald Arsenau}{2001/04/05 v3.1} +% {\CTAN{macros/latex/contrib/misc/titleref.sty}} +% \bibpackage{totpages}{Wilhelm M\"uller}{1999/07/14 v1.00} +% {\CTAN{macros/latex/contrib/totpages/}} +% \bibpackage{xr}{David Carlisle}{1994/05/28 v5.02} +% {\CTAN{macros/latex/required/tools/xr.pdf}} +% \bibpackage{xr-hyper}{David Carlisle}{2000/03/22 v6.00beta4} +% {\CTAN{macros/latex/contrib/hyperref/xr-hyper.sty}} +% \end{thebibliography} +% +% \begin{History} +% \begin{Version}{2006/02/20 v1.0} +% \item +% First version. +% \end{Version} +% \begin{Version}{2006/05/03 v1.1} +% \item +% Module perpage added. +% \item +% Module redesign as packages. +% \end{Version} +% \begin{Version}{2006/05/25 v1.2} +% \item +% Module dotfillmin added. +% \item +% Module base: macros \cs{zref@require@uniqe} and \cs{thezref@unique} +% added (used by modules titleref and dotfillmin). +% \end{Version} +% \end{History} +% +% \PrintIndex +% +% \Finale +\endinput |