RE: defcustom and the stars.

["Drew Adams" <drew.adams@oracle.com>]

> > and the effect will be seen soon enough.
> 
> Not agreed (it's not always evident that a variable is a user
> variable, unless you look for it).

I guess you're right about that. But trying `set-variable' or `customize-option' will point out the problem - that's what I meant.

Wrt your point: That's why I define a command `apropos-option' in one of my libraries. I think we should have commands `apropos-option' and `describe-option', which are limited to user options. Just as we intentionally bind `C-h a' to `apropos-command', not to `apropos', so we would privilege `describe-option' over `describe-variable' in the user doc. We might even want to bind `C-h o' to it, and advertise that instead of (i.e. more than) `C-h v'.

> I'm not talking about modifying docstrings by program, right now. But
> I think the gist of Michaël's idea is good (for post-22.1): that
> describe-variable should remove the asterisk (that's an implementation
> artifact, and has no place in documentation), and indicate when a
> variable is a user variable; it already says "You can customize this
> variable" for defcustoms, doesn't it?

I agree that the first `*' has no place appearing in displayed documentation. I didn't think it did appear to users, but I guess I was mistaken about that. (It should appear in the doc string accessed by programs, however.) I support stripping it from what is shown to the user. I thought this was about "fixing" defcustom doc strings that didn't need an initial `*' by removing it definitively, not just for display. I think I misunderstood the question.

I also agree that `describe-variable' should indicate that an option is an option. I think I said that. I support that change.

> So, it's not only about "**text*..." cases, but also "*text*..." where
> the user-variable'ness is unintended.
> 
> > I.e., I need to try to understand what you are saying, and it 
> > is what you mean that needs to be convincing to me, not just
> > the words you use to convey it. I will try better to get your meaning.
> 
> Well, don't take too seriously my previous comment, please. :)

Not to worry ;-).