\input texinfo @c -*-texinfo-*-
-@c "@(#)$Name: $:$Id: eshell.texi,v 1.5 2000/10/29 05:46:42 johnw Exp $"
+@c "@(#)$Name: $:$Id: eshell.texi,v 1.13 2002/06/17 11:50:12 kai Exp $"
@c Documentation for Eshell: The Emacs Shell.
-@c Copyright (C) 1999-2000 Free Software Foundation, Inc.
+@c Copyright (C) 1999, 2000 Free Software Foundation, Inc.
@c This file is part of GNU Emacs
@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.
+Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
+
+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.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
@end ifinfo
@synindex vr fn
@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.
+Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
+
+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.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License. If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
@end titlepage
@contents
@c The real text starts here
@c ================================================================
-@node Top, What is Eshell?, (dir), (dir)
@ifinfo
+@node Top, What is Eshell?, (dir), (dir)
@top Eshell
This manual documents Eshell, a shell-like command interpretor
@end ifinfo
@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.
-* Concept Index::
-* Function and Variable Index::
-* Key Index::
+* 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.
+* 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
-@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
-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
-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
-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
* 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
@item
Edit the file @file{Makefile} in the directory containing the Eshell
-sources to reflect the location of certain Emacs dircetories at your
+sources to reflect the location of certain Emacs directories 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}.
e.g., @code{dvilj4} for LaserJet-compatible printers.
@end enumerate
-@node Command basics, Bugs and ideas, Installation, Top
-@chapter Command basics
+@node Command basics
+@chapter Basic overview
-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.
+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, Command arguments, Command basics, Command basics
+@node Commands verbs
@section Commands verbs
Commands are expressed using @dfn{script}, a special shorthand language
-that computers can understand without trouble.
-
-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:
+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
- VERB [ARGUMENTS]
+@var{verb} [@var{arguments}]
@end example
The verb expresses what you want your computer to do. There are a fixed
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 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
+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
-This piece of script expresses a command that causes the computer to
-print back: ``This is an example of using echo!''.
+This script command causes the computer to echo 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.
+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.
-@node Command arguments, , Commands verbs, Command basics
+@node Command arguments
@section Command arguments
-@node Bugs and ideas, Concept Index, Command basics, Top
+Eshell recognizes several different kinds of command arguments:
+
+@enumerate
+@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
+
+Most users need to worry only about the first two. The third, Lisp lists,
+occur very frequently, but almost always behind the scenes.
+
+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.
+
+Here is a more complicated @command{echo} example:
+
+@example
+echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar
+@end example
+
+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!
+
+@node Commands
+@chapter Commands
+
+@menu
+* Invocation::
+* Completion::
+* Aliases::
+* History::
+* 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).
+
+@end table
+
+@node Scripts
+@section Scripts
+
+
+@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
+* The Parser::
+* Variables::
+* Substitution::
+* Globbing::
+* Predicates::
+@end menu
+
+@node The Parser
+@section The Parser
+
+@node Variables
+@section Variables
+
+@node Substitution
+@section Substitution
+
+@node Globbing
+@section Globbing
+
+@node Predicates
+@section Predicates
+
+
+@node Input/Output
+@chapter Input/Output
+
+@node Process control
+@chapter Process control
+
+
+@node Extension modules
+@chapter Extension modules
+
+@menu
+* Writing a module::
+* Module testing::
+* Directory handling::
+* Key rebinding::
+* Smart scrolling::
+* Terminal emulation::
+* Built-in UNIX commands::
+@end menu
+
+@node Writing a module
+@section Writing a module
+
+@node Module testing
+@section Module testing
+
+@node Directory handling
+@section Directory handling
+
+@node Key rebinding
+@section Key rebinding
+
+@node Smart scrolling
+@section Smart scrolling
+
+@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
@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
-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
@item Differentiate between aliases and functions
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:
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 MS-Windows
-
-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}
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
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.
@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.
@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
HCoop / bpt / emacs.git / blobdiff