programs.texi 73.4 KB
Newer Older
1
@c -*- coding: utf-8 -*-
Dave Love's avatar
#  
Dave Love committed
2
@c This is part of the Emacs manual.
3
@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
4
@c Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
5
@c See file emacs.texi for copying conditions.
6
@node Programs
Dave Love's avatar
#  
Dave Love committed
7 8 9 10 11
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing

12
  This chapter describes Emacs features for facilitating editing
13
programs.  Some of the things these features can do are:
Dave Love's avatar
#  
Dave Love committed
14 15 16

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

@menu
* Program Modes::       Major modes for editing programs.
31 32
* Defuns::              Commands to operate on major top-level parts
                          of a program.
Dave Love's avatar
#  
Dave Love committed
33
* Program Indent::      Adjusting indentation to show the nesting.
34
* Parentheses::         Commands that operate on parentheses.
35
* Comments::            Inserting, killing, and aligning comments.
36
* Documentation::       Getting documentation of functions you plan to call.
37
* Hideshow::            Displaying blocks selectively.
38
* Symbol Completion::   Completion on symbol names of your program or language.
39
* MixedCase Words::     Dealing with identifiersLikeThis.
40
* Semantic::            Suite of editing tools based on source code parsing.
41
* Prettifying Symbols:: Display symbols as composed characters.
42
* Misc for Programs::   Other Emacs features useful for editing programs.
43 44
* C Modes::             Special commands of C, C++, Objective-C, Java,
                          IDL, Pike and AWK modes.
45
* Asm Mode::            Asm mode and its special features.
46 47 48
@ifnottex
* Fortran::             Fortran mode and its special features.
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
49 50 51 52 53
@end menu

@node Program Modes
@section Major Modes for Programming Languages
@cindex modes for programming languages
54

55 56
  Emacs has specialized major modes (@pxref{Major Modes}) for many
programming languages.  A programming language mode typically
57 58
specifies the syntax of expressions, the customary rules for
indentation, how to do syntax highlighting for the language, and how
59 60 61 62
to find the beginning or end of a function definition.  It often has
features for compiling and debugging programs as well.  The major mode
for each language is named after the language; for instance, the major
mode for the C programming language is @code{c-mode}.
63

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

  Ideally, Emacs should have a major mode for each programming
language that you might want to edit.  If it doesn't have a mode for
your favorite language, the mode might be implemented in a package not
distributed with Emacs (@pxref{Packages}); or you can contribute one.
Dave Love's avatar
#  
Dave Love committed
99 100

@kindex DEL @r{(programming modes)}
101
@findex c-electric-backspace
102
@findex backward-delete-char-untabify
103
  In most programming languages, indentation should vary from line to
104 105 106 107 108 109 110
line to illustrate the structure of the program.  Therefore, in most
programming language modes, typing @key{TAB} updates the indentation
of the current line (@pxref{Program Indent}).  Furthermore, @key{DEL}
is usually bound to @code{backward-delete-char-untabify}, which
deletes backward treating each tab as if it were the equivalent number
of spaces, so that you can delete one column of indentation without
worrying whether the whitespace consists of spaces or tabs.
111

Dave Love's avatar
#  
Dave Love committed
112 113 114 115 116 117
@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
118 119 120 121 122 123
  Entering a programming language mode runs the custom Lisp functions
specified in the hook variable @code{prog-mode-hook}, followed by
those specified in the mode's own mode hook (@pxref{Major Modes}).
For instance, entering C mode runs the hooks @code{prog-mode-hook} and
@code{c-mode-hook}.  @xref{Hooks}, for information about hooks.

