diff options
| -rw-r--r-- | doc/misc/ChangeLog | 170 | ||||
| -rw-r--r-- | doc/misc/eshell.texi | 535 |
2 files changed, 474 insertions, 231 deletions
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 1b454741fc0..db3bd460055 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -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. diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index af457d7a9af..8d398900238 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -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,83 +278,56 @@ 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"}} - -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 @@ -368,7 +341,7 @@ eshell/ls is a compiled Lisp function in `em-ls.el' @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 @@ eshell/sudo is a compiled Lisp function in `em-unix.el' 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. @@ -396,14 +450,73 @@ 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 =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 @@ -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. - -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:: @@ -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 |