diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texref |
Initial commit
Diffstat (limited to 'support/texref')
-rw-r--r-- | support/texref/INSTALL | 20 | ||||
-rw-r--r-- | support/texref/MANIFEST | 6 | ||||
-rw-r--r-- | support/texref/Makefile.PL | 19 | ||||
-rw-r--r-- | support/texref/README | 23 | ||||
-rw-r--r-- | support/texref/texref | 597 | ||||
-rw-r--r-- | support/texref/texref.1 | 387 |
6 files changed, 1052 insertions, 0 deletions
diff --git a/support/texref/INSTALL b/support/texref/INSTALL new file mode 100644 index 0000000000..a16b7f6450 --- /dev/null +++ b/support/texref/INSTALL @@ -0,0 +1,20 @@ + +To install the script and man pages in the standard areas, +give the sequence of commands + + perl Makefile.PL + make + make install + +If you want to install the script in your own private space, use + + perl Makefile.PL PREFIX=/my/private/perllib \ + INSTALLMAN1DIR=/my/private/perllib/man/man1 \ + INSTALLMAN3DIR=/my/private/perllib/man/man3 + make + make install + +Or, just do + + cp -p texref /usr/local/bin + cp -p texref /usr/local/man/man1 diff --git a/support/texref/MANIFEST b/support/texref/MANIFEST new file mode 100644 index 0000000000..6203fbab4c --- /dev/null +++ b/support/texref/MANIFEST @@ -0,0 +1,6 @@ +texref +texref.1 +INSTALL +MANIFEST +Makefile.PL +README diff --git a/support/texref/Makefile.PL b/support/texref/Makefile.PL new file mode 100644 index 0000000000..befbc0bd7e --- /dev/null +++ b/support/texref/Makefile.PL @@ -0,0 +1,19 @@ +use ExtUtils::MakeMaker; +# +# See lib/ExtUtils/MakeMaker.pm for details of how to influence +# the contents of the Makefile that is written. +# +# As well, if you wish to force a minimal perl version to run the +# script, insert a line, for example, +# +# require 5.004; +# +# below. + +WriteMakefile( + 'NAME' => 'texref', + 'VERSION_FROM' => 'texref', # finds $VERSION + 'dist' => { COMPRESS => 'gzip', SUFFIX => 'gz' }, + 'EXE_FILES' => [ 'texref' ], # scripts to install +); + diff --git a/support/texref/README b/support/texref/README new file mode 100644 index 0000000000..1c57562c90 --- /dev/null +++ b/support/texref/README @@ -0,0 +1,23 @@ +NAME + texref - Find cross-references for a LaTeX file + +SYNOPSIS + texref [-(no)aux] [-help] [-match *regexp*] [-out *filename*] [- + (no)sort] [-sortby label|def|input] [-unref] [-verbose] *file*[.tex] + +DESCRIPTION + texref reads a .tex file, and (recursively) all \input{} and \include{} + files referenced therein, collecting the names of all \labels and + \*ref{}s as it goes. It then prints the list of labels together with + information about where those labels are referenced in the .tex file(s). + +AUTHOR + Michael Friendly <friendly@yorku.ca> + +LICENSE + texref 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. + diff --git a/support/texref/texref b/support/texref/texref new file mode 100644 index 0000000000..950a87553b --- /dev/null +++ b/support/texref/texref @@ -0,0 +1,597 @@ +#! /usr/local/bin/perl + +$VERSION=1.01; # 12 Sep 1999 13:57:21 +use vars qw($VERSION); + +$Author='Michael Friendly (friendly@yorku.ca)'; # Copyright 1999 +$License = 'LPPL'; # released under the LPPL license + +######################################################################## +# texref: a Perl script for finding cross-refs in a LaTeX file + +# texref reads a .tex file, and (recursively) all \input{} and +# \include{} files referenced therein, collecting the names of all +# \labels and \*ref{}s as it goes. It then prints the list of labels +# together with information about where those labels are referenced +# in the .tex file(s). + +# Pretty documentation: run pod2man or pod2text on this script, +# or just read the documentation after __END__ + +# A C/C++ program of the same name was written by Maurizio Loreti +# <maurizio.loreti@pd.infn.it> and is available by ftp at +# cmssun1.pd.infn.it/pub/MLO/texref.tar.gz + +# Changes: +# 1.00 Initial version. [Thanks to Bernd Schandl +# <bschand@math.clemson.edu> for suggestions.] +# 1.01 Added $opt_sortby = input, and made it the default. +###################### Start of configuration ###################### + +$opt_aux = 1; # Search .aux files for extended label info +$opt_sort = 1; # Sort labels +$opt_sortby = 'input'; # Sort by label|def|input +$VERBOSE = 0; # Lots of messages... + +# How to search for files on the various TeX paths: + +# If teTeX is installed, use kpsetool to locate tex/bst/sty files before +# trying the TEXINPUTS path, for efficiency. +$KPSEWHICH = '/usr/local/teTeX/bin/kpsewhich'; # won't fail if not -x +# Otherwise, uncomment the following statement +#undef $KPSEWHICH; + +$TEXINPUTS = "TEXINPUTS"; # Name of TEXINPUTS environment variable + +# These patterns are currently NOT USED. Why don't they work when used +# in get_xrefs? +# Patterns for include-type statements, leaving filename in #1 +$include_pat = join('|', + ('\\input\b\{?(\S+)\}', + '\\include\s*\{(\S+)\}' + )); + +# Patterns for references to a label, leaving label in $1 +$ref_pat = '\\[a-z]*ref\{([^}]+)\}'; # pattern for single ref + +$refs_pat = '\\[a-z]*refs\{([^}]+)\}'; # pattern for multiple refs + +$ref_range = '\\[a-z]*range\{([^}]+)\}\{([^}]+)\}'; # for ref range + +###################### End of configuration ###################### + +######################### Initializations ######################## + +# remove path from our name + + $progname = $0; + $progname =~ s@(.*)/@@i; + + $in_preamble = 1; + @labels = (); + +################## get and process command options ############### + + use Getopt::Long; + $result = GetOptions ('aux!', 'help', 'match=s', 'out=s', 'sort', + 'sortby=s', 'unref', 'verbose'); + + &usage() if $opt_help; # and exit + + if ($opt_out) { + open(STDOUT, ">$opt_out") or die "$progname: -out $opt_out: can't create.\n"; + } else { + select(STDOUT); $| = 1; + } + + + $VERBOSE=1 if $opt_verbose; + + $texfile = $ARGV[0] || &usage(); # usage doesn't return + shift; + +######################################################################## +# Split the tex filename up into a path, name, and extension +# +($TEXFILEPATH,$TEXFILENAME,$TEXFILEEXT) = &splitfn($texfile,".tex"); + +######################################################################## +# Locate the requested TeX file. It's either in the current (or +# specified) directory or no path was specified and it's on the +# TEXINPUTS path. +# +$Qtexfile = &cleanup_texfilename($texfile); +if (! -e $Qtexfile ) { + if ($texfile !~ /[\/\\]/) { # no path... + $Qtexfile = &find_on_path("$ENV{$TEXINPUTS}", "$texfile", 'tex'); + $Qtexfile = &find_on_path("$ENV{$TEXINPUTS}", "$texfile".".tex", 'tex') + if $Qtexfile eq ""; + die "Cannot find \"$texfile\[.tex\]\" on $TEXINPUTS path.\n" + if $Qtexfile eq ""; + + $texfile = $Qtexfile ; + } else { + die "Cannot find \"$texfile\[.tex\]\".\n"; + } +} else { + $texfile = $Qtexfile; +} + +# Main +&get_xrefs($texfile); + +if ($opt_aux) { + &find_auxfiles($TEXFILENAME); + print "Found AUX files: ", @aux, "\n" if $VERBOSE; + + unshift (@aux, $TEXFILENAME) unless $AUXSEEN{$TEXFILENAME . '.aux'}; + foreach (@aux) { + &parse_auxfile($_); + } +} + +#print "labels:\n", join(' ', @labels), "\n"; + +if ($opt_sort) { + @keys = ($opt_sortby =~ /label/) ? + (sort keys %label_def) : + ($opt_sortby =~ /def/) ? + (sort {$label_def{$a} cmp $label_def{$b} }keys %label_def) : + @labels; +} +else { + @keys = keys %label_def; +} +foreach (@keys) { + $lab = $_; + if ($opt_match) { + next unless $lab =~ m%$opt_match%; + } + if ($label_ref{$lab}) { + print "$lab\t($label_def{$lab}): ", join(', ',@{$label_ref{$lab}}),"\n" unless $opt_unref; +# print "$lab\t($label_def{$lab}): @{$label_ref{$lab}}\n" unless $opt_unref; + } + else { + print "$lab\t($label_def{$lab}): UNREF\n"; + } +} + + +exit; + +######################################################################## +# Parse the TeX file looking for \label and \ref. Build the +# hashes %label_def and %label_ref to hold the definitions and +# references. + +sub get_xrefs { + local($texfile) = @_; + local($in_preamble,$p,$lineno); + local(*TEXFILE); + + open (TEXFILE, $texfile) || die "Can't read $texfile.\n"; + + $lineno=0; + while (<TEXFILE>) { + chop; + $lineno++; + s/%.*//; # decomment + last if /\\endinput/; # are we done? + + if (/\\begin\s*\{document\s*\}/) { + $in_preamble = 0; + } + next if $in_preamble; + + if (m#\\label\{([^}]+)\}#) { + next if $1 =~ m/\#\d/; # avoid tex command defs + push(@labels, $1) unless $seen{'LABEL' . $1}++; + $label_def{$1} = "$texfile $lineno"; + } + + # parse different kinds of references, store info in $label{$key} + while (m#\\[a-z]*ref\{([^}]+)\}#g) { + $ref = $1; + next if $ref =~ m/\#\d/; # avoid tex command defs + push @{ $label_ref{$1} }, "$texfile $lineno"; + } + + # multiple refs: \refs{fig:one,fig:two} --> $1 + while (m#\\[a-z]*refs\{([^}]+)\}#g) { + @refs = split(',',$1); + foreach $ref (@refs) { + next if $ref =~ m/\#\d/; # avoid tex command defs + push @{ $label_ref{$ref} }, "$texfile $lineno"; + } + } + + # range refs: \figrange{fig:one}{fig:two} --> $1 $2 + while (m#\\[a-z]*range\{([^}]+)\}\{([^}]+)\}#g) { + @refs = ($1, $2); + foreach $ref (@refs) { + next if $ref =~/#\d/; # avoid tex command defs + push @{ $label_ref{$ref} }, "$texfile $lineno"; + } + } + + # Search recursively in included files + if (m#\\(input|include)\b\{?([/\w\d.]+)#) { + $p = $2; + $p .= '.tex' unless $p =~ /\.tex$/; + if ($opt_expand) { + $fullname = &find_on_path($ENV{"$TEXINPUTS"}, $p, 'tex'); + if ($fullname ne "" && -r $fullname) { + $p = $fullname; + } + } + if (-r $p) { + print STDERR "Recursing into $p\n" if $VERBOSE; + &get_xrefs($p); + } + } + } + + close (TEXFILE); +} + +######################################################################## +# Parse a TeX .aux file looking for \newlabel. Append the label number +# and page location to the %label_def entry. + +sub parse_auxfile { + my ($texfilename) = shift; + local ($auxfile) = &auxfile($texfilename, "aux"); + local ($rest, $curfile); + if (-r $auxfile) { + print STDERR "Reading $auxfile ..." if $VERBOSE; + open (AUXFILE, $auxfile); + while (<AUXFILE>) { + chop; + + if (/\\newlabel\{([^{}]+)\}/) { + local ($label, $number, $page, $def); + $label = $1; + $rest = $'; + $rest =~ s/[{}]/ /g; + ($number, $page) = split(' ', $rest); + $def = $label_def{$label} . " #$number P$page"; + $label_def{$label} = $def; + } + } + close (AUXFILE); + print STDERR "done\n" if $VERBOSE; + } +} + +######################################################################## +# Cleanup the TeX filename. Add the extension ".tex" if it doesn't +# already have an extension. +# +sub cleanup_texfilename { + local($texfile) = @_; + local($path,$base,$ext) = &splitfn($texfile,".tex"); + + $ext = "tex" if ($ext eq ""); + $path = "" if $path eq './'; + $path . $base . "." . $ext; +} + +######################################################################## +# This helpful little routine locates a file on a TeX path. The path can +# be ":" or ";" delimited. If the file is found, it's fully qualified +# name is returned, otherwise the null string is returned. If the +# input path contains "/" or "\" then either it is returned (if the file +# specified exists) or the empty string is returned, the path _is not_ +# searched. +# +sub find_on_path { + local($path, $file, $type) = @_; + local($dir, $filename); + + $filename = ""; + + if ($KPSEWHICH && -x $KPSEWHICH) { + chop($filename = `$KPSEWHICH $type $file`); + #print "kpse: $filename\n"; + $filename = "" if $filename =~ /not found/; + } + + unless ($filename) { + if ($file =~ /\/|\\/) { + $filename = $file if -e $file; + } else { + foreach $dir (split(/;|:/,$path)) { + #print "looking for $file in $dir\n"; + $dir =~ s/\\/\//g; + $filename = $dir . "/" . $file; + last if -e $filename; + $filename = ""; + } + } + } + $filename; +} + +######################################################################## +# Break a filename into it's path, basename, and extension components. +# The path returned always ends with a slash. "./" is returned if the +# file has no path. If the filename passed in does not exist, the +# default extension passed in is tried (actually, is assumed to be +# correct). +# +sub splitfn { + local ($filename, $defext) = @_; + local ($path, $basename, $ext) = ("", "", ""); + + $filename =~ tr/\\/\//; # translate \ into / + + $filename = $filename . $defext if ! -r $filename; + + if ($filename =~ /\//) { + ($path = $filename) =~ s/\/[^\/]*$//; + ($basename = $filename) =~ s/.*\///; + } + else { + $path = "."; + $basename = $filename; + } + + if ($basename =~ /\./) { + ($ext = $basename) =~ s/.*\.//; + $basename =~ s/\.[^.]*$//; + } + + ($path . "/",$basename,$ext); +} + +sub find_auxfiles { + my ($texfilename) = shift; + # look for new aux files... + local ($curfile); + local ($logfile) = &auxfile($texfilename, "log"); + + if (-r $logfile) { + print STDERR "Reading $logfile ..." if $VERBOSE; + open (LOGFILE, $logfile); + while (<LOGFILE>) { + chop; + while (/\(([^\s]+\.aux)\)/g) { + $curfile = $1; + push (@aux, $curfile) unless $AUXSEEN{$curfile}++; + } + } + close (LOGFILE); + print STDERR "done\n" if $VERBOSE; + } +} + +######################################################################## +# Input: an extension, `ext' +# Output: the filename $TEXFILENAME . `.ext' +# Note: auxilliary files are always placed in the current directory, +# the path is ignored. +# +sub auxfile { + local($texfilename, $ext) = @_; + local($dot)=''; + $dot = "." if $ext ne "" && $ext !~ /^\./; + return ($texfilename =~ /$dot$ext/) ? + $texfilename : + $texfilename . $dot . $ext; +} + + +######################################################################## +# +sub usage { + + print <<"EOF"; +Find LaTex cross references, Version: $VERSION, $Author +Usage: $progname <options> texfile[.tex] + where <options> may be abbreviated to unique truncations, and are: + -aux|noaux do (dont) find & read .aux file(s) for label #, page + -help print this measly help + -match=regexp regexp to select labels printed + -out=filename send output to a file + -sort|nosort do (dont) sort the labels + -sortby=label if sorting, sort by the label string + =def by label def string + -unref print only unreferenced labels + -verbose lots of messages +EOF + + exit 1; +} +__END__ + +=head1 NAME + +texref - Find cross-references for a LaTeX file + +=head1 SYNOPSIS + +B<texref> +[B<-(no)aux>] +[B<-help>] +[B<-match> I<regexp>] +[B<-out> I<filename>] +[B<-(no)sort>] +[B<-sortby label|def|input>] +[B<-unref>] +[B<-verbose>] +I<file>[.tex] + +=head1 DESCRIPTION + +B<texref> reads a .tex file, and (recursively) all \input{} and +\include{} files referenced therein, collecting the names of all +\labels and \*ref{}s as it goes. It then prints the list of labels +together with information about where those labels are referenced +in the .tex file(s). + +References to labels are recognized as commands of the form + + \[a-z]*ref{key} + +This allows for custom LaTeX referencing commands, such as + + \newcommand{figref}[1]{Figure~\ref{#1}} + +as well as the varioref package, which uses the \vref{key} command. +In addition, the program recognizes lists of references, encoded +as commands of the form, + + \[a-z]*refs{key1,key2,key3} + +which expand to something like 'Figure 1, Figure 2, and Figure 3'. +These could be provided by the LaTeX commands + + \newcommand{\figrefs}[1]{\dorefs{#1}{Figures}} + \newcommand{\tabrefs}[1]{\dorefs{#1}{Tables}} + \newcommand{\exrefs}[1]{\dorefs{#1}{Examples}} + \makeatletter + \newcommand{\dorefs}[2]{% + \let\@dummy\@empty + #2~% + \@for\@term:=#1\do{% + \@dummy + \edef\@dummy{\ref{\@term}, }}% + \expandafter\format@last\@dummy} + \def\format@last#1, {and #1} + \makeatother + +Finally, the program recognizes reference ranges, like \figrange{key1}{key3} +which expand to 'Figure 1--3', from commands like + + \newcommand{\figrange}[2]{Figures~\ref{#1}--\ref{#2}} + \newcommand{\tabrange}[2]{Tables~\ref{#1}--\ref{#2}} + + +Labels are described by the filename and line number where they +are defined; if the B<-aux> option is in effect, the corresponding +I<.aux> files are also read (\newlabel{} lines) to obtain the label +number and the page location in the document, assuming the file +has been processed by LaTeX. + + +=head1 OPTIONS AND ARGUMENTS + +All options may be abbreviated to their unique truncations, so B<-h>, B<-he>, +B<-hel> all print help. +Options which take an argument may be followed by a blank or '='. +Those values may need to be quoted if they contain characters interpreted +by your shell. + +=over 4 + +=item B<-aux> | B<-noaux> + +If the B<-aux> option is in effect, the .log file is read to find +the I<.aux> files corresponding to the .tex file. Then, each .aux +file is read (looking for \newlabel{} 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 B<-aux> (unless +changed in the configuration section). + +=item B<-help> + +Print a brief help message and exit. + +=item B<-match>S< >I<rexexp> + +Print only the labels which match the I<rexexp>. If you use systematic +labels (e.g., fig:name for figures, sec:name for sections, etc.) +B<-match> 'fig:' will select only figure labels, etc. Use a pipe to grep to +select more finely (e.g., to find figure labels in Chapter 4). + +=item B<-out>S< >I<filename> + +Send the output to a named file rather than to STDOUT. + +=item B<-sort> | B<-nosort> + +Sort (or do not sort) the labels in the output. If sorting, the sort +order can be set by the B<-sortby> option. If not sorting, the +order in the output is apparently haphazard (the order of perl keys +for a hash). + +=item B<-sortby>S< >[label|def|input] + +If sorting, B<-sortby>=label means that the output is sorted by the +label string. B<-sortby>=def means that the output is sorted by +the label definition string, which normally looks line + + filename linenumber labelnum pagenum + +B<-sortby>=input (the default) simply lists the labels in the order +encountered in the input file(s). This order is easiest to use +for resolving unreferenced labels. + +=item B<-unref> + +If specified, only labels for which no corresponding \*ref references +have been found are printed. + +=item B<-verbose> + +Lots of messages, written to STDERR. + +=back 4 + +=head1 EXAMPLES + +To show the output format, the following command uses all defaults: + + % 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 + ... + +To print only unrefereced labels: + + % texref -unr drew + eq:pij (drew.tex 212 #1 P2): UNREF + +=head1 LIMITATIONS + +The program is tuned to LaTeX, not TeX. + +It does not handle references to subfigures, as provided by the +subfigure and subfigmat packages. + +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? + +The output format is inflexible. + +=head1 BUGS + +Sorting by def sorts the label definitions as strings, so 'myfile 1020' +appears before 'myfile 723', which appears before 'myfile 9'. + + + +=head1 SEE ALSO + +ftp://cmssun1.pd.infn.it/pub/MLO/texref.tar.gz + +texdepend: CTAN support/texdepend + +texfind: CTAN support/texfind + +=head1 AUTHOR + +Michael Friendly <friendly@yorku.ca> + +=head1 LICENSE + +B<texref> 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. diff --git a/support/texref/texref.1 b/support/texref/texref.1 new file mode 100644 index 0000000000..1e3c16cd92 --- /dev/null +++ b/support/texref/texref.1 @@ -0,0 +1,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" + |