bug#46910: 27.1; (elisp) RX doc

bug#46910: 27.1; (elisp) RX doc

[Drew Adams]

1. `Rx Constructs' doesn't explain that the "constructs" are used in
arguments to macro `rx'.

E.g.: "some-string" is not an RX expression.
      (rx "some-string") is an RX expression.

Please make this clear.

2. `Rx Constructs': Don't show things like `\sCODE' without saying what
CODE means.  If the column title for the table explaining RX names is
`Syntax character' or `Category character' then that's apparently what
CODE corresponds to for `\sCODE' or `\cCODE'.  But there's no way to
know that unless you're already familiar with `\s' and `\c' syntax.

3. `Rx Constructs', `Zero-width assertions': Call this `Zero-width
matching' or some such.

4. `Rx Functions': RX-EXPR is used as parameter name for what is, I
guess an Rx construct (the language used in `Rx Construct').  Expression
or construct?  Make it clear that RX-EXPR is an RX construct, if that's
what it is.  And consider adding an xref to `Rx Construct'.

5. `Rx Functions': A couple places talk about `'regexp' forms', but
those are specified nowhere, AFAICT.  The same places talk about
'literal' forms, which are specified, but which don't seem to work (?).
(See bug #46909.)


In GNU Emacs 27.1 (build 1, x86_64-w64-mingw32)
 of 2020-08-12
Repository revision: 86d8d76aa36037184db0b2897c434cdaab1a9ae8
Windowing system distributor `Microsoft Corp.', version 10.0.19041
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static''

bug#46910: 27.1; (elisp) RX doc

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> 1. `Rx Constructs' doesn't explain that the "constructs" are used in
> arguments to macro `rx'.
>
> E.g.: "some-string" is not an RX expression.
>       (rx "some-string") is an RX expression.
>
> Please make this clear.
>
> 2. `Rx Constructs': Don't show things like `\sCODE' without saying what
> CODE means.  If the column title for the table explaining RX names is
> `Syntax character' or `Category character' then that's apparently what
> CODE corresponds to for `\sCODE' or `\cCODE'.  But there's no way to
> know that unless you're already familiar with `\s' and `\c' syntax.
>
> 3. `Rx Constructs', `Zero-width assertions': Call this `Zero-width
> matching' or some such.
>
> 4. `Rx Functions': RX-EXPR is used as parameter name for what is, I
> guess an Rx construct (the language used in `Rx Construct').  Expression
> or construct?  Make it clear that RX-EXPR is an RX construct, if that's
> what it is.  And consider adding an xref to `Rx Construct'.
>
> 5. `Rx Functions': A couple places talk about `'regexp' forms', but
> those are specified nowhere, AFAICT.  The same places talk about
> 'literal' forms, which are specified, but which don't seem to work (?).
> (See bug #46909.)

Mattias, is this perhaps something you could take a look at?  I guess
it's about (info "(elisp) Rx Notation").

bug#46910: 27.1; (elisp) RX doc

[Mattias Engdegård]

25 sep. 2021 kl. 17.25 skrev Stefan Kangas <stefan@marxist.se>:
> 
> Drew Adams <drew.adams@oracle.com> writes:
> 
>> 1. `Rx Constructs' doesn't explain that the "constructs" are used in
>> arguments to macro `rx'.

Yes, I've added an explanation.

>> 2. `Rx Constructs': Don't show things like `\sCODE' without saying what
>> CODE means.  If the column title for the table explaining RX names is
>> `Syntax character' or `Category character' then that's apparently what
>> CODE corresponds to for `\sCODE' or `\cCODE'.  But there's no way to
>> know that unless you're already familiar with `\s' and `\c' syntax.

That's a valid point; now elaborated.

If anything I'd like to move the tables of syntax and (especially) category names to a separate page since they are rarely consulted and take up a lot of space. Not sure how to best do that.

>> 3. `Rx Constructs', `Zero-width assertions': Call this `Zero-width
>> matching' or some such.

Thank you, but it's established terminology and immediately explained in the first sentence.

>> 4. `Rx Functions': RX-EXPR is used as parameter name for what is, I
>> guess an Rx construct

That was a clear mistake, now fixed -- thanks.

>> 5. `Rx Functions': A couple places talk about `'regexp' forms', but
>> those are specified nowhere

The `regexp` and `literal` forms are both documented on the previous page.

For good measure, I also added some examples to illustrate the difference between `rx` and `rx-to-string`.