From 275fec146ee94c5480a521050dede61d47a2a06e Mon Sep 17 00:00:00 2001 From: Jim Porter Date: Fri, 31 May 2024 09:36:03 -0700 Subject: [PATCH] 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. (cherry picked from commit 991600a82c7678fa15301e609f259cf3ec184089) --- doc/misc/eshell.texi | 228 +++++++++++++++++++++++++------------------ 1 file changed, 134 insertions(+), 94 deletions(-) diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 873d14aff32..c8a04bfa33f 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -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" ># @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 -- 2.39.2