programs.texi 71.3 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
3
@c   2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
4 5 6 7 8 9 10
@c See file emacs.texi for copying conditions.
@node Programs, Building, Text, Top
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing

Richard M. Stallman's avatar
Richard M. Stallman committed
11 12
  Emacs provides many features to facilitate editing programs.  Some
of these features can
Dave Love's avatar
#  
Dave Love committed
13 14 15

@itemize @bullet
@item
16
Find or move over top-level definitions (@pxref{Defuns}).
Dave Love's avatar
#  
Dave Love committed
17
@item
18 19
Apply the usual indentation conventions of the language
(@pxref{Program Indent}).
Dave Love's avatar
#  
Dave Love committed
20
@item
21
Balance parentheses (@pxref{Parentheses}).
22
@item
23 24
Insert, kill or align comments (@pxref{Comments}).
@item
25
Highlight program syntax (@pxref{Font Lock}).
Dave Love's avatar
#  
Dave Love committed
26 27
@end itemize

Richard M. Stallman's avatar
Richard M. Stallman committed
28 29
  This chapter describes these features and many more.

Dave Love's avatar
#  
Dave Love committed
30 31
@menu
* Program Modes::       Major modes for editing programs.
32 33
* Defuns::              Commands to operate on major top-level parts
                          of a program.
Dave Love's avatar
#  
Dave Love committed
34
* Program Indent::      Adjusting indentation to show the nesting.
35
* Parentheses::         Commands that operate on parentheses.
36
* Comments::	        Inserting, killing, and aligning comments.
37
* Documentation::       Getting documentation of functions you plan to call.
38
* Hideshow::            Displaying blocks selectively.
39
* Symbol Completion::   Completion on symbol names of your program or language.
40
* Glasses::             Making identifiersLikeThis more readable.
41
* Misc for Programs::   Other Emacs features useful for editing programs.
Francesco Potortì's avatar
etags:  
Francesco Potortì committed
42
* C Modes::             Special commands of C, C++, Objective-C,
Dave Love's avatar
#  
Dave Love committed
43
                          Java, and Pike modes.
44
* Asm Mode::            Asm mode and its special features.
Dave Love's avatar
#  
Dave Love committed
45 46 47 48 49
@end menu

@node Program Modes
@section Major Modes for Programming Languages
@cindex modes for programming languages
50 51 52 53 54

  Emacs has specialized major modes for various programming languages.
@xref{Major Modes}.  A programming language major mode typically
specifies the syntax of expressions, the customary rules for
indentation, how to do syntax highlighting for the language, and how
Richard M. Stallman's avatar
Richard M. Stallman committed
55 56
to find the beginning of a function definition.  It often customizes
or provides facilities for compiling and debugging programs as well.
57 58 59 60 61 62

  Ideally, Emacs should provide a major mode for each programming
language that you might want to edit; if it doesn't have a mode for
your favorite language, you can contribute one.  But often the mode
for one language can serve for other syntactically similar languages.
The major mode for language @var{l} is called @code{@var{l}-mode},
Richard M. Stallman's avatar
Richard M. Stallman committed
63
and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
64 65
@xref{Choosing Modes}.

Dave Love's avatar
#  
Dave Love committed
66 67 68 69 70
@cindex Perl mode
@cindex Icon mode
@cindex Makefile mode
@cindex Tcl mode
@cindex CPerl mode
Dave Love's avatar
Dave Love committed
71 72 73 74 75
@cindex DSSSL mode
@cindex Octave mode
@cindex Metafont mode
@cindex Modula2 mode
@cindex Prolog mode
76
@cindex Python mode
Dave Love's avatar
Dave Love committed
77 78 79 80
@cindex Simula mode
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
81 82
@cindex Delphi mode
@cindex PostScript mode
83 84
@cindex Conf mode
@cindex DNS mode
85 86
  The existing programming language major modes include Lisp, Scheme (a
variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
87
ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
88 89
format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
companion for font creation), Modula2, Objective-C, Octave, Pascal,
90 91 92
Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL.  An
alternative mode for Perl is called CPerl mode.  Modes are available for
the scripting languages of the common GNU and Unix shells, VMS DCL, and
93
MS-DOS/MS-Windows @samp{BAT} files.  There are also major modes for
94 95
editing makefiles, DNS master files, and various sorts of configuration
files.
Dave Love's avatar
#  
Dave Love committed
96 97

@kindex DEL @r{(programming modes)}
98
@findex c-electric-backspace
99 100
  In most programming languages, indentation should vary from line to
line to illustrate the structure of the program.  So the major modes
Richard M. Stallman's avatar
Richard M. Stallman committed
101 102 103 104 105 106
for programming languages arrange for @key{TAB} to update the
indentation of the current line.  They also rebind @key{DEL} to treat
a tab as if it were the equivalent number of spaces; this lets you
delete one column of indentation without worrying whether the
whitespace consists of spaces or tabs.  Use @kbd{C-b C-d} to delete a
tab character before point, in these modes.
Dave Love's avatar
#  
Dave Love committed
107

108
  Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
