bug#23067: 25.0.92; A detail in the doc of query-replace

bug#23067: 25.0.92; A detail in the doc of query-replace

[Michael Heerdegen]

Hello,

"In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer."

I think the second sentence is confusing (wrong).  The command operates
up to `point-max'.


Thanks,

Michael.



In GNU Emacs 25.0.92.8 (x86_64-pc-linux-gnu, GTK+ Version 3.18.9)
 of 2016-03-19 built on drachen
Repository revision: 9ab03f27fad7b1ae68dda7a2effd075658dcf184
Windowing system distributor 'The X.Org Foundation', version 11.0.11802000
System Description:	Debian GNU/Linux testing (stretch)

bug#23067: 25.0.92; A detail in the doc of query-replace

[Drew Adams]

> "In Transient Mark mode, if the mark is active, operate on the contents
> of the region.  Otherwise, operate from point to the end of the buffer."
> 
> I think the second sentence is confusing (wrong).  The command operates
> up to `point-max'.

+1.  End of the buffer or its restriction, i.e., point-max.

bug#23067: 25.0.92; A detail in the doc of query-replace

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Sun, 20 Mar 2016 03:02:00 +0100
> 
> "In Transient Mark mode, if the mark is active, operate on the contents
> of the region.  Otherwise, operate from point to the end of the buffer."
> 
> I think the second sentence is confusing (wrong).  The command operates
> up to `point-max'.

Thanks.  I fixed the doc string of this function (and of a few others
in the same file).

However, I must say that it makes very little sense to me to make such
corrections only in a couple of functions, when we have gobs of them
with the same problem in the doc strings, so much so that I wonder
whether "end of buffer" isn't already a widely accepted synonym of
"end of the buffer's accessible portion", and we shouldn't bother,
certainly not with fixing that one function at a time.  I won't be
surprised if the same issue has crept in the manuals as well.

Please, let's not start another prolonged dispute that leads nowhere.
Instead, if someone really thinks this stuff should be spelled out in
documentation, that someone is kindly requested to submit a patch that
fixes _all_ of the instances where we don't say that explicitly.  TIA.

bug#23067: 25.0.92; A detail in the doc of query-replace

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> However, I must say that it makes very little sense to me to make such
> corrections only in a couple of functions, when we have gobs of them with
> the same problem in the doc strings, so much so that I wonder whether "end
> of buffer" isn't already a widely accepted synonym of "end of the buffer's
> accessible portion", and we shouldn't bother, certainly not with fixing that
> one function at a time. I won't be surprised if the same issue has crept in
> the manuals as well.

I agree, Eli. Why I applaud the desire for correctness, if something in our
documentation isn't actively producing user confusion, there is no pressing
need to be pedantic. I think "End of buffer" is colloquially understood to be
where M-> takes you, and I've never found myself troubled by the fact that, at
times, there might be more text after that point.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

bug#23067: 25.0.92; A detail in the doc of query-replace

[Drew Adams]

> > "In Transient Mark mode, if the mark is active, operate on the contents
> > of the region.  Otherwise, operate from point to the end of the buffer."
> >
> > I think the second sentence is confusing (wrong).  The command operates
> > up to `point-max'.
> 
> Thanks.  I fixed the doc string of this function (and of a few others
> in the same file).
> 
> However, I must say that it makes very little sense to me to make such
> corrections only in a couple of functions, when we have gobs of them
> with the same problem in the doc strings, so much so that I wonder
> whether "end of buffer" isn't already a widely accepted synonym of
> "end of the buffer's accessible portion", and we shouldn't bother,
> certainly not with fixing that one function at a time.  I won't be
> surprised if the same issue has crept in the manuals as well.
> 
> Please, let's not start another prolonged dispute that leads nowhere.
> Instead, if someone really thinks this stuff should be spelled out in
> documentation, that someone is kindly requested to submit a patch that
> fixes _all_ of the instances where we don't say that explicitly.  TIA.

There's another way to look at this that occurs to me.  It is also
perhaps not without some ambiguity, but it might nevertheless help.

"End of buffer" can be regarded as `point-max'.

This is what we say in the doc string of the predicate (`eobp') that
determines (tests for) end-of-buffer-ness:

 Return t if point is at the end of the buffer.
                         ^^^^^^^^^^^^^^^^^^^^^
 If the buffer is narrowed, this means the end of the narrowed part.
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Notice too that even though this is a predicate for Lisp, and you
would expect its doc to be aimed at Lisp programmers and not just
non-Lisper users, it does not mention `point-max'.

Again, yes, there is some perhaps inherent ambiguity in using the
term "end of the buffer" this way.  But it might help, in general.

bug#23067: 25.0.92; A detail in the doc of query-replace

[Eli Zaretskii]

> Date: Fri, 25 Mar 2016 07:13:48 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23067-done@debbugs.gnu.org
> 
> > However, I must say that it makes very little sense to me to make such
> > corrections only in a couple of functions, when we have gobs of them
> > with the same problem in the doc strings, so much so that I wonder
> > whether "end of buffer" isn't already a widely accepted synonym of
> > "end of the buffer's accessible portion", and we shouldn't bother,
> > certainly not with fixing that one function at a time.  I won't be
> > surprised if the same issue has crept in the manuals as well.
> > 
> > Please, let's not start another prolonged dispute that leads nowhere.
> > Instead, if someone really thinks this stuff should be spelled out in
> > documentation, that someone is kindly requested to submit a patch that
> > fixes _all_ of the instances where we don't say that explicitly.  TIA.
> 
> There's another way to look at this that occurs to me.  It is also
> perhaps not without some ambiguity, but it might nevertheless help.
> 
> "End of buffer" can be regarded as `point-max'.

