GNU bug report logs - #13810
24.3.50; Docstring of `newline' is confusing

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 13810 in the body.
You can then email your comments to 13810 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: Xue Fuqiao <xfq.free <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 18:03:09 +0800

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.  Maybe the doc string of this function should be improved.



In GNU Emacs 24.3.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.6.0)
 of 2013-02-24 on Emacs
Bzr revision: 111865 rgm <at> gnu.org-20130223220645-ym5xjdm8i09p2huy
Windowing system distributor `The X.Org Foundation', version 11.0.11300000
System Description:	Ubuntu 12.10

Configured using:
 `configure --config-cache --enable-link-time-optimization'

Important settings:
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<menu> e m - r e <tab> C-g <menu> r e - e m - b u <tab> 
<return>

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Quit

Load-path shadows:
None found.

Features:
(shadow sort gnus-util mail-extr emacsbug message format-spec rfc822 mml
easymenu mml-sec mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils time-date tooltip ediff-hook vc-hooks
lisp-float-type mwheel x-win x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces
cus-face macroexp files text-properties overlay sha1 md5 base64 format
env code-pages mule custom widget hashtable-print-readable backquote
make-network-process dbusbind inotify dynamic-setting
system-font-setting font-render-setting move-toolbar gtk x-toolkit x
multi-tty emacs)

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

Message #8 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Xue Fuqiao <xfq.free <at> gmail.com>
Cc: 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 13:23:14 +0100

On Mon, 25 Feb 2013 18:03:09 +0800 Xue Fuqiao <xfq.free <at> 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

Message #11 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Xue Fuqiao <xfq.free <at> gmail.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 20:48:06 +0800

On Mon, 25 Feb 2013 13:23:14 +0100
Stephen Berman <stephen.berman <at> gmx.net> wrote:

> On Mon, 25 Feb 2013 18:03:09 +0800 Xue Fuqiao <xfq.free <at> 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)?

> 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'?

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.

> Steve Berman

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

Message #14 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Xue Fuqiao <xfq.free <at> gmail.com>
Cc: 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 14:05:31 +0100

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

> On Mon, 25 Feb 2013 13:23:14 +0100
> Stephen Berman <stephen.berman <at> gmx.net> wrote:
>
>> On Mon, 25 Feb 2013 18:03:09 +0800 Xue Fuqiao <xfq.free <at> 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

Message #17 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Xue Fuqiao <xfq.free <at> gmail.com>
Cc: 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 14:18:59 +0100

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

> On Mon, 25 Feb 2013 13:23:14 +0100
> Stephen Berman <stephen.berman <at> gmx.net> wrote:
>
>> On Mon, 25 Feb 2013 18:03:09 +0800 Xue Fuqiao <xfq.free <at> 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)?

It just occurred to me that your confusion was probably due to thinking
of the newline character (C-j, line feed, "\n"), which is inserted at
the end of the line before the new line.  In the doc string the two
words "new line" unambiguously refer to the line after the inserted
newline character that results from calling newline, but the first word
"newline" should perhaps be replaced by "newline character" or "line
feed".

Steve Berman

Message #20 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Xue Fuqiao <xfq.free <at> gmail.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 21:27:42 +0800

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

> On Mon, 25 Feb 2013 20:48:06 +0800 Xue Fuqiao <xfq.free <at> gmail.com> wrote:
> > On Mon, 25 Feb 2013 13:23:14 +0100
> > Stephen Berman <stephen.berman <at> gmx.net> wrote:
> >> On Mon, 25 Feb 2013 18:03:09 +0800 Xue Fuqiao <xfq.free <at> 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

Message #23 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Xue Fuqiao <xfq.free <at> gmail.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 21:35:22 +0800

On Mon, 25 Feb 2013 14:18:59 +0100
Stephen Berman <stephen.berman <at> gmx.net> 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)?
> In the doc string the two
> words "new line" unambiguously refer to the line after the inserted
> newline character that results from calling newline, but the first word
> "newline" should perhaps be replaced by "newline character" or "line
> feed".

Sounds fine for me.

> Steve Berman

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

Message #26 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: Xue Fuqiao <xfq.free <at> gmail.com>, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 10:30:50 -0500

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

Yet, I think that newline doesn't call the `auto-fill-function'
function, but the function contained in the
`auto-fill-function' variable.


        Stefan

Message #29 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Xue Fuqiao <xfq.free <at> gmail.com>
Cc: stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 17:50:14 +0200

> Date: Mon, 25 Feb 2013 21:27:42 +0800
> From: Xue Fuqiao <xfq.free <at> gmail.com>
> Cc: 13810 <at> debbugs.gnu.org
> 
> > > 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?

The glossary is not the place where to look for all the possible
meanings of "margin".  Type "i margin RET" and see there; if it tells
you there are more than one hit, type comma ',' to walk through all of
them.

Message #32 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Xue Fuqiao <xfq.free <at> gmail.com>, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 25 Feb 2013 17:43:55 +0100

On Mon, 25 Feb 2013 10:30:50 -0500 Stefan Monnier <monnier <at> iro.umontreal.ca> wrote:

>> 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).
>
> Yet, I think that newline doesn't call the `auto-fill-function'
> function, but the function contained in the
> `auto-fill-function' variable.

Still, it doesn't "call the variable" ;-).  Anyway, isn't the potential
for confusion here rather limited, since the function auto-fill-function
is a noop just there for its doc string?

Steve Berman

Message #35 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Xue Fuqiao <xfq.free <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Tue, 26 Feb 2013 06:33:11 +0800

On Mon, 25 Feb 2013 17:50:14 +0200
Eli Zaretskii <eliz <at> gnu.org> wrote:

> The glossary is not the place where to look for all the possible
> meanings of "margin".

Why?  Because it has to be brief?

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

Message #38 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Xue Fuqiao <xfq.free <at> gmail.com>
Cc: stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Tue, 26 Feb 2013 05:46:44 +0200

> Date: Tue, 26 Feb 2013 06:33:11 +0800
> From: Xue Fuqiao <xfq.free <at> gmail.com>
> Cc: stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
> 
> On Mon, 25 Feb 2013 17:50:14 +0200
> Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> > The glossary is not the place where to look for all the possible
> > meanings of "margin".
> 
> Why?  Because it has to be brief?

Because it doesn't pretend to cover everything.

I do agree that it would be good in this particular case to add the
other meaning of "margin" to the glossary, though.

Message #41 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Xue Fuqiao <xfq.free <at> gmail.com>, stephen.berman <at> gmx.net,
 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Sat, 25 Jan 2020 16:39:37 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Tue, 26 Feb 2013 06:33:11 +0800
>> From: Xue Fuqiao <xfq.free <at> gmail.com>
>> Cc: stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
>> 
>> On Mon, 25 Feb 2013 17:50:14 +0200
>> Eli Zaretskii <eliz <at> gnu.org> wrote:
>> 
>> > The glossary is not the place where to look for all the possible
>> > meanings of "margin".
>> 
>> Why?  Because it has to be brief?
>
> Because it doesn't pretend to cover everything.
>
> I do agree that it would be good in this particular case to add the
> other meaning of "margin" to the glossary, though.

I'm not sure it's worth mentioning in this context to be honest.

One possibility would be to instead rename `left-margin' to something
like `indent-column' or `electric-indent-column' so we can get rid of
this terminological confusion altogether.

