xemacs-beta: man/xemacs/programs.texi comparison

comparison man/xemacs/programs.texi @ 70:131b0175ea99 r20-0b30

Import from CVS: tag r20-0b30

author	cvs
date	Mon, 13 Aug 2007 09:02:59 +0200
parents	376386a54a3c
children	43dd3413c7c7

comparison

equal deleted inserted replaced

-:804d1389bcd6
+:131b0175ea99
 (case where line is killed, point is at eob and that line is
 not displayed), set it again in final compute_motion.
 @end smallexample
 @node Tags, Fortran, Change Log, Programs
-@section Tag Tables
+@section Tags Tables
-@cindex tag table
+@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
 one command.  Recording the function names and positions makes it
 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
+tags tables are stored in files called @dfn{tags table files}.  The
-conventional name for a tag table file is @file{TAGS}.
+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::
+* Tag Syntax::		Tag syntax for various types of code and text files.
-* Create Tag Table::
+* Create Tags Table::	Creating a tags table with @code{etags}.
-* Select Tag Table::
+* Select Tags Table::	How to visit a tags table.
-* Find Tag::
+* Find Tag::		Commands to find the definition of a specific tag.
-* Tags Search::
+* Tags Search::		Using a tags table for searching and replacing.
-* Tags Stepping::
+* List Tags::		Listing and finding tags defined in a file.
-* List Tags::
 @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
+@itemize @bullet
-defined with @code{defvar} or @code{defconst}, and the first argument of
+@item
-any expression that starts with @samp{(def} in column zero, is a tag.
+In Lisp code, any function defined with @code{defun}, any variable
+defined with @code{defvar} or @code{defconst}, and in general the first
-In C code, any C function is a tag, and so is any typedef if @code{-t} is
+argument of any expression that starts with @samp{(def} in column zero, is
-specified when the tag table is constructed.
+a tag.
-In Fortran code, functions and subroutines are tags.
+@item
+In Scheme code, tags include anything defined with @code{def} or with a
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
+construct whose name starts with @samp{def}.  They also include variables
-@code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno},
+set with @code{set!} at top level in the file.
-@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, and
-@*@code{\typeout} is a tag.@refill
+@item
+In C code, any C function or typedef is a tag, and so are definitions of
-@node Create Tag Table, Select Tag Table, Tag Syntax, Tags
+@code{struct}, @code{union} and @code{enum}.  @code{#define} macro
-@subsection Creating Tag Tables
+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.
+@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
+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
+@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 @code{etags} program is used to create a tags table file.  It knows
-the syntax of C, Fortran, La@TeX{}, Scheme, and Emacs Lisp/Common Lisp.  To
+the syntax of several languages, as described in
-use @code{etags}, use it as a shell command:
+@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 @code{etags} program reads the specified files, and writes a tags table
-The program reads the specified files and writes a tag table
 named @file{TAGS} in the current working directory.  @code{etags}
-recognizes the language used in an input file based on the name and
+recognizes the language used in an input file based on its file name and
-contents of the file; there are no switches for specifying the language.
+contents.  You can specify the language with the
-The @code{-t} switch tells @code{etags} to record typedefs in C code as
+@samp{--language=@var{name}} option, described below.
-tags.
+If the tags table data become outdated due to changes in the files
-If the tag 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
-described in the table, you can update the tag table by running the
+was made in the first place.  It is not necessary to do this often.
-program from the shell again.  It is not necessary to do this often.
+If the tags table fails to record a tag, or records it for the wrong
-If the tag table fails to record a tag, or records it for the wrong file,
+file, then Emacs cannot possibly find its definition.  However, if the
-Emacs cannot find its definition.  However, if the position
+position recorded in the tags table becomes a little bit wrong (due to
-recorded in the tag table becomes a little bit wrong (due to some editing
+some editing in the file that the tag definition is in), the only
-in the file that the tag definition is in), the only consequence is to slow
+consequence is a slight delay in finding the tag.  Even if the stored
-down finding the tag slightly.  Even if the stored position is very wrong,
+position is very wrong, Emacs will still find the tag, but it must
-Emacs will still find the tag, but it must search the entire file for it.
+search the entire file for it.
-You should update a tag table when you define new tags you want
+So you should update a tags table when you define new tags that you want
-to have listed, when you move tag definitions from one file to another,
+to have listed, or when you move tag definitions from one file to another,
-or when changes become substantial.  You don't have to update
+or when changes become substantial.  Normally there is no need to update
-the tag table after each edit, or even every day.
+the tags table after each edit, or even every day.
-@node Select Tag Table, Find Tag, Create Tag Table, Tags
+One tags table can effectively include another.  Specify the included
-@subsection Selecting a Tag Table
+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 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
+@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:
+@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):
+@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
+At any time Emacs has one @dfn{selected} tags table, and all the commands
-for working with tag tables use the selected one.  To select a tag table,
+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
 @code{TAGS} files should be active for a given buffer.  This is not
 really an association list, in that all elements are checked.  The car
 	  ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
 	  ("" . "/usr/local/emacs/src/")
 	  ))
 @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
 Anything in the directory @file{/usr/src/public/perl/}
 should use the @file{TAGS} file @file{/usr/src/public/perl/perl-3.0/TAGS}.
 the variable @code{tag-table-alist}, tells tags commands to use the tags
 table file @var{file} first.  The @var{file} should be the name of a
 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
 @item M-.@: @var{tag &optional other-window}
 Find first definition of @var{tag} (@code{find-tag}).
 @end table
 @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
