Editing Programs
****************

Emacs provides many features to facilitate editing programs.  Some of these features can

  * Find or move over top-level definitions (see Defuns).

  * Apply the usual indentation conventions of the language (see Program Indent).

  * Balance parentheses (see Parentheses).

  * Insert, kill or align comments (see Comments).

  * Highlight program syntax (see Font Lock).

This chapter describes these features and many more.

Major Modes for Programming Languages
=====================================

Emacs has specialized major modes for various programming languages. See 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 or end 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 L is called L-mode, and you can select it by typing M-x L-mode RET. See Choosing Modes.

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, Icon, IDL (CORBA), IDLWAVE, Java, Metafont (TeX's companion for font creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, 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 BAT files.  There are also major modes for editing makefiles, DNS master files, and various sorts of configuration files.

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 TAB to update the indentation of the current line (see Program Indent).  They also rebind 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 C-b C-d to delete a tab character before point, in these modes.

Separate manuals are available for the modes for Ada (see Ada Mode), C/C++/Objective C/Java/Corba IDL/Pike/AWK (see CC Mode) and the IDLWAVE modes (see IDLWAVE (IDLWAVE User Manual)).  For Fortran mode, see Fortran.

Turning on a major mode runs a normal hook called the 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 -hook.  For example, turning on C mode runs the hook c-mode-hook, while turning on Lisp mode runs the hook lisp-mode-hook.  The purpose of the mode hook is to give you a place to set up customizations for that major mode.  See Hooks.

Top-Level Definitions, or Defuns
================================

In Emacs, a major definition at the top level in the buffer, such as a function, is called a defun.  The name comes from Lisp, but in Emacs we use it for all languages.

Left Margin Convention
----------------------

Many programming-language modes assume by default that any opening delimiter found at the left margin is the start of a top-level definition, or defun.  Therefore, don't put an opening delimiter at the left margin unless it should have that significance. 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.

The convention speeds up many Emacs operations, which would otherwise have to scan back to the beginning of the buffer to analyze the syntax of the code.

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 (see Program Indent) and Font Lock mode (see 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 (\, in C and Emacs Lisp, / 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:

       (insert "Foo:
     \(bar)
     ")

To help you catch violations of this convention, Font Lock mode highlights confusing opening delimiters (those that ought to be quoted) in bold red.

If you need to override this convention, you can do so by setting this user option:

 -- Variable: open-paren-in-column-0-is-defun-start
     If this user option is set to t (the default), opening parentheses or braces at column zero always start defuns.  When it's nil, defuns are found by searching for parens or braces at the outermost level.

Usually, you should leave this option at its default value of t.  If your buffer contains parentheses or braces in column zero which don't start defuns, and it is somehow impractical to remove these parentheses or braces, it might be helpful to set the option to nil.  Be aware that this might make scrolling and display in large buffers quite sluggish.  Furthermore, the parentheses and braces must be correctly matched throughout the buffer for it to work properly.

Moving by Defuns
----------------

These commands move point or set up the region based on top-level major definitions, also called defuns.

C-M-a
     Move to beginning of current or preceding defun (beginning-of-defun).

C-M-e
     Move to end of current or following defun (end-of-defun).

C-M-h
     Put region around whole current or following defun (mark-defun).

The commands to move to the beginning and end of the current defun are C-M-a (beginning-of-defun) and C-M-e (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.

C-M-a with a negative argument -N moves forward N times to the next beginning of a defun.  This is not exactly the same place that C-M-e with argument 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, C-M-e with a negative argument moves back to an end of a defun, which is not quite the same as C-M-a with a positive argument.

To operate on the current defun, use C-M-h (mark-defun), which sets the mark at the end of the current defun and puts point at its beginning.  See Marking Objects.  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.  If you use the command while the mark is already active, it sets the mark but does not move point; furthermore, each successive use of C-M-h extends the end of the region to include one more defun.

In C mode, C-M-h runs the function c-mark-function, which is almost the same as 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.

Imenu
-----

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. (see Tags, for a more powerful feature that handles multiple files together.)

If you type 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.

Alternatively, you can bind the command 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 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 imenu-add-menubar-index to its mode hook.  But if you have done that, you will have to wait a little while each time you visit a file in that mode, while Emacs finds all the definitions in that buffer.

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 *Rescan* item in the menu. Rescanning happens automatically if you set imenu-auto-rescan to a non-nil value.  There is no need to rescan because of small changes in the text.

You can customize the way the menus are sorted by setting the variable imenu-sort-function.  By default, names are ordered as they occur in the buffer; if you want alphabetic sorting, use the symbol 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 (see Which Function). The Speedbar can also use it (see Speedbar).

Which Function Mode
-------------------

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.

To either enable or disable Which Function mode, use the command M-x which-function-mode.  This command 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 which-func-modes.  If the value of which-func-modes is t rather than a list of modes, 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.

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 either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping.

Emacs also provides a Lisp pretty-printer in the library pp. This program reformats a Lisp object with indentation chosen to look nice.

Basic Program Indentation Commands
----------------------------------

The basic indentation commands indent a single line according to the usual conventions of the language you are editing.

TAB
     Adjust indentation of current line.

C-j
     Insert a newline, then adjust indentation of following line (newline-and-indent).

The basic indentation command is TAB.  In any programming-language major mode, TAB gives the current line the correct indentation as determined from the previous lines.  It does this by inserting or deleting whitespace at the beginning of the current line.  If point was inside the whitespace at the beginning of the line, TAB puts it at the end of that whitespace; otherwise, TAB keeps point fixed with respect to the characters around it. If the region is active (see Mark), TAB indents every line within the region instead of just the current line.  The function that TAB runs depends on the major mode; for instance, it is c-indent-line-or-region in C mode.  Each function is aware of the syntax and conventions for its particular language.

Use C-q TAB to insert a tab character at point.

When entering lines of new code, use C-j (newline-and-indent), which inserts a newline and then adjusts indentation after it.  (It also deletes any trailing whitespace which remains before the new newline.)  For instance, C-j at the end of a line creates a blank line with appropriate indentation.  In programming language modes, it is equivalent to RET TAB.

When Emacs indents a line that starts within a parenthetical grouping, it usually places the start of the line under the preceding line within the group, or under the text after the parenthesis.  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 TAB indentation (e.g., for aesthetic purposes).

Many programming-language modes assume that an open-parenthesis, open-brace or other opening delimiter at the left margin is the start of a function.  This assumption speeds up indentation commands.  If the text you are editing contains opening delimiters in column zero that aren't the beginning of a functions---even if these delimiters occur inside strings or comments---then you must set open-paren-in-column-0-is-defun-start.  See Left Margin Paren.

Normally, Emacs indents lines using an ``optimal'' mix of tab and space characters.  If you want Emacs to use spaces only, set indent-tabs-mode (see Just Spaces).

Indenting Several Lines
-----------------------

Sometimes, you may want to reindent several lines of code at a time. One way to do this is to use the mark; when the mark is active and the region is non-empty, TAB indents every line within the region. In addition, Emacs provides several other commands for indenting large chunks of code:

C-M-q
     Reindent all the lines within one parenthetical grouping.

C-M-\
     Reindent all lines in the region (indent-region).

C-u TAB
     Shift an entire parenthetical grouping rigidly sideways so that its first line is properly indented.

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.

To reindent the contents of a single parenthetical grouping, position point before the beginning of the grouping and type C-M-q.  This changes the relative indentation within the grouping, without affecting its overall indentation (i.e., the indentation of the line where the grouping starts).  The function that C-M-q runs depends on the major mode; it is indent-pp-sexp in Lisp mode, c-indent-exp in C mode, etc.  To correct the overall indentation as well, type TAB first.

C-M-\ (indent-region) applies TAB to the region. This is useful when Transient Mark mode is disabled (see Persistent Mark), because in that case TAB does not act on the region.

If you like the relative indentation within a grouping but not the indentation of its first line, move point to that first line and type C-u TAB.  In Lisp, C, and some other major modes, 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.

The command M-x indent-code-rigidly rigidly shifts all the lines in the region sideways, like indent-rigidly does (see 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.

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.

If the variable lisp-indent-offset is non-nil, it overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented lisp-indent-offset more columns than the containing list.

Certain functions override the standard pattern.  Functions whose names start with def treat the second lines as the start of a body, by indenting the second line lisp-body-indent additional columns beyond the open-parenthesis that starts the expression.

You can override the standard pattern in various ways for individual functions, according to the lisp-indent-function property of the function name.  Normally you would use this for macro definitions and specify it using the declare construct (see Defining Macros (the Emacs Lisp Reference Manual)).

Commands for C Indentation
--------------------------

Here are special features for indentation in C mode and related modes:

C-c C-q
     Reindent the current top-level function definition or aggregate type declaration (c-indent-defun).

C-M-q
     Reindent each line in the balanced expression that follows point (c-indent-exp).  A prefix argument inhibits warning messages about invalid syntax.

TAB
     Reindent the current line, and/or in some cases insert a tab character (c-indent-command).

     If c-tab-always-indent is t, this command always reindents the current line and does nothing else.  This is the default.

     If that variable is 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 indent-tabs-mode is nil).

     Any other value (not nil or t) means always reindent the line, and also insert a tab if within a comment or a string.

To reindent the whole current buffer, type C-x h C-M-\.  This first selects the whole buffer as the region, then reindents that region.

To reindent the current block, use C-M-u C-M-q.  This moves to the front of the block and then reindents it all.

Customizing C 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 style with the syntactic construct and adds this onto the indentation of the anchor statement.

C-c . RET STYLE RET
     Select a predefined style STYLE (c-set-style).

A style is a named collection of customizations that can be used in C mode and the related modes.  Styles (The CC Mode Manual), for a complete description.  Emacs comes with several predefined styles, including gnu, k&r, bsd, stroustrup, linux, python, java, whitesmith, ellemtel, and 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 C-M-q at the start of a function definition.

To choose a style for the current buffer, use the command 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 C-x h C-M-\.

You can also set the variable 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,

     (setq c-default-style
           '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))

specifies explicit choices for Java and AWK modes, and the default 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 M-x java-mode there.

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

See Indentation Engine Basics (the CC Mode Manual), and Customizing Indentation (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.

Commands for Editing with Parentheses
=====================================

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 (see Syntax).  In Lisp, only parentheses count; in C, these commands apply to braces and brackets too.

You can use M-x check-parens to find any unbalanced parentheses and unbalanced string quotes in the buffer.

Expressions with Balanced Parentheses
-------------------------------------

These commands deal with balanced expressions, also called sexps (The word ``sexp'' is used to refer to an expression in Lisp.).

C-M-f
     Move forward over a balanced expression (forward-sexp).

C-M-b
     Move backward over a balanced expression (backward-sexp).

C-M-k
     Kill balanced expression forward (kill-sexp).

C-M-t
     Transpose expressions (transpose-sexps).

C-M-@
C-M-SPC
     Put mark after following expression (mark-sexp).

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.

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 C-M-b moves backward over a balanced expression, just as M-b moves back over a word.

To move forward over a balanced expression, use C-M-f (forward-sexp).  If the first significant character after point is an opening delimiter (( in Lisp; (, [ or { in C), C-M-f moves past the matching closing delimiter.  If the character begins a symbol, string, or number, C-M-f moves over that.

The command C-M-b (backward-sexp) moves backward over a balanced expression.  The detailed rules are like those above for C-M-f, but with directions reversed.  If there are prefix characters (single-quote, backquote and comma, in Lisp) preceding the expression, C-M-b moves back over them as well.  The balanced expression commands move across comments as if they were whitespace, in most modes.

C-M-f or C-M-b with an argument repeats that operation the specified number of times; with a negative argument, it moves in the opposite direction.

Killing a whole balanced expression can be done with C-M-k (kill-sexp).  C-M-k kills the characters that C-M-f would move over.

A somewhat random-sounding command which is nevertheless handy is C-M-t (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 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.

To set the region around the next balanced expression in the buffer, use C-M-SPC (mark-sexp), which sets mark at the same place that C-M-f would move to.  C-M-SPC treats numeric arguments in the same way as C-M-f; in particular, a negative argument puts the mark at the beginning of the previous balanced expression.  The alias C-M-@ is equivalent to C-M-SPC.  While the mark is active, each successive use of C-M-SPC extends the region by shifting the mark by one sexp.

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 foo + bar as a single expression, even though it is one C expression; instead, it recognizes foo as one expression and bar as another, with the + as punctuation between them.  Both foo + bar and foo are legitimate choices for ``the expression following point'' when point is at the f, so the expression commands must perforce choose one or the other to operate on.  Note that (foo + bar) is recognized as a single expression in C mode, because of the parentheses.

Moving in the Parenthesis Structure
-----------------------------------

The Emacs commands for handling parenthetical groupings see nothing except parentheses (or whatever characters must balance in the language you are working with).  They ignore strings and comments (including any parentheses within them) and ignore parentheses quoted by an escape character.  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.

These commands assume that the starting point is not inside a string or a comment.  Sometimes you can invoke them usefully from one of these places (for example, when you have a parenthesised clause in a comment) but this is unreliable.

C-M-n
     Move forward over a parenthetical group (forward-list).

C-M-p
     Move backward over a parenthetical group (backward-list).

C-M-u
     Move up in parenthesis structure (backward-up-list).

C-M-d
     Move down in parenthesis structure (down-list).

The ``list'' commands C-M-n (forward-list) and C-M-p (backward-list) move forward or backward over one (or N) parenthetical groupings.

C-M-n and C-M-p try to stay at the same level in the parenthesis structure.  To move up one (or N) levels, use C-M-u (backward-up-list).  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 down in the parenthesis structure, use C-M-d (down-list).  In Lisp mode, where ( is the only opening delimiter, this is nearly the same as searching for a (.  An argument specifies the number of levels to go down.

Automatic Display Of Matching Parentheses
-----------------------------------------

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 [x)---a warning message is displayed in the echo area.

Three variables control parenthesis match display:

blink-matching-paren turns the feature on or off: nil disables it, but the default is t to enable match display.

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.

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

Show Paren mode provides a more powerful kind of automatic matching. Whenever point is before an opening delimiter or after a closing delimiter, both that delimiter and its opposite delimiter are highlighted.  Use the command M-x show-paren-mode to enable or disable this mode.

Show Paren mode uses the faces show-paren-match and show-paren-mismatch to highlight parentheses; you can customize them to control how highlighting looks.  See Face Customization.

Manipulating 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 (see Spelling).

Comment Commands
----------------

The commands in this table insert, kill and align comments:

M-;
     Insert or realign comment on current line; alternatively, comment or uncomment the region (comment-dwim).

C-u M-;
     Kill comment on current line (comment-kill).

C-x ;
     Set comment column (comment-set-column).

C-M-j
M-j
     Like RET followed by inserting and aligning a comment (comment-indent-new-line).  See Multi-Line Comments.

M-x comment-region
C-c C-c (in C-like modes)
     Add or remove comment delimiters on all the lines in the region.

The command to create or align a comment is M-; (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.

When a region is active, M-; either adds or removes comment delimiters on each line of the region.  See Mark.  If every line in the region is a comment, it removes comment delimiters from each; otherwise, it adds comment delimiters to each.  You can also use the commands comment-region and uncomment-region to explicitly comment or uncomment the text in the region (see Multi-Line Comments).  If you supply a prefix argument to M-; when a region is active, that specifies how many comment delimiters to add or how many to delete.

If the region is not active, M-; inserts a new comment if there is no comment already on the line.  The new comment is normally aligned at a specific column called the comment column; if the text of the line extends past the comment column, M-; aligns the comment start string to a suitable boundary (usually, at least one space is inserted).  The comment begins with the string Emacs thinks comments should start with (the value of comment-start; see below).  Emacs places point 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, M-; inserts that string after point, to keep the syntax valid.

You can also use M-; to align an existing comment.  If a line already contains the comment-start string, M-; realigns 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, M-; is still useful for moving directly to the start of the text inside the comment.

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 C-y, and then do M-; to realign it.

Note that C-u M-; is not a distinct key; it is M-; (comment-dwim) with a prefix argument.  That command is programmed so that when it receives a prefix argument it calls comment-kill.  However, comment-kill is a valid command in its own right, and you can bind it directly to a key if you wish.

Some major modes have special rules for aligning 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 and are often used for sectioning purposes.  Emacs understands these conventions by indenting a double-semicolon comment using TAB, and by not changing the indentation of a triple-semicolon comment at all.

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

For C-like modes, you can configure the exact effect of M-; by setting the variables c-indent-comment-alist and c-indent-comments-syntactically-p.  For example, on a line ending in a closing brace, M-; puts the comment one space after the brace rather than at comment-column.  For full details see Comment Commands (The CC Mode Manual).

Multiple Lines of Comments
--------------------------

If you are typing a comment and wish to continue it on another line, you can use the command C-M-j or M-j (comment-indent-new-line).  If comment-multi-line (see Options for Comments) is non-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.

To turn existing lines into comment lines, use the M-x comment-region command (or type C-c C-c in C-like modes).  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, 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, C-u 2 M-x comment-region adds ;; to each line. Duplicating the comment delimiter is a way of calling attention to the comment.  It can also affect how the comment is aligned or 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 / at the start of a line in a multi-line block comment, this closes the comment.  Enable the comment-close-slash clean-up for this. See Clean-ups (The CC Mode Manual).

Options Controlling Comments
----------------------------

The comment column, the column at which Emacs tries to place comments, is stored in the variable comment-column.  You can set it to a number explicitly.  Alternatively, the command C-x ; (comment-set-column) sets the comment column to the column point is at.  C-u C-x ; sets the comment column to match the last comment before point in the buffer, and then does a M-; to align the current line's comment under the previous one.

The variable 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 setq-default. See Locals.  Many major modes initialize this variable for the current buffer.

The comment commands recognize comments based on the regular expression that is the value of the variable 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 "/\\*+ *\\|//+ *", which matches extra stars and spaces after the /* itself, and accepts C++ style comments also. (Note that \\ is needed in Lisp syntax to include a \ in the string, which is needed to deny the first star its special meaning in regexp syntax.  See Regexp Backslash.)

When a comment command makes a new comment, it inserts the value of comment-start to begin it.  The value of comment-end is inserted after point, so that it will follow the text that you will insert into the comment.  When comment-end is non-empty, it should start with a space.  For example, in C mode, comment-start has the value "/* " and comment-end has the value " */".

The variable comment-padding specifies how many spaces 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.  nil means 0.  Alternatively, comment-padding can hold the actual string to insert.

The variable comment-multi-line controls how C-M-j (indent-new-comment-line) behaves when used inside a comment. Specifically, when comment-multi-line is 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.

The variable comment-indent-function should contain a function that will be called to compute the alignment 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.

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.

Info Documentation Lookup
-------------------------

For major modes that apply to languages which have documentation in Info, you can use C-h S (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 command only works if the appropriate manual's Info files are installed.

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 M-x info-lookup-file to look for documentation for a file name.

If you use C-h S in a major mode that does not support it, it asks you to specify the ``symbol help mode.''  You should enter a command such as c-mode that would select a major mode which C-h S does support.

Man Page Lookup
---------------

On Unix, the main form of on-line documentation was the manual page or man page.  In the GNU operating system, we aim to replace man pages with better-organized manuals that you can browse with Info (see Misc Help).  This process is not finished, so it is still useful to read manual pages.

You can read the man page for an operating system command, library function, or system call, with the M-x man command.  It runs the man program to format the man page; if the system permits, it runs 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 man to finish.)  The result goes in a buffer named *Man TOPIC*.  These buffers use a special major mode, Man mode, that facilitates scrolling and jumping to other manual pages.  For details, type C-h m while in a man page buffer.

Each man page belongs to one of ten or more 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 TOPIC(SECTION) or SECTION TOPIC when M-x manual-entry prompts for the topic.  For example, to read the man page for the C library function chmod (as opposed to a command of the same name), type M-x manual-entry RET chmod(2) RET.  (chmod is a system call, so it is in section 2.)

If you do not specify a section, the results depend on how the 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 M-n and M-p keys (On some systems, the man program accepts a -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 Man-switches.). The mode line shows how many manual pages are present in the Man buffer.

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 Man-fontify-manpage-flag to nil.

If you insert the text of a man page into an Emacs buffer in some other fashion, you can use the command M-x Man-fontify-manpage to perform the same conversions that M-x manual-entry does.

An alternative way of reading manual pages is the M-x woman command (The name of the command, woman, is an acronym for ``w/o (without) man,'' since it doesn't use the man program.).  Unlike 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 man program (and other programs it uses) are not generally available.

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

For more information about setting up and using M-x woman, see Browse UN*X Manual Pages WithOut Man (The WoMan Manual).

Emacs Lisp Documentation Lookup
-------------------------------

As you edit Lisp code to be run in Emacs, you can use the commands C-h f (describe-function) and C-h v (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 C-h f, the default is the function called in the innermost list containing point.  C-h v uses the symbol name around or adjacent to point as its default.

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 M-x eldoc-mode to enable or disable this feature.

Hideshow minor mode
===================

Hideshow minor mode provides selective display of portions of a program, known as blocks.  You can use M-x hs-minor-mode to enable or disable this mode, or add 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.

C-c @ C-h
     Hide the current block (hs-hide-block).

C-c @ C-s
     Show the current block (hs-show-block).

C-c @ C-c
     Either hide or show the current block (hs-toggle-hiding).

S-Mouse-2
     Either hide or show the block you click on (hs-mouse-toggle-hiding).

C-c @ C-M-h
     Hide all top-level blocks (hs-hide-all).

C-c @ C-M-s
     Show everything in the buffer (hs-show-all).

C-c @ C-l
     Hide all blocks N levels below this block (hs-hide-level).

These variables exist for customizing Hideshow mode.

hs-hide-comments-when-hiding-all
     Non-nil says that hs-hide-all should hide comments too.

hs-isearch-open
     Specifies what kind of hidden blocks incremental search should make visible.  The value should be one of these four symbols:

     code
          Open only code blocks.

     comment
          Open only comments.

     t
          Open both code blocks and comments.

     nil
          Open neither code blocks nor comments.

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.

Completion for Symbol Names
===========================

In Emacs, completion is something you normally do in the minibuffer (see Completion).  But one kind of completion is available in all buffers: completion for symbol names.

The character M-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 M-TAB to switch windows, you can type ESC TAB or C-M-i instead. However, most window managers let you customize these shortcuts, so you can change any that interfere with the way you use Emacs.

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, M-TAB displays a list of all possible completions in another window.

In most programming language major modes, M-TAB runs the command complete-symbol, which provides two kinds of completion. Normally it does completion based on a tags table (see 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 M-TAB with no argument; to complete the name of a standard library function, use C-u M-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.

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 lisp-complete-symbol.

In Text mode and related modes, M-TAB completes words based on the spell-checker's dictionary.  See Spelling.

Glasses minor mode
==================

Glasses minor mode makes 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 M-x glasses-mode to enable or disable the mode in the current buffer; you can also add glasses-mode to the mode hook of the programming language major modes in which you normally want to use Glasses mode.

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 (see Words); sentences can be found in strings and comments (see 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 (see 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 (see Selective Display).  This feature hides the lines that are indented more than a specified amount. Programming modes often support Outline minor mode (see Outline Mode).  The Foldout package provides folding-editor features (see Foldout).

The ``automatic typing'' features may be useful for writing programs. See Autotyping.

C and Related Modes
===================

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.'')  See CC Mode, for a more extensive description of these modes and their special features.

C Mode Motion Commands
----------------------

This section describes commands for moving point, in C mode and related modes.

M-x c-beginning-of-defun
M-x 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, beginning-of-defun and 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 C-M-a and C-M-e to these commands.  See Moving by Defuns.

C-c C-u
     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.

     #elif is equivalent to #else followed by #if, so the function will stop at a #elif when going backward, but not when going forward.

C-c C-p
     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.

C-c C-n
     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.

M-a
     Move point to the beginning of the innermost C statement (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 N, move back N - 1 statements.

     In comments or in strings which span more than one line, this command moves by sentences instead of statements.

M-e
     Move point to the end of the innermost C statement or sentence; like M-a except that it moves in the other direction (c-end-of-statement).

Electric C Characters
---------------------

In C mode and related modes, certain printing characters are electric---in addition to inserting themselves, they also reindent the current line, and optionally also insert newlines.  The ``electric'' characters are {, }, :, #, ;, ,, <, >, /, *, (, and ).

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 C-c C-l; when it is enabled, /l appears in the mode line after the mode name:

C-c C-l
     Toggle electric action (c-toggle-electric-state).  With a prefix argument, this command enables electric action if the argument is positive, disables it if it is negative.

Electric characters insert newlines only when, in addition to the electric state, the auto-newline feature is enabled (indicated by /la in the mode line after the mode name).  You can turn this feature on or off with the command C-c C-a:

C-c C-a
     Toggle the auto-newline feature (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.

Usually the CC Mode style configures the exact circumstances in which Emacs inserts auto-newlines.  You can also configure this directly.  See Custom Auto-newlines (The CC Mode Manual).

Hungry Delete Feature in C
--------------------------

If you want to delete an entire block of whitespace at point, you can use hungry deletion.  This deletes all the contiguous whitespace either before point or after point in a single operation. Whitespace here includes tabs and newlines, but not comments or preprocessor commands.

C-c C-DEL
C-c DEL
     c-hungry-delete-backwards---Delete the entire block of whitespace preceding point.

C-c C-d
C-c C-DELETE
C-c DELETE
     c-hungry-delete-forward---Delete the entire block of whitespace following point.

As an alternative to the above commands, you can enable hungry delete mode.  When this feature is enabled (indicated by /h in the mode line after the mode name), a single DEL deletes all preceding whitespace, not just one space, and a single C-c C-d (but not plain DELETE) deletes all following whitespace.

M-x c-toggle-hungry-state
     Toggle the hungry-delete feature (c-toggle-hungry-state) (This command had the binding C-c C-d in earlier versions of Emacs.  C-c C-d is now bound to 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.

The variable c-hungry-delete-key controls whether the hungry-delete feature is enabled.

Other Commands for C Mode
-------------------------

C-c C-w
M-x c-subword-mode
     Enable (or disable) subword mode.  In subword mode, Emacs's word commands recognize upper case letters in StudlyCapsIdentifiers as word boundaries.  This is indicated by the flag /w on the mode line after the mode name (e.g. C/law).  You can even use M-x c-subword-mode in non-CC Mode buffers.

     In the GNU project, we recommend using underscores to separate words within an identifier in C or C++, rather than using case distinctions.

M-x 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 C-j (newline-and-indent), in a C preprocessor line it additionally inserts a \ at the line break, and within comments it's like M-j (c-indent-new-comment-line).

     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 C-j.  We use c-initialization-hook here to make sure the keymap is loaded before we try to change it.

          (defun my-bind-clb ()
            (define-key c-mode-base-map "\C-j" 'c-context-line-break))
          (add-hook 'c-initialization-hook 'my-bind-clb)

C-M-h
     Put mark at the end of a function definition, and put point at the beginning (c-mark-function).

M-q
     Fill a paragraph, handling C and C++ comments (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.

C-c C-e
     Run the C preprocessor on the text in the region, and show the result, which includes the expansion of all the macro calls (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.

C-c C-\
     Insert or align \ characters at the ends of the lines of the region (c-backslash-region).  This is useful after writing or editing a C macro definition.

     If a line already ends in \, this command adjusts the amount of whitespace before it.  Otherwise, it inserts a new \.  However, the last line in the region is treated specially; no \ is inserted on that line, and any \ there is deleted.

M-x cpp-highlight-buffer
     Highlight parts of the text according to its preprocessor conditionals. This command displays another buffer named *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 [A]pply these settings (or go to that buffer and type a) to rehighlight the C mode buffer accordingly.

C-c C-s
     Display the syntactic information about the current source line (c-show-syntactic-information).  This information directs how the line is indented.

M-x cwarn-mode
M-x global-cwarn-mode
     CWarn minor mode highlights certain suspicious C and C++ constructions:

       * Assignments inside expressions.

       * Semicolon following immediately after if, for, and while (except after a do ... while statement);

       * C++ functions with reference parameters.

     You can enable the mode for one buffer with the command M-x cwarn-mode, or for all suitable buffers with the command M-x global-cwarn-mode or by customizing the variable global-cwarn-mode.  You must also enable Font Lock mode to make it work.

M-x hide-ifdef-mode
     Hide-ifdef minor mode hides selected code within #if and #ifdef preprocessor blocks.  If you change the variable hide-ifdef-shadow to t, Hide-ifdef minor mode ``shadows'' preprocessor blocks by displaying them with a less prominent face, instead of hiding them entirely.  See the documentation string of hide-ifdef-mode for more information.

M-x ff-find-related-file
     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 ff-related-file-alist specifies how to compute related file names.

Asm Mode
========

Asm mode is a major mode for editing files of assembler code.  It defines these commands:

TAB
     tab-to-tab-stop.

C-j
     Insert a newline and then indent using tab-to-tab-stop.

:
     Insert a colon and then remove the indentation from before the label preceding colon.  Then do tab-to-tab-stop.

;
     Insert or align a comment.

The variable asm-comment-char specifies which character starts comments in assembler syntax.

     [file fortran-xtra.texi not included]