| 1 | .TH REF 1
|
|---|
| 2 | .SH NAME
|
|---|
| 3 | ref - Display a C function header
|
|---|
| 4 | .SH SYNOPSIS
|
|---|
| 5 | \fBref\fR [-t] [-c \fIclass\fR]... [-f \fIfile\fR]... \fItag\fR
|
|---|
| 6 | .SH DESCRIPTION
|
|---|
| 7 | \fIref\fP quickly locates and displays the header of a function.
|
|---|
| 8 | To do this, \fIref\fR
|
|---|
| 9 | looks in the "tags" file for the line that describes the function, and then
|
|---|
| 10 | scans the source file for the function.
|
|---|
| 11 | When it locates the function, it displays an introductory comment
|
|---|
| 12 | (if there is one), the function's declaration, and the declarations of all
|
|---|
| 13 | arguments.
|
|---|
| 14 | .SH "SEARCH METHOD"
|
|---|
| 15 | .PP
|
|---|
| 16 | \fIref\fR uses a fairly sophisticated tag look-up algorithm.
|
|---|
| 17 | If you supply a filename via \fB-f\fR \fIfile\fR, then elvis first scans
|
|---|
| 18 | the tags file for a static tag from that file.
|
|---|
| 19 | This search is limited to the tags file in the current directory.
|
|---|
| 20 | .PP
|
|---|
| 21 | If you supply a classname via \fB-c\fR \fIclass\fR, then elvis searches
|
|---|
| 22 | for a tag from that class.
|
|---|
| 23 | This search is not limited to the current directory;
|
|---|
| 24 | You can supply a list of directories in the environment variable \fITAGPATH\fR,
|
|---|
| 25 | and \fIref\fR will search through the "tags" file in each directory until it finds
|
|---|
| 26 | a tag in the desired class.
|
|---|
| 27 | .PP
|
|---|
| 28 | If that fails, \fIref\fR will then try to look up an ordinary global tag.
|
|---|
| 29 | This search checks all of the directories listed in \fITAGPATH\fR, too.
|
|---|
| 30 | .PP
|
|---|
| 31 | If you've given the \fB-t\fR flag, then \fIref\fR will simply output the tag line that
|
|---|
| 32 | it found, and then exit.
|
|---|
| 33 | Without \fB-t\fR, though, \fIref\fR will search for the tag line.
|
|---|
| 34 | It will try to open the source file, which should be in the same directory
|
|---|
| 35 | as the tags file where the tag was discovered.
|
|---|
| 36 | If the source file doesn't exist, or is unreadable, then \fIref\fR will try to open
|
|---|
| 37 | a file called "\fIrefs\fR" in that directory.
|
|---|
| 38 | Either way, \fIref\fR will try to locate the tag, and display whatever it finds.
|
|---|
| 39 | .SH "INTERACTION WITH ELVIS"
|
|---|
| 40 | .PP
|
|---|
| 41 | \fIref\fP is used by \fIelvis\fR' shift-K command.
|
|---|
| 42 | If the cursor is located on a word such as "splat", in the file "foo.c",
|
|---|
| 43 | then \fIelvis\fR will invoke \fIref\fR with the command "ref -f foo.c splat".
|
|---|
| 44 | .PP
|
|---|
| 45 | If \fIelvis\fR has been compiled with the -DEXTERNAL_TAGS flag, then \fIelvis\fR will
|
|---|
| 46 | use \fIref\fR \fB\fRto scan the tags files.
|
|---|
| 47 | This is slower than the built-in tag searching, but it allows \fIelvis\fR to access
|
|---|
| 48 | the more sophisticated tag lookup provided by \fIref\fR.
|
|---|
| 49 | Other than that, external tags should act exactly like internal tags.
|
|---|
| 50 | .SH OPTIONS
|
|---|
| 51 | .IP \fB-t\fR
|
|---|
| 52 | Output tag info, instead of the function header.
|
|---|
| 53 | .IP "\fB-f\fR \fIfile\fR"
|
|---|
| 54 | The tag might be a static function in \fIfile\fR.
|
|---|
| 55 | You can use several -f flags to have \fIref\fR consider static tags from more than one file.
|
|---|
| 56 | .IP "\fB-c\fR \fIclass\fR"
|
|---|
| 57 | The tag might be a member of class \fIclass\fR.
|
|---|
| 58 | You can use several -c flags to have \fIref\fR consider tags from more than one class.
|
|---|
| 59 | .SH FILES
|
|---|
| 60 | .IP \fBtags\fR
|
|---|
| 61 | List of function names and their locations, generated by \fIctags\fR.
|
|---|
| 62 | .IP \fBrefs\fR
|
|---|
| 63 | Function headers extracted from source files (optional).
|
|---|
| 64 | .SH ENVIRONMENT
|
|---|
| 65 | .IP \fBTAGPATH\fR
|
|---|
| 66 | List of directories to be searched.
|
|---|
| 67 | The elements in the list are separated by either
|
|---|
| 68 | semicolons (for MS-DOS, Atari TOS, and AmigaDos), or
|
|---|
| 69 | by colons (every other operating system).
|
|---|
| 70 | For each operating system, \fIref\fR has a built-in default which is probably
|
|---|
| 71 | adequate.
|
|---|
| 72 | .SH NOTES
|
|---|
| 73 | .PP
|
|---|
| 74 | You might want to generate a "tags" file the directory that contains the
|
|---|
| 75 | source code for standard C library on your system.
|
|---|
| 76 | If licensing restrictions prevent you from making the library source readable
|
|---|
| 77 | by everybody, then you can have \fIctags\fR generate a "refs" file,
|
|---|
| 78 | and make "refs" readable by everybody.
|
|---|
| 79 | .PP
|
|---|
| 80 | If your system doesn't come with the library source code, then perhaps you
|
|---|
| 81 | can produce something workable from the \fIlint\fR libraries.
|
|---|
| 82 | .SH "SEE ALSO"
|
|---|
| 83 | elvis(1), ctags(1)
|
|---|
| 84 | .SH AUTHOR
|
|---|
| 85 | .nf
|
|---|
| 86 | Steve Kirkendall
|
|---|
| 87 | kirkenda@cs.pdx.edu
|
|---|
| 88 | .fi
|
|---|
