X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/08861c5cb87e91e83e5b0bf53cb53c1377434c8f..19ae0deb1c8c9475eb81daf7876cec5a44b5d5e0:/doc/misc/eshell.texi

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 5d6bd73a6c..c32aa659e1 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -9,25 +9,19 @@
 This manual is for Eshell, the Emacs shell.
 
 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
-2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+2005, 2006, 2007, 2008, 2009, 2010 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.2 or
+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'', 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'' in the Emacs manual.
-
-(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.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License.  If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+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''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual.  Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
 @end quotation
 @end copying
 
@@ -36,8 +30,6 @@ license to the document, as described in section 6 of the license.
 * Eshell: (eshell).     A command shell implemented in Emacs Lisp.
 @end direntry
 
-@setchapternewpage on
-
 @titlepage
 @sp 4
 @c The title is printed in a large font.
@@ -70,13 +62,15 @@ license to the document, as described in section 6 of the license.
 @node Top, What is Eshell?, (dir), (dir)
 @top Eshell
 
-This manual documents Eshell, a shell-like command interpretor
+Eshell is a shell-like command interpretor
 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.
 @c This manual is updated to release 2.4 of Eshell.
+
+@insertcopying
 @end ifnottex
 
 @menu
@@ -340,6 +334,20 @@ This variable always contains the current working directory.
 This variable always contains the previous working directory (the
 current working directory from before the last @code{cd} command).
 
+@item $_
+@vindex $_
+It refers to the last argument of the last command.
+
+@item $$
+@vindex $$
+This is the result of the last command.  In case of an external
+command, it is @code{t} or @code{nil}.
+
+@item $?
+@vindex $?
+This variable contains the exit code of the last command (0 or 1 for
+Lisp functions, based on successful completion).
+
 @end table
 
 @node Scripts
@@ -349,7 +357,19 @@ current working directory from before the last @code{cd} command).
 @node Built-ins
 @section Built-in commands
 
-Here is a list of built-in commands that Eshell knows about:
+Several commands are built-in in Eshell.  In order to call the
+external variant of a built-in command @code{foo}, you could call
+@code{*foo}.  Usually, this should not be necessary.  You can check
+what will be applied by the @code{which} command:
+
+@example
+~ $ which ls
+eshell/ls is a compiled Lisp function in `em-ls.el'
+~ $ which *ls
+/bin/ls
+@end example
+
+Some of the built-in commands have a special behaviour in Eshell:
 
 @table @code
 
@@ -373,6 +393,48 @@ that directory.
 
 With @samp{cd -42}, you can access the directory stack by number.
 
+@item history
+@findex 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
+command invocation, therefore the @samp{history} command shall be
+applied before using the expansion mechanism with history numbers.
+
+The n-th entry of the history ring can be applied with the @samp{!n}
+command.  If @code{n} is negative, the entry is counted from the end
+of the history ring.
+
+@samp{!foo} expands to the last command beginning with @code{foo}, and
+@samp{!?foo} to the last command containing @code{foo}.  The n-th
+argument of the last command beginning with @code{foo} is accessible
+by @code{!foo:n}.
+
+@item su
+@findex su
+@itemx sudo
+@findex sudo
+@code{su} 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
+@code{default-directory} is a remote file name.  The necessary
+proxy configuration of Tramp is performed
+@ifinfo
+automatically, @ref{Multi-hops, , , tramp}.
+@end ifinfo
+@ifnotinfo
+automatically.
+@end ifnotinfo
+Example:
+
+@example
+~ $ cd /ssh:otherhost:/etc
+/ssh:user@@otherhost:/etc $ sudo find-file shadow
+@end example
+
 @end table