bug-gnulib
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Automatically-generated regexp documentation


From: Reuben Thomas
Subject: Re: Automatically-generated regexp documentation
Date: Fri, 21 Oct 2016 19:43:37 +0100

On 21 October 2016 at 14:46, Reuben Thomas <address@hidden> wrote:
On 21 October 2016 at 14:25, Eric Blake <address@hidden> 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:


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.

--

reply via email to

[Prev in Thread] Current Thread [Next in Thread]