--- a/man/xemacs/programs.texi	Mon Aug 13 09:00:04 2007 +0200
+++ b/man/xemacs/programs.texi	Mon Aug 13 09:02:59 2007 +0200
@@ -1004,10 +1004,10 @@
 @end smallexample
 
 @node Tags, Fortran, Change Log, Programs
-@section Tag Tables
-@cindex tag table
+@section Tags Tables
+@cindex tags table
 
-  A @dfn{tag table} is a description of how a multi-file program is
+  A @dfn{tags table} is a description of how a multi-file program is
 broken up into files.  It lists the names of the component files and the
 names and positions of the functions in each file.  Grouping the related
 files makes it possible to search or replace through all the files with
@@ -1015,87 +1015,276 @@
 possible to use the @kbd{Meta-.} command, which finds the definition of a
 function without asking for information on the file it is in.
 
-  Tag tables are stored in files called @dfn{tag table files}.  The
-conventional name for a tag table file is @file{TAGS}.
+  tags tables are stored in files called @dfn{tags table files}.  The
+conventional name for a tags table file is @file{TAGS}.
 
-  Each entry in the tag table records the name of one tag, the name of the
+  Each entry in the tags table records the name of one tag, the name of the
 file that the tag is defined in (implicitly), and the position in that file
 of the tag's definition.
 
    The programming language of a file determines what names are recorded
-in the tag table depends on.  Normally, Emacs includes all functions and
+in the tags table depends on.  Normally, Emacs includes all functions and
 subroutines, and may also include global variables, data types, and
 anything else convenient.  Each recorded name is called a @dfn{tag}.
 
 @menu
-* Tag Syntax::
-* Create Tag Table::
-* Select Tag Table::
-* Find Tag::
-* Tags Search::
-* Tags Stepping::
-* List Tags::
+* Tag Syntax::		Tag syntax for various types of code and text files.  
+* Create Tags Table::	Creating a tags table with @code{etags}.
+* Select Tags Table::	How to visit a tags table.
+* Find Tag::		Commands to find the definition of a specific tag. 
+* Tags Search::		Using a tags table for searching and replacing.
+* List Tags::		Listing and finding tags defined in a file.
 @end menu
 
-@node Tag Syntax, Create Tag Table, Tags, Tags
+@node Tag Syntax, Create Tags Table, Tags, Tags
 @subsection Source File Tag Syntax
 
