Sprints: Regular expressions material needs filling in

[duncan-crane]

Request type

• Correction or update

Details

Sorry it's my first time here so I hope I've followed correct procedure.
I have relied heavily on the content of this section of the documentation for a couple of years, as it gave one of the clearest and most succinct explanations of what is a complex topic for many.
One of it's strengths was that everything was on a single page, so when trying to interpret a complex regular expression it was easy to scroll up and down to get the meaning of different components.
I appreciate greatly what a fantastic resource this is and the tremendous effort all contributors make. I would be really really grateful if you could revert to the single page for this subject. Although it is quite long, that is the most helpful format for people who need to keep referencing this topic who are maybe less experienced, like me.

[chrisdavidmills]

Hi @duncan-crane,

Thanks for your thoughts here. One of my counterparts at Google started doing this splitting work, on the understanding that the page was getting really long, and each section needs even more information added before it can be counted as complete, so it would just get longer.

I will give him a ping to see when he might complete the work. I think maybe more signposts as to what the pages contain would make things easier to navigate, but the consensus was that generally the page was getting too unwieldy and needed splitting.

[SphinxKnight]

@chrisdavidmills / @Elchi3 is there any update about this work (last significant edits are from Q1 2019)? There are still empty sections/headings left.
I agree that the page was getting quite long and needed splitting. However, I prefer 1 long page rather than several "drafts" lasting for months (esp. for en-US / fr parity maintenance).

Depending on the plan, I'm willing to lend a hand and help fixing this.

[chrisdavidmills]

@SphinxKnight yeah, looks like this isn't getting done ;-(

If you had some time to spend on this, I would be really grateful. I can probably chip in too. Let's make some plans!

[chrisdavidmills]

Referencing resource: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

[chrisdavidmills]

For my first task on this ticket, I've gone over the entire main page, and given it a good tidy up:

https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions

[chrisdavidmills]

Remaining tasks:

• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Assertions: Mainly just needs the Compatibility data, Specifications, and See also sections filled in, but we could also do with updating the table entries to be the same as what I did in the original article.
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Boundaries: same as the above really
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Character_Classes: same, but also needs examples filling in
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Ranges: same, plus also needs examples.
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Quantifiers: same, also needs examples
• https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Unicode_Property_Escapes: this is in a somewhat different format, and we need to think about what to do about it.

[chrisdavidmills]

Update: I have gone through all 6 sub-pages, and added the following sections:

• Specifications
• Browser compatibility
• See also

Still to be done:

• Update the javascript regexp browser-compat-data (javascript.builtins.RegExp) to include the structures I've indicated on the different pages.
• Decide whether Assertions and Boundaries should really just be one page, given that the spec basically groups them together as one thing.
  
  
  
  • Add Examples to "Character classes", "Groups and Ranges", "Quantifiers", and "Unicode property escapes"
  
  
• Get all the other sections of "Unicode property escapes" filled in, as well as deciding if the page structure is suitable.

Also:

• Remove the draft macro when the pages are done.
• Check in with @Elchi3 to see if all this sounds ok, when he is back. For example, we might want to move the subpages below the regexp constructor page instead, as it is a bit strange having these reference pages hung off of a JS guide page.

[chrisdavidmills]

@SphinxKnight are you still interested in contributing to this one?

[SphinxKnight]

@chrisdavidmills Yes I am :s I'll add examples to the pages and will review them (tonight / tomorrow)

[chrisdavidmills]

@SphinxKnight super ;-)

So if you work on examples, I'll get to work on updating the Regexp browser-compat-data.

[chrisdavidmills]

Browser compat data updated: https://github.com/mdn/browser-compat-data/pull/5350

[SphinxKnight]

* Decide whether Assertions and Boundaries should really just be one page, given that the spec basically groups them together as one thing.

I'm inclined to merge them as well (writing examples using both of them feels natural but clunky if this is documented in two distinct pages)

[SphinxKnight]

I've added a few examples across most of the pages and I concur with the Unicode property escape issue. I think providing a few examples and the concepts should be enough then linking to the spec(s) (tc39 + Unicode) for a thorougher list

(unless we can use a <details> element on the page and dump a loooong table in it :s)

[chrisdavidmills]

I've added a few examples across most of the pages and I concur with the Unicode property escape issue. I think providing a few examples and the concepts should be enough then linking to the spec(s) (tc39 + Unicode) for a thorougher list

(unless we can use a <details> element on the page and dump a loooong table in it :s)

Thanks for the awesome work!

Yeah, I think deleting the long list and linking to the spec sounds like a good idea. Are you happy to handle that, or would you rather I do it? Happy either way.

I'm inclined to merge them as well (writing examples using both of them feels natural but clunky if this is documented in two distinct pages)

Cool, I'm gonna merge 'em!

[SphinxKnight]

Yeah, I think deleting the long list and linking to the spec sounds like a good idea. Are you happy to handle that, or would you rather I do it?

I'll do it while adding examples :) (still no emoji on kuma for the examples tho :p)

[chrisdavidmills]

I'll do it while adding examples :) (still no emoji on kuma for the examples tho :p)

Yay, thanks!

For emoji examples, I think we could get around the restriction by putting an example on https://github.com/mdn/js-examples/ for now, and embedding it using the EmbedGHLiveSample macro?

