Last changes for etags (I hope).

3 files changed, 110 insertions, 65 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 0c30b07658a..cea0444e1c8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -387,10 +387,10 @@ sh-script can attempt to "learn" the current buffer's style.
 *** In DOS, etags looks for file.cgz if it cannot find file.c.
 
 *** New option --ignore-case-regex is an alternative to --regex.  It is now
-    possible to bind a regexp to a language, by prepending the regexp with
-    {lang}, where lang is one of the languages that `etags --help' prints
-    out.  This feature is useful especially for regex files, where each
-    line contains a regular expression.  The manual contains details.
+possible to bind a regexp to a language, by prepending the regexp with
+{lang}, where lang is one of the languages that `etags --help' prints out.
+This feature is useful especially for regex files, where each line contains
+a regular expression.  The manual contains details.
 
 *** In C and derived languages, etags creates tags for function
 declarations when given the --declarations option.
@@ -413,7 +413,8 @@ variables are tagged.
 
 *** New language Python: def and class at the beginning of a line are tags.
 
-*** .ss files are Scheme files.
+*** .ss files are Scheme files, .pdb is Postscript with C syntax, .psw is
+for PSWrap.
 
 ** Emacs now attempts to determine the initial language environment
 and preferred and locale coding systems systematically from the
diff --git a/etc/etags.1 b/etc/etags.1
index 20febe24c2f..20d2a10b44f 100644
--- a/etc/etags.1
+++ b/etc/etags.1
@@ -1,6 +1,6 @@
 .\" Copyright (c) 1992 Free Software Foundation
 .\" See section COPYING for conditions for redistribution
-.TH etags 1 "19apr1994" "GNU Tools" "GNU Tools"
+.TH etags 1 "02nov1999" "GNU Tools" "GNU Tools"
 .de BP
 .sp
 .ti -.2i
@@ -12,24 +12,31 @@ etags, ctags \- generate tag file for Emacs, vi
 .SH SYNOPSIS
 .hy 0
 .na
-.B etags [\|\-aCDRSVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|] [\|\-i \fIregexp\fP\|] [\|\-o \fItagfile\fP\|]
-.br
-[\|\-\-c++\|] [\|\-\-no\-defines\|] [\|\-\-ignore\-indentation\|]
-[\|\-\-language=\fIlanguage\fP\|] [\|\-\-regex=\fIregexp\fP\|]
-[\|\-\-no\-regexp\|] [\|\-\-help\|] [\|\-\-version\|]
-[\|\-\-include=\fIfile\fP\|] [\|\-\-output=\fItagfile\fP\|]
-[\|\-\-append\|] \fIfile\fP .\|.\|.
+.B etags [\|\-aCDGImRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|]
+.if n .br
+.B [\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|]
+.br
+[\|\-\-append\|] [\|\-\-c++\|] [\|\-\-no\-defines\|]
+[\|\-\-no\-globals\|] [\|\-\-include=\fIfile\fP\|]
+[\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|]
+[\|\-\-members\|] [\|\-\-output=\fItagfile\fP\|]
+[\|\-\-regex=\fIregexp\fP\|] [\|\-\-no\-regex\|]
+[\|\-\-help\|] [\|\-\-version\|]
+\fIfile\fP .\|.\|.
 
-.B ctags [\|\-aCdRSVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|]
-.br
-[\|\-i \fIregexp\fP\|] [\|\-o \fItagfile\fP\|]
-[\|\-\-c++\|] [\|\-\-defines\|] [\|\-\-ignore\-indentation\|]
-[\|\-\-no\-warn\|] [\|\-\-cxref\|] [\|\-\-backward\-search\|]
-[\|\-\-forward\-search\|] [\|\-\-typedefs\|] [\|\-\-typedefs\-and\-c++\|]
-[\|\-\-language=\fIlanguage\fP\|] [\|\-\-regex=\fIregexp\fP\|]
+.B ctags [\|\-aCdgImRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|]
+.if n .br
+.B [\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|]
+.br
+[\|\-\-append\|] [\|\-\-backward\-search\|] [\|\-\-c++\|]
+[\|\-\-cxref\|] [\|\-\-defines\|] [\|\-\-forward\-search\|]
+[\|\-\-globals\|] [\|\-\-ignore\-indentation\|]
+[\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|]
+[\|\-\-output=\fItagfile\fP\|] [\|\-\-regex=\fIregexp\fP\|]
+[\|\-\-typedefs\|] [\|\-\-typedefs\-and\-c++\|]
+[\|\-\-update\|] [\|\-\-no\-warn\|]
 [\|\-\-help\|] [\|\-\-version\|]
