1@c -*- coding: utf-8 -*- 2@c This is part of the Emacs manual. 3@c Copyright (C) 1985--1987, 1993--1995, 1997, 1999--2021 Free Software 4@c Foundation, Inc. 5@c See file emacs.texi for copying conditions. 6@node Programs 7@chapter Editing Programs 8@cindex Lisp editing 9@cindex C editing 10@cindex program editing 11 12 This chapter describes Emacs features for facilitating editing 13programs. Some of the things these features can do are: 14 15@itemize @bullet 16@item 17Find or move over top-level definitions (@pxref{Defuns}). 18@item 19Apply the usual indentation conventions of the language 20(@pxref{Program Indent}). 21@item 22Balance parentheses (@pxref{Parentheses}). 23@item 24Insert, kill or align comments (@pxref{Comments}). 25@item 26Highlight program syntax (@pxref{Font Lock}). 27@end itemize 28 29@menu 30* Program Modes:: Major modes for editing programs. 31* Defuns:: Commands to operate on major top-level parts 32 of a program. 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* Misc for Programs:: Other Emacs features useful for editing programs. 42* C Modes:: Special commands of C, C++, Objective-C, Java, 43 IDL, Pike and AWK modes. 44* Asm Mode:: Asm mode and its special features. 45@ifnottex 46* Fortran:: Fortran mode and its special features. 47@end ifnottex 48@end menu 49 50@node Program Modes 51@section Major Modes for Programming Languages 52@cindex modes for programming languages 53 54 Emacs has specialized major modes (@pxref{Major Modes}) for many 55programming languages. A programming language mode typically 56specifies the syntax of expressions, the customary rules for 57indentation, how to do syntax highlighting for the language, and how 58to find the beginning or end of a function definition. It often has 59features for compiling and debugging programs as well. The major mode 60for each language is named after the language; for instance, the major 61mode for the C programming language is @code{c-mode}. 62 63@cindex Perl mode 64@cindex Icon mode 65@cindex Makefile mode 66@cindex Tcl mode 67@cindex CPerl mode 68@cindex DSSSL mode 69@cindex Octave mode 70@cindex Metafont mode 71@cindex Modula2 mode 72@cindex Prolog mode 73@cindex Python mode 74@cindex Ruby mode 75@cindex Simula mode 76@cindex Verilog mode 77@cindex VHDL mode 78@cindex M4 mode 79@cindex Shell-script mode 80@cindex OPascal mode 81@cindex PostScript mode 82@cindex Conf mode 83@cindex DNS mode 84@cindex Javascript mode 85@cindex Awk mode 86 Emacs has programming language modes for Lisp, Scheme, the 87Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, 88Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles, 89Metafont (@TeX{}'s companion for font creation), Modula2, Object 90Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, 91Python, Ruby, Simula, SQL, Tcl, Verilog, and VHDL@. An alternative 92mode for Perl is called CPerl mode. Modes are also available for the 93scripting languages of the common GNU and Unix shells, and 94MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, DNS master 95files, and various sorts of configuration files. 96 97 Ideally, Emacs should have a major mode for each programming 98language that you might want to edit. If it doesn't have a mode for 99your favorite language, the mode might be implemented in a package not 100distributed with Emacs (@pxref{Packages}); or you can contribute one. 101 102@kindex DEL @r{(programming modes)} 103@findex backward-delete-char-untabify 104 In most programming languages, indentation should vary from line to 105line to illustrate the structure of the program. Therefore, in most 106programming language modes, typing @kbd{@key{TAB}} updates the 107indentation of the current line (@pxref{Program Indent}). 108Furthermore, @kbd{@key{DEL}} is usually bound to 109@code{backward-delete-char-untabify}, which deletes backward treating 110each tab as if it were the equivalent number of spaces, so that you 111can delete one column of indentation without worrying whether the 112whitespace consists of spaces or tabs. 113 114@cindex mode hook, and major modes 115@vindex c-mode-hook 116@vindex lisp-mode-hook 117@vindex emacs-lisp-mode-hook 118@vindex lisp-interaction-mode-hook 119@vindex scheme-mode-hook 120 Entering a programming language mode runs the custom Lisp functions 121specified in the hook variable @code{prog-mode-hook}, followed by 122those specified in the mode's own mode hook (@pxref{Major Modes}). 123For instance, entering C mode runs the hooks @code{prog-mode-hook} and 124@code{c-mode-hook}. @xref{Hooks}, for information about hooks. 125 126@ifnottex 127 Separate manuals are available for the modes for Ada (@pxref{Top,, 128Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba 129IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), Octave, VHDL, 130and IDLWAVE (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). 131@end ifnottex 132@iftex 133 The Emacs distribution contains Info manuals for the major modes for 134Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, Octave, VHDL, and 135IDLWAVE@. For Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized 136Emacs Features}. 137@end iftex 138 139@node Defuns 140@section Top-Level Definitions, or Defuns 141 142 In Emacs, a major definition at the top level in the buffer, such as 143a function, is called a @dfn{defun}. The name comes from Lisp, but in 144Emacs we use it for all languages. 145 146@menu 147* Left Margin Paren:: An open-paren or similar opening delimiter 148 starts a defun if it is at the left margin. 149* Moving by Defuns:: Commands to move over or mark a major definition. 150* Imenu:: Making buffer indexes as menus. 151* Which Function:: Which Function mode shows which function you are in. 152@end menu 153 154@node Left Margin Paren 155@subsection Left Margin Convention 156 157@cindex open-parenthesis in leftmost column 158@cindex ( in leftmost column 159 Many programming-language modes have traditionally assumed that any 160opening parenthesis or brace found at the left margin is the start of 161a top-level definition, or defun. So, by default, commands which seek 162the beginning of a defun accept such a delimiter as signifying that 163position. 164 165@vindex open-paren-in-column-0-is-defun-start 166 If you want to override this convention, you can do so by setting 167the user option @code{open-paren-in-column-0-is-defun-start} to 168@code{nil}. If this option is set to @code{t} (the default), commands 169seeking the start of a defun will stop at opening parentheses or 170braces at column zero which aren't in a comment or string. When it is 171@code{nil}, defuns are found by searching for parens or braces at the 172outermost level. Since low-level Emacs routines no longer depend on 173this convention, you usually won't need to change 174@code{open-paren-in-column-0-is-defun-start} from its default. 175 176@node Moving by Defuns 177@subsection Moving by Defuns 178@cindex defuns 179 180 These commands move point or set up the region based on top-level 181major definitions, also called @dfn{defuns}. 182 183@table @kbd 184@item C-M-a 185Move to beginning of current or preceding defun 186(@code{beginning-of-defun}). 187@item C-M-e 188Move to end of current or following defun (@code{end-of-defun}). 189@item C-M-h 190Put region around whole current or following defun (@code{mark-defun}). 191@end table 192 193@cindex move to beginning or end of function 194@cindex function, move to beginning or end 195@kindex C-M-a 196@kindex C-M-e 197@kindex C-M-h 198@findex beginning-of-defun 199@findex end-of-defun 200@findex mark-defun 201 The commands to move to the beginning and end of the current defun 202are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} 203(@code{end-of-defun}). If you repeat one of these commands, or use a 204positive numeric argument, each repetition moves to the next defun in 205the direction of motion. 206 207 @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward 208@var{n} times to the next beginning of a defun. This is not exactly 209the same place that @kbd{C-M-e} with argument @var{n} would move to; 210the end of this defun is not usually exactly the same place as the 211beginning of the following defun. (Whitespace, comments, and perhaps 212declarations can separate them.) Likewise, @kbd{C-M-e} with a 213negative argument moves back to an end of a defun, which is not quite 214the same as @kbd{C-M-a} with a positive argument. 215 216@kindex C-M-h @r{(C mode)} 217@findex c-mark-function 218 To operate on the current defun, use @kbd{C-M-h} 219(@code{mark-defun}), which sets the mark at the end of the current 220defun and puts point at its beginning. @xref{Marking Objects}. This 221is the easiest way to get ready to kill the defun in order to move it 222to a different place in the file. If the defun is directly preceded 223by comments (with no intervening blank lines), they are marked, too. 224If you use the command while point is between defuns, it uses the 225following defun. If you use the command while the mark is already 226active, it extends the end of the region to include one more defun. 227With a prefix argument, it marks that many defuns or extends the 228region by the appropriate number of defuns. With negative prefix 229argument it marks defuns in the opposite direction and also changes 230the direction of selecting for subsequent uses of @code{mark-defun}. 231 232 In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, 233which is almost the same as @code{mark-defun}; the difference is that 234it backs up over the argument declarations, function name and returned 235data type so that the entire C function is inside the region. This is 236an example of how major modes adjust the standard key bindings so that 237they do their standard jobs in a way better fitting a particular 238language. Other major modes may replace any or all of these key 239bindings for that purpose. 240 241@node Imenu 242@subsection Imenu 243@cindex index of buffer definitions 244@cindex buffer definitions index 245 246 The Imenu facility offers a way to find the major definitions in 247a file by name. It is also useful in text formatter major modes, 248where it treats each chapter, section, etc., as a definition. 249(@xref{Xref}, for a more powerful feature that handles multiple files 250together.) 251 252@findex imenu 253 If you type @kbd{M-x imenu}, it reads the name of a definition using 254the minibuffer, then moves point to that definition. You can use 255completion to specify the name; the command always displays the whole 256list of valid names. 257 258@findex imenu-add-menubar-index 259 Alternatively, you can bind the command @code{imenu} to a mouse 260click. Then it displays mouse menus for you to select a definition 261name. You can also add the buffer's index to the menu bar by calling 262@code{imenu-add-menubar-index}. If you want to have this menu bar 263item available for all buffers in a certain major mode, you can do 264this by adding @code{imenu-add-menubar-index} to its mode hook. But 265if you have done that, you will have to wait a little while each time 266you visit a file in that mode, while Emacs finds all the definitions 267in that buffer. 268 269@vindex imenu-auto-rescan 270 When you change the contents of a buffer, if you add or delete 271definitions, you can update the buffer's index based on the 272new contents by invoking the @samp{*Rescan*} item in the menu. 273Rescanning happens automatically if you set @code{imenu-auto-rescan} to 274a non-@code{nil} value. There is no need to rescan because of small 275changes in the text. 276 277@vindex imenu-auto-rescan-maxout 278 @code{imenu-auto-rescan} will be disabled in buffers that are larger 279than @code{imenu-auto-rescan-maxout} in bytes. 280 281@vindex imenu-sort-function 282 You can customize the way the menus are sorted by setting the 283variable @code{imenu-sort-function}. By default, names are ordered as 284they occur in the buffer; if you want alphabetic sorting, use the 285symbol @code{imenu--sort-by-name} as the value. You can also 286define your own comparison function by writing Lisp code. 287 288 Imenu provides the information to guide Which Function mode 289@ifnottex 290(@pxref{Which Function}). 291@end ifnottex 292@iftex 293(see below). 294@end iftex 295The Speedbar can also use it (@pxref{Speedbar}). 296 297@node Which Function 298@subsection Which Function Mode 299@cindex current function name in mode line 300 301 Which Function mode is a global minor mode (@pxref{Minor Modes}) 302which displays the current function name in the mode line, updating it 303as you move around in a buffer. 304 305@findex which-function-mode 306@vindex which-func-modes 307 To either enable or disable Which Function mode, use the command 308@kbd{M-x which-function-mode}. Which Function mode is a global minor 309mode. By default, it takes effect in all major modes that 310know how to support it (i.e., all the major modes that support 311Imenu). You can restrict it to a specific list of major modes by 312changing the value of the variable @code{which-func-modes} from 313@code{t} (which means to support all available major modes) to a list 314of major mode names. 315 316@node Program Indent 317@section Indentation for Programs 318@cindex indentation for programs 319 320 The best way to keep a program properly indented is to use Emacs to 321reindent it as you change it. Emacs has commands to indent either a 322single line, a specified number of lines, or all of the lines inside a 323single parenthetical grouping. 324 325 @xref{Indentation}, for general information about indentation. This 326section describes indentation features specific to programming 327language modes. 328 329@menu 330* Basic Indent:: Indenting a single line. 331* Multi-line Indent:: Commands to reindent many lines at once. 332* Lisp Indent:: Specifying how each Lisp function should be indented. 333* C Indent:: Extra features for indenting C and related modes. 334* Custom C Indent:: Controlling indentation style for C and related modes. 335@end menu 336 337@cindex pretty-printer 338 Emacs also provides a Lisp pretty-printer in the @code{pp} package, 339which reformats Lisp objects with nice-looking indentation. 340@xref{Output Functions, pp,, elisp, The Emacs Lisp Reference Manual}. 341 342@node Basic Indent 343@subsection Basic Program Indentation Commands 344 345@table @kbd 346@item @key{TAB} 347Adjust indentation of current line (@code{indent-for-tab-command}). 348@item @key{RET} 349Insert a newline, then adjust indentation of following line 350(@code{newline}). 351@end table 352 353@kindex TAB @r{(programming modes)} 354@findex indent-line-function 355 The basic indentation command is @kbd{@key{TAB}} 356(@code{indent-for-tab-command}), which was documented in 357@ref{Indentation}. In programming language modes, @kbd{@key{TAB}} 358indents the current line, based on the indentation and syntactic 359content of the preceding lines; if the region is active, 360@kbd{@key{TAB}} indents each line within the region, not just the 361current line. 362 363 The command @kbd{@key{RET}} (@code{newline}), which was documented 364in @ref{Inserting Text}, does the same as @kbd{C-j} followed by 365@kbd{@key{TAB}}: it inserts a new line, then adjusts the line's 366indentation. 367 368 When indenting a line that starts within a parenthetical grouping, 369Emacs usually places the start of the line under the preceding line 370within the group, or under the text after the parenthesis. If you 371manually give one of these lines a nonstandard indentation (e.g., for 372aesthetic purposes), the lines below will follow it. 373 374 The indentation commands for most programming language modes assume 375that an open-parenthesis, open-brace or other opening delimiter at the 376left margin is the start of a function. If the code you are editing 377violates this assumption---even if the delimiters occur in strings or 378comments---you must set @code{open-paren-in-column-0-is-defun-start} 379to @code{nil} for indentation to work properly. @xref{Left Margin 380Paren}. 381 382@node Multi-line Indent 383@subsection Indenting Several Lines 384 385 Sometimes, you may want to reindent several lines of code at a time. 386One way to do this is to use the mark; when the mark is active and the 387region is non-empty, @kbd{@key{TAB}} indents every line in the region. 388Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents 389every line in the region, whether or not the mark is active 390(@pxref{Indentation Commands}). 391 392 In addition, Emacs provides the following commands for indenting 393large chunks of code: 394 395@table @kbd 396@item C-M-q 397Reindent all the lines within one parenthetical grouping. 398@item C-u @key{TAB} 399Shift an entire parenthetical grouping rigidly sideways so that its 400first line is properly indented. 401@item M-x indent-code-rigidly 402Shift all the lines in the region rigidly sideways, but do not alter 403lines that start inside comments and strings. 404@end table 405 406@kindex C-M-q 407@findex indent-pp-sexp 408 To reindent the contents of a single parenthetical grouping, 409position point before the beginning of the grouping and type 410@kbd{C-M-q}. This changes the relative indentation within the 411grouping, without affecting its overall indentation (i.e., the 412indentation of the line where the grouping starts). The function that 413@kbd{C-M-q} runs depends on the major mode; it is 414@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, 415etc. To correct the overall indentation as well, type @kbd{@key{TAB}} 416first. 417 418@kindex C-u TAB 419 If you like the relative indentation within a grouping but not the 420indentation of its first line, move point to that first line and type 421@kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, 422@kbd{@key{TAB}} with a numeric argument reindents the current line as 423usual, then reindents by the same amount all the lines in the 424parenthetical grouping starting on the current line. It is clever, 425though, and does not alter lines that start inside strings. Neither 426does it alter C preprocessor lines when in C mode, but it does 427reindent any continuation lines that may be attached to them. 428 429@findex indent-code-rigidly 430 The command @kbd{M-x indent-code-rigidly} rigidly shifts all the 431lines in the region sideways, like @code{indent-rigidly} does 432(@pxref{Indentation Commands}). It doesn't alter the indentation of 433lines that start inside a string, unless the region also starts inside 434that string. The prefix arg specifies the number of columns to 435indent. 436 437@node Lisp Indent 438@subsection Customizing Lisp Indentation 439@cindex customizing Lisp indentation 440 441 The indentation pattern for a Lisp expression can depend on the function 442called by the expression. For each Lisp function, you can choose among 443several predefined patterns of indentation, or define an arbitrary one with 444a Lisp program. 445 446 The standard pattern of indentation is as follows: the second line of the 447expression is indented under the first argument, if that is on the same 448line as the beginning of the expression; otherwise, the second line is 449indented underneath the function name. Each following line is indented 450under the previous line whose nesting depth is the same. 451 452@vindex lisp-indent-offset 453 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides 454the usual indentation pattern for the second line of an expression, so that 455such lines are always indented @code{lisp-indent-offset} more columns than 456the containing list. 457 458@vindex lisp-body-indent 459 Certain functions override the standard pattern. Functions whose 460names start with @code{def} treat the second lines as the start of 461a @dfn{body}, by indenting the second line @code{lisp-body-indent} 462additional columns beyond the open-parenthesis that starts the 463expression. 464 465@cindex @code{lisp-indent-function} property 466 You can override the standard pattern in various ways for individual 467functions, according to the @code{lisp-indent-function} property of 468the function name. This is normally done for macro definitions, using 469the @code{declare} construct. @xref{Defining Macros,,, elisp, The 470Emacs Lisp Reference Manual}. 471 472@node C Indent 473@subsection Commands for C Indentation 474 475 Here are special features for indentation in C mode and related modes: 476 477@table @kbd 478@item C-c C-q 479@kindex C-c C-q @r{(C mode)} 480@findex c-indent-defun 481Reindent the current top-level function definition or aggregate type 482declaration (@code{c-indent-defun}). 483 484@item C-M-q 485@kindex C-M-q @r{(C mode)} 486@findex c-indent-exp 487Reindent each line in the balanced expression that follows point 488(@code{c-indent-exp}). A prefix argument inhibits warning messages 489about invalid syntax. 490 491@item @key{TAB} 492@findex c-indent-command 493Reindent the current line, and/or in some cases insert a tab character 494(@code{c-indent-command}). 495 496@vindex c-tab-always-indent 497If @code{c-tab-always-indent} is @code{t}, this command always reindents 498the current line and does nothing else. This is the default. 499 500If that variable is @code{nil}, this command reindents the current line 501only if point is at the left margin or in the line's indentation; 502otherwise, it inserts a tab (or the equivalent number of spaces, 503if @code{indent-tabs-mode} is @code{nil}). 504 505Any other value (not @code{nil} or @code{t}) means always reindent the 506line, and also insert a tab if within a comment or a string. 507@end table 508 509 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This 510first selects the whole buffer as the region, then reindents that 511region. 512 513 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves 514to the front of the block and then reindents it all. 515 516@node Custom C Indent 517@subsection Customizing C Indentation 518@cindex style (for indentation) 519 520 C mode and related modes use a flexible mechanism for customizing 521indentation. C mode indents a source line in two steps: first it 522classifies the line syntactically according to its contents and 523context; second, it determines the indentation offset associated by 524your selected @dfn{style} with the syntactic construct and adds this 525onto the indentation of the @dfn{anchor statement}. 526 527@table @kbd 528@item C-c . @var{style} @key{RET} 529Select a predefined style @var{style} (@code{c-set-style}). 530@end table 531 532 A @dfn{style} is a named collection of customizations that can be 533used in C mode and the related modes. @ref{Styles,,, ccmode, The CC 534Mode Manual}, for a complete description. Emacs comes with several 535predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, 536@code{stroustrup}, @code{linux}, @code{python}, @code{java}, 537@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these 538styles are primarily intended for one language, but any of them can be 539used with any of the languages supported by these modes. To find out 540what a style looks like, select it and reindent some code, e.g., by 541typing @kbd{C-M-q} at the start of a function definition. 542 543@kindex C-c . @r{(C mode)} 544@findex c-set-style 545 To choose a style for the current buffer, use the command @w{@kbd{C-c 546.}}. Specify a style name as an argument (case is not significant). 547This command affects the current buffer only, and it affects only 548future invocations of the indentation commands; it does not reindent 549the code already in the buffer. To reindent the whole buffer in the 550new style, you can type @kbd{C-x h C-M-\}. 551 552@vindex c-default-style 553 You can also set the variable @code{c-default-style} to specify the 554default style for various major modes. Its value should be either the 555style's name (a string) or an alist, in which each element specifies 556one major mode and which indentation style to use for it. For 557example, 558 559@example 560(setq c-default-style 561 '((java-mode . "java") 562 (awk-mode . "awk") 563 (other . "gnu"))) 564@end example 565 566@noindent 567specifies explicit choices for Java and AWK modes, and the default 568@samp{gnu} style for the other C-like modes. (These settings are 569actually the defaults.) This variable takes effect when you select 570one of the C-like major modes; thus, if you specify a new default 571style for Java mode, you can make it take effect in an existing Java 572mode buffer by typing @kbd{M-x java-mode} there. 573 574 The @code{gnu} style specifies the formatting recommended by the GNU 575Project for C; it is the default, so as to encourage use of our 576recommended style. 577 578 @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and 579@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more 580information on customizing indentation for C and related modes, 581including how to override parts of an existing style and how to define 582your own styles. 583 584@findex c-guess 585@findex c-guess-install 586 As an alternative to specifying a style, you can tell Emacs to guess 587a style by typing @kbd{M-x c-guess} in a sample code buffer. You can 588then apply the guessed style to other buffers with @kbd{M-x 589c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode 590Manual}, for details. 591 592@node Parentheses 593@section Commands for Editing with Parentheses 594 595@findex check-parens 596@cindex unbalanced parentheses and quotes 597 This section describes the commands and features that take advantage 598of the parenthesis structure in a program, or help you keep it 599balanced. 600 601 When talking about these facilities, the term ``parenthesis'' also 602includes braces, brackets, or whatever delimiters are defined to match 603in pairs. The major mode controls which delimiters are significant, 604through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp, 605The Emacs Lisp Reference Manual}). In Lisp, only parentheses count; 606in C, these commands apply to braces and brackets too. 607 608 You can use @kbd{M-x check-parens} to find any unbalanced 609parentheses and unbalanced string quotes in the buffer. 610 611@menu 612* Expressions:: Expressions with balanced parentheses. 613* Moving by Parens:: Commands for moving up, down and across 614 in the structure of parentheses. 615* Matching:: Insertion of a close-delimiter flashes matching open. 616@end menu 617 618@node Expressions 619@subsection Expressions with Balanced Parentheses 620 621@cindex sexp 622@cindex expression 623@cindex balanced expression 624 Each programming language mode has its own definition of a 625@dfn{balanced expression}. Balanced expressions typically include 626individual symbols, numbers, and string constants, as well as pieces 627of code enclosed in a matching pair of delimiters. The following 628commands deal with balanced expressions (in Emacs, such expressions 629are referred to internally as @dfn{sexps}@footnote{The word ``sexp'' 630is used to refer to an expression in Lisp.}). 631 632@table @kbd 633@item C-M-f 634Move forward over a balanced expression (@code{forward-sexp}). 635@item C-M-b 636Move backward over a balanced expression (@code{backward-sexp}). 637@item C-M-k 638Kill balanced expression forward (@code{kill-sexp}). 639@item C-M-t 640Transpose expressions (@code{transpose-sexps}). 641@item C-M-@@ 642@itemx C-M-@key{SPC} 643Put mark after following expression (@code{mark-sexp}). 644@end table 645 646@kindex C-M-f 647@kindex C-M-b 648@findex forward-sexp 649@findex backward-sexp 650 To move forward over a balanced expression, use @kbd{C-M-f} 651(@code{forward-sexp}). If the first significant character after point 652is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C), 653this command moves past the matching closing delimiter. If the 654character begins a symbol, string, or number, the command moves over 655that. 656 657 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a 658balanced expression---like @kbd{C-M-f}, but in the reverse direction. 659If the expression is preceded by any prefix characters (single-quote, 660backquote and comma, in Lisp), the command moves back over them as 661well. 662 663 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation 664the specified number of times; with a negative argument means to move 665in the opposite direction. In most modes, these two commands move 666across comments as if they were whitespace. Note that their keys, 667@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b}, 668which move by characters (@pxref{Moving Point}), and @kbd{M-f} and 669@kbd{M-b}, which move by words (@pxref{Words}). 670 671@cindex killing expressions 672@kindex C-M-k 673@findex kill-sexp 674 To kill a whole balanced expression, type @kbd{C-M-k} 675(@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move 676over. 677 678@cindex transposition of expressions 679@kindex C-M-t 680@findex transpose-sexps 681 @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the 682previous balanced expression and the next one. It is analogous to the 683@kbd{C-t} command, which transposes characters (@pxref{Transpose}). 684An argument to @kbd{C-M-t} serves as a repeat count, moving the 685previous expression over that many following ones. A negative 686argument moves the previous balanced expression backwards across those 687before it. An argument of zero, rather than doing nothing, transposes 688the balanced expressions ending at or after point and the mark. 689 690@kindex C-M-SPC 691 To operate on balanced expressions with a command which acts on the 692region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the 693mark where @kbd{C-M-f} would move to. While the mark is active, each 694successive call to this command extends the region by shifting the 695mark by one expression. Positive or negative numeric arguments move 696the mark forward or backward by the specified number of expressions. 697The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}. 698@xref{Marking Objects}, for more information about this and related 699commands. 700 701 In languages that use infix operators, such as C, it is not possible 702to recognize all balanced expressions because there can be multiple 703possibilities at a given position. For example, C mode does not treat 704@samp{foo + bar} as a single expression, even though it @emph{is} one 705C expression; instead, it recognizes @samp{foo} as one expression and 706@samp{bar} as another, with the @samp{+} as punctuation between them. 707However, C mode recognizes @samp{(foo + bar)} as a single expression, 708because of the parentheses. 709 710@node Moving by Parens 711@subsection Moving in the Parenthesis Structure 712 713@cindex parenthetical groupings 714@cindex parentheses, moving across 715@cindex matching parenthesis and braces, moving to 716@cindex braces, moving across 717@cindex list commands 718 719 The following commands move over groupings delimited by parentheses 720(or whatever else serves as delimiters in the language you are working 721with). They ignore strings and comments, including any parentheses 722within them, and also ignore parentheses that are quoted with an 723escape character. These commands are mainly intended for editing 724programs, but can be useful for editing any text containing 725parentheses. They are referred to internally as ``list commands'' 726because in Lisp these groupings are lists. 727 728 These commands assume that the starting point is not inside a string 729or a comment. If you invoke them from inside a string or comment, the 730results are unreliable. 731 732@table @kbd 733@item C-M-n 734Move forward over a parenthetical group (@code{forward-list}). 735@item C-M-p 736Move backward over a parenthetical group (@code{backward-list}). 737@item C-M-u 738Move up in parenthesis structure (@code{backward-up-list}). 739@item C-M-d 740Move down in parenthesis structure (@code{down-list}). 741@end table 742 743@kindex C-M-n 744@kindex C-M-p 745@findex forward-list 746@findex backward-list 747 The list commands @kbd{C-M-n} (@code{forward-list}) and 748@kbd{C-M-p} (@code{backward-list}) move forward or backward over one 749(or @var{n}) parenthetical groupings. 750 751@kindex C-M-u 752@findex backward-up-list 753 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the 754parenthesis structure. To move @emph{up} one (or @var{n}) levels, use 755@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up 756past one unmatched opening delimiter. A positive argument serves as a 757repeat count; a negative argument reverses the direction of motion, so 758that the command moves forward and up one or more levels. 759 760@kindex C-M-d 761@findex down-list 762 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} 763(@code{down-list}). In Lisp mode, where @samp{(} is the only opening 764delimiter, this is nearly the same as searching for a @samp{(}. An 765argument specifies the number of levels to go down. 766 767@node Matching 768@subsection Matching Parentheses 769@cindex matching parentheses 770@cindex parentheses, displaying matches 771 772 Emacs has a number of @dfn{parenthesis matching} features, which 773make it easy to see how and whether parentheses (or other delimiters) 774match up. 775 776 Whenever you type a self-inserting character that is a closing 777delimiter, Emacs briefly indicates the location of the matching 778opening delimiter, provided that is on the screen. If it is not on 779the screen, Emacs displays some of the text near it in the echo area. 780Either way, you can tell which grouping you are closing off. If the 781opening delimiter and closing delimiter are mismatched---such as in 782@samp{[x)}---a warning message is displayed in the echo area. 783 784@vindex blink-matching-paren 785@vindex blink-matching-paren-distance 786@vindex blink-matching-delay 787 Three variables control the display of matching parentheses: 788 789@itemize @bullet 790@item 791@code{blink-matching-paren} turns the feature on or off: @code{nil} 792disables it, but the default is @code{t} to enable it. Set it to 793@code{jump} to make indication work by momentarily moving the cursor 794to the matching opening delimiter. Set it to @code{jump-offscreen} to 795make the cursor jump, even if the opening delimiter is off screen. 796 797@item 798@code{blink-matching-delay} says how many seconds to keep indicating 799the matching opening delimiter. This may be an integer or 800floating-point number; the default is 1. 801 802@item 803@code{blink-matching-paren-distance} specifies how many characters 804back to search to find the matching opening delimiter. If the match 805is not found in that distance, Emacs stops scanning and nothing is 806displayed. The default is 102400. 807@end itemize 808 809@cindex Show Paren mode 810@cindex highlighting matching parentheses 811@findex show-paren-mode 812 Show Paren mode, a global minor mode, provides a more powerful kind 813of automatic matching. Whenever point is before an opening delimiter 814or after a closing delimiter, the delimiter, its matching delimiter, 815and optionally the text between them are highlighted. To toggle Show 816Paren mode, type @kbd{M-x show-paren-mode}. To customize it, type 817@kbd{M-x customize-group @key{RET} paren-showing}. The customizable 818options which control the operation of this mode include: 819 820@itemize @bullet 821@item 822@vindex show-paren-highlight-openparen 823@code{show-paren-highlight-openparen} controls whether to highlight 824an open paren when point stands just before it, and hence its position 825is marked by the cursor anyway. The default is non-@code{nil} (yes). 826 827@item 828@vindex show-paren-style 829@code{show-paren-style} controls whether just the two parens, or also 830the space between them get highlighted. The valid options here are 831@code{parenthesis} (show the matching paren), @code{expression} 832(highlight the entire expression enclosed by the parens), and 833@code{mixed} (highlight the matching paren if it is visible, the 834expression otherwise). 835 836@item 837@vindex show-paren-when-point-inside-paren 838@code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes 839highlighting also when point is on the inside of a parenthesis. 840 841@item 842@vindex show-paren-when-point-in-periphery 843@code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes 844highlighting also when point is in whitespace at the beginning or end 845of a line, and there is a paren at, respectively, the first or last, 846or the last, non-whitespace position on the line. 847@end itemize 848 849@cindex Electric Pair mode 850@cindex inserting matching parentheses 851@findex electric-pair-mode 852 Electric Pair mode, a global minor mode, provides a way to easily 853insert matching delimiters: parentheses, braces, brackets, etc. 854Whenever you insert an opening delimiter, the matching closing 855delimiter is automatically inserted as well, leaving point between the 856two. Conversely, when you insert a closing delimiter over an existing 857one, no insertion takes places, and that position is simply skipped 858over. If the region is active (@pxref{Mark}), insertion of a 859delimiter operates on the region: the characters in the region are 860enclosed in a pair of matching delimiters, leaving point after the 861delimiter you typed. 862 863These variables control additional features of Electric Pair mode: 864 865@itemize @bullet 866@item 867@vindex electric-pair-preserve-balance 868@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the 869default pairing logic balance out the number of opening and closing 870delimiters. 871 872@item 873@vindex electric-pair-delete-adjacent-pairs 874@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes 875backspacing between two adjacent delimiters also automatically delete 876the closing delimiter. 877 878@item 879@vindex electric-pair-open-newline-between-pairs 880@code{electric-pair-open-newline-between-pairs}, when non-@code{nil}, 881makes inserting a newline between two adjacent pairs also 882automatically open an extra newline after point. 883 884@item 885@vindex electric-pair-skip-whitespace 886@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor 887mode to skip whitespace forward before deciding whether to skip over 888the closing delimiter. 889@end itemize 890 891To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}. To 892toggle the mode in a single buffer, use @kbd{M-x 893electric-pair-local-mode}. 894 895@node Comments 896@section Manipulating Comments 897@cindex comments 898 899 Because comments are such an important part of programming, Emacs 900provides special commands for editing and inserting comments. It can 901also do spell checking on comments with Flyspell Prog mode 902(@pxref{Spelling}). 903 904 Some major modes have special rules for indenting different kinds of 905comments. For example, in Lisp code, comments starting with two 906semicolons are indented as if they were lines of code, while those 907starting with three semicolons are supposed to be aligned to the left 908margin and are often used for sectioning purposes. Emacs understands 909these conventions; for instance, typing @kbd{@key{TAB}} on a comment 910line will indent the comment to the appropriate position. 911 912@example 913;; This function is just an example. 914;;; Here either two or three semicolons are appropriate. 915(defun foo (x) 916;;; And now, the first part of the function: 917 ;; The following line adds one. 918 (1+ x)) ; This line adds one. 919@end example 920 921@menu 922* Comment Commands:: Inserting, killing, and aligning comments. 923* Multi-Line Comments:: Commands for adding and editing multi-line comments. 924* Options for Comments::Customizing the comment features. 925@end menu 926 927@node Comment Commands 928@subsection Comment Commands 929@cindex indentation for comments 930@cindex alignment for comments 931 932 The following commands operate on comments: 933 934@table @asis 935@item @kbd{M-;} 936Insert or realign comment on current line; if the region is active, 937comment or uncomment the region instead (@code{comment-dwim}). 938@item @kbd{C-x C-;} 939Comment or uncomment the current line (@code{comment-line}). If the 940region is active, comment or uncomment the lines in the region 941instead. 942@item @kbd{C-u M-;} 943Kill comment on current line (@code{comment-kill}). 944@item @kbd{C-x ;} 945Set comment column (@code{comment-set-column}). 946@item @kbd{C-M-j} 947@itemx @kbd{M-j} 948Like @kbd{@key{RET}} followed by inserting and aligning a comment 949(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. 950@item @kbd{M-x comment-region} 951@itemx @kbd{C-c C-c} (in C-like modes) 952Add comment delimiters to all the lines in the region. 953@end table 954 955@kindex M-; 956@findex comment-dwim 957 The command to create or align a comment is @kbd{M-;} 958(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What 959I Mean''; it indicates that this command can be used for many 960different jobs relating to comments, depending on the situation where 961you use it. 962 963 When a region is active (@pxref{Mark}), @kbd{M-;} either adds 964comment delimiters to the region, or removes them. If every line in 965the region is already a comment, it uncomments each of those lines 966by removing their comment delimiters. Otherwise, it adds comment 967delimiters to enclose the text in the region. 968 969 If you supply a prefix argument to @kbd{M-;} when a region is 970active, that specifies the number of comment delimiters to add or 971delete. A positive argument @var{n} adds @var{n} delimiters, while a 972negative argument @minus{}@var{n} removes @var{n} delimiters. 973 974 If the region is not active, and there is no existing comment on the 975current line, @kbd{M-;} adds a new comment to the current line. If 976the line is blank (i.e., empty or containing only whitespace 977characters), the comment is indented to the same position where 978@kbd{@key{TAB}} would indent to (@pxref{Basic Indent}). If the line 979is non-blank, the comment is placed after the last non-whitespace 980character on the line. Emacs tries to fit the comment between the 981columns specified by the variables @code{comment-column} and 982@code{comment-fill-column} (@pxref{Options for Comments}), if 983possible. Otherwise, it will choose some other suitable position, 984usually separated from the non-comment text by at least one space. In 985each case, Emacs places point after the comment's starting delimiter, 986so that you can start typing the comment text right away. 987 988 You can also use @kbd{M-;} to align an existing comment. If a line 989already contains the comment-start string, @kbd{M-;} realigns it to 990the conventional alignment and moves point after the comment's 991starting delimiter. As an exception, comments starting in column 0 992are not moved. Even when an existing comment is properly aligned, 993@kbd{M-;} is still useful for moving directly to the start of the 994comment text. 995 996@findex comment-line 997@kindex C-x C-; 998 @kbd{C-x C-;} (@code{comment-line}) comments or uncomments complete 999lines. When a region is active (@pxref{Mark}), @kbd{C-x C-;} either 1000comments or uncomments the lines in the region. If the region is not 1001active, this command comments or uncomments the line point is on. 1002With a positive prefix argument @var{n}, it operates on @var{n} lines 1003starting with the current one; with a negative argument 1004@minus{}@var{n}, it affects @var{n} preceding lines. After invoking 1005this command with a negative argument, successive invocations with a 1006positive argument will operate on preceding lines as if the argument 1007were negated. 1008 1009@findex comment-kill 1010@kindex C-u M-; 1011 @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any 1012comment on the current line, along with the whitespace before it. 1013Since the comment is saved to the kill ring, you can reinsert it on 1014another line by moving to the end of that line, doing @kbd{C-y}, and 1015then @kbd{M-;} to realign the comment. You can achieve the same 1016effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill} 1017(@code{comment-dwim} actually calls @code{comment-kill} as a 1018subroutine when it is given a prefix argument). 1019 1020@kindex C-c C-c @r{(C mode)} 1021@findex comment-region 1022@findex uncomment-region 1023 The command @kbd{M-x comment-region} is equivalent to calling 1024@kbd{M-;} on an active region, except that it always acts on the 1025region, even if the mark is inactive. In C mode and related modes, 1026this command is bound to @kbd{C-c C-c}. The command @kbd{M-x 1027uncomment-region} uncomments each line in the region; a numeric prefix 1028argument specifies the number of comment delimiters to remove 1029(negative arguments specify the number of comment delimiters to add). 1030 1031 For C-like modes, you can configure the exact effect of @kbd{M-;} by 1032setting the variables @code{c-indent-comment-alist} and 1033@code{c-indent-comments-syntactically-p}. For example, on a line 1034ending in a closing brace, @kbd{M-;} puts the comment one space after 1035the brace rather than at @code{comment-column}. For full details see 1036@ref{Comment Commands,,, ccmode, The CC Mode Manual}. 1037 1038@node Multi-Line Comments 1039@subsection Multiple Lines of Comments 1040 1041@kindex C-M-j 1042@kindex M-j 1043@cindex blank lines in programs 1044@findex comment-indent-new-line 1045@vindex comment-multi-line 1046 If you are typing a comment and wish to continue it to another line, 1047type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This 1048breaks the current line, and inserts the necessary comment delimiters 1049and indentation to continue the comment. 1050 1051 For languages with closing comment delimiters (e.g., @samp{*/} in 1052C), the exact behavior of @kbd{M-j} depends on the value of the 1053variable @code{comment-multi-line}. If the value is @code{nil}, the 1054command closes the comment on the old line and starts a new comment on 1055the new line. Otherwise, it opens a new line within the current 1056comment delimiters. 1057 1058 When Auto Fill mode is on, going past the fill column while typing a 1059comment also continues the comment, in the same way as an explicit 1060invocation of @kbd{M-j}. 1061 1062 To turn existing lines into comment lines, use @kbd{M-;} with the 1063region active, or use @kbd{M-x comment-region} 1064@ifinfo 1065(@pxref{Comment Commands}). 1066@end ifinfo 1067@ifnotinfo 1068as described in the preceding section. 1069@end ifnotinfo 1070 1071 You can configure C Mode such that when you type a @samp{/} at the 1072start of a line in a multi-line block comment, this closes the 1073comment. Enable the @code{comment-close-slash} clean-up for this. 1074@xref{Clean-ups,,, ccmode, The CC Mode Manual}. 1075 1076@node Options for Comments 1077@subsection Options Controlling Comments 1078 1079@vindex comment-column 1080@vindex comment-fill-column 1081@kindex C-x ; 1082@findex comment-set-column 1083 As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command 1084adds a comment to a line, it tries to place the comment between the 1085columns specified by the buffer-local variables @code{comment-column} 1086and @code{comment-fill-column} (or if that is @code{nil}, then the 1087value of @code{fill-column}, @pxref{Fill Commands}). You can set 1088either the local value or the default value of these buffer-local 1089variables in the usual way (@pxref{Locals}). Alternatively, you can 1090type @kbd{C-x ;} (@code{comment-set-column}) to set the value of 1091@code{comment-column} in the current buffer to the column where point 1092is currently located. @kbd{C-u C-x ;} sets the comment column to 1093match the last comment before point in the buffer, and then does a 1094@kbd{M-;} to align the current line's comment under the previous one. 1095 1096@vindex comment-start-skip 1097 The comment commands recognize comments based on the regular 1098expression that is the value of the variable @code{comment-start-skip}. 1099Make sure this regexp does not match the null string. It may match more 1100than the comment starting delimiter in the strictest sense of the word; 1101for example, in C mode the value of the variable is 1102@c This stops M-q from breaking the line inside that @code. 1103@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and 1104spaces after the @samp{/*} itself, and accepts C++ style comments 1105also. (Note that @samp{\\} is needed in Lisp syntax to include a 1106@samp{\} in the string, which is needed to deny the first star its 1107special meaning in regexp syntax. @xref{Regexp Backslash}.) 1108 1109@vindex comment-start 1110@vindex comment-end 1111 When a comment command makes a new comment, it inserts the value of 1112@code{comment-start} as an opening comment delimiter. It also inserts 1113the value of @code{comment-end} after point, as a closing comment 1114delimiter. For example, in Lisp mode, @code{comment-start} is 1115@samp{";"} and @code{comment-end} is @code{""} (the empty string). In 1116C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is 1117@code{" */"}. 1118 1119@vindex comment-padding 1120 The variable @code{comment-padding} specifies a string that the 1121commenting commands should insert between the comment delimiter(s) and 1122the comment text. The default, @samp{" "}, specifies a single space. 1123Alternatively, the value can be a number, which specifies that number 1124of spaces, or @code{nil}, which means no spaces at all. 1125 1126 The variable @code{comment-multi-line} controls how @kbd{M-j} and 1127Auto Fill mode continue comments over multiple lines. 1128@xref{Multi-Line Comments}. 1129 1130@vindex comment-indent-function 1131 The variable @code{comment-indent-function} should contain a function 1132that will be called to compute the alignment for a newly inserted 1133comment or for aligning an existing comment. It is set differently by 1134various major modes. The function is called with no arguments, but with 1135point at the beginning of the comment, or at the end of a line if a new 1136comment is to be inserted. It should return the column in which the 1137comment ought to start. For example, the default function bases its 1138decision on how many comment characters begin an existing comment. 1139 1140Emacs also tries to align comments on adjacent lines. To override 1141this, the function may return a cons of two (possibly equal) integers 1142to indicate an acceptable range of indentation. 1143 1144@node Documentation 1145@section Documentation Lookup 1146 1147 Emacs provides several features you can use to look up the 1148documentation of functions, variables and commands that you plan to 1149use in your program. 1150 1151@menu 1152* Info Lookup:: Looking up library functions and commands in Info files. 1153* Man Page:: Looking up man pages of library functions and commands. 1154* Lisp Doc:: Looking up Emacs Lisp functions, etc. 1155@end menu 1156 1157@node Info Lookup 1158@subsection Info Documentation Lookup 1159 1160@findex info-lookup-file 1161 For major modes that apply to languages which have documentation in 1162Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the 1163Info documentation for a symbol used in the program. You specify the 1164symbol with the minibuffer; the default is the symbol appearing in the 1165buffer at point. For example, in C mode this looks for the symbol in 1166the C Library Manual. The command only works if the appropriate 1167manual's Info files are installed. 1168 1169 Emacs determines where to look for documentation for the 1170symbol---which Info files to look in, and which indices to 1171search---based on the major mode. You can also use @kbd{M-x 1172info-lookup-file} to look for documentation for a file name. 1173 1174 If you use @kbd{C-h S} in a major mode that does not support it, 1175it asks you to specify the symbol help mode. You should enter 1176a command such as @code{c-mode} that would select a major 1177mode which @kbd{C-h S} does support. 1178 1179@node Man Page 1180@subsection Man Page Lookup 1181 1182@cindex man page 1183 On Unix, the main form of on-line documentation was the @dfn{manual 1184page} or @dfn{man page}. In the GNU operating system, we aim to 1185replace man pages with better-organized manuals that you can browse 1186with Info (@pxref{Misc Help}). This process is not finished, so it is 1187still useful to read manual pages. 1188 1189@findex man 1190 You can read the man page for an operating system command, library 1191function, or system call, with the @kbd{M-x man} command. This 1192prompts for a topic, with completion (@pxref{Completion}), and runs 1193the @command{man} program to format the corresponding man page. If 1194the system permits, it runs @command{man} asynchronously, so that you 1195can keep on editing while the page is being formatted. The result 1196goes in a buffer named @file{*Man @var{topic}*}. These buffers use a 1197special major mode, Man mode, that facilitates scrolling and jumping 1198to other manual pages. For details, type @kbd{C-h m} while in a Man 1199mode buffer. 1200 1201@cindex sections of manual pages 1202 Each man page belongs to one of ten or more @dfn{sections}, each 1203named by a digit or by a digit and a letter. Sometimes there are man 1204pages with the same name in different sections. To read a man page 1205from a specific section, type @samp{@var{topic}(@var{section})} or 1206@samp{@var{section} @var{topic}} when @kbd{M-x man} prompts for the 1207topic. For example, the man page for the C library function 1208@code{chmod} is in section 2, but there is a shell command of the same 1209name, whose man page is in section 1; to view the former, type 1210@w{@kbd{M-x man @key{RET} chmod(2) @key{RET}}}. 1211 1212@vindex Man-switches 1213@kindex M-n @r{(Man mode)} 1214@kindex M-p @r{(Man mode)} 1215 If you do not specify a section, @kbd{M-x man} normally displays 1216only the first man page found. On some systems, the @code{man} 1217program accepts a @samp{-a} command-line option, which tells it to 1218display all the man pages for the specified topic. To make use of 1219this, change the value of the variable @code{Man-switches} to 1220@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and 1221@kbd{M-p} to switch between man pages in different sections. The mode 1222line shows how many manual pages are available. 1223 1224@findex woman 1225@cindex manual pages, on MS-DOS/MS-Windows 1226 An alternative way of reading manual pages is the @kbd{M-x woman} 1227command. Unlike @kbd{M-x man}, it does not run any external programs 1228to format and display the man pages; the formatting is done by Emacs, 1229so it works on systems such as MS-Windows where the @command{man} 1230program may be unavailable. It prompts for a man page, and displays 1231it in a buffer named @file{*WoMan @var{section} @var{topic}}. 1232 1233 @kbd{M-x woman} computes the completion list for manpages the first 1234time you invoke the command. With a numeric argument, it recomputes 1235this list; this is useful if you add or delete manual pages. 1236 1237 If you type a name of a manual page and @kbd{M-x woman} finds that 1238several manual pages by the same name exist in different sections, it 1239pops up a window with possible candidates asking you to choose one of 1240them. 1241 1242 Note that @kbd{M-x woman} doesn't yet support the latest features of 1243modern man pages, so we recommend using @kbd{M-x man} if that is 1244available on your system. 1245 1246 For more information about setting up and using @kbd{M-x woman}, see 1247@ifinfo 1248@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The 1249WoMan Manual}. 1250@end ifinfo 1251@ifnotinfo 1252the WoMan Info manual, which is distributed with Emacs. 1253@end ifnotinfo 1254 1255@node Lisp Doc 1256@subsection Emacs Lisp Documentation Lookup 1257 1258 When editing Emacs Lisp code, you can use the commands @kbd{C-h f} 1259(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) 1260to view the built-in documentation for the Lisp functions and 1261variables that you want to use. @xref{Name Help}. 1262 1263@cindex ElDoc mode 1264@findex eldoc-mode 1265@findex global-eldoc-mode 1266 ElDoc is a buffer-local minor mode that helps with looking up Lisp 1267documentation. When it is enabled, the echo area displays some useful 1268information whenever there is a Lisp function or variable at point; 1269for a function, it shows the argument list, and for a variable it 1270shows the first line of the variable's documentation string. To 1271toggle ElDoc mode, type @kbd{M-x eldoc-mode}. There's also a Global 1272ElDoc mode, which is turned on by default, and affects buffers, such 1273as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp 1274Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally). 1275 1276@node Hideshow 1277@section Hideshow minor mode 1278@cindex Hideshow mode 1279@cindex mode, Hideshow 1280 1281@findex hs-minor-mode 1282 Hideshow mode is a buffer-local minor mode that allows you to 1283selectively display portions of a program, which are referred to as 1284@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode 1285(@pxref{Minor Modes}). 1286 1287 When you use Hideshow mode to hide a block, the block disappears 1288from the screen, to be replaced by an ellipsis (three periods in a 1289row). Just what constitutes a block depends on the major mode. In C 1290mode and related modes, blocks are delimited by braces, while in Lisp 1291mode they are delimited by parentheses. Multi-line comments also 1292count as blocks. 1293 1294 Hideshow mode provides the following commands: 1295 1296@findex hs-hide-all 1297@findex hs-hide-block 1298@findex hs-show-all 1299@findex hs-show-block 1300@findex hs-show-region 1301@findex hs-hide-level 1302@findex hs-toggle-hiding 1303@findex hs-mouse-toggle-hiding 1304@kindex C-c @@ C-h 1305@kindex C-c @@ C-s 1306@kindex C-c @@ C-c 1307@kindex C-c @@ C-M-h 1308@kindex C-c @@ C-M-s 1309@kindex C-c @@ C-r 1310@kindex C-c @@ C-l 1311@kindex S-mouse-2 1312@table @kbd 1313@item C-c @@ C-h 1314@itemx C-c @@ C-d 1315Hide the current block (@code{hs-hide-block}). 1316@item C-c @@ C-s 1317Show the current block (@code{hs-show-block}). 1318@item C-c @@ C-c 1319@itemx C-c @@ C-e 1320Either hide or show the current block (@code{hs-toggle-hiding}). 1321@item S-mouse-2 1322Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}). 1323@item C-c @@ C-M-h 1324@itemx C-c @@ C-t 1325Hide all top-level blocks (@code{hs-hide-all}). 1326@item C-c @@ C-M-s 1327@itemx C-c @@ C-a 1328Show all blocks in the buffer (@code{hs-show-all}). 1329@item C-u @var{n} C-c @@ C-l 1330Hide all blocks @var{n} levels below this block 1331(@code{hs-hide-level}). 1332@end table 1333 1334@vindex hs-hide-comments-when-hiding-all 1335@vindex hs-isearch-open 1336@vindex hs-special-modes-alist 1337 These variables can be used to customize Hideshow mode: 1338 1339@table @code 1340@item hs-hide-comments-when-hiding-all 1341If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides 1342comments too. 1343 1344@item hs-isearch-open 1345This variable specifies the conditions under which incremental search 1346should unhide a hidden block when matching text occurs within the 1347block. Its value should be either @code{code} (unhide only code 1348blocks), @code{comment} (unhide only comments), @code{t} (unhide both 1349code blocks and comments), or @code{nil} (unhide neither code blocks 1350nor comments). The default value is @code{code}. 1351@end table 1352 1353@node Symbol Completion 1354@section Completion for Symbol Names 1355@cindex completion (symbol names) 1356 1357 Completion is normally done in the minibuffer (@pxref{Completion}), 1358but you can also complete symbol names in ordinary Emacs buffers. 1359 1360@kindex M-TAB 1361@kindex C-M-i 1362 In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}} 1363to complete the partial symbol before point. On graphical displays, 1364the @kbd{M-@key{TAB}} key is usually reserved by the window manager 1365for switching graphical windows, so you should type @kbd{C-M-i} or 1366@kbd{@key{ESC} @key{TAB}} instead. 1367 1368@cindex tags-based completion 1369@findex completion-at-point@r{, in programming language modes} 1370@cindex Lisp symbol completion 1371@cindex completion (Lisp symbols) 1372 In most programming language modes, @kbd{C-M-i} (or 1373@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point}, 1374which generates its completion list in a flexible way. If Semantic 1375mode is enabled, it tries to use the Semantic parser data for 1376completion (@pxref{Semantic}). If Semantic mode is not enabled or 1377fails at performing completion, it tries to complete using the 1378selected tags table (@pxref{Tags Tables}). If in Emacs Lisp mode, it 1379performs completion using the function, variable, or property names 1380defined in the current Emacs session. 1381 1382 In all other respects, in-buffer symbol completion behaves like 1383minibuffer completion. For instance, if Emacs cannot complete to a 1384unique symbol, it displays a list of completion alternatives in 1385another window. @xref{Completion}. 1386 1387 In Text mode and related modes, @kbd{M-@key{TAB}} completes words 1388based on the spell-checker's dictionary. @xref{Spelling}. 1389 1390@node MixedCase Words 1391@section MixedCase Words 1392@cindex camel case 1393 1394 Some programming styles make use of mixed-case (or ``CamelCase'') 1395symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend 1396using underscores to separate words within an identifier, rather than 1397using case distinctions.) Emacs has various features to make it easier 1398to deal with such symbols. 1399 1400@cindex Glasses mode 1401@cindex mode, Glasses 1402 Glasses mode is a buffer-local minor mode that makes it easier to read 1403such symbols, by altering how they are displayed. By default, it 1404displays extra underscores between each lower-case letter and the 1405following capital letter. This does not alter the buffer text, only how 1406it is displayed. 1407 1408 To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor 1409Modes}). When Glasses mode is enabled, the minor mode indicator 1410@samp{o^o} appears in the mode line. For more information about 1411Glasses mode, type @kbd{C-h P glasses @key{RET}}. 1412 1413@cindex Subword mode 1414@findex subword-mode 1415 Subword mode is another buffer-local minor mode. In subword mode, 1416Emacs's word commands recognize upper case letters in 1417@samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is 1418enabled, the minor mode indicator @samp{,} appears in the mode line. 1419See also the similar @code{superword-mode} (@pxref{Misc for Programs}). 1420 1421@node Semantic 1422@section Semantic 1423@cindex Semantic package 1424 1425Semantic is a package that provides language-aware editing commands 1426based on @code{source code parsers}. This section provides a brief 1427description of Semantic; for full details, 1428@ifnottex 1429see @ref{Top, Semantic,, semantic, Semantic}. 1430@end ifnottex 1431@iftex 1432see the Semantic Info manual, which is distributed with Emacs. 1433@end iftex 1434 1435 Most of the language-aware features in Emacs, such as Font Lock 1436mode (@pxref{Font Lock}), rely on rules of thumb@footnote{Regular 1437expressions and syntax tables.} that usually give good results but are 1438never completely exact. In contrast, the parsers used by Semantic 1439have an exact understanding of programming language syntax. This 1440allows Semantic to provide search, navigation, and completion commands 1441that are powerful and precise. 1442 1443@cindex Semantic mode 1444@cindex mode, Semantic 1445 To begin using Semantic, type @kbd{M-x semantic-mode} or click on 1446the menu item named @samp{Source Code Parsers (Semantic)} in the 1447@samp{Tools} menu. This enables Semantic mode, a global minor mode. 1448 1449 When Semantic mode is enabled, Emacs automatically attempts to 1450parse each file you visit. Currently, Semantic understands C, C++, 1451HTML, Java, Javascript, Make, Python, Scheme, SRecode, and Texinfo. 1452Within each parsed buffer, the following commands are available: 1453 1454@table @kbd 1455@item C-c , j 1456@kindex C-c , j 1457Prompt for the name of a function defined in the current file, and 1458move point there (@code{semantic-complete-jump-local}). 1459 1460@item C-c , J 1461@kindex C-c , J 1462Prompt for the name of a function defined in any file Emacs has 1463parsed, and move point there (@code{semantic-complete-jump}). 1464 1465@item C-c , @key{SPC} 1466@kindex C-c , SPC 1467Display a list of possible completions for the symbol at point 1468(@code{semantic-complete-analyze-inline}). This also activates a set 1469of special key bindings for choosing a completion: @kbd{@key{RET}} 1470accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through 1471possible completions, @kbd{@key{TAB}} completes as far as possible and 1472then cycles, and @kbd{C-g} or any other key aborts completion. 1473 1474@item C-c , l 1475@kindex C-c , l 1476Display a list of the possible completions of the symbol at point, in 1477another window (@code{semantic-analyze-possible-completions}). 1478@end table 1479 1480@noindent 1481In addition to the above commands, the Semantic package provides a 1482variety of other ways to make use of parser information. For 1483instance, you can use it to display a list of completions when Emacs 1484is idle. 1485@ifnottex 1486@xref{Top, Semantic,, semantic, Semantic}, for details. 1487@end ifnottex 1488 1489@node Misc for Programs 1490@section Other Features Useful for Editing Programs 1491 1492 Some Emacs commands that aren't designed specifically for editing 1493programs are useful for that nonetheless. 1494 1495 The Emacs commands that operate on words, sentences and paragraphs 1496are useful for editing code. Most symbol names contain words 1497(@pxref{Words}), while sentences can be found in strings and comments 1498(@pxref{Sentences}). As for paragraphs, they are defined in most 1499programming language modes to begin and end at blank lines 1500(@pxref{Paragraphs}). Therefore, judicious use of blank lines to make 1501the program clearer will also provide useful chunks of text for the 1502paragraph commands to work on. Auto Fill mode, if enabled in a 1503programming language major mode, indents the new lines which it 1504creates. 1505 1506@findex superword-mode 1507 Superword mode is a buffer-local minor mode that causes editing and 1508motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words. 1509When Superword mode is enabled, the minor mode indicator 1510@iftex 1511@samp{@math{^2}} 1512@end iftex 1513@ifnottex 1514@samp{²} 1515@end ifnottex 1516appears in the mode line. See also the similar @code{subword-mode} 1517(@pxref{MixedCase Words}). 1518 1519@findex electric-layout-mode 1520 Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global 1521minor mode that automatically inserts newlines when you type certain 1522characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript 1523mode. 1524 1525 Apart from Hideshow mode (@pxref{Hideshow}), another way to 1526selectively display parts of a program is to use the selective display 1527feature (@pxref{Selective Display}). Programming modes often also 1528support Outline minor mode (@pxref{Outline Mode}), which can be used 1529with the Foldout package (@pxref{Foldout}). 1530 1531@ifinfo 1532 The automatic typing features may be useful for writing programs. 1533@xref{Top,,Autotyping, autotype, Autotyping}. 1534@end ifinfo 1535 1536@findex prettify-symbols-mode 1537 Prettify Symbols mode is a buffer-local minor mode that replaces 1538certain strings with more attractive versions for display purposes. 1539For example, in Emacs Lisp mode, it replaces the string @samp{lambda} 1540with the Greek lambda character @samp{λ}. In a @TeX{} buffer, it will 1541replace @samp{\alpha} @dots{} @samp{\omega} and other math macros with 1542their Unicode characters. You may wish to use this in non-programming 1543modes as well. You can customize the mode by adding more entries to 1544@code{prettify-symbols-alist}. More elaborate customization is 1545available via customizing @code{prettify-symbols-compose-predicate} if 1546its default value @code{prettify-symbols-default-compose-p} is not 1547appropriate. There is also a global version, 1548@code{global-prettify-symbols-mode}, which enables the mode in all 1549buffers that support it. 1550 1551 The symbol at point can be shown in its original form. This is 1552controlled by the variable @code{prettify-symbols-unprettify-at-point}: 1553if non-@code{nil}, the original form of symbol at point will be 1554restored for as long as point is at it. 1555 1556 1557@node C Modes 1558@section C and Related Modes 1559@cindex C mode 1560@cindex Java mode 1561@cindex Pike mode 1562@cindex IDL mode 1563@cindex CORBA IDL mode 1564@cindex Objective C mode 1565@cindex C++ mode 1566@cindex AWK mode 1567@cindex mode, Java 1568@cindex mode, C 1569@cindex mode, C++ 1570@cindex mode, Objective C 1571@cindex mode, CORBA IDL 1572@cindex mode, Pike 1573@cindex mode, AWK 1574 1575 This section gives a brief description of the special features 1576available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. 1577(These are called ``C mode and related modes''.) 1578@ifinfo 1579@xref{Top,, CC Mode, ccmode, CC Mode}, for more details. 1580@end ifinfo 1581@ifnotinfo 1582For more details, see the CC mode Info manual, which is distributed 1583with Emacs. 1584@end ifnotinfo 1585 1586@menu 1587* Motion in C:: Commands to move by C statements, etc. 1588* Electric C:: Colon and other chars can automatically reindent. 1589* Hungry Delete:: A more powerful DEL command. 1590* Other C Commands:: Filling comments, viewing expansion of macros, 1591 and other neat features. 1592@end menu 1593 1594@node Motion in C 1595@subsection C Mode Motion Commands 1596 1597 This section describes commands for moving point, in C mode and 1598related modes. 1599 1600@table @code 1601@item C-M-a 1602@itemx C-M-e 1603@findex c-beginning-of-defun 1604@findex c-end-of-defun 1605Move point to the beginning or end of the current function or 1606top-level definition. In languages with enclosing scopes (such as 1607C++'s classes) the @dfn{current function} is the immediate one, 1608possibly inside a scope. Otherwise it is the one defined by the least 1609enclosing braces. (By contrast, @code{beginning-of-defun} and 1610@code{end-of-defun} search for braces in column zero.) @xref{Moving 1611by Defuns}. 1612 1613@item C-c C-u 1614@kindex C-c C-u @r{(C mode)} 1615@findex c-up-conditional 1616Move point back to the containing preprocessor conditional, leaving the 1617mark behind. A prefix argument acts as a repeat count. With a negative 1618argument, move point forward to the end of the containing 1619preprocessor conditional. 1620 1621@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so 1622the function will stop at a @samp{#elif} when going backward, but not 1623when going forward. 1624 1625@item C-c C-p 1626@kindex C-c C-p @r{(C mode)} 1627@findex c-backward-conditional 1628Move point back over a preprocessor conditional, leaving the mark 1629behind. A prefix argument acts as a repeat count. With a negative 1630argument, move forward. 1631 1632@item C-c C-n 1633@kindex C-c C-n @r{(C mode)} 1634@findex c-forward-conditional 1635Move point forward across a preprocessor conditional, leaving the mark 1636behind. A prefix argument acts as a repeat count. With a negative 1637argument, move backward. 1638 1639@item M-a 1640@kindex M-a @r{(C mode)} 1641@findex c-beginning-of-statement 1642Move point to the beginning of the innermost C statement 1643(@code{c-beginning-of-statement}). If point is already at the beginning 1644of a statement, move to the beginning of the preceding statement. With 1645prefix argument @var{n}, move back @var{n} @minus{} 1 statements. 1646 1647In comments or in strings which span more than one line, this command 1648moves by sentences instead of statements. 1649 1650@item M-e 1651@kindex M-e @r{(C mode)} 1652@findex c-end-of-statement 1653Move point to the end of the innermost C statement or sentence; like 1654@kbd{M-a} except that it moves in the other direction 1655(@code{c-end-of-statement}). 1656@end table 1657 1658@node Electric C 1659@subsection Electric C Characters 1660 1661 In C mode and related modes, certain printing characters are 1662@dfn{electric}---in addition to inserting themselves, they also 1663reindent the current line, and optionally also insert newlines. The 1664electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, 1665@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and 1666@kbd{)}. 1667 1668 You might find electric indentation inconvenient if you are editing 1669chaotically indented code. If you are new to CC Mode, you might find 1670it disconcerting. You can toggle electric action with the command 1671@kbd{C-c C-l}; when it is enabled, @samp{/@var{c}l} appears in the 1672mode line after the mode name (where @var{c}, if present, is @samp{*} 1673or @samp{/}, depending on whether the comment style is block or line). 1674@xref{Minor Modes,,, ccmode, The CC Mode Manual}, for more about 1675mode-line indicators in CC Mode. 1676 1677@table @kbd 1678@item C-c C-l 1679@kindex C-c C-l @r{(C mode)} 1680@findex c-toggle-electric-state 1681Toggle electric action (@code{c-toggle-electric-state}). With a 1682positive prefix argument, this command enables electric action, with a 1683negative one it disables it. 1684@end table 1685 1686 Electric characters insert newlines only when, in addition to the 1687electric state, the @dfn{auto-newline} feature is enabled (indicated 1688by @samp{/@var{c}la} in the mode line after the mode name). You can 1689turn this feature on or off with the command @kbd{C-c C-a}: 1690 1691@table @kbd 1692@item C-c C-a 1693@kindex C-c C-a @r{(C mode)} 1694@findex c-toggle-auto-newline 1695Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a 1696prefix argument, this command turns the auto-newline feature on if the 1697argument is positive, and off if it is negative. 1698@end table 1699 1700 Usually the CC Mode style configures the exact circumstances in 1701which Emacs inserts auto-newlines. You can also configure this 1702directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. 1703 1704@node Hungry Delete 1705@subsection Hungry Delete Feature in C 1706@cindex hungry deletion (C Mode) 1707 1708 If you want to delete an entire block of whitespace at point, you 1709can use @dfn{hungry deletion}. This deletes all the contiguous 1710whitespace either before point or after point in a single operation. 1711@dfn{Whitespace} here includes tabs and newlines, but not comments or 1712preprocessor commands. 1713 1714@table @kbd 1715@item C-c C-@key{DEL} 1716@itemx C-c @key{DEL} 1717@findex c-hungry-delete-backwards 1718@kindex C-c C-DEL @r{(C Mode)} 1719@kindex C-c DEL @r{(C Mode)} 1720Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}). 1721 1722@item C-c C-d 1723@itemx C-c C-@key{Delete} 1724@itemx C-c @key{Delete} 1725@findex c-hungry-delete-forward 1726@kindex C-c C-d @r{(C Mode)} 1727@kindex C-c C-Delete @r{(C Mode)} 1728@kindex C-c Delete @r{(C Mode)} 1729Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}). 1730@end table 1731 1732 As an alternative to the above commands, you can enable @dfn{hungry 1733delete mode}. When this feature is enabled (indicated by @samp{h} 1734after a @samp{/} in the mode line after the mode name), a single 1735@kbd{@key{DEL}} deletes all preceding whitespace, not just one space, 1736and a single @kbd{C-d} (but @emph{not} plain @kbd{@key{Delete}}) 1737deletes all following whitespace. 1738 1739@table @kbd 1740@item M-x c-toggle-hungry-state 1741@findex c-toggle-hungry-state 1742Toggle the hungry-delete feature 1743(@code{c-toggle-hungry-state}). With a prefix argument, 1744this command turns the hungry-delete feature on if the argument is 1745positive, and off if it is negative. 1746@end table 1747 1748@vindex c-hungry-delete-key 1749 The variable @code{c-hungry-delete-key} controls whether the 1750hungry-delete feature is enabled. 1751 1752@node Other C Commands 1753@subsection Other Commands for C Mode 1754 1755@table @kbd 1756@item M-x c-context-line-break 1757@findex c-context-line-break 1758This command inserts a line break and indents the new line in a manner 1759appropriate to the context. In normal code, it does the work of 1760@kbd{@key{RET}} (@code{newline}), in a C preprocessor line it additionally 1761inserts a @samp{\} at the line break, and within comments it's like 1762@kbd{M-j} (@code{c-indent-new-comment-line}). 1763 1764@code{c-context-line-break} isn't bound to a key by default, but it 1765needs a binding to be useful. The following code will bind it to 1766@kbd{@key{RET}}. We use @code{c-initialization-hook} here to make 1767sure the keymap is loaded before we try to change it. 1768 1769@example 1770(defun my-bind-clb () 1771 (define-key c-mode-base-map "\C-m" 1772 'c-context-line-break)) 1773(add-hook 'c-initialization-hook 'my-bind-clb) 1774@end example 1775 1776@item C-M-h 1777Put mark at the end of a function definition, and put point at the 1778beginning (@code{c-mark-function}). 1779 1780@item M-q 1781@kindex M-q @r{(C mode)} 1782@findex c-fill-paragraph 1783Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). 1784If any part of the current line is a comment or within a comment, this 1785command fills the comment or the paragraph of it that point is in, 1786preserving the comment indentation and comment delimiters. 1787 1788@item C-c C-e 1789@cindex macro expansion in C 1790@cindex expansion of C macros 1791@findex c-macro-expand 1792@kindex C-c C-e @r{(C mode)} 1793Run the C preprocessor on the text in the region, and show the result, 1794which includes the expansion of all the macro calls 1795(@code{c-macro-expand}). The buffer text before the region is also 1796included in preprocessing, for the sake of macros defined there, but the 1797output from this part isn't shown. 1798 1799When you are debugging C code that uses macros, sometimes it is hard to 1800figure out precisely how the macros expand. With this command, you 1801don't have to figure it out; you can see the expansions. 1802 1803@item C-c C-\ 1804@findex c-backslash-region 1805@kindex C-c C-\ @r{(C mode)} 1806Insert or align @samp{\} characters at the ends of the lines of the 1807region (@code{c-backslash-region}). This is useful after writing or 1808editing a C macro definition. 1809 1810If a line already ends in @samp{\}, this command adjusts the amount of 1811whitespace before it. Otherwise, it inserts a new @samp{\}. However, 1812the last line in the region is treated specially; no @samp{\} is 1813inserted on that line, and any @samp{\} there is deleted. 1814 1815@item M-x cpp-highlight-buffer 1816@cindex preprocessor highlighting 1817@findex cpp-highlight-buffer 1818Highlight parts of the text according to its preprocessor conditionals. 1819This command displays another buffer named @file{*CPP Edit*}, which 1820serves as a graphic menu for selecting how to display particular kinds 1821of conditionals and their contents. After changing various settings, 1822click on @samp{[A]pply these settings} (or go to that buffer and type 1823@kbd{a}) to rehighlight the C mode buffer accordingly. 1824 1825@item C-c C-s 1826@findex c-show-syntactic-information 1827@kindex C-c C-s @r{(C mode)} 1828Display the syntactic information about the current source line 1829(@code{c-show-syntactic-information}). This information directs how 1830the line is indented. 1831 1832@item M-x cwarn-mode 1833@itemx M-x global-cwarn-mode 1834@findex cwarn-mode 1835@findex global-cwarn-mode 1836@vindex global-cwarn-mode 1837@cindex CWarn mode 1838@cindex suspicious constructions in C, C++ 1839CWarn minor mode highlights certain suspicious C and C++ constructions: 1840 1841@itemize @bullet{} 1842@item 1843Assignments inside expressions. 1844@item 1845Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} 1846(except after a @samp{do @dots{} while} statement); 1847@item 1848C++ functions with reference parameters. 1849@end itemize 1850 1851@noindent 1852You can enable the mode for one buffer with the command @kbd{M-x 1853cwarn-mode}, or for all suitable buffers with the command @kbd{M-x 1854global-cwarn-mode} or by customizing the variable 1855@code{global-cwarn-mode}. You must also enable Font Lock mode to make 1856it work. 1857 1858@item M-x hide-ifdef-mode 1859@findex hide-ifdef-mode 1860@cindex Hide-ifdef mode 1861@vindex hide-ifdef-shadow 1862Hide-ifdef minor mode hides selected code within @samp{#if} and 1863@samp{#ifdef} preprocessor blocks. If you change the variable 1864@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode 1865shadows preprocessor blocks by displaying them with a less 1866prominent face, instead of hiding them entirely. See the 1867documentation string of @code{hide-ifdef-mode} for more information. 1868 1869@item M-x ff-find-related-file 1870@cindex related files 1871@findex ff-find-related-file 1872@vindex ff-related-file-alist 1873Find a file related in a special way to the file visited by the 1874current buffer. Typically this will be the header file corresponding 1875to a C/C++ source file, or vice versa. The variable 1876@code{ff-related-file-alist} specifies how to compute related file 1877names. 1878@end table 1879 1880@node Asm Mode 1881@section Asm Mode 1882 1883@cindex Asm mode 1884@cindex assembler mode 1885Asm mode is a major mode for editing files of assembler code. It 1886defines these commands: 1887 1888@table @kbd 1889@item @key{TAB} 1890@code{tab-to-tab-stop}. 1891@c FIXME: Maybe this should be consistent with other programming modes. 1892 1893@item C-j 1894Insert a newline and then indent using @code{tab-to-tab-stop}. 1895 1896@item : 1897Insert a colon and then remove the indentation from before the label 1898preceding colon. Then do @code{tab-to-tab-stop}. 1899 1900@item ; 1901Insert or align a comment. 1902@end table 1903 1904 The variable @code{asm-comment-char} specifies which character 1905starts comments in assembler syntax. 1906 1907@ifnottex 1908@include fortran-xtra.texi 1909@end ifnottex 1910