unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#23067: 25.0.92; A detail in the doc of query-replace
@ 2016-03-20  2:02 Michael Heerdegen
  2016-03-20  2:14 ` Drew Adams
  2016-03-25 10:09 ` Eli Zaretskii
  0 siblings, 2 replies; 9+ messages in thread
From: Michael Heerdegen @ 2016-03-20  2:02 UTC (permalink / raw)
  To: 23067


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)






^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
  2016-03-20  2:02 bug#23067: 25.0.92; A detail in the doc of query-replace Michael Heerdegen
@ 2016-03-20  2:14 ` Drew Adams
  2016-03-25 10:09 ` Eli Zaretskii
  1 sibling, 0 replies; 9+ messages in thread
From: Drew Adams @ 2016-03-20  2:14 UTC (permalink / raw)
  To: Michael Heerdegen, 23067

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
  2016-03-20  2:02 bug#23067: 25.0.92; A detail in the doc of query-replace Michael Heerdegen
  2016-03-20  2:14 ` Drew Adams
@ 2016-03-25 10:09 ` Eli Zaretskii
  2016-03-26 22:06   ` John Wiegley
  1 sibling, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2016-03-25 10:09 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: 23067-done

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
       [not found] ` <<83k2kq27j0.fsf@gnu.org>
@ 2016-03-25 14:13   ` Drew Adams
  2016-03-25 14:23     ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2016-03-25 14:13 UTC (permalink / raw)
  To: Eli Zaretskii, Michael Heerdegen; +Cc: 23067-done

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
  2016-03-25 14:13   ` Drew Adams
@ 2016-03-25 14:23     ` Eli Zaretskii
  0 siblings, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2016-03-25 14:23 UTC (permalink / raw)
  To: Drew Adams; +Cc: michael_heerdegen, 23067

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
       [not found]     ` <<837fgq1vr4.fsf@gnu.org>
@ 2016-03-25 14:41       ` Drew Adams
  2016-03-25 15:55         ` Michael Heerdegen
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2016-03-25 14:41 UTC (permalink / raw)
  To: Eli Zaretskii, Drew Adams; +Cc: michael_heerdegen, 23067

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
  2016-03-25 14:41       ` Drew Adams
@ 2016-03-25 15:55         ` Michael Heerdegen
  2016-03-25 16:08           ` Drew Adams
  0 siblings, 1 reply; 9+ messages in thread
From: Michael Heerdegen @ 2016-03-25 15:55 UTC (permalink / raw)
  To: Drew Adams; +Cc: 23067

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.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
  2016-03-25 15:55         ` Michael Heerdegen
@ 2016-03-25 16:08           ` Drew Adams
  0 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2016-03-25 16:08 UTC (permalink / raw)
  To: Michael Heerdegen; +Cc: 23067

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#23067: 25.0.92; A detail in the doc of query-replace
  2016-03-25 10:09 ` Eli Zaretskii
@ 2016-03-26 22:06   ` John Wiegley
  0 siblings, 0 replies; 9+ messages in thread
From: John Wiegley @ 2016-03-26 22:06 UTC (permalink / raw)
  To: 23067; +Cc: michael_heerdegen

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2016-03-26 22:06 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-03-20  2:02 bug#23067: 25.0.92; A detail in the doc of query-replace Michael Heerdegen
2016-03-20  2:14 ` Drew Adams
2016-03-25 10:09 ` Eli Zaretskii
2016-03-26 22:06   ` John Wiegley
     [not found] <<87oaa9vrdz.fsf@web.de>
     [not found] ` <<83k2kq27j0.fsf@gnu.org>
2016-03-25 14:13   ` Drew Adams
2016-03-25 14:23     ` Eli Zaretskii
     [not found] <<<87oaa9vrdz.fsf@web.de>
     [not found] ` <<<83k2kq27j0.fsf@gnu.org>
     [not found]   ` <<42d06a78-824b-4661-aa84-845def8ca855@default>
     [not found]     ` <<837fgq1vr4.fsf@gnu.org>
2016-03-25 14:41       ` Drew Adams
2016-03-25 15:55         ` Michael Heerdegen
2016-03-25 16:08           ` Drew Adams

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).