+File: xemacs.info, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs
+
+Change Logs
+===========
+
+ The Emacs command `M-x add-change-log-entry' helps you keep a record
+of when and why you have changed a program. It assumes that you have a
+file in which you write a chronological sequence of entries describing
+individual changes. The default is to store the change entries in a
+file called `ChangeLog' in the same directory as the file you are
+editing. The same `ChangeLog' file therefore records changes for all
+the files in a directory.
+
+ A change log entry starts with a header line that contains your name
+and the current date. Except for these header lines, every line in the
+change log starts with a tab. One entry can describe several changes;
+each change starts with a line starting with a tab and a star. `M-x
+add-change-log-entry' visits the change log file and creates a new entry
+unless the most recent entry is for today's date and your name. In
+either case, it adds a new line to start the description of another
+change just after the header line of the entry. When `M-x
+add-change-log-entry' is finished, all is prepared for you to edit in
+the description of what you changed and how. You must then save the
+change log file yourself.
+
+ The change log file is always visited in Indented Text mode, which
+means that <LFD> and auto-filling indent each new line like the previous
+line. This is convenient for entering the contents of an entry, which
+must be indented. *Note Text Mode::.
+
+ Here is an example of the formatting conventions used in the change
+log for Emacs:
+
+ Wed Jun 26 19:29:32 1985 Richard M. Stallman (rms at mit-prep)
+
+ * xdisp.c (try_window_id):
+ If C-k is done at end of next-to-last line,
+ this fn updates window_end_vpos and cannot leave
+ window_end_pos nonnegative (it is zero, in fact).
+ If display is preempted before lines are output,
+ this is inconsistent. Fix by setting
+ blank_end_of_window to nonzero.
+
+ Tue Jun 25 05:25:33 1985 Richard M. Stallman (rms at mit-prep)
+
+ * cmds.c (Fnewline):
+ Call the auto fill hook if appropriate.
+
+ * xdisp.c (try_window_id):
+ If point is found by compute_motion after xp, record that
+ permanently. If display_text_line sets point position wrong
+ (case where line is killed, point is at eob and that line is
+ not displayed), set it again in final compute_motion.
+
+\1f
+File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs
+
+Tags Tables
+===========
+
+ A "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 (or other named subunits) 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 possible the `M-.' command which finds the
+definition of a function by looking up which of the files it is in.
+
+ Tags tables are stored in files called "tags table files". The
+conventional name for a tags table file is `TAGS'.
+
+ 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.
+
+ Just what names from the described files are recorded in the tags
+table depends on the programming language of the described file. They
+normally include all functions and subroutines, and may also include
+global variables, data types, and anything else convenient. Each name
+recorded is called a "tag".
+
+ The Ebrowse is a separate facility tailored for C++, with tags and a
+class browser. *Note : (ebrowse).
+
+* Menu:
+
+* Tag Syntax:: Tag syntax for various types of code and text files.
+* Create Tags Table:: Creating a tags table with `etags'.
+* Etags Regexps:: Create arbitrary tags using regular expressions.
+* 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.
+
+\1f
+File: xemacs.info, Node: Tag Syntax, Next: Create Tags Table, Up: Tags
+
+Source File Tag Syntax
+----------------------
+
+ Here is how tag syntax is defined for the most popular languages:
+
+ * In C code, any C function or typedef is a tag, and so are
+ definitions of `struct', `union' and `enum'. You can tag function
+ declarations and external variables in addition to function
+ definitions by giving the `--declarations' option to `etags'.
+ `#define' macro definitions and `enum' constants are also tags,
+ unless you specify `--no-defines' when making the tags table.
+ Similarly, global variables are tags, unless you specify
+ `--no-globals'. Use of `--no-globals' and `--no-defines' can make
+ the tags table file much smaller.
+
+ * In C++ code, in addition to all the tag constructs of C code,
+ member functions are also recognized, and optionally member
+ variables if you use the `--members' option. Tags for variables
+ and functions in classes are named `CLASS::VARIABLE' and
+ `CLASS::FUNCTION'. `operator' functions tags are named, for
+ example `operator+'.
+
+ * In Java code, tags include all the constructs recognized in C++,
+ plus the `interface', `extends' and `implements' constructs. Tags
+ for variables and functions in classes are named `CLASS.VARIABLE'
+ and `CLASS.FUNCTION'.
+
+ * In LaTeX text, the argument of any of the commands `\chapter',
+ `\section', `\subsection', `\subsubsection', `\eqno', `\label',
+ `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or
+ `\index', is a tag.
+
+ Other commands can make tags as well, if you specify them in the
+ environment variable `TEXTAGS' before invoking `etags'. The value
+ of this environment variable should be a colon-separated list of
+ command names. For example,
+
+ TEXTAGS="def:newcommand:newenvironment"
+ export TEXTAGS
+
+ specifies (using Bourne shell syntax) that the commands `\def',
+ `\newcommand' and `\newenvironment' also define tags.
+
+ * In Lisp code, any function defined with `defun', any variable
+ defined with `defvar' or `defconst', and in general the first
+ argument of any expression that starts with `(def' in column zero,
+ is a tag.
+
+ * In Scheme code, tags include anything defined with `def' or with a
+ construct whose name starts with `def'. They also include
+ variables set with `set!' at top level in the file.
+
+ Several other languages are also supported:
+
+ * In Ada code, functions, procedures, packages, tasks, and types are
+ tags. Use the `--packages-only' option to create tags for
+ packages only.
+
+ With Ada, it is possible to have the same name used for different
+ entity kinds (e.g. the same name for a procedure and a function).
+ Also, for things like packages, procedures and functions, there is
+ the spec (i.e. the interface) and the body (i.e. the
+ implementation). To facilitate the choice to the user, a tag
+ value is appended with a qualifier:
+
+ function
+ `/f'
+
+ procedure
+ `/p'
+
+ package spec
+ `/s'
+
+ package body
+ `/b'
+
+ type
+ `/t'
+
+ task
+ `/k'
+
+ So, as an example, `M-x find-tag bidule/b' will go directly to the
+ body of the package BIDULE while `M-x find-tag bidule' will just
+ search for any tag BIDULE.
+
+ * In assembler code, labels appearing at the beginning of a line,
+ followed by a colon, are tags.
+
+ * In Bison or Yacc 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.
+
+ * In Cobol code, tags are paragraph names; that is, any word
+ starting in column 8 and followed by a period.
+
+ * In Erlang code, the tags are the functions, records, and macros
+ defined in the file.
+
+ * In Fortran code, functions, subroutines and blockdata are tags.
+
+ * In makefiles, targets are tags.
+
+ * In Objective C code, tags include Objective C definitions for
+ classes, class categories, methods, and protocols.
+
+ * In Pascal code, the tags are the functions and procedures defined
+ in the file.
+
+ * In Perl code, the tags are the procedures defined by the `sub',
+ `my' and `local' keywords. Use `--globals' if you want to tag
+ global variables.
+
+ * In PostScript code, the tags are the functions.
+
+ * In Prolog code, a tag name appears at the left margin.
+
+ * In Python code, `def' or `class' at the beginning of a line
+ generate a tag.
+
+ You can also generate tags based on regexp matching (*note Etags
+Regexps::) to handle other formats and languages.
+
+\1f
+File: xemacs.info, Node: Create Tags Table, Next: Etags Regexps, Prev: Tag Syntax, Up: Tags
+
+Creating Tags Tables
+--------------------
+
+ The `etags' program is used to create a tags table file. It knows
+the syntax of several languages, as described in *Note Tag Syntax::.
+Here is how to run `etags':
+
+ etags INPUTFILES...
+
+The `etags' program reads the specified files, and writes a tags table
+named `TAGS' in the current working directory. You can intermix
+compressed and plain text source file names. `etags' knows about the
+most common compression formats, and does the right thing. So you can
+compress all your source files and have `etags' look for compressed
+versions of its file name arguments, if it does not find uncompressed
+versions. Under MS-DOS, `etags' also looks for file names like
+`mycode.cgz' if it is given `mycode.c' on the command line and
+`mycode.c' does not exist.
+
+ `etags' recognizes the language used in an input file based on its
+file name and contents. You can specify the language with the
+`--language=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 `--include=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
+`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 `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
+`/', or with `DEVICE:/' on MS-DOS and MS-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 `etags' to read the file names from its standard input, by
+typing a dash in place of the file names, like this:
+
+ find . -name "*.[chCH]" -print | etags -
+
+ Use the option `--language=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 `--language=auto' to tell
+`etags' to resume guessing the language from the file names and file
+contents. Specify `--language=none' to turn off language-specific
+processing entirely; then `etags' recognizes tags by regexp matching
+alone (*note Etags Regexps::).
+
+ `etags --help' prints the list of the languages `etags' knows, and
+the file name rules for guessing the language. It also prints a list of
+all the available `etags' options, together with a short explanation.
+
+\1f
+File: xemacs.info, Node: Etags Regexps, Next: Select Tags Table, Prev: Create Tags Table, Up: Tags
+
+Etags Regexps
+-------------
+
+ The `--regex' option provides a general way of recognizing tags
+based on regexp matching. You can freely intermix it with file names.
+Each `--regex' option adds to the preceding ones, and applies only to
+the following files. The syntax is:
+
+ --regex=/TAGREGEXP[/NAMEREGEXP]/
+
+where TAGREGEXP is used to match the lines to tag. It is always
+anchored, that is, it behaves as if preceded by `^'. If you want to
+account for indentation, just match any initial number of blanks by
+beginning your regular expression with `[ \t]*'. In the regular
+expressions, `\' quotes the next character, and `\t' stands for the tab
+character. Note that `etags' does not handle the other C escape
+sequences for special characters.
+
+ The syntax of regular expressions in `etags' is the same as in
+Emacs, augmented with the "interval operator", which works as in `grep'
+and `ed'. The syntax of an interval operator is `\{M,N\}', and its
+meaning is to match the preceding expression at least M times and up to
+N times.
+
+ You should not match more characters with 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 TAGREGEXP (as will
+usually be the case), you should add a NAMEREGEXP, to pick out just the
+tag. This will enable Emacs to find tags more accurately and to do
+completion on tag names more reliably. You can find some examples
+below.
+
+ The option `--ignore-case-regex' (or `-c') is like `--regex', except
+that the regular expression provided will be matched without regard to
+case, which is appropriate for various programming languages.
+
+ The `-R' option deletes all the regexps defined with `--regex'
+options. It applies to the file names following it, as you can see
+from the following example:
+
+ etags --regex=/REG1/ voo.doo --regex=/REG2/ \
+ bar.ber -R --lang=lisp los.er
+
+Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
+according to their contents. `etags' also uses REG1 to recognize
+additional tags in `voo.doo', and both REG1 and REG2 to recognize
+additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no
+regexp matching, to recognize tags in `los.er'.
+
+ A regular expression can be bound to a given language, by prepending
+it with `{lang}'. When you do this, `etags' will use the regular
+expression only for files of that language. `etags --help' prints the
+list of languages recognised by `etags'. The following example tags
+the `DEFVAR' macros in the Emacs source files. `etags' applies this
+regular expression to C files only:
+
+ --regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
+
+This feature is particularly useful when storing a list of regular
+expressions in a file. The following option syntax instructs `etags'
+to read two files of regular expressions. The regular expressions
+contained in the second file are matched without regard to case.
+
+ --regex=@first-file --ignore-case-regex=@second-file
+
+A regex file contains one regular expressions per line. Empty lines,
+and lines beginning with space or tab are ignored. When the first
+character in a line is `@', `etags' assumes that the rest of the line
+is the name of a file of regular expressions. This means that such
+files can be nested. All the other lines are taken to be regular
+expressions. For example, one can create a file called `emacs.tags'
+with the following contents (the first line in the file is a comment):
+
+ -- This is for GNU Emacs source files
+ {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+
+and then use it like this:
+
+ etags --regex=@emacs.tags *.[ch] */*.[ch]
+
+ Here are some more examples. The regexps are quoted to protect them
+from shell interpretation.
+
+ * Tag Octave files:
+
+ etags --language=none \
+ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+ --regex='/###key \(.*\)/\1/' \
+ --regex='/[ \t]*global[ \t].*/' \
+ *.m
+
+ 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.
+
+ * Tag Tcl files:
+
+ etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+
+ * Tag VHDL files:
+
+ --language=none \
+ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+
+\1f
+File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
+
+Selecting a Tags Table
+----------------------
+
+ At any time Emacs has one "selected" tags table, and all the commands
+for working with tags tables use the selected one. To select a tags
+table, use the variable `tag-table-alist'.
+
+ The value of `tag-table-alist' is a list that determines which
+`TAGS' files should be active for a given buffer. This is not really
+an association list, in that all elements are checked. The car of each
+element of this list is a pattern against which the buffers file name
+is compared; if it matches, then the cdr of the list should be the name
+of the tags table to use. If more than one element of this list
+matches the buffers file name, all of the associated tags tables are
+used. Earlier ones are searched first.
+
+ If the car of elements of this list are strings, they are treated as
+regular-expressions against which the file is compared (like the
+`auto-mode-alist'). If they are not strings, they are evaluated. If
+they evaluate to non-`nil', the current buffer is considered to match.
+
+ If the cdr of the elements of this list are strings, they are
+assumed to name a tags file. If they name a directory, the string
+`tags' is appended to them to get the file name. If they are not
+strings, they are evaluated and must return an appropriate string.
+
+ For example:
+
+ (setq tag-table-alist
+ '(("/usr/src/public/perl/" . "/usr/src/public/perl/perl-3.0/")
+ ("\\.el$" . "/usr/local/emacs/src/")
+ ("/jbw/gnu/" . "/usr15/degree/stud/jbw/gnu/")
+ ("" . "/usr/local/emacs/src/")
+ ))
+
+ The example defines the tags table alist in the following way:
+
+ * Anything in the directory `/usr/src/public/perl/' should use the
+ `TAGS' file `/usr/src/public/perl/perl-3.0/TAGS'.
+
+ * Files ending in `.el' should use the `TAGS' file
+ `/usr/local/emacs/src/TAGS'.
+
+ * Anything in or below the directory `/jbw/gnu/' should use the
+ `TAGS' file `/usr15/degree/stud/jbw/gnu/TAGS'.
+
+ If you had a file called `/usr/jbw/foo.el', it would use both `TAGS'
+files,
+`/usr/local/emacs/src/TAGS' and `/usr15/degree/stud/jbw/gnu/TAGS' (in
+that order), because it matches both patterns.
+
+ If the buffer-local variable `buffer-tag-table' is set, it names a
+tags table that is searched before all others when `find-tag' is
+executed from this buffer.
+
+ If there is a file called `TAGS' in the same directory as the file
+in question, then that tags file will always be used as well (after the
+`buffer-tag-table' but before the tables specified by this list).
+
+ If the variable `tags-file-name' is set, the `TAGS' file it names
+will apply to all buffers (for backwards compatibility.) It is searched
+first.
+
+ If the value of the variable `tags-always-build-completion-table' is
+`t', the tags file will always be added to the completion table without
+asking first, regardless of the size of the tags file.
+
+ The function `M-x visit-tags-table', is largely made obsolete by the
+variable `tag-table-alist', tells tags commands to use the tags table
+file FILE first. The FILE should be the name of a file created with
+the `etags' program. A directory name is also acceptable; it means the
+file `TAGS' in that directory. The function only stores the file name
+you provide in the variable `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 `visit-tags-table'. The value
+of the variable `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 `tag-table-alist'.
+
+\1f
+File: xemacs.info, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags
+
+Finding a Tag
+-------------
+
+ The most important thing that a tags table enables you to do is to
+find the definition of a specific tag.
+
+`M-. TAG &OPTIONAL OTHER-WINDOW'
+ Find first definition of TAG (`find-tag').
+
+`C-u M-.'
+ Find next alternate definition of last tag specified.
+
+`C-x 4 . TAG'
+ Find first definition of TAG, but display it in another window
+ (`find-tag-other-window').
+
+ `M-.' (`find-tag') is the command to find the definition of 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 `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.
+
+ If an empty argument is given (by typing <RET>), the sexp in the
+buffer before or around point is used as the name of the tag to find.
+*Note Lists::, for information on sexps.
+
+ The argument to `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 `find-tag' works by
+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 `find-tag' a numeric argument, as in `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 <META> key, `M-0 M-.' is an easier
+alternative to `C-u M-.'.
+
+ If the optional second argument OTHER-WINDOW is non-`nil', it uses
+another window to display the tag. Multiple active tags tables and
+completion are supported.
+
+ Variables of note include the following:
+
+`tag-table-alist'
+ Controls which tables apply to which buffers.
+
+`tags-file-name'
+ Stores a default tags table.
+
+`tags-build-completion-table'
+ Controls completion behavior.
+
+`buffer-tag-table'
+ Specifies a buffer-local table.
+
+`make-tags-files-invisible'
+ Sets whether tags tables should be very hidden.
+
+`tag-mark-stack-max'
+ Specifies how many tags-based hops to remember.
+
+ Like most commands that can switch buffers, `find-tag' has another
+similar command that displays the new buffer in another window. `C-x 4
+.' invokes the function `find-tag-other-window'. (This key sequence
+ends with a period.)
+
+ Emacs comes with a tags table 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 `visit-tags-table'
+and then using `M-.' you can quickly look at the source of any Emacs
+function.
+
+\1f
projects / chise / xemacs-chise.git- / blobdiff