summaryrefslogtreecommitdiff
path: root/support/texref/texref.1
blob: 1e3c16cd92be944a71b5c8e69d41f7e3a8bc0424 (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
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
.rn '' }`
''' $RCSfile$$Revision$$Date$
'''
''' $Log$
'''
.de Sh
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb
.ft CW
.nf
.ne \\$1
..
.de Ve
.ft R

.fi
..
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.ds PI pi
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
'br\}
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
.\}
.TH TEXREF 1 "perl 5.004, patch 04" "13/Sep/99" "User Contributed Perl Documentation"
.UC
.if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
.bd B 3
.	\" fudge factors for nroff and troff
.if n \{\
.	ds #H 0
.	ds #V .8m
.	ds #F .3m
.	ds #[ \f1
.	ds #] \fP
.\}
.if t \{\
.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.	ds #V .6m
.	ds #F 0
.	ds #[ \&
.	ds #] \&
.\}
.	\" simple accents for nroff and troff
.if n \{\
.	ds ' \&
.	ds ` \&
.	ds ^ \&
.	ds , \&
.	ds ~ ~
.	ds ? ?
.	ds ! !
.	ds /
.	ds q
.\}
.if t \{\
.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
.\}
.	\" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
.	\" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.	\" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.	ds : e
.	ds 8 ss
.	ds v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	ds o a
.	ds d- d\h'-1'\(ga
.	ds D- D\h'-1'\(hy
.	ds th \o'bp'
.	ds Th \o'LP'
.	ds ae ae
.	ds Ae AE
.	ds oe oe
.	ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
texref \- Find cross-references for a LaTeX file
.SH "SYNOPSIS"
\fBtexref\fR
[\fB\-(no)aux\fR]
[\fB\-help\fR]
[\fB\-match\fR \fIregexp\fR]
[\fB\-out\fR \fIfilename\fR]
[\fB\-(no)sort\fR]
[\fB\-sortby label|def|input\fR]
[\fB\-unref\fR]
[\fB\-verbose\fR]
\fIfile\fR[.tex]
.SH "DESCRIPTION"
\fBtexref\fR reads a .tex file, and (recursively) all \einput{} and
\einclude{} files referenced therein, collecting the names of all
\elabels and \e*ref{}s as it goes.  It then prints the list of labels
together with information about where those labels are referenced
in the .tex \fIfile\fR\|(s).
.PP
References to labels are recognized as commands of the form
.PP
.Vb 1
\&   \e[a-z]*ref{key}
.Ve
This allows for custom LaTeX referencing commands, such as
.PP
.Vb 1
\&   \enewcommand{figref}[1]{Figure~\eref{#1}}
.Ve
as well as the varioref package, which uses the \evref{key} command.
In addition, the program recognizes lists of references, encoded
as commands of the form,
.PP
.Vb 1
\&   \e[a-z]*refs{key1,key2,key3}
.Ve
which expand to something like \*(L'Figure 1, Figure 2, and Figure 3\*(R'.
These could be provided by the LaTeX commands
.PP
.Vb 13
\&   \enewcommand{\efigrefs}[1]{\edorefs{#1}{Figures}}
\&   \enewcommand{\etabrefs}[1]{\edorefs{#1}{Tables}}
\&   \enewcommand{\eexrefs}[1]{\edorefs{#1}{Examples}}
\&   \emakeatletter
\&   \enewcommand{\edorefs}[2]{%
\&      \elet\e@dummy\e@empty
\&      #2~%
\&      \e@for\e@term:=#1\edo{%
\&         \e@dummy
\&         \eedef\e@dummy{\eref{\e@term}, }}%
\&      \eexpandafter\eformat@last\e@dummy}
\&   \edef\eformat@last#1, {and #1}
\&   \emakeatother
.Ve
Finally, the program recognizes reference ranges, like \efigrange{key1}{key3}
which expand to \*(L'Figure 1\*(--3\*(R', from commands like
.PP
.Vb 2
\&   \enewcommand{\efigrange}[2]{Figures~\eref{#1}--\eref{#2}}
\&   \enewcommand{\etabrange}[2]{Tables~\eref{#1}--\eref{#2}}
.Ve
Labels are described by the filename and line number where they
are defined;  if the \fB\-aux\fR option is in effect, the corresponding
\&\fI.aux\fR files are also read (\enewlabel{} lines) to obtain the label
number and the page location in the document, assuming the file
has been processed by LaTeX.
.SH "OPTIONS AND ARGUMENTS"
All options may be abbreviated to their unique truncations, so \fB\-h\fR, \fB\-he\fR,
\fB\-hel\fR all print help.
Options which take an argument may be followed by a blank or \*(L'=\*(R'.
Those values may need to be quoted if they contain characters interpreted
by your shell.
.Ip "\fB\-aux\fR | \fB\-noaux\fR" 4
If the \fB\-aux\fR option is in effect, the .log file is read to find
the \fI.aux\fR files corresponding to the .tex file.  Then, each .aux
file is read (looking for \enewlabel{} lines) to obtain the label
number and the page location in the document.  This assumes that
the .tex file has been processed by LaTeX so that the information
in the .aux files is up to date.  The default is \fB\-aux\fR (unless
changed in the configuration section).
.Ip "\fB\-help\fR" 4
Print a brief help message and exit.
.Ip "\fB\-match\fR\ \fIrexexp\fR" 4
Print only the labels which match the \fIrexexp\fR.  If you use systematic
labels (e.g., fig:name for figures, sec:name for sections, etc.)
\fB\-match\fR \*(L'fig:\*(R' will select only figure labels, etc.  Use a pipe to grep to
select more finely (e.g., to find figure labels in Chapter 4).
.Ip "\fB\-out\fR\ \fIfilename\fR" 4
Send the output to a named file rather than to \s-1STDOUT\s0.
.Ip "\fB\-sort\fR | \fB\-nosort\fR" 4
Sort (or do not sort) the labels in the output.  If sorting, the sort
order can be set by the \fB\-sortby\fR option.  If not sorting, the
order in the output is apparently haphazard (the order of perl keys
for a hash).
.Ip "\fB\-sortby\fR\ [label|def|input]" 4
If sorting, \fB\-sortby\fR=label means that the output is sorted by the
label string.  \fB\-sortby\fR=def means that the output is sorted by
the label definition string, which normally looks line
.Sp
.Vb 1
\&  filename linenumber labelnum pagenum
.Ve
\fB\-sortby\fR=input (the default) simply lists the labels in the order
encountered in the input \fIfile\fR\|(s).  This order is easiest to use
for resolving unreferenced labels.
 
=item \fB\-unref\fR
.Sp
If specified, only labels for which no corresponding \e*ref references
have been found are printed.
.Ip "\fB\-verbose\fR" 4
Lots of messages, written to \s-1STDERR\s0.
.SH "EXAMPLES"
To show the output format, the following command uses all defaults:
.PP
.Vb 8
\&   % texref drew
\&   sec:mosaic      (drew.tex 186 #2 P2): drew.tex 137
\&   eq:pij  (drew.tex 212 #1 P2): UNREF
\&   tab:hairdat     (tab/hairdat.tex 3 #1 P3): drew.tex 222, drew.tex 455
\&   fig:mosaic3i    (drew.tex 248 #1 P3): drew.tex 231, drew.tex 234
\&   fig:mosaic34    (drew.tex 306 #2 P5): drew.tex 282, drew.tex 311, drew.tex 322, drew.tex 486
\&   eq:pijkl        (drew.tex 344 #2 P5): drew.tex 348
\&    ...
.Ve
To print only unrefereced labels:
.PP
.Vb 2
\&    % texref -unr drew
\&    eq:pij  (drew.tex 212 #1 P2): UNREF
.Ve
.SH "LIMITATIONS"
The program is tuned to LaTeX, not TeX.
.PP
It does not handle references to subfigures, as provided by the
subfigure and subfigmat packages.
.PP
There is no \-undef option to print labels which are referenced but not
defined.  But you did catch these when you LaTeX'd your file, right?
.PP
The output format is inflexible.
.SH "BUGS"
Sorting by def sorts the label definitions as strings, so \*(L'myfile 1020\*(R'
appears before \*(L'myfile 723\*(R', which appears before \*(L'myfile 9\*(R'.
.SH "SEE ALSO"
ftp://cmssun1.pd.infn.it/pub/MLO/texref.tar.gz
.PP
texdepend: CTAN support/texdepend
.PP
texfind: CTAN support/texfind
.SH "AUTHOR"
Michael Friendly <friendly@yorku.ca>
.SH "LICENSE"
\fBtexref\fR is distributed under the terms of the LaTeX Project Public
License (LPPL).  This means that you may freely copy or distribute this
software, but if you modify it and distribute it (even locally) you must
change the name to avoid confusion.
See: CTAN:: help/Catalog/Licenses.html.

.rn }` ''
.IX Title "TEXREF 1"
.IX Name "texref - Find cross-references for a LaTeX file"

.IX Header "NAME"

.IX Header "SYNOPSIS"

.IX Header "DESCRIPTION"

.IX Header "OPTIONS AND ARGUMENTS"

.IX Item "\fB\-aux\fR | \fB\-noaux\fR"

.IX Item "\fB\-help\fR"

.IX Item "\fB\-match\fR\ \fIrexexp\fR"

.IX Item "\fB\-out\fR\ \fIfilename\fR"

.IX Item "\fB\-sort\fR | \fB\-nosort\fR"

.IX Item "\fB\-sortby\fR\ [label|def|input]"

.IX Item "\fB\-verbose\fR"

.IX Header "EXAMPLES"

.IX Header "LIMITATIONS"

.IX Header "BUGS"

.IX Header "SEE ALSO"

.IX Header "AUTHOR"

.IX Header "LICENSE"