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

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

[Drew Adams]

"Optional second argument NOERROR, if t, means if file is not found
just return nil (no error)."
 
Sigh.  This says only what a value of `t' means.  It does not say what
other non-nil values mean.  Please state clearly and completely what
NOERROR means.
 
In GNU Emacs 24.0.91.1 (i386-mingw-nt5.1.2600) of 2011-11-14 on MARVIN
 Windowing system distributor `Microsoft Corp.', version 5.1.2600
 configured using `configure --with-gcc (4.6) --no-opt --cflags
 -I"D:/devel/emacs/libs/libXpm-3.5.8/include"
 -I"D:/devel/emacs/libs/libXpm-3.5.8/src"
 -I"D:/devel/emacs/libs/libpng-dev_1.4.3-1/include"
 -I"D:/devel/emacs/libs/zlib-dev_1.2.5-2/include"
 -I"D:/devel/emacs/libs/giflib-4.1.4-1/include"
 -I"D:/devel/emacs/libs/jpeg-6b-4/include"
 -I"D:/devel/emacs/libs/tiff-3.8.2-1/include"
 -I"D:/devel/emacs/libs/gnutls-2.10.1/include" --ldflags
 -L"D:/devel/emacs/libs/gnutls-2.10.1/lib"'
 

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

[Juri Linkov]

> "Optional second argument NOERROR, if t, means if file is not found
> just return nil (no error)."
>
> Sigh.  This says only what a value of `t' means.  It does not say what
> other non-nil values mean.  Please state clearly and completely what
> NOERROR means.

Do you know other possible non-nil values?

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

[Stefan Monnier]

> "Optional second argument NOERROR, if t, means if file is not found
> just return nil (no error)."
 
> Sigh.  This says only what a value of `t' means.  It does not say what
> other non-nil values mean.  Please state clearly and completely what
> NOERROR means.
 
Well, it does say that if you use a non-nil and non-t value, you're on
your own.  So the only potentially missing doc is what happens when it's
absent (aka nil), which is only explained in a indirect way.


        Stefan

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

[Drew Adams]

> > "Optional second argument NOERROR, if t, means if file is not found
> > just return nil (no error)."
> >
> > This says only what a value of `t' means.  It does not say what
> > other non-nil values mean.  Please state clearly and completely what
> > NOERROR means.
> 
> 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.

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

[Drew Adams]

> > "Optional second argument NOERROR, if t, means if file is not found
> > just return nil (no error)."
>  
> > Sigh.  This says only what a value of `t' means.  It does 
> > not say what other non-nil values mean.  Please state clearly
> > and completely what NOERROR means.
>  
> Well, it does say that if you use a non-nil and non-t value, you're on
> your own.

No, it does _not_ say that.  It says nothing of the kind.  It says nothing about
non-nil and non-t.  Saying nothing is not the same thing as saying you're on
your own - far from it.

There is zero reason to mention any particular non-nil value here, unless there
really is something special about the behavior of that non-nil value.  Judging
by the email replies, there is not.

> So the only potentially missing doc is what happens when
> it's absent (aka nil), which is only explained in a indirect way.

There is no problem understanding what nil does.

You could have corrected this and made it crystal clear by now, by simply
changing `t' to `non-nil'.  Instead, defensive justification...

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

[Andreas Schwab]

"Drew Adams" <drew.adams@oracle.com> writes:

>> > "Optional second argument NOERROR, if t, means if file is not found
>> > just return nil (no error)."
>> >
>> > This says only what a value of `t' means.  It does not say what
>> > other non-nil values mean.  Please state clearly and completely what
>> > NOERROR means.
>> 
>> 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.

You are supposed to use only the value that is documented.  This is
called future compatibility.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Drew Adams]

> You are supposed to use only the value that is documented.  This is
> called future compatibility.

In that case, if that is truly a worry, then the doc should say that.  As it is,
the doc is vague and incomplete.  It does not at all convey the interpretation
you are adding here.

Hey - pick any set of supported values and associated behaviors you like.  Have
them mean whatever you like.  But document what they do, completely and
unambiguously.  If non-nil other than `t' is to be unsupported or discouraged
for reasons of <whatever>, then say so.

Sheesh.  This really should be a no-brainer.

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

[Stefan Monnier]

>> Well, it does say that if you use a non-nil and non-t value, you're on
>> your own.
> No, it does _not_ say that.

Yes it does.  We've been through this many times, and we know you disagree,
but "not documented" generally means "you're on your own".


        Stefan

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

