From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.devel Subject: RE: Leading * in docstrings of defcustoms. Date: Mon, 24 Nov 2008 14:43:58 -0800 Message-ID: <006401c94e86$23d44d70$c2b22382@us.oracle.com> References: <8763mfsgks.fsf@speer.lan><000601c94e55$7f997580$c2b22382@us.oracle.com> <87wses3lpg.fsf@cyd.mit.edu> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1227566669 16917 80.91.229.12 (24 Nov 2008 22:44:29 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 24 Nov 2008 22:44:29 +0000 (UTC) Cc: 'Glenn Morris' , emacs-devel@gnu.org, 'Stefan Monnier' , 'Lute Kamstra' , 'Juanma Barranquero' To: "'Chong Yidong'" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Nov 24 23:45:31 2008 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1L4kBK-0001ye-Dw for ged-emacs-devel@m.gmane.org; Mon, 24 Nov 2008 23:45:27 +0100 Original-Received: from localhost ([127.0.0.1]:53659 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1L4kAB-0000Sr-61 for ged-emacs-devel@m.gmane.org; Mon, 24 Nov 2008 17:44:15 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1L4kA6-0000QZ-DO for emacs-devel@gnu.org; Mon, 24 Nov 2008 17:44:10 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1L4kA4-0000NH-2b for emacs-devel@gnu.org; Mon, 24 Nov 2008 17:44:09 -0500 Original-Received: from [199.232.76.173] (port=34673 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1L4kA3-0000N1-Tc for emacs-devel@gnu.org; Mon, 24 Nov 2008 17:44:07 -0500 Original-Received: from rcsinet13.oracle.com ([148.87.113.125]:36435 helo=rgminet13.oracle.com) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1L4k9z-0005FV-VF; Mon, 24 Nov 2008 17:44:04 -0500 Original-Received: from acsinet13.oracle.com (acsinet13.oracle.com [141.146.126.235]) by rgminet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id mAOMiI0Z027284 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 24 Nov 2008 22:44:20 GMT Original-Received: from acsmt703.oracle.com (acsmt703.oracle.com [141.146.40.81]) by acsinet13.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id mAOMiDoC021936; Mon, 24 Nov 2008 22:44:14 GMT Original-Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 24 Nov 2008 14:43:55 -0800 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <87wses3lpg.fsf@cyd.mit.edu> Thread-Index: AclOdFZuk+jLwf4ZRqKawe/RRP5DCAACERMw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Source-IP: acsmt703.oracle.com [141.146.40.81] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090203.492B2E2D.016E:SCFSTAT928724,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 1) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:106122 Archived-At: > They should already be omitted, or strongly deprecated, in > the manuals. For example, the Variable Definitions node in > the Lisp manual says > > There is no need to start [the docstring] with a `*', because > `defcustom' automatically marks `option' as a "user option" > > If you find a spot in the manual that still follows the old > convention, please let us know. Elisp manual nodes: * Defining Variables If the variable is a user option that users would want to set interactively, you should use `*' as the first character of ^^^^^^^^^^^^^^^^^^ DOC-STRING. This lets users set the variable conveniently using the `set-variable' command. Note that you should nearly always use `defcustom' instead of `defvar' to define these variables, so that users can use `M-x customize' and related commands to set them. *Note Customization::. ... User option variables are distinguished from other variables either though being declared using `defcustom'(1) or by the first character of their `variable-documentation' property. If the property exists and is a string, and its first character is `*', then the variable is a user option. Aliases of user options are also user options. While this "if" is true, and nothing here claims the "only if" case, it's easy to misread that text to also think the "only if" case applies, that is, that if a symbol has property `variable-documentation' then `*' is _required_ for a variable to be a user option. * Accessing Documentation goal-column Option *Semipermanent goal column for vertical motion, as set by ... The asterisk `*' as the first character of a variable's doc string, as shown above for the `goal-column' variable, means that it is a user option; see the description of `defvar' in *Note Defining Variables::. Again, depending on what is understood by "means", one can read this as saying that `*' is necessary if you want the variable to be a user option. Especially considering that `goal-column' is a defcustom, this text should perhaps be removed or updated.