109
Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
110
(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
111 112
(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).  For Fortran
mode, @inforef{Fortran,, emacs-xtra}.
113

Dave Love's avatar
#  
Dave Love committed
114 115 116 117 118 119
@cindex mode hook
@vindex c-mode-hook
@vindex lisp-mode-hook
@vindex emacs-lisp-mode-hook
@vindex lisp-interaction-mode-hook
@vindex scheme-mode-hook
120 121 122 123 124 125 126
  Turning on a major mode runs a normal hook called the @dfn{mode
hook}, which is the value of a Lisp variable.  Each major mode has a
mode hook, and the hook's name is always made from the mode command's
name by adding @samp{-hook}.  For example, turning on C mode runs the
hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
@code{lisp-mode-hook}.  The purpose of the mode hook is to give you a
place to set up customizations for that major mode.  @xref{Hooks}.
Dave Love's avatar
#  
Dave Love committed
127

128 129
@node Defuns
@section Top-Level Definitions, or Defuns
Dave Love's avatar
#  
Dave Love committed
130

131 132 133
  In Emacs, a major definition at the top level in the buffer,
something like a function, is called a @dfn{defun}.  The name comes
from Lisp, but in Emacs we use it for all languages.
Dave Love's avatar
#  
Dave Love committed
134

135 136 137 138 139 140 141
@menu
* Left Margin Paren::   An open-paren or similar opening delimiter
                          starts a defun if it is at the left margin.
* Moving by Defuns::    Commands to move over or mark a major definition.
* Imenu::               Making buffer indexes as menus.
* Which Function::      Which Function mode shows which function you are in.
@end menu
Dave Love's avatar
#  
Dave Love committed
142

143 144
@node Left Margin Paren
@subsection Left Margin Convention
Dave Love's avatar
#  
Dave Love committed
145

146 147
@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
148 149 150 151 152 153 154 155
  Emacs assumes by default that any opening delimiter found at the
left margin is the start of a top-level definition, or defun.  You can
override this default by setting this user option:

@defvar open-paren-in-column-0-is-defun-start
If this user option is set to @code{t} (the default), opening
parentheses or braces at column zero always start defuns.  When it's
@code{nil}, defuns are found by searching for parens or braces at the
156 157 158
outermost level.  Some major modes, including C and related modes, set
@code{open-paren-in-column-0-is-defun-start} buffer-locally to
@code{nil}
159 160
@end defvar

161
  In modes where @code{open-paren-in-column-0-is-defun-start} is
162 163
@code{t}, @strong{don't put an opening delimiter at the left margin
unless it is a defun start}.  For instance, never put an
164
open-parenthesis at the left margin in a Lisp file unless it is the
165
start of a top-level list.
166 167 168 169 170 171 172 173 174

  If you don't follow this convention, not only will you have trouble
when you explicitly use the commands for motion by defuns; other
features that use them will also give you trouble.  This includes
the indentation commands (@pxref{Program Indent}) and Font Lock
mode (@pxref{Font Lock}).

  The most likely problem case is when you want an opening delimiter
at the start of a line inside a string.  To avoid trouble, put an
175 176 177 178
escape character (@samp{\}, in Emacs Lisp, @samp{/} in some other Lisp
dialects) before the opening delimiter.  This will not affect the
contents of the string, but will prevent that opening delimiter from
starting a defun.  Here's an example:
Dave Love's avatar
#  
Dave Love committed
179

180 181 182 183 184
@example
  (insert "Foo:
\(bar)
")
@end example
Dave Love's avatar
#  
Dave Love committed
185

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

190 191 192 193 194 195 196
  In the earliest days, the original Emacs found defuns by moving
upward a level of parentheses or braces until there were no more
levels to go up.  This always required scanning all the way back to
the beginning of the buffer, even for a small function.  To speed up
the operation, we changed Emacs to assume that any opening delimiter
at the left margin is the start of a defun.  This heuristic is nearly
always right, and avoids the need to scan back to the beginning of the
197
buffer.  However, now that modern computers are so powerful, this
198
scanning is rarely slow enough to annoy, so we've provided a way to
199
disable the heuristic.
200 201 202

@node Moving by Defuns
@subsection Moving by Defuns
Dave Love's avatar
#  
Dave Love committed
203 204
@cindex defuns

205 206
  These commands move point or set up the region based on top-level
major definitions, also called @dfn{defuns}.
207

Dave Love's avatar
#  
Dave Love committed
208 209 210 211 212 213 214 215 216 217
@table @kbd
@item C-M-a
Move to beginning of current or preceding defun
(@code{beginning-of-defun}).
@item C-M-e
Move to end of current or following defun (@code{end-of-defun}).
@item C-M-h
Put region around whole current or following defun (@code{mark-defun}).
@end table

218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235
@cindex move to beginning or end of function
@cindex function, move to beginning or end
@kindex C-M-a
@kindex C-M-e
@kindex C-M-h
@findex beginning-of-defun
@findex end-of-defun
@findex mark-defun
  The commands to move to the beginning and end of the current defun
are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
(@code{end-of-defun}).  If you repeat one of these commands, or use a
positive numeric argument, each repetition moves to the next defun in
the direction of motion.

  @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
@var{n} times to the next beginning of a defun.  This is not exactly
the same place that @kbd{C-M-e} with argument @var{n} would move to;
the end of this defun is not usually exactly the same place as the
236 237 238 239
beginning of the following defun.  (Whitespace, comments, and perhaps
declarations can separate them.)  Likewise, @kbd{C-M-e} with a
negative argument moves back to an end of a defun, which is not quite
the same as @kbd{C-M-a} with a positive argument.
240

241
@kindex C-M-h @r{(C mode)}
Dave Love's avatar
#  
Dave Love committed
242
@findex c-mark-function
243 244
  To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
which puts point at the beginning and mark at the end of the current
245 246 247
defun.  This is the easiest way to get ready to kill the defun in
order to move it to a different place in the file.  If you use the
command while point is between defuns, it uses the following defun.
248
Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode
Richard M. Stallman's avatar
Richard M. Stallman committed
249 250
when the mark is active, extends the end of the region to include one
more defun each time.
251 252 253 254

  In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
which is almost the same as @code{mark-defun}; the difference is that
it backs up over the argument declarations, function name and returned
Richard M. Stallman's avatar
Richard M. Stallman committed
255 256 257 258 259
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.
Dave Love's avatar
#  
Dave Love committed
260

261 262
@node Imenu
@subsection Imenu
Richard M. Stallman's avatar
Richard M. Stallman committed
263 264
@cindex index of buffer definitions
@cindex buffer definitions index
265 266
@cindex tags

Pavel Janík's avatar
Pavel Janík committed
267
  The Imenu facility offers a way to find the major definitions in
268 269
a file by name.  It is also useful in text formatter major modes,
where it treats each chapter, section, etc., as a definition.
Richard M. Stallman's avatar
Richard M. Stallman committed
270
(@xref{Tags}, for a more powerful feature that handles multiple files
271
together.)
272 273

@findex imenu
274
  If you type @kbd{M-x imenu}, it reads the name of a definition using
Richard M. Stallman's avatar
Richard M. Stallman committed
275 276 277
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.
278

279
@findex imenu-add-menubar-index
280
  Alternatively, you can bind the command @code{imenu} to a mouse
Richard M. Stallman's avatar
Richard M. Stallman committed
281 282 283 284 285
click.  Then it displays mouse menus for you to select a definition
name.  You can also add the buffer's index to the menu bar by calling
@code{imenu-add-menubar-index}.  If you want to have this menu bar
item available for all buffers in a certain major mode, you can do
this by adding @code{imenu-add-menubar-index} to its mode hook.  But
Richard M. Stallman's avatar
Richard M. Stallman committed
286 287 288
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.
289 290 291

@vindex imenu-auto-rescan
  When you change the contents of a buffer, if you add or delete
Richard M. Stallman's avatar
Richard M. Stallman committed
292
definitions, you can update the buffer's index based on the
293
new contents by invoking the @samp{*Rescan*} item in the menu.
Eli Zaretskii's avatar
Eli Zaretskii committed
294 295
Rescanning happens automatically if you set @code{imenu-auto-rescan} to
a non-@code{nil} value.  There is no need to rescan because of small
Richard M. Stallman's avatar
Richard M. Stallman committed
296
changes in the text.
297 298

@vindex imenu-sort-function
299
  You can customize the way the menus are sorted by setting the
Richard M. Stallman's avatar
Richard M. Stallman committed
300
variable @code{imenu-sort-function}.  By default, names are ordered as
301 302 303
they occur in the buffer; if you want alphabetic sorting, use the
symbol @code{imenu--sort-by-name} as the value.  You can also
define your own comparison function by writing Lisp code.
304 305 306 307 308 309 310 311 312 313 314 315

  Imenu provides the information to guide Which Function mode
@ifnottex
(@pxref{Which Function}).
@end ifnottex
@iftex
(see below).
@end iftex
The Speedbar can also use it (@pxref{Speedbar}).

@node Which Function
@subsection Which Function Mode
316
@cindex current function name in mode line
317 318 319 320 321 322 323 324 325

  Which Function mode is a minor mode that displays the current
function name in the mode line, updating it as you move around in a
buffer.

@findex which-function-mode
@vindex which-func-modes
  To enable (or disable) Which Function mode, use the command @kbd{M-x
which-function-mode}.  This command is global; it applies to all
326
buffers, both existing ones and those yet to be created.  However, it
327
takes effect only in certain major modes, those listed in the value of
328 329 330
@code{which-func-modes}.  If the value is @code{t}, then Which Function
mode applies to all major modes that know how to support it---in other
words, all the major modes that support Imenu.
Dave Love's avatar
#  
Dave Love committed
331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348

@node Program Indent
@section Indentation for Programs
@cindex indentation for programs

  The best way to keep a program properly indented is to use Emacs to
reindent it as you change it.  Emacs has commands to indent properly
either a single line, a specified number of lines, or all of the lines
inside a single parenthetical grouping.

@menu
* Basic Indent::	Indenting a single line.
* Multi-line Indent::   Commands to reindent many lines at once.
* Lisp Indent::		Specifying how each Lisp function should be indented.
* C Indent::		Extra features for indenting C and related modes.
* Custom C Indent::	Controlling indentation style for C and related modes.
@end menu

349
@cindex pretty-printer
Dave Love's avatar
#  
Dave Love committed
350 351 352 353 354 355
  Emacs also provides a Lisp pretty-printer in the library @code{pp}.
This program reformats a Lisp object with indentation chosen to look nice.

@node Basic Indent
@subsection Basic Program Indentation Commands

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

Dave Love's avatar
#  
Dave Love committed
359 360 361 362
@table @kbd
@item @key{TAB}
Adjust indentation of current line.
@item C-j
363 364
Insert a newline, then adjust indentation of following line
(@code{newline-and-indent}).
Dave Love's avatar
#  
Dave Love committed
365 366 367
@end table

@kindex TAB @r{(programming modes)}
368 369
@findex c-indent-command
@findex indent-line-function
370
@findex indent-for-tab-command
Dave Love's avatar
#  
Dave Love committed
371 372
  The basic indentation command is @key{TAB}, which gives the current line
the correct indentation as determined from the previous lines.  The
373
function that @key{TAB} runs depends on the major mode; it is
374
@code{lisp-indent-line}
375
in Lisp mode, @code{c-indent-command} in C mode, etc.  These functions
376 377
understand the syntax and conventions of different languages, but they all do
conceptually the same job: @key{TAB} in any programming-language major mode
Dave Love's avatar
#  
Dave Love committed
378
inserts or deletes whitespace at the beginning of the current line,
379 380 381
independent of where point is in the line.  If point was inside the
whitespace at the beginning of the line, @key{TAB} puts it at the end of
that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
Dave Love's avatar
#  
Dave Love committed
382 383
the characters around it.

384
  Use @kbd{C-q @key{TAB}} to insert a tab character at point.
Dave Love's avatar
#  
Dave Love committed
385 386 387

@kindex C-j
@findex newline-and-indent
388
  When entering lines of new code, use @kbd{C-j}
389 390 391 392
(@code{newline-and-indent}), which inserts a newline and then adjusts
indentation after it.  Thus, @kbd{C-j} at the end of a line creates a
blank line with appropriate indentation.  In programming language
modes, it is equivalent to @key{RET} @key{TAB}.
Dave Love's avatar
#  
Dave Love committed
393

394 395 396 397 398 399 400
  @key{TAB} indents a line that starts within a parenthetical grouping
under the preceding line within the grouping, or the text after the
parenthesis.  Therefore, if you manually give one of these lines a
nonstandard indentation, the lines below will tend to follow it.  This
behavior is convenient in cases where you have overridden the standard
result of @key{TAB} because you find it unaesthetic for a particular
line.
Dave Love's avatar
#  
Dave Love committed
401

Richard M. Stallman's avatar
Richard M. Stallman committed
402
  In some modes, an open-parenthesis, open-brace or other opening
403 404 405 406 407 408 409
delimiter at the left margin is assumed by Emacs (including the
indentation routines) to be the start of a function.  This speeds up
indentation commands.  If you will be editing text which contains
opening delimiters in column zero that aren't the beginning of a
functions, even inside strings or comments, you must set
@code{open-paren-in-column-0-is-defun-start}.  @xref{Left Margin
Paren}, for more information on this.
Dave Love's avatar
#  
Dave Love committed
410

411
  Normally, lines are indented with tabs and spaces.  If you want Emacs
Luc Teirlinck's avatar
Luc Teirlinck committed
412
to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}).
413

