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

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Thu, 4 Jul 2019 14:13:26 +0200
> 
> The rx notation is useful and complex enough to merit inclusion in the manual.
> 
> Right now, it's mainly described in the `rx' doc string, which is fairly 
> well-written but quite long and a bit unstructured. Describing it in the 
> manual permits a different pace and style of exposition, the inclusion of 
> examples and related information, structured into separate sections with 
> cross-references.
> 
> Proposed patch attached. It covers all rx features, functions, macros, 
> including the pcase pattern, and a mention of the corresponding string regexp 
> constructs.

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.

> The existing `rx' doc string can be left unchanged, or reduced to something 
> more concise, perhaps without a description of the entire rx language but 
> with a manual reference. Suggestions are welcome.

Yes, the doc string should be reduced to the summary of the
constructs.

> +@table @code
> +@item (let @var{ref} @var{rx-expr}@dots{})
> +Bind the name @var{ref} to a submatch that matches @var{rx-expr}@enddots{}.
   ^^^^^^^^^^^^^^^^^^^^^^^
"Bind the symbol @var{ref}", no?

> +@example
> +@group
> +(rx "/*"                          ; Initial /*
> +    (zero-or-more
> +     (or (not (any "*"))          ;  Either non-*,
> +         (seq "*"                 ;  or * followed by
> +              (not (any "/")))))  ;  non-/
> +    (one-or-more "*")             ; At least one star,
> +    "/")                          ; and the final /
> +@end group
> +@end example
> +
> +or, using shorter synonyms and written more compactly,

This last line needs @noindent before it.

> +@table @asis
> +@item @code{"some-string"}

Why @code{"..."} and not @samp{...}?  The latter will look better both
in print and in Info format.

> +Corresponding string regexp: @samp{AB@dots{}} (subexpressions in sequence).
                                ^^^^^^^^^^^^^^^^
I think this should use @samp{@var{a}@var{b}@dots{}} instead.  And
likewise for the other "corresponding string regexps".  The reason is
that neither A nor B stand for themselves, literally, they are
meta-variables.

> +Match the @var{rx}s once or not at all.@*

"Match @var{rx} or an empty string" sounds better to me.

> +Match the @var{rx}s zero or more times, non-greedily.@*

I would add here a cross-reference to where greedy matching is
described.

> +@item @code{(any @var{charset}@dots{})}

Please don't call this "charset", as that term is already taken by a
very different creature in Emacs.  I suggest "character set" instead.

> +Each @var{charset} is a character, a string representing the set of
> +its characters, a range or a character class.  A range is either a
> +hyphen-separated string like @code{"A-Z"}, or a cons of characters
> +like @code{(?A . ?Z)}.

Again, a cross-reference to where "character class" described would be
good here, as would a @cindex entry for "character class in rx".

> +@item @code{space}, @code{whitespace}, @code{white}
> +Match any character that has whitespace syntax.

Only ASCII or also non-ASCII?  This should be spelled out.

> +@xref{Syntax Class Table} for details.  Please note that
                            ^
Comma missing there.

> +@kbd{M-x describe-categories @key{RET}}.  @xref{Categories} for how
                                                              ^
Likewise.

Thanks.