bug#41006: 26.3; regular expressions documentation

[Stefan Kangas <stefan@marxist.se>]

Eli Zaretskii <eliz@gnu.org> writes:

>> Now we have
>>
>> >   > * Regular Expressions::   Describing classes of strings.
>> >   > * Regexp Search::         Searching for a match for a regexp.
>>
>> We could convert Regexp Search into a subsection under Regular
>> Expressions.  I don't see any harm in doing that.

I'm glad to hear that.

> Let's first decide whether we are talking about the Emacs user manual,
> the ELisp reference manual, or both.  The current organization of this
> stuff is slightly different in each one.  The OP meant the user
> manual, AFAIU.

Yes, I brought up the ELisp manual.  Sorry to bring this related issue
into this discussion without clearly marking it as such.

> To answer the specific question you asked: this is all part of a
> chapter called "Searching and Replacement" in the user manual and
> "Searching and Matching" in the ELisp manual.  So having there a
> section called "Regular Expressions" which would include a subsection
> about regexp search makes less sense to me than the other way around:
> have a section "Regular Expression Search" which would start with
> syntax of regexps and go on to a subsection that describes the regexp
> search facilities (it should then probably include the "POSIX Regexps"
> section as well).

I see your point here.

In the user manual, perhaps we could re-organize what we have now
(excluding other subsections for the sake of brevity):

* Searching and Replacement
** Regexp Search::             Search for match for a regexp.
** Regexps::                   Syntax of regular expressions.
** Regexp Backslash::          Regular expression constructs starting with ‘\’.
** Regexp Example::            A complex regular expression explained.

Into something like:

* Searching and Replacement
** Regular Expression Search   Search for match for a regexp.
*** Regexp Syntax::             Syntax of regular expressions.
*** Regexp Backslash::          Regular expression constructs starting with ‘\’.
*** Regexp Example::            A complex regular expression explained.

I think one needs to look at it in the context of the user manual, and
what the Info node `(emacs) Search' looks like to fully understand the
merit of your argument.  Every other subheading in that chapter is
called something with "<foo> Search" (besides one, which is called
"Replace").

---

In the ELisp manual, I think it could fine to have a section called
simply "Regular Expressions".  Either the user already knows about
regexps, in which case we have no problem, or the user does not know but
will soon find out.

I argue this only because I find the shorter name more elegant.  This is
a minor stylistic point, though, and I'm fine with "Regular Expression
Search" there, too.

In any case, it looks like it needs a bit more work.  There are actually
bits and pieces about regular expressions spread out in the chapter
`(elisp) Searching and Matching':

* Regular Expressions::   Describing classes of strings.
* Regexp Search::         Searching for a match for a regexp.
* POSIX Regexps::         Searching POSIX-style for the longest match.
* Match Data::            Finding out which part of the text matched,
                            after a string or regexp search.
* Search and Replace::    Commands that loop, searching and replacing.
* Standard Regexps::      Useful regexps for finding sentences, pages,...

Moving "Regexp Search" into a more general section called "Regular
Expressions" is a step in the right direction.  But then comes the
problem with finding match data, which is part of the "Match Data"
section, or using `re-search-forward', which is in the "Search and
Replace" section.  I have found all this information to be hard to find
in the past.

Maybe we can take a small first step here.  But perhaps this section
needs a bigger rethink?

Best regards,
Stefan Kangas