comparison man/programs.texi @ 90072:cb67264d6096

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-2 Merge from emacs--cvs-trunk--0 Patches applied: * [e-mail]--gnu-2004/gnus--rel--5.10--patch-83 - [e-mail]--gnu-2004/gnus--rel--5.10--patch-84 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-3 - [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-4 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-5 Merge from gnus--rel--5.10 * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-6 - [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-11 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-12 Remove "-face" suffix from lazy-highlight face name * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-13 - [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-16 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-17 Merge from gnus--rel--5.10 * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-18 - [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-21 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-22 <no summary provided> * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-23 - [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-39 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-40 Fix regressions from latest reftex update * [e-mail]--gnu-2005/gnus--rel--5.10--base-0 tag of [e-mail]--gnu-2004/gnus--rel--5.10--patch-82 * [e-mail]--gnu-2005/gnus--rel--5.10--patch-1 Merge from emacs--cvs-trunk--0 * [e-mail]--gnu-2005/gnus--rel--5.10--patch-2 Merge from [e-mail]--gnu-2004 * [e-mail]--gnu-2005/gnus--rel--5.10--patch-3 Merge from emacs--cvs-trunk--0

90071:f6b4d0ebf147

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.

@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

@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

@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

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.

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

  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

@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-@@

@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

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

command@footnote{The name of the command, @code{woman}, is an acronym
for ``w/o (without) man,'' since it doesn't use the @code{man}
program.}.  Unlike @kbd{M-x man}, it does not run any external
programs to format and display the man pages; instead it does the job
in Emacs Lisp, so it works on systems such as MS-Windows, where the
@code{man} program (and 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

@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

@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

@item hs-hide-comments-when-hiding-all
Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.

@item hs-isearch-open
Specifies what kind of hidden blocks to open in Isearch mode.
The value should be one of these four symbols.

@table @code
@item code
Open only code blocks.
@item comment

@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 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

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.

@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-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

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

90072:cb67264d6096

Find or move over top-level definitions (@pxref{Defuns}).
@item
Apply the usual indentation conventions of the language
(@pxref{Program Indent}).
@item
Balance parentheses (@pxref{Parentheses}).
@item
Insert, kill or align comments (@pxref{Comments}).
@item
Highlight program syntax (@pxref{Font Lock}).
@end itemize

  This chapter describes these features and many more.

@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,
ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
companion for font creation), Modula2, Objective-C, Octave, Pascal,
Perl, Pike, PostScript, Prolog, 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

@findex which-function-mode
@vindex which-func-modes
  To enable (or disable) Which Function mode, use the command @kbd{M-x
which-function-mode}.  This command is global; it applies to all
buffers, both existing ones and those yet to be created.  However, it
takes effect only in certain major modes, those listed in the value of
@code{which-func-modes}.  If the value is @code{t}, then Which Function
mode applies to all major modes that know how to support it---in other
words, all the major modes that support Imenu.

@node Program Indent
@section Indentation for Programs
@cindex indentation for programs

@findex indent-line-function
@findex indent-for-tab-command
  The basic indentation command is @key{TAB}, which gives the current line
the correct indentation as determined from the previous lines.  The
function that @key{TAB} runs depends on the major mode; it is
@code{lisp-indent-line}
in Lisp mode, @code{c-indent-command} in C mode, etc.  These functions
understand the syntax and conventions of different languages, but they all do
conceptually the same job: @key{TAB} in any programming-language major mode
inserts or deletes whitespace at the beginning of the current line,
independent of where point is in the line.  If point was inside the

altered or moved to a different level in the parenthesis structure,
you have several commands available.

@table @kbd
@item C-M-q
Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}).
@item C-M-\
Reindent all lines in the region (@code{indent-region}).
@item C-u @key{TAB}
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.

Shift all the lines in the region rigidly sideways, but do not alter
lines that start inside comments and strings.
@end table

@kindex C-M-q
@findex indent-pp-sexp
  You can reindent the contents of a single parenthetical grouping by
positioning point before the beginning of it and typing @kbd{C-M-q}
(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
bound to other suitable commands in other modes).  The indentation of
the line where the grouping starts is not changed; therefore this
changes only the relative indentation within the grouping, not its
overall indentation.  To correct that as well, type @key{TAB} first.

  Another way to specify the range to be reindented is with the
region.  The command @kbd{C-M-\} (@code{indent-region}) applies

  You can also perform this operation on the region, using the command
@kbd{M-x indent-code-rigidly}.  It rigidly shifts all the lines in the
region sideways, like @code{indent-rigidly} does (@pxref{Indentation
Commands}).  It doesn't alter the indentation of lines that start
inside a string, unless the region also starts inside that string.
The prefix arg specifies the number of columns to indent.

@node Lisp Indent
@subsection Customizing Lisp Indentation
@cindex customizing Lisp indentation

@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-@@

@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

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

command@footnote{The name of the command, @code{woman}, is an acronym
for ``w/o (without) man,'' since it doesn't use the @code{man}
program.}.  Unlike @kbd{M-x man}, it does not run any external
programs to format and display the man pages; instead it does the job
in Emacs Lisp, so it works on systems such as MS-Windows, where the
@code{man} program (and other programs it uses) are not generally
available.

  @kbd{M-x woman} prompts for a name of a manual page, and provides
completion based on the list of manual pages that are installed on
your machine; the list of available manual pages is computed

@findex eldoc-mode
  A more automatic but less powerful method is Eldoc mode.  This minor
mode constantly displays in the echo area the argument list for the
function being called at point.  (In other words, it finds the
function call that point is contained in, and displays the argument
list of that function.)  If point is over a documented variable, it
shows the variable's docstring.  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

@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

@item hs-hide-comments-when-hiding-all
Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.

@item hs-isearch-open
Specifies what kind of hidden blocks to open in Isearch mode.
The value should be one of these four symbols:

@table @code
@item code
Open only code blocks.
@item comment

@item C-c C-s
@findex c-show-syntactic-information
@kindex C-c C-s @r{(C mode)}
Display the syntactic information about the current source line
(@code{c-show-syntactic-information}).  This information directs how
the line is indented.

@item M-x cwarn-mode
@itemx M-x global-cwarn-mode
@findex cwarn-mode
@findex global-cwarn-mode

@vindex 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 right-justified 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}.  


@node ForIndent Conv
@subsubsection Syntactic Conventions

  Fortran mode assumes that you follow certain conventions that simplify

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-indent-comment}).

@item C-x ;
Applies to nonstandard @samp{!} comments only.

@item C-c ;
Turn all lines of the region into comments, or (with argument) turn them back
into real code (@code{fortran-comment-region}).
@end table

  @kbd{M-;} in Fortran mode is redefined as the command
@code{fortran-indent-comment}.  Like the usual @kbd{M-;} command, this
recognizes any kind of existing comment and aligns its text appropriately;
if there is no existing comment, a comment is inserted and aligned.  But
inserting and aligning comments are not the same in Fortran mode as in
other modes.

@item relative
Align the text as if it were a line of code, but with an additional
@code{fortran-comment-line-extra-indent} columns of indentation.

@item nil
Don't move text in full-line comments automatically.
@end table

@vindex fortran-comment-indent-char
  In addition, you can specify the character to be used to indent within
full-line comments by setting the variable

@code{fortran-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} toggles Fortran Auto Fill mode,
which is a variant of normal Auto Fill mode (@pxref{Filling}) designed
for Fortran programs.  Fortran Auto Fill mode is a buffer-local minor
mode (@pxref{Minor Modes}).  When Fortran Auto Fill mode is in effect,
the word @samp{Fill} appears in the mode line inside the parentheses.

@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.

  To enable this mode 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

with; but the positions they indicate in the line are standard for
Fortran.

@vindex fortran-column-ruler-fixed
@vindex fortran-column-ruler-tabs
  The text used to display the column ruler depends on the value of the
variable @code{indent-tabs-mode}.  If @code{indent-tabs-mode} is
@code{nil}, then the value of the variable
@code{fortran-column-ruler-fixed} is used as the column ruler.
Otherwise, the value of the variable @code{fortran-column-ruler-tab} is
displayed.  By changing these variables, you can change the column ruler
display.

@kindex C-c C-w @r{(Fortran mode)}
@findex fortran-window-create-momentarily
  @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
splits the current window horizontally, making a window 72 columns