mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-04 11:00:45 -08:00
Code Issues Projects Releases Wiki Activity

* doc/misc/eshell.texi: Fill most of the missing sections.

Browse source
This commit is contained in:
Aidan Gauland 2013-02-08 09:59:24 -05:00 • committed by Stefan Monnier
commit dacbc44ca3
2 changed files with 483 additions and 240 deletions
Download patch file Download diff file Expand all files Collapse all files

170
doc/misc/ChangeLog
View file

@ -1,3 +1,7 @@
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.
@ -17,8 +21,8 @@
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>
@ -72,8 +76,7 @@
* 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.
@ -212,8 +215,8 @@
* 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)
@ -222,8 +225,7 @@
* 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>
@ -271,8 +273,8 @@
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>
@ -372,14 +374,14 @@
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>
@ -483,8 +485,7 @@
(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
@ -502,8 +503,8 @@
(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>
@ -535,8 +536,8 @@
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".
@ -553,18 +554,16 @@
* 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
@ -582,8 +581,7 @@
* 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.
@ -739,8 +737,8 @@
(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>
@ -772,8 +770,8 @@
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>
@ -965,8 +963,8 @@
(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.
@ -999,8 +997,8 @@
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>
@ -1098,12 +1096,11 @@
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>
@ -1204,8 +1201,8 @@
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>
@ -1253,8 +1250,7 @@
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>
@ -1276,8 +1272,8 @@
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>
@ -1327,8 +1323,7 @@
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>
@ -1362,8 +1357,8 @@
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>
@ -1382,8 +1377,7 @@
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>
@ -1396,9 +1390,8 @@
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>
@ -1524,7 +1517,7 @@
* 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.
@ -1564,8 +1557,7 @@
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>
@ -1583,8 +1575,7 @@
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>
@ -1663,13 +1654,11 @@
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>
@ -1689,8 +1678,7 @@
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>
@ -1711,8 +1699,7 @@
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>
@ -1726,8 +1713,8 @@
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>
@ -1754,15 +1741,15 @@
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>
@ -1792,17 +1779,16 @@
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>
@ -1827,8 +1813,7 @@
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>
@ -1853,15 +1838,15 @@
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)
@ -1888,8 +1873,8 @@
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>
@ -1952,7 +1937,7 @@
* 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>
@ -2024,9 +2009,8 @@
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.
@ -3069,8 +3053,8 @@
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.
@ -5724,7 +5708,7 @@
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
@ -6528,7 +6512,7 @@
(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>
@ -6760,7 +6744,7 @@
(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.

553
doc/misc/eshell.texi
View file

@ -2,6 +2,7 @@
@c %**start of header
@setfilename ../../info/eshell
@settitle Eshell: The Emacs Shell
@defindex cm
@synindex vr fn
@c %**end of header
@ -42,7 +43,7 @@ modify this GNU manual.''
@c -release-
@end ignore
@sp 3
@center John Wiegley
@center John Wiegley & Aidan Gauland
@c -date-
@page
@ -75,16 +76,15 @@ handling the sort of tasks accomplished by those tools.
* 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?
@ -278,47 +278,194 @@ on your mind. Have fun!
@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"}}
input line 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:
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.
@enumerate
@item Parse the command string into separate arguments.
@item
@end enumerate
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 Completion
@section Completion
@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 Aliases
@section Aliases
@node Built-ins
@node History
@section History
@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
what will be applied by the @code{which} command:
@example
~ $ which ls
eshell/ls is a compiled Lisp function in `em-ls.el'
~ $ which *ls
/bin/ls
@end example
If you want to discard a given built-in command, you could declare an
alias, @ref{Aliases}. Example:
@example
~ $ which sudo
eshell/sudo is a compiled Lisp function in `em-unix.el'
~ $ alias sudo '*sudo $*'
~ $ which sudo
sudo is an alias, defined as "*sudo $*"
@end example
@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
@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 @command{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.
@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
@ -348,62 +495,28 @@ Lisp functions, based on successful completion).
@end table
@node Scripts
@section Scripts
@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
@node Built-ins
@section Built-in commands
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).
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
what will be applied by the @code{which} command:
@example
~ $ which ls
eshell/ls is a compiled Lisp function in `em-ls.el'
~ $ which *ls
/bin/ls
@end example
If you want to discard a given built-in command, you could declare an
alias, @ref{Aliases}. Eample:
@example
~ $ which sudo
eshell/sudo is a compiled Lisp function in `em-unix.el'
~ $ alias sudo '*sudo $*'
~ $ which sudo
sudo is an alias, defined as "*sudo $*"
@end example
Some of the built-in commands have a special behavior in Eshell:
@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.
@item history
@findex history
@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
@ -419,70 +532,226 @@ of the history ring.
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.
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.
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:
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
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 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
* Dollars Expansion::
* Globbing::
@end menu
@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.
@table @code
@item $var
Expands to the value bound to @code{var}. This is the main way to use
variables in command invocations.
@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}).
@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.
@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.
@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 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
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}.
@node Process control
@chapter Process control
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::
@ -491,7 +760,6 @@ Example:
* Key rebinding::
* Smart scrolling::
* Terminal emulation::
* Built-in UNIX commands::
@end menu
@node Writing a module
@ -512,13 +780,6 @@ Example:
@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
@ -527,6 +788,8 @@ Example:
@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
@ -537,16 +800,7 @@ 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
@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
@ -554,7 +808,7 @@ which is the version included with Emacs 22.
@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
@ -838,7 +1092,7 @@ them; @code{min} would display the smallest figure, etc.
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*}.
@ -1008,6 +1262,11 @@ Since it keeps the cursor up where the command was invoked.
@printindex fn
@node Command Index
@unnumbered Command Index
@printindex cm
@node Key Index
@unnumbered Key Index