\begindata{text,539013432}
\textdsversion{12}
\template{help}
\define{global
}


\chapter{\center{Tags: a tag package for EZ

}}
\section{What tags is

}\leftindent{
Tags is a package for EZ which allows you to quickly find function definitions 
within program source files.  It is similar to the tags library available in 
Emacs. Tags uses the \italic{\helptopic{ctags}} program to generate a 
database, called a tag file, which lists function definitions and the files in 
which the definitions appear.  With this information, the tags package can 
locate the definition of a given function, even if it is not in the current 
file.

}
\section{Starting tags

}\leftindent{
To use tags within ez, include the following lines in your \italic{.ezinit} 
file:


\leftindent{\typewriter{addkey tags-find-tag ^X^T ctextview

addkey tags-goto-tag ^X^G ctextview

addkey tags-load-tag-file ^X^L ctextview

addkey tags-rebuild-tags \\et ctextview}}\example{


}To make the tag commands appear on the menus, add the following lines to your 
.ezinit:


\example{addmenu "tags-find-tag" "Tags,Find Tag~10" ctextview

addmenu "tags-goto-tag" "Tags,Goto Tag~11" ctextview

addmenu "tags-load-tag-file" "Tags,Load New Tag File~20" ctextview

addmenu "tags-rebuild-tags" "Tags,Rebuild Tag File~50" ctextview

}
These lines set up the default keybindings and menu card for the tags package. 
 The keybindings and menu items will only be active when you are editing 
program files with a ".c" or ".h" extension which use the \italic{ctext} 
dataobject.  (See the help file on  \italic{\helptopic{ctext}}  for more 
details.)  You can, of course, assign the tags functions to other key 
sequences if you want.


}\section{Warnings

}\leftindent{
Currently tags only looks in the file "tags" in the current directory to find 
its tag information.  


}\section{Using tags

}\leftindent{
There are two commands you can use to find function definitions:


\bold{Goto Tag} (^X^G) prompts for the name of a function and looks up that 
function in the tag table.  


\bold{Find Tag} (^X^T) interprets the word at the position of the text caret 
as a function name, then looks that name up in the tag table.


In both cases, a buffer will be created to hold the source file in which the 
function is defined, if one does not already exist.  If the tag cannot be 
found, or if the source file cannot be opened, an error message will appear in 
the message line.  Otherwise, the current buffer will switch to the one 
containing the function definition, and the first line of the function will be 
highlighted.


EZ will then enter \italic{recursive editing mode}.  In this mode, you can do 
anything you would otherwise do in EZ.  However, the editor still remembers 
the place from which you started the recursive editing.  When you are finished 
viewing or editing the function definition, press \italic{control-C} (^C) to 
return to your starting point (the point at which you issued the goto-tag or 
find-tag command).


Sometimes you might not want to enter recursive editing mode when you visit a 
tag.  If that is the case, you can give both goto-tag and find-tag an argument 
by typing \italic{control-U} (^U) before the command.  This will prevent the 
command from entering recursive editing mode.


The \bold{Rebuild tags} command (<ESC>-t) rebuilds the file which tags uses to 
look up function definitions.  You should use this command whenever the source 
files which you want to cross-reference have changed.  This command will run 
the  \italic{ctags}  program, cross-referencing the function definitions of 
all files in the current directory that have a .c or .h extension.  The result 
will be placed in the file "tags".


If you want to include files other than those in the current directory, or 
files without a .c or .h  extension, you must change the arguments that 
rebuild-tags gives to the ctags program.  To change these arguments, give the 
rebuild-tags command an argument by typing \italic{control-U} (^U) before the 
command.  You will then be prompted in the message line for a new command to 
use.  See the help file on \italic{\helptopic{ctags}} for an explanation of 
the arguments.


The \bold{Load New Tag File} command lets you load in a different tag file for 
the tags package to use.  Normally tags looks for a file in the current 
directory named "tags"; with this command you can explicitly tell tags to use 
a different file or a file in another directory.  This is especially useful if 
you are editing two programs in different directories with different tag 
files.  The load-tag-file command uses the filename completion facility (as do 
commands like visit-file).


}\section{Program Author}


\leftindent{Curt Galloway}

\leftindent{
}\section{Related tools}  


Select (highlight) one of the italicized names, put the cursor in the box, and 
choose "Show Help on Selected Word" from the pop-up menu to see the help file 
for:

\leftindent{
\italic{\helptopic{ez}

\helptopic{ctext}

\helptopic{ctags}}

}

\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,830,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: This software is part of version 6.1 of the 

Andrew User Interface System and is 

the property of IBM, Carnegie Mellon University, 

and the other copyright holders.  The source 

code of this version is for the sole use of 

the individual named in ./config/allsys.h.  

This source code is not to be redistributed.  

Binary object code compiled or derived from 

these sources is not to be distributed to non-

members.  Members may have additional 

distribution rights granted by prior written 

permission of Carnegie Mellon University.



IBM, CARNEGIE MELLON UNIVERSITY, 

AND THE OTHER COPYRIGHT HOLDERS

 DISCLAIM ALL WARRANTIES WITH 

REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANT-

ABILITY AND FITNESS. IN 

NO EVENT SHALL  IBM, CARNEGIE 

MELLON UNIVERSITY, OR ANY OTHER 

COPYRIGHT HOLDER BE LIABLE FOR 

ANY SPECIAL, INDIRECT OR CONSE-

QUENTIAL DAMAGES OR ANY DAMAGES 

WHATSOEVER RESULTING FROM LOSS OF

USE, DATA OR PROFITS, WHETHER IN AN

ACTION OF CONTRACT, NEGLIGENCE OR

OTHER TORTIOUS ACTION, ARISING OUT 

OF OR IN CONNECTION WITH THE USE OR

PERFORMANCE OF THIS SOFTWARE.

 $

}}\enddata{text,539013432}
