Commit | Line | Data |
---|---|---|
1f19bad0 AM |
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 |