[Emacs-diffs] Changes to etags.1

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/09/06 03:52:43

Index: etags.1
===================================================================
RCS file: etags.1
diff -N etags.1
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ etags.1     6 Sep 2007 03:52:43 -0000       1.1
@@ -0,0 +1,306 @@
+.\" Copyright (C) 1992, 2001, 2002, 2003, 2004,
+.\"   2005, 2006, 2007  Free Software Foundation, Inc.
+.\" See section COPYING for conditions for redistribution
+.TH etags 1 "23nov2001" "GNU Tools" "GNU Tools"
+.de BP
+.sp
+.ti -.2i
+\(**
+..
+
+.SH NAME
+etags, ctags \- generate tag file for Emacs, vi
+.SH SYNOPSIS
+.hy 0
+.na
+\fBetags\fP [\|\-aCDGIRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|]
+.if n .br
+[\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|]
+[\|\-\-parse\-stdin=\fIfile\fP\|]
+.br
+[\|\-\-append\|] [\|\-\-no\-defines\|]
+[\|\-\-no\-globals\|] [\|\-\-include=\fIfile\fP\|]
+[\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|]
+[\|\-\-no\-members\|] [\|\-\-output=\fItagfile\fP\|]
+[\|\-\-regex=\fIregexp\fP\|] [\|\-\-no\-regex\|]
+[\|\-\-help\|] [\|\-\-version\|]
+\fIfile\fP .\|.\|.
+
+\fBctags\fP [\|\-aCdgIRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|]
+.if n .br
+[\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|]
+[\|\-\-parse\-stdin=\fIfile\fP\|]
+.br
+[\|\-\-append\|] [\|\-\-backward\-search\|]
+[\|\-\-cxref\|] [\|\-\-defines\|] [\|\-\-forward\-search\|]
+[\|\-\-globals\|] [\|\-\-ignore\-indentation\|]
+[\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|]
+[\|\-\-output=\fItagfile\fP\|] [\|\-\-regex=\fIregexp\fP\|]
+[\|\-\-typedefs\|] [\|\-\-typedefs\-and\-c++\|]
+[\|\-\-update\|]
+[\|\-\-help\|] [\|\-\-version\|]
+\fIfile\fP .\|.\|.
+.ad b
+.hy 1
+.SH DESCRIPTION
+The \|\fBetags\fP\| program is used to create a tag table file, in a format
+understood by
+.BR emacs ( 1 )\c
+\&; the \|\fBctags\fP\| program is used to create a similar table in a
+format understood by
+.BR vi ( 1 )\c
+\&.  Both forms of the program understand
+the syntax of C, Objective C, C++, Java, Fortran, Ada, Cobol, Erlang, HTML,
+LaTeX, Emacs Lisp/Common Lisp, Lua, makefile, Pascal, Perl, PHP, Postscript,
+Python, Prolog, Scheme and
+most assembler\-like syntaxes.
+Both forms read the files specified on the command line, and write a tag
+table (defaults: \fBTAGS\fP for \fBetags\fP, \fBtags\fP for
+\fBctags\fP) in the current working directory.
+Files specified with relative file names will be recorded in the tag
+table with file names relative to the directory where the tag table
+resides.  If the tag table is in /dev, however, the file names are made
+relative to the working directory.  Files specified with absolute file
+names will be recorded
+with absolute file names.  Files generated from a source file\-\-like
+a C file generated from a source Cweb file\-\-will be recorded with
+the name of the source file.
+The programs recognize the language used in an input file based on its
+file name and contents.  The \fB\-\-language\fP switch can be used to force
+parsing of the file names following the switch according to the given
+language, overriding guesses based on filename extensions.
+.SH OPTIONS
+Some options make sense only for the \fBvi\fP style tag files produced
+by ctags;
+\fBetags\fP does not recognize them.
+The programs accept unambiguous abbreviations for long option names.
+.TP
+.B \-a, \-\-append
+Append to existing tag file.  (For \fBvi\fP-format tag files, see also
+\fB\-\-update\fP.)
+.TP
+.B \-B, \-\-backward\-search
+Tag files written in the format expected by \fBvi\fP contain regular
+expression search instructions; the \fB\-B\fP option writes them using
+the delimiter `\|\fB?\fP\|', to search \fIbackwards\fP through files.
+The default is to use the delimiter `\|\fB/\fP\|', to search \fIforwards\fP
+through files.
+Only \fBctags\fP accepts this option.
+.TP
+.B \-\-declarations
+In C and derived languages, create tags for function declarations,
+and create tags for extern variables unless \-\-no\-globals is used.
+.TP
+.B \-d, \-\-defines
+Create tag entries for C preprocessor constant definitions
+and enum constants, too.  Since this is the default behavior of
+\fBetags\fP, only \fBctags\fP accepts this option.
+.TP
+.B \-D, \-\-no\-defines
+Do not create tag entries for C preprocessor constant definitions
+and enum constants.
+This may make the tags file much smaller if many header files are tagged.
+Since this is the default behavior of \fBctags\fP, only \fBetags\fP
+accepts this option.
+.TP
+.B \-\-globals
+Create tag entries for global variables in C, C++, Objective C, Java,
+and Perl.
+Since this is the default behavior of \fBetags\fP, only \fBctags\fP
+accepts this option.
+.TP
+.B \-\-no\-globals
+Do not tag global variables.  Typically this reduces the file size by
+one fourth.  Since this is the default behavior of \fBctags\fP, only
+\fBetags\fP accepts this option.
+.TP
+\fB\-i\fP \fIfile\fP, \fB\-\-include=\fIfile\fP
+Include a note in the tag file indicating that, when searching for a
+tag, one should also consult the tags file \fIfile\fP after checking the
+current file.  Only \fBetags\fP accepts this option.
+.TP
+.B \-I, \-\-ignore\-indentation
+Don't rely on indentation as much as we normally do.  Currently, this
+means not to assume that a closing brace in the first column is the
+final brace of a function or structure definition in C and C++.
+.TP
+\fB\-l\fP \fIlanguage\fP, \fB\-\-language=\fIlanguage\fP
+Parse the following files according to the given language.  More than
+one such options may be intermixed with filenames.  Use \fB\-\-help\fP
+to get a list of the available languages and their default filename
+extensions.  The `auto' language can be used to restore automatic
+detection of language based on the file name.  The `none'
+language may be used to disable language parsing altogether; only
+regexp matching is done in this case (see the \fB\-\-regex\fP option).
+.TP
+.B \-\-members
+Create tag entries for variables that are members of structure-like
+constructs in C++, Objective C, Java.  This is the default for etags.
+.TP
+.B \-\-no\-members
+Do not tag member variables.  This is the default for ctags.
+.TP
+.B \-\-packages\-only
+Only tag packages in Ada files.
+.TP
+\fB\-\-parse\-stdin=\fIfile\fP
+May be used (only once) in place of a file name on the command line.
+\fBetags\fP will read from standard input and mark the produced tags
+as belonging to the file \fBFILE\fP.
+.TP
+\fB\-o\fP \fItagfile\fP, \fB\-\-output=\fItagfile\fP
+Explicit name of file for tag table; overrides default \fBTAGS\fP or
+\fBtags\fP.   (But ignored with \fB\-v\fP or \fB\-x\fP.)
+.TP
+\fB\-r\fP \fIregexp\fP, \fB\-\-regex=\fIregexp\fP
+
+Make tags based on regexp matching for the files following this option,
+in addition to the tags made with the standard parsing based on
+language. May be freely intermixed with filenames and the \fB\-R\fP
+option.  The regexps are cumulative, i.e. each such option will add to
+the previous ones.  The regexps are of one of the forms:
+.br
+       
[\fB{\fP\fIlanguage\fP\fB}\fP]\fB/\fP\fItagregexp/\fP[\fInameregexp\fP\fB/\fP]\fImodifiers\fP
+.br
+       address@hidden
+.br
+
+where \fItagregexp\fP is used to match the tag.  It should not match
+useless characters.  If the match is such that more characters than
+needed are unavoidably matched by \fItagregexp\fP, it may be useful to
+add a \fInameregexp\fP, to narrow down the tag scope.  \fBctags\fP
+ignores regexps without a \fInameregexp\fP.  The syntax of regexps is
+the same as in emacs.  The following character escape sequences are
+supported: \\a, \\b, \\d, \\e, \\f, \\n, \\r, \\t, \\v, which
+respectively stand for the ASCII characters BEL, BS, DEL, ESC, FF, NL,
+CR, TAB, VT.
+.br
+The \fImodifiers\fP are a sequence of 0 or more characters among
+\fIi\fP, which means to ignore case when matching; \fIm\fP, which means
+that the \fItagregexp\fP will be matched against the whole file contents
+at once, rather than line by line, and the matching sequence can match
+multiple lines; and \fIs\fP, which implies \fIm\fP and means that the
+dot character in \fItagregexp\fP matches the newline char as well.
+.br
+The separator, which is \fB/\fP in the examples, can be any character
+different from space, tab, braces and address@hidden  If the separator
+character is needed inside the regular expression, it must be quoted
+by preceding it with \fB\\\fP.
+.br
+The optional \fB{\fP\fIlanguage\fP\fB}\fP prefix means that the tag
+should be
+created only for files of language \fIlanguage\fP, and ignored
+otherwise.  This is particularly useful when storing many predefined
+regexps in a file.
+.br
+In its second form, \fIregexfile\fP is the name of a file that contains
+a number of arguments to the \fI\-\-regex\=\fP option,
+one per line.  Lines beginning with a space or tab are assumed
+to be comments, and ignored.
+
+.br
+Here are some examples.  All the regexps are quoted to protect them
+from shell interpretation.
+.br
+
+Tag the DEFVAR macros in the emacs source files:
+.br
+\fI\-\-regex\='/[ \\t]*DEFVAR_[A-Z_ \\t(]+"\\([^"]+\\)"/'\fP
+.\"" This comment is to avoid confusion to Emacs syntax highlighting
+.br
+
+Tag VHDL files (this example is a single long line, broken here for
+formatting reasons):
+.br
+\fI\-\-language\=none\ \-\-regex='/[\ \\t]*\\(ARCHITECTURE\\|\\
+CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex\='/[\ \\t]*\\
+\\(ATTRIBUTE\\|ENTITY\\|FUNCTION\\|PACKAGE\\(\ BODY\\)?\\
+\\|PROCEDURE\\|PROCESS\\|TYPE\\)[\ \\t]+\\([^\ \\t(]+\\)/\\3/'\fP
+.br
+
+Tag TCL files (this last example shows the usage of a \fItagregexp\fP):
+.br
+\fI\-\-lang\=none \-\-regex\='/proc[\ \\t]+\\([^\ \\t]+\\)/\\1/'\fP
+
+.br
+A regexp can be preceded by {\fIlang\fP}, thus restricting it to match
+lines of files of the specified language.  Use \fBetags \-\-help\fP to obtain
+a list of the recognised languages.  This feature is particularly useful inside
+\fBregex files\fP.  A regex file contains one regex per line.  Empty lines,
+and those lines beginning with space or tab are ignored.  Lines beginning
+with @ are references to regex files whose name follows the @ sign.  Other
+lines are considered regular expressions like those following \fB\-\-regex\fP.
+.br
+For example, the command
+.br
+\fIetags address@hidden *.c\fP
+.br
+reads the regexes contained in the file regex.file.
+.TP
+.B \-R, \-\-no\-regex
+Don't do any more regexp matching on the following files.  May be
+freely intermixed with filenames and the \fB\-\-regex\fP option.
+.TP
+.B \-t, \-\-typedefs
+Record typedefs in C code as tags.  Since this is the default behavior
+of \fBetags\fP, only \fBctags\fP accepts this option.
+.TP
+.B \-T, \-\-typedefs\-and\-c++
+Generate tag entries for typedefs, struct, enum, and union tags, and
+C++ member functions.  Since this is the default behavior
+of \fBetags\fP, only \fBctags\fP accepts this option.
+.TP
+.B \-u, \-\-update
+Update tag entries for \fIfiles\fP specified on command line, leaving
+tag entries for other files in place.  Currently, this is implemented
+by deleting the existing entries for the given files and then
+rewriting the new entries at the end of the tags file.  It is often
+faster to simply rebuild the entire tag file than to use this.
+Only \fBctags\fP accepts this option.
+.TP
+.B \-v, \-\-vgrind
+Instead of generating a tag file, write index (in \fBvgrind\fP format)
+to standard output.  Only \fBctags\fP accepts this option.
+.TP
+.B \-x, \-\-cxref
+Instead of generating a tag file, write a cross reference (in
+\fBcxref\fP format) to standard output.  Only \fBctags\fP accepts this option.
+.TP
+.B \-h, \-H, \-\-help
+Print usage information.  Followed by one or more \-\-language=LANG
+prints detailed information about how tags are created for LANG.
+.TP
+.B \-V, \-\-version
+Print the current version of the program (same as the version of the
+emacs \fBetags\fP is shipped with).
+
+.SH "SEE ALSO"
+`\|\fBemacs\fP\|' entry in \fBinfo\fP; \fIGNU Emacs Manual\fP, Richard
+Stallman.
+.br
+.BR cxref ( 1 ),
+.BR emacs ( 1 ),
+.BR vgrind ( 1 ),
+.BR vi ( 1 ).
+
+.SH COPYING
+Copyright
+.if t \(co
+.if n (c)
+1999, 2001, 2002, 2003, 2004, 2005, 2006, 2007  Free Software Foundation, Inc.
+.PP
+Permission is granted to make and distribute verbatim copies of this
+document provided the copyright notice and this permission notice are
+preserved on all copies.
+.PP
+Permission is granted to copy and distribute modified versions of
+this document under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of
+a permission notice identical to this one.
+.PP
+Permission is granted to copy and distribute translations of this
+document into another language, under the above conditions for
+modified versions, except that this permission notice may be stated
+in a translation approved by the Free Software Foundation.
+
+.\" arch-tag: 9534977f-af78-42f0-991d-1df6b6c05573