bug#11636: 23.1; wrong comment indentation

[Noam Postavsky <npostavs@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 172 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> Sounds good, but could you please break those two longish sentences
> into 2, so that the text reads more easily?

Is this better?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 3054 bytes --]

From cc0349f11f9e45afcad696aed35d80dd3d3e5f70 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Tue, 13 Feb 2018 22:10:03 -0500
Subject: [PATCH v2] Document comment-fill-column in the manual (Bug#11636)

* doc/emacs/programs.texi (Comment Commands)
(Options for Comments): Mention comment-fill-column.
---
 doc/emacs/programs.texi | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 4289124545..7d54a99c09 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -988,13 +988,13 @@ Comment Commands
 characters), the comment is indented to the same position where
 @key{TAB} would indent to (@pxref{Basic Indent}).  If the line is
 non-blank, the comment is placed after the last non-whitespace
-character on the line; normally, Emacs tries putting it at the column
-specified by the variable @code{comment-column} (@pxref{Options for
-Comments}), but if the line already extends past that column, it puts
-the comment at some suitable position, usually separated from the
-non-comment text by at least one space.  In each case, Emacs places
-point after the comment's starting delimiter, so that you can start
-typing the comment text right away.
+character on the line.  Emacs tries to fit the comment between the
+columns specified by the variables @code{comment-column} and
+@code{comment-fill-column} (@pxref{Options for Comments}), if
+possible.  Otherwise, it will choose some other suitable position,
+usually separated from the non-comment text by at least one space.  In
+each case, Emacs places point after the comment's starting delimiter,
+so that you can start typing the comment text right away.
 
   You can also use @kbd{M-;} to align an existing comment.  If a line
 already contains the comment-start string, @kbd{M-;} realigns it to
@@ -1088,13 +1088,16 @@ Options for Comments
 @subsection Options Controlling Comments
 
 @vindex comment-column
+@vindex comment-fill-column
 @kindex C-x ;
 @findex comment-set-column
   As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
-adds a comment to a line, it tries to place the comment at the column
-specified by the buffer-local variable @code{comment-column}.  You can
-set either the local value or the default value of this buffer-local
-variable in the usual way (@pxref{Locals}).  Alternatively, you can
+adds a comment to a line, it tries to place the comment between the
+columns specified by the buffer-local variables @code{comment-column}
+and @code{comment-fill-column} (or if that is @code{nil}, then the
+value of @code{fill-column}, @pxref{Fill Commands}).  You can set
+either the local value or the default value of these buffer-local
+variables in the usual way (@pxref{Locals}).  Alternatively, you can
 type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
 @code{comment-column} in the current buffer to the column where point
 is currently located.  @kbd{C-u C-x ;} sets the comment column to
-- 
2.11.0