-This is ../info/xemacs.info, produced by makeinfo version 3.12s 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.
+File: xemacs.info, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
+
+Pages
+=====
+
+ Files are often thought of as divided into "pages" by the "formfeed"
+character (ASCII Control-L, octal code 014). For example, if a file is
+printed on a line printer, each "page" of the file starts on a new page
+of paper. Emacs treats a page-separator character just like any other
+character. It can be inserted with `C-q C-l' or deleted with <DEL>.
+You are free to paginate your file or not. However, since pages are
+often meaningful divisions of the file, commands are provided to move
+over them and operate on them.
+
+`C-x ['
+ Move point to previous page boundary (`backward-page').
+
+`C-x ]'
+ Move point to next page boundary (`forward-page').
+
+`C-x C-p'
+ Put point and mark around this page (or another page)
+ (`mark-page').
+
+`C-x l'
+ Count the lines in this page (`count-lines-page').
+
+ The `C-x [' (`backward-page') command moves point to immediately
+after the previous page delimiter. If point is already right after a
+page delimiter, the command skips that one and stops at the previous
+one. A numeric argument serves as a repeat count. The `C-x ]'
+(`forward-page') command moves forward past the next page delimiter.
+
+ The `C-x C-p' command (`mark-page') puts point at the beginning of
+the current page and the mark at the end. The page delimiter at the end
+is included (the mark follows it). The page delimiter at the front is
+excluded (point follows it). You can follow this command by `C-w' to
+kill a page you want to move elsewhere. If you insert the page after a
+page delimiter, at a place where `C-x ]' or `C-x [' would take you, the
+page will be properly delimited before and after once again.
+
+ A numeric argument to `C-x C-p' is used to specify which page to go
+to, relative to the current one. Zero means the current page. One
+means the next page, and -1 means the previous one.
+
+ The `C-x l' command (`count-lines-page') can help you decide where
+to break a page in two. It prints the total number of lines in the
+current page in the echo area, then divides the lines into those
+preceding the current line and those following it, for example
+
+ Page has 96 (72+25) lines
+
+Notice that the sum is off by one; this is correct if point is not at
+the beginning of a line.
+
+ The variable `page-delimiter' should have as its value a regexp that
+matches the beginning of a line that separates pages. This defines
+where pages begin. The normal value of this variable is `"^\f"', which
+matches a formfeed character at the beginning of a line.
\1f
-File: xemacs.info, Node: Tags, Next: Fortran, Prev: Change Log, Up: Programs
+File: xemacs.info, Node: Filling, Next: Case, Prev: Pages, Up: Text
-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.
+Filling Text
+============
- 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".
+ If you use Auto Fill mode, Emacs "fills" text (breaks it up into
+lines that fit in a specified width) as you insert it. When you alter
+existing text it is often no longer be properly filled afterwards and
+you can use explicit commands for filling.
* 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, Prev: Tags, 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.
-
- * 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 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.
+* Auto Fill:: Auto Fill mode breaks long lines automatically.
+* Fill Commands:: Commands to refill paragraphs and center lines.
+* Fill Prefix:: Filling when every line is indented or in a comment, etc.
\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.
+File: xemacs.info, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
+
+Auto Fill Mode
+--------------
+
+ "Auto Fill" mode is a minor mode in which lines are broken
+automatically when they become too wide. Breaking happens only when
+you type a <SPC> or <RET>.
+
+`M-x auto-fill-mode'
+ Enable or disable Auto Fill mode.
+
+`<SPC>'
+`<RET>'
+ In Auto Fill mode, break lines when appropriate.
+
+ `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off
+if it was on. With a positive numeric argument the command always turns
+Auto Fill mode on, and with a negative argument it always turns it off.
+The presence of the word `Fill' in the mode line, inside the
+parentheses, indicates that Auto Fill mode is in effect. Auto Fill mode
+is a minor mode; you can turn it on or off for each buffer individually.
+*Note Minor Modes::.
+
+ In Auto Fill mode, lines are broken automatically at spaces when
+they get longer than desired. Line breaking and rearrangement takes
+place only when you type <SPC> or <RET>. To insert a space or newline
+without permitting line-breaking, type `C-q <SPC>' or `C-q <LFD>'
+(recall that a newline is really a linefeed). `C-o' inserts a newline
+without line breaking.
+
+ Auto Fill mode works well with Lisp mode: when it makes a new line in
+Lisp mode, it indents that line with <TAB>. If a line ending in a Lisp
+comment gets too long, the text of the comment is split into two
+comment lines. Optionally, new comment delimiters are inserted at the
+end of the first line and the beginning of the second, so that each line
+is a separate comment. The variable `comment-multi-line' controls the
+choice (*note Comments::).
+
+ Auto Fill mode does not refill entire paragraphs. It can break
+lines but cannot merge lines. Editing in the middle of a paragraph can
+result in a paragraph that is not correctly filled. The easiest way to
+make the paragraph properly filled again is using an explicit fill
+commands.
+
+ Many users like Auto Fill mode and want to use it in all text files.
+The section on init files explains how you can arrange this permanently
+for yourself. *Note Init File::.
\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
+File: xemacs.info, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
-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.
+Explicit Fill Commands
+----------------------
- --regex=@first-file --ignore-case-regex=@second-file
+`M-q'
+ Fill current paragraph (`fill-paragraph').
-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):
+`M-g'
+ Fill each paragraph in the region (`fill-region').
- -- This is for GNU Emacs source files
- {c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
+`C-x f'
+ Set the fill column (`set-fill-column').
-and then use it like this:
+`M-x fill-region-as-paragraph'
+ Fill the region, considering it as one paragraph.
- etags --regex=@emacs.tags *.[ch] */*.[ch]
+`M-s'
+ Center a line.
- Here are some more examples. The regexps are quoted to protect them
-from shell interpretation.
+ To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
+It causes the paragraph containing point, or the one after point if
+point is between paragraphs, to be refilled. All line breaks are
+removed, and new ones are inserted where necessary. `M-q' can be
+undone with `C-_'. *Note Undo::.
- * Tag Octave files:
+ To refill many paragraphs, use `M-g' (`fill-region'), which divides
+the region into paragraphs and fills each of them.
- etags --language=none \
- --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
- --regex='/###key \(.*\)/\1/' \
- --regex='/[ \t]*global[ \t].*/' \
- *.m
+ `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
+paragraph boundaries (*note Paragraphs::). For more control, you can
+use `M-x fill-region-as-paragraph', which refills everything between
+point and mark. This command recognizes only blank lines as paragraph
+separators.
- 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.
+ A numeric argument to `M-g' or `M-q' causes it to "justify" the text
+as well as filling it. Extra spaces are inserted to make the right
+margin line up exactly at the fill column. To remove the extra spaces,
+use `M-q' or `M-g' with no argument.
- * Tag Tcl files:
+ The variable `auto-fill-inhibit-regexp' takes as a value a regexp to
+match lines that should not be auto-filled.
- etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
+ The command `Meta-s' (`center-line') centers the current line within
+the current fill column. With an argument, it centers several lines
+individually and moves past them.
- * Tag VHDL files:
+ The maximum line width for filling is in the variable `fill-column'.
+Altering the value of `fill-column' makes it local to the current
+buffer; until then, the default value--initially 70--is in effect.
+*Note Locals::.
- --language=none \
- --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
- --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
- \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
+ The easiest way to set `fill-column' is to use the command `C-x f'
+(`set-fill-column'). With no argument, it sets `fill-column' to the
+current horizontal position of point. With a numeric argument, it uses
+that number as the new fill column.
\1f
-File: xemacs.info, Node: Select Tags Table, Next: Find Tag, Prev: Etags Regexps, Up: Tags
+File: xemacs.info, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
-Selecting a Tags Table
-----------------------
+The Fill Prefix
+---------------
- 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'.
+ To fill a paragraph in which each line starts with a special marker
+(which might be a few spaces, giving an indented paragraph), use the
+"fill prefix" feature. The fill prefix is a string which is not
+included in filling. Emacs expects every line to start with a fill
+prefix.
+
+`C-x .'
+ Set the fill prefix (`set-fill-prefix').
+
+`M-q'
+ Fill a paragraph using current fill prefix (`fill-paragraph').
+
+`M-x fill-individual-paragraphs'
+ Fill the region, considering each change of indentation as
+ starting a new paragraph.
+
+ To specify a fill prefix, move to a line that starts with the desired
+prefix, put point at the end of the prefix, and give the command
+`C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
+off the fill prefix, specify an empty prefix: type `C-x .' with point
+at the beginning of a line.
+
+ When a fill prefix is in effect, the fill commands remove the fill
+prefix from each line before filling and insert it on each line after
+filling. Auto Fill mode also inserts the fill prefix inserted on new
+lines it creates. Lines that do not start with the fill prefix are
+considered to start paragraphs, both in `M-q' and the paragraph
+commands; this is just right if you are using paragraphs with hanging
+indentation (every line indented except the first one). Lines which are
+blank or indented once the prefix is removed also separate or start
+paragraphs; this is what you want if you are writing multi-paragraph
+comments with a comment delimiter on each line.
+
+ The fill prefix is stored in the variable `fill-prefix'. Its value
+is a string, or `nil' when there is no fill prefix. This is a
+per-buffer variable; altering the variable affects only the current
+buffer, but there is a default value which you can change as well.
+*Note Locals::.
+
+ Another way to use fill prefixes is through `M-x
+fill-individual-paragraphs'. This function divides the region into
+groups of consecutive lines with the same amount and kind of
+indentation and fills each group as a paragraph, using its indentation
+as a fill prefix.
\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.
+File: xemacs.info, Node: Case, Prev: Filling, Up: Text
- 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-.'.
+Case Conversion Commands
+========================
- 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.
+ Emacs has commands for converting either a single word or any
+arbitrary range of text to upper case or to lower case.
- Variables of note include the following:
+`M-l'
+ Convert following word to lower case (`downcase-word').
-`tag-table-alist'
- Controls which tables apply to which buffers.
+`M-u'
+ Convert following word to upper case (`upcase-word').
-`tags-file-name'
- Stores a default tags table.
+`M-c'
+ Capitalize the following word (`capitalize-word').
-`tags-build-completion-table'
- Controls completion behavior.
+`C-x C-l'
+ Convert region to lower case (`downcase-region').
-`buffer-tag-table'
- Specifies a buffer-local table.
+`C-x C-u'
+ Convert region to upper case (`upcase-region').
-`make-tags-files-invisible'
- Sets whether tags tables should be very hidden.
+ The word conversion commands are used most frequently. `Meta-l'
+(`downcase-word') converts the word after point to lower case, moving
+past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
+(`upcase-word') converts to all capitals instead, while `Meta-c'
+(`capitalize-word') puts the first letter of the word into upper case
+and the rest into lower case. The word conversion commands convert
+several words at once if given an argument. They are especially
+convenient for converting a large amount of text from all upper case to
+mixed case: you can move through the text using `M-l', `M-u', or `M-c'
+on each word as appropriate, occasionally using `M-f' instead to skip a
+word.
-`tag-mark-stack-max'
- Specifies how many tags-based hops to remember.
+ When given a negative argument, the word case conversion commands
+apply to the appropriate number of words before point, but do not move
+point. This is convenient when you have just typed a word in the wrong
+case: you can give the case conversion command and continue typing.
- 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.)
+ If a word case conversion command is given in the middle of a word,
+it applies only to the part of the word which follows point. This is
+just like what `Meta-d' (`kill-word') does. With a negative argument,
+case conversion applies only to the part of the word before point.
- 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.
+ The other case conversion commands are `C-x C-u' (`upcase-region')
+and `C-x C-l' (`downcase-region'), which convert everything between
+point and mark to the specified case. Point and mark do not move.
\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.
+File: xemacs.info, Node: Programs, Next: Running, Prev: Text, Up: Top
- 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.
+Editing Programs
+****************
- 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::.
+ Emacs has many commands designed to understand the syntax of
+programming languages such as Lisp and C. These commands can:
- 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'.
+ * Move over or kill balanced expressions or "sexps" (*note Lists::).
-`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.
+ * Move over or mark top-level balanced expressions ("defuns", in
+ Lisp; functions, in C).
-`M-x next-file'
- Visit the next file in the selected tags table.
+ * Show how parentheses balance (*note Matching::).
-\1f
-File: xemacs.info, Node: List Tags, Prev: Tags Search, Up: Tags
+ * Insert, kill, or align comments (*note Comments::).
-Tags Table Inquiries
---------------------
+ * Follow the usual indentation conventions of the language (*note
+ Grinding::).
-`M-x list-tags'
- Display a list of the tags defined in a specific program file.
+ The commands available for words, sentences, and paragraphs are
+useful in editing code even though their canonical application is for
+editing human language text. Most symbols contain words (*note
+Words::); sentences can be found in strings and comments (*note
+Sentences::). Paragraphs per se are not present in code, but the
+paragraph commands are useful anyway, because Lisp mode and C mode
+define paragraphs to begin and end at blank lines (*note Paragraphs::).
+Judicious use of blank lines to make the program clearer also provides
+interesting chunks of text for the paragraph commands to work on.
-`M-x tags-apropos'
- Display a list of all tags matching a specified regexp.
+ The selective display feature is useful for looking at the overall
+structure of a function (*note Selective Display::). This feature
+causes only the lines that are indented less than a specified amount to
+appear on the screen.
- `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.
+* Menu:
- `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.
+* Program Modes:: Major modes for editing programs.
+* Lists:: Expressions with balanced parentheses.
+ There are editing commands to operate on them.
+* Defuns:: Each program is made up of separate functions.
+ There are editing commands to operate on them.
+* Grinding:: Adjusting indentation to show the nesting.
+* Matching:: Insertion of a close-delimiter flashes matching open.
+* Comments:: Inserting, filling and aligning comments.
+* Balanced Editing:: Inserting two matching parentheses at once, etc.
+* Lisp Completion:: Completion on symbol names in Lisp code.
+* Documentation:: Getting documentation of functions you plan to call.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go direct to any function in your program in one
+ command. Tags remembers which file it is in.
+* Fortran:: Fortran mode and its special features.
+* Asm Mode:: Asm mode and its special features.
\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.
+File: xemacs.info, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
+
+Major Modes for Programming Languages
+=====================================
+
+ Emacs has several major modes for the programming languages Lisp,
+Scheme (a variant of Lisp), C, Fortran, and Muddle. Ideally, a major
+mode should be implemented for each programming language you might want
+to edit with Emacs; but often the mode for one language can serve for
+other syntactically similar languages. The language modes that exist
+are those that someone decided to take the trouble to write.
+
+ There are several variants of Lisp mode, which differ in the way they
+interface to Lisp execution. *Note Lisp Modes::.
+
+ Each of the programming language modes defines the <TAB> key to run
+an indentation function that knows the indentation conventions of that
+language and updates the current line's indentation accordingly. For
+example, in C mode <TAB> is bound to `c-indent-line'. <LFD> is
+normally defined to do <RET> followed by <TAB>; thus it, too, indents
+in a mode-specific fashion.
+
+ In most programming languages, indentation is likely to vary from
+line to line. So the major modes for those languages rebind <DEL> to
+treat a tab as if it were the equivalent number of spaces (using the
+command `backward-delete-char-untabify'). This makes it possible to
+rub out indentation one column at a time without worrying whether it is
+made up of spaces or tabs. In these modes, use `C-b C-d' to delete a
+tab character before point.
+
+ Programming language modes define paragraphs to be separated only by
+blank lines, so that the paragraph commands remain useful. Auto Fill
+mode, if enabled in a programming language major mode, indents the new
+lines which it creates.
+
+ Turning on a major mode calls a user-supplied function called the
+"mode hook", which is the value of a Lisp variable. For example,
+turning on C mode calls the value of the variable `c-mode-hook' if that
+value exists and is non-`nil'. Mode hook variables for other
+programming language modes include `lisp-mode-hook',
+`emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
+`scheme-mode-hook', and `muddle-mode-hook'. The mode hook function
+receives no arguments.
- 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: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
+
+Lists and Sexps
+===============
+
+ By convention, Emacs keys for dealing with balanced expressions are
+usually `Control-Meta-' characters. They tend to be analogous in
+function to their `Control-' and `Meta-' equivalents. These commands
+are usually thought of as pertaining to expressions in programming
+languages, but can be useful with any language in which some sort of
+parentheses exist (including English).
+
+ The commands fall into two classes. Some commands deal only with
+"lists" (parenthetical groupings). They see nothing except
+parentheses, brackets, braces (depending on what must balance in the
+language you are working with), and escape characters that might be used
+to quote those.
+
+ The other commands deal with expressions or "sexps". The word `sexp'
+is derived from "s-expression", the term for a symbolic expression in
+Lisp. In Emacs, the notion of `sexp' is not limited to Lisp. It
+refers to an expression in the language your program is written in.
+Each programming language has its own major mode, which customizes the
+syntax tables so that expressions in that language count as sexps.
+
+ Sexps typically include symbols, numbers, and string constants, as
+well as anything contained in parentheses, brackets, or braces.
+
+ In languages that use prefix and infix operators, such as C, it is
+not possible for all expressions to be sexps. For example, C mode does
+not recognize `foo + bar' as an sexp, even though it is a C expression;
+it recognizes `foo' as one sexp and `bar' as another, with the `+' as
+punctuation between them. This is a fundamental ambiguity: both `foo +
+bar' and `foo' are legitimate choices for the sexp to move over if
+point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
+
+ Some languages have obscure forms of syntax for expressions that
+nobody has bothered to make Emacs understand properly.
+
+`C-M-f'
+ Move forward over an sexp (`forward-sexp').
+
+`C-M-b'
+ Move backward over an sexp (`backward-sexp').
+
+`C-M-k'
+ Kill sexp forward (`kill-sexp').
+
+`C-M-u'
+ Move up and backward in list structure (`backward-up-list').
+
+`C-M-d'
+ Move down and forward in list structure (`down-list').
+
+`C-M-n'
+ Move forward over a list (`forward-list').
+
+`C-M-p'
+ Move backward over a list (`backward-list').
+
+`C-M-t'
+ Transpose expressions (`transpose-sexps').
+
+`C-M-@'
+ Put mark after following expression (`mark-sexp').
+
+ To move forward over an sexp, use `C-M-f' (`forward-sexp'). If the
+first significant character after point is an opening delimiter (`(' in
+Lisp; `(', `[', or `{' in C), `C-M-f' moves past the matching closing
+delimiter. If the character begins a symbol, string, or number,
+`C-M-f' moves over that. If the character after point is a closing
+delimiter, `C-M-f' just moves past it. (This last is not really moving
+across an sexp; it is an exception which is included in the definition
+of `C-M-f' because it is as useful a behavior as anyone can think of
+for that situation.)
+
+ The command `C-M-b' (`backward-sexp') moves backward over a sexp.
+The detailed rules are like those above for `C-M-f', but with
+directions reversed. If there are any prefix characters (single quote,
+back quote, and comma, in Lisp) preceding the sexp, `C-M-b' moves back
+over them as well.
+
+ `C-M-f' or `C-M-b' with an argument repeats that operation the
+specified number of times; with a negative argument, it moves in the
+opposite direction.
+
+ In languages such as C where the comment-terminator can be
+recognized, the sexp commands move across comments as if they were
+whitespace. In Lisp and other languages where comments run until the
+end of a line, it is very difficult to ignore comments when parsing
+backwards; therefore, in such languages the sexp commands treat the
+text of comments as if it were code.
+
+ Killing an sexp at a time can be done with `C-M-k' (`kill-sexp').
+`C-M-k' kills the characters that `C-M-f' would move over.
+
+ The "list commands", `C-M-n' (`forward-list') and `C-M-p'
+(`backward-list'), move over lists like the sexp commands but skip over
+any number of other kinds of sexps (symbols, strings, etc). In some
+situations, these commands are useful because they usually ignore
+comments, since the comments usually do not contain any lists.
+
+ `C-M-n' and `C-M-p' stay at the same level in parentheses, when that
+is possible. To move up one (or N) levels, use `C-M-u'
+(`backward-up-list'). `C-M-u' moves backward up past one unmatched
+opening delimiter. A positive argument serves as a repeat count; a
+negative argument reverses direction of motion and also requests
+repetition, so it moves forward and up one or more levels.
+
+ To move down in list structure, use `C-M-d' (`down-list'). In Lisp
+mode, where `(' is the only opening delimiter, this is nearly the same
+as searching for a `('. An argument specifies the number of levels of
+parentheses to go down.
+
+ `C-M-t' (`transpose-sexps') drags the previous sexp across the next
+one. An argument serves as a repeat count, and a negative argument
+drags backwards (thus canceling out the effect of `C-M-t' with a
+positive argument). An argument of zero, rather than doing nothing,
+transposes the sexps ending after point and the mark.
+
+ To make the region be the next sexp in the buffer, use `C-M-@'
+(`mark-sexp') which sets the mark at the same place that `C-M-f' would
+move to. `C-M-@' takes arguments like `C-M-f'. In particular, a
+negative argument is useful for putting the mark at the beginning of
+the previous sexp.
+
+ The list and sexp commands' understanding of syntax is completely
+controlled by the syntax table. Any character can, for example, be
+declared to be an opening delimiter and act like an open parenthesis.
+*Note Syntax::.
\1f
-File: xemacs.info, Node: Fortran Motion, Next: Fortran Indent, Prev: Fortran, Up: Fortran
+File: xemacs.info, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
-Motion Commands
----------------
+Defuns
+======
- 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.
+ In Emacs, a parenthetical grouping at the top level in the buffer is
+called a "defun". The name derives from the fact that most top-level
+lists in Lisp are instances of the special form `defun', but Emacs
+calls any top-level parenthetical grouping counts a defun regardless of
+its contents or the programming language. For example, in C, the body
+of a function definition is a defun.
`C-M-a'
- Move to beginning of subprogram
- (`beginning-of-fortran-subprogram').
+ Move to beginning of current or preceding defun
+ (`beginning-of-defun').
`C-M-e'
- Move to end of subprogram (`end-of-fortran-subprogram').
+ Move to end of current or following defun (`end-of-defun').
`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').
+ Put region around whole current or following defun (`mark-defun').
+
+ The commands to move to the beginning and end of the current defun
+are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
+
+ To operate on the current defun, use `C-M-h' (`mark-defun') which
+puts point at the beginning and the mark at the end of the current or
+next defun. This is the easiest way to prepare for moving the defun to
+a different place. In C mode, `C-M-h' runs the function
+`mark-c-function', which is almost the same as `mark-defun', but which
+backs up over the argument declarations, function name, and returned
+data type so that the entire C function is inside the region.
+
+ To compile and evaluate the current defun, use `M-x compile-defun'.
+This function prints the results in the minibuffer. If you include an
+argument, it inserts the value in the current buffer after the defun.
+
+ Emacs assumes that any open-parenthesis found in the leftmost column
+is the start of a defun. Therefore, never put an open-parenthesis at
+the left margin in a Lisp file unless it is the start of a top level
+list. Never put an open-brace or other opening delimiter at the
+beginning of a line of C code unless it starts the body of a function.
+The most likely problem case is when you want an opening delimiter at
+the start of a line inside a string. To avoid trouble, put an escape
+character (`\' in C and Emacs Lisp, `/' in some other Lisp dialects)
+before the opening delimiter. It will not affect the contents of the
+string.
+
+ The original Emacs found defuns by moving upward a level of
+parentheses until there were no more levels to go up. This required
+scanning back to the beginning of the buffer for every function. To
+speed this up, Emacs was changed to assume that any `(' (or other
+character assigned the syntactic class of opening-delimiter) at the
+left margin is the start of a defun. This heuristic is nearly always
+right; however, it mandates the convention described above.
\1f
-File: xemacs.info, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran
+File: xemacs.info, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
-Fortran Indentation
--------------------
+Indentation for Programs
+========================
- 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.
+ The best way to keep a program properly indented ("ground") is to
+use Emacs to re-indent it as you change the program. Emacs has commands
+to indent properly either a single line, a specified number of lines, or
+all of the lines inside a single parenthetical grouping.
* 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.
+* Basic Indent::
+* Multi-line Indent:: Commands to reindent many lines at once.
+* Lisp Indent:: Specifying how each Lisp function should be indented.
+* C Indent:: Choosing an indentation style for C code.
\1f
-File: xemacs.info, Node: ForIndent Commands, Next: ForIndent Num, Prev: Fortran Indent, Up: Fortran Indent
+File: xemacs.info, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
-Fortran Indentation Commands
-............................
+Basic Program Indentation Commands
+----------------------------------
`<TAB>'
- Indent the current line (`fortran-indent-line').
+ Adjust indentation of current line.
-`M-<LFD>'
- Break the current line and set up a continuation line.
+`<LFD>'
+ Equivalent to <RET> followed by <TAB> (`newline-and-indent').
+
+ The basic indentation command is <TAB>, which gives the current line
+the correct indentation as determined from the previous lines. The
+function that <TAB> runs depends on the major mode; it is
+`lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
+functions understand different syntaxes for different languages, but
+they all do about the same thing. <TAB> in any programming language
+major mode inserts or deletes whitespace at the beginning of the
+current line, independent of where point is in the line. If point is
+inside the whitespace at the beginning of the line, <TAB> leaves it at
+the end of that whitespace; otherwise, <TAB> leaves point fixed with
+respect to the characters around it.
+
+ Use `C-q <TAB>' to insert a tab at point.
+
+ When entering a large amount of new code, use <LFD>
+(`newline-and-indent'), which is equivalent to a <RET> followed by a
+<TAB>. <LFD> creates a blank line, then gives it the appropriate
+indentation.
+
+ <TAB> indents the second and following lines of the body of a
+parenthetical grouping each under the preceding one; therefore, if you
+alter one line's indentation to be nonstandard, the lines below tend to
+follow it. This is the right behavior in cases where the standard
+result of <TAB> does not look good.
+
+ Remember that Emacs assumes that an open-parenthesis, open-brace, or
+other opening delimiter at the left margin (including the indentation
+routines) is the start of a function. You should therefore never have
+an opening delimiter in column zero that is not the beginning of a
+function, not even inside a string. This restriction is vital for
+making the indentation commands fast. *Note Defuns::, for more
+information on this behavior.
-`C-M-q'
- Indent all the lines of the subprogram point is in
- (`fortran-indent-subprogram').
+\1f
+File: xemacs.info, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
- <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.
+Indenting Several Lines
+-----------------------
- 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.
+ Several commands are available to re-indent several lines of code
+which have been altered or moved to a different level in a list
+structure.
- 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.
+`C-M-q'
+ Re-indent all the lines within one list (`indent-sexp').
+
+`C-u <TAB>'
+ Shift an entire list rigidly sideways so that its first line is
+ properly indented.
+
+`C-M-\'
+ Re-indent all lines in the region (`indent-region').
+
+ To re-indent the contents of a single list, position point before the
+beginning of it and type `C-M-q'. This key is bound to `indent-sexp' in
+Lisp mode, `indent-c-exp' in C mode, and bound to other suitable
+functions in other modes. The indentation of the line the sexp starts
+on is not changed; therefore, only the relative indentation within the
+list, and not its position, is changed. To correct the position as
+well, type a <TAB> before `C-M-q'.
+
+ If the relative indentation within a list is correct but the
+indentation of its beginning is not, go to the line on which the list
+begins and type `C-u <TAB>'. When you give <TAB> a numeric argument,
+it moves all the lines in the group, starting on the current line,
+sideways the same amount that the current line moves. The command does
+not move lines that start inside strings, or C preprocessor lines when
+in C mode.
+
+ Another way to specify a range to be re-indented is with point and
+mark. The command `C-M-\' (`indent-region') applies <TAB> to every
+line whose first character is between point and mark.
\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.
+File: xemacs.info, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
-\1f
-File: xemacs.info, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent
+Customizing Lisp Indentation
+----------------------------
+
+ The indentation pattern for a Lisp expression can depend on the
+function called by the expression. For each Lisp function, you can
+choose among several predefined patterns of indentation, or define an
+arbitrary one with a Lisp program.
-Syntactic Conventions
-.....................
+ The standard pattern of indentation is as follows: the second line
+of the expression is indented under the first argument, if that is on
+the same line as the beginning of the expression; otherwise, the second
+line is indented underneath the function name. Each following line is
+indented under the previous line whose nesting depth is the same.
- Fortran mode assumes that you follow certain conventions that
-simplify the task of understanding a Fortran program well enough to
-indent it properly:
+ If the variable `lisp-indent-offset' is non-`nil', it overrides the
+usual indentation pattern for the second line of an expression, so that
+such lines are always indented `lisp-indent-offset' more columns than
+the containing list.
- * Two nested `do' loops never share a `continue' statement.
+ Certain functions override the standard pattern. Functions whose
+names start with `def' always indent the second line by
+`lisp-body-indention' extra columns beyond the open-parenthesis
+starting the expression.
- * 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 `$'.
+ Individual functions can override the standard pattern in various
+ways, according to the `lisp-indent-function' property of the function
+name. (Note: `lisp-indent-function' was formerly called
+`lisp-indent-hook'). There are four possibilities for this property:
-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.
+`nil'
+ This is the same as no property; the standard indentation pattern
+ is used.
+
+`defun'
+ The pattern used for function names that start with `def' is used
+ for this function also.
+
+a number, NUMBER
+ The first NUMBER arguments of the function are "distinguished"
+ arguments; the rest are considered the "body" of the expression.
+ A line in the expression is indented according to whether the
+ first argument on it is distinguished or not. If the argument is
+ part of the body, the line is indented `lisp-body-indent' more
+ columns than the open-parenthesis starting the containing
+ expression. If the argument is distinguished and is either the
+ first or second argument, it is indented twice that many extra
+ columns. If the argument is distinguished and not the first or
+ second argument, the standard pattern is followed for that line.
+
+a symbol, SYMBOL
+ SYMBOL should be a function name; that function is called to
+ calculate the indentation of a line within this expression. The
+ function receives two arguments:
+ STATE
+ The value returned by `parse-partial-sexp' (a Lisp primitive
+ for indentation and nesting computation) when it parses up to
+ the beginning of this line.
+
+ POS
+ The position at which the line being indented begins.
+
+ It should return either a number, which is the number of columns of
+ indentation for that line, or a list whose first element is such a
+ number. The difference between returning a number and returning a
+ list is that a number says that all following lines at the same
+ nesting level should be indented just like this one; a list says
+ that following lines might call for different indentations. This
+ makes a difference when the indentation is computed by `C-M-q'; if
+ the value is a number, `C-M-q' need not recalculate indentation
+ for the following lines until the end of the list.
\1f
-File: xemacs.info, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent
+File: xemacs.info, Node: C Indent, Prev: Lisp Indent, Up: Grinding
-Variables for Fortran Indentation
-.................................
+Customizing C Indentation
+-------------------------
- Several additional variables control how Fortran indentation works.
+ Two variables control which commands perform C indentation and when.
-`fortran-do-indent'
- Extra indentation within each level of `do' statement (the default
- is 3).
+ If `c-auto-newline' is non-`nil', newlines are inserted both before
+and after braces that you insert and after colons and semicolons.
+Correct C indentation is done on all the lines that are made this way.
-`fortran-if-indent'
- Extra indentation within each level of `if' statement (the default
- is 3).
+ If `c-tab-always-indent' is non-`nil', the <TAB> command in C mode
+does indentation only if point is at the left margin or within the
+line's indentation. If there is non-whitespace to the left of point,
+<TAB> just inserts a tab character in the buffer. Normally, this
+variable is `nil', and <TAB> always reindents the current line.
-`fortran-continuation-indent'
- Extra indentation for bodies of continuation lines (the default is
- 5).
+ C does not have anything analogous to particular function names for
+which special forms of indentation are desirable. However, it has a
+different need for customization facilities: many different styles of C
+indentation are in common use.
-`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'.
+ There are six variables you can set to control the style that Emacs C
+mode will use.
-`fortran-minimum-statement-indent'
- Minimum indentation for Fortran statements. For standard Fortran,
- this is 6. Statement bodies are always indented at least this
- much.
+`c-indent-level'
+ Indentation of C statements within surrounding block. The
+ surrounding block's indentation is the indentation of the line on
+ which the open-brace appears.
-\1f
-File: xemacs.info, Node: Fortran Comments, Next: Fortran Columns, Prev: Fortran Indent, Up: Fortran
+`c-continued-statement-offset'
+ Extra indentation given to a substatement, such as the then-clause
+ of an `if' or body of a `while'.
-Comments
---------
+`c-brace-offset'
+ Extra indentation for lines that start with an open brace.
- 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.
+`c-brace-imaginary-offset'
+ An open brace following other text is treated as if it were this
+ far to the right of the start of its line.
- 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::).
+`c-argdecl-indent'
+ Indentation level of declarations of C function arguments.
-`M-;'
- Align comment or insert new comment (`fortran-comment-indent').
+`c-label-offset'
+ Extra indentation for a line that is a label, case, or default.
-`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.
+ The variable `c-indent-level' controls the indentation for C
+statements with respect to the surrounding block. In the example:
-`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.
+ {
+ foo ();
-\1f
-File: xemacs.info, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Comments, Up: Fortran
+the difference in indentation between the lines is `c-indent-level'.
+Its standard value is 2.
-Columns
--------
+ If the open-brace beginning the compound statement is not at the
+beginning of its line, the `c-indent-level' is added to the indentation
+of the line, not the column of the open-brace. For example,
-`C-c C-r'
- Displays a "column ruler" momentarily above the current line
- (`fortran-column-ruler').
+ if (losing) {
+ do_this ();
-`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').
+One popular indentation style is that which results from setting
+`c-indent-level' to 8 and putting open-braces at the end of a line in
+this way. Another popular style prefers to put the open-brace on a
+separate line.
- 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.
+ In fact, the value of the variable `c-brace-imaginary-offset' is
+also added to the indentation of such a statement. Normally this
+variable is zero. Think of this variable as the imaginary position of
+the open brace, relative to the first non-blank character on the line.
+By setting the variable to 4 and `c-indent-level' to 0, you can get
+this style:
- 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.
+ if (x == y) {
+ do_it ();
+ }
- 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.
+ When `c-indent-level' is zero, the statements inside most braces
+line up exactly under the open brace. An exception are braces in column
+zero, like those surrounding a function's body. The statements inside
+those braces are not placed at column zero. Instead, `c-brace-offset'
+and `c-continued-statement-offset' (see below) are added to produce a
+typical offset between brace levels, and the statements are indented
+that far.
- 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.
+ `c-continued-statement-offset' controls the extra indentation for a
+line that starts within a statement (but not within parentheses or
+brackets). These lines are usually statements inside other statements,
+like the then-clauses of `if' statements and the bodies of `while'
+statements. The `c-continued-statement-offset' parameter determines
+the difference in indentation between the two lines in:
-\1f
-File: xemacs.info, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran
+ if (x == y)
+ do_it ();
-Fortran Keyword Abbrevs
------------------------
+The default value for `c-continued-statement-offset' is 2. Some
+popular indentation styles correspond to a value of zero for
+`c-continued-statement-offset'.
- 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::.
+ `c-brace-offset' is the extra indentation given to a line that
+starts with an open-brace. Its standard value is zero; compare:
- 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".
+ if (x == y)
+ {
- 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.
+with:
- Type `;?' or `;C-h' to display a list of all built-in Fortran
-abbrevs and what they stand for.
+ if (x == y)
+ do_it ();
-\1f
-File: xemacs.info, Node: Asm Mode, Prev: Fortran, Up: Programs
+If you set `c-brace-offset' to 4, the first example becomes:
-Asm Mode
-========
+ if (x == y)
+ {
- Asm mode is a major mode for editing files of assembler code. It
-defines these commands:
+ `c-argdecl-indent' controls the indentation of declarations of the
+arguments of a C function. It is absolute: argument declarations
+receive exactly `c-argdecl-indent' spaces. The standard value is 5 and
+results in code like this:
-`<TAB>'
- `tab-to-tab-stop'.
+ char *
+ index (string, char)
+ char *string;
+ int char;
-`<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.
+ `c-label-offset' is the extra indentation given to a line that
+contains a label, a case statement, or a `default:' statement. Its
+standard value is -2 and results in code like this:
- The variable `asm-comment-char' specifies which character starts
-comments in assembler syntax.
+ switch (c)
+ {
+ case 'x':
-\1f
-File: xemacs.info, Node: Running, Next: Packages, Prev: Programs, Up: Top
+If `c-label-offset' were zero, the same code would be indented as:
-Compiling and Testing Programs
-******************************
+ switch (c)
+ {
+ case 'x':
- 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.
+This example assumes that the other variables above also have their
+default values.
-* Menu:
+ Using the indentation style produced by the default settings of the
+variables just discussed and putting open braces on separate lines
+produces clear and readable files. For an example, look at any of the C
+source files of XEmacs.
-* 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: Matching, Next: Comments, Prev: Grinding, Up: Programs
+
+Automatic Display of Matching Parentheses
+=========================================
+
+ The Emacs parenthesis-matching feature shows you automatically how
+parentheses match in the text. Whenever a self-inserting character that
+is a closing delimiter is typed, the cursor moves momentarily to the
+location of the matching opening delimiter, provided that is visible on
+the screen. If it is not on the screen, some text starting with that
+opening delimiter is displayed in the echo area. Either way, you see
+the grouping you are closing off.
+
+ In Lisp, automatic matching applies only to parentheses. In C, it
+also applies to braces and brackets. Emacs knows which characters to
+regard as matching delimiters based on the syntax table set by the major
+mode. *Note Syntax::.
+
+ If the opening delimiter and closing delimiter are mismatched--as in
+`[x)'--the echo area displays a warning message. The correct matches
+are specified in the syntax table.
+
+ Two variables control parenthesis matching displays.
+`blink-matching-paren' turns the feature on or off. The default is `t'
+(match display is on); `nil' turns it off.
+`blink-matching-paren-distance' specifies how many characters back
+Emacs searches to find a matching opening delimiter. If the match is
+not found in the specified region, scanning stops, and nothing is
+displayed. This prevents wasting lots of time scanning when there is no
+match. The default is 4000.
\1f
-File: xemacs.info, Node: Compilation, Next: Lisp Modes, Prev: Running, Up: Running
+File: xemacs.info, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs
-Running "make", or Compilers Generally
-======================================
+Manipulating Comments
+=====================
- 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 = ...
+ The comment commands insert, kill and align comments.
-\1f
-File: xemacs.info, Node: Lisp Modes, Next: Lisp Libraries, Prev: Compilation, Up: Running
+`M-;'
+ Insert or align comment (`indent-for-comment').
-Major Modes for Lisp
-====================
+`C-x ;'
+ Set comment column (`set-comment-column').
- 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.
+`C-u - C-x ;'
+ Kill comment on current line (`kill-comment').
-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::.
+`M-<LFD>'
+ Like <RET> followed by inserting and aligning a comment
+ (`indent-new-comment-line').
+
+ The command that creates a comment is `Meta-;'
+(`indent-for-comment'). If there is no comment already on the line, a
+new comment is created and aligned at a specific column called the
+"comment column". Emacs creates the comment by inserting the string at
+the value of `comment-start'; see below. Point is left after that
+string. If the text of the line extends past the comment column,
+indentation is done to a suitable boundary (usually, at least one space
+is inserted). If the major mode has specified a string to terminate
+comments, that string is inserted after point, to keep the syntax valid.
+
+ You can also use `Meta-;' to align an existing comment. If a line
+already contains the string that starts comments, `M-;' just moves
+point after it and re-indents it to the conventional place. Exception:
+comments starting in column 0 are not moved.
+
+ Some major modes have special rules for indenting certain kinds of
+comments in certain contexts. For example, in Lisp code, comments which
+start with two semicolons are indented as if they were lines of code,
+instead of at the comment column. Comments which start with three
+semicolons are supposed to start at the left margin. Emacs understands
+these conventions by indenting a double-semicolon comment using <TAB>
+and by not changing the indentation of a triple-semicolon comment at
+all.
+
+ ;; This function is just an example.
+ ;;; Here either two or three semicolons are appropriate.
+ (defun foo (x)
+ ;;; And now, the first part of the function:
+ ;; The following line adds one.
+ (1+ x)) ; This line adds one.
+
+ In C code, a comment preceded on its line by nothing but whitespace
+is indented like a line of code.
+
+ Even when an existing comment is properly aligned, `M-;' is still
+useful for moving directly to the start of the comment.
+
+ `C-u - C-x ;' (`kill-comment') kills the comment on the current
+line, if there is one. The indentation before the start of the comment
+is killed as well. If there does not appear to be a comment in the
+line, nothing happens. To reinsert the comment on another line, move
+to the end of that line, type first `C-y', and then `M-;' to realign
+the comment. Note that `C-u - C-x ;' is not a distinct key; it is `C-x
+;' (`set-comment-column') with a negative argument. That command is
+programmed to call `kill-comment' when called with a negative argument.
+However, `kill-comment' is a valid command which you could bind
+directly to a key if you wanted to.
+
+Multiple Lines of Comments
+--------------------------
+
+ If you are typing a comment and want to continue it on another line,
+use the command `Meta-<LFD>' (`indent-new-comment-line'), which
+terminates the comment you are typing, creates a new blank line
+afterward, and begins a new comment indented under the old one. If
+Auto Fill mode is on and you go past the fill column while typing, the
+comment is continued in just this fashion. If point is not at the end
+of the line when you type `M-<LFD>', the text on the rest of the line
+becomes part of the new comment line.
+
+Options Controlling Comments
+----------------------------
+
+ The comment column is stored in the variable `comment-column'. You
+can explicitly set it to a number. Alternatively, the command `C-x ;'
+(`set-comment-column') sets the comment column to the column point is
+at. `C-u C-x ;' sets the comment column to match the last comment
+before point in the buffer, and then calls `Meta-;' to align the
+current line's comment under the previous one. Note that `C-u - C-x ;'
+runs the function `kill-comment' as described above.
+
+ `comment-column' is a per-buffer variable; altering the variable
+affects only the current buffer. You can also change the default value.
+*Note Locals::. Many major modes initialize this variable for the
+current buffer.
-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::.
+ The comment commands recognize comments based on the regular
+expression that is the value of the variable `comment-start-skip'.
+This regexp should not match the null string. It may match more than
+the comment starting delimiter in the strictest sense of the word; for
+example, in C mode the value of the variable is `"/\\*+ *"', which
+matches extra stars and spaces after the `/*' itself. (Note that `\\'
+is needed in Lisp syntax to include a `\' in the string, which is needed
+to deny the first star its special meaning in regexp syntax. *Note
+Regexps::.)
+
+ When a comment command makes a new comment, it inserts the value of
+`comment-start' to begin it. The value of `comment-end' is inserted
+after point and will follow the text you will insert into the comment.
+In C mode, `comment-start' has the value `"/* "' and `comment-end' has
+the value `" */"'.
+
+ `comment-multi-line' controls how `M-<LFD>'
+(`indent-new-comment-line') behaves when used inside a comment. If
+`comment-multi-line' is `nil', as it normally is, then `M-<LFD>'
+terminates the comment on the starting line and starts a new comment on
+the new following line. If `comment-multi-line' is not `nil', then
+`M-<LFD>' sets up the new following line as part of the same comment
+that was found on the starting line. This is done by not inserting a
+terminator on the old line and not inserting a starter on the new line.
+In languages where multi-line comments are legal, the value you choose
+for this variable is a matter of taste.
+
+ The variable `comment-indent-hook' should contain a function that is
+called to compute the indentation for a newly inserted comment or for
+aligning an existing comment. Major modes set this variable
+differently. The function is called with no arguments, but with point
+at the beginning of the comment, or at the end of a line if a new
+comment is to be inserted. The function should return the column in
+which the comment ought to start. For example, in Lisp mode, the
+indent hook function bases its decision on the number of semicolons
+that begin an existing comment and on the code in the preceding lines.
-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::.
+\1f
+File: xemacs.info, Node: Balanced Editing, Next: Lisp Completion, Prev: Comments, Up: Programs
-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::).
+Editing Without Unbalanced Parentheses
+======================================
+
+`M-('
+ Put parentheses around next sexp(s) (`insert-parentheses').
-Scheme mode
- Like Lisp mode but for Scheme programs.
+`M-)'
+ Move past next close parenthesis and re-indent
+ (`move-over-close-and-reindent').
-Inferior Scheme mode
- The mode for an interactive session with an inferior Scheme
- process.
+ The commands `M-(' (`insert-parentheses') and `M-)'
+(`move-over-close-and-reindent') are designed to facilitate a style of
+editing which keeps parentheses balanced at all times. `M-(' inserts a
+pair of parentheses, either together as in `()', or, if given an
+argument, around the next several sexps, and leaves point after the open
+parenthesis. Instead of typing `( F O O )', you can type `M-( F O O',
+which has the same effect except for leaving the cursor before the
+close parenthesis. You can then type `M-)', which moves past the close
+parenthesis, deletes any indentation preceding it (in this example
+there is none), and indents with <LFD> after it.
\1f
-File: xemacs.info, Node: Lisp Libraries, Next: Lisp Eval, Prev: Lisp Modes, Up: Running
+File: xemacs.info, Node: Lisp Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs
-Libraries of Lisp Code for Emacs
-================================
+Completion for Lisp Symbols
+===========================
- 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::).
+ Completion usually happens in the minibuffer. An exception is
+completion for Lisp symbol names, which is available in all buffers.
-* Menu:
+ The command `M-<TAB>' (`lisp-complete-symbol') takes the partial
+Lisp symbol before point to be an abbreviation, and compares it against
+all non-trivial Lisp symbols currently known to Emacs. Any additional
+characters that they all have in common are inserted at point.
+Non-trivial symbols are those that have function definitions, values, or
+properties.
-* 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.
+ If there is an open-parenthesis immediately before the beginning of
+the partial symbol, only symbols with function definitions are
+considered as completions.
+
+ If the partial name in the buffer has more than one possible
+completion and they have no additional characters in common, a list of
+all possible completions is displayed in another window.
+
+\1f
+File: xemacs.info, Node: Documentation, Next: Change Log, Prev: Lisp Completion, Up: Programs
+
+Documentation Commands
+======================
+
+ As you edit Lisp code to be run in Emacs, you can use the commands
+`C-h f' (`describe-function') and `C-h v' (`describe-variable') to
+print documentation of functions and variables you want to call. These
+commands use the minibuffer to read the name of a function or variable
+to document, and display the documentation in a window.
+
+ For extra convenience, these commands provide default arguments
+based on the code in the neighborhood of point. `C-h f' sets the
+default to the function called in the innermost list containing point.
+`C-h v' uses the symbol name around or adjacent to point as its default.
+
+ The `M-x manual-entry' command gives you access to documentation on
+Unix commands, system calls, and libraries. The command reads a topic
+as an argument, and displays the Unix manual page for that topic.
+`manual-entry' always searches all 8 sections of the manual and
+concatenates all the entries it finds. For example, the topic
+`termcap' finds the description of the termcap library from section 3,
+followed by the description of the termcap data base from section 5.
projects / chise / xemacs-chise.git- / blobdiff