From 94e7f1da87af6a6fa9f42ac484ea77ba242a68e1 Mon Sep 17 00:00:00 2001 From: Jim Porter Date: Fri, 12 May 2023 20:03:48 -0700 Subject: [PATCH 4/4] Document optional Eshell modules * lisp/eshell/em-rebind.el (eshell-rebind): Correct/reword docstring. * doc/misc/eshell.texi (Built-ins): Move disabled-by-default commands to... (Tramp extensions, Extra built-in commands): ...here (Optional modules, Key rebinding, Smart scrolling): Add documentation. (Bug and ideas): Documentation is no longer incomplete! --- doc/misc/eshell.texi | 211 ++++++++++++++++++++++++--------------- lisp/eshell/em-rebind.el | 19 ++-- 2 files changed, 139 insertions(+), 91 deletions(-) diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index bb1ee99ffc0..0e2f5e02973 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -586,14 +586,6 @@ Built-ins Set environment variables using input like Bash's @command{export}, as in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}. -@item expr -@cmindex expr -An implementation of @command{expr} using the Calc package. -@xref{Top,,, calc, The GNU Emacs Calculator}. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - @item grep @cmindex grep @itemx agrep @@ -628,15 +620,6 @@ Built-ins reader. @xref{Misc Help, , , emacs, The GNU Emacs Manual}. -@item intersection -@cmindex intersection -A wrapper around the function @code{cl-intersection} (@pxref{Lists as -Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command -can be used for comparing lists of strings. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - @item jobs @cmindex jobs List subprocesses of the Emacs process, if any, using the function @@ -706,15 +689,6 @@ Built-ins Display Man pages using the Emacs @code{man} command. @xref{Man Page, , , emacs, The GNU Emacs Manual}. -@item mismatch -@cmindex mismatch -A wrapper around the function @code{cl-mismatch} (@pxref{Searching -Sequences,,, cl, GNU Emacs Common Lisp Emulation}). This command can -be used for comparing lists of strings. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - @item mkdir @cmindex mkdir Make new directories. @@ -771,24 +745,6 @@ Built-ins @cmindex rmdir Removes directories if they are empty. -@item set-difference -@cmindex set-difference -A wrapper around the function @code{cl-set-difference} (@pxref{Lists as -Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command -can be used for comparing lists of strings. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - -@item set-exclusive-or -@cmindex set-exclusive-or -A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists -as Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command can be -used for comparing lists of strings. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - @item set @cmindex set Set variable values, using the function @code{set} like a command @@ -808,27 +764,6 @@ Built-ins confused with the command @command{.}, which sources a file in the current environment. -@item su -@cmindex su -@itemx sudo -@cmindex sudo -@itemx doas -@cmindex doas -Uses TRAMP's @command{su}, @command{sudo}, or @command{doas} method -@pxref{Inline methods, , , tramp} to run a command via @command{su}, -@command{sudo}, or @command{doas}. These commands are in the -eshell-tramp module, which is disabled by default. - - -@item substitute -@cmindex substitute -A wrapper around the function @code{cl-substitute} (@pxref{Sequence -Functions,,, cl, GNU Emacs Common Lisp Emulation}). This command can -be used for comparing lists of strings. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - @item time @cmindex time Show the time elapsed during a command's execution. @@ -838,15 +773,6 @@ Built-ins Set or view the default file permissions for newly created files and directories. -@item union -@cmindex union -A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,, -cl, GNU Emacs Common Lisp Emulation}). This command can be used for -comparing lists of strings. - -This command can be loaded as part of the eshell-xtra module, which is -disabled by default. - @item unset @cmindex unset Unset one or more variables. As with @command{set}, a variable name @@ -2029,7 +1955,10 @@ Extension modules @node Optional modules @section Optional modules -This section is not yet written. +In addition to the various modules enabled by default (documented +above), Eshell provides several other modules which are @emph{not} +enabled by default. If you want to enable these, you can add them to +@code{eshell-modules-list}. @menu * Key rebinding:: @@ -2042,12 +1971,66 @@ Optional modules @node Key rebinding @subsection Key rebinding -This section is not yet written. +This module allows for special keybindings that only take effect +while the point is in a region of input text. The default keybindings +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}. + +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 +input history. + +If @code{eshell-confine-point-to-input} is non-@code{nil}, this module +prevents certain commands from causing the point to leave the input +area, such as @code{backward-word}, @code{previous-line}, etc. @node Smart scrolling @subsection Smart scrolling -This section is not yet written. +This module combines the facility of normal, modern shells with some +of the edit/review concepts inherent in the design of Plan 9's 9term. +To enable it, add @code{eshell-smart} to @code{eshell-modules-list}. + +@itemize @bullet +@item +When you invoke a command, it is assumed that you want to read the +output of that command. + +@item +If the output is not what you wanted, it is assumed that you will want +to edit, and then resubmit a refined version of that command. + +@item +If the output is valid, pressing any self-inserting character key will +jump to end of the buffer and insert that character, in order to begin +entry of a new command. + +@item +If you show an intention to edit the previous command -- by moving +around within it -- then the next self-inserting characters will +insert *there*, instead of at the bottom of the buffer. + +@item +If you show an intention to review old commands, such as @kbd{M-p} or +@kbd{M-r}, point will jump to the bottom of the buffer before invoking +that command. + +@item +If none of the above has happened yet (i.e.@: your point is just +sitting on the previous command), you can use @kbd{SPC} and +@kbd{BACKSPACE} (or @kbd{Delete}) to page forward and backward +@emph{through the output of the last command only}. It will constrain +the movement of the point and window so that the maximum amount of +output is always displayed at all times. + +@item +While output is being generated from a command, the window will be +constantly reconfigured (until it would otherwise make no difference) +in order to always show you the most output from the command possible. +This happens if you change window sizes, scroll, etc. +@end itemize @node Electric forward slash @subsection Electric forward slash @@ -2107,12 +2090,76 @@ Electric forward slash @node Tramp extensions @subsection Tramp extensions -This section is not yet written. +This module adds built-in commands that use Tramp to handle running +other commands as different users, replacing the corresponding +external commands. To enable it, add @code{eshell-tramp} to +@code{eshell-modules-list}. -@node Extra built-in functions -@subsection Extra built-in functions +@table @code + +@item su +@cmindex su +@itemx sudo +@cmindex sudo +@itemx doas +@cmindex doas +Uses TRAMP's @command{su}, @command{sudo}, or @command{doas} method +(@pxref{Inline methods, , , tramp, The Tramp Manual}) to run a command +via @command{su}, @command{sudo}, or @command{doas}. -This section is not yet written. +@end table + +@node Extra built-in commands +@subsection Extra built-in commands + +This module provides several extra built-in commands documented below, +primarily for working with lists of strings in Eshell. To enable it, +add @code{eshell-xtra} to @code{eshell-modules-list}. + +@table @code + +@item expr +@cmindex expr +An implementation of @command{expr} using the Calc package. +@xref{Top,,, calc, The GNU Emacs Calculator}. + +@item intersection +@cmindex intersection +A wrapper around the function @code{cl-intersection} (@pxref{Lists as +Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command +can be used for comparing lists of strings. + +@item mismatch +@cmindex mismatch +A wrapper around the function @code{cl-mismatch} (@pxref{Searching +Sequences,,, cl, GNU Emacs Common Lisp Emulation}). This command can +be used for comparing lists of strings. + +@item set-difference +@cmindex set-difference +A wrapper around the function @code{cl-set-difference} (@pxref{Lists +as Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command can be +used for comparing lists of strings. + +@item set-exclusive-or +@cmindex set-exclusive-or +A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists +as Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command can be +used for comparing lists of strings. + +@item substitute +@cmindex substitute +A wrapper around the function @code{cl-substitute} (@pxref{Sequence +Functions,,, cl, GNU Emacs Common Lisp Emulation}). This command can +be used for comparing lists of strings. + +@item union +@cmindex union +A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,, +cl, GNU Emacs Common Lisp Emulation}). This command can be used for +comparing lists of strings. + +@end table @node Writing a module @section Writing a module @@ -2164,8 +2211,6 @@ Bugs and ideas which is the version included with Emacs 22. @table @asis -@item Documentation incomplete - @item Differentiate between aliases and functions Allow for a Bash-compatible syntax, such as: diff --git a/lisp/eshell/em-rebind.el b/lisp/eshell/em-rebind.el index 75a2848a9d5..e4579497edc 100644 --- a/lisp/eshell/em-rebind.el +++ b/lisp/eshell/em-rebind.el @@ -29,14 +29,17 @@ (progn (defgroup eshell-rebind nil "This module allows for special keybindings that only take effect -while the point is in a region of input text. By default, it binds -C-a to move to the beginning of the input text (rather than just the -beginning of the line), and C-p and C-n to move through the input -history, C-u kills the current input text, etc. It also, if -`eshell-confine-point-to-input' is non-nil, does not allow certain -commands to cause the point to leave the input area, such as -`backward-word', `previous-line', etc. This module intends to mimic -the behavior of normal shells while the user editing new input text." +while the point is in a region of input text. The default +keybindings mimic the bindings used in other shells when the user +is editing new input text. + +For example, it binds C-u to kill the current input text and C-w +to `backward-kill-word'. If the history module is enabled, it +also binds C-p and C-n to move through the input history, etc. + +If `eshell-confine-point-to-input' is non-nil, this module prevents +certain commands from causing the point to leave the input area, such +as `backward-word', `previous-line', etc." :tag "Rebind keys at input" :group 'eshell-module)) -- 2.25.1