Sync up with r21-4-14-chise-0_21-22.

[chise/xemacs-chise.git-] / info / xemacs.info-12

This is ../info/xemacs.info, produced by makeinfo version 4.0b from
xemacs/xemacs.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* XEmacs: (xemacs).             XEmacs Editor.
END-INFO-DIR-ENTRY

   This file documents the XEmacs editor.

   Copyright (C) 1985, 1986, 1988 Richard M. Stallman.  Copyright (C)
1991, 1992, 1993, 1994 Lucid, Inc.  Copyright (C) 1993, 1994 Sun
Microsystems, Inc.  Copyright (C) 1995 Amdahl Corporation.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
General Public License" are included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "The GNU Manifesto",
"Distribution" and "GNU General Public License" may be included in a
translation approved by the author instead of in the original English.

\1f
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
File: xemacs.info,  Node: Tags Search,  Next: List Tags,  Prev: Find Tag,  Up: Tags

Searching and Replacing with Tags Tables
----------------------------------------

   The commands in this section visit and search all the files listed
in the 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 `M-x grep' (*note Compilation::).

`M-x tags-search <RET> REGEXP <RET>'
     Search for REGEXP through the files in the selected tags table.

`M-x tags-query-replace <RET> REGEXP <RET> REPLACEMENT <RET>'
     Perform a `query-replace-regexp' on each file in the selected tags
     table.

`M-,'
     Restart one of the commands above, from the current location of
     point (`tags-loop-continue').

   `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, `tags-search'
returns.

   Having found one match, you probably want to find all the rest.  To
find one more match, type `M-,' (`tags-loop-continue') to resume the
`tags-search'.  This searches the rest of the current buffer, followed
by the remaining files of the tags table.

   `M-x tags-query-replace' performs a single `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 `M-x
query-replace-regexp'.  It searches much like `M-x tags-search', but
repeatedly, processing matches according to your input.  *Note
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 `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 `M-,'; this command resumes the last tags search
or replace command that you did.

   The commands in this section carry out much broader searches than the
`find-tag' family.  The `find-tag' commands search only for definitions
of tags that match your substring or regexp.  The commands
`tags-search' and `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 `tags-search' is a lot like `grep'.  You
can also run `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 `grep' matches works
like finding the compilation errors.  *Note Compilation::.

   If you wish to process all the files in a selected tags table, but
`M-x tags-search' and `M-x tags-query-replace' are not giving you the
desired result, you can use `M-x next-file'.

`C-u M-x next-file'
     With a numeric argument, regardless of its value, visit the first
     file in the tags table and prepare to advance sequentially by
     files.

`M-x next-file'
     Visit the next file in the selected tags table.

\1f
File: xemacs.info,  Node: List Tags,  Prev: Tags Search,  Up: Tags

Tags Table Inquiries
--------------------

`M-x list-tags'
     Display a list of the tags defined in a specific program file.

`M-x tags-apropos'
     Display a list of all tags matching a specified regexp.

   `M-x list-tags' reads the name of one of the files described by the
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 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 tags table contains that directory.

   `M-x tags-apropos' is like `apropos' for tags.  It reads a regexp,
then finds all the tags in the selected tags table whose entries match
that regexp, and displays the tag names found.

\1f
File: xemacs.info,  Node: Fortran,  Next: Asm Mode,  Prev: Tags,  Up: Programs

Fortran Mode
============

   Fortran mode provides special motion commands for Fortran statements
and subprograms, and indentation commands that understand Fortran
conventions of nesting, line numbers, and continuation statements.

   Special commands for comments are provided because Fortran comments
are unlike those of other languages.

   Built-in abbrevs optionally save typing when you insert Fortran
