X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/7a22490f14441898e1c4f6679f5924f097f3bb34..fd60bf6c902b47daadda6ebf442045dbe1328941:/doc/misc/eshell.texi diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 4604b262e7..e7c3c71afd 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -4,18 +4,19 @@ @settitle Eshell: The Emacs Shell @defindex cm @synindex vr fn +@documentencoding UTF-8 @c %**end of header @copying This manual is for Eshell, the Emacs shell. -Copyright @copyright{} 1999--2013 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', +Invariant Sections, 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''. @@ -61,20 +62,19 @@ modify this GNU manual.'' @node Top @top Eshell -Eshell is a shell-like command interpreter -implemented in Emacs Lisp. It invokes no external processes except for -those requested by the user. It is intended to be a functional -replacement for command shells such as @command{bash}, @command{zsh}, -@command{rc}, or @command{4dos}; since Emacs itself is capable of -handling the sort of tasks accomplished by those tools. +Eshell is a shell-like command interpreter implemented in Emacs Lisp. +It invokes no external processes except for those requested by the +user. It is intended to be an alternative to the IELM (@pxref{Lisp Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor}) +REPL for Emacs @emph{and} with an interface similar to command shells +such as @command{bash}, @command{zsh}, @command{rc}, or +@command{4dos}. @c This manual is updated to release 2.4 of Eshell. @insertcopying @end ifnottex @menu -* What is Eshell?:: A brief introduction to the Emacs Shell. -* Command basics:: The basics of command usage. +* Introduction:: A brief introduction to the Emacs Shell. * Commands:: * Expansion:: * Input/Output:: @@ -87,8 +87,9 @@ handling the sort of tasks accomplished by those tools. * Key Index:: @end menu -@node What is Eshell? -@chapter What is Eshell? +@node Introduction +@chapter Introduction +@section What is Eshell? @cindex what is Eshell? @cindex Eshell, what it is @@ -139,6 +140,24 @@ Any tool you use often deserves the time spent learning to master it. looks like: But don't let it fool you; once you know what's going on, it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} +@section What Eshell is not +@cindex Eshell, what it is not +@cindex what Eshell is not +@cindex what isn't Eshell? + +Eshell is @emph{not} a replacement for system shells such as +@command{bash} or @command{zsh}. Use Eshell when you want to move +text between Emacs and external processes; if you only want to pipe +output from one external process to another (and then another, and so +on), use a system shell, because Emacs's IO system is buffer oriented, +not stream oriented, and is very inefficient at such tasks. If you +want to write shell scripts in Eshell, don't; either write an elisp +library or use a system shell. + +Some things Eshell just doesn't do well. It fills the niche between +IELM and your system shell, where the peculiar use-cases lie, and it +is less than ideal outside that niche. + @menu * Contributors to Eshell:: People who have helped out! @end menu @@ -158,123 +177,31 @@ The following persons have made contributions to 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, requests, bug reports and encouragement. Thanks a lot! Without you there would be no new releases of Eshell. -@node Command basics -@chapter Basic overview - -A command shell is a means of entering verbally-formed commands. This -is really all that it does, and every feature described in this manual -is a means to that end. Therefore, it's important to take firm hold on -exactly what a command is, and how it fits in the overall picture of -things. - -@menu -* Commands verbs:: Commands always begin with a verb. -* Command arguments:: Some verbs require arguments. -@end menu - -@node Commands verbs -@section Commands verbs - -Commands are expressed using @dfn{script}, a special shorthand language -computers can understand with no trouble. Script is an extremely simple -language; oddly enough, this is what makes it look so complicated! -Whereas normal languages use a variety of embellishments, the form of a -script command is always: - -@example -@var{verb} [@var{arguments}] -@end example - -The verb expresses what you want your computer to do. There are a fixed -number of verbs, although this number is usually quite large. On the -author's computer, it reaches almost 1400 in number. But of course, -only a handful of these are really necessary. - -Sometimes, the verb is all that's written. A verb is always a single -word, usually related to the task it performs. @command{reboot} is a -good example. Entering that on GNU/Linux will reboot the -computer---assuming you have sufficient privileges. - -Other verbs require more information. These are usually very capable -verbs, and must be told specifically what to do. The extra information -is given in the form of @dfn{arguments}. For example, the -@command{echo} verb prints back whatever arguments you type. It -requires these arguments to know what to echo. A proper use of -@command{echo} looks like this: - -@example -echo This is an example of using echo! -@end example - -This script command causes the computer to echo back: ``This is an -example of using echo!'' - -Although command verbs are always simple words, like @command{reboot} or -@command{echo}, arguments may have a wide variety of forms. There are -textual arguments, numerical arguments---even Lisp arguments. -Distinguishing these different types of arguments requires special -typing, for the computer to know exactly what you mean. - -@node Command arguments -@section Command arguments - -Eshell recognizes several different kinds of command arguments: - -@enumerate -@item Strings (also called textual arguments) -@item Numbers (floating point or integer) -@item Lisp lists -@item Lisp symbols -@item Emacs buffers -@item Emacs process handles -@end enumerate - -Most users need to worry only about the first two. The third, Lisp lists, -occur very frequently, but almost always behind the scenes. - -Strings are the most common type of argument, and consist of nearly any -character. Special characters---those used by Eshell -specifically---must be preceded by a backslash (@samp{\}). When in doubt, it -is safe to add backslashes anywhere and everywhere. - -Here is a more complicated @command{echo} example: - -@example -echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar -@end example - -Beyond this, things get a bit more complicated. While not beyond the -reach of someone wishing to learn, it is definitely beyond the scope of -this manual to present it all in a simplistic manner. Get comfortable -with Eshell as a basic command invocation tool, and learn more about the -commands on your system; then come back when it all sits more familiarly -on your mind. Have fun! - @node Commands @chapter Commands @@ -353,9 +280,9 @@ sudo is an alias, defined as "*sudo $*" @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 +Some of the built-in commands have different behavior from their external counterparts, and some have no external counterpart. Most of these will print a usage message when given the @code{--help} option. @@ -515,7 +442,7 @@ Aliases are commands that expand to a longer input line. For example, 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). @@ -539,7 +466,7 @@ by @code{!foo:n}. 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. @@ -701,7 +628,7 @@ 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, The Z Shell Manual} -for full syntax. To customize the syntax and behaviour of globbing in +for full syntax. To customize the syntax and behavior of globbing in Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, The GNU Emacs Manual}.} groups ``eshell-glob'' and ``eshell-pred''. @@ -721,11 +648,11 @@ 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 @var{eshell-visual-commands}; for commands that are +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 @var{eshell-visual-subcommands}; and for +not @samp{git status} -- use @code{eshell-visual-subcommands}; and for commands that are visual only when passed certain options, use -@var{eshell-visual-options}. +@code{eshell-visual-options}. @section Redirection Redirection is mostly the same in Eshell as it is in other command @@ -738,19 +665,19 @@ virtual devices. 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 >>> #} -inserts the string @code{"hello"} into the @code{*scratch*} buffer. +inserts the string @code{"hello"} into the @file{*scratch*} buffer. -@var{eshell-virtual-targets} is a list of mappings of virtual device +@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 -non-nil, then the function is passed the redirection mode as a +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 @code{nil}, then the function is the output function; if it is +non-@code{nil}, then the function is passed the redirection mode as a symbol--@code{overwrite} for @code{>}, @code{append} for @code{>>}, or @code{insert} for @code{>>>}--and the function is expected to return the output function. @@ -774,7 +701,7 @@ Eshell module.} You also need to load the following as shown: @example (eval-when-compile - (require 'cl) + (require 'cl-lib) (require 'esh-mode) (require 'eshell))