From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 28 Nov 2010 19:39:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 7509@debbugs.gnu.org X-Debbugs-Original-To: Received: via spool by submit@debbugs.gnu.org id=B.129097314122452 (code B ref -1); Sun, 28 Nov 2010 19:39:02 +0000 Received: (at submit) by debbugs.gnu.org; 28 Nov 2010 19:39:01 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMn5Q-0005q4-J5 for submit@debbugs.gnu.org; Sun, 28 Nov 2010 14:39:00 -0500 Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMn5P-0005pu-BP for submit@debbugs.gnu.org; Sun, 28 Nov 2010 14:38:59 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PMnAk-0001V3-2s for submit@debbugs.gnu.org; Sun, 28 Nov 2010 14:44:31 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_MED, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 Received: from lists.gnu.org ([199.232.76.165]:49646) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PMnAk-0001Ut-0c for submit@debbugs.gnu.org; Sun, 28 Nov 2010 14:44:30 -0500 Received: from [140.186.70.92] (port=37227 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PMnAi-0003PK-SR for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 14:44:29 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PMnAh-0001UG-Kw for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 14:44:28 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]:33778) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PMnAh-0001U3-DS for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 14:44:27 -0500 Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oASJiO8w005895 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sun, 28 Nov 2010 19:44:26 GMT Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oASJWEZ7004961 for ; Sun, 28 Nov 2010 19:44:24 GMT Received: from abhmt019.oracle.com by acsmt353.oracle.com with ESMTP id 819419021290973375; Sun, 28 Nov 2010 11:42:55 -0800 Received: from dradamslap1 (/10.159.220.140) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 28 Nov 2010 11:42:55 -0800 From: "Drew Adams" Date: Sun, 28 Nov 2010 11:42:46 -0800 Message-ID: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 Thread-Index: AcuPNG6LTHjmlZRcTaiWtPDCAP1yyA== X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) 1. User option `comment-style' should be documented in the Emacs manual. It is in neither that manual nor the Elisp manual. Don't bother to answer that not all options are described in the manual - your stock reply. This is a bug report about a _particular_ option's (lack of) doc. 2. The doc string of `comment-style' should explain what each of the possible values is/does. It should not refer you to the doc string for `comment-styles' (a defconst). The `comment-style' doc string should explain the values in a way that makes sense for `M-x customize-option custom-style', that is, not just with reference to the Lisp values but in terms of the `Value Menu' labels. Users of Customize should not just be sent to a defconst doc string that requires them to somehow map the `Value Menu' labels against the Lisp values. It is perfectly OK to _also_ say "see also `comment-style'. And the latter's doc string _should_ of course describe the Lisp values. 3. The doc string of `comment-styles' is anyway out of date. Not all of the values are described. This means that users trying to customize `comment-style' are lost. In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600) of 2010-11-22 on 3249CTO Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.4) --no-opt --cflags -Ic:/imagesupport/include' From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: Stefan Monnier Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 28 Nov 2010 20:56:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129097774729237 (code B ref 7509); Sun, 28 Nov 2010 20:56:02 +0000 Received: (at 7509) by debbugs.gnu.org; 28 Nov 2010 20:55:47 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMoHi-0007bW-J1 for submit@debbugs.gnu.org; Sun, 28 Nov 2010 15:55:47 -0500 Received: from chene.dit.umontreal.ca ([132.204.246.20]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMoHe-0007bI-8d for 7509@debbugs.gnu.org; Sun, 28 Nov 2010 15:55:43 -0500 Received: from pastel.home (lechon.iro.umontreal.ca [132.204.27.242]) by chene.dit.umontreal.ca (8.14.1/8.14.1) with ESMTP id oASL1CvW030278; Sun, 28 Nov 2010 16:01:12 -0500 Received: by pastel.home (Postfix, from userid 20848) id 786A6A85F1; Sun, 28 Nov 2010 16:01:11 -0500 (EST) From: Stefan Monnier Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Sun, 28 Nov 2010 16:01:11 -0500 In-Reply-To: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> (Drew Adams's message of "Sun, 28 Nov 2010 11:42:46 -0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 1 Rules triggered RV3693=0 X-Spam-Score: -1.9 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) > 1. User option `comment-style' should be documented in the Emacs manual. Indeed. It probably doesn't need to be in the Elisp manual, but the User manual should mention it. > 2. The doc string of `comment-style' should explain what each of the > possible values is/does. It should not refer you to the doc string for > `comment-styles' (a defconst). >From a modularity point of view, this is somewhat problematic. So I have philosophical problems with this, although I agree that the current docstring doesn't work well in Custom. Maybe a solution is to extend comment-styles so it includes a short docstring for each entry that can then be used for the label on each value in the "Value menu" of comment-style. > 3. The doc string of `comment-styles' is anyway out of date. Not all of > the values are described. This means that users trying to customize > `comment-style' are lost. I don't understand: the docstring of comment-styles (like all other variable docstrings) doesn't describe its current value, but rather what are its possible value(s) and what they mean. It seems to be just as up-to-date as when I originally wrote it (that part of the code hasn't changed since, AFAIK). Stefan From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 28 Nov 2010 22:30:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Stefan Monnier'" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.12909833964796 (code B ref 7509); Sun, 28 Nov 2010 22:30:03 +0000 Received: (at 7509) by debbugs.gnu.org; 28 Nov 2010 22:29:56 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMpkp-0001FJ-0M for submit@debbugs.gnu.org; Sun, 28 Nov 2010 17:29:55 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMpkn-0001F8-1a for 7509@debbugs.gnu.org; Sun, 28 Nov 2010 17:29:53 -0500 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oASMZNEJ029030 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 28 Nov 2010 22:35:24 GMT Received: from acsmt354.oracle.com (acsmt354.oracle.com [141.146.40.154]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oASMP91f027275; Sun, 28 Nov 2010 22:35:21 GMT Received: from abhmt019.oracle.com by acsmt354.oracle.com with ESMTP id 810544881290983655; Sun, 28 Nov 2010 14:34:15 -0800 Received: from dradamslap1 (/10.159.220.140) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 28 Nov 2010 14:34:15 -0800 From: "Drew Adams" References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Sun, 28 Nov 2010 14:34:05 -0800 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 Thread-Index: AcuPP2pXrRJLgVKnSyWiYj1n937sKQADD4ow X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) > > 2. The doc string of `comment-style' should explain what each of the > > possible values is/does. It should not refer you to the > > doc string for `comment-styles' (a defconst). > > From a modularity point of view, this is somewhat problematic. > So I have philosophical problems with this, Yes, I recognize that. It's a general problem. But some individual cases can be improved to some extent. But modularity is impacted, since we have two variables. It could be OK for one to refer to the other, but in this case one is a defcustom (so the values should be user-recognizable) and the other is a defconst (so the values need to be the Lisp symbols). > although I agree that the > current docstring doesn't work well in Custom. > > Maybe a solution is to extend comment-styles so it includes a short > docstring for each entry that can then be used for the label on each > value in the "Value menu" of comment-style. If that can be done so that updates work automatically, that would be good. IOW, I think you're saying that we would update the descriptions in only one place, and they would appear in both places. > > 3. The doc string of `comment-styles' is anyway out of > > date. Not all of the values are described. This means that > > users trying to customize `comment-style' are lost. > > I don't understand: the docstring of comment-styles (like all other > variable docstrings) doesn't describe its current value, but > rather what > are its possible value(s) and what they mean. It seems to be just as > up-to-date as when I originally wrote it (that part of the code hasn't > changed since, AFAIK). The possible values seem to include `box' and `box-multi' (at least I see those in the default alist value). Neither of those is described in the doc string. Comment region styles of the form (STYLE . (MULTI ALIGN EXTRA INDENT)). STYLE should be a mnemonic symbol. MULTI specifies that comments are allowed to span multiple lines. ALIGN specifies that the `comment-end' markers should be aligned. EXTRA specifies that an extra line should be used before and after the region to comment (to put the `comment-end' and `comment-start'). INDENT specifies that the `comment-start' markers should not be put at the left margin but at the current indentation of the region to comment. If INDENT is `multi-char', that means indent multi-character comment starters, but not one-character comment starters. Value: ((plain nil nil nil nil) (indent nil nil nil t) (indent-or-triple nil nil nil multi-char) (aligned nil t nil t) (multi-line t nil nil t) (extra-line t nil t t) (box nil t t t) ; <===================== (box-multi t t t t)) ; <================ From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 28 Nov 2010 22:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Stefan Monnier'" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.12909843676189 (code B ref 7509); Sun, 28 Nov 2010 22:47:01 +0000 Received: (at 7509) by debbugs.gnu.org; 28 Nov 2010 22:46:07 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMq0V-0001bm-2w for submit@debbugs.gnu.org; Sun, 28 Nov 2010 17:46:07 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMq0T-0001bJ-C8 for 7509@debbugs.gnu.org; Sun, 28 Nov 2010 17:46:05 -0500 Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oASMpaNY012758 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 28 Nov 2010 22:51:37 GMT Received: from acsmt354.oracle.com (acsmt354.oracle.com [141.146.40.154]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oASL1sn1008914; Sun, 28 Nov 2010 22:51:35 GMT Received: from abhmt021.oracle.com by acsmt354.oracle.com with ESMTP id 810554151290984579; Sun, 28 Nov 2010 14:49:39 -0800 Received: from dradamslap1 (/10.159.220.140) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 28 Nov 2010 14:49:39 -0800 From: "Drew Adams" References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Sun, 28 Nov 2010 14:49:30 -0800 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 Thread-Index: AcuPP2pXrRJLgVKnSyWiYj1n937sKQADD4owAAClX3A= X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) > > I don't understand: the docstring of comment-styles (like all other > > variable docstrings) doesn't describe its current value, but > > rather what are its possible value(s) and what they mean. It > > seems to be just as up-to-date as when I originally wrote it > > The possible values seem to include `box' and `box-multi' (at > least I see those in the default alist value). Neither of those > is described in the doc string. I was mistaken. I was interpreting the alist values wrt the labels in the menu for `comment-style'. I guess that all that's missing are descriptions of the latter. From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: Stefan Monnier Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 29 Nov 2010 01:34:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129099439820327 (code B ref 7509); Mon, 29 Nov 2010 01:34:02 +0000 Received: (at 7509) by debbugs.gnu.org; 29 Nov 2010 01:33:18 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMscH-0005Ho-DF for submit@debbugs.gnu.org; Sun, 28 Nov 2010 20:33:17 -0500 Received: from pruche.dit.umontreal.ca ([132.204.246.22]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PMscF-0005HV-JY for 7509@debbugs.gnu.org; Sun, 28 Nov 2010 20:33:15 -0500 Received: from pastel.home (lechon.iro.umontreal.ca [132.204.27.242]) by pruche.dit.umontreal.ca (8.14.1/8.14.1) with ESMTP id oAT1cffs008108; Sun, 28 Nov 2010 20:38:42 -0500 Received: by pastel.home (Postfix, from userid 20848) id 1E6AAA8761; Sun, 28 Nov 2010 20:38:41 -0500 (EST) From: Stefan Monnier Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Sun, 28 Nov 2010 20:38:41 -0500 In-Reply-To: (Drew Adams's message of "Sun, 28 Nov 2010 14:34:05 -0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 1 Rules triggered RV3693=0 X-Spam-Score: -1.9 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) > The possible values seem to include `box' and `box-multi' (at least > I see those in the default alist value). Neither of those is > described in the doc string. Neither are plain, indent, indent-or-triple, aligned, multi-line, and extra-line. Stefan From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: Stefan Monnier Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 30 Nov 2010 18:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.12911406055941 (code B ref 7509); Tue, 30 Nov 2010 18:11:02 +0000 Received: (at 7509) by debbugs.gnu.org; 30 Nov 2010 18:10:05 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNUeS-0001Xm-I8 for submit@debbugs.gnu.org; Tue, 30 Nov 2010 13:10:04 -0500 Received: from pruche.dit.umontreal.ca ([132.204.246.22]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNUeQ-0001XG-50 for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 13:10:02 -0500 Received: from pastel.home (lechon.iro.umontreal.ca [132.204.27.242]) by pruche.dit.umontreal.ca (8.14.1/8.14.1) with ESMTP id oAUIFaeB016919; Tue, 30 Nov 2010 13:15:37 -0500 Received: by pastel.home (Postfix, from userid 20848) id C667BA85ED; Tue, 30 Nov 2010 13:15:35 -0500 (EST) From: Stefan Monnier Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Tue, 30 Nov 2010 13:15:35 -0500 In-Reply-To: (Drew Adams's message of "Sun, 28 Nov 2010 14:49:30 -0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 1 Rules triggered RV3695=0 X-Spam-Score: -1.9 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) Can you try the patch below and tell us if it addresses your problem (I'm not that happy with the doc for some of those styles, so if you have suggestions for improvements, I'm all ears). Stefan === modified file 'lisp/newcomment.el' --- lisp/newcomment.el 2010-10-22 13:45:31 +0000 +++ lisp/newcomment.el 2010-11-29 18:26:11 +0000 @@ -187,16 +187,18 @@ it is 1 so that regions are commented with two or three semi-colons.") (defconst comment-styles - '((plain . (nil nil nil nil)) - (indent . (nil nil nil t)) + '((plain nil nil nil nil "Comment in column 0")) + (indent nil nil nil t "Indented as code")) (indent-or-triple - . (nil nil nil multi-char)) - (aligned . (nil t nil t)) - (multi-line . (t nil nil t)) - (extra-line . (t nil t t)) - (box . (nil t t t)) - (box-multi . (t t t t))) - "Comment region styles of the form (STYLE . (MULTI ALIGN EXTRA INDENT)). + nil nil nil multi-char "Indent only multi-char starters")) + (aligned nil t nil t "Indented and with closers aligned")) + (multi-line t nil nil t "Use multi-line comments")) + (extra-line t nil t t "Multi-line with starter&ender on their own line")) + (box nil t t t "Wrap comments in boxes")) + (box-multi t t t t "Boxes using multi-line comments"))) + "Comment region style definitions. +Each style is defined with a form (STYLE . (MULTI ALIGN EXTRA INDENT DOC)). +DOC should succinctly describe the style. STYLE should be a mnemonic symbol. MULTI specifies that comments are allowed to span multiple lines. ALIGN specifies that the `comment-end' markers should be aligned. @@ -210,7 +212,8 @@ (defcustom comment-style 'indent "Style to be used for `comment-region'. See `comment-styles' for a list of available styles." - :type `(choice ,@(mapcar (lambda (s) `(const ,(car s))) comment-styles)) + :type `(choice ,@(mapcar (lambda (s) `(const :tag ,(nth 5 s) ,(car s))) + comment-styles)) :version "23.1" :group 'comment) From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 30 Nov 2010 19:08:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Stefan Monnier'" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129114407110797 (code B ref 7509); Tue, 30 Nov 2010 19:08:02 +0000 Received: (at 7509) by debbugs.gnu.org; 30 Nov 2010 19:07:51 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNVYL-0002o6-CJ for submit@debbugs.gnu.org; Tue, 30 Nov 2010 14:07:49 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNVYJ-0002nu-Us for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 14:07:48 -0500 Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oAUJDN5O012519 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 30 Nov 2010 19:13:24 GMT Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oAUDEKSa019535; Tue, 30 Nov 2010 19:13:22 GMT Received: from abhmt010.oracle.com by acsmt354.oracle.com with ESMTP id 816627581291144384; Tue, 30 Nov 2010 11:13:04 -0800 Received: from dradamslap1 (/10.159.217.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 30 Nov 2010 11:13:04 -0800 From: "Drew Adams" References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Tue, 30 Nov 2010 11:13:03 -0800 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcuQup87Hy82oh2yR5WVIrvrMi0bEQAAnhTg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 In-Reply-To: X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) > Can you try the patch below and tell us if it addresses your problem > (I'm not that happy with the doc for some of those styles, so if you > have suggestions for improvements, I'm all ears). Thanks for working on this. I came across some variable definition weirdness (unrelated to this bug): I edited the code in another file (a copy), to apply the patch, then used C-M-x to redefine each var. In Customize for `comment-style' I clicked the link for `comment-styles', and it said the var is defined in `newcomment.el' (I evaled the new definition in a different file). And the doc was still the doc of the old definition. Also, the Customize buffer for `comment-style' said that the value was changed outside Customize (dunno if defining a defcustom should be considered that way, but whatever...). I clicked Restore to Standard Setting, and I got this error: (void-variable indent). From then on whenever I clicked the State button, instead of getting a State menu I got this: Debugger entered--Lisp error: (void-variable indent) eval(indent) (equal (eval (car cval)) (default-value symbol)) (not (equal (eval (car cval)) (default-value symbol))) (and cval (default-boundp symbol) (not (equal (eval (car cval)) (default-value symbol)))) (let* ((symbol (widget-get-tag-or-value widget))...) (lambda (widget) (let* ((symbol (widget-get-tag-or-value widget))...) custom-menu-filter((("Set for Current Session" custom-variable-set ...) custom-variable-action((custom-variable :documentation-shown t...) widget-apply((custom-variable :documentation-shown t...) widget-parent-action((custom-magic :args (nil) :parent (custom-variable...) widget-apply((custom-magic :args (nil) :parent (custom-variable...) widget-parent-action((choice-item :help-echo "Change the state of this item."...) widget-apply((choice-item :help-echo "Change the state of this item."...) widget-apply-action((choice-item :help-echo "Change the state of this item."...) byte-code("... I started over (emacs -Q)... Same thing, but this time I didn't restore to standard setting (so no error was raised). Seems there is something buggy about the Customize code or C-M-x or both. C-M-x on a defcustom or a defconst in file foo.el should not give a *Help* buffer that says that the var is defined in file bar.el, and it should not give the doc from a definition in bar.el. I tried (makunbound 'comment-style) and (makunbound 'comment-styles), then used `C-M-x' again. The `makunbound' calls worked OK (as shown by `boundp'). And C-h v then showed the correct doc strings. But it also still showed the wrong file name: "comment-styles is a variable defined in `newcomment.el'". So *Help* shows a doc string that is not even present in the file it mentions! What's the magic to competely undo a defcustom or defconst - `makunbound' doesn't seem to be enough. Anyway, back to this bug... The problem with my commenting on the description text is that I don't know what the various behaviors are, so I can't suggest doc improvements. Yes, that means that the current descriptions are inadequate, at least for me - I still have no clue what is meant. Can you please give me an example of each style, for a context/language appropriate to that style? Then I can try to suggest better one-liner descriptions. If the behavior is different depending on whether comment-end is nil, then give me an example of each behavior. Also, if a given style has no effect (or has the same effect as some other style) when comment-end is nil then the doc should say that. E.g., if `box-multi' is the same as `multi-line' (just a wild guess) for a language where there is no comment-end, then we should point this out somehow. The only style description I really understand is this one: "Comment in column 0". My (minor) suggestion here is to say "comment chars" or "comment beginning", not just "comment". In sum, for me to help here, you will need to give me more info about the styles. Don't try to word the descriptions; just give me a more verbose explanation/description - or examples. Then I'll suggest some descriptive text. Other than the particular text to be used, the patch (design) seems good to me. Another minor nit: "See `comment-styles' for a list..." should say "See `comment-styles' for the list...". It is precisely the same list as what is available here. HTH. From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: Stefan Monnier Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 30 Nov 2010 22:02:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129115446625330 (code B ref 7509); Tue, 30 Nov 2010 22:02:01 +0000 Received: (at 7509) by debbugs.gnu.org; 30 Nov 2010 22:01:06 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNYG2-0006aU-8P for submit@debbugs.gnu.org; Tue, 30 Nov 2010 17:01:06 -0500 Received: from chene.dit.umontreal.ca ([132.204.246.20]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNYG0-0006Zq-LE for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 17:01:05 -0500 Received: from faina.iro.umontreal.ca (lechon.iro.umontreal.ca [132.204.27.242]) by chene.dit.umontreal.ca (8.14.1/8.14.1) with ESMTP id oAUM6OKo010672; Tue, 30 Nov 2010 17:06:24 -0500 Received: by faina.iro.umontreal.ca (Postfix, from userid 20848) id 91877B4154; Tue, 30 Nov 2010 17:06:23 -0500 (EST) From: Stefan Monnier Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Tue, 30 Nov 2010 17:06:23 -0500 In-Reply-To: (Drew Adams's message of "Tue, 30 Nov 2010 11:13:03 -0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 1 Rules triggered RV3695=0 X-Spam-Score: -1.9 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) > I came across some variable definition weirdness (unrelated to this > bug): I must say I have no idea how you got into such a mess. My only explanation would be that some part of the patch did not apply properly. > Seems there is something buggy about the Customize code or C-M-x or > both. C-M-x on a defcustom or a defconst in file foo.el should not > give a *Help* buffer that says that the var is defined in file bar.el, > and it should not give the doc from a definition in bar.el. AFAIK, none of those things occur in my usage. > What's the magic to competely undo a defcustom or defconst - `makunbound' > doesn't seem to be enough. There's no such magic. > Can you please give me an example of each style, for > a context/language appropriate to that style? Then I can try to > suggest better one-liner descriptions. If the behavior is different > depending on whether comment-end is nil, then give me an example of > each behavior. >From memory: feel free to test them in a C-mode buffer. plain: /* blabla */ /* bla */ indent /* blabla */ /* bla */ multi-line /* blabla * bla */ extra-line /* * blabla * bla */ aligned /* blabla */ /* bla */ box /**********/ /* blabla */ /* bla */ /**********/ box-multi /********** * blabla * * bla * **********/ When comment-end is the empty string, indent=multi-line=extra-line=aligned and box=box-multi. Stefan From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 30 Nov 2010 22:32:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Stefan Monnier'" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129115630827911 (code B ref 7509); Tue, 30 Nov 2010 22:32:02 +0000 Received: (at 7509) by debbugs.gnu.org; 30 Nov 2010 22:31:48 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNYjj-0007G8-Cn for submit@debbugs.gnu.org; Tue, 30 Nov 2010 17:31:47 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNYjh-0007Fw-5k for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 17:31:45 -0500 Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oAUMbKxo028153 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 30 Nov 2010 22:37:22 GMT Received: from acsmt353.oracle.com (acsmt353.oracle.com [141.146.40.153]) by acsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oAUBucOP027936; Tue, 30 Nov 2010 22:37:19 GMT Received: from abhmt004.oracle.com by acsmt353.oracle.com with ESMTP id 828862081291156601; Tue, 30 Nov 2010 14:36:41 -0800 Received: from dradamslap1 (/10.159.217.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 30 Nov 2010 14:36:41 -0800 From: "Drew Adams" References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> Date: Tue, 30 Nov 2010 14:36:41 -0800 Message-ID: <27E6B536A09248629C372671995E7E97@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcuQ2vK+868ZSwtfRMK4wQAx7gV50gAAE0jA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 In-Reply-To: X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) > > I came across some variable definition weirdness (unrelated to this > > bug): > > I must say I have no idea how you got into such a mess. My only > explanation would be that some part of the patch did not > apply properly. No, I did not mean to suggest that this had anything to do with your patch. (And I just "applied" the patch by hand editing.) > AFAIK, none of those things occur in my usage. I won't worry about it. If I have time I'll report it. I don't have the time now. > > What's the magic to competely undo a defcustom or defconst > > - `makunbound' doesn't seem to be enough. > > There's no such magic. Are you saying that `makunbound' should take care of it? It's pretty easy to see at least some of the problems, I think. Put these in different files: (defcustom foo 1 "The first definition" :type 'integer) (defcustom foo 2 "The second definition" :type 'integer) Then eval the first, then the second, then maybe the first again, using C-M-x. Use C-h v and see if you don't see at least the wrong file name mentioned at some points. I do right away, using the latest Windows binary (built today by Sean) and emacs -Q. But all this is outside of bug #7509. I didn't mean to suggest it had anything to do with your patch. > From memory: feel free to test them in a C-mode buffer. I'll go by your memory. Someone can correct them later if your memory isn't perfect. > plain: > /* blabla */ > /* bla */ > > indent > /* blabla */ > /* bla */ > > multi-line > /* blabla > * bla */ > > extra-line > /* > * blabla > * bla > */ > > aligned > /* blabla */ > /* bla */ > > box > /**********/ > /* blabla */ > /* bla */ > /**********/ > > box-multi > /********** > * blabla * > * bla * > **********/ > > When comment-end is the empty string, > indent=multi-line=extra-line=aligned and box=box-multi. Thanks. That helps a lot. Below are some suggestions. Also, it wouldn't hurt to include such tiny diagrams in the doc string for `comment-styles' (esp. since it is a defconst). In this case, a set of pictures is worth more than a set of one-liner descriptions. BTW, why are all of the various possibilities (align, extra, box etc.) defined only for indented comments? plain - Start in column 0 (do not indent) indent - Full comment per line, ends not aligned aligned - Full comment per line, ends aligned box - Full comment per line, ends aligned, + top and bottom extra-line - One comment for all lines, end on a line by itself multi-line - One comment for all lines, end on last commented line box-multi - One comment for all lines, + top and bottom And the descriptions make more sense if presented in this order, IMO. The doc string for `comment-styles' can also point out: 1. That all except for `plain' indent the comment to the current indent level. 2. That when `comment-end' is empty... Those general rules help understanding and recollection. HTH. From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: Stefan Monnier Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 01 Dec 2010 02:52:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129117189516853 (code B ref 7509); Wed, 01 Dec 2010 02:52:02 +0000 Received: (at 7509) by debbugs.gnu.org; 1 Dec 2010 02:51:35 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNcn8-0004Nm-59 for submit@debbugs.gnu.org; Tue, 30 Nov 2010 21:51:34 -0500 Received: from ironport2-out.teksavvy.com ([206.248.154.183] helo=ironport2-out.pppoe.ca) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNcn5-0004Na-AB for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 21:51:32 -0500 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvcIABlI9UxMCqFw/2dsb2JhbACDUJ46gQRyswqQb4EhgzNzBIRcOI03 X-IronPort-AV: E=Sophos;i="4.59,282,1288584000"; d="scan'208";a="84189887" Received: from 76-10-161-112.dsl.teksavvy.com (HELO ceviche.home) ([76.10.161.112]) by ironport2-out.pppoe.ca with ESMTP/TLS/ADH-AES256-SHA; 30 Nov 2010 21:57:08 -0500 Received: by ceviche.home (Postfix, from userid 20848) id 42FF3660DC; Tue, 30 Nov 2010 21:57:08 -0500 (EST) From: Stefan Monnier Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> <27E6B536A09248629C372671995E7E97@us.oracle.com> Date: Tue, 30 Nov 2010 21:57:08 -0500 In-Reply-To: <27E6B536A09248629C372671995E7E97@us.oracle.com> (Drew Adams's message of "Tue, 30 Nov 2010 14:36:41 -0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.1 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.1 (--) >> There's no such magic. > Are you saying that `makunbound' should take care of it? No. I'm saying that there is no known trick to undo a defcustom. > Also, it wouldn't hurt to include such tiny diagrams in the doc string > for `comment-styles' (esp. since it is a defconst). In this case, > a set of pictures is worth more than a set of one-liner descriptions. Again, that would amount to documenting the particular current value of that variable, rather than the set of possible values and their meaning. So that would be wrong. Such documentation can't belong to comment-styles's docstring; only to the doc of each style defined there. > BTW, why are all of the various possibilities (align, extra, box etc.) > defined only for indented comments? The only reason `plain' exists is because that's what was used in Emacs=E2=89=A422. I strongly discourage people from using it since it often results in comments that aren't properly indented. > plain - Start in column 0 (do not indent) > indent - Full comment per line, ends not aligned > aligned - Full comment per line, ends aligned > box - Full comment per line, ends aligned, + top and bottom > extra-line - One comment for all lines, end on a line by itself > multi-line - One comment for all lines, end on last commented line > box-multi - One comment for all lines, + top and bottom Thanks, that seems much better than what I have now. Stefan From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 01 Dec 2010 04:07:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Stefan Monnier'" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129117641623231 (code B ref 7509); Wed, 01 Dec 2010 04:07:01 +0000 Received: (at 7509) by debbugs.gnu.org; 1 Dec 2010 04:06:56 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNdy3-00062e-SN for submit@debbugs.gnu.org; Tue, 30 Nov 2010 23:06:56 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1PNdy1-00062R-N1 for 7509@debbugs.gnu.org; Tue, 30 Nov 2010 23:06:54 -0500 Received: from rcsinet13.oracle.com (rcsinet13.oracle.com [148.87.113.125]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oB14CTIG005501 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Wed, 1 Dec 2010 04:12:30 GMT Received: from acsmt355.oracle.com (acsmt355.oracle.com [141.146.40.155]) by rcsinet13.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oB14C4d7019760; Wed, 1 Dec 2010 04:12:04 GMT Received: from abhmt006.oracle.com by acsmt354.oracle.com with ESMTP id 829726541291176635; Tue, 30 Nov 2010 20:10:35 -0800 Received: from dradamslap1 (/10.159.216.81) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 30 Nov 2010 20:10:34 -0800 From: "Drew Adams" References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com><27E6B536A09248629C372671995E7E97@us.oracle.com> Date: Tue, 30 Nov 2010 20:10:36 -0800 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: AcuRA3QpXinHB3TlTV2fzRxb7y44OwACAGQg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) > > Also, it wouldn't hurt to include such tiny diagrams in the > > doc string for `comment-styles' (esp. since it is a defconst). > > In this case, a set of pictures is worth more than a set of > > one-liner descriptions. > > Again, that would amount to documenting the particular > current value of that variable, rather than the set of > possible values and their meaning. No, we would be documenting the _default_ value. Nothing wrong with that. It serves as a model, a particular value, yes, but also a good example. And the value that defines the behavior (the possibilities) out of the box - good to know. Both understanding the default behavior/value and having it as a model are useful. > So that would be wrong. Such documentation can't belong to > comment-styles's docstring; only to the doc of each style > defined there. Either nothing is defined there (it's just one possible value, as you point out) or everything is defined there (it's the default value, defining all the behavior possibilities you get if you don't change anything). You cannot have it both ways. ;-) I'd say that we should describe the default value in the doc string (and not just inside the value itself), because I think that will help users. The doc string just needs to make clear that this description applies to the _default value_, which serves as _an example_. No matter how good the one-liner descriptions we might come up with, they are no match for the little samples you sent me. Once you see them it's all clear, but until then a reader is really only guessing. IMO. > > BTW, why are all of the various possibilities (align, > > extra, box etc.) defined only for indented comments? > > The only reason `plain' exists is because that's what was used in > Emacs=22. I strongly discourage people from using it since it often > results in comments that aren't properly indented. I strongly prefer `plain'. ;-) But I don't program in C. And I don't pretend to speak for anyone but myself. > > plain - Start in column 0 (do not indent) > > indent - Full comment per line, ends not aligned > > aligned - Full comment per line, ends aligned > > box - Full comment per line, ends aligned, + top and bottom > > extra-line - One comment for all lines, end on a line by itself > > multi-line - One comment for all lines, end on last commented line > > box-multi - One comment for all lines, + top and bottom > > Thanks, that seems much better than what I have now. You're welcome. Thanks for making the changes. From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: Stefan Monnier Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 03 Dec 2010 23:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "Drew Adams" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129141784422599 (code B ref 7509); Fri, 03 Dec 2010 23:11:02 +0000 Received: (at 7509) by debbugs.gnu.org; 3 Dec 2010 23:10:44 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1POem4-0005sS-5A for submit@debbugs.gnu.org; Fri, 03 Dec 2010 18:10:44 -0500 Received: from chene.dit.umontreal.ca ([132.204.246.20]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1POem2-0005sF-55 for 7509@debbugs.gnu.org; Fri, 03 Dec 2010 18:10:42 -0500 Received: from pastel.home (lechon.iro.umontreal.ca [132.204.27.242]) by chene.dit.umontreal.ca (8.14.1/8.14.1) with ESMTP id oB3NGPCM004371; Fri, 3 Dec 2010 18:16:25 -0500 Received: by pastel.home (Postfix, from userid 20848) id BBBE3A8364; Fri, 3 Dec 2010 18:16:24 -0500 (EST) From: Stefan Monnier Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> <27E6B536A09248629C372671995E7E97@us.oracle.com> Date: Fri, 03 Dec 2010 18:16:24 -0500 In-Reply-To: (Drew Adams's message of "Tue, 30 Nov 2010 20:10:36 -0800") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 1 Rules triggered RV3698=0 X-Spam-Score: -1.9 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -1.9 (-) > You're welcome. Thanks for making the changes. I've installed the patch below, which I hope addresses your concerns without offending my sense of modularity. Stefan --- lisp/newcomment.el 2010-10-21 20:12:38 +0000 +++ lisp/newcomment.el 2010-12-03 23:11:10 +0000 @@ -187,21 +187,58 @@ it is 1 so that regions are commented with two or three semi-colons.") (defconst comment-styles - '((plain . (nil nil nil nil)) - (indent . (nil nil nil t)) - (indent-or-triple - . (nil nil nil multi-char)) - (aligned . (nil t nil t)) - (multi-line . (t nil nil t)) - (extra-line . (t nil t t)) - (box . (nil t t t)) - (box-multi . (t t t t))) - "Comment region styles of the form (STYLE . (MULTI ALIGN EXTRA INDENT)). + '((plain nil nil nil nil + "Start in column 0 (do not indent), as in Emacs-20") + (indent-or-triple nil nil nil multi-char + "Start in column 0, but only for single-char starters") + (indent nil nil nil t + "Full comment per line, ends not aligned") + (aligned nil t nil t + "Full comment per line, ends aligned") + (box nil t t t + "Full comment per line, ends aligned, + top and bottom") + (extra-line t nil t t + "One comment for all lines, end on a line by itself") + (multi-line t nil nil t + "One comment for all lines, end on last commented line") + (box-multi t t t t + "One comment for all lines, + top and bottom")) + "Comment region style definitions. +Each style is defined with a form (STYLE . (MULTI ALIGN EXTRA INDENT DOC)). +DOC should succinctly describe the style. STYLE should be a mnemonic symbol. MULTI specifies that comments are allowed to span multiple lines. + e.g. in C it comments regions as + /* blabla + * bli */ + rather than + /* blabla */ + /* bli */ + if `comment-end' is empty, this has no effect. + ALIGN specifies that the `comment-end' markers should be aligned. + e.g. in C it comments regions as + /* blabla */ + /* bli */ + rather than + /* blabla */ + /* bli */ + if `comment-end' is empty, this has no effect, unless EXTRA is also set, + in which case the comment gets wrapped in a box. + EXTRA specifies that an extra line should be used before and after the region to comment (to put the `comment-end' and `comment-start'). + e.g. in C it comments regions as + /* + * blabla + * bli + */ + rather than + /* blabla + * bli */ + if the comment style is not multi line, this has no effect, unless ALIGN + is also set, in which case the comment gets wrapped in a box. + INDENT specifies that the `comment-start' markers should not be put at the left margin but at the current indentation of the region to comment. If INDENT is `multi-char', that means indent multi-character @@ -212,7 +249,10 @@ "Style to be used for `comment-region'. See `comment-styles' for a list of available styles." :type (if (boundp 'comment-styles) - `(choice ,@(mapcar (lambda (s) `(const ,(car s))) + `(choice + ,@(mapcar (lambda (s) + `(const :tag ,(format "%s: %s" (car s) (nth 5 s)) + ,(car s))) comment-styles)) 'symbol) :version "23.1" From unknown Sat Jun 21 03:17:40 2025 X-Loop: help-debbugs@gnu.org Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 03 Dec 2010 23:29:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7509 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: "'Stefan Monnier'" Cc: 7509@debbugs.gnu.org Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129141892424069 (code B ref 7509); Fri, 03 Dec 2010 23:29:01 +0000 Received: (at 7509) by debbugs.gnu.org; 3 Dec 2010 23:28:44 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1POf3U-0006GA-MZ for submit@debbugs.gnu.org; Fri, 03 Dec 2010 18:28:44 -0500 Received: from rcsinet10.oracle.com ([148.87.113.121]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1POf3S-0006Fy-Vk for 7509@debbugs.gnu.org; Fri, 03 Dec 2010 18:28:43 -0500 Received: from rcsinet15.oracle.com (rcsinet15.oracle.com [148.87.113.117]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id oB3NYQsX007068 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Fri, 3 Dec 2010 23:34:27 GMT Received: from acsmt354.oracle.com (acsmt354.oracle.com [141.146.40.154]) by rcsinet15.oracle.com (Switch-3.4.2/Switch-3.4.1) with ESMTP id oB3EmCJ2016722; Fri, 3 Dec 2010 23:34:26 GMT Received: from abhmt007.oracle.com by acsmt354.oracle.com with ESMTP id 843194171291419243; Fri, 03 Dec 2010 15:34:03 -0800 Received: from dradamslap1 (/10.159.244.34) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 03 Dec 2010 15:34:03 -0800 From: "Drew Adams" References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com><27E6B536A09248629C372671995E7E97@us.oracle.com> Date: Fri, 3 Dec 2010 15:34:05 -0800 Message-ID: <96298A2BBF834FE5ADE3B5E72F576005@us.oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcuTQCSDmymCBX5XSGmUAKxfu9XLZQAAXHKg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 In-Reply-To: X-Spam-Score: -6.4 (------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -6.4 (------) Looks good. Minor: > ALIGN ... > + if `comment-end' is empty, this has no effect, unless > EXTRA is also set, > + in which case the comment gets wrapped in a box. You don't say what "wrapped in a box" means. It's OK, but my guess is that someone will just have to try this to understand. > EXTRA ... > + if the comment style is not multi line, this has no > effect, unless ALIGN > + is also set, in which case the comment gets wrapped in a box. Likewise. Again, it's OK, even if not real clear. > If INDENT is `multi-char', that means indent multi-character Sentence should end in a period. From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 14 11:10:00 2011 Received: (at control) by debbugs.gnu.org; 14 Jul 2011 15:10:00 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhNY7-0000lO-PG for submit@debbugs.gnu.org; Thu, 14 Jul 2011 11:10:00 -0400 Received: from hermes.netfonds.no ([80.91.224.195]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QhNY6-0000lC-9I for control@debbugs.gnu.org; Thu, 14 Jul 2011 11:09:58 -0400 Received: from cm-84.215.51.58.getinternet.no ([84.215.51.58] helo=quimbies.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1QhNXv-0000My-6G for control@debbugs.gnu.org; Thu, 14 Jul 2011 17:09:47 +0200 Date: Thu, 14 Jul 2011 17:09:46 +0200 Message-Id: To: control@debbugs.gnu.org From: Lars Magne Ingebrigtsen Subject: control message for bug #7509 X-MailScanner-ID: 1QhNXv-0000My-6G X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1311260987.68609@Wo9b06P0O7hzE5rvWiRXVQ X-Spam-Status: No X-Spam-Score: -2.7 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -2.7 (--) close 7509