bug#13810: 24.3.50; Docstring of `newline' is confusing

[Stephen Berman]

On Mon, 25 Feb 2013 20:48:06 +0800 Xue Fuqiao <xfq.free@gmail.com> wrote:

> On Mon, 25 Feb 2013 13:23:14 +0100
> Stephen Berman <stephen.berman@gmx.net> wrote:
>
>> On Mon, 25 Feb 2013 18:03:09 +0800 Xue Fuqiao <xfq.free@gmail.com> wrote:
>> > In the doc string of the function `newline':
>> >   Insert a newline, and move to left margin of the new line if it's
>> >   blank.
>> > To reproduce this bug:
>> >
>> >    emacs -Q
>> >    M-<
>> >    M-: (newline) RET
>> > A new line appears, but the point doesn't move to left margin of the
>> > first line.  
>> I think you misread the doc string: point should -- and does -- move to
>> the left margin of the *new* line.
>
> You mean the *new* line is the second line (now)?

Yes; I think that's the only interpretation that makes sense when
newline is called at point-max, so for consistency it should be
interpreted that way everywhere.

>> Your report prompted me to check the code of newline and I think I found
>> a bug: a comment says, "If the newline leaves the previous line blank,
>> and we have a left margin, delete that from the blank line", but the
>> code only checks whether the previous line consists of a *single* space
>> or tab, so if there's more than one space or tab and the line is
>> otherwise blank, these won't be deleted.
>
> What does the "left margin" mean?  I'm a little confused here.  Does it mean
> the "margin" in the variable `left-margin-width'?

No, it's referring to (the result of setting) the variable left-margin,
which is different from left-margin-width.

> BTW there is another problem with the doc string of the function `newline'.
> The `auto-fill-function' in the doc string is somewhat ambiguous.  It is a
> Lisp function in simple.el, but it is also is a variable defined in buffer.c.

The doc string of newline says "Call `auto-fill-function'..."; you can
only call a function, not a variable (I suppose you can call a variable
something, but not just call it).

Steve Berman