]> code.delx.au - gnu-emacs/blobdiff - man/eshell.texi
(calc-embedded-close-formula, calc-embedded-open-formula,
[gnu-emacs] / man / eshell.texi
index c690909a94c718d288c2f413b6cb4ec61d7f3c2c..fe36780955b2b3311795ea2b75cc47f9d0e98332 100644 (file)
@@ -1,67 +1,43 @@
 \input texinfo  @c -*-texinfo-*-
 \input texinfo  @c -*-texinfo-*-
+@c %**start of header
+@setfilename ../info/eshell
+@settitle Eshell: The Emacs Shell
+@synindex vr fn
+@c %**end of header
 
 
-@c "@(#)$Name:  $:$Id: eshell.texi,v 1.3 2000/10/16 18:24:30 eliz Exp $"
-
-@c Documentation for Eshell: The Emacs Shell.
-@c Copyright (C) 1999-2000  Free Software Foundation, Inc.
-
-@c This file is part of GNU Emacs
+@copying
+This manual is for Eshell, the Emacs shell.
 
 
-@c GNU Emacs is free software; you can redistribute it and/or modify it
-@c under the terms of the GNU General Public License as published by the
-@c Free Software Foundation; either version 2 of the License, or (at
-@c your option) any later version.
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
+   2005 Free Software Foundation, Inc.
 
 
-@c GNU Emacs is distributed in the hope that it will be useful, but
-@c WITHOUT ANY WARRANTY; without even the implied warraonty of
-@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-@c General Public License for more details.
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 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.
 
 
-@c You should have received a copy of the GNU General Public License
-@c along with Eshell; see the file COPYING.  If not, write to the Free
-@c Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+(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.''
 
 
-@c %**start of header
-@setfilename ../info/eshell
-@settitle Eshell: The Emacs Shell
-@c %**end of header
+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.
+@end quotation
+@end copying
 
 @dircategory Emacs
 @direntry
 * Eshell: (eshell).     A command shell implemented in Emacs Lisp.
 @end direntry
 
 @dircategory Emacs
 @direntry
 * Eshell: (eshell).     A command shell implemented in Emacs Lisp.
 @end direntry
-@setchapternewpage on
-     
-@ifinfo
-Copyright @copyright{} 1999-2000  Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-@end ignore
 
 
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this
-one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' and this
-permission notice may be included in translations approved by the Free
-Software Foundation instead of in the original English.
-@end ifinfo
+@setchapternewpage on
 
 
-@synindex vr fn
-@c The titlepage section does not appear in the Info file.
 @titlepage
 @sp 4
 @c The title is printed in a large font.
 @titlepage
 @sp 4
 @c The title is printed in a large font.
@@ -79,28 +55,9 @@ Software Foundation instead of in the original English.
 @center John Wiegley
 @c -date-
 
 @center John Wiegley
 @c -date-
 
-@c  The following two commands start the copyright page for the printed
-@c  manual.  This will not appear in the Info file.
 @page
 @vskip 0pt plus 1filll
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2000  Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this
-one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' and this
-permission notice may be included in translations approved by the Free
-Software Foundation instead of in the original English.
+@insertcopying
 @end titlepage
 
 @contents
 @end titlepage
 
 @contents
@@ -109,8 +66,8 @@ Software Foundation instead of in the original English.
 @c                   The real text starts here
 @c ================================================================
 
 @c                   The real text starts here
 @c ================================================================
 
+@ifnottex
 @node Top, What is Eshell?, (dir), (dir)
 @node Top, What is Eshell?, (dir), (dir)
-@ifinfo
 @top Eshell
 
 This manual documents Eshell, a shell-like command interpretor
 @top Eshell
 
 This manual documents Eshell, a shell-like command interpretor
@@ -120,43 +77,47 @@ 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.
 @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.
-@end ifinfo
+@end ifnottex
 
 @menu
 
 @menu
-* What is Eshell?::        A brief introduction to the Emacs Shell.
-* Installation::           For users of Emacs 20 and XEmacs.
-* Command basics::         The basics of command usage.     
-* Bugs and ideas::         Known problems, and future ideas.
+* What is Eshell?::             A brief introduction to the Emacs Shell.
+* Command basics::              The basics of command usage.
+* Commands::
+* Arguments::
+* Input/Output::
+* Process control::
+* Extension modules::
+* Extras and Goodies::
+* Bugs and ideas::              Known problems, and future ideas.
 * Concept Index::
 * Function and Variable Index::
 * Key Index::
 @end menu
 
 * Concept Index::
 * Function and Variable Index::
 * Key Index::
 @end menu
 
-@node What is Eshell?, Installation, Top, Top
+@node What is Eshell?
 @chapter What is Eshell?
 @cindex what is Eshell?
 @cindex Eshell, what it is
 
 Eshell is a @dfn{command shell} written in Emacs Lisp.  Everything it
 @chapter What is Eshell?
 @cindex what is Eshell?
 @cindex Eshell, what it is
 
 Eshell is a @dfn{command shell} written in Emacs Lisp.  Everything it
-does it uses Emacs' facilities to do.  This means that Eshell is as
+does, it uses Emacs' facilities to do.  This means that Eshell is as
 portable as Emacs itself.  It also means that cooperation with Lisp code
 is natural and seamless.
 
 What is a command shell?  To properly understand the role of a shell,
 it's necessary to visualize what a computer does for you.  Basically, a
 computer is a tool; in order to use that tool, you must tell it what to
 portable as Emacs itself.  It also means that cooperation with Lisp code
 is natural and seamless.
 
 What is a command shell?  To properly understand the role of a shell,
 it's necessary to visualize what a computer does for you.  Basically, a
 computer is a tool; in order to use that tool, you must tell it what to
-do---or give it ``commands''.  These commands take many forms, such as
+do---or give it ``commands.''  These commands take many forms, such as
 clicking with a mouse on certain parts of the screen.  But that is only
 one form of command input.
 
 By far the most versatile way to express what you want the computer to
 clicking with a mouse on certain parts of the screen.  But that is only
 one form of command input.
 
 By far the most versatile way to express what you want the computer to
-do is by using an abbreviated language called @dfn{script}.  In script,
-instead of telling the computer, ``list my files, please'', one writes
-just ``list''.  In fact, this command is so commonly used that it is
-abbreviated to ``ls''.  Typing @kbd{ls} in a command shell is a script
-way of telling the computer to list your files.@footnote{This is
-comparable to viewing the contents of a folder using a graphical
-display.}
+do is by using an abbreviated language called @dfn{script}.  In
+script, instead of telling the computer, ``list my files, please'',
+one writes a standard abbreviated command word---@samp{ls}.  Typing
+@samp{ls} in a command shell is a script way of telling the computer
+to list your files.@footnote{This is comparable to viewing the
+contents of a folder using a graphical display.}
 
 The real flexibility of this approach is apparent only when you realize
 that there are many, many different ways to list files.  Perhaps you
 
 The real flexibility of this approach is apparent only when you realize
 that there are many, many different ways to list files.  Perhaps you
@@ -185,13 +146,11 @@ 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)}.}
 
 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)}.}
 
