comparison man/programs.texi @ 61021:6fb8ff7dc693

Reformat and update copyright years. (Fortran): Update section.

61020:d3326c3d7c9d

@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

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

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
@findex f90-next-statement

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

@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

@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 non-@code{nil} 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
non-@code{nil} 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 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

@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
non-@code{nil}, 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-indent-comment}).

@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

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.

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

@table @kbd

@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

61021:6fb8ff7dc693

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
@c               2001, 2005  Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Programs, Building, Text, Top
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing

@node Fortran
@section Fortran Mode
@cindex Fortran mode
@cindex mode, Fortran

  Fortran mode provides special motion commands for Fortran statements
and subprograms, and indentation commands that understand Fortran
conventions of nesting, line numbers and continuation statements.
Fortran mode has support for Auto Fill mode that breaks long lines into
proper Fortran continuation lines.

  Special commands for comments are provided because Fortran comments
are unlike those of other languages.  Built-in abbrevs optionally save
typing when you insert Fortran keywords.

runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).

@cindex Fortran77 and Fortran90
@findex f90-mode
@findex fortran-mode
  Fortran mode is meant for editing Fortran77 ``fixed format'' (and also
``tab format'') source code.  For editing the modern Fortran90 or
Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}).
Emacs normally uses Fortran mode for files with extension @samp{.f},
@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and
@samp{.f95}.  GNU Fortran supports both kinds of format.

@menu
* Motion: Fortran Motion.	 Moving point by statements or subprograms.
* Indent: Fortran Indent.	 Indentation commands for Fortran.
* Comments: Fortran Comments.	 Inserting and aligning comments.
* Autofill: Fortran Autofill.	 Auto fill support for Fortran.
* Columns: Fortran Columns.	 Measuring columns for valid Fortran.
* Abbrev: Fortran Abbrev.	 Built-in abbrevs for Fortran keywords.
@end menu

@node Fortran Motion
@subsection Motion Commands

  In addition to the normal commands for moving by and operating on
``defuns'' (Fortran subprograms---functions and subroutines, as well as
modules for F90 mode), Fortran mode provides special commands to move by
statements.

@table @kbd
@kindex C-c C-n @r{(Fortran mode)}
@findex fortran-next-statement
@findex f90-next-statement

@subsection Fortran Indentation

  Special commands and features are needed for indenting Fortran code in
order to make sure various syntactic entities (line numbers, comment line
indicators and continuation line flags) appear in the columns that are
required for standard, fixed (or tab) format Fortran.

@menu
* Commands: ForIndent Commands.  Commands for indenting and filling Fortran.
* Contline: ForIndent Cont.      How continuation lines indent.
* Numbers:  ForIndent Num.       How line numbers auto-indent.

@node ForIndent Commands
@subsubsection Fortran Indentation and Filling Commands

@table @kbd
@item C-M-j
Break the current line at point and set up a continuation line
(@code{fortran-split-line}).
@item M-^
Join this line to the previous line (@code{fortran-join-line}).
@item C-M-q
Indent all the lines of the subprogram point is in

@node ForIndent Cont
@subsubsection Continuation Lines
@cindex Fortran continuation lines

@vindex fortran-continuation-string
  Most Fortran77 compilers allow two ways of writing continuation lines.
If the first non-space character on a line is in column 5, then that
line is a continuation of the previous line.  We call this @dfn{fixed
format}.  (In GNU Emacs we always count columns from 0; but note that
the Fortran standard counts from 1.)  The variable
@code{fortran-continuation-string} specifies what character to put in
column 5.  A line that starts with a tab character followed by any digit
except @samp{0} is also a continuation line.  We call this style of
continuation @dfn{tab format}.  (Fortran90 introduced ``free format'',
with another style of continuation lines).

@vindex indent-tabs-mode @r{(Fortran mode)}
@vindex fortran-analyze-depth
@vindex fortran-tab-mode-default
@vindex fortran-tab-mode-string
  Fortran mode can use either style of continuation line.  When you
enter Fortran mode, it tries to deduce the proper continuation style
automatically from the buffer contents.  It does this by scanning up to
@code{fortran-analyze-depth} (default 100) lines from the start of the
buffer.  The first line that begins with either a tab character or six
spaces determines the choice.  If the scan fails (for example, if the
buffer is new and therefore empty), the value of
@code{fortran-tab-mode-default} (@code{nil} for fixed format, and
non-@code{nil} for tab format) is used.  You can tell which style is
presently in effect by the presence or absence of the string specified
by @code{fortran-tab-mode-string} (default @samp{/t}) in the mode line.

@vindex fortran-continuation-string
  If the text on a line starts with the Fortran continuation marker
specified by @code{fortran-continuation-string} (conventionally
@samp{$}), or if it begins with any non-whitespace character in column
5, Fortran mode treats it as a continuation line.  When you indent a
continuation line with @key{TAB}, it converts the line to the current
continuation style.  When you split a Fortran statement with
@kbd{C-M-j}, the continuation marker on the newline is created according
to the continuation style.

  The setting of continuation style affects several other aspects of
