* cc-mode.texi: Updated for CC Mode 5.30.
Note: Please refrain from doing purely cosmetic changes like
removing trailing whitespace in this manual; it clobbers cvs
merging for no good reason.
@c This is part of the Emacs manual.@c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@node Programs, Building, Text, Top@chapter Editing Programs@cindex Lisp editing@cindex C editing@cindex program editing Emacs provides many features to facilitate editing programs. Someof these features can@itemize @bullet@itemFind or move over top-level definitions (@pxref{Defuns}).@itemApply the usual indentation conventions of the language(@pxref{Program Indent}).@itemInsert, kill or align comments (@pxref{Comments}).@itemBalance parentheses (@pxref{Parentheses}).@itemHighlight program syntax (@pxref{Font Lock}).@end itemize This chapter describes these features and many more.@menu* Program Modes:: Major modes for editing programs.* Defuns:: Commands to operate on major top-level parts of a program.* Program Indent:: Adjusting indentation to show the nesting.* Comments:: Inserting, killing, and aligning comments.* Parentheses:: Commands that operate on parentheses.* Documentation:: Getting documentation of functions you plan to call.* Hideshow:: Displaying blocks selectively.* Symbol Completion:: Completion on symbol names of your program or language.* Glasses:: Making identifiersLikeThis more readable.* Misc for Programs:: Other Emacs features useful for editing programs.* C Modes:: Special commands of C, C++, Objective-C, Java, and Pike modes.* Fortran:: Fortran mode and its special features.* Asm Mode:: Asm mode and its special features.@end menu@node Program Modes@section Major Modes for Programming Languages@cindex modes for programming languages Emacs has specialized major modes for various programming languages.@xref{Major Modes}. A programming language major mode typicallyspecifies the syntax of expressions, the customary rules forindentation, how to do syntax highlighting for the language, and howto find the beginning of a function definition. It often customizesor provides facilities for compiling and debugging programs as well. Ideally, Emacs should provide a major mode for each programminglanguage that you might want to edit; if it doesn't have a mode foryour favorite language, you can contribute one. But often the modefor one language can serve for other syntactically similar languages.The major mode for language @var{l} is called @code{@var{l}-mode},and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.@xref{Choosing Modes}.@cindex Perl mode@cindex Icon mode@cindex Awk mode@cindex Makefile mode@cindex Tcl mode@cindex CPerl mode@cindex DSSSL mode@cindex Octave mode@cindex Metafont mode@cindex Modula2 mode@cindex Prolog mode@cindex Simula mode@cindex VHDL mode@cindex M4 mode@cindex Shell-script mode@cindex Delphi mode@cindex PostScript mode The existing programming language major modes include Lisp, Scheme (avariant of Lisp) and the Scheme-based DSSSL expression language, Ada,Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixedformat), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'scompanion for font creation), Modula2, Objective-C, Octave, Pascal,Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There isalso a major mode for makefiles, called Makefile mode. An alternativemode for Perl is called CPerl mode. Modes are available for thescripting languages of the common GNU and Unix shells, VMS DCL, andMS-DOS/MS-Windows @samp{BAT} files. There are also major modes forediting various sorts of configuration files.@kindex DEL @r{(programming modes)}@findex c-electric-backspace In most programming languages, indentation should vary from line toline to illustrate the structure of the program. So the major modesfor programming languages arrange for @key{TAB} to update theindentation of the current line. They also rebind @key{DEL} to treata tab as if it were the equivalent number of spaces; this lets youdelete one column of indentation without worrying whether thewhitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete atab character before point, in these modes. Separate manuals are available for the modes for Ada (@pxref{Top, , AdaMode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).@cindex mode hook@vindex c-mode-hook@vindex lisp-mode-hook@vindex emacs-lisp-mode-hook@vindex lisp-interaction-mode-hook@vindex scheme-mode-hook Turning on a major mode runs a normal hook called the @dfn{modehook}, which is the value of a Lisp variable. Each major mode has amode hook, and the hook's name is always made from the mode command'sname by adding @samp{-hook}. For example, turning on C mode runs thehook @code{c-mode-hook}, while turning on Lisp mode runs the hook@code{lisp-mode-hook}. The purpose of the mode hook is to give you aplace to set up customizations for that major mode. @xref{Hooks}.@node Defuns@section Top-Level Definitions, or Defuns In Emacs, a major definition at the top level in the buffer iscalled a @dfn{defun}. The name comes from Lisp, but in Emacs we useit for all languages. In most programming language modes, Emacs assumes that a defun isany pair of parentheses (or braces, if the language uses braces thisway) that starts at the left margin. For example, in C, the body of afunction definition is normally a defun, because the open-brace thatbegins it is normally at the left margin. A variable's initializercan also count as a defun, if the open-brace that begins theinitializer is at the left margin. However, some language modes provide their own code for recognizingdefuns in a way that suits the language syntax and conventions better.@menu* Left Margin Paren:: An open-paren or similar opening delimiter starts a defun if it is at the left margin.* Moving by Defuns:: Commands to move over or mark a major definition.* Imenu:: Making buffer indexes as menus.* Which Function:: Which Function mode shows which function you are in.@end menu@node Left Margin Paren@subsection Left Margin Convention@cindex open-parenthesis in leftmost column@cindex ( in leftmost column In most major modes, Emacs assumes that any opening delimiter foundat the left margin is the start of a top-level definition, or defun.Therefore, @strong{never put an opening delimiter at the left marginunless it should have that significance.} For instance, never put anopen-parenthesis at the left margin in a Lisp file unless it is thestart of a top-level list. Never put an open-brace or other openingdelimiter at the beginning of a line of C code unless it is at toplevel. If you don't follow this convention, not only will you have troublewhen you explicitly use the commands for motion by defuns; otherfeatures that use them will also give you trouble. This includesthe indentation commands (@pxref{Program Indent}) and Font Lockmode (@pxref{Font Lock}). The most likely problem case is when you want an opening delimiterat the start of a line inside a string. To avoid trouble, put anescape character (@samp{\}, in C and Emacs Lisp, @samp{/} in someother Lisp dialects) before the opening delimiter. This will notaffect the contents of the string, but will prevent that openingdelimiter from starting a defun. Here's an example:@example (insert "Foo:\(bar)")@end example To help you catch violations of this convention, Font Lock modehighlights confusing opening delimiters (those that ought to bequoted) in bold red. In the earliest days, the original Emacs found defuns by movingupward a level of parentheses or braces until there were no morelevels to go up. This always required scanning all the way back tothe beginning of the buffer, even for a small function. To speed upthe operation, we changed Emacs to assume that any opening delimiterat the left margin is the start of a defun. This heuristic is nearlyalways right, and avoids the need to scan back to the beginning of thebuffer. However, it mandates following the convention describedabove.@node Moving by Defuns@subsection Moving by Defuns@cindex defuns These commands move point or set up the region based on top-levelmajor definitions, also called @dfn{defuns}.@table @kbd@item C-M-aMove to beginning of current or preceding defun(@code{beginning-of-defun}).@item C-M-eMove to end of current or following defun (@code{end-of-defun}).@item C-M-hPut region around whole current or following defun (@code{mark-defun}).@end table@cindex move to beginning or end of function@cindex function, move to beginning or end@kindex C-M-a@kindex C-M-e@kindex C-M-h@findex beginning-of-defun@findex end-of-defun@findex mark-defun The commands to move to the beginning and end of the current defunare @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}(@code{end-of-defun}). If you repeat one of these commands, or use apositive numeric argument, each repetition moves to the next defun inthe direction of motion. @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward@var{n} times to the next beginning of a defun. This is not exactlythe same place that @kbd{C-M-e} with argument @var{n} would move to;the end of this defun is not usually exactly the same place as thebeginning of the following defun. (Whitespace, comments, and perhapsdeclarations can separate them.) Likewise, @kbd{C-M-e} with anegative argument moves back to an end of a defun, which is not quitethe same as @kbd{C-M-a} with a positive argument.@kindex C-M-h @r{(C mode)}@findex c-mark-function To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})which puts point at the beginning and mark at the end of the currentdefun. This is the easiest way to get ready to kill the defun inorder to move it to a different place in the file. If you use thecommand while point is between defuns, it uses the following defun. In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},which is almost the same as @code{mark-defun}; the difference is thatit backs up over the argument declarations, function name and returneddata type so that the entire C function is inside the region. This isan example of how major modes adjust the standard key bindings so thatthey do their standard jobs in a way better fitting a particularlanguage. Other major modes may replace any or all of these keybindings for that purpose.@node Imenu@subsection Imenu@cindex index of buffer definitions@cindex buffer definitions index@cindex tags The Imenu facility offers a way to find the major definitions ina file by name. It is also useful in text formatter major modes,where it treats each chapter, section, etc., as a definition.(@xref{Tags}, for a more powerful feature that handles multiple filestogether.)@findex imenu If you type @kbd{M-x imenu}, it reads the name of a definition usingthe minibuffer, then moves point to that definition. You can usecompletion to specify the name; the command always displays the wholelist of valid names.@findex imenu-add-menubar-index Alternatively, you can bind the command @code{imenu} to a mouseclick. Then it displays mouse menus for you to select a definitionname. You can also add the buffer's index to the menu bar by calling@code{imenu-add-menubar-index}. If you want to have this menu baritem available for all buffers in a certain major mode, you can dothis by adding @code{imenu-add-menubar-index} to its mode hook. Butif you have done that, you will have to wait each time you visit afile in that mode, while Emacs finds all the definitions in thatbuffer.@vindex imenu-auto-rescan When you change the contents of a buffer, if you add or deletedefinitions, you can update the buffer's index based on thenew contents by invoking the @samp{*Rescan*} item in the menu.Rescanning happens automatically if you set @code{imenu-auto-rescan} toa non-@code{nil} value. There is no need to rescan because of smallchanges in the text.@vindex imenu-sort-function You can customize the way the menus are sorted by setting thevariable @code{imenu-sort-function}. By default, names are ordered asthey occur in the buffer; if you want alphabetic sorting, use thesymbol @code{imenu--sort-by-name} as the value. You can alsodefine your own comparison function by writing Lisp code. Imenu provides the information to guide Which Function mode@ifnottex(@pxref{Which Function}).@end ifnottex@iftex(see below).@end iftexThe Speedbar can also use it (@pxref{Speedbar}).@node Which Function@subsection Which Function Mode@cindex current function name in mode line Which Function mode is a minor mode that displays the currentfunction name in the mode line, updating it as you move around in abuffer.@findex which-function-mode@vindex which-func-modes To enable (or disable) Which Function mode, use the command @kbd{M-xwhich-function-mode}. This command is global; it applies to allbuffers, 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 WhichFunction mode applies to all major modes that know how to supportit---in other words, all the major modes that support Imenu.@node Program Indent@section Indentation for Programs@cindex indentation for programs The best way to keep a program properly indented is to use Emacs toreindent it as you change it. Emacs has commands to indent properlyeither a single line, a specified number of lines, or all of the linesinside a single parenthetical grouping.@menu* Basic Indent:: Indenting a single line.* Multi-line Indent:: Commands to reindent many lines at once.* Lisp Indent:: Specifying how each Lisp function should be indented.* C Indent:: Extra features for indenting C and related modes.* Custom C Indent:: Controlling indentation style for C and related modes.@end menu@cindex pretty-printer Emacs also provides a Lisp pretty-printer in the library @code{pp}.This program reformats a Lisp object with indentation chosen to look nice.@node Basic Indent@subsection Basic Program Indentation Commands The basic indentation commands indent a single line according to theusual conventions of the language you are editing.@table @kbd@item @key{TAB}Adjust indentation of current line.@item C-jEquivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).@item @key{LINEFEED}This key, if the keyboard has it, is another way to enter @kbd{C-j}.@end table@kindex TAB @r{(programming modes)}@findex c-indent-command@findex indent-line-function@findex indent-for-tab-command The basic indentation command is @key{TAB}, which gives the current linethe correct indentation as determined from the previous lines. Thefunction 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 functionsunderstand the syntax and conventions of different languages, but they all doconceptually the same job: @key{TAB} in any programming-language major modeinserts or deletes whitespace at the beginning of the current line,independent of where point is in the line. If point was inside thewhitespace at the beginning of the line, @key{TAB} puts it at the end ofthat whitespace; otherwise, @key{TAB} keeps point fixed with respect tothe characters around it. Use @kbd{C-q @key{TAB}} to insert a tab at point.@kindex C-j@findex newline-and-indent When entering lines of new code, use @kbd{C-j}(@code{newline-and-indent}), which is equivalent to a @key{RET}followed by a @key{TAB}. @kbd{C-j} at the end of a line creates ablank line and then gives it the appropriate indentation. @key{TAB} indents lines that start within a parenthetical groupingeach under the preceding line (or the text after the parenthesis).Therefore, if you manually give one of these lines a nonstandardindentation, the lines below will tend to follow it. This behavior isconvenient in cases where you have overridden the standard result of@key{TAB} because you find it unaesthetic for a particular line. Remember that an open-parenthesis, open-brace or other opening delimiterat the left margin is assumed by Emacs (including the indentation routines)to be the start of a function. Therefore, you must never have an openingdelimiter in column zero that is not the beginning of a function, not eveninside a string. This restriction is vital for making the indentationcommands fast; you must simply accept it. @xref{Left Margin Paren},for more information on this. Normally, lines are indented with tabs and spaces. If you want Emacsto use spaces only, see @ref{Just Spaces}.@node Multi-line Indent@subsection Indenting Several Lines When you wish to reindent several lines of code which have beenaltered or moved to a different level in the parenthesis structure,you have several commands available.@table @kbd@item C-M-qReindent 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 itsfirst line is properly indented.@item M-x indent-code-rigidlyShift all the lines in the region rigidly sideways, but do not alterlines 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 bypositioning 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; alsobound to other suitable commands in other modes). The indentation ofthe line where the grouping starts is not changed; therefore, thischanges only the relative indentation within the grouping, not itsoverall indentation. To correct that as well, type @key{TAB} first. Another way to specify the range to be reindented is with theregion. The command @kbd{C-M-\} (@code{indent-region}) applies@key{TAB} to every line whose first character is between point andmark.@kindex C-u TAB If you like the relative indentation within a grouping, but not theindentation of its first line, you can type @kbd{C-u @key{TAB}} toreindent the whole grouping as a rigid unit. (This works in Lispmodes and C and related modes.) @key{TAB} with a numeric argumentreindents the current line as usual, then reindents by the same amountall the lines in the parenthetical grouping starting on the currentline. It is clever, though, and does not alter lines that startinside strings, or C preprocessor lines when in C mode.@findex indent-code-rigidly You can also perform this operation on the region, using the command@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in theregion sideways, like @code{indent-rigidly} does (@pxref{IndentationCommands}). It doesn't alter the indentation of lines that startinside a comment or a string, unless the region starts inside thatcomment or string.@node Lisp Indent@subsection Customizing Lisp Indentation@cindex customizing Lisp indentation The indentation pattern for a Lisp expression can depend on the functioncalled by the expression. For each Lisp function, you can choose amongseveral predefined patterns of indentation, or define an arbitrary one witha Lisp program. The standard pattern of indentation is as follows: the second line of theexpression is indented under the first argument, if that is on the sameline as the beginning of the expression; otherwise, the second line isindented underneath the function name. Each following line is indentedunder the previous line whose nesting depth is the same.@vindex lisp-indent-offset If the variable @code{lisp-indent-offset} is non-@code{nil}, it overridesthe usual indentation pattern for the second line of an expression, so thatsuch lines are always indented @code{lisp-indent-offset} more columns thanthe containing list.@vindex lisp-body-indent Certain functions override the standard pattern. Functions whosenames start with @code{def} treat the second lines as the start ofa @dfn{body}, by indenting the second line @code{lisp-body-indent}additional columns beyond the open-parenthesis that starts theexpression.@cindex @code{lisp-indent-function} property You can override the standard pattern in various ways for individualfunctions, according to the @code{lisp-indent-function} property ofthe function name. Normally you would use this for macro definitionsand specify it using the @code{declare} construct (@pxref{DefiningMacros,,, elisp, the Emacs Lisp Reference Manual}).@node C Indent@subsection Commands for C Indentation Here are special features for indentation in C mode and related modes:@table @code@item C-c C-q@kindex C-c C-q @r{(C mode)}@findex c-indent-defunReindent the current top-level function definition or aggregate typedeclaration (@code{c-indent-defun}).@item C-M-q@kindex C-M-q @r{(C mode)}@findex c-indent-expReindent each line in the balanced expression that follows point(@code{c-indent-exp}). A prefix argument inhibits error checking andwarning messages about invalid syntax.@item @key{TAB}@findex c-indent-commandReindent the current line, and/or in some cases insert a tab character(@code{c-indent-command}).If @code{c-tab-always-indent} is @code{t}, this command always reindentsthe current line and does nothing else. This is the default.If that variable is @code{nil}, this command reindents the current lineonly if point is at the left margin or in the line's indentation;otherwise, it inserts a tab (or the equivalent number of spaces,if @code{indent-tabs-mode} is @code{nil}).Any other value (not @code{nil} or @code{t}) means always reindent theline, and also insert a tab if within a comment, a string, or apreprocessor directive.@end table To reindent the whole current buffer, type @kbd{C-x h C-M-\}. Thisfirst selects the whole buffer as the region, then reindents thatregion. To reindent the current block, use @kbd{C-M-u C-M-q}. This movesto the front of the block and then reindents it all.@node Custom C Indent@subsection Customizing C Indentation@cindex style (for indentation) C mode and related modes use a simple yet flexible mechanism forcustomizing indentation. The mechanism works in two steps: first itclassifies the line syntactically according to its contents and context;second, it associates each kind of syntactic construct with anindentation offset based on your selected @dfn{style}.@table @kbd@item M-x c-set-style @key{RET} @var{style} @key{RET}Select predefined indentation style @var{style}.@end table A style is a named collection of indentation customizations that canbe used in C mode and the related modes. Emacs comes with severalpredefined styles, including @code{gnu}, @code{k&r}, @code{bsd},@code{stroustrup}, @code{linux}, @code{python}, @code{java},@code{whitesmith}, @code{ellemtel}, @code{cc-mode}, and @code{user}.Some of these styles are primarily intended for one language, but anyof them can be used with any of the languages supported by thesemodes. To find out what a style looks like, select it and reindentsome code, e.g., by typing @key{C-M-q} at the start of a functiondefinition.@findex c-set-style To choose a style for the current buffer, use the command @kbd{M-xc-set-style}. Specify a style name as an argument (case is notsignificant). This command affects the current buffer only, and itaffects only future invocations of the indentation commands; it doesnot reindent the code in the buffer. To reindent the whole buffer inthe new style, you can type @kbd{C-x h C-M-\}.@vindex c-default-style You can also set the variable @code{c-default-style} to specify thedefault style for various major modes. Its value should be an alist,in which each element specifies one major mode and which indentationstyle to use for it. For example,@example(setq c-default-style '((java-mode . "java") (other . "gnu")))@end example@noindentspecifies an explicit choice for Java mode, and the default @samp{gnu}style for the other C-like modes. This variable takes effect when youselect one of the C-like major modes; thus, if you specify a newdefault style for Java mode, you can make it take effect in anexisting Java mode buffer by typing @kbd{M-x java-mode} there. The @code{gnu} style specifies the formatting recommended by the GNUProject for C; it is the default, so as to encourage use of ourrecommended style. @xref{Customizing Indentation,,, ccmode, the CC Mode Manual}, formore information on customizing indentation for C and related modes,including how to override parts of an existing style and how to defineyour own styles.@node Parentheses@section Commands for Editing with Parentheses@findex check-parens@cindex unbalanced parentheses and quotes This section describes the commands and features that take advantageof the parenthesis structure in a program, or help you keep itbalanced. When talking about these facilities, the term ``parenthesis'' alsoincludes braces, brackets, or whatever delimiters are defined to matchin pairs. The major mode controls which delimiters are significant,through the syntax table (@pxref{Syntax}). In Lisp, only parenthesescount; in C, these commands apply to braces and brackets too. You can use @kbd{M-x check-parens} to find any unbalancedparentheses and unbalanced string quotes in the buffer.@menu* Expressions:: Expressions with balanced parentheses.* Moving by Parens:: Commands for moving up, down and across in the structure of parentheses.* Matching:: Insertion of a close-delimiter flashes matching open.@end menu@node Expressions@subsection Expressions with Balanced Parentheses@cindex sexp@cindex expression@cindex balanced expression These commands deal with balanced expressions, also called@dfn{sexps}@footnote{The word ``sexp'' is used to refer to anexpression in Lisp.}.@table @kbd@item C-M-fMove forward over a balanced expression (@code{forward-sexp}).@item C-M-bMove backward over a balanced expression(@code{backward-sexp}).@item C-M-kKill balanced expression forward (@code{kill-sexp}).@item C-M-tTranspose expressions (@code{transpose-sexps}).@item C-M-@@Put mark after following expression (@code{mark-sexp}).@end table Each programming language major mode customizes the definition ofbalanced expressions to suit that language. Balanced expressionstypically include symbols, numbers, and string constants, as well asany pair of matching delimiters and their contents. Some languageshave obscure forms of expression syntax that nobody has bothered toimplement in Emacs.@cindex Control-Meta By convention, the keys for these commands are all Control-Metacharacters. They usually act on expressions just as the correspondingMeta characters act on words. For instance, the command @kbd{C-M-b}moves backward over a balanced expression, just as @kbd{M-b} movesback over a word.@kindex C-M-f@kindex C-M-b@findex forward-sexp@findex backward-sexp To move forward over a balanced expression, use @kbd{C-M-f}(@code{forward-sexp}). If the first significant character after pointis an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or@samp{@{} in C), @kbd{C-M-f} moves past the matching closingdelimiter. If the character begins a symbol, string, or number,@kbd{C-M-f} moves over that. The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over abalanced expression. The detailed rules are like those above for@kbd{C-M-f}, but with directions reversed. If there are prefixcharacters (single-quote, backquote and comma, in Lisp) preceding theexpression, @kbd{C-M-b} moves back over them as well. The balancedexpression commands move across comments as if they were whitespace,in most modes. @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation thespecified number of times; with a negative argument, it moves in theopposite direction.@cindex killing expressions@kindex C-M-k@findex kill-sexp Killing a whole balanced expression can be done with @kbd{C-M-k}(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}would move over.@cindex transposition of expressions@kindex C-M-t@findex transpose-sexps A somewhat random-sounding command which is nevertheless handy is@kbd{C-M-t} (@code{transpose-sexps}), which drags the previousbalanced expression across the next one. An argument serves as arepeat count, and a negative argument drags the previous balancedexpression backwards across those before it (thus canceling out theeffect of @kbd{C-M-t} with a positive argument). An argument of zero,rather than doing nothing, transposes the balanced expressions endingat or after point and the mark.@kindex C-M-@@@findex mark-sexp To set the region around the next balanced expression in the buffer,use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same placethat @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like@kbd{C-M-f}. In particular, a negative argument is useful for puttingthe mark at the beginning of the previous balanced expression. In languages that use infix operators, such as C, it is not possibleto recognize all balanced expressions as such because there can bemultiple possibilities at a given position. For example, C mode doesnot treat @samp{foo + bar} as a single expression, even though it@emph{is} one C expression; instead, it recognizes @samp{foo} as oneexpression and @samp{bar} as another, with the @samp{+} as punctuationbetween them. Both @samp{foo + bar} and @samp{foo} are legitimatechoices for ``the expression following point'' when point is at the@samp{f}, so the expression commands must perforce choose one or theother to operate on. Note that @samp{(foo + bar)} is recognized as asingle expression in C mode, because of the parentheses.@node Moving by Parens@subsection Moving in the Parenthesis Structure@cindex parenthetical groupings@cindex parentheses, moving across@cindex matching parenthesis and braces, moving to@cindex braces, moving across@cindex list commands The Emacs commands for handling parenthetical groupings see nothingexcept parentheses (or whatever characters must balance in thelanguage you are working with), and the escape characters that mightbe used to quote those. They are mainly intended for editingprograms, but can be useful for editing any text that has parentheses.They are sometimes called ``list'' commands because in Lisp thesegroupings are lists.@table @kbd@item C-M-nMove forward over a parenthetical group (@code{forward-list}).@item C-M-pMove backward over a parenthetical group(@code{backward-list}).@item C-M-uMove up in parenthesis structure (@code{backward-up-list}).@item C-M-dMove down in parenthesis structure (@code{down-list}).@end table@kindex C-M-n@kindex C-M-p@findex forward-list@findex backward-list The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})parenthetical groupings, skipping blithely over any amount of textthat doesn't include meaningful parentheses (symbols, strings, etc.).@kindex C-M-u@kindex C-M-d@findex backward-up-list@findex down-list @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in theparenthesis structure. To move @emph{up} one (or @var{n}) levels, use@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward uppast one unmatched opening delimiter. A positive argument serves as arepeat count; a negative argument reverses the direction of motion, sothat the command moves forward and up one or more levels. To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}(@code{down-list}). In Lisp mode, where @samp{(} is the only openingdelimiter, this is nearly the same as searching for a @samp{(}. Anargument specifies the number of levels to go down.@node Matching@subsection Automatic Display Of Matching Parentheses@cindex matching parentheses@cindex parentheses, displaying matches The Emacs parenthesis-matching feature is designed to showautomatically how parentheses (and other matching delimiters) match inthe text. Whenever you type a self-inserting character that is aclosing delimiter, the cursor moves momentarily to the location of thematching opening delimiter, provided that is on the screen. If it isnot on the screen, Emacs displays some of the text near it in the echoarea. Either way, you can tell which grouping you are closing off. If the opening delimiter and closing delimiter are mismatched---suchas 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 thecursor on the matching opening delimiter, before bringing it back tothe real location of point; the default is 1, but on some systems itis useful to specify a fraction of a second. @code{blink-matching-paren-distance} specifies how many charactersback to search to find the matching opening delimiter. If the matchis not found in that distance, scanning stops, and nothing is displayed.This is to prevent the scan for the matching delimiter from wastinglots of time when there is no match. The default is 25600.@cindex Show Paren mode@cindex highlighting matching parentheses@findex show-paren-mode Show Paren mode provides a more powerful kind of automatic matching.Whenever point is after a closing delimiter, that delimiter and itsmatching opening delimiter are both highlighted; otherwise, if pointis before an opening delimiter, the matching closing delimiter ishighlighted. (There is no need to highlight the opening delimiter inthat case, because the cursor appears on top of that character.) Usethe command @kbd{M-x show-paren-mode} to enable or disable this mode. By default, @code{show-paren-mode} uses colors to highlight theparentheses. However, if your display doesn't support colors, you cancustomize the faces @code{show-paren-match-face} and@code{show-paren-mismatch-face} to use other attributes, such as bold orunderline. @xref{Face Customization}.@node Comments@section Manipulating Comments@cindex comments Because comments are such an important part of programming, Emacsprovides special commands for editing and inserting comments. It canalso do spell checking on comments with Flyspell Prog mode(@pxref{Spelling}).@menu* Comment Commands:: Inserting, killing, and indenting comments.* Multi-Line Comments:: Commands for adding and editing multi-line comments.* Options for Comments::Customizing the comment features.@end menu@node Comment Commands@subsection Comment Commands@cindex indentation for comments The comment commands in this table insert, kill and align comments.They are described in this section and following sections.@table @kbd@item M-;Insert or realign comment on current line; alternatively, comment oruncomment the region (@code{comment-dwim}).@item C-u M-;Kill comment on current line (@code{comment-kill}).@item C-x ;Set comment column (@code{comment-set-column}).@item C-M-jLike @key{RET} followed by inserting and aligning a comment(@code{comment-indent-new-line}).@item M-x comment-regionAdd or remove comment delimiters on all the lines in the region.@end table@kindex M-;@findex comment-dwim The command to create or align a comment is @kbd{M-;}(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do WhatI Mean''; it indicates that this command can be used for manydifferent jobs relating to comments, depending on the situation whereyou use it. If there is no comment already on the line, @kbd{M-;} inserts a newcomment, aligned at a specific column called the @dfn{comment column}.The new comment begins with the string Emacs thinks comments shouldstart with (the value of @code{comment-start}; see below). Point isafter that string, so you can insert the text of the comment rightaway. If the major mode has specified a string to terminate comments,@kbd{M-;} inserts that too, to keep the syntax valid. If the text of the line extends past the comment column, then thecomment start string is indented to a suitable boundary (usually, atleast one space is inserted). You can also use @kbd{M-;} to align an existing comment. If a linealready contains the comment-start string, @kbd{M-;} reindents it tothe conventional alignment and moves point after it. (Exception:comments starting in column 0 are not moved.) Even when an existingcomment is properly aligned, @kbd{M-;} is still useful for movingdirectly to the start of the text inside the comment.@findex comment-kill@kindex C-u M-; @kbd{C-u M-;} kills any comment on the current line, along with thewhitespace before it. To reinsert the comment on another line, moveto the end of that line, do @kbd{C-y}, and then do @kbd{M-;} torealign it. Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}(@code{comment-dwim}) with a prefix argument. That command isprogrammed so that when it receives a prefix argument it calls@code{comment-kill}. However, @code{comment-kill} is a valid commandin its own right, and you can bind it directly to a key if you wish. @kbd{M-;} does two other jobs when used with an active region inTransient Mark mode (@pxref{Transient Mark}). Then it either adds orremoves comment delimiters on each line of the region. (If every lineis a comment, it removes comment delimiters from each; otherwise, itadds comment delimiters to each.) If you are not using Transient Markmode, then you should use the commands @code{comment-region} and@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}).A prefix argument used in these circumstances specifies how manycomment delimiters to add or how many to delete. Some major modes have special rules for indenting certain kinds ofcomments in certain contexts. For example, in Lisp code, comments whichstart with two semicolons are indented as if they were lines of code,instead of at the comment column. Comments which start with threesemicolons are supposed to start at the left margin. Emacs understandsthese conventions by indenting a double-semicolon comment using @key{TAB},and by not changing the indentation of a triple-semicolon comment at all.@example;; This function is just an example;;; Here either two or three semicolons are appropriate.(defun foo (x);;; And now, the first part of the function: ;; The following line adds one. (1+ x)) ; This line adds one.@end example In C code, a comment preceded on its line by nothing but whitespaceis indented like a line of code.@node Multi-Line Comments@subsection Multiple Lines of Comments@kindex C-M-j@cindex blank lines in programs@findex comment-indent-new-line If you are typing a comment and wish to continue it on another line,you can use the command @kbd{C-M-j} (@code{comment-indent-new-line}).This terminates the comment you are typing, creates a new blank lineafterward, and begins a new comment indented under the old one. WhenAuto Fill mode is on, going past the fill column while typing a commentcauses the comment to be continued in just this fashion. If point isnot at the end of the line when @kbd{C-M-j} is typed, the text onthe rest of the line becomes part of the new comment line.@findex comment-region To turn existing lines into comment lines, use the @kbd{M-xcomment-region} command. It adds comment delimiters to the lines that startin the region, thus commenting them out. With a negative argument, itdoes the opposite---it deletes comment delimiters from the lines in theregion. With a positive argument, @code{comment-region} duplicates the lastcharacter of the comment start sequence it adds; the argument specifieshow many copies of the character to insert. Thus, in Lisp mode,@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicatingthe comment delimiter is a way of calling attention to the comment. Itcan also affect how the comment is indented. In Lisp, for properindentation, you should use an argument of two or three, if between defuns;if within a defun, it must be three.@node Options for Comments@subsection Options Controlling Comments@vindex comment-column@kindex C-x ;@findex comment-set-column The comment column is stored in the variable @code{comment-column}. Youcan set it to a number explicitly. Alternatively, the command @kbd{C-x ;}(@code{comment-set-column}) sets the comment column to the column point isat. @kbd{C-u C-x ;} sets the comment column to match the last commentbefore point in the buffer, and then does a @kbd{M-;} to align thecurrent line's comment under the previous one. The variable @code{comment-column} is per-buffer: setting the variablein the normal fashion affects only the current buffer, but there is adefault value which you can change with @code{setq-default}.@xref{Locals}. Many major modes initialize this variable for thecurrent buffer.@vindex comment-start-skip The comment commands recognize comments based on the regularexpression that is the value of the variable @code{comment-start-skip}.Make sure this regexp does not match the null string. It may match morethan the comment starting delimiter in the strictest sense of the word;for example, in C mode the value of the variable is@c This stops M-q from breaking the line inside that @code.@code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spacesafter the @samp{/*} itself, and accepts C++ style comments also.(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} inthe string, which is needed to deny the first star its special meaningin regexp syntax. @xref{Regexps}.)@vindex comment-start@vindex comment-end When a comment command makes a new comment, it inserts the value of@code{comment-start} to begin it. The value of @code{comment-end} isinserted after point, so that it will follow the text that you will insertinto the comment. In C mode, @code{comment-start} has the value@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.@vindex comment-padding The variable @code{comment-padding} specifies how many spaces@code{comment-region} should insert on each line between thecomment delimiter and the line's original text. The default is 1,to insert one space.@vindex comment-multi-line The variable @code{comment-multi-line} controls how @kbd{C-M-j}(@code{indent-new-comment-line}) behaves when used inside a comment. If@code{comment-multi-line} is @code{nil}, as it normally is, then thecomment on the starting line is terminated and a new comment is startedon the new following line. If @code{comment-multi-line} is not@code{nil}, then the new following line is set up as part of the samecomment that was found on the starting line. This is done by notinserting a terminator on the old line, and not inserting a starter onthe new line. In languages where multi-line comments work, the choiceof value for this variable is a matter of taste.@vindex comment-indent-function The variable @code{comment-indent-function} should contain a functionthat will be called to compute the indentation for a newly insertedcomment or for aligning an existing comment. It is set differently byvarious major modes. The function is called with no arguments, but withpoint at the beginning of the comment, or at the end of a line if a newcomment is to be inserted. It should return the column in which thecomment ought to start. For example, in Lisp mode, the indent hookfunction bases its decision on how many semicolons begin an existingcomment, and on the code in the preceding lines.@node Documentation@section Documentation Lookup Emacs provides several features you can use to look up thedocumentation of functions, variables and commands that you plan touse in your program.@menu* Info Lookup:: Looking up library functions and commands in Info files.* Man Page:: Looking up man pages of library functions and commands.* Lisp Doc:: Looking up Emacs Lisp functions, etc.@end menu@node Info Lookup@subsection Info Documentation Lookup@findex info-lookup-symbol@findex info-lookup-file@kindex C-h C-i For C, Lisp, and other languages that have documentation in Info,you can use @kbd{C-h C-i} (@code{info-lookup-symbol}) to view the Infodocumentation for a symbol. You specify the symbol with theminibuffer; the default is the symbol appearing in the buffer atpoint. The major mode determines where to look for documentation for thesymbol---which Info files to look in, and which indices to search.You can also use @kbd{M-x info-lookup-file} to look for documentationfor a file name. This feature currently supports the modes Awk, Autoconf, Bison, C,Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo,provided you have installed the relevant Info files, which aretypically available with the appropriate GNU package.@node Man Page@subsection Man Page Lookup@cindex manual page On Unix, the main form of on-line documentation was the @dfn{manualpage} or @dfn{man page}. In the GNU operating system, we hope toreplace man pages with better-organized manuals that you can browsewith Info (@pxref{Misc Help}). This process is not finished, so it isstill useful to read manual pages.@findex manual-entry You can read the man page for an operating system command, libraryfunction, or system call, with the @kbd{M-x manual-entry} command. Itruns the @code{man} program to format the man page; if the systempermits, it runs @code{man} asynchronously, so that you can keep onediting while the page is being formatted. (On MS-DOS and MS-Windows3, you cannot edit while Emacs waits for @code{man} to finish.) Theresult goes in a buffer named @samp{*Man @var{topic}*}. These buffersuse a special major mode, Man mode, that facilitates scrolling andjumping to other manual pages. For details, type @kbd{C-h m} while ina man page buffer.@cindex sections of manual pages Each man page belongs to one of ten or more @dfn{sections}, eachnamed by a digit or by a digit and a letter. Sometimes there aremultiple man pages with the same name in different sections. To reada man page from a specific section, type@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}when @kbd{M-x manual-entry} prompts for the topic. For example, toread the man page for the C library function @code{chmod} (as opposedto a command of the same name), type @kbd{M-x manual-entry @key{RET}chmod(2) @key{RET}} (@code{chmod} is a system call, so it is insection @samp{2}).@vindex Man-switches If you do not specify a section, the results depend on how the@code{man} program works on your system. Some of them display onlythe first man page they find. Others display all man pages that havethe specified name, so you can move between them with the @kbd{M-n}and @kbd{M-p} keys@footnote{On some systems, the @code{man} programaccepts a @samp{-a} command-line option which tells it to display allthe man pages for the specified topic. If you want this behavior, youcan add this option to the value of the variable @code{Man-switches}.}.The mode line shows how many manual pages are present in the Man buffer.@vindex Man-fontify-manpage-flag By default, Emacs highlights the text in man pages. For a long manpage, highlighting can take substantial time. You can turn offhighlighting of man pages by setting the variable@code{Man-fontify-manpage-flag} to @code{nil}.@findex Man-fontify-manpage If you insert the text of a man page into an Emacs buffer in someother fashion, you can use the command @kbd{M-x Man-fontify-manpage} toperform the same conversions that @kbd{M-x manual-entry} does.@findex woman@cindex manual pages, on MS-DOS/MS-Windows An alternative way of reading manual pages is the @kbd{M-x woman}command@footnote{The name of the command, @code{woman}, is an acronymfor ``w/o (without) man,'' since it doesn't use the @code{man}program.}. Unlike @kbd{M-x man}, it does not run any externalprograms to format and display the man pages; instead it does the jobin Emacs Lisp, so it works on systems such as MS-Windows, where the@code{man} program (and the other programs it uses) are not generallyavailable. @kbd{M-x woman} prompts for a name of a manual page, and providescompletion based on the list of manual pages that are installed onyour machine; the list of available manual pages is computedautomatically the first time you invoke @code{woman}. The word atpoint in the current buffer is used to suggest the default for thename the manual page. With a numeric argument, @kbd{M-x woman} recomputes the list of themanual pages used for completion. This is useful if you add or deletemanual pages. If you type a name of a manual page and @kbd{M-x woman} finds thatseveral manual pages by the same name exist in different sections, itpops up a window with possible candidates asking you to choose one ofthem.@vindex woman-manpath By default, @kbd{M-x woman} looks for manual pages in thedirectories specified in the @code{MANPATH} environment variable. (If@code{MANPATH} is not set, @code{woman} uses a suitable default value,which can be customized.) More precisely, @code{woman} looks forsubdirectories that match the shell wildcard pattern @file{man*} in each oneof these directories, and tries to find the manual pages in thosesubdirectories. When first invoked, @kbd{M-x woman} converts thevalue of @code{MANPATH} to a list of directory names and stores thatlist in the @code{woman-manpath} variable. Changing the value of thisvariable is another way to control the list of directories used.@vindex woman-path You can also augment the list of directories searched by@code{woman} by setting the value of the @code{woman-path} variable.This variable should hold a list of specific directories which@code{woman} should search, in addition to those in@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in@code{woman-path} are searched for the manual pages, not for@file{man*} subdirectories.@findex woman-find-file Occasionally, you might need to display manual pages that are not inany of the directories listed by @code{woman-manpath} and@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for aname of a manual page file, with completion, and then formats anddisplays that file like @kbd{M-x woman} does.@vindex woman-dired-keys The first time you invoke @kbd{M-x woman}, it defines the Dired@kbd{W} key to run the @code{woman-find-file} command on the currentline's file. You can disable this by setting the variable@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition,the Tar-mode @kbd{w} key is define to invoke @code{woman-find-file} onthe current line's archive member. For more information about setting up and using @kbd{M-x woman}, see@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoManManual}.@node Lisp Doc@subsection Emacs Lisp Documentation Lookup As you edit Lisp code to be run in Emacs, you can use the commands@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}(@code{describe-variable}) to view documentation of functions andvariables that you want to use. These commands use the minibuffer toread the name of a function or variable to document, and display thedocumentation in a window. Their default arguments are based on thecode in the neighborhood of point. For @kbd{C-h f}, the default isthe function called in the innermost list containing point. @kbd{C-hv} uses the symbol name around or adjacent to point as its default.@cindex Eldoc mode@findex eldoc-mode A more automatic but less powerful method is Eldoc mode. This minormode constantly displays in the echo area the argument list for thefunction being called at point. (In other words, it finds thefunction call that point is contained in, and displays the argumentlist of that function.) Eldoc mode applies in Emacs Lisp and LispInteraction modes only. Use the command @kbd{M-x eldoc-mode} toenable or disable this feature.@node Hideshow@section Hideshow minor mode@findex hs-minor-mode Hideshow minor mode provides selective display of portions of aprogram, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode}to enable or disable this mode, or add @code{hs-minor-mode} to themode hook for certain major modes in order to enable it automaticallyfor those modes. Just what constitutes a block depends on the major mode. In C modeor C++ mode, they are delimited by braces, while in Lisp mode andsimilar modes they are delimited by parentheses. Multi-line commentsalso count as blocks.@findex hs-hide-all@findex hs-hide-block@findex hs-show-all@findex hs-show-block@findex hs-show-region@findex hs-hide-level@findex hs-minor-mode@kindex C-c @@ C-h@kindex C-c @@ C-s@kindex C-c @@ C-M-h@kindex C-c @@ C-M-s@kindex C-c @@ C-r@kindex C-c @@ C-l@kindex S-Mouse-2@table @kbd@item C-c @@ C-hHide the current block (@code{hs-hide-block}).@item C-c @@ C-sShow the current block (@code{hs-show-block}).@item C-c @@ C-cEither hide or show the current block (@code{hs-toggle-hiding})@item S-Mouse-2Either hide or show the block you click on (@code{hs-mouse-toggle-hiding})@item C-c @@ C-M-hHide all top-level blocks (@code{hs-hide-all}).@item C-c @@ C-M-sShow everything in the buffer (@code{hs-show-all}).@item C-c @@ C-lHide all blocks @var{n} levels below this block(@code{hs-hide-level}).@end table@vindex hs-hide-comments-when-hiding-all@vindex hs-isearch-open@vindex hs-special-modes-alist These user options exist for customizing Hideshow mode.@table @code@item hs-hide-comments-when-hiding-allNon-@code{nil} says that @kbd{hs-hide-all} should hide comments too.@item hs-isearch-openSpecifies what kind of hidden blocks to open in Isearch mode.The value should be one of these four symbols.@table @code@item codeOpen only code blocks.@item commentOpen only comments.@item tOpen both code blocks and comments.@item nilOpen neither code blocks nor comments.@end table@item hs-special-modes-alistA list of elements, each specifying how to initialize Hideshowvariables for one major mode. See the variable's documentation stringfor more information.@end table@node Symbol Completion@section Completion for Symbol Names@cindex completion (symbol names) In Emacs, completion is something you normally do in the minibuffer.But one kind of completion is available in all buffers: completion forsymbol names.@kindex M-TAB The character @kbd{M-@key{TAB}} runs a command to complete thepartial symbol before point against the set of meaningful symbolnames. This command inserts at point any additional characters thatit can determine from the partial name. If the partial name in the buffer has multiple possible completionsthat differ in the very next character, so that it is impossible tocomplete even one more character, @kbd{M-@key{TAB}} displays a list ofall possible completions in another window.@cindex tags-based completion@cindex Info index completion@findex complete-symbol In most programming language major modes, @kbd{M-@key{TAB}} runs thecommand @code{complete-symbol}, which provides two kinds of completion.Normally it does completion based on a tags table (@pxref{Tags}); with anumeric argument (regardless of the value), it does completion based onthe names listed in the Info file indexes for your language. Thus, tocomplete the name of a symbol defined in your own program, use@kbd{M-@key{TAB}} with no argument; to complete the name of a standardlibrary function, use @kbd{C-u M-@key{TAB}}. Of course, Info-basedcompletion works only if there is an Info file for the standard libraryfunctions of your language, and only if it is installed at your site.@cindex Lisp symbol completion@cindex completion (Lisp symbols)@findex lisp-complete-symbol In Emacs-Lisp mode, the name space for completion normally consists ofnontrivial symbols present in Emacs---those that have functiondefinitions, values or properties. However, if there is anopen-parenthesis immediately before the beginning of the partial symbol,only symbols with function definitions are considered as completions.The command which implements this is @code{lisp-complete-symbol}. In Text mode and related modes, @kbd{M-@key{TAB}} completes wordsbased on the spell-checker's dictionary. @xref{Spelling}.@node Glasses@section Glasses minor mode@cindex Glasses mode@cindex identifiers, making long ones readable@cindex StudlyCaps, making them readable@findex glasses-mode Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}readable by altering the way they display. It knows two differentways to do this: by displaying underscores between a lower-case letterand the following capital letter, and by emboldening the capitalletters. It does not alter the buffer text, only the way theydisplay, so you can use it even on read-only buffers. You can use thecommand @kbd{M-x glasses-mode} to enable or disable the mode in thecurrent buffer; you can also add @code{glasses-mode} to the mode hookof the programming language major modes in which you normally wantto use Glasses mode.@node Misc for Programs@section Other Features Useful for Editing Programs A number of Emacs commands that aren't designed specifically forediting programs are useful for that nonetheless. The Emacs commands that operate on words, sentences and paragraphsare useful for editing code. Most symbols names contain words(@pxref{Words}); sentences can be found in strings and comments(@pxref{Sentences}). Paragraphs in the strict sense can be found inprogram code (in long comments), but the paragraph commands are usefulin other places too, because programming language major modes defineparagraphs to begin and end at blank lines (@pxref{Paragraphs}).Judicious use of blank lines to make the program clearer will alsoprovide useful chunks of text for the paragraph commands to work on.Auto Fill mode, if enabled in a programming language major mode,indents the new lines which it creates. The selective display feature is useful for looking at the overallstructure of a function (@pxref{Selective Display}). This featurehides the lines that are indented more than a specified amount.Programming modes often support Outline minor mode (@pxref{OutlineMode}). The Foldout package provides folding-editor features(@pxref{Foldout}). The ``automatic typing'' features may be useful for writing programs.@xref{Top,,Autotyping, autotype, Autotyping}.@node C Modes@section C and Related Modes@cindex C mode@cindex Java mode@cindex Pike mode@cindex IDL mode@cindex CORBA IDL mode@cindex Objective C mode@cindex C++ mode@cindex mode, Java@cindex mode, C@cindex mode, Objective C@cindex mode, CORBA IDL@cindex mode, Pike This section gives a brief description of the special featuresavailable in C, C++, Objective-C, Java, CORBA IDL, and Pike modes.(These are called ``C mode and related modes.'') @xref{Top, CC Mode,ccmode, , CC Mode}, for a more extensive description of these modesand their special features.@menu* Motion in C:: Commands to move by C statements, etc.* Electric C:: Colon and other chars can automatically reindent.* Hungry Delete:: A more powerful DEL command.* Other C Commands:: Filling comments, viewing expansion of macros, and other neat features.* Comments in C:: Options for customizing comment style.@end menu@node Motion in C@subsection C Mode Motion Commands This section describes commands for moving point, in C mode andrelated modes.@table @code@item C-c C-u@kindex C-c C-u @r{(C mode)}@findex c-up-conditionalMove point back to the containing preprocessor conditional, leaving themark behind. A prefix argument acts as a repeat count. With a negativeargument, move point forward to the end of the containingpreprocessor conditional. When going backwards, @code{#elif} is treatedlike @code{#else} followed by @code{#if}. When going forwards,@code{#elif} is ignored.@refill@item C-c C-p@kindex C-c C-p @r{(C mode)}@findex c-backward-conditionalMove point back over a preprocessor conditional, leaving the markbehind. A prefix argument acts as a repeat count. With a negativeargument, move forward.@item C-c C-n@kindex C-c C-n @r{(C mode)}@findex c-forward-conditionalMove point forward across a preprocessor conditional, leaving the markbehind. A prefix argument acts as a repeat count. With a negativeargument, move backward.@item M-a@kindex ESC a@findex c-beginning-of-statementMove point to the beginning of the innermost C statement(@code{c-beginning-of-statement}). If point is already at the beginningof a statement, move to the beginning of the preceding statement. Withprefix argument @var{n}, move back @var{n} @minus{} 1 statements.If point is within a string or comment, or next to a comment (onlywhitespace between them), this command moves by sentences instead ofstatements.When called from a program, this function takes three optionalarguments: the numeric prefix argument, a buffer position limit(don't move back before that place), and a flag that controls whetherto do sentence motion when inside of a comment.@item M-e@kindex ESC e@findex c-end-of-statementMove point to the end of the innermost C statement; like @kbd{M-a}except that it moves in the other direction (@code{c-end-of-statement}).@item M-x c-backward-into-nomenclature@findex c-backward-into-nomenclatureMove point backward to beginning of a C++ nomenclature section or word.With prefix argument @var{n}, move @var{n} times. If @var{n} isnegative, move forward. C++ nomenclature means a symbol name in thestyle of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letterbegins a section or word.In the GNU project, we recommend using underscores to separate wordswithin an identifier in C or C++, rather than using case distinctions.@item M-x c-forward-into-nomenclature@findex c-forward-into-nomenclatureMove point forward to end of a C++ nomenclature section or word.With prefix argument @var{n}, move @var{n} times.@end table@node Electric C@subsection Electric C Characters In C mode and related modes, certain printing characters are``electric''---in addition to inserting themselves, they also reindentthe current line and may insert newlines. This feature is controlled bythe variable @code{c-auto-newline}. The ``electric'' characters are@kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},@kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. Electric characters insert newlines only when the @dfn{auto-newline}feature is enabled (indicated by @samp{/a} in the mode line after themode name). This feature is controlled by the variable@code{c-auto-newline}. You can turn this feature on or off with thecommand @kbd{C-c C-a}:@table @kbd@item C-c C-a@kindex C-c C-a @r{(C mode)}@findex c-toggle-auto-stateToggle the auto-newline feature (@code{c-toggle-auto-state}). With aprefix argument, this command turns the auto-newline feature on if theargument is positive, and off if it is negative.@end table The colon character is electric because that is appropriate for asingle colon. But when you want to insert a double colon in C++, theelectric behavior of colon is inconvenient. You can insert a doublecolon with no reindentation or newlines by typing @kbd{C-c :}:@table @kbd@item C-c :@ifinfo@c This uses ``colon'' instead of a literal `:' because Info cannot@c cope with a `:' in a menu@kindex C-c @key{colon} @r{(C mode)}@end ifinfo@ifnotinfo@kindex C-c : @r{(C mode)}@end ifnotinfo@findex c-scope-operatorInsert a double colon scope operator at point, without reindenting theline or adding any newlines (@code{c-scope-operator}).@end table The electric @kbd{#} key reindents the line if it appears to be thebeginning of a preprocessor directive. This happens when the value of@code{c-electric-pound-behavior} is @code{(alignleft)}. You can turnthis feature off by setting @code{c-electric-pound-behavior} to@code{nil}. The variable @code{c-hanging-braces-alist} controls the insertion ofnewlines before and after inserted braces. It is an association listwith elements of the following form: @code{(@var{syntactic-symbol}. @var{nl-list})}. Most of the syntactic symbols that appear in@code{c-offsets-alist} are meaningful here as well. The list @var{nl-list} may contain either of the symbols@code{before} or @code{after}, or both; or it may be @code{nil}. When abrace is inserted, the syntactic context it defines is looked up in@code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is usedto determine where newlines are inserted: either before the brace,after, or both. If not found, the default is to insert a newline bothbefore and after braces. The variable @code{c-hanging-colons-alist} controls the insertion ofnewlines before and after inserted colons. It is an association listwith elements of the following form: @code{(@var{syntactic-symbol}. @var{nl-list})}. The list @var{nl-list} may contain either of thesymbols @code{before} or @code{after}, or both; or it may be @code{nil}. When a colon is inserted, the syntactic symbol it defines is lookedup in this list, and if found, the @var{nl-list} is used to determinewhere newlines are inserted: either before the brace, after, or both.If the syntactic symbol is not found in this list, no newlines areinserted. Electric characters can also delete newlines automatically when theauto-newline feature is enabled. This feature makes auto-newline moreacceptable, by deleting the newlines in the most common cases where youdo not want them. Emacs can recognize several cases in which deleting anewline might be desirable; by setting the variable@code{c-cleanup-list}, you can specify @emph{which} of these cases thatshould happen. The variable's value is a list of symbols, eachdescribing one case for possible deletion of a newline. Here are themeaningful symbols, and their meanings:@table @code@item brace-catch-braceClean up @samp{@} catch (@var{condition}) @{} constructs by placing theentire construct on a single line. The clean-up occurs when you typethe @samp{@{}, if there is nothing between the braces aside from@code{catch} and @var{condition}.@item brace-else-braceClean up @samp{@} else @{} constructs by placing the entire construct ona single line. The clean-up occurs when you type the @samp{@{} afterthe @code{else}, but only if there is nothing but white space betweenthe braces and the @code{else}.@item brace-elseif-braceClean up @samp{@} else if (@dots{}) @{} constructs by placing the entireconstruct on a single line. The clean-up occurs when you type the@samp{@{}, if there is nothing but white space between the @samp{@}} and@samp{@{} aside from the keywords and the @code{if}-condition.@item empty-defun-bracesClean up empty defun braces by placing the braces on the sameline. Clean-up occurs when you type the closing brace.@item defun-close-semiClean up the semicolon after a @code{struct} or similar typedeclaration, by placing the semicolon on the same line as the closingbrace. Clean-up occurs when you type the semicolon.@item list-close-commaClean up commas following braces in array and aggregateinitializers. Clean-up occurs when you type the comma.@item scope-operatorClean up double colons which may designate a C++ scope operator, byplacing the colons together. Clean-up occurs when you type the secondcolon, but only when the two colons are separated by nothing butwhitespace.@end table@node Hungry Delete@subsection Hungry Delete Feature in C When the @dfn{hungry-delete} feature is enabled (indicated by@samp{/h} or @samp{/ah} in the mode line after the mode name), a single@key{DEL} command deletes all preceding whitespace, not just one space.To turn this feature on or off, use @kbd{C-c C-d}:@table @kbd@item C-c C-d@kindex C-c C-d @r{(C mode)}@findex c-toggle-hungry-stateToggle the hungry-delete feature (@code{c-toggle-hungry-state}). With aprefix argument, this command turns the hungry-delete feature on if theargument is positive, and off if it is negative.@item C-c C-t@kindex C-c C-t @r{(C mode)}@findex c-toggle-auto-hungry-stateToggle the auto-newline and hungry-delete features, both at once(@code{c-toggle-auto-hungry-state}).@end table@vindex c-hungry-delete-key The variable @code{c-hungry-delete-key} controls whether thehungry-delete feature is enabled.@node Other C Commands@subsection Other Commands for C Mode@table @kbd@item C-M-hPut mark at the end of a function definition, and put point at thebeginning (@code{c-mark-function}).@item M-q@kindex M-q @r{(C mode)}@findex c-fill-paragraphFill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).If any part of the current line is a comment or within a comment, thiscommand fills the comment or the paragraph of it that point is in,preserving the comment indentation and comment delimiters.@item C-c C-e@cindex macro expansion in C@cindex expansion of C macros@findex c-macro-expand@kindex C-c C-e @r{(C mode)}Run the C preprocessor on the text in the region, and show the result,which includes the expansion of all the macro calls(@code{c-macro-expand}). The buffer text before the region is alsoincluded in preprocessing, for the sake of macros defined there, but theoutput from this part isn't shown.When you are debugging C code that uses macros, sometimes it is hard tofigure out precisely how the macros expand. With this command, youdon't have to figure it out; you can see the expansions.@item C-c C-\@findex c-backslash-region@kindex C-c C-\ @r{(C mode)}Insert or align @samp{\} characters at the ends of the lines of theregion (@code{c-backslash-region}). This is useful after writing orediting a C macro definition.If a line already ends in @samp{\}, this command adjusts the amount ofwhitespace before it. Otherwise, it inserts a new @samp{\}. However,the last line in the region is treated specially; no @samp{\} isinserted on that line, and any @samp{\} there is deleted.@item M-x cpp-highlight-buffer@cindex preprocessor highlighting@findex cpp-highlight-bufferHighlight parts of the text according to its preprocessor conditionals.This command displays another buffer named @samp{*CPP Edit*}, whichserves as a graphic menu for selecting how to display particular kindsof conditionals and their contents. After changing various settings,click on @samp{[A]pply these settings} (or go to that buffer and type@kbd{a}) to rehighlight the C mode buffer accordingly.@item C-c C-s@findex c-show-syntactic-information@kindex C-c C-s @r{(C mode)}Display the syntactic information about the current source line(@code{c-show-syntactic-information}). This is the information thatdirects how the line is indented.@item M-x cwarn-mode@itemx M-x global-cwarn-mode@findex cwarn-mode@findex global-cwarn-mode@cindex CWarn mode@cindex suspicious constructions in C, C++CWarn minor mode highlights certain suspicious C and C++ constructions:@itemize @bullet{}@itemAssignments inside expressions.@itemSemicolon following immediately after @samp{if}, @samp{for}, and @samp{while}(except after a @samp{do @dots{} while} statement);@itemC++ functions with reference parameters.@end itemize@noindentYou can enable the mode for one buffer with the command @kbd{M-xcwarn-mode}, or for all suitable buffers with the command @kbd{M-xglobal-cwarn-mode} or by customizing the variable@code{global-cwarn-mode}. You must also enable Font Lock mode to makeit work.@item M-x hide-ifdef-mode@findex hide-ifdef-mode@cindex Hide-ifdef modeHide-ifdef minor mode hides selected code within @samp{#if} and@samp{#ifdef} preprocessor blocks. See the documentation string of@code{hide-ifdef-mode} for more information.@item M-x ff-find-related-file@cindex related files@findex ff-find-related-file@vindex ff-related-file-alistFind a file ``related'' in a special way to the file visited by thecurrent buffer. Typically this will be the header file correspondingto a C/C++ source file, or vice versa. The variable@code{ff-related-file-alist} specifies how to compute related filenames.@end table@node Comments in C@subsection Comments in C Modes C mode and related modes use a number of variables for controllingcomment format.@table @code@item c-comment-only-line-offset@vindex c-comment-only-line-offsetExtra offset for line which contains only the start of a comment. Itcan be either an integer or a cons cell of the form@code{(@var{non-anchored-offset} . @var{anchored-offset})}, where@var{non-anchored-offset} is the amount of offset given tonon-column-zero anchored comment-only lines, and @var{anchored-offset}is the amount of offset to give column-zero anchored comment-only lines.Just an integer as value is equivalent to @code{(@var{val} . 0)}.@item c-comment-start-regexp@vindex c-comment-start-regexpThis buffer-local variable specifies how to recognize the start of a comment.@item c-hanging-comment-ender-p@vindex c-hanging-comment-ender-pIf this variable is @code{nil}, @code{c-fill-paragraph} leaves thecomment terminator of a block comment on a line by itself. The defaultvalue is @code{t}, which puts the comment-end delimiter @samp{*/} at theend of the last line of the comment text.@item c-hanging-comment-starter-p@vindex c-hanging-comment-starter-pIf this variable is @code{nil}, @code{c-fill-paragraph} leaves thestarting delimiter of a block comment on a line by itself. The defaultvalue is @code{t}, which puts the comment-start delimiter @samp{/*} atthe beginning of the first line of the comment text.@end table@node Fortran@section Fortran Mode@cindex Fortran mode@cindex mode, Fortran Fortran mode provides special motion commands for Fortran statements andsubprograms, and indentation commands that understand Fortran conventionsof nesting, line numbers and continuation statements. Fortran mode hasits own Auto Fill mode that breaks long lines into proper Fortrancontinuation lines. Special commands for comments are provided because Fortran commentsare unlike those of other languages. Built-in abbrevs optionally savetyping when you insert Fortran keywords. Use @kbd{M-x fortran-mode} to switch to this major mode. This commandruns 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'' sourcecode. For editing the modern Fortran90 ``free format'' source code,use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode forfiles with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 modefor the extension @samp{.f90}. GNU Fortran supports both kinds offormat.@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), Fortranmode provides special commands to move by statements.@table @kbd@kindex C-c C-n @r{(Fortran mode)}@findex fortran-next-statement@item C-c C-nMove to beginning of current or next statement(@code{fortran-next-statement}).@kindex C-c C-p @r{(Fortran mode)}@findex fortran-previous-statement@item C-c C-pMove to beginning of current or previous statement(@code{fortran-previous-statement}).@end table@node Fortran Indent@subsection Fortran Indentation Special commands and features are needed for indenting Fortran code inorder to make sure various syntactic entities (line numbers, comment lineindicators and continuation line flags) appear in the columns that arerequired for standard Fortran.@menu* Commands: ForIndent Commands. Commands for indenting and filling Fortran.* Contline: ForIndent Cont. How continuation lines indent.* Numbers: ForIndent Num. How line numbers auto-indent.* Conv: ForIndent Conv. Conventions you must obey to avoid trouble.* Vars: ForIndent Vars. Variables controlling Fortran indent style.@end menu@node ForIndent Commands@subsubsection Fortran Indentation and Filling Commands@table @kbd@item C-M-jBreak 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-qIndent all the lines of the subprogram point is in(@code{fortran-indent-subprogram}).@item M-qFill 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 commandto reindent all the lines of the Fortran subprogram (function orsubroutine) 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 splitsa line in the appropriate fashion for Fortran. In a non-comment line,the second half becomes a continuation line and is indentedaccordingly. In a comment line, both halves become separate commentlines.@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 asthe inverse of @code{fortran-split-line}. The point must be on acontinuation line when this command is invoked.@kindex M-q @r{(Fortran mode)}@kbd{M-q} in Fortran mode fills the comment block or statement thatpoint is in. This removes any excess statement continuations.@node ForIndent Cont@subsubsection Continuation Lines@cindex Fortran continuation lines@vindex fortran-continuation-string Most modern Fortran compilers allow two ways of writing continuationlines. If the first non-space character on a line is in column 5, thenthat line is a continuation of the previous line. We call this@dfn{fixed format}. (In GNU Emacs we always count columns from 0.) Thevariable @code{fortran-continuation-string} specifies what character toput on column 5. A line that starts with a tab character followed byany digit except @samp{0} is also a continuation line. We call thisstyle of continuation @dfn{tab format}.@vindex indent-tabs-mode @r{(Fortran mode)} Fortran mode can make either style of continuation line, but youmust specify which one you prefer. The value of the variable@code{indent-tabs-mode} controls the choice: @code{nil} for fixedformat, and non-@code{nil} for tab format. You can tell which styleis 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 Fortrancontinuation marker @samp{$}, or if it begins with any non-whitespacecharacter in column 5, Fortran mode treats it as a continuation line.When you indent a continuation line with @key{TAB}, it converts the lineto the current continuation style. When you split a Fortran statementwith @kbd{C-M-j}, the continuation marker on the newline is createdaccording to the continuation style. The setting of continuation style affects several other aspects ofediting in Fortran mode. In fixed format mode, the minimum columnnumber for the body of a statement is 6. Lines inside of Fortranblocks that are indented to larger column numbers always use only thespace character for whitespace. In tab format mode, the minimumcolumn number for the statement body is 8, and the whitespace beforecolumn 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 theproper continuation style automatically from the file contents. The firstline that begins with either a tab character or six spaces determines thechoice. The variable @code{fortran-analyze-depth} specifies how many linesto consider (at the beginning of the file); if none of those linesindicates a style, then the variable @code{fortran-tab-mode-default}specifies the style. If it is @code{nil}, that specifies fixed format, andnon-@code{nil} specifies tab format.@node ForIndent Num@subsubsection Line Numbers If a number is the first non-whitespace in the line, Fortranindentation assumes it is a line number and moves it to columns 0through 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; itspecifies the maximum indentation a line number can have. Line numbersare indented to right-justify them to end in column 4 unless that wouldrequire more than this maximum indentation. The default value of thevariable is 1.@vindex fortran-electric-line-number Simply inserting a line number is enough to indent it according tothese 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 linenumbers is like inserting anything else.@node ForIndent Conv@subsubsection Syntactic Conventions Fortran mode assumes that you follow certain conventions that simplifythe task of understanding a Fortran program well enough to indent itproperly:@itemize @bullet@itemTwo nested @samp{do} loops never share a @samp{continue} statement.@itemFortran 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 stringconstants, but Fortran mode does not recognize these keywords if theyare 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 thefirst and not on a continuation line.@end itemize@noindentIf you fail to follow these conventions, the indentation commands mayindent some lines unaesthetically. However, a correct Fortran programretains its meaning when reindented even if the conventions are notfollowed.@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-indentExtra indentation within each level of @samp{do} statement (default 3).@item fortran-if-indentExtra indentation within each level of @samp{if} statement (default 3).This value is also used for extra indentation within each level of theFortran 90 @samp{where} statement.@item fortran-structure-indentExtra indentation within each level of @samp{structure}, @samp{union}, or@samp{map} statements (default 3).@item fortran-continuation-indentExtra indentation for bodies of continuation lines (default 5).@item fortran-check-all-num-for-matching-doIf this is @code{nil}, indentation assumes that each @samp{do} statementends on a @samp{continue} statement. Therefore, when computingindentation for a statement other than @samp{continue}, it can save timeby not checking for a @samp{do} statement ending there. If this isnon-@code{nil}, indenting any numbered statement must check for a@samp{do} that ends there. The default is @code{nil}.@item fortran-blink-matching-ifIf this is @code{t}, indenting an @samp{endif} statement moves thecursor momentarily to the matching @samp{if} statement to show where itis. The default is @code{nil}.@item fortran-minimum-statement-indent-fixedMinimum indentation for fortran statements when using fixed formatcontinuation line style. Statement bodies are never indented less thanthis much. The default is 6.@item fortran-minimum-statement-indent-tabMinimum indentation for fortran statements for tab format continuation linestyle. Statement bodies are never indented less than this much. Thedefault is 8.@end table@node Fortran Comments@subsection Fortran Comments The usual Emacs comment commands assume that a comment can follow a lineof code. In Fortran, the standard comment syntax requires an entire lineto be just a comment. Therefore, Fortran mode replaces the standard Emacscomment commands and defines some new variables. Fortran mode can also handle the Fortran90 comment syntax where commentsstart with @samp{!} and can follow other text. Because only some Fortran77compilers accept this syntax, Fortran mode will not insert such commentsunless 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 backinto 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, thisrecognizes any kind of existing comment and aligns its text appropriately;if there is no existing comment, a comment is inserted and aligned. Butinserting and aligning comments are not the same in Fortran mode as inother modes. When a new comment must be inserted, if the current line is blank, afull-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 afull-line comment is inserted on a new line before the current line. Nonstandard @samp{!} comments are aligned like comments in otherlanguages, but full-line comments are different. In a standard full-linecomment, the comment delimiter itself must always appear in column zero.What can be aligned is the text within the comment. You can choose fromthree 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 fixedAlign the text at a fixed column, which is the sum of@code{fortran-comment-line-extra-indent} and the minimum statementindentation. This is the default.The minimum statement indentation is@code{fortran-minimum-statement-indent-fixed} for fixed formatcontinuation line style and @code{fortran-minimum-statement-indent-tab}for tab format style.@item relativeAlign the text as if it were a line of code, but with an additional@code{fortran-comment-line-extra-indent} columns of indentation.@item nilDon'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 withinfull-line comments by setting the variable@code{fortran-comment-indent-char} to the single-character string you wantto use.@vindex fortran-directive-re Compiler directive lines, or preprocessor lines, have much the sameappearance as comment lines. It is important, though, that such linesnever 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 whichlines are directives. Matching lines are never indented, and receivedistinctive 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 sameroles played by @code{comment-start} and @code{comment-start-skip} forordinary text-following comments. Normally these are set properly byFortran mode, so you do not need to change them. The normal Emacs comment command @kbd{C-x ;} has not been redefined. Ifyou use @samp{!} comments, this command can be used with them. Otherwiseit 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 thelines of the region into comments by inserting the string @samp{C$$$} atthe front of each one. With a numeric argument, it turns the regionback into live code by deleting @samp{C$$$} from the front of each linein it. The string used for these comments can be controlled by settingthe variable @code{fortran-comment-region}. Note that here we have anexample of a command and a variable with the same name; these two usesof the name never conflict because in Lisp and in Emacs it is alwaysclear 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 splitsFortran 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}). Thissplitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, andalso in the Fortran indentation commands.@findex fortran-auto-fill-mode @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if itwas off, or off if it was on. This command works the same as @kbd{M-xauto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). Apositive numeric argument turns Fortran Auto Fill mode on, and anegative argument turns it off. You can see when Fortran Auto Fill modeis 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, turnedon 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 thelines 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 bydefault), the break comes before the delimiter. By default, Fortran Auto Fill mode is not enabled. If you want thisfeature turned on permanently, add a hook function to@code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.@xref{Hooks}.@node Fortran Columns@subsection Checking Columns in Fortran@table @kbd@item C-c C-rDisplay a ``column ruler'' momentarily above the current line(@code{fortran-column-ruler}).@item C-c C-wSplit the current window horizontally temporarily so that it is 72columns wide (@code{fortran-window-create-momentarily}). This mayhelp you avoid making lines longer than the 72-character limit thatsome Fortran compilers impose.@item C-u C-c C-wSplit 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-nosDelete 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 columnruler momentarily above the current line. The comment ruler is two linesof text that show you the locations of columns with special significance inFortran programs. Square brackets show the limits of the columns for linenumbers, and curly brackets show the limits of the columns for thestatement 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 familiarwith; but the positions they indicate in the line are standard forFortran.@vindex fortran-column-ruler-fixed@vindex fortran-column-ruler-tabs The text used to display the column ruler depends on the value ofthe 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}) temporarilysplits the current window horizontally, making a window 72 columnswide, so you can see which lines that is too long. Type a space torestore 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 withthe split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-xfortran-window-create}). By editing in this window you canimmediately 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 incolumn 72 and beyond, on all lines in the current buffer. This is theeasiest 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 anddeclarations. These are the same sort of abbrev that you can defineyourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. The built-in abbrevs are unusual in one way: they all start with asemicolon. You cannot normally use semicolon in an abbrev, but Fortranmode makes this possible by changing the syntax of semicolon to ``wordconstituent.'' For example, one built-in Fortran abbrev is @samp{;c} for@samp{continue}. If you insert @samp{;c} and then insert a punctuationcharacter such as a space or a newline, the @samp{;c} expands automaticallyto @samp{continue}, provided Abbrev mode is enabled.@refill Type @samp{;?} or @samp{;C-h} to display a list of all the built-inFortran abbrevs and what they stand for.@node Asm Mode@section Asm Mode@cindex Asm mode@cindex assembler modeAsm mode is a major mode for editing files of assembler code. Itdefines these commands:@table @kbd@item @key{TAB}@code{tab-to-tab-stop}.@item C-jInsert a newline and then indent using @code{tab-to-tab-stop}.@item :Insert a colon and then remove the indentation from before the labelpreceding colon. Then do @code{tab-to-tab-stop}.@item ;Insert or align a comment.@end table The variable @code{asm-comment-char} specifies which characterstarts comments in assembler syntax.@ignore arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0@end ignore