Peter Eisentraut <peter_e@gmx.net> writes:
> Tom Lane writes:
>> But I don't see anything
>> wrong with the concept. The short description is also the first
>> sentence of the long description; what's unreasonable about that?
> It constrains the writer of the description in a way he might not suspect.
> For example, we have
> check_function_bodies (boolean)
> This parameter is normally true. When set false, it disables
> validation ...
> Then the primary description would become "This parameter is normally
> true."
You have a point, but on the other hand, as the author of that
particular description I can feel free to criticize it. It's generally
considered good style for the first sentence of a paragraph to convey
the basic point. (In fact, I recall being dissatisfied with that text
when I wrote it, but I was too rushed to fix it.) Maybe we should just
go ahead and rewrite the variable descriptions to conform to this style.
> I think there are two ways this can be resolved:
> 1) Leave it this way, deal with it, but then we can put everything in one
> field and let the software parse out the first sentence automatically.
True.
> 2) Make real separate "short" and "long" descriptions.
We'd have to break the strings freeze to do that. How bad do you want it?
regards, tom lane
