home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / elvis184.zip / os2 / ref.doc < prev    next >
Text File  |  1994-01-17  |  5KB  |  133 lines
  1.  
  2.  
  3. NAME
  4.        ref - Display a C function header
  5.  
  6. SYNOPSIS
  7.        ref [-t] [-x] [-c class]... [-f file]... tag
  8.  
  9. DESCRIPTION
  10.        ref quickly locates and displays the header of a function.
  11.        To do this, ref looks in the "tags" file for the line that
  12.        describes the function, and then scans the source file for
  13.        the function.  When it locates the function,  it  displays
  14.        an  introductory comment (if there is one), the function's
  15.        declaration, and the declarations of all arguments.
  16.  
  17. SEARCH METHOD
  18.        ref uses a fairly sophisticated tag look-up algorithm.  If
  19.        you  supply a filename via -f file, then elvis first scans
  20.        the tags file for a  static  tag  from  that  file.   This
  21.        search  is  limited to the tags file in the current direc-
  22.        tory.
  23.  
  24.        If you  supply  a  classname  via  -c  class,  then  elvis
  25.        searches  for  a  tag from that class.  This search is not
  26.        limited to the current directory; You can supply a list of
  27.        directories  in  the environment variable TAGPATH, and ref
  28.        will search through the  "tags"  file  in  each  directory
  29.        until it finds a tag in the desired class.
  30.  
  31.        If  that  fails,  ref will then try to look up an ordinary
  32.        global tag.  This search checks  all  of  the  directories
  33.        listed  in  TAGPATH, too.  If the tag being sought doesn't
  34.        contain any colons, and you haven't given a -x flag,  then
  35.        any  static  tags in a tags file will be treated as global
  36.        tags.
  37.  
  38.        If you've given the -t flag, then ref will  simply  output
  39.        the  tag  line  that it found, and then exit.  Without -t,
  40.        though, ref will search for the tag line.  It will try  to
  41.        open  the  source file, which should be in the same direc-
  42.        tory as the tags file where the tag  was  discovered.   If
  43.        the  source file doesn't exist, or is unreadable, then ref
  44.        will try to open a file called "refs" in  that  directory.
  45.        Either  way,  ref  will try to locate the tag, and display
  46.        whatever it finds.
  47.  
  48. INTERACTION WITH ELVIS
  49.        ref is used by elvis' shift-K command.  If the  cursor  is
  50.        located  on  a  word such as "splat", in the file "foo.c",
  51.        then elvis will invoke ref with the command "ref -f  foo.c
  52.        splat".
  53.  
  54.        If  elvis has been compiled with the -DEXTERNAL_TAGS flag,
  55.        then elvis will use ref to scan the tags files.   This  is
  56.        slower  than  the  built-in  tag  searching, but it allows
  57.  
  58.  
  59.  
  60.                                                                 1
  61.  
  62.  
  63.  
  64.  
  65.  
  66. REF(1)                                                     REF(1)
  67.  
  68.  
  69.        elvis to access the more sophisticated tag lookup provided
  70.        by ref.  Other than that, external tags should act exactly
  71.        like internal tags.
  72.  
  73. OPTIONS
  74.        -t     Output tag info, instead of the function header.
  75.  
  76.        -f file
  77.               The tag might be a static function  in  file.   You
  78.               can  use  several  -f  flags  to  have ref consider
  79.               static tags from more than one file.
  80.  
  81.        -c class
  82.               The tag might be a member of class class.  You  can
  83.               use several -c flags to have ref consider tags from
  84.               more than one class.
  85.  
  86. FILES
  87.        tags   List of function names and their locations,  gener-
  88.               ated by ctags.
  89.  
  90.        refs   Function   headers   extracted  from  source  files
  91.               (optional).
  92.  
  93. ENVIRONMENT
  94.        TAGPATH
  95.               List of directories to be searched.   The  elements
  96.               in the list are separated by either semicolons (for
  97.               MS-DOS, Atari TOS,  and  AmigaDos),  or  by  colons
  98.               (every other operating system).  For each operating
  99.               system, ref has a built-in default which is  proba-
  100.               bly adequate.
  101.  
  102. NOTES
  103.        You  might  want  to  generate a "tags" file the directory
  104.        that contains the source code for standard  C  library  on
  105.        your  system.   If licensing restrictions prevent you from
  106.        making the library source readable by everybody, then  you
  107.        can  have  ctags  generate  a "refs" file, and make "refs"
  108.        readable by everybody.
  109.  
  110.        If your system doesn't come with the library source  code,
  111.        then  perhaps  you can produce something workable from the
  112.        lint libraries.
  113.  
  114. SEE ALSO
  115.        elvis(1), ctags(1)
  116.  
  117. AUTHOR
  118.        Steve Kirkendall
  119.        kirkenda@cs.pdx.edu
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.                                                                 2
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.