[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/man/programs.texi [gnus-5_10-branch]
From: |
Miles Bader |
Subject: |
[Emacs-diffs] Changes to emacs/man/programs.texi [gnus-5_10-branch] |
Date: |
Sat, 04 Sep 2004 08:44:03 -0400 |
Index: emacs/man/programs.texi
diff -c /dev/null emacs/man/programs.texi:1.82.2.1
*** /dev/null Sat Sep 4 12:03:05 2004
--- emacs/man/programs.texi Sat Sep 4 12:01:15 2004
***************
*** 0 ****
--- 1,2297 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 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
+ Insert, kill or align comments (@pxref{Comments}).
+ @item
+ Balance parentheses (@pxref{Parentheses}).
+ @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 @address@hidden,
+ 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 Simula mode
+ @cindex VHDL mode
+ @cindex M4 mode
+ @cindex Shell-script mode
+ @cindex Delphi mode
+ @cindex PostScript mode
+ The existing programming language major modes include Lisp, Scheme (a
+ variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
+ 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, Simula, Tcl, and VHDL. There is
+ also a major mode for makefiles, called Makefile mode. 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 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 is
+ called a @dfn{defun}. The name comes from Lisp, but in Emacs we use
+ it for all languages.
+
+ In most 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 normally a defun, because the open-brace that
+ begins it is normally at the left margin. 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
+ In most major modes, Emacs assumes that any opening delimiter found
+ at the left margin is the start of a top-level definition, or defun.
+ Therefore, @strong{never put an opening delimiter at the left margin
+ unless it should have that significance.} 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. Never put an open-brace or other opening
+ delimiter at the beginning of a line of C code unless it is at top
+ level.
+
+ 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 C and 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, it mandates following the convention described
+ above.
+
+ @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 @address@hidden 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.
+
+ 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 address@hidden 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 only takes effect 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{indent-for-tab-command}
+ 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 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 lines that start within a parenthetical grouping
+ each under the preceding line (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.
+
+ Remember that 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. Therefore, you must never have an opening
+ delimiter in column zero that is not the beginning of a function, not even
+ inside a string. This restriction is vital for making the indentation
+ commands fast; you must simply accept it. @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-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-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-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.
+
+ @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 address@hidden, 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. 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}, @code{cc-mode}, and @code{user}.
+ 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 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") (other . "gnu")))
+ @end example
+
+ @noindent
+ specifies an explicit choice for Java mode, and the default @samp{gnu}
+ style for the other C-like modes. 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{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
+ @address@hidden 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 address@hidden
+ 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
+ @address@hidden 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, and 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 address@hidden
+ @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 @address@hidden is equivalent to @kbd{C-M-@@}.
+
+ 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}).
+ @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
+
+ In C code, a comment preceded on its line by nothing but whitespace
+ is indented like a line of code.
+
+ @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}). This terminates the comment you are
+ typing, creates a new blank line afterward, and begins a new comment
+ indented under the old one. 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. If point is not at the end of the line when you
+ type the command, the text on the rest of the line becomes part of the
+ new comment line.
+
+ @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. 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.
+
+ @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.
+ @address@hidden"/\\*+ *\\|//+ *"}}, 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{Regexps}.)
+
+ @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. In C mode, @code{comment-start} has the value
+ @address@hidden"/* "}} and @code{comment-end} has the value @address@hidden"
*/"}}.
+
+ @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
+ default value), 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.
+
+ @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. You specify the symbol with the
+ minibuffer; the default is the symbol appearing in the buffer at
+ point.
+
+ 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
+ @address@hidden(@var{section})} or @address@hidden @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} address@hidden 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}
+ address@hidden 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 the 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.) Eldoc mode applies in Emacs Lisp and Lisp
+ Interaction modes only. 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 user options exist for customizing Hideshow mode.
+
+ @table @code
+ @item hs-hide-comments-when-hiding-all
+ address@hidden 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 @address@hidden 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 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, @address@hidden 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, @address@hidden 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
+ @address@hidden with no argument; to complete the name of a standard
+ library function, use @kbd{C-u address@hidden 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, @address@hidden 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.
+
+ 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
+ ``electric''---in addition to inserting themselves, they also reindent
+ the current line and may insert newlines. This feature is controlled by
+ the variable @code{c-auto-newline}. The ``electric'' characters are
+ @address@hidden, @address@hidden, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
+ @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
+
+ Electric characters insert newlines only when the @dfn{auto-newline}
+ feature is enabled (indicated by @samp{/a} in the mode line after the
+ mode name). This feature is controlled by the variable
+ @code{c-auto-newline}. 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-state
+ Toggle the auto-newline feature (@code{c-toggle-auto-state}). 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
+
+ The colon character is electric because that is appropriate for a
+ single colon. But when you want to insert a double colon in C++, the
+ electric behavior of colon is inconvenient. You can insert a double
+ colon with no reindentation or newlines by typing @kbd{C-c :}:
+
+ @table @kbd
+ @item C-c :
+ @ifinfo
+ @c This uses ``colon'' instead of a literal `:' because Info cannot
+ @c cope with a `:' in a menu
+ @kindex C-c @key{colon} @r{(C mode)}
+ @end ifinfo
+ @ifnotinfo
+ @kindex C-c : @r{(C mode)}
+ @end ifnotinfo
+ @findex c-scope-operator
+ Insert a double colon scope operator at point, without reindenting the
+ line or adding any newlines (@code{c-scope-operator}).
+ @end table
+
+ @vindex c-electric-pound-behavior
+ The electric @kbd{#} key reindents the line if it appears to be the
+ beginning of a preprocessor directive. This happens when the value of
+ @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
+ this feature off by setting @code{c-electric-pound-behavior} to
+ @code{nil}.
+
+ @vindex c-hanging-braces-alist
+ The variable @code{c-hanging-braces-alist} controls the insertion of
+ newlines before and after inserted braces. It is an association list
+ with elements of the following form: @code{(@var{syntactic-symbol}
+ . @var{nl-list})}. Most of the syntactic symbols that appear in
+ @code{c-offsets-alist} are meaningful here as well.
+
+ The list @var{nl-list} may contain either of the symbols
+ @code{before} or @code{after}, or both; or it may be @code{nil}. When a
+ brace is inserted, the syntactic context it defines is looked up in
+ @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
+ to determine where newlines are inserted: either before the brace,
+ after, or both. If not found, the default is to insert a newline both
+ before and after braces.
+
+ @vindex c-hanging-colons-alist
+ The variable @code{c-hanging-colons-alist} controls the insertion of
+ newlines before and after inserted colons. It is an association list
+ with elements of the following form: @code{(@var{syntactic-symbol}
+ . @var{nl-list})}. The list @var{nl-list} may contain either of the
+ symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
+
+ When a colon is inserted, the syntactic symbol it defines is looked
+ up in this list, and if found, the @var{nl-list} is used to determine
+ where newlines are inserted: either before the brace, after, or both.
+ If the syntactic symbol is not found in this list, no newlines are
+ inserted.
+
+ @vindex c-cleanup-list
+ Electric characters can also delete newlines automatically when the
+ auto-newline feature is enabled. This feature makes auto-newline more
+ acceptable, by deleting the newlines in the most common cases where you
+ do not want them. Emacs can recognize several cases in which deleting a
+ newline might be desirable; by setting the variable
+ @code{c-cleanup-list}, you can specify @emph{which} of these cases that
+ should happen. The variable's value is a list of symbols, each
+ describing one case for possible deletion of a newline. Here are the
+ meaningful symbols, and their meanings:
+
+ @table @code
+ @item brace-catch-brace
+ Clean up @address@hidden catch (@var{condition}) @{} constructs by placing the
+ entire construct on a single line. The clean-up occurs when you type
+ the @address@hidden, if there is nothing between the braces aside from
+ @code{catch} and @var{condition}.
+
+ @item brace-else-brace
+ Clean up @address@hidden else @{} constructs by placing the entire construct
on
+ a single line. The clean-up occurs when you type the @address@hidden after
+ the @code{else}, but only if there is nothing but white space between
+ the braces and the @code{else}.
+
+ @item brace-elseif-brace
+ Clean up @address@hidden else if (@dots{}) @{} constructs by placing the
entire
+ construct on a single line. The clean-up occurs when you type the
+ @address@hidden, if there is nothing but white space between the
@address@hidden and
+ @address@hidden aside from the keywords and the @code{if}-condition.
+
+ @item empty-defun-braces
+ Clean up empty defun braces by placing the braces on the same
+ line. Clean-up occurs when you type the closing brace.
+
+ @item defun-close-semi
+ Clean up the semicolon after a @code{struct} or similar type
+ declaration, by placing the semicolon on the same line as the closing
+ brace. Clean-up occurs when you type the semicolon.
+
+ @item list-close-comma
+ Clean up commas following braces in array and aggregate
+ initializers. Clean-up occurs when you type the comma.
+
+ @item scope-operator
+ Clean up double colons which may designate a C++ scope operator, by
+ placing the colons together. Clean-up occurs when you type the second
+ colon, but only when the two colons are separated by nothing but
+ whitespace.
+ @end table
+
+ @node Hungry Delete
+ @subsection Hungry Delete Feature in C
+ @cindex hungry deletion (C Mode)
+
+ When the @dfn{hungry-delete} feature is enabled (indicated by
+ @samp{/h} or @samp{/ah} in the mode line after the mode name), a single
+ @key{DEL} command deletes all preceding whitespace, not just one space.
+ To turn this feature on or off, use @kbd{C-c C-d}:
+
+ @table @kbd
+ @item C-c C-d
+ @kindex C-c C-d @r{(C mode)}
+ @findex c-toggle-hungry-state
+ Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a
+ prefix argument, this command turns the hungry-delete feature on if the
+ argument is positive, and off if it is negative.
+
+ @item C-c C-t
+ @kindex C-c C-t @r{(C mode)}
+ @findex c-toggle-auto-hungry-state
+ Toggle the auto-newline and hungry-delete features, both at once
+ (@code{c-toggle-auto-hungry-state}).
+ @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 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}.
+ @example
+ (define-key c-mode-base-map "\C-j" 'c-context-line-break)
+ @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 is the information that
+ 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
+ its own 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'' source
+ code. For editing the modern Fortran90 ``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}. 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 minor mode 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), Fortran
+ mode provides special commands to move by statements.
+
+ @table @kbd
+ @kindex C-c C-n @r{(Fortran mode)}
+ @findex fortran-next-statement
+ @item C-c C-n
+ Move to beginning of current or next statement
+ (@code{fortran-next-statement}).
+
+ @kindex C-c C-p @r{(Fortran mode)}
+ @findex fortran-previous-statement
+ @item C-c C-p
+ Move to beginning of current or previous statement
+ (@code{fortran-previous-statement}).
+ @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 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 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 modern Fortran 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.) The
+ variable @code{fortran-continuation-string} specifies what character to
+ put on 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}.
+
+ @vindex indent-tabs-mode @r{(Fortran mode)}
+ Fortran mode can make either style of continuation line, but you
+ must specify which one you prefer. The value of the variable
+ @code{indent-tabs-mode} controls the choice: @code{nil} for fixed
+ format, and address@hidden for tab format. You can tell which style
+ is presently in effect by the presence or absence of the string
+ @samp{Tab} in the mode line.
+
+ If the text on a line starts with the conventional 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.
+
+ @vindex fortran-tab-mode-default
+ @vindex fortran-analyze-depth
+ When you enter Fortran mode for an existing file, it tries to deduce the
+ proper continuation style automatically from the file contents. The first
+ line that begins with either a tab character or six spaces determines the
+ choice. The variable @code{fortran-analyze-depth} specifies how many lines
+ to consider (at the beginning of the file); if none of those lines
+ indicates a style, then the variable @code{fortran-tab-mode-default}
+ specifies the style. If it is @code{nil}, that specifies fixed format, and
+ address@hidden specifies tab format.
+
+ @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. Line numbers
+ are indented to right-justify them to end in column 4 unless that would
+ require more than this maximum indentation. The default value of the
+ variable is 1.
+
+ @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}. Then inserting line
+ numbers is like inserting anything else.
+
+ @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 address@hidden
+ @vindex address@hidden
+ 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} statement (default 3).
+ This value is also used for extra indentation within each level of the
+ Fortran 90 @samp{where} statement.
+
+ @item fortran-structure-indent
+ Extra indentation within each level of @samp{structure}, @samp{union}, or
+ @samp{map} statements (default 3).
+
+ @item fortran-continuation-indent
+ Extra indentation for bodies of continuation lines (default 5).
+
+ @item fortran-check-all-num-for-matching-do
+ If this is @code{nil}, indentation assumes that each @samp{do} statement
+ ends on a @samp{continue} statement. Therefore, when computing
+ indentation for a statement other than @samp{continue}, it can save time
+ by not checking for a @samp{do} statement ending there. If this is
+ address@hidden, indenting any numbered statement must check for a
+ @samp{do} that ends there. The default is @code{nil}.
+
+ @item fortran-blink-matching-if
+ If this is @code{t}, indenting an @samp{endif} statement moves the
+ cursor momentarily to the matching @samp{if} 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
+
+ @node Fortran Comments
+ @subsection Fortran Comments
+
+ The usual Emacs comment commands assume that a comment can follow a line
+ of code. In Fortran, the standard comment syntax requires an entire line
+ to be just a comment. Therefore, Fortran mode replaces the standard Emacs
+ comment commands and defines some new variables.
+
+ Fortran mode can also handle 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{comment-start} to @samp{"!"} (@pxref{Variables}).
+
+ @table @kbd
+ @item M-;
+ Align comment or insert new comment (@code{fortran-comment-indent}).
+
+ @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
+
+ @kbd{M-;} in Fortran mode is redefined as the command
+ @code{fortran-comment-indent}. 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 at all.
+ @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.
+
+ @vindex comment-line-start
+ @vindex comment-line-start-skip
+ Fortran mode introduces two variables @code{comment-line-start} and
+ @code{comment-line-start-skip}, which play for full-line comments the same
+ roles played by @code{comment-start} and @code{comment-start-skip} for
+ ordinary text-following comments. Normally these are set properly by
+ Fortran mode, so you do not need to change them.
+
+ The normal Emacs comment command @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 Fortran Auto Fill Mode
+
+ Fortran Auto Fill mode is a minor mode which automatically splits
+ Fortran 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.
+
+ @findex fortran-auto-fill-mode
+ @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
+ was off, or off if it was on. This command works the same as @kbd{M-x
+ auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
+ positive numeric argument turns Fortran Auto Fill mode on, and a
+ negative argument turns it off. You can see when Fortran Auto Fill mode
+ is in effect by the presence of the word @samp{Fill} in the mode line,
+ inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
+ on or off for each buffer individually. @xref{Minor Modes}.
+
+ @vindex fortran-break-before-delimiters
+ Fortran Auto Fill mode breaks lines at spaces or delimiters when the
+ lines get longer than the desired width (the value of @code{fill-column}).
+ The delimiters that Fortran Auto Fill mode may 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.
+
+ By default, Fortran Auto Fill mode is not enabled. If you want this
+ feature turned on permanently, add a hook function to
+ @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
+ @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 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 which lines that is 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 address@hidden
+
+ 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/man/programs.texi [gnus-5_10-branch],
Miles Bader <=