In my testing I'm also confused as to what the `left-margin' variable
is supposed to do.  I tried:

1. emacs -Q
2. M-x fundamental-mode
3. M-x set-variable RET left-margin RET 3 RET

Now `newline' (RET) does not indent to column 3.  However,
`electric-newline-and-maybe-indent' (C-j) does indent to that
column.  This seems to contradict the doc string of `left-margin',
which says "Linefeed indents to this column in Fundamental mode."

I also found some possibility for improving the doc string of
`newline', and propose the attached patch.  WDYT?

Best regards,
Stefan Kangas

[0001-Improve-doc-string-of-newline.patch (text/x-diff, inline)]

From 9b120aaa635b95bb19f3151f88f50fd04b4ac25c Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> gmail.com>
Date: Sat, 25 Jan 2020 16:21:06 +0100
Subject: [PATCH] Improve doc string of 'newline'

* lisp/simple.el (newline): Doc fix.  Move 'use-hard-newlines' down,
since it's less important than the meaning of the prefix argument, and
is less frequently used than 'electric-indent-mode' and
'auto-fill-mode'.  Change the wording to no longer call it an
option.  (Bug#13810)
---
 lisp/simple.el | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lisp/simple.el b/lisp/simple.el
index 8be27745b1..2ec3da680f 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -503,9 +503,7 @@ hard-newline
 
 (defun newline (&optional arg interactive)
   "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.
+With prefix argument ARG, insert that many newlines.
 
 If `electric-indent-mode' is enabled, this indents the final new line
 that it adds, and reindents the preceding line.  To just insert
@@ -514,6 +512,9 @@ newline
 If `auto-fill-mode' is enabled, this may cause automatic line
 breaking of the preceding line.  A non-nil ARG inhibits this.
 
+If `use-hard-newlines' is enabled, the newline is marked with the
+text-property `hard'.
+
 A non-nil INTERACTIVE argument means to run the `post-self-insert-hook'."
   (interactive "*P\np")
   (barf-if-buffer-read-only)
-- 
2.20.1

Message #44 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: xfq.free <at> gmail.com, stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Sat, 25 Jan 2020 19:20:59 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: Xue Fuqiao <xfq.free <at> gmail.com>,  stephen.berman <at> gmx.net,
>   13810 <at> debbugs.gnu.org
> Date: Sat, 25 Jan 2020 16:39:37 +0100
> 
> 1. emacs -Q
> 2. M-x fundamental-mode
> 3. M-x set-variable RET left-margin RET 3 RET
> 
> Now `newline' (RET) does not indent to column 3.  However,
> `electric-newline-and-maybe-indent' (C-j) does indent to that
> column.  This seems to contradict the doc string of `left-margin',
> which says "Linefeed indents to this column in Fundamental mode."

Linefeed is not RET, nor "newline".  It's C-j.

> I also found some possibility for improving the doc string of
> `newline', and propose the attached patch.  WDYT?

That's OK, but it's unrelated, isn't it?

Message #47 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: xfq.free <at> gmail.com, stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Sat, 25 Jan 2020 19:05:37 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> Linefeed is not RET, nor "newline".  It's C-j.

Where is this documented?  I can't find "linefeed" in the index of the
Emacs manual, nor in the glossary.

>> I also found some possibility for improving the doc string of
>> `newline', and propose the attached patch.  WDYT?
>
> That's OK, but it's unrelated, isn't it?

Yes, it's somewhat tangential.

Best regards,
Stefan Kangas

Message #50 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: xfq.free <at> gmail.com, stephen.berman <at> gmx.net, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Sat, 25 Jan 2020 20:29:53 +0200

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: xfq.free <at> gmail.com,  stephen.berman <at> gmx.net,  13810 <at> debbugs.gnu.org
> Date: Sat, 25 Jan 2020 19:05:37 +0100
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> > Linefeed is not RET, nor "newline".  It's C-j.
> 
> Where is this documented?

It's that character's official name, and supposed to be "common
knowledge".  Go to the end of any line in an Emacs buffer, and type
"C-u C-x =" -- Emacs will show the name of the character in the *Help*
buffer it pops up.

Message #53 received at 13810 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: Xue Fuqiao <xfq.free <at> gmail.com>, 13810 <at> debbugs.gnu.org
Subject: Re: bug#13810: 24.3.50; Docstring of `newline' is confusing
Date: Mon, 21 Sep 2020 16:35:56 +0200

Stephen Berman <stephen.berman <at> gmx.net> writes:

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

Thanks; I've now applied your patch to Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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