+++ /dev/null
-@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
-@c See file emacs.texi for copying conditions.
-@node Programs, Building, Text, Top
-@chapter Editing Programs
-@cindex Lisp editing
-@cindex C editing
-@cindex program editing
-
- Emacs provides many features to facilitate editing programs. Some
-of these features can
-
-@itemize @bullet
-@item
-Find or move over top-level definitions (@pxref{Defuns}).
-@item
-Apply the usual indentation conventions of the language
-(@pxref{Program Indent}).
-@item
-Balance parentheses (@pxref{Parentheses}).
-@item
-Insert, kill or align comments (@pxref{Comments}).
-@item
-Highlight program syntax (@pxref{Font Lock}).
-@end itemize
-
- This chapter describes these features and many more.
-
-@menu
-* Program Modes:: Major modes for editing programs.
-* Defuns:: Commands to operate on major top-level parts
- of a program.
-* Program Indent:: Adjusting indentation to show the nesting.
-* Parentheses:: Commands that operate on parentheses.
-* Comments:: Inserting, killing, and aligning comments.
-* Documentation:: Getting documentation of functions you plan to call.
-* Hideshow:: Displaying blocks selectively.
-* Symbol Completion:: Completion on symbol names of your program or language.
-* Glasses:: Making identifiersLikeThis more readable.
-* Misc for Programs:: Other Emacs features useful for editing programs.
-* C Modes:: Special commands of C, C++, Objective-C,
- Java, and Pike modes.
-* Fortran:: Fortran mode and its special features.
-* Asm Mode:: Asm mode and its special features.
-@end menu
-
-@node Program Modes
-@section Major Modes for Programming Languages
-@cindex modes for programming languages
-
- Emacs has specialized major modes for various programming languages.
-@xref{Major Modes}. A programming language major mode typically
-specifies the syntax of expressions, the customary rules for
-indentation, how to do syntax highlighting for the language, and how
-to find the beginning of a function definition. It often customizes
-or provides facilities for compiling and debugging programs as well.
-
- Ideally, Emacs should provide a major mode for each programming
-language that you might want to edit; if it doesn't have a mode for
-your favorite language, you can contribute one. But often the mode
-for one language can serve for other syntactically similar languages.
-The major mode for language @var{l} is called @code{@var{l}-mode},
-and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
-@xref{Choosing Modes}.
-
-@cindex Perl mode
-@cindex Icon mode
-@cindex Makefile mode
-@cindex Tcl mode
-@cindex CPerl mode
-@cindex DSSSL mode
-@cindex Octave mode
-@cindex Metafont mode
-@cindex Modula2 mode
-@cindex Prolog mode
-@cindex Python mode
-@cindex Simula mode
-@cindex VHDL mode
-@cindex M4 mode
-@cindex Shell-script mode
-@cindex Delphi mode
-@cindex PostScript mode
-@cindex Conf mode
-@cindex DNS mode
- The existing programming language major modes include Lisp, Scheme (a
-variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
-ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
-format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
-companion for font creation), Modula2, Objective-C, Octave, Pascal,
-Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An
-alternative mode for Perl is called CPerl mode. Modes are available for
-the scripting languages of the common GNU and Unix shells, VMS DCL, and
-MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
-editing makefiles, DNS master files, and various sorts of configuration
-files.
-
-@kindex DEL @r{(programming modes)}
-@findex c-electric-backspace
- In most programming languages, indentation should vary from line to
-line to illustrate the structure of the program. So the major modes
-for programming languages arrange for @key{TAB} to update the
-indentation of the current line. They also rebind @key{DEL} to treat
-a tab as if it were the equivalent number of spaces; this lets you
-delete one column of indentation without worrying whether the
-whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a
-tab character before point, in these modes.
-
- Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
-Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
-(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
-(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
-
-@cindex mode hook
-@vindex c-mode-hook
-@vindex lisp-mode-hook
-@vindex emacs-lisp-mode-hook
-@vindex lisp-interaction-mode-hook
-@vindex scheme-mode-hook
- Turning on a major mode runs a normal hook called the @dfn{mode
-hook}, which is the value of a Lisp variable. Each major mode has a
-mode hook, and the hook's name is always made from the mode command's
-name by adding @samp{-hook}. For example, turning on C mode runs the
-hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
-@code{lisp-mode-hook}. The purpose of the mode hook is to give you a
-place to set up customizations for that major mode. @xref{Hooks}.
-
-@node Defuns
-@section Top-Level Definitions, or Defuns
-
- In Emacs, a major definition at the top level in the buffer,
-something like a function, is called a @dfn{defun}. The name comes
-from Lisp, but in Emacs we use it for all languages.
-
- In many programming language modes, Emacs assumes that a defun is
-any pair of parentheses (or braces, if the language uses braces this
-way) that starts at the left margin. For example, in C, the body of a
-function definition is a defun, usually recognized as an open-brace
-that begins at the left margin@footnote{Alternatively, you can set up
-C Mode to recognize a defun at an opening brace at the outermost
-level. @xref{Movement Commands,,, ccmode, the CC Mode Manual}.}. A
-variable's initializer can also count as a defun, if the open-brace
-that begins the initializer is at the left margin.
-
- However, some language modes provide their own code for recognizing
-defuns in a way that suits the language syntax and conventions better.
-
-@menu
-* Left Margin Paren:: An open-paren or similar opening delimiter
- starts a defun if it is at the left margin.
-* Moving by Defuns:: Commands to move over or mark a major definition.
-* Imenu:: Making buffer indexes as menus.
-* Which Function:: Which Function mode shows which function you are in.
-@end menu
-
-@node Left Margin Paren
-@subsection Left Margin Convention
-
-@cindex open-parenthesis in leftmost column
-@cindex ( in leftmost column
- Emacs assumes by default that any opening delimiter found at the
-left margin is the start of a top-level definition, or defun. You can
-override this default by setting this user option:
-
-@defvar open-paren-in-column-0-is-defun-start
-If this user option is set to @code{t} (the default), opening
-parentheses or braces at column zero always start defuns. When it's
-@code{nil}, defuns are found by searching for parens or braces at the
-outermost level. Some major modes, including C and related modes, set
-@code{open-paren-in-column-0-is-defun-start} buffer-locally to
-@code{nil}
-@end defvar
-
- In modes where @code{open-paren-in-column-0-is-defun-start} is
-@code{t}, @strong{don't put an opening delimiter at the left margin
-unless it is a defun start}. For instance, never put an
-open-parenthesis at the left margin in a Lisp file unless it is the
-start of a top-level list.
-
- If you don't follow this convention, not only will you have trouble
-when you explicitly use the commands for motion by defuns; other
-features that use them will also give you trouble. This includes
-the indentation commands (@pxref{Program Indent}) and Font Lock
-mode (@pxref{Font Lock}).
-
- 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 (@samp{\}, in Emacs Lisp, @samp{/} in some other Lisp
-dialects) before the opening delimiter. This will not affect the
-contents of the string, but will prevent that opening delimiter from
-starting a defun. Here's an example:
-
-@example
- (insert "Foo:
-\(bar)
-")
-@end example
-
- To help you catch violations of this convention, Font Lock mode
-highlights confusing opening delimiters (those that ought to be
-quoted) in bold red.
-
- In the earliest days, the original Emacs found defuns by moving
-upward a level of parentheses or braces until there were no more
-levels to go up. This always required scanning all the way back to
-the beginning of the buffer, even for a small function. To speed up
-the operation, we changed Emacs to assume that any opening delimiter
-at the left margin is the start of a defun. This heuristic is nearly
-always right, and avoids the need to scan back to the beginning of the
-buffer. However, now that modern computers are so powerful, this
-scanning is rarely slow enough to annoy, so we've provided a way to
-disable the heuristic.
-
-@node Moving by Defuns
-@subsection Moving by Defuns
-@cindex defuns
-
- These commands move point or set up the region based on top-level
-major definitions, also called @dfn{defuns}.
-
-@table @kbd
-@item C-M-a
-Move to beginning of current or preceding defun
-(@code{beginning-of-defun}).
-@item C-M-e
-Move to end of current or following defun (@code{end-of-defun}).
-@item C-M-h
-Put region around whole current or following defun (@code{mark-defun}).
-@end table
-
-@cindex move to beginning or end of function
-@cindex function, move to beginning or end
-@kindex C-M-a
-@kindex C-M-e
-@kindex C-M-h
-@findex beginning-of-defun
-@findex end-of-defun
-@findex mark-defun
- The commands to move to the beginning and end of the current defun
-are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
-(@code{end-of-defun}). If you repeat one of these commands, or use a
-positive numeric argument, each repetition moves to the next defun in
-the direction of motion.
-
- @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
-@var{n} times to the next beginning of a defun. This is not exactly
-the same place that @kbd{C-M-e} with argument @var{n} would move to;
-the end of this defun is not usually exactly the same place as the
-beginning of the following defun. (Whitespace, comments, and perhaps
-declarations can separate them.) Likewise, @kbd{C-M-e} with a
-negative argument moves back to an end of a defun, which is not quite
-the same as @kbd{C-M-a} with a positive argument.
-
-@kindex C-M-h @r{(C mode)}
-@findex c-mark-function
- To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
-which puts point at the beginning and mark at the end of the current
-defun. This is the easiest way to get ready to kill the defun in
-order to move it to a different place in the file. If you use the
-command while point is between defuns, it uses the following defun.
-Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode
-when the mark is active, includes an additional defun in the region
-each time.
-
- In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
-which is almost the same as @code{mark-defun}; the difference is that
-it backs up over the argument declarations, function name and returned
-data type so that the entire C function is inside the region. This is
-an example of how major modes adjust the standard key bindings so that
-they do their standard jobs in a way better fitting a particular
-language. Other major modes may replace any or all of these key
-bindings for that purpose.
-
-@node Imenu
-@subsection Imenu
-@cindex index of buffer definitions
-@cindex buffer definitions index
-@cindex tags
-
- The Imenu facility offers a way to find the major definitions in
-a file by name. It is also useful in text formatter major modes,
-where it treats each chapter, section, etc., as a definition.
-(@xref{Tags}, for a more powerful feature that handles multiple files
-together.)
-
-@findex imenu
- If you type @kbd{M-x imenu}, it reads the name of a definition using
-the minibuffer, then moves point to that definition. You can use
-completion to specify the name; the command always displays the whole
-list of valid names.
-
-@findex imenu-add-menubar-index
- Alternatively, you can bind the command @code{imenu} to a mouse
-click. Then it displays mouse menus for you to select a definition
-name. You can also add the buffer's index to the menu bar by calling
-@code{imenu-add-menubar-index}. If you want to have this menu bar
-item available for all buffers in a certain major mode, you can do
-this by adding @code{imenu-add-menubar-index} to its mode hook. But
-if you have done that, you will have to wait each time you visit a
-file in that mode, while Emacs finds all the definitions in that
-buffer.
-
-@vindex imenu-auto-rescan
- When you change the contents of a buffer, if you add or delete
-definitions, you can update the buffer's index based on the
-new contents by invoking the @samp{*Rescan*} item in the menu.
-Rescanning happens automatically if you set @code{imenu-auto-rescan} to
-a non-@code{nil} value. There is no need to rescan because of small
-changes in the text.
-
-@vindex imenu-sort-function
- You can customize the way the menus are sorted by setting the
-variable @code{imenu-sort-function}. By default, names are ordered as
-they occur in the buffer; if you want alphabetic sorting, use the
-symbol @code{imenu--sort-by-name} as the value. You can also
-define your own comparison function by writing Lisp code.
-
- Imenu provides the information to guide Which Function mode
-@ifnottex
-(@pxref{Which Function}).
-@end ifnottex
-@iftex
-(see below).
-@end iftex
-The Speedbar can also use it (@pxref{Speedbar}).
-
-@node Which Function
-@subsection Which Function Mode
-@cindex current function name in mode line
-
- Which Function mode is a minor mode that displays the current
-function name in the mode line, updating it as you move around in a
-buffer.
-
-@findex which-function-mode
-@vindex which-func-modes
- To enable (or disable) Which Function mode, use the command @kbd{M-x
-which-function-mode}. This command is global; it applies to all
-buffers, both existing ones and those yet to be created. However, it
-takes effect only in certain major modes, those listed in the value of
-@code{which-func-modes}. If the value is @code{t}, then Which Function
-mode applies to all major modes that know how to support it---in other
-words, all the major modes that support Imenu.
-
-@node Program Indent
-@section Indentation for Programs
-@cindex indentation for programs
-
- The best way to keep a program properly indented is to use Emacs to
-reindent it as you change it. 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
-* Basic Indent:: Indenting a single line.
-* Multi-line Indent:: Commands to reindent many lines at once.
-* Lisp Indent:: Specifying how each Lisp function should be indented.
-* C Indent:: Extra features for indenting C and related modes.
-* Custom C Indent:: Controlling indentation style for C and related modes.
-@end menu
-
-@cindex pretty-printer
- Emacs also provides a Lisp pretty-printer in the library @code{pp}.
-This program reformats a Lisp object with indentation chosen to look nice.
-
-@node Basic Indent
-@subsection Basic Program Indentation Commands
-
- The basic indentation commands indent a single line according to the
-usual conventions of the language you are editing.
-
-@table @kbd
-@item @key{TAB}
-Adjust indentation of current line.
-@item C-j
-Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
-@item @key{LINEFEED}
-This key, if the keyboard has it, is another way to enter @kbd{C-j}.
-@end table
-
-@kindex TAB @r{(programming modes)}
-@findex c-indent-command
-@findex indent-line-function
-@findex indent-for-tab-command
- The basic indentation command is @key{TAB}, which gives the current line
-the correct indentation as determined from the previous lines. The
-function that @key{TAB} runs depends on the major mode; it is
-@code{lisp-indent-line}
-in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
-understand the syntax and conventions of different languages, but they all do
-conceptually the same job: @key{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 was inside the
-whitespace at the beginning of the line, @key{TAB} puts it at the end of
-that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
-the characters around it.
-
- Use @kbd{C-q @key{TAB}} to insert a tab character at point.
-
-@kindex C-j
-@findex newline-and-indent
- When entering lines of new code, use @kbd{C-j}
-(@code{newline-and-indent}), which is equivalent to a @key{RET}
-followed by a @key{TAB}. @kbd{C-j} at the end of a line creates a
-blank line and then gives it the appropriate indentation.
-
- @key{TAB} indents a line that starts within a parenthetical grouping
-under the preceding line within the grouping, or the text after the
-parenthesis. Therefore, if you manually give one of these lines a
-nonstandard indentation, the lines below will tend to follow it. This
-behavior is convenient in cases where you have overridden the standard
-result of @key{TAB} because you find it unaesthetic for a particular
-line.
-
- By default, an open-parenthesis, open-brace or other opening
-delimiter at the left margin is assumed by Emacs (including the
-indentation routines) to be the start of a function. This speeds up
-indentation commands. If you will be editing text which contains
-opening delimiters in column zero that aren't the beginning of a
-functions, even inside strings or comments, you must set
-@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin
-Paren}, for more information on this.
-
- Normally, lines are indented with tabs and spaces. If you want Emacs
-to use spaces only, see @ref{Just Spaces}.
-
-@node Multi-line Indent
-@subsection Indenting Several Lines
-
- When you wish to reindent several lines of code which have been
-altered or moved to a different level in the parenthesis structure,
-you have several commands available.
-
-@table @kbd
-@item C-M-q
-Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}).
-@item C-M-\
-Reindent all lines in the region (@code{indent-region}).
-@item C-u @key{TAB}
-Shift an entire parenthetical grouping rigidly sideways so that its
-first line is properly indented.
-@item M-x indent-code-rigidly
-Shift all the lines in the region rigidly sideways, but do not alter
-lines that start inside comments and strings.
-@end table
-
-@kindex C-M-q
-@findex indent-pp-sexp
- You can reindent the contents of a single parenthetical grouping by
-positioning point before the beginning of it and typing @kbd{C-M-q}
-(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
-bound to other suitable commands in other modes). The indentation of
-the line where the grouping starts is not changed; therefore this
-changes only the relative indentation within the grouping, not its
-overall indentation. To correct that as well, type @key{TAB} first.
-
- Another way to specify the range to be reindented is with the
-region. The command @kbd{C-M-\} (@code{indent-region}) applies
-@key{TAB} to every line whose first character is between point and
-mark.
-
-@kindex C-u TAB
- If you like the relative indentation within a grouping, but not the
-indentation of its first line, you can type @kbd{C-u @key{TAB}} to
-reindent the whole grouping as a rigid unit. (This works in Lisp
-modes and C and related modes.) @key{TAB} with a numeric argument
-reindents the current line as usual, then reindents by the same amount
-all the lines in the parenthetical grouping starting on the current
-line. It is clever, though, and does not alter lines that start
-inside strings. Neither does it alter C preprocessor lines when in C
-mode, but it does reindent any continuation lines that may be attached
-to them.
-
-@findex indent-code-rigidly
- You can also perform this operation on the region, using the command
-@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the
-region sideways, like @code{indent-rigidly} does (@pxref{Indentation
-Commands}). It doesn't alter the indentation of lines that start
-inside a string, unless the region also starts inside that string.
-The prefix arg specifies the number of columns to indent.
-
-@node Lisp Indent
-@subsection Customizing Lisp Indentation
-@cindex 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.
-
- 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.
-
-@vindex lisp-indent-offset
- If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
-the usual indentation pattern for the second line of an expression, so that
-such lines are always indented @code{lisp-indent-offset} more columns than
-the containing list.
-
-@vindex lisp-body-indent
- Certain functions override the standard pattern. Functions whose
-names start with @code{def} treat the second lines as the start of
-a @dfn{body}, by indenting the second line @code{lisp-body-indent}
-additional columns beyond the open-parenthesis that starts the
-expression.
-
-@cindex @code{lisp-indent-function} property
- You can override the standard pattern in various ways for individual
-functions, according to the @code{lisp-indent-function} property of
-the function name. Normally you would use this for macro definitions
-and specify it using the @code{declare} construct (@pxref{Defining
-Macros,,, elisp, the Emacs Lisp Reference Manual}).
-
-@node C Indent
-@subsection Commands for C Indentation
-
- Here are special features for indentation in C mode and related modes:
-
-@table @code
-@item C-c C-q
-@kindex C-c C-q @r{(C mode)}
-@findex c-indent-defun
-Reindent the current top-level function definition or aggregate type
-declaration (@code{c-indent-defun}).
-
-@item C-M-q
-@kindex C-M-q @r{(C mode)}
-@findex c-indent-exp
-Reindent each line in the balanced expression that follows point
-(@code{c-indent-exp}). A prefix argument inhibits warning messages
-about invalid syntax.
-
-@item @key{TAB}
-@findex c-indent-command
-Reindent the current line, and/or in some cases insert a tab character
-(@code{c-indent-command}).
-
-@vindex c-tab-always-indent
-If @code{c-tab-always-indent} is @code{t}, this command always reindents
-the current line and does nothing else. This is the default.
-
-If that variable is @code{nil}, this command reindents the current line
-only if point is at the left margin or in the line's indentation;
-otherwise, it inserts a tab (or the equivalent number of spaces,
-if @code{indent-tabs-mode} is @code{nil}).
-
-Any other value (not @code{nil} or @code{t}) means always reindent the
-line, and also insert a tab if within a comment or a string.
-@end table
-
- To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
-first selects the whole buffer as the region, then reindents that
-region.
-
- To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
-to the front of the block and then reindents it all.
-
-@node Custom C Indent
-@subsection Customizing C Indentation
-@cindex style (for indentation)
-
- C mode and related modes use a flexible mechanism for customizing
-indentation. C mode indents a source line in two steps: first it
-classifies the line syntactically according to its contents and
-context; second, it determines the indentation offset associated by
-your selected @dfn{style} with the syntactic construct and adds this
-onto the indentation of the @dfn{anchor statement}.
-
-@table @kbd
-@item C-c . @key{RET} @var{style} @key{RET}
-Select a predefined style @var{style} (@code{c-set-style}).
-@end table
-
- A @dfn{style} is a named collection of customizations that can be
-used in C mode and the related modes. @ref{Styles,,, ccmode, The CC
-Mode Manual}, for a complete description. Emacs comes with several
-predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
-@code{stroustrup}, @code{linux}, @code{python}, @code{java},
-@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these
-styles are primarily intended for one language, but any of them can be
-used with any of the languages supported by these modes. To find out
-what a style looks like, select it and reindent some code, e.g., by
-typing @key{C-M-q} at the start of a function definition.
-
-@kindex C-c . @r{(C mode)}
-@findex c-set-style
- To choose a style for the current buffer, use the command @kbd{C-c
-.}. Specify a style name as an argument (case is not significant).
-This command affects the current buffer only, and it affects only
-future invocations of the indentation commands; it does not reindent
-the code already in the buffer. To reindent the whole buffer in the
-new style, you can type @kbd{C-x h C-M-\}.
-
-@vindex c-default-style
- You can also set the variable @code{c-default-style} to specify the
-default style for various major modes. Its value should be either the
-style's name (a string) or an alist, in which each element specifies
-one major mode and which indentation style to use for it. For
-example,
-
-@example
-(setq c-default-style
- '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))
-@end example
-
-@noindent
-specifies explicit choices for Java and AWK modes, and the default
-@samp{gnu} style for the other C-like modes. (These settings are
-actually the defaults.) This variable takes effect when you select
-one of the C-like major modes; thus, if you specify a new default
-style for Java mode, you can make it take effect in an existing Java
-mode buffer by typing @kbd{M-x java-mode} there.
-
- The @code{gnu} style specifies the formatting recommended by the GNU
-Project for C; it is the default, so as to encourage use of our
-recommended style.
-
- @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
-@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
-information on customizing indentation for C and related modes,
-including how to override parts of an existing style and how to define
-your own styles.
-
-@node Parentheses
-@section Commands for Editing with Parentheses
-
-@findex check-parens
-@cindex unbalanced parentheses and quotes
- This section describes the commands and features that take advantage
-of the parenthesis structure in a program, or help you keep it
-balanced.
-
- When talking about these facilities, the term ``parenthesis'' also
-includes braces, brackets, or whatever delimiters are defined to match
-in pairs. The major mode controls which delimiters are significant,
-through the syntax table (@pxref{Syntax}). In Lisp, only parentheses
-count; in C, these commands apply to braces and brackets too.
-
- You can use @kbd{M-x check-parens} to find any unbalanced
-parentheses and unbalanced string quotes in the buffer.
-
-@menu
-* Expressions:: Expressions with balanced parentheses.
-* Moving by Parens:: Commands for moving up, down and across
- in the structure of parentheses.
-* Matching:: Insertion of a close-delimiter flashes matching open.
-@end menu
-
-@node Expressions
-@subsection Expressions with Balanced Parentheses
-
-@cindex sexp
-@cindex expression
-@cindex balanced expression
- These commands deal with balanced expressions, also called
-@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
-expression in Lisp.}.
-
-@table @kbd
-@item C-M-f
-Move forward over a balanced expression (@code{forward-sexp}).
-@item C-M-b
-Move backward over a balanced expression (@code{backward-sexp}).
-@item C-M-k
-Kill balanced expression forward (@code{kill-sexp}).
-@item C-M-t
-Transpose expressions (@code{transpose-sexps}).
-@item C-M-@@
-@itemx C-M-@key{SPC}
-Put mark after following expression (@code{mark-sexp}).
-@end table
-
- Each programming language major mode customizes the definition of
-balanced expressions to suit that language. Balanced expressions
-typically include symbols, numbers, and string constants, as well as
-any pair of matching delimiters and their contents. Some languages
-have obscure forms of expression syntax that nobody has bothered to
-implement in Emacs.
-
-@cindex Control-Meta
- By convention, the keys for these commands are all Control-Meta
-characters. They usually act on expressions just as the corresponding
-Meta characters act on words. For instance, the command @kbd{C-M-b}
-moves backward over a balanced expression, just as @kbd{M-b} moves
-back over a word.
-
-@kindex C-M-f
-@kindex C-M-b
-@findex forward-sexp
-@findex backward-sexp
- To move forward over a balanced expression, use @kbd{C-M-f}
-(@code{forward-sexp}). If the first significant character after point
-is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
-@samp{@{} in C), @kbd{C-M-f} moves past the matching closing
-delimiter. If the character begins a symbol, string, or number,
-@kbd{C-M-f} moves over that.
-
- The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
-balanced expression. The detailed rules are like those above for
-@kbd{C-M-f}, but with directions reversed. If there are prefix
-characters (single-quote, backquote and comma, in Lisp) preceding the
-expression, @kbd{C-M-b} moves back over them as well. The balanced
-expression commands move across comments as if they were whitespace,
-in most modes.
-
- @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
-specified number of times; with a negative argument, it moves in the
-opposite direction.
-
-@cindex killing expressions
-@kindex C-M-k
-@findex kill-sexp
- Killing a whole balanced expression can be done with @kbd{C-M-k}
-(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}
-would move over.
-
-@cindex transposition of expressions
-@kindex C-M-t
-@findex transpose-sexps
- A somewhat random-sounding command which is nevertheless handy is
-@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
-balanced expression across the next one. An argument serves as a
-repeat count, moving the previous expression over that many following
-ones. A negative argument drags the previous balanced expression
-backwards across those before it (thus canceling out the effect of
-@kbd{C-M-t} with a positive argument). An argument of zero, rather
-than doing nothing, transposes the balanced expressions ending at or
-after point and the mark.
-
-@kindex C-M-@@
-@kindex C-M-@key{SPC}
-@findex mark-sexp
- To set the region around the next balanced expression in the buffer,
-use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
-that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like
-@kbd{C-M-f}. In particular, a negative argument is useful for putting
-the mark at the beginning of the previous balanced expression. The
-alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you
-repeat this command, or use it in Transient Mark mode when the mark is
-active, it extends the region by one sexp each time.
-
- In languages that use infix operators, such as C, it is not possible
-to recognize all balanced expressions as such because there can be
-multiple possibilities at a given position. For example, C mode does
-not treat @samp{foo + bar} as a single expression, even though it
-@emph{is} one C expression; instead, it recognizes @samp{foo} as one
-expression and @samp{bar} as another, with the @samp{+} as punctuation
-between them. Both @samp{foo + bar} and @samp{foo} are legitimate
-choices for ``the expression following point'' when point is at the
-@samp{f}, so the expression commands must perforce choose one or the
-other to operate on. Note that @samp{(foo + bar)} is recognized as a
-single expression in C mode, because of the parentheses.
-
-@node Moving by Parens
-@subsection Moving in the Parenthesis Structure
-
-@cindex parenthetical groupings
-@cindex parentheses, moving across
-@cindex matching parenthesis and braces, moving to
-@cindex braces, moving across
-@cindex list commands
- The Emacs commands for handling parenthetical groupings see nothing
-except parentheses (or whatever characters must balance in the
-language you are working with), and the escape characters that might
-be used to quote those. They are mainly intended for editing
-programs, but can be useful for editing any text that has parentheses.
-They are sometimes called ``list'' commands because in Lisp these
-groupings are lists.
-
-@table @kbd
-@item C-M-n
-Move forward over a parenthetical group (@code{forward-list}).
-@item C-M-p
-Move backward over a parenthetical group (@code{backward-list}).
-@item C-M-u
-Move up in parenthesis structure (@code{backward-up-list}).
-@item C-M-d
-Move down in parenthesis structure (@code{down-list}).
-@end table
-
-@kindex C-M-n
-@kindex C-M-p
-@findex forward-list
-@findex backward-list
- The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
-@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})
-parenthetical groupings, skipping blithely over any amount of text
-that doesn't include meaningful parentheses (symbols, strings, etc.).
-
-@kindex C-M-u
-@kindex C-M-d
-@findex backward-up-list
-@findex down-list
- @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
-parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
-@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
-past one unmatched opening delimiter. A positive argument serves as a
-repeat count; a negative argument reverses the direction of motion, so
-that the command moves forward and up one or more levels.
-
- To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
-(@code{down-list}). In Lisp mode, where @samp{(} is the only opening
-delimiter, this is nearly the same as searching for a @samp{(}. An
-argument specifies the number of levels to go down.
-
-@node Matching
-@subsection Automatic Display Of Matching Parentheses
-@cindex matching parentheses
-@cindex parentheses, displaying matches
-
- The Emacs parenthesis-matching feature is designed to show
-automatically how parentheses (and other matching delimiters) match in
-the text. Whenever you type a self-inserting character that is a
-closing delimiter, the cursor moves momentarily to the location of the
-matching opening delimiter, provided that is on the screen. If it is
-not on the screen, Emacs displays some of the text near it in the echo
-area. Either way, you can tell which grouping you are closing off.
-
- If the opening delimiter and closing delimiter are mismatched---such
-as in @samp{[x)}---a warning message is displayed in the echo area.
-
-@vindex blink-matching-paren
-@vindex blink-matching-paren-distance
-@vindex blink-matching-delay
- Three variables control parenthesis match display:
-
- @code{blink-matching-paren} turns the feature on or off: @code{nil}
-disables it, but the default is @code{t} to enable match display.
-
- @code{blink-matching-delay} says how many seconds to leave the
-cursor on the matching opening delimiter, before bringing it back to
-the real location of point; the default is 1, but on some systems it
-is useful to specify a fraction of a second.
-
- @code{blink-matching-paren-distance} specifies how many characters
-back to search to find the matching opening delimiter. If the match
-is not found in that distance, scanning stops, and nothing is displayed.
-This is to prevent the scan for the matching delimiter from wasting
-lots of time when there is no match. The default is 25600.
-
-@cindex Show Paren mode
-@cindex highlighting matching parentheses
-@findex show-paren-mode
- Show Paren mode provides a more powerful kind of automatic matching.
-Whenever point is after a closing delimiter, that delimiter and its
-matching opening delimiter are both highlighted; otherwise, if point
-is before an opening delimiter, the matching closing delimiter is
-highlighted. (There is no need to highlight the opening delimiter in
-that case, because the cursor appears on top of that character.) Use
-the command @kbd{M-x show-paren-mode} to enable or disable this mode.
-
- By default, @code{show-paren-mode} uses colors to highlight the
-parentheses. However, if your display doesn't support colors, you can
-customize the faces @code{show-paren-match-face} and
-@code{show-paren-mismatch-face} to use other attributes, such as bold or
-underline. @xref{Face Customization}.
-
-@node Comments
-@section Manipulating Comments
-@cindex comments
-
- Because comments are such an important part of programming, Emacs
-provides special commands for editing and inserting comments. It can
-also do spell checking on comments with Flyspell Prog mode
-(@pxref{Spelling}).
-
-@menu
-* Comment Commands:: Inserting, killing, and indenting comments.
-* Multi-Line Comments:: Commands for adding and editing multi-line comments.
-* Options for Comments::Customizing the comment features.
-@end menu
-
-@node Comment Commands
-@subsection Comment Commands
-@cindex indentation for comments
-
- The comment commands in this table insert, kill and align comments.
-They are described in this section and following sections.
-
-@table @asis
-@item @kbd{M-;}
-Insert or realign comment on current line; alternatively, comment or
-uncomment the region (@code{comment-dwim}).
-@item @kbd{C-u M-;}
-Kill comment on current line (@code{comment-kill}).
-@item @kbd{C-x ;}
-Set comment column (@code{comment-set-column}).
-@item @kbd{C-M-j}
-@itemx @kbd{M-j}
-Like @key{RET} followed by inserting and aligning a comment
-(@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
-@item @kbd{M-x comment-region}
-@itemx @kbd{C-c C-c} (in C-like modes)
-Add or remove comment delimiters on all the lines in the region.
-@end table
-
-@kindex M-;
-@findex comment-dwim
- The command to create or align a comment is @kbd{M-;}
-(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
-I Mean''; it indicates that this command can be used for many
-different jobs relating to comments, depending on the situation where
-you use it.
-
- If there is no comment already on the line, @kbd{M-;} inserts a new
-comment, aligned at a specific column called the @dfn{comment column}.
-The new comment begins with the string Emacs thinks comments should
-start with (the value of @code{comment-start}; see below). Point is
-after that string, so you can insert the text of the comment right
-away. If the major mode has specified a string to terminate comments,
-@kbd{M-;} inserts that too, to keep the syntax valid.
-
- If the text of the line extends past the comment column, then the
-comment start string is indented to a suitable boundary (usually, at
-least one space is inserted).
-
- You can also use @kbd{M-;} to align an existing comment. If a line
-already contains the comment-start string, @kbd{M-;} reindents it to
-the conventional alignment and moves point after it. (Exception:
-comments starting in column 0 are not moved.) Even when an existing
-comment is properly aligned, @kbd{M-;} is still useful for moving
-directly to the start of the text inside the comment.
-
-@findex comment-kill
-@kindex C-u M-;
- @kbd{C-u M-;} kills any comment on the current line, along with the
-whitespace before it. To reinsert the comment on another line, move
-to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
-realign it.
-
- Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
-(@code{comment-dwim}) with a prefix argument. That command is
-programmed so that when it receives a prefix argument it calls
-@code{comment-kill}. However, @code{comment-kill} is a valid command
-in its own right, and you can bind it directly to a key if you wish.
-
- @kbd{M-;} does two other jobs when used with an active region in
-Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
-removes comment delimiters on each line of the region. (If every line
-is a comment, it removes comment delimiters from each; otherwise, it
-adds comment delimiters to each.) If you are not using Transient Mark
-mode, then you should use the commands @code{comment-region} and
-@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}).
-A prefix argument used in these circumstances specifies how many
-comment delimiters to add or how many to delete.
-
- 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 @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
-
-@example
-;; 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.
-@end example
-
- For C-like buffers, you can configure the exact effect of @kbd{M-;}
-more flexibly than for most buffers by setting the user options
-@code{c-indent-comment-alist} and
-@code{c-indent-comments-syntactically-p}. For example, on a line
-ending in a closing brace, @kbd{M-;} puts the comment one space after
-the brace rather than at @code{comment-column}. For full details see
-@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
-
-@node Multi-Line Comments
-@subsection Multiple Lines of Comments
-
-@kindex C-M-j
-@kindex M-j
-@cindex blank lines in programs
-@findex comment-indent-new-line
-
- If you are typing a comment and wish to continue it on another line,
-you can use the command @kbd{C-M-j} or @kbd{M-j}
-(@code{comment-indent-new-line}). If @code{comment-multi-line}
-(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
-line within the comment. Otherwise it closes the comment and starts a
-new comment on a new line. When Auto Fill mode is on, going past the
-fill column while typing a comment causes the comment to be continued
-in just this fashion.
-
-@kindex C-c C-c (C mode)
-@findex comment-region
- To turn existing lines into comment lines, use the @kbd{M-x
-comment-region} command (or type @kbd{C-c C-c} in C-like buffers). It
-adds comment delimiters to the lines that start in the region, thus
-commenting them out. With a negative argument, it does the
-opposite---it deletes comment delimiters from the lines in the region.
-
- With a positive argument, @code{comment-region} duplicates the last
-character of the comment start sequence it adds; the argument specifies
-how many copies of the character to insert. Thus, in Lisp mode,
-@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
-the comment delimiter is a way of calling attention to the comment. It
-can also affect how the comment is indented. In Lisp, for proper
-indentation, you should use an argument of two or three, if between defuns;
-if within a defun, it must be three.
-
- You can configure C Mode such that when you type a @samp{/} at the
-start of a line in a multi-line block comment, this closes the
-comment. Enable the @code{comment-close-slash} clean-up for this.
-@xref{Clean-ups,,, ccmode, The CC Mode Manual}.
-
-@node Options for Comments
-@subsection Options Controlling Comments
-
-@vindex comment-column
-@kindex C-x ;
-@findex comment-set-column
- The @dfn{comment column}, the column at which Emacs tries to place
-comments, is stored in the variable @code{comment-column}. You can
-set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
-(@code{comment-set-column}) sets the comment column to the column
-point is at. @kbd{C-u C-x ;} sets the comment column to match the
-last comment before point in the buffer, and then does a @kbd{M-;} to
-align the current line's comment under the previous one.
-
- The variable @code{comment-column} is per-buffer: setting the variable
-in the normal fashion affects only the current buffer, but there is a
-default value which you can change with @code{setq-default}.
-@xref{Locals}. Many major modes initialize this variable for the
-current buffer.
-
-@vindex comment-start-skip
- The comment commands recognize comments based on the regular
-expression that is the value of the variable @code{comment-start-skip}.
-Make sure this regexp does 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
-@c This stops M-q from breaking the line inside that @code.
-@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
-after the @samp{/*} itself, and accepts C++ style comments also.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax. @xref{Regexp Backslash}.)
-
-@vindex comment-start
-@vindex comment-end
- When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it. The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will
-insert into the comment. When @code{comment-end} is non-empty, it
-should start with a space. For example, in C mode,
-@code{comment-start} has the value @w{@code{"/* "}} and
-@code{comment-end} has the value @w{@code{" */"}}.
-
-@vindex comment-padding
- The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the comment
-delimiter and the line's original text. The default is 1, to insert
-one space. @code{nil} means 0. Alternatively, @code{comment-padding}
-can hold the actual string to insert.
-
-@vindex comment-multi-line
- The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment.
-Specifically, when @code{comment-multi-line} is @code{nil}, the
-command inserts a comment terminator, begins a new line, and finally
-inserts a comment starter. Otherwise it does not insert the
-terminator and starter, so it effectively continues the current
-comment across multiple lines. In languages that allow multi-line
-comments, the choice of value for this variable is a matter of taste.
-The default for this variable depends on the major mode.
-
-@vindex comment-indent-function
- The variable @code{comment-indent-function} should contain a function
-that will be called to compute the indentation for a newly inserted
-comment or for aligning an existing comment. It is set differently by
-various major modes. 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. It should return the column in which the
-comment ought to start. For example, in Lisp mode, the indent hook
-function bases its decision on how many semicolons begin an existing
-comment, and on the code in the preceding lines.
-
-@node Documentation
-@section Documentation Lookup
-
- Emacs provides several features you can use to look up the
-documentation of functions, variables and commands that you plan to
-use in your program.
-
-@menu
-* Info Lookup:: Looking up library functions and commands
- in Info files.
-* Man Page:: Looking up man pages of library functions and commands.
-* Lisp Doc:: Looking up Emacs Lisp functions, etc.
-@end menu
-
-@node Info Lookup
-@subsection Info Documentation Lookup
-
-@findex info-lookup-symbol
-@findex info-lookup-file
-@kindex C-h S
- For C, Lisp, and other languages that have documentation in Info,
-you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the Info
-documentation for a symbol used in the program. You specify the
-symbol with the minibuffer; the default is the symbol appearing in the
-buffer at point. For example, in C mode this looks for the symbol in
-the C Library Manual.
-
- The major mode determines where to look for documentation for the
-symbol---which Info files to look in, and which indices to search.
-You can also use @kbd{M-x info-lookup-file} to look for documentation
-for a file name.
-
- This feature currently supports the modes AWK, Autoconf, Bison, C,
-Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo,
-provided you have installed the relevant Info files, which are
-typically available with the appropriate GNU package.
-
-@node Man Page
-@subsection Man Page Lookup
-
-@cindex manual page
- On Unix, the main form of on-line documentation was the @dfn{manual
-page} or @dfn{man page}. In the GNU operating system, we hope to
-replace man pages with better-organized manuals that you can browse
-with Info (@pxref{Misc Help}). This process is not finished, so it is
-still useful to read manual pages.
-
-@findex manual-entry
- You can read the man page for an operating system command, library
-function, or system call, with the @kbd{M-x man} command. It
-runs the @code{man} program to format the man page; if the system
-permits, it runs @code{man} asynchronously, so that you can keep on
-editing while the page is being formatted. (On MS-DOS and MS-Windows
-3, you cannot edit while Emacs waits for @code{man} to finish.) The
-result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
-use a special major mode, Man mode, that facilitates scrolling and
-jumping to other manual pages. For details, type @kbd{C-h m} while in
-a man page buffer.
-
-@cindex sections of manual pages
- Each man page belongs to one of ten or more @dfn{sections}, each
-named by a digit or by a digit and a letter. Sometimes there are
-multiple man pages with the same name in different sections. To read
-a man page from a specific section, type
-@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
-when @kbd{M-x manual-entry} prompts for the topic. For example, to
-read the man page for the C library function @code{chmod} (as opposed
-to a command of the same name), type @kbd{M-x manual-entry @key{RET}
-chmod(2) @key{RET}} (@code{chmod} is a system call, so it is in
-section @samp{2}).
-
-@vindex Man-switches
- If you do not specify a section, the results depend on how the
-@code{man} program works on your system. Some of them display only
-the first man page they find. Others display all man pages that have
-the specified name, so you can move between them with the @kbd{M-n}
-and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
-accepts a @samp{-a} command-line option which tells it to display all
-the man pages for the specified topic. If you want this behavior, you
-can add this option to the value of the variable @code{Man-switches}.}.
-The mode line shows how many manual pages are present in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
- By default, Emacs highlights the text in man pages. For a long man
-page, highlighting can take substantial time. You can turn off
-highlighting of man pages by setting the variable
-@code{Man-fontify-manpage-flag} to @code{nil}.
-
-@findex Man-fontify-manpage
- If you insert the text of a man page into an Emacs buffer in some
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
-
-@findex woman
-@cindex manual pages, on MS-DOS/MS-Windows
- An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man,'' since it doesn't use the @code{man}
-program.}. Unlike @kbd{M-x man}, it does not run any external
-programs to format and display the man pages; instead it does the job
-in Emacs Lisp, so it works on systems such as MS-Windows, where the
-@code{man} program (and other programs it uses) are not generally
-available.
-
- @kbd{M-x woman} prompts for a name of a manual page, and provides
-completion based on the list of manual pages that are installed on
-your machine; the list of available manual pages is computed
-automatically the first time you invoke @code{woman}. The word at
-point in the current buffer is used to suggest the default for the
-name the manual page.
-
- With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion. This is useful if you add or delete
-manual pages.
-
- If you type a name of a manual page and @kbd{M-x woman} finds that
-several manual pages by the same name exist in different sections, it
-pops up a window with possible candidates asking you to choose one of
-them.
-
-@vindex woman-manpath
- By default, @kbd{M-x woman} looks for manual pages in the
-directories specified in the @code{MANPATH} environment variable. (If
-@code{MANPATH} is not set, @code{woman} uses a suitable default value,
-which can be customized.) More precisely, @code{woman} looks for
-subdirectories that match the shell wildcard pattern @file{man*} in each one
-of these directories, and tries to find the manual pages in those
-subdirectories. When first invoked, @kbd{M-x woman} converts the
-value of @code{MANPATH} to a list of directory names and stores that
-list in the @code{woman-manpath} variable. Changing the value of this
-variable is another way to control the list of directories used.
-
-@vindex woman-path
- You can also augment the list of directories searched by
-@code{woman} by setting the value of the @code{woman-path} variable.
-This variable should hold a list of specific directories which
-@code{woman} should search, in addition to those in
-@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
-@code{woman-path} are searched for the manual pages, not for
-@file{man*} subdirectories.
-
-@findex woman-find-file
- Occasionally, you might need to display manual pages that are not in
-any of the directories listed by @code{woman-manpath} and
-@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
-name of a manual page file, with completion, and then formats and
-displays that file like @kbd{M-x woman} does.
-
-@vindex woman-dired-keys
- The first time you invoke @kbd{M-x woman}, it defines the Dired
-@kbd{W} key to run the @code{woman-find-file} command on the current
-line's file. You can disable this by setting the variable
-@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition,
-the Tar-mode @kbd{w} key is define to invoke @code{woman-find-file} on
-the current line's archive member.
-
- For more information about setting up and using @kbd{M-x woman}, see
-@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
-Manual}.
-
-@node Lisp Doc
-@subsection Emacs Lisp Documentation Lookup
-
- As you edit Lisp code to be run in Emacs, you can use the commands
-@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
-(@code{describe-variable}) to view documentation of functions and
-variables that you want to use. These commands use the minibuffer to
-read the name of a function or variable to document, and display the
-documentation in a window. Their default arguments are based on the
-code in the neighborhood of point. For @kbd{C-h f}, the default is
-the function called in the innermost list containing point. @kbd{C-h
-v} uses the symbol name around or adjacent to point as its default.
-
-@cindex Eldoc mode
-@findex eldoc-mode
- A more automatic but less powerful method is Eldoc mode. This minor
-mode constantly displays in the echo area the argument list for the
-function being called at point. (In other words, it finds the
-function call that point is contained in, and displays the argument
-list of that function.) If point is over a documented variable, it
-shows the first line of the variable's docstring. Eldoc mode applies
-in Emacs Lisp and Lisp Interaction modes, and perhaps a few others
-that provide special support for looking up doc strings. Use the
-command @kbd{M-x eldoc-mode} to enable or disable this feature.
-
-@node Hideshow
-@section Hideshow minor mode
-
-@findex hs-minor-mode
- Hideshow minor mode provides selective display of portions of a
-program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode}
-to enable or disable this mode, or add @code{hs-minor-mode} to the
-mode hook for certain major modes in order to enable it automatically
-for those modes.
-
- Just what constitutes a block depends on the major mode. In C mode
-or C++ mode, they are delimited by braces, while in Lisp mode and
-similar modes they are delimited by parentheses. Multi-line comments
-also count as blocks.
-
-@findex hs-hide-all
-@findex hs-hide-block
-@findex hs-show-all
-@findex hs-show-block
-@findex hs-show-region
-@findex hs-hide-level
-@findex hs-minor-mode
-@kindex C-c @@ C-h
-@kindex C-c @@ C-s
-@kindex C-c @@ C-M-h
-@kindex C-c @@ C-M-s
-@kindex C-c @@ C-r
-@kindex C-c @@ C-l
-@kindex S-Mouse-2
-@table @kbd
-@item C-c @@ C-h
-Hide the current block (@code{hs-hide-block}).
-@item C-c @@ C-s
-Show the current block (@code{hs-show-block}).
-@item C-c @@ C-c
-Either hide or show the current block (@code{hs-toggle-hiding}).
-@item S-Mouse-2
-Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}).
-@item C-c @@ C-M-h
-Hide all top-level blocks (@code{hs-hide-all}).
-@item C-c @@ C-M-s
-Show everything in the buffer (@code{hs-show-all}).
-@item C-c @@ C-l
-Hide all blocks @var{n} levels below this block
-(@code{hs-hide-level}).
-@end table
-
-@vindex hs-hide-comments-when-hiding-all
-@vindex hs-isearch-open
-@vindex hs-special-modes-alist
- These variables exist for customizing Hideshow mode.
-
-@table @code
-@item hs-hide-comments-when-hiding-all
-Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
-
-@item hs-isearch-open
-Specifies what kind of hidden blocks to open in Isearch mode.
-The value should be one of these four symbols:
-
-@table @code
-@item code
-Open only code blocks.
-@item comment
-Open only comments.
-@item t
-Open both code blocks and comments.
-@item nil
-Open neither code blocks nor comments.
-@end table
-
-@item hs-special-modes-alist
-A list of elements, each specifying how to initialize Hideshow
-variables for one major mode. See the variable's documentation string
-for more information.
-@end table
-
-@node Symbol Completion
-@section Completion for Symbol Names
-@cindex completion (symbol names)
-
- In Emacs, completion is something you normally do in the minibuffer.
-But one kind of completion is available in all buffers: completion for
-symbol names.
-
-@kindex M-TAB
- The character @kbd{M-@key{TAB}} runs a command to complete the
-partial symbol before point against the set of meaningful symbol
-names. This command inserts at point any additional characters that
-it can determine from the partial name. (If your window manager
-defines @kbd{M-@key{TAB}} to switch windows, you can type
-@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.)
-
- If the partial name in the buffer has multiple possible completions
-that differ in the very next character, so that it is impossible to
-complete even one more character, @kbd{M-@key{TAB}} displays a list of
-all possible completions in another window.
-
-@cindex tags-based completion
-@cindex Info index completion
-@findex complete-symbol
- In most programming language major modes, @kbd{M-@key{TAB}} runs the
-command @code{complete-symbol}, which provides two kinds of completion.
-Normally it does completion based on a tags table (@pxref{Tags}); with a
-numeric argument (regardless of the value), it does completion based on
-the names listed in the Info file indexes for your language. Thus, to
-complete the name of a symbol defined in your own program, use
-@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
-library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
-completion works only if there is an Info file for the standard library
-functions of your language, and only if it is installed at your site.
-
-@cindex Lisp symbol completion
-@cindex completion (Lisp symbols)
-@findex lisp-complete-symbol
- In Emacs-Lisp mode, the name space for completion normally consists of
-nontrivial symbols present in Emacs---those that have function
-definitions, values or properties. However, if there is an
-open-parenthesis immediately before the beginning of the partial symbol,
-only symbols with function definitions are considered as completions.
-The command which implements this is @code{lisp-complete-symbol}.
-
- In Text mode and related modes, @kbd{M-@key{TAB}} completes words
-based on the spell-checker's dictionary. @xref{Spelling}.
-
-@node Glasses
-@section Glasses minor mode
-@cindex Glasses mode
-@cindex identifiers, making long ones readable
-@cindex StudlyCaps, making them readable
-@findex glasses-mode
-
- Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
-readable by altering the way they display. It knows two different
-ways to do this: by displaying underscores between a lower-case letter
-and the following capital letter, and by emboldening the capital
-letters. It does not alter the buffer text, only the way they
-display, so you can use it even on read-only buffers. You can use the
-command @kbd{M-x glasses-mode} to enable or disable the mode in the
-current buffer; you can also add @code{glasses-mode} to the mode hook
-of the programming language major modes in which you normally want
-to use Glasses mode.
-
-@node Misc for Programs
-@section Other Features Useful for Editing Programs
-
- A number of Emacs commands that aren't designed specifically for
-editing programs are useful for that nonetheless.
-
- The Emacs commands that operate on words, sentences and paragraphs
-are useful for editing code. Most symbols names contain words
-(@pxref{Words}); sentences can be found in strings and comments
-(@pxref{Sentences}). Paragraphs in the strict sense can be found in
-program code (in long comments), but the paragraph commands are useful
-in other places too, because programming language major modes define
-paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
-Judicious use of blank lines to make the program clearer will also
-provide useful chunks of text for the paragraph commands to work on.
-Auto Fill mode, if enabled in a programming language major mode,
-indents the new lines which it creates.
-
- The selective display feature is useful for looking at the overall
-structure of a function (@pxref{Selective Display}). This feature
-hides the lines that are indented more than a specified amount.
-Programming modes often support Outline minor mode (@pxref{Outline
-Mode}). The Foldout package provides folding-editor features
-(@pxref{Foldout}).
-
- The ``automatic typing'' features may be useful for writing programs.
-@xref{Top,,Autotyping, autotype, Autotyping}.
-
-@node C Modes
-@section C and Related Modes
-@cindex C mode
-@cindex Java mode
-@cindex Pike mode
-@cindex IDL mode
-@cindex CORBA IDL mode
-@cindex Objective C mode
-@cindex C++ mode
-@cindex AWK mode
-@cindex mode, Java
-@cindex mode, C
-@cindex mode, C++
-@cindex mode, Objective C
-@cindex mode, CORBA IDL
-@cindex mode, Pike
-@cindex mode, AWK
-
- This section gives a brief description of the special features
-available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
-(These are called ``C mode and related modes.'') @xref{Top, , CC Mode,
-ccmode, CC Mode}, for a more extensive description of these modes
-and their special features.
-
-@menu
-* Motion in C:: Commands to move by C statements, etc.
-* Electric C:: Colon and other chars can automatically reindent.
-* Hungry Delete:: A more powerful DEL command.
-* Other C Commands:: Filling comments, viewing expansion of macros,
- and other neat features.
-@end menu
-
-@node Motion in C
-@subsection C Mode Motion Commands
-
- This section describes commands for moving point, in C mode and
-related modes.
-
-@table @code
-@item M-x c-beginning-of-defun
-@itemx M-x c-end-of-defun
-@findex c-beginning-of-defun
-@findex c-end-of-defun
-Move point to the beginning or end of the current function or
-top-level definition. These are found by searching for the least
-enclosing braces. (By contrast, @code{beginning-of-defun} and
-@code{end-of-defun} search for braces in column zero.) If you are
-editing code where the opening brace of a function isn't placed in
-column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
-these commands. @xref{Moving by Defuns}.
-
-@item C-c C-u
-@kindex C-c C-u @r{(C mode)}
-@findex c-up-conditional
-Move point back to the containing preprocessor conditional, leaving the
-mark behind. A prefix argument acts as a repeat count. With a negative
-argument, move point forward to the end of the containing
-preprocessor conditional.
-
-@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
-the function will stop at a @samp{#elif} when going backward, but not
-when going forward.
-
-@item C-c C-p
-@kindex C-c C-p @r{(C mode)}
-@findex c-backward-conditional
-Move point back over a preprocessor conditional, leaving the mark
-behind. A prefix argument acts as a repeat count. With a negative
-argument, move forward.
-
-@item C-c C-n
-@kindex C-c C-n @r{(C mode)}
-@findex c-forward-conditional
-Move point forward across a preprocessor conditional, leaving the mark
-behind. A prefix argument acts as a repeat count. With a negative
-argument, move backward.
-
-@item M-a
-@kindex M-a (C mode)
-@findex c-beginning-of-statement
-Move point to the beginning of the innermost C statement
-(@code{c-beginning-of-statement}). If point is already at the beginning
-of a statement, move to the beginning of the preceding statement. With
-prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
-
-In comments or in strings which span more than one line, this command
-moves by sentences instead of statements.
-
-@item M-e
-@kindex M-e (C mode)
-@findex c-end-of-statement
-Move point to the end of the innermost C statement or sentence; like
-@kbd{M-a} except that it moves in the other direction
-(@code{c-end-of-statement}).
-
-@item M-x c-backward-into-nomenclature
-@findex c-backward-into-nomenclature
-Move point backward to beginning of a C++ nomenclature section or
-word. With prefix argument @var{n}, move @var{n} times. If @var{n}
-is negative, move forward. C++ nomenclature means a symbol name in
-the style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital
-letter begins a section or word. Rather than this command, you might
-well prefer the newer ``Subword Mode'', which does the same thing
-better. @xref{Other C Commands}.
-
-In the GNU project, we recommend using underscores to separate words
-within an identifier in C or C++, rather than using case distinctions.
-
-@item M-x c-forward-into-nomenclature
-@findex c-forward-into-nomenclature
-Move point forward to end of a C++ nomenclature section or word.
-With prefix argument @var{n}, move @var{n} times.
-@end table
-
-@node Electric C
-@subsection Electric C Characters
-
- In C mode and related modes, certain printing characters are
-@dfn{electric}---in addition to inserting themselves, they also
-reindent the current line, and optionally also insert newlines. The
-``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
-@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
-@kbd{)}.
-
- You might find electric indentation inconvenient if you are editing
-chaotically indented code. If you are new to CC Mode, you might find
-it disconcerting. You can toggle electric action with the command
-@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
-after the mode name:
-
-@table @kbd
-@item C-c C-l
-@kindex C-c C-l @r{(C mode)}
-@findex c-toggle-electric-state
-Toggle electric action (@code{c-toggle-electric-state}). With a
-prefix argument, this command enables electric action if the argument
-is positive, disables it if it is negative.
-@end table
-
- Electric characters insert newlines only when, in addition to the
-electric state, the @dfn{auto-newline} feature is enabled (indicated
-by @samp{/la} in the mode line after the mode name). You can turn
-this feature on or off with the command @kbd{C-c C-a}:
-
-@table @kbd
-@item C-c C-a
-@kindex C-c C-a @r{(C mode)}
-@findex c-toggle-auto-newline
-Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
-prefix argument, this command turns the auto-newline feature on if the
-argument is positive, and off if it is negative.
-@end table
-
- Usually the CC Mode style configures the exact circumstances in
-which Emacs inserts auto-newlines. You can also configure this
-directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
-
-@node Hungry Delete
-@subsection Hungry Delete Feature in C
-@cindex hungry deletion (C Mode)
-
- If you want to delete an entire block of whitespace at point, you
-can use @dfn{hungry deletion}. This deletes all the contiguous
-whitespace either before point or after point in a single operation.
-@dfn{Whitespace} here includes tabs and newlines, but not comments or
-preprocessor commands.
-
-@table @kbd
-@item C-c C-@key{BS}
-@itemx C-c @key{BS}
-@findex c-hungry-backspace
-@kindex C-c C-@key{BS} (C Mode)
-@kindex C-c @key{BS} (C Mode)
-@code{c-hungry-backspace}---Delete the entire block of whitespace
-preceding point.
-
-@item C-c C-d
-@itemx C-c C-@key{DEL}
-@itemx C-c @key{DEL}
-@findex c-hungry-delete-forward
-@kindex C-c C-d (C Mode)
-@kindex C-c C-@key{DEL} (C Mode)
-@kindex C-c @key{DEL} (C Mode)
-@code{c-hungry-delete-forward}---Delete the entire block of whitespace
-following point.
-@end table
-
- As an alternative to the above commands, you can enable @dfn{hungry
-delete mode}. When this feature is enabled (indicated by @samp{/h} in
-the mode line after the mode name), a single @key{BS} command deletes
-all preceding whitespace, not just one space, and a single @kbd{C-c
-C-d} (but @emph{not} @key{delete}) deletes all following whitespace.
-
-@table @kbd
-@item M-x c-toggle-hungry-state
-@findex c-toggle-hungry-state
-Toggle the hungry-delete feature
-(@code{c-toggle-hungry-state})@footnote{This command had the binding
-@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now
-bound to @code{c-hungry-delete-forward}.}. With a prefix argument,
-this command turns the hungry-delete feature on if the argument is
-positive, and off if it is negative.
-@end table
-
-@vindex c-hungry-delete-key
- The variable @code{c-hungry-delete-key} controls whether the
-hungry-delete feature is enabled.
-
-@node Other C Commands
-@subsection Other Commands for C Mode
-
-@table @kbd
-@item C-c C-w
-@itemx M-x c-subword-mode
-@findex c-subword-mode
-Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word
-commands then recognize upper case letters in
-@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by
-the flag @samp{/w} on the mode line after the mode name
-(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in
-non-CC Mode buffers.
-
-@item M-x c-context-line-break
-@findex c-context-line-break
-This command inserts a line break and indents the new line in a manner
-appropriate to the context. In normal code, it does the work of
-@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
-additionally inserts a @samp{\} at the line break, and within comments
-it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
-
-@code{c-context-line-break} isn't bound to a key by default, but it
-needs a binding to be useful. The following code will bind it to
-@kbd{C-j}. We use @code{c-initialization-hook} here to make sure
-the keymap is loaded before we try to change it.
-
-@example
-(defun my-bind-clb ()
- (define-key c-mode-base-map "\C-j" 'c-context-line-break))
-(add-hook 'c-initialization-hook 'my-bind-clb)
-@end example
-
-@item C-M-h
-Put mark at the end of a function definition, and put point at the
-beginning (@code{c-mark-function}).
-
-@item M-q
-@kindex M-q @r{(C mode)}
-@findex c-fill-paragraph
-Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
-If any part of the current line is a comment or within a comment, this
-command fills the comment or the paragraph of it that point is in,
-preserving the comment indentation and comment delimiters.
-
-@item C-c C-e
-@cindex macro expansion in C
-@cindex expansion of C macros
-@findex c-macro-expand
-@kindex C-c C-e @r{(C mode)}
-Run the C preprocessor on the text in the region, and show the result,
-which includes the expansion of all the macro calls
-(@code{c-macro-expand}). The buffer text before the region is also
-included in preprocessing, for the sake of macros defined there, but the
-output from this part isn't shown.
-
-When you are debugging C code that uses macros, sometimes it is hard to
-figure out precisely how the macros expand. With this command, you
-don't have to figure it out; you can see the expansions.
-
-@item C-c C-\
-@findex c-backslash-region
-@kindex C-c C-\ @r{(C mode)}
-Insert or align @samp{\} characters at the ends of the lines of the
-region (@code{c-backslash-region}). This is useful after writing or
-editing a C macro definition.
-
-If a line already ends in @samp{\}, this command adjusts the amount of
-whitespace before it. Otherwise, it inserts a new @samp{\}. However,
-the last line in the region is treated specially; no @samp{\} is
-inserted on that line, and any @samp{\} there is deleted.
-
-@item M-x cpp-highlight-buffer
-@cindex preprocessor highlighting
-@findex cpp-highlight-buffer
-Highlight parts of the text according to its preprocessor conditionals.
-This command displays another buffer named @samp{*CPP Edit*}, which
-serves as a graphic menu for selecting how to display particular kinds
-of conditionals and their contents. After changing various settings,
-click on @samp{[A]pply these settings} (or go to that buffer and type
-@kbd{a}) to rehighlight the C mode buffer accordingly.
-
-@item C-c C-s
-@findex c-show-syntactic-information
-@kindex C-c C-s @r{(C mode)}
-Display the syntactic information about the current source line
-(@code{c-show-syntactic-information}). This information directs how
-the line is indented.
-
-@item M-x cwarn-mode
-@itemx M-x global-cwarn-mode
-@findex cwarn-mode
-@findex global-cwarn-mode
-@vindex global-cwarn-mode
-@cindex CWarn mode
-@cindex suspicious constructions in C, C++
-CWarn minor mode highlights certain suspicious C and C++ constructions:
-
-@itemize @bullet{}
-@item
-Assignments inside expressions.
-@item
-Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
-(except after a @samp{do @dots{} while} statement);
-@item
-C++ functions with reference parameters.
-@end itemize
-
-@noindent
-You can enable the mode for one buffer with the command @kbd{M-x
-cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
-global-cwarn-mode} or by customizing the variable
-@code{global-cwarn-mode}. You must also enable Font Lock mode to make
-it work.
-
-@item M-x hide-ifdef-mode
-@findex hide-ifdef-mode
-@cindex Hide-ifdef mode
-Hide-ifdef minor mode hides selected code within @samp{#if} and
-@samp{#ifdef} preprocessor blocks. See the documentation string of
-@code{hide-ifdef-mode} for more information.
-
-@item M-x ff-find-related-file
-@cindex related files
-@findex ff-find-related-file
-@vindex ff-related-file-alist
-Find a file ``related'' in a special way to the file visited by the
-current buffer. Typically this will be the header file corresponding
-to a C/C++ source file, or vice versa. The variable
-@code{ff-related-file-alist} specifies how to compute related file
-names.
-@end table
-
-@node Fortran
-@section Fortran Mode
-@cindex Fortran mode
-@cindex mode, Fortran
-
- 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.
-Fortran mode has support for Auto Fill mode that breaks long lines into
-proper Fortran continuation lines.
-
- Special commands for comments are provided because Fortran comments
-are unlike those of other languages. Built-in abbrevs optionally save
-typing when you insert Fortran keywords.
-
- Use @kbd{M-x fortran-mode} to switch to this major mode. This command
-runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
-
-@cindex Fortran77 and Fortran90
-@findex f90-mode
-@findex fortran-mode
- Fortran mode is meant for editing Fortran77 ``fixed format'' (and also
-``tab format'') source code. For editing the modern Fortran90 or
-Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}).
-Emacs normally uses Fortran mode for files with extension @samp{.f},
-@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and
-@samp{.f95}. GNU Fortran supports both kinds of format.
-
-@menu
-* Motion: Fortran Motion. Moving point by statements or subprograms.
-* Indent: Fortran Indent. Indentation commands for Fortran.
-* Comments: Fortran Comments. Inserting and aligning comments.
-* Autofill: Fortran Autofill. Auto fill support for Fortran.
-* Columns: Fortran Columns. Measuring columns for valid Fortran.
-* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
-@end menu
-
-@node Fortran Motion
-@subsection Motion Commands
-
- In addition to the normal commands for moving by and operating on
-``defuns'' (Fortran subprograms---functions and subroutines, as well as
-modules for F90 mode), Fortran mode provides special commands to move by
-statements and other program units.
-
-@table @kbd
-@kindex C-c C-n @r{(Fortran mode)}
-@findex fortran-next-statement
-@findex f90-next-statement
-@item C-c C-n
-Move to the beginning of the next statement
-(@code{fortran-next-statement}/@code{f90-next-statement}).
-
-@kindex C-c C-p @r{(Fortran mode)}
-@findex fortran-previous-statement
-@findex f90-previous-statement
-@item C-c C-p
-Move to the beginning of the previous statement
-(@code{fortran-previous-statement}/@code{f90-previous-statement}).
-If there is no previous statement (i.e. if called from the first
-statement in the buffer), move to the start of the buffer.
-
-@kindex C-c C-e @r{(F90 mode)}
-@findex f90-next-block
-@item C-c C-e
-Move point forward to the start of the next code block
-(@code{f90-next-block}). A code block is a subroutine,
-@code{if}--@code{endif} statement, and so forth. This command exists
-for F90 mode only, not Fortran mode. With a numeric argument, this
-moves forward that many blocks.
-
-@kindex C-c C-a @r{(F90 mode)}
-@findex f90-previous-block
-@item C-c C-a
-Move point backward to the previous code block
-(@code{f90-previous-block}). This is like @code{f90-next-block}, but
-moves backwards.
-
-@kindex C-M-n @r{(Fortran mode)}
-@findex fortran-end-of-block
-@findex f90-end-of-block
-@item C-M-n
-Move to the end of the current code block
-(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric
-agument, move forward that number of blocks. The mark is set before
-moving point. The F90 mode version of this command checks for
-consistency of block types and labels (if present), but it does not
-check the outermost block since that may be incomplete.
-
-@kindex C-M-p @r{(Fortran mode)}
-@findex fortran-beginning-of-block
-@findex f90-beginning-of-block
-@item C-M-p
-Move to the start of the current code block
-(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This
-is like @code{fortran-end-of-block}, but moves backwards.
-@end table
-
-@node Fortran Indent
-@subsection Fortran Indentation
-
- Special commands and features are needed for indenting Fortran code in
-order to make sure various syntactic entities (line numbers, comment line
-indicators and continuation line flags) appear in the columns that are
-required for standard, fixed (or tab) format Fortran.
-
-@menu
-* Commands: ForIndent Commands. Commands for indenting and filling Fortran.
-* Contline: ForIndent Cont. How continuation lines indent.
-* 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.
-@end menu
-
-@node ForIndent Commands
-@subsubsection Fortran Indentation and Filling Commands
-
-@table @kbd
-@item C-M-j
-Break the current line at point and set up a continuation line
-(@code{fortran-split-line}).
-@item M-^
-Join this line to the previous line (@code{fortran-join-line}).
-@item C-M-q
-Indent all the lines of the subprogram point is in
-(@code{fortran-indent-subprogram}).
-@item M-q
-Fill a comment block or statement.
-@end table
-
-@kindex C-M-q @r{(Fortran mode)}
-@findex fortran-indent-subprogram
- The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
-to reindent all the lines of the Fortran subprogram (function or
-subroutine) containing point.
-
-@kindex C-M-j @r{(Fortran mode)}
-@findex fortran-split-line
- The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
-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.
-
-@kindex M-^ @r{(Fortran mode)}
-@kindex C-c C-d @r{(Fortran mode)}
-@findex fortran-join-line
- @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
-which joins a continuation line back to the previous line, roughly as
-the inverse of @code{fortran-split-line}. The point must be on a
-continuation line when this command is invoked.
-
-@kindex M-q @r{(Fortran mode)}
-@kbd{M-q} in Fortran mode fills the comment block or statement that
-point is in. This removes any excess statement continuations.
-
-@node ForIndent Cont
-@subsubsection Continuation Lines
-@cindex Fortran continuation lines
-
-@vindex fortran-continuation-string
- Most Fortran77 compilers allow two ways of writing continuation lines.
-If the first non-space character on a line is in column 5, then that
-line is a continuation of the previous line. We call this @dfn{fixed
-format}. (In GNU Emacs we always count columns from 0; but note that
-the Fortran standard counts from 1.) The variable
-@code{fortran-continuation-string} specifies what character to put in
-column 5. A line that starts with a tab character followed by any digit
-except @samp{0} is also a continuation line. We call this style of
-continuation @dfn{tab format}. (Fortran90 introduced ``free format'',
-with another style of continuation lines).
-
-@vindex indent-tabs-mode @r{(Fortran mode)}
-@vindex fortran-analyze-depth
-@vindex fortran-tab-mode-default
- Fortran mode can use either style of continuation line. When you
-enter Fortran mode, it tries to deduce the proper continuation style
-automatically from the buffer contents. It does this by scanning up to
-@code{fortran-analyze-depth} (default 100) lines from the start of the
-buffer. The first line that begins with either a tab character or six
-spaces determines the choice. If the scan fails (for example, if the
-buffer is new and therefore empty), the value of
-@code{fortran-tab-mode-default} (@code{nil} for fixed format, and
-non-@code{nil} for tab format) is used. @samp{/t} in the mode line
-indicates tab format is selected. Fortran mode sets the value of
-@code{indent-tabs-mode} accordingly (@pxref{Just Spaces}).
-
- If the text on a line starts with the Fortran continuation marker
-@samp{$}, or if it begins with any non-whitespace character in column
-5, Fortran mode treats it as a continuation line. When you indent a
-continuation line with @key{TAB}, it converts the line to the current
-continuation style. When you split a Fortran statement with
-@kbd{C-M-j}, the continuation marker on the newline is created according
-to the continuation style.
-
- The setting of continuation style affects several other aspects of
-editing in Fortran mode. In fixed format mode, the minimum column
-number for the body of a statement is 6. Lines inside of Fortran
-blocks that are indented to larger column numbers always use only the
-space character for whitespace. In tab format mode, the minimum
-column number for the statement body is 8, and the whitespace before
-column 8 must always consist of one tab character.
-
-@node ForIndent Num
-@subsubsection Line Numbers
-
- If a number is the first non-whitespace in the line, Fortran
-indentation assumes it is a line number and moves it to columns 0
-through 4. (Columns always count from 0 in GNU Emacs.)
-
-@vindex fortran-line-number-indent
- Line numbers of four digits or less are normally indented one space.
-The variable @code{fortran-line-number-indent} controls this; it
-specifies the maximum indentation a line number can have. The default
-value of the variable is 1. Fortran mode tries to prevent line number
-digits passing column 4, reducing the indentation below the specified
-maximum if necessary. If @code{fortran-line-number-indent} has the
-value 5, line numbers are right-justified to end in column 4.
-
-@vindex fortran-electric-line-number
- 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
-@code{fortran-electric-line-number} to @code{nil}.
-
-
-@node ForIndent Conv
-@subsubsection Syntactic Conventions
-
- Fortran mode assumes that you follow certain conventions that simplify
-the task of understanding a Fortran program well enough to indent it
-properly:
-
-@itemize @bullet
-@item
-Two nested @samp{do} loops never share a @samp{continue} statement.
-
-@item
-Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
-and others are written without embedded whitespace or line breaks.
-
-Fortran compilers generally ignore whitespace outside of string
-constants, but Fortran mode does not recognize these keywords if they
-are not contiguous. Constructs such as @samp{else if} or @samp{end do}
-are acceptable, but the second word should be on the same line as the
-first and not on a continuation line.
-@end itemize
-
-@noindent
-If you fail to follow these conventions, the indentation commands may
-indent some lines unaesthetically. However, a correct Fortran program
-retains its meaning when reindented even if the conventions are not
-followed.
-
-@node ForIndent Vars
-@subsubsection Variables for Fortran Indentation
-
-@vindex fortran-do-indent
-@vindex fortran-if-indent
-@vindex fortran-structure-indent
-@vindex fortran-continuation-indent
-@vindex fortran-check-all-num@dots{}
-@vindex fortran-minimum-statement-indent@dots{}
- Several additional variables control how Fortran indentation works:
-
-@table @code
-@item fortran-do-indent
-Extra indentation within each level of @samp{do} statement (default 3).
-
-@item fortran-if-indent
-Extra indentation within each level of @samp{if}, @samp{select case}, or
-@samp{where} statements (default 3).
-
-@item fortran-structure-indent
-Extra indentation within each level of @samp{structure}, @samp{union},
-@samp{map}, or @samp{interface} statements (default 3).
-
-@item fortran-continuation-indent
-Extra indentation for bodies of continuation lines (default 5).
-
-@item fortran-check-all-num-for-matching-do
-In Fortran77, a numbered @samp{do} statement is ended by any statement
-with a matching line number. It is common (but not compulsory) to use a
-@samp{continue} statement for this purpose. If this variable has a
-non-@code{nil} value, indenting any numbered statement must check for a
-@samp{do} that ends there. If you always end @samp{do} statements with
-a @samp{continue} line (or if you use the more modern @samp{enddo}),
-then you can speed up indentation by setting this variable to
-@code{nil}. The default is @code{nil}.
-
-@item fortran-blink-matching-if
-If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
-statement moves the cursor momentarily to the matching @samp{if} (or
-@samp{do}) statement to show where it is. The default is @code{nil}.
-
-@item fortran-minimum-statement-indent-fixed
-Minimum indentation for Fortran statements when using fixed format
-continuation line style. Statement bodies are never indented less than
-this much. The default is 6.
-
-@item fortran-minimum-statement-indent-tab
-Minimum indentation for Fortran statements for tab format continuation line
-style. Statement bodies are never indented less than this much. The
-default is 8.
-@end table
-
-The variables controlling the indentation of comments are described in
-the following section.
-
-@node Fortran Comments
-@subsection Fortran Comments
-
- The usual Emacs comment commands assume that a comment can follow a
-line of code. In Fortran77, 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.
-
-@vindex fortran-comment-line-start
- Fortran mode can also handle the Fortran90 comment syntax where comments
-start with @samp{!} and can follow other text. Because only some Fortran77
-compilers accept this syntax, Fortran mode will not insert such comments
-unless you have said in advance to do so. To do this, set the variable
-@code{fortran-comment-line-start} to @samp{"!"}.
-
-@table @kbd
-@item M-;
-Align comment or insert new comment (@code{fortran-indent-comment}).
-
-@item C-x ;
-Applies to nonstandard @samp{!} comments only.
-
-@item C-c ;
-Turn all lines of the region into comments, or (with argument) turn them back
-into real code (@code{fortran-comment-region}).
-@end table
-
-@findex fortran-indent-comment
- @kbd{M-;} in Fortran mode is redefined as the command
-@code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this
-recognizes any kind of existing comment and aligns its text appropriately;
-if there is no existing comment, a comment is inserted and aligned. But
-inserting and aligning comments are not the same in Fortran mode as in
-other modes.
-
- When a new comment must be inserted, if the current line is blank, a
-full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
-comment is inserted if you have said you want to use them. Otherwise a
-full-line comment is inserted on a new line before the current line.
-
- Nonstandard @samp{!} comments are aligned like comments in other
-languages, but full-line comments are different. 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
-@code{fortran-comment-indent-style} to one of these values:
-
-@vindex fortran-comment-indent-style
-@vindex fortran-comment-line-extra-indent
-@table @code
-@item fixed
-Align the text at a fixed column, which is the sum of
-@code{fortran-comment-line-extra-indent} and the minimum statement
-indentation. This is the default.
-
-The minimum statement indentation is
-@code{fortran-minimum-statement-indent-fixed} for fixed format
-continuation line style and @code{fortran-minimum-statement-indent-tab}
-for tab format style.
-
-@item relative
-Align the text as if it were a line of code, but with an additional
-@code{fortran-comment-line-extra-indent} columns of indentation.
-
-@item nil
-Don't move text in full-line comments automatically.
-@end table
-
-@vindex fortran-comment-indent-char
- In addition, you can specify the character to be used to indent within
-full-line comments by setting the variable
-@code{fortran-comment-indent-char} to the single-character string you want
-to use.
-
-@vindex fortran-directive-re
- Compiler directive lines, or preprocessor lines, have much the same
-appearance as comment lines. It is important, though, that such lines
-never be indented at all, no matter what the value of
-@code{fortran-comment-indent-style}. The variable
-@code{fortran-directive-re} is a regular expression that specifies which
-lines are directives. Matching lines are never indented, and receive
-distinctive font-locking.
-
- The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
-you use @samp{!} comments, this command can be used with them. Otherwise
-it is useless in Fortran mode.
-
-@kindex C-c ; @r{(Fortran mode)}
-@findex fortran-comment-region
-@vindex fortran-comment-region
- The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
-lines of the region into comments by inserting the string @samp{C$$$} at
-the front of each one. With a numeric argument, it turns the region
-back into live code by deleting @samp{C$$$} from the front of each line
-in it. The string used for these comments can be controlled by setting
-the variable @code{fortran-comment-region}. Note that here we have an
-example of a command and a variable with the same name; these two uses
-of the name never conflict because in Lisp and in Emacs it is always
-clear from the context which one is meant.
-
-@node Fortran Autofill
-@subsection Auto Fill in Fortran Mode
-
- Fortran mode has specialized support for Auto Fill mode, which is a
-minor mode that automatically splits statements as you insert them when
-they become too wide. Splitting a statement involves making
-continuation lines using @code{fortran-continuation-string}
-(@pxref{ForIndent Cont}). This splitting happens when you type
-@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran indentation
-commands. You activate Auto Fill in Fortran mode in the normal way
-(@pxref{Auto Fill}).
-
-@vindex fortran-break-before-delimiters
- Auto Fill breaks lines at spaces or delimiters when the lines get
-longer than the desired width (the value of @code{fill-column}). The
-delimiters (besides whitespace) that Auto Fill can break at are
-@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>},
-and @samp{,}. The line break comes after the delimiter if the
-variable @code{fortran-break-before-delimiters} is @code{nil}.
-Otherwise (and by default), the break comes before the delimiter.
-
- To enable Auto Fill in all Fortran buffers, add
-@code{turn-on-auto-fill} to @code{fortran-mode-hook}. @xref{Hooks}.
-
-@node Fortran Columns
-@subsection Checking Columns in Fortran
-
-@table @kbd
-@item C-c C-r
-Display a ``column ruler'' momentarily above the current line
-(@code{fortran-column-ruler}).
-@item C-c C-w
-Split the current window horizontally temporarily so that it is 72
-columns wide (@code{fortran-window-create-momentarily}). This may
-help you avoid making lines longer than the 72-character limit that
-some Fortran compilers impose.
-@item C-u C-c C-w
-Split the current window horizontally so that it is 72 columns wide
-(@code{fortran-window-create}). You can then continue editing.
-@item M-x fortran-strip-sequence-nos
-Delete all text in column 72 and beyond.
-@end table
-
-@kindex C-c C-r @r{(Fortran mode)}
-@findex fortran-column-ruler
- The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
-ruler momentarily above the current line. The comment ruler is two lines
-of text that show you the locations of columns with special significance in
-Fortran programs. Square brackets show the limits of the columns for line
-numbers, and curly brackets show the limits of the columns for the
-statement body. Column numbers appear above them.
-
- Note that the column numbers count from zero, as always in GNU Emacs.
-As a result, the numbers may be one less than those you are familiar
-with; but the positions they indicate in the line are standard for
-Fortran.
-
-@vindex fortran-column-ruler-fixed
-@vindex fortran-column-ruler-tabs
- The text used to display the column ruler depends on the value of the
-variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
-@code{nil}, then the value of the variable
-@code{fortran-column-ruler-fixed} is used as the column ruler.
-Otherwise, the value of the variable @code{fortran-column-ruler-tab} is
-displayed. By changing these variables, you can change the column ruler
-display.
-
-@kindex C-c C-w @r{(Fortran mode)}
-@findex fortran-window-create-momentarily
- @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
-splits the current window horizontally, making a window 72 columns
-wide, so you can see any lines that are too long. Type a space to
-restore the normal width.
-
-@kindex C-u C-c C-w @r{(Fortran mode)}
-@findex fortran-window-create
- You can also split the window horizontally and continue editing with
-the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x
-fortran-window-create}). By editing in this window you can
-immediately see when you make a line too wide to be correct Fortran.
-
-@findex fortran-strip-sequence-nos
- The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in
-column 72 and beyond, on all lines in the current buffer. This is the
-easiest way to get rid of old sequence numbers.
-
-@node Fortran Abbrev
-@subsection Fortran Keyword Abbrevs
-
- Fortran mode provides many built-in abbrevs for common keywords and
-declarations. These are the same sort of abbrev that you can define
-yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}.
-
- The built-in abbrevs are unusual in one way: they all start with a
-semicolon. You cannot normally use semicolon in an abbrev, but Fortran
-mode makes this possible by changing the syntax of semicolon to ``word
-constituent.''
-
- For example, one built-in Fortran abbrev is @samp{;c} for
-@samp{continue}. If you insert @samp{;c} and then insert a punctuation
-character such as a space or a newline, the @samp{;c} expands automatically
-to @samp{continue}, provided Abbrev mode is enabled.@refill
-
- Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
-Fortran abbrevs and what they stand for.
-
-@node Asm Mode
-@section Asm Mode
-
-@cindex Asm mode
-@cindex assembler mode
-Asm mode is a major mode for editing files of assembler code. It
-defines these commands:
-
-@table @kbd
-@item @key{TAB}
-@code{tab-to-tab-stop}.
-@item C-j
-Insert a newline and then indent using @code{tab-to-tab-stop}.
-@item :
-Insert a colon and then remove the indentation from before the label
-preceding colon. Then do @code{tab-to-tab-stop}.
-@item ;
-Insert or align a comment.
-@end table
-
- The variable @code{asm-comment-char} specifies which character
-starts comments in assembler syntax.
-
-@ignore
- arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0
-@end ignore