-As of Emacs 21, Eshell is part of the standard Emacs distribution.
-
 @menu
 * Contributors to Eshell::      People who have helped out!
 @end menu
 
 @menu
 * Contributors to Eshell::      People who have helped out!
 @end menu
 
-@node Contributors to Eshell,  , What is Eshell?, What is Eshell?
+@node Contributors to Eshell
 @section Contributors to Eshell
 @cindex contributors
 @cindex authors
 @section Contributors to Eshell
 @cindex contributors
 @cindex authors
@@ -231,260 +190,264 @@ 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.
 
 requests, bug reports and encouragement.  Thanks a lot!  Without you
 there would be no new releases of Eshell.
 
-@node Installation, Command basics, What is Eshell?, Top
-@chapter Installation
-@cindex installation
+@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
 
 
-As mentioned above, Eshell comes preinstalled as of Emacs 21.  If you're
-using Emacs 20.4 or later, or XEmacs 21, you can download the most
-recent version of Eshell from
-@url{http://www.gci-net.com/users/j/johnw/Emacs/eshell.tar.gz}.
+This script command causes the computer to echo back: ``This is an
+example of using echo!''
 
 
-However, if you are using Emacs 21, you may skip this section.
+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.
 
 
-@section Short Form
+@node Command arguments
+@section Command arguments
 
 
-Here's exactly what to do, with no explanation why:
+Eshell recognizes several different kinds of command arguments:
 
 @enumerate
 
 @enumerate
-@item
-@samp{M-x load-file RET eshell-auto.el RET}.
+@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
 
 
-@item
-@samp{ESC : (add-to-list 'load-path "<path where Eshell resides>") RET}.
+Most users need to worry only about the first two.  The third, Lisp lists,
+occur very frequently, but almost always behind the scenes.
 
 
-@item
-@samp{ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET}.
+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.
 
 
-@item
-@samp{M-x eshell RET}.
+Here is a more complicated @command{echo} example:
 
 
-You should see a version banner displayed.
+@example
+echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar
+@end example
 
 
-@item
-@samp{ls RET}.
+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!
 
 
-Confirm that you see a file listing.
+@node Commands
+@chapter Commands
 
 
-@item
-@samp{eshell-test RET}.
+@menu
+* Invocation::
+* Completion::
+* Aliases::
+* History::
+* Scripts::
+* Built-ins::
+@end menu
 
 
-Confirm that everything runs correctly.  Use @kbd{M-x eshell-report-bug} if
-not.
+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.
 
 
-@item
-@samp{cd $@{dirname (locate-library "eshell-auto")@} RET}.
+@node Invocation
+@section Invocation
 
 
-@item
-@samp{find-file Makefile RET}.
+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"}}
 
 
-@item
-Edit the Makefile to reflect your site.
+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
 @item
-@samp{M-x eshell RET}.
+@end enumerate
 
 
-@item
-@samp{make install RET}.
+@node Completion
+@section Completion
 
 
-@item
-@samp{find-file $user-init-file RET}.
+@node Aliases
+@section Aliases
 
 
-@item
-Add the following lines to your @file{.emacs} file:
+@node History
+@section History
 
 
-@example
-(add-to-list 'load-path "<directory where you install Eshell>")
-(load "eshell-auto")
-@end example
+Eshell knows a few built-in variables:
 
 
-@item
-@samp{M-x eshell RET}.
+@table @code
 
 
-@item
-@samp{customize-option #'eshell-modules-list RET}.
+@item $+
+@vindex $+
+This variable always contains the current working directory.
 
 
-@item
-Select the extension modules you prefer.
+@item $-
+@vindex $-
+This variable always contains the previous working directory (the
+current working directory from before the last @code{cd} command).
 
 
-@item
-Restart Emacs!
+@end table
 
 
-@item
-@samp{M-x info RET m Eshell RET}.
+@node Scripts
+@section Scripts
 
 
-Read the manual and enjoy!
-@end enumerate
 
 
-@section Long Form
+@node Built-ins
+@section Built-in commands
 
 
-@enumerate
-@item
-Before building and installing Eshell, it is important to test that it
-will work properly on your system.  To do this, first load the file
-@file{eshell-auto}, which will define certain autoloads required to run
-Eshell.  This can be done using the command @kbd{M-x load-file}, and
-then selecting the file @file{eshell-auto.el}.
+Here is a list of built-in commands that Eshell knows about:
 
 
-@item
-In order for Emacs to find Eshell's files, the Eshell directory must be
-added to the @code{load-path} variable.  This can be done within Emacs by
-typing:
+@table @code
 
 
-@example
-ESC : (add-to-list 'load-path "<path where Eshell resides>") RET
-ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET
-@end example
+@item cd
+@findex 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:
 
 
-@item
-Start Eshell from the distributed sources, using default settings, by
-typing @kbd{M-x eshell}.
+When it receives no argument at all, it changes to the home directory.
 
 
-@item
-Verify that Eshell is functional by typing @command{ls} followed by
-@key{RET}.  You should have already seen a version banner announcing the
-version number of this release, followed by a prompt.
+Giving the command @samp{cd -} changes back to the previous working
+directory (this is the same as @samp{cd $-}).
 
 
-@item
-Run the test suite by typing @command{eshell-test} followed by @key{RET}
-in the Eshell buffer.  It is important that Emacs be left alone while
-the tests are running, since extraneous command input may cause some of
-the tests to fail (they were never intended to run in the background).
-If all of the tests pass, Eshell should work just fine on your system.
-If any of the tests fail, please send e-mail to the Eshell maintainer
-using the command @kbd{M-x eshell-report-bug}.
+The command @samp{cd =} shows the directory stack.  Each line is
+numbered.
 
 
-@item
-Edit the file @file{Makefile} in the directory containing the Eshell
-sources to reflect the location of certain Emacs dircetories at your
-site.  The only things you really have to change are the definitions of
-@code{lispdir} and @code{infodir}.  The elisp files will be copied to
-@code{lispdir}, and the info file to @code{infodir}.
+With @samp{cd =foo}, Eshell searches the directory stack for a
+directory matching the regular expression @samp{foo} and changes to
+that directory.
 
 
-@item
-Type @kbd{make install} in the directory containing the Eshell sources.
-This will byte-compile all of the @file{*.el} files and copy both the
-source and compiled versions to the directories specified in the
-previous step.  It will also copy the info file, and add a corresponding
-entry to your @file{dir} file----if the program @code{install-info} can
-be found on your system.
+With @samp{cd -42}, you can access the directory stack by number.
 
 
-If you only want to create the compiled elisp files, but don't want to
-install them, you can type just @kbd{make} instead.
+@end table
 
 
-@item
-Add the directory into which Eshell was installed to your
-@code{load-path} variable.  This can be done by adding the following
-line to your @file{.emacs} file:
 
 
-@example
-(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/eshell")
-@end example
+@node Arguments
+@chapter Arguments
 
 
-The actual directory on your system may differ.
+@menu
+* The Parser::
+* Variables::
+* Substitution::
+* Globbing::
+* Predicates::
+@end menu
 
 
-@item
-To install Eshell privately, edit your @file{.emacs} file; to install
-Eshell site-wide, edit the file @file{site-start.el} in your
-@file{site-lisp} directory (usually
-@file{/usr/local/share/emacs/site-lisp} or something similar).  In
-either case enter the following line into the appropriate file:
+@node The Parser
+@section The Parser
 
 
-@example
-(load "eshell-auto")
-@end example
+@node Variables
+@section Variables
 
 
-@item
-Restart Emacs.  After restarting, customize the variable
-@code{eshell-modules-list}.  This variable selects which Eshell
-extension modules you want to use.  You will find documentation on each
-of those modules in the Info manual.
-@end enumerate
+@node Substitution
+@section Substitution
 
 
-@cindex documentation, printed version
-@cindex printed version of documentation
-If you have @TeX{} installed at your site, you can make a typeset manual
-from @file{eshell.texi}.
+@node Globbing
+@section Globbing
 
 
-@enumerate
-@item
-Run @TeX{} by typing @kbd{texi2dvi eshell.texi}.  (With Emacs 21.1 or
-later, typing @kbd{make eshell.dvi} in the @file{man/} subdirectory of
-the Emacs source distribution will do that.)
+@node Predicates
+@section Predicates
 
 
-@item
-Convert the resulting device independent file @file{eshell.dvi} to a
-form which your printer can output and print it.  If you have a
-postscript printer, there is a program, @code{dvi2ps}, which does that; there
-is also a program which comes together with @TeX{}, @code{dvips}, which
-you can use.  For other printers, use a suitable DVI driver,
-e.g., @code{dvilj4} for LaserJet-compatible printers.
-@end enumerate
 
 
-@node Command basics, Bugs and ideas, Installation, Top
-@chapter Command basics
+@node Input/Output
+@chapter Input/Output
+
+@node Process control
+@chapter Process control
+
 
 
-A command shell is a mechanism for 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 get a firm
-grasp on exactly what a command is, and how it fits into the overall
-picture of things.
+@node Extension modules
+@chapter Extension modules
 
 @menu
 
 @menu
-* Commands verbs::              Commands always begin with a verb.
-* Command arguments::           Some verbs require arguments.
+* Writing a module::
+* Module testing::
+* Directory handling::
+* Key rebinding::
+* Smart scrolling::
+* Terminal emulation::
+* Built-in UNIX commands::
 @end menu
 
 @end menu
 
-@node Commands verbs, Command arguments, Command basics, Command basics
-@section Commands verbs
+@node Writing a module
+@section Writing a module
 
 
-Commands are expressed using @dfn{script}, a special shorthand language
-that computers can understand without trouble.
+@node Module testing
+@section Module testing
 
 
-Script is an extremely simplified language.  Oddly enough, this actually
-makes it look more complicated than it is.  Whereas normal languages use
-a variety of embellishments, the form of a script command is always:
+@node Directory handling
+@section Directory handling
 
 
-@example
-  VERB [ARGUMENTS]
-@end example
+@node Key rebinding
+@section Key rebinding
 
 
-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.
+@node Smart scrolling
+@section Smart scrolling
 
 
-Sometimes, the verb is all that's written.  A verb is always a single
-word, usually related to the task it will perform.  @command{reboot} is
-a good example.  Entering that will cause your computer to reboot,
-assuming you have sufficient privileges.
-
-Other verbs require more information.  These are usually very capable of
-verbs, and must be told more specifically what to do.  This extra
-information is given in the form of arguments.  Arguments are also
-single words, that appear after the verb.  For example, @command{echo}
-is a command verb that prints back whatever you say.  @command{echo}
-requires arguments, so that it knows what to echo.  A proper use of
-@command{echo} looks like this:
+@node Terminal emulation
+@section Terminal emulation
 
 
-@example
-echo This is an example of using echo!
-@end example
+@node Built-in UNIX commands
+@section Built-in UNIX commands
 
 
-This piece of script expresses a command that causes the computer to
-print back: ``This is an example of using echo!''.
 
 
-Although command verbs always take the form of simple words, such as
-@command{reboot} and @command{echo}, arguments have a wide vaierty of
-forms.  There are textual arguments, numerical arguments---even Lisp
-arguments.  Distinguishing between these different types of arguments
-requires special typing, since the computer needs to know exactly what
-you mean.
+@node Extras and Goodies
+@chapter Extras and Goodies
 
 
-@node Command arguments,  , Commands verbs, Command basics
-@section Command arguments
-
-@node Bugs and ideas, Concept Index, Command basics, Top
+@node Bugs and ideas
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
 @cindex bugs, how to report them
 @chapter Bugs and ideas
 @cindex reporting bugs and ideas
 @cindex bugs, how to report them
@@ -503,25 +466,27 @@ extensions to this package, I would like to hear from you.  I hope you
 find this package useful!
 
 @menu
 find this package useful!
 
 @menu
-* Known problems::              
+* Known problems::
 @end menu
 
 @end menu
 
-@node Known problems,  , Bugs and ideas, Bugs and ideas
+@node Known problems
 @section Known problems
 @cindex known bugs
 @cindex bugs, known
 
 @section Known problems
 @cindex known bugs
 @cindex bugs, known
 
-Below is a partial list of currently known problems with Eshell version
-2.4, which is the version distributed with Emacs 21.1.
+Below is complete list of known problems with Eshell version 2.4.1,
+which is the version included with Emacs 21.1.
 
 @table @asis
 
 @table @asis
+@item Documentation incomplete
+
 @item Differentiate between aliases and functions
 
 Allow for a bash-compatible syntax, such as:
 
 @example
 alias arg=blah
 @item Differentiate between aliases and functions
 
 Allow for a bash-compatible syntax, such as:
 
 @example
 alias arg=blah
-function arg () { blah $* }
+function arg () @{ blah $* @}
 @end example
 
 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
 @end example
 
 @item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
@@ -570,7 +535,7 @@ scrolls back.
 
 @item Using C-p and C-n with rebind gets into a locked state
 
 
 @item Using C-p and C-n with rebind gets into a locked state
 
-This happened a few times in Emacs 21, but has been unreproducable
+This happened a few times in Emacs 21, but has been unreproducible
 since.
 
 @item If an interactive process is currently running, @kbd{M-!} doesn't work
 since.
 
 @item If an interactive process is currently running, @kbd{M-!} doesn't work
@@ -587,7 +552,7 @@ called with the input strings as arguments.  This will require changing
 
 See the above entry.
 
 
 See the above entry.
 
-@item Problem running @command{less} without argument on Windows
+@item Problem running @command{less} without arguments on Windows
 
 The result in the Eshell buffer is:
 
 
 The result in the Eshell buffer is:
 
@@ -601,15 +566,15 @@ Also a new @command{less} buffer was created with nothing in it@dots{}
 If @command{less.exe} is invoked from the Eshell command line, the
 expected output is written to the buffer.
 
 If @command{less.exe} is invoked from the Eshell command line, the
 expected output is written to the buffer.
 
-Note that this happens on NT-Emacs 20.6.1 on Win2000. The term.el
-package and the supplied shell both use the @command{cmdproxy} for
-running shells.
+Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el
+package and the supplied shell both use the @command{cmdproxy} program
+for running shells.
 
 @item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
 
 @item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
 
 
 @item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
 
 @item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
 
-@item @samp{mv DIR FILE.tar} does not remove directories
+@item @samp{mv @var{dir} @var{file}.tar} does not remove directories
 
 This is because the tar option --remove-files doesn't do so.  Should it
 be Eshell's job?
 
 This is because the tar option --remove-files doesn't do so.  Should it
 be Eshell's job?
@@ -651,21 +616,15 @@ Invalid regexp: "Unmatched ( or \\("
 With @command{zsh}, the glob above expands to all files named
 @file{Root} in directories named @file{CVS}.
 
 With @command{zsh}, the glob above expands to all files named
 @file{Root} in directories named @file{CVS}.
 
-@item Typing @samp{echo ${locate locate}/bin<TAB>} results in a Lisp error
+@item Typing @samp{echo $@{locate locate@}/bin<TAB>} results in a Lisp error
 
 Perhaps it should interpolate all permutations, and make that the
 globbing result, since otherwise hitting return here will result in
 ``(list of filenames)/bin'', which is never valuable.  Thus, one could
 
 Perhaps it should interpolate all permutations, and make that the
 globbing result, since otherwise hitting return here will result in
 ``(list of filenames)/bin'', which is never valuable.  Thus, one could
-@command{cat} only C backup files by using @samp{ls ${identity *.c}~}.
+@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}.
 In that case, having an alias command name @command{glob} for
 @command{identity} would be useful.
 
 In that case, having an alias command name @command{glob} for
 @command{identity} would be useful.
 
-@item Fix `file-name-all-completions' for XEmacs on Win32
-
-Make sure it returns directory names terminated by
-@code{directory-sep-char} (which is initialized to be @samp{?/}), rather
-than backslash.
-
 @item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
 
 @item Create @code{eshell-expand-file-name}
 @item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
 
 @item Create @code{eshell-expand-file-name}
@@ -677,7 +636,7 @@ This would use a data table to transform things such as @samp{~+},
 
 It only really needs: to be hooked onto the output filter and the
 pre-command hook, and to have the input-end and input-start markers.
 
 It only really needs: to be hooked onto the output filter and the
 pre-command hook, and to have the input-end and input-start markers.
-And to know whether the last output group was ``successful''.
+And to know whether the last output group was ``successful.''
 
 @item Allow for fully persisting the state of Eshell
 
 
 @item Allow for fully persisting the state of Eshell
 
@@ -695,7 +654,7 @@ At the moment, this is not supported.
 @item Error if a glob doesn't expand due to a predicate
 
 An error should be generated only if @code{eshell-error-if-no-glob} is
 @item Error if a glob doesn't expand due to a predicate
 
 An error should be generated only if @code{eshell-error-if-no-glob} is
-non-nil.
+non-@code{nil}.
 
 @item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
 
 
 @item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
 
@@ -751,7 +710,7 @@ A special associate array, which can take references of the form
 
 @item Eshell scripts can't execute in the background
 
 
 @item Eshell scripts can't execute in the background
 
-@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{NAME:-VAL@}}
+@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}}
 
 @item Write an @command{info} alias that can take arguments
 
 
 @item Write an @command{info} alias that can take arguments
 
@@ -777,12 +736,12 @@ If it's a Lisp function, input redirection implies @command{xargs} (in a
 way@dots{}).  If input redirection is added, also update the
 @code{file-name-quote-list}, and the delimiter list.
 
 way@dots{}).  If input redirection is added, also update the
 @code{file-name-quote-list}, and the delimiter list.
 
-@item Allow @samp{#<WORD ARG>} as a generic syntax
+@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax
 
 With the handling of @emph{word} specified by an
 @code{eshell-special-alist}.
 
 
 With the handling of @emph{word} specified by an
 @code{eshell-special-alist}.
 
-@item In @code{eshell-eval-using-options}, allow a @code{:complete} tag
+@item In @code{eshell-veal-using-options}, allow a @code{:complete} tag
 
 It would be used to provide completion rules for that command.  Then the
 macro will automagically define the completion function.
 
 It would be used to provide completion rules for that command.  Then the
 macro will automagically define the completion function.
@@ -818,11 +777,11 @@ from @samp{!:1*}.
 
 @item Specifying a frame as a redirection target should imply the currently active window's buffer
 
 
 @item Specifying a frame as a redirection target should imply the currently active window's buffer
 
-@item Implement @samp{>FUNC-OR-FUNC-LIST}
+@item Implement @samp{>@var{func-or-func-list}}
 
 This would allow for an ``output translators'', that take a function to
 modify output with, and a target.  Devise a syntax that works well with
 
 This would allow for an ``output translators'', that take a function to
 modify output with, and a target.  Devise a syntax that works well with
-pipes, and can accomodate multiple functions (i.e., @samp{>'(upcase
+pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase
 regexp-quote)} or @samp{>'upcase}).
 
 @item Allow Eshell to read/write to/from standard input and output
 regexp-quote)} or @samp{>'upcase}).
 
 @item Allow Eshell to read/write to/from standard input and output
@@ -832,12 +791,12 @@ This would allow it to be run from the command line (perhaps).
 
 @item Write a @command{help} command
 
 
 @item Write a @command{help} command
 
-It would call subcommands with ``--help'', or ``-h'' or ``/?'', as
-appropriate.
+It would call subcommands with @option{--help}, or @option{-h} or
+@option{/?}, as appropriate.
 
 @item Implement @command{stty} in Lisp
 
 
 @item Implement @command{stty} in Lisp
 
-@item Support @command{rc}'s matching operator, e.g. @samp{~ (list) regexp}
+@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}}
 
 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
 
 
 @item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
 
@@ -866,8 +825,9 @@ last command.
 Make it possible for the user to send char-by-char to the underlying
 process.  Ultimately, I should be able to move away from using term.el
 altogether, since everything but the ANSI code handling is already part
 Make it possible for the user to send char-by-char to the underlying
 process.  Ultimately, I should be able to move away from using term.el
 altogether, since everything but the ANSI code handling is already part
-of Eshell.  Then, things would work correctly on Win32 as well (which
-doesn't have @file{/bin/sh}, although @file{term.el} tries to use it)
+of Eshell.  Then, things would work correctly on MS-Windows as well
+(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use
+it).
 
 @item Make the shell spawning commands be visual
 
 
 @item Make the shell spawning commands be visual
 
@@ -877,7 +837,7 @@ That is, make (@command{su}, @command{bash}, @command{telnet},
 being used to invoke a single command.  Then, the behavior should be
 based on what that command is.
 
 being used to invoke a single command.  Then, the behavior should be
 based on what that command is.
 
-@item Create an smart viewing command named @command{open}
+@item Create a smart viewing command named @command{open}
 
 This would search for some way to open its argument (similar to opening
 a file in the Windows Explorer).
 
 This would search for some way to open its argument (similar to opening
 a file in the Windows Explorer).
@@ -893,7 +853,7 @@ auto-revert mode in that buffer at frequent intervals---and a
 
 @item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
 
 
 @item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
 
-@item Write emsh.c
+@item Write mesh.c
 
 This would run Emacs with the appropriate arguments to invoke Eshell
 only.  That way, it could be listed as a login shell.
 
 This would run Emacs with the appropriate arguments to invoke Eshell
 only.  That way, it could be listed as a login shell.
@@ -939,8 +899,8 @@ perform this on-thy-fly rewriting.
 
 @item Write an alias for @command{less} that brings up a @code{view-mode} buffer
 
 
 @item Write an alias for @command{less} that brings up a @code{view-mode} buffer
 
-Such that the user can press @kbd{SPC} and @kbd{DEL}, and then @kbd{q}
-to return to Eshell.  It would be equivalent to: 
+Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
+to return to Eshell.  It would be equivalent to:
 @samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
 
 @item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
 @samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
 
 @item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
@@ -962,18 +922,22 @@ Since it keeps the cursor up where the command was invoked.
 
 @end table
 
 
 @end table
 
-@node Concept Index, Function and Variable Index, Bugs and ideas, Top
+@node Concept Index
 @unnumbered Concept Index
 
 @printindex cp
 
 @unnumbered Concept Index
 
 @printindex cp
 
-@node Function and Variable Index, Key Index, Concept Index, Top
+@node Function and Variable Index
 @unnumbered Function and Variable Index
 
 @printindex fn
 
 @unnumbered Function and Variable Index
 
 @printindex fn
 
-@node Key Index,  , Function and Variable Index, Top
+@node Key Index
 @unnumbered Key Index
 
 @printindex ky
 @bye
 @unnumbered Key Index
 
 @printindex ky
 @bye
+
+@ignore
+   arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01
+@end ignore