@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
+@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
As opposed to most normal Emacs packages, Gnus uses a number of
different buffers to display information and to receive commands. The
three buffers users spend most of their time in are the @dfn{group
-buffer}, the @dfn{summary buffer} and the @dfn{article buffer}.
+buffer}, the @dfn{summary buffer} and the @dfn{article buffer}.
The @dfn{group buffer} contains a list of groups. This is the first
buffer Gnus displays when it starts up. It normally displays only the
@node Summary of Gnus
@subsection Summary of Gnus Commands
-Reading news is a two step process:
+Reading news is a two-step process:
@enumerate
@item
and display the first unread article in that group.
@need 1000
-In the summary buffer,
+In the summary buffer,
@itemize @bullet
@item
@item
Have Gnus score articles according to various criteria, like author
name, subject, or string in the body of the articles.@*
-@xref{Scoring, , , gnus, The Gnus Manual}.
+@xref{Scoring, , , gnus, The Gnus Manual}.
@item
Send an article to a newsgroup.@*
emulator window.
There is a shell implemented entirely in Emacs, documented in a separate
-manual. @xref{, ,Eshell , eshell, Eshell: The Emacs Shell}.
+manual. @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
@table @kbd
@item M-! @var{cmd} @key{RET}
@kbd{M-!} (@code{shell-command}) reads a line of text using the
minibuffer and executes it as a shell command in a subshell made just
for that command. Standard input for the command comes from the null
-device. If the shell command produces any output, the output goes into
-an Emacs buffer named @samp{*Shell Command Output*}, which is displayed
-in another window but not selected. A numeric argument, as in @kbd{M-1
-M-!}, directs this command to insert any output into the current buffer.
-In that case, point is left before the output and the mark is set after
-the output.
+device. If the shell command produces any output, the output appears
+either in the echo area (if it is short), or in an Emacs buffer named
+@samp{*Shell Command Output*}, which is displayed in another window
+but not selected (if the output is long).
+
+ For instance, one way to decompress a file @file{foo.gz} from Emacs
+is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command
+normally creates the file @file{foo} and produces no terminal output.
+
+ A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal
+output into the current buffer instead of a separate buffer. It puts
+point before the output, and sets the mark after the output. For
+instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
+uncompressed equivalent of @file{foo.gz} into the current buffer.
If the shell command line ends in @samp{&}, it runs asynchronously.
For a synchronous shell command, @code{shell-command} returns the
command's exit status (0 means success), when it is called from a Lisp
-program.
+program. You do not get any status information for an asynchronous
+command, since it hasn't finished yet.
@kindex M-|
@findex shell-command-on-region
first and the output replaces it as the contents of the region. It
returns the command's exit status when it is called from a Lisp program.
+ One use for @kbd{M-|} is to run @code{uudecode}. For instance, if
+the buffer contains uuencoded text, type @kbd{C-x h M-| uudecode
+@key{RET}} to feed the entire buffer contents to the @code{uudecode}
+program. That program will ignore everything except the encoded text,
+and will store the decoded output into the file whose name is
+specified in the encoded text.
+
@vindex shell-file-name
-@cindex environment
Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
shell to use. This variable is initialized based on your @env{SHELL}
environment variable when Emacs is started. If the file name does not
face @code{comint-highlight-prompt}. This makes it easier to see
previous input lines in the buffer. @xref{Faces}.
- To make multiple subshells, rename the buffer @samp{*shell*} to
-something different using @kbd{M-x rename-uniquely}. Then type @kbd{M-x
-shell} again to create a new buffer @samp{*shell*} with its own
-subshell. If you rename this buffer as well, you can create a third
-one, and so on. All the subshells run independently and in parallel.
+ To make multiple subshells, you can invoke @kbd{M-x shell} with a
+prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
+name and create (or reuse) a subshell in that buffer. You can also
+rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
+create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. All the
+subshells in different buffers run independently and in parallel.
@vindex explicit-shell-file-name
+@cindex environment variables for subshells
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable
The file name used to load the subshell is the value of the variable
specify a coding system after starting the shell by using @kbd{C-x
@key{RET} p} in the shell buffer. @xref{Specify Coding}.
- Emacs defines the environment variable @env{EMACS} in the subshell,
-with value @code{t}. A shell script can check this variable to
-determine whether it has been run from an Emacs subshell.
+@cindex @env{EMACS} environment variable
+ Unless the environment variable @env{EMACS} is already defined,
+Emacs defines it in the subshell, with value @code{t}. A shell script
+can check this variable to determine whether it has been run from an
+Emacs subshell.
@node Shell Mode
@subsection Shell Mode
@findex comint-send-input
At end of buffer send line as input; otherwise, copy current line to
end of buffer and send it (@code{comint-send-input}). When a line is
-copied, any prompt at the beginning if the line (text output by
-programs preceding your input) is omitted. See also
-@code{comint-use-prompt-regexp-instead-of-fields}).
+copied, any prompt at the beginning of the line (text output by
+programs preceding your input) is omitted. (See also the variable
+@code{comint-use-prompt-regexp-instead-of-fields}.)
@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@vindex shell-completion-fignore
@vindex comint-completion-fignore
The variable @code{shell-completion-fignore} specifies a list of file
-name extensions to ignore in Shell mode completion. The default setting
-ignores file names ending in @samp{~}, @samp{#} or @samp{%}. Other
+name extensions to ignore in Shell mode completion. The default
+setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
+ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other
related Comint modes use the variable @code{comint-completion-fignore}
instead.
@item C-c C-a
@kindex C-c C-a @r{(Shell mode)}
-@findex comint-bol
+@findex comint-bol-or-process-mark
Move to the beginning of the line, but after the prompt if any
-(@code{comint-bol}). If you repeat this command twice in a row, the
-second time it moves back to the process mark, which is the beginning of
-the input that you have not yet sent to the subshell. (Normally that is
-the same place---the end of the prompt on this line---but after @kbd{C-c
-@key{SPC}} the process mark may be in a previous line.)
+(@code{comint-bol-or-process-mark}). If you repeat this command twice
+in a row, the second time it moves back to the process mark, which is
+the beginning of the input that you have not yet sent to the subshell.
+(Normally that is the same place---the end of the prompt on this
+line---but after @kbd{C-c @key{SPC}} the process mark may be in a
+previous line.)
@item C-c @key{SPC}
Accumulate multiple lines of input, then send them together. This
@item C-c C-x @r{(Shell mode)}
@findex comint-get-next-from-history
Fetch the next subsequent command from the history.
+
+@item C-c . @r{(Shell mode)}
+@findex comint-input-previous-argument
+Fetch one argument from an old shell command.
@end table
Shell buffers provide a history of previously entered shell commands. To
The history search commands @kbd{M-r} and @kbd{M-s} read a regular
expression and search through the history for a matching command. Aside
from the choice of which command to fetch, they work just like @kbd{M-p}
-and @kbd{M-r}. If you enter an empty regexp, these commands reuse the
+and @kbd{M-n}. If you enter an empty regexp, these commands reuse the
same regexp used last time.
When you find the previous input you want, you can resubmit it by
can reexecute several successive commands by typing @kbd{C-c C-x
@key{RET}} over and over.
+ The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
+copies an individual argument from a previous command, like @kbd{ESC
+.} in Bash. The simplest use copies the last argument from the
+previous shell command. With a prefix argument @var{n}, it copies the
+@var{n}th argument instead. Repeating @kbd{C-c .} copies from an
+earlier shell command instead, always using the same value of @var{n}
+(don't give a prefix argument when you repeat the @kbd{C-c .}
+command).
+
These commands get the text of previous shell commands from a special
history list, not from the shell buffer itself. Thus, editing the shell
buffer, or even killing large parts of it, does not affect the history
These commands are recognized only at the beginning of a shell command
line.
+@ignore @c This seems to have been deleted long ago.
@vindex shell-set-directory-error-hook
If Emacs gets an error while trying to handle what it believes is a
@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
@code{shell-set-directory-error-hook} (@pxref{Hooks}).
+@end ignore
@findex dirs
If Emacs gets confused about changes in the current directory of the
@vindex comint-scroll-show-maximum-output
If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
-scrolling due to arrival of output tries to place the last line of text
-at the bottom line of the window, so as to show as much useful text as
-possible. (This mimics the scrolling behavior of many terminals.)
-The default is @code{nil}.
+scrolling due to the arrival of output tries to place the last line of
+text at the bottom line of the window, so as to show as much useful
+text as possible. (This mimics the scrolling behavior of many
+terminals.) The default is @code{nil}.
@vindex comint-scroll-to-bottom-on-output
By setting @code{comint-scroll-to-bottom-on-output}, you can opt for
having point jump to the end of the buffer whenever output arrives---no
matter where in the buffer point was before. If the value is
@code{this}, point jumps in the selected window. If the value is
-@code{all}, point jumps in each window that shows the comint buffer. If
+@code{all}, point jumps in each window that shows the Comint buffer. If
the value is @code{other}, point jumps in all nonselected windows that
show the current buffer. The default value is @code{nil}, which means
point does not jump to the end.
@code{comint-completion-autolist}, if non-@code{nil}, says to list all
the possible completions whenever completion is not exact.
-@findex comint-dynamic-complete-variable
- The command @code{comint-dynamic-complete-variable} does variable-name
-completion using the environment variables as set within Emacs. The
-variables controlling file name completion apply to variable-name
-completion too. This command is normally available through the menu
-bar.
-
-@vindex shell-command-execonly
+@vindex shell-completion-execonly
Command completion normally considers only executable files.
-If you set @code{shell-command-execonly} to @code{nil},
+If you set @code{shell-completion-execonly} to @code{nil},
it considers nonexecutable files as well.
@findex shell-pushd-tohome
(@code{shell-pushd-dunique}). The values you choose should match the
underlying shell, of course.
+ If you want Shell mode to handle color output from shell commands,
+you can enable ANSI Color mode. Here is how to do this:
+
+@example
+(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
+@end example
+
@node Terminal emulator
@subsection Emacs Terminal Emulator
@findex term
To run a subshell in a terminal emulator, putting its typescript in
an Emacs buffer, use @kbd{M-x term}. This creates (or reuses) a
-buffer named @samp{*term*}, and runs a subshell with input coming from
-your keyboard, and output going to that buffer.
+buffer named @samp{*terminal*}, and runs a subshell with input coming
+from your keyboard, and output going to that buffer.
The terminal emulator uses Term mode, which has two input modes. In
line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
The file name used to load the subshell is determined the same way
as for Shell mode. To make multiple terminal emulators, rename the
-buffer @samp{*term*} to something different using @kbd{M-x
+buffer @samp{*terminal*} to something different using @kbd{M-x
rename-uniquely}, just as with Shell mode.
Unlike Shell mode, Term mode does not track the current directory by
To switch between line and char mode, use these commands:
@table @kbd
-@kindex C-c C-k @r{(Term mode)}
+@kindex C-c C-j @r{(Term mode)}
@findex term-char-mode
-@item C-c C-k
+@item C-c C-j
Switch to line mode. Do nothing if already in line mode.
-@kindex C-c C-j @r{(Term mode)}
+@kindex C-c C-k @r{(Term mode)}
@findex term-line-mode
-@item C-c C-j
+@item C-c C-k
Switch to char mode. Do nothing if already in char mode.
@end table
screenful of output since your last input, it pauses, displaying
@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next
screenful of output. Type @kbd{?} to see your other options. The
-interface is similar to the Unix @code{more} program.
+interface is similar to the @code{more} program.
@node Remote Host
@subsection Remote Host Shell
happens automatically; there is no special password processing.)
When you log in to a different machine, you need to specify the type
-of terminal your using. Terminal types @samp{ansi} or @samp{vt100}
+of terminal you're using. Terminal types @samp{ansi} or @samp{vt100}
will work on most systems.
@c If you are talking to a Bourne-compatible
@c as long as Emacs can access the source files specified by gdb.
@ignore
- You cannot log into to a remote computer using the Shell mode.
+ You cannot log in to a remote computer using the Shell mode.
@c (This will change when Shell is re-written to use Term.)
Instead, Emacs provides two commands for logging in to another computer
and communicating with it through an Emacs buffer using Comint mode:
@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
inconvenient fashion, by starting a new, separate Emacs process. This
is inconvenient because it takes time and because the new Emacs process
-doesn't share the buffers in the existing Emacs process.
+doesn't share the buffers in any existing Emacs process.
You can arrange to use your existing Emacs process as the editor for
programs like @code{mail} by using the Emacs client and Emacs server
to exit. @kbd{C-x #} also checks for other pending external requests
to edit various files, and selects the next such file.
- You can switch to a server buffer manually if you wish; you don't have
-to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the only way to
-say that you are ``finished'' with one.
+ You can switch to a server buffer manually if you wish; you don't
+have to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the way to
+say that you are finished with one.
@vindex server-kill-new-buffers
@vindex server-temp-file-regexp
and optionally line numbers as well. Do it like this:
@example
-emacsclient @r{@{}@r{[}+@var{line}@r{]} @var{filename}@r{@}}@dots{}
+emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
@end example
@noindent
This tells Emacs to visit each of the specified files; if you specify a
line number for a certain file, Emacs moves to that line in the file.
+If you specify a column number as well, Emacs puts point on that column
+in the line.
Ordinarily, @code{emacsclient} does not return until you use the
@kbd{C-x #} command on each of these buffers. When that happens,
function which will communicate with a running Emacs server, or start
one if none exists.
+If you use several displays, you can tell Emacs on which display to
+open the given files with the option @samp{--display=@var{DISPLAY}}.
+This can be used typically when connecting from home to an Emacs
+server running on your machine at your workplace.
+
+You can also use @code{emacsclient} to execute any piece of Emacs Lisp
+code, using the option @samp{--eval}. When this option is given, the
+rest of the arguments is not taken as a list of files to visit but as
+a list of expressions to evaluate.
+
@node Hardcopy, PostScript, Emacs Server, Top
@section Hardcopy Output
@cindex hardcopy
@cindex handwriting
@kbd{M-x handwrite} is more frivolous. It generates a PostScript
rendition of the current buffer as a cursive handwritten document. It
-can be customized in group @code{handwrite}.
+can be customized in group @code{handwrite}. This function only
+supports ISO 8859-1 characters.
@ifinfo
The following section describes variables for customizing these commands.
@code{Times}. The variable @code{ps-font-size} specifies the size of
the font for ordinary text. It defaults to 8.5 points.
+@vindex ps-multibyte-buffer
+@cindex Intlfonts for PostScript printing
+@cindex fonts for PostScript printing
+ Emacs supports more scripts and characters than a typical PostScript
+printer. Thus, some of the characters in your buffer might not be
+printable using the fonts built into your printer. You can augment
+the fonts supplied with the printer with those from the GNU Intlfonts
+package, or you can instruct Emacs to use Intlfonts exclusively. The
+variable @code{ps-multibyte-buffer} controls this: the default value,
+@code{nil}, is appropriate for printing ASCII and Latin-1
+characters; a value of @code{non-latin-printer} is for printers which
+have the fonts for ASCII, Latin-1, Japanese, and Korean
+characters built into them. A value of @code{bdf-font} arranges for
+the BDF fonts from the Intlfonts package to be used for @emph{all}
+characters. Finally, a value of @code{bdf-font-except-latin}
+instructs the printer to use built-in fonts for ASCII and Latin-1
+characters, and Intlfonts BDF fonts for the rest.
+
+@vindex bdf-directory-list
+ To be able to use the BDF fonts, Emacs needs to know where to find
+them. The variable @code{bdf-directory-list} holds the list of
+directories where Emacs should look for the fonts; the default value
+includes a single directory @file{/usr/local/share/emacs/fonts/bdf}.
+
Many other customization variables for these commands are defined and
-described in the Lisp file @file{ps-print.el}.
+described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
@node Sorting, Narrowing, PostScript Variables, Top
@section Sorting Text
field 1, etc. A negative argument means count fields from the right
instead of from the left; thus, minus 1 means sort by the last field.
If several lines have identical contents in the field being sorted, they
-keep same relative order that they had in the original buffer.
+keep the same relative order that they had in the original buffer.
@item M-x sort-numeric-fields
Like @kbd{M-x sort-fields} except the specified field is converted
paragraph by eliminating clutter. It can also be used to restrict the
range of operation of a replace command or repeating keyboard macro.
-@c WideCommands
@table @kbd
@item C-x n n
Narrow down to between point and mark (@code{narrow-to-region}).
@findex narrow-to-region
The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
It sets the current buffer's restrictions so that the text in the current
-region remains accessible but all text before the region or after the region
-is inaccessible. Point and mark do not change.
+region remains accessible, but all text before the region or after the
+region is inaccessible. Point and mark do not change.
@kindex C-x n p
@findex narrow-to-page
@end table
@noindent
-Other Hexl commands let you insert strings (sequences) of binary bytes,
-move by short's or int's, etc.; type @kbd{C-h a hexl- RET} for details.
+Other Hexl commands let you insert strings (sequences) of binary
+bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a
+hexl-@key{RET}} for details.
@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top
@section Saving Emacs Sessions
@cindex saving sessions
+@cindex restore session
+@cindex remember editing session
+@cindex reload files
@cindex desktop
You can use the Desktop library to save the state of Emacs from one
The mode line shows you when you are in a recursive edit by displaying
square brackets around the parentheses that always surround the major and
-minor mode names. Every window's mode line shows this, in the same way,
+minor mode names. Every window's mode line shows this in the same way,
since being in a recursive edit is true of Emacs as a whole rather than
any particular window or buffer.
@cindex other editors
@cindex EDT
@cindex vi
-@cindex PC keybindings
+@cindex PC key bindings
@cindex scrolling all windows
-@cindex PC selecion
-@cindex Motif keybindings
-@cindex Macintosh keybindings
+@cindex PC selection
+@cindex Motif key bindings
+@cindex Macintosh key bindings
@cindex WordStar
GNU Emacs can be programmed to emulate (more or less) most other
@cindex Brief emulation
@cindex emulation of Brief
@cindex mode, CRiSP
-You can turn on keybindings to emulate the CRiSP/Brief editor with
+You can turn on key bindings to emulate the CRiSP/Brief editor with
@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs
unless you change the user option @code{crisp-override-meta-x}. You can
also use the command @kbd{M-x scroll-all-mode} or set the user option
@cindex PC Selection minor mode
@cindex mode, PC selection
@cindex selection, PC
-The command @kbd{M-x pc-selection-mode} enables a global minor mode
+The command @kbd{M-x pc-selection-mode} toggles a global minor mode
that emulates the mark, copy, cut and paste commands of various other
-systems---an interface known as CUA. It establishes the keybindings
+systems---an interface known as CUA. It establishes the key bindings
of PC mode, and also modifies the bindings of the cursor keys and the
@kbd{next}, @kbd{prior}, @kbd{home} and @kbd{end} keys. It does not
-provide the full set of CUA keybindings---the fundamental Emacs keys
+provide the full set of CUA key bindings---the fundamental Emacs keys
@kbd{C-c}, @kbd{C-v} and @kbd{C-x} are not changed.
The standard keys for moving around (@kbd{right}, @kbd{left},
are available on @kbd{C-insert}, @kbd{S-delete} and @kbd{S-insert}
respectively.
+Turning @code{pc-selection-mode} off restores the old key bindings of
+these keys.
+
@cindex s-region package
The @code{s-region} package provides similar, but less complete,
facilities.
@item WordStar (old wordprocessor)
@findex wordstar-mode
@kbd{M-x wordstar-mode} provides a major mode with WordStar-like
-keybindings.
+key bindings.
@end table
@node Hyperlinking, Dissociated Press, Emulation, Top
@cindex URLs
@table @kbd
-@item M-x browse-url @key{RET} @var{url} @key{ret}
+@item M-x browse-url @key{RET} @var{url} @key{RET}
Load a URL into a Web browser.
@end table
@code{browse-url-at-point} and @code{browse-url-at-mouse}.
@vindex browse-url-browser-function
- You can customize Browse-URL's behaviour via various options in the
+ You can customize Browse-URL's behavior via various options in the
@code{browse-url} Customize group, particularly
@code{browse-url-browser-function}. You can invoke actions dependent
on the type of URL by defining @code{browse-url-browser-function} as
@table @kbd
@item M-x find-function @key{RET} @var{function} @key{RET}
-Find the definition @var{function} in its source file.
+Find the definition of @var{function} in its source file.
@item M-x find-variable @key{RET} @var{variable} @key{RET}
Find the definition of @var{variable} in its source file.
@item M-x find-function-on-key @key{RET} @var{key}
These commands provide an easy way to find the definitions of Emacs
Lisp functions and variables. They are similar in purpose to the Tags
facility (@pxref{Tags}), but don't require a tags table; on the other
-hand, they only works for function and variable definitions that are
+hand, they only work for function and variable definitions that are
already loaded in the Emacs session.
@findex find-function
buffer to another. In order to produce plausible output rather than
gibberish, it insists on a certain amount of overlap between the end of
one run of consecutive words or characters and the start of the next.
-That is, if it has just printed out `president' and then decides to jump
+That is, if it has just output `president' and then decides to jump
to a different point in the file, it might spot the `ent' in `pentagon'
and continue from there, producing `presidentagon'.@footnote{This
dissociword actually appeared during the Vietnam War, when it was very
@cindex tower of Hanoi
If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
-considerably bored, give it a numeric argument. If you are very very
+considerably bored, give it a numeric argument. If you are very, very
bored, try an argument of 9. Sit back and watch.
@cindex Go Moku