* doc/misc/eshell.texi: Fill most of the missing sections.

2 files changed, 474 insertions, 231 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 1b454741fc0..db3bd460055 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,7 @@
+2013-02-08  Aidan Gauland  <aidalgol@no8wireless.co.nz>
+
+        * eshell.texi: Fill most of the missing sections.
+
 2013-02-07  Bastien Guerry  <bzg@gnu.org>
 
         * org.texi (References): Clarify an example.
@@ -17,8 +21,8 @@
         from ede new.
         (Simple projects): Re-write to not talk about ede-simple-project
         which is deprecated, and instead use the term to mean projects
-        that don't do much management, just project wrapping.  Add
-        ede-generic-project link.
+        that don't do much management, just project wrapping.
+        Add ede-generic-project link.
         (ede-generic-project): New node (bug#11441).
 
 2013-02-03  Glenn Morris  <rgm@gnu.org>
@@ -72,8 +76,7 @@
         * ede.texi (Top): Rename from top, all uses changed.
         * eshell.texi: Add missing argument to @sp.
         * forms.texi (Top): Reorder menu to match structure.
-        * htmlfontify.texi (Customisation): Add missing @item in
-        @enumerate.
+        * htmlfontify.texi (Customisation): Add missing @item in @enumerate.
         * org.texi (Advanced features): Add missing argument for @item.
         (Property searches): Use @backslashchar{} in macro argument.
         * pcl-cvs.texi: Add missing argument to @sp.
@@ -212,8 +215,8 @@
         * org.texi (Summary, Code block specific header arguments)
         (Code block specific header arguments)
         (Header arguments in function calls, var, noweb)
-        (Results of evaluation, Code evaluation security): Small
-        reformatting: add a blank line before some example.
+        (Results of evaluation, Code evaluation security):
+        Small reformatting: add a blank line before some example.
 
         * org.texi (System-wide header arguments)
         (Header arguments in Org mode properties, Conflicts)
@@ -222,8 +225,7 @@
 
         * org.texi (Comment lines): Fix description of the comment syntax.
 
-        * org.texi (Installation): Mention "make test" in the correct
-        section.
+        * org.texi (Installation): Mention "make test" in the correct section.
 
 2012-12-02  Michael Albinus  <michael.albinus@gmx.de>
 
@@ -271,8 +273,8 @@
 
 2012-11-08  Chong Yidong  <cyd@gnu.org>
 
-        * url.texi (Introduction): Rename from Getting Started.  Rewrite
-        the introduction.
+        * url.texi (Introduction): Rename from Getting Started.
+        Rewrite the introduction.
         (URI Parsing): Rewrite.  Omit the obsolete attributes slot.
 
 2012-11-07  Glenn Morris  <rgm@gnu.org>
@@ -372,14 +374,14 @@
 
 2012-10-26  Bastien Guerry  <bzg@gnu.org>
 
-        * org.texi (Installation): Update the link to Org's ELPA.  Also
-        don't mention org-install.el anymore as the replacement file
+        * org.texi (Installation): Update the link to Org's ELPA.
+        Also don't mention org-install.el anymore as the replacement file
         org-loaddefs.el is now loaded by org.el.
 
 2012-10-25  Michael Albinus  <michael.albinus@gmx.de>
 
-        * tramp.texi (Frequently Asked Questions): Mention
-        `tramp-completion-reread-directory-timeout' for performance
+        * tramp.texi (Frequently Asked Questions):
+        Mention `tramp-completion-reread-directory-timeout' for performance
         improvement.
 
 2012-10-25  Glenn Morris  <rgm@gnu.org>
@@ -483,8 +485,7 @@
         (Imprint): Mention Wolfgang in list of contributors.
         (Creating Citations): Give a hint about how to
         auto-revert the BibTeX database file when using external editors.
-        (Referencing Labels): Simplify section about reference macro
-        cycling.
+        (Referencing Labels): Simplify section about reference macro cycling.
         (Options (Referencing Labels)): Adapt to new structure of
         `reftex-ref-style-alist'.
         (Referencing Labels, Reference Styles): Document changes in the
@@ -502,8 +503,8 @@
         (Referencing Labels): Update regarding reference styles.
         (Citation Styles): Mention support for ConTeXt.
         (Options (Defining Label Environments)): Fix typo.
-        (Options (Creating Citations)): Document
-        `reftex-cite-key-separator'.
+        (Options (Creating Citations)):
+        Document `reftex-cite-key-separator'.
 
 2012-09-30  Achim Gratz  <Stromeko@Stromeko.DE>
 
@@ -535,8 +536,8 @@
 
 2012-09-30  Bastien Guerry  <bzg@gnu.org>
 
-        * org.texi (Installation, Feedback, Batch execution): Use
-        (add-to-list 'load-path ... t) for the contrib dir.
+        * org.texi (Installation, Feedback, Batch execution):
+        Use (add-to-list 'load-path ... t) for the contrib dir.
 
         * org.texi (results): Update documentation for ":results drawer"
         and ":results org".
@@ -553,18 +554,16 @@
 
         * org.texi (History and Acknowledgments): Fix typo.
 
-        * org.texi (History and Acknowledgments): Add my own
-        acknowledgments.
+        * org.texi (History and Acknowledgments): Add my own acknowledgments.
 
         * org.texi (Agenda commands): Document the new command and the new
         option.
 
         * org.texi (Agenda commands): Delete `org-agenda-action' section.
-        (Agenda commands): Reorder.  Document `*' to toggle persistent
-        marks.
+        (Agenda commands): Reorder.  Document `*' to toggle persistent marks.
 
-        * org.texi (Agenda dispatcher): Mention
-        `org-toggle-agenda-sticky'.
+        * org.texi (Agenda dispatcher):
+        Mention `org-toggle-agenda-sticky'.
         (Agenda commands, Exporting Agenda Views): Fix typo.
 
         * org.texi (Templates in contexts, Setting Options): Update to
@@ -582,8 +581,7 @@
         * org.texi (Formula syntax for Lisp): Reformat.
 
         * org.texi (Special properties, Column attributes)
-        (Agenda column view): Document the new special property
-        CLOCKSUM_T.
+        (Agenda column view): Document the new special property CLOCKSUM_T.
 
         * org.texi (Template expansion): Document the new %l template.
 
@@ -739,8 +737,8 @@
         (Unsafe Simplifications):  Mention `m E'.
         (Simplification of Units): Mention `m U'.
         (Trigonometric/Hyperbolic Functions, Reducing and Mapping)
-        (Kinds of Declarations, Functions for Declarations):  Mention
-        "algebraic simplifications" instead of `a s'.
+        (Kinds of Declarations, Functions for Declarations):
+        Mention "algebraic simplifications" instead of `a s'.
         (Algebraic Entry): Remove mention of default simplifications.
 
 2012-07-30  Jay Belanger  <jay.p.belanger@gmail.com>
@@ -772,8 +770,8 @@
 
 2012-07-06  Michael Albinus  <michael.albinus@gmx.de>
 
-        * tramp.texi (Multi-hops): Introduce
-        `tramp-restricted-shell-hosts-alist'.
+        * tramp.texi (Multi-hops):
+        Introduce `tramp-restricted-shell-hosts-alist'.
 
 2012-06-26  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
@@ -965,8 +963,8 @@
         (Synchronous Methods): Remove obsolete dbus-call-method-non-blocking.
         (Asynchronous Methods): Fix description of
         dbus-call-method-asynchronously.
-        (Receiving Method Calls): Fix some minor errors.  Add
-        dbus-interface-emacs.
+        (Receiving Method Calls): Fix some minor errors.
+        Add dbus-interface-emacs.
         (Signals): Describe unicast signals and the new match rules.
         (Alternative Buses): Add the PRIVATE optional argument to
         dbus-init-bus.  Describe its new return value.  Add dbus-setenv.
@@ -999,8 +997,8 @@
 
 2012-04-09  Eli Zaretskii  <eliz@gnu.org>
 
-        * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add
-        emacs-gnutls.
+        * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean):
+        Add emacs-gnutls.
         ($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets.
 
 2012-04-09  Teodor Zlatanov  <tzz@lifelogs.com>
@@ -1098,12 +1096,11 @@
 2012-04-01  Carsten Dominik  <carsten.dominik@gmail.com>
 
         * org.texi (MobileOrg): Change the wording to reflect that the
-        Android Version is no longer just the little brother of the iOS
-        version.
+        Android Version is no longer just the little brother of the iOS version.
 
 2012-04-01  Eric Schulte  <eric.schulte@gmx.com>
 
-        * org.texi (Key bindings and useful functions): Updated babel key
+        * org.texi (Key bindings and useful functions): Update babel key
         binding documentation in manual.
 
 2012-04-01  Eric Schulte  <eric.schulte@gmx.com>
@@ -1204,8 +1201,8 @@
 
 2012-02-13  Lars Ingebrigtsen  <larsi@gnus.org>
 
-        * gnus.texi (Customizing the IMAP Connection): Mention
-        nnimap-record-commands.
+        * gnus.texi (Customizing the IMAP Connection):
+        Mention nnimap-record-commands.
 
 2012-02-10  Glenn Morris  <rgm@gnu.org>
 
@@ -1253,8 +1250,7 @@
 2012-01-03  Eric Schulte  <eric.schulte@gmx.com>
 
         * org.texi (Noweb reference syntax): Adding documentation of
-        the `*org-babel-use-quick-and-dirty-noweb-expansion*'
-        variable.
+        the `*org-babel-use-quick-and-dirty-noweb-expansion*' variable.
 
 2012-01-03  Bastien Guerry  <bzg@gnu.org>
 
@@ -1276,8 +1272,8 @@
 
 2012-01-03  Bernt Hansen  <bernt@norang.ca>
 
-        * org.texi (Agenda commands): Document
-        `org-clock-report-include-clocking-task'.
+        * org.texi (Agenda commands):
+        Document `org-clock-report-include-clocking-task'.
 
 2012-01-03  Bastien Guerry  <bzg@gnu.org>
 
@@ -1327,8 +1323,7 @@
 
 2012-01-03  Thomas Dye  <dk@poto.local>
 
-        * org.texi: Changed DATA to NAME in Working With Source Code
-        section.
+        * org.texi: Changed DATA to NAME in Working With Source Code section.
 
 2012-01-03  Tom Dye  <tsd@tsdye.com>
 
@@ -1362,8 +1357,8 @@
 
 2012-01-03  Eric Schulte  <schulte.eric@gmail.com>
 
-        * org.texi (Buffer-wide header arguments): Update
-        documentation to reflect removal of #+PROPERTIES.
+        * org.texi (Buffer-wide header arguments):
+        Update documentation to reflect removal of #+PROPERTIES.
 
 2012-01-03  Carsten Dominik  <carsten.dominik@gmail.com>
 
@@ -1382,8 +1377,7 @@
 
 2012-01-03  Tom Dye  <tsd@tsdye.com>
 
-        * org.texi: Added a line to specify that header arguments are
-        lowercase.
+        * org.texi: Added a line to specify that header arguments are lowercase.
 
 2012-01-03  Tom Dye  <tsd@tsdye.com>
 
@@ -1396,9 +1390,8 @@
 
 2012-01-03  David Maus  <dmaus@ictsoc.de>
 
-        * org.texi (Exporting Agenda Views, Extracting agenda
-        information): Fix command line syntax, quote symbol parameter
-        values.
+        * org.texi (Exporting Agenda Views, Extracting agenda information):
+        Fix command line syntax, quote symbol parameter values.
 
 2012-01-03  David Maus  <dmaus@ictsoc.de>
 
@@ -1524,7 +1517,7 @@
 
         * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
         release 8.3.
-        (Preface): Updated support information.
+        (Preface): Update support information.
         (From Bill Wohler): Reset text to original version.  As a
         historical quote, the tense should be correct in the time that it
         was written.
@@ -1564,8 +1557,7 @@
 
 2011-08-15  Bastien Guerry  <bzg@gnu.org>
 
-        * org.texi (Languages): Add Lilypond and Awk as supported
-        languages.
+        * org.texi (Languages): Add Lilypond and Awk as supported languages.
 
 2011-08-15  Achim Gratz  <stromeko@nexgo.de>
 
@@ -1583,8 +1575,7 @@
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
         * org.texi (Results of evaluation): More explicit about the
-        mechanism through which interactive evaluation of code is
-        performed.
+        mechanism through which interactive evaluation of code is performed.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
@@ -1663,13 +1654,11 @@
 
 2011-08-15  Puneeth Chaganti  <punchagan@gmail.com>
 
-        * org.texi (Agenda commands): Doc for function option to bulk
-        action.
+        * org.texi (Agenda commands): Doc for function option to bulk action.
 
 2011-08-15  Carsten Dominik  <carsten.dominik@gmail.com>
 
-        * org.texi (Template expansion): Document new %<...> template
-        escape.
+        * org.texi (Template expansion): Document new %<...> template escape.
 
 2011-08-15  Carsten Dominik  <carsten.dominik@gmail.com>
 
@@ -1689,8 +1678,7 @@
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
-        * org.texi (padline): Documentation of the new padline header
-        argument.
+        * org.texi (padline): Documentation of the new padline header argument.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
@@ -1711,8 +1699,7 @@
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
-        * org.texi (var): Clarification of indexing into tabular
-        variables.
+        * org.texi (var): Clarification of indexing into tabular variables.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
@@ -1726,8 +1713,8 @@
 
 2011-08-15  Bastien Guerry  <bzg@gnu.org>
 
-        * org.texi (Dynamic blocks, Structure editing): Mention
-        the function `org-narrow-to-block'.
+        * org.texi (Dynamic blocks, Structure editing):
+        Mention the function `org-narrow-to-block'.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
@@ -1754,15 +1741,15 @@
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
-        * org.texi (Conflicts): Changed "yasnippets" to "yasnippet" and
+        * org.texi (Conflicts): Change "yasnippets" to "yasnippet" and
         added extra whitespace around functions to be consistent with the
         rest of the section.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
-        * org.texi (Evaluating code blocks): Expanded discussion of
+        * org.texi (Evaluating code blocks): Expand discussion of
         #+call: line syntax.
-        (Header arguments in function calls): Expanded discussion of
+        (Header arguments in function calls): Expand discussion of
         #+call: line syntax.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
@@ -1792,17 +1779,16 @@
 
 2011-08-15  Tom Dye  <tsd@tsdye.com>
 
-        * org.texi (cache): Improved documentation of code block caches.
+        * org.texi (cache): Improve documentation of code block caches.
 
 2011-08-15  Tom Dye  <tsd@tsdye.com>
 
-        * org.texi (Code block specific header arguments): Documentation
-        of multi-line header arguments.
+        * org.texi (Code block specific header arguments):
+        Documentation of multi-line header arguments.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
-        * org.texi (Code evaluation security): Add example for using a
-        function.
+        * org.texi (Code evaluation security): Add example for using a function.
 
 2011-08-15  Eric Schulte  <schulte.eric@gmail.com>
 
@@ -1827,8 +1813,7 @@
 2011-07-14  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * widget.texi (Setting Up the Buffer): Remove mention of the
-        global keymap parent, which doesn't seem to be accurate
-        (bug#7045).
+        global keymap parent, which doesn't seem to be accurate (bug#7045).
 
 2011-07-12  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
@@ -1853,15 +1838,15 @@
 
 2011-07-04  Michael Albinus  <michael.albinus@gmx.de>
 
-        * tramp.texi (Cleanup remote connections): Add
-        `tramp-cleanup-this-connection'.
+        * tramp.texi (Cleanup remote connections):
+        Add `tramp-cleanup-this-connection'.
 
 2011-07-03  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
         * gnus.texi (Subscription Methods): Link to "Group Levels" to explain
         zombies.
         (Checking New Groups): Ditto (bug#8974).
-        (Checking New Groups): Moved the reference to the right place.
+        (Checking New Groups): Move the reference to the right place.
 
 2011-07-03  Dave Abrahams  <dave@boostpro.com>  (tiny change)
 
@@ -1888,8 +1873,8 @@
 
 2011-06-26  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
-        * gnus.texi (Summary Mail Commands): Document
-        `gnus-summary-reply-to-list-with-original'.
+        * gnus.texi (Summary Mail Commands):
+        Document `gnus-summary-reply-to-list-with-original'.
 
 2011-06-20  Stefan Monnier  <monnier@iro.umontreal.ca>
 
@@ -1952,7 +1937,7 @@
 
         * gnus.texi (nnmairix caveats, Setup, Registry Article Refer Method)
         (Fancy splitting to parent, Store arbitrary data):
-        Updated gnus-registry docs.
+        Update gnus-registry docs.
 
 2011-04-13  Juanma Barranquero  <lekktu@gmail.com>
 
@@ -2024,9 +2009,8 @@
 
 2011-03-06  Jay Belanger  <jay.p.belanger@gmail.com>
 
-        * calc.texi (Logarithmic Units): Rename calc-logunits-dblevel
-        and calc-logunits-nplevel to calc-dblevel and calc-nplevel,
-        respectively.
+        * calc.texi (Logarithmic Units): Rename calc-logunits-dblevel and
+        calc-logunits-nplevel to calc-dblevel and calc-nplevel, respectively.
         (Musical Notes): New section.
         (Customizing Calc): Mention the customizable variable
         calc-note-threshold.
@@ -3069,8 +3053,8 @@
 
         Sync with Tramp 2.1.19.
 
-        * tramp.texi (Inline methods, Default Method): Mention
-        `tramp-inline-compress-start-size'.  Remove "kludgy" phrase.
+        * tramp.texi (Inline methods, Default Method):
+        Mention `tramp-inline-compress-start-size'.  Remove "kludgy" phrase.
         Remove remark about doubled "-t" argument.
         (Auto-save and Backup): Remove reference to Emacs 21.
         (Filename Syntax): Describe port numbers.
@@ -5724,7 +5708,7 @@
 2007-10-28  Kevin Greiner  <kevin.greiner@compsol.cc>
 
         * gnus.texi (nntp-open-via-telnet-and-telnet): Fix grammar.
-        (Agent Parameters): Updated parameter names to match code.
+        (Agent Parameters): Update parameter names to match code.
         (Group Agent Commands): Corrected 'gnus-agent-fetch-series' as
         'gnus-agent-summary-fetch-series'.
         (Agent and flags): New section providing a generalized discussion
@@ -6528,7 +6512,7 @@
         (Tag searches): Document regular expression search for tags.
         (Stuck projects): New section.
         (In-buffer settings): New keywords.
-        (History and Acknowledgments): Updated description.
+        (History and Acknowledgments): Update description.
 
 2007-02-24  Alan Mackenzie  <acm@muc.de>
 
@@ -6760,7 +6744,7 @@
         (Custom agenda views): Section completely rewritten.
         (Summary): Compare with Planner.
         (Feedback): More info about creating backtraces.
-        (Plain lists): Modified example.
+        (Plain lists): Modify example.
         (Breaking down tasks): New section.
         (Custom time format): New section.
         (Time stamps): Document inactive timestamps.
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index af457d7a9af..8d398900238 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -2,6 +2,7 @@
 @c %**start of header
 @setfilename ../../info/eshell
 @settitle Eshell: The Emacs Shell
+@defindex cm
 @synindex vr fn
 @c %**end of header
 
@@ -42,7 +43,7 @@ modify this GNU manual.''
 @c -release-
 @end ignore
 @sp 3
-@center John Wiegley
+@center John Wiegley & Aidan Gauland
 @c -date-
 
 @page
@@ -75,16 +76,15 @@ handling the sort of tasks accomplished by those tools.
 * 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?
@@ -278,83 +278,56 @@ on your mind.  Have fun!
 @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 form.@footnote{To 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:
-
-@enumerate
-@item Parse the command string into separate arguments.
-@item
-@end enumerate
-
-@node Completion
-@section Completion
-
-@node Aliases
-@section Aliases
-
-@node History
-@section History
-
-Eshell knows a few built-in variables:
-
-@table @code
-
-@item $+
-@vindex $+
-This variable always contains the current working directory.
-
-@item $-
-@vindex $-
-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
-@section Scripts
+input line into a callable Lisp form.@footnote{To 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.
 
+@node Arguments
+@section 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
+@ref{Expansion, expansions}).  As with other shells, you can
+escape special characters and spaces with the backslash (@code{\}) and
+the single (@code{''}) and double (@code{""}) quotes.
 
 @node Built-ins
-@section Built-in commands
 
+@section 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
 @code{*foo}.  Usually, this should not be necessary.  You can check
@@ -368,7 +341,7 @@ eshell/ls is a compiled Lisp function in `em-ls.el'
 @end example
 
 If you want to discard a given built-in command, you could declare an
-alias, @ref{Aliases}.  Eample:
+alias, @ref{Aliases}.  Example:
 
 @example
 ~ $ which sudo
@@ -378,15 +351,96 @@ eshell/sudo is a compiled Lisp function in `em-unix.el'
 sudo is an alias, defined as "*sudo $*"
 @end example
 
-Some of the built-in commands have a special behavior in Eshell:
+@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}.
+
+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 usage message when given the @code{--help} option.
 
 @table @code
 
+@item addpath
+@cmindex 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.
+
+@item alias
+@cmindex alias
+Define an alias (@pxref{Aliases}).  This does not add it to the aliases
+file.
+
+@item date
+@cmindex date
+Similar to, but slightly different from, the GNU Coreutils
+@command{date} command.
+
+@item define
+@cmindex define
+Define a varalias.  @xref{Variable Aliases, , , elisp}.
+
+@item diff
+@cmindex diff
+Use Emacs's internal @code{diff} (not to be confused with
+@code{ediff}).  @xref{Comparing Files, , , elisp}.
+
+@item grep
+@cmindex grep
+@itemx agrep
+@cmindex agrep
+@itemx egrep
+@cmindex egrep
+@itemx fgrep
+@cmindex fgrep
+@itemx glimpse
+@cmindex glimpse
+The @command{grep} commands are compatible with GNU @command{grep}, but
+use Emacs's internal @code{grep} instead.
+
+@item info
+@cmindex info
+Same as the external @command{info} command, but uses Emacs's internal
+Info reader.
+
+@item jobs
+@cmindex jobs
+List subprocesses of the Emacs process, if any, using the function
+@code{list-processes}.
+
+@item kill
+@cmindex kill
+Kill processes.  Takes a PID or a process object and an optional
+signal specifier.
+
+@item listify
+@cmindex 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")}.
+
+@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}.
+
+@item make
+@cmindex make
+Run @command{make} through @code{compile}.  @xref{Running Compilations under Emacs, , , elisp}.
+
+@item occur
+@cmindex occur
+Alias to Emacs's @code{occur}.  @xref{Other Search-and-Loop Commands, , , elisp}.
+
+@item printnl
+@cmindex printnl
+Print the arguments separated by newlines.
+
 @item cd
-@findex cd
+@cmindex 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:
+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.
 
@@ -396,14 +450,73 @@ 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 =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.
 
-@item history
-@findex history
+@item su
+@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}.
+
+@end table
+
+@section Built-in variables
+Eshell knows a few built-in variables:
+
+@table @code
+
+@item $+
+@vindex $+
+This variable always contains the current working directory.
+
+@item $-
+@vindex $-
+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 Variables
+@section Variables
+Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print 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
+@code{setq} for convenience.
+
+@node Aliases
+@section Aliases
+
+Aliases are commands that expand to a longer input line.  For example,
+@command{ll} 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).
+
+@node History
+@section History
+@cmindex 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
@@ -419,70 +532,226 @@ of the history ring.
 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:
