RegExp reference

[Josh-Cena]

I want to discuss about the possibility of moving RegExp grammar from "guide" to "reference". Namely, these pages:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Character_Classes
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Backreferences
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Quantifiers
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Unicode_Property_Escapes

This was mostly based on my own experience prior to being familiar with MDN's site structure. Every time I want to look up something (e.g. "lookbehind"), I go to the "Reference" sidebar—but I was never able to find the RegExp grammar section. Sometimes I randomly arrive at a page via search, but I was never able to discover them independently. Only lately did I discover that they are subpages of the Regular expression guide: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

I have a habit of not reading guides, because guides, which sound like tutorials, often spend time introducing basic concepts while I just want to look up a particular language feature. I have always assumed the reference section contains all language features, and the guide is just a more approachable re-organization of these points. However, for RegExps, there's absolutely no mention of their grammar in the reference section.

One problem this brings about is the lack of browser compatibility table for RegExp grammars. For example, it's not known which browsers support lookbehinds /(?<a)b/—Safari doesn't support that to this day, and it had been a footgun for me in the past. Sure, this data isn't present in BCD atm; but even if it is, we have the tradition of not having browser compat tables in the guide section, so they would be weird to appear there. We need a reference page just for the purpose of presenting browser compat.

In addition, the flags are still underdocumented. It's not clear how the multiline or unicode flags work in tandem with various regex features, or how global and sticky impact exec(). mdn/content#19540 will bring some improvements, but I wish there's a central place to document how flags interact with regex's interpretation and execution.

My questions are:

• Shall we move these RegExp feature pages to the reference section, under a new "RegExp grammar" page in "misc"?
• How exhaustive do we want to be for the RegExp guide? Do we need to lay out every single syntax, or only introduce a few and link to the rest in the references?
• Is is feasible to have RegExp browser compat data?

cc @queengooborg @mdn/yari-content-javascript

[sideshowbarker]

Shall we move these RegExp feature pages to the reference section, under a new "RegExp grammar" page in "misc"?

Yes (for the reasons described above)

How exhaustive do we want to be for the RegExp guide? Do we need to lay out every single syntax, or only introduce a few and link to the rest in the references?

I think we should aim to be as complete as possible in having the docs provide answers to any questions that developers might have.

Is is feasible to have RegExp browser compat data?

Given that at https://test262.report/browse/built-ins/RegExp we have results for all browserJS engines for a relatively comprehensive test suite, it seems all the compat data we’d need to draw from is readily available?

[wbamberg]

I'm sympathetic to the issue here but there are questions, mostly: where would they live, what structure would they have, and how would they relate to the existing docs in the JS reference?

We want docs in reference (in JS, CSS, and everywhere else) to be very consistently organized, to make it easier for people to find things. (As you say, the model for reference is "look up") So we have this implicit idea that a set of reference docs consists of pages of different types, that have a consistent relationship with each other. For example, https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp is a page describing a JS global object, like the Date or Array pages, and has a similar structure to them and a similar relation to other pages. Its child pages document things like constructor, properties, and methods of that object. Things like the sidebar depends on those kinds of assumptions being true.

I've been working on a project to formalize this for MDN: mdn/content#15539.

But a page like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions doesn't seem to be any of these things. Where should it live, then, and how should it be navigable from pages like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp, and do we want to implement special cases just for this?

[hamishwillee]

@Josh-Cena

I think I'd need to see a prototype of ^^^^ to be able to envisage if that "works". But my feeling is that this is worth exploring if compat data is of any importance at all to re support (I assume it is).

• I'd expect to find that under https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/asssertions/\ say (though that particular URL won't work because of the slashes).
• I would still want the top level assertion page. Most of the time that is where I'd be looking.
• I never want to see a section named "misc" except as a last resort.

@wbamberg I have had exactly this same problem with finding the JavaScript regexp, to the extent that I normally just go to the Python regexp syntax docs https://docs.python.org/3/library/re.html#regular-expression-syntax and then search for anything else I need. They look a lot like our guide.

I completely agree with your points, and to that I'd add "what would our guide look like if we called this reference"?

But if we can't work out a way that we are happy to make this more reference-like in the way that MDN normally expects, I would still consider it a pragmatic move to move the guide across.

[Josh-Cena]

If we decided to go with one feature per page, we don't need to move existing guide pages at all. We'll simply make more.

Also, every feature has a name, so the slug would be like /Reference/RegExp/Named_capture_group and /Reference/RegExp/Lookbehind.

[wbamberg]

"what would our guide look like if we called this reference"?

Yeah, that was my reaction as well, but then I thought about https://documentation.divio.com/ , and according to that, these regex pages count as reference material - they're just not necessarily reference material that follows the same structure as the rest of it.

As I say, we already have "misc", that has unstructured docs in "Reference".

Still it is a valid question, what our JS guide pages (and actually, our site-wide guide pages) ought to be.

[hamishwillee]

they're just not necessarily reference material that follows the same structure as the rest of it.

Yes, so in theory we could all just agree that "this is the structure of regexp reference" and move them across. I'd be OK with that.

But I'd like to explore the idea of single page features. What are the benefits/problems. Again, a prototype of one or two cases would help understand whether this has value or just adds to the clutter.

And yes, we don't have a clear idea of what guide should be anywhere. Worse, we are very poor at linking from our guide to our reference and visa versa. So much so that I assume this is some sort of deliberate policy.

[Rumyra]

Hey folks - thanks for the suggestion @Josh-Cena

But I'd like to explore the idea of single page features. What are the benefits/problems. Again, a prototype of one or two cases would help understand whether this has value or just adds to the clutter.

I like this idea and it could actually fall into our 2023 goals quite well - I've added it to be triaged for our roadmap (coming soon) 👍

[Josh-Cena]

Reviving the thread a bit—I've tentatively decided on 16 pages to be created:

• Disjunction: |
• Input boundary assertion: ^, $
• Word boundary assertion: \b, \B
• Lookahead assertion: (?=...), (?!...)
• Lookbehind assertion: (?<=...), (?<!...)
• Quantifier: *, +, ?, {n}, {n,}, {n,m}
• Wildcard: .
• Character class: [...], [^...]
• Capturing group: (...)
• Named capturing group: (?<name>...)
• Non-capturing group: (?:...)
• Backreference: \1, \2
• Named backreference: \k<name>
• Character class escape: \d, \D, \s, \S, \w, \W
• Unicode character class escape: \p{...}, \P{...}
• Escape characters: \n, \u{...}

(These are page titles, literally)

Some pages may be longer than others (e.g. there could be a lot to talk about for backreferences, lookarounds, etc., less so for wildcard or character classes), but generally I expect them to be short—around the length between RegExp.prototype.unicode and RegExp.prototype.sticky. I'm open to initial ideas on the list above—or if people want to have a few pages as demo, I'm happy to write drafts as well.

[Josh-Cena]

PR's in: mdn/content#22210 just a few incomplete pages. Welcoming feedback.

[Diego200208]

Puede alguien ayudarme porfavor