Category : Word Processors
Archive   : ELVIB184.ZIP
Filename : REF.DOC

NAME
ref - Display a C function header

SYNOPSIS
ref [-t] [-x] [-c class]... [-f file]... tag

DESCRIPTION
ref quickly locates and displays the header of a function.
To do this, ref looks in the "tags" file for the line that
describes the function, and then scans the source file for
the function. When it locates the function, it displays
an introductory comment (if there is one), the function's
declaration, and the declarations of all arguments.

SEARCH METHOD
ref uses a fairly sophisticated tag look-up algorithm. If
you supply a filename via -f file, then elvis first scans
the tags file for a static tag from that file. This
search is limited to the tags file in the current direc-
tory.

If you supply a classname via -c class, then elvis
searches for a tag from that class. This search is not
limited to the current directory; You can supply a list of
directories in the environment variable TAGPATH, and ref
will search through the "tags" file in each directory
until it finds a tag in the desired class.

If that fails, ref will then try to look up an ordinary
global tag. This search checks all of the directories
listed in TAGPATH, too. If the tag being sought doesn't
contain any colons, and you haven't given a -x flag, then
any static tags in a tags file will be treated as global
tags.

If you've given the -t flag, then ref will simply output
the tag line that it found, and then exit. Without -t,
though, ref will search for the tag line. It will try to
open the source file, which should be in the same direc-
tory as the tags file where the tag was discovered. If
the source file doesn't exist, or is unreadable, then ref
will try to open a file called "refs" in that directory.
Either way, ref will try to locate the tag, and display
whatever it finds.

INTERACTION WITH ELVIS
ref is used by elvis' shift-K command. If the cursor is
located on a word such as "splat", in the file "foo.c",
then elvis will invoke ref with the command "ref -f foo.c
splat".

If elvis has been compiled with the -DEXTERNAL_TAGS flag,
then elvis will use ref to scan the tags files. This is
slower than the built-in tag searching, but it allows



1





REF(1) REF(1)


elvis to access the more sophisticated tag lookup provided
by ref. Other than that, external tags should act exactly
like internal tags.

OPTIONS
-t Output tag info, instead of the function header.

-f file
The tag might be a static function in file. You
can use several -f flags to have ref consider
static tags from more than one file.

-c class
The tag might be a member of class class. You can
use several -c flags to have ref consider tags from
more than one class.

FILES
tags List of function names and their locations, gener-
ated by ctags.

refs Function headers extracted from source files
(optional).

ENVIRONMENT
TAGPATH
List of directories to be searched. The elements
in the list are separated by either semicolons (for
MS-DOS, Atari TOS, and AmigaDos), or by colons
(every other operating system). For each operating
system, ref has a built-in default which is proba-
bly adequate.

NOTES
You might want to generate a "tags" file the directory
that contains the source code for standard C library on
your system. If licensing restrictions prevent you from
making the library source readable by everybody, then you
can have ctags generate a "refs" file, and make "refs"
readable by everybody.

If your system doesn't come with the library source code,
then perhaps you can produce something workable from the
lint libraries.

SEE ALSO
elvis(1), ctags(1)

AUTHOR
Steve Kirkendall
[email protected]






2