124
@ifnottex
125 126 127 128
  Separate manuals are available for the modes for Ada (@pxref{Top,,
Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
129 130
@end ifnottex
@iftex
131
  The Emacs distribution contains Info manuals for the major modes for
132
Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@.  For
133
Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
134
@end iftex
Dave Love's avatar
#  
Dave Love committed
135

136 137
@node Defuns
@section Top-Level Definitions, or Defuns
Dave Love's avatar
#  
Dave Love committed
138

139 140 141
  In Emacs, a major definition at the top level in the buffer, such as
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
142

143 144 145 146 147 148 149
@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
150

151 152
@node Left Margin Paren
@subsection Left Margin Convention
Dave Love's avatar
#  
Dave Love committed
153

154 155
@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
156 157 158 159 160 161 162 163 164 165
  Many programming-language modes assume by default that any opening
delimiter found at the left margin is the start of a top-level
definition, or defun.  Therefore, @strong{don't put an opening
delimiter at the left margin unless it should have that significance}.
For instance, never put an open-parenthesis at the left margin in a
Lisp file unless it is the start of a top-level list.

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

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

  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 C and 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
@vindex open-paren-in-column-0-is-defun-start
191
  If you need to override this convention, you can do so by setting
192
the variable @code{open-paren-in-column-0-is-defun-start}.
193
If this user option is set to @code{t} (the default), opening
194
parentheses or braces at column zero always start defuns.  When it is
195 196 197
@code{nil}, defuns are found by searching for parens or braces at the
outermost level.

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

@node Moving by Defuns
@subsection Moving by Defuns
Dave Love's avatar
#  
Dave Love committed
209 210
@cindex defuns

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

Dave Love's avatar
#  
Dave Love committed
214 215 216 217 218 219 220 221 222 223
@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

224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
@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
242 243 244 245
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.
246

247
@kindex C-M-h @r{(C mode)}
Dave Love's avatar
#  
Dave Love committed
248
@findex c-mark-function
249 250 251 252 253 254 255 256 257
  To operate on the current defun, use @kbd{C-M-h}
(@code{mark-defun}), which sets the mark at the end of the current
defun and puts point at its beginning.  @xref{Marking Objects}.  This
is the easiest way to get ready to kill the defun in order to move it
to a different place in the file.  If you use the command while point
is between defuns, it uses the following defun.  If you use the
command while the mark is already active, it sets the mark but does
not move point; furthermore, each successive use of @kbd{C-M-h}
extends the end of the region to include one more defun.
258 259 260 261

  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
262 263 264 265 266
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
267

268 269
@node Imenu
@subsection Imenu
Richard M. Stallman's avatar
Richard M. Stallman committed
270 271
@cindex index of buffer definitions
@cindex buffer definitions index
272

Pavel Janík's avatar
Pavel Janík committed
273
  The Imenu facility offers a way to find the major definitions in
274 275
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
276
(@xref{Tags}, for a more powerful feature that handles multiple files
277
together.)
278 279

@findex imenu
280
  If you type @kbd{M-x imenu}, it reads the name of a definition using
Richard M. Stallman's avatar
Richard M. Stallman committed
281 282 283
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.
284

285
@findex imenu-add-menubar-index
286
  Alternatively, you can bind the command @code{imenu} to a mouse
Richard M. Stallman's avatar
Richard M. Stallman committed
287 288 289 290 291
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
292 293 294
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.
295 296 297

@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
298
definitions, you can update the buffer's index based on the
299
new contents by invoking the @samp{*Rescan*} item in the menu.
Eli Zaretskii's avatar
Eli Zaretskii committed
300 301
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
302
changes in the text.
303 304

@vindex imenu-sort-function
305
  You can customize the way the menus are sorted by setting the
Richard M. Stallman's avatar
Richard M. Stallman committed
306
variable @code{imenu-sort-function}.  By default, names are ordered as
307 308 309
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.
310 311 312 313 314 315 316 317 318 319 320 321

  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
322
@cindex current function name in mode line
323

324 325 326
  Which Function mode is a global minor mode (@pxref{Minor Modes})
which displays the current function name in the mode line, updating it
as you move around in a buffer.
327 328 329

@findex which-function-mode
@vindex which-func-modes
Karl Berry's avatar
Karl Berry committed
330
  To either enable or disable Which Function mode, use the command
331 332
@kbd{M-x which-function-mode}.  Which Function mode is a global minor
mode.  By default, it takes effect in all major modes major modes that
333
know how to support it (i.e., all the major modes that support
334 335 336 337
Imenu).  You can restrict it to a specific list of major modes by
changing the value of the variable @code{which-func-modes} from
@code{t} (which means to support all available major modes) to a list
of major mode names.
Dave Love's avatar
#  
Dave Love committed
338 339 340 341 342 343

@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
344 345 346
reindent it as you change it.  Emacs has commands to indent either a
single line, a specified number of lines, or all of the lines inside a
single parenthetical grouping.
Dave Love's avatar
#  
Dave Love committed
347

348 349 350 351
  @xref{Indentation}, for general information about indentation.  This
section describes indentation features specific to programming
language modes.

Dave Love's avatar
#  
Dave Love committed
352
@menu
353
* Basic Indent::        Indenting a single line.
Dave Love's avatar
#  
Dave Love committed
354
* Multi-line Indent::   Commands to reindent many lines at once.
355 356 357
* 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.
Dave Love's avatar
#  
Dave Love committed
358 359
@end menu

360
@cindex pretty-printer
361 362
  Emacs also provides a Lisp pretty-printer in the @code{pp} package,
which reformats Lisp objects with nice-looking indentation.
Dave Love's avatar
#  
Dave Love committed
363 364 365 366 367 368

@node Basic Indent
@subsection Basic Program Indentation Commands

@table @kbd
@item @key{TAB}
369
Adjust indentation of current line (@code{indent-for-tab-command}).
370
@item @key{RET}
371
Insert a newline, then adjust indentation of following line
372
(@code{newline}).
Dave Love's avatar
#  
Dave Love committed
373 374 375
@end table

@kindex TAB @r{(programming modes)}
376 377
@findex c-indent-command
@findex indent-line-function
378
@findex indent-for-tab-command
379 380 381 382 383 384
  The basic indentation command is @key{TAB}
(@code{indent-for-tab-command}), which was documented in
@ref{Indentation}.  In programming language modes, @key{TAB} indents
the current line, based on the indentation and syntactic content of
the preceding lines; if the region is active, @key{TAB} indents each
line within the region, not just the current line.
Dave Love's avatar
#  
Dave Love committed
385

386 387 388
  The command @key{RET} (@code{newline}), which was documented in
@ref{Inserting Text}, does the same as @key{C-j} followed by
@key{TAB}: it inserts a new line, then adjusts the line's indentation.
389 390 391 392

  When indenting a line that starts within a parenthetical grouping,
Emacs usually places the start of the line under the preceding line
within the group, or under the text after the parenthesis.  If you
393
manually give one of these lines a nonstandard indentation (e.g., for
394 395 396 397 398 399 400 401
aesthetic purposes), the lines below will follow it.

  The indentation commands for most programming language modes assume
that a open-parenthesis, open-brace or other opening delimiter at the
left margin is the start of a function.  If the code you are editing
violates this assumption---even if the delimiters occur in strings or
comments---you must set @code{open-paren-in-column-0-is-defun-start}
to @code{nil} for indentation to work properly.  @xref{Left Margin
402
Paren}.
Dave Love's avatar
#  
Dave Love committed
403 404 405 406

@node Multi-line Indent
@subsection Indenting Several Lines

407 408
  Sometimes, you may want to reindent several lines of code at a time.
One way to do this is to use the mark; when the mark is active and the
409 410 411 412 413 414 415
region is non-empty, @key{TAB} indents every line in the region.
Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
every line in the region, whether or not the mark is active
(@pxref{Indentation Commands}).

  In addition, Emacs provides the following commands for indenting
large chunks of code:
Dave Love's avatar
#  
Dave Love committed
416 417 418

@table @kbd
@item C-M-q
419
Reindent all the lines within one parenthetical grouping.
Dave Love's avatar
#  
Dave Love committed
420
@item C-u @key{TAB}
421 422
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.
423 424 425
@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
426 427 428
@end table

@kindex C-M-q
429
@findex indent-pp-sexp
430 431 432
  To reindent the contents of a single parenthetical grouping,
position point before the beginning of the grouping and type
@kbd{C-M-q}.  This changes the relative indentation within the
433
grouping, without affecting its overall indentation (i.e., the
434 435 436 437 438 439
indentation of the line where the grouping starts).  The function that
@kbd{C-M-q} runs depends on the major mode; it is
@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
etc.  To correct the overall indentation as well, type @key{TAB}
first.

Dave Love's avatar
#  
Dave Love committed
440
@kindex C-u TAB
441 442 443 444 445 446 447 448 449
  If you like the relative indentation within a grouping but not the
indentation of its first line, move point to that first line and type
@kbd{C-u @key{TAB}}.  In Lisp, C, and some other major modes,
@key{TAB} with a numeric argument reindents the current line as usual,
then reindents by the same amount all the lines in the parenthetical
grouping starting on the current line.  It is clever, though, and does
not alter lines that start inside strings.  Neither does it alter C
preprocessor lines when in C mode, but it does reindent any
continuation lines that may be attached to them.
Dave Love's avatar
#  
Dave Love committed
450

451
@findex indent-code-rigidly
452 453 454 455 456 457
  The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
lines in the region sideways, like @code{indent-rigidly} does
(@pxref{Indentation Commands}).  It doesn't alter the indentation of
lines that start inside a string, unless the region also starts inside
that string.  The prefix arg specifies the number of columns to
indent.
Dave Love's avatar
#  
Dave Love committed
458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480

@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
481
  Certain functions override the standard pattern.  Functions whose
Pavel Janík's avatar
Pavel Janík committed
482
names start with @code{def} treat the second lines as the start of
483 484 485
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
486

487
@cindex @code{lisp-indent-function} property
488
  You can override the standard pattern in various ways for individual
489
functions, according to the @code{lisp-indent-function} property of
490 491 492
the function name.  This is normally done for macro definitions, using
the @code{declare} construct.  @xref{Defining Macros,,, elisp, the
Emacs Lisp Reference Manual}.
Dave Love's avatar
#  
Dave Love committed
493 494 495 496

@node C Indent
@subsection Commands for C Indentation

497
  Here are special features for indentation in C mode and related modes:
Dave Love's avatar
#  
Dave Love committed
498 499 500 501 502 503 504 505 506 507 508 509

@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
510 511
(@code{c-indent-exp}).  A prefix argument inhibits warning messages
about invalid syntax.
Dave Love's avatar
#  
Dave Love committed
512 513 514 515 516 517

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

518
@vindex c-tab-always-indent
Dave Love's avatar
#  
Dave Love committed
519 520 521 522 523 524 525 526 527
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
528
line, and also insert a tab if within a comment or a string.
Dave Love's avatar
#  
Dave Love committed
529 530 531 532 533 534 535 536 537 538 539
@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
540
@cindex style (for indentation)
Dave Love's avatar
#  
Dave Love committed
541

542 543 544 545 546 547
  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
548

549
@table @kbd
550 551
@item C-c . @key{RET} @var{style} @key{RET}
Select a predefined style @var{style} (@code{c-set-style}).
552
@end table
Dave Love's avatar
#  
Dave Love committed
553

554 555 556
  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
557 558
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
559 560 561 562 563
@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
564

565
@kindex C-c . @r{(C mode)}
566
@findex c-set-style
Richard M. Stallman's avatar
Richard M. Stallman committed
567 568
  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).
569 570
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
571 572
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
573

574 575
@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
576 577 578 579
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
580 581

@example
582
(setq c-default-style
583 584 585
      '((java-mode . "java")
        (awk-mode . "awk")
        (other . "gnu")))
