bash.1 anomalously documents some readline variables

[Branden Robinson]

Configuration Information [Automatically generated, do not change]:
Machine: x86_64
OS: cygwin
Compiler: gcc
Compilation CFLAGS:  -DPROGRAM='bash.exe' -DCONF_HOSTTYPE='x86_64'
-DCONF_OSTYPE='cygwin' -DCONF_MACHTYPE='x86_64-unknown-cygwin'
-DCONF_VENDOR='unknown' -DLOCALEDIR='/usr/share/locale'
-DPACKAGE='bash' -DSHELL -DHAVE_CONFIG_H -DRECYCLES_PIDS   -I.
-I/usr/src/bash-4.3.42-4.x86_64/src/bash-4.3
-I/usr/src/bash-4.3.42-4.x86_64/src/bash-4.3/include
-I/usr/src/bash-4.3.42-4.x86_64/src/bash-4.3/lib  -DWORDEXP_OPTION
-ggdb -O2 -pipe -Wimplicit-function-declaration
-fdebug-prefix-map=/usr/src/bash-4.3.42-4.x86_64/build=/usr/src/debug/bash-4.3.42-4
-fdebug-prefix-map=/usr/src/bash-4.3.42-4.x86_64/src/bash-4.3=/usr/src/debug/bash-4.3.42-4
uname output: CYGWIN_NT-6.3 Lenovo-PC 2.4.1(0.293/5/3) 2016-01-24
11:26 x86_64 Cygwin
Machine Type: x86_64-unknown-cygwin

Bash Version: 4.3
Patch Level: 42
Release Status: release

Description:
        Bash man page has anomalous documentation of readline variables

Repeat-By:
        In bash.1, in the "Readline Variables" section:

        1. The "blink-matching-paren" variable is not documented.  The feature
        works despite the claims at:
            
https://superuser.com/questions/213872/bash-readline-blink-matching-paren-not-blinking-matching-parentheses

           I was able to toggle the feature via all the methods I'm aware of:
               a) edit .inputrc, re-exec() bash;
               b) edit .inputrc, C-x C-r at prompt; and
               c) bind "set blink-matching-paren $BOOL", where $BOOL is "on" or
               "off"

        2. The "byte-oriented" variable is not documented.  A grep of the source
        code suggests that the feature is defunct and the variable can be
        removed from lib/readline/bind.c:boolean_varlist.

        3. The "completion-display-width" variable is not documented here.  It's
        documented in lib/readline/doc/rluser.texi, though.

        4. The "completion-map-case" variable is not documented here.  It's
        documented in lib/readline/doc/rluser.texi, though.

        N.B.: I find this variable to be confusingly named.  I don't think of
        the "-" and "_" characters as having case.  I don't think the Unicode
        standard does either; I'm willing to research the topic if you like.

        5. The "convert-meta" variable is documented as defaulting "on", but
        that appears to be out of date per lib/readline/bind.c:boolean_varlist.

        The example .inputrc in lib/readline/doc/rluser.texi should perhaps be
        updated to document reasons for turning convert-meta on rather than off.
        If so, question G1 in the FAQ may also benefit from an update.  You know
        better than I whether most Bash users are living in 8-bit friendly
        terminals.

        6. The "editing-mode" variable is out of lexicographic order, preceding
        "echo-control-characters".  The same is true in
        lib/readline/doc/rluser.texi.

        7. The "history-size" variable documents a default of "0", which appears
        to be incorrect.  bashhist.c:load_history() sets it to 500 if the user
        hasn't already set it.

        lib/readline/bind.c:sv_histsize() seem to set the history size to 500 as
        well, if the function is passed something that can't be parsed as an
        integer.  This suggests that lib/readline/doc/rluser.texi should be
        updated as well.

        8. The "input-meta" variable is documented as defaulting "off", and that
        agrees with lib/readline/bind.c:boolean_varlist, but when I launch bash
        with --noprofile --norc, it appears to default on instead.  Perhaps the
        default is determined by querying the terminal?

        Also, I'm having trouble understanding this option's description as
        anything but strictly the logical inverse of "convert-meta".  However,
        it does not behave that way; input-meta/meta-flag is controllable
        independently of convert-meta.

        Perhaps at least two of "convert-meta", "input-meta", and "meta-flag"
        could be deprecated for Bash 4.4 and made to go away in a subsequent
        release?

        If it's a matter of one flag ignoring/stripping the eighth bit*, and the
        other interpeting an unstripped 8-bit character as a printable
        character** or a meta-key sequence, then could that please be clarified
        in the man page?

        * Which I would have thought to be the terminal driver's responsibility,
        but I realize Bash has to work on some incredibly brain-damaged systems.

        ** I then remember the C1 characters and throw up my hands in despair.

        9. The "isearch-terminators" variable is documented in the man page,
        but, if left at its default value, not reported by "bind -v" or "bind
        -V".

        10. The "meta-flag" variable is not documented in its own right, but
        only mentioned under the entry for "input-meta" as an alias for the
        latter.  I would add a brief cross-reference entry, "see input-meta,
        above"), since some users are not sophisticated enough to run a search
        in the pager.  If this variable name is to be deprecated, question G1 in
        the FAQ should perhaps be updated to refer to "input-meta" instead.

        that agrees with lib/readline/bind.c:boolean_varlist, but when I launch
        bash with --noprofile --norc, it appears to default on instead.

        11. The "output-meta" variable is documented as defaulting "off", and
        that agrees with lib/readline/bind.c:boolean_varlist, but when I launch
        bash with --noprofile --norc, it appears to default on instead.  Perhaps
        the default is determined by querying the terminal?

        12. The "prefer-visible-bell" variable is not documented here.  It's not
        documented in lib/readline/doc/rluser.texi, either.  It appears that
        readline defaults to an audible bell at lib/readline/readline.c:227, but
        lib/readline/bind.c:91 overrides this with a visible default.

Fix:
        I'm happy to provide documentation patches for all of the above issues,
        but some of them I don't completely understand.

Best regards,
Branden