GNU bug report logs - #38183
26.3; Doc about equality of markers

Previous Next

Full log

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
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''

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.