-This is ../info/xemacs.info, produced by makeinfo version 4.0 from
+This is ../info/xemacs.info, produced by makeinfo version 4.0b from
xemacs/xemacs.texi.
INFO-DIR-SECTION XEmacs Editor
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
comments in assembler syntax.
\1f
-File: xemacs.info, Node: Running, Next: Packages, Prev: Programs, Up: Top
+File: xemacs.info, Node: Running, Next: Abbrevs, Prev: Programs, Up: Top
Compiling and Testing Programs
******************************
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
+ 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
The mode for an interactive session with an inferior Scheme
process.
-\1f
-File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
-
-Libraries of Lisp Code for Emacs
-================================
-
- Lisp code for Emacs editing commands is stored in files whose names
-conventionally end in `.el'. This ending tells Emacs to edit them in
-Emacs-Lisp mode (*note Lisp Modes::).
-
-* Menu:
-
-* Loading:: Loading libraries of Lisp code into Emacs for use.
-* Compiling Libraries:: Compiling a library makes it load and run faster.
-* Mocklisp:: Converting Mocklisp to Lisp so XEmacs can run it.
-
-\1f
-File: xemacs.info, Node: Loading, Next: Compiling Libraries, Prev: Lisp Libraries, Up: Lisp Libraries
-
-Loading Libraries
------------------
-
-`M-x load-file FILE'
- Load the file FILE of Lisp code.
-
-`M-x load-library LIBRARY'
- Load the library named LIBRARY.
-
-`M-x locate-library LIBRARY &optional NOSUFFIX'
- Show the full path name of Emacs library LIBRARY.
-
- To execute a file of Emacs Lisp, use `M-x load-file'. This command
-reads the file name you provide in the minibuffer, then executes the
-contents of that file as Lisp code. It is not necessary to visit the
-file first; in fact, this command reads the file as found on disk, not
-the text in an Emacs buffer.
-
- Once a file of Lisp code is installed in the Emacs Lisp library
-directories, users can load it using `M-x load-library'. Programs can
-load it by calling `load-library', or with `load', a more primitive
-function that is similar but accepts some additional arguments.
-
- `M-x load-library' differs from `M-x load-file' in that it searches
-a sequence of directories and tries three file names in each directory.
-The three names are: first, the specified name with `.elc' appended;
-second, the name with `.el' appended; third, the specified name alone.
-A `.elc' file would be the result of compiling the Lisp file into byte
-code; if possible, it is loaded in preference to the Lisp file itself
-because the compiled file loads and runs faster.
-
- Because the argument to `load-library' is usually not in itself a
-valid file name, file name completion is not available. In fact, when
-using this command, you usually do not know exactly what file name will
-be used.
-
- The sequence of directories searched by `M-x load-library' is
-specified by the variable `load-path', a list of strings that are
-directory names. The elements of this list may not begin with "`~'",
-so you must call `expand-file-name' on them before adding them to the
-list. The default value of the list contains the directory where the
-Lisp code for Emacs itself is stored. If you have libraries of your
-own, put them in a single directory and add that directory to
-`load-path'. `nil' in this list stands for the current default
-directory, but it is probably not a good idea to put `nil' in the list.
-If you start wishing that `nil' were in the list, you should probably
-use `M-x load-file' for this case.
-
- The variable is initialized by the EMACSLOADPATH environment
-variable. If no value is specified, the variable takes the default value
-specified in the file `paths.h' when Emacs was built. If a path isn't
-specified in `paths.h', a default value is obtained from the file
-system, near the directory in which the Emacs executable resides.
-
- Like `M-x load-library', `M-x locate-library' searches the
-directories in `load-path' to find the file that `M-x load-library'
-would load. If the optional second argument NOSUFFIX is non-`nil', the
-suffixes `.elc' or `.el' are not added to the specified name LIBRARY
-(like calling `load' instead of `load-library').
-
- You often do not have to give any command to load a library, because
-the commands defined in the library are set up to "autoload" that
-library. Running any of those commands causes `load' to be called to
-load the library; this replaces the autoload definitions with the real
-ones from the library.
-
- If autoloading a file does not finish, either because of an error or
-because of a `C-g' quit, all function definitions made by the file are
-undone automatically. So are any calls to `provide'. As a
-consequence, the entire file is loaded a second time if you use one of
-the autoloadable commands again. This prevents problems when the
-command is no longer autoloading but is working incorrectly because the
-file was only partially loaded. Function definitions are undone only
-for autoloading; explicit calls to `load' do not undo anything if
-loading is not completed.
-
- The variable `after-load-alist' takes an alist of expressions to be
-evaluated when particular files are loaded. Each element has the form
-`(FILENAME forms...)'. When `load' is run and the filename argument is
-FILENAME, the forms in the corresponding element are executed at the
-end of loading.
-
- FILENAME must match exactly. Normally FILENAME is the name of a
-library, with no directory specified, since that is how load is
-normally called. An error in `forms' does not undo the load, but it
-does prevent execution of the rest of the `forms'.
-
-\1f
-File: xemacs.info, Node: Compiling Libraries, Next: Mocklisp, Prev: Loading, Up: Lisp Libraries
-
-Compiling Libraries
--------------------
-
- Emacs Lisp code can be compiled into byte-code which loads faster,
-takes up less space when loaded, and executes faster.
-
-`M-x batch-byte-compile'
- Run byte-compile-file on the files remaining on the command line.
-
-`M-x byte-compile-buffer &optional BUFFER'
- Byte-compile and evaluate contents of BUFFER (default is current
- buffer).
-
-`M-x byte-compile-file'
- Compile a file of Lisp code named FILENAME into a file of byte
- code.
-
-`M-x byte-compile-and-load-file FILENAME'
- Compile a file of Lisp code named FILENAME into a file of byte
- code and load it.
-
-`M-x byte-recompile-directory DIRECTORY'
- Recompile every `.el' file in DIRECTORY that needs recompilation.
-
-`M-x disassemble'
- Print disassembled code for OBJECT on (optional) STREAM.
-
-`M-x make-obsolete FUNCTION NEW'
- Make the byte-compiler warn that FUNCTION is obsolete and NEW
- should be used instead.
-
- `byte-compile-file' creates a byte-code compiled file from an
-Emacs-Lisp source file. The default argument for this function is the
-file visited in the current buffer. The function reads the specified
-file, compiles it into byte code, and writes an output file whose name
-is made by appending `c' to the input file name. Thus, the file
-`rmail.el' would be compiled into `rmail.elc'. To compile a file of
-Lisp code named FILENAME into a file of byte code and then load it, use
-`byte-compile-and-load-file'. To compile and evaluate Lisp code in a
-given buffer, use `byte-compile-buffer'.
-
- To recompile all changed Lisp files in a directory, use `M-x
-byte-recompile-directory'. Specify just the directory name as an
-argument. Each `.el' file that has been byte-compiled before is
-byte-compiled again if it has changed since the previous compilation.
-A numeric argument to this command tells it to offer to compile each
-`.el' file that has not been compiled yet. You must answer `y' or `n'
-to each offer.
-
- You can use the function `batch-byte-compile' to invoke Emacs
-non-interactively from the shell to do byte compilation. When you use
-this function, the files to be compiled are specified with command-line
-arguments. Use a shell command of the form:
-
- emacs -batch -f batch-byte-compile FILES...
-
- Directory names may also be given as arguments; in that case,
-`byte-recompile-directory' is invoked on each such directory.
-`batch-byte-compile' uses all remaining command-line arguments as file
-or directory names, then kills the Emacs process.
-
- `M-x disassemble' explains the result of byte compilation. Its
-argument is a function name. It displays the byte-compiled code in a
-help window in symbolic form, one instruction per line. If the
-instruction refers to a variable or constant, that is shown, too.
-
-\1f
-File: xemacs.info, Node: Mocklisp, Prev: Compiling Libraries, Up: Lisp Libraries
-
-Converting Mocklisp to Lisp
----------------------------
-
- XEmacs can run Mocklisp files by converting them to Emacs Lisp first.
-To convert a Mocklisp file, visit it and then type `M-x
-convert-mocklisp-buffer'. Then save the resulting buffer of Lisp file
-in a file whose name ends in `.el' and use the new file as a Lisp
-library.
-
- You cannot currently byte-compile converted Mocklisp code. The
-reason is that converted Mocklisp code uses some special Lisp features
-to deal with Mocklisp's incompatible ideas of how arguments are
-evaluated and which values signify "true" or "false".
-
-\1f
-File: xemacs.info, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Running
-
-Evaluating Emacs-Lisp Expressions
-=================================
-
- Lisp programs intended to be run in Emacs should be edited in
-Emacs-Lisp mode; this will happen automatically for file names ending in
-`.el'. By contrast, Lisp mode itself should be used for editing Lisp
-programs intended for other Lisp systems. Emacs-Lisp mode can be
-selected with the command `M-x emacs-lisp-mode'.
-
- For testing of Lisp programs to run in Emacs, it is useful to be able
-to evaluate part of the program as it is found in the Emacs buffer. For
-example, if you change the text of a Lisp function definition and then
-evaluate the definition, Emacs installs the change for future calls to
-the function. Evaluation of Lisp expressions is also useful in any
-kind of editing task for invoking non-interactive functions (functions
-that are not commands).
-
-`M-<ESC>'
- Read a Lisp expression in the minibuffer, evaluate it, and print
- the value in the minibuffer (`eval-expression').
-
-`C-x C-e'
- Evaluate the Lisp expression before point, and print the value in
- the minibuffer (`eval-last-sexp').
-
-`C-M-x'
- Evaluate the defun containing point or after point, and print the
- value in the minibuffer (`eval-defun').
-
-`M-x eval-region'
- Evaluate all the Lisp expressions in the region.
-
-`M-x eval-current-buffer'
- Evaluate all the Lisp expressions in the buffer.
-
- `M-<ESC>' (`eval-expression') is the most basic command for
-evaluating a Lisp expression interactively. It reads the expression
-using the minibuffer, so you can execute any expression on a buffer
-regardless of what the buffer contains. When evaluation is complete,
-the current buffer is once again the buffer that was current when
-`M-<ESC>' was typed.
-
- `M-<ESC>' can easily confuse users, especially on keyboards with
-autorepeat, where it can result from holding down the <ESC> key for too
-long. Therefore, `eval-expression' is normally a disabled command.
-Attempting to use this command asks for confirmation and gives you the
-option of enabling it; once you enable the command, you are no longer
-required to confirm. *Note Disabling::.
-
- In Emacs-Lisp mode, the key `C-M-x' is bound to the function
-`eval-defun', which parses the defun containing point or following point
-as a Lisp expression and evaluates it. The value is printed in the echo
-area. This command is convenient for installing in the Lisp environment
-changes that you have just made in the text of a function definition.
-
- The command `C-x C-e' (`eval-last-sexp') performs a similar job but
-is available in all major modes, not just Emacs-Lisp mode. It finds
-the sexp before point, reads it as a Lisp expression, evaluates it, and
-prints the value in the echo area. It is sometimes useful to type in an
-expression and then, with point still after it, type `C-x C-e'.
-
- If `C-M-x' or `C-x C-e' are given a numeric argument, they print the
-value by inserting it into the current buffer at point, rather than in
-the echo area. The argument value does not matter.
-
- The most general command for evaluating Lisp expressions from a
-buffer is `eval-region'. `M-x eval-region' parses the text of the
-region as one or more Lisp expressions, evaluating them one by one.
-`M-x eval-current-buffer' is similar, but it evaluates the entire
-buffer. This is a reasonable way to install the contents of a file of
-Lisp code that you are just ready to test. After finding and fixing a
-bug, use `C-M-x' on each function that you change, to keep the Lisp
-world in step with the source file.
-
-\1f
-File: xemacs.info, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Running
-
-The Emacs-Lisp Debugger
-=======================
-
- XEmacs contains a debugger for Lisp programs executing inside it.
-This debugger is normally not used; many commands frequently get Lisp
-errors when invoked in inappropriate contexts (such as `C-f' at the end
-of the buffer) and it would be unpleasant to enter a special debugging
-mode in this case. When you want to make Lisp errors invoke the
-debugger, you must set the variable `debug-on-error' to non-`nil'.
-Quitting with `C-g' is not considered an error, and `debug-on-error'
-has no effect on the handling of `C-g'. However, if you set
-`debug-on-quit' to be non-`nil', `C-g' will invoke the debugger. This
-can be useful for debugging an infinite loop; type `C-g' once the loop
-has had time to reach its steady state. `debug-on-quit' has no effect
-on errors.
-
- You can make Emacs enter the debugger when a specified function is
-called or at a particular place in Lisp code. Use `M-x debug-on-entry'
-with argument FUN-NAME to have Emacs enter the debugger as soon as
-FUN-NAME is called. Use `M-x cancel-debug-on-entry' to make the
-function stop entering the debugger when called. (Redefining the
-function also does this.) To enter the debugger from some other place
-in Lisp code, you must insert the expression `(debug)' there and
-install the changed code with `C-M-x'. *Note Lisp Eval::.
-
- When the debugger is entered, it displays the previously selected
-buffer in one window and a buffer named `*Backtrace*' in another
-window. The backtrace buffer contains one line for each level of Lisp
-function execution currently going on. At the beginning of the buffer
-is a message describing the reason that the debugger was invoked, for
-example, an error message if it was invoked due to an error.
-
- The backtrace buffer is read-only and is in Backtrace mode, a special
-major mode in which letters are defined as debugger commands. The
-usual Emacs editing commands are available; you can switch windows to
-examine the buffer that was being edited at the time of the error, and
-you can switch buffers, visit files, and perform any other editing
-operations. However, the debugger is a recursive editing level (*note
-Recursive Edit::); it is a good idea to return to the backtrace buffer
-and explictly exit the debugger when you don't want to use it any more.
-Exiting the debugger kills the backtrace buffer.
-
- The contents of the backtrace buffer show you the functions that are
-executing and the arguments that were given to them. It also allows you
-to specify a stack frame by moving point to the line describing that
-frame. The frame whose line point is on is considered the "current
-frame". Some of the debugger commands operate on the current frame.
-Debugger commands are mainly used for stepping through code one
-expression at a time. Here is a list of them:
-
-`c'
- Exit the debugger and continue execution. In most cases,
- execution of the program continues as if the debugger had never
- been entered (aside from the effect of any variables or data
- structures you may have changed while inside the debugger). This
- includes entry to the debugger due to function entry or exit,
- explicit invocation, and quitting or certain errors. Most errors
- cannot be continued; trying to continue an error usually causes
- the same error to occur again.
-
-`d'
- Continue execution, but enter the debugger the next time a Lisp
- function is called. This allows you to step through the
- subexpressions of an expression, and see what the subexpressions
- do and what values they compute.
-
- When you enter the debugger this way, Emacs flags the stack frame
- for the function call from which you entered. The same function
- is then called when you exit the frame. To cancel this flag, use
- `u'.
-
-`b'
- Set up to enter the debugger when the current frame is exited.
- Frames that invoke the debugger on exit are flagged with stars.
-
-`u'
- Don't enter the debugger when the current frame is exited. This
- cancels a `b' command on a frame.
-
-`e'
- Read a Lisp expression in the minibuffer, evaluate it, and print
- the value in the echo area. This is equivalent to the command
- `M-<ESC>', except that `e' is not normally disabled like `M-<ESC>'.
-
-`q'
- Terminate the program being debugged; return to top-level Emacs
- command execution.
-
- If the debugger was entered due to a `C-g' but you really want to
- quit, not to debug, use the `q' command.
-
-`r'
- Return a value from the debugger. The value is computed by
- reading an expression with the minibuffer and evaluating it.
-
- The value returned by the debugger makes a difference when the
- debugger was invoked due to exit from a Lisp call frame (as
- requested with `b'); then the value specified in the `r' command
- is used as the value of that frame.
-
- The debugger's return value also matters with many errors. For
- example, `wrong-type-argument' errors will use the debugger's
- return value instead of the invalid argument; `no-catch' errors
- will use the debugger value as a throw tag instead of the tag that
- was not found. If an error was signaled by calling the Lisp
- function `signal', the debugger's return value is returned as the
- value of `signal'.
-
-\1f
-File: xemacs.info, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Running
-
-Lisp Interaction Buffers
-========================
-
- The buffer `*scratch*', which is selected when Emacs starts up, is
-provided for evaluating Lisp expressions interactively inside Emacs.
-Both the expressions you evaluate and their output goes in the buffer.
-
- The `*scratch*' buffer's major mode is Lisp Interaction mode, which
-is the same as Emacs-Lisp mode except for one command, <LFD>. In
-Emacs-Lisp mode, <LFD> is an indentation command. In Lisp Interaction
-mode, <LFD> is bound to `eval-print-last-sexp'. This function reads
-the Lisp expression before point, evaluates it, and inserts the value
-in printed representation before point.
-
- The way to use the `*scratch*' buffer is to insert Lisp expressions
-at the end, ending each one with <LFD> so that it will be evaluated.
-The result is a complete typescript of the expressions you have
-evaluated and their values.
-
- The rationale for this feature is that Emacs must have a buffer when
-it starts up, but that buffer is not useful for editing files since a
-new buffer is made for every file that you visit. The Lisp interpreter
-typescript is the most useful thing I can think of for the initial
-buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp
-Interaction mode.
-
-\1f
-File: xemacs.info, Node: External Lisp, Prev: Lisp Interaction, Up: Running
-
-Running an External Lisp
-========================
-
- Emacs has facilities for running programs in other Lisp systems.
-You can run a Lisp process as an inferior of Emacs, and pass
-expressions to it to be evaluated. You can also pass changed function
-definitions directly from the Emacs buffers in which you edit the Lisp
-programs to the inferior Lisp process.
-
- To run an inferior Lisp process, type `M-x run-lisp'. This runs the
-program named `lisp', the same program you would run by typing `lisp'
-as a shell command, with both input and output going through an Emacs
-buffer named `*lisp*'. In other words, any "terminal output" from Lisp
-will go into the buffer, advancing point, and any "terminal input" for
-Lisp comes from text in the buffer. To give input to Lisp, go to the
-end of the buffer and type the input, terminated by <RET>. The
-`*lisp*' buffer is in Inferior Lisp mode, which has all the special
-characteristics of Lisp mode and Shell mode (*note Shell Mode::).
-
- Use Lisp mode to run the source files of programs in external Lisps.
-You can select this mode with `M-x lisp-mode'. It is used automatically
-for files whose names end in `.l' or `.lisp', as most Lisp systems
-usually expect.
-
- When you edit a function in a Lisp program you are running, the
-easiest way to send the changed definition to the inferior Lisp process
-is the key `C-M-x'. In Lisp mode, this key runs the function
-`lisp-send-defun', which finds the defun around or following point and
-sends it as input to the Lisp process. (Emacs can send input to any
-inferior process regardless of what buffer is current.)
-
- Contrast the meanings of `C-M-x' in Lisp mode (for editing programs
-to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
-programs to be run in Emacs): in both modes it has the effect of
-installing the function definition that point is in, but the way of
-doing so is different according to where the relevant Lisp environment
-is found. *Note Lisp Modes::.
-
-\1f
-File: xemacs.info, Node: Packages, Next: Abbrevs, Prev: Running, Up: Top
-
-Packages
-========
-
- The XEmacs 21 distribution comes only with a very basic set of
-built-in modes and packages. Most of the packages that were part of
-the distribution of earlier versions of XEmacs are now available
-separately. The installer as well as the user can choose which
-packages to install; the actual installation process is easy. This
-gives an installer the ability to tailor an XEmacs installation for
-local needs with safe removal of unnecessary code.
-
-* Menu:
-
-* Package Terminology:: Understanding different kinds of packages.
-* Using Packages:: How to install and use packages.
-* Building Packages:: Building packages from sources.
-
-\1f
-File: xemacs.info, Node: Package Terminology, Next: Using Packages, Up: Packages
-
-Package Flavors
----------------
-
- There are two main flavors of packages.
-
- * Regular Packages A regular package is one in which multiple files
- are involved and one may not in general safely remove any of them.
-
- * Single-File Packages A single-file package is an aggregate
- collection of thematically related but otherwise independent lisp
- files. These files are bundled together for download convenience
- and individual files may be deleted at will without any loss of
- functionality.
-
-Package Distributions
----------------------
-
- XEmacs Lisp packages are distributed in two ways, depending on the
-intended use. Binary Packages are for installers and end-users and may
-be installed directly into an XEmacs package directory. Source Packages
-are for developers and include all files necessary for rebuilding
-bytecompiled lisp and creating tarballs for distribution.
-
-Binary Packages
----------------
-
- Binary packages may be installed directly into an XEmacs package
-hierarchy.
-
-Source Packages
----------------
-
- Source packages contain all of the Package author's (where
-appropriate in regular packages) source code plus all of the files
-necessary to build distribution tarballs (Unix Tar format files,
-gzipped for space savings).
-
-\1f
-File: xemacs.info, Node: Using Packages, Next: Building Packages, Prev: Package Terminology, Up: Packages
-
-Getting Started
----------------
-
- When you first download XEmacs 21, you will usually first grab the
-"core distribution", a file called `xemacs-21.0.tar.gz'. (Replace the
-21.0 by the current version number.) The core distribution contains
-the sources of XEmacs and a minimal set of Emacs Lisp files, which are
-in the subdirectory named `lisp'. This subdirectory used to contain
-all Emacs Lisp files distributed with XEmacs. Now, to conserve disk
-space, most non-essential packages were made optional.
-
-Choosing the Packages You Need
-------------------------------
-
- The available packages can currently be found in the same ftp
-directory where you grabbed the core distribution from, and are located
-in the subdirectory `packages/binary-packages'. Package file names
-follow the naming convention `<package-name>-<version>-pkg.tar.gz'.
-
- If you have EFS *Note (EFS)::, packages can be installed over the
-network. Alternatively, if you have copies of the packages locally,
-you can install packages from a local disk or CDROM.
-
- The file `etc/PACKAGES' in the core distribution contains a list of
-the packages available at the time of the XEmacs release. Packages are
-also listed on the `Options' menu under:
-
- Options->Customize->Emacs->Packages
-
- However, don't select any of these menu picks unless you actually
-want to install the given package (and have properly configured your
-system to do so).
-
- You can also get a list of available packages, and whether or not
-they are installed, using the visual package browser and installer.
-You can access it via the menus:
-
- Options->Manage Packages->List & Install
-
- Or, you can get to it via the keyboard:
-
- M-x pui-list-packages
-
- Hint to system administrators of multi-user systems: it might be a
-good idea to install all packages and not interfere with the wishes of
-your users.
-
- If you can't find which package provides the feature you require, try
-using the `package-get-package-provider' function. Eg., if you know
-that you need `thingatpt', type:
-
- M-x package-get-package-provider RET thingatpt
-
- which will return something like (fsf-compat "1.06"). You can the use
-one of the methods above for installing the package you want.
-
-XEmacs and Installing Packages
-------------------------------
-
- Normally, packages are installed over the network, using EFS *Note
-(EFS)::. However, you may not have network access, or you may already
-have some or all of the packages on a local disk, such as a CDROM. If
-you want to install from a local disk, you must first tell XEmacs where
-to find the package binaries. This is done by adding a line like the
-following to your `.emacs' file:
-
- (setq package-get-remote (cons (list nil "/my/path/to/package/binaries")
- package-get-remote))
-
- Here, you'd change `/my/path/to/package/binaries' to be the path to
-your local package binaries. Next, restart XEmacs, and you're ready to
-go (advanced users can just re-evaluate the sexp).
-
- If you are installing from a temporary, one-time directory, you can
-also add these directory names to `package-get-remote' using:
-
- M-x pui-add-install-directory
-
- Note, however, that any directories added using this function are not
-saved; this information will be lost when you quit XEmacs.
-
- If you're going to install over the network, you only have to insure
-that EFS *Note (EFS):: works, and that it can get outside a firewall, if
-you happen to be behind one. You shouldn't have to do anything else;
-XEmacs already knows where to go. However you can add your own mirrors
-to this list. See `package-get-remote'.
-
- The easiest way to install a package is to use the visual package
-browser and installer, using the menu pick:
-
- Options->Manage Packages->List & Install
- or
- Options->Manage Packages->Using Custom->Select-> ...
-
- You can also access it using the keyboard:
-
- M-x pui-list-packages
-
- The visual package browser will then display a list of all packages.
-Help information will be displayed at the very bottom of the buffer; you
-may have to scroll down to see it. You can also press `?' to get the
-same help. From this buffer, you can tell the package status by the
-character in the first column:
-
-`-'
- The package has not been installed.
-
-`*'
- The package has been installed, but a newer version is available.
- The current version is out-of-date.
-
-`+'
- The package has been marked for installation/update.
-
- If there is no character in the first column, the package has been
-installed and is up-to-date.
-
- From here, you can select or unselect packages for installation using
-the <RET> key, the `Mouse-2' button or selecting "Select" from the
-(Popup) Menu. Once you've finished selecting the packages, you can
-press the `x' key (or use the menu) to actually install the packages.
-Note that you will have to restart XEmacs for XEmacs to recognize any
-new packages.
-
- Key summary:
-
-`?'
- Display simple help.
-
-`<RET>'
-`<Mouse-2>'
- Toggle between selecting and unselecting a package for
- installation.
-
-`x'
- Install selected packages.
-
-`<SPC>'
- View, in the minibuffer, additional information about the package,
- such as the package date (not the build date) and the package
- author. Moving the mouse over a package name will also do the
- same thing.
-
-`v'
- Toggle between verbose and non-verbose package display.
-
-`g'
- Refresh the package display.
-
-`q'
- Kill the package buffer.
-
- Moving the mouse over a package will also cause additional
-information about the package to be displayed in the minibuffer.
-
-Other package installation interfaces
--------------------------------------
-
- For an alternative package interface, you can select packages from
-the customize menus, under:
-
- Options->Customize->Emacs->Packages-> ...
- or
- Options->Manage Packages->Using Custom->Select-> ...
-
- Set their state to on, and then do:
-
- Options->Manage Packages->Using Custom->Update Packages
-
- This will automatically retrieve the packages you have selected from
-the XEmacs ftp site or your local disk, and install them into XEmacs.
-Additionally it will update any packages you already have installed to
-the newest version. Note that if a package is newly installed you will
-have to restart XEmacs for the change to take effect.
-
- You can also install packages using a semi-manual interface:
-
- M-x package-get-all <return>
-
- Enter the name of the package (e.g., `prog-modes'), and XEmacs will
-search for the latest version (as listed in the lisp file
-`lisp/package-get-base.el'), and install it and any packages that it
-depends upon.
-
-Manual Binary Package Installation
-----------------------------------
-
- Pre-compiled, binary packages can be installed in either a system
-package directory (this is determined when XEmacs is compiled), or in
-one of the following subdirectories of your `$HOME' directory:
-
- ~/.xemacs/mule-packages
- ~/.xemacs/xemacs-packages
-
- Packages in the former directory will only be found by a Mule-enabled
-XEmacs.
-
- XEmacs does not have to be running to install binary packages,
-although XEmacs will not know about any newly-installed packages until
-you restart XEmacs. Note, however, that installing a newer version of a
-package while XEmacs is running could cause strange errors in XEmacs;
-it's best to exit XEmacs before upgrading an existing package.
-
- To install binary packages manually:
-
- 1. Download the package(s) that you want to install. Each binary
- package will typically be a gzip'd tarball.
-
- 2. Decide where to install the packages: in the system package
- directory, or in `~/.xemacs/mule-packages' or
- `~/.xemacs/xemacs-packages', respectively. If you want to install
- the packages in the system package directory, make sure you can
- write into that directory. If you want to install in your `$HOME'
- directory, create the directory, `~/.xemacs/mule-packages' or
- `~/.xemacs/xemacs-packages', respectively.
-
- 3. Next, `cd' to the directory under which you want to install the
- package(s).
-
- 4. From this directory, uncompress and extract each of the gzip'd
- tarballs that you downloaded in step 1. Unix and Cygnus cygwin
- users will typically do this using the commands:
-
- gunzip < package.tar.gz | tar xvf -
-
- Above, replace `package.tar.gz' with the filename of the package
- that you downloaded in step 1.
-
- Of course, if you use GNU `tar', you could also use:
-
- tar xvzf package.tar.gz
-
- 5. That's it. Quit and restart XEmacs to get it to recognize any new
- or changed packages.
-
-
-\1f
-File: xemacs.info, Node: Building Packages, Prev: Using Packages, Up: Packages
-
- Source packages are available from the `packages/source-packages'
-subdirectory of your favorite XEmacs distribution site. Alternatively,
-they are available via CVS from `cvs.xemacs.org'. Look at
-`http://cvs.xemacs.org' for instructions.
-
-Prerequisites for Building Source Packages
-------------------------------------------
-
- You must have GNU `cp', GNU `install' (or a BSD compatible `install'
-program) GNU `make' (3.75 or later preferred), `makeinfo' (1.68 from
-`texinfo-3.11' or later required), GNU `tar' and XEmacs 21.0. The
-source packages will untar into a correct directory structure. At the
-top level you must have `XEmacs.rules' and `package-compile.el'. These
-files are available from the XEmacs FTP site from the same place you
-obtained your source package distributions.
-
-What You Can Do With Source Packages
-------------------------------------
-
- NB: A global build operation doesn't exist yet as of 13 January
-1998.
-
- Source packages are most useful for creating XEmacs package tarballs
-for installation into your own XEmacs installations or for distributing
-to others.
-
- Supported operations from `make' are:
-
-`clean'
- Remove all built files except `auto-autoloads.el' and
- `custom-load.el'.
-
-`distclean'
- Remove XEmacs backups as well as the files deleted by `make clean'.
-
-`all'
- Bytecompile all files, build and bytecompile byproduct files like
- `auto-autoloads.el' and `custom-load.el'. Create info version of
- TeXinfo documentation if present.
-
-`srckit'
- Usually aliased to `make srckit-std'. This does a `make
- distclean' and creates a package source tarball in the staging
- directory. This is generally only of use for package maintainers.
-
-`binkit'
- May be aliased to `binkit-sourceonly', `binkit-sourceinfo',
- `binkit-sourcedata', or `binkit-sourcedatainfo'. `sourceonly'
- indicates there is nothing to install in a data directory or info
- directory. `sourceinfo' indicates that source and info files are
- to be installed. `sourcedata' indicates that source and etc
- (data) files are to be installed. `sourcedatainfo' indicates
- source, etc (data), and info files are to be installed. A few
- packages have needs beyond the basic templates so this is not yet
- complete.
-
-`dist'
- Runs the rules `srckit' followed by `binkit'. This is primarily
- of use by XEmacs maintainers producing files for distribution.
-
-\1f
-File: xemacs.info, Node: Abbrevs, Next: Picture, Prev: Packages, Up: Top
-
-Abbrevs
-*******
-
- An "abbrev" is a word which "expands" into some different text.
-Abbrevs are defined by the user to expand in specific ways. For
-example, you might define `foo' as an abbrev expanding to `find outer
-otter'. With this abbrev defined, you would be able to get `find outer
-otter ' into the buffer by typing `f o o <SPC>'.
-
- Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
-Disabling Abbrev mode does not cause abbrev definitions to be discarded,
-but they do not expand until Abbrev mode is enabled again. The command
-`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it
-turns Abbrev mode on if the argument is positive, off otherwise. *Note
-Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on
-when the variable is non-`nil'. The variable `abbrev-mode'
-automatically becomes local to the current buffer when it is set.
-
- Abbrev definitions can be "mode-specific"--active only in one major
-mode. Abbrevs can also have "global" definitions that are active in
-all major modes. The same abbrev can have a global definition and
-various mode-specific definitions for different major modes. A
-mode-specific definition for the current major mode overrides a global
-definition.
-
- You can define Abbrevs interactively during an editing session. You
-can also save lists of abbrev definitions in files and reload them in
-later sessions. Some users keep extensive lists of abbrevs that they
-load in every session.
-
- A second kind of abbreviation facility is called the "dynamic
-expansion". Dynamic abbrev expansion happens only when you give an
-explicit command and the result of the expansion depends only on the
-current contents of the buffer. *Note Dynamic Abbrevs::.
-
-* Menu:
-
-* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
-* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
-* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
-* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
-* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
-
-\1f
-File: xemacs.info, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs
-
-Defining Abbrevs
-================
-
-`C-x a g'
- Define an abbrev to expand into some text before point
- (`add-global-abbrev').
-
-`C-x a l'
- Similar, but define an abbrev available only in the current major
- mode (`add-mode-abbrev').
-
-`C-x a i g'
- Define a word in the buffer as an abbrev
- (`inverse-add-global-abbrev').
-
-`C-x a i l'
- Define a word in the buffer as a mode-specific abbrev
- (`inverse-add-mode-abbrev').
-
-`M-x kill-all-abbrevs'
- After this command, no abbrev definitions remain in effect.
-
- The usual way to define an abbrev is to enter the text you want the
-abbrev to expand to, position point after it, and type `C-x a g'
-(`add-global-abbrev'). This reads the abbrev itself using the
-minibuffer, and then defines it as an abbrev for one or more words
-before point. Use a numeric argument to say how many words before point
-should be taken as the expansion. For example, to define the abbrev
-`foo' as in the example above, insert the text `find outer otter', then
-type
-`C-u 3 C-x a g f o o <RET>'.
-
- An argument of zero to `C-x a g' means to use the contents of the
-region as the expansion of the abbrev being defined.
-
- The command `C-x a l' (`add-mode-abbrev') is similar, but defines a
-mode-specific abbrev. Mode-specific abbrevs are active only in a
-particular major mode. `C-x a l' defines an abbrev for the major mode
-in effect at the time `C-x a l' is typed. The arguments work the same
-way they do for `C-x a g'.
-
- If the text of an abbrev you want is already in the buffer instead of
-the expansion, use command `C-x a i g' (`inverse-add-global-abbrev')
-instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev')
-instead of `C-x a l'. These commands are called "inverse" because they
-invert the meaning of the argument found in the buffer and the argument
-read using the minibuffer.
-
- To change the definition of an abbrev, just add the new definition.
-You will be asked to confirm if the abbrev has a prior definition. To
-remove an abbrev definition, give a negative argument to `C-x a g' or
-`C-x a l'. You must choose the command to specify whether to kill a
-global definition or a mode-specific definition for the current mode,
-since those two definitions are independent for one abbrev.
-
- `M-x kill-all-abbrevs' removes all existing abbrev definitions.
-
projects / chise / xemacs-chise.git- / blobdiff