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

[Xue Fuqiao <xfq.free@gmail.com>]

On Mon, 25 Feb 2013 14:05:31 +0100
Stephen Berman <stephen.berman@gmx.net> wrote:

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

I see, thanks.

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

Ah, I see.  But in (info "(emacs) Glossary"), the term "margin" only contains
the meaning from `left-margin-width'.  Is it another bug?

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

1. The variable contains the *function* called to perform auto-fill;

2. In (info "(elisp) Documentation Tips"):

  However, when a symbol has both a function definition and a
  variable definition, and you want to refer to just one of them,
  you can specify which one by writing one of the words `variable',
  `option', `function', or `command', immediately before the symbol
  name.

However, I think most people know that the `auto-fill-function' here refers to
its function cell.  So it is a very minor problem.

> Steve Berman

-- 
Best regards, Xue Fuqiao.
http://www.emacswiki.org/emacs/XueFuqiao