RE: read-file-name-predicate

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

> > My point is that it is currently entre deux chaises. Either 1)
> > it should be, as it is, accessible from Lisp, in which case it
> > should be documented, or 2) it should be inaccessible from Lisp.
> > (Yes, I do realize that not everything that is accessible from
> > Lisp is documented.)
>
> There are internal functions written in Lisp and internal Lisp
> variables.  They are frequently not documented too well because it is
> frequently hard to document them without explaining a lot of Emacs
> internals.  This is perfectly normal.
>
> I don't know if in this specific case the variable is a left-over from
> something we don't need anymore; I hope Kim will answer that.  But
> your general point -- that Lisp variables should all be documented to
> the degree that every Emacs user should understand -- is not valid (as
> a generality).

Eli, you are arguing against the wind again.

That was *not* my "general point". I did *not* make that point at all, in
fact. I never said anything about "all" Lisp variables needing to be
documented. I explicitly said "Yes, I do realize that *not* everything that
is accessible from
Lisp is documented."

I argued only for documenting *this* variable, not all Lisp variables. The
argument I gave for documenting *this* variable is that it is useful for
Lisp programmers. The current doc does not say what it is for or what it
does. To use it, users will need to know that info. It's really very simple:
just say that this is the predicate supplied to `read-file-name'.

I also said nothing about "internal Lisp variables".

My point about internal/external was to point out that this variable, whose
doc says only that it is for use by a C-coded Lisp function, is not, in
fact, only accessible or only useful for that built-in function. It is just
as useful as the variable `minibuffer-completion-predicate', which is
prominently documented, and which is also used by a built-in function. To
me, these two variables are parallel.

Is this clear enough:

*IF*, as I hope, this is to remain a Lisp variable, and *IF*, as I claim, it
is useful to users in the same way that `minibuffer-completion-predicate' is
useful, *THEN* it should be documented similarly to
`minibuffer-completion-predicate'.

*IF* someone decides that this should be usable only by the built-in Lisp
function `read-file-name', *THEN* perhaps it should not be a Lisp variable
at all. A Lisp variable whose doc says, in effect, "There is no reason that
I am a Lisp variable, I don't do anything anyway, and you must not use me"
is silly.