autoconf documentation for m4_bregexp and m4_bpatsubst

Hi,

(This may be relevant to the m4 list as well, which I'm not currently
subscribed to.)

tl;dr:
======

I think that the autoconf and m4 manuals could have improved
cross-references to the regular expression syntax actually supported
in autoconf via GNU m4:

autoconf:
- m4_bpatsubst():
   - Cross-reference to M4's patsubst().
   - Possibly cross-reference to Gnulib's emacs-style regex syntax.
- m4_bregexp():
   - Cross-reference to M4's regexp().
   - Possibly cross-reference to Gnulib's emacs-style regex syntax.

m4:
- regexp:
   - Cross-reference to Gnulib's emacs-style regex syntax.
- patsubst:
   - Already internally references to m4's regexp, so covered above?


Thoughts?


Details:
========

While debugging an issue with m4_bregexp() (and m4_bpatsubst()),
I ended up in a twisty maze of documentation trying to understand
the specific regex features available in autoconf and GNU m4.


1. autoconf section 8.3.1 'Redefined M4 Macros'
	https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.71/html_node/Redefined-M4-Macros.html

	Macro: m4_bregexp (string, regexp, [replacement]) This macro
	corresponds to regexp. The name m4_regexp is kept for future
	versions of M4sugar, once GNU M4 2.0 is released and supports
	extended regular expression syntax.

There's no specific cross-link here to the m4 macros.


2. m4 section 11.3 'Searching for regular expressions'
	https://www.gnu.org/software/m4/manual/html_node/Regexp.html

	Builtin: regexp (string, regexp, [replacement])
	Searches for regexp in string. The syntax for regular
	expressions is the same as in GNU Emacs, which is similar to
	BRE, Basic Regular Expressions in POSIX.
	See [Syntax of Regular Expressions] in the GNU Emacs Manual.
	Support for ERE, Extended Regular Expressions is not available,
	but will be added in GNU M4 2.0.

[Syntax of Regular Expressions] is a link to
	 https://www.gnu.org/software/emacs/manual/emacs.html#Regexps
which goes to the top of the Emacs manual. After a bit of poking
around I found Emacs manual section 15.6 - see below

Code inspection of GNU m4 reveals that m4 uses Gnulib's regex
implementation in the default (Emacs-like) regex mode;
src/builtin.c (etc) don't call re_set_syntax() and the default
appears to be RE_SYNTAX_EMACS 0. See item 5 below.


3. Emacs section 15.6 'Syntax of Regular Expressions'
	https://www.gnu.org/software/emacs/manual/html_node/emacs/Regexps.html

	This section (and this manual in general) describes regular
	expression features that users typically use.
	See [Regular Expressions] in The Emacs Lisp Reference Manual,
	for additional features used mainly in Lisp programs.

[Regular Expressions] is a link to
	https://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html#Regular-Expressions


4. Emacs section 35.3 'Regular Expressions'
	https://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html
contains section 35.3.1 'Syntax of Regular Expressions'
	https://www.gnu.org/software/emacs/manual/html_node/elisp/Syntax-of-Regexps.html
contains section 35.3.1.3 'Backslash Constructs in Regular Expressions'
	https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Backslash.html
which describes various backslash features.

As far as I can tell, some of these aren't implemented by GNU m4:
- \{ and \} for intervals.
- \(?: ... \) for shy groups.
- \(?num ... \) for explicitly numbered groups.


5. Gnulib section 18.7.4 '‘emacs’ regular expression syntax'
	https://www.gnu.org/software/gnulib/manual/html_node/emacs-regular-expression-syntax.html

This describes various regex features in Gnulib's emacs emulation.
Supports \( \) grouping, \| alternation, some GNU extensions,
but not \{ \} intervals from Emacs / POSIX BREs.



Regards,
Luke.