[Emacs-diffs] /srv/bzr/emacs/emacs-23 r100663: * doc/misc/eshell.texi: Fill most of the missing sections.

[Stefan Monnier]

------------------------------------------------------------
revno: 100663
author: Aidan Gauland <address@hidden>
committer: Stefan Monnier <address@hidden>
branch nick: emacs-23
timestamp: Fri 2013-02-08 09:44:17 -0500
message:
  * doc/misc/eshell.texi: Fill most of the missing sections.
modified:
  doc/misc/eshell.texi

=== modified file 'doc/misc/eshell.texi'
--- a/doc/misc/eshell.texi      2012-01-11 07:52:35 +0000
+++ b/doc/misc/eshell.texi      2013-02-08 14:44:17 +0000
@@ -2,6 +2,7 @@
 @c %**start of header
 @setfilename ../../info/eshell
 @settitle Eshell: The Emacs Shell
address@hidden cm
 @synindex vr fn
 @c %**end of header
 
@@ -44,7 +45,7 @@
 @c -release-
 @end ignore
 @sp 3
address@hidden John Wiegley
address@hidden John Wiegley & Aidan Gauland
 @c -date-
 
 @page
@@ -77,16 +78,15 @@
 * What is Eshell?::             A brief introduction to the Emacs Shell.
 * Command basics::              The basics of command usage.
 * Commands::
-* Arguments::
+* Expansion::
 * Input/Output::
-* Process control::
 * Extension modules::
-* Extras and Goodies::
 * Bugs and ideas::              Known problems, and future ideas.
 * GNU Free Documentation License:: The license for this documentation.
 * Concept Index::
 * Function and Variable Index::
 * Key Index::
+* Command Index::
 @end menu
 
 @node What is Eshell?
@@ -280,47 +280,183 @@
 @node Commands
 @chapter Commands
 
+In a command shell, everything is done by invoking commands.  This
+chapter covers command invocations in Eshell, including the command
+history and invoking commands in a script file.
+
 @menu
 * Invocation::
-* Completion::
+* Arguments::
+* Variables::
+* Built-ins::
 * Aliases::
 * History::
+* Completion::
+* for loop::
 * Scripts::
-* Built-ins::
 @end menu
 
-Essentially, a command shell is all about invoking commands---and
-everything that entails.  So understanding how Eshell invokes commands
-is the key to comprehending how it all works.
-
 @node Invocation
 @section Invocation
-
 Unlike regular system shells, Eshell never invokes kernel functions
 directly, such as @code{exec(3)}.  Instead, it uses the Lisp functions
 available in the Emacs Lisp library.  It does this by transforming the
