[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Review of Readline command documentation
From: |
Branden Robinson |
Subject: |
Review of Readline command documentation |
Date: |
Tue, 29 Nov 2016 23:57:51 +0000 |
Bash Version: 4.4
Release Status: release
Description:
I attempted a comprehensive review of Readline command documentation,
similar to what I did for Readline variables earlier this year. Thank
you for incorporating so many fixes into Bash 4.4.
* emacs-editing-mode: is documented in rluser.texi but not the manpage.
* vi-editing-mode: Ditto.
* old-menu-complete: is not documented anywhere except the FAQ.
* do-uppercase-version: documented but not implemented(!?)
Did I get the _good_ crack?
$ grep -rl do.uppercase bash-4.4
bash-4.4/doc/bash.html
bash-4.4/doc/bash.info
bash-4.4/doc/bashref.dvi
bash-4.4/doc/bashref.html
bash-4.4/doc/bashref.info
bash-4.4/doc/bashref.ps
bash-4.4/lib/readline/doc/rluser.texi
* Readline commands not documented at all:
arrow-key-prefix
appears to be dead code?
Might be a good time to remove it since readline just bumped its
major version number.
backward-byte
live code, tied up with multibyte character handling and
deprecated, undocumented "byte-oriented" readline variable
byte-oriented nowadays appears to be a way to make Bash behave
multibyte-ignorantly if it was compiled with multibyte awareness
(it's ALWAYS tested like this:
if (MB_CUR_MAX > 1 && !rl_byte_oriented)
or boolean-isomorphically thereto)
do-lowercase-version
very much alive, see lib/readline/text.c:1047-1056
also bound to many keys by default, so should be documented
PROPOSED LANGUAGE: (simply apes do-uppercase-version, mutatis mutandis)
If the metafied character x is uppercase, run the
command that is bound to the corresponding lowercase
character.
XXX: Are loops detected between this and do-uppercase-version?
No, but that's only because one of them doesn't actually exist.
forward-byte
see backward-byte above
history-substring-search-backward
Added in 4.3.
history-substring-search-forward
Ditto.
non-incremental-forward-search-history-again
live code, underneath rl_vi_search_again but also directly accessible
non-incremental-reverse-search-history-again
Ditto.
paste-from-clipboard
Not documented except in CHANGES, NEWS.
tty-status
Not documented.
vi-append-eol
None of the vi readline commands are documented; a glance at
historical Bashes (1.14.7, 2.05b, 3.2.57) suggests that they
never were. This might be because either:
1) no one loves both readline _and_ vi; or
2) vi is so intuitive that it doesn't require
documentation. If only we'd noticed 30 years
ago...
vi-append-mode
vi-arg-digit
vi-bWord
vi-back-to-indent
vi-backward-bigword
vi-backward-word
vi-bword
vi-change-case
vi-change-char
vi-change-to
vi-char-search
vi-column
vi-complete
vi-delete
vi-delete-to
vi-eWord
vi-end-bigword
vi-end-word
vi-eof-maybe
vi-eword
vi-fWord
vi-first-print
vi-forward-bigword
vi-forward-word
vi-fword
vi-goto-mark
vi-insert-beg
vi-insertion-mode
vi-match
vi-movement-mode
vi-next-word
vi-overstrike
vi-overstrike-delete
vi-prev-word
vi-put
vi-redo
vi-replace
vi-rubout
vi-search
vi-search-again
vi-set-mark
vi-subst
vi-tilde-expand
vi-yank-arg
vi-yank-to
Ditto. Would you like a patch documenting these? _I_ love both
vi and Readline...
Wishlist items
==============
* wishlist: show-mode-in-prompt should xref emacs-mode-string,
vi-cmd-cmode-string, vi-ins-mode-string
* wishlist: No need to repeat language about readline commands unbound
by default. (in my opinion)
+ overwrite-mode "By default, this command is unbound."
+ menu-complete "but is unbound by default."
+ menu-complete-backward "This command is unbound by default."
+ delete-char-or-list "This command is unbound by default."
+ skip-csi-sequence "This is unbound by default, but usually bound to
ESC-[." (explain rationale for this in rluser.texi? Is it a
sledgehammer for people with broken termcap/terminfo driven
insane by escape sequence crud echoing at the prompt?)
* wishlist: From the manpage, remove potentially confusing language
about what the readline command (menu-complete) is "intended"
to be bound to. rluser.texi is a better place to suggest
that people can bind menu-complete instead of complete to TAB.
* edit-and-execute-command description should put a space between the
keystrokes, like all the the other multi-key sqeuence bindings.
Issue appears in both bash.1 and rluser.texi.
* wishlist: Add some further notation explanation at "Readline Command
Names". PROPOSED LANGUAGE:
In the descriptions below, a multi-key sequence bound to
a command is presented with each of its constituent
keystrokes separated by spaces.
In a few cases, different keys are bound to the same
command. Where these occur, a comma and a space
separate each binding. Ellipses (...) have their usual
meaning; they are not literal.
* wishlist: warnings for parse failures and unrecognized readline commands and
variables in inputrc lines would be nice
* wishlist: emacs-mode-string is not lexicographically sorted in doc/bash.1
Thank you for your consideration!
Regards,
Branden
- Review of Readline command documentation,
Branden Robinson <=