0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2018 Free Software
0004: @c Foundation, Inc.
0005: @c See file emacs.texi for copying conditions.
0006: @node Programs
0007: @chapter Editing Programs
0008: @cindex Lisp editing
0009: @cindex C editing
0010: @cindex program editing
0011: 
0012:   This chapter describes Emacs features for facilitating editing
0013: programs.  Some of the things these features can do are:
0014: 
0015: @itemize @bullet
0016: @item
0017: Find or move over top-level definitions (@pxref{Defuns}).
0018: @item
0019: Apply the usual indentation conventions of the language
0020: (@pxref{Program Indent}).
0021: @item
0022: Balance parentheses (@pxref{Parentheses}).
0023: @item
0024: Insert, kill or align comments (@pxref{Comments}).
0025: @item
0026: Highlight program syntax (@pxref{Font Lock}).
0027: @end itemize
0028: 
0029: @menu
0030: * Program Modes::       Major modes for editing programs.
0031: * Defuns::              Commands to operate on major top-level parts
0032:                           of a program.
0033: * Program Indent::      Adjusting indentation to show the nesting.
0034: * Parentheses::         Commands that operate on parentheses.
0035: * Comments::            Inserting, killing, and aligning comments.
0036: * Documentation::       Getting documentation of functions you plan to call.
0037: * Hideshow::            Displaying blocks selectively.
0038: * Symbol Completion::   Completion on symbol names of your program or language.
0039: * MixedCase Words::     Dealing with identifiersLikeThis.
0040: * Semantic::            Suite of editing tools based on source code parsing.
0041: * Misc for Programs::   Other Emacs features useful for editing programs.
0042: * C Modes::             Special commands of C, C++, Objective-C, Java,
0043:                           IDL, Pike and AWK modes.
0044: * Asm Mode::            Asm mode and its special features.
0045: @ifnottex
0046: * Fortran::             Fortran mode and its special features.
0047: @end ifnottex
0048: @end menu
0049: 
0050: @node Program Modes
0051: @section Major Modes for Programming Languages
0052: @cindex modes for programming languages
0053: 
0054:   Emacs has specialized major modes (@pxref{Major Modes}) for many
0055: programming languages.  A programming language mode typically
0056: specifies the syntax of expressions, the customary rules for
0057: indentation, how to do syntax highlighting for the language, and how
0058: to find the beginning or end of a function definition.  It often has
0059: features for compiling and debugging programs as well.  The major mode
0060: for each language is named after the language; for instance, the major
0061: mode for the C programming language is @code{c-mode}.
0062: 
0063: @cindex Perl mode
0064: @cindex Icon mode
0065: @cindex Makefile mode
0066: @cindex Tcl mode
0067: @cindex CPerl mode
0068: @cindex DSSSL mode
0069: @cindex Octave mode
0070: @cindex Metafont mode
0071: @cindex Modula2 mode
0072: @cindex Prolog mode
0073: @cindex Python mode
0074: @cindex Ruby mode
0075: @cindex Simula mode
0076: @cindex Verilog mode
0077: @cindex VHDL mode
0078: @cindex M4 mode
0079: @cindex Shell-script mode
0080: @cindex OPascal mode
0081: @cindex PostScript mode
0082: @cindex Conf mode
0083: @cindex DNS mode
0084: @cindex Javascript mode
0085: @cindex Awk mode
0086:   Emacs has programming language modes for Lisp, Scheme, the
0087: Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
0088: Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles,
0089: Metafont (@TeX{}'s companion for font creation), Modula2, Object
0090: Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog,
0091: Python, Ruby, Simula, SQL, Tcl, Verilog, and VHDL@.  An alternative
0092: mode for Perl is called CPerl mode.  Modes are also available for the
0093: scripting languages of the common GNU and Unix shells, and
0094: MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, DNS master
0095: files, and various sorts of configuration files.
0096: 
0097:   Ideally, Emacs should have a major mode for each programming
0098: language that you might want to edit.  If it doesn't have a mode for
0099: your favorite language, the mode might be implemented in a package not
0100: distributed with Emacs (@pxref{Packages}); or you can contribute one.
0101: 
0102: @kindex DEL @r{(programming modes)}
0103: @findex backward-delete-char-untabify
0104:   In most programming languages, indentation should vary from line to
0105: line to illustrate the structure of the program.  Therefore, in most
0106: programming language modes, typing @kbd{@key{TAB}} updates the
0107: indentation of the current line (@pxref{Program Indent}).
0108: Furthermore, @kbd{@key{DEL}} is usually bound to
0109: @code{backward-delete-char-untabify}, which deletes backward treating
0110: each tab as if it were the equivalent number of spaces, so that you
0111: can delete one column of indentation without worrying whether the
0112: whitespace consists of spaces or tabs.
0113: 
0114: @cindex mode hook, and major modes
0115: @vindex c-mode-hook
0116: @vindex lisp-mode-hook
0117: @vindex emacs-lisp-mode-hook
0118: @vindex lisp-interaction-mode-hook
0119: @vindex scheme-mode-hook
0120:   Entering a programming language mode runs the custom Lisp functions
0121: specified in the hook variable @code{prog-mode-hook}, followed by
0122: those specified in the mode's own mode hook (@pxref{Major Modes}).
0123: For instance, entering C mode runs the hooks @code{prog-mode-hook} and
0124: @code{c-mode-hook}.  @xref{Hooks}, for information about hooks.
0125: 
0126: @ifnottex
0127:   Separate manuals are available for the modes for Ada (@pxref{Top,,
0128: Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
0129: IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), Octave, VHDL,
0130: and IDLWAVE (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
0131: @end ifnottex
0132: @iftex
0133:   The Emacs distribution contains Info manuals for the major modes for
0134: Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, Octave, VHDL, and
0135: IDLWAVE@.  For Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized
0136: Emacs Features}.
0137: @end iftex
0138: 
0139: @node Defuns
0140: @section Top-Level Definitions, or Defuns
0141: 
0142:   In Emacs, a major definition at the top level in the buffer, such as
0143: a function, is called a @dfn{defun}.  The name comes from Lisp, but in
0144: Emacs we use it for all languages.
0145: 
0146: @menu
0147: * Left Margin Paren::   An open-paren or similar opening delimiter
0148:                           starts a defun if it is at the left margin.
0149: * Moving by Defuns::    Commands to move over or mark a major definition.
0150: * Imenu::               Making buffer indexes as menus.
0151: * Which Function::      Which Function mode shows which function you are in.
0152: @end menu
0153: 
0154: @node Left Margin Paren
0155: @subsection Left Margin Convention
0156: 
0157: @cindex open-parenthesis in leftmost column
0158: @cindex ( in leftmost column
0159:   Many programming-language modes assume by default that any opening
0160: delimiter found at the left margin is the start of a top-level
0161: definition, or defun.  Therefore, @strong{don't put an opening
0162: delimiter at the left margin unless it should have that significance}.
0163: For instance, never put an open-parenthesis at the left margin in a
0164: Lisp file unless it is the start of a top-level list.
0165: 
0166:   The convention speeds up many Emacs operations, which would
0167: otherwise have to scan back to the beginning of the buffer to analyze
0168: the syntax of the code.
0169: 
0170:   If you don't follow this convention, not only will you have trouble
0171: when you explicitly use the commands for motion by defuns; other
0172: features that use them will also give you trouble.  This includes the
0173: indentation commands (@pxref{Program Indent}) and Font Lock mode
0174: (@pxref{Font Lock}).
0175: 
0176:   The most likely problem case is when you want an opening delimiter
0177: at the start of a line inside a string.  To avoid trouble, put an
0178: escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
0179: other Lisp dialects) before the opening delimiter.  This will not
0180: affect the contents of the string, but will prevent that opening
0181: delimiter from starting a defun.  Here's an example:
0182: 
0183: @example
0184:   (insert "Foo:
0185: \(bar)
0186: ")
0187: @end example
0188: 
0189:   To help you catch violations of this convention, Font Lock mode
0190: highlights confusing opening delimiters (those that ought to be
0191: quoted) in bold red.
0192: 
0193: @vindex open-paren-in-column-0-is-defun-start
0194:   If you need to override this convention, you can do so by setting
0195: the variable @code{open-paren-in-column-0-is-defun-start}.
0196: If this user option is set to @code{t} (the default), opening
0197: parentheses or braces at column zero always start defuns.  When it is
0198: @code{nil}, defuns are found by searching for parens or braces at the
0199: outermost level.
0200: 
0201:   Usually, you should leave this option at its default value of
0202: @code{t}.  If your buffer contains parentheses or braces in column
0203: zero which don't start defuns, and it is somehow impractical to remove
0204: these parentheses or braces, it might be helpful to set the option to
0205: @code{nil}.  Be aware that this might make scrolling and display in
0206: large buffers quite sluggish.  Furthermore, the parentheses and braces
0207: must be correctly matched throughout the buffer for it to work
0208: properly.
0209: 
0210: @node Moving by Defuns
0211: @subsection Moving by Defuns
0212: @cindex defuns
0213: 
0214:   These commands move point or set up the region based on top-level
0215: major definitions, also called @dfn{defuns}.
0216: 
0217: @table @kbd
0218: @item C-M-a
0219: Move to beginning of current or preceding defun
0220: (@code{beginning-of-defun}).
0221: @item C-M-e
0222: Move to end of current or following defun (@code{end-of-defun}).
0223: @item C-M-h
0224: Put region around whole current or following defun (@code{mark-defun}).
0225: @end table
0226: 
0227: @cindex move to beginning or end of function
0228: @cindex function, move to beginning or end
0229: @kindex C-M-a
0230: @kindex C-M-e
0231: @kindex C-M-h
0232: @findex beginning-of-defun
0233: @findex end-of-defun
0234: @findex mark-defun
0235:   The commands to move to the beginning and end of the current defun
0236: are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
0237: (@code{end-of-defun}).  If you repeat one of these commands, or use a
0238: positive numeric argument, each repetition moves to the next defun in
0239: the direction of motion.
0240: 
0241:   @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
0242: @var{n} times to the next beginning of a defun.  This is not exactly
0243: the same place that @kbd{C-M-e} with argument @var{n} would move to;
0244: the end of this defun is not usually exactly the same place as the
0245: beginning of the following defun.  (Whitespace, comments, and perhaps
0246: declarations can separate them.)  Likewise, @kbd{C-M-e} with a
0247: negative argument moves back to an end of a defun, which is not quite
0248: the same as @kbd{C-M-a} with a positive argument.
0249: 
0250: @kindex C-M-h @r{(C mode)}
0251: @findex c-mark-function
0252:   To operate on the current defun, use @kbd{C-M-h}
0253: (@code{mark-defun}), which sets the mark at the end of the current
0254: defun and puts point at its beginning.  @xref{Marking Objects}.  This
0255: is the easiest way to get ready to kill the defun in order to move it
0256: to a different place in the file.  If the defun is directly preceded
0257: by comments (with no intervening blank lines), they are marked, too.
0258: If you use the command while point is between defuns, it uses the
0259: following defun.  If you use the command while the mark is already
0260: active, it extends the end of the region to include one more defun.
0261: With a prefix argument, it marks that many defuns or extends the
0262: region by the appropriate number of defuns.  With negative prefix
0263: argument it marks defuns in the opposite direction and also changes
0264: the direction of selecting for subsequent uses of @code{mark-defun}.
0265: 
0266:   In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
0267: which is almost the same as @code{mark-defun}; the difference is that
0268: it backs up over the argument declarations, function name and returned
0269: data type so that the entire C function is inside the region.  This is
0270: an example of how major modes adjust the standard key bindings so that
0271: they do their standard jobs in a way better fitting a particular
0272: language.  Other major modes may replace any or all of these key
0273: bindings for that purpose.
0274: 
0275: @node Imenu
0276: @subsection Imenu
0277: @cindex index of buffer definitions
0278: @cindex buffer definitions index
0279: 
0280:   The Imenu facility offers a way to find the major definitions in
0281: a file by name.  It is also useful in text formatter major modes,
0282: where it treats each chapter, section, etc., as a definition.
0283: (@xref{Xref}, for a more powerful feature that handles multiple files
0284: together.)
0285: 
0286: @findex imenu
0287:   If you type @kbd{M-x imenu}, it reads the name of a definition using
0288: the minibuffer, then moves point to that definition.  You can use
0289: completion to specify the name; the command always displays the whole
0290: list of valid names.
0291: 
0292: @findex imenu-add-menubar-index
0293:   Alternatively, you can bind the command @code{imenu} to a mouse
0294: click.  Then it displays mouse menus for you to select a definition
0295: name.  You can also add the buffer's index to the menu bar by calling
0296: @code{imenu-add-menubar-index}.  If you want to have this menu bar
0297: item available for all buffers in a certain major mode, you can do
0298: this by adding @code{imenu-add-menubar-index} to its mode hook.  But
0299: if you have done that, you will have to wait a little while each time
0300: you visit a file in that mode, while Emacs finds all the definitions
0301: in that buffer.
0302: 
0303: @vindex imenu-auto-rescan
0304:   When you change the contents of a buffer, if you add or delete
0305: definitions, you can update the buffer's index based on the
0306: new contents by invoking the @samp{*Rescan*} item in the menu.
0307: Rescanning happens automatically if you set @code{imenu-auto-rescan} to
0308: a non-@code{nil} value.  There is no need to rescan because of small
0309: changes in the text.
0310: 
0311: @vindex imenu-auto-rescan-maxout
0312:   @code{imenu-auto-rescan} will be disabled in buffers that are larger
0313: than @code{imenu-auto-rescan-maxout} in bytes.
0314: 
0315: @vindex imenu-sort-function
0316:   You can customize the way the menus are sorted by setting the
0317: variable @code{imenu-sort-function}.  By default, names are ordered as
0318: they occur in the buffer; if you want alphabetic sorting, use the
0319: symbol @code{imenu--sort-by-name} as the value.  You can also
0320: define your own comparison function by writing Lisp code.
0321: 
0322:   Imenu provides the information to guide Which Function mode
0323: @ifnottex
0324: (@pxref{Which Function}).
0325: @end ifnottex
0326: @iftex
0327: (see below).
0328: @end iftex
0329: The Speedbar can also use it (@pxref{Speedbar}).
0330: 
0331: @node Which Function
0332: @subsection Which Function Mode
0333: @cindex current function name in mode line
0334: 
0335:   Which Function mode is a global minor mode (@pxref{Minor Modes})
0336: which displays the current function name in the mode line, updating it
0337: as you move around in a buffer.
0338: 
0339: @findex which-function-mode
0340: @vindex which-func-modes
0341:   To either enable or disable Which Function mode, use the command
0342: @kbd{M-x which-function-mode}.  Which Function mode is a global minor
0343: mode.  By default, it takes effect in all major modes that
0344: know how to support it (i.e., all the major modes that support
0345: Imenu).  You can restrict it to a specific list of major modes by
0346: changing the value of the variable @code{which-func-modes} from
0347: @code{t} (which means to support all available major modes) to a list
0348: of major mode names.
0349: 
0350: @node Program Indent
0351: @section Indentation for Programs
0352: @cindex indentation for programs
0353: 
0354:   The best way to keep a program properly indented is to use Emacs to
0355: reindent it as you change it.  Emacs has commands to indent either a
0356: single line, a specified number of lines, or all of the lines inside a
0357: single parenthetical grouping.
0358: 
0359:   @xref{Indentation}, for general information about indentation.  This
0360: section describes indentation features specific to programming
0361: language modes.
0362: 
0363: @menu
0364: * Basic Indent::        Indenting a single line.
0365: * Multi-line Indent::   Commands to reindent many lines at once.
0366: * Lisp Indent::         Specifying how each Lisp function should be indented.
0367: * C Indent::            Extra features for indenting C and related modes.
0368: * Custom C Indent::     Controlling indentation style for C and related modes.
0369: @end menu
0370: 
0371: @cindex pretty-printer
0372:   Emacs also provides a Lisp pretty-printer in the @code{pp} package,
0373: which reformats Lisp objects with nice-looking indentation.
0374: @xref{Output Functions, pp,, elisp, The Emacs Lisp Reference Manual}.
0375: 
0376: @node Basic Indent
0377: @subsection Basic Program Indentation Commands
0378: 
0379: @table @kbd
0380: @item @key{TAB}
0381: Adjust indentation of current line (@code{indent-for-tab-command}).
0382: @item @key{RET}
0383: Insert a newline, then adjust indentation of following line
0384: (@code{newline}).
0385: @end table
0386: 
0387: @kindex TAB @r{(programming modes)}
0388: @findex indent-line-function
0389:   The basic indentation command is @kbd{@key{TAB}}
0390: (@code{indent-for-tab-command}), which was documented in
0391: @ref{Indentation}.  In programming language modes, @kbd{@key{TAB}}
0392: indents the current line, based on the indentation and syntactic
0393: content of the preceding lines; if the region is active,
0394: @kbd{@key{TAB}} indents each line within the region, not just the
0395: current line.
0396: 
0397:   The command @kbd{@key{RET}} (@code{newline}), which was documented
0398: in @ref{Inserting Text}, does the same as @kbd{C-j} followed by
0399: @kbd{@key{TAB}}: it inserts a new line, then adjusts the line's
0400: indentation.
0401: 
0402:   When indenting a line that starts within a parenthetical grouping,
0403: Emacs usually places the start of the line under the preceding line
0404: within the group, or under the text after the parenthesis.  If you
0405: manually give one of these lines a nonstandard indentation (e.g., for
0406: aesthetic purposes), the lines below will follow it.
0407: 
0408:   The indentation commands for most programming language modes assume
0409: that an open-parenthesis, open-brace or other opening delimiter at the
0410: left margin is the start of a function.  If the code you are editing
0411: violates this assumption---even if the delimiters occur in strings or
0412: comments---you must set @code{open-paren-in-column-0-is-defun-start}
0413: to @code{nil} for indentation to work properly.  @xref{Left Margin
0414: Paren}.
0415: 
0416: @node Multi-line Indent
0417: @subsection Indenting Several Lines
0418: 
0419:   Sometimes, you may want to reindent several lines of code at a time.
0420: One way to do this is to use the mark; when the mark is active and the
0421: region is non-empty, @kbd{@key{TAB}} indents every line in the region.
0422: Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
0423: every line in the region, whether or not the mark is active
0424: (@pxref{Indentation Commands}).
0425: 
0426:   In addition, Emacs provides the following commands for indenting
0427: large chunks of code:
0428: 
0429: @table @kbd
0430: @item C-M-q
0431: Reindent all the lines within one parenthetical grouping.
0432: @item C-u @key{TAB}
0433: Shift an entire parenthetical grouping rigidly sideways so that its
0434: first line is properly indented.
0435: @item M-x indent-code-rigidly
0436: Shift all the lines in the region rigidly sideways, but do not alter
0437: lines that start inside comments and strings.
0438: @end table
0439: 
0440: @kindex C-M-q
0441: @findex indent-pp-sexp
0442:   To reindent the contents of a single parenthetical grouping,
0443: position point before the beginning of the grouping and type
0444: @kbd{C-M-q}.  This changes the relative indentation within the
0445: grouping, without affecting its overall indentation (i.e., the
0446: indentation of the line where the grouping starts).  The function that
0447: @kbd{C-M-q} runs depends on the major mode; it is
0448: @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
0449: etc.  To correct the overall indentation as well, type @kbd{@key{TAB}}
0450: first.
0451: 
0452: @kindex C-u TAB
0453:   If you like the relative indentation within a grouping but not the
0454: indentation of its first line, move point to that first line and type
0455: @kbd{C-u @key{TAB}}.  In Lisp, C, and some other major modes,
0456: @kbd{@key{TAB}} with a numeric argument reindents the current line as
0457: usual, then reindents by the same amount all the lines in the
0458: parenthetical grouping starting on the current line.  It is clever,
0459: though, and does not alter lines that start inside strings.  Neither
0460: does it alter C preprocessor lines when in C mode, but it does
0461: reindent any continuation lines that may be attached to them.
0462: 
0463: @findex indent-code-rigidly
0464:   The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
0465: lines in the region sideways, like @code{indent-rigidly} does
0466: (@pxref{Indentation Commands}).  It doesn't alter the indentation of
0467: lines that start inside a string, unless the region also starts inside
0468: that string.  The prefix arg specifies the number of columns to
0469: indent.
0470: 
0471: @node Lisp Indent
0472: @subsection Customizing Lisp Indentation
0473: @cindex customizing Lisp indentation
0474: 
0475:   The indentation pattern for a Lisp expression can depend on the function
0476: called by the expression.  For each Lisp function, you can choose among
0477: several predefined patterns of indentation, or define an arbitrary one with
0478: a Lisp program.
0479: 
0480:   The standard pattern of indentation is as follows: the second line of the
0481: expression is indented under the first argument, if that is on the same
0482: line as the beginning of the expression; otherwise, the second line is
0483: indented underneath the function name.  Each following line is indented
0484: under the previous line whose nesting depth is the same.
0485: 
0486: @vindex lisp-indent-offset
0487:   If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
0488: the usual indentation pattern for the second line of an expression, so that
0489: such lines are always indented @code{lisp-indent-offset} more columns than
0490: the containing list.
0491: 
0492: @vindex lisp-body-indent
0493:   Certain functions override the standard pattern.  Functions whose
0494: names start with @code{def} treat the second lines as the start of
0495: a @dfn{body}, by indenting the second line @code{lisp-body-indent}
0496: additional columns beyond the open-parenthesis that starts the
0497: expression.
0498: 
0499: @cindex @code{lisp-indent-function} property
0500:   You can override the standard pattern in various ways for individual
0501: functions, according to the @code{lisp-indent-function} property of
0502: the function name.  This is normally done for macro definitions, using
0503: the @code{declare} construct.  @xref{Defining Macros,,, elisp, The
0504: Emacs Lisp Reference Manual}.
0505: 
0506: @node C Indent
0507: @subsection Commands for C Indentation
0508: 
0509:   Here are special features for indentation in C mode and related modes:
0510: 
0511: @table @kbd
0512: @item C-c C-q
0513: @kindex C-c C-q @r{(C mode)}
0514: @findex c-indent-defun
0515: Reindent the current top-level function definition or aggregate type
0516: declaration (@code{c-indent-defun}).
0517: 
0518: @item C-M-q
0519: @kindex C-M-q @r{(C mode)}
0520: @findex c-indent-exp
0521: Reindent each line in the balanced expression that follows point
0522: (@code{c-indent-exp}).  A prefix argument inhibits warning messages
0523: about invalid syntax.
0524: 
0525: @item @key{TAB}
0526: @findex c-indent-command
0527: Reindent the current line, and/or in some cases insert a tab character
0528: (@code{c-indent-command}).
0529: 
0530: @vindex c-tab-always-indent
0531: If @code{c-tab-always-indent} is @code{t}, this command always reindents
0532: the current line and does nothing else.  This is the default.
0533: 
0534: If that variable is @code{nil}, this command reindents the current line
0535: only if point is at the left margin or in the line's indentation;
0536: otherwise, it inserts a tab (or the equivalent number of spaces,
0537: if @code{indent-tabs-mode} is @code{nil}).
0538: 
0539: Any other value (not @code{nil} or @code{t}) means always reindent the
0540: line, and also insert a tab if within a comment or a string.
0541: @end table
0542: 
0543:   To reindent the whole current buffer, type @kbd{C-x h C-M-\}.  This
0544: first selects the whole buffer as the region, then reindents that
0545: region.
0546: 
0547:   To reindent the current block, use @kbd{C-M-u C-M-q}.  This moves
0548: to the front of the block and then reindents it all.
0549: 
0550: @node Custom C Indent
0551: @subsection Customizing C Indentation
0552: @cindex style (for indentation)
0553: 
0554:   C mode and related modes use a flexible mechanism for customizing
0555: indentation.  C mode indents a source line in two steps: first it
0556: classifies the line syntactically according to its contents and
0557: context; second, it determines the indentation offset associated by
0558: your selected @dfn{style} with the syntactic construct and adds this
0559: onto the indentation of the @dfn{anchor statement}.
0560: 
0561: @table @kbd
0562: @item C-c . @var{style} @key{RET}
0563: Select a predefined style @var{style} (@code{c-set-style}).
0564: @end table
0565: 
0566:   A @dfn{style} is a named collection of customizations that can be
0567: used in C mode and the related modes.  @ref{Styles,,, ccmode, The CC
0568: Mode Manual}, for a complete description.  Emacs comes with several
0569: predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
0570: @code{stroustrup}, @code{linux}, @code{python}, @code{java},
0571: @code{whitesmith}, @code{ellemtel}, and @code{awk}.  Some of these
0572: styles are primarily intended for one language, but any of them can be
0573: used with any of the languages supported by these modes.  To find out
0574: what a style looks like, select it and reindent some code, e.g., by
0575: typing @kbd{C-M-q} at the start of a function definition.
0576: 
0577: @kindex C-c . @r{(C mode)}
0578: @findex c-set-style
0579:   To choose a style for the current buffer, use the command @w{@kbd{C-c
0580: .}}.  Specify a style name as an argument (case is not significant).
0581: This command affects the current buffer only, and it affects only
0582: future invocations of the indentation commands; it does not reindent
0583: the code already in the buffer.  To reindent the whole buffer in the
0584: new style, you can type @kbd{C-x h C-M-\}.
0585: 
0586: @vindex c-default-style
0587:   You can also set the variable @code{c-default-style} to specify the
0588: default style for various major modes.  Its value should be either the
0589: style's name (a string) or an alist, in which each element specifies
0590: one major mode and which indentation style to use for it.  For
0591: example,
0592: 
0593: @example
0594: (setq c-default-style
0595:       '((java-mode . "java")
0596:         (awk-mode . "awk")
0597:         (other . "gnu")))
0598: @end example
0599: 
0600: @noindent
0601: specifies explicit choices for Java and AWK modes, and the default
0602: @samp{gnu} style for the other C-like modes.  (These settings are
0603: actually the defaults.)  This variable takes effect when you select
0604: one of the C-like major modes; thus, if you specify a new default
0605: style for Java mode, you can make it take effect in an existing Java
0606: mode buffer by typing @kbd{M-x java-mode} there.
0607: 
0608:   The @code{gnu} style specifies the formatting recommended by the GNU
0609: Project for C; it is the default, so as to encourage use of our
0610: recommended style.
0611: 
0612:   @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
0613: @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
0614: information on customizing indentation for C and related modes,
0615: including how to override parts of an existing style and how to define
0616: your own styles.
0617: 
0618: @findex c-guess
0619: @findex c-guess-install
0620:   As an alternative to specifying a style, you can tell Emacs to guess
0621: a style by typing @kbd{M-x c-guess} in a sample code buffer.  You can
0622: then apply the guessed style to other buffers with @kbd{M-x
0623: c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
0624: Manual}, for details.
0625: 
0626: @node Parentheses
0627: @section Commands for Editing with Parentheses
0628: 
0629: @findex check-parens
0630: @cindex unbalanced parentheses and quotes
0631:   This section describes the commands and features that take advantage
0632: of the parenthesis structure in a program, or help you keep it
0633: balanced.
0634: 
0635:   When talking about these facilities, the term ``parenthesis'' also
0636: includes braces, brackets, or whatever delimiters are defined to match
0637: in pairs.  The major mode controls which delimiters are significant,
0638: through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
0639: The Emacs Lisp Reference Manual}).  In Lisp, only parentheses count;
0640: in C, these commands apply to braces and brackets too.
0641: 
0642:   You can use @kbd{M-x check-parens} to find any unbalanced
0643: parentheses and unbalanced string quotes in the buffer.
0644: 
0645: @menu
0646: * Expressions::         Expressions with balanced parentheses.
0647: * Moving by Parens::    Commands for moving up, down and across
0648:                           in the structure of parentheses.
0649: * Matching::            Insertion of a close-delimiter flashes matching open.
0650: @end menu
0651: 
0652: @node Expressions
0653: @subsection Expressions with Balanced Parentheses
0654: 
0655: @cindex sexp
0656: @cindex expression
0657: @cindex balanced expression
0658:   Each programming language mode has its own definition of a
0659: @dfn{balanced expression}.  Balanced expressions typically include
0660: individual symbols, numbers, and string constants, as well as pieces
0661: of code enclosed in a matching pair of delimiters.  The following
0662: commands deal with balanced expressions (in Emacs, such expressions
0663: are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
0664: is used to refer to an expression in Lisp.}).
0665: 
0666: @table @kbd
0667: @item C-M-f
0668: Move forward over a balanced expression (@code{forward-sexp}).
0669: @item C-M-b
0670: Move backward over a balanced expression (@code{backward-sexp}).
0671: @item C-M-k
0672: Kill balanced expression forward (@code{kill-sexp}).
0673: @item C-M-t
0674: Transpose expressions (@code{transpose-sexps}).
0675: @item C-M-@@
0676: @itemx C-M-@key{SPC}
0677: Put mark after following expression (@code{mark-sexp}).
0678: @end table
0679: 
0680: @kindex C-M-f
0681: @kindex C-M-b
0682: @findex forward-sexp
0683: @findex backward-sexp
0684:   To move forward over a balanced expression, use @kbd{C-M-f}
0685: (@code{forward-sexp}).  If the first significant character after point
0686: is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
0687: this command moves past the matching closing delimiter.  If the
0688: character begins a symbol, string, or number, the command moves over
0689: that.
0690: 
0691:   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
0692: balanced expression---like @kbd{C-M-f}, but in the reverse direction.
0693: If the expression is preceded by any prefix characters (single-quote,
0694: backquote and comma, in Lisp), the command moves back over them as
0695: well.
0696: 
0697:   @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
0698: the specified number of times; with a negative argument means to move
0699: in the opposite direction.  In most modes, these two commands move
0700: across comments as if they were whitespace.  Note that their keys,
0701: @kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
0702: which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
0703: @kbd{M-b}, which move by words (@pxref{Words}).
0704: 
0705: @cindex killing expressions
0706: @kindex C-M-k
0707: @findex kill-sexp
0708:   To kill a whole balanced expression, type @kbd{C-M-k}
0709: (@code{kill-sexp}).  This kills the text that @kbd{C-M-f} would move
0710: over.
0711: 
0712: @cindex transposition of expressions
0713: @kindex C-M-t
0714: @findex transpose-sexps
0715:   @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
0716: previous balanced expression and the next one.  It is analogous to the
0717: @kbd{C-t} command, which transposes characters (@pxref{Transpose}).
0718: An argument to @kbd{C-M-t} serves as a repeat count, moving the
0719: previous expression over that many following ones.  A negative
0720: argument moves the previous balanced expression backwards across those
0721: before it.  An argument of zero, rather than doing nothing, transposes
0722: the balanced expressions ending at or after point and the mark.
0723: 
0724: @kindex C-M-SPC
0725:   To operate on balanced expressions with a command which acts on the
0726: region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
0727: mark where @kbd{C-M-f} would move to.  While the mark is active, each
0728: successive call to this command extends the region by shifting the
0729: mark by one expression.  Positive or negative numeric arguments move
0730: the mark forward or backward by the specified number of expressions.
0731: The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
0732: @xref{Marking Objects}, for more information about this and related
0733: commands.
0734: 
0735:   In languages that use infix operators, such as C, it is not possible
0736: to recognize all balanced expressions because there can be multiple
0737: possibilities at a given position.  For example, C mode does not treat
0738: @samp{foo + bar} as a single expression, even though it @emph{is} one
0739: C expression; instead, it recognizes @samp{foo} as one expression and
0740: @samp{bar} as another, with the @samp{+} as punctuation between them.
0741: However, C mode recognizes @samp{(foo + bar)} as a single expression,
0742: because of the parentheses.
0743: 
0744: @node Moving by Parens
0745: @subsection Moving in the Parenthesis Structure
0746: 
0747: @cindex parenthetical groupings
0748: @cindex parentheses, moving across
0749: @cindex matching parenthesis and braces, moving to
0750: @cindex braces, moving across
0751: @cindex list commands
0752: 
0753:   The following commands move over groupings delimited by parentheses
0754: (or whatever else serves as delimiters in the language you are working
0755: with).  They ignore strings and comments, including any parentheses
0756: within them, and also ignore parentheses that are quoted with an
0757: escape character.  These commands are mainly intended for editing
0758: programs, but can be useful for editing any text containing
0759: parentheses.  They are referred to internally as ``list commands''
0760: because in Lisp these groupings are lists.
0761: 
0762:   These commands assume that the starting point is not inside a string
0763: or a comment.  If you invoke them from inside a string or comment, the
0764: results are unreliable.
0765: 
0766: @table @kbd
0767: @item C-M-n
0768: Move forward over a parenthetical group (@code{forward-list}).
0769: @item C-M-p
0770: Move backward over a parenthetical group (@code{backward-list}).
0771: @item C-M-u
0772: Move up in parenthesis structure (@code{backward-up-list}).
0773: @item C-M-d
0774: Move down in parenthesis structure (@code{down-list}).
0775: @end table
0776: 
0777: @kindex C-M-n
0778: @kindex C-M-p
0779: @findex forward-list
0780: @findex backward-list
0781:   The list commands @kbd{C-M-n} (@code{forward-list}) and
0782: @kbd{C-M-p} (@code{backward-list}) move forward or backward over one
0783: (or @var{n}) parenthetical groupings.
0784: 
0785: @kindex C-M-u
0786: @findex backward-up-list
0787:   @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
0788: parenthesis structure.  To move @emph{up} one (or @var{n}) levels, use
0789: @kbd{C-M-u} (@code{backward-up-list}).  @kbd{C-M-u} moves backward up
0790: past one unmatched opening delimiter.  A positive argument serves as a
0791: repeat count; a negative argument reverses the direction of motion, so
0792: that the command moves forward and up one or more levels.
0793: 
0794: @kindex C-M-d
0795: @findex down-list
0796:   To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
0797: (@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
0798: delimiter, this is nearly the same as searching for a @samp{(}.  An
0799: argument specifies the number of levels to go down.
0800: 
0801: @node Matching
0802: @subsection Matching Parentheses
0803: @cindex matching parentheses
0804: @cindex parentheses, displaying matches
0805: 
0806:   Emacs has a number of @dfn{parenthesis matching} features, which
0807: make it easy to see how and whether parentheses (or other delimiters)
0808: match up.
0809: 
0810:   Whenever you type a self-inserting character that is a closing
0811: delimiter, Emacs briefly indicates the location of the matching
0812: opening delimiter, provided that is on the screen.  If it is not on
0813: the screen, Emacs displays some of the text near it in the echo area.
0814: Either way, you can tell which grouping you are closing off.  If the
0815: opening delimiter and closing delimiter are mismatched---such as in
0816: @samp{[x)}---a warning message is displayed in the echo area.
0817: 
0818: @vindex blink-matching-paren
0819: @vindex blink-matching-paren-distance
0820: @vindex blink-matching-delay
0821:   Three variables control the display of matching parentheses:
0822: 
0823: @itemize @bullet
0824: @item
0825: @code{blink-matching-paren} turns the feature on or off: @code{nil}
0826: disables it, but the default is @code{t} to enable it.  Set it to
0827: @code{jump} to make indication work by momentarily moving the cursor
0828: to the matching opening delimiter.  Set it to @code{jump-offscreen} to
0829: make the cursor jump, even if the opening delimiter is off screen.
0830: 
0831: @item
0832: @code{blink-matching-delay} says how many seconds to keep indicating
0833: the matching opening delimiter.  This may be an integer or
0834: floating-point number; the default is 1.
0835: 
0836: @item
0837: @code{blink-matching-paren-distance} specifies how many characters
0838: back to search to find the matching opening delimiter.  If the match
0839: is not found in that distance, Emacs stops scanning and nothing is
0840: displayed.  The default is 102400.
0841: @end itemize
0842: 
0843: @cindex Show Paren mode
0844: @cindex highlighting matching parentheses
0845: @findex show-paren-mode
0846:   Show Paren mode, a global minor mode, provides a more powerful kind
0847: of automatic matching.  Whenever point is before an opening delimiter
0848: or after a closing delimiter, the delimiter, its matching delimiter,
0849: and optionally the text between them are highlighted.  To toggle Show
0850: Paren mode, type @kbd{M-x show-paren-mode}.  To customize it, type
0851: @kbd{M-x customize-group @key{RET} paren-showing}.  The customizable
0852: options which control the operation of this mode include:
0853: 
0854: @itemize @bullet
0855: @item
0856: @vindex show-paren-highlight-openparen
0857: @code{show-paren-highlight-openparen} controls whether to highlight
0858: an open paren when point stands just before it, and hence its position
0859: is marked by the cursor anyway.  The default is non-@code{nil} (yes).
0860: 
0861: @item
0862: @vindex show-paren-style
0863: @code{show-paren-style} controls whether just the two parens, or also
0864: the space between them get highlighted.  The valid options here are
0865: @code{parenthesis} (show the matching paren), @code{expression}
0866: (highlight the entire expression enclosed by the parens), and
0867: @code{mixed} (highlight the matching paren if it is visible, the
0868: expression otherwise).
0869: 
0870: @item
0871: @vindex show-paren-when-point-inside-paren
0872: @code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
0873: highlighting also when point is on the inside of a parenthesis.
0874: 
0875: @item
0876: @vindex show-paren-when-point-in-periphery
0877: @code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes
0878: highlighting also when point is in whitespace at the beginning or end
0879: of a line, and there is a paren at, respectively, the first or last,
0880: or the last, non-whitespace position on the line.
0881: @end itemize
0882: 
0883: @cindex Electric Pair mode
0884: @cindex inserting matching parentheses
0885: @findex electric-pair-mode
0886:   Electric Pair mode, a global minor mode, provides a way to easily
0887: insert matching delimiters: parentheses, braces, brackets, etc.
0888: Whenever you insert an opening delimiter, the matching closing
0889: delimiter is automatically inserted as well, leaving point between the
0890: two.  Conversely, when you insert a closing delimiter over an existing
0891: one, no insertion takes places, and that position is simply skipped
0892: over.  If the region is active (@pxref{Mark}), insertion of a
0893: delimiter operates on the region: the characters in the region are
0894: enclosed in a pair of matching delimiters, leaving point after the
0895: delimiter you typed.
0896: 
0897: These variables control additional features of Electric Pair mode:
0898: 
0899: @itemize @bullet
0900: @item
0901: @vindex electric-pair-preserve-balance
0902: @code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
0903: default pairing logic balance out the number of opening and closing
0904: delimiters.
0905: 
0906: @item
0907: @vindex electric-pair-delete-adjacent-pairs
0908: @code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
0909: backspacing between two adjacent delimiters also automatically delete
0910: the closing delimiter.
0911: 
0912: @item
0913: @vindex electric-pair-open-newline-between-pairs
0914: @code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
0915: makes inserting a newline between two adjacent pairs also
0916: automatically open an extra newline after point.
0917: 
0918: @item
0919: @vindex electric-pair-skip-whitespace
0920: @code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
0921: mode to skip whitespace forward before deciding whether to skip over
0922: the closing delimiter.
0923: @end itemize
0924: 
0925: To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.  To
0926: toggle the mode in a single buffer, use @kbd{M-x
0927: electric-pair-local-mode}.
0928: 
0929: @node Comments
0930: @section Manipulating Comments
0931: @cindex comments
0932: 
0933:   Because comments are such an important part of programming, Emacs
0934: provides special commands for editing and inserting comments.  It can
0935: also do spell checking on comments with Flyspell Prog mode
0936: (@pxref{Spelling}).
0937: 
0938:   Some major modes have special rules for indenting different kinds of
0939: comments.  For example, in Lisp code, comments starting with two
0940: semicolons are indented as if they were lines of code, while those
0941: starting with three semicolons are supposed to be aligned to the left
0942: margin and are often used for sectioning purposes.  Emacs understands
0943: these conventions; for instance, typing @kbd{@key{TAB}} on a comment
0944: line will indent the comment to the appropriate position.
0945: 
0946: @example
0947: ;; This function is just an example.
0948: ;;; Here either two or three semicolons are appropriate.
0949: (defun foo (x)
0950: ;;;  And now, the first part of the function:
0951:   ;; The following line adds one.
0952:   (1+ x))           ; This line adds one.
0953: @end example
0954: 
0955: @menu
0956: * Comment Commands::    Inserting, killing, and aligning comments.
0957: * Multi-Line Comments:: Commands for adding and editing multi-line comments.
0958: * Options for Comments::Customizing the comment features.
0959: @end menu
0960: 
0961: @node Comment Commands
0962: @subsection Comment Commands
0963: @cindex indentation for comments
0964: @cindex alignment for comments
0965: 
0966:   The following commands operate on comments:
0967: 
0968: @table @asis
0969: @item @kbd{M-;}
0970: Insert or realign comment on current line; if the region is active,
0971: comment or uncomment the region instead (@code{comment-dwim}).
0972: @item @kbd{C-x C-;}
0973: Comment or uncomment the current line (@code{comment-line}).  If the
0974: region is active, comment or uncomment the lines in the region
0975: instead.
0976: @item @kbd{C-u M-;}
0977: Kill comment on current line (@code{comment-kill}).
0978: @item @kbd{C-x ;}
0979: Set comment column (@code{comment-set-column}).
0980: @item @kbd{C-M-j}
0981: @itemx @kbd{M-j}
0982: Like @kbd{@key{RET}} followed by inserting and aligning a comment
0983: (@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
0984: @item @kbd{M-x comment-region}
0985: @itemx @kbd{C-c C-c} (in C-like modes)
0986: Add comment delimiters to all the lines in the region.
0987: @end table
0988: 
0989: @kindex M-;
0990: @findex comment-dwim
0991:   The command to create or align a comment is @kbd{M-;}
0992: (@code{comment-dwim}).  The word ``dwim'' is an acronym for ``Do What
0993: I Mean''; it indicates that this command can be used for many
0994: different jobs relating to comments, depending on the situation where
0995: you use it.
0996: 
0997:   When a region is active (@pxref{Mark}), @kbd{M-;} either adds
0998: comment delimiters to the region, or removes them.  If every line in
0999: the region is already a comment, it uncomments each of those lines
1000: by removing their comment delimiters.  Otherwise, it adds comment
1001: delimiters to enclose the text in the region.
1002: 
1003:   If you supply a prefix argument to @kbd{M-;} when a region is
1004: active, that specifies the number of comment delimiters to add or
1005: delete.  A positive argument @var{n} adds @var{n} delimiters, while a
1006: negative argument @var{-n} removes @var{n} delimiters.
1007: 
1008:   If the region is not active, and there is no existing comment on the
1009: current line, @kbd{M-;} adds a new comment to the current line.  If
1010: the line is blank (i.e., empty or containing only whitespace
1011: characters), the comment is indented to the same position where
1012: @kbd{@key{TAB}} would indent to (@pxref{Basic Indent}).  If the line
1013: is non-blank, the comment is placed after the last non-whitespace
1014: character on the line.  Emacs tries to fit the comment between the
1015: columns specified by the variables @code{comment-column} and
1016: @code{comment-fill-column} (@pxref{Options for Comments}), if
1017: possible.  Otherwise, it will choose some other suitable position,
1018: usually separated from the non-comment text by at least one space.  In
1019: each case, Emacs places point after the comment's starting delimiter,
1020: so that you can start typing the comment text right away.
1021: 
1022:   You can also use @kbd{M-;} to align an existing comment.  If a line
1023: already contains the comment-start string, @kbd{M-;} realigns it to
1024: the conventional alignment and moves point after the comment's
1025: starting delimiter.  As an exception, comments starting in column 0
1026: are not moved.  Even when an existing comment is properly aligned,
1027: @kbd{M-;} is still useful for moving directly to the start of the
1028: comment text.
1029: 
1030: @findex comment-line
1031: @kindex C-x C-;
1032:   @kbd{C-x C-;} (@code{comment-line}) comments or uncomments complete
1033: lines.  When a region is active (@pxref{Mark}), @kbd{C-x C-;} either
1034: comments or uncomments the lines in the region.  If the region is not
1035: active, this command comments or uncomments the line point is on.
1036: With a positive prefix argument @var{n}, it operates on @var{n} lines
1037: starting with the current one; with a negative @var{n}, it affects
1038: @var{n} preceding lines.  After invoking this command with a negative
1039: argument, successive invocations with a positive argument will operate
1040: on preceding lines as if the argument were negated.
1041: 
1042: @findex comment-kill
1043: @kindex C-u M-;
1044:   @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
1045: comment on the current line, along with the whitespace before it.
1046: Since the comment is saved to the kill ring, you can reinsert it on
1047: another line by moving to the end of that line, doing @kbd{C-y}, and
1048: then @kbd{M-;} to realign the comment.  You can achieve the same
1049: effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
1050: (@code{comment-dwim} actually calls @code{comment-kill} as a
1051: subroutine when it is given a prefix argument).
1052: 
1053: @kindex C-c C-c @r{(C mode)}
1054: @findex comment-region
1055: @findex uncomment-region
1056:   The command @kbd{M-x comment-region} is equivalent to calling
1057: @kbd{M-;} on an active region, except that it always acts on the
1058: region, even if the mark is inactive.  In C mode and related modes,
1059: this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
1060: uncomment-region} uncomments each line in the region; a numeric prefix
1061: argument specifies the number of comment delimiters to remove
1062: (negative arguments specify the number of comment delimiters to add).
1063: 
1064:   For C-like modes, you can configure the exact effect of @kbd{M-;} by
1065: setting the variables @code{c-indent-comment-alist} and
1066: @code{c-indent-comments-syntactically-p}.  For example, on a line
1067: ending in a closing brace, @kbd{M-;} puts the comment one space after
1068: the brace rather than at @code{comment-column}.  For full details see
1069: @ref{Comment Commands,,, ccmode, The CC Mode Manual}.
1070: 
1071: @node Multi-Line Comments
1072: @subsection Multiple Lines of Comments
1073: 
1074: @kindex C-M-j
1075: @kindex M-j
1076: @cindex blank lines in programs
1077: @findex comment-indent-new-line
1078: @vindex comment-multi-line
1079:   If you are typing a comment and wish to continue it to another line,
1080: type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}).  This
1081: breaks the current line, and inserts the necessary comment delimiters
1082: and indentation to continue the comment.
1083: 
1084:   For languages with closing comment delimiters (e.g., @samp{*/} in
1085: C), the exact behavior of @kbd{M-j} depends on the value of the
1086: variable @code{comment-multi-line}.  If the value is @code{nil}, the
1087: command closes the comment on the old line and starts a new comment on
1088: the new line.  Otherwise, it opens a new line within the current
1089: comment delimiters.
1090: 
1091:   When Auto Fill mode is on, going past the fill column while typing a
1092: comment also continues the comment, in the same way as an explicit
1093: invocation of @kbd{M-j}.
1094: 
1095:   To turn existing lines into comment lines, use @kbd{M-;} with the
1096: region active, or use @kbd{M-x comment-region}
1097: @ifinfo
1098: (@pxref{Comment Commands}).
1099: @end ifinfo
1100: @ifnotinfo
1101: as described in the preceding section.
1102: @end ifnotinfo
1103: 
1104:   You can configure C Mode such that when you type a @samp{/} at the
1105: start of a line in a multi-line block comment, this closes the
1106: comment.  Enable the @code{comment-close-slash} clean-up for this.
1107: @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
1108: 
1109: @node Options for Comments
1110: @subsection Options Controlling Comments
1111: 
1112: @vindex comment-column
1113: @vindex comment-fill-column
1114: @kindex C-x ;
1115: @findex comment-set-column
1116:   As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
1117: adds a comment to a line, it tries to place the comment between the
1118: columns specified by the buffer-local variables @code{comment-column}
1119: and @code{comment-fill-column} (or if that is @code{nil}, then the
1120: value of @code{fill-column}, @pxref{Fill Commands}).  You can set
1121: either the local value or the default value of these buffer-local
1122: variables in the usual way (@pxref{Locals}).  Alternatively, you can
1123: type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
1124: @code{comment-column} in the current buffer to the column where point
1125: is currently located.  @kbd{C-u C-x ;} sets the comment column to
1126: match the last comment before point in the buffer, and then does a
1127: @kbd{M-;} to align the current line's comment under the previous one.
1128: 
1129: @vindex comment-start-skip
1130:   The comment commands recognize comments based on the regular
1131: expression that is the value of the variable @code{comment-start-skip}.
1132: Make sure this regexp does not match the null string.  It may match more
1133: than the comment starting delimiter in the strictest sense of the word;
1134: for example, in C mode the value of the variable is
1135: @c This stops M-q from breaking the line inside that @code.
1136: @code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
1137: spaces after the @samp{/*} itself, and accepts C++ style comments
1138: also.  (Note that @samp{\\} is needed in Lisp syntax to include a
1139: @samp{\} in the string, which is needed to deny the first star its
1140: special meaning in regexp syntax.  @xref{Regexp Backslash}.)
1141: 
1142: @vindex comment-start
1143: @vindex comment-end
1144:   When a comment command makes a new comment, it inserts the value of
1145: @code{comment-start} as an opening comment delimiter.  It also inserts
1146: the value of @code{comment-end} after point, as a closing comment
1147: delimiter.  For example, in Lisp mode, @code{comment-start} is
1148: @samp{";"} and @code{comment-end} is @code{""} (the empty string).  In
1149: C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
1150: @code{" */"}.
1151: 
1152: @vindex comment-padding
1153:   The variable @code{comment-padding} specifies a string that the
1154: commenting commands should insert between the comment delimiter(s) and
1155: the comment text.  The default, @samp{" "}, specifies a single space.
1156: Alternatively, the value can be a number, which specifies that number
1157: of spaces, or @code{nil}, which means no spaces at all.
1158: 
1159:   The variable @code{comment-multi-line} controls how @kbd{M-j} and
1160: Auto Fill mode continue comments over multiple lines.
1161: @xref{Multi-Line Comments}.
1162: 
1163: @vindex comment-indent-function
1164:   The variable @code{comment-indent-function} should contain a function
1165: that will be called to compute the alignment for a newly inserted
1166: comment or for aligning an existing comment.  It is set differently by
1167: various major modes.  The function is called with no arguments, but with
1168: point at the beginning of the comment, or at the end of a line if a new
1169: comment is to be inserted.  It should return the column in which the
1170: comment ought to start.  For example, the default function bases its
1171: decision on how many comment characters begin an existing comment.
1172: 
1173: Emacs also tries to align comments on adjacent lines.  To override
1174: this, the function may return a cons of two (possibly equal) integers
1175: to indicate an acceptable range of indentation.
1176: 
1177: @node Documentation
1178: @section Documentation Lookup
1179: 
1180:   Emacs provides several features you can use to look up the
1181: documentation of functions, variables and commands that you plan to
1182: use in your program.
1183: 
1184: @menu
1185: * Info Lookup::         Looking up library functions and commands in Info files.
1186: * Man Page::            Looking up man pages of library functions and commands.
1187: * Lisp Doc::            Looking up Emacs Lisp functions, etc.
1188: @end menu
1189: 
1190: @node Info Lookup
1191: @subsection Info Documentation Lookup
1192: 
1193: @findex info-lookup-file
1194:   For major modes that apply to languages which have documentation in
1195: Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
1196: Info documentation for a symbol used in the program.  You specify the
1197: symbol with the minibuffer; the default is the symbol appearing in the
1198: buffer at point.  For example, in C mode this looks for the symbol in
1199: the C Library Manual.  The command only works if the appropriate
1200: manual's Info files are installed.
1201: 
1202:   Emacs determines where to look for documentation for the
1203: symbol---which Info files to look in, and which indices to
1204: search---based on the major mode.  You can also use @kbd{M-x
1205: info-lookup-file} to look for documentation for a file name.
1206: 
1207:   If you use @kbd{C-h S} in a major mode that does not support it,
1208: it asks you to specify the symbol help mode.  You should enter
1209: a command such as @code{c-mode} that would select a major
1210: mode which @kbd{C-h S} does support.
1211: 
1212: @node Man Page
1213: @subsection Man Page Lookup
1214: 
1215: @cindex man page
1216:   On Unix, the main form of on-line documentation was the @dfn{manual
1217: page} or @dfn{man page}.  In the GNU operating system, we aim to
1218: replace man pages with better-organized manuals that you can browse
1219: with Info (@pxref{Misc Help}).  This process is not finished, so it is
1220: still useful to read manual pages.
1221: 
1222: @findex man
1223:   You can read the man page for an operating system command, library
1224: function, or system call, with the @kbd{M-x man} command.  This
1225: prompts for a topic, with completion (@pxref{Completion}), and runs
1226: the @command{man} program to format the corresponding man page.  If
1227: the system permits, it runs @command{man} asynchronously, so that you
1228: can keep on editing while the page is being formatted.  The result
1229: goes in a buffer named @file{*Man @var{topic}*}.  These buffers use a
1230: special major mode, Man mode, that facilitates scrolling and jumping
1231: to other manual pages.  For details, type @kbd{C-h m} while in a Man
1232: mode buffer.
1233: 
1234: @cindex sections of manual pages
1235:   Each man page belongs to one of ten or more @dfn{sections}, each
1236: named by a digit or by a digit and a letter.  Sometimes there are man
1237: pages with the same name in different sections.  To read a man page
1238: from a specific section, type @samp{@var{topic}(@var{section})} or
1239: @samp{@var{section} @var{topic}} when @kbd{M-x man} prompts for the
1240: topic.  For example, the man page for the C library function
1241: @code{chmod} is in section 2, but there is a shell command of the same
1242: name, whose man page is in section 1; to view the former, type
1243: @w{@kbd{M-x man @key{RET} chmod(2) @key{RET}}}.
1244: 
1245: @vindex Man-switches
1246: @kindex M-n @r{(Man mode)}
1247: @kindex M-p @r{(Man mode)}
1248:   If you do not specify a section, @kbd{M-x man} normally displays
1249: only the first man page found.  On some systems, the @code{man}
1250: program accepts a @samp{-a} command-line option, which tells it to
1251: display all the man pages for the specified topic.  To make use of
1252: this, change the value of the variable @code{Man-switches} to
1253: @samp{"-a"}.  Then, in the Man mode buffer, you can type @kbd{M-n} and
1254: @kbd{M-p} to switch between man pages in different sections.  The mode
1255: line shows how many manual pages are available.
1256: 
1257: @findex woman
1258: @cindex manual pages, on MS-DOS/MS-Windows
1259:   An alternative way of reading manual pages is the @kbd{M-x woman}
1260: command.  Unlike @kbd{M-x man}, it does not run any external programs
1261: to format and display the man pages; the formatting is done by Emacs,
1262: so it works on systems such as MS-Windows where the @command{man}
1263: program may be unavailable.  It prompts for a man page, and displays
1264: it in a buffer named @file{*WoMan @var{section} @var{topic}}.
1265: 
1266:   @kbd{M-x woman} computes the completion list for manpages the first
1267: time you invoke the command.  With a numeric argument, it recomputes
1268: this list; this is useful if you add or delete manual pages.
1269: 
1270:   If you type a name of a manual page and @kbd{M-x woman} finds that
1271: several manual pages by the same name exist in different sections, it
1272: pops up a window with possible candidates asking you to choose one of
1273: them.
1274: 
1275:   Note that @kbd{M-x woman} doesn't yet support the latest features of
1276: modern man pages, so we recommend using @kbd{M-x man} if that is
1277: available on your system.
1278: 
1279:   For more information about setting up and using @kbd{M-x woman}, see
1280: @ifinfo
1281: @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
1282: WoMan Manual}.
1283: @end ifinfo
1284: @ifnotinfo
1285: the WoMan Info manual, which is distributed with Emacs.
1286: @end ifnotinfo
1287: 
1288: @node Lisp Doc
1289: @subsection Emacs Lisp Documentation Lookup
1290: 
1291:   When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
1292: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
1293: to view the built-in documentation for the Lisp functions and
1294: variables that you want to use.  @xref{Name Help}.
1295: 
1296: @cindex Eldoc mode
1297: @findex eldoc-mode
1298: @findex global-eldoc-mode
1299:   Eldoc is a buffer-local minor mode that helps with looking up Lisp
1300: documentation.  When it is enabled, the echo area displays some useful
1301: information whenever there is a Lisp function or variable at point;
1302: for a function, it shows the argument list, and for a variable it
1303: shows the first line of the variable's documentation string.  To
1304: toggle Eldoc mode, type @kbd{M-x eldoc-mode}.  There's also a Global
1305: Eldoc mode, which is turned on by default, and affects buffers, such
1306: as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp
1307: Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally).
1308: 
1309: @node Hideshow
1310: @section Hideshow minor mode
1311: @cindex Hideshow mode
1312: @cindex mode, Hideshow
1313: 
1314: @findex hs-minor-mode
1315:   Hideshow mode is a buffer-local minor mode that allows you to
1316: selectively display portions of a program, which are referred to as
1317: @dfn{blocks}.  Type @kbd{M-x hs-minor-mode} to toggle this minor mode
1318: (@pxref{Minor Modes}).
1319: 
1320:   When you use Hideshow mode to hide a block, the block disappears
1321: from the screen, to be replaced by an ellipsis (three periods in a
1322: row).  Just what constitutes a block depends on the major mode.  In C
1323: mode and related modes, blocks are delimited by braces, while in Lisp
1324: mode they are delimited by parentheses.  Multi-line comments also
1325: count as blocks.
1326: 
1327:   Hideshow mode provides the following commands:
1328: 
1329: @findex hs-hide-all
1330: @findex hs-hide-block
1331: @findex hs-show-all
1332: @findex hs-show-block
1333: @findex hs-show-region
1334: @findex hs-hide-level
1335: @kindex C-c @@ C-h
1336: @kindex C-c @@ C-s
1337: @kindex C-c @@ C-M-h
1338: @kindex C-c @@ C-M-s
1339: @kindex C-c @@ C-r
1340: @kindex C-c @@ C-l
1341: @kindex S-mouse-2
1342: @table @kbd
1343: @item C-c @@ C-h
1344: @itemx C-c @@ C-d
1345: Hide the current block (@code{hs-hide-block}).
1346: @item C-c @@ C-s
1347: Show the current block (@code{hs-show-block}).
1348: @item C-c @@ C-c
1349: @itemx C-x @@ C-e
1350: Either hide or show the current block (@code{hs-toggle-hiding}).
1351: @item S-mouse-2
1352: Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
1353: @item C-c @@ C-M-h
1354: @itemx C-c @@ C-t
1355: Hide all top-level blocks (@code{hs-hide-all}).
1356: @item C-c @@ C-M-s
1357: @itemx C-c @@ C-a
1358: Show all blocks in the buffer (@code{hs-show-all}).
1359: @item C-u @var{n} C-c @@ C-l
1360: Hide all blocks @var{n} levels below this block
1361: (@code{hs-hide-level}).
1362: @end table
1363: 
1364: @vindex hs-hide-comments-when-hiding-all
1365: @vindex hs-isearch-open
1366: @vindex hs-special-modes-alist
1367:   These variables can be used to customize Hideshow mode:
1368: 
1369: @table @code
1370: @item hs-hide-comments-when-hiding-all
1371: If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
1372: comments too.
1373: 
1374: @item hs-isearch-open
1375: This variable specifies the conditions under which incremental search
1376: should unhide a hidden block when matching text occurs within the
1377: block.  Its value should be either @code{code} (unhide only code
1378: blocks), @code{comment} (unhide only comments), @code{t} (unhide both
1379: code blocks and comments), or @code{nil} (unhide neither code blocks
1380: nor comments).  The default value is @code{code}.
1381: @end table
1382: 
1383: @node Symbol Completion
1384: @section Completion for Symbol Names
1385: @cindex completion (symbol names)
1386: 
1387:   Completion is normally done in the minibuffer (@pxref{Completion}),
1388: but you can also complete symbol names in ordinary Emacs buffers.
1389: 
1390: @kindex M-TAB
1391: @kindex C-M-i
1392:   In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
1393: to complete the partial symbol before point.  On graphical displays,
1394: the @kbd{M-@key{TAB}} key is usually reserved by the window manager
1395: for switching graphical windows, so you should type @kbd{C-M-i} or
1396: @kbd{@key{ESC} @key{TAB}} instead.
1397: 
1398: @cindex tags-based completion
1399: @findex completion-at-point@r{, in programming language modes}
1400: @cindex Lisp symbol completion
1401: @cindex completion (Lisp symbols)
1402:   In most programming language modes, @kbd{C-M-i} (or
1403: @kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
1404: which generates its completion list in a flexible way.  If Semantic
1405: mode is enabled, it tries to use the Semantic parser data for
1406: completion (@pxref{Semantic}).  If Semantic mode is not enabled or
1407: fails at performing completion, it tries to complete using the
1408: selected tags table (@pxref{Tags Tables}).  If in Emacs Lisp mode, it
1409: performs completion using the function, variable, or property names
1410: defined in the current Emacs session.
1411: 
1412:   In all other respects, in-buffer symbol completion behaves like
1413: minibuffer completion.  For instance, if Emacs cannot complete to a
1414: unique symbol, it displays a list of completion alternatives in
1415: another window.  @xref{Completion}.
1416: 
1417:   In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1418: based on the spell-checker's dictionary.  @xref{Spelling}.
1419: 
1420: @node MixedCase Words
1421: @section MixedCase Words
1422: @cindex camel case
1423: 
1424:   Some programming styles make use of mixed-case (or ``CamelCase'')
1425: symbols like @samp{unReadableSymbol}.  (In the GNU project, we recommend
1426: using underscores to separate words within an identifier, rather than
1427: using case distinctions.)  Emacs has various features to make it easier
1428: to deal with such symbols.
1429: 
1430: @cindex Glasses mode
1431: @cindex mode, Glasses
1432:   Glasses mode is a buffer-local minor mode that makes it easier to read
1433: such symbols, by altering how they are displayed.  By default, it
1434: displays extra underscores between each lower-case letter and the
1435: following capital letter.  This does not alter the buffer text, only how
1436: it is displayed.
1437: 
1438:   To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
1439: Modes}).  When Glasses mode is enabled, the minor mode indicator
1440: @samp{o^o} appears in the mode line.  For more information about
1441: Glasses mode, type @kbd{C-h P glasses @key{RET}}.
1442: 
1443: @cindex Subword mode
1444: @findex subword-mode
1445:   Subword mode is another buffer-local minor mode.  In subword mode,
1446: Emacs's word commands recognize upper case letters in
1447: @samp{StudlyCapsIdentifiers} as word boundaries.  When Subword mode is
1448: enabled, the minor mode indicator @samp{,} appears in the mode line.
1449: See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
1450: 
1451: @node Semantic
1452: @section Semantic
1453: @cindex Semantic package
1454: 
1455: Semantic is a package that provides language-aware editing commands
1456: based on @code{source code parsers}.  This section provides a brief
1457: description of Semantic; for full details,
1458: @ifnottex
1459: see @ref{Top, Semantic,, semantic, Semantic}.
1460: @end ifnottex
1461: @iftex
1462: see the Semantic Info manual, which is distributed with Emacs.
1463: @end iftex
1464: 
1465:   Most of the language-aware features in Emacs, such as Font Lock
1466: mode (@pxref{Font Lock}), rely on rules of thumb@footnote{Regular
1467: expressions and syntax tables.} that usually give good results but are
1468: never completely exact.  In contrast, the parsers used by Semantic
1469: have an exact understanding of programming language syntax.  This
1470: allows Semantic to provide search, navigation, and completion commands
1471: that are powerful and precise.
1472: 
1473: @cindex Semantic mode
1474: @cindex mode, Semantic
1475:   To begin using Semantic, type @kbd{M-x semantic-mode} or click on
1476: the menu item named @samp{Source Code Parsers (Semantic)} in the
1477: @samp{Tools} menu.  This enables Semantic mode, a global minor mode.
1478: 
1479:    When Semantic mode is enabled, Emacs automatically attempts to
1480: parse each file you visit.  Currently, Semantic understands C, C++,
1481: HTML, Java, Javascript, Make, Python, Scheme, SRecode, and Texinfo.
1482: Within each parsed buffer, the following commands are available:
1483: 
1484: @table @kbd
1485: @item C-c , j
1486: @kindex C-c , j
1487: Prompt for the name of a function defined in the current file, and
1488: move point there (@code{semantic-complete-jump-local}).
1489: 
1490: @item C-c , J
1491: @kindex C-c , J
1492: Prompt for the name of a function defined in any file Emacs has
1493: parsed, and move point there (@code{semantic-complete-jump}).
1494: 
1495: @item C-c , @key{SPC}
1496: @kindex C-c , SPC
1497: Display a list of possible completions for the symbol at point
1498: (@code{semantic-complete-analyze-inline}).  This also activates a set
1499: of special key bindings for choosing a completion: @kbd{@key{RET}}
1500: accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
1501: possible completions, @kbd{@key{TAB}} completes as far as possible and
1502: then cycles, and @kbd{C-g} or any other key aborts completion.
1503: 
1504: @item C-c , l
1505: @kindex C-c , l
1506: Display a list of the possible completions of the symbol at point, in
1507: another window (@code{semantic-analyze-possible-completions}).
1508: @end table
1509: 
1510: @noindent
1511: In addition to the above commands, the Semantic package provides a
1512: variety of other ways to make use of parser information.  For
1513: instance, you can use it to display a list of completions when Emacs
1514: is idle.
1515: @ifnottex
1516: @xref{Top, Semantic,, semantic, Semantic}, for details.
1517: @end ifnottex
1518: 
1519: @node Misc for Programs
1520: @section Other Features Useful for Editing Programs
1521: 
1522:   Some Emacs commands that aren't designed specifically for editing
1523: programs are useful for that nonetheless.
1524: 
1525:   The Emacs commands that operate on words, sentences and paragraphs
1526: are useful for editing code.  Most symbol names contain words
1527: (@pxref{Words}), while sentences can be found in strings and comments
1528: (@pxref{Sentences}).  As for paragraphs, they are defined in most
1529: programming language modes to begin and end at blank lines
1530: (@pxref{Paragraphs}).  Therefore, judicious use of blank lines to make
1531: the program clearer will also provide useful chunks of text for the
1532: paragraph commands to work on.  Auto Fill mode, if enabled in a
1533: programming language major mode, indents the new lines which it
1534: creates.
1535: 
1536: @findex superword-mode
1537:  Superword mode is a buffer-local minor mode that causes editing and
1538: motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
1539: When Superword mode is enabled, the minor mode indicator
1540: @iftex
1541: @samp{@math{^2}}
1542: @end iftex
1543: @ifnottex
1544: @samp{²}
1545: @end ifnottex
1546: appears in the mode line.  See also the similar @code{subword-mode}
1547: (@pxref{MixedCase Words}).
1548: 
1549: @findex electric-layout-mode
1550:   Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
1551: minor mode that automatically inserts newlines when you type certain
1552: characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript
1553: mode.
1554: 
1555:   Apart from Hideshow mode (@pxref{Hideshow}), another way to
1556: selectively display parts of a program is to use the selective display
1557: feature (@pxref{Selective Display}).  Programming modes often also
1558: support Outline minor mode (@pxref{Outline Mode}), which can be used
1559: with the Foldout package (@pxref{Foldout}).
1560: 
1561: @ifinfo
1562:   The automatic typing features may be useful for writing programs.
1563: @xref{Top,,Autotyping, autotype, Autotyping}.
1564: @end ifinfo
1565: 
1566: @findex prettify-symbols-mode
1567:   Prettify Symbols mode is a buffer-local minor mode that replaces
1568: certain strings with more attractive versions for display purposes.
1569: For example, in Emacs Lisp mode, it replaces the string @samp{lambda}
1570: with the Greek lambda character @samp{λ}.  In a @TeX{} buffer, it will
1571: replace @samp{\alpha} @dots{} @samp{\omega} and other math macros with
1572: their Unicode characters.  You may wish to use this in non-programming
1573: modes as well.  You can customize the mode by adding more entries to
1574: @code{prettify-symbols-alist}.  More elaborate customization is
1575: available via customizing @code{prettify-symbols-compose-predicate} if
1576: its default value @code{prettify-symbols-default-compose-p} is not
1577: appropriate.  There is also a global version,
1578: @code{global-prettify-symbols-mode}, which enables the mode in all
1579: buffers that support it.
1580: 
1581:   The symbol at point can be shown in its original form.  This is
1582: controlled by the variable @code{prettify-symbols-unprettify-at-point}:
1583: if non-@code{nil}, the original form of symbol at point will be
1584: restored for as long as point is at it.
1585: 
1586: 
1587: @node C Modes
1588: @section C and Related Modes
1589: @cindex C mode
1590: @cindex Java mode
1591: @cindex Pike mode
1592: @cindex IDL mode
1593: @cindex CORBA IDL mode
1594: @cindex Objective C mode
1595: @cindex C++ mode
1596: @cindex AWK mode
1597: @cindex mode, Java
1598: @cindex mode, C
1599: @cindex mode, C++
1600: @cindex mode, Objective C
1601: @cindex mode, CORBA IDL
1602: @cindex mode, Pike
1603: @cindex mode, AWK
1604: 
1605:   This section gives a brief description of the special features
1606: available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
1607: (These are called ``C mode and related modes''.)
1608: @ifinfo
1609: @xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
1610: @end ifinfo
1611: @ifnotinfo
1612: For more details, see the CC mode Info manual, which is distributed
1613: with Emacs.
1614: @end ifnotinfo
1615: 
1616: @menu
1617: * Motion in C::                 Commands to move by C statements, etc.
1618: * Electric C::                  Colon and other chars can automatically reindent.
1619: * Hungry Delete::               A more powerful DEL command.
1620: * Other C Commands::            Filling comments, viewing expansion of macros,
1621:                                 and other neat features.
1622: @end menu
1623: 
1624: @node Motion in C
1625: @subsection C Mode Motion Commands
1626: 
1627:   This section describes commands for moving point, in C mode and
1628: related modes.
1629: 
1630: @table @code
1631: @item C-M-a
1632: @itemx C-M-e
1633: @findex c-beginning-of-defun
1634: @findex c-end-of-defun
1635: Move point to the beginning or end of the current function or
1636: top-level definition.  In languages with enclosing scopes (such as
1637: C++'s classes) the @dfn{current function} is the immediate one,
1638: possibly inside a scope.  Otherwise it is the one defined by the least
1639: enclosing braces.  (By contrast, @code{beginning-of-defun} and
1640: @code{end-of-defun} search for braces in column zero.)  @xref{Moving
1641: by Defuns}.
1642: 
1643: @item C-c C-u
1644: @kindex C-c C-u @r{(C mode)}
1645: @findex c-up-conditional
1646: Move point back to the containing preprocessor conditional, leaving the
1647: mark behind.  A prefix argument acts as a repeat count.  With a negative
1648: argument, move point forward to the end of the containing
1649: preprocessor conditional.
1650: 
1651: @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
1652: the function will stop at a @samp{#elif} when going backward, but not
1653: when going forward.
1654: 
1655: @item C-c C-p
1656: @kindex C-c C-p @r{(C mode)}
1657: @findex c-backward-conditional
1658: Move point back over a preprocessor conditional, leaving the mark
1659: behind.  A prefix argument acts as a repeat count.  With a negative
1660: argument, move forward.
1661: 
1662: @item C-c C-n
1663: @kindex C-c C-n @r{(C mode)}
1664: @findex c-forward-conditional
1665: Move point forward across a preprocessor conditional, leaving the mark
1666: behind.  A prefix argument acts as a repeat count.  With a negative
1667: argument, move backward.
1668: 
1669: @item M-a
1670: @kindex M-a @r{(C mode)}
1671: @findex c-beginning-of-statement
1672: Move point to the beginning of the innermost C statement
1673: (@code{c-beginning-of-statement}).  If point is already at the beginning
1674: of a statement, move to the beginning of the preceding statement.  With
1675: prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
1676: 
1677: In comments or in strings which span more than one line, this command
1678: moves by sentences instead of statements.
1679: 
1680: @item M-e
1681: @kindex M-e @r{(C mode)}
1682: @findex c-end-of-statement
1683: Move point to the end of the innermost C statement or sentence; like
1684: @kbd{M-a} except that it moves in the other direction
1685: (@code{c-end-of-statement}).
1686: @end table
1687: 
1688: @node Electric C
1689: @subsection Electric C Characters
1690: 
1691:   In C mode and related modes, certain printing characters are
1692: @dfn{electric}---in addition to inserting themselves, they also
1693: reindent the current line, and optionally also insert newlines.  The
1694: electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
1695: @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
1696: @kbd{)}.
1697: 
1698:   You might find electric indentation inconvenient if you are editing
1699: chaotically indented code.  If you are new to CC Mode, you might find
1700: it disconcerting.  You can toggle electric action with the command
1701: @kbd{C-c C-l}; when it is enabled, @samp{/@var{c}l} appears in the
1702: mode line after the mode name (where @var{c}, if present, is @samp{*}
1703: or @samp{/}, depending on whether the comment style is block or line).
1704: @xref{Minor Modes,,, ccmode, The CC Mode Manual}, for more about
1705: mode-line indicators in CC Mode.
1706: 
1707: @table @kbd
1708: @item C-c C-l
1709: @kindex C-c C-l @r{(C mode)}
1710: @findex c-toggle-electric-state
1711: Toggle electric action (@code{c-toggle-electric-state}).  With a
1712: positive prefix argument, this command enables electric action, with a
1713: negative one it disables it.
1714: @end table
1715: 
1716:   Electric characters insert newlines only when, in addition to the
1717: electric state, the @dfn{auto-newline} feature is enabled (indicated
1718: by @samp{/@var{c}la} in the mode line after the mode name).  You can
1719: turn this feature on or off with the command @kbd{C-c C-a}:
1720: 
1721: @table @kbd
1722: @item C-c C-a
1723: @kindex C-c C-a @r{(C mode)}
1724: @findex c-toggle-auto-newline
1725: Toggle the auto-newline feature (@code{c-toggle-auto-newline}).  With a
1726: prefix argument, this command turns the auto-newline feature on if the
1727: argument is positive, and off if it is negative.
1728: @end table
1729: 
1730:   Usually the CC Mode style configures the exact circumstances in
1731: which Emacs inserts auto-newlines.  You can also configure this
1732: directly.  @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
1733: 
1734: @node Hungry Delete
1735: @subsection Hungry Delete Feature in C
1736: @cindex hungry deletion (C Mode)
1737: 
1738:   If you want to delete an entire block of whitespace at point, you
1739: can use @dfn{hungry deletion}.  This deletes all the contiguous
1740: whitespace either before point or after point in a single operation.
1741: @dfn{Whitespace} here includes tabs and newlines, but not comments or
1742: preprocessor commands.
1743: 
1744: @table @kbd
1745: @item C-c C-@key{DEL}
1746: @itemx C-c @key{DEL}
1747: @findex c-hungry-delete-backwards
1748: @kindex C-c C-DEL @r{(C Mode)}
1749: @kindex C-c DEL @r{(C Mode)}
1750: Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).
1751: 
1752: @item C-c C-d
1753: @itemx C-c C-@key{Delete}
1754: @itemx C-c @key{Delete}
1755: @findex c-hungry-delete-forward
1756: @kindex C-c C-d @r{(C Mode)}
1757: @kindex C-c C-Delete @r{(C Mode)}
1758: @kindex C-c Delete @r{(C Mode)}
1759: Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
1760: @end table
1761: 
1762:   As an alternative to the above commands, you can enable @dfn{hungry
1763: delete mode}.  When this feature is enabled (indicated by @samp{h}
1764: after a @samp{/} in the mode line after the mode name), a single
1765: @kbd{@key{DEL}} deletes all preceding whitespace, not just one space,
1766: and a single @kbd{C-d} (but @emph{not} plain @kbd{@key{Delete}})
1767: deletes all following whitespace.
1768: 
1769: @table @kbd
1770: @item M-x c-toggle-hungry-state
1771: @findex c-toggle-hungry-state
1772: Toggle the hungry-delete feature
1773: (@code{c-toggle-hungry-state}).  With a prefix argument,
1774: this command turns the hungry-delete feature on if the argument is
1775: positive, and off if it is negative.
1776: @end table
1777: 
1778: @vindex c-hungry-delete-key
1779:    The variable @code{c-hungry-delete-key} controls whether the
1780: hungry-delete feature is enabled.
1781: 
1782: @node Other C Commands
1783: @subsection Other Commands for C Mode
1784: 
1785: @table @kbd
1786: @item M-x c-context-line-break
1787: @findex c-context-line-break
1788: This command inserts a line break and indents the new line in a manner
1789: appropriate to the context.  In normal code, it does the work of
1790: @kbd{@key{RET}} (@code{newline}), in a C preprocessor line it additionally
1791: inserts a @samp{\} at the line break, and within comments it's like
1792: @kbd{M-j} (@code{c-indent-new-comment-line}).
1793: 
1794: @code{c-context-line-break} isn't bound to a key by default, but it
1795: needs a binding to be useful.  The following code will bind it to
1796: @kbd{@key{RET}}.  We use @code{c-initialization-hook} here to make
1797: sure the keymap is loaded before we try to change it.
1798: 
1799: @example
1800: (defun my-bind-clb ()
1801:   (define-key c-mode-base-map "\C-m"
1802:               'c-context-line-break))
1803: (add-hook 'c-initialization-hook 'my-bind-clb)
1804: @end example
1805: 
1806: @item C-M-h
1807: Put mark at the end of a function definition, and put point at the
1808: beginning (@code{c-mark-function}).
1809: 
1810: @item M-q
1811: @kindex M-q @r{(C mode)}
1812: @findex c-fill-paragraph
1813: Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
1814: If any part of the current line is a comment or within a comment, this
1815: command fills the comment or the paragraph of it that point is in,
1816: preserving the comment indentation and comment delimiters.
1817: 
1818: @item C-c C-e
1819: @cindex macro expansion in C
1820: @cindex expansion of C macros
1821: @findex c-macro-expand
1822: @kindex C-c C-e @r{(C mode)}
1823: Run the C preprocessor on the text in the region, and show the result,
1824: which includes the expansion of all the macro calls
1825: (@code{c-macro-expand}).  The buffer text before the region is also
1826: included in preprocessing, for the sake of macros defined there, but the
1827: output from this part isn't shown.
1828: 
1829: When you are debugging C code that uses macros, sometimes it is hard to
1830: figure out precisely how the macros expand.  With this command, you
1831: don't have to figure it out; you can see the expansions.
1832: 
1833: @item C-c C-\
1834: @findex c-backslash-region
1835: @kindex C-c C-\ @r{(C mode)}
1836: Insert or align @samp{\} characters at the ends of the lines of the
1837: region (@code{c-backslash-region}).  This is useful after writing or
1838: editing a C macro definition.
1839: 
1840: If a line already ends in @samp{\}, this command adjusts the amount of
1841: whitespace before it.  Otherwise, it inserts a new @samp{\}.  However,
1842: the last line in the region is treated specially; no @samp{\} is
1843: inserted on that line, and any @samp{\} there is deleted.
1844: 
1845: @item M-x cpp-highlight-buffer
1846: @cindex preprocessor highlighting
1847: @findex cpp-highlight-buffer
1848: Highlight parts of the text according to its preprocessor conditionals.
1849: This command displays another buffer named @file{*CPP Edit*}, which
1850: serves as a graphic menu for selecting how to display particular kinds
1851: of conditionals and their contents.  After changing various settings,
1852: click on @samp{[A]pply these settings} (or go to that buffer and type
1853: @kbd{a}) to rehighlight the C mode buffer accordingly.
1854: 
1855: @item C-c C-s
1856: @findex c-show-syntactic-information
1857: @kindex C-c C-s @r{(C mode)}
1858: Display the syntactic information about the current source line
1859: (@code{c-show-syntactic-information}).  This information directs how
1860: the line is indented.
1861: 
1862: @item M-x cwarn-mode
1863: @itemx M-x global-cwarn-mode
1864: @findex cwarn-mode
1865: @findex global-cwarn-mode
1866: @vindex global-cwarn-mode
1867: @cindex CWarn mode
1868: @cindex suspicious constructions in C, C++
1869: CWarn minor mode highlights certain suspicious C and C++ constructions:
1870: 
1871: @itemize @bullet{}
1872: @item
1873: Assignments inside expressions.
1874: @item
1875: Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
1876: (except after a @samp{do @dots{} while} statement);
1877: @item
1878: C++ functions with reference parameters.
1879: @end itemize
1880: 
1881: @noindent
1882: You can enable the mode for one buffer with the command @kbd{M-x
1883: cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
1884: global-cwarn-mode} or by customizing the variable
1885: @code{global-cwarn-mode}.  You must also enable Font Lock mode to make
1886: it work.
1887: 
1888: @item M-x hide-ifdef-mode
1889: @findex hide-ifdef-mode
1890: @cindex Hide-ifdef mode
1891: @vindex hide-ifdef-shadow
1892: Hide-ifdef minor mode hides selected code within @samp{#if} and
1893: @samp{#ifdef} preprocessor blocks.  If you change the variable
1894: @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
1895: shadows preprocessor blocks by displaying them with a less
1896: prominent face, instead of hiding them entirely.  See the
1897: documentation string of @code{hide-ifdef-mode} for more information.
1898: 
1899: @item M-x ff-find-related-file
1900: @cindex related files
1901: @findex ff-find-related-file
1902: @vindex ff-related-file-alist
1903: Find a file related in a special way to the file visited by the
1904: current buffer.  Typically this will be the header file corresponding
1905: to a C/C++ source file, or vice versa.  The variable
1906: @code{ff-related-file-alist} specifies how to compute related file
1907: names.
1908: @end table
1909: 
1910: @node Asm Mode
1911: @section Asm Mode
1912: 
1913: @cindex Asm mode
1914: @cindex assembler mode
1915: Asm mode is a major mode for editing files of assembler code.  It
1916: defines these commands:
1917: 
1918: @table @kbd
1919: @item @key{TAB}
1920: @code{tab-to-tab-stop}.
1921: @c FIXME: Maybe this should be consistent with other programming modes.
1922: 
1923: @item C-j
1924: Insert a newline and then indent using @code{tab-to-tab-stop}.
1925: 
1926: @item :
1927: Insert a colon and then remove the indentation from before the label
1928: preceding colon.  Then do @code{tab-to-tab-stop}.
1929: 
1930: @item ;
1931: Insert or align a comment.
1932: @end table
1933: 
1934:   The variable @code{asm-comment-char} specifies which character
1935: starts comments in assembler syntax.
1936: 
1937: @ifnottex
1938: @include fortran-xtra.texi
1939: @end ifnottex
1940: