docs(tar): move commentary from README to variable and implementation

While at it, make semantics of setting the variable more accurate: it
needs to be set before the *tar* completion is sourced (not
bash_completion), and it needs to be set to a non-null value.

Author: scop

README.md

@@ -212,34 +212,6 @@ A. Define `$COMP_CVS_REMOTE`. Setting this to anything will result in
 A. Define `$COMP_CONFIGURE_HINTS`. Setting this to anything will
    result in the behaviour you would like.
 
-**Q. When doing tar completion on a file within a tar file like this:**
-
-   ```shell
-   tar tzvf foo.tar.gz <Tab>
-   ```
-
-   **the pathnames contained in the tar file are not displayed
-   correctly. The slashes are removed, and everything looks like it's
-   in a single directory. Why is this?**
-
-A. It's a choice we had to make. bash's programmable completion is
-   limited in how it handles the list of possible completions it
-   returns.
-
-   Because the paths returned from within the tar file are likely not
-   existing paths on the file system, `-o dirnames` must be passed to
-   the `complete` built-in to make it treat them as such. However,
-   then bash will append a space when completing on directories during
-   pathname completion to the tar files themselves.
-
-   It's more important to have proper completion of paths to tar files
-   than it is to have completion for their contents, so this sacrifice
-   was made and `-o filenames` is used with complete instead.
-
-   If you would rather have correct path completion for tar file
-   contents, define `$COMP_TAR_INTERNAL_PATHS` *before* sourcing
-   `bash_completion`.
-
 **Q. When completing on a symlink to a directory, bash does not append
    the trailing `/` and I have to hit <kbd>&lt;Tab></kbd> again.
    I don't like this.**

completions/tar

@@ -37,6 +37,24 @@
 #        - mode option should be advised only once
 #        - format option should be advised only once
 #        ...
+#
+# Tar files vs internal paths
+# ===========================
+#
+# bash's programmable completion is limited in how it handles the list of
+# possible completions it returns.
+#
+# Because the paths returned from within the tar file are likely not existing
+# paths on the file system, `-o dirnames` must be passed to the `complete`
+# built-in to make it treat them as such. However, then bash will append a
+# space when completing on directories during pathname completion to the tar
+# files themselves.
+#
+# It's more important to have proper completion of paths to tar files than it
+# is to have completion for their contents, so this sacrifice was made and
+# `-o filenames` is used with complete instead by default. Setting the
+# `$COMP_TAR_INTERNAL_PATHS` environment variable to a non-null
+# value *before sourcing* this completion toggles that the other way around.
 
 __gtar_parse_help_opt()
 {

doc/bash_completion.txt

@@ -57,7 +57,9 @@
     Default is unset.
 
 *COMP_TAR_INTERNAL_PATHS*::
-    If set and not null *before* sourcing bash_completion, `tar` completion
-    will do correct path completion for tar file contents.  If unset or null,
-    `tar' completion will do correct completion for paths to tar files.  See
-    also README.
+    If set and not null *before sourcing* the `tar` completion, it will do
+    correct path completion for tar file _contents_.  If unset or null,
+    _paths to_ tar files will be correctly completed. Unfortunately we do not
+    have a way to make both Just Work properly at the moment.  We consider it
+    more important to have proper completion of paths to tar files than it is
+    to have completion for their contents, so the default is unset.