Added the beginnings of proper Eshell documentation.

3 files changed, 814 insertions, 2 deletions

diff --git a/man/ChangeLog b/man/ChangeLog
index 4d75c13e81b..37d3fd7011e 100644
--- a/man/ChangeLog
+++ b/man/ChangeLog
@@ -1,3 +1,10 @@
+2000-10-13  John Wiegley  <johnw@gnu.org>
+
+        * Makefile.in: Added build targets for eshell.texi.
+
+        * eshell.texi: New file.  Note that this file is only just
+        beginning.  It's based heavily on the structure of pcl-cvs.texi.
+
 2000-10-04  Miles Bader  <miles@lsi.nec.co.jp>
 
         * emacs.texi (Top): Update version in `Antinews' menu entry.
diff --git a/man/Makefile.in b/man/Makefile.in
index ec6eb52a88d..186144aa58b 100644
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -18,12 +18,12 @@ INFO_TARGETS = ../info/emacs ../info/ccmode ../info/cl \
                 ../info/sc ../info/vip ../info/viper ../info/widget \
                 ../info/efaq ../info/ada-mode ../info/autotype \
                 ../info/idlwave ../info/eudc ../info/ebrowse ../info/pcl-cvs \
-                ../info/woman ../info/emacs-mime
+                ../info/woman ../info/emacs-mime ../info/eshell
 DVI_TARGETS = emacs.dvi cc-mode.dvi cl.dvi dired-x.dvi \
                  ediff.dvi forms.dvi gnus.dvi message.dvi mh-e.dvi \
                  reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
                  ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
-                 pcl-cvs.dvi woman.dvi emacs-mime.dvi
+                 pcl-cvs.dvi woman.dvi emacs-mime.dvi eshell.dvi
 INFOSOURCES = info.texi info-stnd.texi
 
 # The following rule does not work with all versions of `make'.
@@ -111,6 +111,11 @@ ada-mode.dvi: ada-mode.texi
 pcl-cvs.dvi: pcl-cvs.texi
         $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi
 
+../info/eshell: eshell.texi
+        cd $(srcdir); $(MAKEINFO) eshell.texi
+eshell.dvi: eshell.texi
+        $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi
+
 ../info/cl: cl.texi
         cd $(srcdir); $(MAKEINFO) cl.texi
 cl.dvi: cl.texi
