Re: docstrings (WAS: Re: Q: Making an XEmacs package)
>>>> "Matt" == Matt Tucker
<tuck(a)whistlingfish.net> writes:
Matt> -- Jarl Friis <jarl(a)diku.dk> spake thusly:
> On 14 Dec 2001, Stephen J. Turnbull wrote:
Jarl> one should start the documentation string with an asteriks
Jarl> to indicate it's a user option, the
>> This is used by (hyper-)?apropos. You should still do it in
>> defcustoms.
> It affects (hyper-)?apropos with an indication that it is a
> user-variable, no other way right? [...] Related is the affect
> to `set-variable' which completion includes it if and only if
> the doc string contains an asterisk.
Exactly.
Also, as far as I know, with the advent of custom there is no good
reason for a defvar docstring to have a "user option" asterisk, and
the only not-half-bad reason is that the feature is sufficiently
unimportant that it hasn't been converted to custom.
Matt> I always find this sort of 'feature' weird; it seems like a
Matt> hack to me. Would it make sense to change this interface to
Matt> use a property for user options instead of an asterisk?
This might require surgery in a number of not-obvious places.
Remember that docstrings live in DOC as well as in properties on
symbols.
Also, this would introduce a very large number of nearly gratuitous
diffs against mainline GNU Emacs. We should try to coordinate this
kind of thing with the GNU Emacs project.
--
Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Don't ask how you can "do" free software business;
ask what your business can "do for" free software.