[AUCTeX-devel] Re: Doc strings and Customize

[David Kastrup]

Ralf Angeli <address@hidden> writes:

> * David Kastrup (2007-10-03) writes:
>
>> In short: there is no necessity to have the exact same wording and
>> spelling of the customization options in the DOC string: the DOC
>> string should have a natural flow of words even when not looking at
>> the customization options, and fit the grammar and spelling (so
>> quite often, the customization option will be in singular, and the
>> description in plural).  Of course, one will basically use the same
>> catch phrase and also keep the order of descriptions and options
>> strictly the same.
>
> But then you are running at risk that the user is not able to make
> the connection between a symbol and the respective choice in the
> customization interface.

Well, the changes should just be enough to fit nicely into their
environment.  There are probably no really good rules for everything:
writing documentation remains an art.

> I seem to recall a user complaining about something like that but
> maybe it's just my mind playing tricks on me.

It is much easier for us to get a user to complain rather than a
developer.  It is probably hopeless to make all users satisfied with
all of AUCTeX.

> Perhaps we should repeat symbol names in tags.

I much prefer having a something obviously corresponding to part of
the description here.  The customize "button area" should form a
coherent whole once you basically know the available options, and
implementation details detract from it.

> If such connections are made on the Customize side, they don't
> pollute the doc string which is used elsewhere as well.

Well, but I'd like to keep both Customize and DOC string reasonably
clean on their own if possible.

Again: this is more or less an art, and we'll probably not succeed on
all fronts at once.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum