changeset 84241:f144b998e85f

Move here from ../../man

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/emacs/fortran-xtra.texi	Thu Sep 06 04:46:02 2007 +0000
@@ -0,0 +1,548 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@c
+@c This file is included either in emacs-xtra.texi (when producing the
+@c printed version) or in the main Emacs manual (for the on-line version).
+@node Fortran
+@section Fortran Mode
+@cindex Fortran mode
+@cindex mode, Fortran
+
+  Fortran mode provides special motion commands for Fortran statements
+and subprograms, and indentation commands that understand Fortran
+conventions of nesting, line numbers and continuation statements.
+Fortran mode has support for Auto Fill mode that breaks long lines into
+proper Fortran continuation lines.
+
+  Special commands for comments are provided because Fortran comments
+are unlike those of other languages.  Built-in abbrevs optionally save
+typing when you insert Fortran keywords.
+
+  Use @kbd{M-x fortran-mode} to switch to this major mode.  This
+command runs the hook @code{fortran-mode-hook}.
+@iftex
+@xref{Hooks,,, emacs, the Emacs Manual}.
+@end iftex
+@ifnottex
+@xref{Hooks}.
+@end ifnottex
+
+@cindex Fortran77 and Fortran90
+@findex f90-mode
+@findex fortran-mode
+  Fortran mode is meant for editing Fortran77 ``fixed format'' (and also
+``tab format'') source code.  For editing the modern Fortran90 or
+Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}).
+Emacs normally uses Fortran mode for files with extension @samp{.f},
+@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and
+@samp{.f95}.  GNU Fortran supports both kinds of format.
+
+@menu
+* Motion: Fortran Motion.	 Moving point by statements or subprograms.
+* Indent: Fortran Indent.	 Indentation commands for Fortran.
+* Comments: Fortran Comments.	 Inserting and aligning comments.
+* Autofill: Fortran Autofill.	 Auto fill support for Fortran.
+* Columns: Fortran Columns.	 Measuring columns for valid Fortran.
+* Abbrev: Fortran Abbrev.	 Built-in abbrevs for Fortran keywords.
+@end menu
+
+@node Fortran Motion
+@subsection Motion Commands
+
+  In addition to the normal commands for moving by and operating on
+``defuns'' (Fortran subprograms---functions and subroutines, as well as
+modules for F90 mode), Fortran mode provides special commands to move by
+statements and other program units.
+
+@table @kbd
+@kindex C-c C-n @r{(Fortran mode)}
+@findex fortran-next-statement
+@findex f90-next-statement
+@item C-c C-n
+Move to the beginning of the next statement
+(@code{fortran-next-statement}/@code{f90-next-statement}).
+
+@kindex C-c C-p @r{(Fortran mode)}
+@findex fortran-previous-statement
+@findex f90-previous-statement
+@item C-c C-p
+Move to the beginning of the previous statement
+(@code{fortran-previous-statement}/@code{f90-previous-statement}).
+If there is no previous statement (i.e. if called from the first
+statement in the buffer), move to the start of the buffer.
+
+@kindex C-c C-e @r{(F90 mode)}
+@findex f90-next-block
+@item C-c C-e
+Move point forward to the start of the next code block
+(@code{f90-next-block}).  A code block is a subroutine,
+@code{if}--@code{endif} statement, and so forth.  This command exists
+for F90 mode only, not Fortran mode.  With a numeric argument, this
+moves forward that many blocks.
+
+@kindex C-c C-a @r{(F90 mode)}
+@findex f90-previous-block
+@item C-c C-a
+Move point backward to the previous code block
+(@code{f90-previous-block}).  This is like @code{f90-next-block}, but
+moves backwards.
+
+@kindex C-M-n @r{(Fortran mode)}
+@findex fortran-end-of-block
+@findex f90-end-of-block
+@item C-M-n
+Move to the end of the current code block
+(@code{fortran-end-of-block}/@code{f90-end-of-block}).  With a numeric
+argument, move forward that number of blocks.  The mark is set before
+moving point.  The F90 mode version of this command checks for
+consistency of block types and labels (if present), but it does not
+check the outermost block since that may be incomplete.
+
+@kindex C-M-p @r{(Fortran mode)}
+@findex fortran-beginning-of-block
+@findex f90-beginning-of-block
+@item C-M-p
+Move to the start of the current code block
+(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This
+is like @code{fortran-end-of-block}, but moves backwards.
+@end table
+
+@node Fortran Indent
+@subsection Fortran Indentation
+
+  Special commands and features are needed for indenting Fortran code in
+order to make sure various syntactic entities (line numbers, comment line
+indicators and continuation line flags) appear in the columns that are
+required for standard, fixed (or tab) format Fortran.
+
+@menu
+* Commands: ForIndent Commands.  Commands for indenting and filling Fortran.
+* Contline: ForIndent Cont.      How continuation lines indent.
+* Numbers:  ForIndent Num.       How line numbers auto-indent.
+* Conv:     ForIndent Conv.      Conventions you must obey to avoid trouble.
+* Vars:     ForIndent Vars.      Variables controlling Fortran indent style.
+@end menu
+
+@node ForIndent Commands
+@subsubsection Fortran Indentation and Filling Commands
+
+@table @kbd
+@item C-M-j
+Break the current line at point and set up a continuation line
+(@code{fortran-split-line}).
+@item M-^
+Join this line to the previous line (@code{fortran-join-line}).
+@item C-M-q
+Indent all the lines of the subprogram point is in
+(@code{fortran-indent-subprogram}).
+@item M-q
+Fill a comment block or statement.
+@end table
+
+@kindex C-M-q @r{(Fortran mode)}
+@findex fortran-indent-subprogram
+  The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
+to reindent all the lines of the Fortran subprogram (function or
+subroutine) containing point.
+
+@kindex C-M-j @r{(Fortran mode)}
+@findex fortran-split-line
+  The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
+a line in the appropriate fashion for Fortran.  In a non-comment line,
+the second half becomes a continuation line and is indented
+accordingly.  In a comment line, both halves become separate comment
+lines.
+
+@kindex M-^ @r{(Fortran mode)}
+@kindex C-c C-d @r{(Fortran mode)}
+@findex fortran-join-line
+  @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
+which joins a continuation line back to the previous line, roughly as
+the inverse of @code{fortran-split-line}.  The point must be on a
+continuation line when this command is invoked.
+
+@kindex M-q @r{(Fortran mode)}
+@kbd{M-q} in Fortran mode fills the comment block or statement that
+point is in.  This removes any excess statement continuations.
+
+@node ForIndent Cont
+@subsubsection Continuation Lines
+@cindex Fortran continuation lines
+
+@vindex fortran-continuation-string
+  Most Fortran77 compilers allow two ways of writing continuation lines.
+If the first non-space character on a line is in column 5, then that
+line is a continuation of the previous line.  We call this @dfn{fixed
+format}.  (In GNU Emacs we always count columns from 0; but note that
+the Fortran standard counts from 1.)  The variable
+@code{fortran-continuation-string} specifies what character to put in
+column 5.  A line that starts with a tab character followed by any digit
+except @samp{0} is also a continuation line.  We call this style of
+continuation @dfn{tab format}.  (Fortran90 introduced ``free format,''
+with another style of continuation lines).
+
+@vindex indent-tabs-mode @r{(Fortran mode)}
+@vindex fortran-analyze-depth
+@vindex fortran-tab-mode-default
+  Fortran mode can use either style of continuation line.  When you
+enter Fortran mode, it tries to deduce the proper continuation style
+automatically from the buffer contents.  It does this by scanning up to
+@code{fortran-analyze-depth} (default 100) lines from the start of the
+buffer.  The first line that begins with either a tab character or six
+spaces determines the choice.  If the scan fails (for example, if the
+buffer is new and therefore empty), the value of
+@code{fortran-tab-mode-default} (@code{nil} for fixed format, and
+non-@code{nil} for tab format) is used.  @samp{/t} in the mode line
+indicates tab format is selected.  Fortran mode sets the value of
+@code{indent-tabs-mode} accordingly.
+
+  If the text on a line starts with the Fortran continuation marker
+@samp{$}, or if it begins with any non-whitespace character in column
+5, Fortran mode treats it as a continuation line.  When you indent a
+continuation line with @key{TAB}, it converts the line to the current
+continuation style.  When you split a Fortran statement with
+@kbd{C-M-j}, the continuation marker on the newline is created according
+to the continuation style.
+
+  The setting of continuation style affects several other aspects of
+editing in Fortran mode.  In fixed format mode, the minimum column
+number for the body of a statement is 6.  Lines inside of Fortran
+blocks that are indented to larger column numbers always use only the
+space character for whitespace.  In tab format mode, the minimum
+column number for the statement body is 8, and the whitespace before
+column 8 must always consist of one tab character.
+
+@node ForIndent Num
+@subsubsection Line Numbers
+
+  If a number is the first non-whitespace in the line, Fortran
+indentation assumes it is a line number and moves it to columns 0
+through 4.  (Columns always count from 0 in GNU Emacs.)
+
+@vindex fortran-line-number-indent
+  Line numbers of four digits or less are normally indented one space.
+The variable @code{fortran-line-number-indent} controls this; it
+specifies the maximum indentation a line number can have.  The default
+value of the variable is 1.  Fortran mode tries to prevent line number
+digits passing column 4, reducing the indentation below the specified
+maximum if necessary.  If @code{fortran-line-number-indent} has the
+value 5, line numbers are right-justified to end in column 4.
+
+@vindex fortran-electric-line-number
+  Simply inserting a line number is enough to indent it according to
+these rules.  As each digit is inserted, the indentation is recomputed.
+To turn off this feature, set the variable
+@code{fortran-electric-line-number} to @code{nil}.
+
+
+@node ForIndent Conv
+@subsubsection Syntactic Conventions
+
+  Fortran mode assumes that you follow certain conventions that simplify
+the task of understanding a Fortran program well enough to indent it
+properly:
+
+@itemize @bullet
+@item
+Two nested @samp{do} loops never share a @samp{continue} statement.
+
+@item
+Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
+and others are written without embedded whitespace or line breaks.
+
+Fortran compilers generally ignore whitespace outside of string
+constants, but Fortran mode does not recognize these keywords if they
+are not contiguous.  Constructs such as @samp{else if} or @samp{end do}
+are acceptable, but the second word should be on the same line as the
+first and not on a continuation line.
+@end itemize
+
+@noindent
+If you fail to follow these conventions, the indentation commands may
+indent some lines unaesthetically.  However, a correct Fortran program
+retains its meaning when reindented even if the conventions are not
+followed.
+
+@node ForIndent Vars
+@subsubsection Variables for Fortran Indentation
+
+@vindex fortran-do-indent
+@vindex fortran-if-indent
+@vindex fortran-structure-indent
+@vindex fortran-continuation-indent
+@vindex fortran-check-all-num@dots{}
+@vindex fortran-minimum-statement-indent@dots{}
+  Several additional variables control how Fortran indentation works:
+
+@table @code
+@item fortran-do-indent
+Extra indentation within each level of @samp{do} statement (default 3).
+
+@item fortran-if-indent
+Extra indentation within each level of @samp{if}, @samp{select case}, or
+@samp{where} statements (default 3).
+
+@item fortran-structure-indent
+Extra indentation within each level of @samp{structure}, @samp{union},
+@samp{map}, or @samp{interface} statements (default 3).
+
+@item fortran-continuation-indent
+Extra indentation for bodies of continuation lines (default 5).
+
+@item fortran-check-all-num-for-matching-do
+In Fortran77, a numbered @samp{do} statement is ended by any statement
+with a matching line number.  It is common (but not compulsory) to use a
+@samp{continue} statement for this purpose.  If this variable has a
+non-@code{nil} value, indenting any numbered statement must check for a
+@samp{do} that ends there.  If you always end @samp{do} statements with
+a @samp{continue} line (or if you use the more modern @samp{enddo}),
+then you can speed up indentation by setting this variable to
+@code{nil}.  The default is @code{nil}.
+
+@item fortran-blink-matching-if
+If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
+statement moves the cursor momentarily to the matching @samp{if} (or
+@samp{do}) statement to show where it is.  The default is @code{nil}.
+
+@item fortran-minimum-statement-indent-fixed
+Minimum indentation for Fortran statements when using fixed format
+continuation line style.  Statement bodies are never indented less than
+this much.  The default is 6.
+
+@item fortran-minimum-statement-indent-tab
+Minimum indentation for Fortran statements for tab format continuation line
+style.  Statement bodies are never indented less than this much.  The
+default is 8.
+@end table
+
+The variables controlling the indentation of comments are described in
+the following section.
+
+@node Fortran Comments
+@subsection Fortran Comments
+
+  The usual Emacs comment commands assume that a comment can follow a
+line of code.  In Fortran77, the standard comment syntax requires an
+entire line to be just a comment.  Therefore, Fortran mode replaces the
+standard Emacs comment commands and defines some new variables.
+
+@vindex fortran-comment-line-start
+  Fortran mode can also handle the Fortran90 comment syntax where comments
+start with @samp{!} and can follow other text.  Because only some Fortran77
+compilers accept this syntax, Fortran mode will not insert such comments
+unless you have said in advance to do so.  To do this, set the variable
+@code{fortran-comment-line-start} to @samp{"!"}.
+
+@table @kbd
+@item M-;
+Align comment or insert new comment (@code{fortran-indent-comment}).
+
+@item C-x ;
+Applies to nonstandard @samp{!} comments only.
+
+@item C-c ;
+Turn all lines of the region into comments, or (with argument) turn them back
+into real code (@code{fortran-comment-region}).
+@end table
+
+@findex fortran-indent-comment
+  @kbd{M-;} in Fortran mode is redefined as the command
+@code{fortran-indent-comment}.  Like the usual @kbd{M-;} command, this
+recognizes any kind of existing comment and aligns its text appropriately;
+if there is no existing comment, a comment is inserted and aligned.  But
+inserting and aligning comments are not the same in Fortran mode as in
+other modes.
+
+  When a new comment must be inserted, if the current line is blank, a
+full-line comment is inserted.  On a non-blank line, a nonstandard @samp{!}
+comment is inserted if you have said you want to use them.  Otherwise a
+full-line comment is inserted on a new line before the current line.
+
+  Nonstandard @samp{!} comments are aligned like comments in other
+languages, but full-line comments are different.  In a standard full-line
+comment, the comment delimiter itself must always appear in column zero.
+What can be aligned is the text within the comment.  You can choose from
+three styles of alignment by setting the variable
+@code{fortran-comment-indent-style} to one of these values:
+
+@vindex fortran-comment-indent-style
+@vindex fortran-comment-line-extra-indent
+@table @code
+@item fixed
+Align the text at a fixed column, which is the sum of
+@code{fortran-comment-line-extra-indent} and the minimum statement
+indentation.  This is the default.
+
+The minimum statement indentation is
+@code{fortran-minimum-statement-indent-fixed} for fixed format
+continuation line style and @code{fortran-minimum-statement-indent-tab}
+for tab format style.
+
+@item relative
+Align the text as if it were a line of code, but with an additional
+@code{fortran-comment-line-extra-indent} columns of indentation.
+
+@item nil
+Don't move text in full-line comments automatically.
+@end table
+
+@vindex fortran-comment-indent-char
+  In addition, you can specify the character to be used to indent within
+full-line comments by setting the variable
+@code{fortran-comment-indent-char} to the single-character string you want
+to use.
+
+@vindex fortran-directive-re
+  Compiler directive lines, or preprocessor lines, have much the same
+appearance as comment lines.  It is important, though, that such lines
+never be indented at all, no matter what the value of
+@code{fortran-comment-indent-style}.  The variable
+@code{fortran-directive-re} is a regular expression that specifies which
+lines are directives.  Matching lines are never indented, and receive
+distinctive font-locking.
+
+  The normal Emacs comment command @kbd{C-x ;} has not been redefined.  If
+you use @samp{!} comments, this command can be used with them.  Otherwise
+it is useless in Fortran mode.
+
+@kindex C-c ; @r{(Fortran mode)}
+@findex fortran-comment-region
+@vindex fortran-comment-region
+  The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
+lines of the region into comments by inserting the string @samp{C$$$} at
+the front of each one.  With a numeric argument, it turns the region
+back into live code by deleting @samp{C$$$} from the front of each line
+in it.  The string used for these comments can be controlled by setting
+the variable @code{fortran-comment-region}.  Note that here we have an
+example of a command and a variable with the same name; these two uses
+of the name never conflict because in Lisp and in Emacs it is always
+clear from the context which one is meant.
+
+@node Fortran Autofill
+@subsection Auto Fill in Fortran Mode
+
+  Fortran mode has specialized support for Auto Fill mode, which is a
+minor mode that automatically splits statements as you insert them
+when they become too wide.  Splitting a statement involves making
+continuation lines using @code{fortran-continuation-string}
+(@pxref{ForIndent Cont}).  This splitting happens when you type
+@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran
+indentation commands.  You activate Auto Fill in Fortran mode in the
+normal way.
+@iftex
+@xref{Auto Fill,,, emacs, the Emacs Manual}.
+@end iftex
+@ifnottex
+@xref{Auto Fill}.
+@end ifnottex
+
+@vindex fortran-break-before-delimiters
+   Auto Fill breaks lines at spaces or delimiters when the lines get
+longer than the desired width (the value of @code{fill-column}).  The
+delimiters (besides whitespace) that Auto Fill can break at are
+@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>},
+and @samp{,}.  The line break comes after the delimiter if the
+variable @code{fortran-break-before-delimiters} is @code{nil}.
+Otherwise (and by default), the break comes before the delimiter.
+
+  To enable Auto Fill in all Fortran buffers, add
+@code{turn-on-auto-fill} to @code{fortran-mode-hook}.
+@iftex
+@xref{Hooks,,, emacs, the Emacs Manual}.
+@end iftex
+@ifnottex
+@xref{Hooks}.
+@end ifnottex
+
+@node Fortran Columns
+@subsection Checking Columns in Fortran
+
+@table @kbd
+@item C-c C-r
+Display a ``column ruler'' momentarily above the current line
+(@code{fortran-column-ruler}).
+@item C-c C-w
+Split the current window horizontally temporarily so that it is 72
+columns wide (@code{fortran-window-create-momentarily}).  This may
+help you avoid making lines longer than the 72-character limit that
+some Fortran compilers impose.
+@item C-u C-c C-w
+Split the current window horizontally so that it is 72 columns wide
+(@code{fortran-window-create}).  You can then continue editing.
+@item M-x fortran-strip-sequence-nos
+Delete all text in column 72 and beyond.
+@end table
+
+@kindex C-c C-r @r{(Fortran mode)}
+@findex fortran-column-ruler
+  The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
+ruler momentarily above the current line.  The comment ruler is two lines
+of text that show you the locations of columns with special significance in
+Fortran programs.  Square brackets show the limits of the columns for line
+numbers, and curly brackets show the limits of the columns for the
+statement body.  Column numbers appear above them.
+
+  Note that the column numbers count from zero, as always in GNU Emacs.
+As a result, the numbers may be one less than those you are familiar
+with; but the positions they indicate in the line are standard for
+Fortran.
+
+@vindex fortran-column-ruler-fixed
+@vindex fortran-column-ruler-tabs
+  The text used to display the column ruler depends on the value of the
+variable @code{indent-tabs-mode}.  If @code{indent-tabs-mode} is
+@code{nil}, then the value of the variable
+@code{fortran-column-ruler-fixed} is used as the column ruler.
+Otherwise, the value of the variable @code{fortran-column-ruler-tab} is
+displayed.  By changing these variables, you can change the column ruler
+display.
+
+@kindex C-c C-w @r{(Fortran mode)}
+@findex fortran-window-create-momentarily
+  @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
+splits the current window horizontally, making a window 72 columns
+wide, so you can see any lines that are too long.  Type a space to
+restore the normal width.
+
+@kindex C-u C-c C-w @r{(Fortran mode)}
+@findex fortran-window-create
+  You can also split the window horizontally and continue editing with
+the split in place.  To do this, use @kbd{C-u C-c C-w} (@code{M-x
+fortran-window-create}).  By editing in this window you can
+immediately see when you make a line too wide to be correct Fortran.
+
+@findex fortran-strip-sequence-nos
+  The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in
+column 72 and beyond, on all lines in the current buffer.  This is the
+easiest way to get rid of old sequence numbers.
+
+@node Fortran Abbrev
+@subsection Fortran Keyword Abbrevs
+
+  Fortran mode provides many built-in abbrevs for common keywords and
+declarations.  These are the same sort of abbrev that you can define
+yourself.  To use them, you must turn on Abbrev mode.
+@iftex
+@xref{Abbrevs,,, emacs, the Emacs Manual}.
+@end iftex
+@ifnottex
+@xref{Abbrevs}.
+@end ifnottex
+
+  The built-in abbrevs are unusual in one way: they all start with a
+semicolon.  You cannot normally use semicolon in an abbrev, but Fortran
+mode makes this possible by changing the syntax of semicolon to ``word
+constituent.''
+
+  For example, one built-in Fortran abbrev is @samp{;c} for
+@samp{continue}.  If you insert @samp{;c} and then insert a punctuation
+character such as a space or a newline, the @samp{;c} expands automatically
+to @samp{continue}, provided Abbrev mode is enabled.@refill
+
+  Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
+Fortran abbrevs and what they stand for.
+
+@ignore
+   arch-tag: 23ed7c36-1517-4646-9235-2d5ade5f06f6
+@end ignore