+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:
+
+@table @kbd
+@item M-r
+@itemx M-s
+History I-search.
+
+@item M-p
+@itemx 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.
+@end table
+
+@node Completion
+@section 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
+@command{rmdir} 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-?}.
+
+@subsection pcomplete
+Pcomplete, short for programmable completion, is the completion
+library originally written for Eshell, but usable for command
+completion@footnote{Command 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
+@code{pcomplete/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.
+
+@node for loop
+@section @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
+@code{for VAR in TOKENS @{ command invocation(s) @}}
 @end example
 
-@end table
-
+where @samp{TOKENS} is a space-separated sequence of values of
+@var{VAR} for each iteration.  This can even be the output of a
+command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}.
 
-@node Arguments
-@chapter Arguments
+@node Scripts
+@section Scripts
+@cmindex source
+@fnindex 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}.
+
+@cmindex .
+If you wish to load a script into your @emph{current} environment,
+rather than in a subshell, use the @code{.} command.
+
+@node Expansion
+@chapter 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 manipulation.@footnote{Eshell 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 commands.@footnote{e.g. 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
 
-@node The Parser
-@section The Parser
+@node Dollars Expansion
+@section 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.
 
-@node Variables
-@section Variables
+@table @code
 
-@node Substitution
-@section Substitution
+@item $var
+Expands to the value bound to @code{var}.  This is the main way to use
+variables in command invocations.
 
-@node Globbing
-@section Globbing
+@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}).
 
