findutils-patches
[Top][All Lists]
Advanced

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

Re: [Findutils-patches] Automatically-generated regexp documentation


From: Eric Blake
Subject: Re: [Findutils-patches] Automatically-generated regexp documentation
Date: Fri, 21 Oct 2016 13:59:52 -0500
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.4.0

[adding James and findutils]

On 10/21/2016 01:43 PM, Reuben Thomas wrote:
> 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:
> 
> 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

Attachment: signature.asc
Description: OpenPGP digital signature


reply via email to

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