* GNU Free Documentation License:: The license for this documentation.
* Concept Index::
* Function and Variable Index::
-* Key Index::
* Command Index::
+* Key Index::
@end menu
@node What is Eshell?
@item
Eli Zaretskii made it possible for Eshell to run without requiring
asynchronous subprocess support. This is important for MS-DOS, which
-does not have such support.@refill
+does not have such support.
@item
-Miles Bader contributed many fixes during the port to Emacs 21.@refill
+Miles Bader contributed many fixes during the port to Emacs 21.
@item
Stefan Monnier fixed the things which bothered him, which of course made
-things better for all.@refill
+things better for all.
@item
Gerd Moellmann also helped to contribute bug fixes during the initial
-integration with Emacs 21.@refill
+integration with Emacs 21.
@item
Alex Schroeder contributed code for interactively querying the user
-before overwriting files.@refill
+before overwriting files.
@item
-Sudish Joseph helped with some XEmacs compatibility issues.@refill
+Sudish Joseph helped with some XEmacs compatibility issues.
@end itemize
Apart from these, a lot of people have sent suggestions, ideas,
@menu
* Invocation::
* Arguments::
-* Variables::
* Built-ins::
+* Variables::
* Aliases::
* History::
* Completion::
@vindex eshell-prefer-lisp-functions
If you would prefer to use the built-in commands instead of the external
-commands, set @var{eshell-prefer-lisp-functions} to @code{t}.
+commands, set @code{eshell-prefer-lisp-functions} to @code{t}.
Some of the built-in commands have different behaviour from their
external counterparts, and some have no external counterpart. Most of
@item define
@cmindex define
-Define a varalias. @xref{Variable Aliases, , , elisp}.
+Define a varalias.
+@xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}.
@item diff
@cmindex diff
Use Emacs's internal @code{diff} (not to be confused with
-@code{ediff}). @xref{Comparing Files, , , elisp}.
+@code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}.
@item grep
@cmindex grep
@item locate
@cmindex locate
Alias to Emacs's @code{locate} function, which simply runs the external
-@command{locate} command and parses the results. @xref{Dired and `find', , , elisp}.
+@command{locate} command and parses the results.
+@xref{Dired and Find, , , emacs, The GNU Emacs Manual}.
@item make
@cmindex make
-Run @command{make} through @code{compile}. @xref{Running Compilations under Emacs, , , elisp}.
+Run @command{make} through @code{compile}.
+@xref{Compilation, , , emacs, The GNU Emacs Manual}.
@item occur
@cmindex occur
-Alias to Emacs's @code{occur}. @xref{Other Search-and-Loop Commands, , , elisp}.
+Alias to Emacs's @code{occur}.
+@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}.
@item printnl
@cmindex printnl
@cmindex su
@itemx sudo
@cmindex sudo
-Uses TRAMP's @command{su} or @command{sudo} method to run a command via
-@command{su} or @command{sudo}.
+Uses TRAMP's @command{su} or @command{sudo} method @pxref{Inline methods, , , tramp}
+to run a command via @command{su} or @command{sudo}. These commands
+are in the eshell-tramp module, which is disabled by default.
@end table
-@section Built-in variables
+@subsection Built-in variables
Eshell knows a few built-in variables:
@table @code
with the command invocation @samp{alias ll ls -l}; with this defined,
running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}.
Aliases defined (or deleted) by the @command{alias} command are
-automatically written to the file named by @var{eshell-aliases-file},
+automatically written to the file named by @code{eshell-aliases-file},
which you can also edit directly (although you will have to manually
reload it).
The history ring is loaded from a file at the start of every session,
and written back to the file at the end of every session. The file path
-is specified in @var{eshell-history-file-name}. Unlike other shells,
+is specified in @code{eshell-history-file-name}. Unlike other shells,
such as Bash, Eshell can not be configured to keep a history ring of a
different size than that of the history file.
provides many functions for this.} For example, @code{$var} on a line
expands to the value of the variable @code{var} when the line is
executed. Expansions are usually passed as arguments, but may also be
-used as commands.@footnote{e.g. Entering just @samp{$var} at the prompt
+used as commands.@footnote{E.g., entering just @samp{$var} at the prompt
is equivalent to entering the value of @code{var} at the prompt.}
@menu
@item $#var
Expands to the length of the value bound to @code{var}. Raises an error
-if the value is not a sequence (@pxref{Sequences Arrays and Vectors, Sequences, , elisp}).
+if the value is not a sequence
+(@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}).
@item $(lisp)
Expands to the result of evaluating the S-expression @code{(lisp)}. On
@item $var[hello]
Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
-an alist (@pxref{Association List Type, Association Lists, , elisp}).
+an alist (@pxref{Association List Type, Association Lists, , elisp,
+The Emacs Lisp Reference Manual}).
@item $#var[hello]
Returns the length of the cdr of the element of @code{var} who car is equal
Eshell's globbing syntax is very similar to that of Zsh. Users coming
from Bash can still use Bash-style globbing, as there are no
incompatibilities. Most globbing is pattern-based expansion, but there
-is also predicate-based expansion. See @ref{Filename Generation, , , zsh}
+is also predicate-based expansion. See
+@ref{Filename Generation, , , zsh, The Z Shell Manual}
for full syntax. To customize the syntax and behaviour of globbing in
-Eshell see the Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
+Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs,
+The GNU Emacs Manual}.}
groups ``eshell-glob'' and ``eshell-pred''.
@node Input/Output
@chapter Input/Output
Since Eshell does not communicate with a terminal like most command
-shells, IO is a little different. If you try to run programs from
-within Eshell that are not line-oriented, such as programs that use
-ncurses, you will just get garbage output, since the Eshell buffer is
-not a terminal emulator. Eshell solves this problem by running
-specified commands in Emacs's terminal emulator; to let Eshell know
-which commands need to be run in a terminal, add them to the list
-@var{eshell-visual-commands}.
-
+shells, IO is a little different.
+
+@section Visual Commands
+If you try to run programs from within Eshell that are not
+line-oriented, such as programs that use ncurses, you will just get
+garbage output, since the Eshell buffer is not a terminal emulator.
+Eshell solves this problem by running such programs in Emacs's
+terminal emulator.
+
+Programs that need a terminal to display output properly are referred
+to in this manual as ``visual commands,'' because they are not simply
+line-oriented. You must tell Eshell which commands are visual, by
+adding them to @code{eshell-visual-commands}; for commands that are
+visual for only certain @emph{sub}-commands -- e.g. @samp{git log} but
+not @samp{git status} -- use @code{eshell-visual-subcommands}; and for
+commands that are visual only when passed certain options, use
+@code{eshell-visual-options}.
+
+@section Redirection
Redirection is mostly the same in Eshell as it is in other command
-shells. The output redirection operators @code{>} and @code{>>} as well
-as pipes are supported, but there is not yet any support for input
-redirection. Output can also be redirected to Elisp functions, using
+shells. The output redirection operators @code{>} and @code{>>} as
+well as pipes are supported, but there is not yet any support for
+input redirection. Output can also be redirected to buffers, using
+the @code{>>>} redirection operator, and Elisp functions, using
virtual devices.
-@var{eshell-virtual-targets} is a list of mappings of virtual device
+The buffer redirection operator, @code{>>>}, expects a buffer object
+on the right-hand side, into which it inserts the output of the
+left-hand side. e.g., @samp{echo hello >>> #<buffer *scratch*>}
+inserts the string @code{"hello"} into the @code{*scratch*} buffer.
+
+@code{eshell-virtual-targets} is a list of mappings of virtual device
names to functions. Eshell comes with two virtual devices:
@file{/dev/kill}, which sends the text to the kill ring, and
@file{/dev/clip}, which sends text to the clipboard.
You can, of course, define your own virtual targets. They are defined
-by adding a list of the form @code{("/dev/name" function mode)} to
-@var{eshell-virtual-targets}. The first element is the device name;
-@code{function} may be either a lambda or a function name. If
-@code{mode} is nil, then the function is the output function; if it is
+by adding a list of the form @samp{("/dev/name" @var{function} @var{mode})} to
+@code{eshell-virtual-targets}. The first element is the device name;
+@var{function} may be either a lambda or a function name. If
+@var{mode} is nil, then the function is the output function; if it is
non-nil, then the function is passed the redirection mode as a
-symbol--@code{overwrite}, @code{append}, or @code{insert}--and the
-function is expected to return the output function.
+symbol--@code{overwrite} for @code{>}, @code{append} for @code{>>}, or
+@code{insert} for @code{>>>}--and the function is expected to return
+the output function.
The output function is called once on each line of output until
@code{nil} is passed, indicating end of output.
and to provide a common parent Customize group for the
modules.@footnote{ERC provides a similar module facility.} An Eshell
module is defined the same as any other library but one requirement: the
-module must define a Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
+module must define a Customize@footnote{@xref{Customization, , ,
+elisp, The Emacs Lisp Reference Manual}.}
group using @code{eshell-defgroup} (in place of @code{defgroup}) with
@code{eshell-module} as the parent group.@footnote{If the module has
no user-customizable options, then there is no need to define it as an
@example
(eval-when-compile
- (require 'cl)
+ (require 'cl-lib)
(require 'esh-mode)
(require 'eshell))
@cindex known bugs
@cindex bugs, known
-If you find a bug or misfeature, don't hesitate to let me know! Send
-email to @email{johnw@@gnu.org}. Feature requests should also be sent
-there. I prefer discussing one thing at a time. If you find several
+If you find a bug or misfeature, don't hesitate to report it, by
+using @kbd{M-x report-emacs-bug}. The same applies to feature requests.
+It is best to discuss one thing at a time. If you find several
unrelated bugs, please report them separately.
+@ignore
If you have ideas for improvements, or if you have written some
extensions to this package, I would like to hear from you. I hope you
find this package useful!
+@end ignore
-Below is a complete list of known problems with Eshell version 2.4.2,
+Below is a list of some known problems with Eshell version 2.4.2,
which is the version included with Emacs 22.
@table @asis
@item Make the shell spawning commands be visual
That is, make (@command{su}, @command{bash}, @command{telnet},
-@command{rlogin}, @command{rsh}, etc.) be part of
+@command{rlogin}, @command{rsh}, etc.)@: be part of
@code{eshell-visual-commands}. The only exception is if the shell is
being used to invoke a single command. Then, the behavior should be
based on what that command is.