-.br
-[\|\-\-output=\fItagfile\fP\|] [\|\-\-append\|] [\|\-\-update\|] \fIfile\fP .\|.\|.
+\fIfile\fP .\|.\|.
 .ad b
 .hy 1
 .SH DESCRIPTION
@@ -40,8 +47,9 @@ understood by
 format understood by
 .BR vi ( 1 )\c
 \&.  Both forms of the program understand
-the syntax of C, C++, Fortran, Pascal, LaTeX, Scheme,
-Emacs Lisp/Common Lisp, Erlang, Prolog and most assembler\-like syntaxes.
+the syntax of C, Objective C, C++, Java, Fortran, Pascal, Cobol, Ada, Perl,
+LaTeX, Scheme, Emacs Lisp/Common Lisp, Postscript, Erlang, Python, Prolog and
+most assembler\-like syntaxes.
 Both forms read the files specified on the command line, and write a tag
 table (defaults: `\|TAGS\|' for \fBetags\fP, `\|tags\|' for
 \fBctags\fP) in the current working directory.
@@ -76,16 +84,39 @@ Treat files with `\|.c\|' and `\|.h\|' extensions as C++ code, not C
 code.  Files with `\|.C\|', `\|.H\|', `\|.cxx\|', `\|.hxx\|', or
 `\|.cc\|' extensions are always assumed to be C++ code.
 .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 definitions, too.  This is the
-default behavior for \fBetags\fP, so this option is only accepted
-by \fBctags\fP.
+Create tag entries for C preprocessor constant definitions
+and enum constants, too.  This is the
+default behavior for \fBetags\fP.
 .TP
 .B \-D, \-\-no\-defines
-Do not create tag entries for C preprocessor definitions.
+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.
-This is the default behavior for \fBctags\fP, so this option is only
-accepted by \fBetags\fP.
+This is the default behavior for \fBctags\fP.
+.TP
+.B \-g, \-\-globals
+Create tag entries for global variables in C, C++, Objective C, Java,
+and Perl.
+This is the default behavior for \fBetags\fP.
+.TP
+.B \-G, \-\-no\-globals
+Do not tag global variables.  Typically this reduces the file size by
+one fourth.  This is the default behavior for \fBctags\fP.
+.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.  This options is only accepted by \fBetags\fP.
+.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
@@ -96,6 +127,16 @@ detection of language based on filename extension.  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 \-m, \-\-members
+Create tag entries for variables that are members of structure-like
+constructs in C++, Objective C, Java.
+.TP
+.B \-M, \-\-no\-members
+Do not tag member variables.  This is the default behavior.
+.TP
+.B \-\-packages\-only
+Only tag packages in Ada files.
+.TP
 \fB\-o\fP \fItagfile\fP, \fB\-\-output=\fItagfile\fP
 Explicit name of file for tag table; overrides default `\|TAGS\|' or
 `\|tags\|'.   (But ignored with \fB\-v\fP or \fB\-x\fP.)
@@ -116,7 +157,8 @@ 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. 
+\fInameregexp\fP.  The syntax of regexps is the same as in emacs,
+augmented with intervals of the form \\{m,n\\}, as in ed or grep.
 .br
 Here are some examples.  All the regexps are quoted to protect them
 from shell interpretation.
