Re: `set-variable' should use :set

[Stephen J. Turnbull]

Juanma Barranquero writes:

 > > Most important is clarity, and I find "However, this feature is
 > > largely obsoleted by `defcustom'" quite clear as far as it goes
 > > (it doesn't say why or how).
 > 
 > I find it quite clear too.

Clear, yes.  I personally think it's ugly and awkward, the kind of
usage a tasteless engineer[1] would invent.  I would hope that Emacs
aspires to a higher, more literary standard.  That's why I suggested
Drew contribute a patch, not as an indirect way of asking him to shut
up.  (The smiley was because I expected the response he produced: a
few hundred words on emacs-devel and no patch.)

I don't think that clarity is sufficiently important that we should
say "if it's clear, ship it."  Precision in natural language is as
important as precision in formal languages.  I don't have an issue
with efficient use of one's time; if you happen to be a tasteless
engineer, your contribution will be in elegant code, not elegant
docs.  Clarity is the sine qua non, and that's what you should aim for
if getting even that is a struggle.

But a superior application will have elegant docs, which the user will
appreciate far more than elegant code.  (Of course neither holds a
candle to elegant UI.)

Footnotes: 
[1]  The adjective is not redundant.