Dave Love's avatar
#  
Dave Love committed
586 587
@end example

588
@noindent
589 590 591 592 593 594
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
595

596 597 598
  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
599

600 601 602
  @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,
603 604
including how to override parts of an existing style and how to define
your own styles.
Dave Love's avatar
#  
Dave Love committed
605

606 607 608 609 610
@findex c-guess
@findex c-guess-install
  As an alternative to specifying a style, you can tell Emacs to guess
a style by typing @kbd{M-x c-guess} in a sample code buffer.  You can
then apply the guessed style to other buffers with @kbd{M-x
611
c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
612
Manual}, for details.
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
in pairs.  The major mode controls which delimiters are significant,
626 627 628
through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
The Emacs Lisp Reference Manual}).  In Lisp, only parentheses count;
in C, these commands apply to braces and brackets too.
Dave Love's avatar
#  
Dave Love committed
629

630 631
  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
632

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

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

643 644 645
@cindex sexp
@cindex expression
@cindex balanced expression
646 647 648 649 650 651 652
  Each programming language mode has its own definition of a
@dfn{balanced expression}.  Balanced expressions typically include
individual symbols, numbers, and string constants, as well as pieces
of code enclosed in a matching pair of delimiters.  The following
commands deal with balanced expressions (in Emacs, such expressions
are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
is used to refer to an expression in Lisp.}).
Dave Love's avatar
#  
Dave Love committed
653

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

668 669 670 671 672 673
@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
674
is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
675 676 677
this command moves past the matching closing delimiter.  If the
character begins a symbol, string, or number, the command moves over
that.
Dave Love's avatar
#  
Dave Love committed
678

679
  The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
680 681 682 683 684 685 686 687 688 689 690 691
balanced expression---like @kbd{C-M-f}, but in the reverse direction.
If the expression is preceded by any prefix characters (single-quote,
backquote and comma, in Lisp), the command moves back over them as
well.

  @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
the specified number of times; with a negative argument means to move
in the opposite direction.  In most modes, these two commands move
across comments as if they were whitespace.  Note that their keys,
@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
@kbd{M-b}, which move by words (@pxref{Words}).
Dave Love's avatar
#  
Dave Love committed
692

693 694 695
@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
696 697 698
  To kill a whole balanced expression, type @kbd{C-M-k}
(@code{kill-sexp}).  This kills the text that @kbd{C-M-f} would move
over.
Dave Love's avatar
#  
Dave Love committed
699

700 701 702
@cindex transposition of expressions
@kindex C-M-t
@findex transpose-sexps
703 704 705 706 707 708 709 710
  @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
previous balanced expression and the next one.  It is analogous to the
@kbd{C-t} command, which transposes characters (@pxref{Transpose}).
An argument to @kbd{C-M-t} serves as a repeat count, moving the
previous expression over that many following ones.  A negative
argument moves the previous balanced expression backwards across those
before it.  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
711

712
@kindex C-M-@@
713
@kindex C-M-@key{SPC}
714
@findex mark-sexp
715 716 717 718 719 720 721 722 723
  To operate on balanced expressions with a command which acts on the
region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
mark where @kbd{C-M-f} would move to.  While the mark is active, each
successive call to this command extends the region by shifting the
mark by one expression.  Positive or negative numeric arguments move
the mark forward or backward by the specified number of expressions.
The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
@xref{Marking Objects}, for more information about this and related
commands.
724 725

  In languages that use infix operators, such as C, it is not possible
726 727 728 729 730 731 732
to recognize all balanced expressions 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.
However, C mode recognizes @samp{(foo + bar)} as a single expression,
because of the parentheses.
733 734 735 736 737 738 739 740 741

@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
742

743 744 745 746 747 748 749 750
  The following commands move over groupings delimited by parentheses
(or whatever else serves as delimiters in the language you are working
with).  They ignore strings and comments, including any parentheses
within them, and also ignore parentheses that are ``quoted'' with an
escape character.  These commands are mainly intended for editing
programs, but can be useful for editing any text containing
parentheses.  They are referred to internally as ``list'' commands
because in Lisp these groupings are lists.
Dave Love's avatar
#  
Dave Love committed
751

752 753 754
  These commands assume that the starting point is not inside a string
or a comment.  If you invoke them from inside a string or comment, the
results are unreliable.
755

Dave Love's avatar
#  
Dave Love committed
756
@table @kbd
757 758 759
@item C-M-n
Move forward over a parenthetical group (@code{forward-list}).
@item C-M-p
760
Move backward over a parenthetical group (@code{backward-list}).
761 762 763 764
@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
765 766
@end table

767 768 769 770 771
@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
772 773
@kbd{C-M-p} (@code{backward-list}) move forward or backward over one
(or @var{n}) parenthetical groupings.
Dave Love's avatar
#  
Dave Love committed
774

775 776 777 778 779 780 781
@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
782
that the command moves forward and up one or more levels.
783

Richard M. Stallman's avatar
Richard M. Stallman committed
784 785
@kindex C-M-d
@findex down-list
786 787 788 789
  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
790 791

@node Matching
792
@subsection Matching Parentheses
Dave Love's avatar
#  
Dave Love committed
793 794 795
@cindex matching parentheses
@cindex parentheses, displaying matches

796 797 798 799 800
  Emacs has a number of @dfn{parenthesis matching} features, which
make it easy to see how and whether parentheses (or other delimiters)
match up.

  Whenever you type a self-inserting character that is a closing
Dmitry Gutov's avatar
Dmitry Gutov committed
801 802 803 804 805 806
delimiter, Emacs briefly indicates the location of the matching
opening delimiter, provided that is on the screen.  If it is not on
the screen, Emacs displays some of the text near it in the echo area.
Either way, you can tell which grouping you are closing off.  If the
opening delimiter and closing delimiter are mismatched---such as in
@samp{[x)}---a warning message is displayed in the echo area.
Dave Love's avatar
#  
Dave Love committed
807 808 809 810

@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@vindex blink-matching-delay
811
  Three variables control the display of matching parentheses:
812

813 814 815
@itemize @bullet
@item
@code{blink-matching-paren} turns the feature on or off: @code{nil}
816
disables it, but the default is @code{t} to enable it.  Set it to
817 818
@code{jump} to make indication work by momentarily moving the cursor
to the matching opening delimiter.
819

820
@item
821 822 823
@code{blink-matching-delay} says how many seconds to keep indicating
the matching opening delimiter.  This may be an integer or
floating-point number; the default is 1.
824

825 826
@item
@code{blink-matching-paren-distance} specifies how many characters
827
back to search to find the matching opening delimiter.  If the match
828 829 830
is not found in that distance, Emacs stops scanning and nothing is
displayed.  The default is 102400.
@end itemize
Dave Love's avatar
#  
Dave Love committed
831 832

@cindex Show Paren mode
833
@cindex highlighting matching parentheses
Dave Love's avatar
#  
Dave Love committed
834
@findex show-paren-mode
835 836 837 838 839 840 841 842 843 844 845 846
  Show Paren mode, a global minor mode, provides a more powerful kind
of automatic matching.  Whenever point is before an opening delimiter
or after a closing delimiter, both that delimiter and its opposite
delimiter are highlighted.  To toggle Show Paren mode, type @kbd{M-x
show-paren-mode}.

@cindex Electric Pair mode
@cindex inserting matching parentheses
@findex electric-pair-mode
  Electric Pair mode, a global minor mode, provides a way to easily
insert matching delimiters.  Whenever you insert an opening delimiter,
the matching closing delimiter is automatically inserted as well,
847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868
leaving point between the two. Conversely, when you insert a closing
delimiter over an existing one, no inserting takes places and that
position is simply skipped over. These variables control additional
features of Electric Pair mode:

@itemize @bullet
@item
@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
default pairing logic balance out the number of opening and closing
delimiters.

@item
@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
backspacing between two adjacent delimiters also automatically delete
the closing delimiter.

@item
@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
makes inserting inserting a newline between two adjacent pairs also
automatically open and extra newline after point.

@item
869
@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
870 871 872 873 874
mode to skip whitespace forward before deciding whether to skip over
the closing delimiter.
@end itemize

To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.
Dave Love's avatar
#  
Dave Love committed
875 876 877 878 879 880

@node Comments
@section Manipulating Comments
@cindex comments

  Because comments are such an important part of programming, Emacs
881 882 883
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
884

885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901
  Some major modes have special rules for indenting different kinds of
comments.  For example, in Lisp code, comments starting with two
semicolons are indented as if they were lines of code, while those
starting with three semicolons are supposed to be aligned to the left
margin and are often used for sectioning purposes.  Emacs understand
these conventions; for instance, typing @key{TAB} on a comment line
will indent the comment to the appropriate position.

@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

Dave Love's avatar
#  
Dave Love committed
902
@menu
903
* Comment Commands::    Inserting, killing, and aligning comments.
904 905
* 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
906 907 908 909 910
@end menu

@node Comment Commands
@subsection Comment Commands
@cindex indentation for comments
911
@cindex alignment for comments
Dave Love's avatar
#  
Dave Love committed
912

913
  The following commands operate on comments:
Dave Love's avatar
#  
Dave Love committed
914

915 916
@table @asis
@item @kbd{M-;}
917 918
Insert or realign comment on current line; if the region is active,
comment or uncomment the region instead (@code{comment-dwim}).
919
@item @kbd{C-u M-;}
920
Kill comment on current line (@code{comment-kill}).
921
@item @kbd{C-x ;}
922
Set comment column (@code{comment-set-column}).
923 924
@item @kbd{C-M-j}
@itemx @kbd{M-j}
Dave Love's avatar
#  
Dave Love committed
925
Like @key{RET} followed by inserting and aligning a comment
926
(@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
927 928
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
929
Add comment delimiters to all the lines in the region.
Dave Love's avatar
#  
Dave Love committed
930 931
@end table

932 933 934 935 936 937 938 939
@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.

940 941 942 943 944 945 946 947 948 949 950 951 952
  When a region is active (@pxref{Mark}), @kbd{M-;} either adds
comment delimiters to the region, or removes them.  If every line in
the region is already a comment, it ``uncomments'' each of those lines
by removing their comment delimiters.  Otherwise, it adds comment
delimiters to enclose the text in the region.

  If you supply a prefix argument to @kbd{M-;} when a region is
active, that specifies the number of comment delimiters to add or
delete.  A positive argument @var{n} adds @var{n} delimiters, while a
negative argument @var{-n} removes @var{n} delimiters.

  If the region is not active, and there is no existing comment on the
current line, @kbd{M-;} adds a new comment to the current line.  If
953
the line is blank (i.e., empty or containing only whitespace
954 955 956 957 958 959 960 961 962 963
characters), the comment is indented to the same position where
@key{TAB} would indent to (@pxref{Basic Indent}).  If the line is
non-blank, the comment is placed after the last non-whitespace
character on the line; normally, Emacs tries putting it at the column
specified by the variable @code{comment-column} (@pxref{Options for
Comments}), but if the line already extends past that column, it puts
the comment at some suitable position, usually separated from the
non-comment text by at least one space.  In each case, Emacs places
point after the comment's starting delimiter, so that you can start
typing the comment text right away.
964 965

  You can also use @kbd{M-;} to align an existing comment.  If a line
966
already contains the comment-start string, @kbd{M-;} realigns it to
967 968 969 970 971
the conventional alignment and moves point after the comment's
starting delimiter.  As an 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
comment text.
972 973 974

@findex comment-kill
@kindex C-u M-;
975 976 977 978
  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
comment on the current line, along with the whitespace before it.
Since the comment is saved to the kill ring, you can reinsert it on
another line by moving to the end of that line, doing @kbd{C-y}, and
979
then @kbd{M-;} to realign the comment.  You can achieve the same
980 981 982
effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
(@code{comment-dwim} actually calls @code{comment-kill} as a
subroutine when it is given a prefix argument).
Dave Love's avatar
#  
Dave Love committed
983

984 985 986 987 988 989 990 991 992 993 994
@kindex C-c C-c (C mode)
@findex comment-region
@findex uncomment-region
  The command @kbd{M-x comment-region} is equivalent to calling
@kbd{M-;} on an active region, except that it always acts on the
region, even if the mark is inactive.  In C mode and related modes,
this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
uncomment-region} uncomments each line in the region; a numeric prefix
argument specifies the number of comment delimiters to remove
(negative arguments specify the number of comment to delimiters to
add).
Dave Love's avatar
#  
Dave Love committed
995

