Sky Schulz Wednesday, December 7, 1988
------------------------------------------------------------------------------


BRIEF Tag Version 2.00


Summary

This is the 'tags' macro facility I currently use with BRIEF 2.1.

It is composed of a set of BRIEF macros and a MS/PC-DOS executable.
The executable program is used to generate a 'tags' file which is
used by the macros to provide symbol-tagging on 'C' language source
files, much like the same feature available in VI. Only better!

The symbols which are made available for tagging are:

o '#define' macros and manifest constants

o Function definitions

o Typedef definitions

o Structure definitions

o Union definitions

o Enum definitions and enum constant definitions


The features that make this implementation of tags 'better' than
VI's are:

o Multiple symbols are supported -- VI requires that
identical symbols be removed from the tags file

o BRIEF's regular expressions may be used to specify symbols

o Menu selection of multiple symbols

o N-level 'tag undo' stack


Installation

To install this tag facility within your BRIEF 2.1 (or later) macro
package:

1) Copy the files 'tag.m', 'tag.cm' to your BRIEF macro
directory.

2) Add these statement to your BRIEF initials startup macro:

(autoload "tag.cm" "tag" "tag_key" "undo_tag"
"save_tag_undo"
"write_tag_stack")

2.a) If you wish to assign these macros to keys, then add the
following statements to your BRIEF initials startup macro:

(assign_to_key "" "tag_key")
(assign_to_key "" "tag_key")
(assign_to_key "" "undo_tag")

3) Run the program, CTAGS, on your source files to generate
the 'tags' file with a set of commands similiar to these:

A> cd \project
A> ctags src/*.c lib/*.c

* Note that by specifying the file names as relative to the
project directory the tag macro will load the file as
relative to the project directory. This is most useful in
projects with two or more directories of source involved.

* Note, also, that the tag macro expects the name of the tags
file itself to be 'tags'.

4) Add this line to your AUTOEXEC.BAT file:

set BTAGPATH=c:\project

Where 'c:\project' is the path to your current projects
directory. It is assumed that any directories containing the
projects source will be found within this directory.

This specifies where the tags macro can find your 'tags'
file, and where the source files can be found, relative to
the 'tags' file.

Note: The tags macro will look for a 'tags' file first in
your current directory, then in the single directory
specified with the environment variable 'BTAGPATH'.


Description

The program, ctags, generates a tag file by reading the input source
file(s) and performing *very* simple lexical analysis to detect
function definitions, macro (#define) definitions, typedef, struct,
union, and enum definitions.

The resulting tags file is composed of lines with the function
or macro name, the file-name, and a BRIEF RE which should match
to that function or macro. Each element must seperated by a
single tab character.


Example

Generating a tags file

Below is an example tag file generated with this command:

C> ctags ctags.c

Contents of resulting file, tags (note, leading tabs are for *this*
text file only):

LINT_ARGS ctags.c <#[\t ]@define[\t ]+LINT_ARGS
SEEK_SET ctags.c <#[\t ]@define[\t ]+SEEK_SET
main ctags.c find_functions ctags.c gettoken ctags.c print_defn_line ctags.c
Options to the tags file generator

Several command-line options may be specified to the CTAGS
program. These control what type(s) of symbols are searched
for, the name of the output file (the default is 'tags'), and
whether to append the resulting output to the tags file.

Under normal operation, the CTAGS program will 'update' the
tags file by deleting lines from the tags file that corrspond
to any of the files specified on the command-line. This can
take some time for it must read each line of the original
tags file to find any matching lines.

If the 'append' option (-a) is used, the 'update' operation
is not performed. Use this option only when you are adding
new files to the tags file; otherwise, many symbols will have
duplicate entries in the tags file. This doesn't cause a
problem, but can be confusing, especially if the regular-
expression pattern used to match the definition line changes
from the old, first matching entry and the new, next
matching entry(ies).


Usage: ctags [-avdtsue] [-?|h] [-f tagsfile] [-] file ...

-aAppend to tags file
-vGenerate VI compatible tagsfile
-dDisable tag generation for '#define' symbols
-t " " " " 'typedef' symbols
-s " " " " 'struct' symbols
-u " " " " 'union' symbols
-e " " " " 'enum' symbols
-?|hDisplay this usage information
-f tagsfile Specifiy alternate tags file (default is 'tags')
-Terminate command-line option processing

Using the BRIEF macros

If you have used the default key assignments, then, place your cursor
over, or in front of a symbol (function-name, or #defined) you would
like to tag on and press .

The tag macro looks in the tag file for that symbol, if it is found
it attempts to open the tagged file, and then searches for the symbol
within that file.

Any errors in searching the tags file, loading the tagged file, or
searching for the symbol within the tagged file will be reported.

Alternatively, you may press and type 'tag ' and press
. Replace with the actual symbol you would like to
tag on.

With the alternate method you may also use BRIEF's RE characters in
the symbol name given to the tag macro. Any matches found in the
tags file will be presented in a menu.

Additional features of the BRIEF macros

Pressing and typing 'tag' alone, without the symbol, will
return your cursor to the last tag location.

Pressing will 'undo' the last tag and return you to your point
of origin before you tagged on a symbol. The tag stack has unlimited
depth, up to the largest file size BRIEF can handle.

The 'undo' stack is kept in a buffer which you may write out to a
file by using the macro (write_tag_stack). This can be useful for
generating call-trace diagrams. The tag stack can also be
pasted into the current buffer using the macro
(paste_tag_stack).


Possible Improvements

Support for assembly files: PROCs, STRUCTs, and MACROs.


File Listing

ctags.exe- MSC 5.1 compiled tag gen. (linked with SETARGV.OBJ)
tag.m- BRIEF 2.1 macro language source of tag facility
tags- Demonstration tags file using ctags.c


------------------------------------------------------------------------------