Dave Love's avatar
#  
Dave Love committed
414 415 416
@node Multi-line Indent
@subsection Indenting Several Lines

417 418 419
  When you wish to reindent several lines of code which have been
altered or moved to a different level in the parenthesis structure,
you have several commands available.
Dave Love's avatar
#  
Dave Love committed
420 421 422

@table @kbd
@item C-M-q
423
Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}).
Richard M. Stallman's avatar
Richard M. Stallman committed
424 425
@item C-M-\
Reindent all lines in the region (@code{indent-region}).
Dave Love's avatar
#  
Dave Love committed
426
@item C-u @key{TAB}
427 428
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.
429 430 431
@item M-x indent-code-rigidly
Shift all the lines in the region rigidly sideways, but do not alter
lines that start inside comments and strings.
Dave Love's avatar
#  
Dave Love committed
432 433 434
@end table

@kindex C-M-q
435
@findex indent-pp-sexp
436 437
  You can reindent the contents of a single parenthetical grouping by
positioning point before the beginning of it and typing @kbd{C-M-q}
438
(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
439
bound to other suitable commands in other modes).  The indentation of
440
the line where the grouping starts is not changed; therefore this
441 442
changes only the relative indentation within the grouping, not its
overall indentation.  To correct that as well, type @key{TAB} first.
Dave Love's avatar
#  
Dave Love committed
443

