[adding James and findutils] On 10/21/2016 01:43 PM, Reuben Thomas wrote: > On 21 October 2016 at 14:46, Reuben Thomas <r...@sc3d.org> wrote: > >> On 21 October 2016 at 14:25, Eric Blake <ebl...@redhat.com> wrote: >> >>> >>> In fact, such documentation already exists, and IS used in other GNU >>> manuals: at least findutils and m4 use the regexprops-generic module, >>> which generates the gnulib file doc/regexprops-generic.texi as a >>> human-readable user description of all regex flavors. >>> >> >> That's excellent! Another undiscovered gnulib gem. >> > > I looked at the Emacs Lisp manual to see what it currently looks like. The > relevant part, on the syntax of regexps, is here: > > https://www.gnu.org/software/emacs/manual/html_node/elisp/Syntax-of-Regexps.html#Syntax-of-Regexps > > Currently, it seems rather more elaborated than the gnulib documentation. > > Would it be acceptable to gnulib to have its template updated to be more > like Emacs's? Essentially, this means the inclusion of more explanation. I > imagine this would be necessary for the Emacs maintainers to consider > taking their documentation from regexproper-generic.texi.
Gnulib is currently just a distribution point; the upstream template was written by James Youngman for findutils (see findutils.git/lib/regexprops.c). But I suspect patches would be welcome, if you'd like to contribute some improvements. > > Note that I'm not talking about introducing full-on tutorial and example > sections. In the case of Emacs, the user manual has a section on regexps > which is more tutorial in nature, while the Elisp manual has a separate > examples section. > > There are also notes in the Emacs manual, as comments in the source, that > suggest differences that are not currently documented: for example, a claim > that character class ranges such as [a-z] respect LC_COLLATE in grep, but > not in Emacs. This sort of difference could usefully be studied, and > perhaps hooks introduced for program-specific notes. > > I'm happy to look into this if it's agreeable to the maintainers. It seems > to me an obvious opportunity to extend the good work already done by this > module in increasing documentation quality while reducing maintenance > effort. > -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
