Add experimental code block options: highlight, strikeout, wrap, showLineNumbers

[DebugSteven]

Summary

This PR implements new code block options for line highlighting, line striking, line wrapping, and showing line numbers. When the enable-experimental-code-block flag is enabled, authors can specify options in the code block language line to control presentation:

• highlight=[1, 2, 3] — highlight the given line numbers
• strikeout=[3] — strikethrough the given line numbers
• wrap=80 — wrap code lines to the specified character width
• showLineNumbers — turn on line numbers
  These options may appear after a specified language or alone.

User Experience

With the enable-experimental-code-block flag, authors can annotate code listings with these new options using the language line.

```swift, showLineNumbers, highlight=[1, 3], strikeout=[2], wrap=80
let a = 1
deprecated() // struck out
print(a) // highlighted
```


or without a language


```highlight=[2], wrap=60
let a = 1
let b = 2
let c = 3
```



• highlight and strikeout accept 1-indexed arrays
• wrap takes an integer and applies soft wrapping at that width

Implementation Overview

• In swift-docc, this change parses showLineNumbers, highlight=[Int], strikeout=[Int], and wrap=Int from the language line in triple-backtick code blocks, where language (optionally) should be specified as the first option when it’s included.
• Adds an OptionName enum on the CodeListing struct for available options.
• Updates RenderNode.spec.json to document the new CodeListing fields.
• Adds Utility/ParseLanguageString.swift for parsing the language string and option arrays.
• Extends the InvalidCodeBlockOption checker to identify typos in options, suggest an unknown option might be the language (when it’s not placed first), and validate array indices for highlight and strikeout are within the bounds of a code block.

Dependencies

This PR builds on top of #1273 and depends on associated changes in swift-docc-render to actually render and handle the highlight, strikeout, wrap, and showLineNumbers options. The associated swift-docc-render PR is here: swiftlang/swift-docc-render#965

Testing

Setup

Use the additional-metadata branches for swift-docc and swift-docc-render with the new highlight, strikeout, wrap and showLineNumbers changes.
Rebuild documentation using swift-docc and the feature flag enable-experimental-code-block. Serve it using a local build of swift-docc-render.

How to Test

1. In any code listing using ``` or by adding a code listing, add the highlight, `strikeout`, `wrap` and/or `showLineNumbers` options after the language (optionally) like this:

```swift, showLineNumbers, highlight=[1,3,4], strikeout=[2, 3], wrap=40
let a = 1
let b = 2
let c = 3
let d = 4
```

2. Confirm highlighted lines and struck-through lines have the correct styling
3. Confirm that wrapping is styled with the configured width.
4. Confirm the show line number option shows line numbers.
5. Confirm these options can be combined and are styled correctly.
6. Verify the above behavior with and without a language token in the language line.

Checklist

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary - Updated RenderNode.spec.json, holding off on documentation for experimental features

These new options looks like the below:

Compared to without these options:

[heckj]

@swift-ci please test

[heckj]

@swift-ci please test

[d-ronnqvist]

There's a few places of either API breaking changes or API that's designed in a way where it's likely to break in the future. That needs to be addressed.

Also, I have serious concerns about the way that the new code block attributes is encoded in the Render Node specification. We don't have a process for handling breaking changes to that specification today, so that format needs to be rethought to ensure that it's flexible and extensible for the type of information we want to encode there.

[d-ronnqvist]

This is going to be quite limiting going forward. If we require in public API that the highlight is a list of integers then we can't represent partially highlighted lines without either:

• API breaking changes
• having to different arrays for different types of highlights.

[d-ronnqvist]

Also, with this API design, each time we need to add a new type of highlight we need to add a new public property. It would be more flexible if this was represented differently (for example making the style a property of the "highlight").

[d-ronnqvist]

Similar to the API design, I have serious concerns about this scaling to either new styles of highlight style or partial highlight ranges.

Unlike the Swift API, we have no process at all for breaking changes to the Render Node specification so we need to really think this through so that the JSON format is flexible and extensible for the type of information we want to encode here.

[d-ronnqvist]

Although this is rather technical, it might be good to discuss this in the forums to get greater visibility and to get inputs from a wider audience.

[heckj]

Reference to forums discussion: https://forums.swift.org/t/rfc-additional-options-for-code-blocks-highlight-strikeout-wrap-line-numbers/82065/11