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 11:42:46 -0800 Message-ID: <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 1290973533 15644 80.91.229.12 (28 Nov 2010 19:45:33 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 28 Nov 2010 19:45:33 +0000 (UTC) To: 7509@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Nov 28 20:45:28 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 1PMnBY-0003WI-8o for geb-bug-gnu-emacs@m.gmane.org; Sun, 28 Nov 2010 20:45:21 +0100 Original-Received: from localhost ([127.0.0.1]:44246 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PMnBX-0003Ya-Pr for geb-bug-gnu-emacs@m.gmane.org; Sun, 28 Nov 2010 14:45:19 -0500 Original-Received: from [140.186.70.92] (port=37602 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PMnBT-0003YK-1V for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 14:45:16 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PMnBS-0001cq-0b for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 14:45:14 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:55839) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PMnBR-0001cm-VB for bug-gnu-emacs@gnu.org; Sun, 28 Nov 2010 14:45:13 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1PMn5S-0005qL-Of; Sun, 28 Nov 2010 14:39: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: 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: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.129097314122452 (code B ref -1); Sun, 28 Nov 2010 19:39:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 28 Nov 2010 19:39:01 +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 1PMn5Q-0005q4-J5 for submit@debbugs.gnu.org; Sun, 28 Nov 2010 14:39:00 -0500 Original-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 Original-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 Original-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 Original-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 Original-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 Original-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 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 oASJiO8w005895 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sun, 28 Nov 2010 19:44:26 GMT Original-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 Original-Received: from abhmt019.oracle.com by acsmt353.oracle.com with ESMTP id 819419021290973375; Sun, 28 Nov 2010 11:42:55 -0800 Original-Received: from dradamslap1 (/10.159.220.140) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 28 Nov 2010 11:42:55 -0800 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sun, 28 Nov 2010 14:39: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:41977 Archived-At: 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'