GNU bug report logs - #12416
24.2; doc string of `line-beginning-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 12416 in the body.
You can then email your comments to 12416 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: 24.2; doc string of `line-beginning-position'
Date: Tue, 11 Sep 2012 08:41:36 -0700

This makes it sound like a value of 1 is some kind of exception:
 
 "With argument N not nil or 1, move forward N - 1 lines first."
 
Actually, 1 is treated like any other number N.
 
The exception is nil.  And to document that we should simply say that
the default value of N is 1.  That takes care of two places where we
talk about "if N is nil or 1".
 
IOW, this doc is unnecessarily complicated.
 
And it is misleading to say first that we "move forward" and then state,
at the very end, after details about behavior wrt fields, that the
function does NOT move point.  Just say something like this:
 
 Non-nil optional arg N means return the beginning position of the line
 N lines past the current line (before it if N is negative).
 
The doc is also overly complex in speaking of "the scan", which is
undefined and unexplained.
 
And please make clear what the blah-blah about "first character in the
logical order..." is all about.  If it means anything, then it is worth
explaining/describing.  So far, it is opaque, or at best, obscure.
 
Likewise, `line-end-position', of course.
 
In GNU Emacs 24.2.1 (i386-mingw-nt5.1.2600)
 of 2012-08-28 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

Message #10 received at 12416-done <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 12416-done <at> debbugs.gnu.org
Subject: Re: bug#12416: 24.2; doc string of `line-beginning-position'
Date: Sat, 22 Sep 2012 23:29:21 +0800

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

> This makes it sound like a value of 1 is some kind of exception:
>  
>  "With argument N not nil or 1, move forward N - 1 lines first."
>  
> Actually, 1 is treated like any other number N.
>  
> The exception is nil.  And to document that we should simply say that
> the default value of N is 1.  That takes care of two places where we
> talk about "if N is nil or 1".
>  
> IOW, this doc is unnecessarily complicated.

Fixed in trunk.

Previous Next

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