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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Tue, 26 Feb 2013 06:33:11 +0800
>> From: Xue Fuqiao <xfq.free@gmail.com>
>> Cc: stephen.berman@gmx.net, 13810@debbugs.gnu.org
>> 
>> On Mon, 25 Feb 2013 17:50:14 +0200
>> Eli Zaretskii <eliz@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

>From 9b120aaa635b95bb19f3151f88f50fd04b4ac25c Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@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