[resent because the gnu.org mail server was not working right for a short
while yesterday]
Hello Reuben,
Paolo Bonzini wrote:
> But Bruno is the doc guru.
Actually, Karl is in a much better position to comment here: He is the doc
guru, and he wrote part of the regex manual himself.
> The first thing that caught my eye is the mention
> of "regex.c". This can be expunged
Feel free to submit a patch that Eric or Karl or I can apply.
On the following, please consider Karl's opinion more than mine.
> 1. You have started with regex.texi, but really the source is
> xregex.texi, which includes bits of regex.h. It seems silly to go back
> to maintaining these inserts manually when there is already code to
> maintain them automatically! Would you be happy to restart with
> xregex.texi (presumably applying the diff that was applied to
> regex.texi would mostly work)?
I went for using regex.texi, because I did not understand the purpose
of xregex.texi. Not a good argument :-) But two real arguments in favour
of regex.texi are:
- It less Makefile rules to use it directly, and regex.h changes rarely
enough.
- Debian people may have a legal problem if they have to generate a
.info or .html documentation from input under different, incompatible
licenses (gnulib.texi and regex.texi without the code are under GFDL,
whereas regex.h is under LGPL). It's less a problem for us to perform
this combination, since we may more easily get the blessing of the FSF
(the copyright holder) for this.
Again, Karl's opinion will weigh more than mine here.
> 2. What's the reasoning behind removing the top level of the manual?
> (I understand the removal of the rest of the boilerplate, but it seems
> to me that the introductory node and top-level menu is part of the
> manual, not part of the boilerplate.)
You mean this text?
"This file documents the GNU regular expression library."
"This manual documents how to program with the GNU regular expression
library. This is edition 0.12a of the manual, 19 September 1992."
These sentences made no sense to me, since regex is now part of glibc
and gnulib. But feel free to submit a patch that gives an overview before
the overview.
The top-level menu is moved to gnulib.texi.
The text
"The first part of this master menu lists the major nodes in this Info
document, including the index. The rest of the menu lists all the
lower level nodes in the document."
is boilerplate; we don't need to teach people about the 'info' format
any more nowadays.
> Supplementary question: in regexprops-generic.texi, I think that
> having a plain English definition of the various syntaxes obscures the
> fact that each is defined as a strict combination of features. Would
> you be happy if I rewrote the manual as English documentation of each
> feature plus a simple list (possibly automatically generated from
> regex.h) of which features are present in which syntax?
Ask Karl and James. Karl added regexprops-generic.texi to gnulib in the
first place, and GNU findutils uses it.
Bruno