-@node Predicates
-@section Predicates
+@item $(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}.
 
+@item $@{command@}
+Returns the output of @command{command}, which can be any valid Eshell
+command invocation, and may even contain expansions.
 
-@node Input/Output
-@chapter Input/Output
+@item $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.
+
+@item $var[: i]
+As above, but now splitting occurs at the colon character.
 
-@node Process control
-@chapter Process control
+@item $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.
 
+@item $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]}.
+
+@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}).
+
+@item $#var[hello]
+Returns the length of the cdr of the element of @code{var} who car is equal
+to @code{"hello"}.
+
+@end table
+
+@node Globbing
+@section Globbing
+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 Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
+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}.
+
+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.
+
+@var{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
+symbol--@code{overwrite}, @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
+@code{nil} 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
+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}.}
+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
+Eshell module.}  You also need to load the following as shown:
+
+@example
+(eval-when-compile
+  (require 'cl)
+  (require 'esh-mode)
+  (require 'eshell))
+
+(require 'esh-util)
+@end example
 
 @menu
 * Writing a module::
@@ -491,7 +760,6 @@ Example:
 * Key rebinding::
 * Smart scrolling::
 * Terminal emulation::
-* Built-in UNIX commands::
 @end menu
 
 @node Writing a module
@@ -512,13 +780,6 @@ Example:
 @node Terminal emulation
 @section Terminal emulation
 
-@node Built-in UNIX commands
-@section Built-in UNIX commands
-
-
-@node Extras and Goodies
-@chapter Extras and Goodies
-
 @node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
@@ -527,6 +788,8 @@ Example:
 @cindex email to the author
 @cindex FAQ
 @cindex problems, list of common
+@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
@@ -537,16 +800,7 @@ 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!
 
-@menu
-* Known problems::
-@end menu
-
-@node Known problems
-@section Known problems
-@cindex known bugs
-@cindex 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
@@ -554,7 +808,7 @@ which is the version included with Emacs 22.
 
 @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
@@ -838,7 +1092,7 @@ them; @code{min} would display the smallest figure, etc.
 It would provide syntax, abbrev, highlighting and indenting support like
 @code{emacs-lisp-mode} and @code{shell-mode}.
 
-@item In the history mechanism, finish the @command{bash}-style support
+@item In the history mechanism, finish the Bash-style support
 
 This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
 from @samp{!:1*}.
@@ -1008,6 +1262,11 @@ Since it keeps the cursor up where the command was invoked.
 
 @printindex fn
 
+@node Command Index
+@unnumbered Command Index
+
+@printindex cm
+
 @node Key Index
 @unnumbered Key Index