The refstyle package∗

Danie Els
Department of Mechanical and Mechatronics Engineering
University of Stellenbosch, South Africa.
e-mail: dnjels@sun.ac.za

2010/11/02

Overview of the refstyle package

When writing complex documents, often a large number of commands for different
type of references are defined, for example:
\newcommand*{\eqref}[1]{eqn~(\ref{#1})}
\newcommand*{\Eqref}[1]{Equation~(\ref{#1})}
The refstyle package was developed to automate this process. The package provides
a user interface to define sets of reference and label commands for each referable
object such as an equation or a table, etc. When you declare, for example, a set
of reference commands to an equation:
\newref{eq}{hkey lsti}
a series of commands of the format \eq... and \Eq... are produced. The
configuration options are set with a list of key-values. Prefixes, inserts and other
options for all the different perturbations such as capitalized first letters, singular
and plural from, etc. can be defined. The configuration can be changed temporarily
with an optional list of key-values when the commands are used. A direct interface
to the varioref package is also provided. This enables compact reference formats:
\eqref{e1} ... → equation (1) ...
\Eqref[vref]{e1} ... → Equation (1) on page 6 ...
\eqref[s]{e1} and ... → equations (1) and ...
\eqref[name=eq.~]{e1} ... → eq. (1) ...
A range or a list of references can also be referred to in a consistent way.
\eqref{e1,e2,e3} ... → equations (1), (2) and (3) ...
\eqrangeref[vref]{e1}{e3} ... → equations (1) to (3) on page 6 ...
Templates for the different reference types and different languages can be
loaded with a configuring file.
The package is aimed at large projects, enabling a consistent way of producing
references throughout a project. Enough flexibility is provided to make local
changes to a single reference. For large projects such as a series of books or a
multi volume thesis, written as freestanding documents, a facility is provided to
interface to the xr package for external document references.

See also refconfig.pdf for setup and examples.

∗ This file has version number v0.5, last revised 2010/11/02.

1
Contents
1 Loading the refstyle Package 3
1.1 Document preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Package options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Companion packages . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 User Interface 5

3 Command Descriptions 5
3.1 The reference key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 Reference label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3 Reference commands . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.4 Range reference commands . . . . . . . . . . . . . . . . . . . . . . 7
3.5 Page reference command . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Keyval Optional Arguments 9

4.1 Identifier: key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Plural form: s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3 Extended reference: vref . . . . . . . . . . . . . . . . . . . . . . . 9
4.4 External interfaces: xr . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.5 Language parameters: name, names, Name, Names, rngtxt, lsttwotxt,
lsttxt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.6 Reference formatting command: refcmd . . . . . . . . . . . . . . . 11

5 Default configuration files 12

6 Implementation: refstyle.sty 13
6.1 Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2 External packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.3 Utility commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.4 First character case changes . . . . . . . . . . . . . . . . . . . . . . 15
6.5 Reference building commands . . . . . . . . . . . . . . . . . . . . . 15
6.6 Reference formatting commands . . . . . . . . . . . . . . . . . . . 17
6.7 varioref command predefinitions . . . . . . . . . . . . . . . . . . . . 20
6.8 Support for language option inclusions in config file . . . . . . . . . 20
6.9 Configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2
1 Loading the refstyle Package
1.1 Document preamble
The refstyle package is loaded in the preamble of the document:
(a) With a config file with babel language support
\usepackage{varioref}[2001/09/04]% ← To use the vref option
\usepackage{refstyle}

When the package is loaded, it first searchers for a local user defined con-
figuration file refstyle.def. If it is not available it looks for the global
default config file refstyle.cfg provided with this package. These configu-
ration files are loaded before the package options are precess. It can therefore
contain option commands using globally defined language options and can
interface to babel for language changes. The macro
\DeclareLangOpt{hlanguagei}{hdefinitionsi}

is provided to declare the package option hlanguagei and add hdefinitionsi

to the \extrashlanguagei token for babel. It can only be used inside
refstyle.cfg or refstyle.def.
(b) Or with an existing configuration with language support and addition of
your own extensions
\documentclass[norwegian]{article}
\usepackage{babel}
\usepackage{refstyle}
\RSaddto{\RSnorwegian}{%
\def\RSthmtxt{teorem~}%
\def\RSthmstxt{teorem~}%
\def\RSThmtxt{Teorem~}%
\def\RSThmstxt{Teorem~}}
\newref{thm}{
name = \RSthmtxt,
names = \RSthmstxt,
Name = \RSThmtxt,
Names = \RSThmstxt,
rngtxt = \RSrngtxt,
lsttxt = \RSlsttxt,
lsttwotxt = \RSlsttwotxt}

(c) Or without any configuration file, but by declaring your own reference com-
mands in the preamble.
\usepackage[noconfig]{refstyle}
\newref{hreftype 1 i}{hkey lsti}
\newref{hreftype 2 i}{hkey lsti}
..
.

(d) Or with your own configuration file (without babel language support) for a
specific project:
\usepackage[noconfig]{refstyle}
\input{thisproject.ref}

3
1.2 Package options
noconfig Neither of the user supplied refstyle.def config file or refstyle.cfg
the config file supplied with this package are loaded. The user must declare
his or her own definitions and templates. Note that these definitions are not
passed on to babel’s language changing mechanisms.
nokeyprefix Custom labeling commands \htypeilabel are generated by refstyle
for every htypei definition. It defaults to
\htypeilabel{abc} → \label{htype : iabc}

With the nokeyprefix option, the prefix is turned of and the labeling com-
mands defaults to
\htypeilabel{abc} → \label{abc}

This is useful for old documents with existing labeling commands or where
the user prefer not to use the \htypeilabel commands.

1.3 Companion packages

The refstyle packages is intended for large projects. It is therefore important that
it works together with, or has direct interfaces to the following packages:

varioref:1 Produce sophisticated page and page range references.

hyperref:2 To establish hyper links between the references and the labels.
xr, xr-hyper: To establish references to external documents.
showkeys: To show all the labels and references. This is very useful to find labels
in large documents.

1 varioref v1.3c, 2001/09/04 or later, because the starred versions of the commands are used.
2 hyperref v6.72r, 2002/05/27 or later, where a bug for interference with varioref was fixed.

4
 2 User Interface
\newref The refstyle package has one configuring command, \newref, that internally cre-
ates a series of label and reference commands:

\newref{htypei}{hkey lsti}
\htypeikey Reference argument prefix
\htypeilabel Custom label
\htypeiref In text reference
\hTypeiref Start of sentence reference
\htypeirangeref In text range reference
\hTypeirangeref Start of sentence range reference
\htypeipageref Page reference

All the \htypei... commands, excluding \htypeikey and \htypeilabel are robust.
All the options for the referencing commands are set with a key-value list. Table 1
on page 8 gives a full list of all the key-values and defaults.
The refstyle package do not redefine any internal LATEX commands and depends
only on the \label, \ref, \pageref and the varioref commands. The internally
defined commands do not overwrite any existing command with the same name,
and an error results if a command already exists. The exception is commands
declared with a previous \newref call, can be redefined by calling \newref again
with a new set of parameter. If the amsmath package is loaded, and you define
\newref{eq} for references to equations, you need to undefine \eqref before
issuing \newref by
\let\eqref=\relax

3 Command Descriptions
The structure of the label and reference commands is given by the syntax diagrams
that follows. Examples are included for references to equations, defined according
to the template in refstyle.cfg with the \newref{eq}{hkey lsti}. See also
section §4 for explanations of the key-values.

3.1 The reference key

-
- \htypeikey -

The \htypeikey command returns the prefix added to the argument of the label
and the reference commands, for example:

\newref{htypei}{} \htypeikey → htype : i

\newref{htypei}{key=xxx-} \htypeikey → xxx-

The \htypeikey command is not a general command, but was provided only as a
link to the standard LATEX \ref and \pageref commands:

\label{\htypeikey abc} → \label{htype : iabc}

\ref{\htypeikey abc} → \ref{htype : iabc}

5
Note if the the nokeyprefix option is active then the \htypeikey is empty.

Examples: equations with \newref{eq}{hkey lsti}:

\eqkey eq:
in eq.~\ref{\eqkey e1} ... in eq. 1 ...
on page \pageref{\eqkey e1} ... on page 6 ...
\vpageref*{\eqkey e1} ... on this page ...

3.2 Reference label

-
- \htypeilabel{hlbl i} -

The command \htypeilabel prefix the reference string in the \label with the
string htype : i, or its redefinition with the key option.
\htypeilabel{abc} → \label{htype : iabc}

Examples:
Let z = x + iy and α = β + iγ, with i2 = −1, then
ez = ex (cos y + i sin y) (1) \eqlabel{e1}
α α ln z
z =e (2) \eqlabel{e2}

Equations (1) and (2) lead to the following interesting results:

eiπ + 1 = 0 (3) \eqlabel{e3}

i −π/2
i =e (4) \eqlabel{e4}

3.3 Reference commands

 , 
-
- \htypeiref    {  hlbl i } -
 ∗   [hkey lsti] 

 , 
-
- \hTypeiref   {  hlbl i } -
 ∗   [hkey lsti] 

The * optional form of the \htypeiref and \hTypeiref commands eliminates the
name prefix. The [s] optional key-value argument is for the plural form of the
name prefix.

Examples:
in \eqref{e1} ... in equation (1) ...
in \eqref[s]{e1}--\eqref*{e4} ... in equations (1)–(4) ...
in \eqref[name=eq.~]{e2} ... in eq. (2) ...

A list of references can be used:

in \eqref{e1,e2} ... in equations (1) and (2) ...
in \eqref{e1,e2,e3} ... in equations (1), (2) and (3) ...
in \eqref[lsttxt={, and~}]{e1,e2,e3} ... in equations (1), (2), and (3) ...

6
The reference to the page can be included with the vref or vref=far options
that activates the varioref reference.
in \eqref[vref]{e1} ... in equation (1) on the previous page ...
in \eqref[vref=far]{e1} ... in equation (1) on page 6 ...

The \hTypeiref command is identical to the \htypeiref command except that it

uses the Name and Names key-value options.
\Eqref{e1} is ... Equation (1) is ...
\Eqref{e1,e2} are ... Equations (1) and (2) are ...
\Eqref[lsttxt={\ or~}]{e1,e2,e3} Equations (1), (2) or (3)

References to external documents can be added with the xr option. Please read
the documentation of the xr package.

\eqref[xr =A-]{xyz} → equation~\ref{A-eq:xyz}

3.4 Range reference commands

-
- \htypeirangeref    {hlbl i1 }{hlbl i2 } -
 ∗   [hkey lsti] 

-
- \hTypeirangeref    {hlbl i1 }{hlbl i2 } -
 ∗   [hkey lsti] 

The \htypeirangeref and \hTypeirangeref commands return a range of refer-

ences and take two arguments. The * optional form again eliminates the name
prefix.

Examples:
in \eqrangeref{e1}{e4} ... in equations (1) to (4) ...
... and \eqrangeref*{e1}{e4} ... ... and (1) to (4) ...
\Eqrangeref{e1}{e4} are ... Equations (1) to (4) are ...
\Eqrangeref[vref,rngtxt=--]{e1}{e4} Equations (1)–(4) on the preceding page

3.5 Page reference command

-
- \htypeipageref   {hlbl i} -
 [hkey lsti] 

The \htypeipageref commands returns the page number of a reference.

Examples:
it is on page \eqpageref{e1} ... it is on page 6 ...
it is \eqpageref[vref]{e1} ... it is on the previous page ...

7
Table 1: The available options and key-value parameters for the label and reference
commands of the refstyle package.

Commands∗

\hTypeirangeref
\htypeirangeref

\htypeipageref
\htypeilabel

\hTypeiref
\htypeikey

\htypeiref
Parameter Default
∗       
[hkey lsti]       
key ={htype:i},       
s ={true}† ,       
vref ={true}† ,       
xr ={},       
name ={},       
names ‡ ={},       
Name ={},       
Names ‡ ={},       
lsttwotxt ={\space and~},       
lsttxt ={\space and~},       
rngtxt ={\space to~},       
refcmd =\ref{#1},       
 – Available
 – Not available

∗ The commands are obtained by calling the configuring command \newref and

setting the default key-values. The active key-values can be changed temporarily
inside the commands.
† Options defaults to true but is initialized as false. The \htypeiref[s]{hlbli}

command results in the plural: names. The same principle is also valid for the
vref option.
‡ Option depends on the selection of the s=true/false optional key-value for

singular or plural.

8
4 Keyval Optional Arguments
Al the options for the referencing commands are set with a key-value list. Table 1
on the preceding page gives a full list of all the key-values and defaults. The
options can also be changed locally with the [hkey lsti] optional arguments.

4.1 Identifier: key

The key key-value is the prefix to the reference label of the \ref and \pageref
commands. The default is key= htype : i. With the default refstyle.cfg:

\newref{tab}{...}
\tablabel{abc} → \label{tab:abc}
\tabref{abc} → table~\ref{tab:abc}
\newref{tab}{key=xxx-,...}
\tablabel{abc} → \label{xxx-abc}
\tabref{abc} → table~\ref{xxx-abc}

For existing documents containing labels such as \label{tab:xx}, you can use
the nokeyprefix option which defines key ={}. The normal \label command
can then be used and the reference commands defaults to
\label{tab:xx}
\tabref{tab:xx} → table~\ref{tab:xx}

4.2 Plural form: s

The s conditional option (true/false) switches the singular/plural form of the
reference on and off. The default is s =true, but it is initialized to false.
\tabref{abc} → table~\ref{tab:abc}
\tabref[s]{abc} → tables~\ref{tab:abc}

4.3 Extended reference: vref

The vref conditional option (true/far/false) switches the varioref page refer-
encing on and off. The default is vref =true, but it is initialized to false.

\tabref{abc} → table~\ref{tab:abc}
\tabref[vref]{abc} → table~\ref{tab:abc} \vpageref[\unskip]{tab:abc}
\tabref[vref=far]{abc} → table~\ref{tab:abc} \reftextfaraway{tab:abc}

4.4 External interfaces: xr

The xr option is for references to external documents. It inserts a prefix in the
reference label, compatible with the xr package. The default is xr ={}.
External document can be defined in the preamble with the xr or xr-hyper
packages:
\usepackage{xr}
\externaldocument[hxr keyi]{hfilenamei}

9
 If, for example, an external document defined with hxr keyi={A-}, uses an iden-
tical setup (e.g. the same refstyle.cfg), then it can be referenced with
\tabref[xr=A-]{abc} → table~\ref{A-tab:abc}

or otherwise
\tabref[xr=A-,key=]{abc} → table~\ref{A-abc}

4.5 Language parameters: name, names, Name, Names, rngtxt,

lsttwotxt, lsttxt
This key-values contain the text prefixes and insertions. Every house style or user
has his or her own preference for naming the reference types, therefore are there
no defaults provided.
name — Inside sentence reference prefix (singular) default={}
names — Inside sentence reference prefix (plural) default={}
Name — First word reference prefix (singular) default={}
Names — First word reference prefix (plural) default={}
rngtxt — Range of references default={\ to~}
lsttwotxt— List of references (two) default={\ and~}
lsttxt — List of references (more than two) default={\ and~}

Good typographic style manuals recommend the minimum use of capital letters
and punctuation that breaks the flow of a sentence or paragraph. For abbrevia-
tions, Bringhurst[1] recommends the Oxford house style: Use a period only when
the word stops prematurely. The period is omitted if the abbreviation begins with
the first letter and end with the last. As an example for equations, use eq. (1)
or eqn (1). A good guideline is not to abbreviate any reference type names. If
a sentence starts with a reference then the type name must always be written in
full. A typical example for references to a table is:
name ={table~}, names ={tables~},
Name ={Table~}, Names ={Tables~},
rngtxt ={\ to~}, lsttxt ={, and~}, lsttwotxt ={\ and~},
Note the hardspace after the text. It is needed to keep the text and the reference
together on the same line.
The refstyle configuration file can be setup to interface with babel for different
languages or for automatic language changes inside a document. The language
specific key-values can be added to the babel hook \extrashlanguagei. The com-
\DeclareLangOpt mand \DeclareLangOpt3 is provided to supply a hlanguagei option to the package
and to add the option contents to \extrashlanguagei. The default config file con-
tains the following lines for equations:
\newcommand\RSenglish{%
\def\RSeqtxt{equation~}%
\def\RSeqstxt{equations~}%
\def\RSEqtxt{Equation~}%
\def\RSEqstxt{Equations~}%
:
}
\DeclareLangOpt{english}{\RSenglish}
3 Only for use in refstyle.cfg the default config file

10
\RSaddto or manually with the \RSaddto command
\RSaddto{\extrasenglish}{\RSenglish}

The key-value options for language specific options are then set as:
\newref{eq}{%
name = \RSeqtxt,
names = \RSeqstxt,
Name = \RSEqtxt,
Names = \RSEqstxt,
:
}

LATEX/babel provides some language specific names that can be utilized.

\chaptername \appendixname
\figurename \tablename
\partname \pagename

To setup a multilingual document with babel, always make the language op-
tions global so that other language compliant packages can detect it. A typical
setup for an Afrikaans/English document would be:
\documentclass[UKenglish,afrikaans,hoptions i]{hLaTeX class i}
\usepackage[T1]{fontenc}%..hyphenation of words with accents
\usepackage{babel}%........language def’s
\usepackage{varioref}%.....for vref option
\usepackage{refstyle}

4.6 Reference formatting command: refcmd

The refcmd key-value holds the contents of the internal command that formats
the reference. The #1 parameter passed to the command is the full reference label.
For example:
refcmd =(\ref{#1}) → (\ref{hlabeli})

External commands can be employed. For example, to make references to

equations identical to the AMS \eqref command:
refcmd ={\textup{\tagform@{\ref{#1}}}}% It needs amsmath.sty

The refcmd can be used in conjuntion with the \ifRSstar, \ifRSnameon,

\ifRSplural and \ifRScapname internal conditional variables to format the ref-
erence. As an example for a reference to a footnote, where a duplicate footnote
mark is needed, can the refcmd be configured so that the starred form of the
reference command produce a superscripted duplicate mark:
\newcommand{\RSfnmark}[1]{%
\begingroup
\unrestored@protected@xdef\@thefnmark{#1}%
\endgroup
\@footnotemark}
refcmd ={\ifRSstar\RSfnmark{\ref{#1}}\else(\ref{#1})\fi}

11
The second footnote mark, † , in table 1 on page 8, was obtained in this way with
the reference \fnref*{b}. See refstyle.cfg for another example for references
to chapters and appendices.
The nameref package can easily be incorporated if you need elaborate references
which include the section or chapter name:
\Secref[vref, refcmd={\S\ref{#1}, ‘\nameref{#1}’}]{PRefCmds}

gives
Section §3.5, ‘Page reference command’ on page 7

5 Default configuration files

The refstyle package first searches for the refstyle.def configuration file, and
if it not found, then it uses the default configuration file refstyle.cfg that is
supplied with the package.
The default configuration file, refstyle.cfg, makes a number of default refer-
ence declarations and provides language definitions for the language parameters.
See the file refconfig.pdf for the documentation.

Any user is welcome to customize the

local copy of the refstyle.cfg file or
copy the relevant contents to your own
refstyle.def configuration file.

References
[1] Bringhurst, R. (1996), The elements of typographic style, Hartley & Marks
Publishers, Point Roberts, WA, USA and Vancouver, BC, Canada, second
edn.

12
 6 Implementation: refstyle.sty
6.1 Identification
1 h∗pkgi
2 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
3 \ProvidesPackage{refstyle}[\RefstyleFileDate\space
4 \RefstyleFileVersion\space
5 Reference formatting (DNJ Els)]
6 \newcommand*{\RS@pkgname}{refstyle}

6.2 External packages

Load all the external packages.
7 \RequirePackage{keyval}

\RS@setkeys Note if xkeyval is loaded, it redefines keyval’s macros. To fix this bug, we need the
original \setkeys command.
\def\RS@setkeys#1#2{%
8
9 \def\KV@prefix{KV@#1@}%
10 \let\@tempc\relax
11 \KV@do#2,\relax,}

A small bug-fix for showkeys. Will be removed after release of new version.
12 \@ifundefined{vref@space}{\let\vref@space\space}{}

\@safe@activestrue If babel is not loaded, make the following commands inactive.

\@safe@activesfalse 13 \providecommand*{\@safe@activestrue}{}
14 \providecommand*{\@safe@activesfalse}{}

6.3 Utility commands

\RS@namelet The following is a list of commands that take a variable {hnamei} as argument.
\RS@nameuse This enables on-the-fly definitions of user commands.
\RS@namedef
Usage: \RS@namelet{hnamei} → \let\hnamei
\RS@robustnamedef
\RS@nameuse{hnamei} → \hnamei
\RS@namedef{hnamei} → \def\hnamei
\RS@robustnamedef{hnamei} → \def\hnamei{\protect\hname i}\def\hname i

15 \newcommand*{\RS@namelet}[1]{\expandafter\let\csname #1\endcsname}
16 \newcommand*{\RS@nameuse}[1]{\csname #1\endcsname}
17 \newcommand*{\RS@namedef}[1]{\expandafter\def\csname #1\endcsname}
18 \newcommand*{\RS@robustnamedef}[1]{%
19 \expandafter\edef\csname #1\endcsname{%
20 \noexpand\protect\RS@nameuse{#1 }}%
21 \RS@namedef{#1 }}

\RS@ifundefined This is an improved definition4 for the LATEX kernel command \@ifundefined
that do not leave an undefined command defined as \relax after the test.
The usage is: \RS@ifundefined{hnamei}{htruei}{hfalsei} executes the con-
tents of htruei if \hnamei is not defined and hfalsei if defined.
4 Posted by Markus Kohm on c.t.t. 2002/11/11

13
 22 \def\RS@ifundefined#1{%
23 \begingroup\expandafter\expandafter\expandafter\endgroup
24 \expandafter\ifx\csname#1\endcsname\relax
25 \expandafter\@firstoftwo
26 \else
27 \expandafter\@secondoftwo
28 \fi}

\RS@removedef The command removes the definition of a command, including robust definitions.
29 \newcommand*{\RS@removedef}[1]{%
30 \RS@namelet{#1}\@undefined%
31 \RS@ifundefined{#1 }{}{\RS@namelet{#1 }\@undefined}}

\RS@testednamedef These command are identical to \RS@namedef and \RS@robustnamedef, but only
\RS@testedrobustnamedef define the \hnamei command if it is legal. Otherwise an error message is written
to the log file and the program is terminated.
32 \newcommand*{\RS@testednamedef}[1]{%
33 \RS@ifnamedefinable{#1}\RS@namedef{#1}}
34 \newcommand*{\RS@testedrobustnamedef}[1]{%
35 \RS@ifnamedefinable{#1}\RS@robustnamedef{#1}}

\RS@ifnamedefinable A modified version of the LATEX kernel command (from ltdefns.dtx).

36 \long\def\RS@ifnamedefinable #1{%
37 \edef\reserved@a{#1}%
38 \RS@ifundefined\reserved@a
39 {\edef\reserved@b{\expandafter\@carcube \reserved@a xxx\@nil}%
40 \ifx \reserved@b\@qend \RS@notdefinable\else
41 \ifx \reserved@a\@qrelax \RS@notdefinable\else
42 \PackageInfo{\RS@pkgname}{\@backslashchar\reserved@a\space created}%
43 \fi
44 \fi}%
45 \RS@notdefinable}

\RS@notdefinable The error message when an illegal definition is attempted.

46 \gdef\RS@notdefinable{%
47 \PackageError{\RS@pkgname}{%
48 Command \@backslashchar\reserved@a\space
49 already defined.\MessageBreak
50 Or name \@backslashchar\@qend... illegal.\MessageBreak
51 It can not be redefined by the \@backslashchar newref%
52 }{%
53 If \@backslashchar\reserved@a\space is not important\MessageBreak
54 then \protect\let\@backslashchar\reserved@a%
55 =\protect\relax,\MessageBreak
56 else use a different \@backslashchar newref.}%
57 }

\RS@setbool The command5 \RS@setbool{hconditionali}{htrue/falsei} sets the hconditionali

to true or false.
Usage: \RS@setbool{RSplural}{false} → \RSpluralfalse
\RS@setbool{RSplural}{true} → \RSpluraltrue
5 Taken from the ifthen package.

14
 58 \newcommand*{\RS@setbool}[2]{%
59 \lowercase{\def\@tempa{#2}}%
60 \@ifundefined{@tempswa\@tempa}%
61 {\PackageError{\RS@pkgname}%
62 {You can only set the option to ‘true’ or ‘false’}\@ehc}%
63 {\csname#1\@tempa\endcsname}}

6.4 First character case changes

\RS@firstcap This macro6 change the first character of a string to uppercase and returns the
result in \RS@cap.
Usage: \RS@fistcap xxxx\@nil then \RS@cap → Xxxx

64 \def\RS@firstcap#1#2\@nil{%
65 \iffalse{\fi
66 \uppercase{\edef\RS@cap{\iffalse}\fi#1}#2}}%

6.5 Reference building commands

\ifRS@keyactive We need to peek into the options list for the nokeyprefix option before the options
are processed to find out if the key prefix must be included in the \hkeyilabel
command. Make nokeyprefix not used afterwards.
67 \newif\ifRS@keyactive
68 \@ifpackagewith{\@currname}{nokeyprefix}%
69 {\RS@keyactivefalse}%
70 {\RS@keyactivetrue}
71 \DeclareOption{nokeyprefix}{\OptionNotUsed}

\ifRSstar The \if conditional values that are set by the reference commands. These values
\ifRSnameon can be accessed by user defined key-values.
\ifRScapname 72 \newif\ifRSstar\RSstarfalse
\ifRSplural 73 \newif\ifRSnameon\RSnameontrue
\ifRSlsttwo 74 \newif\ifRScapname\RScapnamefalse
75 \newif\ifRSplural\RSpluralfalse
76 \newif\ifRSlsttwo\RSlsttwofalse

\newref The main user interface for template setup. It take the #1 or hkeyi parameter and
make it lowercase before passing it on to \RS@newref.
77 \newcommand*{\newref}[1]{%
78 \lowercase{\def\RS@tempa{#1}}%
79 \expandafter\RS@newref\expandafter{\RS@tempa}}

\RS@newref This command configures a new template.

80 \newcommand*{\RS@newref}[2]{%
Clears an existing template before defining a new one.
81 \RS@clearref{#1}%
Create \ifRS@hkeyivref conditional
82 % \expandafter\newif\csname ifRS@#1vref\endcsname%
6 Posted by Dan Luecking on c.t.t.

15
 Creates a series of key-values for every template that stores the setup
for the specific template.
83 \ifRS@keyactive
84 \define@key{RS@#1}{key}[#1:]{\RS@namedef{RS@#1@key}{##1}}%
85 \else
86 \define@key{RS@#1}{key}[]{\RS@namedef{RS@#1@key}{##1}}%
87 \fi
88 \define@key{RS@#1}{s}[true]{\RS@setbool{RSplural}{##1}}%
89 \define@key{RS@#1}{name}[]{\RS@namedef{RS@#1@name}{##1}}%
90 \define@key{RS@#1}{names}[]{\RS@namedef{RS@#1@names}{##1}}%
91 \define@key{RS@#1}{Name}[]{\RS@namedef{RS@#1@Name}{##1}}%
92 \define@key{RS@#1}{Names}[]{\RS@namedef{RS@#1@Names}{##1}}%
93 \define@key{RS@#1}{rngtxt}[\space to~]{\RS@namedef{RS@#1@rngtxt}{##1}}%
94 \define@key{RS@#1}{lsttwotxt}[\space and~]{\RS@namedef{RS@#1@lsttwotxt}{##1}}%
95 \define@key{RS@#1}{lsttxt}[\space and~]{\RS@namedef{RS@#1@lsttxt}{##1}}%
96 \define@key{RS@#1}{refcmd}[\ref{####1}]{\RS@namedef{RS@#1@rcmd}####1{##1}}%
97 \define@key{RS@#1}{xr}[]{\RS@namedef{RS@#1@xr}{##1}}%
98 \define@key{RS@#1}{vref}[true]{\RS@namedef{RS@#1vref}{##1}}%
Set default key-value parameters.
99 \RS@setkeys{RS@#1}{key,
100 s=false,
101 name,names,Name,Names,
102 rngtxt,lsttwotxt,lsttxt,
103 refcmd,
104 xr,
105 vref=false}%
Set key-values according to user definitions.
106 \RS@setkeys{RS@#1}{#2}%
Build the reference commands.
107 \RS@buildref{#1}%
108 }

\RS@clearref Clear a reference template for redefinition. It check if the template already exists
and clear it if it does.
109 \newcommand*{\RS@clearref}[1]{%
110 \RS@ifundefined{RS@#1@template}
111 {\RS@namedef{RS@#1@template}{#1}%
112 \PackageInfo{\RS@pkgname}%
113 {New reference template \protect\newref{#1}}{}}
114 {\PackageInfo{\RS@pkgname}%
115 {Reference template \protect\newref{#1} redefined}{}
116 \RS@firstcap#1\@nil
117 \RS@removedef{#1key}%
118 \RS@removedef{#1label}%
119 \RS@removedef{#1ref}%
120 \RS@removedef{\RS@cap ref}%
121 \RS@removedef{#1rangeref}%
122 \RS@removedef{\RS@cap rangeref}%
123 \RS@removedef{#1pageref}%
124 }%
125 }

16
\RS@buildref Build the reference commands. See table 1 for the list of commands. The
\RS@buildref{hkeyi} build commands to call \RS@cmd{hcmdi}{hkeyi}, for ex-
ample:
\hkeyiref → {\RScapnamefalse\RS@cmd{ref}{hkeyi}}

126 \newcommand*{\RS@buildref}[1]{%
127 \RS@firstcap#1\@nil
128 \RS@testednamedef{#1key}{\RS@nameuse{RS@#1@key}}
129 \RS@testednamedef{#1label}##1{\label{\RS@nameuse{RS@#1@key}##1}}
130 \RS@testedrobustnamedef{#1ref}{\RScapnamefalse\RS@cmd{ref}{#1}}
131 \RS@testedrobustnamedef{\RS@cap ref}{\RScapnametrue\RS@cmd{ref}{#1}}
132 \RS@testedrobustnamedef{#1rangeref}{\RScapnamefalse\RS@cmd{rangeref}{#1}}
133 \RS@testedrobustnamedef{\RS@cap rangeref}{\RScapnametrue\RS@cmd{rangeref}{#1}}
134 \RS@testedrobustnamedef{#1pageref}{\RScapnamefalse\RS@cmd{pageref}{#1}}
135 }

\RS@cmd The command \RS@cmd{hcmdi}{hkeyi} calls the final reference formatting com-
\RS@@cmd mands. It checks for the starred form and set the conditionals \ifRSstar and
\ifRSnameon accordingly. It also extracts the optional key-value list.
\RS@cmd{ref}{hkeyi} → \RS@ref{hkeyi}[hkey lsti]
\RS@cmd{rangeref}{hkeyi} → \RS@rangeref{hkeyi}[hkey lsti]
\RS@cmd{pageref}{hkeyi} → \RS@pageref{hkeyi}[hkey lsti]

136 \newcommand*{\RS@cmd}[2]{%
137 \@ifstar{\RSstartrue\RSnameonfalse\RS@@cmd{#1}{#2}}%
138 {\RSstarfalse\RSnameontrue\RS@@cmd{#1}{#2}}}
139 \newcommand*{\RS@@cmd}[2]{%
140 \@ifnextchar[%
141 {\RS@nameuse{RS@#1}{#2}}%
142 {\RS@nameuse{RS@#1}{#2}[]}}

6.6 Reference formatting commands

\RS@ref The command \RS@ref{hkeyi}[hkey lsti]{hlabel lsti} typeset the references to
\RS@@ref the comma-separated reference label list according to the configuration for hkeyi.
\RS@@@ref First of all, remove all spaces for the reference label list.
143 \def\RS@ref#1[#2]#3{%
144 \begingroup
145 \RS@setkeys{RS@#1}{#2}%
146 \@safe@activestrue%
147 \edef\RS@tmpa{\zap@space#3 \@empty}%
148 \@safe@activesfalse%
149 \edef\RS@tmpa{\noexpand\RS@@ref{#1} \RS@tmpa,\relax\noexpand\@eolst}%
150 \RS@tmpa%
151 \endgroup}
Check if there is a single or multiple references in the reference label list. If a single
reference label then use the form set by the s key-value. If multiple reference labels
the use the plural form of the name prefix.7
152 \def\RS@@ref#1 #2,#3\@eolst{%
7 The list of reference commands came from the typedref package.

17
 153 \ifx\relax#3\relax
154 \RS@makename{#1}%
155 \RS@makeref{#1}{#2}%
156 \RS@makevpageref{#1}{#2}%
157 \else
158 \RSpluraltrue%
159 \RS@makename{#1}%
160 \RS@makeref{#1}{#2}%
161 \RS@makevpageref{#1}{#2}%
162 \RSnameonfalse%
163 \RSlsttwotrue%
164 \RS@@@ref{#1} #3\@eolst%
165 \fi}
For more than one reference in the reference list, typeset the rest of the references.
166 \def\RS@@@ref#1 #2,#3\@eolst{%
167 \ifx\relax#3\relax
168 \ifRSlsttwo
169 \RS@nameuse{RS@#1@lsttwotxt}%
170 \else
171 \RS@nameuse{RS@#1@lsttxt}%
172 \fi
173 \RS@makeref{#1}{#2}%
174 \RS@makevpageref{#1}{#2}%
175 \else
176 \RSlsttwofalse%
177 \unskip,\space%
178 \RS@makeref{#1}{#2}%
179 \RS@makevpageref{#1}{#2}%
180 \RS@@@ref{#1} #3\@eolst%
181 \fi}

\RS@rangeref The command \RS@rangeref{hkeyi}[hkey lsti]{hlbl1i}{hlbl2i} typeset the ref-

erences as a range.
182 \def\RS@rangeref#1[#2]#3#4{%
183 \begingroup
184 \RS@setkeys{RS@#1}{#2}%
185 \RSpluraltrue%
186 \RS@makename{#1}%
187 \RS@makeref{#1}{#3}%
188 \RS@nameuse{RS@#1@rngtxt}%
189 \RSnameonfalse%
190 \RS@makeref{#1}{#4}%
191 \RS@makevpagerefrange{#1}{#3}{#4}%
192 \endgroup}

\RS@pageref The command \RS@pageref{hkeyi}[hkey lsti]{hlbli} type the page where {hlbli}
was defined.
193 \def\RS@pageref#1[#2]#3{%
194 \begingroup%
195 \RS@setkeys{RS@#1}{#2}%
196 \RS@ifvref{#1}%
197 {\mbox{}\vpageref*{\RS@lbl{#1}{#3}}}%
198 {\reftextfaraway{\RS@lbl{#1}{#3}}}%

18
 199 {\pageref{\RS@lbl{#1}{#3}}}%
200 \endgroup}

201 \newcommand*{\RS@true}{true}
202 \newcommand*{\RS@false}{false}
203 \newcommand*{\RS@far}{far}

\RS@ifvref The command \RS@ifvref{hkeyi}{htruei}{hfarawayi}{hfalsei} executes the con-

tents of htruei if the vref option for the hkeyi reference type is true and hfalsei
otherwise.
204 \newcommand{\RS@ifvref}[4]{%
205 \edef\RS@tempa{\RS@nameuse{RS@#1vref}}%
206 \ifx\RS@tempa\RS@true\relax
207 #2%
208 \else\ifx\RS@tempa\RS@far\relax
209 #3%
210 \else\ifx\RS@tempa\RS@false\relax
211 #4%
212 \else
213 \PackageError{\RS@pkgname}%
214 {You can only set the vref option to ‘true’, ‘far’ or ‘false’}\@ehc
215 \fi\fi\fi}

\RS@makename The command \RS@makename{hkeyi} build the prefix to the reference commands.
216 \newcommand{\RS@makename}[1]{%
217 \ifRSstar\else\ifRSnameon
218 \ifRSplural
219 \ifRScapname
220 \RS@nameuse{RS@#1@Names}%
221 \else
222 \RS@nameuse{RS@#1@names}%
223 \fi
224 \else
225 \ifRScapname
226 \RS@nameuse{RS@#1@Name}%
227 \else
228 \RS@nameuse{RS@#1@name}%
229 \fi
230 \fi
231 \fi\fi
232 }

\RS@lbl This command builds the full label string for the \ref command.
\RS@lbl{hkeyi}{hlabeli} → {hxr keyihkeyihlabeli}

233 \newcommand*{\RS@lbl}[2]{%
234 \RS@nameuse{RS@#1@xr}\RS@nameuse{RS@#1@key}#2%
235 }

\RS@makeref The command \RS@makeref{hkeyi}{hlabeli} formats the \ref output

\RS@makeref{hkeyi}{hlabeli} → \hrcmdi{\ref{hxr keyihkeyihlabeli}}

19
 236 \newcommand{\RS@makeref}[2]{%
237 \RS@nameuse{RS@#1@rcmd}{\RS@lbl{#1}{#2}}%
238 }

\RS@makevpageref The command \RS@makevpageref{hkeyi}{hlabeli} adds the varioref page refer-

ence if the vref option is true.
239 \newcommand{\RS@makevpageref}[2]{%
240 \RS@ifvref{#1}%
241 {\vpageref[\unskip]{\RS@lbl{#1}{#2}}}%
242 { \reftextfaraway{\RS@lbl{#1}{#2}}}%
243 {}%
244 }

\RS@makevpagerefrange The command \RS@makevpagerefrange{hkeyi}{hlbl1i}{hlbl1i} adds the varioref

page range reference if the vref option is true.
245 \newcommand{\RS@makevpagerefrange}[3]{%
246 \RS@ifvref{#1}%
247 {\space\vpagerefrange[\unskip]{\RS@lbl{#1}{#2}}{\RS@lbl{#1}{#3}}}%
248 {\space\vpagerefrange[\unskip]{\RS@lbl{#1}{#2}}{\RS@lbl{#1}{#3}}}%
249 {}%
250 }

6.7 varioref command predefinitions

251 \AtBeginDocument{%
252 \providecommand{\vpageref}{%
253 \PackageError{\RS@pkgname}%
254 {The vref option used, but varioref.sty not loaded.}%
255 {Load varioref.sty}}
256 \providecommand{\reftextfaraway}{%
257 \PackageError{\RS@pkgname}%
258 {The vref=far option used, but varioref.sty not loaded.}%
259 {Load varioref.sty}}
260 \providecommand{\vpagerefrange}{%
261 \PackageError{\RS@pkgname}%
262 {The vref option used, but varioref.sty not loaded.}%
263 {Load varioref.sty}}
264 }

6.8 Support for language option inclusions in config file

\RSaddto Command from the varioref package is used to add language definitions to the
\extrashlanguagei token for babel.
265 \def\RSaddto#1#2{%
266 #2%
267 \@temptokena{#2}%
268 \ifx#1\relax
269 \let#1\@empty
270 \fi
271 \ifx#1\undefined
272 \edef#1{\the\@temptokena}%
273 \else
274 \toks@\expandafter{#1}%
275 \edef#1{\the\toks@\the\@temptokena}%

20
 276 \fi
277 \@temptokena{}\toks@\@temptokena}

\DeclareLangOpt Command to declare a language option and add language definitions to the
\extrashlanguagei token for babel.
278 \def\DeclareLangOpt#1#2{%
279 \edef\RS@tempa{\expandafter\@gobble\string#2}%
280 \RS@ifundefined{\RS@tempa}%
281 {\PackageError{\RS@pkgname}{%
282 Unknown definitions \@backslashchar\RS@tempa\MessageBreak
283 for language option ‘#1’}{}}%
284 {\DeclareOption{#1}{%
285 \AtBeginDocument{\expandafter\RSaddto\csname extras#1\endcsname #2}}}%
286 }

6.9 Configuration files

\RS@cfgfile,\RS@reffile Define the config file and alternate definition file names.
287 \newcommand*{\RS@cfgfile}{refstyle.cfg}
288 \newcommand*{\RS@reffile}{refstyle.def}

We need to peek into the options list before the options are processed to find
out if the config file is to be loaded or not. The config file can contain options and
must be loaded before \ProcessOptions. Make noconfig not used afterwards.
We first test for a local config file refstyle.def and then for the global config
file refstyle.cfg.
289 \@ifpackagewith{\@currname}{noconfig}%
290 {\PackageInfo{\RS@pkgname}{No config file loaded}}%
291 {\InputIfFileExists{\RS@reffile}%
292 {\PackageInfo{\RS@pkgname}{Local config file \RS@reffile\space used}}
293 {\InputIfFileExists{\RS@cfgfile}%
294 {\PackageInfo{\RS@pkgname}{Config file \RS@cfgfile\space used}}%
295 {\PackageInfo{\RS@pkgname}{No config file found}}}}
296 \DeclareOption{noconfig}{\OptionNotUsed}%
Process the options, including options in config file.
297 \ProcessOptions*\relax
The end of this package.
298 h/pkgi

Change History

v0.0 of \htypeilabel . . . . . . . . . . 17
General: Initial version . . . . . . . . 1 \RSaddto: Rename \RS@addto to
v0.1 \RSaddto . . . . . . . . . . . . . . . 20
General: First stable version . . . . . 1
v0.3
v0.2
General: First updated version . . . 1 General: Documentation update . . 1
Remove redundant \RS@label 19 \RS@setkeys: original \setkeys
\RS@buildref: Remove robust def copy . . . . . . . . . . . . . . . . . . . 13

21
v0.4 \efstyle.def . . . . . . . . . . . . 21
General: Add nokeyprefix option 1 \RS@newref: Ad lsttwotxt option 15
Documentation update . . . . . . . 1 v0.5
\ifRS@keyactive: Add nokeyprefix
\@safe@activesfalse: Add
to turn of the key prefix . . . . 15
\@safe@activestrue . . . . . . . 13
\ifRSlsttwo: Add \ifRSlsttwo
\@safe@activestrue: Add
test for list containing only two
\@safe@activesfalse . . . . . . 13
parameter . . . . . . . . . . . . . . . 15
\RS@@@ref: Add \ifRSlsttwo test General: Documentation update . . 1
for list containing only two pa- \DeclareLangOpt: Add \extrashlanguagei
rameter . . . . . . . . . . . . . . . . 17 to beginning of document. . . . 21
\RS@cfgfile,\RS@reffile: Ad \RS@ref: Add \@safe@activestrue
alternative definition file to avoid active chars is ref list 17

Index
Numbers written in italic refer to the page where the corresponding entry is de-
scribed; numbers underlined refer to the code line of the definition; numbers in
roman refer to the code lines where the entry is used.

Symbols \KV@prefix ........ 9 \RS@far . . . . . . 203, 208

\@currname . . . . 68, 289 \RS@firstcap 64, 116, 127
\@eolst . . . . . . 149, L \RS@ifnamedefinable
152, 164, 166, 180 \label . . . . . . . . . . . 129 . . . . . . . 33, 35, 36
\@gobble . . . . . . . . . 279 \RS@ifundefined . . .
\@ifpackagewith 68, 289 N 22, 31, 38, 110, 280
\@safe@activesfalse \newref . . . 77, 113, 115 \RS@ifvref . . . . . . .
. . . . . . . . 13, 148 . 196, 204, 240, 246
\@safe@activestrue . O \RS@keyactivefalse . 69
. . . . . . . . 13, 146 \OptionNotUsed . 71, 296 \RS@keyactivetrue . 70
\@tempc . . . . . . . . . . 10 \RS@lbl . . . . . . 197–
\@temptokena . . . . . . P 199, 233, 237,
. 267, 272, 275, 277 \pageref . . . . . . . . . 199 241, 242, 247, 248
\RS@makename . . . . . .
A R . 154, 159, 186, 216
\AtBeginDocument . . \ref . . . . . . . . . . . . . 96 \RS@makeref . . . . . . .
. . . . . . . . 251, 285 \RefstyleFileDate . . 3 . 155, 160, 173,
\RefstyleFileVersion 4 178, 187, 190, 236
D \reftextfaraway . . . \RS@makevpageref 156,
\DeclareLangOpt . . . 278 . . . . 198, 242, 256 161, 174, 179, 239
\define@key . . . . . . . \RS@@@ref . . . . . . . . \RS@makevpagerefrange
. . . . 84, 86, 88–98 . 143, 164, 166, 180 . . . . . . . . 191, 245
\RS@@cmd . . . . . . . . . 136 \RS@namedef . . 15, 33,
I \RS@@ref . . . . . . . . . 143 84, 86, 89–98, 111
\ifRS@keyactive . 67, 83 \RS@buildref . . 107, 126 \RS@namelet . . 15, 30, 31
\ifRScapname 72, 219, 225 \RS@cap . . . . . . . 66, \RS@nameuse . 15, 128,
\ifRSlsttwo . . . . 72, 168 120, 122, 131, 133 129, 141, 142,
\ifRSnameon . . . . 72, 217 \RS@cfgfile . . . 293, 294 169, 171, 188,
\ifRSplural . . . . 72, 218 \RS@cfgfile,\RS@reffile 205, 220, 222,
\ifRSstar . . . . . 72, 217 . . . . . . . . . . . 287 226, 228, 234, 237
\RS@clearref . . . 81, 109 \RS@newref . . . . . 79, 80
K \RS@cmd . . . 130–134, 136 \RS@notdefinable . .
\KV@do . . . . . . . . . . . 11 \RS@false . . . . 202, 210 . . . . 40, 41, 45, 46

22
\RS@pageref . . . . . . . 193 \RS@testedrobustnamedef \RSstarfalse . . . 72, 138
\RS@rangeref . . . . . . 182 . . . . . 32, 130–134 \RSstartrue . . . . . . . 137
\RS@ref . . . . . . . . . . 143 \RS@true . . . . . 201, 206
\RS@reffile . . . 291, 292 \RSaddto . . . . . 265, 285 T
\RScapnamefalse . . . \the . . . . . . . . . 272, 275
\RS@removedef . . . . .
. 74, 130, 132, 134 \toks@ . . . . 274, 275, 277
. . . . . 29, 117–123
\RS@robustnamedef 15, 35 \RScapnametrue 131, 133
U
\RS@setbool . . . . . 58, 88 \RSlsttwofalse . 76, 176
\undefined . . . . . . . 271
\RS@setkeys . . . . . . . . 8 \RSlsttwotrue . . . . . 163
\RS@tempa . . . 78, 79, \RSnameonfalse . . . . V
205, 206, 208, . . . . 137, 162, 189 \vpageref . 197, 241, 252
210, 279, 280, 282 \RSnameontrue . . 73, 138 \vpagerefrange . . . .
\RS@testednamedef . \RSpluralfalse . . . . 75 . . . . 247, 248, 260
. . . . . 32, 128, 129 \RSpluraltrue . 158, 185 \vref@space . . . . . . . 12

23