Re: Documentation question

[Reuben Thomas]

On 14 August 2010 16:46, Reuben Thomas <address@hidden> wrote:
> On 4 August 2010 09:54, James Youngman <address@hidden> wrote:
>> On Wed, Aug 4, 2010 at 1:02 AM, Reuben Thomas <address@hidden> wrote:
>>
>>> "in regexprops-generic.texi, I think that having a plain English
>>> definition of the various syntaxes obscures the fact that each is
>>> defined as a strict combination of features. Would you be happy if I
>>> rewrote the manual as English documentation of each
>>> feature plus a simple list (possibly automatically generated from
>>> regex.h) of which features are present in which syntax?"
>>
>> I'm not sure the two options need to be exclusive.
>
> Fair enough, especially as it's machine generated, so the maintenance
> problem I imagined is non-existent.
>
>> In any case, the current documentation is machine-generated by a C
>> program in findutils.   You might want to download it; this should
>> help you get some more specific ideas about what you propose to
>> change.
>
> gnulib people: you seem to be unhappy with code-generated
> documentation. How would you like to proceed?

A possibly more useful summary:

At present, this documentation is machine generated. My proposal to
rewrite it would make it machine checkable rather than machine
generated, but would remove the full English-language description of
each syntax which James seems to want to keep. I am unconvinced that
the English-language description is a good thing, because it obscures
the fact that the various regex syntaxes are made up of combinations
of the same primitive features; hence, I'd rather have English
documentation only of the features, and simply reproduce in neater
form the lists of combinations from regex.h to document the higher
level syntax combinations.

It seems that if James wants to keep the machine-generated English,
then gnulib won't want to host the documentation. On the other hand,
if he doesn't mind getting rid of it, then I can rewrite the
documentation in such a form that it need no longer be
machine-generated, but can, if desired, be machine-checked. It would
be nice, as James has said, if gnulib were able to be upstream of
findutils for this last piece for which it should logically be
upstream but isn't.

Can we come to some agreement?

-- 
http://rrt.sc3d.org