[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Leading * in docstrings of defcustoms.
From: |
Drew Adams |
Subject: |
RE: Leading * in docstrings of defcustoms. |
Date: |
Mon, 24 Nov 2008 14:43:58 -0800 |
> 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.
- Leading * in docstrings of defcustoms., Lute Kamstra, 2008/11/22
- Re: Leading * in docstrings of defcustoms., Juanma Barranquero, 2008/11/22
- Re: Leading * in docstrings of defcustoms., Glenn Morris, 2008/11/24
- Re: Leading * in docstrings of defcustoms., Juanma Barranquero, 2008/11/24
- Re: Leading * in docstrings of defcustoms., Stefan Monnier, 2008/11/24
- RE: Leading * in docstrings of defcustoms., Drew Adams, 2008/11/24
- Re: Leading * in docstrings of defcustoms., Chong Yidong, 2008/11/24
- RE: Leading * in docstrings of defcustoms.,
Drew Adams <=
- Re: Leading * in docstrings of defcustoms., Chong Yidong, 2008/11/24
- Re: Leading * in docstrings of defcustoms., Stephen J. Turnbull, 2008/11/24
- Re: Leading * in docstrings of defcustoms., Lute Kamstra, 2008/11/25
- Re: Leading * in docstrings of defcustoms., Lute Kamstra, 2008/11/28
- Re: Leading * in docstrings of defcustoms., Juanma Barranquero, 2008/11/28