annotate man/programs.texi @ 48342:09be0bd22123

*** empty log message ***
author Markus Rost <rost@math.uni-bielefeld.de>
date Fri, 15 Nov 2002 05:25:19 +0000
parents e8faddf96f0f
children df6767370b43
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
2 @c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @node Programs, Building, Text, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @chapter Editing Programs
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @cindex Lisp editing
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @cindex C editing
Dave Love <fx@gnu.org>
parents:
diff changeset
8 @cindex program editing
Dave Love <fx@gnu.org>
parents:
diff changeset
9
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
10 Emacs provides many features to facilitate editing programs. Some
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
11 of these features can
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
12
Dave Love <fx@gnu.org>
parents:
diff changeset
13 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
14 @item
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
15 Find or move over top-level definitions (@pxref{Defuns}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
16 @item
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
17 Apply the usual indentation conventions of the language
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
18 (@pxref{Program Indent}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
19 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
20 Insert, kill or align comments (@pxref{Comments}).
Dave Love <fx@gnu.org>
parents:
diff changeset
21 @item
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
22 Balance parentheses (@pxref{Parentheses}).
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
23 @item
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
24 Highlight program syntax (@pxref{Font Lock}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
25 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
26
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
27 This chapter describes these features and many more.
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
28
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
29 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
30 * Program Modes:: Major modes for editing programs.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
31 * Defuns:: Commands to operate on major top-level parts
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
32 of a program.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
33 * Program Indent:: Adjusting indentation to show the nesting.
Dave Love <fx@gnu.org>
parents:
diff changeset
34 * Comments:: Inserting, killing, and aligning comments.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
35 * Parentheses:: Commands that operate on parentheses.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
36 * Documentation:: Getting documentation of functions you plan to call.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
37 * Hideshow:: Displaying blocks selectively.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
38 * Symbol Completion:: Completion on symbol names of your program or language.
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
39 * Glasses:: Making identifiersLikeThis more readable.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
40 * Misc for Programs:: Other Emacs features useful for editing programs.
26264
Francesco Potortì <pot@gnu.org>
parents: 26106
diff changeset
41 * C Modes:: Special commands of C, C++, Objective-C,
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
42 Java, and Pike modes.
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
43 * Fortran:: Fortran mode and its special features.
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
44 * Asm Mode:: Asm mode and its special features.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
45 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
46
Dave Love <fx@gnu.org>
parents:
diff changeset
47 @node Program Modes
Dave Love <fx@gnu.org>
parents:
diff changeset
48 @section Major Modes for Programming Languages
Dave Love <fx@gnu.org>
parents:
diff changeset
49 @cindex modes for programming languages
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
50
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
51 Emacs has specialized major modes for various programming languages.
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
52 @xref{Major Modes}. A programming language major mode typically
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
53 specifies the syntax of expressions, the customary rules for
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
54 indentation, how to do syntax highlighting for the language, and how
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
55 to find the beginning of a function definition. It often customizes
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
56 or provides facilities for compiling and debugging programs as well.
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
57
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
58 Ideally, Emacs should provide a major mode for each programming
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
59 language that you might want to edit; if it doesn't have a mode for
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
60 your favorite language, you can contribute one. But often the mode
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
61 for one language can serve for other syntactically similar languages.
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
62 The major mode for language @var{l} is called @code{@var{l}-mode},
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
63 and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
64 @xref{Choosing Modes}.
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
65
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
66 @cindex Perl mode
Dave Love <fx@gnu.org>
parents:
diff changeset
67 @cindex Icon mode
Dave Love <fx@gnu.org>
parents:
diff changeset
68 @cindex Awk mode
Dave Love <fx@gnu.org>
parents:
diff changeset
69 @cindex Makefile mode
Dave Love <fx@gnu.org>
parents:
diff changeset
70 @cindex Tcl mode
Dave Love <fx@gnu.org>
parents:
diff changeset
71 @cindex CPerl mode
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
72 @cindex DSSSL mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
73 @cindex Octave mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
74 @cindex Metafont mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
75 @cindex Modula2 mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
76 @cindex Prolog mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
77 @cindex Simula mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
78 @cindex VHDL mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
79 @cindex M4 mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
80 @cindex Shell-script mode
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
81 @cindex Delphi mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
82 @cindex PostScript mode
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
83 The existing programming language major modes include Lisp, Scheme (a
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
84 variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
85 Awk, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
86 format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
87 companion for font creation), Modula2, Objective-C, Octave, Pascal,
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
88 Perl, Pike, PostScript, Prolog, Simula, Tcl, and VHDL. There is
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
89 also a major mode for makefiles, called Makefile mode. An alternative
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
90 mode for Perl is called CPerl mode. Modes are available for the
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
91 scripting languages of the common GNU and Unix shells, VMS DCL, and
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
92 MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
93 editing various sorts of configuration files.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
94
Dave Love <fx@gnu.org>
parents:
diff changeset
95 @kindex DEL @r{(programming modes)}
37978
c41356c953a0 Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents: 37868
diff changeset
96 @findex c-electric-backspace
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
97 In most programming languages, indentation should vary from line to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
98 line to illustrate the structure of the program. So the major modes
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
99 for programming languages arrange for @key{TAB} to update the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
100 indentation of the current line. They also rebind @key{DEL} to treat
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
101 a tab as if it were the equivalent number of spaces; this lets you
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
102 delete one column of indentation without worrying whether the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
103 whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
104 tab character before point, in these modes.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
105
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
106 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
107 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
108 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
109 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}).
38122
4aeb215906f3 Proofreading fixes from Peter Milliken <Peter.Milliken@GTECH.COM>.
Eli Zaretskii <eliz@gnu.org>
parents: 38090
diff changeset
110
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
111 @cindex mode hook
Dave Love <fx@gnu.org>
parents:
diff changeset
112 @vindex c-mode-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
113 @vindex lisp-mode-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
114 @vindex emacs-lisp-mode-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
115 @vindex lisp-interaction-mode-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
116 @vindex scheme-mode-hook
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
117 Turning on a major mode runs a normal hook called the @dfn{mode
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
118 hook}, which is the value of a Lisp variable. Each major mode has a
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
119 mode hook, and the hook's name is always made from the mode command's
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
120 name by adding @samp{-hook}. For example, turning on C mode runs the
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
121 hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
122 @code{lisp-mode-hook}. The purpose of the mode hook is to give you a
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
123 place to set up customizations for that major mode. @xref{Hooks}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
124
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
125 @node Defuns
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
126 @section Top-Level Definitions, or Defuns
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
127
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
128 In Emacs, a major definition at the top level in the buffer is
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
129 called a @dfn{defun}. The name comes from Lisp, but in Emacs we use
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
130 it for all languages.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
131
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
132 In most programming language modes, Emacs assumes that a defun is
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
133 any pair of parentheses (or braces, if the language uses braces this
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
134 way) that starts at the left margin. For example, in C, the body of a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
135 function definition is normally a defun, because the open-brace that
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
136 begins it is normally at the left margin. A variable's initializer
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
137 can also count as a defun, if the open-brace that begins the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
138 initializer is at the left margin.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
139
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
140 However, some language modes provide their own code for recognizing
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
141 defuns in a way that suits the language syntax and conventions better.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
142
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
143 @menu
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
144 * Left Margin Paren:: An open-paren or similar opening delimiter
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
145 starts a defun if it is at the left margin.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
146 * Moving by Defuns:: Commands to move over or mark a major definition.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
147 * Imenu:: Making buffer indexes as menus.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
148 * Which Function:: Which Function mode shows which function you are in.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
149 @end menu
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
150
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
151 @node Left Margin Paren
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
152 @subsection Left Margin Convention
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
153
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
154 @cindex open-parenthesis in leftmost column
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
155 @cindex ( in leftmost column
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
156 In most major modes, Emacs assumes that any opening delimiter found
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
157 at the left margin is the start of a top-level definition, or defun.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
158 Therefore, @strong{never put an opening delimiter at the left margin
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
159 unless it should have that significance.} For instance, never put an
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
160 open-parenthesis at the left margin in a Lisp file unless it is the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
161 start of a top-level list. Never put an open-brace or other opening
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
162 delimiter at the beginning of a line of C code unless it is at top
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
163 level.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
164
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
165 If you don't follow this convention, not only will you have trouble
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
166 when you explicitly use the commands for motion by defuns; other
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
167 features that use them will also give you trouble. This includes
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
168 the indentation commands (@pxref{Program Indent}) and Font Lock
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
169 mode (@pxref{Font Lock}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
170
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
171 The most likely problem case is when you want an opening delimiter
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
172 at the start of a line inside a string. To avoid trouble, put an
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
173 escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
174 other Lisp dialects) before the opening delimiter. This will not
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
175 affect the contents of the string, but will prevent that opening
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
176 delimiter from starting a defun. Here's an example:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
177
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
178 @example
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
179 (insert "Foo:
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
180 \(bar)
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
181 ")
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
182 @end example
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
183
46035
11e7a6a33a8c Explain font lock highlighting of opening delims that should be quoted.
Richard M. Stallman <rms@gnu.org>
parents: 45997
diff changeset
184 To help you catch violations of this convention, Font Lock mode
11e7a6a33a8c Explain font lock highlighting of opening delims that should be quoted.
Richard M. Stallman <rms@gnu.org>
parents: 45997
diff changeset
185 highlights confusing opening delimiters (those that ought to be
11e7a6a33a8c Explain font lock highlighting of opening delims that should be quoted.
Richard M. Stallman <rms@gnu.org>
parents: 45997
diff changeset
186 quoted) in bold red.
11e7a6a33a8c Explain font lock highlighting of opening delims that should be quoted.
Richard M. Stallman <rms@gnu.org>
parents: 45997
diff changeset
187
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
188 In the earliest days, the original Emacs found defuns by moving
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
189 upward a level of parentheses or braces until there were no more
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
190 levels to go up. This always required scanning all the way back to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
191 the beginning of the buffer, even for a small function. To speed up
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
192 the operation, we changed Emacs to assume that any opening delimiter
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
193 at the left margin is the start of a defun. This heuristic is nearly
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
194 always right, and avoids the need to scan back to the beginning of the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
195 buffer. However, it mandates following the convention described
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
196 above.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
197
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
198 @node Moving by Defuns
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
199 @subsection Moving by Defuns
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
200 @cindex defuns
Dave Love <fx@gnu.org>
parents:
diff changeset
201
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
202 These commands move point or set up the region based on top-level
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
203 major definitions, also called @dfn{defuns}.
38123
af8117970ca7 More proofreading fixes from Peter Milliken.
Eli Zaretskii <eliz@gnu.org>
parents: 38122
diff changeset
204
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
205 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
206 @item C-M-a
Dave Love <fx@gnu.org>
parents:
diff changeset
207 Move to beginning of current or preceding defun
Dave Love <fx@gnu.org>
parents:
diff changeset
208 (@code{beginning-of-defun}).
Dave Love <fx@gnu.org>
parents:
diff changeset
209 @item C-M-e
Dave Love <fx@gnu.org>
parents:
diff changeset
210 Move to end of current or following defun (@code{end-of-defun}).
Dave Love <fx@gnu.org>
parents:
diff changeset
211 @item C-M-h
Dave Love <fx@gnu.org>
parents:
diff changeset
212 Put region around whole current or following defun (@code{mark-defun}).
Dave Love <fx@gnu.org>
parents:
diff changeset
213 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
214
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
215 @cindex move to beginning or end of function
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
216 @cindex function, move to beginning or end
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
217 @kindex C-M-a
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
218 @kindex C-M-e
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
219 @kindex C-M-h
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
220 @findex beginning-of-defun
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
221 @findex end-of-defun
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
222 @findex mark-defun
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
223 The commands to move to the beginning and end of the current defun
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
224 are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
225 (@code{end-of-defun}). If you repeat one of these commands, or use a
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
226 positive numeric argument, each repetition moves to the next defun in
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
227 the direction of motion.
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
228
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
229 @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
230 @var{n} times to the next beginning of a defun. This is not exactly
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
231 the same place that @kbd{C-M-e} with argument @var{n} would move to;
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
232 the end of this defun is not usually exactly the same place as the
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
233 beginning of the following defun. (Whitespace, comments, and perhaps
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
234 declarations can separate them.) Likewise, @kbd{C-M-e} with a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
235 negative argument moves back to an end of a defun, which is not quite
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
236 the same as @kbd{C-M-a} with a positive argument.
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
237
36263
11db0318031d Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents: 36198
diff changeset
238 @kindex C-M-h @r{(C mode)}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
239 @findex c-mark-function
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
240 To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
241 which puts point at the beginning and mark at the end of the current
38238
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
242 defun. This is the easiest way to get ready to kill the defun in
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
243 order to move it to a different place in the file. If you use the
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
244 command while point is between defuns, it uses the following defun.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
245
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
246 In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
247 which is almost the same as @code{mark-defun}; the difference is that
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
248 it backs up over the argument declarations, function name and returned
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
249 data type so that the entire C function is inside the region. This is
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
250 an example of how major modes adjust the standard key bindings so that
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
251 they do their standard jobs in a way better fitting a particular
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
252 language. Other major modes may replace any or all of these key
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
253 bindings for that purpose.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
254
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
255 @node Imenu
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
256 @subsection Imenu
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
257 @cindex index of buffer definitions
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
258 @cindex buffer definitions index
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
259 @cindex tags
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
260
42675
640c0fcaebf1 Fix typos.
Pavel Janík <Pavel@Janik.cz>
parents: 41495
diff changeset
261 The Imenu facility offers a way to find the major definitions in
38238
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
262 a file by name. It is also useful in text formatter major modes,
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
263 where it treats each chapter, section, etc., as a definition.
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
264 (@xref{Tags}, for a more powerful feature that handles multiple files
38238
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
265 together.)
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
266
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
267 @findex imenu
38238
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
268 If you type @kbd{M-x imenu}, it reads the name of a definition using
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
269 the minibuffer, then moves point to that definition. You can use
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
270 completion to specify the name; the command always displays the whole
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
271 list of valid names.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
272
38238
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
273 @findex imenu-add-menubar-index
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
274 Alternatively, you can bind the command @code{imenu} to a mouse
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
275 click. Then it displays mouse menus for you to select a definition
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
276 name. You can also add the buffer's index to the menu bar by calling
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
277 @code{imenu-add-menubar-index}. If you want to have this menu bar
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
278 item available for all buffers in a certain major mode, you can do
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
279 this by adding @code{imenu-add-menubar-index} to its mode hook. But
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
280 if you have done that, you will have to wait each time you visit a
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
281 file in that mode, while Emacs finds all the definitions in that
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
282 buffer.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
283
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
284 @vindex imenu-auto-rescan
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
285 When you change the contents of a buffer, if you add or delete
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
286 definitions, you can update the buffer's index based on the
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
287 new contents by invoking the @samp{*Rescan*} item in the menu.
39063
6ecd6d3c0630 (Imenu): Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents: 38946
diff changeset
288 Rescanning happens automatically if you set @code{imenu-auto-rescan} to
6ecd6d3c0630 (Imenu): Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents: 38946
diff changeset
289 a non-@code{nil} value. There is no need to rescan because of small
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
290 changes in the text.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
291
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
292 @vindex imenu-sort-function
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
293 You can customize the way the menus are sorted by setting the
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
294 variable @code{imenu-sort-function}. By default, names are ordered as
38238
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
295 they occur in the buffer; if you want alphabetic sorting, use the
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
296 symbol @code{imenu--sort-by-name} as the value. You can also
6d50c21307ed Minor clarifications. Explain how to use imenu-sort-function.
Richard M. Stallman <rms@gnu.org>
parents: 38231
diff changeset
297 define your own comparison function by writing Lisp code.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
298
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
299 Imenu provides the information to guide Which Function mode
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
300 @ifnottex
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
301 (@pxref{Which Function}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
302 @end ifnottex
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
303 @iftex
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
304 (see below).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
305 @end iftex
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
306 The Speedbar can also use it (@pxref{Speedbar}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
307
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
308 @node Which Function
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
309 @subsection Which Function Mode
40175
ba769a5fb855 (Which Function): Add a cindex entry.
Eli Zaretskii <eliz@gnu.org>
parents: 39063
diff changeset
310 @cindex current function name in mode line
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
311
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
312 Which Function mode is a minor mode that displays the current
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
313 function name in the mode line, updating it as you move around in a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
314 buffer.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
315
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
316 @findex which-function-mode
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
317 @vindex which-func-modes
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
318 To enable (or disable) Which Function mode, use the command @kbd{M-x
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
319 which-function-mode}. This command is global; it applies to all
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
320 buffers, both existing ones and those yet to be created. However,
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
321 it only takes effect in certain major modes, those listed in the value of
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
322 @code{which-func-modes}. If the value is @code{t}, then Which
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
323 Function mode applies to all major modes that know how to support
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
324 it---in other words, all the major modes that support Imenu.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
325
Dave Love <fx@gnu.org>
parents:
diff changeset
326 @node Program Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
327 @section Indentation for Programs
Dave Love <fx@gnu.org>
parents:
diff changeset
328 @cindex indentation for programs
Dave Love <fx@gnu.org>
parents:
diff changeset
329
Dave Love <fx@gnu.org>
parents:
diff changeset
330 The best way to keep a program properly indented is to use Emacs to
Dave Love <fx@gnu.org>
parents:
diff changeset
331 reindent it as you change it. Emacs has commands to indent properly
Dave Love <fx@gnu.org>
parents:
diff changeset
332 either a single line, a specified number of lines, or all of the lines
Dave Love <fx@gnu.org>
parents:
diff changeset
333 inside a single parenthetical grouping.
Dave Love <fx@gnu.org>
parents:
diff changeset
334
Dave Love <fx@gnu.org>
parents:
diff changeset
335 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
336 * Basic Indent:: Indenting a single line.
Dave Love <fx@gnu.org>
parents:
diff changeset
337 * Multi-line Indent:: Commands to reindent many lines at once.
Dave Love <fx@gnu.org>
parents:
diff changeset
338 * Lisp Indent:: Specifying how each Lisp function should be indented.
Dave Love <fx@gnu.org>
parents:
diff changeset
339 * C Indent:: Extra features for indenting C and related modes.
Dave Love <fx@gnu.org>
parents:
diff changeset
340 * Custom C Indent:: Controlling indentation style for C and related modes.
Dave Love <fx@gnu.org>
parents:
diff changeset
341 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
342
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
343 @cindex pretty-printer
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
344 Emacs also provides a Lisp pretty-printer in the library @code{pp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
345 This program reformats a Lisp object with indentation chosen to look nice.
Dave Love <fx@gnu.org>
parents:
diff changeset
346
Dave Love <fx@gnu.org>
parents:
diff changeset
347 @node Basic Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
348 @subsection Basic Program Indentation Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
349
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
350 The basic indentation commands indent a single line according to the
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
351 usual conventions of the language you are editing.
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
352
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
353 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
354 @item @key{TAB}
Dave Love <fx@gnu.org>
parents:
diff changeset
355 Adjust indentation of current line.
Dave Love <fx@gnu.org>
parents:
diff changeset
356 @item C-j
Dave Love <fx@gnu.org>
parents:
diff changeset
357 Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
358 @item @key{LINEFEED}
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
359 This key, if the keyboard has it, is another way to enter @kbd{C-j}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
360 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
361
Dave Love <fx@gnu.org>
parents:
diff changeset
362 @kindex TAB @r{(programming modes)}
37978
c41356c953a0 Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents: 37868
diff changeset
363 @findex c-indent-command
c41356c953a0 Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents: 37868
diff changeset
364 @findex indent-line-function
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
365 @findex indent-for-tab-command
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
366 The basic indentation command is @key{TAB}, which gives the current line
Dave Love <fx@gnu.org>
parents:
diff changeset
367 the correct indentation as determined from the previous lines. The
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
368 function that @key{TAB} runs depends on the major mode; it is
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
369 @code{indent-for-tab-command}
37978
c41356c953a0 Correct names of some C mode indentation commands.
Richard M. Stallman <rms@gnu.org>
parents: 37868
diff changeset
370 in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
371 understand the syntax and conventions of different languages, but they all do
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
372 conceptually the same job: @key{TAB} in any programming-language major mode
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
373 inserts or deletes whitespace at the beginning of the current line,
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
374 independent of where point is in the line. If point was inside the
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
375 whitespace at the beginning of the line, @key{TAB} puts it at the end of
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
376 that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
377 the characters around it.
Dave Love <fx@gnu.org>
parents:
diff changeset
378
Dave Love <fx@gnu.org>
parents:
diff changeset
379 Use @kbd{C-q @key{TAB}} to insert a tab at point.
Dave Love <fx@gnu.org>
parents:
diff changeset
380
Dave Love <fx@gnu.org>
parents:
diff changeset
381 @kindex C-j
Dave Love <fx@gnu.org>
parents:
diff changeset
382 @findex newline-and-indent
38136
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
383 When entering lines of new code, use @kbd{C-j}
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
384 (@code{newline-and-indent}), which is equivalent to a @key{RET}
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
385 followed by a @key{TAB}. @kbd{C-j} at the end of a line creates a
278f2295cde6 New node Program Misc; text about word and paragraph and selective
Richard M. Stallman <rms@gnu.org>
parents: 38123
diff changeset
386 blank line and then gives it the appropriate indentation.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
387
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
388 @key{TAB} indents lines that start within a parenthetical grouping
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
389 each under the preceding line (or the text after the parenthesis).
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
390 Therefore, if you manually give one of these lines a nonstandard
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
391 indentation, the lines below will tend to follow it. This behavior is
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
392 convenient in cases where you have overridden the standard result of
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
393 @key{TAB} because you find it unaesthetic for a particular line.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
394
Dave Love <fx@gnu.org>
parents:
diff changeset
395 Remember that an open-parenthesis, open-brace or other opening delimiter
Dave Love <fx@gnu.org>
parents:
diff changeset
396 at the left margin is assumed by Emacs (including the indentation routines)
Dave Love <fx@gnu.org>
parents:
diff changeset
397 to be the start of a function. Therefore, you must never have an opening
Dave Love <fx@gnu.org>
parents:
diff changeset
398 delimiter in column zero that is not the beginning of a function, not even
Dave Love <fx@gnu.org>
parents:
diff changeset
399 inside a string. This restriction is vital for making the indentation
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
400 commands fast; you must simply accept it. @xref{Left Margin Paren},
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
401 for more information on this.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
402
38009
b6036155d1ca (Basic Indent): Add a cross-reference to description of indent-tabs-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 37997
diff changeset
403 Normally, lines are indented with tabs and spaces. If you want Emacs
b6036155d1ca (Basic Indent): Add a cross-reference to description of indent-tabs-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 37997
diff changeset
404 to use spaces only, see @ref{Just Spaces}.
b6036155d1ca (Basic Indent): Add a cross-reference to description of indent-tabs-mode.
Eli Zaretskii <eliz@gnu.org>
parents: 37997
diff changeset
405
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
406 @node Multi-line Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
407 @subsection Indenting Several Lines
Dave Love <fx@gnu.org>
parents:
diff changeset
408
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
409 When you wish to reindent several lines of code which have been
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
410 altered or moved to a different level in the parenthesis structure,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
411 you have several commands available.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
412
Dave Love <fx@gnu.org>
parents:
diff changeset
413 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
414 @item C-M-q
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
415 Reindent all the lines within one parenthetical grouping(@code{indent-sexp}).
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
416 @item C-M-\
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
417 Reindent all lines in the region (@code{indent-region}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
418 @item C-u @key{TAB}
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
419 Shift an entire parenthetical grouping rigidly sideways so that its
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
420 first line is properly indented.
38149
a07facd0bdf8 (Multi-line Indent): Document indent-code-rigidly.
Eli Zaretskii <eliz@gnu.org>
parents: 38148
diff changeset
421 @item M-x indent-code-rigidly
a07facd0bdf8 (Multi-line Indent): Document indent-code-rigidly.
Eli Zaretskii <eliz@gnu.org>
parents: 38148
diff changeset
422 Shift all the lines in the region rigidly sideways, but do not alter
a07facd0bdf8 (Multi-line Indent): Document indent-code-rigidly.
Eli Zaretskii <eliz@gnu.org>
parents: 38148
diff changeset
423 lines that start inside comments and strings.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
424 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
425
Dave Love <fx@gnu.org>
parents:
diff changeset
426 @kindex C-M-q
Dave Love <fx@gnu.org>
parents:
diff changeset
427 @findex indent-sexp
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
428 You can reindent the contents of a single parenthetical grouping by
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
429 positioning point before the beginning of it and typing @kbd{C-M-q}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
430 (@code{indent-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
431 bound to other suitable commands in other modes). The indentation of
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
432 the line where the grouping starts is not changed; therefore, this
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
433 changes only the relative indentation within the grouping, not its
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
434 overall indentation. To correct that as well, type @key{TAB} first.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
435
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
436 Another way to specify the range to be reindented is with the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
437 region. The command @kbd{C-M-\} (@code{indent-region}) applies
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
438 @key{TAB} to every line whose first character is between point and
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
439 mark.
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
440
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
441 @kindex C-u TAB
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
442 If you like the relative indentation within a grouping, but not the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
443 indentation of its first line, you can type @kbd{C-u @key{TAB}} to
38323
1241890094ae C-u TAB works only in certain modes.
Richard M. Stallman <rms@gnu.org>
parents: 38287
diff changeset
444 reindent the whole grouping as a rigid unit. (This works in Lisp
1241890094ae C-u TAB works only in certain modes.
Richard M. Stallman <rms@gnu.org>
parents: 38287
diff changeset
445 modes and C and related modes.) @key{TAB} with a numeric argument
1241890094ae C-u TAB works only in certain modes.
Richard M. Stallman <rms@gnu.org>
parents: 38287
diff changeset
446 reindents the current line as usual, then reindents by the same amount
1241890094ae C-u TAB works only in certain modes.
Richard M. Stallman <rms@gnu.org>
parents: 38287
diff changeset
447 all the lines in the parenthetical grouping starting on the current
1241890094ae C-u TAB works only in certain modes.
Richard M. Stallman <rms@gnu.org>
parents: 38287
diff changeset
448 line. It is clever, though, and does not alter lines that start
1241890094ae C-u TAB works only in certain modes.
Richard M. Stallman <rms@gnu.org>
parents: 38287
diff changeset
449 inside strings, or C preprocessor lines when in C mode.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
450
38149
a07facd0bdf8 (Multi-line Indent): Document indent-code-rigidly.
Eli Zaretskii <eliz@gnu.org>
parents: 38148
diff changeset
451 @findex indent-code-rigidly
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
452 You can also perform this operation on the region, using the command
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
453 @kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
454 region sideways, like @code{indent-rigidly} does (@pxref{Indentation
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
455 Commands}). It doesn't alter the indentation of lines that start
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
456 inside a comment or a string, unless the region starts inside that
38149
a07facd0bdf8 (Multi-line Indent): Document indent-code-rigidly.
Eli Zaretskii <eliz@gnu.org>
parents: 38148
diff changeset
457 comment or string.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
458
Dave Love <fx@gnu.org>
parents:
diff changeset
459 @node Lisp Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
460 @subsection Customizing Lisp Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
461 @cindex customizing Lisp indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
462
Dave Love <fx@gnu.org>
parents:
diff changeset
463 The indentation pattern for a Lisp expression can depend on the function
Dave Love <fx@gnu.org>
parents:
diff changeset
464 called by the expression. For each Lisp function, you can choose among
Dave Love <fx@gnu.org>
parents:
diff changeset
465 several predefined patterns of indentation, or define an arbitrary one with
Dave Love <fx@gnu.org>
parents:
diff changeset
466 a Lisp program.
Dave Love <fx@gnu.org>
parents:
diff changeset
467
Dave Love <fx@gnu.org>
parents:
diff changeset
468 The standard pattern of indentation is as follows: the second line of the
Dave Love <fx@gnu.org>
parents:
diff changeset
469 expression is indented under the first argument, if that is on the same
Dave Love <fx@gnu.org>
parents:
diff changeset
470 line as the beginning of the expression; otherwise, the second line is
Dave Love <fx@gnu.org>
parents:
diff changeset
471 indented underneath the function name. Each following line is indented
Dave Love <fx@gnu.org>
parents:
diff changeset
472 under the previous line whose nesting depth is the same.
Dave Love <fx@gnu.org>
parents:
diff changeset
473
Dave Love <fx@gnu.org>
parents:
diff changeset
474 @vindex lisp-indent-offset
Dave Love <fx@gnu.org>
parents:
diff changeset
475 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
Dave Love <fx@gnu.org>
parents:
diff changeset
476 the usual indentation pattern for the second line of an expression, so that
Dave Love <fx@gnu.org>
parents:
diff changeset
477 such lines are always indented @code{lisp-indent-offset} more columns than
Dave Love <fx@gnu.org>
parents:
diff changeset
478 the containing list.
Dave Love <fx@gnu.org>
parents:
diff changeset
479
Dave Love <fx@gnu.org>
parents:
diff changeset
480 @vindex lisp-body-indent
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
481 Certain functions override the standard pattern. Functions whose
42675
640c0fcaebf1 Fix typos.
Pavel Janík <Pavel@Janik.cz>
parents: 41495
diff changeset
482 names start with @code{def} treat the second lines as the start of
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
483 a @dfn{body}, by indenting the second line @code{lisp-body-indent}
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
484 additional columns beyond the open-parenthesis that starts the
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
485 expression.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
486
41409
9cea749ef5c3 (Lisp Indent): Add index entry for lisp-indent-function.
Eli Zaretskii <eliz@gnu.org>
parents: 40175
diff changeset
487 @cindex @code{lisp-indent-function} property
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
488 You can override the standard pattern in various ways for individual
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
489 functions, according to the @code{lisp-indent-function} property of the
Dave Love <fx@gnu.org>
parents:
diff changeset
490 function name. There are four possibilities for this property:
Dave Love <fx@gnu.org>
parents:
diff changeset
491
Dave Love <fx@gnu.org>
parents:
diff changeset
492 @table @asis
Dave Love <fx@gnu.org>
parents:
diff changeset
493 @item @code{nil}
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
494 This is the same as no property---use the standard indentation pattern.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
495 @item @code{defun}
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
496 Handle this function like a @samp{def} construct: treat the second
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
497 line as the start of a @dfn{body}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
498 @item a number, @var{number}
Dave Love <fx@gnu.org>
parents:
diff changeset
499 The first @var{number} arguments of the function are
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
500 @dfn{distinguished} arguments; the rest are considered the body
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
501 of the expression. A line in the expression is indented according to
Dave Love <fx@gnu.org>
parents:
diff changeset
502 whether the first argument on it is distinguished or not. If the
Dave Love <fx@gnu.org>
parents:
diff changeset
503 argument is part of the body, the line is indented @code{lisp-body-indent}
Dave Love <fx@gnu.org>
parents:
diff changeset
504 more columns than the open-parenthesis starting the containing
Dave Love <fx@gnu.org>
parents:
diff changeset
505 expression. If the argument is distinguished and is either the first
Dave Love <fx@gnu.org>
parents:
diff changeset
506 or second argument, it is indented @emph{twice} that many extra columns.
Dave Love <fx@gnu.org>
parents:
diff changeset
507 If the argument is distinguished and not the first or second argument,
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
508 the line uses the standard pattern.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
509 @item a symbol, @var{symbol}
Dave Love <fx@gnu.org>
parents:
diff changeset
510 @var{symbol} should be a function name; that function is called to
Dave Love <fx@gnu.org>
parents:
diff changeset
511 calculate the indentation of a line within this expression. The
Dave Love <fx@gnu.org>
parents:
diff changeset
512 function receives two arguments:
Dave Love <fx@gnu.org>
parents:
diff changeset
513 @table @asis
Dave Love <fx@gnu.org>
parents:
diff changeset
514 @item @var{state}
Dave Love <fx@gnu.org>
parents:
diff changeset
515 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
Dave Love <fx@gnu.org>
parents:
diff changeset
516 indentation and nesting computation) when it parses up to the
Dave Love <fx@gnu.org>
parents:
diff changeset
517 beginning of this line.
Dave Love <fx@gnu.org>
parents:
diff changeset
518 @item @var{pos}
Dave Love <fx@gnu.org>
parents:
diff changeset
519 The position at which the line being indented begins.
Dave Love <fx@gnu.org>
parents:
diff changeset
520 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
521 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
522 It should return either a number, which is the number of columns of
Dave Love <fx@gnu.org>
parents:
diff changeset
523 indentation for that line, or a list whose car is such a number. The
Dave Love <fx@gnu.org>
parents:
diff changeset
524 difference between returning a number and returning a list is that a
Dave Love <fx@gnu.org>
parents:
diff changeset
525 number says that all following lines at the same nesting level should
Dave Love <fx@gnu.org>
parents:
diff changeset
526 be indented just like this one; a list says that following lines might
Dave Love <fx@gnu.org>
parents:
diff changeset
527 call for different indentations. This makes a difference when the
Dave Love <fx@gnu.org>
parents:
diff changeset
528 indentation is being computed by @kbd{C-M-q}; if the value is a
Dave Love <fx@gnu.org>
parents:
diff changeset
529 number, @kbd{C-M-q} need not recalculate indentation for the following
Dave Love <fx@gnu.org>
parents:
diff changeset
530 lines until the end of the list.
Dave Love <fx@gnu.org>
parents:
diff changeset
531 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
532
Dave Love <fx@gnu.org>
parents:
diff changeset
533 @node C Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
534 @subsection Commands for C Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
535
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
536 Here are special features for indentation in C mode and related modes:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
537
Dave Love <fx@gnu.org>
parents:
diff changeset
538 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
539 @item C-c C-q
Dave Love <fx@gnu.org>
parents:
diff changeset
540 @kindex C-c C-q @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
541 @findex c-indent-defun
Dave Love <fx@gnu.org>
parents:
diff changeset
542 Reindent the current top-level function definition or aggregate type
Dave Love <fx@gnu.org>
parents:
diff changeset
543 declaration (@code{c-indent-defun}).
Dave Love <fx@gnu.org>
parents:
diff changeset
544
Dave Love <fx@gnu.org>
parents:
diff changeset
545 @item C-M-q
Dave Love <fx@gnu.org>
parents:
diff changeset
546 @kindex C-M-q @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
547 @findex c-indent-exp
Dave Love <fx@gnu.org>
parents:
diff changeset
548 Reindent each line in the balanced expression that follows point
Dave Love <fx@gnu.org>
parents:
diff changeset
549 (@code{c-indent-exp}). A prefix argument inhibits error checking and
Dave Love <fx@gnu.org>
parents:
diff changeset
550 warning messages about invalid syntax.
Dave Love <fx@gnu.org>
parents:
diff changeset
551
Dave Love <fx@gnu.org>
parents:
diff changeset
552 @item @key{TAB}
Dave Love <fx@gnu.org>
parents:
diff changeset
553 @findex c-indent-command
Dave Love <fx@gnu.org>
parents:
diff changeset
554 Reindent the current line, and/or in some cases insert a tab character
Dave Love <fx@gnu.org>
parents:
diff changeset
555 (@code{c-indent-command}).
Dave Love <fx@gnu.org>
parents:
diff changeset
556
Dave Love <fx@gnu.org>
parents:
diff changeset
557 If @code{c-tab-always-indent} is @code{t}, this command always reindents
Dave Love <fx@gnu.org>
parents:
diff changeset
558 the current line and does nothing else. This is the default.
Dave Love <fx@gnu.org>
parents:
diff changeset
559
Dave Love <fx@gnu.org>
parents:
diff changeset
560 If that variable is @code{nil}, this command reindents the current line
Dave Love <fx@gnu.org>
parents:
diff changeset
561 only if point is at the left margin or in the line's indentation;
Dave Love <fx@gnu.org>
parents:
diff changeset
562 otherwise, it inserts a tab (or the equivalent number of spaces,
Dave Love <fx@gnu.org>
parents:
diff changeset
563 if @code{indent-tabs-mode} is @code{nil}).
Dave Love <fx@gnu.org>
parents:
diff changeset
564
Dave Love <fx@gnu.org>
parents:
diff changeset
565 Any other value (not @code{nil} or @code{t}) means always reindent the
Dave Love <fx@gnu.org>
parents:
diff changeset
566 line, and also insert a tab if within a comment, a string, or a
Dave Love <fx@gnu.org>
parents:
diff changeset
567 preprocessor directive.
Dave Love <fx@gnu.org>
parents:
diff changeset
568 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
569
Dave Love <fx@gnu.org>
parents:
diff changeset
570 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
Dave Love <fx@gnu.org>
parents:
diff changeset
571 first selects the whole buffer as the region, then reindents that
Dave Love <fx@gnu.org>
parents:
diff changeset
572 region.
Dave Love <fx@gnu.org>
parents:
diff changeset
573
Dave Love <fx@gnu.org>
parents:
diff changeset
574 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
Dave Love <fx@gnu.org>
parents:
diff changeset
575 to the front of the block and then reindents it all.
Dave Love <fx@gnu.org>
parents:
diff changeset
576
Dave Love <fx@gnu.org>
parents:
diff changeset
577 @node Custom C Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
578 @subsection Customizing C Indentation
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
579 @cindex style (for indentation)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
580
Dave Love <fx@gnu.org>
parents:
diff changeset
581 C mode and related modes use a simple yet flexible mechanism for
Dave Love <fx@gnu.org>
parents:
diff changeset
582 customizing indentation. The mechanism works in two steps: first it
Dave Love <fx@gnu.org>
parents:
diff changeset
583 classifies the line syntactically according to its contents and context;
Dave Love <fx@gnu.org>
parents:
diff changeset
584 second, it associates each kind of syntactic construct with an
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
585 indentation offset based on your selected @dfn{style}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
586
Dave Love <fx@gnu.org>
parents:
diff changeset
587 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
588 @item M-x c-set-style @key{RET} @var{style} @key{RET}
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
589 Select predefined indentation style @var{style}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
590 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
591
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
592 A style is a named collection of indentation customizations that can
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
593 be used in C mode and the related modes. Emacs comes with several
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
594 predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
595 @code{stroustrup}, @code{linux}, @code{python}, @code{java},
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
596 @code{whitesmith}, @code{ellemtel}, @code{cc-mode}, and @code{user}.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
597 Some of these styles are primarily intended for one language, but any
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
598 of them can be used with any of the languages supported by these
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
599 modes. To find out what a style looks like, select it and reindent
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
600 some code, e.g., by typing @key{C-M-q} at the start of a function
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
601 definition.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
602
Dave Love <fx@gnu.org>
parents:
diff changeset
603 @findex c-set-style
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
604 To choose a style for the current buffer, use the command @kbd{M-x
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
605 c-set-style}. Specify a style name as an argument (case is not
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
606 significant). This command affects the current buffer only, and it
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
607 affects only future invocations of the indentation commands; it does
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
608 not reindent the code in the buffer. To reindent the whole buffer in
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
609 the new style, you can type @kbd{C-x h C-M-\}.
38148
071d97105015 Proofreading fixes from Peter Milliken.
Eli Zaretskii <eliz@gnu.org>
parents: 38136
diff changeset
610
071d97105015 Proofreading fixes from Peter Milliken.
Eli Zaretskii <eliz@gnu.org>
parents: 38136
diff changeset
611 @vindex c-default-style
071d97105015 Proofreading fixes from Peter Milliken.
Eli Zaretskii <eliz@gnu.org>
parents: 38136
diff changeset
612 You can also set the variable @code{c-default-style} to specify the
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
613 default style for various major modes. Its value should be an alist,
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
614 in which each element specifies one major mode and which indentation
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
615 style to use for it. For example,
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
616
Dave Love <fx@gnu.org>
parents:
diff changeset
617 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
618 (setq c-default-style
Dave Love <fx@gnu.org>
parents:
diff changeset
619 '((java-mode . "java") (other . "gnu")))
Dave Love <fx@gnu.org>
parents:
diff changeset
620 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
621
Dave Love <fx@gnu.org>
parents:
diff changeset
622 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
623 specifies an explicit choice for Java mode, and the default @samp{gnu}
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
624 style for the other C-like modes. This variable takes effect when you
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
625 select one of the C-like major modes; thus, if you specify a new
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
626 default style for Java mode, you can make it take effect in an
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
627 existing Java mode buffer by typing @kbd{M-x java-mode} there.
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
628
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
629 The @code{gnu} style specifies the formatting recommended by the GNU
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
630 Project for C; it is the default, so as to encourage use of our
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
631 recommended style.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
632
38871
9cefdb98080f (Custom C Indent): Fix an invalid xref.
Eli Zaretskii <eliz@gnu.org>
parents: 38867
diff changeset
633 @xref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
634 more information on customizing indentation for C and related modes,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
635 including how to override parts of an existing style and how to define
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
636 your own styles.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
637
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
638 @node Parentheses
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
639 @section Commands for Editing with Parentheses
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
640
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
641 @findex check-parens
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
642 @cindex unbalanced parentheses and quotes
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
643 This section describes the commands and features that take advantage
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
644 of the parenthesis structure in a program, or help you keep it
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
645 balanced.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
646
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
647 When talking about these facilities, the term ``parenthesis'' also
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
648 includes braces, brackets, or whatever delimiters are defined to match
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
649 in pairs. The major mode controls which delimiters are significant,
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
650 through the syntax table (@pxref{Syntax}). In Lisp, only parentheses
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
651 count; in C, these commands apply to braces and brackets too.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
652
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
653 You can use @kbd{M-x check-parens} to find any unbalanced
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
654 parentheses and unbalanced string quotes in the buffer.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
655
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
656 @menu
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
657 * Expressions:: Expressions with balanced parentheses.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
658 * Moving by Parens:: Commands for moving up, down and across
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
659 in the structure of parentheses.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
660 * Matching:: Insertion of a close-delimiter flashes matching open.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
661 @end menu
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
662
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
663 @node Expressions
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
664 @subsection Expressions with Balanced Parentheses
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
665
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
666 @cindex sexp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
667 @cindex expression
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
668 @cindex balanced expression
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
669 These commands deal with balanced expressions, also called
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
670 @dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
671 expression in Lisp.}.
28627
1f6ba3e73fe9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28391
diff changeset
672
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
673 @table @kbd
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
674 @item C-M-f
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
675 Move forward over a balanced expression (@code{forward-sexp}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
676 @item C-M-b
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
677 Move backward over a balanced expression(@code{backward-sexp}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
678 @item C-M-k
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
679 Kill balanced expression forward (@code{kill-sexp}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
680 @item C-M-@key{DEL}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
681 Kill balanced expression backward (@code{backward-kill-sexp}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
682 @item C-M-t
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
683 Transpose expressions (@code{transpose-sexps}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
684 @item C-M-@@
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
685 Put mark after following expression (@code{mark-sexp}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
686 @end table
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
687
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
688 Each programming language major mode customizes the definition of
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
689 balanced expressions to suit that language. Balanced expressions
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
690 typically include symbols, numbers, and string constants, as well as
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
691 any pair of matching delimiters and their contents. Some languages
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
692 have obscure forms of expression syntax that nobody has bothered to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
693 implement in Emacs.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
694
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
695 @cindex Control-Meta
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
696 By convention, the keys for these commands are all Control-Meta
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
697 characters. They usually act on expressions just as the corresponding
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
698 Meta characters act on words. For instance, the command @kbd{C-M-b}
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
699 moves backward over a balanced expression, just as @kbd{M-b} moves
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
700 back over a word.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
701
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
702 @kindex C-M-f
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
703 @kindex C-M-b
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
704 @findex forward-sexp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
705 @findex backward-sexp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
706 To move forward over a balanced expression, use @kbd{C-M-f}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
707 (@code{forward-sexp}). If the first significant character after point
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
708 is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
709 @samp{@{} in C), @kbd{C-M-f} moves past the matching closing
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
710 delimiter. If the character begins a symbol, string, or number,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
711 @kbd{C-M-f} moves over that.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
712
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
713 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
714 balanced expression. The detailed rules are like those above for
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
715 @kbd{C-M-f}, but with directions reversed. If there are prefix
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
716 characters (single-quote, backquote and comma, in Lisp) preceding the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
717 expression, @kbd{C-M-b} moves back over them as well. The balanced
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
718 expression commands move across comments as if they were whitespace,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
719 in most modes.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
720
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
721 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
722 specified number of times; with a negative argument, it moves in the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
723 opposite direction.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
724
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
725 @cindex killing expressions
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
726 @kindex C-M-k
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
727 @findex kill-sexp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
728 @kindex C-M-DEL
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
729 @findex backward-kill-sexp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
730 Killing a whole balanced expression can be done with @kbd{C-M-k}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
731 (@code{kill-sexp}) or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
732 @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over, and
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
733 @kbd{C-M-@key{DEL}} kills the characters that @kbd{C-M-b} would move
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
734 over. On some machines, @kbd{C-M-@key{DEL}} typed on the console is a
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
735 command to reboot; when that is so, you cannot use it as an Emacs
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
736 command. This conflict is rare, though: usually the @key{DEL} key for
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
737 Emacs is really @key{BACKSPACE}, and the reboot command is
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
738 @kbd{C-M-@key{DELETE}}, so there is no conflict.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
739
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
740 @cindex transposition of expressions
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
741 @kindex C-M-t
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
742 @findex transpose-sexps
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
743 A somewhat random-sounding command which is nevertheless handy is
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
744 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
745 balanced expression across the next one. An argument serves as a
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
746 repeat count, and a negative argument drags the previous balanced
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
747 expression backwards across those before it (thus canceling out the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
748 effect of @kbd{C-M-t} with a positive argument). An argument of zero,
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
749 rather than doing nothing, transposes the balanced expressions ending
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
750 at or after point and the mark.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
751
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
752 @kindex C-M-@@
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
753 @findex mark-sexp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
754 To set the region around the next balanced expression in the buffer,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
755 use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
756 that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
757 @kbd{C-M-f}. In particular, a negative argument is useful for putting
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
758 the mark at the beginning of the previous balanced expression.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
759
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
760 In languages that use infix operators, such as C, it is not possible
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
761 to recognize all balanced expressions as such because there can be
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
762 multiple possibilities at a given position. For example, C mode does
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
763 not treat @samp{foo + bar} as a single expression, even though it
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
764 @emph{is} one C expression; instead, it recognizes @samp{foo} as one
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
765 expression and @samp{bar} as another, with the @samp{+} as punctuation
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
766 between them. Both @samp{foo + bar} and @samp{foo} are legitimate
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
767 choices for ``the expression following point'' when point is at the
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
768 @samp{f}, so the expression commands must perforce choose one or the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
769 other to operate on. Note that @samp{(foo + bar)} is recognized as a
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
770 single expression in C mode, because of the parentheses.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
771
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
772 @node Moving by Parens
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
773 @subsection Moving in the Parenthesis Structure
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
774
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
775 @cindex parenthetical groupings
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
776 @cindex parentheses, moving across
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
777 @cindex matching parenthesis and braces, moving to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
778 @cindex braces, moving across
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
779 @cindex list commands
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
780 The Emacs commands for handling parenthetical groupings see nothing
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
781 except parentheses (or whatever characters must balance in the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
782 language you are working with), and the escape characters that might
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
783 be used to quote those. They are mainly intended for editing
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
784 programs, but can be useful for editing any text that has parentheses.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
785 They are sometimes called ``list'' commands because in Lisp these
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
786 groupings are lists.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
787
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
788 @table @kbd
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
789 @item C-M-n
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
790 Move forward over a parenthetical group (@code{forward-list}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
791 @item C-M-p
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
792 Move backward over a parenthetical group(@code{backward-list}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
793 @item C-M-u
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
794 Move up in parenthesis structure (@code{backward-up-list}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
795 @item C-M-d
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
796 Move down in parenthesis structure (@code{down-list}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
797 @end table
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
798
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
799 @kindex C-M-n
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
800 @kindex C-M-p
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
801 @findex forward-list
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
802 @findex backward-list
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
803 The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
804 @kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
805 parenthetical groupings, skipping blithely over any amount of text
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
806 that doesn't include meaningful parentheses (symbols, strings, etc.).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
807
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
808 @kindex C-M-u
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
809 @kindex C-M-d
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
810 @findex backward-up-list
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
811 @findex down-list
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
812 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
813 parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
814 @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
815 past one unmatched opening delimiter. A positive argument serves as a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
816 repeat count; a negative argument reverses the direction of motion, so
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
817 that the command moves forward and up one or more levels.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
818
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
819 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
820 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
821 delimiter, this is nearly the same as searching for a @samp{(}. An
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
822 argument specifies the number of levels to go down.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
823
Dave Love <fx@gnu.org>
parents:
diff changeset
824 @node Matching
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
825 @subsection Automatic Display Of Matching Parentheses
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
826 @cindex matching parentheses
Dave Love <fx@gnu.org>
parents:
diff changeset
827 @cindex parentheses, displaying matches
Dave Love <fx@gnu.org>
parents:
diff changeset
828
Dave Love <fx@gnu.org>
parents:
diff changeset
829 The Emacs parenthesis-matching feature is designed to show
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
830 automatically how parentheses (and other matching delimiters) match in
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
831 the text. Whenever you type a self-inserting character that is a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
832 closing delimiter, the cursor moves momentarily to the location of the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
833 matching opening delimiter, provided that is on the screen. If it is
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
834 not on the screen, Emacs displays some of the text near it in the echo
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
835 area. Either way, you can tell which grouping you are closing off.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
836
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
837 If the opening delimiter and closing delimiter are mismatched---such
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
838 as in @samp{[x)}---a warning message is displayed in the echo area.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
839
Dave Love <fx@gnu.org>
parents:
diff changeset
840 @vindex blink-matching-paren
Dave Love <fx@gnu.org>
parents:
diff changeset
841 @vindex blink-matching-paren-distance
Dave Love <fx@gnu.org>
parents:
diff changeset
842 @vindex blink-matching-delay
Dave Love <fx@gnu.org>
parents:
diff changeset
843 Three variables control parenthesis match display.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
844 @code{blink-matching-paren} turns the feature on or off: @code{nil}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
845 disables it, but the default is @code{t} to enable match display.
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
846
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
847 @code{blink-matching-delay} says how many seconds to leave the
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
848 cursor on the matching opening delimiter, before bringing it back to
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
849 the real location of point; the default is 1, but on some systems it
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
850 is useful to specify a fraction of a second.
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
851
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
852 @code{blink-matching-paren-distance} specifies how many characters
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
853 back to search to find the matching opening delimiter. If the match
38287
d6fff7f22127 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38238
diff changeset
854 is not found in that distance, scanning stops, and nothing is displayed.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
855 This is to prevent the scan for the matching delimiter from wasting
38164
ec15967a5cf7 Add details about C-M-a and C-M-e.
Richard M. Stallman <rms@gnu.org>
parents: 38149
diff changeset
856 lots of time when there is no match. The default is 25600.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
857
Dave Love <fx@gnu.org>
parents:
diff changeset
858 @cindex Show Paren mode
34122
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
859 @cindex highlighting matching parentheses
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
860 @findex show-paren-mode
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
861 Show Paren mode provides a more powerful kind of automatic matching.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
862 Whenever point is after a closing delimiter, that delimiter and its
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
863 matching opening delimiter are both highlighted; otherwise, if point
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
864 is before an opening delimiter, the matching closing delimiter is
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
865 highlighted. (There is no need to highlight the opening delimiter in
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
866 that case, because the cursor appears on top of that character.) Use
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
867 the command @kbd{M-x show-paren-mode} to enable or disable this mode.
34122
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
868
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
869 By default, @code{show-paren-mode} uses colors to highlight the
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
870 parentheses. However, if your display doesn't support colors, you can
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
871 customize the faces @code{show-paren-match-face} and
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
872 @code{show-paren-mismatch-face} to use other attributes, such as bold or
c42bb7d4437b Don't tell that show-paren only works on X. Explain how to customize
Eli Zaretskii <eliz@gnu.org>
parents: 31188
diff changeset
873 underline. @xref{Face Customization}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
874
Dave Love <fx@gnu.org>
parents:
diff changeset
875 @node Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
876 @section Manipulating Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
877 @cindex comments
Dave Love <fx@gnu.org>
parents:
diff changeset
878
Dave Love <fx@gnu.org>
parents:
diff changeset
879 Because comments are such an important part of programming, Emacs
47502
e8faddf96f0f Add ref for Flyspell Prog mode.
Richard M. Stallman <rms@gnu.org>
parents: 46035
diff changeset
880 provides special commands for editing and inserting comments. It can
e8faddf96f0f Add ref for Flyspell Prog mode.
Richard M. Stallman <rms@gnu.org>
parents: 46035
diff changeset
881 also do spell checking on comments with Flyspell Prog mode
e8faddf96f0f Add ref for Flyspell Prog mode.
Richard M. Stallman <rms@gnu.org>
parents: 46035
diff changeset
882 (@pxref{Spelling}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
883
Dave Love <fx@gnu.org>
parents:
diff changeset
884 @menu
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
885 * Comment Commands:: Inserting, killing, and indenting comments.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
886 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
887 * Options for Comments::Customizing the comment features.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
888 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
889
Dave Love <fx@gnu.org>
parents:
diff changeset
890 @node Comment Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
891 @subsection Comment Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
892 @cindex indentation for comments
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
893
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
894 The comment commands in this table insert, kill and align comments.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
895 They are described in this section and following sections.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
896
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
897 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
898 @item M-;
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
899 Insert or realign comment on current line; alternatively, comment or
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
900 uncomment the region (@code{comment-dwim}).
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
901 @item C-u M-;
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
902 Kill comment on current line (@code{comment-kill}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
903 @item C-x ;
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
904 Set comment column (@code{comment-set-column}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
905 @item C-M-j
Dave Love <fx@gnu.org>
parents:
diff changeset
906 Like @key{RET} followed by inserting and aligning a comment
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
907 (@code{comment-indent-new-line}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
908 @item M-x comment-region
Dave Love <fx@gnu.org>
parents:
diff changeset
909 Add or remove comment delimiters on all the lines in the region.
Dave Love <fx@gnu.org>
parents:
diff changeset
910 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
911
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
912 @kindex M-;
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
913 @findex comment-dwim
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
914 The command to create or align a comment is @kbd{M-;}
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
915 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
916 I Mean''; it indicates that this command can be used for many
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
917 different jobs relating to comments, depending on the situation where
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
918 you use it.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
919
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
920 If there is no comment already on the line, @kbd{M-;} inserts a new
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
921 comment, aligned at a specific column called the @dfn{comment column}.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
922 The new comment begins with the string Emacs thinks comments should
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
923 start with (the value of @code{comment-start}; see below). Point is
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
924 after that string, so you can insert the text of the comment right
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
925 away. If the major mode has specified a string to terminate comments,
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
926 @kbd{M-;} inserts that too, to keep the syntax valid.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
927
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
928 If the text of the line extends past the comment column, then the
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
929 comment start string is indented to a suitable boundary (usually, at
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
930 least one space is inserted).
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
931
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
932 You can also use @kbd{M-;} to align an existing comment. If a line
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
933 already contains the comment-start string, @kbd{M-;} reindents it to
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
934 the conventional alignment and moves point after it. (Exception:
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
935 comments starting in column 0 are not moved.) Even when an existing
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
936 comment is properly aligned, @kbd{M-;} is still useful for moving
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
937 directly to the start of the text inside the comment.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
938
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
939 @findex comment-kill
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
940 @kindex C-u M-;
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
941 @kbd{C-u M-;} kills any comment on the current line, along with the
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
942 whitespace before it. To reinsert the comment on another line, move
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
943 to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
944 realign it.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
945
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
946 Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
947 (@code{comment-dwim}) with a prefix argument. That command is
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
948 programmed so that when it receives a prefix argument it calls
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
949 @code{comment-kill}. However, @code{comment-kill} is a valid command
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
950 in its own right, and you can bind it directly to a key if you wish.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
951
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
952 @kbd{M-;} does two other jobs when used with an active region in
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
953 Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
954 removes comment delimiters on each line of the region. (If every line
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
955 is a comment, it removes comment delimiters from each; otherwise, it
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
956 adds comment delimiters to each.) If you are not using Transient Mark
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
957 mode, then you should use the commands @code{comment-region} and
36198
47124bb72465 Fix typo.
Andreas Schwab <schwab@suse.de>
parents: 36185
diff changeset
958 @code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}).
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
959 A prefix argument used in these circumstances specifies how many
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
960 comment delimiters to add or how many to delete.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
961
Dave Love <fx@gnu.org>
parents:
diff changeset
962 Some major modes have special rules for indenting certain kinds of
Dave Love <fx@gnu.org>
parents:
diff changeset
963 comments in certain contexts. For example, in Lisp code, comments which
Dave Love <fx@gnu.org>
parents:
diff changeset
964 start with two semicolons are indented as if they were lines of code,
Dave Love <fx@gnu.org>
parents:
diff changeset
965 instead of at the comment column. Comments which start with three
Dave Love <fx@gnu.org>
parents:
diff changeset
966 semicolons are supposed to start at the left margin. Emacs understands
Dave Love <fx@gnu.org>
parents:
diff changeset
967 these conventions by indenting a double-semicolon comment using @key{TAB},
Dave Love <fx@gnu.org>
parents:
diff changeset
968 and by not changing the indentation of a triple-semicolon comment at all.
Dave Love <fx@gnu.org>
parents:
diff changeset
969
Dave Love <fx@gnu.org>
parents:
diff changeset
970 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
971 ;; This function is just an example
Dave Love <fx@gnu.org>
parents:
diff changeset
972 ;;; Here either two or three semicolons are appropriate.
Dave Love <fx@gnu.org>
parents:
diff changeset
973 (defun foo (x)
Dave Love <fx@gnu.org>
parents:
diff changeset
974 ;;; And now, the first part of the function:
Dave Love <fx@gnu.org>
parents:
diff changeset
975 ;; The following line adds one.
Dave Love <fx@gnu.org>
parents:
diff changeset
976 (1+ x)) ; This line adds one.
Dave Love <fx@gnu.org>
parents:
diff changeset
977 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
978
Dave Love <fx@gnu.org>
parents:
diff changeset
979 In C code, a comment preceded on its line by nothing but whitespace
Dave Love <fx@gnu.org>
parents:
diff changeset
980 is indented like a line of code.
Dave Love <fx@gnu.org>
parents:
diff changeset
981
Dave Love <fx@gnu.org>
parents:
diff changeset
982 @node Multi-Line Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
983 @subsection Multiple Lines of Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
984
Dave Love <fx@gnu.org>
parents:
diff changeset
985 @kindex C-M-j
Dave Love <fx@gnu.org>
parents:
diff changeset
986 @cindex blank lines in programs
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
987 @findex comment-indent-new-line
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
988 If you are typing a comment and wish to continue it on another line,
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
989 you can use the command @kbd{C-M-j} (@code{comment-indent-new-line}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
990 This terminates the comment you are typing, creates a new blank line
Dave Love <fx@gnu.org>
parents:
diff changeset
991 afterward, and begins a new comment indented under the old one. When
Dave Love <fx@gnu.org>
parents:
diff changeset
992 Auto Fill mode is on, going past the fill column while typing a comment
Dave Love <fx@gnu.org>
parents:
diff changeset
993 causes the comment to be continued in just this fashion. If point is
Dave Love <fx@gnu.org>
parents:
diff changeset
994 not at the end of the line when @kbd{C-M-j} is typed, the text on
Dave Love <fx@gnu.org>
parents:
diff changeset
995 the rest of the line becomes part of the new comment line.
Dave Love <fx@gnu.org>
parents:
diff changeset
996
Dave Love <fx@gnu.org>
parents:
diff changeset
997 @findex comment-region
Dave Love <fx@gnu.org>
parents:
diff changeset
998 To turn existing lines into comment lines, use the @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
999 comment-region} command. It adds comment delimiters to the lines that start
Dave Love <fx@gnu.org>
parents:
diff changeset
1000 in the region, thus commenting them out. With a negative argument, it
Dave Love <fx@gnu.org>
parents:
diff changeset
1001 does the opposite---it deletes comment delimiters from the lines in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1002 region.
Dave Love <fx@gnu.org>
parents:
diff changeset
1003
Dave Love <fx@gnu.org>
parents:
diff changeset
1004 With a positive argument, @code{comment-region} duplicates the last
Dave Love <fx@gnu.org>
parents:
diff changeset
1005 character of the comment start sequence it adds; the argument specifies
Dave Love <fx@gnu.org>
parents:
diff changeset
1006 how many copies of the character to insert. Thus, in Lisp mode,
Dave Love <fx@gnu.org>
parents:
diff changeset
1007 @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating
Dave Love <fx@gnu.org>
parents:
diff changeset
1008 the comment delimiter is a way of calling attention to the comment. It
Dave Love <fx@gnu.org>
parents:
diff changeset
1009 can also affect how the comment is indented. In Lisp, for proper
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1010 indentation, you should use an argument of two or three, if between defuns;
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1011 if within a defun, it must be three.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1012
Dave Love <fx@gnu.org>
parents:
diff changeset
1013 @node Options for Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
1014 @subsection Options Controlling Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
1015
Dave Love <fx@gnu.org>
parents:
diff changeset
1016 @vindex comment-column
Dave Love <fx@gnu.org>
parents:
diff changeset
1017 @kindex C-x ;
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1018 @findex comment-set-column
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1019 The comment column is stored in the variable @code{comment-column}. You
Dave Love <fx@gnu.org>
parents:
diff changeset
1020 can set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1021 (@code{comment-set-column}) sets the comment column to the column point is
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1022 at. @kbd{C-u C-x ;} sets the comment column to match the last comment
Dave Love <fx@gnu.org>
parents:
diff changeset
1023 before point in the buffer, and then does a @kbd{M-;} to align the
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1024 current line's comment under the previous one.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1025
Dave Love <fx@gnu.org>
parents:
diff changeset
1026 The variable @code{comment-column} is per-buffer: setting the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1027 in the normal fashion affects only the current buffer, but there is a
Dave Love <fx@gnu.org>
parents:
diff changeset
1028 default value which you can change with @code{setq-default}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1029 @xref{Locals}. Many major modes initialize this variable for the
Dave Love <fx@gnu.org>
parents:
diff changeset
1030 current buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
1031
Dave Love <fx@gnu.org>
parents:
diff changeset
1032 @vindex comment-start-skip
Dave Love <fx@gnu.org>
parents:
diff changeset
1033 The comment commands recognize comments based on the regular
Dave Love <fx@gnu.org>
parents:
diff changeset
1034 expression that is the value of the variable @code{comment-start-skip}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1035 Make sure this regexp does not match the null string. It may match more
Dave Love <fx@gnu.org>
parents:
diff changeset
1036 than the comment starting delimiter in the strictest sense of the word;
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1037 for example, in C mode the value of the variable is
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1038 @c This stops M-q from breaking the line inside that @code.
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1039 @code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spaces
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1040 after the @samp{/*} itself, and accepts C++ style comments also.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1041 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
Dave Love <fx@gnu.org>
parents:
diff changeset
1042 the string, which is needed to deny the first star its special meaning
Dave Love <fx@gnu.org>
parents:
diff changeset
1043 in regexp syntax. @xref{Regexps}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1044
Dave Love <fx@gnu.org>
parents:
diff changeset
1045 @vindex comment-start
Dave Love <fx@gnu.org>
parents:
diff changeset
1046 @vindex comment-end
Dave Love <fx@gnu.org>
parents:
diff changeset
1047 When a comment command makes a new comment, it inserts the value of
Dave Love <fx@gnu.org>
parents:
diff changeset
1048 @code{comment-start} to begin it. The value of @code{comment-end} is
Dave Love <fx@gnu.org>
parents:
diff changeset
1049 inserted after point, so that it will follow the text that you will insert
Dave Love <fx@gnu.org>
parents:
diff changeset
1050 into the comment. In C mode, @code{comment-start} has the value
Dave Love <fx@gnu.org>
parents:
diff changeset
1051 @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1052
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1053 @vindex comment-padding
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1054 The variable @code{comment-padding} specifies how many spaces
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1055 @code{comment-region} should insert on each line between the
38018
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1056 comment delimiter and the line's original text. The default is 1,
f802bdff6c2c Update various command names and variable defaults.
Richard M. Stallman <rms@gnu.org>
parents: 38009
diff changeset
1057 to insert one space.
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1058
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1059 @vindex comment-multi-line
Dave Love <fx@gnu.org>
parents:
diff changeset
1060 The variable @code{comment-multi-line} controls how @kbd{C-M-j}
Dave Love <fx@gnu.org>
parents:
diff changeset
1061 (@code{indent-new-comment-line}) behaves when used inside a comment. If
Dave Love <fx@gnu.org>
parents:
diff changeset
1062 @code{comment-multi-line} is @code{nil}, as it normally is, then the
Dave Love <fx@gnu.org>
parents:
diff changeset
1063 comment on the starting line is terminated and a new comment is started
Dave Love <fx@gnu.org>
parents:
diff changeset
1064 on the new following line. If @code{comment-multi-line} is not
Dave Love <fx@gnu.org>
parents:
diff changeset
1065 @code{nil}, then the new following line is set up as part of the same
Dave Love <fx@gnu.org>
parents:
diff changeset
1066 comment that was found on the starting line. This is done by not
Dave Love <fx@gnu.org>
parents:
diff changeset
1067 inserting a terminator on the old line, and not inserting a starter on
Dave Love <fx@gnu.org>
parents:
diff changeset
1068 the new line. In languages where multi-line comments work, the choice
Dave Love <fx@gnu.org>
parents:
diff changeset
1069 of value for this variable is a matter of taste.
Dave Love <fx@gnu.org>
parents:
diff changeset
1070
41495
0bac781ea0d6 Undo previous change.
Richard M. Stallman <rms@gnu.org>
parents: 41472
diff changeset
1071 @vindex comment-indent-function
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1072 The variable @code{comment-indent-function} should contain a function
Dave Love <fx@gnu.org>
parents:
diff changeset
1073 that will be called to compute the indentation for a newly inserted
Dave Love <fx@gnu.org>
parents:
diff changeset
1074 comment or for aligning an existing comment. It is set differently by
Dave Love <fx@gnu.org>
parents:
diff changeset
1075 various major modes. The function is called with no arguments, but with
Dave Love <fx@gnu.org>
parents:
diff changeset
1076 point at the beginning of the comment, or at the end of a line if a new
Dave Love <fx@gnu.org>
parents:
diff changeset
1077 comment is to be inserted. It should return the column in which the
Dave Love <fx@gnu.org>
parents:
diff changeset
1078 comment ought to start. For example, in Lisp mode, the indent hook
Dave Love <fx@gnu.org>
parents:
diff changeset
1079 function bases its decision on how many semicolons begin an existing
Dave Love <fx@gnu.org>
parents:
diff changeset
1080 comment, and on the code in the preceding lines.
Dave Love <fx@gnu.org>
parents:
diff changeset
1081
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1082 @node Documentation
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1083 @section Documentation Lookup
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1084
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1085 Emacs provides several features you can use to look up the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1086 documentation of functions, variables and commands that you plan to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1087 use in your program.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1088
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1089 @menu
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1090 * Info Lookup:: Looking up library functions and commands
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1091 in Info files.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1092 * Man Page:: Looking up man pages of library functions and commands.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1093 * Lisp Doc:: Looking up Emacs Lisp functions, etc.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1094 @end menu
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1095
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1096 @node Info Lookup
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1097 @subsection Info Documentation Lookup
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1098
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1099 @findex info-lookup-symbol
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1100 @findex info-lookup-file
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1101 @kindex C-h C-i
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1102 For C, Lisp, and other languages that have documentation in Info,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1103 you can use @kbd{C-h C-i} (@code{info-lookup-symbol}) to view the Info
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1104 documentation for a symbol. You specify the symbol with the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1105 minibuffer; the default is the symbol appearing in the buffer at
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1106 point.
Dave Love <fx@gnu.org>
parents:
diff changeset
1107
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1108 The major mode determines where to look for documentation for the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1109 symbol---which Info files to look in, and which indices to search.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1110 You can also use @kbd{M-x info-lookup-file} to look for documentation
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1111 for a file name.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1112
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1113 This feature currently supports the modes Awk, Autoconf, Bison, C,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1114 Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1115 provided you have installed the relevant Info files, which are
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1116 typically available with the appropriate GNU package.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1117
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1118 @node Man Page
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1119 @subsection Man Page Lookup
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1120
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1121 @cindex manual page
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1122 On Unix, the main form of on-line documentation was the @dfn{manual
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1123 page} or @dfn{man page}. In the GNU operating system, we hope to
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1124 replace man pages with better-organized manuals that you can browse
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1125 with Info (@pxref{Misc Help}). This process is not finished, so it is
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1126 still useful to read manual pages.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1127
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1128 @findex manual-entry
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1129 You can read the man page for an operating system command, library
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1130 function, or system call, with the @kbd{M-x manual-entry} command. It
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1131 runs the @code{man} program to format the man page; if the system
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1132 permits, it runs @code{man} asynchronously, so that you can keep on
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1133 editing while the page is being formatted. (On MS-DOS and MS-Windows
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1134 3, you cannot edit while Emacs waits for @code{man} to finish.) The
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1135 result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1136 use a special major mode, Man mode, that facilitates scrolling and
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1137 jumping to other manual pages. For details, type @kbd{C-h m} while in
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1138 a man page buffer.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1139
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1140 @cindex sections of manual pages
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1141 Each man page belongs to one of ten or more @dfn{sections}, each
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1142 named by a digit or by a digit and a letter. Sometimes there are
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1143 multiple man pages with the same name in different sections. To read
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1144 a man page from a specific section, type
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1145 @samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1146 when @kbd{M-x manual-entry} prompts for the topic. For example, to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1147 read the man page for the C library function @code{chmod} (as opposed
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1148 to a command of the same name), type @kbd{M-x manual-entry @key{RET}
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1149 chmod(2) @key{RET}} (@code{chmod} is a system call, so it is in
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1150 section @samp{2}).
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1151
38667
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1152 @vindex Man-switches
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1153 If you do not specify a section, the results depend on how the
38667
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1154 @code{man} program works on your system. Some of them display only
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1155 the first man page they find. Others display all man pages that have
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1156 the specified name, so you can move between them with the @kbd{M-n}
38667
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1157 and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1158 accepts a @samp{-a} command-line option which tells it to display all
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1159 the man pages for the specified topic. If you want this behavior, you
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1160 can add this option to the value of the variable @code{Man-switches}.}.
6ed2cc05e016 (Man Page): Mention the -a switch to `man' in a footnote.
Eli Zaretskii <eliz@gnu.org>
parents: 38323
diff changeset
1161 The mode line shows how many manual pages are present in the Man buffer.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1162
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1163 @vindex Man-fontify-manpage-flag
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1164 By default, Emacs highlights the text in man pages. For a long man
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1165 page, highlighting can take substantial time. You can turn off
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1166 highlighting of man pages by setting the variable
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1167 @code{Man-fontify-manpage-flag} to @code{nil}.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1168
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1169 @findex Man-fontify-manpage
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1170 If you insert the text of a man page into an Emacs buffer in some
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1171 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1172 perform the same conversions that @kbd{M-x manual-entry} does.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1173
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1174 @findex woman
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1175 @cindex manual pages, on MS-DOS/MS-Windows
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1176 An alternative way of reading manual pages is the @kbd{M-x woman}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1177 command@footnote{The name of the command, @code{woman}, is an acronym
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1178 for ``w/o (without) man,'' since it doesn't use the @code{man}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1179 program.}. Unlike @kbd{M-x man}, it does not run any external
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1180 programs to format and display the man pages; instead it does the job
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1181 in Emacs Lisp, so it works on systems such as MS-Windows, where the
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1182 @code{man} program (and the other programs it uses) are not generally
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1183 available.
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1184
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1185 @kbd{M-x woman} prompts for a name of a manual page, and provides
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1186 completion based on the list of manual pages that are installed on
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1187 your machine; the list of available manual pages is computed
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1188 automatically the first time you invoke @code{woman}. The word at
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1189 point in the current buffer is used to suggest the default for the
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1190 name the manual page.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1191
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1192 With a numeric argument, @kbd{M-x woman} recomputes the list of the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1193 manual pages used for completion. This is useful if you add or delete
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1194 manual pages.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1195
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1196 If you type a name of a manual page and @kbd{M-x woman} finds that
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1197 several manual pages by the same name exist in different sections, it
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1198 pops up a window with possible candidates asking you to choose one of
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1199 them.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1200
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1201 @vindex woman-manpath
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1202 By default, @kbd{M-x woman} looks for manual pages in the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1203 directories specified in the @code{MANPATH} environment variable. (If
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1204 @code{MANPATH} is not set, @code{woman} uses a suitable default value,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1205 which can be customized.) More precisely, @code{woman} looks for
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1206 subdirectories that match the shell wildcard pattern @file{man*} in each one
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1207 of these directories, and tries to find the manual pages in those
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1208 subdirectories. When first invoked, @kbd{M-x woman} converts the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1209 value of @code{MANPATH} to a list of directory names and stores that
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1210 list in the @code{woman-manpath} variable. Changing the value of this
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1211 variable is another way to control the list of directories used.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1212
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1213 @vindex woman-path
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1214 You can also augment the list of directories searched by
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1215 @code{woman} by setting the value of the @code{woman-path} variable.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1216 This variable should hold a list of specific directories which
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1217 @code{woman} should search, in addition to those in
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1218 @code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1219 @code{woman-path} are searched for the manual pages, not for
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1220 @file{man*} subdirectories.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1221
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1222 @findex woman-find-file
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1223 Occasionally, you might need to display manual pages that are not in
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1224 any of the directories listed by @code{woman-manpath} and
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1225 @code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1226 name of a manual page file, with completion, and then formats and
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1227 displays that file like @kbd{M-x woman} does.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1228
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1229 @vindex woman-dired-keys
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1230 The first time you invoke @kbd{M-x woman}, it defines the Dired
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1231 @kbd{W} key to run the @code{woman-find-file} command on the current
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1232 line's file. You can disable this by setting the variable
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1233 @code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1234 the Tar-mode @kbd{w} key is define to invoke @code{woman-find-file} on
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1235 the current line's archive member.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1236
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1237 For more information about setting up and using @kbd{M-x woman}, see
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1238 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1239 Manual}.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1240
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1241 @node Lisp Doc
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1242 @subsection Emacs Lisp Documentation Lookup
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1243
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1244 As you edit Lisp code to be run in Emacs, you can use the commands
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1245 @kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1246 (@code{describe-variable}) to view documentation of functions and
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1247 variables that you want to use. These commands use the minibuffer to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1248 read the name of a function or variable to document, and display the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1249 documentation in a window. Their default arguments are based on the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1250 code in the neighborhood of point. For @kbd{C-h f}, the default is
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1251 the function called in the innermost list containing point. @kbd{C-h
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1252 v} uses the symbol name around or adjacent to point as its default.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1253
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1254 @cindex Eldoc mode
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1255 @findex eldoc-mode
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1256 A more automatic but less powerful method is Eldoc mode. This minor
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1257 mode constantly displays in the echo area the argument list for the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1258 function being called at point. (In other words, it finds the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1259 function call that point is contained in, and displays the argument
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1260 list of that function.) Eldoc mode applies in Emacs Lisp and Lisp
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1261 Interaction modes only. Use the command @kbd{M-x eldoc-mode} to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1262 enable or disable this feature.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1263
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1264 @node Hideshow
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1265 @section Hideshow minor mode
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1266
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1267 @findex hs-minor-mode
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1268 Hideshow minor mode provides selective display of portions of a
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1269 program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode}
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1270 to enable or disable this mode, or add @code{hs-minor-mode} to the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1271 mode hook for certain major modes in order to enable it automatically
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1272 for those modes.
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1273
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1274 Just what constitutes a block depends on the major mode. In C mode
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1275 or C++ mode, they are delimited by braces, while in Lisp mode and
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1276 similar modes they are delimited by parentheses. Multi-line comments
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1277 also count as blocks.
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1278
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1279 @findex hs-hide-all
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1280 @findex hs-hide-block
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1281 @findex hs-show-all
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1282 @findex hs-show-block
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1283 @findex hs-show-region
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1284 @findex hs-hide-level
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1285 @findex hs-minor-mode
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1286 @kindex C-c @@ C-h
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1287 @kindex C-c @@ C-s
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1288 @kindex C-c @@ C-M-h
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1289 @kindex C-c @@ C-M-s
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1290 @kindex C-c @@ C-r
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1291 @kindex C-c @@ C-l
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1292 @kindex S-Mouse-2
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1293 @table @kbd
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1294 @item C-c @@ C-h
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1295 Hide the current block (@code{hs-hide-block}).
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1296 @item C-c @@ C-s
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1297 Show the current block (@code{hs-show-block}).
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1298 @item C-c @@ C-c
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1299 Either hide or show the current block (@code{hs-toggle-hiding})
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1300 @item S-Mouse-2
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1301 Either hide or show the block you click on (@code{hs-mouse-toggle-hiding})
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1302 @item C-c @@ C-M-h
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1303 Hide all top-level blocks (@code{hs-hide-all}).
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1304 @item C-c @@ C-M-s
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1305 Show everything in the buffer (@code{hs-show-all}).
37997
c329103798cc (Hideshow): Fix the docs of keybindings which used a single `@'.
Eli Zaretskii <eliz@gnu.org>
parents: 37978
diff changeset
1306 @item C-c @@ C-l
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1307 Hide all blocks @var{n} levels below this block
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1308 (@code{hs-hide-level}).
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1309 @end table
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1310
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1311 @vindex hs-hide-comments-when-hiding-all
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1312 @vindex hs-isearch-open
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1313 @vindex hs-special-modes-alist
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1314 These user options exist for customizing Hideshow mode.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1315
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1316 @table @code
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1317 @item hs-hide-comments-when-hiding-all
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1318 Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1319
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1320 @item hs-isearch-open
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1321 Specifies what kind of hidden blocks to open in Isearch mode.
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1322 The value should be one of these four symbols.
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1323
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1324 @table @code
38946
9a1045bcf43c Update values of hs-isearch-open.
Richard M. Stallman <rms@gnu.org>
parents: 38871
diff changeset
1325 @item code
9a1045bcf43c Update values of hs-isearch-open.
Richard M. Stallman <rms@gnu.org>
parents: 38871
diff changeset
1326 Open only code blocks.
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1327 @item comment
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1328 Open only comments.
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1329 @item t
38946
9a1045bcf43c Update values of hs-isearch-open.
Richard M. Stallman <rms@gnu.org>
parents: 38871
diff changeset
1330 Open both code blocks and comments.
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1331 @item nil
38946
9a1045bcf43c Update values of hs-isearch-open.
Richard M. Stallman <rms@gnu.org>
parents: 38871
diff changeset
1332 Open neither code blocks nor comments.
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1333 @end table
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1334
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1335 @item hs-special-modes-alist
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1336 A list of elements, each specifying how to initialize Hideshow
38231
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1337 variables for one major mode. See the variable's documentation string
a94c26975e95 Explain purpose of mode hooks.
Richard M. Stallman <rms@gnu.org>
parents: 38212
diff changeset
1338 for more information.
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1339 @end table
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1340
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1341 @node Symbol Completion
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1342 @section Completion for Symbol Names
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1343 @cindex completion (symbol names)
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1344
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1345 In Emacs, completion is something you normally do in the minibuffer.
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1346 But one kind of completion is available in all buffers: completion for
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1347 symbol names.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1348
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1349 @kindex M-TAB
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1350 The character @kbd{M-@key{TAB}} runs a command to complete the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1351 partial symbol before point against the set of meaningful symbol
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1352 names. This command inserts at point any additional characters that
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1353 it can determine from the partial name.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1354
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1355 If the partial name in the buffer has multiple possible completions
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1356 that differ in the very next character, so that it is impossible to
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1357 complete even one more character, @kbd{M-@key{TAB}} displays a list of
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1358 all possible completions in another window.
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1359
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1360 @cindex tags-based completion
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1361 @cindex Info index completion
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1362 @findex complete-symbol
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1363 In most programming language major modes, @kbd{M-@key{TAB}} runs the
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1364 command @code{complete-symbol}, which provides two kinds of completion.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1365 Normally it does completion based on a tags table (@pxref{Tags}); with a
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1366 numeric argument (regardless of the value), it does completion based on
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1367 the names listed in the Info file indexes for your language. Thus, to
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1368 complete the name of a symbol defined in your own program, use
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1369 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1370 library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1371 completion works only if there is an Info file for the standard library
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1372 functions of your language, and only if it is installed at your site.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1373
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1374 @cindex Lisp symbol completion
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1375 @cindex completion (Lisp symbols)
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1376 @findex lisp-complete-symbol
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1377 In Emacs-Lisp mode, the name space for completion normally consists of
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1378 nontrivial symbols present in Emacs---those that have function
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1379 definitions, values or properties. However, if there is an
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1380 open-parenthesis immediately before the beginning of the partial symbol,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1381 only symbols with function definitions are considered as completions.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1382 The command which implements this is @code{lisp-complete-symbol}.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1383
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1384 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1385 based on the spell-checker's dictionary. @xref{Spelling}.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1386
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1387 @node Glasses
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1388 @section Glasses minor mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1389 @cindex Glasses mode
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1390 @cindex identifiers, making long ones readable
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1391 @cindex StudlyCaps, making them readable
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1392 @findex glasses-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1393
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1394 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1395 readable by altering the way they display. It knows two different
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1396 ways to do this: by displaying underscores between a lower-case letter
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1397 and the following capital letter, and by emboldening the capital
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1398 letters. It does not alter the buffer text, only the way they
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1399 display, so you can use it even on read-only buffers. You can use the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1400 command @kbd{M-x glasses-mode} to enable or disable the mode in the
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1401 current buffer; you can also add @code{glasses-mode} to the mode hook
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1402 of the programming language major modes in which you normally want
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1403 to use Glasses mode.
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1404
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1405 @node Misc for Programs
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1406 @section Other Features Useful for Editing Programs
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1407
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1408 A number of Emacs commands that aren't designed specifically for
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1409 editing programs are useful for that nonetheless.
26292
81cd0c225dd9 Last changes for etags (I hope).
Francesco Potortì <pot@gnu.org>
parents: 26289
diff changeset
1410
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1411 The Emacs commands that operate on words, sentences and paragraphs
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1412 are useful for editing code. Most symbols names contain words
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1413 (@pxref{Words}); sentences can be found in strings and comments
38867
bd208373c5a8 Many clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 38667
diff changeset
1414 (@pxref{Sentences}). Paragraphs in the strict sense can be found in
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1415 program code (in long comments), but the paragraph commands are useful
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1416 in other places too, because programming language major modes define
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1417 paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1418 Judicious use of blank lines to make the program clearer will also
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1419 provide useful chunks of text for the paragraph commands to work on.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1420 Auto Fill mode, if enabled in a programming language major mode,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1421 indents the new lines which it creates.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1422
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1423 The selective display feature is useful for looking at the overall
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1424 structure of a function (@pxref{Selective Display}). This feature
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1425 hides the lines that are indented more than a specified amount.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1426 Programming modes often support Outline minor mode (@pxref{Outline
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1427 Mode}). The Foldout package provides folding-editor features
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1428 (@pxref{Foldout}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1429
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1430 The ``automatic typing'' features may be useful for writing programs.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1431 @xref{Top,,Autotyping, autotype, Autotyping}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1432
Dave Love <fx@gnu.org>
parents:
diff changeset
1433 @node C Modes
Dave Love <fx@gnu.org>
parents:
diff changeset
1434 @section C and Related Modes
Dave Love <fx@gnu.org>
parents:
diff changeset
1435 @cindex C mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1436 @cindex Java mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1437 @cindex Pike mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1438 @cindex IDL mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1439 @cindex CORBA IDL mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1440 @cindex Objective C mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1441 @cindex C++ mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1442 @cindex mode, Java
Dave Love <fx@gnu.org>
parents:
diff changeset
1443 @cindex mode, C
Dave Love <fx@gnu.org>
parents:
diff changeset
1444 @cindex mode, Objective C
Dave Love <fx@gnu.org>
parents:
diff changeset
1445 @cindex mode, CORBA IDL
Dave Love <fx@gnu.org>
parents:
diff changeset
1446 @cindex mode, Pike
Dave Love <fx@gnu.org>
parents:
diff changeset
1447
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1448 This section gives a brief description of the special features
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1449 available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1450 (These are called ``C mode and related modes.'') @xref{Top, CC Mode,
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1451 ccmode, , CC Mode}, for a more extensive description of these modes
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1452 and their special features.
28329
6e740f27f255 (Programs): Mention outline features.
Dave Love <fx@gnu.org>
parents: 27221
diff changeset
1453
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1454 @menu
38212
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1455 * Motion in C:: Commands to move by C statements, etc.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1456 * Electric C:: Colon and other chars can automatically reindent.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1457 * Hungry Delete:: A more powerful DEL command.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1458 * Other C Commands:: Filling comments, viewing expansion of macros,
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1459 and other neat features.
6b14cc47a4f2 Major rewrite. Sections Tags, Emerge, Change Log and Authors
Richard M. Stallman <rms@gnu.org>
parents: 38164
diff changeset
1460 * Comments in C:: Options for customizing comment style.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1461 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1462
Dave Love <fx@gnu.org>
parents:
diff changeset
1463 @node Motion in C
Dave Love <fx@gnu.org>
parents:
diff changeset
1464 @subsection C Mode Motion Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1465
Dave Love <fx@gnu.org>
parents:
diff changeset
1466 This section describes commands for moving point, in C mode and
Dave Love <fx@gnu.org>
parents:
diff changeset
1467 related modes.
Dave Love <fx@gnu.org>
parents:
diff changeset
1468
Dave Love <fx@gnu.org>
parents:
diff changeset
1469 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1470 @item C-c C-u
Dave Love <fx@gnu.org>
parents:
diff changeset
1471 @kindex C-c C-u @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1472 @findex c-up-conditional
Dave Love <fx@gnu.org>
parents:
diff changeset
1473 Move point back to the containing preprocessor conditional, leaving the
Dave Love <fx@gnu.org>
parents:
diff changeset
1474 mark behind. A prefix argument acts as a repeat count. With a negative
Dave Love <fx@gnu.org>
parents:
diff changeset
1475 argument, move point forward to the end of the containing
Dave Love <fx@gnu.org>
parents:
diff changeset
1476 preprocessor conditional. When going backwards, @code{#elif} is treated
Dave Love <fx@gnu.org>
parents:
diff changeset
1477 like @code{#else} followed by @code{#if}. When going forwards,
Dave Love <fx@gnu.org>
parents:
diff changeset
1478 @code{#elif} is ignored.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
1479
Dave Love <fx@gnu.org>
parents:
diff changeset
1480 @item C-c C-p
Dave Love <fx@gnu.org>
parents:
diff changeset
1481 @kindex C-c C-p @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1482 @findex c-backward-conditional
Dave Love <fx@gnu.org>
parents:
diff changeset
1483 Move point back over a preprocessor conditional, leaving the mark
Dave Love <fx@gnu.org>
parents:
diff changeset
1484 behind. A prefix argument acts as a repeat count. With a negative
Dave Love <fx@gnu.org>
parents:
diff changeset
1485 argument, move forward.
Dave Love <fx@gnu.org>
parents:
diff changeset
1486
Dave Love <fx@gnu.org>
parents:
diff changeset
1487 @item C-c C-n
Dave Love <fx@gnu.org>
parents:
diff changeset
1488 @kindex C-c C-n @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1489 @findex c-forward-conditional
Dave Love <fx@gnu.org>
parents:
diff changeset
1490 Move point forward across a preprocessor conditional, leaving the mark
Dave Love <fx@gnu.org>
parents:
diff changeset
1491 behind. A prefix argument acts as a repeat count. With a negative
Dave Love <fx@gnu.org>
parents:
diff changeset
1492 argument, move backward.
Dave Love <fx@gnu.org>
parents:
diff changeset
1493
Dave Love <fx@gnu.org>
parents:
diff changeset
1494 @item M-a
Dave Love <fx@gnu.org>
parents:
diff changeset
1495 @kindex ESC a
Dave Love <fx@gnu.org>
parents:
diff changeset
1496 @findex c-beginning-of-statement
Dave Love <fx@gnu.org>
parents:
diff changeset
1497 Move point to the beginning of the innermost C statement
Dave Love <fx@gnu.org>
parents:
diff changeset
1498 (@code{c-beginning-of-statement}). If point is already at the beginning
Dave Love <fx@gnu.org>
parents:
diff changeset
1499 of a statement, move to the beginning of the preceding statement. With
Dave Love <fx@gnu.org>
parents:
diff changeset
1500 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
Dave Love <fx@gnu.org>
parents:
diff changeset
1501
Dave Love <fx@gnu.org>
parents:
diff changeset
1502 If point is within a string or comment, or next to a comment (only
Dave Love <fx@gnu.org>
parents:
diff changeset
1503 whitespace between them), this command moves by sentences instead of
Dave Love <fx@gnu.org>
parents:
diff changeset
1504 statements.
Dave Love <fx@gnu.org>
parents:
diff changeset
1505
Dave Love <fx@gnu.org>
parents:
diff changeset
1506 When called from a program, this function takes three optional
Dave Love <fx@gnu.org>
parents:
diff changeset
1507 arguments: the numeric prefix argument, a buffer position limit
Dave Love <fx@gnu.org>
parents:
diff changeset
1508 (don't move back before that place), and a flag that controls whether
Dave Love <fx@gnu.org>
parents:
diff changeset
1509 to do sentence motion when inside of a comment.
Dave Love <fx@gnu.org>
parents:
diff changeset
1510
Dave Love <fx@gnu.org>
parents:
diff changeset
1511 @item M-e
Dave Love <fx@gnu.org>
parents:
diff changeset
1512 @kindex ESC e
Dave Love <fx@gnu.org>
parents:
diff changeset
1513 @findex c-end-of-statement
Dave Love <fx@gnu.org>
parents:
diff changeset
1514 Move point to the end of the innermost C statement; like @kbd{M-a}
Dave Love <fx@gnu.org>
parents:
diff changeset
1515 except that it moves in the other direction (@code{c-end-of-statement}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1516
Dave Love <fx@gnu.org>
parents:
diff changeset
1517 @item M-x c-backward-into-nomenclature
Dave Love <fx@gnu.org>
parents:
diff changeset
1518 @findex c-backward-into-nomenclature
Dave Love <fx@gnu.org>
parents:
diff changeset
1519 Move point backward to beginning of a C++ nomenclature section or word.
Dave Love <fx@gnu.org>
parents:
diff changeset
1520 With prefix argument @var{n}, move @var{n} times. If @var{n} is
Dave Love <fx@gnu.org>
parents:
diff changeset
1521 negative, move forward. C++ nomenclature means a symbol name in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1522 style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
Dave Love <fx@gnu.org>
parents:
diff changeset
1523 begins a section or word.
Dave Love <fx@gnu.org>
parents:
diff changeset
1524
Dave Love <fx@gnu.org>
parents:
diff changeset
1525 In the GNU project, we recommend using underscores to separate words
Dave Love <fx@gnu.org>
parents:
diff changeset
1526 within an identifier in C or C++, rather than using case distinctions.
Dave Love <fx@gnu.org>
parents:
diff changeset
1527
Dave Love <fx@gnu.org>
parents:
diff changeset
1528 @item M-x c-forward-into-nomenclature
Dave Love <fx@gnu.org>
parents:
diff changeset
1529 @findex c-forward-into-nomenclature
Dave Love <fx@gnu.org>
parents:
diff changeset
1530 Move point forward to end of a C++ nomenclature section or word.
Dave Love <fx@gnu.org>
parents:
diff changeset
1531 With prefix argument @var{n}, move @var{n} times.
Dave Love <fx@gnu.org>
parents:
diff changeset
1532 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1533
Dave Love <fx@gnu.org>
parents:
diff changeset
1534 @node Electric C
Dave Love <fx@gnu.org>
parents:
diff changeset
1535 @subsection Electric C Characters
Dave Love <fx@gnu.org>
parents:
diff changeset
1536
Dave Love <fx@gnu.org>
parents:
diff changeset
1537 In C mode and related modes, certain printing characters are
Dave Love <fx@gnu.org>
parents:
diff changeset
1538 ``electric''---in addition to inserting themselves, they also reindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1539 the current line and may insert newlines. This feature is controlled by
Dave Love <fx@gnu.org>
parents:
diff changeset
1540 the variable @code{c-auto-newline}. The ``electric'' characters are
Dave Love <fx@gnu.org>
parents:
diff changeset
1541 @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<},
Dave Love <fx@gnu.org>
parents:
diff changeset
1542 @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1543
Dave Love <fx@gnu.org>
parents:
diff changeset
1544 Electric characters insert newlines only when the @dfn{auto-newline}
Dave Love <fx@gnu.org>
parents:
diff changeset
1545 feature is enabled (indicated by @samp{/a} in the mode line after the
Dave Love <fx@gnu.org>
parents:
diff changeset
1546 mode name). This feature is controlled by the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1547 @code{c-auto-newline}. You can turn this feature on or off with the
Dave Love <fx@gnu.org>
parents:
diff changeset
1548 command @kbd{C-c C-a}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1549
Dave Love <fx@gnu.org>
parents:
diff changeset
1550 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1551 @item C-c C-a
Dave Love <fx@gnu.org>
parents:
diff changeset
1552 @kindex C-c C-a @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1553 @findex c-toggle-auto-state
Dave Love <fx@gnu.org>
parents:
diff changeset
1554 Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a
Dave Love <fx@gnu.org>
parents:
diff changeset
1555 prefix argument, this command turns the auto-newline feature on if the
Dave Love <fx@gnu.org>
parents:
diff changeset
1556 argument is positive, and off if it is negative.
Dave Love <fx@gnu.org>
parents:
diff changeset
1557 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1558
Dave Love <fx@gnu.org>
parents:
diff changeset
1559 The colon character is electric because that is appropriate for a
Dave Love <fx@gnu.org>
parents:
diff changeset
1560 single colon. But when you want to insert a double colon in C++, the
Dave Love <fx@gnu.org>
parents:
diff changeset
1561 electric behavior of colon is inconvenient. You can insert a double
Dave Love <fx@gnu.org>
parents:
diff changeset
1562 colon with no reindentation or newlines by typing @kbd{C-c :}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1563
Dave Love <fx@gnu.org>
parents:
diff changeset
1564 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1565 @item C-c :
44088
d22891dea363 (Electric C Characters, Evaluating Emacs-Lisp Expressions): Use <colon>
Eli Zaretskii <eliz@gnu.org>
parents: 43889
diff changeset
1566 @ifinfo
43889
c5ea7e769ffd (Electric C, Lisp Eval): Avoid makeinfo warnings about colons in indices.
Eli Zaretskii <eliz@gnu.org>
parents: 42675
diff changeset
1567 @c This uses ``colon'' instead of a literal `:' because Info cannot
c5ea7e769ffd (Electric C, Lisp Eval): Avoid makeinfo warnings about colons in indices.
Eli Zaretskii <eliz@gnu.org>
parents: 42675
diff changeset
1568 @c cope with a `:' in a menu
c5ea7e769ffd (Electric C, Lisp Eval): Avoid makeinfo warnings about colons in indices.
Eli Zaretskii <eliz@gnu.org>
parents: 42675
diff changeset
1569 @kindex C-c @key{colon} @r{(C mode)}
44088
d22891dea363 (Electric C Characters, Evaluating Emacs-Lisp Expressions): Use <colon>
Eli Zaretskii <eliz@gnu.org>
parents: 43889
diff changeset
1570 @end ifinfo
d22891dea363 (Electric C Characters, Evaluating Emacs-Lisp Expressions): Use <colon>
Eli Zaretskii <eliz@gnu.org>
parents: 43889
diff changeset
1571 @ifnotinfo
d22891dea363 (Electric C Characters, Evaluating Emacs-Lisp Expressions): Use <colon>
Eli Zaretskii <eliz@gnu.org>
parents: 43889
diff changeset
1572 @kindex C-c : @r{(C mode)}
d22891dea363 (Electric C Characters, Evaluating Emacs-Lisp Expressions): Use <colon>
Eli Zaretskii <eliz@gnu.org>
parents: 43889
diff changeset
1573 @end ifnotinfo
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1574 @findex c-scope-operator
Dave Love <fx@gnu.org>
parents:
diff changeset
1575 Insert a double colon scope operator at point, without reindenting the
Dave Love <fx@gnu.org>
parents:
diff changeset
1576 line or adding any newlines (@code{c-scope-operator}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1577 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1578
Dave Love <fx@gnu.org>
parents:
diff changeset
1579 The electric @kbd{#} key reindents the line if it appears to be the
Dave Love <fx@gnu.org>
parents:
diff changeset
1580 beginning of a preprocessor directive. This happens when the value of
Dave Love <fx@gnu.org>
parents:
diff changeset
1581 @code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn
Dave Love <fx@gnu.org>
parents:
diff changeset
1582 this feature off by setting @code{c-electric-pound-behavior} to
Dave Love <fx@gnu.org>
parents:
diff changeset
1583 @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1584
Dave Love <fx@gnu.org>
parents:
diff changeset
1585 The variable @code{c-hanging-braces-alist} controls the insertion of
Dave Love <fx@gnu.org>
parents:
diff changeset
1586 newlines before and after inserted braces. It is an association list
Dave Love <fx@gnu.org>
parents:
diff changeset
1587 with elements of the following form: @code{(@var{syntactic-symbol}
Dave Love <fx@gnu.org>
parents:
diff changeset
1588 . @var{nl-list})}. Most of the syntactic symbols that appear in
Dave Love <fx@gnu.org>
parents:
diff changeset
1589 @code{c-offsets-alist} are meaningful here as well.
Dave Love <fx@gnu.org>
parents:
diff changeset
1590
Dave Love <fx@gnu.org>
parents:
diff changeset
1591 The list @var{nl-list} may contain either of the symbols
Dave Love <fx@gnu.org>
parents:
diff changeset
1592 @code{before} or @code{after}, or both; or it may be @code{nil}. When a
Dave Love <fx@gnu.org>
parents:
diff changeset
1593 brace is inserted, the syntactic context it defines is looked up in
Dave Love <fx@gnu.org>
parents:
diff changeset
1594 @code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used
Dave Love <fx@gnu.org>
parents:
diff changeset
1595 to determine where newlines are inserted: either before the brace,
Dave Love <fx@gnu.org>
parents:
diff changeset
1596 after, or both. If not found, the default is to insert a newline both
Dave Love <fx@gnu.org>
parents:
diff changeset
1597 before and after braces.
Dave Love <fx@gnu.org>
parents:
diff changeset
1598
Dave Love <fx@gnu.org>
parents:
diff changeset
1599 The variable @code{c-hanging-colons-alist} controls the insertion of
Dave Love <fx@gnu.org>
parents:
diff changeset
1600 newlines before and after inserted colons. It is an association list
Dave Love <fx@gnu.org>
parents:
diff changeset
1601 with elements of the following form: @code{(@var{syntactic-symbol}
Dave Love <fx@gnu.org>
parents:
diff changeset
1602 . @var{nl-list})}. The list @var{nl-list} may contain either of the
Dave Love <fx@gnu.org>
parents:
diff changeset
1603 symbols @code{before} or @code{after}, or both; or it may be @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1604
Dave Love <fx@gnu.org>
parents:
diff changeset
1605 When a colon is inserted, the syntactic symbol it defines is looked
Dave Love <fx@gnu.org>
parents:
diff changeset
1606 up in this list, and if found, the @var{nl-list} is used to determine
Dave Love <fx@gnu.org>
parents:
diff changeset
1607 where newlines are inserted: either before the brace, after, or both.
Dave Love <fx@gnu.org>
parents:
diff changeset
1608 If the syntactic symbol is not found in this list, no newlines are
Dave Love <fx@gnu.org>
parents:
diff changeset
1609 inserted.
Dave Love <fx@gnu.org>
parents:
diff changeset
1610
Dave Love <fx@gnu.org>
parents:
diff changeset
1611 Electric characters can also delete newlines automatically when the
Dave Love <fx@gnu.org>
parents:
diff changeset
1612 auto-newline feature is enabled. This feature makes auto-newline more
Dave Love <fx@gnu.org>
parents:
diff changeset
1613 acceptable, by deleting the newlines in the most common cases where you
Dave Love <fx@gnu.org>
parents:
diff changeset
1614 do not want them. Emacs can recognize several cases in which deleting a
Dave Love <fx@gnu.org>
parents:
diff changeset
1615 newline might be desirable; by setting the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1616 @code{c-cleanup-list}, you can specify @emph{which} of these cases that
Dave Love <fx@gnu.org>
parents:
diff changeset
1617 should happen. The variable's value is a list of symbols, each
Dave Love <fx@gnu.org>
parents:
diff changeset
1618 describing one case for possible deletion of a newline. Here are the
Dave Love <fx@gnu.org>
parents:
diff changeset
1619 meaningful symbols, and their meanings:
Dave Love <fx@gnu.org>
parents:
diff changeset
1620
Dave Love <fx@gnu.org>
parents:
diff changeset
1621 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1622 @item brace-catch-brace
Dave Love <fx@gnu.org>
parents:
diff changeset
1623 Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the
Dave Love <fx@gnu.org>
parents:
diff changeset
1624 entire construct on a single line. The clean-up occurs when you type
Dave Love <fx@gnu.org>
parents:
diff changeset
1625 the @samp{@{}, if there is nothing between the braces aside from
Dave Love <fx@gnu.org>
parents:
diff changeset
1626 @code{catch} and @var{condition}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1627
Dave Love <fx@gnu.org>
parents:
diff changeset
1628 @item brace-else-brace
Dave Love <fx@gnu.org>
parents:
diff changeset
1629 Clean up @samp{@} else @{} constructs by placing the entire construct on
Dave Love <fx@gnu.org>
parents:
diff changeset
1630 a single line. The clean-up occurs when you type the @samp{@{} after
Dave Love <fx@gnu.org>
parents:
diff changeset
1631 the @code{else}, but only if there is nothing but white space between
Dave Love <fx@gnu.org>
parents:
diff changeset
1632 the braces and the @code{else}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1633
Dave Love <fx@gnu.org>
parents:
diff changeset
1634 @item brace-elseif-brace
Dave Love <fx@gnu.org>
parents:
diff changeset
1635 Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire
Dave Love <fx@gnu.org>
parents:
diff changeset
1636 construct on a single line. The clean-up occurs when you type the
Dave Love <fx@gnu.org>
parents:
diff changeset
1637 @samp{@{}, if there is nothing but white space between the @samp{@}} and
Dave Love <fx@gnu.org>
parents:
diff changeset
1638 @samp{@{} aside from the keywords and the @code{if}-condition.
Dave Love <fx@gnu.org>
parents:
diff changeset
1639
Dave Love <fx@gnu.org>
parents:
diff changeset
1640 @item empty-defun-braces
Dave Love <fx@gnu.org>
parents:
diff changeset
1641 Clean up empty defun braces by placing the braces on the same
Dave Love <fx@gnu.org>
parents:
diff changeset
1642 line. Clean-up occurs when you type the closing brace.
Dave Love <fx@gnu.org>
parents:
diff changeset
1643
Dave Love <fx@gnu.org>
parents:
diff changeset
1644 @item defun-close-semi
Dave Love <fx@gnu.org>
parents:
diff changeset
1645 Clean up the semicolon after a @code{struct} or similar type
Dave Love <fx@gnu.org>
parents:
diff changeset
1646 declaration, by placing the semicolon on the same line as the closing
Dave Love <fx@gnu.org>
parents:
diff changeset
1647 brace. Clean-up occurs when you type the semicolon.
Dave Love <fx@gnu.org>
parents:
diff changeset
1648
Dave Love <fx@gnu.org>
parents:
diff changeset
1649 @item list-close-comma
Dave Love <fx@gnu.org>
parents:
diff changeset
1650 Clean up commas following braces in array and aggregate
Dave Love <fx@gnu.org>
parents:
diff changeset
1651 initializers. Clean-up occurs when you type the comma.
Dave Love <fx@gnu.org>
parents:
diff changeset
1652
Dave Love <fx@gnu.org>
parents:
diff changeset
1653 @item scope-operator
Dave Love <fx@gnu.org>
parents:
diff changeset
1654 Clean up double colons which may designate a C++ scope operator, by
Dave Love <fx@gnu.org>
parents:
diff changeset
1655 placing the colons together. Clean-up occurs when you type the second
Dave Love <fx@gnu.org>
parents:
diff changeset
1656 colon, but only when the two colons are separated by nothing but
Dave Love <fx@gnu.org>
parents:
diff changeset
1657 whitespace.
Dave Love <fx@gnu.org>
parents:
diff changeset
1658 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1659
Dave Love <fx@gnu.org>
parents:
diff changeset
1660 @node Hungry Delete
Dave Love <fx@gnu.org>
parents:
diff changeset
1661 @subsection Hungry Delete Feature in C
Dave Love <fx@gnu.org>
parents:
diff changeset
1662
Dave Love <fx@gnu.org>
parents:
diff changeset
1663 When the @dfn{hungry-delete} feature is enabled (indicated by
Dave Love <fx@gnu.org>
parents:
diff changeset
1664 @samp{/h} or @samp{/ah} in the mode line after the mode name), a single
Dave Love <fx@gnu.org>
parents:
diff changeset
1665 @key{DEL} command deletes all preceding whitespace, not just one space.
Dave Love <fx@gnu.org>
parents:
diff changeset
1666 To turn this feature on or off, use @kbd{C-c C-d}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1667
Dave Love <fx@gnu.org>
parents:
diff changeset
1668 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1669 @item C-c C-d
Dave Love <fx@gnu.org>
parents:
diff changeset
1670 @kindex C-c C-d @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1671 @findex c-toggle-hungry-state
Dave Love <fx@gnu.org>
parents:
diff changeset
1672 Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a
Dave Love <fx@gnu.org>
parents:
diff changeset
1673 prefix argument, this command turns the hungry-delete feature on if the
Dave Love <fx@gnu.org>
parents:
diff changeset
1674 argument is positive, and off if it is negative.
Dave Love <fx@gnu.org>
parents:
diff changeset
1675
Dave Love <fx@gnu.org>
parents:
diff changeset
1676 @item C-c C-t
Dave Love <fx@gnu.org>
parents:
diff changeset
1677 @kindex C-c C-t @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1678 @findex c-toggle-auto-hungry-state
Dave Love <fx@gnu.org>
parents:
diff changeset
1679 Toggle the auto-newline and hungry-delete features, both at once
Dave Love <fx@gnu.org>
parents:
diff changeset
1680 (@code{c-toggle-auto-hungry-state}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1681 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1682
Dave Love <fx@gnu.org>
parents:
diff changeset
1683 @vindex c-hungry-delete-key
Dave Love <fx@gnu.org>
parents:
diff changeset
1684 The variable @code{c-hungry-delete-key} controls whether the
Dave Love <fx@gnu.org>
parents:
diff changeset
1685 hungry-delete feature is enabled.
Dave Love <fx@gnu.org>
parents:
diff changeset
1686
Dave Love <fx@gnu.org>
parents:
diff changeset
1687 @node Other C Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1688 @subsection Other Commands for C Mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1689
Dave Love <fx@gnu.org>
parents:
diff changeset
1690 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1691 @item C-M-h
Dave Love <fx@gnu.org>
parents:
diff changeset
1692 Put mark at the end of a function definition, and put point at the
Dave Love <fx@gnu.org>
parents:
diff changeset
1693 beginning (@code{c-mark-function}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1694
Dave Love <fx@gnu.org>
parents:
diff changeset
1695 @item M-q
Dave Love <fx@gnu.org>
parents:
diff changeset
1696 @kindex M-q @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1697 @findex c-fill-paragraph
Dave Love <fx@gnu.org>
parents:
diff changeset
1698 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1699 If any part of the current line is a comment or within a comment, this
Dave Love <fx@gnu.org>
parents:
diff changeset
1700 command fills the comment or the paragraph of it that point is in,
Dave Love <fx@gnu.org>
parents:
diff changeset
1701 preserving the comment indentation and comment delimiters.
Dave Love <fx@gnu.org>
parents:
diff changeset
1702
Dave Love <fx@gnu.org>
parents:
diff changeset
1703 @item C-c C-e
Dave Love <fx@gnu.org>
parents:
diff changeset
1704 @cindex macro expansion in C
Dave Love <fx@gnu.org>
parents:
diff changeset
1705 @cindex expansion of C macros
Dave Love <fx@gnu.org>
parents:
diff changeset
1706 @findex c-macro-expand
Dave Love <fx@gnu.org>
parents:
diff changeset
1707 @kindex C-c C-e @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1708 Run the C preprocessor on the text in the region, and show the result,
Dave Love <fx@gnu.org>
parents:
diff changeset
1709 which includes the expansion of all the macro calls
Dave Love <fx@gnu.org>
parents:
diff changeset
1710 (@code{c-macro-expand}). The buffer text before the region is also
Dave Love <fx@gnu.org>
parents:
diff changeset
1711 included in preprocessing, for the sake of macros defined there, but the
Dave Love <fx@gnu.org>
parents:
diff changeset
1712 output from this part isn't shown.
Dave Love <fx@gnu.org>
parents:
diff changeset
1713
Dave Love <fx@gnu.org>
parents:
diff changeset
1714 When you are debugging C code that uses macros, sometimes it is hard to
Dave Love <fx@gnu.org>
parents:
diff changeset
1715 figure out precisely how the macros expand. With this command, you
Dave Love <fx@gnu.org>
parents:
diff changeset
1716 don't have to figure it out; you can see the expansions.
Dave Love <fx@gnu.org>
parents:
diff changeset
1717
Dave Love <fx@gnu.org>
parents:
diff changeset
1718 @item C-c C-\
Dave Love <fx@gnu.org>
parents:
diff changeset
1719 @findex c-backslash-region
Dave Love <fx@gnu.org>
parents:
diff changeset
1720 @kindex C-c C-\ @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1721 Insert or align @samp{\} characters at the ends of the lines of the
Dave Love <fx@gnu.org>
parents:
diff changeset
1722 region (@code{c-backslash-region}). This is useful after writing or
Dave Love <fx@gnu.org>
parents:
diff changeset
1723 editing a C macro definition.
Dave Love <fx@gnu.org>
parents:
diff changeset
1724
Dave Love <fx@gnu.org>
parents:
diff changeset
1725 If a line already ends in @samp{\}, this command adjusts the amount of
Dave Love <fx@gnu.org>
parents:
diff changeset
1726 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
Dave Love <fx@gnu.org>
parents:
diff changeset
1727 the last line in the region is treated specially; no @samp{\} is
Dave Love <fx@gnu.org>
parents:
diff changeset
1728 inserted on that line, and any @samp{\} there is deleted.
Dave Love <fx@gnu.org>
parents:
diff changeset
1729
Dave Love <fx@gnu.org>
parents:
diff changeset
1730 @item M-x cpp-highlight-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1731 @cindex preprocessor highlighting
Dave Love <fx@gnu.org>
parents:
diff changeset
1732 @findex cpp-highlight-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1733 Highlight parts of the text according to its preprocessor conditionals.
Dave Love <fx@gnu.org>
parents:
diff changeset
1734 This command displays another buffer named @samp{*CPP Edit*}, which
Dave Love <fx@gnu.org>
parents:
diff changeset
1735 serves as a graphic menu for selecting how to display particular kinds
Dave Love <fx@gnu.org>
parents:
diff changeset
1736 of conditionals and their contents. After changing various settings,
Dave Love <fx@gnu.org>
parents:
diff changeset
1737 click on @samp{[A]pply these settings} (or go to that buffer and type
Dave Love <fx@gnu.org>
parents:
diff changeset
1738 @kbd{a}) to rehighlight the C mode buffer accordingly.
Dave Love <fx@gnu.org>
parents:
diff changeset
1739
Dave Love <fx@gnu.org>
parents:
diff changeset
1740 @item C-c C-s
Dave Love <fx@gnu.org>
parents:
diff changeset
1741 @findex c-show-syntactic-information
Dave Love <fx@gnu.org>
parents:
diff changeset
1742 @kindex C-c C-s @r{(C mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1743 Display the syntactic information about the current source line
Dave Love <fx@gnu.org>
parents:
diff changeset
1744 (@code{c-show-syntactic-information}). This is the information that
Dave Love <fx@gnu.org>
parents:
diff changeset
1745 directs how the line is indented.
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1746
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1747 @item M-x cwarn-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1748 @itemx M-x global-cwarn-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1749 @findex cwarn-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1750 @findex global-cwarn-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1751 @cindex CWarn mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1752 @cindex suspicious constructions in C, C++
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1753 CWarn minor mode highlights certain suspicious C and C++ constructions:
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1754
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1755 @itemize @bullet{}
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1756 @item
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1757 Assignments inside expressions.
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1758 @item
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1759 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1760 (except after a @samp{do @dots{} while} statement);
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1761 @item
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1762 C++ functions with reference parameters.
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1763 @end itemize
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1764
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1765 @noindent
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1766 You can enable the mode for one buffer with the command @kbd{M-x
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1767 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1768 global-cwarn-mode} or by customizing the variable
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1769 @code{global-cwarn-mode}. You must also enable Font Lock mode to make
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1770 it work.
30810
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1771
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1772 @item M-x hide-ifdef-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1773 @findex hide-ifdef-mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1774 @cindex Hide-ifdef mode
6c6b0162bae2 Tidy up previous additions. List more languages. Glasses mode.
Dave Love <fx@gnu.org>
parents: 30793
diff changeset
1775 Hide-ifdef minor mode hides selected code within @samp{#if} and
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1776 @samp{#ifdef} preprocessor blocks. See the documentation string of
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1777 @code{hide-ifdef-mode} for more information.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1778
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1779 @item M-x ff-find-related-file
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1780 @cindex related files
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1781 @findex ff-find-related-file
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1782 @vindex ff-related-file-alist
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1783 Find a file ``related'' in a special way to the file visited by the
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1784 current buffer. Typically this will be the header file corresponding
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1785 to a C/C++ source file, or vice versa. The variable
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1786 @code{ff-related-file-alist} specifies how to compute related file
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1787 names.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1788 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1789
Dave Love <fx@gnu.org>
parents:
diff changeset
1790 @node Comments in C
Dave Love <fx@gnu.org>
parents:
diff changeset
1791 @subsection Comments in C Modes
Dave Love <fx@gnu.org>
parents:
diff changeset
1792
Dave Love <fx@gnu.org>
parents:
diff changeset
1793 C mode and related modes use a number of variables for controlling
Dave Love <fx@gnu.org>
parents:
diff changeset
1794 comment format.
Dave Love <fx@gnu.org>
parents:
diff changeset
1795
Dave Love <fx@gnu.org>
parents:
diff changeset
1796 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1797 @item c-comment-only-line-offset
Dave Love <fx@gnu.org>
parents:
diff changeset
1798 @vindex c-comment-only-line-offset
Dave Love <fx@gnu.org>
parents:
diff changeset
1799 Extra offset for line which contains only the start of a comment. It
Dave Love <fx@gnu.org>
parents:
diff changeset
1800 can be either an integer or a cons cell of the form
Dave Love <fx@gnu.org>
parents:
diff changeset
1801 @code{(@var{non-anchored-offset} . @var{anchored-offset})}, where
Dave Love <fx@gnu.org>
parents:
diff changeset
1802 @var{non-anchored-offset} is the amount of offset given to
Dave Love <fx@gnu.org>
parents:
diff changeset
1803 non-column-zero anchored comment-only lines, and @var{anchored-offset}
Dave Love <fx@gnu.org>
parents:
diff changeset
1804 is the amount of offset to give column-zero anchored comment-only lines.
Dave Love <fx@gnu.org>
parents:
diff changeset
1805 Just an integer as value is equivalent to @code{(@var{val} . 0)}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1806
Dave Love <fx@gnu.org>
parents:
diff changeset
1807 @item c-comment-start-regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
1808 @vindex c-comment-start-regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
1809 This buffer-local variable specifies how to recognize the start of a comment.
Dave Love <fx@gnu.org>
parents:
diff changeset
1810
Dave Love <fx@gnu.org>
parents:
diff changeset
1811 @item c-hanging-comment-ender-p
Dave Love <fx@gnu.org>
parents:
diff changeset
1812 @vindex c-hanging-comment-ender-p
Dave Love <fx@gnu.org>
parents:
diff changeset
1813 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
Dave Love <fx@gnu.org>
parents:
diff changeset
1814 comment terminator of a block comment on a line by itself. The default
Dave Love <fx@gnu.org>
parents:
diff changeset
1815 value is @code{t}, which puts the comment-end delimiter @samp{*/} at the
Dave Love <fx@gnu.org>
parents:
diff changeset
1816 end of the last line of the comment text.
Dave Love <fx@gnu.org>
parents:
diff changeset
1817
Dave Love <fx@gnu.org>
parents:
diff changeset
1818 @item c-hanging-comment-starter-p
Dave Love <fx@gnu.org>
parents:
diff changeset
1819 @vindex c-hanging-comment-starter-p
Dave Love <fx@gnu.org>
parents:
diff changeset
1820 If this variable is @code{nil}, @code{c-fill-paragraph} leaves the
Dave Love <fx@gnu.org>
parents:
diff changeset
1821 starting delimiter of a block comment on a line by itself. The default
Dave Love <fx@gnu.org>
parents:
diff changeset
1822 value is @code{t}, which puts the comment-start delimiter @samp{/*} at
Dave Love <fx@gnu.org>
parents:
diff changeset
1823 the beginning of the first line of the comment text.
Dave Love <fx@gnu.org>
parents:
diff changeset
1824 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1825
Dave Love <fx@gnu.org>
parents:
diff changeset
1826 @node Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
1827 @section Fortran Mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1828 @cindex Fortran mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1829 @cindex mode, Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
1830
Dave Love <fx@gnu.org>
parents:
diff changeset
1831 Fortran mode provides special motion commands for Fortran statements and
Dave Love <fx@gnu.org>
parents:
diff changeset
1832 subprograms, and indentation commands that understand Fortran conventions
Dave Love <fx@gnu.org>
parents:
diff changeset
1833 of nesting, line numbers and continuation statements. Fortran mode has
Dave Love <fx@gnu.org>
parents:
diff changeset
1834 its own Auto Fill mode that breaks long lines into proper Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
1835 continuation lines.
Dave Love <fx@gnu.org>
parents:
diff changeset
1836
Dave Love <fx@gnu.org>
parents:
diff changeset
1837 Special commands for comments are provided because Fortran comments
Dave Love <fx@gnu.org>
parents:
diff changeset
1838 are unlike those of other languages. Built-in abbrevs optionally save
Dave Love <fx@gnu.org>
parents:
diff changeset
1839 typing when you insert Fortran keywords.
Dave Love <fx@gnu.org>
parents:
diff changeset
1840
Dave Love <fx@gnu.org>
parents:
diff changeset
1841 Use @kbd{M-x fortran-mode} to switch to this major mode. This command
Dave Love <fx@gnu.org>
parents:
diff changeset
1842 runs the hook @code{fortran-mode-hook} (@pxref{Hooks}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1843
36263
11db0318031d Remove redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents: 36198
diff changeset
1844 @cindex Fortran77 and Fortran90
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1845 @findex f90-mode
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1846 @findex fortran-mode
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1847 Fortan mode is meant for editing Fortran77 ``fixed format'' source
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1848 code. For editing the modern Fortran90 ``free format'' source code,
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1849 use F90 mode (@code{f90-mode}). Emacs normally uses Fortran mode for
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1850 files with extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1851 for the extension @samp{.f90}. GNU Fortran supports both kinds of
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1852 format.
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1853
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1854 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1855 * Motion: Fortran Motion. Moving point by statements or subprograms.
Dave Love <fx@gnu.org>
parents:
diff changeset
1856 * Indent: Fortran Indent. Indentation commands for Fortran.
Dave Love <fx@gnu.org>
parents:
diff changeset
1857 * Comments: Fortran Comments. Inserting and aligning comments.
Dave Love <fx@gnu.org>
parents:
diff changeset
1858 * Autofill: Fortran Autofill. Auto fill minor mode for Fortran.
Dave Love <fx@gnu.org>
parents:
diff changeset
1859 * Columns: Fortran Columns. Measuring columns for valid Fortran.
Dave Love <fx@gnu.org>
parents:
diff changeset
1860 * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.
Dave Love <fx@gnu.org>
parents:
diff changeset
1861 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1862
Dave Love <fx@gnu.org>
parents:
diff changeset
1863 @node Fortran Motion
Dave Love <fx@gnu.org>
parents:
diff changeset
1864 @subsection Motion Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1865
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1866 In addition to the normal commands for moving by and operating on
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1867 ``defuns'' (Fortran subprograms---functions and subroutines), Fortran
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1868 mode provides special commands to move by statements.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1869
Dave Love <fx@gnu.org>
parents:
diff changeset
1870 @table @kbd
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1871 @kindex C-c C-n @r{(Fortran mode)}
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1872 @findex fortran-next-statement
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1873 @item C-c C-n
Dave Love <fx@gnu.org>
parents:
diff changeset
1874 Move to beginning of current or next statement
Dave Love <fx@gnu.org>
parents:
diff changeset
1875 (@code{fortran-next-statement}).
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1876
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1877 @kindex C-c C-p @r{(Fortran mode)}
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1878 @findex fortran-previous-statement
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1879 @item C-c C-p
Dave Love <fx@gnu.org>
parents:
diff changeset
1880 Move to beginning of current or previous statement
Dave Love <fx@gnu.org>
parents:
diff changeset
1881 (@code{fortran-previous-statement}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1882 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1883
Dave Love <fx@gnu.org>
parents:
diff changeset
1884 @node Fortran Indent
Dave Love <fx@gnu.org>
parents:
diff changeset
1885 @subsection Fortran Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
1886
Dave Love <fx@gnu.org>
parents:
diff changeset
1887 Special commands and features are needed for indenting Fortran code in
Dave Love <fx@gnu.org>
parents:
diff changeset
1888 order to make sure various syntactic entities (line numbers, comment line
Dave Love <fx@gnu.org>
parents:
diff changeset
1889 indicators and continuation line flags) appear in the columns that are
Dave Love <fx@gnu.org>
parents:
diff changeset
1890 required for standard Fortran.
Dave Love <fx@gnu.org>
parents:
diff changeset
1891
Dave Love <fx@gnu.org>
parents:
diff changeset
1892 @menu
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1893 * Commands: ForIndent Commands. Commands for indenting and filling Fortran.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1894 * Contline: ForIndent Cont. How continuation lines indent.
Dave Love <fx@gnu.org>
parents:
diff changeset
1895 * Numbers: ForIndent Num. How line numbers auto-indent.
Dave Love <fx@gnu.org>
parents:
diff changeset
1896 * Conv: ForIndent Conv. Conventions you must obey to avoid trouble.
Dave Love <fx@gnu.org>
parents:
diff changeset
1897 * Vars: ForIndent Vars. Variables controlling Fortran indent style.
Dave Love <fx@gnu.org>
parents:
diff changeset
1898 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1899
Dave Love <fx@gnu.org>
parents:
diff changeset
1900 @node ForIndent Commands
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1901 @subsubsection Fortran Indentation and Filling Commands
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1902
Dave Love <fx@gnu.org>
parents:
diff changeset
1903 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1904 @item C-M-j
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1905 Break the current line and set up a continuation line
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1906 (@code{fortran-split-line}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1907 @item M-^
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1908 Join this line to the previous line (@code{fortran-join-line}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1909 @item C-M-q
Dave Love <fx@gnu.org>
parents:
diff changeset
1910 Indent all the lines of the subprogram point is in
Dave Love <fx@gnu.org>
parents:
diff changeset
1911 (@code{fortran-indent-subprogram}).
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1912 @item M-q
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1913 Fill a comment block or statement.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1914 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1915
Dave Love <fx@gnu.org>
parents:
diff changeset
1916 @kindex C-M-q @r{(Fortran mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1917 @findex fortran-indent-subprogram
Dave Love <fx@gnu.org>
parents:
diff changeset
1918 The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command
Dave Love <fx@gnu.org>
parents:
diff changeset
1919 to reindent all the lines of the Fortran subprogram (function or
Dave Love <fx@gnu.org>
parents:
diff changeset
1920 subroutine) containing point.
Dave Love <fx@gnu.org>
parents:
diff changeset
1921
Dave Love <fx@gnu.org>
parents:
diff changeset
1922 @kindex C-M-j @r{(Fortran mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1923 @findex fortran-split-line
Dave Love <fx@gnu.org>
parents:
diff changeset
1924 The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits
Dave Love <fx@gnu.org>
parents:
diff changeset
1925 a line in the appropriate fashion for Fortran. In a non-comment line,
Dave Love <fx@gnu.org>
parents:
diff changeset
1926 the second half becomes a continuation line and is indented
Dave Love <fx@gnu.org>
parents:
diff changeset
1927 accordingly. In a comment line, both halves become separate comment
Dave Love <fx@gnu.org>
parents:
diff changeset
1928 lines.
Dave Love <fx@gnu.org>
parents:
diff changeset
1929
Dave Love <fx@gnu.org>
parents:
diff changeset
1930 @kindex M-^ @r{(Fortran mode)}
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1931 @kindex C-c C-d @r{(Fortran mode)}
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1932 @findex fortran-join-line
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1933 @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1934 which joins a continuation line back to the previous line, roughly as
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1935 the inverse of @code{fortran-split-line}. The point must be on a
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1936 continuation line when this command is invoked.
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
1937
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1938 @kindex M-q @r{(Fortran mode)}
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1939 @kbd{M-q} in Fortran mode fills the comment block or statement that
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
1940 point is in. This removes any excess statement continuations.
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
1941
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1942 @node ForIndent Cont
Dave Love <fx@gnu.org>
parents:
diff changeset
1943 @subsubsection Continuation Lines
Dave Love <fx@gnu.org>
parents:
diff changeset
1944 @cindex Fortran continuation lines
Dave Love <fx@gnu.org>
parents:
diff changeset
1945
Dave Love <fx@gnu.org>
parents:
diff changeset
1946 @vindex fortran-continuation-string
Dave Love <fx@gnu.org>
parents:
diff changeset
1947 Most modern Fortran compilers allow two ways of writing continuation
Dave Love <fx@gnu.org>
parents:
diff changeset
1948 lines. If the first non-space character on a line is in column 5, then
Dave Love <fx@gnu.org>
parents:
diff changeset
1949 that line is a continuation of the previous line. We call this
Dave Love <fx@gnu.org>
parents:
diff changeset
1950 @dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The
Dave Love <fx@gnu.org>
parents:
diff changeset
1951 variable @code{fortran-continuation-string} specifies what character to
Dave Love <fx@gnu.org>
parents:
diff changeset
1952 put on column 5. A line that starts with a tab character followed by
Dave Love <fx@gnu.org>
parents:
diff changeset
1953 any digit except @samp{0} is also a continuation line. We call this
Dave Love <fx@gnu.org>
parents:
diff changeset
1954 style of continuation @dfn{tab format}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1955
Dave Love <fx@gnu.org>
parents:
diff changeset
1956 @vindex indent-tabs-mode @r{(Fortran mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1957 Fortran mode can make either style of continuation line, but you
Dave Love <fx@gnu.org>
parents:
diff changeset
1958 must specify which one you prefer. The value of the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1959 @code{indent-tabs-mode} controls the choice: @code{nil} for fixed
Dave Love <fx@gnu.org>
parents:
diff changeset
1960 format, and non-@code{nil} for tab format. You can tell which style
Dave Love <fx@gnu.org>
parents:
diff changeset
1961 is presently in effect by the presence or absence of the string
Dave Love <fx@gnu.org>
parents:
diff changeset
1962 @samp{Tab} in the mode line.
Dave Love <fx@gnu.org>
parents:
diff changeset
1963
Dave Love <fx@gnu.org>
parents:
diff changeset
1964 If the text on a line starts with the conventional Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
1965 continuation marker @samp{$}, or if it begins with any non-whitespace
Dave Love <fx@gnu.org>
parents:
diff changeset
1966 character in column 5, Fortran mode treats it as a continuation line.
Dave Love <fx@gnu.org>
parents:
diff changeset
1967 When you indent a continuation line with @key{TAB}, it converts the line
Dave Love <fx@gnu.org>
parents:
diff changeset
1968 to the current continuation style. When you split a Fortran statement
Dave Love <fx@gnu.org>
parents:
diff changeset
1969 with @kbd{C-M-j}, the continuation marker on the newline is created
Dave Love <fx@gnu.org>
parents:
diff changeset
1970 according to the continuation style.
Dave Love <fx@gnu.org>
parents:
diff changeset
1971
Dave Love <fx@gnu.org>
parents:
diff changeset
1972 The setting of continuation style affects several other aspects of
Dave Love <fx@gnu.org>
parents:
diff changeset
1973 editing in Fortran mode. In fixed format mode, the minimum column
Dave Love <fx@gnu.org>
parents:
diff changeset
1974 number for the body of a statement is 6. Lines inside of Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
1975 blocks that are indented to larger column numbers always use only the
Dave Love <fx@gnu.org>
parents:
diff changeset
1976 space character for whitespace. In tab format mode, the minimum
Dave Love <fx@gnu.org>
parents:
diff changeset
1977 column number for the statement body is 8, and the whitespace before
Dave Love <fx@gnu.org>
parents:
diff changeset
1978 column 8 must always consist of one tab character.
Dave Love <fx@gnu.org>
parents:
diff changeset
1979
Dave Love <fx@gnu.org>
parents:
diff changeset
1980 @vindex fortran-tab-mode-default
Dave Love <fx@gnu.org>
parents:
diff changeset
1981 @vindex fortran-analyze-depth
Dave Love <fx@gnu.org>
parents:
diff changeset
1982 When you enter Fortran mode for an existing file, it tries to deduce the
Dave Love <fx@gnu.org>
parents:
diff changeset
1983 proper continuation style automatically from the file contents. The first
Dave Love <fx@gnu.org>
parents:
diff changeset
1984 line that begins with either a tab character or six spaces determines the
Dave Love <fx@gnu.org>
parents:
diff changeset
1985 choice. The variable @code{fortran-analyze-depth} specifies how many lines
Dave Love <fx@gnu.org>
parents:
diff changeset
1986 to consider (at the beginning of the file); if none of those lines
Dave Love <fx@gnu.org>
parents:
diff changeset
1987 indicates a style, then the variable @code{fortran-tab-mode-default}
Dave Love <fx@gnu.org>
parents:
diff changeset
1988 specifies the style. If it is @code{nil}, that specifies fixed format, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1989 non-@code{nil} specifies tab format.
Dave Love <fx@gnu.org>
parents:
diff changeset
1990
Dave Love <fx@gnu.org>
parents:
diff changeset
1991 @node ForIndent Num
Dave Love <fx@gnu.org>
parents:
diff changeset
1992 @subsubsection Line Numbers
Dave Love <fx@gnu.org>
parents:
diff changeset
1993
Dave Love <fx@gnu.org>
parents:
diff changeset
1994 If a number is the first non-whitespace in the line, Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
1995 indentation assumes it is a line number and moves it to columns 0
Dave Love <fx@gnu.org>
parents:
diff changeset
1996 through 4. (Columns always count from 0 in GNU Emacs.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1997
Dave Love <fx@gnu.org>
parents:
diff changeset
1998 @vindex fortran-line-number-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
1999 Line numbers of four digits or less are normally indented one space.
Dave Love <fx@gnu.org>
parents:
diff changeset
2000 The variable @code{fortran-line-number-indent} controls this; it
Dave Love <fx@gnu.org>
parents:
diff changeset
2001 specifies the maximum indentation a line number can have. Line numbers
Dave Love <fx@gnu.org>
parents:
diff changeset
2002 are indented to right-justify them to end in column 4 unless that would
Dave Love <fx@gnu.org>
parents:
diff changeset
2003 require more than this maximum indentation. The default value of the
Dave Love <fx@gnu.org>
parents:
diff changeset
2004 variable is 1.
Dave Love <fx@gnu.org>
parents:
diff changeset
2005
Dave Love <fx@gnu.org>
parents:
diff changeset
2006 @vindex fortran-electric-line-number
Dave Love <fx@gnu.org>
parents:
diff changeset
2007 Simply inserting a line number is enough to indent it according to
Dave Love <fx@gnu.org>
parents:
diff changeset
2008 these rules. As each digit is inserted, the indentation is recomputed.
Dave Love <fx@gnu.org>
parents:
diff changeset
2009 To turn off this feature, set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2010 @code{fortran-electric-line-number} to @code{nil}. Then inserting line
Dave Love <fx@gnu.org>
parents:
diff changeset
2011 numbers is like inserting anything else.
Dave Love <fx@gnu.org>
parents:
diff changeset
2012
Dave Love <fx@gnu.org>
parents:
diff changeset
2013 @node ForIndent Conv
Dave Love <fx@gnu.org>
parents:
diff changeset
2014 @subsubsection Syntactic Conventions
Dave Love <fx@gnu.org>
parents:
diff changeset
2015
Dave Love <fx@gnu.org>
parents:
diff changeset
2016 Fortran mode assumes that you follow certain conventions that simplify
Dave Love <fx@gnu.org>
parents:
diff changeset
2017 the task of understanding a Fortran program well enough to indent it
Dave Love <fx@gnu.org>
parents:
diff changeset
2018 properly:
Dave Love <fx@gnu.org>
parents:
diff changeset
2019
Dave Love <fx@gnu.org>
parents:
diff changeset
2020 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
2021 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2022 Two nested @samp{do} loops never share a @samp{continue} statement.
Dave Love <fx@gnu.org>
parents:
diff changeset
2023
Dave Love <fx@gnu.org>
parents:
diff changeset
2024 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
2025 Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do}
Dave Love <fx@gnu.org>
parents:
diff changeset
2026 and others are written without embedded whitespace or line breaks.
Dave Love <fx@gnu.org>
parents:
diff changeset
2027
Dave Love <fx@gnu.org>
parents:
diff changeset
2028 Fortran compilers generally ignore whitespace outside of string
Dave Love <fx@gnu.org>
parents:
diff changeset
2029 constants, but Fortran mode does not recognize these keywords if they
Dave Love <fx@gnu.org>
parents:
diff changeset
2030 are not contiguous. Constructs such as @samp{else if} or @samp{end do}
Dave Love <fx@gnu.org>
parents:
diff changeset
2031 are acceptable, but the second word should be on the same line as the
Dave Love <fx@gnu.org>
parents:
diff changeset
2032 first and not on a continuation line.
Dave Love <fx@gnu.org>
parents:
diff changeset
2033 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
2034
Dave Love <fx@gnu.org>
parents:
diff changeset
2035 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
2036 If you fail to follow these conventions, the indentation commands may
Dave Love <fx@gnu.org>
parents:
diff changeset
2037 indent some lines unaesthetically. However, a correct Fortran program
Dave Love <fx@gnu.org>
parents:
diff changeset
2038 retains its meaning when reindented even if the conventions are not
Dave Love <fx@gnu.org>
parents:
diff changeset
2039 followed.
Dave Love <fx@gnu.org>
parents:
diff changeset
2040
Dave Love <fx@gnu.org>
parents:
diff changeset
2041 @node ForIndent Vars
Dave Love <fx@gnu.org>
parents:
diff changeset
2042 @subsubsection Variables for Fortran Indentation
Dave Love <fx@gnu.org>
parents:
diff changeset
2043
Dave Love <fx@gnu.org>
parents:
diff changeset
2044 @vindex fortran-do-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2045 @vindex fortran-if-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2046 @vindex fortran-structure-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2047 @vindex fortran-continuation-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2048 @vindex fortran-check-all-num@dots{}
Dave Love <fx@gnu.org>
parents:
diff changeset
2049 @vindex fortran-minimum-statement-indent@dots{}
Dave Love <fx@gnu.org>
parents:
diff changeset
2050 Several additional variables control how Fortran indentation works:
Dave Love <fx@gnu.org>
parents:
diff changeset
2051
Dave Love <fx@gnu.org>
parents:
diff changeset
2052 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
2053 @item fortran-do-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2054 Extra indentation within each level of @samp{do} statement (default 3).
Dave Love <fx@gnu.org>
parents:
diff changeset
2055
Dave Love <fx@gnu.org>
parents:
diff changeset
2056 @item fortran-if-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2057 Extra indentation within each level of @samp{if} statement (default 3).
Dave Love <fx@gnu.org>
parents:
diff changeset
2058 This value is also used for extra indentation within each level of the
Dave Love <fx@gnu.org>
parents:
diff changeset
2059 Fortran 90 @samp{where} statement.
Dave Love <fx@gnu.org>
parents:
diff changeset
2060
Dave Love <fx@gnu.org>
parents:
diff changeset
2061 @item fortran-structure-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2062 Extra indentation within each level of @samp{structure}, @samp{union}, or
Dave Love <fx@gnu.org>
parents:
diff changeset
2063 @samp{map} statements (default 3).
Dave Love <fx@gnu.org>
parents:
diff changeset
2064
Dave Love <fx@gnu.org>
parents:
diff changeset
2065 @item fortran-continuation-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2066 Extra indentation for bodies of continuation lines (default 5).
Dave Love <fx@gnu.org>
parents:
diff changeset
2067
Dave Love <fx@gnu.org>
parents:
diff changeset
2068 @item fortran-check-all-num-for-matching-do
Dave Love <fx@gnu.org>
parents:
diff changeset
2069 If this is @code{nil}, indentation assumes that each @samp{do} statement
Dave Love <fx@gnu.org>
parents:
diff changeset
2070 ends on a @samp{continue} statement. Therefore, when computing
Dave Love <fx@gnu.org>
parents:
diff changeset
2071 indentation for a statement other than @samp{continue}, it can save time
Dave Love <fx@gnu.org>
parents:
diff changeset
2072 by not checking for a @samp{do} statement ending there. If this is
Dave Love <fx@gnu.org>
parents:
diff changeset
2073 non-@code{nil}, indenting any numbered statement must check for a
Dave Love <fx@gnu.org>
parents:
diff changeset
2074 @samp{do} that ends there. The default is @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2075
Dave Love <fx@gnu.org>
parents:
diff changeset
2076 @item fortran-blink-matching-if
Dave Love <fx@gnu.org>
parents:
diff changeset
2077 If this is @code{t}, indenting an @samp{endif} statement moves the
Dave Love <fx@gnu.org>
parents:
diff changeset
2078 cursor momentarily to the matching @samp{if} statement to show where it
Dave Love <fx@gnu.org>
parents:
diff changeset
2079 is. The default is @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2080
Dave Love <fx@gnu.org>
parents:
diff changeset
2081 @item fortran-minimum-statement-indent-fixed
Dave Love <fx@gnu.org>
parents:
diff changeset
2082 Minimum indentation for fortran statements when using fixed format
Dave Love <fx@gnu.org>
parents:
diff changeset
2083 continuation line style. Statement bodies are never indented less than
Dave Love <fx@gnu.org>
parents:
diff changeset
2084 this much. The default is 6.
Dave Love <fx@gnu.org>
parents:
diff changeset
2085
Dave Love <fx@gnu.org>
parents:
diff changeset
2086 @item fortran-minimum-statement-indent-tab
Dave Love <fx@gnu.org>
parents:
diff changeset
2087 Minimum indentation for fortran statements for tab format continuation line
Dave Love <fx@gnu.org>
parents:
diff changeset
2088 style. Statement bodies are never indented less than this much. The
Dave Love <fx@gnu.org>
parents:
diff changeset
2089 default is 8.
Dave Love <fx@gnu.org>
parents:
diff changeset
2090 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2091
Dave Love <fx@gnu.org>
parents:
diff changeset
2092 @node Fortran Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
2093 @subsection Fortran Comments
Dave Love <fx@gnu.org>
parents:
diff changeset
2094
Dave Love <fx@gnu.org>
parents:
diff changeset
2095 The usual Emacs comment commands assume that a comment can follow a line
Dave Love <fx@gnu.org>
parents:
diff changeset
2096 of code. In Fortran, the standard comment syntax requires an entire line
Dave Love <fx@gnu.org>
parents:
diff changeset
2097 to be just a comment. Therefore, Fortran mode replaces the standard Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
2098 comment commands and defines some new variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
2099
27221
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
2100 Fortran mode can also handle the Fortran90 comment syntax where comments
4a723a7bc25a Mention outline-minor-mode, check-parens,
Dave Love <fx@gnu.org>
parents: 26462
diff changeset
2101 start with @samp{!} and can follow other text. Because only some Fortran77
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2102 compilers accept this syntax, Fortran mode will not insert such comments
Dave Love <fx@gnu.org>
parents:
diff changeset
2103 unless you have said in advance to do so. To do this, set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2104 @code{comment-start} to @samp{"!"} (@pxref{Variables}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2105
Dave Love <fx@gnu.org>
parents:
diff changeset
2106 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2107 @item M-;
Dave Love <fx@gnu.org>
parents:
diff changeset
2108 Align comment or insert new comment (@code{fortran-comment-indent}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2109
Dave Love <fx@gnu.org>
parents:
diff changeset
2110 @item C-x ;
Dave Love <fx@gnu.org>
parents:
diff changeset
2111 Applies to nonstandard @samp{!} comments only.
Dave Love <fx@gnu.org>
parents:
diff changeset
2112
Dave Love <fx@gnu.org>
parents:
diff changeset
2113 @item C-c ;
Dave Love <fx@gnu.org>
parents:
diff changeset
2114 Turn all lines of the region into comments, or (with argument) turn them back
Dave Love <fx@gnu.org>
parents:
diff changeset
2115 into real code (@code{fortran-comment-region}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2116 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2117
Dave Love <fx@gnu.org>
parents:
diff changeset
2118 @kbd{M-;} in Fortran mode is redefined as the command
Dave Love <fx@gnu.org>
parents:
diff changeset
2119 @code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this
Dave Love <fx@gnu.org>
parents:
diff changeset
2120 recognizes any kind of existing comment and aligns its text appropriately;
Dave Love <fx@gnu.org>
parents:
diff changeset
2121 if there is no existing comment, a comment is inserted and aligned. But
Dave Love <fx@gnu.org>
parents:
diff changeset
2122 inserting and aligning comments are not the same in Fortran mode as in
Dave Love <fx@gnu.org>
parents:
diff changeset
2123 other modes.
Dave Love <fx@gnu.org>
parents:
diff changeset
2124
Dave Love <fx@gnu.org>
parents:
diff changeset
2125 When a new comment must be inserted, if the current line is blank, a
Dave Love <fx@gnu.org>
parents:
diff changeset
2126 full-line comment is inserted. On a non-blank line, a nonstandard @samp{!}
Dave Love <fx@gnu.org>
parents:
diff changeset
2127 comment is inserted if you have said you want to use them. Otherwise a
Dave Love <fx@gnu.org>
parents:
diff changeset
2128 full-line comment is inserted on a new line before the current line.
Dave Love <fx@gnu.org>
parents:
diff changeset
2129
Dave Love <fx@gnu.org>
parents:
diff changeset
2130 Nonstandard @samp{!} comments are aligned like comments in other
Dave Love <fx@gnu.org>
parents:
diff changeset
2131 languages, but full-line comments are different. In a standard full-line
Dave Love <fx@gnu.org>
parents:
diff changeset
2132 comment, the comment delimiter itself must always appear in column zero.
Dave Love <fx@gnu.org>
parents:
diff changeset
2133 What can be aligned is the text within the comment. You can choose from
Dave Love <fx@gnu.org>
parents:
diff changeset
2134 three styles of alignment by setting the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2135 @code{fortran-comment-indent-style} to one of these values:
Dave Love <fx@gnu.org>
parents:
diff changeset
2136
Dave Love <fx@gnu.org>
parents:
diff changeset
2137 @vindex fortran-comment-indent-style
Dave Love <fx@gnu.org>
parents:
diff changeset
2138 @vindex fortran-comment-line-extra-indent
Dave Love <fx@gnu.org>
parents:
diff changeset
2139 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
2140 @item fixed
Dave Love <fx@gnu.org>
parents:
diff changeset
2141 Align the text at a fixed column, which is the sum of
Dave Love <fx@gnu.org>
parents:
diff changeset
2142 @code{fortran-comment-line-extra-indent} and the minimum statement
Dave Love <fx@gnu.org>
parents:
diff changeset
2143 indentation. This is the default.
Dave Love <fx@gnu.org>
parents:
diff changeset
2144
Dave Love <fx@gnu.org>
parents:
diff changeset
2145 The minimum statement indentation is
Dave Love <fx@gnu.org>
parents:
diff changeset
2146 @code{fortran-minimum-statement-indent-fixed} for fixed format
Dave Love <fx@gnu.org>
parents:
diff changeset
2147 continuation line style and @code{fortran-minimum-statement-indent-tab}
Dave Love <fx@gnu.org>
parents:
diff changeset
2148 for tab format style.
Dave Love <fx@gnu.org>
parents:
diff changeset
2149
Dave Love <fx@gnu.org>
parents:
diff changeset
2150 @item relative
Dave Love <fx@gnu.org>
parents:
diff changeset
2151 Align the text as if it were a line of code, but with an additional
Dave Love <fx@gnu.org>
parents:
diff changeset
2152 @code{fortran-comment-line-extra-indent} columns of indentation.
Dave Love <fx@gnu.org>
parents:
diff changeset
2153
Dave Love <fx@gnu.org>
parents:
diff changeset
2154 @item nil
Dave Love <fx@gnu.org>
parents:
diff changeset
2155 Don't move text in full-line comments automatically at all.
Dave Love <fx@gnu.org>
parents:
diff changeset
2156 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2157
Dave Love <fx@gnu.org>
parents:
diff changeset
2158 @vindex fortran-comment-indent-char
Dave Love <fx@gnu.org>
parents:
diff changeset
2159 In addition, you can specify the character to be used to indent within
Dave Love <fx@gnu.org>
parents:
diff changeset
2160 full-line comments by setting the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2161 @code{fortran-comment-indent-char} to the single-character string you want
Dave Love <fx@gnu.org>
parents:
diff changeset
2162 to use.
Dave Love <fx@gnu.org>
parents:
diff changeset
2163
45997
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2164 @vindex fortran-directive-re
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2165 Compiler directive lines, or preprocessor lines, have much the same
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2166 appearance as comment lines. It is important, though, that such lines
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2167 never be indented at all, no matter what the value of
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2168 @code{fortran-comment-indent-style}. The variable
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2169 @code{fortran-directive-re} is a regular expression that specifies which
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2170 lines are directives. Matching lines are never indented, and receive
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2171 distinctive font-locking.
9ee4a7e22180 *** empty log message ***
Glenn Morris <rgm@gnu.org>
parents: 44088
diff changeset
2172
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2173 @vindex comment-line-start
Dave Love <fx@gnu.org>
parents:
diff changeset
2174 @vindex comment-line-start-skip
Dave Love <fx@gnu.org>
parents:
diff changeset
2175 Fortran mode introduces two variables @code{comment-line-start} and
Dave Love <fx@gnu.org>
parents:
diff changeset
2176 @code{comment-line-start-skip}, which play for full-line comments the same
Dave Love <fx@gnu.org>
parents:
diff changeset
2177 roles played by @code{comment-start} and @code{comment-start-skip} for
Dave Love <fx@gnu.org>
parents:
diff changeset
2178 ordinary text-following comments. Normally these are set properly by
Dave Love <fx@gnu.org>
parents:
diff changeset
2179 Fortran mode, so you do not need to change them.
Dave Love <fx@gnu.org>
parents:
diff changeset
2180
Dave Love <fx@gnu.org>
parents:
diff changeset
2181 The normal Emacs comment command @kbd{C-x ;} has not been redefined. If
Dave Love <fx@gnu.org>
parents:
diff changeset
2182 you use @samp{!} comments, this command can be used with them. Otherwise
Dave Love <fx@gnu.org>
parents:
diff changeset
2183 it is useless in Fortran mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
2184
Dave Love <fx@gnu.org>
parents:
diff changeset
2185 @kindex C-c ; @r{(Fortran mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
2186 @findex fortran-comment-region
Dave Love <fx@gnu.org>
parents:
diff changeset
2187 @vindex fortran-comment-region
Dave Love <fx@gnu.org>
parents:
diff changeset
2188 The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
Dave Love <fx@gnu.org>
parents:
diff changeset
2189 lines of the region into comments by inserting the string @samp{C$$$} at
Dave Love <fx@gnu.org>
parents:
diff changeset
2190 the front of each one. With a numeric argument, it turns the region
Dave Love <fx@gnu.org>
parents:
diff changeset
2191 back into live code by deleting @samp{C$$$} from the front of each line
Dave Love <fx@gnu.org>
parents:
diff changeset
2192 in it. The string used for these comments can be controlled by setting
Dave Love <fx@gnu.org>
parents:
diff changeset
2193 the variable @code{fortran-comment-region}. Note that here we have an
Dave Love <fx@gnu.org>
parents:
diff changeset
2194 example of a command and a variable with the same name; these two uses
Dave Love <fx@gnu.org>
parents:
diff changeset
2195 of the name never conflict because in Lisp and in Emacs it is always
Dave Love <fx@gnu.org>
parents:
diff changeset
2196 clear from the context which one is meant.
Dave Love <fx@gnu.org>
parents:
diff changeset
2197
Dave Love <fx@gnu.org>
parents:
diff changeset
2198 @node Fortran Autofill
Dave Love <fx@gnu.org>
parents:
diff changeset
2199 @subsection Fortran Auto Fill Mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2200
Dave Love <fx@gnu.org>
parents:
diff changeset
2201 Fortran Auto Fill mode is a minor mode which automatically splits
Dave Love <fx@gnu.org>
parents:
diff changeset
2202 Fortran statements as you insert them when they become too wide.
Dave Love <fx@gnu.org>
parents:
diff changeset
2203 Splitting a statement involves making continuation lines using
Dave Love <fx@gnu.org>
parents:
diff changeset
2204 @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This
Dave Love <fx@gnu.org>
parents:
diff changeset
2205 splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and
Dave Love <fx@gnu.org>
parents:
diff changeset
2206 also in the Fortran indentation commands.
Dave Love <fx@gnu.org>
parents:
diff changeset
2207
Dave Love <fx@gnu.org>
parents:
diff changeset
2208 @findex fortran-auto-fill-mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2209 @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it
Dave Love <fx@gnu.org>
parents:
diff changeset
2210 was off, or off if it was on. This command works the same as @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
2211 auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A
Dave Love <fx@gnu.org>
parents:
diff changeset
2212 positive numeric argument turns Fortran Auto Fill mode on, and a
Dave Love <fx@gnu.org>
parents:
diff changeset
2213 negative argument turns it off. You can see when Fortran Auto Fill mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2214 is in effect by the presence of the word @samp{Fill} in the mode line,
Dave Love <fx@gnu.org>
parents:
diff changeset
2215 inside the parentheses. Fortran Auto Fill mode is a minor mode, turned
Dave Love <fx@gnu.org>
parents:
diff changeset
2216 on or off for each buffer individually. @xref{Minor Modes}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2217
Dave Love <fx@gnu.org>
parents:
diff changeset
2218 @vindex fortran-break-before-delimiters
Dave Love <fx@gnu.org>
parents:
diff changeset
2219 Fortran Auto Fill mode breaks lines at spaces or delimiters when the
Dave Love <fx@gnu.org>
parents:
diff changeset
2220 lines get longer than the desired width (the value of @code{fill-column}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2221 The delimiters that Fortran Auto Fill mode may break at are @samp{,},
Dave Love <fx@gnu.org>
parents:
diff changeset
2222 @samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2223 The line break comes after the delimiter if the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2224 @code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by
Dave Love <fx@gnu.org>
parents:
diff changeset
2225 default), the break comes before the delimiter.
Dave Love <fx@gnu.org>
parents:
diff changeset
2226
Dave Love <fx@gnu.org>
parents:
diff changeset
2227 By default, Fortran Auto Fill mode is not enabled. If you want this
Dave Love <fx@gnu.org>
parents:
diff changeset
2228 feature turned on permanently, add a hook function to
Dave Love <fx@gnu.org>
parents:
diff changeset
2229 @code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2230 @xref{Hooks}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2231
Dave Love <fx@gnu.org>
parents:
diff changeset
2232 @node Fortran Columns
Dave Love <fx@gnu.org>
parents:
diff changeset
2233 @subsection Checking Columns in Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
2234
Dave Love <fx@gnu.org>
parents:
diff changeset
2235 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2236 @item C-c C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
2237 Display a ``column ruler'' momentarily above the current line
Dave Love <fx@gnu.org>
parents:
diff changeset
2238 (@code{fortran-column-ruler}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2239 @item C-c C-w
Dave Love <fx@gnu.org>
parents:
diff changeset
2240 Split the current window horizontally temporarily so that it is 72
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2241 columns wide (@code{fortran-window-create-momentarily}). This may
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2242 help you avoid making lines longer than the 72-character limit that
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2243 some Fortran compilers impose.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2244 @item C-u C-c C-w
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2245 Split the current window horizontally so that it is 72 columns wide
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2246 (@code{fortran-window-create}). You can then continue editing.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2247 @item M-x fortran-strip-sequence-nos
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2248 Delete all text in column 72 and beyond.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2249 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2250
Dave Love <fx@gnu.org>
parents:
diff changeset
2251 @kindex C-c C-r @r{(Fortran mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
2252 @findex fortran-column-ruler
Dave Love <fx@gnu.org>
parents:
diff changeset
2253 The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
Dave Love <fx@gnu.org>
parents:
diff changeset
2254 ruler momentarily above the current line. The comment ruler is two lines
Dave Love <fx@gnu.org>
parents:
diff changeset
2255 of text that show you the locations of columns with special significance in
Dave Love <fx@gnu.org>
parents:
diff changeset
2256 Fortran programs. Square brackets show the limits of the columns for line
Dave Love <fx@gnu.org>
parents:
diff changeset
2257 numbers, and curly brackets show the limits of the columns for the
Dave Love <fx@gnu.org>
parents:
diff changeset
2258 statement body. Column numbers appear above them.
Dave Love <fx@gnu.org>
parents:
diff changeset
2259
Dave Love <fx@gnu.org>
parents:
diff changeset
2260 Note that the column numbers count from zero, as always in GNU Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
2261 As a result, the numbers may be one less than those you are familiar
Dave Love <fx@gnu.org>
parents:
diff changeset
2262 with; but the positions they indicate in the line are standard for
Dave Love <fx@gnu.org>
parents:
diff changeset
2263 Fortran.
Dave Love <fx@gnu.org>
parents:
diff changeset
2264
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2265 @vindex fortran-column-ruler-fixed
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2266 @vindex fortran-column-ruler-tabs
26264
Francesco Potortì <pot@gnu.org>
parents: 26106
diff changeset
2267 The text used to display the column ruler depends on the value of
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2268 the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is
Dave Love <fx@gnu.org>
parents:
diff changeset
2269 @code{nil}, then the value of the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2270 @code{fortran-column-ruler-fixed} is used as the column ruler.
Dave Love <fx@gnu.org>
parents:
diff changeset
2271 Otherwise, the variable @code{fortran-column-ruler-tab} is displayed.
Dave Love <fx@gnu.org>
parents:
diff changeset
2272 By changing these variables, you can change the column ruler display.
Dave Love <fx@gnu.org>
parents:
diff changeset
2273
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2274 @kindex C-c C-w @r{(Fortran mode)}
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2275 @findex fortran-window-create-momentarily
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2276 @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2277 splits the current window horizontally, making a window 72 columns
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2278 wide, so you can see which lines that is too long. Type a space to
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2279 restore the normal width.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2280
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2281 @kindex C-u C-c C-w @r{(Fortran mode)}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2282 @findex fortran-window-create
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2283 You can also split the window horizontally and continue editing with
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2284 the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2285 fortran-window-create}). By editing in this window you can
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2286 immediately see when you make a line too wide to be correct Fortran.
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2287
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2288 @findex fortran-strip-sequence-nos
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2289 The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2290 column 72 and beyond, on all lines in the current buffer. This is the
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2291 easiest way to get rid of old sequence numbers.
26106
19c8f63a59f1 List additional modes.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2292
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2293 @node Fortran Abbrev
Dave Love <fx@gnu.org>
parents:
diff changeset
2294 @subsection Fortran Keyword Abbrevs
Dave Love <fx@gnu.org>
parents:
diff changeset
2295
Dave Love <fx@gnu.org>
parents:
diff changeset
2296 Fortran mode provides many built-in abbrevs for common keywords and
Dave Love <fx@gnu.org>
parents:
diff changeset
2297 declarations. These are the same sort of abbrev that you can define
Dave Love <fx@gnu.org>
parents:
diff changeset
2298 yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2299
Dave Love <fx@gnu.org>
parents:
diff changeset
2300 The built-in abbrevs are unusual in one way: they all start with a
Dave Love <fx@gnu.org>
parents:
diff changeset
2301 semicolon. You cannot normally use semicolon in an abbrev, but Fortran
Dave Love <fx@gnu.org>
parents:
diff changeset
2302 mode makes this possible by changing the syntax of semicolon to ``word
Dave Love <fx@gnu.org>
parents:
diff changeset
2303 constituent.''
Dave Love <fx@gnu.org>
parents:
diff changeset
2304
Dave Love <fx@gnu.org>
parents:
diff changeset
2305 For example, one built-in Fortran abbrev is @samp{;c} for
Dave Love <fx@gnu.org>
parents:
diff changeset
2306 @samp{continue}. If you insert @samp{;c} and then insert a punctuation
Dave Love <fx@gnu.org>
parents:
diff changeset
2307 character such as a space or a newline, the @samp{;c} expands automatically
Dave Love <fx@gnu.org>
parents:
diff changeset
2308 to @samp{continue}, provided Abbrev mode is enabled.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
2309
Dave Love <fx@gnu.org>
parents:
diff changeset
2310 Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
Dave Love <fx@gnu.org>
parents:
diff changeset
2311 Fortran abbrevs and what they stand for.
Dave Love <fx@gnu.org>
parents:
diff changeset
2312
Dave Love <fx@gnu.org>
parents:
diff changeset
2313 @node Asm Mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2314 @section Asm Mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2315
Dave Love <fx@gnu.org>
parents:
diff changeset
2316 @cindex Asm mode
36183
d3f65290e6b2 Clean up comment-dwim vs indent-for-comment, etc.
Richard M. Stallman <rms@gnu.org>
parents: 35477
diff changeset
2317 @cindex assembler mode
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2318 Asm mode is a major mode for editing files of assembler code. It
Dave Love <fx@gnu.org>
parents:
diff changeset
2319 defines these commands:
Dave Love <fx@gnu.org>
parents:
diff changeset
2320
Dave Love <fx@gnu.org>
parents:
diff changeset
2321 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2322 @item @key{TAB}
Dave Love <fx@gnu.org>
parents:
diff changeset
2323 @code{tab-to-tab-stop}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2324 @item C-j
Dave Love <fx@gnu.org>
parents:
diff changeset
2325 Insert a newline and then indent using @code{tab-to-tab-stop}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2326 @item :
Dave Love <fx@gnu.org>
parents:
diff changeset
2327 Insert a colon and then remove the indentation from before the label
Dave Love <fx@gnu.org>
parents:
diff changeset
2328 preceding colon. Then do @code{tab-to-tab-stop}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2329 @item ;
Dave Love <fx@gnu.org>
parents:
diff changeset
2330 Insert or align a comment.
Dave Love <fx@gnu.org>
parents:
diff changeset
2331 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2332
Dave Love <fx@gnu.org>
parents:
diff changeset
2333 The variable @code{asm-comment-char} specifies which character
Dave Love <fx@gnu.org>
parents:
diff changeset
2334 starts comments in assembler syntax.