bug#7160: `defcustom' manual documentation divergent with docstring

[MON KEY]

current through Bzr-101790

in doc/lispref/customize.texi there is this line:

,----
|
| @defmac defcustom option standard doc [keyword value]@dots{}
|
`----

with subsequent references to the parameters '@var{option}'
'@var{standard}' appearing throughout the remaining germane
portions of the manual's documentation.

The argument signature for the `defcustom' macro is:

 defcustom (symbol value doc &rest args)

The docstring refers only to parameter names SYMBOL and VALUE and not
those used in the manual, e.g. OPTION and STANDARD.

Note too, that the OPTION/STANDARD usage is not in keeping with the
signature of function `custom-declare-variable':

 custom-declare-variable (symbol default doc &rest args)

Given the miasma of hairyness one encounters when attempting to grok
the horror that is `defcustom' the current disconnect in param names
is really disconcerting.

This said, it is not immediately clear what is the correct fix for
this the problem because there are multiple different semantic uses of
"option" throughout the relevant section, such that it is not always
clear which semantic is current.  This context-conflict is hinted at
in doc/lispref/ChangeLog:

,----
| 2006-12-17  Richard Stallman  <rms@gnu.org>
|
| * customize.texi: Use "option" only for user options.
| For the keyword values inside defcustom etc, say "keywords".
| For :options value's elements, say "elements".
`----

As such, it prob. not wise to do simply query-replace-regexp over the
relevant section exchanging '@var{option}' with '@var{symbol}'.  Indeed,
nor would replacing '@var{standard}' with '@var{value}' help clarify the
docs in so much as VALUE is also such a semantically loaded term given
the context.

The better fix would be to rename `defcustom's parameters to less
loaded terms and adjust the manual accordingly (including those places
where the word "option" is used ambiguously - though prob. only Chong
Yidong has the sufficient requisite understanding of `defcustom'
capable of teasing out those subtle usage anomalies).

Maybe instead of the { OPTION/STANDARD | SYMBOL/VALUE } parameter
names these would work better:

 VAR-SYMBOL and VAR-VALUE

Note that `defcustom' has had its above referenced signature since at
least Bzr-17335 of 1997-04-07. Likewise, `custom-declare-variable' has
had its signature since Bzr-19517 of 1997-08-25. It isn't clear from
the revision log of customize.texi how long it has used a divergent
signature.

--
/s_P\