-  In Lisp code, any function defined with @code{defun}, any variable
-defined with @code{defvar} or @code{defconst}, and the first argument of
-any expression that starts with @samp{(def} in column zero, is a tag.
+@itemize @bullet
+@item
+In Lisp code, any function defined with @code{defun}, any variable
+defined with @code{defvar} or @code{defconst}, and in general the first
+argument of any expression that starts with @samp{(def} in column zero, is
+a tag.
+
+@item
+In Scheme code, tags include anything defined with @code{def} or with a
+construct whose name starts with @samp{def}.  They also include variables
+set with @code{set!} at top level in the file.
 
-  In C code, any C function is a tag, and so is any typedef if @code{-t} is
-specified when the tag table is constructed.
+@item
+In C code, any C function or typedef is a tag, and so are definitions of
+@code{struct}, @code{union} and @code{enum}.  @code{#define} macro
+definitions and @code{enum} constant are also tags, unless
+@samp{--no-defines} is specified when the tags table is constructed,
+which sometimes makes the tags file much smaller.  In C++ code, member
+functions are also recognized.
+
+@item
+In Yacc or Bison input files, each rule defines as a tag the
+nonterminal it constructs.  The portions of the file that contain C code
+are parsed as C code.
+
+@item
+In Fortran code, functions and subroutines are tags.
+
+@item
+In Pascal code, the tags are the functions and procedures defined in
+the file.
+
+@item
+In Perl code, the tags are the procedures defined by the @code{sub}
+keyword.
 
-  In Fortran code, functions and subroutines are tags.
+@item
+In Prolog code, a tag name appears at the left margin.
+
+@item
+In Erlang code, the tags are the functions, records, and macros defined
+in the file.
+
+@item
+In assembler code, labels appearing at the beginning of a line,
+followed by a colon, are tags.
+
+@item
+In La@TeX{} text, the argument of any of the commands @code{\chapter},
+@code{\section}, @code{\subsection}, @code{\subsubsection},
+@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
+@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
+tag.@refill
 
-  In La@TeX{} text, the argument of any of the commands @code{\chapter},
-@code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno},
-@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, and
-@*@code{\typeout} is a tag.@refill
+Other commands can make tags as well, if you specify them in the
+environment variable @code{TEXTAGS} before invoking @code{etags}.  The
+value of this environment variable should be a colon-separated list of
+commands names.  For example,
+
+@example
+TEXTAGS="def:newcommand:newenvironment"
+export TEXTAGS
+@end example
 
-@node Create Tag Table, Select Tag Table, Tag Syntax, Tags
-@subsection Creating Tag Tables
+@noindent
+specifies (using Bourne shell syntax) that the commands @samp{\def},
+@samp{\newcommand} and @samp{\newenvironment} also define tags.
+
+@item
+You can also generate tags based on regexp matching
+(@pxref{Create Tags Table}) for any text file.
+@end itemize
+
+@node Create Tags Table, Select Tags Table, Tag Syntax, Tags
+@subsection Creating Tags Tables
 @cindex etags program
 
-  The @code{etags} program is used to create a tag table file.  It knows
-the syntax of C, Fortran, La@TeX{}, Scheme, and Emacs Lisp/Common Lisp.  To
-use @code{etags}, use it as a shell command:
+  The @code{etags} program is used to create a tags table file.  It knows
+the syntax of several languages, as described in
+@iftex
+the previous section.
+@end iftex
+@ifinfo
+@ref{Tag Syntax}.
+@end ifinfo
+Here is how to run @code{etags}:
 
 @example
 etags @var{inputfiles}@dots{}
 @end example
+
 @noindent
-
-The program reads the specified files and writes a tag table
+The @code{etags} program reads the specified files, and writes a tags table
 named @file{TAGS} in the current working directory.  @code{etags}
-recognizes the language used in an input file based on the name and
-contents of the file; there are no switches for specifying the language.
-The @code{-t} switch tells @code{etags} to record typedefs in C code as
-tags.
+recognizes the language used in an input file based on its file name and
+contents.  You can specify the language with the
+@samp{--language=@var{name}} option, described below.
+
+  If the tags table data become outdated due to changes in the files
+described in the table, the way to update the tags table is the same way it
+was made in the first place.  It is not necessary to do this often.
+
+  If the tags table fails to record a tag, or records it for the wrong
+file, then Emacs cannot possibly find its definition.  However, if the
+position recorded in the tags table becomes a little bit wrong (due to
+some editing in the file that the tag definition is in), the only
+consequence is a slight delay in finding the tag.  Even if the stored
+position is very wrong, Emacs will still find the tag, but it must
+search the entire file for it.
+
+  So you should update a tags table when you define new tags that you want
+to have listed, or when you move tag definitions from one file to another,
+or when changes become substantial.  Normally there is no need to update
+the tags table after each edit, or even every day.
+
+  One tags table can effectively include another.  Specify the included
+tags file name with the @samp{--include=@var{file}} option when creating
+the file that is to include it.  The latter file then acts as if it
+contained all the files specified in the included file, as well as the
+files it directly contains.
+
+  If you specify the source files with relative file names when you run
+@code{etags}, the tags file will contain file names relative to the
+directory where the tags file was initially written.  This way, you can
+move an entire directory tree containing both the tags file and the
+source files, and the tags file will still refer correctly to the source
+files.
 
-  If the tag table data become outdated due to changes in the files
-described in the table, you can update the tag table by running the
-program from the shell again.  It is not necessary to do this often.
+  If you specify absolute file names as arguments to @code{etags}, then
+the tags file will contain absolute file names.  This way, the tags file
+will still refer to the same files even if you move it, as long as the
+source files remain in the same place.  Absolute file names start with
+@samp{/}, or with @samp{@var{device}:/} on MS-DOS and Windows.
+
+  When you want to make a tags table from a great number of files, you
+may have problems listing them on the command line, because some systems
+have a limit on its length.  The simplest way to circumvent this limit
+is to tell @code{etags} to read the file names from its standard input,
+by typing a dash in place of the file names, like this:
+
+@example
+find . -name "*.[chCH]" -print | etags -
+@end example
+
+  Use the option @samp{--language=@var{name}} to specify the language
+explicitly.  You can intermix these options with file names; each one
+applies to the file names that follow it.  Specify
+@samp{--language=auto} to tell @code{etags} to resume guessing the
+language from the file names and file contents.  Specify
+@samp{--language=none} to turn off language-specific processing
+entirely; then @code{etags} recognizes tags by regexp matching alone.
+@samp{etags --help} prints the list of the languages @code{etags} knows,
+and the file name rules for guessing the language.
+
+  The @samp{--regex} option provides a general way of recognizing tags
+based on regexp matching.  You can freely intermix it with file names.
+Each @samp{--regex} option adds to the preceding ones, and applies only
+to the following files.  The syntax is:
+
+@example
+--regex=/@var{tagregexp}[/@var{nameregexp}]/
+@end example
 
-  If the tag table fails to record a tag, or records it for the wrong file,
-Emacs cannot find its definition.  However, if the position
-recorded in the tag table becomes a little bit wrong (due to some editing
-in the file that the tag definition is in), the only consequence is to slow
-down finding the tag slightly.  Even if the stored position is very wrong,
-Emacs will still find the tag, but it must search the entire file for it.
+@noindent
+where @var{tagregexp} is used to match the lines to tag.  It is always
+anchored, that is, it behaves as if preceded by @samp{^}.  If you want
+to account for indentation, just match any initial number of blanks by
+beginning your regular expression with @samp{[ \t]*}.  In the regular
+expressions, @samp{\} quotes the next character, and @samp{\t} stands
+for the tab character.  Note that @code{etags} does not handle the
+other C escape sequences for special characters.
+
+  You should not match more characters with @var{tagregexp} than that
+needed to recognize what you want to tag.  If the match is such that
+more characters than needed are unavoidably matched by @var{tagregexp},
+you may find useful to add a @var{nameregexp}, in order to narrow the
+tag scope.  You can find some examples below.
+
+  The @samp{-R} option deletes all the regexps defined with
+@samp{--regex} options.  It applies to the file names following it, as
+you can see from the following example:
+
+@example
+etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
+    bar.ber -R --lang=lisp los.er
+@end example
+
+@noindent
+Here @code{etags} chooses the parsing language for @file{voo.doo} and
+@file{bar.ber} according to their contents.  @code{etags} also uses
+@var{reg1} to recognize additional tags in @file{voo.doo}, and both
+@var{reg1} and @var{reg2} to recognize additional tags in
+@file{bar.ber}.  @code{etags} uses the Lisp tags rules, and no regexp
+matching, to recognize tags in @file{los.er}.
+
+  Here are some more examples.  The regexps are quoted to protect them
+from shell interpretation.
+
+@noindent
+Tag the @code{DEFVAR} macros in the emacs source files:
 
-   You should update a tag table when you define new tags you want
-to have listed, when you move tag definitions from one file to another,
-or when changes become substantial.  You don't have to update
-the tag table after each edit, or even every day.
+@example
+--regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+@end example
+
+@noindent
+Tag VHDL files (this example is a single long line, broken here for
+formatting reasons):
+
+@example
+--language=none
+--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
+--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+@end example
+
+@noindent
+Tag Cobol files (every label starting in column seven):
 
-@node Select Tag Table, Find Tag, Create Tag Table, Tags
-@subsection Selecting a Tag Table
+@example
+--language=none --regex='/.......[a-zA-Z0-9-]+\./'
+@end example
+
+@noindent
+Tag Postscript files (every label starting in column one):
+
+@example
+--language=none --regex='#/[^ \t@{]+#/'
+@end example
+
+@noindent
+Tag TCL files (this last example shows the usage of a @var{nameregexp}):
+
+@example
+--lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
+@end example
+
+  For a list of the other available @code{etags} options, execute
+@code{etags --help}.
+
+@node Select Tags Table, Find Tag, Create Tags Table, Tags
+@subsection Selecting a Tags Table
 
 @vindex tag-table-alist
-   At any time Emacs has one @dfn{selected} tag table, and all the commands
-for working with tag tables use the selected one.  To select a tag table,
+   At any time Emacs has one @dfn{selected} tags table, and all the commands
+for working with tags tables use the selected one.  To select a tags table,
 use the variable @code{tag-table-alist}.
 
 The value of @code{tag-table-alist} is a list that determines which
@@ -1129,7 +1318,7 @@
 	  ))
 @end example
 
