This is ../info/emacs, produced by makeinfo version 4.0 from emacs.texi.
This is the Fourteenth edition of the `GNU Emacs Manual', updated
for Emacs version 21.1.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Emacs: (emacs). The extensible self-documenting text editor.
END-INFO-DIR-ENTRY
Published by the Free Software Foundation 59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1985,
1986,1987,1993,1994,1995,1996,1997,1998,1999,2000,2001 Free Software
Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "The GNU Manifesto", "Distribution" and "GNU
GENERAL PUBLIC LICENSE", with the Front-Cover texts being "A GNU
Manual," and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License."
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development."
File: emacs, Node: C Indent, Next: Custom C Indent, Prev: Lisp Indent, Up: Program Indent
Commands for C Indentation
--------------------------
Here are special features for indentation in C mode and related
modes:
`C-c C-q'
Reindent the current top-level function definition or aggregate
type declaration (`c-indent-defun').
`C-M-q'
Reindent each line in the balanced expression that follows point
(`c-indent-exp'). A prefix argument inhibits error checking and
warning messages about invalid syntax.
`<TAB>'
Reindent the current line, and/or in some cases insert a tab
character (`c-indent-command').
If `c-tab-always-indent' is `t', this command always reindents the
current line and does nothing else. This is the default.
If that variable is `nil', this command reindents the current line
only if point is at the left margin or in the line's indentation;
otherwise, it inserts a tab (or the equivalent number of spaces,
if `indent-tabs-mode' is `nil').
Any other value (not `nil' or `t') means always reindent the line,
and also insert a tab if within a comment, a string, or a
preprocessor directive.
To reindent the whole current buffer, type `C-x h C-M-\'. This
first selects the whole buffer as the region, then reindents that
region.
To reindent the current block, use `C-M-u C-M-q'. This moves to the
front of the block and then reindents it all.
File: emacs, Node: Custom C Indent, Prev: C Indent, Up: Program Indent
Customizing C Indentation
-------------------------
C mode and related modes use a simple yet flexible mechanism for
customizing indentation. The mechanism works in two steps: first it
classifies the line syntactically according to its contents and context;
second, it associates each kind of syntactic construct with an
indentation offset based on your selected "style".
`M-x c-set-style <RET> STYLE <RET>'
Select predefined indentation style STYLE.
A style is a named collection of indentation customizations that can
be used in C mode and the related modes. Emacs comes with several
predefined styles, including `gnu', `k&r', `bsd', `stroustrup',
`linux', `python', `java', `whitesmith', `ellemtel', `cc-mode', and
`user'. Some of these styles are primarily intended for one language,
but any of them can be used with any of the languages supported by these
modes. To find out what a style looks like, select it and reindent
some code, e.g., by typing <C-M-q> at the start of a function
definition.
To choose a style for the current buffer, use the command `M-x
c-set-style'. Specify a style name as an argument (case is not
significant). This command affects the current buffer only, and it
affects only future invocations of the indentation commands; it does
not reindent the code in the buffer. To reindent the whole buffer in
the new style, you can type `C-x h C-M-\'.
You can also set the variable `c-default-style' to specify the
default style for various major modes. Its value should be an alist,
in which each element specifies one major mode and which indentation
style to use for it. For example,
(setq c-default-style
'((java-mode . "java") (other . "gnu")))
specifies an explicit choice for Java mode, and the default `gnu' style
for the other C-like modes. This variable takes effect when you select
one of the C-like major modes; thus, if you specify a new default style
for Java mode, you can make it take effect in an existing Java mode
buffer by typing `M-x java-mode' there.
The `gnu' style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.
*Note Customizing Indentation: (ccmode)Customizing Indentation, for
more information on customizing indentation for C and related modes,
including how to override parts of an existing style and how to define
your own styles.
File: emacs, Node: Parentheses, Next: Documentation, Prev: Comments, Up: Programs
Commands for Editing with Parentheses
=====================================
This section describes the commands and features that take advantage
of the parenthesis structure in a program, or help you keep it balanced.
When talking about these facilities, the term "parenthesis" also
includes braces, brackets, or whatever delimiters are defined to match
in pairs. The major mode controls which delimiters are significant,
through the syntax table (*note Syntax::). In Lisp, only parentheses
count; in C, these commands apply to braces and brackets too.
You can use `M-x check-parens' to find any unbalanced parentheses
and unbalanced string quotes in the buffer.
* Menu:
* Expressions:: Expressions with balanced parentheses.
* Moving by Parens:: Commands for moving up, down and across
in the structure of parentheses.
* Matching:: Insertion of a close-delimiter flashes matching open.
File: emacs, Node: Expressions, Next: Moving by Parens, Up: Parentheses
Expressions with Balanced Parentheses
-------------------------------------
These commands deal with balanced expressions, also called
"sexps"(1).
`C-M-f'
Move forward over a balanced expression (`forward-sexp').
`C-M-b'
Move backward over a balanced expression(`backward-sexp').
`C-M-k'
Kill balanced expression forward (`kill-sexp').
`C-M-<DEL>'
Kill balanced expression backward (`backward-kill-sexp').
`C-M-t'
Transpose expressions (`transpose-sexps').
`C-M-@'
Put mark after following expression (`mark-sexp').
Each programming language major mode customizes the definition of
balanced expressions to suit that language. Balanced expressions
typically include symbols, numbers, and string constants, as well as
any pair of matching delimiters and their contents. Some languages
have obscure forms of expression syntax that nobody has bothered to
implement in Emacs.
By convention, the keys for these commands are all Control-Meta
characters. They usually act on expressions just as the corresponding
Meta characters act on words. For instance, the command `C-M-b' moves
backward over a balanced expression, just as `M-b' moves back over a
word.
To move forward over a balanced expression, use `C-M-f'
(`forward-sexp'). If the first significant character after point is an
opening delimiter (`(' in Lisp; `(', `[' or `{' in C), `C-M-f' moves
past the matching closing delimiter. If the character begins a symbol,
string, or number, `C-M-f' moves over that.
The command `C-M-b' (`backward-sexp') moves backward over a balanced
expression. The detailed rules are like those above for `C-M-f', but
with directions reversed. If there are prefix characters
(single-quote, backquote and comma, in Lisp) preceding the expression,
`C-M-b' moves back over them as well. The balanced expression commands
move across comments as if they were whitespace, in most modes.
`C-M-f' or `C-M-b' with an argument repeats that operation the
specified number of times; with a negative argument, it moves in the
opposite direction.
Killing a whole balanced expression can be done with `C-M-k'
(`kill-sexp') or `C-M-<DEL>' (`backward-kill-sexp'). `C-M-k' kills the
characters that `C-M-f' would move over, and `C-M-<DEL>' kills the
characters that `C-M-b' would move over. On some machines, `C-M-<DEL>'
typed on the console is a command to reboot; when that is so, you
cannot use it as an Emacs command. This conflict is rare, though:
usually the <DEL> key for Emacs is really <BACKSPACE>, and the reboot
command is `C-M-<DELETE>', so there is no conflict.
A somewhat random-sounding command which is nevertheless handy is
`C-M-t' (`transpose-sexps'), which drags the previous balanced
expression across the next one. An argument serves as a repeat count,
and a negative argument drags the previous balanced expression
backwards across those before it (thus canceling out the effect of
`C-M-t' with a positive argument). An argument of zero, rather than
doing nothing, transposes the balanced expressions ending at or after
point and the mark.
To set the region around the next balanced expression in the buffer,
use `C-M-@' (`mark-sexp'), which sets mark at the same place that
`C-M-f' would move to. `C-M-@' takes arguments like `C-M-f'. In
particular, a negative argument is useful for putting the mark at the
beginning of the previous balanced expression.
In languages that use infix operators, such as C, it is not possible
to recognize all balanced expressions as such because there can be
multiple possibilities at a given position. For example, C mode does
not treat `foo + bar' as a single expression, even though it _is_ one C
expression; instead, it recognizes `foo' as one expression and `bar' as
another, with the `+' as punctuation between them. Both `foo + bar'
and `foo' are legitimate choices for "the expression following point"
when point is at the `f', so the expression commands must perforce
choose one or the other to operate on. Note that `(foo + bar)' is
recognized as a single expression in C mode, because of the parentheses.
---------- Footnotes ----------
(1) The word "sexp" is used to refer to an expression in Lisp.
File: emacs, Node: Moving by Parens, Next: Matching, Prev: Expressions, Up: Parentheses
Moving in the Parenthesis Structure
-----------------------------------
The Emacs commands for handling parenthetical groupings see nothing
except parentheses (or whatever characters must balance in the language
you are working with), and the escape characters that might be used to
quote those. They are mainly intended for editing programs, but can be
useful for editing any text that has parentheses. They are sometimes
called "list" commands because in Lisp these groupings are lists.
`C-M-n'
Move forward over a parenthetical group (`forward-list').
`C-M-p'
Move backward over a parenthetical group(`backward-list').
`C-M-u'
Move up in parenthesis structure (`backward-up-list').
`C-M-d'
Move down in parenthesis structure (`down-list').
The "list" commands `C-M-n' (`forward-list') and `C-M-p'
(`backward-list') move over one (or N) parenthetical groupings,
skipping blithely over any amount of text that doesn't include
meaningful parentheses (symbols, strings, etc.).
`C-M-n' and `C-M-p' try to stay at the same level in the parenthesis
structure. To move _up_ one (or N) levels, use `C-M-u'
(`backward-up-list'). `C-M-u' moves backward up past one unmatched
opening delimiter. A positive argument serves as a repeat count; a
negative argument reverses the direction of motion, so that the command
moves forward and up one or more levels.
To move _down_ in the parenthesis structure, use `C-M-d'
(`down-list'). In Lisp mode, where `(' is the only opening delimiter,
this is nearly the same as searching for a `('. An argument specifies
the number of levels to go down.
File: emacs, Node: Matching, Prev: Moving by Parens, Up: Parentheses
Automatic Display Of Matching Parentheses
-----------------------------------------
The Emacs parenthesis-matching feature is designed to show
automatically how parentheses (and other matching delimiters) match in
the text. Whenever you type a self-inserting character that is a
closing delimiter, the cursor moves momentarily to the location of the
matching opening delimiter, provided that is on the screen. If it is
not on the screen, Emacs displays some of the text near it in the echo
area. Either way, you can tell which grouping you are closing off.
If the opening delimiter and closing delimiter are mismatched--such
as in `[x)'--a warning message is displayed in the echo area.
Three variables control parenthesis match display.
`blink-matching-paren' turns the feature on or off: `nil' disables it,
but the default is `t' to enable match display.
`blink-matching-delay' says how many seconds to leave the cursor on
the matching opening delimiter, before bringing it back to the real
location of point; the default is 1, but on some systems it is useful
to specify a fraction of a second.
`blink-matching-paren-distance' specifies how many characters back
to search to find the matching opening delimiter. If the match is not
found in that distance, scanning stops, and nothing is displayed. This
is to prevent the scan for the matching delimiter from wasting lots of
time when there is no match. The default is 25600.
Show Paren mode provides a more powerful kind of automatic matching.
Whenever point is after a closing delimiter, that delimiter and its
matching opening delimiter are both highlighted; otherwise, if point is
before an opening delimiter, the matching closing delimiter is
highlighted. (There is no need to highlight the opening delimiter in
that case, because the cursor appears on top of that character.) Use
the command `M-x show-paren-mode' to enable or disable this mode.
By default, `show-paren-mode' uses colors to highlight the
parentheses. However, if your display doesn't support colors, you can
customize the faces `show-paren-match-face' and
`show-paren-mismatch-face' to use other attributes, such as bold or
underline. *Note Face Customization::.
File: emacs, Node: Comments, Next: Parentheses, Prev: Program Indent, Up: Programs
Manipulating Comments
=====================
Because comments are such an important part of programming, Emacs
provides special commands for editing and inserting comments.
* Menu:
* Comment Commands:: Inserting, killing, and indenting comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.
File: emacs, Node: Comment Commands, Next: Multi-Line Comments, Up: Comments
Comment Commands
----------------
The comment commands in this table insert, kill and align comments.
They are described in this section and following sections.
`M-;'
Insert or realign comment on current line; alternatively, comment
or uncomment the region (`comment-dwim').
`C-u M-;'
Kill comment on current line (`comment-kill').
`C-x ;'
Set comment column (`comment-set-column').
`C-M-j'
Like <RET> followed by inserting and aligning a comment
(`comment-indent-new-line').
`M-x comment-region'
Add or remove comment delimiters on all the lines in the region.
The command to create or align a comment is `M-;' (`comment-dwim').
The word "dwim" is an acronym for "Do What I Mean"; it indicates that
this command can be used for many different jobs relating to comments,
depending on the situation where you use it.
If there is no comment already on the line, `M-;' inserts a new
comment, aligned at a specific column called the "comment column". The
new comment begins with the string Emacs thinks comments should start
with (the value of `comment-start'; see below). Point is after that
string, so you can insert the text of the comment right away. If the
major mode has specified a string to terminate comments, `M-;' inserts
that too, to keep the syntax valid.
If the text of the line extends past the comment column, then the
comment start string is indented to a suitable boundary (usually, at
least one space is inserted).
You can also use `M-;' to align an existing comment. If a line
already contains the comment-start string, `M-;' reindents it to the
conventional alignment and moves point after it. (Exception: comments
starting in column 0 are not moved.) Even when an existing comment is
properly aligned, `M-;' is still useful for moving directly to the
start of the text inside the comment.
`C-u M-;' kills any comment on the current line, along with the
whitespace before it. To reinsert the comment on another line, move to
the end of that line, do `C-y', and then do `M-;' to realign it.
Note that `C-u M-;' is not a distinct key; it is `M-;'
(`comment-dwim') with a prefix argument. That command is programmed so
that when it receives a prefix argument it calls `comment-kill'.
However, `comment-kill' is a valid command in its own right, and you
can bind it directly to a key if you wish.
`M-;' does two other jobs when used with an active region in
Transient Mark mode (*note Transient Mark::). Then it either adds or
removes comment delimiters on each line of the region. (If every line
is a comment, it removes comment delimiters from each; otherwise, it
adds comment delimiters to each.) If you are not using Transient Mark
mode, then you should use the commands `comment-region' and
`uncomment-region' to do these jobs (*note Multi-Line Comments::). A
prefix argument used in these circumstances specifies how many comment
delimiters to add or how many to delete.
Some major modes have special rules for indenting certain kinds of
comments in certain contexts. For example, in Lisp code, comments which
start with two semicolons are indented as if they were lines of code,
instead of at the comment column. Comments which start with three
semicolons are supposed to start at the left margin. Emacs understands
these conventions by indenting a double-semicolon comment using <TAB>,
and by not changing the indentation of a triple-semicolon comment at
all.
;; This function is just an example
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;; And now, the first part of the function:
;; The following line adds one.
(1+ x)) ; This line adds one.
In C code, a comment preceded on its line by nothing but whitespace
is indented like a line of code.
File: emacs, Node: Multi-Line Comments, Next: Options for Comments, Prev: Comment Commands, Up: Comments
Multiple Lines of Comments
--------------------------
If you are typing a comment and wish to continue it on another line,
you can use the command `C-M-j' (`comment-indent-new-line'). This
terminates the comment you are typing, creates a new blank line
afterward, and begins a new comment indented under the old one. When
Auto Fill mode is on, going past the fill column while typing a comment
causes the comment to be continued in just this fashion. If point is
not at the end of the line when `C-M-j' is typed, the text on the rest
of the line becomes part of the new comment line.
To turn existing lines into comment lines, use the `M-x
comment-region' command. It adds comment delimiters to the lines that
start in the region, thus commenting them out. With a negative
argument, it does the opposite--it deletes comment delimiters from the
lines in the region.
With a positive argument, `comment-region' duplicates the last
character of the comment start sequence it adds; the argument specifies
how many copies of the character to insert. Thus, in Lisp mode, `C-u 2
M-x comment-region' adds `;;' to each line. Duplicating the comment
delimiter is a way of calling attention to the comment. It can also
affect how the comment is indented. In Lisp, for proper indentation,
you should use an argument of two or three, if between defuns; if
within a defun, it must be three.
File: emacs, Node: Options for Comments, Prev: Multi-Line Comments, Up: Comments
Options Controlling Comments
----------------------------
The comment column is stored in the variable `comment-column'. You
can set it to a number explicitly. Alternatively, the command `C-x ;'
(`comment-set-column') sets the comment column to the column point is
at. `C-u C-x ;' sets the comment column to match the last comment
before point in the buffer, and then does a `M-;' to align the current
line's comment under the previous one.
The variable `comment-column' is per-buffer: setting the variable in
the normal fashion affects only the current buffer, but there is a
default value which you can change with `setq-default'. *Note
Locals::. Many major modes initialize this variable for the current
buffer.
The comment commands recognize comments based on the regular
expression that is the value of the variable `comment-start-skip'.
Make sure this regexp does not match the null string. It may match more
than the comment starting delimiter in the strictest sense of the word;
for example, in C mode the value of the variable is
`"/\\*+ *\\|//+ *""', which matches extra stars and spaces after the
`/*' itself, and accepts C++ style comments also. (Note that `\\' is
needed in Lisp syntax to include a `\' in the string, which is needed
to deny the first star its special meaning in regexp syntax. *Note
Regexps::.)
When a comment command makes a new comment, it inserts the value of
`comment-start' to begin it. The value of `comment-end' is inserted
after point, so that it will follow the text that you will insert into
the comment. In C mode, `comment-start' has the value `"/* "' and
`comment-end' has the value `" */"'.
The variable `comment-padding' specifies how many spaces
`comment-region' should insert on each line between the comment
delimiter and the line's original text. The default is 1, to insert
one space.
The variable `comment-multi-line' controls how `C-M-j'
(`indent-new-comment-line') behaves when used inside a comment. If
`comment-multi-line' is `nil', as it normally is, then the comment on
the starting line is terminated and a new comment is started on the new
following line. If `comment-multi-line' is not `nil', then the new
following line is set up as part of the same comment that was found on
the starting line. This is done by not inserting a terminator on the
old line, and not inserting a starter on the new line. In languages
where multi-line comments work, the choice of value for this variable
is a matter of taste.
The variable `comment-indent-function' should contain a function
that will be called to compute the indentation for a newly inserted
comment or for aligning an existing comment. It is set differently by
various major modes. The function is called with no arguments, but with
point at the beginning of the comment, or at the end of a line if a new
comment is to be inserted. It should return the column in which the
comment ought to start. For example, in Lisp mode, the indent hook
function bases its decision on how many semicolons begin an existing
comment, and on the code in the preceding lines.
File: emacs, Node: Documentation, Next: Hideshow, Prev: Parentheses, Up: Programs
Documentation Lookup
====================
Emacs provides several features you can use to look up the
documentation of functions, variables and commands that you plan to use
in your program.
* Menu:
* Info Lookup:: Looking up library functions and commands
in Info files.
* Man Page:: Looking up man pages of library functions and commands.
* Lisp Doc:: Looking up Emacs Lisp functions, etc.
File: emacs, Node: Info Lookup, Next: Man Page, Up: Documentation
Info Documentation Lookup
-------------------------
For C, Lisp, and other languages that have documentation in Info,
you can use `C-h C-i' (`info-lookup-symbol') to view the Info
documentation for a symbol. You specify the symbol with the
minibuffer; the default is the symbol appearing in the buffer at point.
The major mode determines where to look for documentation for the
symbol--which Info files to look in, and which indices to search. You
can also use `M-x info-lookup-file' to look for documentation for a
file name.
This feature currently supports the modes Awk, Autoconf, Bison, C,
Emacs Lisp, LaTeX, M4, Makefile, Octave, Perl, Scheme, and Texinfo,
provided you have installed the relevant Info files, which are
typically available with the appropriate GNU package.
File: emacs, Node: Man Page, Next: Lisp Doc, Prev: Info Lookup, Up: Documentation
Man Page Lookup
---------------
On Unix, the main form of on-line documentation was the "manual
page" or "man page". In the GNU operating system, we hope to replace
man pages with better-organized manuals that you can browse with Info
(*note Misc Help::). This process is not finished, so it is still
useful to read manual pages.
You can read the man page for an operating system command, library
function, or system call, with the `M-x manual-entry' command. It runs
the `man' program to format the man page; if the system permits, it
runs `man' asynchronously, so that you can keep on editing while the
page is being formatted. (On MS-DOS and MS-Windows 3, you cannot edit
while Emacs waits for `man' to finish.) The result goes in a buffer
named `*Man TOPIC*'. These buffers use a special major mode, Man mode,
that facilitates scrolling and jumping to other manual pages. For
details, type `C-h m' while in a man page buffer.
Each man page belongs to one of ten or more "sections", each named
by a digit or by a digit and a letter. Sometimes there are multiple
man pages with the same name in different sections. To read a man page
from a specific section, type `TOPIC(SECTION)' or `SECTION TOPIC' when
`M-x manual-entry' prompts for the topic. For example, to read the man
page for the C library function `chmod' (as opposed to a command of the
same name), type `M-x manual-entry <RET> chmod(2) <RET>' (`chmod' is a
system call, so it is in section `2').
If you do not specify a section, the results depend on how the `man'
program works on your system. Some of them display only the first man
page they find. Others display all man pages that have the specified
name, so you can move between them with the `M-n' and `M-p' keys(1).
The mode line shows how many manual pages are present in the Man buffer.
By default, Emacs highlights the text in man pages. For a long man
page, highlighting can take substantial time. You can turn off
highlighting of man pages by setting the variable
`Man-fontify-manpage-flag' to `nil'.
If you insert the text of a man page into an Emacs buffer in some
other fashion, you can use the command `M-x Man-fontify-manpage' to
perform the same conversions that `M-x manual-entry' does.
An alternative way of reading manual pages is the `M-x woman'
command(2). Unlike `M-x man', it does not run any external programs to
format and display the man pages; instead it does the job in Emacs
Lisp, so it works on systems such as MS-Windows, where the `man'
program (and the other programs it uses) are not generally available.
`M-x woman' prompts for a name of a manual page, and provides
completion based on the list of manual pages that are installed on your
machine; the list of available manual pages is computed automatically
the first time you invoke `woman'. The word at point in the current
buffer is used to suggest the default for the name the manual page.
With a numeric argument, `M-x woman' recomputes the list of the
manual pages used for completion. This is useful if you add or delete
manual pages.
If you type a name of a manual page and `M-x woman' finds that
several manual pages by the same name exist in different sections, it
pops up a window with possible candidates asking you to choose one of
them.
By default, `M-x woman' looks for manual pages in the directories
specified in the `MANPATH' environment variable. (If `MANPATH' is not
set, `woman' uses a suitable default value, which can be customized.)
More precisely, `woman' looks for subdirectories that match the shell
wildcard pattern `man*' in each one of these directories, and tries to
find the manual pages in those subdirectories. When first invoked,
`M-x woman' converts the value of `MANPATH' to a list of directory
names and stores that list in the `woman-manpath' variable. Changing
the value of this variable is another way to control the list of
directories used.
You can also augment the list of directories searched by `woman' by
setting the value of the `woman-path' variable. This variable should
hold a list of specific directories which `woman' should search, in
addition to those in `woman-manpath'. Unlike `woman-manpath', the
directories in `woman-path' are searched for the manual pages, not for
`man*' subdirectories.
Occasionally, you might need to display manual pages that are not in
any of the directories listed by `woman-manpath' and `woman-path'. The
`M-x woman-find-file' command prompts for a name of a manual page file,
with completion, and then formats and displays that file like `M-x
woman' does.
The first time you invoke `M-x woman', it defines the Dired `W' key
to run the `woman-find-file' command on the current line's file. You
can disable this by setting the variable `woman-dired-keys' to `nil'.
*Note Dired::. In addition, the Tar-mode `w' key is define to invoke
`woman-find-file' on the current line's archive member.
For more information about setting up and using `M-x woman', see
*Note WoMan: (woman)Top.
---------- Footnotes ----------
(1) On some systems, the `man' program accepts a `-a' command-line
option which tells it to display all the man pages for the specified
topic. If you want this behavior, you can add this option to the value
of the variable `Man-switches'.
(2) The name of the command, `woman', is an acronym for "w/o
(without) man," since it doesn't use the `man' program.
File: emacs, Node: Lisp Doc, Prev: Man Page, Up: Documentation
Emacs Lisp Documentation Lookup
-------------------------------
As you edit Lisp code to be run in Emacs, you can use the commands
`C-h f' (`describe-function') and `C-h v' (`describe-variable') to view
documentation of functions and variables that you want to use. These
commands use the minibuffer to read the name of a function or variable
to document, and display the documentation in a window. Their default
arguments are based on the code in the neighborhood of point. For `C-h
f', the default is the function called in the innermost list containing
point. `C-h v' uses the symbol name around or adjacent to point as its
default.
A more automatic but less powerful method is Eldoc mode. This minor
mode constantly displays in the echo area the argument list for the
function being called at point. (In other words, it finds the function
call that point is contained in, and displays the argument list of that
function.) Eldoc mode applies in Emacs Lisp and Lisp Interaction modes
only. Use the command `M-x eldoc-mode' to enable or disable this
feature.
File: emacs, Node: Hideshow, Next: Symbol Completion, Prev: Documentation, Up: Programs
Hideshow minor mode
===================
Hideshow minor mode provides selective display of portions of a
program, known as "blocks". You can use `M-x hs-minor-mode' to enable
or disable this mode, or add `hs-minor-mode' to the mode hook for
certain major modes in order to enable it automatically for those modes.
Just what constitutes a block depends on the major mode. In C mode
or C++ mode, they are delimited by braces, while in Lisp mode and
similar modes they are delimited by parentheses. Multi-line comments
also count as blocks.
`C-c @ C-h'
Hide the current block (`hs-hide-block').
`C-c @ C-s'
Show the current block (`hs-show-block').
`C-c @ C-c'
Either hide or show the current block (`hs-toggle-hiding')
`S-Mouse-2'
Either hide or show the block you click on
(`hs-mouse-toggle-hiding')
`C-c @ C-M-h'
Hide all top-level blocks (`hs-hide-all').
`C-c @ C-M-s'
Show everything in the buffer (`hs-show-all').
`C-c @ C-l'
Hide all blocks N levels below this block (`hs-hide-level').
These user options exist for customizing Hideshow mode.
`hs-hide-comments-when-hiding-all'
Non-`nil' says that `hs-hide-all' should hide comments too.
`hs-isearch-open'
Specifies what kind of hidden blocks to open in Isearch mode. The
value should be one of these four symbols.
`code'
Open only code blocks.
`comment'
Open only comments.
`t'
Open both code blocks and comments.
`nil'
Open neither code blocks nor comments.
`hs-special-modes-alist'
A list of elements, each specifying how to initialize Hideshow
variables for one major mode. See the variable's documentation
string for more information.
File: emacs, Node: Symbol Completion, Next: Glasses, Prev: Hideshow, Up: Programs
Completion for Symbol Names
===========================
In Emacs, completion is something you normally do in the minibuffer.
But one kind of completion is available in all buffers: completion for
symbol names.
The character `M-<TAB>' runs a command to complete the partial
symbol before point against the set of meaningful symbol names. This
command inserts at point any additional characters that it can
determine from the partial name.
If the partial name in the buffer has multiple possible completions
that differ in the very next character, so that it is impossible to
complete even one more character, `M-<TAB>' displays a list of all
possible completions in another window.
In most programming language major modes, `M-<TAB>' runs the command
`complete-symbol', which provides two kinds of completion. Normally it
does completion based on a tags table (*note Tags::); with a numeric
argument (regardless of the value), it does completion based on the
names listed in the Info file indexes for your language. Thus, to
complete the name of a symbol defined in your own program, use
`M-<TAB>' with no argument; to complete the name of a standard library
function, use `C-u M-<TAB>'. Of course, Info-based completion works
only if there is an Info file for the standard library functions of
your language, and only if it is installed at your site.
In Emacs-Lisp mode, the name space for completion normally consists
of nontrivial symbols present in Emacs--those that have function
definitions, values or properties. However, if there is an
open-parenthesis immediately before the beginning of the partial symbol,
only symbols with function definitions are considered as completions.
The command which implements this is `lisp-complete-symbol'.
In Text mode and related modes, `M-<TAB>' completes words based on
the spell-checker's dictionary. *Note Spelling::.
File: emacs, Node: Glasses, Next: Misc for Programs, Prev: Symbol Completion, Up: Programs
Glasses minor mode
==================
Glasses minor mode makes `unreadableIdentifiersLikeThis' readable by
altering the way they display. It knows two different ways to do this:
by displaying underscores between a lower-case letter and the following
capital letter, and by emboldening the capital letters. It does not
alter the buffer text, only the way they display, so you can use it
even on read-only buffers. You can use the command `M-x glasses-mode'
to enable or disable the mode in the current buffer; you can also add
`glasses-mode' to the mode hook of the programming language major modes
in which you normally want to use Glasses mode.
File: emacs, Node: Misc for Programs, Next: C Modes, Prev: Glasses, Up: Programs
Other Features Useful for Editing Programs
==========================================
A number of Emacs commands that aren't designed specifically for
editing programs are useful for that nonetheless.
The Emacs commands that operate on words, sentences and paragraphs
are useful for editing code. Most symbols names contain words (*note
Words::); sentences can be found in strings and comments (*note
Sentences::). Paragraphs in the strict sense can be found in program
code (in long comments), but the paragraph commands are useful in other
places too, because programming language major modes define paragraphs
to begin and end at blank lines (*note Paragraphs::). Judicious use of
blank lines to make the program clearer will also provide useful chunks
of text for the paragraph commands to work on. Auto Fill mode, if
enabled in a programming language major mode, indents the new lines
which it creates.
The selective display feature is useful for looking at the overall
structure of a function (*note Selective Display::). This feature
hides the lines that are indented more than a specified amount.
Programming modes often support Outline minor mode (*note Outline
Mode::). The Foldout package provides folding-editor features (*note
Foldout::).
The "automatic typing" features may be useful for writing programs.
*Note Autotyping: (autotype)Top.
File: emacs, Node: C Modes, Next: Fortran, Prev: Misc for Programs, Up: Programs
C and Related Modes
===================
This section gives a brief description of the special features
available in C, C++, Objective-C, Java, CORBA IDL, and Pike modes.
(These are called "C mode and related modes.") *Note CC Mode: ()Top,
for a more extensive description of these modes and their special
features.
* Menu:
* Motion in C:: Commands to move by C statements, etc.
* Electric C:: Colon and other chars can automatically reindent.
* Hungry Delete:: A more powerful DEL command.
* Other C Commands:: Filling comments, viewing expansion of macros,
and other neat features.
* Comments in C:: Options for customizing comment style.
File: emacs, Node: Motion in C, Next: Electric C, Up: C Modes
C Mode Motion Commands
----------------------
This section describes commands for moving point, in C mode and
related modes.
`C-c C-u'
Move point back to the containing preprocessor conditional,
leaving the mark behind. A prefix argument acts as a repeat
count. With a negative argument, move point forward to the end of
the containing preprocessor conditional. When going backwards,
`#elif' is treated like `#else' followed by `#if'. When going
forwards, `#elif' is ignored.
`C-c C-p'
Move point back over a preprocessor conditional, leaving the mark
behind. A prefix argument acts as a repeat count. With a negative
argument, move forward.
`C-c C-n'
Move point forward across a preprocessor conditional, leaving the
mark behind. A prefix argument acts as a repeat count. With a
negative argument, move backward.
`M-a'
Move point to the beginning of the innermost C statement
(`c-beginning-of-statement'). If point is already at the beginning
of a statement, move to the beginning of the preceding statement.
With prefix argument N, move back N - 1 statements.
If point is within a string or comment, or next to a comment (only
whitespace between them), this command moves by sentences instead
of statements.
When called from a program, this function takes three optional
arguments: the numeric prefix argument, a buffer position limit
(don't move back before that place), and a flag that controls
whether to do sentence motion when inside of a comment.
`M-e'
Move point to the end of the innermost C statement; like `M-a'
except that it moves in the other direction (`c-end-of-statement').
`M-x c-backward-into-nomenclature'
Move point backward to beginning of a C++ nomenclature section or
word. With prefix argument N, move N times. If N is negative,
move forward. C++ nomenclature means a symbol name in the style
of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter
begins a section or word.
In the GNU project, we recommend using underscores to separate
words within an identifier in C or C++, rather than using case
distinctions.
`M-x c-forward-into-nomenclature'
Move point forward to end of a C++ nomenclature section or word.
With prefix argument N, move N times.
File: emacs, Node: Electric C, Next: Hungry Delete, Prev: Motion in C, Up: C Modes
Electric C Characters
---------------------
In C mode and related modes, certain printing characters are
"electric"--in addition to inserting themselves, they also reindent the
current line and may insert newlines. This feature is controlled by
the variable `c-auto-newline'. The "electric" characters are `{', `}',
`:', `#', `;', `,', `<', `>', `/', `*', `(', and `)'.
Electric characters insert newlines only when the "auto-newline"
feature is enabled (indicated by `/a' in the mode line after the mode
name). This feature is controlled by the variable `c-auto-newline'.
You can turn this feature on or off with the command `C-c C-a':
`C-c C-a'
Toggle the auto-newline feature (`c-toggle-auto-state'). With a
prefix argument, this command turns the auto-newline feature on if
the argument is positive, and off if it is negative.
The colon character is electric because that is appropriate for a
single colon. But when you want to insert a double colon in C++, the
electric behavior of colon is inconvenient. You can insert a double
colon with no reindentation or newlines by typing `C-c :':
`C-c :'
Insert a double colon scope operator at point, without reindenting
the line or adding any newlines (`c-scope-operator').
The electric `#' key reindents the line if it appears to be the
beginning of a preprocessor directive. This happens when the value of
`c-electric-pound-behavior' is `(alignleft)'. You can turn this
feature off by setting `c-electric-pound-behavior' to `nil'.
The variable `c-hanging-braces-alist' controls the insertion of
newlines before and after inserted braces. It is an association list
with elements of the following form: `(SYNTACTIC-SYMBOL . NL-LIST)'.
Most of the syntactic symbols that appear in `c-offsets-alist' are
meaningful here as well.
The list NL-LIST may contain either of the symbols `before' or
`after', or both; or it may be `nil'. When a brace is inserted, the
syntactic context it defines is looked up in `c-hanging-braces-alist';
if it is found, the NL-LIST is used to determine where newlines are
inserted: either before the brace, after, or both. If not found, the
default is to insert a newline both before and after braces.
The variable `c-hanging-colons-alist' controls the insertion of
newlines before and after inserted colons. It is an association list
with elements of the following form: `(SYNTACTIC-SYMBOL . NL-LIST)'.
The list NL-LIST may contain either of the symbols `before' or `after',
or both; or it may be `nil'.
When a colon is inserted, the syntactic symbol it defines is looked
up in this list, and if found, the NL-LIST is used to determine where
newlines are inserted: either before the brace, after, or both. If the
syntactic symbol is not found in this list, no newlines are inserted.
Electric characters can also delete newlines automatically when the
auto-newline feature is enabled. This feature makes auto-newline more
acceptable, by deleting the newlines in the most common cases where you
do not want them. Emacs can recognize several cases in which deleting a
newline might be desirable; by setting the variable `c-cleanup-list',
you can specify _which_ of these cases that should happen. The
variable's value is a list of symbols, each describing one case for
possible deletion of a newline. Here are the meaningful symbols, and
their meanings:
`brace-catch-brace'
Clean up `} catch (CONDITION) {' constructs by placing the entire
construct on a single line. The clean-up occurs when you type the
`{', if there is nothing between the braces aside from `catch' and
CONDITION.
`brace-else-brace'
Clean up `} else {' constructs by placing the entire construct on
a single line. The clean-up occurs when you type the `{' after
the `else', but only if there is nothing but white space between
the braces and the `else'.
`brace-elseif-brace'
Clean up `} else if (...) {' constructs by placing the entire
construct on a single line. The clean-up occurs when you type the
`{', if there is nothing but white space between the `}' and `{'
aside from the keywords and the `if'-condition.
`empty-defun-braces'
Clean up empty defun braces by placing the braces on the same
line. Clean-up occurs when you type the closing brace.
`defun-close-semi'
Clean up the semicolon after a `struct' or similar type
declaration, by placing the semicolon on the same line as the
closing brace. Clean-up occurs when you type the semicolon.
`list-close-comma'
Clean up commas following braces in array and aggregate
initializers. Clean-up occurs when you type the comma.
`scope-operator'
Clean up double colons which may designate a C++ scope operator, by
placing the colons together. Clean-up occurs when you type the
second colon, but only when the two colons are separated by
nothing but whitespace.
File: emacs, Node: Hungry Delete, Next: Other C Commands, Prev: Electric C, Up: C Modes
Hungry Delete Feature in C
--------------------------
When the "hungry-delete" feature is enabled (indicated by `/h' or
`/ah' in the mode line after the mode name), a single <DEL> command
deletes all preceding whitespace, not just one space. To turn this
feature on or off, use `C-c C-d':
`C-c C-d'
Toggle the hungry-delete feature (`c-toggle-hungry-state'). With a
prefix argument, this command turns the hungry-delete feature on
if the argument is positive, and off if it is negative.
`C-c C-t'
Toggle the auto-newline and hungry-delete features, both at once
(`c-toggle-auto-hungry-state').
The variable `c-hungry-delete-key' controls whether the
hungry-delete feature is enabled.
File: emacs, Node: Other C Commands, Next: Comments in C, Prev: Hungry Delete, Up: C Modes
Other Commands for C Mode
-------------------------
`C-M-h'
Put mark at the end of a function definition, and put point at the
beginning (`c-mark-function').
`M-q'
Fill a paragraph, handling C and C++ comments (`c-fill-paragraph').
If any part of the current line is a comment or within a comment,
this command fills the comment or the paragraph of it that point
is in, preserving the comment indentation and comment delimiters.
`C-c C-e'
Run the C preprocessor on the text in the region, and show the
result, which includes the expansion of all the macro calls
(`c-macro-expand'). The buffer text before the region is also
included in preprocessing, for the sake of macros defined there,
but the output from this part isn't shown.
When you are debugging C code that uses macros, sometimes it is
hard to figure out precisely how the macros expand. With this
command, you don't have to figure it out; you can see the
expansions.
`C-c C-\'
Insert or align `\' characters at the ends of the lines of the
region (`c-backslash-region'). This is useful after writing or
editing a C macro definition.
If a line already ends in `\', this command adjusts the amount of
whitespace before it. Otherwise, it inserts a new `\'. However,
the last line in the region is treated specially; no `\' is
inserted on that line, and any `\' there is deleted.
`M-x cpp-highlight-buffer'
Highlight parts of the text according to its preprocessor
conditionals. This command displays another buffer named `*CPP
Edit*', which serves as a graphic menu for selecting how to
display particular kinds of conditionals and their contents.
After changing various settings, click on `[A]pply these settings'
(or go to that buffer and type `a') to rehighlight the C mode
buffer accordingly.
`C-c C-s'
Display the syntactic information about the current source line
(`c-show-syntactic-information'). This is the information that
directs how the line is indented.
`M-x cwarn-mode'
`M-x global-cwarn-mode'
CWarn minor mode highlights certain suspicious C and C++
constructions:
* Assignments inside expressions.
* Semicolon following immediately after `if', `for', and `while'
(except after a `do ... while' statement);
* C++ functions with reference parameters.
You can enable the mode for one buffer with the command `M-x
cwarn-mode', or for all suitable buffers with the command `M-x
global-cwarn-mode' or by customizing the variable
`global-cwarn-mode'. You must also enable Font Lock mode to make
it work.
`M-x hide-ifdef-mode'
Hide-ifdef minor mode hides selected code within `#if' and
`#ifdef' preprocessor blocks. See the documentation string of
`hide-ifdef-mode' for more information.
`M-x ff-find-related-file'
Find a file "related" in a special way to the file visited by the
current buffer. Typically this will be the header file
corresponding to a C/C++ source file, or vice versa. The variable
`ff-related-file-alist' specifies how to compute related file
names.