keywords.

   Use `M-x fortran-mode' to switch to this major mode.  Doing so calls
the value of `fortran-mode-hook' as a function of no arguments if that
variable has a non-`nil' value.

* Menu:

* Motion: Fortran Motion.     Moving point by statements or subprograms.
* Indent: Fortran Indent.     Indentation commands for Fortran.
* Comments: Fortran Comments. Inserting and aligning comments.
* Columns: Fortran Columns.   Measuring columns for valid Fortran.
* Abbrev: Fortran Abbrev.     Built-in abbrevs for Fortran keywords.

   Fortran mode was contributed by Michael Prange.

\1f
File: xemacs.info,  Node: Fortran Motion,  Next: Fortran Indent,  Prev: Fortran,  Up: Fortran

Motion Commands
---------------

   Fortran mode provides special commands to move by subprograms
(functions and subroutines) and by statements.  There is also a command
to put the region around one subprogram, which is convenient for
killing it or moving it.

`C-M-a'
     Move to beginning of subprogram
     (`beginning-of-fortran-subprogram').

`C-M-e'
     Move to end of subprogram (`end-of-fortran-subprogram').

`C-M-h'
     Put point at beginning of subprogram and mark at end
     (`mark-fortran-subprogram').

`C-c C-n'
     Move to beginning of current or next statement (`fortran-next-
     statement').

`C-c C-p'
     Move to beginning of current or previous statement (`fortran-
     previous-statement').

\1f
File: xemacs.info,  Node: Fortran Indent,  Next: Fortran Comments,  Prev: Fortran Motion,  Up: Fortran

Fortran Indentation
-------------------

   Special commands and features are available for indenting Fortran
code.  They make sure various syntactic entities (line numbers, comment
line indicators, and continuation line flags) appear in the columns
that are required for standard Fortran.

* Menu:

* Commands: ForIndent Commands. Commands for indenting Fortran.
* Numbers:  ForIndent Num.      How line numbers auto-indent.
* Conv:     ForIndent Conv.     Conventions you must obey to avoid trouble.
* Vars:     ForIndent Vars.     Variables controlling Fortran indent style.

\1f
File: xemacs.info,  Node: ForIndent Commands,  Next: ForIndent Num,  Prev: Fortran Indent,  Up: Fortran Indent

Fortran Indentation Commands
............................

`<TAB>'
     Indent the current line (`fortran-indent-line').

`M-<LFD>'
     Break the current line and set up a continuation line.

`C-M-q'
     Indent all the lines of the subprogram point is in
     (`fortran-indent-subprogram').

   <TAB> is redefined by Fortran mode to reindent the current line for
Fortran (`fortran-indent-line').  Line numbers and continuation markers
are indented to their required columns, and the body of the statement
is independently indented, based on its nesting in the program.

   The key `C-M-q' is redefined as `fortran-indent-subprogram', a
command that reindents all the lines of the Fortran subprogram
(function or subroutine) containing point.

   The key `M-<LFD>' is redefined as `fortran-split-line', a command to
split a line in the appropriate fashion for Fortran.  In a non-comment
line, the second half becomes a continuation line and is indented
accordingly.  In a comment line, both halves become separate comment
lines.

\1f
File: xemacs.info,  Node: ForIndent Num,  Next: ForIndent Conv,  Prev: ForIndent Commands,  Up: Fortran Indent

Line Numbers and Continuation
.............................

   If a number is the first non-whitespace in the line, it is assumed
to be a line number and is moved to columns 0 through 4.  (Columns are
always counted from 0 in XEmacs.)  If the text on the line starts with
the conventional Fortran continuation marker `$', it is moved to column
5.  If the text begins with any non whitespace character in column 5,
it is assumed to be an unconventional continuation marker and remains
in column 5.

   Line numbers of four digits or less are normally indented one space.
This amount is controlled by the variable `fortran-line-number-indent',
which is the maximum indentation a line number can have.  Line numbers
are indented to right-justify them to end in column 4 unless that would
require more than the maximum indentation.  The default value of the
variable is 1.

   Simply inserting a line number is enough to indent it according to
these rules.  As each digit is inserted, the indentation is recomputed.
To turn off this feature, set the variable
`fortran-electric-line-number' to `nil'.  Then inserting line numbers
is like inserting anything else.

\1f
File: xemacs.info,  Node: ForIndent Conv,  Next: ForIndent Vars,  Prev: ForIndent Num,  Up: Fortran Indent

Syntactic Conventions
.....................

   Fortran mode assumes that you follow certain conventions that
simplify the task of understanding a Fortran program well enough to
indent it properly:

   * Two nested `do' loops never share a `continue' statement.

   * The same character appears in column 5 of all continuation lines.
     It is the value of the variable `fortran-continuation-char'.  By
     default, this character is `$'.

If you fail to follow these conventions, the indentation commands may
indent some lines unaesthetically.  However, a correct Fortran program
will retain its meaning when reindented even if the conventions are not
followed.

\1f
File: xemacs.info,  Node: ForIndent Vars,  Prev: ForIndent Conv,  Up: Fortran Indent

Variables for Fortran Indentation
.................................

   Several additional variables control how Fortran indentation works.

`fortran-do-indent'
     Extra indentation within each level of `do' statement (the default
     is 3).

`fortran-if-indent'
     Extra indentation within each level of `if' statement (the default
     is 3).

`fortran-continuation-indent'
     Extra indentation for bodies of continuation lines (the default is
     5).

`fortran-check-all-num-for-matching-do'
     If this is `nil', indentation assumes that each `do' statement
     ends on a `continue' statement.  Therefore, when computing
     indentation for a statement other than `continue', it can save
     time by not checking for a `do' statement ending there.  If this
     is non-`nil', indenting any numbered statement must check for a
     `do' that ends there.  The default is `nil'.

`fortran-minimum-statement-indent'
     Minimum indentation for Fortran statements.  For standard Fortran,
     this is 6.  Statement bodies are always indented at least this
     much.

\1f
File: xemacs.info,  Node: Fortran Comments,  Next: Fortran Columns,  Prev: Fortran Indent,  Up: Fortran

Comments
--------

   The usual Emacs comment commands assume that a comment can follow a
line of code.  In Fortran, the standard comment syntax requires an
entire line to be just a comment.  Therefore, Fortran mode replaces the
standard Emacs comment commands and defines some new variables.

   Fortran mode can also handle a non-standard comment syntax where
comments start with `!' and can follow other text.  Because only some
Fortran compilers accept this syntax, Fortran mode will not insert such
comments unless you have specified to do so in advance by setting the
variable `comment-start' to `"!"' (*note Variables::).

`M-;'
     Align comment or insert new comment (`fortran-comment-indent').

`C-x ;'
     Applies to nonstandard `!' comments only.

`C-c ;'
     Turn all lines of the region into comments, or (with arg) turn
     them back into real code (`fortran-comment-region').

   `M-;' in Fortran mode is redefined as the command
`fortran-comment-indent'.  Like the usual `M-;' command, it recognizes
an existing comment and aligns its text appropriately.  If there is no
existing comment, a comment is inserted and aligned.

   Inserting and aligning comments is not the same in Fortran mode as in
other modes.  When a new comment must be inserted, a full-line comment
is inserted if the current line is blank.  On a non-blank line, a
non-standard `!' comment is inserted if you previously specified you
wanted to use them.  Otherwise a full-line comment is inserted on a new
line before the current line.

   Non-standard `!' comments are aligned like comments in other
languages, but full-line comments are aligned differently.  In a
standard full-line comment, the comment delimiter itself must always
appear in column zero.  What can be aligned is the text within the
comment.  You can choose from three styles of alignment by setting the
variable `fortran-comment-indent-style' to one of these values:

`fixed'
     The text is aligned at a fixed column, which is the value of
     `fortran-comment-line-column'.  This is the default.

`relative'
     The text is aligned as if it were a line of code, but with an
     additional `fortran-comment-line-column' columns of indentation.

`nil'
     Text in full-line columns is not moved automatically.

   You can also specify the character to be used to indent within
full-line comments by setting the variable `fortran-comment-indent-char'
to the character you want to use.

   Fortran mode introduces two variables `comment-line-start' and
`comment-line-start-skip', which do for full-line comments what
`comment-start' and `comment-start-skip' do for ordinary text-following
comments.  Normally these are set properly by Fortran mode, so you do
not need to change them.

   The normal Emacs comment command `C-x ;' has not been redefined.  It
can therefore be used if you use `!' comments, but is useless in
Fortran mode otherwise.

   The command `C-c ;' (`fortran-comment-region') turns all the lines
of the region into comments by inserting the string `C$$$' at the front
of each one.  With a numeric arg, the region is turned back into live
code by deleting `C$$$' from the front of each line.  You can control
the string used for the comments by setting the variable
`fortran-comment-region'.  Note that here we have an example of a
command and a variable with the same name; the two uses of the name
never conflict because in Lisp and in Emacs it is always clear from the
context which one is referred to.

\1f
File: xemacs.info,  Node: Fortran Columns,  Next: Fortran Abbrev,  Prev: Fortran Comments,  Up: Fortran

Columns
-------

`C-c C-r'
     Displays a "column ruler" momentarily above the current line
     (`fortran-column-ruler').

`C-c C-w'
     Splits the current window horizontally so that it is 72 columns
     wide.  This may help you avoid going over that limit
     (`fortran-window-create').

   The command `C-c C-r' (`fortran-column-ruler') shows a column ruler
above the current line.  The comment ruler consists of two lines of
text that show you the locations of columns with special significance
in Fortran programs.  Square brackets show the limits of the columns for
line numbers, and curly brackets show the limits of the columns for the
statement body.  Column numbers appear above them.

   Note that the column numbers count from zero, as always in XEmacs.
As a result, the numbers may not be those you are familiar with; but the
actual positions in the line are standard Fortran.

   The text used to display the column ruler is the value of the
variable `fortran-comment-ruler'.  By changing this variable, you can
change the display.

   For even more help, use `C-c C-w' (`fortran-window-create'), a
command which splits the current window horizontally, resulting in a
window 72 columns wide.  When you edit in this window, you can
immediately see when a line gets too wide to be correct Fortran.

\1f
File: xemacs.info,  Node: Fortran Abbrev,  Prev: Fortran Columns,  Up: Fortran

Fortran Keyword Abbrevs
-----------------------

   Fortran mode provides many built-in abbrevs for common keywords and
declarations.  These are the same sort of abbrevs that you can define
yourself.  To use them, you must turn on Abbrev mode.  *note Abbrevs::.

   The built-in abbrevs are unusual in one way: they all start with a
semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
mode makes this possible by changing the syntax of semicolon to "word
constituent".

   For example, one built-in Fortran abbrev is `;c' for `continue'.  If
you insert `;c' and then insert a punctuation character such as a space
or a newline, the `;c' changes automatically to `continue', provided
Abbrev mode is enabled.

   Type `;?' or `;C-h' to display a list of all built-in Fortran
abbrevs and what they stand for.

\1f
File: xemacs.info,  Node: Asm Mode,  Prev: Fortran,  Up: Programs

Asm Mode
========

   Asm mode is a major mode for editing files of assembler code.  It
defines these commands:

`<TAB>'
     `tab-to-tab-stop'.

`<LFD>'
     Insert a newline and then indent using `tab-to-tab-stop'.

`:'
     Insert a colon and then remove the indentation from before the
     label preceding colon.  Then do `tab-to-tab-stop'.

`;'
     Insert or align a comment.

   The variable `asm-comment-char' specifies which character starts
comments in assembler syntax.

\1f
File: xemacs.info,  Node: Running,  Next: Abbrevs,  Prev: Programs,  Up: Top

Compiling and Testing Programs
******************************

   The previous chapter discusses the Emacs commands that are useful for
making changes in programs.  This chapter deals with commands that
assist in the larger process of developing and maintaining programs.

* Menu:

* Compilation::        Compiling programs in languages other than Lisp
                        (C, Pascal, etc.)
* Modes: Lisp Modes.   Various modes for editing Lisp programs, with
                       different facilities for running the Lisp programs.
* Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
* Eval: Lisp Eval.     Executing a single Lisp expression in Emacs.
* Debug: Lisp Debug.   Debugging Lisp programs running in Emacs.
* Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
* External Lisp::      Communicating through Emacs with a separate Lisp.

\1f
File: xemacs.info,  Node: Compilation,  Next: Lisp Modes,  Prev: Running,  Up: Running

Running "make", or Compilers Generally
======================================

   Emacs can run compilers for non-interactive languages like C and
Fortran as inferior processes, feeding the error log into an Emacs
buffer.  It can also parse the error messages and visit the files in
which errors are found, moving point to the line where the error
occurred.

`M-x compile'
     Run a compiler asynchronously under Emacs, with error messages to
     `*compilation*' buffer.

`M-x grep'
     Run `grep' asynchronously under Emacs, with matching lines listed
     in the buffer named `*compilation*'.

`M-x kill-compilation'
     Kill the process made by the `M-x compile' command.

`M-x kill-grep'
     Kill the running compilation or `grep' subprocess.

`C-x `'
     Visit the next compiler error message or `grep' match.

   To run `make' or another compiler, type `M-x compile'.  This command
reads a shell command line using the minibuffer, then executes the
specified command line in an inferior shell with output going to the
buffer named `*compilation*'.  By default, the current buffer's default
directory is used as the working directory for the execution of the
command; therefore, the makefile comes from this directory.

   When the shell command line is read, the minibuffer appears
containing a default command line (the command you used the last time
you typed `M-x compile').  If you type just <RET>, the same command
line is used again.  The first `M-x compile' provides `make -k' as the
default.  The default is taken from the variable `compile-command'; if
the appropriate compilation command for a file is something other than
`make -k', it can be useful to have the file specify a local value for
`compile-command' (*note File Variables::).

   When you start a compilation, the buffer `*compilation*' is
displayed in another window but not selected.  Its mode line displays
the word `run' or `exit' in the parentheses to tell you whether
compilation is finished.  You do not have to keep this buffer visible;
compilation continues in any case.

   To kill the compilation process, type `M-x kill-compilation'.  The
mode line of the `*compilation*' buffer changes to say `signal' instead
of `run'.  Starting a new compilation also kills any running
compilation, as only one can occur at any time.  Starting a new
compilation prompts for confirmation before actually killing a
compilation that is running.

   To parse the compiler error messages, type `C-x `' (`next-error').
The character following `C-x' is the grave accent, not the single
quote.  The command displays the buffer `*compilation*' in one window
and the buffer in which the next error occurred in another window.
Point in that buffer is moved to the line where the error was found.
The corresponding error message is scrolled to the top of the window in
which `*compilation*' is displayed.

   The first time you use `C-x `' after the start of a compilation, it
parses all the error messages, visits all the files that have error
messages, and creates markers pointing at the lines the error messages
refer to.  It then moves to the first error message location.
Subsequent uses of `C-x `' advance down the data set up by the first
use.  When the preparsed error messages are exhausted, the next `C-x `'
checks for any more error messages that have come in; this is useful if
you start editing compiler errors while compilation is still going on.
If no additional error messages have come in, `C-x `' reports an error.

   `C-u C-x `' discards the preparsed error message data and parses the
`*compilation*' buffer again, then displays the first error.  This way,
you can process the same set of errors again.

   Instead of running a compiler, you can run `grep' and see the lines
on which matches were found.  To do this, type `M-x grep' with an
argument line that contains the same arguments you would give to
`grep': a `grep'-style regexp (usually in single quotes to quote the
shell's special characters) followed by filenames, which may use
wildcard characters.  The output from `grep' goes in the
`*compilation*' buffer.  You can use `C-x `' to find the lines that
match as if they were compilation errors.

   Note: a shell is used to run the compile command, but the shell is
not run in interactive mode.  In particular, this means that the shell
starts up with no prompt.  If you find your usual shell prompt making an
unsightly appearance in the `*compilation*' buffer, it means you have
made a mistake in your shell's initialization file (`.cshrc' or `.shrc'
or ...) by setting the prompt unconditionally.  The shell
initialization file should set the prompt only if there already is a
prompt.  Here's how to do it in `csh':

     if ($?prompt) set prompt = ...

\1f
File: xemacs.info,  Node: Lisp Modes,  Next: Lisp Libraries,  Prev: Compilation,  Up: Running

Major Modes for Lisp
====================

   Emacs has four different major modes for Lisp.  They are the same in
terms of editing commands, but differ in the commands for executing Lisp
expressions.

Emacs-Lisp mode
     The mode for editing source files of programs to run in Emacs Lisp.
     This mode defines `C-M-x' to evaluate the current defun.  *Note
     Lisp Libraries::.

Lisp Interaction mode
     The mode for an interactive session with Emacs Lisp.  It defines
     <LFD> to evaluate the sexp before point and insert its value in the
     buffer.  *Note Lisp Interaction::.

Lisp mode
     The mode for editing source files of programs that run in other
     dialects of Lisp than Emacs Lisp.  This mode defines `C-M-x' to
     send the current defun to an inferior Lisp process.  *Note
     External Lisp::.

Inferior Lisp mode
     The mode for an interactive session with an inferior Lisp process.
     This mode combines the special features of Lisp mode and Shell mode
     (*note Shell Mode::).

Scheme mode
     Like Lisp mode but for Scheme programs.

Inferior Scheme mode
     The mode for an interactive session with an inferior Scheme
     process.