Richard M. Stallman's avatar
Richard M. Stallman committed
444 445 446 447 448
  Another way to specify the range to be reindented is with the
region.  The command @kbd{C-M-\} (@code{indent-region}) applies
@key{TAB} to every line whose first character is between point and
mark.

Dave Love's avatar
#  
Dave Love committed
449
@kindex C-u TAB
450 451
  If you like the relative indentation within a grouping, but not the
indentation of its first line, you can type @kbd{C-u @key{TAB}} to
452 453 454 455 456
reindent the whole grouping as a rigid unit.  (This works in Lisp
modes and C and related modes.)  @key{TAB} with a numeric argument
reindents the current line as usual, then reindents by the same amount
all the lines in the parenthetical grouping starting on the current
line.  It is clever, though, and does not alter lines that start
457 458 459
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.
Dave Love's avatar
#  
Dave Love committed
460

461
@findex indent-code-rigidly
Richard M. Stallman's avatar
Richard M. Stallman committed
462 463 464 465
  You can also perform this operation on the region, using the command
@kbd{M-x indent-code-rigidly}.  It rigidly shifts all the lines in the
region sideways, like @code{indent-rigidly} does (@pxref{Indentation
Commands}).  It doesn't alter the indentation of lines that start
466
inside a string, unless the region also starts inside that string.
467
The prefix arg specifies the number of columns to indent.
Dave Love's avatar
#  
Dave Love committed
468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490

@node Lisp Indent
@subsection Customizing Lisp Indentation
@cindex customizing Lisp indentation

  The indentation pattern for a Lisp expression can depend on the function
called by the expression.  For each Lisp function, you can choose among
several predefined patterns of indentation, or define an arbitrary one with
a Lisp program.

  The standard pattern of indentation is as follows: the second line of the
expression is indented under the first argument, if that is on the same
line as the beginning of the expression; otherwise, the second line is
indented underneath the function name.  Each following line is indented
under the previous line whose nesting depth is the same.

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

@vindex lisp-body-indent
491
  Certain functions override the standard pattern.  Functions whose
Pavel Janík's avatar
Pavel Janík committed
492
names start with @code{def} treat the second lines as the start of
493 494 495
a @dfn{body}, by indenting the second line @code{lisp-body-indent}
additional columns beyond the open-parenthesis that starts the
expression.
Dave Love's avatar
#  
Dave Love committed
496

497
@cindex @code{lisp-indent-function} property
498
  You can override the standard pattern in various ways for individual
499 500 501 502
functions, according to the @code{lisp-indent-function} property of
the function name.  Normally you would use this for macro definitions
and specify it using the @code{declare} construct (@pxref{Defining
Macros,,, elisp, the Emacs Lisp Reference Manual}).
Dave Love's avatar
#  
Dave Love committed
503 504 505 506

@node C Indent
@subsection Commands for C Indentation

507
  Here are special features for indentation in C mode and related modes:
Dave Love's avatar
#  
Dave Love committed
508 509 510 511 512 513 514 515 516 517 518 519

@table @code
@item C-c C-q
@kindex C-c C-q @r{(C mode)}
@findex c-indent-defun
Reindent the current top-level function definition or aggregate type
declaration (@code{c-indent-defun}).

@item C-M-q
@kindex C-M-q @r{(C mode)}
@findex c-indent-exp
Reindent each line in the balanced expression that follows point
520 521
(@code{c-indent-exp}).  A prefix argument inhibits warning messages
about invalid syntax.
Dave Love's avatar
#  
Dave Love committed
522 523 524 525 526 527

@item @key{TAB}
@findex c-indent-command
Reindent the current line, and/or in some cases insert a tab character
(@code{c-indent-command}).

528
@vindex c-tab-always-indent
Dave Love's avatar
#  
Dave Love committed
529 530 531 532 533 534 535 536 537
If @code{c-tab-always-indent} is @code{t}, this command always reindents
the current line and does nothing else.  This is the default.

If that variable is @code{nil}, this command reindents the current line
only if point is at the left margin or in the line's indentation;
otherwise, it inserts a tab (or the equivalent number of spaces,
if @code{indent-tabs-mode} is @code{nil}).

