comparison man/fortran-xtra.texi @ 70440:5e1c038e4afa

New file, a portion of emacs-xtra.texi.
author Eli Zaretskii <eliz@gnu.org>
date Sat, 06 May 2006 12:45:46 +0000
parents
children bdd0ac985d67
comparison
equal deleted inserted replaced
70439:48fec2b642c9 70440:5e1c038e4afa
1 @c This file is included either in emacs-xtra.texi (when producing the
2 @c printed version) or in the main Emacs manual (for the on-line version).
3 @node Fortran
4 @section Fortran Mode
5 @cindex Fortran mode
6 @cindex mode, Fortran
7
8 Fortran mode provides special motion commands for Fortran statements
9 and subprograms, and indentation commands that understand Fortran
10 conventions of nesting, line numbers and continuation statements.
11 Fortran mode has support for Auto Fill mode that breaks long lines into
12 proper Fortran continuation lines.
13
14 Special commands for comments are provided because Fortran comments
15 are unlike those of other languages. Built-in abbrevs optionally save
16 typing when you insert Fortran keywords.
17
18 Use @kbd{M-x fortran-mode} to switch to this major mode. This
19 command runs the hook @code{fortran-mode-hook}. @xref{Hooks,,, emacs,
20 the Emacs Manual}.
21
22 @cindex Fortran77 and Fortran90
23 @findex f90-mode
24 @findex fortran-mode
25 Fortran mode is meant for editing Fortran77 ``fixed format'' (and also
26 ``tab format'') source code. For editing the modern Fortran90 or
27 Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}).
28 Emacs normally uses Fortran mode for files with extension @samp{.f},
29 @samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and
30 @samp{.f95}. GNU Fortran supports both kinds of format.
31
32 @menu
33 * Motion: Fortran Motion. Moving point by statements or subprograms.
34 * Indent: Fortran Indent. Indentation commands for Fortran.
35 * Comments: Fortran Comments. Inserting and aligning comments.
36 * Autofill: Fortran Autofill. Auto fill support for Fortran.
37 * Columns: Fortran Columns. Measuring columns for valid Fortran.
38 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
39 @end menu
40
41 @node Fortran Motion
42 @subsection Motion Commands
43
44 In addition to the normal commands for moving by and operating on
45 ``defuns'' (Fortran subprograms---functions and subroutines, as well as
46 modules for F90 mode), Fortran mode provides special commands to move by
47 statements and other program units.
48
49 @table @kbd
50 @kindex C-c C-n @r{(Fortran mode)}
51 @findex fortran-next-statement
52 @findex f90-next-statement
53 @item C-c C-n
54 Move to the beginning of the next statement
55 (@code{fortran-next-statement}/@code{f90-next-statement}).
56
57 @kindex C-c C-p @r{(Fortran mode)}
58 @findex fortran-previous-statement
59 @findex f90-previous-statement
60 @item C-c C-p
61 Move to the beginning of the previous statement
62 (@code{fortran-previous-statement}/@code{f90-previous-statement}).
63 If there is no previous statement (i.e. if called from the first
64 statement in the buffer), move to the start of the buffer.
65
66 @kindex C-c C-e @r{(F90 mode)}
67 @findex f90-next-block
68 @item C-c C-e
69 Move point forward to the start of the next code block
70 (@code{f90-next-block}). A code block is a subroutine,
71 @code{if}--@code{endif} statement, and so forth. This command exists
72 for F90 mode only, not Fortran mode. With a numeric argument, this
73 moves forward that many blocks.
74
75 @kindex C-c C-a @r{(F90 mode)}
76 @findex f90-previous-block
77 @item C-c C-a
78 Move point backward to the previous code block
79 (@code{f90-previous-block}). This is like @code{f90-next-block}, but
80 moves backwards.
81
82 @kindex C-M-n @r{(Fortran mode)}
83 @findex fortran-end-of-block
84 @findex f90-end-of-block
85 @item C-M-n
86 Move to the end of the current code block
87 (@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric
88 agument, move forward that number of blocks. The mark is set before
89 moving point. The F90 mode version of this command checks for
90 consistency of block types and labels (if present), but it does not
91 check the outermost block since that may be incomplete.
92
93 @kindex C-M-p @r{(Fortran mode)}
94 @findex fortran-beginning-of-block
95 @findex f90-beginning-of-block
96 @item C-M-p
97 Move to the start of the current code block
98 (@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This
99 is like @code{fortran-end-of-block}, but moves backwards.
100 @end table
101
102 @node Fortran Indent
103 @subsection Fortran Indentation
104
105 Special commands and features are needed for indenting Fortran code in
106 order to make sure various syntactic entities (line numbers, comment line
107 indicators and continuation line flags) appear in the columns that are
108 required for standard, fixed (or tab) format Fortran.
109
110 @menu
111 * Commands: ForIndent Commands. Commands for indenting and filling Fortran.
112 * Contline: ForIndent Cont. How continuation lines indent.
113 * Numbers: ForIndent Num. How line numbers auto-indent.
114 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
115 * Vars: ForIndent Vars. Variables controlling Fortran indent style.
116 @end menu
117
118 @node ForIndent Commands
119 @subsubsection Fortran Indentation and Filling Commands
120
121 @table @kbd
122 @item C-M-j
123 Break the current line at point and set up a continuation line
124 (@code{fortran-split-line}).
125 @item M-^
126 Join this line to the previous line (@code{fortran-join-line}).
127 @item C-M-q
128 Indent all the lines of the subprogram point is in
129 (@code{fortran-indent-subprogram}).
130 @item M-q
131 Fill a comment block or statement.
132 @end table
133
134 @kindex C-M-q @r{(Fortran mode)}
135 @findex fortran-indent-subprogram
136 The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
137 to reindent all the lines of the Fortran subprogram (function or
138 subroutine) containing point.
139
140 @kindex C-M-j @r{(Fortran mode)}
141 @findex fortran-split-line
142 The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
143 a line in the appropriate fashion for Fortran. In a non-comment line,
144 the second half becomes a continuation line and is indented
145 accordingly. In a comment line, both halves become separate comment
146 lines.
147
148 @kindex M-^ @r{(Fortran mode)}
149 @kindex C-c C-d @r{(Fortran mode)}
150 @findex fortran-join-line
151 @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
152 which joins a continuation line back to the previous line, roughly as
153 the inverse of @code{fortran-split-line}. The point must be on a
154 continuation line when this command is invoked.
155
156 @kindex M-q @r{(Fortran mode)}
157 @kbd{M-q} in Fortran mode fills the comment block or statement that
158 point is in. This removes any excess statement continuations.
159
160 @node ForIndent Cont
161 @subsubsection Continuation Lines
162 @cindex Fortran continuation lines
163
164 @vindex fortran-continuation-string
165 Most Fortran77 compilers allow two ways of writing continuation lines.
166 If the first non-space character on a line is in column 5, then that
167 line is a continuation of the previous line. We call this @dfn{fixed
168 format}. (In GNU Emacs we always count columns from 0; but note that
169 the Fortran standard counts from 1.) The variable
170 @code{fortran-continuation-string} specifies what character to put in
171 column 5. A line that starts with a tab character followed by any digit
172 except @samp{0} is also a continuation line. We call this style of
173 continuation @dfn{tab format}. (Fortran90 introduced ``free format'',
174 with another style of continuation lines).
175
176 @vindex indent-tabs-mode @r{(Fortran mode)}
177 @vindex fortran-analyze-depth
178 @vindex fortran-tab-mode-default
179 Fortran mode can use either style of continuation line. When you
180 enter Fortran mode, it tries to deduce the proper continuation style
181 automatically from the buffer contents. It does this by scanning up to
182 @code{fortran-analyze-depth} (default 100) lines from the start of the
183 buffer. The first line that begins with either a tab character or six
184 spaces determines the choice. If the scan fails (for example, if the
185 buffer is new and therefore empty), the value of
186 @code{fortran-tab-mode-default} (@code{nil} for fixed format, and
187 non-@code{nil} for tab format) is used. @samp{/t} in the mode line
188 indicates tab format is selected. Fortran mode sets the value of
189 @code{indent-tabs-mode} accordingly.
190
191 If the text on a line starts with the Fortran continuation marker
192 @samp{$}, or if it begins with any non-whitespace character in column
193 5, Fortran mode treats it as a continuation line. When you indent a
194 continuation line with @key{TAB}, it converts the line to the current
195 continuation style. When you split a Fortran statement with
196 @kbd{C-M-j}, the continuation marker on the newline is created according
197 to the continuation style.
198
199 The setting of continuation style affects several other aspects of
200 editing in Fortran mode. In fixed format mode, the minimum column
201 number for the body of a statement is 6. Lines inside of Fortran
202 blocks that are indented to larger column numbers always use only the
203 space character for whitespace. In tab format mode, the minimum
204 column number for the statement body is 8, and the whitespace before
205 column 8 must always consist of one tab character.
206
207 @node ForIndent Num
208 @subsubsection Line Numbers
209
210 If a number is the first non-whitespace in the line, Fortran
211 indentation assumes it is a line number and moves it to columns 0
212 through 4. (Columns always count from 0 in GNU Emacs.)
213
214 @vindex fortran-line-number-indent
215 Line numbers of four digits or less are normally indented one space.
216 The variable @code{fortran-line-number-indent} controls this; it
217 specifies the maximum indentation a line number can have. The default
218 value of the variable is 1. Fortran mode tries to prevent line number
219 digits passing column 4, reducing the indentation below the specified
220 maximum if necessary. If @code{fortran-line-number-indent} has the
221 value 5, line numbers are right-justified to end in column 4.
222
223 @vindex fortran-electric-line-number
224 Simply inserting a line number is enough to indent it according to
225 these rules. As each digit is inserted, the indentation is recomputed.
226 To turn off this feature, set the variable
227 @code{fortran-electric-line-number} to @code{nil}.
228
229
230 @node ForIndent Conv
231 @subsubsection Syntactic Conventions
232
233 Fortran mode assumes that you follow certain conventions that simplify
234 the task of understanding a Fortran program well enough to indent it
235 properly:
236
237 @itemize @bullet
238 @item
239 Two nested @samp{do} loops never share a @samp{continue} statement.
240
241 @item
242 Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
243 and others are written without embedded whitespace or line breaks.
244
245 Fortran compilers generally ignore whitespace outside of string
246 constants, but Fortran mode does not recognize these keywords if they
247 are not contiguous. Constructs such as @samp{else if} or @samp{end do}
248 are acceptable, but the second word should be on the same line as the
249 first and not on a continuation line.
250 @end itemize
251
252 @noindent
253 If you fail to follow these conventions, the indentation commands may
254 indent some lines unaesthetically. However, a correct Fortran program
255 retains its meaning when reindented even if the conventions are not
256 followed.
257
258 @node ForIndent Vars
259 @subsubsection Variables for Fortran Indentation
260
261 @vindex fortran-do-indent
262 @vindex fortran-if-indent
263 @vindex fortran-structure-indent
264 @vindex fortran-continuation-indent
265 @vindex fortran-check-all-num@dots{}
266 @vindex fortran-minimum-statement-indent@dots{}
267 Several additional variables control how Fortran indentation works:
268
269 @table @code
270 @item fortran-do-indent
271 Extra indentation within each level of @samp{do} statement (default 3).
272
273 @item fortran-if-indent
274 Extra indentation within each level of @samp{if}, @samp{select case}, or
275 @samp{where} statements (default 3).
276
277 @item fortran-structure-indent
278 Extra indentation within each level of @samp{structure}, @samp{union},
279 @samp{map}, or @samp{interface} statements (default 3).
280
281 @item fortran-continuation-indent
282 Extra indentation for bodies of continuation lines (default 5).
283
284 @item fortran-check-all-num-for-matching-do
285 In Fortran77, a numbered @samp{do} statement is ended by any statement
286 with a matching line number. It is common (but not compulsory) to use a
287 @samp{continue} statement for this purpose. If this variable has a
288 non-@code{nil} value, indenting any numbered statement must check for a
289 @samp{do} that ends there. If you always end @samp{do} statements with
290 a @samp{continue} line (or if you use the more modern @samp{enddo}),
291 then you can speed up indentation by setting this variable to
292 @code{nil}. The default is @code{nil}.
293
294 @item fortran-blink-matching-if
295 If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
296 statement moves the cursor momentarily to the matching @samp{if} (or
297 @samp{do}) statement to show where it is. The default is @code{nil}.
298
299 @item fortran-minimum-statement-indent-fixed
300 Minimum indentation for Fortran statements when using fixed format
301 continuation line style. Statement bodies are never indented less than
302 this much. The default is 6.
303
304 @item fortran-minimum-statement-indent-tab
305 Minimum indentation for Fortran statements for tab format continuation line
306 style. Statement bodies are never indented less than this much. The
307 default is 8.
308 @end table
309
310 The variables controlling the indentation of comments are described in
311 the following section.
312
313 @node Fortran Comments
314 @subsection Fortran Comments
315
316 The usual Emacs comment commands assume that a comment can follow a
317 line of code. In Fortran77, the standard comment syntax requires an
318 entire line to be just a comment. Therefore, Fortran mode replaces the
319 standard Emacs comment commands and defines some new variables.
320
321 @vindex fortran-comment-line-start
322 Fortran mode can also handle the Fortran90 comment syntax where comments
323 start with @samp{!} and can follow other text. Because only some Fortran77
324 compilers accept this syntax, Fortran mode will not insert such comments
325 unless you have said in advance to do so. To do this, set the variable
326 @code{fortran-comment-line-start} to @samp{"!"}.
327
328 @table @kbd
329 @item M-;
330 Align comment or insert new comment (@code{fortran-indent-comment}).
331
332 @item C-x ;
333 Applies to nonstandard @samp{!} comments only.
334
335 @item C-c ;
336 Turn all lines of the region into comments, or (with argument) turn them back
337 into real code (@code{fortran-comment-region}).
338 @end table
339
340 @findex fortran-indent-comment
341 @kbd{M-;} in Fortran mode is redefined as the command
342 @code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this
343 recognizes any kind of existing comment and aligns its text appropriately;
344 if there is no existing comment, a comment is inserted and aligned. But
345 inserting and aligning comments are not the same in Fortran mode as in
346 other modes.
347
348 When a new comment must be inserted, if the current line is blank, a
349 full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
350 comment is inserted if you have said you want to use them. Otherwise a
351 full-line comment is inserted on a new line before the current line.
352
353 Nonstandard @samp{!} comments are aligned like comments in other
354 languages, but full-line comments are different. In a standard full-line
355 comment, the comment delimiter itself must always appear in column zero.
356 What can be aligned is the text within the comment. You can choose from
357 three styles of alignment by setting the variable
358 @code{fortran-comment-indent-style} to one of these values:
359
360 @vindex fortran-comment-indent-style
361 @vindex fortran-comment-line-extra-indent
362 @table @code
363 @item fixed
364 Align the text at a fixed column, which is the sum of
365 @code{fortran-comment-line-extra-indent} and the minimum statement
366 indentation. This is the default.
367
368 The minimum statement indentation is
369 @code{fortran-minimum-statement-indent-fixed} for fixed format
370 continuation line style and @code{fortran-minimum-statement-indent-tab}
371 for tab format style.
372
373 @item relative
374 Align the text as if it were a line of code, but with an additional
375 @code{fortran-comment-line-extra-indent} columns of indentation.
376
377 @item nil
378 Don't move text in full-line comments automatically.
379 @end table
380
381 @vindex fortran-comment-indent-char
382 In addition, you can specify the character to be used to indent within
383 full-line comments by setting the variable
384 @code{fortran-comment-indent-char} to the single-character string you want
385 to use.
386
387 @vindex fortran-directive-re
388 Compiler directive lines, or preprocessor lines, have much the same
389 appearance as comment lines. It is important, though, that such lines
390 never be indented at all, no matter what the value of
391 @code{fortran-comment-indent-style}. The variable
392 @code{fortran-directive-re} is a regular expression that specifies which
393 lines are directives. Matching lines are never indented, and receive
394 distinctive font-locking.
395
396 The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
397 you use @samp{!} comments, this command can be used with them. Otherwise
398 it is useless in Fortran mode.
399
400 @kindex C-c ; @r{(Fortran mode)}
401 @findex fortran-comment-region
402 @vindex fortran-comment-region
403 The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
404 lines of the region into comments by inserting the string @samp{C$$$} at
405 the front of each one. With a numeric argument, it turns the region
406 back into live code by deleting @samp{C$$$} from the front of each line
407 in it. The string used for these comments can be controlled by setting
408 the variable @code{fortran-comment-region}. Note that here we have an
409 example of a command and a variable with the same name; these two uses
410 of the name never conflict because in Lisp and in Emacs it is always
411 clear from the context which one is meant.
412
413 @node Fortran Autofill
414 @subsection Auto Fill in Fortran Mode
415
416 Fortran mode has specialized support for Auto Fill mode, which is a
417 minor mode that automatically splits statements as you insert them
418 when they become too wide. Splitting a statement involves making
419 continuation lines using @code{fortran-continuation-string}
420 (@pxref{ForIndent Cont}). This splitting happens when you type
421 @key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran
422 indentation commands. You activate Auto Fill in Fortran mode in the
423 normal way. @xref{Auto Fill,,, emacs, the Emacs Manual}.
424
425 @vindex fortran-break-before-delimiters
426 Auto Fill breaks lines at spaces or delimiters when the lines get
427 longer than the desired width (the value of @code{fill-column}). The
428 delimiters (besides whitespace) that Auto Fill can break at are
429 @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>},
430 and @samp{,}. The line break comes after the delimiter if the
431 variable @code{fortran-break-before-delimiters} is @code{nil}.
432 Otherwise (and by default), the break comes before the delimiter.
433
434 To enable Auto Fill in all Fortran buffers, add
435 @code{turn-on-auto-fill} to @code{fortran-mode-hook}. @xref{Hooks,,,
436 emacs, the Emacs Manual}.
437
438 @node Fortran Columns
439 @subsection Checking Columns in Fortran
440
441 @table @kbd
442 @item C-c C-r
443 Display a ``column ruler'' momentarily above the current line
444 (@code{fortran-column-ruler}).
445 @item C-c C-w
446 Split the current window horizontally temporarily so that it is 72
447 columns wide (@code{fortran-window-create-momentarily}). This may
448 help you avoid making lines longer than the 72-character limit that
449 some Fortran compilers impose.
450 @item C-u C-c C-w
451 Split the current window horizontally so that it is 72 columns wide
452 (@code{fortran-window-create}). You can then continue editing.
453 @item M-x fortran-strip-sequence-nos
454 Delete all text in column 72 and beyond.
455 @end table
456
457 @kindex C-c C-r @r{(Fortran mode)}
458 @findex fortran-column-ruler
459 The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
460 ruler momentarily above the current line. The comment ruler is two lines
461 of text that show you the locations of columns with special significance in
462 Fortran programs. Square brackets show the limits of the columns for line
463 numbers, and curly brackets show the limits of the columns for the
464 statement body. Column numbers appear above them.
465
466 Note that the column numbers count from zero, as always in GNU Emacs.
467 As a result, the numbers may be one less than those you are familiar
468 with; but the positions they indicate in the line are standard for
469 Fortran.
470
471 @vindex fortran-column-ruler-fixed
472 @vindex fortran-column-ruler-tabs
473 The text used to display the column ruler depends on the value of the
474 variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
475 @code{nil}, then the value of the variable
476 @code{fortran-column-ruler-fixed} is used as the column ruler.
477 Otherwise, the value of the variable @code{fortran-column-ruler-tab} is
478 displayed. By changing these variables, you can change the column ruler
479 display.
480
481 @kindex C-c C-w @r{(Fortran mode)}
482 @findex fortran-window-create-momentarily
483 @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
484 splits the current window horizontally, making a window 72 columns
485 wide, so you can see any lines that are too long. Type a space to
486 restore the normal width.
487
488 @kindex C-u C-c C-w @r{(Fortran mode)}
489 @findex fortran-window-create
490 You can also split the window horizontally and continue editing with
491 the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x
492 fortran-window-create}). By editing in this window you can
493 immediately see when you make a line too wide to be correct Fortran.
494
495 @findex fortran-strip-sequence-nos
496 The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in
497 column 72 and beyond, on all lines in the current buffer. This is the
498 easiest way to get rid of old sequence numbers.
499
500 @node Fortran Abbrev
501 @subsection Fortran Keyword Abbrevs
502
503 Fortran mode provides many built-in abbrevs for common keywords and
504 declarations. These are the same sort of abbrev that you can define
505 yourself. To use them, you must turn on Abbrev mode.
506 @xref{Abbrevs,,, emacs, the Emacs Manual}.
507
508 The built-in abbrevs are unusual in one way: they all start with a
509 semicolon. You cannot normally use semicolon in an abbrev, but Fortran
510 mode makes this possible by changing the syntax of semicolon to ``word
511 constituent.''
512
513 For example, one built-in Fortran abbrev is @samp{;c} for
514 @samp{continue}. If you insert @samp{;c} and then insert a punctuation
515 character such as a space or a newline, the @samp{;c} expands automatically
516 to @samp{continue}, provided Abbrev mode is enabled.@refill
517
518 Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
519 Fortran abbrevs and what they stand for.