What do you mean "can be"?  I was saying that it already is regarded
as such.

> This is what we say in the doc string of the predicate (`eobp') that
> determines (tests for) end-of-buffer-ness:
> 
>  Return t if point is at the end of the buffer.
>                          ^^^^^^^^^^^^^^^^^^^^^
>  If the buffer is narrowed, this means the end of the narrowed part.
>                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Are you saying we should change all the similar doc strings to say the
same?  If so, how is this different from what I said above, about the
need to change all of them?

bug#23067: 25.0.92; A detail in the doc of query-replace

[Drew Adams]

> > > However, I must say that it makes very little sense to me to make such
> > > corrections only in a couple of functions, when we have gobs of them
> > > with the same problem in the doc strings, so much so that I wonder
> > > whether "end of buffer" isn't already a widely accepted synonym of
> > > "end of the buffer's accessible portion", and we shouldn't bother,
> > > certainly not with fixing that one function at a time.  I won't be
> > > surprised if the same issue has crept in the manuals as well.
> > >
> > > Please, let's not start another prolonged dispute that leads nowhere.
> > > Instead, if someone really thinks this stuff should be spelled out in
> > > documentation, that someone is kindly requested to submit a patch that
> > > fixes _all_ of the instances where we don't say that explicitly.  TIA.
> >
> > There's another way to look at this that occurs to me.  It is also
> > perhaps not without some ambiguity, but it might nevertheless help.
> >
> > "End of buffer" can be regarded as `point-max'.
> 
> What do you mean "can be"?  I was saying that it already is regarded
> as such.

OK, "is", then.  I wrote "can be" because I think it can also be
regarded as the end of the buffer without regard to any possible
restriction.

I thought the point of this bug report was to distiguish end of
buffer in this sense from last buffer position without regard to
restriction.

If "end of buffer" is always understood as `point-max' then the
missing term is for the latter - the end of the buffer when any
restriction is ignored.

> > This is what we say in the doc string of the predicate (`eobp') that
> > determines (tests for) end-of-buffer-ness:
> >
> >  Return t if point is at the end of the buffer.
> >  If the buffer is narrowed, this means the end of the narrowed part.
> 
> Are you saying we should change all the similar doc strings to say the
> same?  If so, how is this different from what I said above, about the
> need to change all of them?

I'm not saying we should change all of anything.  I'm simply
pointing out that "end of buffer" really does sometimes (you might
say always) mean `point-max' - in particular, it does for the
description of `eobp'.  So changing "end of buffer" to text that
says `point-max' should not be necessary, if we are clear that
"end of buffer" means `point-max'.

But in that case, we will sometimes want to refer to the end of
the buffer without restriction.  AFAIK, we don't have a short
name for that.

And I believe we do sometimes say something like "the end of
the buffer, or the end of its accessible portion if it is
narrowed".

If we do say things like that then that gives credence to an
impression that "end of buffer" might not always mean
`point-max' (otherwise, we would not contrast it with a
description of the buffer end when there is a restriction).

bug#23067: 25.0.92; A detail in the doc of query-replace

[Michael Heerdegen]

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

> If we do say things like that then that gives credence to an
> impression that "end of buffer" might not always mean `point-max'
> (otherwise, we would not contrast it with a description of the buffer
> end when there is a restriction).

I don't think that "end-of-buffer" is such a good synonym for
`point-max'.

But OTOH, this is consistent with widely used functions as `eobp' and
`end-of-buffer'.  I didn't realize this when I created this report.

Since we will undoubtedly not rename these functions, it's best to leave
things as they are.  I still think it was not wrong to clear up things
in this special case, because to the user it could have made sense that
query-replace indeed would operate up to the real end of the buffer.


Thanks,

Michael.

bug#23067: 25.0.92; A detail in the doc of query-replace

[Drew Adams]

> > If we do say things like that then that gives credence to an
> > impression that "end of buffer" might not always mean `point-max'
> > (otherwise, we would not contrast it with a description of the buffer
> > end when there is a restriction).
> 
> I don't think that "end-of-buffer" is such a good synonym for
> `point-max'.
> 
> But OTOH, this is consistent with widely used functions as `eobp' and
> `end-of-buffer'.  I didn't realize this when I created this report.
> 
> Since we will undoubtedly not rename these functions, it's best to leave
> things as they are.  I still think it was not wrong to clear up things
> in this special case, because to the user it could have made sense that
> query-replace indeed would operate up to the real end of the buffer.

I agree that our doc should be clear about which is meant.  And I
think we might want to come up with a term for "the real end of the
buffer", as you put it, to make the distinction.  I don't have a
concreate suggestion at this point.  Sometimes the doc refers to
something like "end of the accessible portion of the buffer", but
that doesn't really help, if we also expect users to understand
"end of the buffer" as the same thing.

It was good to raise the issue generally.  Dunno what the best way
to deal with it is.