-The example defines the tag table alist in the following way:
+The example defines the tags table alist in the following way:
  
 @itemize @bullet
 @item
@@ -1173,17 +1362,17 @@
 file created with the @code{etags} program.  A directory name is also
 acceptable; it means the file @file{TAGS} in that directory.  The
 function only stores the file name you provide in the variable
-@code{tags-file-name}.  Emacs does not actually read in the tag table
+@code{tags-file-name}.  Emacs does not actually read in the tags table
 contents until you try to use them.  You can set the variable explicitly
 instead of using @code{visit-tags-table}.  The value of the variable
 @code{tags-file-name} is the name of the tags table used by all buffers.
 This is for backward compatibility, and is largely supplanted by the
 variable @code{tag-table-alist}.
  
-@node Find Tag, Tags Search, Select Tag Table, Tags
+@node Find Tag, Tags Search, Select Tags Table, Tags
 @subsection Finding a Tag
 
-  The most important thing that a tag table enables you to do is to find
+  The most important thing that a tags table enables you to do is to find
 the definition of a specific tag.
 
 @table @kbd
@@ -1199,8 +1388,8 @@
 @kindex M-.
 @findex find-tag
   @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
-a specified tag.  It searches through the tag table for that tag, as a
-string, then uses the tag table information to determine the file in
+a specified tag.  It searches through the tags table for that tag, as a
+string, then uses the tags table information to determine the file in
 which the definition is used and the approximate character position of
 the definition in the file.  Then @code{find-tag} visits the file,
 moves point to the approximate character position, and starts searching
