[Bash-completion-devel] Bug#780895: Poor documentation and discoverability

[Brian Julin]

Package: bash-completion
Version: 1:2.1-4
Severity: minor
Tags: upstream patch

Figuring out how to customize the pre-installed Debian bash completions
is not easy.

This is probably what happens to your average CLI user when they get fed
up with some of bash completion's defaults and decide to try to change
them:

$ make li<TAB>
$ # .oO(grr I hate bash completions sometimes)
$ <TAB><TAB>
$ man -k completion
dh_bash-completion (1) - install bash completions for package
systemd-notify (1)   - Notify service manager about start-up completion and o..
$ # .oO(grumble)
$ less /etc/bash_completion
$ # .oO(I bet that file is really long)
$ less /etc/bash_completions.d/<TAB><TAB>
$ .oO(#pick one, I guess)
$ less /etc/bash_completions.d/debconf
$ complete -h
bash: complete: -h: invalid option
complete: usage: complete [-abcdefgjksuv] [-pr] [-DE] [-o option] [-A action] [-G globpat] [-W wordlist]  [-F function] [-C command] [-X filterpat] [-P prefix] [-S suffix] [name ...]
$ # .oO(grumble, google, google)
$ help complete
complete: complete [-abcdefgjksuv] [-pr] [-DE] [-o option] [-A action] [-G globpat] [-W wordlist]  [-F function] [-C command] [-X filterpat] [-P prefix] [-S suffix] [name ...]
    Specify how arguments are to be completed by Readline.

    For each NAME, specify how arguments are to be completed.  If no options
    are supplied, existing completion specifications are printed in a way that
    allows them to be reused as input.

    Options:
      -p    print existing completion specifications in a reusable format
      -r    remove a completion specification for each NAME, or, if no
      NAMEs are supplied, all completion specifications
      -D    apply the completions and actions as the default for commands
      without any specific completion defined
      -E      apply the completions and actions to "empty" commands --
      completion attempted on a blank line

    When completion is attempted, the actions are applied in the order the
    uppercase-letter options are listed above.  The -D option takes
    precedence over -E.

    Exit Status:
    Returns success unless an invalid option is supplied or an error occurs.
$ complete -p make
complete -F _make make
$ complete -r make
$ complete -p make
bash: complete: make: no completion specification
$ make li<TAB>
$ # .oO(wth?!?)
$ <TAB><TAB>
$ complete -p make
complete -F _make make
$ ls /etc/*complet*
/etc/bash_completion

/etc/bash_completion.d:
debconf                initramfs-tools  libreoffice.sh                 unar
desktop-file-validate  inkscape         pon                            whiptail
git-prompt             insserv          pulseaudio-bash-completion.sh
grub                   jackd            pygmentize
$ less /etc/bash_completion
$ less /usr/share/bash-completion/bash_completion
$ # .oO(holy crap I'm not reading all that)
$ zless /usr/share/doc/bash-completion/README.gz
$ # .oO(no screw that I don't want to use M-/ I just want TAB to work here.)
$ less /usr/share/bash-completion/bash_completion
$ # .oO(Oh, it autoloads, THAT's why I can't just remove it.)
$ man builtins
$ # .oO(Ah good the rest of the options were documented there)
$ complete -o default -F _make make
$ make li<TAB>b/fo<TAB>bar.c^Ho
$ # .oO( Finally! )

Attached is a patch for the README.  Some comments in /etc/bash_completion
directing users to the README might also help, or a stub documentation
page for /etc/bash_completion which does so.

Additionally, the source tree has doc files that do not appear to be
installed, such as doc/bash_completion.txt:

$ rgrep COMP_FILEDIR_FALLBACK /usr/share
 /usr/share/bash-completion/bash_completion:    [[ -n ${COMP_FILEDIR_FALLBACK:-} && \
$ zgrep COMP_FILEDIR_FALLBACK /usr/share/*
$ zgrep COMP_FILEDIR_FALLBACK /usr/share/*/*
/usr/share/bash-completion/bash_completion:    [[ -n ${COMP_FILEDIR_FALLBACK:-} && \
$ zgrep COMP_FILEDIR_FALLBACK /usr/share/*/*/*



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.alioth.debian.org/pipermail/bash-completion-devel/attachments/20150321/55d70677/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: bash_complete_readme_more.patch
Type: text/x-patch
Size: 1316 bytes
Desc: bash_complete_readme_more.patch
URL: <http://lists.alioth.debian.org/pipermail/bash-completion-devel/attachments/20150321/55d70677/attachment.bin>