Mercurial > emacs
view man/programs.texi @ 68175:85897d09e200
(org-get-time-of-day): Fixed bug with times before 1am.
author | Carsten Dominik <dominik@science.uva.nl> |
---|---|
date | Fri, 13 Jan 2006 14:17:37 +0000 |
parents | 6fc6fd3c71cd |
children | 60492fe37343 7beb78bc1f8e |
line wrap: on
line source
@c This is part of the Emacs manual. @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, @c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Programs, Building, Text, Top @chapter Editing Programs @cindex Lisp editing @cindex C editing @cindex program editing Emacs provides many features to facilitate editing programs. Some of these features can @itemize @bullet @item Find or move over top-level definitions (@pxref{Defuns}). @item Apply the usual indentation conventions of the language (@pxref{Program Indent}). @item Balance parentheses (@pxref{Parentheses}). @item Insert, kill or align comments (@pxref{Comments}). @item Highlight program syntax (@pxref{Font Lock}). @end itemize This chapter describes these features and many more. @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. * Parentheses:: Commands that operate on parentheses. * Comments:: Inserting, killing, and aligning comments. * 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 typically specifies the syntax of expressions, the customary rules for indentation, how to do syntax highlighting for the language, and how to find the beginning of a function definition. It often customizes or provides facilities for compiling and debugging programs as well. Ideally, Emacs should provide a major mode for each programming language that you might want to edit; if it doesn't have a mode for your favorite language, you can contribute one. But often the mode for 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 Makefile mode @cindex Tcl mode @cindex CPerl mode @cindex DSSSL mode @cindex Octave mode @cindex Metafont mode @cindex Modula2 mode @cindex Prolog mode @cindex Python mode @cindex Simula mode @cindex VHDL mode @cindex M4 mode @cindex Shell-script mode @cindex Delphi mode @cindex PostScript mode @cindex Conf mode @cindex DNS mode The existing programming language major modes include Lisp, Scheme (a variant of Lisp) and the Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s companion for font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An alternative mode for Perl is called CPerl mode. Modes are available for the scripting languages of the common GNU and Unix shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for editing makefiles, DNS master files, and various sorts of configuration files. @kindex DEL @r{(programming modes)} @findex c-electric-backspace In most programming languages, indentation should vary from line to line to illustrate the structure of the program. So the major modes for programming languages arrange for @key{TAB} to update the indentation of the current line. They also rebind @key{DEL} to treat a tab as if it were the equivalent number of spaces; this lets you delete one column of indentation without worrying whether the whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point, in these modes. Separate manuals are available for the modes for Ada (@pxref{Top, , Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK (@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{mode hook}, which is the value of a Lisp variable. Each major mode has a mode hook, and the hook's name is always made from the mode command's name by adding @samp{-hook}. For example, turning on C mode runs the hook @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 a place 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, something like a function, is called a @dfn{defun}. The name comes from Lisp, but in Emacs we use it for all languages. In many programming language modes, Emacs assumes that a defun is any pair of parentheses (or braces, if the language uses braces this way) that starts at the left margin. For example, in C, the body of a function definition is a defun, usually recognized as an open-brace that begins at the left margin@footnote{Alternatively, you can set up C Mode to recognize a defun at an opening brace at the outermost level. @xref{Movement Commands,,, ccmode, the CC Mode Manual}.}. A variable's initializer can also count as a defun, if the open-brace that begins the initializer is at the left margin. However, some language modes provide their own code for recognizing defuns 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 Emacs assumes by default that any opening delimiter found at the left margin is the start of a top-level definition, or defun. You can override this default by setting this user option: @defvar open-paren-in-column-0-is-defun-start If this user option is set to @code{t} (the default), opening parentheses or braces at column zero always start defuns. When it's @code{nil}, defuns are found by searching for parens or braces at the outermost level. Some major modes, including C and related modes, set @code{open-paren-in-column-0-is-defun-start} buffer-locally to @code{nil} @end defvar In modes where @code{open-paren-in-column-0-is-defun-start} is @code{t}, @strong{don't put an opening delimiter at the left margin unless it is a defun start}. For instance, never put an open-parenthesis at the left margin in a Lisp file unless it is the start of a top-level list. If you don't follow this convention, not only will you have trouble when you explicitly use the commands for motion by defuns; other features that use them will also give you trouble. This includes the indentation commands (@pxref{Program Indent}) and Font Lock mode (@pxref{Font Lock}). The most likely problem case is when you want an opening delimiter at the start of a line inside a string. To avoid trouble, put an escape character (@samp{\}, in Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening delimiter. This will not affect the contents of the string, but will prevent that opening delimiter from starting a defun. Here's an example: @example (insert "Foo: \(bar) ") @end example To help you catch violations of this convention, Font Lock mode highlights confusing opening delimiters (those that ought to be quoted) in bold red. In the earliest days, the original Emacs found defuns by moving upward a level of parentheses or braces until there were no more levels to go up. This always required scanning all the way back to the beginning of the buffer, even for a small function. To speed up the operation, we changed Emacs to assume that any opening delimiter at the left margin is the start of a defun. This heuristic is nearly always right, and avoids the need to scan back to the beginning of the buffer. However, now that modern computers are so powerful, this scanning is rarely slow enough to annoy, so we've provided a way to disable the heuristic. @node Moving by Defuns @subsection Moving by Defuns @cindex defuns These commands move point or set up the region based on top-level major definitions, also called @dfn{defuns}. @table @kbd @item C-M-a Move to beginning of current or preceding defun (@code{beginning-of-defun}). @item C-M-e Move to end of current or following defun (@code{end-of-defun}). @item C-M-h Put 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 defun are @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 a positive numeric argument, each repetition moves to the next defun in the 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 exactly the 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 the beginning of the following defun. (Whitespace, comments, and perhaps declarations can separate them.) Likewise, @kbd{C-M-e} with a negative argument moves back to an end of a defun, which is not quite the 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 current defun. This is the easiest way to get ready to kill the defun in order to move it to a different place in the file. If you use the command while point is between defuns, it uses the following defun. Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode when the mark is active, includes an additional defun in the region each time. 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 that it backs up over the argument declarations, function name and returned data type so that the entire C function is inside the region. This is an example of how major modes adjust the standard key bindings so that they do their standard jobs in a way better fitting a particular language. Other major modes may replace any or all of these key bindings 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 in a 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 files together.) @findex imenu If you type @kbd{M-x imenu}, it reads the name of a definition using the minibuffer, then moves point to that definition. You can use completion to specify the name; the command always displays the whole list of valid names. @findex imenu-add-menubar-index Alternatively, you can bind the command @code{imenu} to a mouse click. Then it displays mouse menus for you to select a definition name. 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 bar item available for all buffers in a certain major mode, you can do this by adding @code{imenu-add-menubar-index} to its mode hook. But if you have done that, you will have to wait each time you visit a file in that mode, while Emacs finds all the definitions in that buffer. @vindex imenu-auto-rescan When you change the contents of a buffer, if you add or delete definitions, you can update the buffer's index based on the new contents by invoking the @samp{*Rescan*} item in the menu. Rescanning happens automatically if you set @code{imenu-auto-rescan} to a non-@code{nil} value. There is no need to rescan because of small changes in the text. @vindex imenu-sort-function You can customize the way the menus are sorted by setting the variable @code{imenu-sort-function}. By default, names are ordered as they occur in the buffer; if you want alphabetic sorting, use the symbol @code{imenu--sort-by-name} as the value. You can also define 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 iftex The 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 current function name in the mode line, updating it as you move around in a buffer. @findex which-function-mode @vindex which-func-modes To enable (or disable) Which Function mode, use the command @kbd{M-x which-function-mode}. This command is global; it applies to all buffers, both existing ones and those yet to be created. However, it takes effect only in certain major modes, those listed in the value of @code{which-func-modes}. If the value is @code{t}, then Which Function mode applies to all major modes that know how to support it---in other words, all the major modes that support Imenu. @node Program Indent @section Indentation for Programs @cindex indentation for programs The best way to keep a program properly indented is to use Emacs to reindent it as you change it. Emacs has commands to indent properly either a single line, a specified number of lines, or all of the lines inside 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 the usual conventions of the language you are editing. @table @kbd @item @key{TAB} Adjust indentation of current line. @item C-j Equivalent 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 line the correct indentation as determined from the previous lines. The function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line} in Lisp mode, @code{c-indent-command} in C mode, etc. These functions understand the syntax and conventions of different languages, but they all do conceptually the same job: @key{TAB} in any programming-language major mode inserts or deletes whitespace at the beginning of the current line, independent of where point is in the line. If point was inside the whitespace at the beginning of the line, @key{TAB} puts it at the end of that whitespace; otherwise, @key{TAB} keeps point fixed with respect to the characters around it. Use @kbd{C-q @key{TAB}} to insert a tab character 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 a blank line and then gives it the appropriate indentation. @key{TAB} indents a line that starts within a parenthetical grouping under the preceding line within the grouping, or the text after the parenthesis. Therefore, if you manually give one of these lines a nonstandard indentation, the lines below will tend to follow it. This behavior is convenient in cases where you have overridden the standard result of @key{TAB} because you find it unaesthetic for a particular line. By default, an open-parenthesis, open-brace or other opening delimiter at the left margin is assumed by Emacs (including the indentation routines) to be the start of a function. This speeds up indentation commands. If you will be editing text which contains opening delimiters in column zero that aren't the beginning of a functions, even inside strings or comments, you must set @code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin Paren}, for more information on this. Normally, lines are indented with tabs and spaces. If you want Emacs to 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 been altered or moved to a different level in the parenthesis structure, you have several commands available. @table @kbd @item C-M-q Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}). @item C-M-\ Reindent all lines in the region (@code{indent-region}). @item C-u @key{TAB} Shift an entire parenthetical grouping rigidly sideways so that its first line is properly indented. @item M-x indent-code-rigidly Shift all the lines in the region rigidly sideways, but do not alter lines that start inside comments and strings. @end table @kindex C-M-q @findex indent-pp-sexp You can reindent the contents of a single parenthetical grouping by positioning point before the beginning of it and typing @kbd{C-M-q} (@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable commands in other modes). The indentation of the line where the grouping starts is not changed; therefore this changes only the relative indentation within the grouping, not its overall indentation. To correct that as well, type @key{TAB} first. Another way to specify the range to be reindented is with the region. The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line whose first character is between point and mark. @kindex C-u TAB If you like the relative indentation within a grouping, but not the indentation of its first line, you can type @kbd{C-u @key{TAB}} to reindent the whole grouping as a rigid unit. (This works in Lisp modes and C and related modes.) @key{TAB} with a numeric argument reindents the current line as usual, then reindents by the same amount all the lines in the parenthetical grouping starting on the current line. It is clever, though, and does not alter lines that start inside strings. Neither does it alter C preprocessor lines when in C mode, but it does reindent any continuation lines that may be attached to them. @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 the region sideways, like @code{indent-rigidly} does (@pxref{Indentation Commands}). It doesn't alter the indentation of lines that start inside a string, unless the region also starts inside that string. The prefix arg specifies the number of columns to indent. @node Lisp Indent @subsection Customizing Lisp Indentation @cindex customizing Lisp indentation The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program. The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under 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 overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented @code{lisp-indent-offset} more columns than the containing list. @vindex lisp-body-indent Certain functions override the standard pattern. Functions whose names start with @code{def} treat the second lines as the start of a @dfn{body}, by indenting the second line @code{lisp-body-indent} additional columns beyond the open-parenthesis that starts the expression. @cindex @code{lisp-indent-function} property You can override the standard pattern in various ways for individual functions, according to the @code{lisp-indent-function} property of the function name. Normally you would use this for macro definitions and specify it using the @code{declare} construct (@pxref{Defining Macros,,, 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-defun Reindent the current top-level function definition or aggregate type declaration (@code{c-indent-defun}). @item C-M-q @kindex C-M-q @r{(C mode)} @findex c-indent-exp Reindent each line in the balanced expression that follows point (@code{c-indent-exp}). A prefix argument inhibits warning messages about invalid syntax. @item @key{TAB} @findex c-indent-command Reindent the current line, and/or in some cases insert a tab character (@code{c-indent-command}). @vindex c-tab-always-indent If @code{c-tab-always-indent} is @code{t}, this command always reindents the current line and does nothing else. This is the default. If that variable is @code{nil}, this command reindents the current line only 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 the line, and also insert a tab if within a comment or a string. @end table To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This first selects the whole buffer as the region, then reindents that region. To reindent the current block, use @kbd{C-M-u C-M-q}. This moves to 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 flexible mechanism for customizing indentation. C mode indents a source line in two steps: first it classifies the line syntactically according to its contents and context; second, it determines the indentation offset associated by your selected @dfn{style} with the syntactic construct and adds this onto the indentation of the @dfn{anchor statement}. @table @kbd @item C-c . @key{RET} @var{style} @key{RET} Select a predefined style @var{style} (@code{c-set-style}). @end table A @dfn{style} is a named collection of customizations that can be used in C mode and the related modes. @ref{Styles,,, ccmode, The CC Mode Manual}, for a complete description. Emacs comes with several predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup}, @code{linux}, @code{python}, @code{java}, @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these styles are primarily intended for one language, but any of them can be used with any of the languages supported by these modes. To find out what a style looks like, select it and reindent some code, e.g., by typing @key{C-M-q} at the start of a function definition. @kindex C-c . @r{(C mode)} @findex c-set-style To choose a style for the current buffer, use the command @kbd{C-c .}. Specify a style name as an argument (case is not significant). This command affects the current buffer only, and it affects only future invocations of the indentation commands; it does not reindent the code already in the buffer. To reindent the whole buffer in the 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 the default style for various major modes. Its value should be either the style's name (a string) or an alist, in which each element specifies one major mode and which indentation style to use for it. For example, @example (setq c-default-style '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) @end example @noindent specifies explicit choices for Java and AWK modes, and the default @samp{gnu} style for the other C-like modes. (These settings are actually the defaults.) This variable takes effect when you select one of the C-like major modes; thus, if you specify a new default style for Java mode, you can make it take effect in an existing Java mode buffer by typing @kbd{M-x java-mode} there. The @code{gnu} style specifies the formatting recommended by the GNU Project for C; it is the default, so as to encourage use of our recommended style. @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more information on customizing indentation for C and related modes, including how to override parts of an existing style and how to define your 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 advantage of the parenthesis structure in a program, or help you keep it balanced. When talking about these facilities, the term ``parenthesis'' also includes braces, brackets, or whatever delimiters are defined to match in pairs. The major mode controls which delimiters are significant, through the syntax table (@pxref{Syntax}). In Lisp, only parentheses count; in C, these commands apply to braces and brackets too. You can use @kbd{M-x check-parens} to find any unbalanced parentheses 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 an expression in Lisp.}. @table @kbd @item C-M-f Move forward over a balanced expression (@code{forward-sexp}). @item C-M-b Move backward over a balanced expression (@code{backward-sexp}). @item C-M-k Kill balanced expression forward (@code{kill-sexp}). @item C-M-t Transpose expressions (@code{transpose-sexps}). @item C-M-@@ @itemx C-M-@key{SPC} Put mark after following expression (@code{mark-sexp}). @end table Each programming language major mode customizes the definition of balanced expressions to suit that language. Balanced expressions typically include symbols, numbers, and string constants, as well as any pair of matching delimiters and their contents. Some languages have obscure forms of expression syntax that nobody has bothered to implement in Emacs. @cindex Control-Meta By convention, the keys for these commands are all Control-Meta characters. They usually act on expressions just as the corresponding Meta characters act on words. For instance, the command @kbd{C-M-b} moves backward over a balanced expression, just as @kbd{M-b} moves back 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 point is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f} moves past the matching closing delimiter. 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 a balanced expression. The detailed rules are like those above for @kbd{C-M-f}, but with directions reversed. If there are prefix characters (single-quote, backquote and comma, in Lisp) preceding the expression, @kbd{C-M-b} moves back over them as well. The balanced expression 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 the specified number of times; with a negative argument, it moves in the opposite 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 previous balanced expression across the next one. An argument serves as a repeat count, moving the previous expression over that many following ones. A negative argument drags the previous balanced expression backwards across those before it (thus canceling out the effect of @kbd{C-M-t} with a positive argument). An argument of zero, rather than doing nothing, transposes the balanced expressions ending at or after point and the mark. @kindex C-M-@@ @kindex C-M-@key{SPC} @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 place that @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 putting the mark at the beginning of the previous balanced expression. The alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you repeat this command, or use it in Transient Mark mode when the mark is active, it extends the region by one sexp each time. In languages that use infix operators, such as C, it is not possible to recognize all balanced expressions as such because there can be multiple possibilities at a given position. For example, C mode does not treat @samp{foo + bar} as a single expression, even though it @emph{is} one C expression; instead, it recognizes @samp{foo} as one expression and @samp{bar} as another, with the @samp{+} as punctuation between them. Both @samp{foo + bar} and @samp{foo} are legitimate choices for ``the expression following point'' when point is at the @samp{f}, so the expression commands must perforce choose one or the other to operate on. Note that @samp{(foo + bar)} is recognized as a single 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 nothing except parentheses (or whatever characters must balance in the language you are working with), and the escape characters that might be used to quote those. They are mainly intended for editing programs, but can be useful for editing any text that has parentheses. They are sometimes called ``list'' commands because in Lisp these groupings are lists. @table @kbd @item C-M-n Move forward over a parenthetical group (@code{forward-list}). @item C-M-p Move backward over a parenthetical group (@code{backward-list}). @item C-M-u Move up in parenthesis structure (@code{backward-up-list}). @item C-M-d Move down in parenthesis structure (@code{down-list}). @end table @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 text that 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 the parenthesis 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 up past one unmatched opening delimiter. A positive argument serves as a repeat count; a negative argument reverses the direction of motion, so that 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 opening delimiter, this is nearly the same as searching for a @samp{(}. An argument 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 show automatically how parentheses (and other matching delimiters) match in the text. Whenever you type a self-inserting character that is a closing delimiter, the cursor moves momentarily to the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, Emacs displays some of the text near it in the echo area. Either way, you can tell which grouping you are closing off. If the opening delimiter and closing delimiter are mismatched---such as in @samp{[x)}---a warning message is displayed in the echo area. @vindex blink-matching-paren @vindex blink-matching-paren-distance @vindex blink-matching-delay Three variables control parenthesis match display: @code{blink-matching-paren} turns the feature on or off: @code{nil} disables it, but the default is @code{t} to enable match display. @code{blink-matching-delay} says how many seconds to leave the cursor on the matching opening delimiter, before bringing it back to the real location of point; the default is 1, but on some systems it is useful to specify a fraction of a second. @code{blink-matching-paren-distance} specifies how many characters back to search to find the matching opening delimiter. If the match is not found in that distance, scanning stops, and nothing is displayed. This is to prevent the scan for the matching delimiter from wasting lots 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 its matching opening delimiter are both highlighted; otherwise, if point is before an opening delimiter, the matching closing delimiter is highlighted. (There is no need to highlight the opening delimiter in that case, because the cursor appears on top of that character.) Use the command @kbd{M-x show-paren-mode} to enable or disable this mode. By default, @code{show-paren-mode} uses colors to highlight the parentheses. However, if your display doesn't support colors, you can customize the faces @code{show-paren-match-face} and @code{show-paren-mismatch-face} to use other attributes, such as bold or underline. @xref{Face Customization}. @node Comments @section Manipulating Comments @cindex comments Because comments are such an important part of programming, Emacs provides special commands for editing and inserting comments. It can also 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 @asis @item @kbd{M-;} Insert or realign comment on current line; alternatively, comment or uncomment the region (@code{comment-dwim}). @item @kbd{C-u M-;} Kill comment on current line (@code{comment-kill}). @item @kbd{C-x ;} Set comment column (@code{comment-set-column}). @item @kbd{C-M-j} @itemx @kbd{M-j} Like @key{RET} followed by inserting and aligning a comment (@code{comment-indent-new-line}). @xref{Multi-Line Comments}. @item @kbd{M-x comment-region} @itemx @kbd{C-c C-c} (in C-like modes) Add 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 What I Mean''; it indicates that this command can be used for many different jobs relating to comments, depending on the situation where you use it. If there is no comment already on the line, @kbd{M-;} inserts a new comment, aligned at a specific column called the @dfn{comment column}. The new comment begins with the string Emacs thinks comments should start with (the value of @code{comment-start}; see below). Point is after that string, so you can insert the text of the comment right away. 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 the comment start string is indented to a suitable boundary (usually, at least one space is inserted). You can also use @kbd{M-;} to align an existing comment. If a line already contains the comment-start string, @kbd{M-;} reindents it to the conventional alignment and moves point after it. (Exception: comments starting in column 0 are not moved.) Even when an existing comment is properly aligned, @kbd{M-;} is still useful for moving directly 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 the whitespace before it. To reinsert the comment on another line, move to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to realign 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 is programmed so that when it receives a prefix argument it calls @code{comment-kill}. However, @code{comment-kill} is a valid command in 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 in Transient Mark mode (@pxref{Transient Mark}). Then it either adds or removes comment delimiters on each line of the region. (If every line is a comment, it removes comment delimiters from each; otherwise, it adds comment delimiters to each.) If you are not using Transient Mark mode, 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 many comment delimiters to add or how many to delete. Some major modes have special rules for indenting certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin. Emacs understands these 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 For C-like buffers, you can configure the exact effect of @kbd{M-;} more flexibly than for most buffers by setting the user options @code{c-indent-comment-alist} and @code{c-indent-comments-syntactically-p}. For example, on a line ending in a closing brace, @kbd{M-;} puts the comment one space after the brace rather than at @code{comment-column}. For full details see @ref{Comment Commands,,, ccmode, The CC Mode Manual}. @node Multi-Line Comments @subsection Multiple Lines of Comments @kindex C-M-j @kindex 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} or @kbd{M-j} (@code{comment-indent-new-line}). If @code{comment-multi-line} (@pxref{Options for Comments}) is non-@code{nil}, it moves to a new line within the comment. Otherwise it closes the comment and starts a new comment on a new line. When Auto Fill mode is on, going past the fill column while typing a comment causes the comment to be continued in just this fashion. @kindex C-c C-c (C mode) @findex comment-region To turn existing lines into comment lines, use the @kbd{M-x comment-region} command (or type @kbd{C-c C-c} in C-like buffers). It adds comment delimiters to the lines that start in the region, thus commenting them out. With a negative argument, it does the opposite---it deletes comment delimiters from the lines in the region. With a positive argument, @code{comment-region} duplicates the last character of the comment start sequence it adds; the argument specifies how many copies of the character to insert. Thus, in Lisp mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating the comment delimiter is a way of calling attention to the comment. It can also affect how the comment is indented. In Lisp, for proper indentation, you should use an argument of two or three, if between defuns; if within a defun, it must be three. You can configure C Mode such that when you type a @samp{/} at the start of a line in a multi-line block comment, this closes the comment. Enable the @code{comment-close-slash} clean-up for this. @xref{Clean-ups,,, ccmode, The CC Mode Manual}. @node Options for Comments @subsection Options Controlling Comments @vindex comment-column @kindex C-x ; @findex comment-set-column The @dfn{comment column}, the column at which Emacs tries to place comments, is stored in the variable @code{comment-column}. You can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} (@code{comment-set-column}) sets the comment column to the column point is at. @kbd{C-u C-x ;} sets the comment column to match the last comment before point in the buffer, and then does a @kbd{M-;} to align the current line's comment under the previous one. The variable @code{comment-column} is per-buffer: setting the variable in the normal fashion affects only the current buffer, but there is a default value which you can change with @code{setq-default}. @xref{Locals}. Many major modes initialize this variable for the current buffer. @vindex comment-start-skip The comment commands recognize comments based on the regular expression that is the value of the variable @code{comment-start-skip}. Make sure this regexp does not match the null string. It may match more than 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 spaces after the @samp{/*} itself, and accepts C++ style comments also. (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in the string, which is needed to deny the first star its special meaning in regexp syntax. @xref{Regexp Backslash}.) @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} is inserted after point, so that it will follow the text that you will insert into the comment. When @code{comment-end} is non-empty, it should start with a space. For example, 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 the comment delimiter and the line's original text. The default is 1, to insert one space. @code{nil} means 0. Alternatively, @code{comment-padding} can hold the actual string to insert. @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. Specifically, when @code{comment-multi-line} is @code{nil}, the command inserts a comment terminator, begins a new line, and finally inserts a comment starter. Otherwise it does not insert the terminator and starter, so it effectively continues the current comment across multiple lines. In languages that allow multi-line comments, the choice of value for this variable is a matter of taste. The default for this variable depends on the major mode. @vindex comment-indent-function The variable @code{comment-indent-function} should contain a function that will be called to compute the indentation for a newly inserted comment or for aligning an existing comment. It is set differently by various major modes. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. It should return the column in which the comment ought to start. For example, in Lisp mode, the indent hook function bases its decision on how many semicolons begin an existing comment, and on the code in the preceding lines. @node Documentation @section Documentation Lookup Emacs provides several features you can use to look up the documentation of functions, variables and commands that you plan to use 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 S For C, Lisp, and other languages that have documentation in Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the Info documentation for a symbol used in the program. You specify the symbol with the minibuffer; the default is the symbol appearing in the buffer at point. For example, in C mode this looks for the symbol in the C Library Manual. The major mode determines where to look for documentation for the symbol---which Info files to look in, and which indices to search. You can also use @kbd{M-x info-lookup-file} to look for documentation for 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 are typically 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{manual page} or @dfn{man page}. In the GNU operating system, we hope to replace man pages with better-organized manuals that you can browse with Info (@pxref{Misc Help}). This process is not finished, so it is still useful to read manual pages. @findex manual-entry You can read the man page for an operating system command, library function, or system call, with the @kbd{M-x man} command. It runs the @code{man} program to format the man page; if the system permits, it runs @code{man} asynchronously, so that you can keep on editing while the page is being formatted. (On MS-DOS and MS-Windows 3, you cannot edit while Emacs waits for @code{man} to finish.) The result goes in a buffer named @samp{*Man @var{topic}*}. These buffers use a special major mode, Man mode, that facilitates scrolling and jumping to other manual pages. For details, type @kbd{C-h m} while in a man page buffer. @cindex sections of manual pages Each man page belongs to one of ten or more @dfn{sections}, each named by a digit or by a digit and a letter. Sometimes there are multiple man pages with the same name in different sections. To read a 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, to read the man page for the C library function @code{chmod} (as opposed to 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 in section @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 only the first man page they find. Others display all man pages that have the 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} program accepts a @samp{-a} command-line option which tells it to display all the man pages for the specified topic. If you want this behavior, you can 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 man page, highlighting can take substantial time. You can turn off highlighting 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 some other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to perform 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 acronym for ``w/o (without) man,'' since it doesn't use the @code{man} program.}. Unlike @kbd{M-x man}, it does not run any external programs to format and display the man pages; instead it does the job in Emacs Lisp, so it works on systems such as MS-Windows, where the @code{man} program (and other programs it uses) are not generally available. @kbd{M-x woman} prompts for a name of a manual page, and provides completion based on the list of manual pages that are installed on your machine; the list of available manual pages is computed automatically the first time you invoke @code{woman}. The word at point in the current buffer is used to suggest the default for the name the manual page. With a numeric argument, @kbd{M-x woman} recomputes the list of the manual pages used for completion. This is useful if you add or delete manual pages. If you type a name of a manual page and @kbd{M-x woman} finds that several manual pages by the same name exist in different sections, it pops up a window with possible candidates asking you to choose one of them. @vindex woman-manpath By default, @kbd{M-x woman} looks for manual pages in the directories 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 for subdirectories that match the shell wildcard pattern @file{man*} in each one of these directories, and tries to find the manual pages in those subdirectories. When first invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list of directory names and stores that list in the @code{woman-manpath} variable. Changing the value of this variable 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 in any of the directories listed by @code{woman-manpath} and @code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a name of a manual page file, with completion, and then formats and displays 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 current line'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} on the 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 WoMan Manual}. @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 and variables that you want to use. These commands use the minibuffer to read the name of a function or variable to document, and display the documentation in a window. Their default arguments are based on the code in the neighborhood of point. For @kbd{C-h f}, the default is the function called in the innermost list containing point. @kbd{C-h v} 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 minor mode constantly displays in the echo area the argument list for the function being called at point. (In other words, it finds the function call that point is contained in, and displays the argument list of that function.) If point is over a documented variable, it shows the first line of the variable's docstring. Eldoc mode applies in Emacs Lisp and Lisp Interaction modes, and perhaps a few others that provide special support for looking up doc strings. Use the command @kbd{M-x eldoc-mode} to enable or disable this feature. @node Hideshow @section Hideshow minor mode @findex hs-minor-mode Hideshow minor mode provides selective display of portions of a program, 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 the mode hook for certain major modes in order to enable it automatically for those modes. Just what constitutes a block depends on the major mode. In C mode or C++ mode, they are delimited by braces, while in Lisp mode and similar modes they are delimited by parentheses. Multi-line comments also 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-h Hide the current block (@code{hs-hide-block}). @item C-c @@ C-s Show the current block (@code{hs-show-block}). @item C-c @@ C-c Either hide or show the current block (@code{hs-toggle-hiding}). @item S-Mouse-2 Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). @item C-c @@ C-M-h Hide all top-level blocks (@code{hs-hide-all}). @item C-c @@ C-M-s Show everything in the buffer (@code{hs-show-all}). @item C-c @@ C-l Hide 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 variables exist for customizing Hideshow mode. @table @code @item hs-hide-comments-when-hiding-all Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. @item hs-isearch-open Specifies what kind of hidden blocks to open in Isearch mode. The value should be one of these four symbols: @table @code @item code Open only code blocks. @item comment Open only comments. @item t Open both code blocks and comments. @item nil Open neither code blocks nor comments. @end table @item hs-special-modes-alist A list of elements, each specifying how to initialize Hideshow variables for one major mode. See the variable's documentation string for 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 for symbol names. @kindex M-TAB The character @kbd{M-@key{TAB}} runs a command to complete the partial symbol before point against the set of meaningful symbol names. This command inserts at point any additional characters that it can determine from the partial name. (If your window manager defines @kbd{M-@key{TAB}} to switch windows, you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) If the partial name in the buffer has multiple possible completions that differ in the very next character, so that it is impossible to complete even one more character, @kbd{M-@key{TAB}} displays a list of all 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 the command @code{complete-symbol}, which provides two kinds of completion. Normally it does completion based on a tags table (@pxref{Tags}); with a numeric argument (regardless of the value), it does completion based on the names listed in the Info file indexes for your language. Thus, to complete the name of a symbol defined in your own program, use @kbd{M-@key{TAB}} with no argument; to complete the name of a standard library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based completion works only if there is an Info file for the standard library functions 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 of nontrivial symbols present in Emacs---those that have function definitions, values or properties. However, if there is an open-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 words based 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 different ways to do this: by displaying underscores between a lower-case letter and the following capital letter, and by emboldening the capital letters. It does not alter the buffer text, only the way they display, so you can use it even on read-only buffers. You can use the command @kbd{M-x glasses-mode} to enable or disable the mode in the current buffer; you can also add @code{glasses-mode} to the mode hook of the programming language major modes in which you normally want to use Glasses mode. @node Misc for Programs @section Other Features Useful for Editing Programs A number of Emacs commands that aren't designed specifically for editing programs are useful for that nonetheless. The Emacs commands that operate on words, sentences and paragraphs are 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 in program code (in long comments), but the paragraph commands are useful in other places too, because programming language major modes define paragraphs to begin and end at blank lines (@pxref{Paragraphs}). Judicious use of blank lines to make the program clearer will also provide 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 overall structure of a function (@pxref{Selective Display}). This feature hides the lines that are indented more than a specified amount. Programming modes often support Outline minor mode (@pxref{Outline Mode}). 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 AWK mode @cindex mode, Java @cindex mode, C @cindex mode, C++ @cindex mode, Objective C @cindex mode, CORBA IDL @cindex mode, Pike @cindex mode, AWK This section gives a brief description of the special features available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. (These are called ``C mode and related modes.'') @xref{Top, , CC Mode, ccmode, CC Mode}, for a more extensive description of these modes and 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. @end menu @node Motion in C @subsection C Mode Motion Commands This section describes commands for moving point, in C mode and related modes. @table @code @item M-x c-beginning-of-defun @itemx M-x c-end-of-defun @findex c-beginning-of-defun @findex c-end-of-defun Move point to the beginning or end of the current function or top-level definition. These are found by searching for the least enclosing braces. (By contrast, @code{beginning-of-defun} and @code{end-of-defun} search for braces in column zero.) If you are editing code where the opening brace of a function isn't placed in column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to these commands. @xref{Moving by Defuns}. @item C-c C-u @kindex C-c C-u @r{(C mode)} @findex c-up-conditional Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing preprocessor conditional. @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so the function will stop at a @samp{#elif} when going backward, but not when going forward. @item C-c C-p @kindex C-c C-p @r{(C mode)} @findex c-backward-conditional Move point back over a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward. @item C-c C-n @kindex C-c C-n @r{(C mode)} @findex c-forward-conditional Move point forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward. @item M-a @kindex M-a (C mode) @findex c-beginning-of-statement Move point to the beginning of the innermost C statement (@code{c-beginning-of-statement}). If point is already at the beginning of a statement, move to the beginning of the preceding statement. With prefix argument @var{n}, move back @var{n} @minus{} 1 statements. In comments or in strings which span more than one line, this command moves by sentences instead of statements. @item M-e @kindex M-e (C mode) @findex c-end-of-statement Move point to the end of the innermost C statement or sentence; 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-nomenclature Move point backward to beginning of a C++ nomenclature section or word. With prefix argument @var{n}, move @var{n} times. If @var{n} is negative, move forward. C++ nomenclature means a symbol name in the style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter begins a section or word. Rather than this command, you might well prefer the newer ``Subword Mode'', which does the same thing better. @xref{Other C Commands}. In the GNU project, we recommend using underscores to separate words within an identifier in C or C++, rather than using case distinctions. @item M-x c-forward-into-nomenclature @findex c-forward-into-nomenclature Move 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 @dfn{electric}---in addition to inserting themselves, they also reindent the current line, and optionally also insert newlines. The ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. You might find electric indentation inconvenient if you are editing chaotically indented code. If you are new to CC Mode, you might find it disconcerting. You can toggle electric action with the command @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line after the mode name: @table @kbd @item C-c C-l @kindex C-c C-l @r{(C mode)} @findex c-toggle-electric-state Toggle electric action (@code{c-toggle-electric-state}). With a prefix argument, this command enables electric action if the argument is positive, disables it if it is negative. @end table Electric characters insert newlines only when, in addition to the electric state, the @dfn{auto-newline} feature is enabled (indicated by @samp{/la} in the mode line after the mode name). You can turn this feature on or off with the command @kbd{C-c C-a}: @table @kbd @item C-c C-a @kindex C-c C-a @r{(C mode)} @findex c-toggle-auto-newline Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a prefix argument, this command turns the auto-newline feature on if the argument is positive, and off if it is negative. @end table Usually the CC Mode style configures the exact circumstances in which Emacs inserts auto-newlines. You can also configure this directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. @node Hungry Delete @subsection Hungry Delete Feature in C @cindex hungry deletion (C Mode) If you want to delete an entire block of whitespace at point, you can use @dfn{hungry deletion}. This deletes all the contiguous whitespace either before point or after point in a single operation. @dfn{Whitespace} here includes tabs and newlines, but not comments or preprocessor commands. @table @kbd @item C-c C-@key{BS} @itemx C-c @key{BS} @findex c-hungry-backspace @kindex C-c C-@key{BS} (C Mode) @kindex C-c @key{BS} (C Mode) @code{c-hungry-backspace}---Delete the entire block of whitespace preceding point. @item C-c C-d @itemx C-c C-@key{DEL} @itemx C-c @key{DEL} @findex c-hungry-delete-forward @kindex C-c C-d (C Mode) @kindex C-c C-@key{DEL} (C Mode) @kindex C-c @key{DEL} (C Mode) @code{c-hungry-delete-forward}---Delete the entire block of whitespace following point. @end table As an alternative to the above commands, you can enable @dfn{hungry delete mode}. When this feature is enabled (indicated by @samp{/h} in the mode line after the mode name), a single @key{BS} command deletes all preceding whitespace, not just one space, and a single @kbd{C-c C-d} (but @emph{not} @key{delete}) deletes all following whitespace. @table @kbd @item M-x c-toggle-hungry-state @findex c-toggle-hungry-state Toggle the hungry-delete feature (@code{c-toggle-hungry-state})@footnote{This command had the binding @kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now bound to @code{c-hungry-delete-forward}.}. With a prefix argument, this command turns the hungry-delete feature on if the argument is positive, and off if it is negative. @end table @vindex c-hungry-delete-key The variable @code{c-hungry-delete-key} controls whether the hungry-delete feature is enabled. @node Other C Commands @subsection Other Commands for C Mode @table @kbd @item C-c C-w @itemx M-x c-subword-mode @findex c-subword-mode Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word commands then recognize upper case letters in @samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by the flag @samp{/w} on the mode line after the mode name (e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in non-CC Mode buffers. @item M-x c-context-line-break @findex c-context-line-break This command inserts a line break and indents the new line in a manner appropriate to the context. In normal code, it does the work of @kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it additionally inserts a @samp{\} at the line break, and within comments it's like @kbd{M-j} (@code{c-indent-new-comment-line}). @code{c-context-line-break} isn't bound to a key by default, but it needs a binding to be useful. The following code will bind it to @kbd{C-j}. We use @code{c-initialization-hook} here to make sure the keymap is loaded before we try to change it. @example (defun my-bind-clb () (define-key c-mode-base-map "\C-j" 'c-context-line-break)) (add-hook 'c-initialization-hook 'my-bind-clb) @end example @item C-M-h Put mark at the end of a function definition, and put point at the beginning (@code{c-mark-function}). @item M-q @kindex M-q @r{(C mode)} @findex c-fill-paragraph Fill 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, this command 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 also included in preprocessing, for the sake of macros defined there, but the output from this part isn't shown. When you are debugging C code that uses macros, sometimes it is hard to figure out precisely how the macros expand. With this command, you don'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 the region (@code{c-backslash-region}). This is useful after writing or editing a C macro definition. If a line already ends in @samp{\}, this command adjusts the amount of whitespace before it. Otherwise, it inserts a new @samp{\}. However, the last line in the region is treated specially; no @samp{\} is inserted on that line, and any @samp{\} there is deleted. @item M-x cpp-highlight-buffer @cindex preprocessor highlighting @findex cpp-highlight-buffer Highlight parts of the text according to its preprocessor conditionals. This command displays another buffer named @samp{*CPP Edit*}, which serves as a graphic menu for selecting how to display particular kinds of 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 information directs how the line is indented. @item M-x cwarn-mode @itemx M-x global-cwarn-mode @findex cwarn-mode @findex global-cwarn-mode @vindex global-cwarn-mode @cindex CWarn mode @cindex suspicious constructions in C, C++ CWarn minor mode highlights certain suspicious C and C++ constructions: @itemize @bullet{} @item Assignments inside expressions. @item Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} (except after a @samp{do @dots{} while} statement); @item C++ functions with reference parameters. @end itemize @noindent You can enable the mode for one buffer with the command @kbd{M-x cwarn-mode}, or for all suitable buffers with the command @kbd{M-x global-cwarn-mode} or by customizing the variable @code{global-cwarn-mode}. You must also enable Font Lock mode to make it work. @item M-x hide-ifdef-mode @findex hide-ifdef-mode @cindex Hide-ifdef mode Hide-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-alist Find a file ``related'' in a special way to the file visited by the current buffer. Typically this will be the header file corresponding to a C/C++ source file, or vice versa. The variable @code{ff-related-file-alist} specifies how to compute related file names. @end table @node Fortran @section Fortran Mode @cindex Fortran mode @cindex mode, Fortran Fortran mode provides special motion commands for Fortran statements and subprograms, and indentation commands that understand Fortran conventions of nesting, line numbers and continuation statements. Fortran mode has support for Auto Fill mode that breaks long lines into proper Fortran continuation lines. Special commands for comments are provided because Fortran comments are unlike those of other languages. Built-in abbrevs optionally save typing when you insert Fortran keywords. Use @kbd{M-x fortran-mode} to switch to this major mode. This command runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). @cindex Fortran77 and Fortran90 @findex f90-mode @findex fortran-mode Fortran mode is meant for editing Fortran77 ``fixed format'' (and also ``tab format'') source code. For editing the modern Fortran90 or Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and @samp{.f95}. GNU Fortran supports both kinds of format. @menu * Motion: Fortran Motion. Moving point by statements or subprograms. * Indent: Fortran Indent. Indentation commands for Fortran. * Comments: Fortran Comments. Inserting and aligning comments. * Autofill: Fortran Autofill. Auto fill support for Fortran. * Columns: Fortran Columns. Measuring columns for valid Fortran. * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. @end menu @node Fortran Motion @subsection Motion Commands In addition to the normal commands for moving by and operating on ``defuns'' (Fortran subprograms---functions and subroutines, as well as modules for F90 mode), Fortran mode provides special commands to move by statements and other program units. @table @kbd @kindex C-c C-n @r{(Fortran mode)} @findex fortran-next-statement @findex f90-next-statement @item C-c C-n Move to the beginning of the next statement (@code{fortran-next-statement}/@code{f90-next-statement}). @kindex C-c C-p @r{(Fortran mode)} @findex fortran-previous-statement @findex f90-previous-statement @item C-c C-p Move to the beginning of the previous statement (@code{fortran-previous-statement}/@code{f90-previous-statement}). If there is no previous statement (i.e. if called from the first statement in the buffer), move to the start of the buffer. @kindex C-c C-e @r{(F90 mode)} @findex f90-next-block @item C-c C-e Move point forward to the start of the next code block (@code{f90-next-block}). A code block is a subroutine, @code{if}--@code{endif} statement, and so forth. This command exists for F90 mode only, not Fortran mode. With a numeric argument, this moves forward that many blocks. @kindex C-c C-a @r{(F90 mode)} @findex f90-previous-block @item C-c C-a Move point backward to the previous code block (@code{f90-previous-block}). This is like @code{f90-next-block}, but moves backwards. @kindex C-M-n @r{(Fortran mode)} @findex fortran-end-of-block @findex f90-end-of-block @item C-M-n Move to the end of the current code block (@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric agument, move forward that number of blocks. The mark is set before moving point. The F90 mode version of this command checks for consistency of block types and labels (if present), but it does not check the outermost block since that may be incomplete. @kindex C-M-p @r{(Fortran mode)} @findex fortran-beginning-of-block @findex f90-beginning-of-block @item C-M-p Move to the start of the current code block (@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This is like @code{fortran-end-of-block}, but moves backwards. @end table @node Fortran Indent @subsection Fortran Indentation Special commands and features are needed for indenting Fortran code in order to make sure various syntactic entities (line numbers, comment line indicators and continuation line flags) appear in the columns that are required for standard, fixed (or tab) format Fortran. @menu * Commands: ForIndent Commands. Commands for indenting and filling Fortran. * Contline: ForIndent Cont. How continuation lines indent. * Numbers: ForIndent Num. How line numbers auto-indent. * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. * Vars: ForIndent Vars. Variables controlling Fortran indent style. @end menu @node ForIndent Commands @subsubsection Fortran Indentation and Filling Commands @table @kbd @item C-M-j Break the current line at point and set up a continuation line (@code{fortran-split-line}). @item M-^ Join this line to the previous line (@code{fortran-join-line}). @item C-M-q Indent all the lines of the subprogram point is in (@code{fortran-indent-subprogram}). @item M-q Fill a comment block or statement. @end table @kindex C-M-q @r{(Fortran mode)} @findex fortran-indent-subprogram The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command to reindent all the lines of the Fortran subprogram (function or subroutine) containing point. @kindex C-M-j @r{(Fortran mode)} @findex fortran-split-line The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits a line in the appropriate fashion for Fortran. In a non-comment line, the second half becomes a continuation line and is indented accordingly. In a comment line, both halves become separate comment lines. @kindex M-^ @r{(Fortran mode)} @kindex C-c C-d @r{(Fortran mode)} @findex fortran-join-line @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, which joins a continuation line back to the previous line, roughly as the inverse of @code{fortran-split-line}. The point must be on a continuation line when this command is invoked. @kindex M-q @r{(Fortran mode)} @kbd{M-q} in Fortran mode fills the comment block or statement that point is in. This removes any excess statement continuations. @node ForIndent Cont @subsubsection Continuation Lines @cindex Fortran continuation lines @vindex fortran-continuation-string Most Fortran77 compilers allow two ways of writing continuation lines. If the first non-space character on a line is in column 5, then that line is a continuation of the previous line. We call this @dfn{fixed format}. (In GNU Emacs we always count columns from 0; but note that the Fortran standard counts from 1.) The variable @code{fortran-continuation-string} specifies what character to put in column 5. A line that starts with a tab character followed by any digit except @samp{0} is also a continuation line. We call this style of continuation @dfn{tab format}. (Fortran90 introduced ``free format'', with another style of continuation lines). @vindex indent-tabs-mode @r{(Fortran mode)} @vindex fortran-analyze-depth @vindex fortran-tab-mode-default Fortran mode can use either style of continuation line. When you enter Fortran mode, it tries to deduce the proper continuation style automatically from the buffer contents. It does this by scanning up to @code{fortran-analyze-depth} (default 100) lines from the start of the buffer. The first line that begins with either a tab character or six spaces determines the choice. If the scan fails (for example, if the buffer is new and therefore empty), the value of @code{fortran-tab-mode-default} (@code{nil} for fixed format, and non-@code{nil} for tab format) is used. @samp{/t} in the mode line indicates tab format is selected. Fortran mode sets the value of @code{indent-tabs-mode} accordingly (@pxref{Just Spaces}). If the text on a line starts with the Fortran continuation marker @samp{$}, or if it begins with any non-whitespace character in column 5, Fortran mode treats it as a continuation line. When you indent a continuation line with @key{TAB}, it converts the line to the current continuation style. When you split a Fortran statement with @kbd{C-M-j}, the continuation marker on the newline is created according to the continuation style. The setting of continuation style affects several other aspects of editing in Fortran mode. In fixed format mode, the minimum column number for the body of a statement is 6. Lines inside of Fortran blocks that are indented to larger column numbers always use only the space character for whitespace. In tab format mode, the minimum column number for the statement body is 8, and the whitespace before column 8 must always consist of one tab character. @node ForIndent Num @subsubsection Line Numbers If a number is the first non-whitespace in the line, Fortran indentation assumes it is a line number and moves it to columns 0 through 4. (Columns always count from 0 in GNU Emacs.) @vindex fortran-line-number-indent Line numbers of four digits or less are normally indented one space. The variable @code{fortran-line-number-indent} controls this; it specifies the maximum indentation a line number can have. The default value of the variable is 1. Fortran mode tries to prevent line number digits passing column 4, reducing the indentation below the specified maximum if necessary. If @code{fortran-line-number-indent} has the value 5, line numbers are right-justified to end in column 4. @vindex fortran-electric-line-number Simply inserting a line number is enough to indent it according to these rules. As each digit is inserted, the indentation is recomputed. To turn off this feature, set the variable @code{fortran-electric-line-number} to @code{nil}. @node ForIndent Conv @subsubsection Syntactic Conventions Fortran mode assumes that you follow certain conventions that simplify the task of understanding a Fortran program well enough to indent it properly: @itemize @bullet @item Two nested @samp{do} loops never share a @samp{continue} statement. @item Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} and others are written without embedded whitespace or line breaks. Fortran compilers generally ignore whitespace outside of string constants, but Fortran mode does not recognize these keywords if they are not contiguous. Constructs such as @samp{else if} or @samp{end do} are acceptable, but the second word should be on the same line as the first and not on a continuation line. @end itemize @noindent If you fail to follow these conventions, the indentation commands may indent some lines unaesthetically. However, a correct Fortran program retains its meaning when reindented even if the conventions are not followed. @node ForIndent Vars @subsubsection Variables for Fortran Indentation @vindex fortran-do-indent @vindex fortran-if-indent @vindex fortran-structure-indent @vindex fortran-continuation-indent @vindex fortran-check-all-num@dots{} @vindex fortran-minimum-statement-indent@dots{} Several additional variables control how Fortran indentation works: @table @code @item fortran-do-indent Extra indentation within each level of @samp{do} statement (default 3). @item fortran-if-indent Extra indentation within each level of @samp{if}, @samp{select case}, or @samp{where} statements (default 3). @item fortran-structure-indent Extra indentation within each level of @samp{structure}, @samp{union}, @samp{map}, or @samp{interface} statements (default 3). @item fortran-continuation-indent Extra indentation for bodies of continuation lines (default 5). @item fortran-check-all-num-for-matching-do In Fortran77, a numbered @samp{do} statement is ended by any statement with a matching line number. It is common (but not compulsory) to use a @samp{continue} statement for this purpose. If this variable has a non-@code{nil} value, indenting any numbered statement must check for a @samp{do} that ends there. If you always end @samp{do} statements with a @samp{continue} line (or if you use the more modern @samp{enddo}), then you can speed up indentation by setting this variable to @code{nil}. The default is @code{nil}. @item fortran-blink-matching-if If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} statement moves the cursor momentarily to the matching @samp{if} (or @samp{do}) statement to show where it is. The default is @code{nil}. @item fortran-minimum-statement-indent-fixed Minimum indentation for Fortran statements when using fixed format continuation line style. Statement bodies are never indented less than this much. The default is 6. @item fortran-minimum-statement-indent-tab Minimum indentation for Fortran statements for tab format continuation line style. Statement bodies are never indented less than this much. The default is 8. @end table The variables controlling the indentation of comments are described in the following section. @node Fortran Comments @subsection Fortran Comments The usual Emacs comment commands assume that a comment can follow a line of code. In Fortran77, the standard comment syntax requires an entire line to be just a comment. Therefore, Fortran mode replaces the standard Emacs comment commands and defines some new variables. @vindex fortran-comment-line-start Fortran mode can also handle the Fortran90 comment syntax where comments start with @samp{!} and can follow other text. Because only some Fortran77 compilers accept this syntax, Fortran mode will not insert such comments unless you have said in advance to do so. To do this, set the variable @code{fortran-comment-line-start} to @samp{"!"}. @table @kbd @item M-; Align comment or insert new comment (@code{fortran-indent-comment}). @item C-x ; Applies to nonstandard @samp{!} comments only. @item C-c ; Turn all lines of the region into comments, or (with argument) turn them back into real code (@code{fortran-comment-region}). @end table @findex fortran-indent-comment @kbd{M-;} in Fortran mode is redefined as the command @code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this recognizes any kind of existing comment and aligns its text appropriately; if there is no existing comment, a comment is inserted and aligned. But inserting and aligning comments are not the same in Fortran mode as in other modes. When a new comment must be inserted, if the current line is blank, a full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} comment is inserted if you have said you want to use them. Otherwise a full-line comment is inserted on a new line before the current line. Nonstandard @samp{!} comments are aligned like comments in other languages, but full-line comments are different. In a standard full-line comment, the comment delimiter itself must always appear in column zero. What can be aligned is the text within the comment. You can choose from three styles of alignment by setting the variable @code{fortran-comment-indent-style} to one of these values: @vindex fortran-comment-indent-style @vindex fortran-comment-line-extra-indent @table @code @item fixed Align the text at a fixed column, which is the sum of @code{fortran-comment-line-extra-indent} and the minimum statement indentation. This is the default. The minimum statement indentation is @code{fortran-minimum-statement-indent-fixed} for fixed format continuation line style and @code{fortran-minimum-statement-indent-tab} for tab format style. @item relative Align the text as if it were a line of code, but with an additional @code{fortran-comment-line-extra-indent} columns of indentation. @item nil Don't move text in full-line comments automatically. @end table @vindex fortran-comment-indent-char In addition, you can specify the character to be used to indent within full-line comments by setting the variable @code{fortran-comment-indent-char} to the single-character string you want to use. @vindex fortran-directive-re Compiler directive lines, or preprocessor lines, have much the same appearance as comment lines. It is important, though, that such lines never be indented at all, no matter what the value of @code{fortran-comment-indent-style}. The variable @code{fortran-directive-re} is a regular expression that specifies which lines are directives. Matching lines are never indented, and receive distinctive font-locking. The normal Emacs comment command @kbd{C-x ;} has not been redefined. If you use @samp{!} comments, this command can be used with them. Otherwise it is useless in Fortran mode. @kindex C-c ; @r{(Fortran mode)} @findex fortran-comment-region @vindex fortran-comment-region The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the lines of the region into comments by inserting the string @samp{C$$$} at the front of each one. With a numeric argument, it turns the region back into live code by deleting @samp{C$$$} from the front of each line in it. The string used for these comments can be controlled by setting the variable @code{fortran-comment-region}. Note that here we have an example of a command and a variable with the same name; these two uses of the name never conflict because in Lisp and in Emacs it is always clear from the context which one is meant. @node Fortran Autofill @subsection Auto Fill in Fortran Mode Fortran mode has specialized support for Auto Fill mode, which is a minor mode that automatically splits statements as you insert them when they become too wide. Splitting a statement involves making continuation lines using @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran indentation commands. You activate Auto Fill in Fortran mode in the normal way (@pxref{Auto Fill}). @vindex fortran-break-before-delimiters Auto Fill breaks lines at spaces or delimiters when the lines get longer than the desired width (the value of @code{fill-column}). The delimiters (besides whitespace) that Auto Fill can break at are @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, and @samp{,}. The line break comes after the delimiter if the variable @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by default), the break comes before the delimiter. To enable Auto Fill in all Fortran buffers, add @code{turn-on-auto-fill} to @code{fortran-mode-hook}. @xref{Hooks}. @node Fortran Columns @subsection Checking Columns in Fortran @table @kbd @item C-c C-r Display a ``column ruler'' momentarily above the current line (@code{fortran-column-ruler}). @item C-c C-w Split the current window horizontally temporarily so that it is 72 columns wide (@code{fortran-window-create-momentarily}). This may help you avoid making lines longer than the 72-character limit that some Fortran compilers impose. @item C-u C-c C-w Split the current window horizontally so that it is 72 columns wide (@code{fortran-window-create}). You can then continue editing. @item M-x fortran-strip-sequence-nos Delete all text in column 72 and beyond. @end table @kindex C-c C-r @r{(Fortran mode)} @findex fortran-column-ruler The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column ruler momentarily above the current line. The comment ruler is two lines of text that show you the locations of columns with special significance in Fortran programs. Square brackets show the limits of the columns for line numbers, and curly brackets show the limits of the columns for the statement body. Column numbers appear above them. Note that the column numbers count from zero, as always in GNU Emacs. As a result, the numbers may be one less than those you are familiar with; but the positions they indicate in the line are standard for Fortran. @vindex fortran-column-ruler-fixed @vindex fortran-column-ruler-tabs The text used to display the column ruler depends on the value of the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is @code{nil}, then the value of the variable @code{fortran-column-ruler-fixed} is used as the column ruler. Otherwise, the value of the variable @code{fortran-column-ruler-tab} is displayed. By changing these variables, you can change the column ruler display. @kindex C-c C-w @r{(Fortran mode)} @findex fortran-window-create-momentarily @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily splits the current window horizontally, making a window 72 columns wide, so you can see any lines that are too long. Type a space to restore the normal width. @kindex C-u C-c C-w @r{(Fortran mode)} @findex fortran-window-create You can also split the window horizontally and continue editing with the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x fortran-window-create}). By editing in this window you can immediately see when you make a line too wide to be correct Fortran. @findex fortran-strip-sequence-nos The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in column 72 and beyond, on all lines in the current buffer. This is the easiest way to get rid of old sequence numbers. @node Fortran Abbrev @subsection Fortran Keyword Abbrevs Fortran mode provides many built-in abbrevs for common keywords and declarations. These are the same sort of abbrev that you can define yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. The built-in abbrevs are unusual in one way: they all start with a semicolon. You cannot normally use semicolon in an abbrev, but Fortran mode makes this possible by changing the syntax of semicolon to ``word constituent.'' For example, one built-in Fortran abbrev is @samp{;c} for @samp{continue}. If you insert @samp{;c} and then insert a punctuation character such as a space or a newline, the @samp{;c} expands automatically to @samp{continue}, provided Abbrev mode is enabled.@refill Type @samp{;?} or @samp{;C-h} to display a list of all the built-in Fortran abbrevs and what they stand for. @node Asm Mode @section Asm Mode @cindex Asm mode @cindex assembler mode Asm mode is a major mode for editing files of assembler code. It defines these commands: @table @kbd @item @key{TAB} @code{tab-to-tab-stop}. @item C-j Insert a newline and then indent using @code{tab-to-tab-stop}. @item : Insert a colon and then remove the indentation from before the label preceding colon. Then do @code{tab-to-tab-stop}. @item ; Insert or align a comment. @end table The variable @code{asm-comment-char} specifies which character starts comments in assembler syntax. @ignore arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 @end ignore