GNU bug report logs -
#38183
26.3; Doc about equality of markers
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Tue, 12 Nov 2019 19:04:01 UTC
Severity: normal
Found in version 26.3
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your message dated Fri, 15 Nov 2019 21:26:35 +0200
with message-id <83sgmp0wlw.fsf <at> gnu.org>
and subject line Re: bug#38183: 26.3; Doc about equality of markers
has caused the debbugs.gnu.org bug report #38183,
regarding 26.3; Doc about equality of markers
to be marked as done.
(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)
--
38183: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=38183
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
I think the doc about equality of markers should be improved.
In the Elisp manual:
Nodes `Equality Predicates' and `Overview of Markers' point out _one_
difference between `eq' and `equal', for markers. But in both of these
nodes the examples and explanations involve only markers for the same
buffer.
In node `Creating Markers' we finally find get the information that
`equal' requires the markers to also be for the same buffer. But again,
the examples there show only markers for the same buffer. There should
be an example with `equal' for markers with same numerical value but for
different buffers.
Node `Comparison of Numbers' tells us how to compare markers only with
respect to their numerical values, i.e., to ignore a buffer difference.
This info should be brought together, so that wherever we speak of
equality tests for markers we can learn that (1) `eq' requires the
markers to be identical (the same marker object), (2) `equal' requires
them to have the same numerical value and be for the same buffer, and
(3) `=' requires them to just have the same numerical value.
At the very least, all of that info should be available in one place, in
the section about markers. And it should include simple examples (like
now, but including `=' and the case of `equal' for two markers with the
same numerical value but for different buffers).
I think the info belongs in `Overview of Markers'. (But it could
logically be in `Predicates on Markers'.)
In particular, this is not something that's particular to `Creating
Markers'. IMO you could remove the examples of this kind of thing from
the description of `copy-marker'. But if duplication is OK then it's OK
to repeat it there. The point is that that shouldn't be the only place
to find this info.
In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.17763
Configured using:
`configure --without-dbus --host=x86_64-w64-mingw32
--without-compress-install 'CFLAGS=-O2 -static -g3''
[Message part 3 (message/rfc822, inline)]
> Date: Fri, 15 Nov 2019 10:27:27 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 38183 <at> debbugs.gnu.org
>
> Just know that as one user it took me a while
> to find the information.
>
> I started in the Markers section of the manual,
> and I had difficulty finding that `equal'
> includes buffer comparison (`equal' example
> uses only the same buffer).
"Overview of Markers" starts by saying what components are entailed in
a marker, so what 'equal' compares should be clear from that.
> Then, after finding that info, I had difficulty
> finding how to compare markers only numerically
> (nothing in the Markers section).
That's described under '='.
It is impractical to have every piece of information described
together in the same place as every other possibly related piece of
information, as that will lead to endless repetitions.
This bug report was last modified 5 years and 239 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.