bug#38183: 26.3; Doc about equality of markers

bug#38183: 26.3; Doc about equality of markers

[Drew Adams]

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

bug#38183: 26.3; Doc about equality of markers

[Eli Zaretskii]

> Date: Tue, 12 Nov 2019 11:03:20 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> I think the doc about equality of markers should be improved.

I don't understand what are the practical problems caused by the
current text in the manual.  It seems the information you were after
is present, so it isn't clear what exactly is the problem here.

It seems that the only problem you have is the place where the details
of 'equal' for markers are described?

bug#38183: 26.3; Doc about equality of markers

[Drew Adams]

> > I think the doc about equality of markers should be improved.
> 
> I don't understand what are the practical problems caused by the
> current text in the manual.  It seems the information you were after
> is present, so it isn't clear what exactly is the problem here.
> 
> It seems that the only problem you have is the place where the details
> of 'equal' for markers are described?

I think the bug report is pretty clear, detailed, and
specific.  But to provide a quick summary response:

1. Yes, "Creating Markers" is not the best place for
   specifying equality tests between markers.

2. There should be an example for `equal' that shows
   inequality when the positions are the same but the
   buffers differ.

3. In the section about markers, there should be a
   mention of how to compare markers with regard only
   to their positions, i.e., use `='.

This, from the bug report, says what I think is needed,
as a minimum:

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

Please consider putting all of the info in the section
about markers, mentioning the different equality tests:
`eq', `equal', and `='.

bug#38183: 26.3; Doc about equality of markers

[Eli Zaretskii]

> Date: Fri, 15 Nov 2019 09:26:45 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 38183@debbugs.gnu.org
> 
> > > I think the doc about equality of markers should be improved.
> > 
> > I don't understand what are the practical problems caused by the
> > current text in the manual.  It seems the information you were after
> > is present, so it isn't clear what exactly is the problem here.
> > 
> > It seems that the only problem you have is the place where the details
> > of 'equal' for markers are described?
> 
> I think the bug report is pretty clear, detailed, and
> specific.  But to provide a quick summary response:

No need, I've read the original report.

It sounds like you missed the "practical" part of my questions above.
If you just disagree with where the information is now, then we can
agree to disagree.

> Please consider putting all of the info in the section
> about markers, mentioning the different equality tests:
> `eq', `equal', and `='.

I don't think this is needed.  The current text has all the info, and
the place where we have that is fine with me.

bug#38183: 26.3; Doc about equality of markers

[Drew Adams]

> The current text has all the info, and
> the place where we have that is fine with me.

It's your prerogative to do nothing.

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

Then, after finding that info, I had difficulty
finding how to compare markers only numerically
(nothing in the Markers section).

I now have the info.  Others - some anyway -
will likely go through the same obstacle
course.

bug#38183: 26.3; Doc about equality of markers

[Eli Zaretskii]

> Date: Fri, 15 Nov 2019 10:27:27 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 38183@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.