diff --git a/README.md b/README.md
index 645ef5c6a44..21b6b1495e3 100644
--- a/README.md
+++ b/README.md
@@ -188,58 +188,6 @@ A. Install it in one of the directories pointed to by
      ${BASH_COMPLETION_COMPLETIONSDIR})
    ```
 
-**Q. I use CVS in combination with passwordless SSH access to my remote
-   repository. How can I have the `cvs` command complete on remotely
-   checked-out files where relevant?**
-
-A. Define `$COMP_CVS_REMOTE`. Setting this to anything will result in
-   the behaviour you would like.
-
-**Q. When I'm running a `./configure` script and completion returns a list
-   of long options to me, some of these take a parameter,
-   e.g. `--this-option=DESCRIPTION`.**
-
-   **Running `./configure --help` lists these descriptions, but
-   everything after the `=` is stripped when returning completions, so
-   I don't know what kind of data is expected as a given option's
-   parameter.**
-
-   **Is there a way of getting `./configure` completion to return the
-   entire option string, so that I can see what kind of data is
-   required and then simply delete the descriptive text and add my own
-   data?**
-
-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.**
diff --git a/completions/tar b/completions/tar
index b9820969aae..da3c8785871 100644
--- a/completions/tar
+++ b/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()
 {
diff --git a/doc/bash_completion.txt b/doc/bash_completion.txt
index d5be2958622..2a5effdbab0 100644
--- a/doc/bash_completion.txt
+++ b/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.