[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#41006: 26.3; regular expressions documentation
From: |
Stefan Kangas |
Subject: |
bug#41006: 26.3; regular expressions documentation |
Date: |
Fri, 8 May 2020 03:10:45 -0700 |
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
- bug#41006: 26.3; regular expressions documentation, (continued)
- bug#41006: 26.3; regular expressions documentation, Stefan Kangas, 2020/05/07
- bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/06
- bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/06
- bug#41006: 26.3; regular expressions documentation, Drew Adams, 2020/05/06
- bug#41006: 26.3; regular expressions documentation, Stefan Kangas, 2020/05/07
- bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/07
- bug#41006: 26.3; regular expressions documentation, Eli Zaretskii, 2020/05/08
- bug#41006: 26.3; regular expressions documentation,
Stefan Kangas <=
- bug#41006: 26.3; regular expressions documentation, Eli Zaretskii, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Stefan Kangas, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Eli Zaretskii, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Stefan Kangas, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, jan, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Drew Adams, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/08
- bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/08
bug#41006: 26.3; regular expressions documentation, Richard Stallman, 2020/05/03