[Stefan Monnier]

> You could have corrected this and made it crystal clear by now, by simply
> changing `t' to `non-nil'.  Instead, defensive justification...

After all these years, you could send patches and even install them yourself.


        Stefan

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

[Drew Adams]

> > You could have corrected this and made it crystal clear by 
> > now, by simply changing `t' to `non-nil'.  Instead,
> > defensive justification...
> 
> After all these years, you could send patches and even 
> install them yourself.

I've sent plenty of patches, throughout "all these years", as you know.

If you need a patch to change `t' to `non-nil' then there is a problem.

But it's not the lack of a patch that prevents you from making this doc change,
obviously.  You do not _want_ to make it.  You've made that clear, so don't ask
for a patch for the change! - that would be the height of mauvaise foi.

You apparently want a non-nil, non-t value to implicitly be considered
unpredictable and unsupported ("you're on your own"), for the benefit of "future
compatibility", and you apparently do not want to tell users that explicitly.
So be it.

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

[Glenn Morris]

"Drew Adams" wrote:

> I've sent plenty of patches, throughout "all these years", as you know.

Statistics are fun!

According to the ChangeLogs, 33 patches over the past 5 and a half years.

44 messages to bug-gnu-emacs so far this month.

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

[Stefan Monnier]

> I've sent plenty of patches, throughout "all these years", as you know.

No, I do not think you've sent plenty of them.  Especially not
docstring patches.

> If you need a patch to change `t' to `non-nil' then there is a problem.

You've overlooked the "and even  install them yourself" part.

> But it's not the lack of a patch that prevents you from making this
> doc change, obviously.  You do not _want_ to make it.

The docstring you quoted has a clear meaning of "undocumented behavior
for non-nil and non-t values".  I do not know whether that was the
intention of the original author and do not care to figure it out, so no
I don't want to install such a patch.  But if someone else wants to,
I won't oppose it.

> You apparently want a non-nil, non-t value to implicitly be considered
> unpredictable and unsupported ("you're on your own"), for the benefit
> of "future compatibility", and you apparently do not want to tell
> users that explicitly.  So be it.

Saying this explicitly everywhere we rely on it would be silly.
It's a general rule that applies to all software I know.


        Stefan

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

[Drew Adams]

> > I've sent plenty of patches, throughout "all these years", 
> > as you know.
> 
> According to the ChangeLogs, 33 patches over the past 5 and a 
> half years.

Which gives some indication perhaps of the acceptance of patches sent...

> 44 messages to bug-gnu-emacs so far this month.

...and of the number of bugs reported but not fixed (ChangeLogs).

FWIW, I count not 44 but 8 bug reports I submitted so far this month, and 16
bugs I submitted over the last 30 days.

The number of messages sent indicates little about the number of bugs involved,
and even less about the number of those bugs which were reported by me.

I submit bug reports to help Emacs.  You are free to ignore them, as you well
know.

> Statistics are fun!

Amuse-toi bien.

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

[Drew Adams]

> > I've sent plenty of patches, throughout "all these years", 
> > as you know.
> 
> No, I do not think you've sent plenty of them.  Especially not
> docstring patches.

I've sent as many patches as I've cared to send and had time to send.  If you do
not consider it enough, that's your right.  If more had actually been applied I
might have taken the time to send more - dunno.  Like yours, my contribution to
Emacs is voluntary.

> > If you need a patch to change `t' to `non-nil' then there 
> > is a problem.
> 
> You've overlooked the "and even install them yourself" part.

I do not try to install Emacs code, as you know.  That's my choice.  I report
bugs as a user, and I offer suggestions as a user.  You are free to ignore both,
as you know and sometimes do.

> > But it's not the lack of a patch that prevents you from making this
> > doc change, obviously.  You do not _want_ to make it.
> 
> The docstring you quoted has a clear meaning of "undocumented behavior
> for non-nil and non-t values".  I do not know whether that was the
> intention of the original author

Oh?  You don't know the intention?  I thought that was precisely your point: The
intention is clear to readers.

I thought your point was that missing info is necessarily intentionally missing,
and readers should know that - no need to question it.  And that lack signifies
no promises from Emacs Dev: unsupported, unpredictable behavior, to foster
future compatibility.  That's your "general rule" below, which you say applies
to all software.

Readers are supposed to know this, no?  They are not supposed, like me, to
wonder or question what is meant by this or that ambiguous or missing info.
They are supposed to assume that it is undocumented by design - as in all
software you know of.