996 997
  For C-like modes, you can configure the exact effect of @kbd{M-;} by
setting the variables @code{c-indent-comment-alist} and
998 999 1000
@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
1001
@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
Dave Love's avatar
#  
Dave Love committed
1002 1003 1004 1005 1006

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

@kindex C-M-j
1007
@kindex M-j
Dave Love's avatar
#  
Dave Love committed
1008
@cindex blank lines in programs
1009
@findex comment-indent-new-line
1010 1011 1012 1013 1014 1015
@vindex comment-multi-line
  If you are typing a comment and wish to continue it to another line,
type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}).  This
breaks the current line, and inserts the necessary comment delimiters
and indentation to continue the comment.

1016
  For languages with closing comment delimiters (e.g., @samp{*/} in
1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034
C), the exact behavior of @kbd{M-j} depends on the value of the
variable @code{comment-multi-line}.  If the value is @code{nil}, the
command closes the comment on the old line and starts a new comment on
the new line.  Otherwise, it opens a new line within the current
comment delimiters.

  When Auto Fill mode is on, going past the fill column while typing a
comment also continues the comment, in the same way as an explicit
invocation of @kbd{M-j}.

  To turn existing lines into comment lines, use @kbd{M-;} with the
region active, or use @kbd{M-x comment-region}
@ifinfo
(@pxref{Comment Commands}).
@end ifinfo
@ifnotinfo
as described in the preceding section.
@end ifnotinfo
Dave Love's avatar
#  
Dave Love committed
1035

1036 1037 1038 1039 1040
  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
1041 1042 1043 1044 1045
@node Options for Comments
@subsection Options Controlling Comments

@vindex comment-column
@kindex C-x ;
1046
@findex comment-set-column
1047 1048 1049 1050 1051 1052 1053 1054 1055 1056
  As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
adds a comment to a line, it tries to place the comment at the column
specified by the buffer-local variable @code{comment-column}.  You can
set either the local value or the default value of this buffer-local
variable in the usual way (@pxref{Locals}).  Alternatively, you can
type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
@code{comment-column} in the current buffer to the column where point
is currently located.  @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
1057 1058 1059 1060 1061 1062

@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;
1063 1064
for example, in C mode the value of the variable is
@c This stops M-q from breaking the line inside that @code.
1065 1066 1067 1068 1069
@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
spaces after the @samp{/*} itself, and accepts C++ style comments
also.  (Note that @samp{\\} is needed in Lisp syntax to include a
@samp{\} in the string, which is needed to deny the first star its
special meaning in regexp syntax.  @xref{Regexp Backslash}.)
Dave Love's avatar
#  
Dave Love committed
1070 1071 1072 1073

@vindex comment-start
@vindex comment-end
  When a comment command makes a new comment, it inserts the value of
1074 1075 1076 1077 1078 1079
@code{comment-start} as an opening comment delimiter.  It also inserts
the value of @code{comment-end} after point, as a closing comment
delimiter.  For example, in Lisp mode, @code{comment-start} is
@samp{";"} and @code{comment-end} is @code{""} (the empty string).  In
C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
@code{" */"}.
Dave Love's avatar
#  
Dave Love committed
1080

1081
@vindex comment-padding
1082 1083 1084 1085 1086