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. 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. -- http://rrt.sc3d.org
