man/man1/ref.1

   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