perlre.pod - rework documentation of capture groups and backreferences #20823
Conversation
| =back | ||
| | ||
| =head2 Variables related to regular expressions | ||
| =head2 Regex Variables |
There was a problem hiding this comment.
I don't see the need for changing this heading when it would break any existing links to this section.
There was a problem hiding this comment.
I couldn't find any. Do you mean those outside of the core?
There was a problem hiding this comment.
In general, any documentation may link to sections in core docs
There was a problem hiding this comment.
I'd like to rename it. See latest version of the patch.
| the same pattern, use C<\g1> (or C<\g{1}>) for the first, C<\g2> (or C<\g{2}>) | ||
| for the second, and so on. | ||
| This is called a I<backreference>. | ||
| =head3 Capture Groups and Backreferences |
There was a problem hiding this comment.
This would also break existing links to this section and I'm not sure how much value it brings to add the word backreferences to the heading.
There was a problem hiding this comment.
This is related to the other point I am parking for now. I want to get the other stuff cleaned up and then ill thinking about further restructuring.
| You can access the contents of a capture group by absolute number (using | ||
| C<"$1"> instead of C<"\g1">, I<etc>); or by name via the C<%+> hash, | ||
| using C<"$+{I<name>}">. | ||
| =head4 Use of curly braces in backreference notation |
There was a problem hiding this comment.
I like the idea of splitting this into head4 subheadings (it's pretty sorely needed), but this one isn't sufficient on its own: it would imply that the whole rest of the "Capture groups" section is under this subheading which isn't the case. Suggested other subheadings: "Backreferences", "Named capture groups" (moving the last paragraph about capture group scoping before the section on backreferences), and maybe "Backreference notation ambiguity", "Examples", and "Match variables"? some reorganization might be needed.
There was a problem hiding this comment.
I am going to park this one until the rest of the feedback is cleared.
The documentation for capture groups and backreferences was getting somewhat awkward in terms of wording and structure and was inconsistent in terminology, difficult to read in raw form, and had omissions and mistakes in various places. This is an attempt to clean it up, make it more readable, comprehensive, correct the mistakes, enhance what was there, and provide more links from it to perlvar. This also includes changes to reduce the use of "regular expresssion" in favour of "regex" or "regexp" or "regexen". Perl does not have a regular expression engine in the strict sense of the word, it has something more powerful and more useful, and Larry has pioneered the use of these alternative terms as a replacement to avoid confusion.
demerphq force-pushed the yves/perlre_capture_buffer_docs_redo branch from 3e146cf to 616f774 Compare | @Grinnz you available for further review? |
| Unicode rules, and neither did all occurrences of C<\N{}>, until 5.12. | ||
| | ||
| =head2 Regular Expressions | ||
| =head2 Regexen, Regexps and Regular Expressions |
There was a problem hiding this comment.
I don't particularly agree with the relevance of this section here (in addition to my previous objections to renaming sections unnecessarily)
There was a problem hiding this comment.
To try to be more specific: this seems like a subject for a blog post, rather than Perl documentation on regexes.
There was a problem hiding this comment.
(at the very least, I would prefer this be a separate task from this PR's useful reorganization)
The documentation for capture groups and backreferences was getting somewhat awkward in terms of wording and structure and was inconsistent in terminology, difficult to read in raw form, and had omissions and mistakes in various places.
This is an attempt to clean it up, make it more readable, comprehensive, correct the mistakes, enhance what was there, and provide more links from it to perlvar.