By your rule, you, like other readers, should be able to conclude that this
apparent "oubli" was intentional.  That was your claim, no?  The fact that the
info is missing indicates clearly to readers "you're on your own", not that
somebody might have made a boo-boo when writing the doc string.

I just pointed out the missing info, raising the question.  I really did not
know what it meant, and I thought that other users too might like to know.  I
know what the _code_ does: it treats all non-nil values the same.  But that does
not imply that that's what you want to tell users, hence the question.  Your
answer was: if it's missing it should be missing - Circulez, il n'y a rien a
voir!  So be it.

> and do not care to figure it out,

Yes, well, that's the point, isn't it?  And that was the point of my bug report:
to raise the question it turns out you don't care to figure out.  It's not the
"intention of the original author" that counts at this point. It's your
intention that counts - what do you want here?

I didn't pose it in question form, admittedly.  I suggested that whatever the
intention (your call), it be made clear to users.  But since it's your call,
every bug report is in effect a question to you, "Do you want to fix this
problem I noticed?"  Yes/not-a-bug/wishlist/won't-fix...  Users
question/propose; you answer/dispose.

> so no I don't want to install such a patch.
> 
> > You apparently want a non-nil, non-t value to implicitly be 
> > considered unpredictable and unsupported ("you're on your
> > own"), for the benefit of "future compatibility", and you
> > apparently do not want to tell users that explicitly.  So be it.
> 
> Saying this explicitly everywhere we rely on it would be silly.
> It's a general rule that applies to all software I know.

But you just claimed that you don't even know if this is a place where you want
to rely on it - you said that you don't know the intention here.  Either you do
or you don't.  Either this is a place to rely on your general rule or it isn't.

You seem to be saying two contradictory things: 1) If info is missing then it's
intentional - don't bother to report it.  2) You don't know, in this case,
whether it is intentional or not.  (So how would a reader know?)

Apparently, we should not bother to point out when parameters to functions etc.
are undefined/undescribed.  We should just assume that the person who wrote the
doc left out such info intentionally, relying on the "general rule" to indicate
that "you're on your own" for anything that is missing or unclear.

That's one approach, I guess.  Your call.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@ORACLE.COM>
> Date: Tue, 15 Nov 2011 21:24:23 -0800
> Cc: 10057@debbugs.gnu.org
> 
> Apparently, we should not bother to point out when parameters to functions etc.
> are undefined/undescribed.

No.  "We" should of course report such potential omissions, but when
told that the maintainers don't want to spell that out in the doc,
"we" should accept their judgment, instead of raising the level of
flames and continuing the argument.

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

[Drew Adams]

> > Apparently, we should not bother to point out when 
> > parameters to functions etc. are undefined/undescribed.
> 
> No.  "We" should of course report such potential omissions,

Not according to Stefan's "general rule": According to that, omission indicates
clearly to everyone that that the behavior is unpredictable and unsupported.

> but when told that the maintainers don't want to spell that out
> in the doc, "we" should accept their judgment,

What judgment not to spell it out?  Was the bug classified won't-fix? wishlist?
not-a-bug?  Nope, not yet.  There was some disagreement and discussion about
what the doc omission might mean to readers, but there was also: Send a patch.
If someone wants to install, OK.  Install it yourself.

> instead of raising the level of flames and continuing the argument.

It was not I who made a mountain out of this tiny molehill of a bug.  It was a
trivial `t' -> `non-nil' substitution to make things clear.  Do it or don't do
it - your choice.

To me, making that change should be a no-brainer, but the suggestion
nevertheless engendered quite a lot of flak.  Including some that had nothing to
do with this bug in particular or even such doc omissions in general - ad
hominem comment about my participation in bug reporting and fixing bugs.

AFAICT, there was no decision not to make that change, and no decision to make
it.  There was discussion about what the omission (and such omissions generall)
can mean for readers.

And yes, there were some flames ("fun") - about my degree of involvement in
fixing bugs etc.  My end of the discussion has been limited to what it is we
want to tell users, and the effects that incomplete info can have (confuse
readers, make them wonder).

I've been clear that the choice about this proposed change is Stefan's to make,
obviously.  I have no problem with accepting whatever "judgment" might come.
Bug reporters only raise a question; the maintainers answer it: fix/won't fix
etc.

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

[Juri Linkov]

> If you need a patch to change `t' to `non-nil' then there is a problem.

