Subject: bug#36496: [PATCH] Describe the rx notation in the lisp manual

From: Eli Zaretskii <[email-masked]>
Date: Sat, 06 Jul 2019 12:08:08 +0300

> From: Mattias Engdegård <[email-masked]>
> Date: Fri, 5 Jul 2019 16:13:52 +0200
> Cc: [email-masked]
> 
> > This is a large section.  The ELisp reference is already a large book,
> > printed in two separate volumes.  So I think if we want to include
> > this section, it will have to be on a separate file that is
> > conditionally included @ifnottex.
> > 
> > Alternatively, we could make this a separate manual.
> 
> It is about 7-8 pages in all.

It's more that 2500 lines.  We have in doc/misc/ separate manuals much
smaller than this.  So making a separate manual out of this is not
radically different from what we have already.

> One page could be saved by combining the character class descriptions with the existing ones; they are basically the same. However, that would probably preclude separation into separate files or manuals.
> 
> The category names also take up about one page, but that information isn't available anywhere else, since those names are specific to rx. (It would be nice if the names were defined along with the categories, but that isn't the case at present.)

I don't think we should go out of our way to make this text shorter.
it is well written, and doesn't waste words, so any attempt to make it
shorter will IMO make it less useful.

> I would prefer @ifnottex to having a separate manual

Either alternative is fine with me.

> The revised patch (attached) does not separate the contents, because I wanted to hear your opinion on the matter first.

Opinion on which matter? on whether or not make it a separate manual?
If so, you now have my opinion.

> >> +@xref{Syntax Class Table} for details.  Please note that
> >                            ^
> > Comma missing there.
> 
> Ah, yes. Apparently, a comma is inserted automatically in the TeX version, so that we get the desired "See Section XIV, page 123, for details"; this is documented. In the info and html versions there is no page number, so a comma doesn't feel like proper English: "See Section XIV, for details" has a distinct German tone to my ears.
> Explicit comma after @xref seems to be common in the Emacs manuals, so rather than to fight it out I castled the clauses.

The comma is common because older versions of makeinfo insisted on
having it, and would complain if there weren't one.  The latest
versions no longer complain, but we would still like to support the
old versions, as they are ~15 times faster, so some people still keep
them around.

Thanks.