summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-lab-ref.tex
blob: d1629fd7b7c8da4aa113e5a911a9200250af7e92 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
% $Id: faq-lab-ref.tex,v 1.4 2011/05/08 10:16:43 rf10 Exp $

\subsection{Labels and references}

\Question[Q-nameref]{Referring to things by their name}

\LaTeX{}'s labelling mechanism is designed for the impersonal world of
the academic publication, in which everything has a number: an
extension is necessary if we are to record the \emph{name} of things
we've labelled.  The two packages available extend the \LaTeX{}
sectioning commands to provide reference by the name of the section.

The \Package{titleref} package is a simple extension which provides
the command \csx{titleref}; it is a stand-alone package~--- don't use it
in a document in which you also need to use \Package{hyperref}.

The \Package{byname} package is part of the \Package{smartref} bundle
and works well with \Package{smartref}, and works (to an extent) with
\Package{hyperref}, but the links it defines are not hyperlinks.

The \Class{memoir} class incorporates the functionality of
\Package{titleref}, but doesn't work with \Package{byname} (though a
search of \Newsgroup{comp.text.tex} on \URL{groups.google.com} will
find a patch to \Package{byname} to remedy the problem).

The \Package{hyperref} bundle includes a package \Package{nameref},
which will work standing alone (i.e., without \Package{hyperref}: of
course, in this mode its references are not hyperlinked).  If you load
\Package{hyperref} itself, \Package{nameref} is automatically loaded.
\Class{Memoir} requires the \Package{memhfixc} when running with
\Package{hyperref}; following the sequence:
\begin{quote}
\begin{verbatim}
\documentclass[...]{memoir}
...
\usepackage[...]{hyperref}
\usepackage{memhfixc}
\end{verbatim}
\end{quote}
\Package{nameref} commands may be used in a \Class{memoir} document.

\Package{Zref} defines a proposed replacement for all of the \LaTeX{}
reference mechanisms, and among other things provides
name-referencing mechanisms:
\begin{quote}
\begin{verbatim}
\usepackage[user,titleref]{zref}
...
\section{hello}\zlabel{sec:one}
The section name is: \ztitleref{sec:one}.
\end{verbatim}
\end{quote}
(One might hope that something of this sort would be the ``way of the
future'', but things move slowly in the \LaTeX{} world: don't hold
your breath.) 

Each of \Package{titleref}, \Package{byname} and \Package{nameref}
defines a reference command with the same name as the package:
\csx{titleref}, \csx{byname} and \csx{nameref}. The \Package{nameref}
package also defines a command \csx{byshortnameref}, which uses the
optional `short' title argument to the chapter and section commands.
(Although it comes from the same author, \Package{zref} \emph{doesn't}
define a short-name variant.)
\begin{ctanrefs}
\item[byname.sty]Distributed with \CTANref{smartref}
\item[hyperref.sty]\CTANref{hyperref}
\item[memoir.cls]\CTANref{memoir}
\item[nameref.sty]Distributed with \CTANref{hyperref}
\item[smartref.sty]\CTANref{smartref}
\item[titleref.sty]\CTANref{titleref}
\item[zref.sty]Distributed as part of \CTANref{oberdiek}[zref]
\end{ctanrefs}

\Question[Q-extref]{Referring to labels in other documents}

When producing a set of inter-related documents, you'll often want to
refer to labels in another document of the set; but \LaTeX{}, of its
own accord, doesn't permit this.

So the package \Package{xr} was written: if you say
\begin{quote}
\begin{verbatim}
\usepackage{xr}
\externaldocument{volume1}
\end{verbatim}
\end{quote}
will load all the references from \File{volume1} into your present
document.

But what if the documents both have a section labelled
``\environment{introduction}'' (likely enough, after all)?  The
package provides a means to transform all the imported labels, so you
don't have to change label names in either document.  For example:
\begin{quote}
\begin{verbatim}
\usepackage{xr}
\externaldocument[V1-]{volume1}
\end{verbatim}
\end{quote}
loads the references from \File{volume1}, but prefixes every one with
the string \texttt{V1-}.  So you would refer to the introduction to volume~1
as:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\usepackage{xr}
\externaldocument[V1-]{volume1}
...
... the introduction to volume1
               (\ref{V1-introduction})...
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\usepackage{xr}
\externaldocument[V1-]{volume1}
...
... the introduction to volume1 (\ref{V1-introduction})...
\end{verbatim}
\end{wideversion}
\end{quote}
To have the facilities of \Package{xr} working with
\Package{hyperref}, you need \Package{xr-hyper}.  For simple
hyper-cross-referencing (i.e., to a local \acro{PDF} file you've just
compiled), write:
\begin{quote}
\begin{verbatim}
\usepackage{xr-hyper}
\usepackage{hyperref}
\externaldocument[V1-]{volume1}
...
... the \nameref{V1-introduction})...
\end{verbatim}
\end{quote}
and the name reference will appear as an active link to the
``introduction'' chapter of \File{volume1.pdf}.

To link to a \acro{PDF} document on the Web, for which you happen to
have the .aux file, write:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\usepackage{xr-hyper}
\usepackage{hyperref}
\externaldocument[V1-]{volume1}[http://mybook.com/volume1.pdf]
...
... the \nameref{V1-introduction})...
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\usepackage{xr-hyper}
\usepackage{hyperref}
\externaldocument[V1-]{volume1}%
    [http://mybook.com/volume1.pdf]
...
... the \nameref{V1-introduction})...
\end{verbatim}
\end{narrowversion}
\end{quote}
Heiko Oberdiek's experimental \Package{zref} bundle includes a
hyper-crossreferencing mechanism using its \Package{zref-xr} module.
Usage is closely modelled on \Package{xr} and \Package{xr-hyper}; a
trivial example (from a \Newsgroup{comp.text.tex} posting) is
\begin{quote}
\begin{verbatim}
\usepackage{zref-xr,zref-user}
\zexternaldocument*{xr02}
...
\zref{foo}
\end{verbatim}
\end{quote}
The module provides all the facilities of the older packages, and can
deal both with ``traditional'' \LaTeX{} labels and with
\Package{zref}'s style of labels.
\begin{ctanrefs}
\item[xr.sty]Distributed as part of \CTANref{2etools}[xr]
\item[xr-hyper.sty]Distributed with \CTANref{hyperref}[xr-hyper]
\item[zref \nothtml{\rmfamily\itshape}bundle]Distributed as part of
  \CTANref{oberdiek}[zref]
\end{ctanrefs}