+2013-02-08 Aidan Gauland <aidalgol@no8wireless.co.nz>
+
+ * eshell.texi: Fill most of the missing sections.
+
2013-02-07 Bastien Guerry <bzg@gnu.org>
* org.texi (References): Clarify an example.
from ede new.
(Simple projects): Re-write to not talk about ede-simple-project
which is deprecated, and instead use the term to mean projects
- that don't do much management, just project wrapping. Add
- ede-generic-project link.
+ that don't do much management, just project wrapping.
+ Add ede-generic-project link.
(ede-generic-project): New node (bug#11441).
2013-02-03 Glenn Morris <rgm@gnu.org>
* ede.texi (Top): Rename from top, all uses changed.
* eshell.texi: Add missing argument to @sp.
* forms.texi (Top): Reorder menu to match structure.
- * htmlfontify.texi (Customisation): Add missing @item in
- @enumerate.
+ * htmlfontify.texi (Customisation): Add missing @item in @enumerate.
* org.texi (Advanced features): Add missing argument for @item.
(Property searches): Use @backslashchar{} in macro argument.
* pcl-cvs.texi: Add missing argument to @sp.
* org.texi (Summary, Code block specific header arguments)
(Code block specific header arguments)
(Header arguments in function calls, var, noweb)
- (Results of evaluation, Code evaluation security): Small
- reformatting: add a blank line before some example.
+ (Results of evaluation, Code evaluation security):
+ Small reformatting: add a blank line before some example.
* org.texi (System-wide header arguments)
(Header arguments in Org mode properties, Conflicts)
* org.texi (Comment lines): Fix description of the comment syntax.
- * org.texi (Installation): Mention "make test" in the correct
- section.
+ * org.texi (Installation): Mention "make test" in the correct section.
2012-12-02 Michael Albinus <michael.albinus@gmx.de>
2012-11-08 Chong Yidong <cyd@gnu.org>
- * url.texi (Introduction): Rename from Getting Started. Rewrite
- the introduction.
+ * url.texi (Introduction): Rename from Getting Started.
+ Rewrite the introduction.
(URI Parsing): Rewrite. Omit the obsolete attributes slot.
2012-11-07 Glenn Morris <rgm@gnu.org>
2012-10-26 Bastien Guerry <bzg@gnu.org>
- * org.texi (Installation): Update the link to Org's ELPA. Also
- don't mention org-install.el anymore as the replacement file
+ * org.texi (Installation): Update the link to Org's ELPA.
+ Also don't mention org-install.el anymore as the replacement file
org-loaddefs.el is now loaded by org.el.
2012-10-25 Michael Albinus <michael.albinus@gmx.de>
- * tramp.texi (Frequently Asked Questions): Mention
- `tramp-completion-reread-directory-timeout' for performance
+ * tramp.texi (Frequently Asked Questions):
+ Mention `tramp-completion-reread-directory-timeout' for performance
improvement.
2012-10-25 Glenn Morris <rgm@gnu.org>
(Imprint): Mention Wolfgang in list of contributors.
(Creating Citations): Give a hint about how to
auto-revert the BibTeX database file when using external editors.
- (Referencing Labels): Simplify section about reference macro
- cycling.
+ (Referencing Labels): Simplify section about reference macro cycling.
(Options (Referencing Labels)): Adapt to new structure of
`reftex-ref-style-alist'.
(Referencing Labels, Reference Styles): Document changes in the
(Referencing Labels): Update regarding reference styles.
(Citation Styles): Mention support for ConTeXt.
(Options (Defining Label Environments)): Fix typo.
- (Options (Creating Citations)): Document
- `reftex-cite-key-separator'.
+ (Options (Creating Citations)):
+ Document `reftex-cite-key-separator'.
2012-09-30 Achim Gratz <Stromeko@Stromeko.DE>
2012-09-30 Bastien Guerry <bzg@gnu.org>
- * org.texi (Installation, Feedback, Batch execution): Use
- (add-to-list 'load-path ... t) for the contrib dir.
+ * org.texi (Installation, Feedback, Batch execution):
+ Use (add-to-list 'load-path ... t) for the contrib dir.
* org.texi (results): Update documentation for ":results drawer"
and ":results org".
* org.texi (History and Acknowledgments): Fix typo.
- * org.texi (History and Acknowledgments): Add my own
- acknowledgments.
+ * org.texi (History and Acknowledgments): Add my own acknowledgments.
* org.texi (Agenda commands): Document the new command and the new
option.
* org.texi (Agenda commands): Delete `org-agenda-action' section.
- (Agenda commands): Reorder. Document `*' to toggle persistent
- marks.
+ (Agenda commands): Reorder. Document `*' to toggle persistent marks.
- * org.texi (Agenda dispatcher): Mention
- `org-toggle-agenda-sticky'.
+ * org.texi (Agenda dispatcher):
+ Mention `org-toggle-agenda-sticky'.
(Agenda commands, Exporting Agenda Views): Fix typo.
* org.texi (Templates in contexts, Setting Options): Update to
* org.texi (Formula syntax for Lisp): Reformat.
* org.texi (Special properties, Column attributes)
- (Agenda column view): Document the new special property
- CLOCKSUM_T.
+ (Agenda column view): Document the new special property CLOCKSUM_T.
* org.texi (Template expansion): Document the new %l template.
(Unsafe Simplifications): Mention `m E'.
(Simplification of Units): Mention `m U'.
(Trigonometric/Hyperbolic Functions, Reducing and Mapping)
- (Kinds of Declarations, Functions for Declarations): Mention
- "algebraic simplifications" instead of `a s'.
+ (Kinds of Declarations, Functions for Declarations):
+ Mention "algebraic simplifications" instead of `a s'.
(Algebraic Entry): Remove mention of default simplifications.
2012-07-30 Jay Belanger <jay.p.belanger@gmail.com>
2012-07-06 Michael Albinus <michael.albinus@gmx.de>
- * tramp.texi (Multi-hops): Introduce
- `tramp-restricted-shell-hosts-alist'.
+ * tramp.texi (Multi-hops):
+ Introduce `tramp-restricted-shell-hosts-alist'.
2012-06-26 Lars Magne Ingebrigtsen <larsi@gnus.org>
(Synchronous Methods): Remove obsolete dbus-call-method-non-blocking.
(Asynchronous Methods): Fix description of
dbus-call-method-asynchronously.
- (Receiving Method Calls): Fix some minor errors. Add
- dbus-interface-emacs.
+ (Receiving Method Calls): Fix some minor errors.
+ Add dbus-interface-emacs.
(Signals): Describe unicast signals and the new match rules.
(Alternative Buses): Add the PRIVATE optional argument to
dbus-init-bus. Describe its new return value. Add dbus-setenv.
2012-04-09 Eli Zaretskii <eliz@gnu.org>
- * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add
- emacs-gnutls.
+ * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean):
+ Add emacs-gnutls.
($(infodir)/emacs-gnutls, emacs-gnutls.dvi): New targets.
2012-04-09 Teodor Zlatanov <tzz@lifelogs.com>
2012-04-01 Carsten Dominik <carsten.dominik@gmail.com>
* org.texi (MobileOrg): Change the wording to reflect that the
- Android Version is no longer just the little brother of the iOS
- version.
+ Android Version is no longer just the little brother of the iOS version.
2012-04-01 Eric Schulte <eric.schulte@gmx.com>
- * org.texi (Key bindings and useful functions): Updated babel key
+ * org.texi (Key bindings and useful functions): Update babel key
binding documentation in manual.
2012-04-01 Eric Schulte <eric.schulte@gmx.com>
2012-02-13 Lars Ingebrigtsen <larsi@gnus.org>
- * gnus.texi (Customizing the IMAP Connection): Mention
- nnimap-record-commands.
+ * gnus.texi (Customizing the IMAP Connection):
+ Mention nnimap-record-commands.
2012-02-10 Glenn Morris <rgm@gnu.org>
2012-01-03 Eric Schulte <eric.schulte@gmx.com>
* org.texi (Noweb reference syntax): Adding documentation of
- the `*org-babel-use-quick-and-dirty-noweb-expansion*'
- variable.
+ the `*org-babel-use-quick-and-dirty-noweb-expansion*' variable.
2012-01-03 Bastien Guerry <bzg@gnu.org>
2012-01-03 Bernt Hansen <bernt@norang.ca>
- * org.texi (Agenda commands): Document
- `org-clock-report-include-clocking-task'.
+ * org.texi (Agenda commands):
+ Document `org-clock-report-include-clocking-task'.
2012-01-03 Bastien Guerry <bzg@gnu.org>
2012-01-03 Thomas Dye <dk@poto.local>
- * org.texi: Changed DATA to NAME in Working With Source Code
- section.
+ * org.texi: Changed DATA to NAME in Working With Source Code section.
2012-01-03 Tom Dye <tsd@tsdye.com>
2012-01-03 Eric Schulte <schulte.eric@gmail.com>
- * org.texi (Buffer-wide header arguments): Update
- documentation to reflect removal of #+PROPERTIES.
+ * org.texi (Buffer-wide header arguments):
+ Update documentation to reflect removal of #+PROPERTIES.
2012-01-03 Carsten Dominik <carsten.dominik@gmail.com>
2012-01-03 Tom Dye <tsd@tsdye.com>
- * org.texi: Added a line to specify that header arguments are
- lowercase.
+ * org.texi: Added a line to specify that header arguments are lowercase.
2012-01-03 Tom Dye <tsd@tsdye.com>
2012-01-03 David Maus <dmaus@ictsoc.de>
- * org.texi (Exporting Agenda Views, Extracting agenda
- information): Fix command line syntax, quote symbol parameter
- values.
+ * org.texi (Exporting Agenda Views, Extracting agenda information):
+ Fix command line syntax, quote symbol parameter values.
2012-01-03 David Maus <dmaus@ictsoc.de>
* mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
release 8.3.
- (Preface): Updated support information.
+ (Preface): Update support information.
(From Bill Wohler): Reset text to original version. As a
historical quote, the tense should be correct in the time that it
was written.
2011-08-15 Bastien Guerry <bzg@gnu.org>
- * org.texi (Languages): Add Lilypond and Awk as supported
- languages.
+ * org.texi (Languages): Add Lilypond and Awk as supported languages.
2011-08-15 Achim Gratz <stromeko@nexgo.de>
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
* org.texi (Results of evaluation): More explicit about the
- mechanism through which interactive evaluation of code is
- performed.
+ mechanism through which interactive evaluation of code is performed.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
2011-08-15 Puneeth Chaganti <punchagan@gmail.com>
- * org.texi (Agenda commands): Doc for function option to bulk
- action.
+ * org.texi (Agenda commands): Doc for function option to bulk action.
2011-08-15 Carsten Dominik <carsten.dominik@gmail.com>
- * org.texi (Template expansion): Document new %<...> template
- escape.
+ * org.texi (Template expansion): Document new %<...> template escape.
2011-08-15 Carsten Dominik <carsten.dominik@gmail.com>
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
- * org.texi (padline): Documentation of the new padline header
- argument.
+ * org.texi (padline): Documentation of the new padline header argument.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
- * org.texi (var): Clarification of indexing into tabular
- variables.
+ * org.texi (var): Clarification of indexing into tabular variables.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
2011-08-15 Bastien Guerry <bzg@gnu.org>
- * org.texi (Dynamic blocks, Structure editing): Mention
- the function `org-narrow-to-block'.
+ * org.texi (Dynamic blocks, Structure editing):
+ Mention the function `org-narrow-to-block'.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
- * org.texi (Conflicts): Changed "yasnippets" to "yasnippet" and
+ * org.texi (Conflicts): Change "yasnippets" to "yasnippet" and
added extra whitespace around functions to be consistent with the
rest of the section.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
- * org.texi (Evaluating code blocks): Expanded discussion of
+ * org.texi (Evaluating code blocks): Expand discussion of
#+call: line syntax.
- (Header arguments in function calls): Expanded discussion of
+ (Header arguments in function calls): Expand discussion of
#+call: line syntax.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
2011-08-15 Tom Dye <tsd@tsdye.com>
- * org.texi (cache): Improved documentation of code block caches.
+ * org.texi (cache): Improve documentation of code block caches.
2011-08-15 Tom Dye <tsd@tsdye.com>
- * org.texi (Code block specific header arguments): Documentation
- of multi-line header arguments.
+ * org.texi (Code block specific header arguments):
+ Documentation of multi-line header arguments.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
- * org.texi (Code evaluation security): Add example for using a
- function.
+ * org.texi (Code evaluation security): Add example for using a function.
2011-08-15 Eric Schulte <schulte.eric@gmail.com>
2011-07-14 Lars Magne Ingebrigtsen <larsi@gnus.org>
* widget.texi (Setting Up the Buffer): Remove mention of the
- global keymap parent, which doesn't seem to be accurate
- (bug#7045).
+ global keymap parent, which doesn't seem to be accurate (bug#7045).
2011-07-12 Lars Magne Ingebrigtsen <larsi@gnus.org>
2011-07-04 Michael Albinus <michael.albinus@gmx.de>
- * tramp.texi (Cleanup remote connections): Add
- `tramp-cleanup-this-connection'.
+ * tramp.texi (Cleanup remote connections):
+ Add `tramp-cleanup-this-connection'.
2011-07-03 Lars Magne Ingebrigtsen <larsi@gnus.org>
* gnus.texi (Subscription Methods): Link to "Group Levels" to explain
zombies.
(Checking New Groups): Ditto (bug#8974).
- (Checking New Groups): Moved the reference to the right place.
+ (Checking New Groups): Move the reference to the right place.
2011-07-03 Dave Abrahams <dave@boostpro.com> (tiny change)
2011-06-26 Lars Magne Ingebrigtsen <larsi@gnus.org>
- * gnus.texi (Summary Mail Commands): Document
- `gnus-summary-reply-to-list-with-original'.
+ * gnus.texi (Summary Mail Commands):
+ Document `gnus-summary-reply-to-list-with-original'.
2011-06-20 Stefan Monnier <monnier@iro.umontreal.ca>
* gnus.texi (nnmairix caveats, Setup, Registry Article Refer Method)
(Fancy splitting to parent, Store arbitrary data):
- Updated gnus-registry docs.
+ Update gnus-registry docs.
2011-04-13 Juanma Barranquero <lekktu@gmail.com>
2011-03-06 Jay Belanger <jay.p.belanger@gmail.com>
- * calc.texi (Logarithmic Units): Rename calc-logunits-dblevel
- and calc-logunits-nplevel to calc-dblevel and calc-nplevel,
- respectively.
+ * calc.texi (Logarithmic Units): Rename calc-logunits-dblevel and
+ calc-logunits-nplevel to calc-dblevel and calc-nplevel, respectively.
(Musical Notes): New section.
(Customizing Calc): Mention the customizable variable
calc-note-threshold.
Sync with Tramp 2.1.19.
- * tramp.texi (Inline methods, Default Method): Mention
- `tramp-inline-compress-start-size'. Remove "kludgy" phrase.
+ * tramp.texi (Inline methods, Default Method):
+ Mention `tramp-inline-compress-start-size'. Remove "kludgy" phrase.
Remove remark about doubled "-t" argument.
(Auto-save and Backup): Remove reference to Emacs 21.
(Filename Syntax): Describe port numbers.
2007-10-28 Kevin Greiner <kevin.greiner@compsol.cc>
* gnus.texi (nntp-open-via-telnet-and-telnet): Fix grammar.
- (Agent Parameters): Updated parameter names to match code.
+ (Agent Parameters): Update parameter names to match code.
(Group Agent Commands): Corrected 'gnus-agent-fetch-series' as
'gnus-agent-summary-fetch-series'.
(Agent and flags): New section providing a generalized discussion
(Tag searches): Document regular expression search for tags.
(Stuck projects): New section.
(In-buffer settings): New keywords.
- (History and Acknowledgments): Updated description.
+ (History and Acknowledgments): Update description.
2007-02-24 Alan Mackenzie <acm@muc.de>
(Custom agenda views): Section completely rewritten.
(Summary): Compare with Planner.
(Feedback): More info about creating backtraces.
- (Plain lists): Modified example.
+ (Plain lists): Modify example.
(Breaking down tasks): New section.
(Custom time format): New section.
(Time stamps): Document inactive timestamps.
@c %**start of header
@setfilename ../../info/eshell
@settitle Eshell: The Emacs Shell
+@defindex cm
@synindex vr fn
@c %**end of header
@c -release-
@end ignore
@sp 3
-@center John Wiegley
+@center John Wiegley & Aidan Gauland
@c -date-
@page
* What is Eshell?:: A brief introduction to the Emacs Shell.
* Command basics:: The basics of command usage.
* Commands::
-* Arguments::
+* Expansion::
* Input/Output::
-* Process control::
* Extension modules::
-* Extras and Goodies::
* Bugs and ideas:: Known problems, and future ideas.
* GNU Free Documentation License:: The license for this documentation.
* Concept Index::
* Function and Variable Index::
* Key Index::
+* Command Index::
@end menu
@node What is Eshell?
@node Commands
@chapter Commands
+In a command shell, everything is done by invoking commands. This
+chapter covers command invocations in Eshell, including the command
+history and invoking commands in a script file.
+
@menu
* Invocation::
-* Completion::
+* Arguments::
+* Variables::
+* Built-ins::
* Aliases::
* History::
+* Completion::
+* for loop::
* Scripts::
-* Built-ins::
@end menu
-Essentially, a command shell is all about invoking commands---and
-everything that entails. So understanding how Eshell invokes commands
-is the key to comprehending how it all works.
-
@node Invocation
@section Invocation
-
Unlike regular system shells, Eshell never invokes kernel functions
directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
available in the Emacs Lisp library. It does this by transforming the
-command you specify into a callable Lisp form.@footnote{To see the Lisp
-form that will be invoked, type: @samp{eshell-parse-command "echo
-hello"}}
-
-This transformation, from the string of text typed at the command
-prompt, to the ultimate invocation of either a Lisp function or external
-command, follows these steps:
-
-@enumerate
-@item Parse the command string into separate arguments.
-@item
-@end enumerate
-
-@node Completion
-@section Completion
-
-@node Aliases
-@section Aliases
-
-@node History
-@section History
-
-Eshell knows a few built-in variables:
-
-@table @code
-
-@item $+
-@vindex $+
-This variable always contains the current working directory.
-
-@item $-
-@vindex $-
-This variable always contains the previous working directory (the
-current working directory from before the last @code{cd} command).
-
-@item $_
-@vindex $_
-It refers to the last argument of the last command.
-
-@item $$
-@vindex $$
-This is the result of the last command. In case of an external
-command, it is @code{t} or @code{nil}.
-
-@item $?
-@vindex $?
-This variable contains the exit code of the last command (0 or 1 for
-Lisp functions, based on successful completion).
-
-@end table
-
-@node Scripts
-@section Scripts
+input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}}
+
+The command can be either an Elisp function or an external command.
+Eshell looks first for an @ref{Aliases, alias} with the same name as the
+command, then a @ref{Built-ins, built-in command} or a function with the
+same name; if there is no match, it then tries to execute it as an
+external command.
+
+The semicolon (@code{;}) can be used to separate multiple command
+invocations on a single line. A command invocation followed by an
+ampersand (@code{&}) will be run in the background. Eshell has no job
+control, so you can not suspend or background the current process, or
+bring a background process into the foreground. That said, background
+processes invoked from Eshell can be controlled the same way as any
+other background process in Emacs.
+@node Arguments
+@section Arguments
+Command arguments are passed to the functions as either strings or
+numbers, depending on what the parser thinks they look like. If you
+need to use a function that takes some other data type, you will need to
+call it in an Elisp expression (which can also be used with
+@ref{Expansion, expansions}). As with other shells, you can
+escape special characters and spaces with the backslash (@code{\}) and
+the single (@code{''}) and double (@code{""}) quotes.
@node Built-ins
-@section Built-in commands
+@section Built-in commands
Several commands are built-in in Eshell. In order to call the
external variant of a built-in command @code{foo}, you could call
@code{*foo}. Usually, this should not be necessary. You can check
@end example
If you want to discard a given built-in command, you could declare an
-alias, @ref{Aliases}. Eample:
+alias, @ref{Aliases}. Example:
@example
~ $ which sudo
sudo is an alias, defined as "*sudo $*"
@end example
-Some of the built-in commands have a special behavior in Eshell:
+@vindex eshell-prefer-lisp-functions
+If you would prefer to use the built-in commands instead of the external
+commands, set @var{eshell-prefer-lisp-functions} to @code{t}.
+
+Some of the built-in commands have different behaviour from their
+external counterparts, and some have no external counterpart. Most of
+these will print a usage message when given the @code{--help} option.
@table @code
+@item addpath
+@cmindex addpath
+Adds a given path or set of paths to the PATH environment variable, or,
+with no arguments, prints the current paths in this variable.
+
+@item alias
+@cmindex alias
+Define an alias (@pxref{Aliases}). This does not add it to the aliases
+file.
+
+@item date
+@cmindex date
+Similar to, but slightly different from, the GNU Coreutils
+@command{date} command.
+
+@item define
+@cmindex define
+Define a varalias. @xref{Variable Aliases, , , elisp}.
+
+@item diff
+@cmindex diff
+Use Emacs's internal @code{diff} (not to be confused with
+@code{ediff}). @xref{Comparing Files, , , elisp}.
+
+@item grep
+@cmindex grep
+@itemx agrep
+@cmindex agrep
+@itemx egrep
+@cmindex egrep
+@itemx fgrep
+@cmindex fgrep
+@itemx glimpse
+@cmindex glimpse
+The @command{grep} commands are compatible with GNU @command{grep}, but
+use Emacs's internal @code{grep} instead.
+
+@item info
+@cmindex info
+Same as the external @command{info} command, but uses Emacs's internal
+Info reader.
+
+@item jobs
+@cmindex jobs
+List subprocesses of the Emacs process, if any, using the function
+@code{list-processes}.
+
+@item kill
+@cmindex kill
+Kill processes. Takes a PID or a process object and an optional
+signal specifier.
+
+@item listify
+@cmindex listify
+Eshell version of @code{list}. Allows you to create a list using Eshell
+syntax, rather than Elisp syntax. For example, @samp{listify foo bar}
+and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}.
+
+@item locate
+@cmindex locate
+Alias to Emacs's @code{locate} function, which simply runs the external
+@command{locate} command and parses the results. @xref{Dired and `find', , , elisp}.
+
+@item make
+@cmindex make
+Run @command{make} through @code{compile}. @xref{Running Compilations under Emacs, , , elisp}.
+
+@item occur
+@cmindex occur
+Alias to Emacs's @code{occur}. @xref{Other Search-and-Loop Commands, , , elisp}.
+
+@item printnl
+@cmindex printnl
+Print the arguments separated by newlines.
+
@item cd
-@findex cd
+@cmindex cd
This command changes the current working directory. Usually, it is
-invoked as @samp{cd foo} where @file{foo} is the new working
-directory. But @code{cd} knows about a few special arguments:
+invoked as @samp{cd foo} where @file{foo} is the new working directory.
+But @command{cd} knows about a few special arguments:
When it receives no argument at all, it changes to the home directory.
The command @samp{cd =} shows the directory stack. Each line is
numbered.
-With @samp{cd =foo}, Eshell searches the directory stack for a
-directory matching the regular expression @samp{foo} and changes to
-that directory.
+With @samp{cd =foo}, Eshell searches the directory stack for a directory
+matching the regular expression @samp{foo} and changes to that
+directory.
With @samp{cd -42}, you can access the directory stack by number.
-@item history
-@findex history
+@item su
+@cmindex su
+@itemx sudo
+@cmindex sudo
+Uses TRAMP's @command{su} or @command{sudo} method to run a command via
+@command{su} or @command{sudo}.
+
+@end table
+
+@section Built-in variables
+Eshell knows a few built-in variables:
+
+@table @code
+
+@item $+
+@vindex $+
+This variable always contains the current working directory.
+
+@item $-
+@vindex $-
+This variable always contains the previous working directory (the
+current working directory from before the last @code{cd} command).
+
+@item $_
+@vindex $_
+It refers to the last argument of the last command.
+
+@item $$
+@vindex $$
+This is the result of the last command. In case of an external
+command, it is @code{t} or @code{nil}.
+
+@item $?
+@vindex $?
+This variable contains the exit code of the last command (0 or 1 for
+Lisp functions, based on successful completion).
+
+@end table
+
+@node Variables
+@section Variables
+Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it
+does not have its own scope, and simply stores variables the same you
+would in an Elisp program. Eshell provides a command version of
+@code{setq} for convenience.
+
+@node Aliases
+@section Aliases
+
+Aliases are commands that expand to a longer input line. For example,
+@command{ll} is a common alias for @code{ls -l}, and would be defined
+with the command invocation @samp{alias ll ls -l}; with this defined,
+running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}.
+Aliases defined (or deleted) by the @command{alias} command are
+automatically written to the file named by @var{eshell-aliases-file},
+which you can also edit directly (although you will have to manually
+reload it).
+
+@node History
+@section History
+@cmindex history
The @samp{history} command shows all commands kept in the history ring
as numbered list. If the history ring contains
@code{eshell-history-size} commands, those numbers change after every
argument of the last command beginning with @code{foo} is accessible
by @code{!foo:n}.
-@item su
-@findex su
-@itemx sudo
-@findex sudo
-@code{su} and @code{sudo} work as expected: they apply the following
-commands (@code{su}), or the command being an argument (@code{sudo})
-under the permissions of somebody else.
-
-This does not work only on
-the local host, but even on a remote one, when
-@code{default-directory} is a remote file name. The necessary
-proxy configuration of Tramp is performed
-@ifinfo
-automatically, @ref{Multi-hops, , , tramp}.
-@end ifinfo
-@ifnotinfo
-automatically.
-@end ifnotinfo
-Example:
+The history ring is loaded from a file at the start of every session,
+and written back to the file at the end of every session. The file path
+is specified in @var{eshell-history-file-name}. Unlike other shells,
+such as Bash, Eshell can not be configured to keep a history ring of a
+different size than that of the history file.
+
+Since the default buffer navigation and searching key-bindings are
+still present in the Eshell buffer, the commands for history
+navigation and searching are bound to different keys:
+
+@table @kbd
+@item M-r
+@itemx M-s
+History I-search.
+
+@item M-p
+@itemx M-n
+Previous and next history line. If there is anything on the input
+line when you run these commands, they will instead jump to the
+precious or next line that begins with that string.
+@end table
+
+@node Completion
+@section Completion
+Eshell uses the pcomplete package for programmable completion, similar
+to that of other command shells. Argument completion differs depending
+on the preceding command: for example, possible completions for
+@command{rmdir} are only directories, while @command{rm} completions can
+be directories @emph{and} files. Eshell provides predefined completions
+for the built-in functions and some common external commands, and you
+can define your own for any command.
+
+Eshell completion also works for lisp forms and glob patterns. If the
+point is on a lisp form, then @key{TAB} will behave similarly to completion
+in @code{elisp-mode} and @code{lisp-interaction-mode}. For glob
+patterns, If there are few enough possible completions of the patterns,
+they will be cycled when @key{TAB} is pressed, otherwise it will be removed
+from the input line and the possible completions will be listed.
+
+If you want to see the entire list of possible completions when it's
+below the cycling threshold, press @kbd{M-?}.
+
+@subsection pcomplete
+Pcomplete, short for programmable completion, is the completion
+library originally written for Eshell, but usable for command
+completion@footnote{Command completion as opposed to code completion,
+which is a beyond the scope of pcomplete.} in other modes.
+
+Completions are defined as functions (with @code{defun}) named
+@code{pcomplete/COMMAND}, where @code{COMMAND} is the name of the
+command for which this function provides completions; you can also name
+the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions
+for a specific major mode.
+
+@node for loop
+@section @code{for} loop
+Because Eshell commands can not (easily) be combined with lisp forms,
+Eshell provides a command-oriented @command{for}-loop for convenience.
+The syntax is as follows:
@example
-~ $ cd /ssh:otherhost:/etc
-/ssh:user@@otherhost:/etc $ sudo find-file shadow
+@code{for VAR in TOKENS @{ command invocation(s) @}}
@end example
-@end table
-
+where @samp{TOKENS} is a space-separated sequence of values of
+@var{VAR} for each iteration. This can even be the output of a
+command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}.
-@node Arguments
-@chapter Arguments
+@node Scripts
+@section Scripts
+@cmindex source
+@fnindex eshell-source-file
+You can run Eshell scripts much like scripts for other shells; the main
+difference is that since Eshell is not a system command, you have to run
+it from within Emacs. An Eshell script is simply a file containing a
+sequence of commands, as with almost any other shell script. Scripts
+are invoked from Eshell with @command{source}, or from anywhere in Emacs
+with @code{eshell-source-file}.
+
+@cmindex .
+If you wish to load a script into your @emph{current} environment,
+rather than in a subshell, use the @code{.} command.
+
+@node Expansion
+@chapter Expansion
+Expansion in a command shell is somewhat like macro expansion in macro
+parsers (such as @command{cpp} and @command{m4}), but in a command
+shell, they are less often used for constants, and usually for using
+variables and string manipulation.@footnote{Eshell has no
+string-manipulation expansions because the Elisp library already
+provides many functions for this.} For example, @code{$var} on a line
+expands to the value of the variable @code{var} when the line is
+executed. Expansions are usually passed as arguments, but may also be
+used as commands.@footnote{e.g. Entering just @samp{$var} at the prompt
+is equivalent to entering the value of @code{var} at the prompt.}
@menu
-* The Parser::
-* Variables::
-* Substitution::
+* Dollars Expansion::
* Globbing::
-* Predicates::
@end menu
-@node The Parser
-@section The Parser
+@node Dollars Expansion
+@section Dollars Expansion
+Eshell has different @code{$} expansion syntax from other shells. There
+are some similarities, but don't let these lull you into a false sense
+of familiarity.
-@node Variables
-@section Variables
+@table @code
-@node Substitution
-@section Substitution
+@item $var
+Expands to the value bound to @code{var}. This is the main way to use
+variables in command invocations.
-@node Globbing
-@section Globbing
+@item $#var
+Expands to the length of the value bound to @code{var}. Raises an error
+if the value is not a sequence (@pxref{Sequences Arrays and Vectors, Sequences, , elisp}).
-@node Predicates
-@section Predicates
+@item $(lisp)
+Expands to the result of evaluating the S-expression @code{(lisp)}. On
+its own, this is identical to just @code{(lisp)}, but with the @code{$},
+it can be used in a string, such as @samp{/some/path/$(lisp).txt}.
+@item $@{command@}
+Returns the output of @command{command}, which can be any valid Eshell
+command invocation, and may even contain expansions.
-@node Input/Output
-@chapter Input/Output
+@item $var[i]
+Expands to the @code{i}th element of the value bound to @code{var}. If
+the value is a string, it will be split at whitespace to make it a list.
+Again, raises an error if the value is not a sequence.
+
+@item $var[: i]
+As above, but now splitting occurs at the colon character.
-@node Process control
-@chapter Process control
+@item $var[: i j]
+As above, but instead of returning just a string, it now returns a list
+of two strings. If the result is being interpolated into a larger
+string, this list will be flattened into one big string, with each
+element separated by a space.
+@item $var["\\\\" i]
+Separate on backslash characters. Actually, the first argument -- if it
+doesn't have the form of a number, or a plain variable name -- can be
+any regular expression. So to split on numbers, use @samp{$var["[0-9]+" 10 20]}.
+
+@item $var[hello]
+Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
+an alist (@pxref{Association List Type, Association Lists, , elisp}).
+
+@item $#var[hello]
+Returns the length of the cdr of the element of @code{var} who car is equal
+to @code{"hello"}.
+
+@end table
+
+@node Globbing
+@section Globbing
+Eshell's globbing syntax is very similar to that of Zsh. Users coming
+from Bash can still use Bash-style globbing, as there are no
+incompatibilities. Most globbing is pattern-based expansion, but there
+is also predicate-based expansion. See @ref{Filename Generation, , , zsh}
+for full syntax. To customize the syntax and behaviour of globbing in
+Eshell see the Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
+groups ``eshell-glob'' and ``eshell-pred''.
+
+@node Input/Output
+@chapter Input/Output
+Since Eshell does not communicate with a terminal like most command
+shells, IO is a little different. If you try to run programs from
+within Eshell that are not line-oriented, such as programs that use
+ncurses, you will just get garbage output, since the Eshell buffer is
+not a terminal emulator. Eshell solves this problem by running
+specified commands in Emacs's terminal emulator; to let Eshell know
+which commands need to be run in a terminal, add them to the list
+@var{eshell-visual-commands}.
+
+Redirection is mostly the same in Eshell as it is in other command
+shells. The output redirection operators @code{>} and @code{>>} as well
+as pipes are supported, but there is not yet any support for input
+redirection. Output can also be redirected to Elisp functions, using
+virtual devices.
+
+@var{eshell-virtual-targets} is a list of mappings of virtual device
+names to functions. Eshell comes with two virtual devices:
+@file{/dev/kill}, which sends the text to the kill ring, and
+@file{/dev/clip}, which sends text to the clipboard.
+
+You can, of course, define your own virtual targets. They are defined
+by adding a list of the form @code{("/dev/name" function mode)} to
+@var{eshell-virtual-targets}. The first element is the device name;
+@code{function} may be either a lambda or a function name. If
+@code{mode} is nil, then the function is the output function; if it is
+non-nil, then the function is passed the redirection mode as a
+symbol--@code{overwrite}, @code{append}, or @code{insert}--and the
+function is expected to return the output function.
+
+The output function is called once on each line of output until
+@code{nil} is passed, indicating end of output.
@node Extension modules
@chapter Extension modules
+Eshell provides a facility for defining extension modules so that they
+can be disabled and enabled without having to unload and reload them,
+and to provide a common parent Customize group for the
+modules.@footnote{ERC provides a similar module facility.} An Eshell
+module is defined the same as any other library but one requirement: the
+module must define a Customize@footnote{@xref{Customization Settings, Customize, , elisp}.}
+group using @code{eshell-defgroup} (in place of @code{defgroup}) with
+@code{eshell-module} as the parent group.@footnote{If the module has
+no user-customizable options, then there is no need to define it as an
+Eshell module.} You also need to load the following as shown:
+
+@example
+(eval-when-compile
+ (require 'cl)
+ (require 'esh-mode)
+ (require 'eshell))
+
+(require 'esh-util)
+@end example
@menu
* Writing a module::
* Key rebinding::
* Smart scrolling::
* Terminal emulation::
-* Built-in UNIX commands::
@end menu
@node Writing a module
@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 email to the author
@cindex FAQ
@cindex problems, list of common
+@cindex known bugs
+@cindex bugs, known
If you find a bug or misfeature, don't hesitate to let me know! Send
email to @email{johnw@@gnu.org}. Feature requests should also be sent
extensions to this package, I would like to hear from you. I hope you
find this package useful!
-@menu
-* Known problems::
-@end menu
-
-@node Known problems
-@section Known problems
-@cindex known bugs
-@cindex bugs, known
-
-Below is complete list of known problems with Eshell version 2.4.2,
+Below is a complete list of known problems with Eshell version 2.4.2,
which is the version included with Emacs 22.
@table @asis
@item Differentiate between aliases and functions
-Allow for a bash-compatible syntax, such as:
+Allow for a Bash-compatible syntax, such as:
@example
alias arg=blah
It would provide syntax, abbrev, highlighting and indenting support like
@code{emacs-lisp-mode} and @code{shell-mode}.
-@item In the history mechanism, finish the @command{bash}-style support
+@item In the history mechanism, finish the Bash-style support
This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
from @samp{!:1*}.
@printindex fn
+@node Command Index
+@unnumbered Command Index
+
+@printindex cm
+
@node Key Index
@unnumbered Key Index