--- Begin Message ---
|
Subject: |
26.3; Doc about equality of markers |
|
Date: |
Tue, 12 Nov 2019 11:03:20 -0800 (PST) |
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''
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#38183: 26.3; Doc about equality of markers |
|
Date: |
Fri, 15 Nov 2019 21:26:35 +0200 |
> Date: Fri, 15 Nov 2019 10:27:27 -0800 (PST)
> From: Drew Adams <address@hidden>
> Cc: address@hidden
>
> 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.
--- End Message ---