RegEx docs need improvements
- Dominant language
- No language data
- Stars
- 4.8k
- Forks
- 6.1k
- Avg merge
- 19h 10m
- Merged PRs (30d)
- 268
Description
This issue is to track and discuss improvements we can make to the regex language overview pages.
TOC starts at https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-language-quick-reference
To get the conversation started, here are some items we could potentially address.
------
### Placeholders
The placeholders use the older MSDN style where syntax was styled differently from placeholders.
Code
```markdown
`(` *subexpression* `)`
```
Result\
`(` *subexpression* `)`
#### Pros
1. The benefit of this is that the placeholder *subexpression* can be translated.
#### Cons
1. The downside to this is that it may be visually unappealing and hard to read, especially on bigger constructs:
`(?<` *name1* `-` *name2* `>` *subexpression* `)`
2. There are whitespaces introduced around the placeholder which may be confusing when looking at syntax.
#### Suggestion
The syntax could be adjusted to inline `code`. This is easier to maintain, but has the drawback of non translatable placeholders.
Code
```markdown
(subexpression)
```
Result\
`(subexpression)`
A bigger construct would look like this: `(?subexpression)`
------
### Multiline examples
Brought up in [22866](https://github.com/dotnet/docs/issues/22866#issuecomment-781633611) by @daveyostcom
The examples that use multiple code lines to break up bigger regular expressions are a bit hard to read. For example, in [grouping constructs](https://docs.microsoft.com/en-us/dotnet/standard/base-types/grouping-constructs-in-regular-expressions):
```csharp
string pattern = "^[^<>]*" +
"(" +
"((?'Open'<)[^<>]*)+" +
"((?'Close-Open'>)[^<>]*)+" +
")*" +
"(?(Open)(?!))$";
```
This example does use multiple string lines to demonstrate the different groups. Once the string is constructed, it's translated into `^[^<>]*(((?'Open'<)[^<>]*)+((?'Close-Open'>)[^<>]*)+)*(?(Open)(?!))$`.
#### Pros
1. Demonstrates grouping in an easier to read format.
#### Cons
1. You have to manage strings and multiple lines.
#### Suggestion
The code could enable the `RegexOptions.IgnorePatternWhitespace` regex option and then provide the string with white space.
```csharp
string pattern = @"
^
[^<>]*
(
( (?'Open' < ) [^<>]* )+
( (?'Close-Open' > ) [^<>]* )+
)*
(?(Open) (?!) )
$
";
```
This does provide a cleaner look to the regex code and removes the string syntax out of the way. The downsides are
1. The code has to be changed. The code examples used in these articles are still pointing to the legacy `/samples/snippets/` locations. This means moving them to the relative `snippets/markdown-file-name/` folder and potentially breaking code up into multiple projects.
2. Requires the use of a specific regex option. We do have this [option documented](https://docs.microsoft.com/dotnet/standard/base-types/regular-expression-options#ignore-white-space) though
Contributor guide
Assessment
This issue has not been assessed yet.