Any other value (not @code{nil} or @code{t}) means always reindent the
538
line, and also insert a tab if within a comment or a string.
Dave Love's avatar
#  
Dave Love committed
539 540 541 542 543 544 545 546 547 548 549
@end table

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

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

@node Custom C Indent
@subsection Customizing C Indentation
550
@cindex style (for indentation)
Dave Love's avatar
#  
Dave Love committed
551

552 553 554 555 556 557
  C mode and related modes use a flexible mechanism for customizing
indentation.  C mode indents a source line in two steps: first it
classifies the line syntactically according to its contents and
context; second, it determines the indentation offset associated by
your selected @dfn{style} with the syntactic construct and adds this
onto the indentation of the @dfn{anchor statement}.
Dave Love's avatar
#  
Dave Love committed
558

559
@table @kbd
560 561
@item C-c . @key{RET} @var{style} @key{RET}
Select a predefined style @var{style} (@code{c-set-style}).
562
@end table
Dave Love's avatar
#  
Dave Love committed
563

564 565 566
  A @dfn{style} is a named collection of customizations that can be
used in C mode and the related modes.  @ref{Styles,,, ccmode, The CC
Mode Manual}, for a complete description.  Emacs comes with several
567 568
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
569 570 571 572 573
@code{whitesmith}, @code{ellemtel}, and @code{awk}.  Some of these
styles are primarily intended for one language, but any of them can be
used with any of the languages supported by these modes.  To find out
what a style looks like, select it and reindent some code, e.g., by
typing @key{C-M-q} at the start of a function definition.
Dave Love's avatar
#  
Dave Love committed
574

575
@kindex C-c . @r{(C mode)}
576
@findex c-set-style
Richard M. Stallman's avatar
Richard M. Stallman committed
577 578
  To choose a style for the current buffer, use the command @w{@kbd{C-c
.}}.  Specify a style name as an argument (case is not significant).
579 580
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
581 582
the code already in the buffer.  To reindent the whole buffer in the
new style, you can type @kbd{C-x h C-M-\}.
Dave Love's avatar
#  
Dave Love committed
583

584 585
@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
586 587 588 589
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,
Dave Love's avatar
#  
Dave Love committed
590 591

@example
592
(setq c-default-style
593
      '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))
Dave Love's avatar
#  
Dave Love committed
594 595
@end example

596
@noindent
597 598 599 600 601 602
specifies explicit choices for Java and AWK modes, and the default
@samp{gnu} style for the other C-like modes.  (These settings are
actually the defaults.)  This variable takes effect when you select
one of the C-like major modes; thus, if you specify a new default
style for Java mode, you can make it take effect in an existing Java
mode buffer by typing @kbd{M-x java-mode} there.
Dave Love's avatar
#  
Dave Love committed
603

604 605 606
  The @code{gnu} style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.
Dave Love's avatar
#  
Dave Love committed
607

608 609 610
  @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
information on customizing indentation for C and related modes,
611 612
including how to override parts of an existing style and how to define
your own styles.
Dave Love's avatar
#  
Dave Love committed
613

614 615
@node Parentheses
@section Commands for Editing with Parentheses
Dave Love's avatar
#  
Dave Love committed
616

617 618 619 620 621
@findex check-parens
@cindex unbalanced parentheses and quotes
  This section describes the commands and features that take advantage
of the parenthesis structure in a program, or help you keep it
balanced.
Dave Love's avatar
#  
Dave Love committed
622

623 624
  When talking about these facilities, the term ``parenthesis'' also
includes braces, brackets, or whatever delimiters are defined to match
Richard M. Stallman's avatar
Richard M. Stallman committed
625 626 627
in pairs.  The major mode controls which delimiters are significant,
through the syntax table (@pxref{Syntax}).  In Lisp, only parentheses
count; in C, these commands apply to braces and brackets too.
Dave Love's avatar
#  
Dave Love committed
628

629 630
  You can use @kbd{M-x check-parens} to find any unbalanced
parentheses and unbalanced string quotes in the buffer.
Dave Love's avatar
#  
Dave Love committed
631

632 633 634 635 636 637
@menu
* Expressions::         Expressions with balanced parentheses.
* Moving by Parens::    Commands for moving up, down and across
                          in the structure of parentheses.
* Matching::	        Insertion of a close-delimiter flashes matching open.
@end menu
Dave Love's avatar
#  
Dave Love committed
638

639 640
@node Expressions
@subsection Expressions with Balanced Parentheses
Dave Love's avatar
#  
Dave Love committed
641

642 643 644 645 646 647
@cindex sexp
@cindex expression
@cindex balanced expression
  These commands deal with balanced expressions, also called
@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
expression in Lisp.}.
Dave Love's avatar
#  
Dave Love committed
648

649 650 651 652
@table @kbd
@item C-M-f
Move forward over a balanced expression (@code{forward-sexp}).
@item C-M-b
653
Move backward over a balanced expression (@code{backward-sexp}).
654 655 656 657 658
@item C-M-k
Kill balanced expression forward (@code{kill-sexp}).
@item C-M-t
Transpose expressions (@code{transpose-sexps}).
@item C-M-@@
659
@itemx C-M-@key{SPC}
660 661
Put mark after following expression (@code{mark-sexp}).
@end table
Dave Love's avatar
#  
Dave Love committed
662

663 664 665
  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
Richard M. Stallman's avatar
Richard M. Stallman committed
666
any pair of matching delimiters and their contents.  Some languages
667 668
have obscure forms of expression syntax that nobody has bothered to
implement in Emacs.
Dave Love's avatar
#  
Dave Love committed
669

670
@cindex Control-Meta
Richard M. Stallman's avatar
Richard M. Stallman committed
671 672 673 674 675
  By convention, the keys for these commands are all Control-Meta
characters.  They usually act on expressions just as the corresponding
Meta characters act on words.  For instance, the command @kbd{C-M-b}
moves backward over a balanced expression, just as @kbd{M-b} moves
back over a word.
Dave Love's avatar
#  
Dave Love committed
676

677 678 679 680 681 682 683 684 685 686
@kindex C-M-f
@kindex C-M-b
@findex forward-sexp
@findex backward-sexp
  To move forward over a balanced expression, use @kbd{C-M-f}
