On 14 August 2010 16:46, Reuben Thomas <r...@sc3d.org> wrote: > On 4 August 2010 09:54, James Youngman <j...@gnu.org> wrote: >> On Wed, Aug 4, 2010 at 1:02 AM, Reuben Thomas <r...@sc3d.org> 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
