Documentation of `file-name-completion' is somewhat confusing

Documentation of `file-name-completion' is somewhat confusing

[Xue Fuqiao]

Hi list,

In (info "(elisp) File Name Completion"):
 -- Function: file-name-completion filename directory &optional
          predicate
[...]
     If PREDICATE is non-`nil' then it ignores possible completions that
     don't satisfy PREDICATE, after calling that function with one
     argument, the expanded absolute file name.

And in the doc string of this function:
    If PREDICATE is non-nil, call PREDICATE with each possible
    completion (in absolute form) and ignore it if PREDICATE returns
    nil.

It seems to me that the arguments of PREDICATE described by these two
paragraphs don't agree with each other: the first one is "the expanded
absolute file name", but the second one is "each possible completion".
IMHO the latter is more appropriate.  Or maybe I got something wrong.
Any ideas?

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: Documentation of `file-name-completion' is somewhat confusing

[Eli Zaretskii]

> Date: Wed, 12 Jun 2013 10:07:37 +0800
> From: Xue Fuqiao <xfq.free@gmail.com>
> 
> In (info "(elisp) File Name Completion"):
>  -- Function: file-name-completion filename directory &optional
>           predicate
> [...]
>      If PREDICATE is non-`nil' then it ignores possible completions that
>      don't satisfy PREDICATE, after calling that function with one
>      argument, the expanded absolute file name.
> 
> And in the doc string of this function:
>     If PREDICATE is non-nil, call PREDICATE with each possible
>     completion (in absolute form) and ignore it if PREDICATE returns
>     nil.
> 
> It seems to me that the arguments of PREDICATE described by these two
> paragraphs don't agree with each other: the first one is "the expanded
> absolute file name", but the second one is "each possible completion".
> IMHO the latter is more appropriate.  Or maybe I got something wrong.
> Any ideas?

Why do you think that "expanded absolute file name" of a "possible
completion" and "each possible completion (in absolute form)" are
anything but the same thing?  Where exactly do you see the difference
between these two?

Re: Documentation of `file-name-completion' is somewhat confusing

[Xue Fuqiao]

On Wed, Jun 12, 2013 at 10:58 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 12 Jun 2013 10:07:37 +0800
>> From: Xue Fuqiao <xfq.free@gmail.com>
>>
>> In (info "(elisp) File Name Completion"):
>>  -- Function: file-name-completion filename directory &optional
>>           predicate
>> [...]
>>      If PREDICATE is non-`nil' then it ignores possible completions that
>>      don't satisfy PREDICATE, after calling that function with one
>>      argument, the expanded absolute file name.
>>
>> And in the doc string of this function:
>>     If PREDICATE is non-nil, call PREDICATE with each possible
>>     completion (in absolute form) and ignore it if PREDICATE returns
>>     nil.
>>
>> It seems to me that the arguments of PREDICATE described by these two
>> paragraphs don't agree with each other: the first one is "the expanded
>> absolute file name", but the second one is "each possible completion".
>> IMHO the latter is more appropriate.  Or maybe I got something wrong.
>> Any ideas?
>
> Why do you think that "expanded absolute file name" of a "possible
> completion" and "each possible completion (in absolute form)" are
> anything but the same thing?  Where exactly do you see the difference
> between these two?

Well, I misunderstood it.  I thought the "expanded absolute file name"
is for FILENAME, so the first version has only one argument: FILENAME
(in absolute form).

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/