(@code{forward-sexp}).  If the first significant character after point
is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
@samp{@{} in C), @kbd{C-M-f} moves past the matching closing
delimiter.  If the character begins a symbol, string, or number,
@kbd{C-M-f} moves over that.
Dave Love's avatar
#  
Dave Love committed
687

688 689 690 691 692 693 694
  The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
balanced expression.  The detailed rules are like those above for
@kbd{C-M-f}, but with directions reversed.  If there are prefix
characters (single-quote, backquote and comma, in Lisp) preceding the
expression, @kbd{C-M-b} moves back over them as well.  The balanced
expression commands move across comments as if they were whitespace,
in most modes.
Dave Love's avatar
#  
Dave Love committed
695

696 697 698
  @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
specified number of times; with a negative argument, it moves in the
opposite direction.
Dave Love's avatar
#  
Dave Love committed
699

700 701 702 703
@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
  Killing a whole balanced expression can be done with @kbd{C-M-k}
704 705
(@code{kill-sexp}).  @kbd{C-M-k} kills the characters that @kbd{C-M-f}
would move over.
Dave Love's avatar
#  
Dave Love committed
706

707 708 709 710 711 712
@cindex transposition of expressions
@kindex C-M-t
@findex transpose-sexps
  A somewhat random-sounding command which is nevertheless handy is
@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
balanced expression across the next one.  An argument serves as a
713 714 715 716 717 718
repeat count, moving the previous expression over that many following
ones.  A negative argument drags the previous balanced expression
backwards across those before it (thus canceling out the effect of
@kbd{C-M-t} with a positive argument).  An argument of zero, rather
than doing nothing, transposes the balanced expressions ending at or
after point and the mark.
Dave Love's avatar
#  
Dave Love committed
719

720
@kindex C-M-@@
721
@kindex C-M-@key{SPC}
722 723 724 725 726
@findex mark-sexp
  To set the region around the next balanced expression in the buffer,
use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
that @kbd{C-M-f} would move to.  @kbd{C-M-@@} takes arguments like
@kbd{C-M-f}.  In particular, a negative argument is useful for putting
727
the mark at the beginning of the previous balanced expression.  The
728 729
alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}.  When you
repeat this command, or use it in Transient Mark mode when the mark is
Richard M. Stallman's avatar
Richard M. Stallman committed
730
active, it extends the end of the region by one sexp each time.
731 732 733 734 735 736 737 738 739

  In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions as such because there can be
multiple possibilities at a given position.  For example, C mode does
not treat @samp{foo + bar} as a single expression, even though it
@emph{is} one C expression; instead, it recognizes @samp{foo} as one
expression and @samp{bar} as another, with the @samp{+} as punctuation
between them.  Both @samp{foo + bar} and @samp{foo} are legitimate
choices for ``the expression following point'' when point is at the
Richard M. Stallman's avatar
Richard M. Stallman committed
740 741 742
@samp{f}, so the expression commands must perforce choose one or the
other to operate on.  Note that @samp{(foo + bar)} is recognized as a
single expression in C mode, because of the parentheses.
743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758

@node Moving by Parens
@subsection Moving in the Parenthesis Structure

@cindex parenthetical groupings
@cindex parentheses, moving across
@cindex matching parenthesis and braces, moving to
@cindex braces, moving across
@cindex list commands
  The Emacs commands for handling parenthetical groupings see nothing
except parentheses (or whatever characters must balance in the
language you are working with), and the escape characters that might
be used to quote those.  They are mainly intended for editing
programs, but can be useful for editing any text that has parentheses.
They are sometimes called ``list'' commands because in Lisp these
groupings are lists.
Dave Love's avatar
#  
Dave Love committed
759 760

@table @kbd
761 762 763
@item C-M-n
Move forward over a parenthetical group (@code{forward-list}).
@item C-M-p
764
Move backward over a parenthetical group (@code{backward-list}).
765 766 767 768
@item C-M-u
Move up in parenthesis structure (@code{backward-up-list}).
@item C-M-d
Move down in parenthesis structure (@code{down-list}).
Dave Love's avatar
#  
Dave Love committed
769 770
@end table

771 772 773 774 775 776 777 778
@kindex C-M-n
@kindex C-M-p
@findex forward-list
@findex backward-list
  The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})
parenthetical groupings, skipping blithely over any amount of text
that doesn't include meaningful parentheses (symbols, strings, etc.).
Dave Love's avatar
#  
Dave Love committed
779

780 781 782 783 784 785 786
@kindex C-M-u
@findex backward-up-list
  @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
parenthesis structure.  To move @emph{up} one (or @var{n}) levels, use
@kbd{C-M-u} (@code{backward-up-list}).  @kbd{C-M-u} moves backward up
past one unmatched opening delimiter.  A positive argument serves as a
repeat count; a negative argument reverses the direction of motion, so
787
that the command moves forward and up one or more levels.
788

Richard M. Stallman's avatar
Richard M. Stallman committed
789 790
@kindex C-M-d
@findex down-list
791 792 793 794
  To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
