RE: defcustom and the stars.

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

> the docstring (without the asterisk) should *not* start with an
asterisk....
> Otherwise, you have:
>   (defvar my-var nil "**This* is a user variable.")
> and some day you hurriedly modify it to:
>   (defvar my-var nil "*This* is not a user variable.")
> and get an unwanted result.

OK, yes, that is something different from what I wrote about.

I don't see such carelessness as a problem that can or should be cured by
program or convention. If you are saying that anyone who starts a doc string
with two asterisks, and later wants to change the var to a non-user variable
by deleting the leading asterisk, risks forgetting to remove both leading
asterisks, then I would say that that is a problem we should not worry
about.

We should not worry about it because 1) it is unlikely to occur and 2) if it
occurs, the consequences are not great and the effect will be seen soon
enough.

> > people can rephrase the text to avoid starting with `*' if they
> don't want `*' to indicate a user variable.
>
> Yes, that's what I'm saying, only I'm adding that we should perhaps
> explain in the docs: "Please take care the docstring *contents* does
> not start with an asterisk."

I don't think that's necessary, and it could even introduce confusion.

Unless we're worrying about modifying doc strings by program, which you said
you're not talking about here, I don't think there is a problem with saying
only that any doc string that starts with an asterisk indicates a
`set-variable' target.

> > (In my case, I _do_ want it to indicate a user variable.)
>
> I understood it the first time. In fact, I understood it on your
> previous message. I usually have no trouble understanding your
> messages. Pity the reverse is not true. Not your fault, of course.

It could be my fault, or, rather, it is at least partly my responsibility.

When I was 13, my math teacher taught us not to accept anything on guzzle
(i.e. without understanding). What he meant was that if I can't get someone
to understand, then it is mainly my fault: the main burden of teaching is on
the teacher (or arguer, prover), who needs to find some way to get the point
across. His immediate point was about formal proof, but the lesson was a
wider one.

Language is a hard nut to crack, however. Students (like me, here) also need
to try to understand. The burden-of-proof-is-on-the-teacher argument is best
viewed at the level of ideas (logic, arguments), not just at the level of
language.

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.

BTW, I learned from a Japanese user of one of my libraries that Lisp code
can be a good way to get around the English barrier sometimes. Quite a bit
can be communicated using just sexps with end-line comments that indicate
results:

 (toto)    ; => 43
 (foo bar) ; => t (EXPECTED nil)

That's obvious, perhaps, but I never imagined that an entire conversation
could be conducted that way. Lisp cum lingua franca!