Drew, it's so difficult to figure out from your documentation bug
reports what and how you actually want to fix, it would help greatly
if you submitted patches for documentation changes.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <monnier@iro.umontreal.ca>, <10057@debbugs.gnu.org>
> Date: Wed, 16 Nov 2011 06:52:29 -0800
> 
> > > Apparently, we should not bother to point out when 
> > > parameters to functions etc. are undefined/undescribed.
> > 
> > No.  "We" should of course report such potential omissions,
> 
> Not according to Stefan's "general rule": According to that, omission indicates
> clearly to everyone that that the behavior is unpredictable and unsupported.

That's a misrepresentation of what Stefan said.  But you already know
that.

> > instead of raising the level of flames and continuing the argument.
> 
> It was not I who made a mountain out of this tiny molehill [...]

I rest my case.

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

[Drew Adams]

> Drew, it's __so difficult__ to figure out from your documentation
> bug reports what and how you actually want to fix

It's a joke, right?  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.

As to "how" I would like it to be fixed, that really doesn't matter much, does
it?  It should be enough to point out the problem, especially in a trivial case
such as this.

In any case, I did say how I would like to see it fixed:

 >> Please state clearly and completely what NOERROR means.

However that might be done would be fine with me.  The "how" isn't important.

So far, we explain what a `nil' value means and what a `t' value means.  That's
clear as far as it goes, but it is not complete, which means that in the end it
is also not clear.

Singling out the particular non-nil value `t' this way leaves the reader
wondering.  Unless, that is, s?he assumes Stefan's general rule that anything
not mentioned is unpredictable and unsupported.

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

[Drew Adams]

> > Not according to Stefan's "general rule": According to 
> > that, omission indicates clearly to everyone that that
> > the behavior is unpredictable and unsupported.
> 
> That's a misrepresentation of what Stefan said. 

No, I don't think so:

>> You apparently want a non-nil, non-t value to implicitly be
>> considered unpredictable and unsupported ("you're on your own"),
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> for the benefit of "future compatibility", and you apparently
>> do not want to tell users that explicitly.
>
> Saying this explicitly everywhere we rely on it would be silly.
> It's a general rule that applies to all software I know.

What part of what he said does _not_ confirm that he claims that omission
implicitly indicates to readers that the behavior is unpredictable and
unsupported?

And again:

> Well, [the doc string] does say that if you use a non-nil
> and non-t value, you're on your own.

The doc string says nothing explicit about non-nil and non-t.
His claim is that it says this implicitly, by omission.

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

[Memnon Anon]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> You apparently want a non-nil, non-t value to implicitly be considered
>> unpredictable and unsupported ("you're on your own"), for the benefit
>> of "future compatibility", and you apparently do not want to tell
>> users that explicitly.  So be it.
>
> Saying this explicitly everywhere we rely on it would be silly.
> It's a general rule that applies to all software I know.

,----[ (info "(elisp)Documentation Tips") ]
|    * The documentation string for a variable that is a yes-or-no flag
|      should start with words such as "Non-nil means," to make it clear
!      that all non-`nil' values are equivalent and indicate explicitly
|      what `nil' and non-`nil' mean.
`----

How is this so much different?

The function checks for '(if noerror ...' , so "non-nil" matches what the
function actually does more precisely.

Future compatibility? The sentence in the docstring dates back to 2004,
for all versions since then, the test was always '(if noerror ...'.

When is this future to come?

If there were plans to differentiate 't' from other non-nil values, I 
think they got lost :). And it's not like the file is under heavy
development and an ever moving target, anyways ...

Whatever, this teeny tiny issue got way more attention than it deserved
in the first place I guess, so ... I'll stop now ;)

Memnon

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

[Juri Linkov]

> 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.  I'm not aware of other non-nil values you are talking about.

> 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".

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

[Eli Zaretskii]

> From: Memnon Anon <gegendosenfleisch@googlemail.com>
> Date: Wed, 16 Nov 2011 18:43:53 +0000 (UTC)
> 
> ,----[ (info "(elisp)Documentation Tips") ]
> |    * The documentation string for a variable that is a yes-or-no flag
> |      should start with words such as "Non-nil means," to make it clear
> !      that all non-`nil' values are equivalent and indicate explicitly
> |      what `nil' and non-`nil' mean.
> `----
> 
> How is this so much different?

It is different because it's not a yes-or-no flag.

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

[Drew Adams]

> > 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.

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

[Juri Linkov]

> 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.

There would be no such a clamor if you reported this bug saying
clearly and completely "Please change `t' to `non-nil'".
And the best way to achieve such clearness and completeness
of your requirements is by submitting a patch.