bug#11636: 23.1; wrong comment indentation

bug#11636: 23.1; wrong comment indentation

[Jack Duthen]

--text follows this line--

Please write in English if possible, because the Emacs maintainers
usually do not have translators to read other languages for them.

Your bug report will be posted to the bug-gnu-emacs@gnu.org mailing list,
and to the gnu.emacs.bug news group.

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

$ cat bug-comment-col.el
(defun jd-sh-ft-convert-logger_warn-into-COM_log ()
  (interactive)
  (query-replace-regexp
   (concat
    (jd-re-or "COM_writeLog 1")         ;
    (jd-re-paren
     "return ")                       ; \2 <msg> \n <spaces> "return "
    (jd-re-paren "[0-9]"))            ;
   "COM_log \\3\\2\\3"))

$ emacs -Q bug-comment-col.el
M-: comment-column RET => 40
M-< C-M-q  => the semicolons are not aligned

Is this a bug?


If Emacs crashed, and you have the Emacs process in the gdb debugger,
please include the output from the following gdb commands:
    `bt full' and `xbacktrace'.
If you would like to further debug the crash, please read the file
/usr/share/emacs/23.1/etc/DEBUG for instructions.


In GNU Emacs 23.1.1 (i686-pc-linux-gnu, GTK+ Version 2.22.0)
 of 2011-03-04 on roseapple, modified by Debian
Windowing system distributor `The X.Org Foundation', version 11.0.10900000
configured using `configure  '--build=i686-linux-gnu'
'--host=i686-linux-gnu' '--prefix=/usr' '--sharedstatedir=/var/lib'
'--libexecdir=/usr/lib' '--localstatedir=/var/lib'
'--infodir=/usr/share/info' '--mandir=/usr/share/man' '--with-pop=yes'
'--enable-locallisppath=/etc/emacs23:/etc/emacs:/usr/local/share/emacs/23.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/23.1/site-lisp:/usr/share/emacs/site-lisp:/usr/share/emacs/23.1/leim'
'--with-x=yes' '--with-x-toolkit=gtk' '--with-toolkit-scroll-bars'
'build_alias=i686-linux-gnu' 'host_alias=i686-linux-gnu'
'CFLAGS=-DDEBIAN -g -O2' 'LDFLAGS=-g' 'CPPFLAGS=''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: fr_FR.utf8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default-enable-multibyte-characters: t

Major mode: Emacs-Lisp

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

Recent input:
C-x C-f b u <tab> <return> C-M-q <down-mouse-1> <mouse-movement>
<mouse-movement> <drag-mouse-1> C-w C-M-a C-M-q C-x
C-s <down-mouse-1> <mouse-1> <double-down-mouse-1>
<double-mouse-1> <triple-down-mouse-1> <triple-mouse-1>
C-w C-M-a C-M-q <down-mouse-1> <mouse-1> <double-down-mouse-1>
<double-mouse-1> <triple-down-mouse-1> <triple-mouse-1>
C-w C-M-a C-M-q <down-mouse-1> <mouse-1> C-k C-M-a
C-M-q <down-mouse-1> <mouse-1> 1 C-_ C-_ C-k <backspace>
C-n C-n C-b C-b C-k C-n C-k C-M-a C-M-q C-_ C-_ C-M-a
C-M-q C-_ C-_ C-_ C-_ C-_ C-_ C-_ C-M-a C-M-q <down-mouse-1>
<mouse-1> C-k C-M-a C-M-q C-_ C-_ <down-mouse-1> <mouse-1>
<down-mouse-1> <mouse-1> C-k C-M-a C-M-q <down-mouse-1>
<mouse-1> C-f C-x C-s C-d C-M-a C-M-q C-_ C-_ C-f C-f
M-d C-d C-f C-f C-k x C-M-a C-M-q C-_ C-_ C-_ C-_ C-_
C-M-a C-M-q <down-mouse-1> <mouse-1> C-k C-M-a C-M-q
C-_ C-_ C-SPC C-b C-b C-b C-b C-b C-b C-b C-b C-b C-w
C-M-q C-M-a C-M-q C-_ C-_ SPC x x x x x x x x x x x
x x x x C-k C-M-a C-M-q C-_ C-_ C-_ <down-mouse-1>
<mouse-movement> <mouse-1> C-d C-M-a C-M-q <down-mouse-1>
<mouse-1> C-d C-M-a C-M-q C-_ C-_ C-_ C-_ C-f C-f C-f
C-f C-f C-f C-f C-f C-e C-b <backspace> C-M-a C-M-q
C-_ C-_ C-x C-s <down-mouse-1> <mouse-movement> <mouse-1>
C-d M-; <down-mouse-1> <mouse-1> <escape> SPC C-M-a
C-M-q C-_ C-_ C-_ C-_ C-M-a C-M-q M-: M-p c o m m e
n t - c o l <escape> <tab> <return> <down-mouse-1>
<mouse-1> C-a C-4 C-0 C-f C-M-a C-M-q <help-echo> <help-echo>
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo>
<help-echo> <help-echo> <help-echo> <menu-bar> <help-menu>
<send-emacs-bug-report>

