Review of Readline command documentation

[Branden Robinson]

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