\begindata{text,538387784}
\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.  If you 
\italic{never} want to enter recursive editing mode, simply add 
\typewriter{\italic{TagRecursiveEdit: no}} to your ~/preferences.



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,538210560}
\enddata{bp,538210560}
\view{bpv,538210560,0,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL 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,538387784}
