named capture using non-capturing group confusion

[jdv]

I find it odd that the docs say that a non-capturing grouping can be formed with square
brackets and then goes on to say that a named capture can be formed with square
brackets. Maybe that could be reworded to be less confusing.

[smls]

Link to the doc section in question?

In any case, it's true:

• You can form a non-capturing group with square brackets:
  / [ one | two ] three /
• You can form a named capture with square brackets:
  / $<foobar>=[ one | two ] three /

[tisonkun]

named capture does not always using square brackets

/ $<foobar>=( one | two ) three / is ok, and (one | two) won't be $0.

I have read section "Named captures" and "Non-capturing" in doc "Regexes". Which paragraph confuses you?

[jdv]

I'm not debating what works. I'm debating the clarity of the docs.

First, in the Capturing section, its stated that () do capturing and grouping.
Then, in the Non-capturing grouping section, its stated that to do such use [] instead of ().
Then, in Named captures section, named captures are illustrated using [].

So two possible issues to me:

1. Its not clear that () can be used for named captures.
2. its not stated clearly, in the non-capturing group section, that [] can be used for capturing grouping
   and its not stated clearly, in the named captures section, that [] can be used for non-capturing grouping.

[jnthn]

Maybe [...] should just be called a group, rather than a non-capturing group, in the documentation. So far as I'm aware, the only reason it's referred to as a "non-capturing group" is historical (when (?:...) is the syntax for it, then it kinda makes more sense). I don't think we need to carry that baggage forward, however. So:

• [...] is a group, with the things inside of it being treated as an atom
• $<foo>=... captures the atom following it

[JJ]

So maybe "non-capturing" should be eliminated, and just call them group as suggested?

[MorayJ]

Clarifies capturing properties of square brackets in regex #2286

I've not eliminated non-capturing, but have made some changes. With this issue approaching its first birthday, I've put in what I hope helps.