summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/smartref/smartref-doc.tex
blob: 20973999a955d63f341aca36bd386b5fa747e6ad (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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
\documentclass[pagesize=auto, parskip=half, headings=normal]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{hologo}
\usepackage{microtype}
\usepackage{hyperref}

\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cls}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\opt}[1]{\texttt{#1}}
\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}

\addtokomafont{title}{\rmfamily}

\title{The \pkg{smartref} package\thanks{This manual corresponds to \pkg{smartref.sty}~v1.9, dated~2002/02/28.}}
\author{Giuseppe Bilotta\thanks{\mail{bourbaki@bigfoot.com}}}
\date{2002/02/28}


\begin{document}

\maketitle

The purpose of this package is to extend the capability of the
the \cmd{\ref} command; precisely, whenever a label is set, this
package records, along with the label, the values of some other
counters (which, can be selected by the user); then, the value of
these counters can be recalled, with a command similar to
\cmd{\pageref}; moreover, this package adds a command (\cmd{\s\meta{name}ref}) for
each counter added, that displays something only if the value of
the \meta{name} counter is changed from when the label is set. For
example, let's say that we are using the \cls{amsbook} class, and we
are numbering theorems within sections; when we want to refer to
a theorem in another section, same chapter, we just say
`\verb|as in theorem \ref{zorn}|'; but if we want to refer to a theorem in
another chapter, we have to set a label for that chapter and then
say `\verb|as in theorem \ref{zorn}, in chapter \ref{chapterofzorn}|';
if we, later on, move the referenced theorem (or the referencing
line) in some other chapter, we might need to update the
references; with this package, there's no need for that: you say,
at the beginning of the document:
%
\begin{verbatim}
    \addtoreflist{chapter}
\end{verbatim}
%
and then, every \cmd{\label} is recorded alongside with the chapter in
which it occurred. When we refer to the theorem, we might now say
%
\begin{verbatim}
    theorem \ref{zorn}, chapter \chapterref{zorn}
\end{verbatim}
%
if we are sure it will always be in another chapter, or
%
\begin{verbatim}
    theorem \ref{zorn}\schapterref{zorn}
\end{verbatim}
%
where the second command prints nothing if the chapter is the same
as the current, or prints `\verb|, chap. \chapterref{zorn}|' if the chapter
has changed. Since this command sequence is supposed to be used with
quite a frequency, it is not-so-short-handed by \cmd{\srefchapterref}
(\cmd{\sref\meta{name}ref}, in general).

Here's a complete list of the commands made available by this
package.
%
\begin{quote}
  \cmd{\addtoreflist}\marg{name}
\end{quote}
%
This is the first command called: it says that the \meta{name} counter
is to be recorded alongside with all the (following) labels;
please use it \emph{before} defining any label, because the result is
unknown if the SmartReference list changes during use (nothing
special should happen, anyhow; it should work correctly).

The previous command defines a few commands, whose name depends
on the counter chosen. The commands are:
%
\begin{quote}
  \cmd{\sget\meta{name}val}\texttt{\{}\cs{\meta{variable}}\texttt{\}}\marg{foo}
\end{quote}
%
This command gets the value of counter \meta{name} recorded with label
\meta{foo}, and puts this value in the chosen \cs{\meta{variable}}.

\begin{quote}
  \cs{\meta{name}ref}\marg{foo}
\end{quote}
%
This command prints the value of the counter \meta{name} recorded with
label \meta{foo}.

\begin{quote}
  \cs{if\meta{name}changed}
\end{quote}
%
`If' construct for the next two commands:
%
\begin{quote}
  \cmd{\is\meta{name}changed}\marg{foo}
\end{quote}
%
Checks whether the \meta{name} counter is changed from value recorded
with \meta{foo}, and sets \cs{\meta{name}changed} accordingly

\begin{quote}
  \cmd{\s\meta{name}ref}\marg{foo}
\end{quote}
%
This command prints nothing if the value of \meta{name} is not
different, but prints
%
\begin{quote}
  \ttfamily
  , \cmd{\short\meta{name}name} \cs{\meta{name}ref}\marg{foo}
\end{quote}
%
if the
value did change; the \cmd{\short\meta{name}name} should be defined by the
user. It queries by using the previous command.

\begin{quote}
  \cmd{\sref\meta{name}ref}\marg{foo}
\end{quote}
%
Equivalent of `\cmd{\ref}\marg{foo}\cmd{\s\meta{name}ref}\marg{foo}'.

\pagebreak[2]

The only options accepted, as for now, are \opt{chapter} and \opt{part};
\opt{chapter} does the following:
%
\begin{itemize}
\item adds the \texttt{chapter} counter to the smart list
\item defines \cmd{\shortchaptername} to be `Cap.' if \pkg{babel} is loaded with
  option \opt{italian}, `Chap.' otherwise
\item defines \cmd{\smartref} to be \cmd{\srefchapterref}
\end{itemize}

\opt{part} does the following:
%
\begin{itemize}
\item adds the \texttt{part} counter to the smart list
\item defines \cmd{\shortpartname} to be `Parte' if \pkg{babel} is loaded with
  option \opt{italian}, `Part' otherwise
\item defines \cmd{\smartref} to be \cmd{\srefpartref} if previously undefined,
  or adds \cmd{\spartref} to previous definition of \cmd{\smartref} (saved in
  \cmd{\nopart@smartref}) otherwise (this is mainly to be used after the
  option \opt{chapter}).
\end{itemize}

As of version~1.6, the package comes with a small style file:
%
\begin{quote}
  \texttt{byname.sty};
\end{quote}
%
it can be used alone, or within \pkg{smartref}, when the option
\opt{byname} is used; it adds the command
%
\begin{quote}
  \cmd{\byname}\marg{label}
\end{quote}
%
that can be used when referencing to a section (subsection, etc) by
name instead of number. As of version~1.8, the same style file also
provides the command \cmd{\byshortname} that does the same as \cmd{\byname},
except that it uses the ``short'' name (the one provided in square
brackets).

Note that the references create by \pkg{smartref} and \pkg{byname} are \emph{not}
hyperlink, when \pkg{hyperref} is active. Maybe in the future \dots

(You can still have ``named'' links with \pkg{hyperref} using the \pkg{nameref}
style file provided with \pkg{hyperref} itself).

\medskip\centerline{$***$}\medskip

Please send me any bugs, comments, suggestions, hacks, etc etc
etc \dots

Giuseppe Bilotta

Email: \mail{bourbaki@bigfoot.com}

Heartily thanks to James Kilfiger (\mail{mapdn@csv.warwick.ac.uk}) whose
consulence has been essential (let me say vital) to the birth of
this small package in its first revision (v0.1); it was him who
gave me the idea to hack the \cmd{\label} command, and then encouraged
me to put the newborn code in a package (and telling me how to do
it!); it was also him that pointed out a potential bug in
documents where chapters don't start on a page on their own
(seems that the bug is not present, anyway \dots).

\medskip\centerline{$***$}


\section*{TODOs:}

\begin{itemize}
\item \pkg{Babel}: instead of \cmd{\chaptername} (for example), this package uses
  \cmd{\short\-chapter\-name}, and this is not yet changed by \pkg{Babel}; you can
  set it up to your short form of chapter. Please send me the short
  names, so that I can implement them.

\item Maybe put an option (\opt{long}) to make \cmd{\short\meta{name}name} an alias for
  \cs{\meta{name}name}

\item Options: If the option is not recognized, check if it's a counter,
  and add it; otherwise, do nothing

\item Smartrefs: check for counters that get reset by other counters
  (section in chapter, etc); maybe link to the \cmd{\@addtoreset}
  internal command \dots

\item \pkg{ByName}: refine, and add commands to do both references with a single
  command
\end{itemize}

\medskip\centerline{$***$}


\section*{History:}

\begin{labeling}{v1.9}
\item[v0.1] First release (only did chapter and part).
\item[v1.0] First customizable release.
\item[v1.1] Made it work with \pkg{HyperRef}.
\item[v1.5] Added \pkg{nameref.sty}: reference by name.
\item[v1.6] Changed name to \pkg{byname.sty}, because of name conflict with style
  file from the \pkg{HyperRef} bundle.
\item[v1.8] Fixed bugs in \pkg{smartref}, changed behaviour for unknown options,
  fixed bug in \pkg{byname} that actually prevented it from functioning
  properly.
\item[v1.9] Fixed limitation with \hologo{AmSLaTeX}: would not handle \cmd{\labels} within
  equation because \hologo{AmSLaTeX} redefines the \cmd{\label} command for
  equations.\\
  Made \cmd{\smartref} robust.	 
\end{labeling}

\end{document}