[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[AUCTeX-devel] Re: Doc strings and Customize
From: |
David Kastrup |
Subject: |
[AUCTeX-devel] Re: Doc strings and Customize |
Date: |
Thu, 04 Oct 2007 00:25:26 +0200 |
User-agent: |
Gnus/5.11 (Gnus v5.11) Emacs/22.1.50 (gnu/linux) |
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