(@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
delimiter, this is nearly the same as searching for a @samp{(}.  An
argument specifies the number of levels to go down.
Dave Love's avatar
#  
Dave Love committed
795 796

@node Matching
797
@subsection Automatic Display Of Matching Parentheses
Dave Love's avatar
#  
Dave Love committed
798 799 800 801
@cindex matching parentheses
@cindex parentheses, displaying matches

  The Emacs parenthesis-matching feature is designed to show
802 803 804 805
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
Richard M. Stallman's avatar
Richard M. Stallman committed
806 807
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.
808 809 810

  If the opening delimiter and closing delimiter are mismatched---such
as in @samp{[x)}---a warning message is displayed in the echo area.
Dave Love's avatar
#  
Dave Love committed
811 812 813 814

@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@vindex blink-matching-delay
815 816 817
  Three variables control parenthesis match display:

  @code{blink-matching-paren} turns the feature on or off: @code{nil}
818
disables it, but the default is @code{t} to enable match display.
819 820

  @code{blink-matching-delay} says how many seconds to leave the
821
cursor on the matching opening delimiter, before bringing it back to
822 823 824 825 826
the real location of point; the default is 1, but on some systems it
is useful to specify a fraction of a second.

  @code{blink-matching-paren-distance} specifies how many characters
back to search to find the matching opening delimiter.  If the match
Richard M. Stallman's avatar
Richard M. Stallman committed
827
is not found in that distance, scanning stops, and nothing is displayed.
828
This is to prevent the scan for the matching delimiter from wasting
829
lots of time when there is no match.  The default is 25600.
Dave Love's avatar
#  
Dave Love committed
830 831

@cindex Show Paren mode
832
@cindex highlighting matching parentheses
Dave Love's avatar
#  
Dave Love committed
833
@findex show-paren-mode
834 835 836 837 838 839 840
  Show Paren mode provides a more powerful kind of automatic matching.
Whenever point is after a closing delimiter, that delimiter and its
matching opening delimiter are both highlighted; otherwise, if point
is before an opening delimiter, the matching closing delimiter is
highlighted.  (There is no need to highlight the opening delimiter in
that case, because the cursor appears on top of that character.)  Use
the command @kbd{M-x show-paren-mode} to enable or disable this mode.
841

Richard M. Stallman's avatar
Richard M. Stallman committed
842 843 844
  Show Paren mode uses the faces @code{show-paren-match} and
@code{show-paren-mismatch} to highlight parentheses; you can customize
them to control how highlighting looks.  @xref{Face Customization}.
Dave Love's avatar
#  
Dave Love committed
845 846 847 848 849 850

@node Comments
@section Manipulating Comments
@cindex comments

  Because comments are such an important part of programming, Emacs
851 852 853
provides special commands for editing and inserting comments.  It can
also do spell checking on comments with Flyspell Prog mode
(@pxref{Spelling}).
Dave Love's avatar
#  
Dave Love committed
854 855

@menu
856 857 858
* Comment Commands::    Inserting, killing, and indenting comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.
Dave Love's avatar
#  
Dave Love committed
859 860 861 862 863 864
@end menu

@node Comment Commands
@subsection Comment Commands
@cindex indentation for comments

865 866
  The comment commands in this table insert, kill and align comments.
They are described in this section and following sections.
Dave Love's avatar
#  
Dave Love committed
867

868 869
@table @asis
@item @kbd{M-;}
870 871
Insert or realign comment on current line; alternatively, comment or
uncomment the region (@code{comment-dwim}).
872
@item @kbd{C-u M-;}
873
Kill comment on current line (@code{comment-kill}).
874
@item @kbd{C-x ;}
875
Set comment column (@code{comment-set-column}).
876 877
@item @kbd{C-M-j}
@itemx @kbd{M-j}
Dave Love's avatar
#  
Dave Love committed
878
Like @key{RET} followed by inserting and aligning a comment
879
(@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
880 881
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
Dave Love's avatar
#  
Dave Love committed
882 883 884
Add or remove comment delimiters on all the lines in the region.
@end table

885 886 887 888 889 890 891 892 893 894 895 896 897 898
@kindex M-;
@findex comment-dwim
  The command to create or align a comment is @kbd{M-;}
(@code{comment-dwim}).  The word ``dwim'' is an acronym for ``Do What
I Mean''; it indicates that this command can be used for many
different jobs relating to comments, depending on the situation where
you use it.

  If there is no comment already on the line, @kbd{M-;} inserts a new
comment, aligned at a specific column called the @dfn{comment column}.
The new comment begins with the string Emacs thinks comments should
start with (the value of @code{comment-start}; see below).  Point is
after that string, so you can insert the text of the comment right
away.  If the major mode has specified a string to terminate comments,
Richard M. Stallman's avatar
Richard M. Stallman committed
899
@kbd{M-;} inserts that after point, to keep the syntax valid.
900

Richard M. Stallman's avatar
Richard M. Stallman committed
901 902 903
  If the text of the line extends past the comment column, this
command indents the comment start string to a suitable boundary
(usually, at least one space is inserted).
904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930

  You can also use @kbd{M-;} to align an existing comment.  If a line
already contains the comment-start string, @kbd{M-;} reindents it to
the conventional alignment and moves point after it.  (Exception:
comments starting in column 0 are not moved.)  Even when an existing
comment is properly aligned, @kbd{M-;} is still useful for moving
directly to the start of the text inside the comment.

@findex comment-kill
@kindex C-u M-;
  @kbd{C-u M-;} kills any comment on the current line, along with the
whitespace before it.  To reinsert the comment on another line, move
to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
realign it.

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

  @kbd{M-;} does two other jobs when used with an active region in
Transient Mark mode (@pxref{Transient Mark}).  Then it either adds or
removes comment delimiters on each line of the region.  (If every line
is a comment, it removes comment delimiters from each; otherwise, it
adds comment delimiters to each.)  If you are not using Transient Mark
mode, then you should use the commands @code{comment-region} and
Richard M. Stallman's avatar
Richard M. Stallman committed
931 932
@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}),
or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}).
933 934
A prefix argument used in these circumstances specifies how many
comment delimiters to add or how many to delete.
Dave Love's avatar
#  
Dave Love committed
935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952

  Some major modes have special rules for indenting certain kinds of
comments in certain contexts.  For example, in Lisp code, comments which
start with two semicolons are indented as if they were lines of code,
instead of at the comment column.  Comments which start with three
semicolons are supposed to start at the left margin.  Emacs understands
these conventions by indenting a double-semicolon comment using @key{TAB},
and by not changing the indentation of a triple-semicolon comment at all.

@example
;; This function is just an example
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;; And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.
@end example

Richard M. Stallman's avatar
Richard M. Stallman committed
953 954
  For C-like modes, you can configure the exact effect of @kbd{M-;}
more flexibly than for most buffers by setting the variables
955 956 957 958 959
@code{c-indent-comment-alist} and
@code{c-indent-comments-syntactically-p}.  For example, on a line
ending in a closing brace, @kbd{M-;} puts the comment one space after
the brace rather than at @code{comment-column}.  For full details see
@ref{Comment Commands,,, ccmode, The CC Mode Manual}. 
Dave Love's avatar
#  
Dave Love committed
960 961 962 963 964