Recent messages:
Mark set
Undo! [2 times]
(No changes need to be saved)
Mark set
Undo! [4 times]
Mark set
goto-history-element: Beginning of history; no preceding item
40 (#o50, #x28)
Mark set
/usr/bin/mail is not an executable.  Setting mail-interactive to t.

bug#11636: 23.1; wrong comment indentation

[Stefan Monnier]

>     (jd-re-or "COM_writeLog 1")         ;
>     (jd-re-paren
>      "return ")                       ; \2 <msg> \n <spaces> "return "
>     (jd-re-paren "[0-9]"))            ;
>    "COM_log \\3\\2\\3"))
[...]
> Is this a bug?

I don't think so:
- The second comment is not moved to the same column as the first
  because that would push the text past fill-column.  If you shorten the
  second comment or if you increase fill-column, then the 3 comments
  will be aligned.
- The first is not moved to the same column as the second because Emacs
  doesn't look past a non-commented line.  If you add a comment on the
  `jd-re-paren' line, then Emacs will look further and will align all
  4 comments.


        Stefan

bug#11636: 23.1; wrong comment indentation

[Jack Duthen]

Ok.  Many thanks for the explanation.
I made a mistake. (I'm sorry about that...)
So, I just read carefully the docs to understand what happened.

I didn't know `comment-dwim' (maybe it's new since emacs 14...)
and believed the action of M-; was just to insert or reindent
a comment past the right end of a normal code instruction,
but it seems to do much more.

The documentation of the function `comment-dwim' itself
does not refer to the behaviour of the variable `fill-column',
but it refers to the function `comment-indent',
whose documentation refers to the variable `comment-column',
whose documentation refers to the variable `comment-fill-column',
whose documentation refers to the variable `fill-column'.

So, yes, the documentation describes clearly (sic!)
the behaviour you reminded me in your answer!
(I should have RTFM! and apologize!)

Nevertheless there is no such reference in the Emacs info:
30.5 Manipulating Comments
and its sections (30.5.1 30.5.2 30.5.3):
* Comment Commands::    Inserting, killing, and aligning comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.

(though 30.5.2 refers to `auto-fill-mode' (which is not in use
in my example))

Also if you lookup-subject-in-emacs-manual or -in-elisp-manual
with comment-fill-column, you will find no reference to it.

Maybe there should be a word about it in §30.5.1 or §30.5.3 ?


2012/6/6 Stefan Monnier <monnier@iro.umontreal.ca>:
>>     (jd-re-or "COM_writeLog 1")         ;
>>     (jd-re-paren
>>      "return ")                       ; \2 <msg> \n <spaces> "return "
>>     (jd-re-paren "[0-9]"))            ;
>>    "COM_log \\3\\2\\3"))
> [...]
>> Is this a bug?
>
> I don't think so:
> - The second comment is not moved to the same column as the first
>  because that would push the text past fill-column.  If you shorten the
>  second comment or if you increase fill-column, then the 3 comments
>  will be aligned.
> - The first is not moved to the same column as the second because Emacs
>  doesn't look past a non-commented line.  If you add a comment on the
>  `jd-re-paren' line, then Emacs will look further and will align all
>  4 comments.
>
>        Stefan

bug#11636: 23.1; wrong comment indentation

[Noam Postavsky]

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

tags 11636 + patch
quit

Jack Duthen <duthen.mac.01@gmail.com> writes:

> Also if you lookup-subject-in-emacs-manual or -in-elisp-manual
> with comment-fill-column, you will find no reference to it.
>
> Maybe there should be a word about it in §30.5.1 or §30.5.3 ?

How about this:


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

From 8f455ca6dfe5361783bf3e897527816f558dd9c9 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Tue, 13 Feb 2018 22:10:03 -0500
Subject: [PATCH v1] 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 | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 4289124545..6c650a4ccf 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -989,7 +989,8 @@ Comment Commands
 @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
+specified by the variable @code{comment-column} while keeping the end
+of the comment within @code{comment-fill-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
@@ -1088,13 +1089,17 @@ 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 starting at
+the column specified by the buffer-local variable
+@code{comment-column} and ending before @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

bug#11636: 23.1; wrong comment indentation

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@users.sourceforge.net>
> Date: Tue, 13 Feb 2018 22:14:14 -0500
> Cc: 11636@debbugs.gnu.org, Stefan Monnier <monnier@iro.umontreal.ca>
> 
> Jack Duthen <duthen.mac.01@gmail.com> writes:
> 
> > Also if you lookup-subject-in-emacs-manual or -in-elisp-manual
> > with comment-fill-column, you will find no reference to it.
> >
> > Maybe there should be a word about it in §30.5.1 or §30.5.3 ?
> 
> How about this:

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

Thanks.

bug#11636: 23.1; wrong comment indentation

[Noam Postavsky]

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

bug#11636: 23.1; wrong comment indentation

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Cc: 11636@debbugs.gnu.org,  monnier@iro.umontreal.ca,  duthen.mac.01@gmail.com
> Date: Wed, 14 Feb 2018 20:36:50 -0500
> 
> 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?

Yes, much better, thanks.

bug#11636: 23.1; wrong comment indentation

[Noam Postavsky]

close 11636 26.1
quit

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?

> Yes, much better, thanks.

Pushed to emacs-26.

[1: 593bbdaf0b]: 2018-02-16 22:13:34 -0500
  Document comment-fill-column in the manual (Bug#11636)
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=593bbdaf0b890924e9d10918ba6de206bddc2eb6>