\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 (-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}