Add an "Interaction" chapter to the Eshell manual
* doc/misc/eshell.texi (Interaction): New chapter. (Completion, History): Move into "Interaction" and add key indexing. (Key rebinding): Add key indexing. (Command Index): Add this index.
This commit is contained in:
Jim Porter
parent
2a699edbe5
commit
991600a82c
1 changed files with 134 additions and 94 deletions
|
|
@ -79,15 +79,14 @@ similar to command shells such as @command{bash}, @command{zsh},
|
|||
* Commands::
|
||||
* Expansion::
|
||||
* Input/Output::
|
||||
* Interaction::
|
||||
* Extension modules::
|
||||
* Bugs and ideas:: Known problems, and future ideas.
|
||||
* GNU Free Documentation License:: The license for this documentation.
|
||||
* Concept Index::
|
||||
* Function and Variable Index::
|
||||
* Command Index::
|
||||
@ignore
|
||||
* Key Index::
|
||||
@end ignore
|
||||
@end menu
|
||||
|
||||
@node Introduction
|
||||
|
|
@ -208,8 +207,6 @@ that will be invoked, type this as the Eshell prompt:
|
|||
* Variables::
|
||||
* Aliases::
|
||||
* Remote Access::
|
||||
* History::
|
||||
* Completion::
|
||||
* Control Flow::
|
||||
* Scripts::
|
||||
@end menu
|
||||
|
|
@ -1556,92 +1553,6 @@ The GNU Emacs Manual}). To disable explicity-remote commands entirely,
|
|||
you can set the option @code{eshell-explicit-remote-commands} to
|
||||
@code{nil}.
|
||||
|
||||
@node History
|
||||
@section History
|
||||
@cmindex history
|
||||
@vindex eshell-history-size
|
||||
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
|
||||
command invocation, therefore the @samp{history} command shall be
|
||||
applied before using the expansion mechanism with history numbers.
|
||||
|
||||
The n-th entry of the history ring can be applied with the @samp{!n}
|
||||
command. If @code{n} is negative, the entry is counted from the end
|
||||
of the history ring.
|
||||
|
||||
@cindex event designators
|
||||
@findex eshell-expand-history-references
|
||||
When history event designators are enabled (by adding
|
||||
@code{eshell-expand-history-references} to
|
||||
@code{eshell-expand-input-functions}), @samp{!foo} expands to the last
|
||||
command beginning with @code{foo}, and @samp{!?foo} to the last
|
||||
command containing @code{foo}. The n-th argument of the last command
|
||||
beginning with @code{foo} is accessible by @code{!foo:n}.
|
||||
|
||||
@vindex eshell-history-file-name
|
||||
@vindex eshell-history-append
|
||||
The history is loaded to the history ring from the file
|
||||
@code{eshell-history-file-name} at the start of every session, and
|
||||
saved to that file at the end of every session. The default history
|
||||
saving behavior is to overwrite the history file with the whole
|
||||
history ring of the session. If @code{eshell-history-append} is
|
||||
non-@code{nil}, the history will instead be saved by appending new
|
||||
entries from the session to the history file, which could prevent
|
||||
potential history loss with multiple Eshell sessions. Unlike other
|
||||
shells, such as Bash, Eshell cannot currently be configured to control
|
||||
the size of the history file. In particular, when
|
||||
@code{eshell-history-append} is non-@code{nil}, the size of the file
|
||||
will keep increasing, and the recommended way to truncate the file is
|
||||
to run the @samp{history -w} command in an Eshell session.
|
||||
|
||||
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
|
||||
previous 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, the pattern will be removed from the input line, and
|
||||
replaced by the completion.
|
||||
|
||||
If you want to see the entire list of possible completions (e.g. when it's
|
||||
below the @code{completion-cycle-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 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 Control Flow
|
||||
@section Control Flow
|
||||
Because Eshell commands can not (easily) be combined with Lisp forms,
|
||||
|
|
@ -2486,6 +2397,135 @@ at the end of the command are excluded. This allows input like this:
|
|||
sh -c "foo | baz" >#<buffer quux>
|
||||
@end example
|
||||
|
||||
@node Interaction
|
||||
@chapter Interaction
|
||||
|
||||
As an interactive shell, Eshell contains many features for helping to
|
||||
interact with your command environment. In addition, since Eshell is a
|
||||
part of Emacs, all of the usual Emacs commands work within Eshell as
|
||||
well.
|
||||
|
||||
@menu
|
||||
* Navigation::
|
||||
* Completion::
|
||||
* History::
|
||||
@end menu
|
||||
|
||||
@node Navigation
|
||||
@section Navigation
|
||||
|
||||
@table @kbd
|
||||
|
||||
@kindex C-c C-n
|
||||
@kindex C-c C-p
|
||||
@item C-c C-n
|
||||
@itemx C-c C-p
|
||||
Move point to the beginning of the input for the next or previous
|
||||
prompt. With a prefix argument, move to the n-th next or previous
|
||||
prompt.
|
||||
|
||||
@kindex C-c C-r
|
||||
@kindex C-M-l
|
||||
@item C-c C-r
|
||||
@itemx C-M-l
|
||||
Move point to the start of the previous command's output and display it
|
||||
at the top of the window. With a prefix argument, this also narrows the
|
||||
region to the last command's output.
|
||||
|
||||
@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.
|
||||
|
||||
@kindex TAB
|
||||
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, the pattern will be removed from the input line, and
|
||||
replaced by the completion.
|
||||
|
||||
@kindex M-?
|
||||
If you want to see the entire list of possible completions (e.g. when it's
|
||||
below the @code{completion-cycle-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 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 History
|
||||
@section History
|
||||
@cmindex history
|
||||
@vindex eshell-history-size
|
||||
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
|
||||
command invocation, therefore the @samp{history} command shall be
|
||||
applied before using the expansion mechanism with history numbers.
|
||||
|
||||
The n-th entry of the history ring can be applied with the @samp{!n}
|
||||
command. If @code{n} is negative, the entry is counted from the end
|
||||
of the history ring.
|
||||
|
||||
@cindex event designators
|
||||
@findex eshell-expand-history-references
|
||||
When history event designators are enabled (by adding
|
||||
@code{eshell-expand-history-references} to
|
||||
@code{eshell-expand-input-functions}), @samp{!foo} expands to the last
|
||||
command beginning with @code{foo}, and @samp{!?foo} to the last
|
||||
command containing @code{foo}. The n-th argument of the last command
|
||||
beginning with @code{foo} is accessible by @code{!foo:n}.
|
||||
|
||||
@vindex eshell-history-file-name
|
||||
@vindex eshell-history-append
|
||||
The history is loaded to the history ring from the file
|
||||
@code{eshell-history-file-name} at the start of every session, and
|
||||
saved to that file at the end of every session. The default history
|
||||
saving behavior is to overwrite the history file with the whole
|
||||
history ring of the session. If @code{eshell-history-append} is
|
||||
non-@code{nil}, the history will instead be saved by appending new
|
||||
entries from the session to the history file, which could prevent
|
||||
potential history loss with multiple Eshell sessions. Unlike other
|
||||
shells, such as Bash, Eshell cannot currently be configured to control
|
||||
the size of the history file. In particular, when
|
||||
@code{eshell-history-append} is non-@code{nil}, the size of the file
|
||||
will keep increasing, and the recommended way to truncate the file is
|
||||
to run the @samp{history -w} command in an Eshell session.
|
||||
|
||||
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
|
||||
@kindex M-r
|
||||
@kindex M-s
|
||||
@item M-r
|
||||
@itemx M-s
|
||||
History I-search.
|
||||
|
||||
@kindex M-p
|
||||
@kindex M-n
|
||||
@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
|
||||
previous or next line that begins with that string.
|
||||
@end table
|
||||
|
||||
@node Extension modules
|
||||
@chapter Extension modules
|
||||
Eshell provides a facility for defining extension modules so that they
|
||||
|
|
@ -2524,6 +2564,10 @@ mimic the bindings used in other shells when the user is editing new
|
|||
input text. To enable this module, add @code{eshell-rebind} to
|
||||
@code{eshell-modules-list}.
|
||||
|
||||
@kindex C-u
|
||||
@kindex C-w
|
||||
@kindex C-p
|
||||
@kindex C-n
|
||||
For example, it binds @kbd{C-u} to kill the current input text and
|
||||
@kbd{C-w} to @code{backward-kill-word}. If the history module is
|
||||
enabled, it also binds @kbd{C-p} and @kbd{C-n} to move through the
|
||||
|
|
@ -3174,13 +3218,9 @@ Since it keeps the cursor up where the command was invoked.
|
|||
|
||||
@printindex cm
|
||||
|
||||
@c There are no @kindex entries in this manual; avoid generating an
|
||||
@c empty menu.
|
||||
@ignore
|
||||
@node Key Index
|
||||
@unnumbered Key Index
|
||||
|
||||
@printindex ky
|
||||
@end ignore
|
||||
|
||||
@bye
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue