comment-add

comment-add

[Stephen Berman]

Since this change:

2007-09-17  Richard Stallman  <rms@gnu.org>

	* newcomment.el (comment-add): New arg EXTRA.
	(comment-region-default): Pass EXTRA if not indenting lines.

the docstring of the variable comment-add:

  How many more comment chars should be inserted by `comment-region'.
  This determines the default value of the numeric argument of `comment-region'.
  This should generally stay 0, except for a few modes like Lisp where
  it can be convenient to set it to 1 so that regions are commented with
  two semi-colons.
  
doesn't reflect the default behavior in Lisp mode, which is now to
comment regions with three semi-colons, given the default
comment-style 'plain.  If the default comment-style were changed to
'indent, then the doctring would (once again) be accurate.  If the
default comment-style is kept 'plain, the change in behavior should be
mentioned in NEWS.

In case anyone's tallying votes on this, I am in favor of making the
default comment-style 'indent.

Steve Berman

Re: comment-add

[David O'Toole]

Stephen Berman <Stephen.Berman@gmx.net> writes:

>   How many more comment chars should be inserted by
>   `comment-region'.  This determines the default value of the
>   numeric argument of `comment-region'.  This should generally stay
>   0, except for a few modes like Lisp where it can be convenient to
>   set it to 1 so that regions are commented with two semi-colons.
>   
> doesn't reflect the default behavior in Lisp mode, which is now to
> comment regions with three semi-colons, given the default
> comment-style 'plain.  If the default comment-style were changed to
> 'indent, then the doctring would (once again) be accurate.  If the
> default comment-style is kept 'plain, the change in behavior should
> be mentioned in NEWS.

I noticed the new default behavior and didn't like it---it turns every
line of the commented region into a headline matching outline-regexp
(and gets font-locked due to some snippets in my .emacs). Is this
really what was intended?

-- 
David O'Toole 
dto@gnu.org
http://dto.freeshell.org/notebook/

Re: comment-add

[Richard Stallman]

    I noticed the new default behavior and didn't like it---it turns every
    line of the commented region into a headline matching outline-regexp
    (and gets font-locked due to some snippets in my .emacs). Is this
    really what was intended?

That is a peculiar advanced usage mode, not a significant factor for a
decision about defaults.

Re: comment-add

[Tassilo Horn]

Richard Stallman <rms@gnu.org> writes:

>     I noticed the new default behavior and didn't like it---it turns
>     every line of the commented region into a headline matching
>     outline-regexp (and gets font-locked due to some snippets in my
>     .emacs). Is this really what was intended?
>
> That is a peculiar advanced usage mode, not a significant factor for a
> decision about defaults.

But the docs explicitly mention this "peculiar advanced usage mode".

,----[ (info "(elisp)Comment Tips") ]
| `;;;'
|      Comments that start with three semicolons, `;;;', should start at
|      the left margin.  These are used, occasionally, for comments within
|      functions that should start at the margin.  We also use them
|      sometimes for comments that are between functions--whether to use
|      two or three semicolons depends on whether the comment should be
|      considered a "heading" by Outline minor mode.  By default,
|      comments starting with at least three semicolons (followed by a
|      single space and a non-whitespace character) are considered
|      headings, comments starting with two or less are not.
| 
|      Another use for triple-semicolon comments is for commenting out
|      lines within a function.  We use three semicolons for this
|      precisely so that they remain at the left margin.  By default,
|      Outline minor mode does not consider a comment to be a heading
|      (even if it starts with at least three semicolons) if the
|      semicolons are followed by at least two spaces.  Thus, if you add
|      an introductory comment to the commented out code, make sure to
|      indent it by at least two spaces after the three semicolons.
| 
|           (defun foo (a)
|           ;;;  This is no longer necessary.
|           ;;;  (force-mode-line-update)
|             (message "Finished with %s" a))
| 
|      When commenting out entire functions, use two semicolons.
`----

Maybe we could all be happy if we change the new behavior to insert
three semicolons followed by two spaces?

Bye,
Tassilo

Re: comment-add

[Richard Stallman]

    Maybe we could all be happy if we change the new behavior to insert
    three semicolons followed by two spaces?

I finally had time to look at this.  The Lisp mode outline-regexp
matches three or more semicolons followed by one space
followed by something which is not space, tab or newline.

Can you show me a precise test case in which comment-dwim
produces lines that match this?

Re: comment-add

[Tassilo Horn]

Richard Stallman <rms@gnu.org> writes:

>     Maybe we could all be happy if we change the new behavior to
>     insert three semicolons followed by two spaces?
>
> I finally had time to look at this.  The Lisp mode outline-regexp
> matches three or more semicolons followed by one space followed by
> something which is not space, tab or newline.
>
> Can you show me a precise test case in which comment-dwim produces
> lines that match this?

If I comment text that starts at column 0 (a top-level sexp) like this

;;; (defun foo ()
;;;   (do-this)
;;;   (do-that)
;;;   (do-another-thing))

with comment-style set to indent-or-triple it results in the first line
being matched by outline-regexp.  With comment-style set to indent,
which inserts only two semicolons, this is not the case.  I don't know
if it's good to have commented top-level sexps as outline regexps.

comment-dwim for text that doesn't start in line 0 seems to always
produce comments that are not matched by outline-regexp, because the ;;;
is followed by more than one space.

Bye,
Tassilo

Re: comment-add

[Richard Stallman]

    If I comment text that starts at column 0 (a top-level sexp) like this

    ;;; (defun foo ()
    ;;;   (do-this)
    ;;;   (do-that)
    ;;;   (do-another-thing))

That text already consists of comments.

To help me reproduce the problem, could you please post a *precise*
test case for this bug?

The test case should start with `emacs -q', so that your .emacs file
does not affect it, and it should show exactly what text to put in the
buffer, what commands to execute, and how and where to click.  Also
please say exactly what incorrect results you get.

Re: comment-add

[Tassilo Horn]

Richard Stallman <rms@gnu.org> writes:

> To help me reproduce the problem, could you please post a *precise*
> test case for this bug?

1. emacs -Q

2. Goto buffer *scratch*

3. M-x outline-minor-mode

4. Insert:

(defun foo ()
  (do-this)
  (do-that)
  (do-another-thing))

The "(defun foo ()" is matched by outline-regexp.

5. Mark the whole function foo and do M-x comment-region.  This results
in:

;;; (defun foo ()
;;;   (do-this)
;;;   (do-that)
;;;   (do-another-thing))

Now the ";;; (defun foo ()" is still matched by outline-regexp.  That's
the difference between the new default comment-style `indent-or-triple'
and the old default `indent'.

> Also please say exactly what incorrect results you get.

I don't know if having differences in what commented text is matched by
outline-regexp qualifies as a bug, but ideally switching comment-style
shouldn't change that.  So the comment-style `indent-or-triple' should
ensure that ;;; is followed by more than one space if it starts at
column 0.

Bye,
Tassilo

Re: comment-add

[Richard Stallman]

Would someone please look at this bug, and ack?

From: Tassilo Horn <tassilo@member.fsf.org>
To: rms@gnu.org
Cc: dto@gnu.org,  emacs-devel@gnu.org
Subject: Re: comment-add
Mail-Followup-To: rms@gnu.org, dto@gnu.org, emacs-devel@gnu.org
Date: Tue, 11 Dec 2007 21:34:54 +0100
In-Reply-To: <E1J2ALR-0004Is-19@fencepost.gnu.org> (Richard Stallman's message
	of "Tue, 11 Dec 2007 14:00:41 -0500")
Message-ID: <87lk816kcx.fsf@member.fsf.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

Richard Stallman <rms@gnu.org> writes:

> To help me reproduce the problem, could you please post a *precise*
> test case for this bug?

1. emacs -Q

2. Goto buffer *scratch*

3. M-x outline-minor-mode

4. Insert:

(defun foo ()
  (do-this)
  (do-that)
  (do-another-thing))

The "(defun foo ()" is matched by outline-regexp.

5. Mark the whole function foo and do M-x comment-region.  This results
in:

;;; (defun foo ()
;;;   (do-this)
;;;   (do-that)
;;;   (do-another-thing))

Now the ";;; (defun foo ()" is still matched by outline-regexp.  That's
the difference between the new default comment-style `indent-or-triple'
and the old default `indent'.

> Also please say exactly what incorrect results you get.

I don't know if having differences in what commented text is matched by
outline-regexp qualifies as a bug, but ideally switching comment-style
shouldn't change that.  So the comment-style `indent-or-triple' should
ensure that ;;; is followed by more than one space if it starts at
column 0.

Bye,
Tassilo

Re: comment-add

[Stefan Monnier]

> In case anyone's tallying votes on this, I am in favor of making the
> default comment-style 'indent.

Richard likes his comments to start with ";;;" in column 0.
I wrote newcomment.el specifically to add the `indent' style, so obviously
I vote for the `indent' style, but I'm not sure if Richard wants to
entertain a vote.


        Stefan

Re: comment-add

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Tue, 25 Sep 2007 12:07:49 -0400
> Cc: emacs-devel@gnu.org
> 
> I'm not sure if Richard wants to entertain a vote.

A wise person once told me that a typical Free Software project is not
a democracy; it's more like a voluntary monarchy.

Re: comment-add

[Richard Stallman]

    In case anyone's tallying votes on this, I am in favor of making the
    default comment-style `indent'.

I am not deciding by votes between these two choices.

Re: comment-add

[Leo]

On 2007-09-25 18:57 +0100, Richard Stallman wrote:
>     In case anyone's tallying votes on this, I am in favor of making the
>     default comment-style `indent'.
>
> I am not deciding by votes between these two choices.

I also found 'indent the best choice. Actually I was very annoyed by the
default behavior when I was trying to comment out part of an XML file.

-- 
.:  Leo  :.  [ sdl.web AT gmail.com ]  .:  [ GPG Key: 9283AA3F ]  :.

       Use the most powerful email client -- http://gnus.org/