How to make custom linked cross-references?

[Ted Pavlic]

Right now I am using something similar to the script below to do what I
want. I'm wondering if there is a better way.

The script below combines features from the prettyref and hyperref
packages. What I really want is something like \autoref that allows me
to have more control over the reference format. I know that with
\autoref I can modify \*name and \*autoref name in order to change
"Figure" to "Fig.", but I want more control over that. I want the
ability, for example, to place parentheses around equation references
("Eq. (4)") but not around table references ("Table 1").

I also want the ability to occassionally have a reference expand to a
plural format rather than a singular format. For example, sometimes I
might have a "Figs. 3 and 4" where "Figs. 3" links to a figure and "4"
links to a figure.

So what I did was create these commands:

\shortref{ reflabel }
\longref{ reflabel }
\longrefs{ reflabel }

All three hyperlink their text to the correct place. However, they
expand different text:

\shortref{ eq:my_equation } expands to "(1)"
\longref{ eq:my_equation } expands to "Eq. (1)"
\longrefs{ eq:my_equation } expands to "Eqs. (1)"

and similarly for a figure: (notice the lack of parentheses in the
expanded text)

\shortref{ fig:my_figure } expands to "1"
\longref{ fig:my_figure } expands to "Fig. 1"
\longrefs{ fig:my_figure } expands to "Figs. 1"

Downsides:

a) I REQUIRE that the first section of the label is something like
"eq:" or "fig:". A true \autoref would figure these things out
automatically without needing a special label prefix. I don't know how
to do this. I don't know if it's easy to do.

b) This method uses the prettyref package, but it looks like prettyref
is getting deprecated.

c) I'm almost positive there's a better way to do exactly this.

Any hints?







The code I'm currently using: (I've removed a few formats for brevity)

