Document prompt mode
* eat.texi (Shell Integration): Divide into sections. Add new section 'Native Shell Prompt Editing'. * README.org (Usage): Document "prompt" mode. * README.org (Comparison With Other Terminal Emulators): Update comparison.
This commit is contained in:
Akib Azmain Turja
parent
89983b580c
commit
d83f53990f
3 changed files with 94 additions and 14 deletions
20
README.org
20
README.org
|
|
@ -20,7 +20,7 @@ To get the most out of Eat, you should also setup shell integration.
|
|||
|
||||
* Usage
|
||||
|
||||
To start Eat, run =M-x eat=. Eat has three keybinding modes:
|
||||
To start Eat, run =M-x eat=. Eat has four keybinding modes:
|
||||
|
||||
- "semi-char" mode: This is the default keybinding mode. Most keys
|
||||
are bound to send the key to the terminal, except the following
|
||||
|
|
@ -46,6 +46,13 @@ To start Eat, run =M-x eat=. Eat has three keybinding modes:
|
|||
terminal, except =C-M-m= or =M-RET=, which is bound to switch to
|
||||
"semi-char" keybinding mode.
|
||||
|
||||
- "prompt" mode: Similar to Shell mode or Term line mode. You need to
|
||||
enable shell integration to enable this feature.
|
||||
|
||||
- =C-c C-e=: Switch to "emacs" keybinding mode
|
||||
- =C-c C-j=: Switch to "semi-char" keybinding mode.
|
||||
- =C-c M-d=: Switch to "char" keybinding mode.
|
||||
|
||||
If you like Eshell, then there is a good news for you. Eat integrates
|
||||
with Eshell. Eat has two global minor modes for Eshell:
|
||||
|
||||
|
|
@ -138,11 +145,8 @@ is pretty good too. But it's slow. It is so slow that Eat can beat
|
|||
native-compiled Term even without byte-compilation, and when Eat is
|
||||
byte-compiled, Eat is more than three times fast. Also, Term
|
||||
flickers, just try to run =emacs -nw= in it. It doesn't support
|
||||
remote connections, for example over Tramp. However, it has "line"
|
||||
mode, which Eat still doesn't have. If you want line mode in a
|
||||
terminal, or use an old version of Emacs, you can use Term, but
|
||||
Coterm + Shell is probably a better choice in case your Emacs version
|
||||
is 26.1 or above.
|
||||
remote connections, for example over Tramp. However, it's builtin
|
||||
from the early days of Emacs, while Eat needs atleast Emacs 28.1.
|
||||
|
||||
** Vterm
|
||||
|
||||
|
|
@ -163,8 +167,8 @@ just a bit slow than Eat. However, it too flickers like other
|
|||
terminals. Since it's an upgrade to Shell, you get all the features
|
||||
of Shell like "line" mode, completion using your favorite completion
|
||||
UI (Company, Corfu, etc), etc. Most of these features are available
|
||||
in Eat-Eshell-Mode as Eshell is similar to Shell, however it's not
|
||||
Shell mode. Recommended if you like Shell.
|
||||
in Eat, and also in Eat-Eshell-Mode as Eshell is similar to Shell,
|
||||
however it's not Shell mode. Recommended if you like Shell.
|
||||
|
||||
* Acknowledgements
|
||||
|
||||
|
|
|
|||
2
eat.el
2
eat.el
|
|
@ -5600,7 +5600,7 @@ EVENT is the mouse event."
|
|||
(define-key map [C-up] #'eat-prompt-previous-input)
|
||||
(define-key map [C-down] #'eat-prompt-next-input)
|
||||
(define-key map [?\M-r] #'eat-prompt-previous-matching-input)
|
||||
(define-key map [?\C-c ?\M-r] #'eat-prompt-find-input)
|
||||
(define-key map [?\C-c ?\C-r] #'eat-prompt-find-input)
|
||||
(define-key map [?\C-c ?\M-r]
|
||||
#'eat-prompt-previous-matching-input-from-input)
|
||||
(define-key map [?\C-c ?\M-s]
|
||||
|
|
|
|||
86
eat.texi
86
eat.texi
|
|
@ -392,12 +392,14 @@ If you use Zsh, put the following in your @samp{.zshrc} file:
|
|||
source "$EAT_SHELL_INTEGRATION_DIR/zsh"
|
||||
@end example
|
||||
|
||||
@anchor{Directory tracking}
|
||||
@cindex directory tracking
|
||||
@cindex tracking directory
|
||||
@cindex working directory tracking
|
||||
@cindex tracking working directory
|
||||
@cindex cwd tracking
|
||||
@cindex tracking cwd
|
||||
@section Directory tracking
|
||||
After you've setup shell integration, the Eat will track the working
|
||||
directory of your shell. That means @command{find-file} will start
|
||||
from your shell's current working directory. This also works in
|
||||
|
|
@ -410,10 +412,12 @@ This controls directory tracking. When set to non-@code{nil}, Eat
|
|||
tracks the current working directory of programs.
|
||||
@end defopt
|
||||
|
||||
@anchor{Shell Prompt Navigation}
|
||||
@cindex shell prompt navigation
|
||||
@cindex shell navigation, shell prompt
|
||||
@cindex prompt navigation
|
||||
@cindex navigation, prompt
|
||||
@section Shell Prompt Navigation
|
||||
@kindex C-c C-p @r{(``emacs mode''})
|
||||
@kindex C-c C-p @r{(``semi-char mode'')}
|
||||
@findex eat-previous-shell-prompt
|
||||
|
|
@ -437,12 +441,14 @@ You can narrow (@pxref{Narrowing,,, emacs, GNU Emacs Manual}) down Eat
|
|||
buffer to a shell prompt and its output (if any) using the key
|
||||
sequence @kbd{C-x n d}, bound to @command{eat-narrow-to-shell-prompt}.
|
||||
|
||||
@anchor{Shell Prompt Annotation}
|
||||
@cindex shell prompt annotation
|
||||
@cindex annotation, shell prompt
|
||||
@cindex annotate, shell prompt
|
||||
@cindex prompt annotation
|
||||
@cindex annotation, prompt
|
||||
@cindex annotate, prompt
|
||||
@section Shell Prompt Annotation
|
||||
When shell integration is setup, Eat annotates each shell prompt. Eat
|
||||
puts a mark on the shell prompt indicating the whether the command
|
||||
entered in that prompt is running, exited successfully or exited with
|
||||
|
|
@ -489,6 +495,76 @@ face @code{eat-shell-prompt-annotation-failure} control the indicator
|
|||
used to indicate the command has exited unsuccessfully with non-zero
|
||||
exit status.
|
||||
|
||||
@anchor{Native Shell Prompt Editing}
|
||||
@cindex native shell prompt editing
|
||||
@cindex shell prompt native editing
|
||||
@cindex native prompt editing
|
||||
@cindex prompt native editing
|
||||
@cindex shell prompt, native editing
|
||||
@cindex prompt, native editing
|
||||
@cindex prompt mode
|
||||
@cindex mode, prompt
|
||||
@cindex keybindings, prompt mode
|
||||
@cindex keybinding mode, prompt
|
||||
@cindex input mode, prompt
|
||||
@section Native Shell Prompt Editing
|
||||
|
||||
When this feature is enabled, you can edit shell command with regular
|
||||
Emacs command, similar to Shell mode and Term line mode
|
||||
(@pxref{Shell Mode,,, emacs, GNU Emacs Manual} and
|
||||
@ref{Terminal emulator,,, emacs, GNU Emacs Manual}). This
|
||||
feature isn't support in Eshell.
|
||||
|
||||
To enable native shell prompt editing, customize the user option
|
||||
@code{eat-enable-native-shell-prompt-editing}.
|
||||
|
||||
@vindex eat-enable-native-shell-prompt-editing
|
||||
@defopt eat-enable-native-shell-prompt-editing
|
||||
When non-nil, enable support for editing shell commands with native
|
||||
Emacs commands.
|
||||
@end defopt
|
||||
|
||||
When the feature is enabled, Eat automatically switches to a input
|
||||
mode named ``prompt mode'' when the shell prompt appears. In this
|
||||
mode, you can write and edit your shell command input with Emacs. You
|
||||
can't modify the text inside the terminal, however.
|
||||
|
||||
@kindex @key{RET} @r{(``prompt mode'')}
|
||||
@kindex C-d @r{(``prompt mode'')}
|
||||
@kindex C-c C-c @r{(``prompt mode'')}
|
||||
@kindex C-c @key{SPC} @r{(``prompt mode'')}
|
||||
@kindex @key{TAB} @r{(``prompt mode'')}
|
||||
In ``prompt mode'', just like an ordinary shell, you can send the
|
||||
input with @kbd{@key{RET}}, and exit shell with @kbd{C-d} when the
|
||||
input is empty. You can cancel input with @kbd{C-c C-c}. If you want
|
||||
to write a newline without sending it, you can do so with
|
||||
@kbd{C-c @key{SPC}}, To perform completion, press @kbd{@key{TAB}}.
|
||||
|
||||
@kindex M-p @r{(``prompt mode'')}
|
||||
@kindex M-n @r{(``prompt mode'')}
|
||||
@kindex C-@key{up} @r{(``prompt mode'')}
|
||||
@kindex C-@key{down} @r{(``prompt mode'')}
|
||||
@kindex M-r @r{(``prompt mode'')}
|
||||
@kindex C-c M-r @r{(``prompt mode'')}
|
||||
@kindex C-c M-s @r{(``prompt mode'')}
|
||||
@kindex C-c C-r @r{(``prompt mode'')}
|
||||
@kindex @key{TAB} @r{(``prompt mode'')}
|
||||
You can cycle through history with @kbd{M-p} and @kbd{M-n}, and also
|
||||
with @kbd{C-@key{up}} and @kbd{C-@key{down}}. @kbd{M-r} searches the
|
||||
input history, using minibuffer. @kbd{C-c M-r} and @kbd{C-c M-s}
|
||||
searches the input history taking the current input as the query.
|
||||
@kbd{C-c M-r} searches backward while @kbd{C-c M-s} searches forward.
|
||||
And @kbd{C-c C-r} searches the input history using minibuffer with
|
||||
completion.
|
||||
|
||||
@kindex C-c C-e @r{(``prompt mode'')}
|
||||
@kindex C-c C-j @r{(``prompt mode'')}
|
||||
@kindex C-c M-d @r{(``prompt mode'')}
|
||||
You can exit to ``emacs mode'', ``semi-char mode'' or ``char mode''
|
||||
with @kbd{C-c C-e}, @kbd{C-c C-j} or @kbd{C-c M-d} respectively. But
|
||||
once exited, you can't return to ``prompt mode'' without getting a new
|
||||
shell prompt.
|
||||
|
||||
@node Querying Before Kill
|
||||
@cindex querying before kill
|
||||
@cindex querying before kill terminal
|
||||
|
|
@ -1158,11 +1234,11 @@ found a bug, please report it. If you're doubt, please send it
|
|||
anyway. We can't promise that we'll fix the bug or implement your
|
||||
feature idea, or always agree that it's a bug, but we always want to
|
||||
hear from you. Please report bugs at
|
||||
@url{https://codeberg.org/akib/emacs-eat/issues/new}. You may send
|
||||
the bug report by emailing to the maintain
|
||||
(@kbd{M-x describe-package RET eat RET} would show the email address),
|
||||
but we prefer the former method, since the report is visible to
|
||||
everyone immediately.
|
||||
@url{https://codeberg.org/akib/emacs-eat/issues/}. You may send the
|
||||
bug report by emailing to the maintainer
|
||||
(@kbd{M-x describe-package @key{RET} eat @key{RET}} would show the
|
||||
email address), but we prefer the former method, since the report is
|
||||
visible to everyone immediately.
|
||||
|
||||
The most important principle in reporting a bug is to report
|
||||
@emph{facts}. Hypotheses and verbal descriptions are useful when they
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue