bug#10057: 24.0.91; doc string of `Info-find-file'

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

> > What part of this problem statement (your "what") is so difficult
> > to understand?
> >
> >  >> This says only what a value of `t' means.
> >  >> It does not say what other non-nil values mean.
> 
> This statement implies that there are other non-nil values that should
> be documented.

No, it does not imply that, if by that you mean particular non-nil values.  But
it might have been clearer if I had added "might":

"It does not say what other non-nil values might mean."

IOW, there is nothing in my statement that implies that there are other non-nil
values that act differently from `t'.  The point was that non-nil other than t
is not addressed.

So yes, there are other non-nil values, and yes, something should be said about
them.  If they are in the same boat as `t', then there is nothing particular to
say about any of them - including `t': just say "non-nil".

Anyway, you already raised that question for clarification and I answered it:

>> > Do you know other possible non-nil values?
>> 
>> No, not I.  If all non-nil values are treated the same, then 
>> the doc should not single out `t'.  As it stands now, it says
>> "if t, ..." it means ..., which _suggests_ that that is the case
>> _only_ if t.
>> 
>> Either it is saying the wrong thing (via such a suggestion of 
>> "only") or it is incomplete (saying nothing about other non-nil
>> values).
>> 
>> If what is really meant is "if non-nil,...", then please just 
>> say that.

> I'm not aware of other non-nil values you are 
> talking about.

Again.  You asked that already and I answered it.

But "you are talking about" is incorrect - I did not talk about any other
particular non-nil values.

The point is that there _are_ other non-nil values besides `t', and the doc
string does not cover them (but the code handles them, and exactly like `t').

If they are intended (NB _intended_) to act the same as `t', then the doc string
should simply say "non-nil", not "t".

There is no reason to single out `t' here, any more than 42 or `Juri'.  Unless
there is a reason - and in that case, it should be passed along to the users.

It's about making things clear to readers; nothing more than that.  What happens
if the value is 42?  Readers wonder (I did, for one) and they have the right to
know.  Without having to look in the code to find out.

If you want to say that non-nil and non-t is unpredictable and unsupported,
that's fine, and clear.  Saying nothing leaves readers wondering.

> > In any case, I did say how I would like to see it fixed:
> >
> >  >> Please state clearly and completely what NOERROR means.
> 
> Such unclear statements are of no help until you explain
> what do you mean by "clearly".

Doesn't really matter what I mean by "clearly".  As I said, the "how" is not
important.  Fix it anyway you like - choose your own meaning of "clearly" and
"completely".

Come on.  Today, non-nil values other than `t' are not described _at all_.  So
any description of them that is at all accurate would be an improvement in
clarity and completeness.

You are making a big deal out of nothing.

If some other user had reported this bug, saying only "Please change `t' to
`non-nil'", would there have been such a clamor?  I wonder.