RE: Q on read-file-name and completion-ignored-extensions

["Drew Adams" <drew.adams@oracle.com>]

       I guess the reference to `file-name-all-completions' was mistaken,

    No, that reference is correct.  `file-name-all-completions' is the
    function used internally by the commands that display completion lists
    and it is _really_ unaffected by `completion-ignored-extensions'
    (otherwise, there would be a bug).  Note that
    `file-name-all-completions' is described in exactly the same Info node
    as `completion-ignored-extensions'.

       This does _not_ display the list (of all four files), even
       though TAB would normally display the list of possible
       completions in that case (since the
       common part is already in the minibuffer).

    The minibuffer commands do not ignore completion-ignored-extensions in
    deciding _whether_ to display lists of completions (as opposed to
    doing completion), it only ignores it _when_ it displays them.

       Is it perhaps true that the "displaying a list of
       completions" that shows ignored completions (even
       when there are non-ignored candidates) applies
       only to display by `?' and not to display by TAB?

    No, it affects TAB too, if TAB can not do completion, even ignoring
    all extensions in completion-ignored-extensions.  As I explained, TAB
    takes completion-ignored-extensions into account in deciding whether
    it can do completion (as opposed to having to display a list of
    completions), but _after_ it decides that it has to display a list, it
    ignores the variable.

Great. So, since none of that info is in the doc string or the manual, let's
add it:

 Completion ignores file names ending in any string in this list.
 It ignores directory names if they match any string in the list
 that ends in a slash (/).
 However:
  - If all possible completions have ignored extensions, then those
    completions are not ignored.
    Example: If .ico is an ignored extension, and the only possible
    completions are fun.ico and fudge.ico, then those file names
    are available for completion: `C-x C-f fud TAB' completes to
    fudge.ico.
  - Displayed and returned lists of possible completions include
    file names, even if they have ignored extensions. This includes
    the completions displayed in buffer *Completions*, as well as
    the lists of completions returned by functions such as
    `file-name-all-completions'. File names with ignored extensions
    are ignored in deciding whether buffer *Completions* is to be
    displayed, but if it is displayed then it includes any matching
    file names with ignored extensions.
    Example: files fun.ico and fun.el, `C-x C-f fun. TAB' completes
    to fun.el, because fun.ico is ignored for completion.
    `C-x C-f fun ?' displays fun.el and fun.ico in *Completions*,
    because ignored file names are included whenever *Completions*
    is displayed.

Reword as needed. The various points you've made should be addressed in a
clear way, preferably with examples. The examples might be reserved for the
Elisp manual, leaving the doc string simpler (if less clear):

 Completion ignores file names ending in any string in this list.
 It ignores directory names if they match any string in the list
 that ends in a slash (/).
 However:
  - If all possible completions have ignored extensions, then those
    completions are not ignored.
  - Displayed and returned lists of possible completions include
    file names, even if they have ignored extensions. This includes
    the completions displayed in buffer *Completions*, as well as
    the lists of completions returned by functions such as
    `file-name-all-completions'. File names with ignored extensions
    are ignored in deciding whether buffer *Completions* is to be
    displayed, but if it is displayed then it includes any matching
    file names with ignored extensions.