[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111233: * doc/misc/eshell.texi: F
|
From: |
Stefan Monnier |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111233: * doc/misc/eshell.texi: Fill most of the missing sections. |
|
Date: |
Fri, 08 Feb 2013 09:59:24 -0500 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 111233 [merge]
author: Aidan Gauland <address@hidden>
committer: Stefan Monnier <address@hidden>
branch nick: emacs-24
timestamp: Fri 2013-02-08 09:59:24 -0500
message:
* doc/misc/eshell.texi: Fill most of the missing sections.
modified:
doc/misc/ChangeLog
doc/misc/eshell.texi
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2013-02-07 07:11:59 +0000
+++ b/doc/misc/ChangeLog 2013-02-08 14:59:24 +0000
@@ -1,3 +1,7 @@
+2013-02-08 Aidan Gauland <address@hidden>
+
+ * eshell.texi: Fill most of the missing sections.
+
2013-02-07 Bastien Guerry <address@hidden>
* 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 <address@hidden>
@@ -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 <address@hidden>
@@ -271,8 +273,8 @@
2012-11-08 Chong Yidong <address@hidden>
- * 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 <address@hidden>
@@ -372,14 +374,14 @@
2012-10-26 Bastien Guerry <address@hidden>
- * 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 <address@hidden>
- * 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 <address@hidden>
@@ -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 <address@hidden>
@@ -535,8 +536,8 @@
2012-09-30 Bastien Guerry <address@hidden>
- * 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 <address@hidden>
@@ -772,8 +770,8 @@
2012-07-06 Michael Albinus <address@hidden>
- * 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 <address@hidden>
@@ -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 <address@hidden>
- * 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 <address@hidden>
@@ -1098,12 +1096,11 @@
2012-04-01 Carsten Dominik <address@hidden>
* 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 <address@hidden>
- * 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 <address@hidden>
@@ -1204,8 +1201,8 @@
2012-02-13 Lars Ingebrigtsen <address@hidden>
- * 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 <address@hidden>
@@ -1253,8 +1250,7 @@
2012-01-03 Eric Schulte <address@hidden>
* 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 <address@hidden>
@@ -1276,8 +1272,8 @@
2012-01-03 Bernt Hansen <address@hidden>
- * 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 <address@hidden>
@@ -1327,8 +1323,7 @@
2012-01-03 Thomas Dye <address@hidden>
- * 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 <address@hidden>
@@ -1362,8 +1357,8 @@
2012-01-03 Eric Schulte <address@hidden>
- * 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 <address@hidden>
@@ -1382,8 +1377,7 @@
2012-01-03 Tom Dye <address@hidden>
- * 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 <address@hidden>
@@ -1396,9 +1390,8 @@
2012-01-03 David Maus <address@hidden>
- * 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 <address@hidden>
@@ -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 <address@hidden>
- * 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 <address@hidden>
@@ -1583,8 +1575,7 @@
2011-08-15 Eric Schulte <address@hidden>
* 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 <address@hidden>
@@ -1663,13 +1654,11 @@
2011-08-15 Puneeth Chaganti <address@hidden>
- * 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 <address@hidden>
- * org.texi (Template expansion): Document new %<...> template
- escape.
+ * org.texi (Template expansion): Document new %<...> template escape.
2011-08-15 Carsten Dominik <address@hidden>
@@ -1689,8 +1678,7 @@
2011-08-15 Eric Schulte <address@hidden>
- * 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 <address@hidden>
@@ -1711,8 +1699,7 @@
2011-08-15 Eric Schulte <address@hidden>
- * org.texi (var): Clarification of indexing into tabular
- variables.
+ * org.texi (var): Clarification of indexing into tabular variables.
2011-08-15 Eric Schulte <address@hidden>
@@ -1726,8 +1713,8 @@
2011-08-15 Bastien Guerry <address@hidden>
- * 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 <address@hidden>
@@ -1754,15 +1741,15 @@
2011-08-15 Eric Schulte <address@hidden>
- * 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 <address@hidden>
- * 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 <address@hidden>
@@ -1792,17 +1779,16 @@
2011-08-15 Tom Dye <address@hidden>
- * org.texi (cache): Improved documentation of code block caches.
+ * org.texi (cache): Improve documentation of code block caches.
2011-08-15 Tom Dye <address@hidden>
- * 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 <address@hidden>
- * 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 <address@hidden>
@@ -1827,8 +1813,7 @@
2011-07-14 Lars Magne Ingebrigtsen <address@hidden>
* 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 <address@hidden>
@@ -1853,15 +1838,15 @@
2011-07-04 Michael Albinus <address@hidden>
- * 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 <address@hidden>
* 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 <address@hidden> (tiny change)
@@ -1888,8 +1873,8 @@
2011-06-26 Lars Magne Ingebrigtsen <address@hidden>
- * 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 <address@hidden>
@@ -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 <address@hidden>
@@ -2024,9 +2009,8 @@
2011-03-06 Jay Belanger <address@hidden>
- * 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 <address@hidden>
* 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 <address@hidden>
@@ -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.
=== modified file 'doc/misc/eshell.texi'
--- a/doc/misc/eshell.texi 2013-01-05 16:19:53 +0000
+++ b/doc/misc/eshell.texi 2013-02-08 14:59:24 +0000
@@ -2,6 +2,7 @@
@c %**start of header
@setfilename ../../info/eshell
@settitle Eshell: The Emacs Shell
address@hidden cm
@synindex vr fn
@c %**end of header
@@ -42,7 +43,7 @@
@c -release-
@end ignore
@sp 3
address@hidden John Wiegley
address@hidden John Wiegley & Aidan Gauland
@c -date-
@page
@@ -75,16 +76,15 @@
* 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,83 +278,56 @@
@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 address@hidden 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:
-
address@hidden
address@hidden Parse the command string into separate arguments.
address@hidden
address@hidden enumerate
-
address@hidden Completion
address@hidden Completion
-
address@hidden Aliases
address@hidden Aliases
-
address@hidden History
address@hidden History
-
-Eshell knows a few built-in variables:
-
address@hidden @code
-
address@hidden $+
address@hidden $+
-This variable always contains the current working directory.
-
address@hidden $-
address@hidden $-
-This variable always contains the previous working directory (the
-current working directory from before the last @code{cd} command).
-
address@hidden $_
address@hidden $_
-It refers to the last argument of the last command.
-
address@hidden $$
address@hidden $$
-This is the result of the last command. In case of an external
-command, it is @code{t} or @code{nil}.
-
address@hidden $?
address@hidden $?
-This variable contains the exit code of the last command (0 or 1 for
-Lisp functions, based on successful completion).
-
address@hidden table
-
address@hidden Scripts
address@hidden Scripts
-
+input line into a callable Lisp address@hidden 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.
+
address@hidden Arguments
address@hidden 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
address@hidden, 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
-
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
@@ -368,7 +341,7 @@
@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
@@ -378,15 +351,96 @@
sudo is an alias, defined as "*sudo $*"
@end example
-Some of the built-in commands have a special behavior in Eshell:
address@hidden 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
address@hidden addpath
address@hidden 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.
+
address@hidden alias
address@hidden alias
+Define an alias (@pxref{Aliases}). This does not add it to the aliases
+file.
+
address@hidden date
address@hidden date
+Similar to, but slightly different from, the GNU Coreutils
address@hidden command.
+
address@hidden define
address@hidden define
+Define a varalias. @xref{Variable Aliases, , , elisp}.
+
address@hidden diff
address@hidden diff
+Use Emacs's internal @code{diff} (not to be confused with
address@hidden). @xref{Comparing Files, , , elisp}.
+
address@hidden grep
address@hidden grep
address@hidden agrep
address@hidden agrep
address@hidden egrep
address@hidden egrep
address@hidden fgrep
address@hidden fgrep
address@hidden glimpse
address@hidden glimpse
+The @command{grep} commands are compatible with GNU @command{grep}, but
+use Emacs's internal @code{grep} instead.
+
address@hidden info
address@hidden info
+Same as the external @command{info} command, but uses Emacs's internal
+Info reader.
+
address@hidden jobs
address@hidden jobs
+List subprocesses of the Emacs process, if any, using the function
address@hidden
+
address@hidden kill
address@hidden kill
+Kill processes. Takes a PID or a process object and an optional
+signal specifier.
+
address@hidden listify
address@hidden 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")}.
+
address@hidden locate
address@hidden locate
+Alias to Emacs's @code{locate} function, which simply runs the external
address@hidden command and parses the results. @xref{Dired and `find', , ,
elisp}.
+
address@hidden make
address@hidden make
+Run @command{make} through @code{compile}. @xref{Running Compilations under
Emacs, , , elisp}.
+
address@hidden occur
address@hidden occur
+Alias to Emacs's @code{occur}. @xref{Other Search-and-Loop Commands, , ,
elisp}.
+
address@hidden printnl
address@hidden printnl
+Print the arguments separated by newlines.
+
@item cd
address@hidden cd
address@hidden 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.
@@ -396,14 +450,73 @@
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.
address@hidden history
address@hidden history
address@hidden su
address@hidden su
address@hidden sudo
address@hidden sudo
+Uses TRAMP's @command{su} or @command{sudo} method to run a command via
address@hidden or @command{sudo}.
+
address@hidden table
+
address@hidden Built-in variables
+Eshell knows a few built-in variables:
+
address@hidden @code
+
address@hidden $+
address@hidden $+
+This variable always contains the current working directory.
+
address@hidden $-
address@hidden $-
+This variable always contains the previous working directory (the
+current working directory from before the last @code{cd} command).
+
address@hidden $_
address@hidden $_
+It refers to the last argument of the last command.
+
address@hidden $$
address@hidden $$
+This is the result of the last command. In case of an external
+command, it is @code{t} or @code{nil}.
+
address@hidden $?
address@hidden $?
+This variable contains the exit code of the last command (0 or 1 for
+Lisp functions, based on successful completion).
+
address@hidden table
+
address@hidden Variables
address@hidden Variables
+Since Eshell is just an Emacs address@hidden 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
address@hidden for convenience.
+
address@hidden Aliases
address@hidden Aliases
+
+Aliases are commands that expand to a longer input line. For example,
address@hidden 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).
+
address@hidden History
address@hidden History
address@hidden 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 @@
argument of the last command beginning with @code{foo} is accessible
by @code{!foo:n}.
address@hidden su
address@hidden su
address@hidden sudo
address@hidden sudo
address@hidden 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
address@hidden is a remote file name. The necessary
-proxy configuration of Tramp is performed
address@hidden
-automatically, @ref{Multi-hops, , , tramp}.
address@hidden ifinfo
address@hidden
-automatically.
address@hidden 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:
+
address@hidden @kbd
address@hidden M-r
address@hidden M-s
+History I-search.
+
address@hidden M-p
address@hidden 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.
address@hidden table
+
address@hidden Completion
address@hidden 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
address@hidden 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-?}.
+
address@hidden pcomplete
+Pcomplete, short for programmable completion, is the completion
+library originally written for Eshell, but usable for command
address@hidden 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
address@hidden/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.
+
address@hidden for loop
address@hidden @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
address@hidden VAR in TOKENS @{ command invocation(s) @}}
@end example
address@hidden table
-
-
address@hidden Arguments
address@hidden Arguments
+where @samp{TOKENS} is a space-separated sequence of values of
address@hidden for each iteration. This can even be the output of a
+command if @samp{TOKENS} is replaced with @address@hidden command invocation
@}}.
+
address@hidden Scripts
address@hidden Scripts
address@hidden source
address@hidden 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}.
+
address@hidden .
+If you wish to load a script into your @emph{current} environment,
+rather than in a subshell, use the @code{.} command.
+
address@hidden Expansion
address@hidden 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 address@hidden 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 address@hidden 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
address@hidden The Parser
address@hidden The Parser
-
address@hidden Variables
address@hidden Variables
-
address@hidden Substitution
address@hidden Substitution
address@hidden Dollars Expansion
address@hidden 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.
+
address@hidden @code
+
address@hidden $var
+Expands to the value bound to @code{var}. This is the main way to use
+variables in command invocations.
+
address@hidden $#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}).
+
address@hidden $(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}.
+
address@hidden address@hidden@}
+Returns the output of @command{command}, which can be any valid Eshell
+command invocation, and may even contain expansions.
+
address@hidden $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.
+
address@hidden $var[: i]
+As above, but now splitting occurs at the colon character.
+
address@hidden $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.
+
address@hidden $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]}.
+
address@hidden $var[hello]
+Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
+an alist (@pxref{Association List Type, Association Lists, , elisp}).
+
address@hidden $#var[hello]
+Returns the length of the cdr of the element of @code{var} who car is equal
+to @code{"hello"}.
+
address@hidden table
@node Globbing
@section Globbing
-
address@hidden Predicates
address@hidden 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 address@hidden@xref{Customization Settings, Customize, ,
elisp}.}
+groups ``eshell-glob'' and ``eshell-pred''.
@node Input/Output
@chapter Input/Output
-
address@hidden Process control
address@hidden Process control
-
+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
address@hidden
+
+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.
+
address@hidden is a list of mappings of virtual device
+names to functions. Eshell comes with two virtual devices:
address@hidden/dev/kill}, which sends the text to the kill ring, and
address@hidden/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
address@hidden The first element is the device name;
address@hidden may be either a lambda or a function name. If
address@hidden is nil, then the function is the output function; if it is
+non-nil, then the function is passed the redirection mode as a
address@hidden, @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
address@hidden 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
address@hidden provides a similar module facility.} An Eshell
+module is defined the same as any other library but one requirement: the
+module must define a address@hidden@xref{Customization Settings, Customize, ,
elisp}.}
+group using @code{eshell-defgroup} (in place of @code{defgroup}) with
address@hidden as the parent address@hidden 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:
+
address@hidden
+(eval-when-compile
+ (require 'cl)
+ (require 'esh-mode)
+ (require 'eshell))
+
+(require 'esh-util)
address@hidden example
@menu
* Writing a module::
@@ -491,7 +760,6 @@
* Key rebinding::
* Smart scrolling::
* Terminal emulation::
-* Built-in UNIX commands::
@end menu
@node Writing a module
@@ -512,13 +780,6 @@
@node Terminal emulation
@section Terminal emulation
address@hidden Built-in UNIX commands
address@hidden Built-in UNIX commands
-
-
address@hidden Extras and Goodies
address@hidden Extras and Goodies
-
@node Bugs and ideas
@chapter Bugs and ideas
@cindex reporting bugs and ideas
@@ -527,6 +788,8 @@
@cindex email to the author
@cindex FAQ
@cindex problems, list of common
address@hidden known bugs
address@hidden 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 @@
extensions to this package, I would like to hear from you. I hope you
find this package useful!
address@hidden
-* Known problems::
address@hidden menu
-
address@hidden Known problems
address@hidden Known problems
address@hidden known bugs
address@hidden 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 @@
@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 @@
It would provide syntax, abbrev, highlighting and indenting support like
@code{emacs-lisp-mode} and @code{shell-mode}.
address@hidden In the history mechanism, finish the @command{bash}-style support
address@hidden 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 @@
@printindex fn
address@hidden Command Index
address@hidden Command Index
+
address@hidden cm
+
@node Key Index
@unnumbered Key Index
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-24 r111233: * doc/misc/eshell.texi: Fill most of the missing sections.,
Stefan Monnier <=