\input texinfo @c -*-texinfo-*-
+@c "@(#)$Name: $:$Id: eshell.texi,v 1.16 2002/10/02 23:24:31 karl Exp $"
+@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.9 2001/01/28 18:48:45 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 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
-@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.
@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.
+@insertcopying
@end titlepage
@contents
@c The real text starts here
@c ================================================================
+@ifnottex
@node Top, What is Eshell?, (dir), (dir)
-@ifinfo
@top Eshell
This manual documents Eshell, a shell-like command interpretor
@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
* What is Eshell?:: A brief introduction to the Emacs Shell.
* 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
* 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
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
+@node Installation
@chapter Installation
@cindex installation
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}.
+@url{http://www.gci-net.com/users/j/johnw/Emacs/packages/eshell.tar.gz}.
However, if you are using Emacs 21, you may skip this section.
e.g., @code{dvilj4} for LaserJet-compatible printers.
@end enumerate
-@node Command basics, Commands, Installation, Top
+@node Command basics
@chapter Basic overview
A command shell is a means of entering verbally-formed commands. This
* Command arguments:: Some verbs require arguments.
@end menu
-@node Commands verbs, Command arguments, Command basics, Command basics
+@node Commands verbs
@section Commands verbs
Commands are expressed using @dfn{script}, a special shorthand language
Distinguishing these different types of arguments requires special
typing, for the computer to know exactly what you mean.
-@node Command arguments, , Commands verbs, Command basics
+@node Command arguments
@section Command arguments
Eshell recognizes several different kinds of command arguments:
commands on your system; then come back when it all sits more familiarly
on your mind. Have fun!
-@node Commands, Arguments, Command basics, Top
+@node Commands
@chapter Commands
@menu
* Aliases::
* History::
* Scripts::
+* Built-ins::
@end menu
-@node Invocation, Completion, Commands, Commands
+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
-@node Completion, Aliases, Invocation, Commands
+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, History, Completion, Commands
+@node Aliases
@section Aliases
-@node History, Scripts, Aliases, Commands
+@node History
@section History
-@node Scripts, , History, Commands
+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).
+
+@end table
+
+@node Scripts
@section Scripts
-@node Arguments, Input/Output, Commands, Top
+@node Built-ins
+@section Built-in commands
+
+Here is a list of built-in commands that Eshell knows about:
+
+@table @code
+
+@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:
+
+When it receives no argument at all, it changes to the home directory.
+
+Giving the command @samp{cd -} changes back to the previous working
+directory (this is the same as @samp{cd $-}).
+
+The command @samp{cd =} shows the directory stack. Each line is
+numbered.
+
+With @samp{cd =foo}, Eshell searches the directory stack for a
+directory matching the regular expression @samp{foo} and changes to
+that directory.
+
+With @samp{cd -42}, you can access the directory stack by number.
+
+@end table
+
+
+@node Arguments
@chapter Arguments
@menu
* Predicates::
@end menu
-@node The Parser, Variables, Arguments, Arguments
+@node The Parser
@section The Parser
-@node Variables, Substitution, The Parser, Arguments
+@node Variables
@section Variables
-@node Substitution, Globbing, Variables, Arguments
+@node Substitution
@section Substitution
-@node Globbing, Predicates, Substitution, Arguments
+@node Globbing
@section Globbing
-@node Predicates, , Globbing, Arguments
+@node Predicates
@section Predicates
-@node Input/Output, Process control, Arguments, Top
+@node Input/Output
@chapter Input/Output
-@node Process control, Extension modules, Input/Output, Top
+@node Process control
@chapter Process control
-@node Extension modules, Extras and Goodies, Process control, Top
+@node Extension modules
@chapter Extension modules
@menu
* Built-in UNIX commands::
@end menu
-@node Writing a module, Module testing, Extension modules, Extension modules
+@node Writing a module
@section Writing a module
-@node Module testing, Directory handling, Writing a module, Extension modules
+@node Module testing
@section Module testing
-@node Directory handling, Key rebinding, Module testing, Extension modules
+@node Directory handling
@section Directory handling
-@node Key rebinding, Smart scrolling, Directory handling, Extension modules
+@node Key rebinding
@section Key rebinding
-@node Smart scrolling, Terminal emulation, Key rebinding, Extension modules
+@node Smart scrolling
@section Smart scrolling
-@node Terminal emulation, Built-in UNIX commands, Smart scrolling, Extension modules
+@node Terminal emulation
@section Terminal emulation
-@node Built-in UNIX commands, , Terminal emulation, Extension modules
+@node Built-in UNIX commands
@section Built-in UNIX commands
-@node Extras and Goodies, Bugs and ideas, Extension modules, Top
+@node Extras and Goodies
@chapter Extras and Goodies
-@node Bugs and ideas, Concept Index, Extras and Goodies, Top
+@node Bugs and ideas
@chapter Bugs and ideas
@cindex reporting bugs and ideas
@cindex bugs, how to report them
* Known problems::
@end menu
-@node Known problems, , Bugs and ideas, Bugs and ideas
+@node Known problems
@section Known problems
@cindex known bugs
@cindex bugs, known
@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
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
@end table
-@node Concept Index, Function and Variable Index, Bugs and ideas, Top
+@node Concept Index
@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
-@node Key Index, , Function and Variable Index, Top
+@node Key Index
@unnumbered Key Index
@printindex ky