editing in Fortran mode.  In fixed format mode, the minimum column
number for the body of a statement is 6.  Lines inside of Fortran
blocks that are indented to larger column numbers always use only the
space character for whitespace.  In tab format mode, the minimum
column number for the statement body is 8, and the whitespace before
column 8 must always consist of one tab character.

@node ForIndent Num
@subsubsection Line Numbers

  If a number is the first non-whitespace in the line, Fortran
indentation assumes it is a line number and moves it to columns 0
through 4.  (Columns always count from 0 in GNU Emacs.)

@vindex fortran-line-number-indent
  Line numbers of four digits or less are normally indented one space.
The variable @code{fortran-line-number-indent} controls this; it
specifies the maximum indentation a line number can have.  The default
value of the variable is 1.  Fortran mode tries to prevent line number
digits passing column 4, reducing the indentation below the specified
maximum if necessary.  If @code{fortran-line-number-indent} has the
value 5, line numbers are right-justified to end in column 4.

@vindex fortran-electric-line-number
  Simply inserting a line number is enough to indent it according to
these rules.  As each digit is inserted, the indentation is recomputed.
To turn off this feature, set the variable

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

@item fortran-structure-indent
Extra indentation within each level of @samp{structure}, @samp{union},
@samp{map}, or @samp{interface} statements (default 3).

@item fortran-continuation-indent
Extra indentation for bodies of continuation lines (default 5).

@item fortran-check-all-num-for-matching-do
In Fortran77, a numbered @samp{do} statement is ended by any statement
with a matching line number.  It is common (but not compulsory) to use a
@samp{continue} statement for this purpose.  If this variable has a
non-@code{nil} value, indenting any numbered statement must check for a
@samp{do} that ends there.  If you always end @samp{do} statements with
a @samp{continue} line (or if you use the more modern @samp{enddo}),
then you can speed up indentation by setting this variable to
@code{nil}.  The default is @code{nil}.

@item fortran-blink-matching-if
If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
statement moves the cursor momentarily to the matching @samp{if} (or
@samp{do}) statement to show where it is.  The default is @code{nil}.

@item fortran-minimum-statement-indent-fixed
Minimum indentation for Fortran statements when using fixed format
continuation line style.  Statement bodies are never indented less than
this much.  The default is 6.

@item fortran-minimum-statement-indent-tab
Minimum indentation for Fortran statements for tab format continuation line
style.  Statement bodies are never indented less than this much.  The
default is 8.
@end table

The variables controlling the indentation of comments are described in
a separate section (@pxref{Fortran Comments}).


@node Fortran Comments
@subsection Fortran Comments

  The usual Emacs comment commands assume that a comment can follow a
line of code.  In Fortran77, the standard comment syntax requires an
entire line to be just a comment.  Therefore, Fortran mode replaces the
standard Emacs comment commands and defines some new variables.

@vindex fortran-comment-line-start
  Fortran mode can also handle the Fortran90 comment syntax where comments
start with @samp{!} and can follow other text.  Because only some Fortran77
compilers accept this syntax, Fortran mode will not insert such comments
unless you have said in advance to do so.  To do this, set the variable
@code{fortran-comment-line-start} to @samp{"!"}.

@table @kbd
@item M-;
Align comment or insert new comment (@code{fortran-indent-comment}).

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

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

never be indented at all, no matter what the value of
@code{fortran-comment-indent-style}.  The variable
@code{fortran-directive-re} is a regular expression that specifies which
lines are directives.  Matching lines are never indented, and receive
distinctive font-locking.

  The normal Emacs comment command @kbd{C-x ;} has not been redefined.  If
you use @samp{!} comments, this command can be used with them.  Otherwise
it is useless in Fortran mode.

example of a command and a variable with the same name; these two uses
of the name never conflict because in Lisp and in Emacs it is always
clear from the context which one is meant.

@node Fortran Autofill
@subsection Auto Fill in Fortran Mode

  Fortran mode has specialized support for Auto Fill mode, which is a
minor mode that automatically splits statements as you insert them when
they become too wide.  Splitting a statement involves making
continuation lines using @code{fortran-continuation-string}
(@pxref{ForIndent Cont}).  This splitting happens when you type
@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran indentation
commands.  You activate Auto Fill in Fortran mode in the normal way
(@pxref{Auto Fill}).

@vindex fortran-break-before-delimiters
   Auto Fill breaks lines at spaces or delimiters when the lines get
longer than the desired width (the value of @code{fill-column}).  The
delimiters (besides whitespace) that Auto Fill 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 Auto Fill in all Fortran buffers, add
@code{turn-on-auto-fill} to @code{fortran-mode-hook}.  @xref{Hooks}.

@node Fortran Columns
@subsection Checking Columns in Fortran

@table @kbd

@kindex C-c C-w @r{(Fortran mode)}
@findex fortran-window-create-momentarily
  @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
splits the current window horizontally, making a window 72 columns
wide, so you can see any lines that are too long.  Type a space to
restore the normal width.

@kindex C-u C-c C-w @r{(Fortran mode)}
@findex fortran-window-create
  You can also split the window horizontally and continue editing with