@@ -1214,7 +1403,7 @@
   The argument to @code{find-tag} need not be the whole tag name; it can
 be a substring of a tag name.  However, there can be many tag names
 containing the substring you specify.  Since @code{find-tag} works by
-searching the text of the tag table, it finds the first tag in the table
+searching the text of the tags table, it finds the first tag in the table
 that the specified substring appears in.  To find other tags that match
 the substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
 M-.}.  This does not read a tag name, but continues searching the tag
@@ -1257,83 +1446,93 @@
 .}@: invokes the function @code{find-tag-other-window}.  (This key sequence
 ends with a period.)
 
-  Emacs comes with a tag table file @file{TAGS} (in the directory
+  Emacs comes with a tags table file @file{TAGS} (in the directory
 containing Lisp libraries) that includes all the Lisp libraries and all
 the C sources of Emacs.  By specifying this file with @code{visit-tags-table}
 and then using @kbd{M-.}@: you can quickly look at the source of any Emacs
 function.
 
-@node Tags Search, Tags Stepping, Find Tag, Tags
-@subsection Searching and Replacing with Tag Tables
+@node Tags Search, List Tags, Find Tag, Tags
+@subsection Searching and Replacing with Tags Tables
 
   The commands in this section visit and search all the files listed in the
-selected tag table, one by one.  For these commands, the tag table serves
+selected tags table, one by one.  For these commands, the tags table serves
 only to specify a sequence of files to search.  A related command is
 @kbd{M-x grep} (@pxref{Compilation}).
 
 @table @kbd
-@item M-x tags-search
-Search for the specified regexp through the files in the selected tag
+@item M-x tags-search @key{RET} @var{regexp} @key{RET}
+Search for @var{regexp} through the files in the selected tags
 table.
-@item M-x tags-query-replace
-Perform a @code{query-replace} on each file in the selected tag table.
+@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
+Perform a @code{query-replace-regexp} on each file in the selected tags table.
 @item M-,
 Restart one of the commands above, from the current location of point
 (@code{tags-loop-continue}).
 @end table
 
 @findex tags-search
-  @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits
-the files of the selected tag table one by one, and searches through each
-file for that regexp.  It displays the name of the file being searched so
-you can follow its progress.  As soon as an occurrence is found,
+  @kbd{M-x tags-search} reads a regexp using the minibuffer, then
+searches for matches in all the files in the selected tags table, one
+file at a time.  It displays the name of the file being searched so you
+can follow its progress.  As soon as it finds an occurrence,
 @code{tags-search} returns.
 
 @kindex M-,
 @findex tags-loop-continue
- After you have found one match, you probably want to find all the rest.
-To find one more match, type @kbd{M-,} (@code{tags-loop-continue}) to
-resume the @code{tags-search}.  This searches the rest of the current
-buffer, followed by the remaining files of the tag table.
+  Having found one match, you probably want to find all the rest.  To find
+one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
+@code{tags-search}.  This searches the rest of the current buffer, followed
+by the remaining files of the tags table.@refill
 
 @findex tags-query-replace
-  @kbd{M-x tags-query-replace} performs a single @code{query-replace}
-through all the files in the tag table.  It reads a string to search for
-and a string to replace with, just like ordinary @kbd{M-x query-replace}.
-It searches much like @kbd{M-x tags-search} but repeatedly, processing
-matches according to your input.  @xref{Replace}, for more information on
-@code{query-replace}.@refill
+  @kbd{M-x tags-query-replace} performs a single
+@code{query-replace-regexp} through all the files in the tags table.  It
+reads a regexp to search for and a string to replace with, just like
+ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
+tags-search}, but repeatedly, processing matches according to your
+input.  @xref{Replace}, for more information on query replace.
+
+  It is possible to get through all the files in the tags table with a
+single invocation of @kbd{M-x tags-query-replace}.  But often it is
+useful to exit temporarily, which you can do with any input event that
+has no special query replace meaning.  You can resume the query replace
+subsequently by typing @kbd{M-,}; this command resumes the last tags
+search or replace command that you did.
 