@node Multi-Line Comments
@subsection Multiple Lines of Comments

@kindex C-M-j
965
@kindex M-j
Dave Love's avatar
#  
Dave Love committed
966
@cindex blank lines in programs
967
@findex comment-indent-new-line
968

Dave Love's avatar
#  
Dave Love committed
969
  If you are typing a comment and wish to continue it on another line,
970
you can use the command @kbd{C-M-j} or @kbd{M-j}
971 972 973 974 975 976
(@code{comment-indent-new-line}).  If @code{comment-multi-line}
(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
line within the comment.  Otherwise it closes the comment and starts a
new comment on a new line.  When Auto Fill mode is on, going past the
fill column while typing a comment causes the comment to be continued
in just this fashion.
977 978

@kindex C-c C-c (C mode)
Dave Love's avatar
#  
Dave Love committed
979 980
@findex comment-region
  To turn existing lines into comment lines, use the @kbd{M-x
Richard M. Stallman's avatar
Richard M. Stallman committed
981
comment-region} command (or type @kbd{C-c C-c} in C-like modes).  It
982 983 984
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.
Dave Love's avatar
#  
Dave Love committed
985 986 987 988 989 990 991

  With a positive argument, @code{comment-region} duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert.  Thus, in Lisp mode,
@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.  Duplicating
the comment delimiter is a way of calling attention to the comment.  It
can also affect how the comment is indented.  In Lisp, for proper
992 993
indentation, you should use an argument of two or three, if between defuns;
if within a defun, it must be three.
Dave Love's avatar
#  
Dave Love committed
994

995 996 997 998 999
  You can configure C Mode such that when you type a @samp{/} at the
start of a line in a multi-line block comment, this closes the
comment.  Enable the @code{comment-close-slash} clean-up for this.
@xref{Clean-ups,,, ccmode, The CC Mode Manual}.

Dave Love's avatar
#  
Dave Love committed
1000 1001 1002 1003 1004
@node Options for Comments
@subsection Options Controlling Comments

@vindex comment-column
@kindex C-x ;
1005
@findex comment-set-column
1006 1007 1008 1009 1010 1011 1012
  The @dfn{comment column}, the column at which Emacs tries to place
comments, is stored in the variable @code{comment-column}.  You can
set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
(@code{comment-set-column}) sets the comment column to the column
point is at.  @kbd{C-u C-x ;} sets the comment column to match the
last comment before point in the buffer, and then does a @kbd{M-;} to
align the current line's comment under the previous one.
Dave Love's avatar
#  
Dave Love committed
1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024

  The variable @code{comment-column} is per-buffer: setting the variable
in the normal fashion affects only the current buffer, but there is a
default value which you can change with @code{setq-default}.
@xref{Locals}.  Many major modes initialize this variable for the
current buffer.

@vindex comment-start-skip
  The comment commands recognize comments based on the regular
expression that is the value of the variable @code{comment-start-skip}.
Make sure this regexp does not match the null string.  It may match more
than the comment starting delimiter in the strictest sense of the word;
1025 1026
for example, in C mode the value of the variable is
@c This stops M-q from breaking the line inside that @code.
1027
@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
1028
after the @samp{/*} itself, and accepts C++ style comments also.
Dave Love's avatar
#  
Dave Love committed
1029 1030
(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
the string, which is needed to deny the first star its special meaning
1031
in regexp syntax.  @xref{Regexp Backslash}.)
Dave Love's avatar
#  
Dave Love committed
1032 1033 1034 1035 1036

@vindex comment-start
@vindex comment-end
  When a comment command makes a new comment, it inserts the value of
@code{comment-start} to begin it.  The value of @code{comment-end} is
1037 1038 1039 1040 1041
inserted after point, so that it will follow the text that you will
insert into the comment.  When @code{comment-end} is non-empty, it
should start with a space.  For example, in C mode,
@code{comment-start} has the value @w{@code{"/* "}} and
@code{comment-end} has the value @w{@code{" */"}}.
Dave Love's avatar
#  
Dave Love committed
1042

1043 1044
@vindex comment-padding
  The variable @code{comment-padding} specifies how many spaces
1045 1046 1047 1048
@code{comment-region} should insert on each line between the comment
delimiter and the line's original text.  The default is 1, to insert
one space.  @code{nil} means 0.  Alternatively, @code{comment-padding}
can hold the actual string to insert.
1049

Dave Love's avatar
#  
Dave Love committed
1050 1051
@vindex comment-multi-line
  The variable @code{comment-multi-line} controls how @kbd{C-M-j}
1052
(@code{indent-new-comment-line}) behaves when used inside a comment.
1053 1054 1055 1056 1057 1058 1059
Specifically, when @code{comment-multi-line} is @code{nil}, the
command inserts a comment terminator, begins a new line, and finally
inserts a comment starter.  Otherwise it does not insert the
terminator and starter, so it effectively continues the current
comment across multiple lines.  In languages that allow multi-line
comments, the choice of value for this variable is a matter of taste.
The default for this variable depends on the major mode.
Dave Love's avatar
#  
Dave Love committed
1060

Richard M. Stallman's avatar
Richard M. Stallman committed
1061
@vindex comment-indent-function
Dave Love's avatar
#  
Dave Love committed
1062 1063 1064 1065 1066 1067 1068 1069 1070 1071
  The variable @code{comment-indent-function} should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment.  It is set differently by
various major modes.  The function is called with no arguments, but with
point at the beginning of the comment, or at the end of a line if a new
comment is to be inserted.  It should return the column in which the
comment ought to start.  For example, in Lisp mode, the indent hook
function bases its decision on how many semicolons begin an existing
comment, and on the code in the preceding lines.

1072 1073
@node Documentation
@section Documentation Lookup
Dave Love's avatar
#  
Dave Love committed
1074

1075 1076 1077
  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.
Dave Love's avatar
#  
Dave Love committed
1078