%=====
% These reference formats work with \prettyref to associate a label
name
% prefix (e.g. "fig:") with a reference format. \hyperref is used
within
% each format in order to link the entire reference to its target.
%
% \autoref could be used instead of \prettyref. In that case, the
\*name
% and/or \*autorefname macros would need to be redefined in a similar
% fashion and all \prettyref would have to be changed to \autoref.
% However, if this was done, it may be difficult to automatically place
% parentheses around equation numbers.
\usepackage{prettyref,hyperref,ifthen}
\newboolean{prettyrefname} \setboolean{prettyrefname}{false}
\newboolean{prettyrefplural} \setboolean{prettyrefplural}{false}
\newcommand{\prettyrefends}{\ifthenelse{\boolean{prettyrefplural}}{s}{}}
\newrefformat{lem}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Lemma\prettyrefends{}~}
{}%
\textup{\ref*{#1}}}}
\newrefformat{thm}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Theorem\prettyrefends{}~}
{}%
\textup{\ref*{#1}}}}
\newrefformat{cor}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Corollary\prettyrefends{}~}
{}%
\textup{\ref*{#1}}}}
\newrefformat{prop}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Proposition\prettyrefends{}~}
{}%
\textup{\ref*{#1}}}}
\newrefformat{fig}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Fig\prettyrefends{}.~}
{}%
\textup{\ref*{#1}}}}
\newrefformat{tab}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Table\prettyrefends{}~}
{}%
\textup{\ref*{#1}}}}
\newrefformat{eq}
{\hyperref[#1]{\ifthenelse{\boolean{prettyrefname}}
{Eq\prettyrefends{}.~}
{}%
\textup{(\ref*{#1})}}}

% The following implements a generalized hyperlinked \eqref
%
% \longref and \longrefs cause \prettyref to make a hyperlinked
% reference with a name (e.g. ``Fig. 1'' and ``Figs. 1'' respectively)
%
% \shortref makes a hypyerlinked reference with no name (e.g. ``(1)''
% for an equation and ``1'' for a figure
\newcommand{\shortref}[1]{\setboolean{prettyrefname}{false}%
\prettyref{#1}}

\newcommand{\longref}[1]{\setboolean{prettyrefname}{true}%
\setboolean{prettyrefplural}{false}%
\prettyref{#1}}

\newcommand{\longrefs}[1]{\setboolean{prettyrefname}{true}%
\setboolean{prettyrefplural}{true}%
\prettyref{#1}}
%=====

[Ulrich Diez]

Post by Ted Pavlic
What I really want is something like \autoref that allows me
to have more control over the reference format. I know that with
\autoref I can modify \*name and \*autoref name in order to change
"Figure" to "Fig.", but I want more control over that. I want the
ability, for example, to place parentheses around equation references
("Eq. (4)") but not around table references ("Table 1").
I also want the ability to occassionally have a reference expand to a
plural format rather than a singular format. For example, sometimes I
might have a "Figs. 3 and 4" where "Figs. 3" links to a figure and "4"

I think the basic problem is getting phrases like "section"
or "fig" into the link/reference also. For each counter there
is a macro \p@<counter> for such things.

You can (ab?)use it for achieving "single-case-customizability"
for single counters through another macro \customref which will
let you include leading and trailing phrases into hyperlinks.

Does the example below help you?

Ulrich


\documentclass{article}
%\usepackage{hyperref}

\newcommand*\customrefprefix{}%
\newcommand*\customrefpostfix{}%
\newif\ifcustomref
\customreffalse
\newcommand*\customrefatstar[3]{%
{%
\def\customrefprefix{#2}%
\def\customrefpostfix{#3}%
\customreftrue
\ref*{#1}%
\customreffalse
}%
}%
\newcommand*\customrefatnostar[3]{%
{%
\def\customrefprefix{#2}%
\def\customrefpostfix{#3}%
\customreftrue
\ref{#1}%
\customreffalse
}%
}%
\makeatletter
\newcommand*\customref{%
\@ifstar\customrefatstar\customrefatnostar
}%
%
\newcommand*\makerefcustomizable[1]{%
\expandafter\@ifdefinable\csname oldp@#1\endcsname{%
\expandafter\global
\expandafter\let
\csname oldp@#1\expandafter\endcsname\csname p@#1\endcsname
}%
\expandafter\gdef\csname p@#1\endcsname{%
\csname innerp@#1\expandafter\endcsname
}%
\expandafter\gdef\csname innerp@#1\endcsname##1{%
\protect\ifcustomref
\protect\customrefprefix
\protect\fi
\csname oldp@#1\endcsname
##1%
\protect\ifcustomref
\protect\customrefpostfix
\protect\fi
}%
}%
\makeatother

\usepackage{hyperref}

\begin{document}
\parskip=\medskipamount\relax
\parindent=0pt\relax
% Best use \makerefcustomizable when starting the document, not
% in the preamble. Otherwise it's results might get overridden
% by the hyperref-package which uses the \AtBeginDocument-hook
% a lot.
\makerefcustomizable{subsection}

\section{test}
\label{sec}
\subsection{sub-test}
\label{subsec}

normal ref to a label that refers to a counter the ref-command of
which was not made customizable:
\ref{sec}

normal ref to a label that refers to a counter the ref-command of
which was made customizable:
\ref{subsec}

custom-ref to a label that refers to a counter the ref-command of
which was not made customizable:
\customref{sec}{lead-phrase}{trail-phrase}

custom-ref to a label that refers to a counter the ref-command of
which was made customizable:
\customref{subsec}{lead-phrase}{trail-phrase}

\makeatletter
\gdef\***@subsection{subsection}
\let\***@subsection\relax
\makeatother
\makerefcustomizable{subsection}

\subsection{sub-test 2}
\label{subsec-2}

normal ref to a label that refers to a counter the ref-command of
which was made customizable:
\ref{subsec-2}

custom-ref to a label that refers to a counter the ref-command of
which was made customizable:
\customref{subsec-2}{lead-phrase}{trail-phrase}

\end{document}

[Ted Pavlic]

Well, the big reason I want this is so that I can change all figure
references at the top of the document in one place.

So, again, I really was looking for a sort of combination of \prettyref
and \autoref. Really, since I can change \auto*name, \autoref is almost
perfect. However, \autoref gives me no way to put parentheses around
equation references. I want a reference to a figure label to expand to
"Fig. 1" but a reference to an equation label to expand to "Eq. (1)".

That's why \prettyref seemed perfect. However, \prettyref doesn't
automatically do the linking. Plus, rather than reacting to the type of
the reference, it requires the label to start with something telling it
that information. (e.g., "sec:blah") Really, though, this last part is
ok with me.

So really I'm looking for a standard way to do my \shortref, \longref,
and \longrefs macros. It seems to me like something like this has to
already exist. It's not that strange of a request.

[Ulrich Diez]

Post by Ted Pavlic
Well, the big reason I want this is so that I can change all figure
references at the top of the document in one place.

...

Post by Ted Pavlic
However, \autoref gives me no way to put parentheses around
equation references. I want a reference to a figure label to expand to
"Fig. 1" but a reference to an equation label to expand to "Eq. (1)".

You can specify reference-appearance separately for each counter
by means of the -in my previous posting mentioned- associated

Post by Ted Pavlic
\prettyref doesn't automatically do the linking. Plus, rather than
reacting to the type of the reference, it requires the label to start
with something telling it that information. (e.g., "sec:blah") Really,
though, this last part is ok with me.

Not with me. If you customize \p@-macros directly, hyperlinkage will
done correctly and label-name is not of importance at all.

Again: In my previous posting I mentioned the \p@-macros.
Play with them.

\documentclass{article}
\usepackage{hyperref}
\begin{document}
\makeatletter
\renewcommand*\***@figure{Fig.\thinspace}
% A "trick" for getting something behind the number also:
\renewcommand*\***@equation{\expandafter\***@equation}
\newcommand*\***@equation[1]{Eq.(#1)}
\makeatother

\section{test}~
\section{test}

\begin{figure}
This is a figure
\caption{figure-sample}
\label{testfig}
\end{figure}

\begin{equation}
\label{fermat}
a^n+b^n=c^n
\end{equation}

Reference to float: \ref{testfig}
Reference to equation: \ref{fermat}

\end{document}

By the way: You could also use \customref from my
previous posting for creating macros which always call \customref
with same arguments and thus yield standardized
appearance dependent on the reference-command used.

Ulrich

[Ted Pavlic]

Post by Ulrich Diez
done correctly and label-name is not of importance at all.

I see. I guess I misunderstood. I thought those \customrefs were
actually doing the referencing. I didn't understand that \customref
changed the way \ref worked.

In that case, that would work... However, that seems just as complex as
my current method. I would still need to use hyperref, so I'd still
have a preamble as big as my current one... in fact, possibly longer.

(plus, I know a little about LaTeX and I know even less about TeX.
Seeing lots of \'s and @'s without lots of {'s and }'s intimidates me
to no end)

[Ulrich Diez]

Post by Ted Pavlic
In that case, that would work... However, that seems just as complex as
my current method. I would still need to use hyperref, so I'd still
have a preamble as big as my current one... in fact, possibly longer.

...

You can put your preamble-stuff into a .sty-file and load that
via \usepackage. Thus preamble will be shorter.
I think results of manual customization are worth the efforts.

Short story
===========

For each counter you can use the same pattern:

For changing the appearance of how a special counter is referenced,
you need to adjust it's associated \p@-macro.
In case you just want too add a phrase in front of the number, write:

\makeatletter
\renewcommand*\***@counter{lead-phrase}
\makeatother

In case you want too add a phrase in front and behind the number, write:

\makeatletter
\renewcommand*\***@counter{\expandafter\***@counter}
\newcommand*\***@counter[1]{%
lead-phrase#1trail-phrase%
}%
\makeatother

LaTeX will internally make \***@counter's #1 the token \thecounter.
The pattern is the same for all counters.
E.g. for adjusting "figure", replace the phrase "counter" in the
code-snippets above by the phrase "figure" and you get e.g

\makeatletter
\renewcommand*\***@figure{\expandafter\***@figure}
\newcommand*\***@figure[1]{%
Fig.~(#1)%
}%
\makeatother

By the way: \p@-macros are LaTeX2e-kernel-specific. You don't need
the hyperref-package. But if you customize them and also use hyperref,
hyperlinks will not only be created from the numbers but from the
whole phrases.
(One possibility would be:
Fig.~(\hyperlink{anchor}{1})
But you get something like
\hyperlink{anchor}{Fig.~(1)})

Long story
==========

Post by Ted Pavlic
(plus, I know a little about LaTeX and I know even less about TeX.
to no end)

No need for fear or intimidation in TeX. You can try anything. A widely
used method in TeX is: Change things, compile and check for error-message.
If no error-message and output as expected: All right. Otherwise unchange
things and try again.
Actually a TeX-error-message is nothing to worry about. The system won't
crash or hang-up, the computer won't get destroyed. Getting a TeX-error-
message won't touch your integrity.
You see: Changing a tex-source-file won't affect the computer or the
compiler-program itself. (Unless you willingly specify very obscure
features like \write18 = command-line-call or pass command-line-
parameters for dumping a format-files or the like...)
The only thing I strongly recommend to do is: Before playing around and
changing things, save backup-copies of the source-files you play around
with. If you need to "unchange" a lot of things, this might turn out
very helpful.

About category-codes:
---------------------

TeX reads stuff from input-file or terminal. Before doing anything
else, it forms "tokens" (e.g. control-sequences, or plain characters)
from what it reads. Anything else takes place in terms of tokens.

The category-code of a character determines how TeX will "treat"
that character when reading it from input-file or terminal for
creating TeX-tokens.

E.g.,
- the character "\" has catcode 0, which means that whenever TeX
encounters that character while _reading_ TeX-input from file
or terminal, from that point on it will have to gather the name
of a control-sequence. If you assign "a" the catcode 0 also,
TeX will try to gather the name of a control-sequence from
consecutive characters also whenever encountering "a".
\TeX and aTeX will be equal. \chapter would not work any more as
expected - input would while being read be interpreted equally
to \ch\pter .
- the character "{" has category-code 1, which means that whenever
TeX encounters this character while _reading_ TeX-input from file
or terminal, it will either have to start a new group or to start
gathering an argument.
- the character "}" has category-code 2, which means that whenever
TeX encounters this character while _reading_ TeX-input from file
or terminal, it will either have to end the current group or to
end gathering an argument.

When TeX is gathering an (undelimited) argument, it will consist of
the following token, unless that token has catcode 1/is an
opening-brace. In that case, argument will be gathered till the
matching catcode-2-token /closing-brace is found.

E.g. \newcommand takes one argument which is the name of a to-be-
defined-control-sequence and at least another argument which
is the replacement-text.
Thus \newcommand{\foo}{...} and \newcommand\foo{...} delivers exactly
the same result as the first argument consists of only one token...

The category-code 14 means that a character shall be treated
like a normal letter. That means when writing \makeatletter,
the category-code of "@" gets changed to 14, which means that
TeX will in further reading from the input-file, treat it like
any other character a,b,c... also and thus you can use it in the
same way as these characters and thus also use it within names of
control-sequences.
\makeatother makes the category-code of "@" 12 (=other).
Characters of catcode 12 cannot be used within names of
control-sequences.

So a nice trick is: If you don't want the user to play
around or use some control-sequence, make "@" a normal letter,
create and use that control-sequence and at user-level
make "@" other again. Thus a non-experienced user cannot use
your "internal" command as he cannot call it as he doesn't
know that before calling it,"@" must be made an ordinary
letter again (which can be used within control-sequences)
by changing it's catcode e.g. via \makeatletter.

Category-code-change is only about that TeX understands what
is meant while _reading_ the input-file. A category-code change
does not affect stuff that is already read and tokenized.

For example you can write

...
\makeatletter
\newcommand\***@controlsequence{something}
\newcommand\noatcontrolsequence{\***@controlsequence}
\makeatlother

\noatcontrolsequence
...

The definition/replacement-text both of
\***@controlsequence and \noatcontrolsequence is read/tokenized
while @ is a letter.

For tokenizing a _call_ to \noatcontrolsequence/for successfully calling
\noatcontrolsequence, you don't need @ to be a letter any more as
there is no @ in that control-sequence-name so that there is no room for
"misinterpretation" while reading that control-sequence-name from input.
And the replacement-text was already read from input and tokenized before,
when @ was a letter. You'd better not think of replacement-text as "text",
better say it's "replacement-tokens". The tokens were created when
\newcommand took place.

About counters in LaTeX
-----------------------

Whenever defining a counter <foo> via \newcounter{<foo>},
internally (beneath other things)
- a control-sequence \the<foo> gets defined which is to print
the value of a counter in a nicely-formatted manner (e.g. in
rabic, roman or alphabetic.)
- another control-sequence \***@foo is defined. You can use it
for providing a "Prefix-phrase" which shall be added in front
of the number whenever a value created by that counter gets
referenced by the \ref-command.


About referencing in LaTeX
--------------------------

The concept of referencing in LaTeX is as follows:
- Whenever you write \label{<name>}, information about label-name,
page-number, counter-number (e.g. section, chapter, enumerate,
figure...) plus (in case of hyperref) information about
hyperanchor-name for hyperlinkage, will be written to the
aux-file.
When in consecutive LaTeX-runs the aux-file is read after
reading the preamble and before beginning the document,
control-sequences \r@<label> get formed from what was
written to the aux-file.
Referencing-commands like \ref{<name>} or \pageref{<name>}
internally call \r@{<name>} and pick from it's expansion
the values they need. E.g. \pageref will pick the page-number,
\ref will pick the "counter-number".
- Above I wrote:
Whenever you write \label{<name>}, information about
label-name, page-number, counter-number (e.g. section,
chapter, enumerate, figure...) plus (in case of hyperref)
information about hyperanchor-name for hyperlinkage, will
be written to the aux-file.
A good question would be: "counter-number" - how does \label
know which counter to use. Shall "chapter" be used? or
shall "figure" be used?...
The answer is: Actually \label does not know. It always takes
what is written to the macro \@currentlabel.
\@currentlabel always gets changed/modified when the control-sequence
\refstepcounter is used.
E.g. \refstepcounter{foo} makes \@currentlabel to expand to
\***@foo+<current value of foo printed through \thefoo>.
Document-structuring-commands like \chapter, \section,
\caption (in floats, figures, tables...), \item in enumerate
increment their counters in terms of \refstep.
#1->\stepcounter {#1}\***@edef \@currentlabel {\csname p@#1\endcsname
\csname the#1\endcsname }.

Example: \refstepcounter{foo}
#1=foo ->
\stepcounter {foo}
\***@edef \@currentlabel {
\csname ***@foo\endcsname
\csname thefoo\endcsname
}
, whereby \csname ***@foo\endcsname means that the token \***@foo shall be formed
and \csname thefoo\endcsname means that the token \thefoo shall be formed.

-> \@currentlabel will contain the current expansion of \***@foo\thefoo

If you want to add something both in front and behind \thefoo, you could
make a trick:
Define \***@foo to take an argument. \***@foo is expanded first, so it would
"grab" the token \thefoo as it's argument.
In the replacement-text of \***@foo you can place something both in front of
and behind the argument.
There is a small problem: In the definition of \refstepcounter
\csname...\endcsname-constructs are used. That means: If \***@foo would grab
an argument directly, it would take the token "\csname" from the consecutive
\csname thefoo\endcsname. We should achieve that the token "\thefoo"
gets formed from the \csname...\endcsname-construct _before_ grabbing
the argument. So let's define \***@foo to call an argument-grabber
\***@foo after having formed \thefoo from \csname thefoo\endcsname.
Defining \***@foo to "\expandafter\***@innerfoo" yields:

\refstepcounter{foo}
->
\stepcounter {foo}
\***@edef \@currentlabel {
\csname ***@foo\endcsname
\csname thefoo\endcsname
}

\csname ***@foo\endcsname is expanded first
The edef-ing-chain gets:

-> \***@foo\csname thefoo\endcsname
-> \expandafter\***@foo\csname thefoo\endcsname
-> \***@foo\thefoo

\***@foo grabs \thefoo as it's argument and does something with it.
E.g. place some phrase behind and before it.

So the pattern for customizing referencing-prefix of a counter "foo" is:
Adjust \p@"foo".
In case you don't want something behind the number, just redefine \***@foo
to expand to the phrase you wish in front of the number.
In case you want something behind that number also, redefine \***@foo
to call \expandafter before calling the "argument-grabber". Then define
an argument-grabber which takes one argument. Consider that the argument
will always be the token \thefoo.


Ulrich

[Robin Fairbairns]

Post by Ulrich Diez

Post by Ted Pavlic
In that case, that would work... However, that seems just as complex as
my current method. I would still need to use hyperref, so I'd still
have a preamble as big as my current one... in fact, possibly longer.

...
You can put your preamble-stuff into a .sty-file and load that
via \usepackage. Thus preamble will be shorter.
I think results of manual customization are worth the efforts.
Short story
===========
[lots snipped]

you've obviously got more time to spend on this than a lot of us: why
don't you put such dissertations on the web so's they're easier to
refer to (google groups references are *such* a pain).

[Ulrich Diez]

Post by Ulrich Diez
The category-code 14 means that a character shall be treated
like a normal letter. That means when writing \makeatletter,
TeX will in further reading from the input-file, treat it like
any other character a,b,c... also and thus you can use it in the
same way as these characters and thus also use it within names of
control-sequences.

That's all rubbish. Sorry. It's not catcode14, it's 11.

Ulrich

[Ulrich Diez]

Post by Ted Pavlic
... However, that seems just as complex as
my current method. I would still need to use hyperref, so I'd still
have a preamble as big as my current one... in fact, possibly longer.
(plus, I know a little about LaTeX and I know even less about TeX.
to no end)

That's funny:
Now I will need similar functionality as described by you,so I created a
small .sty-file. Maybe you are interested. It let's you customize
appearance of reference for each counter in the preamble.
Also it provides a \customizeref-command for changing that
appearance for single cases.

Ulrich

<=====Start of custref.sty=====>
%
% Manual/macro-description can be found after \endinput so that it
% won't be read when loading the package. Also you don't need
% these '%'-characters all the time...
%
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{custref}
[2006/05/01 v0.01 customize the appearance of ref-erenced counters]
\newcommand*\nolinkref[1]{%
{%
\@ifundefined{@refstar}%
{\ref{#1}}%
{\ref*{#1}}%
}%
}%
\newcommand*\nolinkpageref[1]{%
{%
\@ifundefined{@pagerefstar}%
{\pageref{#1}}%
{\pageref*{#1}}%
}%
}%
\newcommand*\nolinkcustomizeref[3]{%
{%
\@ifundefined{@pagerefstar}%
{\customizeref{#1}{#2}{#3}}%
{\customizeref*{#1}{#2}{#3}}%
}%
}%
\newcommand*\refleadphrase{}%
\newcommand*\reftrailphrase{}%
\newcommand*\setrefphrases{}%
\newcommand*\resetphrasemacros{%
\renewcommand*\refleadphrase{}%
\renewcommand*\reftrailphrase{}%
\renewcommand*\setrefphrases{}%
}%
\newcommand*\makerefcustomizeable[3]{%
\AtBeginDocument{%
\expandafter\renewcommand\expandafter*\csname p@#1\endcsname{%
\csname innerp@#1\expandafter\endcsname
}%
\expandafter\newcommand\expandafter*\csname innerp@#1\endcsname[1]{%
{%
\expandafter\protect\csname setstandardphrases@#1\endcsname
\protect\setrefphrases
\protect\refleadphrase##1\protect\reftrailphrase
}%
}%
\expandafter\newcommand
\expandafter*%
\csname setstandardphrases@#1\endcsname{%
\toks@{#2}%
\***@edef\refleadphrase{%
{\protect\resetphrasemacros\the\toks@}%
}%
\toks@{#3}%
\***@edef\reftrailphrase{%
{\protect\resetphrasemacros\the\toks@}%
}%
}%
}%
}%
\@onlypreamble\makerefcustomizeable
\newcommand*\customizerefatnostar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{#2}%
\***@edef\refleadphrase{%
{\protect\resetphrasemacros\the\toks@}%
}%
\toks@{#3}%
\***@edef\reftrailphrase{%
{\protect\resetphrasemacros\the\toks@}%
}%
}%
\ref{#1}%
}%
}%
\newcommand*\customizerefatstar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{#2}%
\***@edef\refleadphrase{%
{\protect\resetphrasemacros\the\toks@}%
}%
\toks@{#3}%
\***@edef\reftrailphrase{%
{\protect\resetphrasemacros\the\toks@}%
}%
}%
\ref*{#1}%
}%
}%
\newcommand*\customizeref{\@ifstar\customizerefatstar\customizerefatnostar}%
\endinput
%%
%%
!!!! Here's the promised manual'n stuff !!!!

1. Legal stuff
==============
What is it?: A .sty-file for LaTeX2e, loadable via \usepackage
in the preamble.
Copyright: custref.sty [2006/05/01 v0.01] (C) Ulrich Diez
Author: Ulrich Diez (***@alumni.uni-tuebingen.de)
Licence: LPPL
Submitted to CTAN: No. If somebody wants the package on CTAN,
please contact the author/current maintainer
via e-mail.
Maintenance-status: At may 01, 2006 this sty-file was maintained by
Ulrich Diez.
If somebody wants to overtake maintenance of
the file custref.sty, please contact the author/
current maintainer via e-mail.
Warranties: None. Usage is atyour own risk. If something breaks,
you may keep the pieces.

This file came into being due to a "feature" request of Ted Pavlic
at comp.text.tex (usenet). For more details google the initial-message's
ID: <***@j33g2000cwa.googlegroups.com> .

2. Changes to LaTeX-internals
=============================
Each <counter> defined by LaTeX2e's \newcounter-macro provides
a macro \p@<counter> which is intended for providing some
referencing-prefix. Usually it is empty. This package provides
means for redefining these \p@-macros and thus might break when
being used together with other packages which do the same.

3. Usage
========

Intro
-----

People often wish to customize the way in which counters appear when
referencing takes place. E.g., when referencing a section-counter,
\ref{sec-bla} should deliver something like "section~23", but when
referencing figures, \ref{fig} should deliver something like
"Fig.~(7)".
When looking at these examples, you can find that actually the
reference-text is made of three parts:
1. Some leading phrase (e.g. "Fig.~(")
2. The reference-number as "spit out" by \the<counter>
3. Some closing-phrase (e.g. ")")

package-loading
---------------
in the preamble via \usepackage{custref}


preamble-macro \makerefcustomizable
-----------------------------------

This package provides a preamble-macro
\makerefcustomizable{<counter>}
{<standard-leading-phrase>}
{<standard-trailing-phrase>}
by means of which you can specify the appearance for single counters
when they get referred by means of the \ref-macro.
That means:
You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

, you will get:

A reference to section~(5) of this book

and in case of using hyperref, the hyperlinked phrase is
"section~(5) of this book"

macro \customizeref
-------------------

There is another macro \customizeref for usage within the document.
\customizeref takes 3 arguments:
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}

When applying \customizeref to a label instead of \ref, the leading- and
trailing-phrase of the reference will be formed from \customizeref's
second and third argument _instead_ of what was provided to
\makerefcustomizeable as second and third argument.

You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizeable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

A reference to \customizeref{thissection}{A}{B}

, you will get:

A reference to section~(5) of this book

A reference to A5B

and in case of using hyperref, the first hyperlinked phrase
is "section~(5) of this book", the second is "A5B".

\nolinkref, \nolinkpageref, \nolinkcustomizeref
-----------------------------------------------
A weird but nonetheless existing problem/case is:
You might wish to take reference to yet another label within
\customizeref's second (<this time's-leading-phrase>)-argument
or \customizeref's tird (<this time's-trailing-phrase>)-argument,
e.g. in order to create a hyperlink to only the fifth section of
your book from a phrase like
"chapter 7, section~(5), page 11 of this book".
Simply nesting \ref, \pageref or \customizeref won't work as this
would mean to create hyperlinks in hyperlinks which is not
supported by any driver/viewer yet. Therefore the macros
\nolinkref, \nolinkpageref, \nolinkcustomizeref are provided.
You can use them within the arguments of \customizeref.

Another issue is:
-----------------
If you did not apply the macro \makerefcustomizeable to a
counter in the preamble, but take reference to it via
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}
, the effect will be the same as if you had just written
\ref{<label>} into your source-code instead.

This is because \customizeref heavily uses and relies on
the p@-macros associated to the counters being (re)defined by
\makerefcustomizable in a special way.

4. hyperlinks across long lines
===============================
You can create very long link-phrases by means of this package.
If you do so, make sure that your viewer/driver supports hyper-
links with linebreaks. pdfTeX and pdfe(La)TeX do so.
Most DVI-viewers do not.

5. Usage-example
================

You can copy-paste this example to some separate-file, run it
through (pdf)LaTeX and see how the package works:

\documentclass{article}

\usepackage{hyperref}% Hyperref is not a requirement, but we want
% to see the hyperlinks...
\usepackage{custref}

\makerefcustomizeable{subsection}
{std-lead-phrase-for section~}
{~std-trail-phrase-for section}
\makerefcustomizeable{figure}
{std-lead-phrase-for-figure~}
{~std-trail-phrase-for-figure}

\begin{document}
\parskip=\medskipamount\relax
\parindent=0pt\relax

\section{first section}
\label{firstsection}
This is first section.

\begin{figure}
This is a figure in first section.
\caption{figure's caption}
\label{fig}
\end{figure}

\subsection{first sub-section}
\label{firstsubsection}
This is first sub-section.

\newpage
\section{referencing}

subsection and figure are made "customizeable".
section is not.

This is reference to first sub-section:
\ref{firstsubsection}

This is customize-reference to first sub-section:
\customizeref{firstsubsection}
{customize~}
{~customize}

This is reference to first section:
\ref{firstsection}

This is (effectless) customize-reference to first section:
\customizeref{firstsection}
{customize~}
{~customize}

This is reference to figure:
\ref{fig}

This is customize-reference to figure:
\customizeref{fig}
{customize~}
{~customize}

This is customize-reference to figure with other references
in the arguments:
\customizeref{fig}%
{see page~\nolinkpageref{fig} for figure~}%
{ of the \nolinkcustomizeref{firstsection}{}{}$^{st}$ section}%

\end{document}

%%
%% End of file `custref.sty'.
<=====End of custref.sty=====>

[Ted Pavlic]

Ulrich --

Both of your messages were very informative.

I've always wondered something, and I think you suggest the answer to
it here. When creating new environments (for example, but this could be
generalized to anything that has a "before" and an "after" argument), I
often want to start a command in the "before" and end it in the
"after." For example, (this is contrived) I might want to create a
"bold" environment that surrounds the entire environment in \textbf{}.
Ideally, I would like to put "\textbf{" in the before argument and "}"
in the after argument. However, this causes problems when parsing
because LaTeX is confused by the broken curly braces. It sounds like
you'r suggesting that there is a way for me to change how the curly
brace is interpretted within the "before" and "after" environments so
that I can define the environment and yet still have the
functionality... (though this may confuse my editor's syntax
highlighter)

Also, I always wondered what the whole \makeatletter was doing... Now I
(sorta) understand.

I also think that the style file you provided is VERY elegant. That is,
the functionality it implements is really terrific.

HOWEVER, I'm hesitant to use it for this particular project. You see,
this is for a submission to a journal (Engineering Applications of
Artificial Intelligence) must already have some internal method of
doing what I want. This is an Elsavier journal, so I have a style file
from them, but it doesn't do anything special with its references. It
implies in the documentation for the style file that something like
\autoref of \prettyref should be used. (as well as \citep and \citet
from natbib) However, \autoref and \prettyref do not do linking like
the JOURNAL does. In every journal example, they do the linking from
"Fig. 1" and not just "1".

The journal's submission guidelines say to avoid long custom macros/etc
and to use standard style files.

That's why I was looking for a way to do this that already existed that
would require the least amount of effort for the editors.

So while I may use your (again, very elegant) style file in some of my
own projects, I probably won't use it in this particular submission. If
I can't find a way to do what I want, I may just use standard
referencing (I'm guessing lots of other people do that) and count on
the editors to make any needed changes.

[Ulrich Diez]

Ted Pavlic wrote:

...

Post by Ted Pavlic
However, this causes problems when parsing
because LaTeX is confused by the broken curly braces. It sounds like
you'r suggesting that there is a way for me to change how the curly
brace is interpretted within the "before" and "after" environments so
that I can define the environment and yet still have the
functionality... (though this may confuse my editor's syntax
highlighter)

Nope. My sty-file does not contain any brace-hacking at all. But if you need
some environment that gathers up the content of a box, have a look at
the LaTeX2e-standard-environment "lrbox". I want to say: Gather your stuff
into a box by the rbox-like-environment. At the end of the environment set
that box in bold-face or the style you like. Something like \textbf{\usebox...}
or \textbf{\unvbox...}. Perhaps you need
\expandafter\textbf\expandafter{\unvbox...}. Don't know. Just play around
and find out :-)

Post by Ted Pavlic
This is an Elsavier journal, so I have a style file
from them, but it doesn't do anything special with its references. It
implies in the documentation for the style file that something like
\autoref of \prettyref should be used. (as well as \citep and \citet
from natbib) However, \autoref and \prettyref do not do linking like
the JOURNAL does. In every journal example, they do the linking from
"Fig. 1" and not just "1".

Perhaps they use hyperref's \hyperref-macro ... Instead of anchor and phrase
you can also provide label and phrase there. But then you _must_ use
the hyperref-package. I think with customref you don't have to.

Post by Ted Pavlic
The journal's submission guidelines say to avoid long custom macros/etc
and to use standard style files.

One of the problems is that they don't like to install custom/homebrewed packages
and .sty-files in their systems.

Post by Ted Pavlic
So while I may use your (again, very elegant) style file in some of my
own projects, I probably won't use it in this particular submission. If
I can't find a way to do what I want, I may just use standard
referencing (I'm guessing lots of other people do that) and count on
the editors to make any needed changes.

I think there is a misunderstanding:
Actually custref does not "change" many internals or break with standards. At least
this is my point of view. The only existing-resource that is modified, is the
\p@<counter>-macros which usually are just "empty", not used and by misguided
people considered worthless.
When reading sources2e, I came to the conclusion that these nice hardly ever used
\p@<counter>-macros were _intended_ as hooks for reference-customizing by
the user/author. If I got it right, hyperref does not harm or change that \p@-concept.
That's why custref works with hyperref.
When using custref, you will -in the aux-file-entries- still find the same argument-
structure as without. Nobody said that \p@-macros may not lead to writing
_unexpanded calls_ to macros into the aux-file. But that's all what is done by custref.
The calls get expanded when the arguments are "fetched" by \ref or \pageref...
I did not even touch the definition of \label, \ref or \pageref. These macros still take
their argument from the aux-entry. The argument itself does the work when it gets
expanded. I don't think this is a break with conventions.
I admit, there are packages like "ifthen". ifthen to a certain extent makes comparing
numerical reference-values easy. But if I got it right, that will fail as soon as you decide
to use the \p@<conter>-macro for the purposes intended by the authors of the
LaTeX2e-kernel. It will also fail as soon as you redefine \the<counter> to something
different from just one plain number. It's something that is likely to break as soon as
you decide at all to modify/customize something about counters and referencing.
Nonetheless I now added the macros \extractpagerefnum and \extractrefnum to the
custref package in order to facilitate the creation of a workaround for such situations.
If interested see my other posting.

Ulrich

[Robin Fairbairns]

Post by Ulrich Diez
...

Post by Ted Pavlic
However, this causes problems when parsing
because LaTeX is confused by the broken curly braces. It sounds like
you'r suggesting that there is a way for me to change how the curly
brace is interpretted within the "before" and "after" environments so
that I can define the environment and yet still have the
functionality... (though this may confuse my editor's syntax
highlighter)

Nope. My sty-file does not contain any brace-hacking at all. But if you need
some environment that gathers up the content of a box, have a look at
the LaTeX2e-standard-environment "lrbox". I want to say: Gather your stuff
into a box by the rbox-like-environment. At the end of the environment set
that box in bold-face or the style you like. Something like \textbf{\usebox...}
or \textbf{\unvbox...}. Perhaps you need
\expandafter\textbf\expandafter{\unvbox...}. Don't know. Just play around
and find out :-)

no. things are typeset before putting them in a box, so the things in
the box aren't tokens but character boxes. \textbf has no effect on
them whatever.

there are techniques for gathering the contents of environments into
token registers, and \textbf{\the\toks\foo} does what you want.
however, the technique isn't necessary at all for such a simple
command as \textbf: an environment is after all a group, and apart
from playing with with spacing before and after, there's little else
that \textbf does.

[Ted Pavlic]

I was just using \textbf as an example.

There are plenty of other examples where I think I'd want an
environment:

\begin{myenvironment}
body
\end{myenvironment}

such that the contents are surrounded by a command \mycommand{body}.

Can you explain one of these simple techniques? How do I build an
"myenvironment" above so that it automatically surrounds body with
"mycommand"?

[Ulrich Diez]

Hello!

I found that custref.sty will break some "features" of the ifthen-package
which are related to extracting "plain" page- or reference-number-values
from labels.
In order to facilitate the creation of a workaround, I decided to implement
two macros \extractrefnum and \extractpagerefnum.
More info can be found in the usage-section.

Ulrich

=========================<start of file `custref.sty'>=========================
%
% Manual/macro-description can be found after \endinput so that it
% won't be read when loading the package. Also you don't need
% these '%'-characters all the time...
%
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{custref}
[2006/05/02 v0.02 customize the appearance of ref-erenced counters]
\@ifdefinable\***@extractnum{%
\newif\***@extractnum
\global\@extractnumfalse
}%
\@ifdefinable\extractnum{%
\long\gdef
\extractnum\bgroup\setrefphrases\refleadphrase#1\reftrailphrase\egroup{#1}%
}%
\newcommand*\nolinkref[1]{%
{%
\@ifundefined{@refstar}%
{\ref{#1}}%
{\ref*{#1}}%
}%
}%
\newcommand*\nolinkpageref[1]{%
{%
\@ifundefined{@pagerefstar}%
{\pageref{#1}}%
{\pageref*{#1}}%
}%
}%
\@ifdefinable\@innerextractpagerefnum{%
\def\@innerextractpagerefnum#1#2#3#4\@nil{%
\@expandtwoargs\@tempa{\noexpand#1}{#3}%
}%
}%
\newcommand*\extractpagerefnum[3][\newcommand*]{%
\begingroup
\expandafter\ifx\csname r@#3\endcsname\relax
\protect\***@refundefinedtrue
\@***@warning{Reference `#3' on page \thepage\space
undefined}%
\endgroup
#1#2{0}%
\else
\def\@tempa{%
\def\@tempa####1{%
\endgroup#1####1%
}%
\@innerextractpagerefnum{#2}%
}%
\@extractnumtrue
\expandafter\expandafter
\expandafter\@tempa
\csname r@#3\endcsname\empty\empty\empty\empty\@nil
\@extractnumfalse
\fi
}%
\@ifdefinable\@innerextractrefnum{%
\def\@innerextractrefnum#1#2#3#4\@nil{%
\@expandtwoargs\@tempa{\noexpand#1}{#2}%
}%
}%
\newcommand*\extractrefnum[3][\newcommand*]{%
\begingroup
\expandafter\ifx\csname r@#3\endcsname\relax
\protect\***@refundefinedtrue
\@***@warning{Reference `#3' on page \thepage\space
undefined}%
\endgroup
#1#2{0}%
\else
\def\@tempa{%
\def\@tempa####1{%
\endgroup#1####1%
}%
\@innerextractrefnum{#2}%
}%
\@extractnumtrue
\expandafter\expandafter
\expandafter\@tempa
\csname r@#3\endcsname\empty\empty\empty\empty\@nil
\@extractnumfalse
\fi
}%
\newcommand*\nolinkcustomizeref[3]{%
{%
\@ifundefined{@pagerefstar}%
{\customizeref{#1}{#2}{#3}}%
{\customizeref*{#1}{#2}{#3}}%
}%
}%
\newcommand*\refleadphrase{}%
\newcommand*\reftrailphrase{}%
\newcommand*\setrefphrases{}%
\newcommand*\resetphrasemacros{%
\renewcommand*\refleadphrase{}%
\renewcommand*\reftrailphrase{}%
\renewcommand*\setrefphrases{}%
}%
\newcommand*\makerefcustomizeable[3]{%
\AtBeginDocument{%
\expandafter\renewcommand\expandafter*\csname p@#1\endcsname{%
\csname innerp@#1\expandafter\endcsname
}%
\expandafter\newcommand\expandafter*\csname innerp@#1\endcsname[1]{%
\expandafter\protect\csname setstandardphrases@#1\endcsname
\protect\bgroup
\protect\setrefphrases
\protect\refleadphrase##1\protect\reftrailphrase
\protect\egroup
}%
\expandafter\newcommand
\expandafter*%
\csname setstandardphrases@#1\endcsname[1]{%
\***@extractnum
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
{\extractnum##1}%
{%
##1%
\toks@{{\resetphrasemacros#2}}%
\edef\refleadphrase{\the\toks@}%
\toks@{{\resetphrasemacros#3}}%
\edef\reftrailphrase{\the\toks@}%
}%
}%
}%
}%
\@onlypreamble\makerefcustomizeable
\newcommand*\customizerefatnostar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{{\resetphrasemacros#2}}%
\edef\refleadphrase{\the\toks@}%
\toks@{{\resetphrasemacros#3}}%
\edef\reftrailphrase{\the\toks@}%
}%
\ref{#1}%
}%
}%
\newcommand*\customizerefatstar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{{\resetphrasemacros#2}}%
\edef\refleadphrase{\the\toks@}%
\toks@{{\resetphrasemacros#3}}%
\edef\reftrailphrase{\the\toks@}%
}%
\ref*{#1}%
}%
}%
\newcommand*\customizeref{\@ifstar\customizerefatstar\customizerefatnostar}%
\endinput
%%
%%
!!!! Here's the promised manual'n stuff !!!!

1. Legal stuff
==============
What is it?: A .sty-file for LaTeX2e, loadable via \usepackage
in the preamble.
Copyright: custref.sty [2006/05/02 v0.02] (C) Ulrich Diez
Author: Ulrich Diez (***@alumni.uni-tuebingen.de)
Licence: LPPL
Submitted to CTAN: No. If somebody wants the package on CTAN,
please contact the author/current maintainer
via e-mail.
Maintenance-status: At may 02, 2006 this sty-file was maintained by
Ulrich Diez.
If somebody wants to overtake maintenance of
the file custref.sty, please contact the author/
current maintainer via e-mail.
Warranties: None. Usage is atyour own risk. If something breaks,
you may keep the pieces.

This file came into being due to a "feature-request" of Ted Pavlic
at comp.text.tex (usenet). For more details google the initial-message's
ID: <***@j33g2000cwa.googlegroups.com> .

2. Changes to LaTeX-internals
=============================
Each <counter> defined by LaTeX2e's \newcounter-macro provides
a macro \p@<counter> which is intended for providing some
referencing-prefix. Usually it is empty. This package provides
means for redefining these \p@-macros and thus might break when
being used together with other packages which do the same.

3. Compatibility to other packages
==================================
I assume that this package will break some features of e.g. the
ifthen-package. The reason is: You cannot extract plain
"hyperlinkless" reference- or pagenumbers from the labels
with common methods any more as done e.g. by the ifthen-package
when it comes to comparing e.g. page-number-values of references/
labels.
In order to work around this restriction, this package provides
the macros \extractrefnum and \extractpagerefnum. Usage of these
macros is described in the "Usage"-section.

4. Change-History
=================
2006/05/01 v0.01 - Initial release
2006/05/02 v0.02 - Package: Support for extracting plain numerical values
------- from labels for numerical comparing / Added
macros \extractrefnum and \extractpagerefnum.
Documentation: Fixed some typo and added some
------------- \extract(page)refnum-examples.

5. Usage
========

Intro
-----

People often wish to customize the way in which counters appear when
referencing takes place. E.g., when referencing a section-counter,
\ref{sec-bla} should deliver something like "section~23", but when
referencing figures, \ref{fig} should deliver something like
"Fig.~(7)".
When looking at these examples, you can find that actually the
reference-text is made of three parts:
1. Some leading phrase, e.g. "Fig.~("
2. The reference-number as "spit out" by \the<counter>
3. Some trailing-phrase, e.g. ")"

package-loading
---------------
in the preamble via \usepackage{custref}

preamble-macro \makerefcustomizable
-----------------------------------

This package provides a preamble-macro
\makerefcustomizable{<counter>}
{<standard-leading-phrase>}
{<standard-trailing-phrase>}
by means of which you can specify the appearance for single counters
when they get referred by means of the \ref-macro.
That means:
You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

, you will get:

A reference to section~(5) of this book

and in case of using hyperref, the hyperlinked phrase is
"section~(5) of this book"

macro \customizeref
-------------------

There is another macro \customizeref for usage within the document.
\customizeref takes 3 arguments:
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}

When applying \customizeref to a label instead of \ref, the leading- and
trailing-phrase of the reference will be formed from \customizeref's
second and third argument _instead_ of what was provided to
\makerefcustomizeable as second and third argument.

You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizeable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

A reference to \customizeref{thissection}{A}{B}

, you will get:

A reference to section~(5) of this book

A reference to A5B

and in case of using hyperref, the first hyperlinked phrase
is "section~(5) of this book", the second is "A5B".

\nolinkref, \nolinkpageref, \nolinkcustomizeref
-----------------------------------------------
A weird but nonetheless existing problem/case is:
You might wish to take reference to yet another label within
\customizeref's second argument (<this time's-leading-phrase>)
or tird argument (<this time's-trailing-phrase>),
e.g. in order to create a hyperlink to only the fifth section of
your book from a phrase like
"chapter 7, section~(5), page 11 of this book".
Simply nesting \ref, \pageref or \customizeref won't work as this
would mean to create hyperlinks in hyperlinks which is not
supported by any driver/viewer yet. Therefore the macros
\nolinkref, \nolinkpageref, \nolinkcustomizeref are provided.
You can use them within the arguments of \customizeref.

\extractrefnum and \extractpagerefnum
-------------------------------------
Sometimes you might wish to extract the plain page- or reference-
number which is associated to a label. Just the numerical
value, no hyperlink or the like. The macros
\extractrefnum and \extractpagerefnum are intended for
facilitating this task.

[In the intro was said that a reference is made of 3 parts:
1. Some leading phrase (e.g. "Fig.~(")
2. The reference-number as "spit out" by \the<counter>
3. Some trailing-phrase (e.g. ")")
So the phrase "just the numerical value" means the second part
"The reference-number as spit out by \the<counter>." Thus
if \the<counter> was not defined to "spit out" a plain
arabic number, the "numerical value" won't be a plain number
either and you cannot use it sucessfully for e.g.
\ifnum-comparison!]

\extractrefnum[<defining-command>]{<macro>}{<label>}
\extractpagerefnum[<defining-command>]{<macro>}{<label>}

The macro \extractrefnum takes one optional and two mandatory
arguments: The first mandatory argument is the name of a newly
to be defined <macro>. The second mandatory argument is the name
of an existing <label>.
The <macro> will be defined to expand to the specified <label>'s
"reference-number as spit out by \the<counter>."
\extractpagerefnum works in the same way but delivers the
page-number-value instead.
Usually defining the <macro> will take place in terms of
\newcommand* . Within the optional argument you can specify
otherwise (e.g., [\def], [\global\def], [\providecommand],
[\DeclareRobustCommand],...) Useful when applying
\extract(page)refnum in a loop where always the same temporary
<macro> is to be (re)defined and thus \newcommand* cannot be
applied as that would lead to an unwanted 'already-defined-error'.

If numerical comparison to references , e.g. , via the
ifthen-package fails, you can try to work around this by first
putting the reference-numbers via \extract(page)refnum into
temporary macros and afterwards performing numerical comparison
to them. If you don't want to have temporary macros defined
permanently, you can write something like e.g.,

{% <-open group
\extractrefnum{\tempa}{<labelA>}%
\extractrefnum{\tempb}{<labelB>}
\expandafter}% closing the group and thus destroying the
% temporary macros will due to \expandafter happen
% right after evaluating the expression, before
% acting on one of the branches.
\ifnum\tempa<\tempb\relax
bla bla
\else
blu blu
\fi

IN CASE THAT LABEL IS UNDEFINED, A WARNING-MESSAGE OCCURS AND
<macro> WILL BE DEFINED TO EXPAND TO "0". During the very first
LaTeX-run no label is defined as labels get defined when reading
the aux-file which is not available yet during that run.

Another issue is:
-----------------
If you did not apply the macro \makerefcustomizeable to a
counter in the preamble, but take reference to it via
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}
, the effect will be the same as if you had just written
\ref{<label>} into your source-code instead.

This is because \customizeref heavily uses and relies on
the p@-macros associated to the counters being (re)defined by
\makerefcustomizable in a special way.

6. hyperlinks across long lines
===============================
You can create very long link-phrases by means of this package.
If you do so, make sure that your viewer/driver supports hyper-
links with linebreaks. pdf(e)(La)TeX does. Most DVI-viewers do
not.

7. Usage-example
================

You can copy-paste the following example to some separate-file,
run it through (pdf)LaTeX and see how the package works:

\documentclass{article}

\usepackage{hyperref} % Actually hyperref is not a requirement
% but we want to see the hyperlinks.
\usepackage{custref}

\makerefcustomizeable{subsection}
{std-lead-phrase-for-sub-section~}
{~std-trail-phrase-for-sub-section}
\makerefcustomizeable{figure}
{std-lead-phrase-for-figure~}
{~std-trail-phrase-for-figure}

\begin{document}

\setcounter{page}{20}%
\parskip=\medskipamount\relax
\parindent=0pt\relax

\section{first section}
\label{firstsection}
This is first section.

\begin{figure}
This is a figure in first section.
\caption{figure's caption}
\label{fig}
\end{figure}

\subsection{first sub-section}
\label{firstsubsection}
This is first sub-section.

\newpage
\section{referencing}

subsection and figure are made ``customizeable''.
section is not.

This is reference to first sub-section:
\ref{firstsubsection}

This is customize-reference to first sub-section:
\customizeref{firstsubsection}
{customize~}
{~customize}

This is reference to first section:
\ref{firstsection}

This is (effectless) customize-reference to first section:
\customizeref{firstsection}
{customize~}
{~customize}

This is reference to figure:
\ref{fig}

This is customize-reference to figure:
\customizeref{fig}
{customize~}
{~customize}

This is customize-reference to figure with other references
in the arguments:
\customizeref{fig}%
{see page~\nolinkpageref{fig} for figure~}%
{ of the \nolinkcustomizeref{firstsection}{}{}$^{st}$ section}%


Plain reference-number of the label \emph{fig} is now in
\texttt{%
\string\tempa~=
\extractrefnum{\tempa}{fig}%
\meaning\tempa
}%

% Now \tempa is defined.
% We now have to use "\def" or something like
% "\let\tempa\relax\newcommand*" in order to prevent
% "already-defined-errors":

Plain reference-number of the label \emph{firstsubsection} is now in
\texttt{%
\string\tempa~=
\extractrefnum[\def]{\tempa}{firstsubsection}%
\meaning\tempa
}%

Plain reference-number of the label \emph{firstsection} is now in
\texttt{%
\string\tempa~=
\extractrefnum[\let\tempa\relax\newcommand]{\tempa}{firstsection}%
\meaning\tempa
}%

Plain page-number of the label \emph{fig} is now in protected
\def\spacereplace#1 #2 #3\nil{#1 #2\char`\ #3}%
\texttt{%
\extractpagerefnum[\DeclareRobustCommand]{\tempa}{fig}%
\string\tempa~=
\expandafter\spacereplace\meaning\tempa;\nil
\spacereplace{} \string\tempa{} ~=~\nil
\expandafter\meaning\csname tempa \endcsname
}%

Plain page-number of the label \emph{firstsubsection} is now in
\texttt{%
\string\tempa~=
\extractpagerefnum[\def]{\tempa}{firstsubsection}%
\meaning\tempa
}%

Plain page-number of the label \emph{firstsection} is now in
\texttt{%
\string\tempa~=
\extractpagerefnum[\def]{\tempa}{firstsection}%
\meaning\tempa
}%

\end{document}

%%
%% End of file `custref.sty'.
==========================<end of file `custref.sty'>==========================

[Ulrich Diez]

After learning about grouping and kerning yet another version
where unnecessary grouping and \reset...-macro-stuff is
removed.

Ulrich
=========================<start of file `custref.sty'>=========================
%
% Manual/macro-description can be found after \endinput so that it
% won't be read when loading the package. Also you don't need
% these '%'-characters all the time...
%
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{custref}
[2006/05/03 v0.03 customize the appearance of ref-erenced counters]
\@ifdefinable\***@extractnum{%
\newif\***@extractnum
\global\@extractnumfalse
}%
\@ifdefinable\extractnum{%
\long\gdef
\extractnum\setrefphrases\refleadphrase#1\reftrailphrase{#1}%
}%
\newcommand*\nolinkref[1]{%
{%
\@ifundefined{@refstar}%
{{\ref{#1}}}%
{{\ref*{#1}}}%
}%
}%
\newcommand*\nolinkpageref[1]{%
{%
\@ifundefined{@pagerefstar}%
{{\pageref{#1}}}%
{{\pageref*{#1}}}%
}%
}%
\@ifdefinable\@innerextractpagerefnum{%
\def\@innerextractpagerefnum#1#2#3#4\@nil{%
\@expandtwoargs\@tempa{\noexpand#1}{#3}%
}%
}%
\newcommand*\extractpagerefnum[3][\newcommand*]{%
\begingroup
\expandafter\ifx\csname r@#3\endcsname\relax
\protect\***@refundefinedtrue
\@***@warning{Reference `#3' on page \thepage\space
undefined}%
\endgroup
#1#2{0}%
\else
\def\@tempa{%
\def\@tempa####1{%
\endgroup#1####1%
}%
\@innerextractpagerefnum{#2}%
}%
\@extractnumtrue
\expandafter\expandafter
\expandafter\@tempa
\csname r@#3\endcsname\empty\empty\empty\empty\@nil
\fi
}%
\@ifdefinable\@innerextractrefnum{%
\def\@innerextractrefnum#1#2#3#4\@nil{%
\@expandtwoargs\@tempa{\noexpand#1}{#2}%
}%
}%
\newcommand*\extractrefnum[3][\newcommand*]{%
\begingroup
\expandafter\ifx\csname r@#3\endcsname\relax
\protect\***@refundefinedtrue
\@***@warning{Reference `#3' on page \thepage\space
undefined}%
\endgroup
#1#2{0}%
\else
\def\@tempa{%
\def\@tempa####1{%
\endgroup#1####1%
}%
\@innerextractrefnum{#2}%
}%
\@extractnumtrue
\expandafter\expandafter
\expandafter\@tempa
\csname r@#3\endcsname\empty\empty\empty\empty\@nil
\fi
}%
\newcommand*\nolinkcustomizeref[3]{%
{%
\@ifundefined{@pagerefstar}%
{{\customizeref{#1}{#2}{#3}}}%
{{\customizeref*{#1}{#2}{#3}}}%
}%
}%
\newcommand*\refleadphrase{}%
\newcommand*\reftrailphrase{}%
\newcommand*\setrefphrases{}%
\newcommand*\makerefcustomizeable[3]{%
\AtBeginDocument{%
\expandafter\renewcommand\expandafter*\csname p@#1\endcsname{%
\csname innerp@#1\expandafter\endcsname
}%
\expandafter\newcommand\expandafter*\csname innerp@#1\endcsname[1]{%
\expandafter\protect\csname setstandardphrases@#1\endcsname
\protect\setrefphrases
\protect\refleadphrase##1\protect\reftrailphrase
}%
\expandafter\newcommand
\expandafter*%
\csname setstandardphrases@#1\endcsname{%
\***@extractnum
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
{\extractnum}%
{%
\toks@{#2}\edef\refleadphrase{\the\toks@}%
\toks@{#3}\edef\reftrailphrase{\the\toks@}%
}%
}%
}%
}%
\@onlypreamble\makerefcustomizeable
\newcommand*\customizerefatnostar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{#2}\edef\refleadphrase{\the\toks@}%
\toks@{#3}\edef\reftrailphrase{\the\toks@}%
}%
\ref{#1}%
}%
}%
\newcommand*\customizerefatstar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{#2}\edef\refleadphrase{\the\toks@}%
\toks@{#3}\edef\reftrailphrase{\the\toks@}%
}%
\ref*{#1}%
}%
}%
\newcommand*\customizeref{\@ifstar\customizerefatstar\customizerefatnostar}%
\endinput
%%
%%
!!!! Here's the promised manual'n stuff !!!!

1. Legal stuff
==============
What is it?: A .sty-file for LaTeX2e, loadable via \usepackage
in the preamble.
Copyright: custref.sty [2006/05/03 v0.03] (C) Ulrich Diez
Author: Ulrich Diez (***@alumni.uni-tuebingen.de)
Licence: LPPL
Submitted to CTAN: No. If somebody wants the package on CTAN,
please contact the author/current maintainer
via e-mail.
Maintenance-status: At may 03, 2006 this sty-file was maintained by
Ulrich Diez.
If somebody wants to overtake maintenance of
the file custref.sty, please contact the author/
current maintainer via e-mail.
Warranties: None. Usage is atyour own risk. If something breaks,
you may keep the pieces.

This file came into being due to a "feature-request" of Ted Pavlic
at comp.text.tex (usenet). For more details google the initial-message's
ID: <***@j33g2000cwa.googlegroups.com> .

2. Changes to LaTeX-internals
=============================
Each <counter> defined by LaTeX2e's \newcounter-macro provides
a macro \p@<counter> which is intended for providing some
referencing-prefix. Usually it is empty. This package provides
means for redefining these \p@-macros and thus might break when
being used together with other packages which do the same.

3. Compatibility to other packages
==================================
I assume that this package will break some features of e.g. the
ifthen-package. The reason is: You cannot extract plain
"hyperlinkless" reference- or pagenumbers from the labels
with common methods any more as done e.g. by the ifthen-package
when it comes to comparing e.g. page-number-values of references/
labels.
In order to work around this restriction, this package provides
the macros \extractrefnum and \extractpagerefnum. Usage of these
macros is described in the "Usage"-section.

4. Change-History
=================
2006/05/01 v0.01 - Initial release
2006/05/02 v0.02 - Package: Support for extracting plain numerical values
------- from labels for numerical comparing / Added
macros \extractrefnum and \extractpagerefnum.
Documentation: Fixed some typo and added some
------------- \extract(page)refnum-examples.
2006/05/03 v0.03 - Package: Removed and changed some unnecessary grouping
------- in order to better preserve implicite kerning.
Also removed unnecessary \reset...-macros.

5. Usage
========

Intro
-----

People often wish to customize the way in which counters appear when
referencing takes place. E.g., when referencing a section-counter,
\ref{sec-bla} should deliver something like "section~23", but when
referencing figures, \ref{fig} should deliver something like
"Fig.~(7)".
When looking at these examples, you can find that actually the
reference-text is made of three parts:
1. Some leading phrase, e.g. "Fig.~("
2. The reference-number as "spit out" by \the<counter>
3. Some trailing-phrase, e.g. ")"

package-loading
---------------
in the preamble via \usepackage{custref}

preamble-macro \makerefcustomizable
-----------------------------------

This package provides a preamble-macro
\makerefcustomizable{<counter>}
{<standard-leading-phrase>}
{<standard-trailing-phrase>}
by means of which you can specify the appearance for single counters
when they get referred by means of the \ref-macro.
That means:
You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

, you will get:

A reference to section~(5) of this book

and in case of using hyperref, the hyperlinked phrase is
"section~(5) of this book"

macro \customizeref
-------------------

There is another macro \customizeref for usage within the document.
\customizeref takes 3 arguments:
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}

When applying \customizeref to a label instead of \ref, the leading- and
trailing-phrase of the reference will be formed from \customizeref's
second and third argument _instead_ of what was provided to
\makerefcustomizeable as second and third argument.

You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizeable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

A reference to \customizeref{thissection}{A}{B}

, you will get:

A reference to section~(5) of this book

A reference to A5B

and in case of using hyperref, the first hyperlinked phrase
is "section~(5) of this book", the second is "A5B".

\nolinkref, \nolinkpageref, \nolinkcustomizeref
-----------------------------------------------
A weird but nonetheless existing problem/case is:
You might wish to take reference to yet another label within
\customizeref's second argument (<this time's-leading-phrase>)
or tird argument (<this time's-trailing-phrase>),
e.g. in order to create a hyperlink to only the fifth section of
your book from a phrase like
"chapter 7, section~(5), page 11 of this book".
Simply nesting \ref, \pageref or \customizeref won't work as this
would mean to create hyperlinks in hyperlinks which is not
supported by any driver/viewer yet. Therefore the macros
\nolinkref, \nolinkpageref, \nolinkcustomizeref are provided.
You can use them within the arguments of \customizeref.

\extractrefnum and \extractpagerefnum
-------------------------------------
Sometimes you might wish to extract the plain page- or reference-
number which is associated to a label. Just the numerical
value, no hyperlink or the like. The macros
\extractrefnum and \extractpagerefnum are intended for
facilitating this task.

[In the intro was said that a reference is made of 3 parts:
1. Some leading phrase (e.g. "Fig.~(")
2. The reference-number as "spit out" by \the<counter>
3. Some trailing-phrase (e.g. ")")
So the phrase "just the numerical value" means the second part
"The reference-number as spit out by \the<counter>." Thus
if \the<counter> was not defined to "spit out" a plain
arabic number, the "numerical value" won't be a plain number
either and you cannot use it sucessfully for e.g.
\ifnum-comparison!]

\extractrefnum[<defining-command>]{<macro>}{<label>}
\extractpagerefnum[<defining-command>]{<macro>}{<label>}

The macro \extractrefnum takes one optional and two mandatory
arguments: The first mandatory argument is the name of a newly
to be defined <macro>. The second mandatory argument is the name
of an existing <label>.
The <macro> will be defined to expand to the specified <label>'s
"reference-number as spit out by \the<counter>."
\extractpagerefnum works in the same way but delivers the
page-number-value instead.
Usually defining the <macro> will take place in terms of
\newcommand* . Within the optional argument you can specify
otherwise (e.g., [\def], [\global\def], [\providecommand],
[\DeclareRobustCommand],...) Useful when applying
\extract(page)refnum in a loop where always the same temporary
<macro> is to be (re)defined and thus \newcommand* cannot be
applied as that would lead to an unwanted 'already-defined-error'.

If numerical comparison to references , e.g. , via the
ifthen-package fails, you can try to work around this by first
putting the reference-numbers via \extract(page)refnum into
temporary macros and afterwards performing numerical comparison
to them. If you don't want to have temporary macros defined
permanently, you can write something like e.g.,

{% <-open group
\extractrefnum{\tempa}{<labelA>}%
\extractrefnum{\tempb}{<labelB>}
\expandafter}% closing the group and thus destroying the
% temporary macros will due to \expandafter happen
% right after evaluating the expression, before
% acting on one of the branches.
\ifnum\tempa<\tempb\relax
bla bla
\else
blu blu
\fi

IN CASE THAT LABEL IS UNDEFINED, A WARNING-MESSAGE OCCURS AND
<macro> WILL BE DEFINED TO EXPAND TO "0". During the very first
LaTeX-run no label is defined as labels get defined when reading
the aux-file which is not available yet during that run.

Another issue is:
-----------------
If you did not apply the macro \makerefcustomizeable to a
counter in the preamble, but take reference to it via
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}
, the effect will be the same as if you had just written
\ref{<label>} into your source-code instead.

This is because \customizeref heavily uses and relies on
the p@-macros associated to the counters being (re)defined by
\makerefcustomizable in a special way.

6. hyperlinks across long lines
===============================
You can create very long link-phrases by means of this package.
If you do so, make sure that your viewer/driver supports hyper-
links with linebreaks. pdf(e)(La)TeX does. Most DVI-viewers do
not.

7. Usage-example
================

You can copy-paste the following example to some separate-file,
run it through (pdf)LaTeX and see how the package works:

\documentclass{article}

\usepackage{hyperref} % Actually hyperref is not a requirement
% but we want to see the hyperlinks.
\usepackage{custref}

\makerefcustomizeable{subsection}
{std-lead-phrase-for-sub-section~}
{~std-trail-phrase-for-sub-section}
\makerefcustomizeable{figure}
{std-lead-phrase-for-figure~}
{~std-trail-phrase-for-figure}

\begin{document}

\setcounter{page}{20}%
\parskip=\medskipamount\relax
\parindent=0pt\relax

\section{first section}
\label{firstsection}
This is first section.

\begin{figure}
This is a figure in first section.
\caption{figure's caption}
\label{fig}
\end{figure}

\subsection{first sub-section}
\label{firstsubsection}
This is first sub-section.

\newpage
\section{referencing}

subsection and figure are made ``customizeable''.
section is not.

This is reference to first sub-section:
\ref{firstsubsection}

This is customize-reference to first sub-section:
\customizeref{firstsubsection}
{customize~}
{~customize}

This is reference to first section:
\ref{firstsection}

This is (effectless) customize-reference to first section:
\customizeref{firstsection}
{customize~}
{~customize}

This is reference to figure:
\ref{fig}

This is customize-reference to figure:
\customizeref{fig}
{customize~}
{~customize}

This is customize-reference to figure with other references
in the arguments:
\customizeref{fig}%
{see page~\nolinkpageref{fig} for figure~}%
{ of the \nolinkcustomizeref{firstsection}{}{}$^{st}$ section}%


Plain reference-number of the label \emph{fig} is now in
\texttt{%
\string\tempa~=
\extractrefnum{\tempa}{fig}%
\meaning\tempa
}%

% Now \tempa is defined.
% We now have to use "\def" or something like
% "\let\tempa\relax\newcommand*" in order to prevent
% "already-defined-errors":

Plain reference-number of the label \emph{firstsubsection} is now in
\texttt{%
\string\tempa~=
\extractrefnum[\def]{\tempa}{firstsubsection}%
\meaning\tempa
}%

Plain reference-number of the label \emph{firstsection} is now in
\texttt{%
\string\tempa~=
\extractrefnum[\let\tempa\relax\newcommand]{\tempa}{firstsection}%
\meaning\tempa
}%

Plain page-number of the label \emph{fig} is now in protected
\def\spacereplace#1 #2 #3\nil{#1 #2\char`\ #3}%
\texttt{%
\extractpagerefnum[\DeclareRobustCommand]{\tempa}{fig}%
\string\tempa~=
\expandafter\spacereplace\meaning\tempa;\nil
\spacereplace{} \string\tempa{} ~=~\nil
\expandafter\meaning\csname tempa \endcsname
}%

Plain page-number of the label \emph{firstsubsection} is now in
\texttt{%
\string\tempa~=
\extractpagerefnum[\def]{\tempa}{firstsubsection}%
\meaning\tempa
}%

Plain page-number of the label \emph{firstsection} is now in
\texttt{%
\string\tempa~=
\extractpagerefnum[\def]{\tempa}{firstsection}%
\meaning\tempa
}%

\end{document}
%%
%% End of file `custref.sty'.
==========================<end of file `custref.sty'>==========================

[Ulrich Diez]

The previous "improvement" introduced a bug.
Shame on me. Sorry.

Ulrich

=========================<start of file `custref.sty'>=========================
%
% Manual/macro-description can be found after \endinput so that it
% won't be read when loading the package. Also you don't need
% these '%'-characters all the time...
%
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{custref}
[2006/05/03 v0.04 customize the appearance of ref-erenced counters]
\@ifdefinable\***@extractnum{%
\newif\***@extractnum
\global\@extractnumfalse
}%
\@ifdefinable\extractnum{%
\long\gdef
\extractnum\setrefphrases\refleadphrase#1\reftrailphrase{#1}%
}%
\newcommand*\nolinkref[1]{%
{%
\@ifundefined{@refstar}%
{{\resetrefphrases\ref{#1}}}%
{{\resetrefphrases\ref*{#1}}}%
}%
}%
\newcommand*\nolinkpageref[1]{%
{%
\@ifundefined{@pagerefstar}%
{{\resetrefphrases\pageref{#1}}}%
{{\resetrefphrases\pageref*{#1}}}%
}%
}%
\@ifdefinable\@innerextractpagerefnum{%
\def\@innerextractpagerefnum#1#2#3#4\@nil{%
\@expandtwoargs\@tempa{\noexpand#1}{#3}%
}%
}%
\newcommand*\extractpagerefnum[3][\newcommand*]{%
\begingroup
\expandafter\ifx\csname r@#3\endcsname\relax
\protect\***@refundefinedtrue
\@***@warning{Reference `#3' on page \thepage\space
undefined}%
\endgroup
#1#2{0}%
\else
\def\@tempa{%
\def\@tempa####1{%
\endgroup#1####1%
}%
\@innerextractpagerefnum{#2}%
}%
\@extractnumtrue
\expandafter\expandafter
\expandafter\@tempa
\csname r@#3\endcsname\empty\empty\empty\empty\@nil
\fi
}%
\@ifdefinable\@innerextractrefnum{%
\def\@innerextractrefnum#1#2#3#4\@nil{%
\@expandtwoargs\@tempa{\noexpand#1}{#2}%
}%
}%
\newcommand*\extractrefnum[3][\newcommand*]{%
\begingroup
\expandafter\ifx\csname r@#3\endcsname\relax
\protect\***@refundefinedtrue
\@***@warning{Reference `#3' on page \thepage\space
undefined}%
\endgroup
#1#2{0}%
\else
\def\@tempa{%
\def\@tempa####1{%
\endgroup#1####1%
}%
\@innerextractrefnum{#2}%
}%
\@extractnumtrue
\expandafter\expandafter
\expandafter\@tempa
\csname r@#3\endcsname\empty\empty\empty\empty\@nil
\fi
}%
\newcommand*\nolinkcustomizeref[3]{%
{%
\@ifundefined{@pagerefstar}%
{{\resetrefphrases\customizeref{#1}{#2}{#3}}}%
{{\resetrefphrases\customizeref*{#1}{#2}{#3}}}%
}%
}%
\newcommand*\refleadphrase{}%
\newcommand*\reftrailphrase{}%
\newcommand*\setrefphrases{}%
\newcommand*\resetrefphrases{%
\def\setrefphrases{}%
}%
\newcommand*\makerefcustomizeable[3]{%
\AtBeginDocument{%
\expandafter\renewcommand\expandafter*\csname p@#1\endcsname{%
\csname innerp@#1\expandafter\endcsname
}%
\expandafter\newcommand\expandafter*\csname innerp@#1\endcsname[1]{%
\expandafter\protect\csname setstandardphrases@#1\endcsname
\protect\setrefphrases
\protect\refleadphrase##1\protect\reftrailphrase
}%
\expandafter\newcommand
\expandafter*%
\csname setstandardphrases@#1\endcsname{%
\***@extractnum
\expandafter\@firstoftwo
\else
\expandafter\@secondoftwo
\fi
{\extractnum}%
{%
\toks@{#2}\edef\refleadphrase{\the\toks@}%
\toks@{#3}\edef\reftrailphrase{\the\toks@}%
}%
}%
}%
}%
\@onlypreamble\makerefcustomizeable
\newcommand*\customizerefatnostar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{#2}\edef\refleadphrase{\the\toks@}%
\toks@{#3}\edef\reftrailphrase{\the\toks@}%
}%
\ref{#1}%
}%
}%
\newcommand*\customizerefatstar[3]{%
{%
\renewcommand*\setrefphrases{%
\toks@{#2}\edef\refleadphrase{\the\toks@}%
\toks@{#3}\edef\reftrailphrase{\the\toks@}%
}%
\ref*{#1}%
}%
}%
\newcommand*\customizeref{\@ifstar\customizerefatstar\customizerefatnostar}%
\endinput
%%
%%
!!!! Here's the promised manual'n stuff !!!!

1. Legal stuff
==============
What is it?: A .sty-file for LaTeX2e, loadable via \usepackage
in the preamble.
Copyright: custref.sty [2006/05/03 v0.04] (C) Ulrich Diez
Author: Ulrich Diez (***@alumni.uni-tuebingen.de)
Licence: LPPL
Submitted to CTAN: No. If somebody wants the package on CTAN,
please contact the author/current maintainer
via e-mail.
Maintenance-status: At may 03, 2006 this sty-file was maintained by
Ulrich Diez.
If somebody wants to overtake maintenance of
the file custref.sty, please contact the author/
current maintainer via e-mail.
Warranties: None. Usage is atyour own risk. If something breaks,
you may keep the pieces.

This file came into being due to a "feature-request" of Ted Pavlic
at comp.text.tex (usenet). For more details google the initial-message's
ID: <***@j33g2000cwa.googlegroups.com> .

2. Changes to LaTeX-internals
=============================
Each <counter> defined by LaTeX2e's \newcounter-macro provides
a macro \p@<counter> which is intended for providing some
referencing-prefix. Usually it is empty. This package provides
means for redefining these \p@-macros and thus might break when
being used together with other packages which do the same.

3. Compatibility to other packages
==================================
I assume that this package will break some features of e.g. the
ifthen-package. The reason is: You cannot extract plain
"hyperlinkless" reference- or pagenumbers from the labels
with common methods any more as done e.g. by the ifthen-package
when it comes to comparing e.g. page-number-values of references/
labels.
In order to work around this restriction, this package provides
the macros \extractrefnum and \extractpagerefnum. Usage of these
macros is described in the "Usage"-section.

4. Change-History
=================
2006/05/01 v0.01 - Initial release
2006/05/02 v0.02 - Package: Support for extracting plain numerical values
------- from labels for numerical comparing / Added
macros \extractrefnum and \extractpagerefnum.
Documentation: Fixed some typo and added some
------------- \extract(page)refnum-examples.
2006/05/03 v0.03 - Package: Removed and changed some unnecessary grouping
------- in order to better preserve implicite kerning.
Also removed unnecessary \reset...-macros.
2006/05/03 v0.04 - Package: Restored erroneously removed \reset...-macros.
-------

5. Usage
========

Intro
-----

People often wish to customize the way in which counters appear when
referencing takes place. E.g., when referencing a section-counter,
\ref{sec-bla} should deliver something like "section~23", but when
referencing figures, \ref{fig} should deliver something like
"Fig.~(7)".
When looking at these examples, you can find that actually the
reference-text is made of three parts:
1. Some leading phrase, e.g. "Fig.~("
2. The reference-number as "spit out" by \the<counter>
3. Some trailing-phrase, e.g. ")"

package-loading
---------------
in the preamble via \usepackage{custref}

preamble-macro \makerefcustomizable
-----------------------------------

This package provides a preamble-macro
\makerefcustomizable{<counter>}
{<standard-leading-phrase>}
{<standard-trailing-phrase>}
by means of which you can specify the appearance for single counters
when they get referred by means of the \ref-macro.
That means:
You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

, you will get:

A reference to section~(5) of this book

and in case of using hyperref, the hyperlinked phrase is
"section~(5) of this book"

macro \customizeref
-------------------

There is another macro \customizeref for usage within the document.
\customizeref takes 3 arguments:
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}

When applying \customizeref to a label instead of \ref, the leading- and
trailing-phrase of the reference will be formed from \customizeref's
second and third argument _instead_ of what was provided to
\makerefcustomizeable as second and third argument.

You can -after package-loading- write in the preamble e.g.,
...
\makerefcustomizeable{section}
{section~(}
{) of this book}
...

When writing in the document

...
% fifth-section
\section{some section}\label{thissection}
...
A reference to \ref{thissection}

A reference to \customizeref{thissection}{A}{B}

, you will get:

A reference to section~(5) of this book

A reference to A5B

and in case of using hyperref, the first hyperlinked phrase
is "section~(5) of this book", the second is "A5B".

\nolinkref, \nolinkpageref, \nolinkcustomizeref
-----------------------------------------------
A weird but nonetheless existing problem/case is:
You might wish to take reference to yet another label within
\customizeref's second argument (<this time's-leading-phrase>)
or tird argument (<this time's-trailing-phrase>),
e.g. in order to create a hyperlink to only the fifth section of
your book from a phrase like
"chapter 7, section~(5), page 11 of this book".
Simply nesting \ref, \pageref or \customizeref won't work as this
would mean to create hyperlinks in hyperlinks which is not
supported by any driver/viewer yet. Therefore the macros
\nolinkref, \nolinkpageref, \nolinkcustomizeref are provided.
You can use them within the arguments of \customizeref.

\extractrefnum and \extractpagerefnum
-------------------------------------
Sometimes you might wish to extract the plain page- or reference-
number which is associated to a label. Just the numerical
value, no hyperlink or the like. The macros
\extractrefnum and \extractpagerefnum are intended for
facilitating this task.

[In the intro was said that a reference is made of 3 parts:
1. Some leading phrase (e.g. "Fig.~(")
2. The reference-number as "spit out" by \the<counter>
3. Some trailing-phrase (e.g. ")")
So the phrase "just the numerical value" means the second part
"The reference-number as spit out by \the<counter>." Thus
if \the<counter> was not defined to "spit out" a plain
arabic number, the "numerical value" won't be a plain number
either and you cannot use it sucessfully for e.g.
\ifnum-comparison!]

\extractrefnum[<defining-command>]{<macro>}{<label>}
\extractpagerefnum[<defining-command>]{<macro>}{<label>}

The macro \extractrefnum takes one optional and two mandatory
arguments: The first mandatory argument is the name of a newly
to be defined <macro>. The second mandatory argument is the name
of an existing <label>.
The <macro> will be defined to expand to the specified <label>'s
"reference-number as spit out by \the<counter>."
\extractpagerefnum works in the same way but delivers the
page-number-value instead.
Usually defining the <macro> will take place in terms of
\newcommand* . Within the optional argument you can specify
otherwise (e.g., [\def], [\global\def], [\providecommand],
[\DeclareRobustCommand],...) Useful when applying
\extract(page)refnum in a loop where always the same temporary
<macro> is to be (re)defined and thus \newcommand* cannot be
applied as that would lead to an unwanted 'already-defined-error'.

If numerical comparison to references , e.g. , via the
ifthen-package fails, you can try to work around this by first
putting the reference-numbers via \extract(page)refnum into
temporary macros and afterwards performing numerical comparison
to them. If you don't want to have temporary macros defined
permanently, you can write something like e.g.,

{% <-open group
\extractrefnum{\tempa}{<labelA>}%
\extractrefnum{\tempb}{<labelB>}
\expandafter}% closing the group and thus destroying the
% temporary macros will due to \expandafter happen
% right after evaluating the expression, before
% acting on one of the branches.
\ifnum\tempa<\tempb\relax
bla bla
\else
blu blu
\fi

IN CASE THAT LABEL IS UNDEFINED, A WARNING-MESSAGE OCCURS AND
<macro> WILL BE DEFINED TO EXPAND TO "0". During the very first
LaTeX-run no label is defined as labels get defined when reading
the aux-file which is not available yet during that run.

Another issue is:
-----------------
If you did not apply the macro \makerefcustomizeable to a
counter in the preamble, but take reference to it via
\customizeref{<label>}
{<this time's-leading-phrase>}
{<this time's-trailing-phrase>}
, the effect will be the same as if you had just written
\ref{<label>} into your source-code instead.

This is because \customizeref heavily uses and relies on
the p@-macros associated to the counters being (re)defined by
\makerefcustomizable in a special way.

6. hyperlinks across long lines
===============================
You can create very long link-phrases by means of this package.
If you do so, make sure that your viewer/driver supports hyper-
links with linebreaks. pdf(e)(La)TeX does. Most DVI-viewers do
not.

7. Usage-example
================

You can copy-paste the following example to some separate-file,
run it through (pdf)LaTeX and see how the package works:

\documentclass{article}

\usepackage{hyperref} % Actually hyperref is not a requirement
% but we want to see the hyperlinks.
\usepackage{custref}

\makerefcustomizeable{subsection}
{std-lead-phrase-for-sub-section~}
{~std-trail-phrase-for-sub-section}
\makerefcustomizeable{figure}
{std-lead-phrase-for-figure~}
{~std-trail-phrase-for-figure}

\begin{document}

\setcounter{page}{20}%
\parskip=\medskipamount\relax
\parindent=0pt\relax

\section{first section}
\label{firstsection}
This is first section.

\begin{figure}
This is a figure in first section.
\caption{figure's caption}
\label{fig}
\end{figure}

\subsection{first sub-section}
\label{firstsubsection}
This is first sub-section.

\newpage
\section{referencing}

subsection and figure are made ``customizeable''.
section is not.

This is reference to first sub-section:
\ref{firstsubsection}

This is customize-reference to first sub-section:
\customizeref{firstsubsection}
{customize~}
{~customize}

This is reference to first section:
\ref{firstsection}

This is (effectless) customize-reference to first section:
\customizeref{firstsection}
{customize~}
{~customize}

This is reference to figure:
\ref{fig}

This is customize-reference to figure:
\customizeref{fig}
{customize~}
{~customize}

This is customize-reference to figure with other references
in the arguments:
\customizeref{fig}%
{see page~\nolinkpageref{fig} for figure~}%
{ of the \nolinkcustomizeref{firstsection}{}{}$^{st}$ section}%


Plain reference-number of the label \emph{fig} is now in
\texttt{%
\string\tempa~=
\extractrefnum{\tempa}{fig}%
\meaning\tempa
}%

% Now \tempa is defined.
% We now have to use "\def" or something like
% "\let\tempa\relax\newcommand*" in order to prevent
% "already-defined-errors":

Plain reference-number of the label \emph{firstsubsection} is now in
\texttt{%
\string\tempa~=
\extractrefnum[\def]{\tempa}{firstsubsection}%
\meaning\tempa
}%

Plain reference-number of the label \emph{firstsection} is now in
\texttt{%
\string\tempa~=
\extractrefnum[\let\tempa\relax\newcommand]{\tempa}{firstsection}%
\meaning\tempa
}%

Plain page-number of the label \emph{fig} is now in protected
\def\spacereplace#1 #2 #3\nil{#1 #2\char`\ #3}%
\texttt{%
\extractpagerefnum[\DeclareRobustCommand]{\tempa}{fig}%
\string\tempa~=
\expandafter\spacereplace\meaning\tempa;\nil
\spacereplace{} \string\tempa{} ~=~\nil
\expandafter\meaning\csname tempa \endcsname
}%

Plain page-number of the label \emph{firstsubsection} is now in
\texttt{%
\string\tempa~=
\extractpagerefnum[\def]{\tempa}{firstsubsection}%
\meaning\tempa
}%

Plain page-number of the label \emph{firstsection} is now in
\texttt{%
\string\tempa~=
\extractpagerefnum[\def]{\tempa}{firstsection}%
\meaning\tempa
}%

\end{document}
%%
%% End of file `custref.sty'.
==========================<end of file `custref.sty'>==========================

[Will Robertson]

Post by Ted Pavlic
So really I'm looking for a standard way to do my \shortref, \longref,
and \longrefs macros. It seems to me like something like this has to
already exist. It's not that strange of a request.

Yes, see the refstyle package. I'm pretty sure it does exactly what you
want, plus more perhaps. It took me a while to stumble across this
package; it should be better known.

Will

[Ted Pavlic]

That *is* a neat package. I need to investigate how to get hyperref
working with it, but it says it does work with it.

Additionally, I need to figure out how to get parentheses around
equation numbers. I have to imagine there's some way to do it.

It's definitely worth looking at. It really looks like a neat package.
Thanks for pointing it out.

Post by Will Robertson

Post by Ted Pavlic
So really I'm looking for a standard way to do my \shortref, \longref,
and \longrefs macros. It seems to me like something like this has to
already exist. It's not that strange of a request.

Yes, see the refstyle package. I'm pretty sure it does exactly what you
want, plus more perhaps. It took me a while to stumble across this
package; it should be better known.
Will

[Ted Pavlic]

The "refstyle" package says it works with hyperref, and it does, but it
does only by supporting hyperref's extension to \ref.

What I really want is a way for refstyle to link its entire reference
text (e.g. "Eq. (1)") to the proper target. Right now it just links the
\ref part (e.g. "1").

[Danie]

Post by Ted Pavlic
The "refstyle" package says it works with hyperref, and it does, but it
does only by supporting hyperref's extension to \ref.
What I really want is a way for refstyle to link its entire reference
text (e.g. "Eq. (1)") to the proper target. Right now it just links the
\ref part (e.g. "1").

To do what you are asking, one needs to change the internals of the
\label / \ref commands. My design decision for refstyle was not to
change any of the internal Latex commands, especially not messing
around with the stuff that hyperref also redefine afterwards. The
bottom line is that it will be very difficult to change refstyle to ref
the full string and still be compattible with everything else.

Danie Els (dnjels at sun dot ac dot za)

PS: I would appreciate very much contibutions for the languages
refstyle still needs. Thank you very much.

[Ted Pavlic]

Danie --

I see. That's interesting to me.

You see, there is a journal that I'm submitting to (Engineering
Applications of Artificial Intelligence, an Elsavier <sp> journal) that
uses this linking in the electronic versions of all of its articles. Do
you think that they are just using some custom package of their own in
order to do this?

Ulrich Diez posted a style file (earlier in this thread) that makes the
appropriate changes to the reference counters that makes it so that
hyperref links from all of the text. I have a feeling that EAAI has
something similar in-house. (though, as you suggest, these
modifications may not be compatible with *everything* else)

It just seems like something like this should already exist and be
available on CTAN... :(

[Danie]

The next titbit was described by Ulrich Diez, by I repeat it here:

The basic mechanism of the Latex referencing commands works as follows:
The \label{<ref>} write the following line to the JOBNAME.AUX file

no hyperref :
\newlabel{<ref>}{{<clabel>}{<page>}}
with hyperref:
\newlabel{<ref>}{{<clabel>}{<page>}{<descript>}{<anchor>}{}}

<clabel> = eval(\@currentlabel created by \refstepcounter)
<page> = eval(\thepage)
<descript> = chapter or section title
<anchor> = hyperref anchor

When the JOBNAME.AUX file is loaded automatically on the second run the
\newlabel command creates the following macro (with \@namedef)

\r@<ref> -> {<clabel>}{<page>}
or
\r@<ref> -> {<clabel>}{<page>}{<descript>}{<anchor>}{}

When you call the \ref or \pageref it can access the information by
using the internal command \@nameuse{r@<ref>} to obtain the reference
label or the page number after checking for existence etc.

Take a VERY CLOSE look at the internals of the \autoref command inside
hyperref to define a command the links the full string and still play
ball with every one else. It may be that \autoref can help you a lot
here.

Danie Els