Subject: 24.2; doc string of `line-beginning-position'

From: "Drew Adams" <[email-masked]>
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'