[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
signature.asc
Description: OpenPGP digital signature
- Re: [Findutils-patches] Automatically-generated regexp documentation,
Eric Blake <=
- Re: [Findutils-patches] Automatically-generated regexp documentation, Reuben Thomas, 2016/10/21
- Re: [Findutils-patches] Automatically-generated regexp documentation, Paul Eggert, 2016/10/21
- Re: [Findutils-patches] Automatically-generated regexp documentation, Eric Blake, 2016/10/21
- Re: [Findutils-patches] Automatically-generated regexp documentation, Reuben Thomas, 2016/10/21
- Re: [Findutils-patches] Automatically-generated regexp documentation, Eric Blake, 2016/10/21