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: Tue, 30 Nov 2010 11:13:03 -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 1291183371 19545 80.91.229.12 (1 Dec 2010 06:02:51 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 1 Dec 2010 06:02:51 +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 Wed Dec 01 07:02:47 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 1PNfmA-0007d5-KJ for geb-bug-gnu-emacs@m.gmane.org; Wed, 01 Dec 2010 07:02:46 +0100 Original-Received: from localhost ([127.0.0.1]:58374 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PNfmA-0007pg-04 for geb-bug-gnu-emacs@m.gmane.org; Wed, 01 Dec 2010 01:02:46 -0500 Original-Received: from [140.186.70.92] (port=43428 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PNdqv-0006TP-95 for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2010 22:59:50 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PNVfK-0004gI-9u for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2010 14:15:07 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:41950) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PNVfK-0004ew-0K for bug-gnu-emacs@gnu.org; Tue, 30 Nov 2010 14:15:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1PNVYY-0002oV-9y; Tue, 30 Nov 2010 14:08:02 -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: 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: Original-Received: via spool by 7509-submit@debbugs.gnu.org id=B7509.129114407110797 (code B ref 7509); Tue, 30 Nov 2010 19:08:02 +0000 Original-Received: (at 7509) by debbugs.gnu.org; 30 Nov 2010 19:07:51 +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 1PNVYL-0002o6-CJ for submit@debbugs.gnu.org; Tue, 30 Nov 2010 14:07:49 -0500 Original-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 Original-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 Original-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 Original-Received: from abhmt010.oracle.com by acsmt354.oracle.com with ESMTP id 816627581291144384; Tue, 30 Nov 2010 11:13:04 -0800 Original-Received: from dradamslap1 (/10.159.217.8) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 30 Nov 2010 11:13:04 -0800 X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcuQup87Hy82oh2yR5WVIrvrMi0bEQAAnhTg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5994 In-Reply-To: X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 30 Nov 2010 14:08:02 -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:42022 Archived-At: > 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.