-  It is possible to get through all the files in the tag table with a
-single invocation of @kbd{M-x tags-query-replace}.  But since any
-unrecognized character causes the command to exit, you may need to continue
-from where you left off.  You can use @kbd{M-,} to do this.  It resumes
-the last tags search or replace command that you did.
+  The commands in this section carry out much broader searches than the
+@code{find-tag} family.  The @code{find-tag} commands search only for
+definitions of tags that match your substring or regexp.  The commands
+@code{tags-search} and @code{tags-query-replace} find every occurrence
+of the regexp, as ordinary search commands and replace commands do in
+the current buffer.
 
-  It may have struck you that @code{tags-search} is a lot like @code{grep}.
-You can also run @code{grep} itself as an inferior of Emacs and have Emacs
-show you the matching lines one by one.  This works mostly the same as
-running a compilation and having Emacs show you where the errors were.
+  These commands create buffers only temporarily for the files that they
+have to search (those which are not already visited in Emacs buffers).
+Buffers in which no match is found are quickly killed; the others
+continue to exist.
+
+  It may have struck you that @code{tags-search} is a lot like
+@code{grep}.  You can also run @code{grep} itself as an inferior of
+Emacs and have Emacs show you the matching lines one by one.  This works
+much like running a compilation; finding the source locations of the
+@code{grep} matches works like finding the compilation errors.
 @xref{Compilation}.
 
-@node Tags Stepping, List Tags, Tags Search, Tags
-@subsection Stepping Through a Tag Table
-@findex next-file
-
-  If you wish to process all the files in a selected tag table, but
+  If you wish to process all the files in a selected tags table, but
 @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} are not giving
 you the desired result, you can use @kbd{M-x next-file}.
 
 @table @kbd
 @item C-u M-x next-file
 With a numeric argument, regardless of its value, visit the first
-file in the tag table and prepare to advance sequentially by files.
+file in the tags table and prepare to advance sequentially by files.
 @item M-x next-file
-Visit the next file in the selected tag table.
+Visit the next file in the selected tags table.
 @end table
 
-@node List Tags,, Tags Stepping, Tags
-@subsection Tag Table Inquiries
+@node List Tags,, Tags Search, Tags
+@subsection Tags Table Inquiries
 
 @table @kbd
 @item M-x list-tags
@@ -1344,17 +1543,17 @@
 
 @findex list-tags
   @kbd{M-x list-tags} reads the name of one of the files described by the
-selected tag table, and displays a list of all the tags defined in that
+selected tags table, and displays a list of all the tags defined in that
 file.  The ``file name'' argument is really just a string to compare
-against the names recorded in the tag table; it is read as a string rather
+against the names recorded in the tags table; it is read as a string rather
 than a file name.  Therefore, completion and defaulting are not
 available, and you must enter the string the same way it appears in the tag
 table.  Do not include a directory as part of the file name unless the file
-name recorded in the tag table contains that directory.
+name recorded in the tags table contains that directory.
 
 @findex tags-apropos
   @kbd{M-x tags-apropos} is like @code{apropos} for tags.  It reads a regexp,
-then finds all the tags in the selected tag table whose entries match that
+then finds all the tags in the selected tags table whose entries match that
 regexp, and displays the tag names found.
 
 @node Fortran, Asm Mode, Tags, Programs