-command you specify into a callable Lisp address@hidden see the Lisp
-form that will be invoked, type: @samp{eshell-parse-command "echo
-hello"}}
-
-This transformation, from the string of text typed at the command
-prompt, to the ultimate invocation of either a Lisp function or external
-command, follows these steps:
-
address@hidden
address@hidden Parse the command string into separate arguments.
address@hidden
address@hidden enumerate
-
address@hidden Completion
address@hidden Completion
-
address@hidden Aliases
address@hidden Aliases
-
address@hidden History
address@hidden History
-
+input line into a callable Lisp address@hidden see the Lisp form that will be 
invoked, type: @samp{eshell-parse-command "echo hello"}}
+
+The command can be either an Elisp function or an external command.
+Eshell looks first for an @ref{Aliases, alias} with the same name as the
+command, then a @ref{Built-ins, built-in command} or a function with the
+same name; if there is no match, it then tries to execute it as an
+external command.
+
+The semicolon (@code{;}) can be used to separate multiple command
+invocations on a single line.  A command invocation followed by an
+ampersand (@code{&}) will be run in the background.  Eshell has no job
+control, so you can not suspend or background the current process, or
+bring a background process into the foreground.  That said, background
+processes invoked from Eshell can be controlled the same way as any
+other background process in Emacs.
+
address@hidden Arguments
address@hidden Arguments
+Command arguments are passed to the functions as either strings or
+numbers, depending on what the parser thinks they look like.  If you
+need to use a function that takes some other data type, you will need to
+call it in an Elisp expression (which can also be used with
address@hidden, expansions}).  As with other shells, you can
+escape special characters and spaces with the backslash (@code{\}) and
+the single (@code{''}) and double (@code{""}) quotes.
+
address@hidden Built-ins
+
address@hidden Built-in commands
+Several commands are built-in in Eshell.  In order to call the
+external variant of a built-in command @code{foo}, you could call
address@hidden  Usually, this should not be necessary.  You can check
+what will be applied by the @code{which} command:
+
address@hidden
+~ $ which ls
+eshell/ls is a compiled Lisp function in `em-ls.el'
+~ $ which *ls
+/bin/ls
address@hidden example
+
address@hidden 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}.
+
+Some of the built-in commands have different behaviour from their
+external counterparts, and some have no external counterpart.  Most of
+these will print a useage message when given the @code{--help} option.
+
address@hidden @code
+
address@hidden addpath
address@hidden addpath
+Adds a given path or set of paths to the PATH environment variable, or,
+with no arguments, prints the current paths in this variable.
+
address@hidden alias
address@hidden alias
+Define an alias (@pxref{Aliases}).  This does not add it to the aliases
+file.
+
address@hidden date
address@hidden date
+Similar to, but slightly different from, the GNU Coreutils
address@hidden command.
+
address@hidden define
address@hidden define
+Define a varalias.  @xref{Variable Aliases, , , elisp}.
+
address@hidden diff
address@hidden diff
+Use Emacs's internal @code{diff} (not to be confused with
address@hidden).  @xref{Comparing Files, , , elisp}.
+
address@hidden grep
address@hidden grep
address@hidden agrep
address@hidden agrep
address@hidden egrep
address@hidden egrep
address@hidden fgrep
address@hidden fgrep
address@hidden glimpse
address@hidden glimpse
+The @command{grep} commands are compatible with GNU @command{grep}, but
+use Emacs's internal @code{grep} instead.
+
address@hidden info
address@hidden info
+Same as the external @command{info} command, but uses Emacs's internal
+Info reader.
+
address@hidden jobs
address@hidden jobs
+List subprocesses of the Emacs process, if any, using the function
address@hidden
+
address@hidden kill
address@hidden kill
+Kill processes.  Takes a PID or a process object and an optional
+signal specifier.
+
address@hidden listify
address@hidden listify
+Eshell version of @code{list}.  Allows you to create a list using Eshell
+syntax, rather than Elisp syntax.  For example, @samp{listify foo bar}
+and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}.
+
address@hidden locate
address@hidden locate
+Alias to Emacs's @code{locate} function, which simply runs the external
address@hidden command and parses the results.  @xref{Dired and `find', , , 
elisp}.
+
address@hidden make
address@hidden make
+Run @command{make} through @code{compile}.  @xref{Running Compilations under 
Emacs, , , elisp}.
+
address@hidden occur
address@hidden occur
+Alias to Emacs's @code{occur}.  @xref{Other Search-and-Loop Commands, , , 
elisp}.
+
address@hidden printnl
address@hidden printnl
+Print the arguments separated by newlines.
+
address@hidden cd
address@hidden cd
+This command changes the current working directory.  Usually, it is
+invoked as @samp{cd foo} where @file{foo} is the new working directory.
+But @command{cd} knows about a few special arguments:
+
+When it receives no argument at all, it changes to the home directory.
+
+Giving the command @samp{cd -} changes back to the previous working
+directory (this is the same as @samp{cd $-}).
+
+The command @samp{cd =} shows the directory stack.  Each line is
+numbered.
+
+With @samp{cd =foo}, Eshell searches the directory stack for a directory
+matching the regular expression @samp{foo} and changes to that
+directory.
+
+With @samp{cd -42}, you can access the directory stack by number.
+
address@hidden su
address@hidden su
address@hidden sudo
address@hidden sudo
+Uses TRAMP's @command{su} or @command{sudo} method to run a command via
address@hidden or @command{sudo}.
+
address@hidden table
+
address@hidden Built-in variables
 Eshell knows a few built-in variables:
 
 @table @code