diff --git a/man/eshell.texi b/man/eshell.texi
new file mode 100644
index 00000000000..6492e1e9417
--- /dev/null
+++ b/man/eshell.texi
@@ -0,0 +1,800 @@
+\input texinfo  @c -*-texinfo-*-
+
+@c "@(#)$Name:  $:$Id: $"
+
+@c Documentation for Eshell: The Emacs Shell.
+@c Copyright (C) 1999-2000  Free Software Foundation, Inc.
+
+@c This file is part of GNU Emacs
+
+@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.
+
+@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.
+
+@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.
+
+@c %**start of header
+@setfilename ../info/eshell
+@settitle Eshell: The Emacs Shell
+@c %**end of header
+
+@c @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
+
+@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.
+@center @titlefont{User's Guide}
+@sp
+@center @titlefont{to}
+@sp
+@center @titlefont{Eshell: The Emacs Shell}
+@ignore
+@sp 2
+@center release 2.3.2
+@c -release-
+@end ignore
+@sp 3
+@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
+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.
+@end titlepage
+
+@c ================================================================
+@c                   The real text starts here
+@c ================================================================
+
+@node Top, What is Eshell?, (dir), (dir)
+@ifinfo
+@top Eshell
+
+This manual documents Eshell, a shell-like command interpretor
+implemented entirely in Emacs Lisp.  It invokes no external processes
+beyond those requested by the user.  It is intended to be a functional
+replacement for command shells such as @command{bash}, @command{zsh},
+@command{rc}, @command{4dos}; since Emacs itself is capable of handling
+most of the tasks accomplished by such tools.
+@c This manual is updated to release 2.3.2 of Eshell.
+@end ifinfo
+
+@menu
+* What is Eshell?::             A brief introduction to the Emacs Shell.
+* Bugs and ideas::              
+@end menu
+
+@node What is Eshell?, Bugs and ideas, Top, Top
+@chapter What is Eshell?
+@cindex What is Eshell?
+
+Eshell is a command shell written using Emacs Lisp.  All of what it does
+it uses Emacs' facilities to do.  This means Eshell is as portable as
+Emacs itself.  It also means that cooperation with other Lisp code is
+natural and seamless.
+
+So 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
+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 using an abbreviated language, called script.  In script, instead
+of telling the computer, ``list my files, please'', we write just
+``list''.  In fact, this command is so commonly used that we abbreviate
+it to ``ls''.  Typing @code{ls} in a command shell is a script way of
+telling the computer to list your files.  This is comparable to viewing
+the contents of a folder using a graphical display.
+
+The real flexibility is apparent only when you realize that there are
+many, many ways to list your files.  Perhaps you want them sorted by
+name, or sorted by date, or in reverse order, or grouped by type.  Most
+graphical browsers have simple ways to express this.  But what about
+showing only a few files, or only files that meet a certain criteria?
+In very complex and specific situations, the request becomes too
+difficult to express with a mouse.  It is just these kinds of requests
+that are solvable using a command shell.
+
+For example, what if you want to list every Word file on your hard
+drive, larger than 100 kilobytes in size, and which hasn't been looked
+at in over six months?  That is a good candidate list for deletion, when
+you go to clean up your hard drive.  But have you ever tried asking your
+computer for such a list?  There is no way to do it!  At least, not
+without using a command shell.
+
+So the role of a command shell is to give you more control over what
+your computer does for you.  Not everyone needs this amount of control,
+and it does come at a cost: Learning the necessary script commands to
+express what you want done.  A complicated query, such as the example
+above, takes time to learn.  But if you find yourself using your
+computer frequently enough, it is more than worthwhile in the long run.
+Any tool you use often deserves your time in learning to master it.
+@footnote{For the understandably curious, here is what that command
+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::      
+* Installation::                
+@end menu
+
+@node Contributors to Eshell, Installation, What is Eshell?, What is Eshell?
+@section Contributors to Eshell
+@cindex Contributors
+@cindex Authors
+
+Contributions to Eshell are welcome.  I have limited time to work on
+this project, but I will gladly add any code you contribute to me to
+this package.
+
+The following persons have made contributions to Eshell.
+
+@itemize @bullet
+@item
+Eli Zaretskii made it possible for Eshell to run without requiring
+asynchronous subprocess support.  This is important for MS-DOS, which
+does not have such support.@refill
+
+@item
+Miles Bader contributed many fixes during the port to Emacs 21.@refill
+
+@item
+Stefan Monnier fixed the things which bothered him, which of course made
+things better for all.@refill
+
+@item
+Gerd Moellmann also helped to contribute bug fixes during the initial
+integration with Emacs 21.@refill
+
+@item
+Alex Schroeder contributed code for interactively querying the user
+before overwriting files.@refill
+
+@item
+Sudish Joseph helped with some XEmacs compatibility issues.@refill
+
+@end itemize
+
+Apart from these, a lot of people have sent suggestions, ideas,
+requests, bug reports and encouragement.  Thanks a lot!  Without you
+there would be no new releases of Eshell.
+
+@node Installation,  , Contributors to Eshell, What is Eshell?
+@section Installation
+@cindex Installation
+
+As mentioned above, Eshell comes preinstalled since 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.emacs.org/~johnw/Emacs/eshell.tar.gz}.
+
+If you are using Emacs 21, please skip this section.
+
+@subsection Short Form
+
+Here's exactly what to do, with no explanation why:
+
+@enumerate
+@item @samp{M-x load-file RET eshell-auto.el RET}
+@item @samp{ESC : (add-to-list 'load-path "<path where Eshell resides>") RET}
+@item @samp{ESC : (add-to-list 'load-path "<path where Pcomplete resides>") RET}
+@item @samp{M-x eshell RET}
+
+You should see a version banner displayed.
+
+@item @samp{ls RET}
+
+Confirm that you see a file listing.
+
+@item @samp{eshell-test RET}
+
+Confirm that everything runs correctly.  Use `M-x eshell-report-bug' if
+not.
+
+@item @samp{cd $@{dirname (locate-library "eshell-auto")@} RET}
+@item @samp{find-file Makefile RET}
+@item Edit the Makefile to reflect your site.
+@item @samp{M-x eshell RET}
+@item @samp{make install RET}
+@item @samp{find-file $user-init-file RET}
+@item Add the following lines to your @file{.emacs} file:
+
+@example
+(add-to-list 'load-path "<directory where you install Eshell>")
+(load "eshell-auto")
+@end example
+
+@item @samp{M-x eshell RET}
+@item @samp{customize-option #'eshell-modules-list RET}
+@item Select the extension modules you prefer.
+@item Restart Emacs!
+@item @samp{M-x info RET m Eshell RET}
+
+Read the manual and enjoy!
+@end enumerate
+
+@subsection Long Form
+
+@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
+@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}.
+
+@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:
+
+@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
+Start Eshell from the distributed sources, using default settings, by
+typing @kbd{M-x eshell}.
+
+@item
+Verify that Eshell is functional by typing @command{ls} followed by
+@kbd{RET}.  You should have already seen a version banner announcing the
+version number of this release, followed by a prompt.
+
+@item
+Run the test suite by typing @command{eshell-test} followed by @kbd{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}.
+
+@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}.
+
+@item
+Type @code{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 @file{install-info} can be found.
+
+If you only want to create the compiled elisp files, but don't want to
+install them, you can type just @command{make} instead.
+
+@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
+
+The actual directory on your system may differ.
+
+@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:
+
+@example
+(load "eshell-auto")
+@end example
+
+@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
+
+If you have @TeX{} installed at your site, you can make a typeset manual
+from @file{eshell.texi}.
+
+@enumerate
+@item
+Run @TeX{} by typing @samp{texi2dvi eshell.texi}.
+@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.  There
+is also a program which comes together with @TeX{}, @code{dvips}, which
+you can use.
+@end enumerate
+
+@c @node Forming commands, Known problems, What is Eshell?, Top
+@c @chapter Forming commands
+
+@c A command shell is nothing more than a place to enter commands.
+
+@c What is a command?
+
+@c A command is piece of ``script''---or special shorthand
+@c language---that the computer can understand.
+
+@c What does script look like?
+
+@c Script is an extremely simplified language.  Oddly enough, this
+@c actually makes it look more complicated than it is.  Whereas normal
+@c languages can use many different embellishments, the form of a script
+@c command is always: a command verb, following by its arguments.
+
+@c A verb?  Arguments?
+
+@c The verb is the thing you want your computer to do.  There are a set
+@c number of verbs, although this number is quite large.  On my
+@c computer, it reaches almost 1400 in number!  But of course, only a
+@c handful of these are necessary most of the time.
+
+@c Sometimes, the verb is all that's necessary.  A verb is always a
+@c single word, usually related to the task it will perform.
+@c @command{reboot} is a good example.  Entering that will cause your
+@c computer to reboot, assuming you have sufficient privileges.
+
+@c Other verbs need more information.  These are usually very capable of
+@c verbs, but they must be told more specifically what to do.  This
+@c extra information is given in the form of arguments.  Arguments are
+@c also words, that appear after the verb.  For example, @command{echo}
+@c is a command verb that will print back to you whatever you say.
+@c @command{echo} requires a set of arguments, to know what you want it
+@c to echo!  So a proper use of echo might look like:
+
+@c @example
+@c echo This is an example of using echo!
+@c @end example
+
+@c This command would result in the computer printing back to you,
+@c ``This is an example of using echo!''.  Pretty easy, no?
+
+@c Although commands are always simple words, arguments can take
+@c different forms.  There are textual arguments, numeric arguments,
+@c even Lisp arguments.  Distinguishing among these different types of
+@c arguments requires some special typing, because the computer needs
+@c very specific directions to understand what you mean.
+
+@node Bugs and ideas,  , What is Eshell?, Top
+@chapter Bugs and ideas
+@cindex Reporting bugs and ideas
+@cindex Bugs, how to report them
+@cindex Author, how to reach
+@cindex Email to the author
+@cindex Known bugs
+@cindex Bugs, known
+@cindex FAQ
+@cindex Problems, list of common
+
+If you find a bug or misfeature, don't hesitate to let me know!  Send
+email to @samp{johnw@@gnu.org}.  Feature requests should also be sent
+there.  I prefer discussing one thing at a time.  If you find several
+unrelated bugs, please report them separately.
+
+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,  , Bugs and ideas, Bugs and ideas
+@section Known problems
+
+Below is a partial list of currently known problems with Eshell version
+2.3.2, which is the version distribution with Emacs 21.1.
+
+@table @asis
+@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} fails
+
+In fact, piping to a process from a looping construct doesn't work in
+general.  If I change the call to @code{eshell-copy-handles} in
+@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems
+to work, but the output occurs after the prompt is displayed.  The whole
+structured command thing is too complicated at present.
+
+@item Error with @command{bc} in @code{eshell-test}
+
+On some XEmacs system, the subprocess interaction test fails
+inexplicably, since @command{bc} works fine at the command prompt.
+
+@item @command{ls} in remote directories sometimes fails
+
+For XEmacs users, using @command{ls} in a remote directory sometimes
+fails.  The reason why has not yet been found.
+
+@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+
+
+In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that
+multiple instances of the @file{*Help*} buffer can exist.
+
+@item Pcomplete sometimes gets stuck
+
+When @kbd{TAB}, no completions appear, even though the directory has
+them.  This behavior is rare.
+
+@item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does
+
+This happens because the @code{grep} Lisp function returns immediately,
+and then the asynchronous @command{grep} process expects to examine the
+temporary file, which has since been deleted.
+
+@item Problem with C-r repeating text
+
+If the text @emph{before point} reads "./run", and you type @kbd{C-r r u
+n}, it will repeat the line for every character typed.
+
+@item Backspace doesn't scroll back after continuing (in smart mode)
+
+Hitting space during a process invocation, such as @command{make}, will
+cause it to track the bottom of the output; but backspace no longer
+scrolls back.
+
+@item It's not possible to fully @code{unload-feature} Eshell
+
+@item Menu support was removed, but never put back
+
+@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
+since.
+
+@item If an interactive process is currently running, @kbd{M-!} doesn't work
+
+@item Use a timer instead of @code{sleep-for} when killing child processes
+
+@item Piping to a Lisp function is not supported
+
+Make it so that the Lisp command on the right of the pipe is repeatedly
+called with the input strings as arguments.  This will require changing
+eshell-do-pipeline to handle non-process targets.
+
+@item Input redirection is not supported
+
+See the entry above.
+
+@c @item problem running "less" without argument on Windows
+@c Before running telnet, I noticed that 'less' (for example) was already
+@c configured as a visual command. So I invoked it from eshell to see what
+@c would happen.
+@c 
+@c Here's the result in the eshell buffer:
+@c 
+@c      Spawning child process: invalid argument
+@c 
+@c Also a new 'less' buffer was created with nothing in it .. (presumably this
+@c holds the output of less)
+@c 
+@c If I run 'less.exe' from the eshell command line, I get the output I expect
+@c simply written to the buffer.
+@c 
+@c Note that I'm using FSF NT-Emacs 20.6.1 on Win2000. The term.el package and
+@c the supplied shell both seem to use the 'cmdproxy' program to run things
+@c like shells.
+@c @item implement -r, -n and -s switches for cp
+@c @item Make M-5 eshell -> switch to *eshell<5>*, creating it if need be
+@c @item mv DIR FILE.tar does not remove directories
+@c This is because the tar option --remove-files doesn't do so.  Should
+@c it be Eshell's job?
+@c @item Write an article about Eshell for the LinuxWorld journal.
+@c @item bind standard-output and standard-error, so that if a Lisp function
+@c   calls `print', everything will happen as it should (albeit slowly)
+@c @item when the extension modules fail to load, cd / gives a Lisp error
+@c @item if a globbing patterns returns only one match, should it still be a
+@c   list?
+@c @item make sure that the syntax table correctly in eshell mode
+@c So that M-DEL acts in a predictable manner, etc.
+@c @item allow all Eshell buffers to share the same history and list-dir
+@c @item error with script commands and outputting to /dev/null
+@c If a script file, somewhere in the middle, does a "> /dev/null",
+@c output from all subsequent commands will be swallowed
+@c @item split up parsing of the text after a $ in eshell-var
+@c Similar to way that eshell-arg is structured.  Then add parsing of
+@c $[?\n]
+@c @item after pressing M-RET, redisplay before running the next command
+@c @item argument predicates and modifiers should work anywhere in a path
+@c   /usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)
+@c   Invalid regexp: "Unmatched ( or \\("
+@c 
+@c with zsh, the glob above expands to all files named Root in
+@c directories named CVS.
+@c @item typing "echo ${locate locate}/bin<tab>" results in a Lisp error
+@c Perhaps it should interpolate all permutations, and make that the
+@c globbing result, since otherwise hitting return here will result in
+@c "(list of filenames)/bin", which is never very valuable.  Thus, one
+@c could cat only c backup files by using "ls ${identity *.c}~".  In that
+@c case, having an alias command name `glob' for `identity' would be
+@c useful
+@c @item for XEmacs on Win32, fix `file-name-all-completions'
+@c Make sure it returns directory names terminated by
+@c `directory-sep-char' (which is initialized to be ?/), rather than
+@c backslash
+@c @item once symbolic mode is supported for umask, implement chmod in Lisp
+@c @item create `eshell-expand-file-name'
+@c Which uses a data table to transform things like "~+", "...", etc
+@c @item abstract `eshell-smart.el' into `smart-scroll.el'
+@c It only really needs: to be hooked onto the output filter and the
+@c pre-command hook, and to have the input-end and input-start markers.
+@c And to know whether the last output group was "successful".
+@c @item allow for fully persisting the state of Eshell
+@c vars, history, buffer, input, dir stack, etc.
+@c @item implement D in the predicate list
+@c It means that files beginning with a dot should be included in the
+@c glob match
+@c @item a comma in a predicate list means OR
+@c @item error if a glob doesn't expand due to a predicate
+@c An error should be generated only if `eshell-error-if-no-glob' is
+@c non-nil
+@c @item the following doesn't cause an indent-according-to-mode to occur
+@c (+ RET SPC TAB
+@c @item create `eshell-auto-accumulate-list'
+@c It is a list of commands for which, if the user presses RET, the text
+@c gets staged as the next Eshell command, rather than being sent to the
+@c current interactive
+@c @item display file and line number if an error occurs in a script
+@c @item wait doesn't work with process ids at the moment
+@c @item enable the direct-to-process input code in eshell-term.el
+@c @item problem with repeating "echo ${find /tmp}"
+@c With smart display active, if I hold down RET, after a while it can't
+@c keep up anymore and starts outputting blank lines.  It only happens if
+@c an asynchronous process is involved...
+@c 
+@c I think the problem is that `eshell-send-input' is resetting the input
+@c target location, so that if the asynchronous process is not done by
+@c the time the next RET is received, the input processor thinks that the
+@c input is meant for the process; which, because smart display is
+@c enabled, will be the text of the last command line!  That is a bug in
+@c itself.
+@c 
+@c In holding down RET while an asynchronous process is running, there
+@c will be a point in between termination of the process, and the running
+@c of eshell-post-command-hook, which would cause `eshell-send-input' to
+@c call `eshell-copy-old-input', and then process that text as a command
+@c to be run after the process.  Perhaps there should be a way of killing
+@c pending input between the death of the process, and the
+@c post-command-hook.
+@c @item allow for a more aggressive smart display mode
+@c Perhaps toggled by a command, that makes each output block a smart
+@c display block
+@c @item create more meta variables
+@c $! -- the reason for the failure of the last disk command, or the text
+@c       of the last Lisp error
+@c 
+@c $= -- a special associate array, which can take references of the form
+@c       $=[REGEXP].  It also indexes into the directory ring
+@c @item eshell scripts can't execute in the background
+@c @item support zsh's "Parameter Expansion" syntax, i.e. ${NAME:-VAL}
+@c @item write an `info' alias that can take arguments
+@c So that the user can enter "info chmod"
+@c @item split off more generic code from Eshell
+@c parse-args.el --- parse a list of arguments
+@c interpolate.el --- interpolate $variable $(lisp)... references
+@c interp.el --- find which interpretor to run a script with
+@c sh-ring.el --- extend ring.el for persistant, searchable history
+@c zsh-glob.el --- zsh-style globbing and predicate/modifiers
+@c smartdisp.el --- smart scrolling in input buffers
+@c egetopt.el --- `eshell-eval-using-options'
+@c prompt.el --- code for outputting and navigating prompts
+@c cmd-rebind.el --- rebind certain keys in the input text
+@c unix.el --- provides Lispish UNIX command, such as unix-rm, etc.
+@c emacs-ls.el --- implementation of ls in Emacs Lisp
+@c texidoc.el
+@c pushd.el --- implementation of pushd/popd in Lisp
+@c interface.el -- a mode for reading command-line input from the user
+@c @item create a mode `eshell-browse'
+@c It would treat the Eshell buffer as a outline.  Collapsing the outline
+@c hides all of the output text.  Collapsing again would show only the
+@c first command run in each directory
+@c @item look through the Korn Shell book for feature ideas
+@c @item allow other version of a file to be referenced by "file{rev}"
+@c This would be expanded by `eshell-expand-file-name'
+@c @item print "You have new mail" when the "Mail" icon gets turned on
+@c @item implement M-|
+@c @item implement input redirection
+@c If it's a lisp function, input redirection implies "xargs" (in a
+@c way..).  And if input redirection is added, don't forget to update the
+@c file-name-quote-list, and the delimiter list.
+@c @item allow #<WORD ARG> to be a generic syntax
+@c With the handling of "word" specified by an `eshell-special-alist'.
+@c @item in `eval-using-options', have a :complete tag
+@c It would be used to provide completion rules for that command.  Then
+@c the macro will automagically define the completion function
+@c @item for `eshell-command-on-region', redirections apply to the result
+@c So that "+ > 'blah" will cause the result of the `+' (using input from
+@c the current region) to be inserting in the symbol `blah'.
+@c 
+@c If a disk command is being invoked, the input is sent as standard
+@c input, as if a "cat <region> |" were invoked.
+@c 
+@c If a lisp command, or an alias, is invoked, then: if the line has no
+@c ^J characters, it is divided by whitespace and passed as arguments to
+@c the lisp function.  Otherwise, it is divided at the ^J characters.
+@c Thus, invoking `+' on a series of numbers will add them; `min' would
+@c display the smallest figure.
+@c @item write `eshell-script-mode' as a minor mode
+@c It would provide syntax, abbrev, highlighting and indenting support
+@c like emacs-lisp-mode + shell-mode.
+@c @item in the history mechanism, finish bash-style support
+@c For !n, !#, !:%, and !:1- as separate from !:1*
+@c @item support the -n command line option for "history"
+@c @item implement `fc'
+@c @item specifying a frame as a redirection target implies point's buffer
+@c @item implement ">FUNC-OR-FUNC-LIST"
+@c This would allow for an "output translator", that takes a function to
+@c modify output with, and the target.  Devise a syntax that words well
+@c with pipes, and can accomodate multiple functions (i.e.,">'(upcase
+@c regexp-quote)" or ">'upcase").
+@c @item allow Eshell to read/write to/from standard input and output
+@c This would be optional, rather than always using the Eshell buffer.
+@c This would allow it to be run from the command line.
+@c @item write a "help" command
+@c It could even call subcommands with "--help" (or "-h" or "/?").
+@c @item implement stty
+@c @item support rc's matching operator, "~ (list) regexp"
+@c @item implement "bg" and "fg" to edit `eshell-process-list'
+@c Using "bg" on a process that is already in the background does
+@c nothing.  Specifying redirection targets replaces (or adds) to the
+@c list current being used.
+@c @item have "jobs" print only the processes for the current eshell
+@c @item how do I discover that a background process has requested input?
+@c @item support 2>&1 and >& and 2> and |&
+@c The syntax table for parsing these should be customizable, such that
+@c the user could change it to use rc syntax: >[2=1].
+@c @item allow $_[-1], which reads the last element of the array, etc.
+@c @item make $x[*] equal to listing out the full contents of x
+@c Return them as a list, so that $_[*] is all the arguments of the last
+@c command.
+@c @item move ANSI code handling from `term' into `eshell-term'
+@c And make it possible for the user to send char-by-char to the
+@c underlying process.  Ultimately, I should be able to move away from
+@c using term.el altogether, since everything but the ANSI code handling
+@c is already part of Eshell.  Then, things would work correctly on Win32
+@c as well (which doesn't have "/bin/sh", though term tries to use it)
+@c @item have other shell spawning commands be visual
+@c Make (su, bash, telnet, rlogin, rsh, etc.) be part of
+@c `eshell-visual-commands'.  The only exception is if rsh/su/bash are
+@c simply being used to invoke a single command.  Then, it should be
+@c based on what that command is.
+@c @item create an alias "open"
+@c This will search for some way to open its argument (similar to opening
+@c a file in the Windows Explorer).  Perhaps using ffap...
+@c @item alias "read" to be the same as "open", except read-only
+@c @item write a "tail -f" alias which does a view-file
+@c I.e., it moves point to the end of the buffer, and then turns on
+@c auto-revert mode in that buffer at frequent intervals -- and a head
+@c alias which assums an upper limit of `eshell-maximum-line-length'
+@c characters per line.
+@c @item make dgrep load dired, mark everything, then execute the A binding
+@c @item write emsh.c
+@c It just runs Emacs with the appropriate arguments to invoke eshell.
+@c That way, it could be listed as a login shell.
+@c @item use an intangible PS2 string for multi-line input prompts
+@c @item auto-detect when a command is visual, by checking TERMCAP usage
+@c @item First keypress after M-x watson triggers `eshell-send-input'
+@c @item Emacs 20.3: Figure out why pcomplete won't make
+@c @item Make / electric
+@c So that it automatically expands and corrects pathnames.  Or make
+@c pathname completion for pcomplete auto-expand "/u/i/std<TAB>" to
+@c "/usr/include/std<TAB>".
+@c @item Write pushd/popd out to disk along with last-dir-ring
+@c @item add options to eshell/cat which would cause it to sort and uniq
+@c @item implement in Lisp: wc.  Also count sentences, paragraphs, pages.
+@c @item once piping is added, implement sort and uniq
+@c @item implement touch
+@c @item implement epatch
+@c Calls ediff-patch-file, or ediff-patch-buffer, depending on its
+@c argument.
+@c @item have an option for bringing up ls -l result in a dired buffer
+@c @item write a version of xargs that's based on command rewriting
+@c find X | xargs Y == Y ${find X}.  Maybe I could change
+@c eshell-do-pipelines to perform this on-thy-fly rewriting.
+@c @item implement head and tail in Lisp
+@c @item write an alias for less and more that brings up a view buffer
+@c Such that they can press SPC and DEL, and then q to return to eshell.
+@c The more command would be equivalent to: X > #<buffer Y>; view-buffer
+@c #<buffer Y>
+@c @item differentiate between aliases and functions
+@c Allow for a bash-compatible syntax, such as:
+@c 
+@c   alias arg=blah
+@c   function arg () { blah $* }
+@c @item find the various references to shell-mode within Emacs
+@c And add support for Eshell there, since now Eshell is going to be part
+@c of Emacs.
+@c @item permit umask to be set on a cp target during the cp command
+@c @item if the first thing that I do after I enter Emacs
+@c is to run eshell-command and invoke ls, and then I use M-x eshell, it
+@c doesn't show me anything.
+@c @item M-RET during a long command doesn't quite work
+@c Since it keeps the cursor up where the command was invoked.
+@end table
+
+@unnumbered Function and Variable Index
+
+@printindex fn
+
+@unnumbered Concept Index
+
+@printindex cp
+
+@unnumbered Key Index
+
+@printindex ky
+
+@setchapternewpage odd
+@summarycontents
+@contents
+@bye