From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#7509: 24.0.50; doc for `comment-style' and `comment-styles' Date: Sun, 28 Nov 2010 14:34:05 -0800 Message-ID: References: <9166F5772B0D414D84ECE3808ECD3964@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1290984309 26420 80.91.229.12 (28 Nov 2010 22:45:09 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 28 Nov 2010 22:45:09 +0000 (UTC) Cc: 7509@debbugs.gnu.org To: "'Stefan Monnier'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Nov 28 23:45:04 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PMpzT-0006VS-Sx for geb-bug-gnu-emacs@m.gmane.org; Sun, 28 Nov 2010 23:45:04 +0100 Original-Received: from localhost ([127.0.0.1]:59486 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PMpzT-0000GN-AN for geb-bug-gnu-emacs@m.gmane.org; Sun, 28 Nov 2010 17:45:03 -0500 Original-Received: from [140.186.70.92] (port=58018 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PMpzO-0000GC-7j for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 17:44:59 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PMpzM-0001Xv-3b for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 17:44:58 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:57425) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PMpzM-0001Xr-0j for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 17:44:56 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1PMpkx-0001Fv-Pa; Sun, 28 Nov 2010 17:30:03 -0500 X-Loop: help-debbugs@gnu.org 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: Original-Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.12909833964796 (code B ref 7509); Sun, 28 Nov 2010 22:30:03 +0000 Original-Received: (at 7509) by debbugs.gnu.org; 28 Nov 2010 22:29:56 +0000 Original-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 Original-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 Original-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 Original-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 Original-Received: from abhmt019.oracle.com by acsmt354.oracle.com with ESMTP id 810544881290983655; Sun, 28 Nov 2010 14:34:15 -0800 Original-Received: from dradamslap1 (/10.159.220.140) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 28 Nov 2010 14:34:15 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 Thread-Index: AcuPP2pXrRJLgVKnSyWiYj1n937sKQADD4ow X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sun, 28 Nov 2010 17:30:03 -0500 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:41988 Archived-At: > > 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)) ; <================