@@ -350,51 +486,28 @@
 
 @end table
 
address@hidden Scripts
address@hidden Scripts
-
-
address@hidden Built-ins
address@hidden Built-in commands
-
-Several commands are built-in in Eshell.  In order to call the
-external variant of a built-in command @code{foo}, you could call
address@hidden  Usually, this should not be necessary.  You can check
-what will be applied by the @code{which} command:
-
address@hidden
-~ $ which ls
-eshell/ls is a compiled Lisp function in `em-ls.el'
-~ $ which *ls
-/bin/ls
address@hidden example
-
-Some of the built-in commands have a special behaviour in Eshell:
-
address@hidden @code
-
address@hidden cd
address@hidden cd
-This command changes the current working directory.  Usually, it is
-invoked as @samp{cd foo} where @file{foo} is the new working
-directory.  But @code{cd} knows about a few special arguments:
-
-When it receives no argument at all, it changes to the home directory.
-
-Giving the command @samp{cd -} changes back to the previous working
-directory (this is the same as @samp{cd $-}).
-
-The command @samp{cd =} shows the directory stack.  Each line is
-numbered.
-
-With @samp{cd =foo}, Eshell searches the directory stack for a
-directory matching the regular expression @samp{foo} and changes to
-that directory.
-
-With @samp{cd -42}, you can access the directory stack by number.
-
address@hidden history
address@hidden history
address@hidden Variables
address@hidden Variables
+Since Eshell is just an Emacs address@hidden Loop}, it
+does not have its own scope, and simply stores variables the same you
+would in an Elisp program.  Eshell provides a command version of
address@hidden for convenience.
+
address@hidden Aliases
address@hidden Aliases
+
+Aliases are commands that expand to a longer input line.  For example,
address@hidden is a common alias for @code{ls -l}, and would be defined
+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},
+which you can also edit directly (although you will have to manually
+reload it).
+
address@hidden History
address@hidden History
address@hidden history
 The @samp{history} command shows all commands kept in the history ring
 as numbered list.  If the history ring contains
 @code{eshell-history-size} commands, those numbers change after every
@@ -410,70 +523,226 @@
 argument of the last command beginning with @code{foo} is accessible
 by @code{!foo:n}.
 
address@hidden su
address@hidden su
address@hidden sudo
address@hidden sudo
address@hidden and @code{sudo} work as expected: they apply the following
-commands (@code{su}), or the command being an argument (@code{sudo})
-under the permissions of somebody else.
-
-This does not work only on
-the local host, but even on a remote one, when
address@hidden is a remote file name.  The necessary
-proxy configuration of Tramp is performed
address@hidden
-automatically, @ref{Multi-hops, , , tramp}.
address@hidden ifinfo
address@hidden
-automatically.
address@hidden ifnotinfo
-Example:
+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,
+such as Bash, Eshell can not be configured to keep a history ring of a
+different size than that of the history file.
+
+Since the default buffer navigation and searching key-bindings are
+still present in the Eshell buffer, the commands for history
+navigation and searching are bound to different keys:
+
address@hidden @kbd
address@hidden M-r
address@hidden M-s
+History I-search.
+
address@hidden M-p
address@hidden M-n
+Previous and next history line.  If there is anything on the input
+line when you run these commands, they will instead jump to the
+precious or next line that begins with that string.
address@hidden table
+
address@hidden Completion
address@hidden Completion
+Eshell uses the pcomplete package for programmable completion, similar
+to that of other command shells.  Argument completion differs depending
+on the preceding command: for example, possible completions for
address@hidden are only directories, while @command{rm} completions can
+be directories @emph{and} files.  Eshell provides predefined completions
+for the built-in functions and some common external commands, and you
+can define your own for any command.
+
+Eshell completion also works for lisp forms and glob patterns. If the
+point is on a lisp form, then @key{TAB} will behave similarly to completion
+in @code{elisp-mode} and @code{lisp-interaction-mode}.  For glob
+patterns, If there are few enough possible completions of the patterns,
+they will be cycled when @key{TAB} is pressed, otherwise it will be removed
+from the input line and the possible completions will be listed.
+
+If you want to see the entire list of possible completions when it's
+below the cycling threshold, press @kbd{M-?}.
+
address@hidden pcomplete
+Pcomplete, short for programmable completion, is the completion
+library originally written for Eshell, but usable for command
address@hidden completion as opposed to code completion,
+which is a beyond the scope of pcomplete.}  in other modes.
+
+Completions are defined as functions (with @code{defun}) named
address@hidden/COMMAND}, where @code{COMMAND} is the name of the
+command for which this function provides completions; you can also name
+the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions
+for a specific major mode.
+
address@hidden for loop
address@hidden @code{for} loop
+Because Eshell commands can not (easily) be combined with lisp forms,
+Eshell provides a command-oriented @command{for}-loop for convenience.
+The syntax is as follows:
 
 @example
-~ $ cd /ssh:otherhost:/etc
-/ssh:user@@otherhost:/etc $ sudo find-file shadow
address@hidden VAR in TOKENS @{ command invocation(s) @}}
 @end example
 
address@hidden table
-
-
address@hidden Arguments
address@hidden Arguments
+where @samp{TOKENS} is a space-separated sequence of values of
address@hidden for each iteration.  This can even be the output of a
+command if @samp{TOKENS} is replaced with @address@hidden command invocation 
@}}.
+
address@hidden Scripts
address@hidden Scripts
address@hidden source
address@hidden eshell-source-file
+You can run Eshell scripts much like scripts for other shells; the main
+difference is that since Eshell is not a system command, you have to run
+it from within Emacs.  An Eshell script is simply a file containing a
+sequence of commands, as with almost any other shell script.  Scripts
+are invoked from Eshell with @command{source}, or from anywhere in Emacs
+with @code{eshell-source-file}.
+
address@hidden .
+If you wish to load a script into your @emph{current} environment,
+rather than in a subshell, use the @code{.} command.
+
address@hidden Expansion
address@hidden Expansion
+Expansion in a command shell is somewhat like macro expansion in macro
+parsers (such as @command{cpp} and @command{m4}), but in a command
+shell, they are less often used for constants, and usually for using
+variables and string address@hidden has no
+string-manipulation expansions because the Elisp library already
+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 address@hidden Entering just @samp{$var} at the prompt
+is equivalent to entering the value of @code{var} at the prompt.}
 
 @menu
-* The Parser::
-* Variables::
-* Substitution::
+* Dollars Expansion::
 * Globbing::
-* Predicates::
 @end menu
 
address@hidden The Parser
address@hidden The Parser
-
address@hidden Variables
address@hidden Variables
-
address@hidden Substitution
address@hidden Substitution
address@hidden Dollars Expansion
address@hidden Dollars Expansion
+Eshell has different @code{$} expansion syntax from other shells.  There
+are some similarities, but don't let these lull you into a false sense
+of familiarity.
+
address@hidden @code
+
address@hidden $var
+Expands to the value bound to @code{var}.  This is the main way to use
+variables in command invocations.
+
address@hidden $#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}).
+
address@hidden $(lisp)
+Expands to the result of evaluating the S-expression @code{(lisp)}.  On
+its own, this is identical to just @code{(lisp)}, but with the @code{$},
+it can be used in a string, such as @samp{/some/path/$(lisp).txt}.
+
address@hidden address@hidden@}
+Returns the output of @command{command}, which can be any valid Eshell
+command invocation, and may even contain expansions.
+
address@hidden $var[i]
+Expands to the @code{i}th element of the value bound to @code{var}.  If
+the value is a string, it will be split at whitespace to make it a list.
+Again, raises an error if the value is not a sequence.
+
address@hidden $var[: i]
+As above, but now splitting occurs at the colon character.
+
address@hidden $var[: i j]
+As above, but instead of returning just a string, it now returns a list
+of two strings.  If the result is being interpolated into a larger
+string, this list will be flattened into one big string, with each
+element separated by a space.
+
address@hidden $var["\\\\" i]
+Separate on backslash characters.  Actually, the first argument -- if it
+doesn't have the form of a number, or a plain variable name -- can be
+any regular expression.  So to split on numbers, use @samp{$var["[0-9]+" 10 
20]}.
+
address@hidden $var[hello]
+Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
+an alist (@pxref{Association List Type, Association Lists, , elisp}).
+
address@hidden $#var[hello]
+Returns the length of the cdr of the element of @code{var} who car is equal
+to @code{"hello"}.
+
address@hidden table
 
 @node Globbing
 @section Globbing
-
address@hidden Predicates
address@hidden Predicates
-
+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}
+for full syntax.  To customize the syntax and behaviour of globbing in
+Eshell see the address@hidden@xref{Customization Settings, Customize, , 
elisp}.}
+groups ``eshell-glob'' and ``eshell-pred''.
 
 @node Input/Output
 @chapter Input/Output
-
address@hidden Process control
address@hidden Process control
-
+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
address@hidden
+
+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
+virtual devices.
+
address@hidden is a list of mappings of virtual device
+names to functions.  Eshell comes with two virtual devices:
address@hidden/dev/kill}, which sends the text to the kill ring, and
address@hidden/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
address@hidden  The first element is the device name;
address@hidden may be either a lambda or a function name.  If
address@hidden is nil, then the function is the output function; if it is
+non-nil, then the function is passed the redirection mode as a
address@hidden, @code{append}, or @code{insert}--and the
+function is expected to return the output function.
+
+The output function is called once on each line of output until
address@hidden is passed, indicating end of output.
 
 @node Extension modules
 @chapter Extension modules
+Eshell provides a facility for defining extension modules so that they
+can be disabled and enabled without having to unload and reload them,
+and to provide a common parent Customize group for the
address@hidden provides a similar module facility.}  An Eshell
+module is defined the same as any other library but one requirement: the
+module must define a address@hidden@xref{Customization Settings, Customize, , 
elisp}.}
+group using @code{eshell-defgroup} (in place of @code{defgroup}) with
address@hidden as the parent address@hidden the module has
+no user-customizable options, then there is no need to define it as an
+Eshell module.}  You also need to load the following as shown:
+
address@hidden
+(eval-when-compile
+  (require 'cl)
+  (require 'esh-mode)
+  (require 'eshell))
+
+(require 'esh-util)
address@hidden example
 
 @menu
 * Writing a module::
@@ -482,7 +751,6 @@
 * Key rebinding::
 * Smart scrolling::
 * Terminal emulation::
-* Built-in UNIX commands::
 @end menu
 
 @node Writing a module
@@ -503,13 +771,6 @@
 @node Terminal emulation
 @section Terminal emulation
 
address@hidden Built-in UNIX commands
address@hidden Built-in UNIX commands
-
-
address@hidden Extras and Goodies
address@hidden Extras and Goodies
-
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
@@ -518,6 +779,8 @@
 @cindex email to the author
 @cindex FAQ
 @cindex problems, list of common
address@hidden known bugs
address@hidden 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
@@ -528,16 +791,7 @@
 extensions to this package, I would like to hear from you.  I hope you
 find this package useful!
 
address@hidden
-* Known problems::
address@hidden menu
-
address@hidden Known problems
address@hidden Known problems
address@hidden known bugs
address@hidden bugs, known
-
-Below is complete list of known problems with Eshell version 2.4.2,
+Below is a complete list of known problems with Eshell version 2.4.2,
 which is the version included with Emacs 22.
 
 @table @asis
@@ -545,7 +799,7 @@
 
 @item Differentiate between aliases and functions
 
-Allow for a bash-compatible syntax, such as:
+Allow for a Bash-compatible syntax, such as:
 
 @example
 alias arg=blah
@@ -829,7 +1083,7 @@
 It would provide syntax, abbrev, highlighting and indenting support like
 @code{emacs-lisp-mode} and @code{shell-mode}.
 
address@hidden In the history mechanism, finish the @command{bash}-style support
address@hidden In the history mechanism, finish the Bash-style support
 
 This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
 from @samp{!:1*}.
@@ -999,6 +1253,11 @@
 
 @printindex fn
 
address@hidden Command Index
address@hidden Command Index
+
address@hidden cm
+
 @node Key Index
 @unnumbered Key Index