+a specified tag.  It searches through the tags table for that tag, as a
-string, then uses the tag table information to determine the file in
+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
 ever-increasing distances away for the text that should appear at
 the beginning of the definition.
 @xref{Lists}, for information on sexps.
 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
 table's text for another tag containing the same substring last used.
 If your keyboard has a real @key{META} key, @kbd{M-0 M-.}@: is an easier
 Like most commands that can switch buffers, @code{find-tag} has another
 similar command that displays the new buffer in another window.  @kbd{C-x 4
 .}@: 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
+@node Tags Search, List Tags, Find Tag, Tags
-@subsection Searching and Replacing with Tag Tables
+@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
+@item M-x tags-search @key{RET} @var{regexp} @key{RET}
-Search for the specified regexp through the files in the selected tag
+Search for @var{regexp} through the files in the selected tags
 table.
-@item M-x tags-query-replace
+@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
-Perform a @code{query-replace} on each file in the selected tag table.
+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
+@kbd{M-x tags-search} reads a regexp using the minibuffer, then
-the files of the selected tag table one by one, and searches through each
+searches for matches in all the files in the selected tags table, one
-file for that regexp.  It displays the name of the file being searched so
+file at a time.  It displays the name of the file being searched so you
-you can follow its progress.  As soon as an occurrence is found,
+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.
+Having found one match, you probably want to find all the rest.  To find
-To find one more match, type @kbd{M-,} (@code{tags-loop-continue}) to
+one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
-resume the @code{tags-search}.  This searches the rest of the current
+@code{tags-search}.  This searches the rest of the current buffer, followed
-buffer, followed by the remaining files of the tag table.
+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}
+@kbd{M-x tags-query-replace} performs a single
-through all the files in the tag table.  It reads a string to search for
+@code{query-replace-regexp} through all the files in the tags table.  It
-and a string to replace with, just like ordinary @kbd{M-x query-replace}.
+reads a regexp to search for and a string to replace with, just like
-It searches much like @kbd{M-x tags-search} but repeatedly, processing
+ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
-matches according to your input.  @xref{Replace}, for more information on
+tags-search}, but repeatedly, processing matches according to your
-@code{query-replace}.@refill
+input.  @xref{Replace}, for more information on query replace.
-It is possible to get through all the files in the tag table with a
+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 since any
+single invocation of @kbd{M-x tags-query-replace}.  But often it is
-unrecognized character causes the command to exit, you may need to continue
+useful to exit temporarily, which you can do with any input event that
-from where you left off.  You can use @kbd{M-,} to do this.  It resumes
+has no special query replace meaning.  You can resume the query replace
-the last tags search or replace command that you did.
+subsequently by typing @kbd{M-,}; this command resumes the last tags
+search or replace command that you did.
-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
+The commands in this section carry out much broader searches than the
-show you the matching lines one by one.  This works mostly the same as
+@code{find-tag} family.  The @code{find-tag} commands search only for
-running a compilation and having Emacs show you where the errors were.
+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.
+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
+If you wish to process all the files in a selected tags table, but
-@subsection Stepping Through a Tag Table
-@findex next-file
-If you wish to process all the files in a selected tag 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
+@node List Tags,, Tags Search, Tags
-@subsection Tag Table Inquiries
+@subsection Tags Table Inquiries
 @table @kbd
 @item M-x list-tags
 Display a list of the tags defined in a specific program file.
 @item M-x tags-apropos
 Display a list of all tags matching a specified regexp.
 @end table
 @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
 @section Fortran Mode
 @cindex Fortran mode

Mercurial > hg > xemacs-beta

comparison man/xemacs/programs.texi @ 70:131b0175ea99 r20-0b30