@@ -136,16 +178,6 @@ CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex\='/[\ \\t]*\\
 \\|PROCEDURE\\|PROCESS\\|TYPE\\)[\ \\t]+\\([^\ \\t(]+\\)/\\3/'\fP
 .br
 
-Tag Cobol files:
-.br
-\fI\-\-language\=none \-\-regex\='/.......[a\-zA\-Z0\-9\-]+\\./'\fP
-.br
-
-Tag Postscript files:
-.br
-\fI\-\-language\=none \-\-regex\='#/[^\ \\t{]+#/'\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
@@ -155,11 +187,6 @@ Tag TCL files (this last example shows the usage of a \fItagregexp\fP):
 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 \-S, \-\-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
 .B \-t, \-\-typedefs
 Record typedefs in C code as tags.  Since this is the default behaviour
 of \fBetags\fP, only \fBctags\fP accepts this option.
@@ -190,7 +217,7 @@ allowed with it.
 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, \-\-help
+.B \-h, \-H, \-\-help
 Print usage information.
 .TP
 .B \-V, \-\-version
@@ -207,7 +234,7 @@ Stallman.
 .BR vi ( 1 ).
 
 .SH COPYING
-Copyright (c) 1992 Free Software Foundation, Inc.
+Copyright (c) 1999 Free Software Foundation, Inc.
 .PP
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
diff --git a/man/programs.texi b/man/programs.texi
index 68057d81a25..e2f6badbafc 100644
--- a/man/programs.texi
+++ b/man/programs.texi
@@ -1620,13 +1620,13 @@ recorded is called a @dfn{tag}.
 @item
 In C code, any C function or typedef is a tag, and so are definitions of
 @code{struct}, @code{union} and @code{enum}.  You can tag function
-declarations in addition to function definitions by giving the
-@samp{--declarations} option to @code{etags}.  @code{#define} macro
-definitions and @code{enum} constants are also tags, unless you specify
-@samp{--no-defines} when making the tags table.  Similarly, global
-variables are tags, unless you specify @samp{--no-globals}.  Use of
-@samp{--no-globals} and @samp{--no-defines} can make the tags table file
-much smaller.
+declarations and external variables in addition to function definitions
+by giving the @samp{--declarations} option to @code{etags}.
+@code{#define} macro definitions and @code{enum} constants are also
+tags, unless you specify @samp{--no-defines} when making the tags table.
+Similarly, global variables are tags, unless you specify
+@samp{--no-globals}.  Use of @samp{--no-globals} and @samp{--no-defines}
+can make the tags table file much smaller.
 
 @item
 In C++ code, in addition to all the tag constructs of C code, member
@@ -1680,7 +1680,9 @@ set with @code{set!} at top level in the file.
 @itemize @bullet
 
 @item
-In Ada code, functions, procedures, packages, tasks, and types are tags.
+In Ada code, functions, procedures, packages, tasks, and types are
+tags.  Use the @samp{--packages-only} option to create tags for packages
+only.
 
 @item
 In assembler code, labels appearing at the beginning of a line,
@@ -1720,11 +1722,11 @@ In Postscript code, the tags are the functions.
 
 @item
 In Prolog code, a tag name appears at the left margin.
-@end itemize
 
 @item
 In Python code, @code{def} or @code{class} at the beginning of a line
 generate a tag.
+@end itemize
 
   You can also generate tags based on regexp matching (@pxref{Using
 Regexps}) to handle other formats and languages.
@@ -1930,21 +1932,36 @@ from shell interpretation.
 @itemize @bullet
 
 @item
-Tag VHDL files (this example is a single long line, broken here for
-formatting reasons):
+Tag Octave files:
 
 @smallexample
---language=none
---regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
---regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
-\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+etags --language=none \
+      --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+      --regex='/###key \(.*\)/\1/' \
+      --regex='/[ \t]*global[ \t].*/' \
+      *.m
 @end smallexample
 
+@noindent
+Note that tags are not generated for scripts so that you have to add a
+line by yourself of the form `###key <script-name>' if you want to jump
+to it.
+
 @item
-Tag Tcl files (this last example shows the usage of a @var{nameregexp}):
+Tag Tcl files:
 
 @smallexample
---lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
+etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+@end smallexample
+
+@item
+Tag VHDL files:
+
+@smallexample
+--language=none \
+--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
 @end smallexample
 @end itemize