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

[Stephen Berman <stephen.berman@gmx.net>]

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.

>              Maybe the doc string of this function should be improved.

However, unless I'm misreading it, there is indeed room for improvement,
since point moves to the left margin of the new line whether or not it
is blank, so "if it's blank" is misleading and should be deleted.

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.  I doubt this asymmetry is
intended, so at least the following patch should be made:

=== modified file 'lisp/simple.el'
*** lisp/simple.el	2013-02-15 23:47:50 +0000
--- lisp/simple.el	2013-02-25 12:20:47 +0000
***************
*** 400,406 ****
    "Propertized string representing a hard newline character.")
  
  (defun newline (&optional arg)
!   "Insert a newline, and move to left margin of the new line if it's blank.
  If option `use-hard-newlines' is non-nil, the newline is marked with the
  text-property `hard'.
  With ARG, insert that many newlines.
--- 400,406 ----
    "Propertized string representing a hard newline character.")
  
  (defun newline (&optional arg)
!   "Insert a newline, and move to left margin of the new line.
  If option `use-hard-newlines' is non-nil, the newline is marked with the
  text-property `hard'.
  With ARG, insert that many newlines.
***************
*** 428,434 ****
              (save-excursion
                (goto-char beforepos)
                (beginning-of-line)
!               (and (looking-at "[ \t]$")
                     (> (current-left-margin) 0)
                     (delete-region (point)
                                    (line-end-position))))
--- 428,434 ----
              (save-excursion
                (goto-char beforepos)
                (beginning-of-line)
!               (and (looking-at "[ \t]+$")
                     (> (current-left-margin) 0)
                     (delete-region (point)
                                    (line-end-position))))



Actually, if we take the comment literally, the code should check that
the space left on the previous line has the length of left-margin, and
only in that case delete it.  But I think the comment doesn't really
intend that, but rather to delete any whitespace left on an otherwise
blank line, which the above patch does.

Steve Berman