GNU bug report logs - #21231
25.0.50; doc string of `marker-position'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21231 in the body.
You can then email your comments to 21231 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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: 25.0.50; doc string of `marker-position'
Date: Mon, 10 Aug 2015 08:48:24 -0700 (PDT)

The doc string is misleading or confusing.  Please follow what is said
in the Elisp manual.

The doc string says:

  Return the position MARKER points at, as a character number.

Character number?  What is that?  It either means nothing or it means
something we don't want to convey here: the integer value of a
character.

The Emacs way of talking about this is to refer to it as a "buffer
position".  It is a positive integer.

The manual just says "position".  If you want to add that it is a
positive integer, fine.

And it would be better if the first line indicated the nil possibility.
Something like:

 Return position of MARKER, or nil if it points nowhere.
 If a position, it is a positive integer.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm <at> gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 21231 <at> debbugs.gnu.org
Subject: Re: bug#21231: 25.0.50; doc string of `marker-position'
Date: Sun, 01 May 2016 00:03:55 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> The doc string is misleading or confusing.  Please follow what is said
> in the Elisp manual.
>
> The doc string says:
>
>   Return the position MARKER points at, as a character number.
>
> Character number?  What is that?  It either means nothing or it means
> something we don't want to convey here: the integer value of a
> character.
>
> The Emacs way of talking about this is to refer to it as a "buffer
> position".  It is a positive integer.
>
> The manual just says "position".  If you want to add that it is a
> positive integer, fine.
>
> And it would be better if the first line indicated the nil possibility.
> Something like:
>
>  Return position of MARKER, or nil if it points nowhere.
>  If a position, it is a positive integer.

I don't think the second sentence is necessary.  A "position" is clear
enough.  I've installed that on the trunk.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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