path: root/support/texref/texref.1

.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"