Cool, I'm gonna merge 'em!

This is now done. The assertions page now includes all the information that was on the boundaries page, and the latter now redirects to the former.

[SphinxKnight]

back from holiday, I'll be tackling those before the end of the week :)

[chrisdavidmills]

@SphinxKnight superb, thank you! And a happy new year to you too; hope you had fun.

[SphinxKnight]

Happy new year too @chrisdavidmills \m/ Looking forward to 2020 :)
Fun and rest, aka good holidays :)

[SphinxKnight]

After rewriting https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Unicode_Property_Escapes, a quick attempt at guessing what's left:

• [x] Insert interactive examples in the pages once they will have been merged
• [x] Add examples on https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Quantifiers
• [x] Revamp https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions to reduce the amount of duplicated content
• [x] Check String pages to fix existing links or insert new ones
• [x] Check RegExp pages to fix existing links or insert new ones

[chrisdavidmills]

Great progress here, thanks @SphinxKnight !

I've removed the draft banner from all the pages, except https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Quantifiers. I think they are all looking good and functional for now, but I wondered if the Quantifiers page still felt a bit light on examples?

[SphinxKnight]

@chrisdavidmills I went across those pages and ones about RegExp and String and added a few links here and there for cross-references. I also checked the compat data displaying thread. Let me know if some more work is needed before closing this :)

@duncan-crane sorry for the flood of messages you were (maybe) getting about this lately. As this is (I think) coming to a (good?) end, could you tell us if it is better now?

[duncan-crane]

Hi @SphinxKnight and @chrisdavidmills
I've been watching your progress with interest but thought I'd leave it until you were ready before joining the conversation. Firstly I'd like to thank you for the tremendous work. I've just read through and it it does an excellent job of guiding users in the application of regular expressions. I wish I'd had this when I first started. So full marks on that score.
I then looked at it from the point of view of being a reference guide, which is how I use this documentation most now. I think there may be a small addition which would help this aspect of the documentation without having to develop new content or change the structure.
I should perhaps explain my use case first, so you can see if my suggestion is valid and helpful.
I am currently support a mediawiki extension that allows using the TinyMCE javascript editor on mediawiki pages. This includes a javascript parser with literally hundreds of regular expressions that I need to understand, maintain or replace.
I should also add I'm a weekend coder so I frequently have to refer to the javascript reference guides to understand what's going on, especially with regular expressions.
On the current documentation page I can scroll through the tables that list all the syntax options to help me interpret any given regular expression. I tried this with the new documentation and find I'm having to flip between pages to find a given part of the syntax. This involves returning to the table which points to the pages describing different special character classes.
It may be that I'm an atypical user but in this single aspect, the new documentation is making things a bit harder for me. However, there may be a solution which maintains the excellent structure and content of your new user guide and also helps users like me.
It appears you may be using wiki software for the guide. This might enable you to use the wiki transclusion feature to create an additional page that consolidates information from the sub pages of the main guide. You might then link to this as a quick reference guide for those who might need it.
I'd suggest you wouldn't need to full text of those sub-pages, just the tables of reference information, for example that on Types in the Character Classes sub-page. If you are using mediawiki there is a stable extension which would enable you to do this very easily called Labeled Section Transclusion.
Sorry this is rather a lengthy reply but I hope it is useful. Do let me know if I can help further.
Kind regards, Duncan

[chrisdavidmills]

@SphinxKnight thanks a lot for this, your work here has been simply amazing.

@duncan-crane so basically you are saying that, as well as the separate pages, it would help your use case if we had an index of all the "Types" sections on a single page?

We could do this with the {{page}} macro.

[duncan-crane]

Yes - I think that should do it.

[SphinxKnight]

@duncan-crane I think this -newly created- https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet addresses your needs (thanks for the scenario / explanation, it never hurts to have such details :))

However I have to note that the current tooling MDN uses for transclusion (macros) is kinda being deprecated and that this cheatsheet logically uses them. In a few months/years this information may be served differently.

In the meantime, I hope this is helpful :)

@chrisdavidmills I think I'm good with this issue, I give you the final call for closing it.

[duncan-crane]

@SphinxKnight thanks so much for the solution and quick turnaround. That is precisely what I was looking for.

I did wonder if a slightly more prominent mention in the introductory paragraph of the user guide would help those who already understand the concepts of regular expressions and just want the cheat sheet :-) Perhaps something like:

For those already familiar with the concepts of regular expressions, a quick reference guide to the syntax can be found at https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet

It seems a shame that MDN have deprecated such a useful feature. Let's hope they replace it with something that is equally labour saving.
Thanks again, Duncan

[SphinxKnight]

@duncan-crane I've added a note after https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#Writing_a_regular_expression_pattern (I did not want this link to be "too early" to avoid beginners to be misleaded/not read at least a part of the whole material).

Regarding macros and "wiki" features, I put all of my precautionary conditions in this earlier "kinda". What next to come is bigger than just macros and I should not presume the specific set of features.

[duncan-crane]

Fair enough and thank you for all the stirling work. Often documenting is as hard/harder than writing the code itself :-)

[chrisdavidmills]

Cool, I think this can be closed then. Thanks all!