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

From: "Drew Adams" <[email-masked]>
Date: Tue, 15 Nov 2011 21:24:23 -0800

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