Add latest changes from gitlab-org/gitlab@15-9-stable-eev15.9.0-rc42

1 files changed, 67 insertions, 39 deletions

diff --git a/doc/development/gitlab_flavored_markdown/specification_guide/index.md b/doc/development/gitlab_flavored_markdown/specification_guide/index.md
index 79a4ac9b49a..806ac3837bf 100644
--- a/doc/development/gitlab_flavored_markdown/specification_guide/index.md
+++ b/doc/development/gitlab_flavored_markdown/specification_guide/index.md
@@ -514,29 +514,30 @@ of how the normalizations are specified.
 Given all the constraints above, we can summarize the various goals related to the GLFM
 specification and testing infrastructure:
 
-1. A canonical `spec.txt` exists, and represents the official specification for
-   GLFM, which meets these requirements:
-   1. The spec is a strict superset of the GitHub Flavored Markdown
+1. There is an official specification and single source of truth for how GLFM should render Markdown to HTML.
+   This source of truth is represented by three Markdown files:
+    1. [`ghfm_spec_v_?.??.md`](#github-flavored-markdown-specification) for the CommonMark + GFM examples.
+    1. [`glfm_official_specification.md`](#glfm_official_specificationmd) for the GLFM official examples.
+    1. [`glfm_internal_extensions.md`](#glfm_internal_extensionsmd) for the GLFM internal extensions.
+1. This official specification meets these requirements:
+   1. The specification is a strict superset of the GitHub Flavored Markdown
       (GFM) specification, just as
       <abbr title="GitHub Flavored Markdown">GFM</abbr> is a strict superset
       [of the CommonMark specification](https://github.github.com/gfm/#what-is-github-flavored-markdown-).
    1. Therefore, it contains the superset of all [Markdown examples](#markdown-examples)
       for CommonMark and GFM, as well as the GLFM
       [official specification](#official-specifications) and [internal extensions](#internal-extensions).
-   1. It contains a prose introduction section which is specific to GitLab and GLFM.
-   1. It contains all other non-introduction sections verbatim from the
-      [GFM specification](#github-flavored-markdown-specification).
-   1. It contains new, extra sections for all the additional Markdown contained in the GLFM
+   1. It contains sections and examples for all the additional Markdown contained in the GLFM
       [official specification](#official-specifications) and [internal extensions](#internal-extensions),
-      with [Markdown examples](#markdown-examples) and accompanying prose, just like the CommonMark and GFM examples.
-   1. All its headers and [Markdown examples](#markdown-examples) should be in the standard format which can be processed by the standard
+      with [Markdown examples](#markdown-examples) and any accompanying prose, just like the CommonMark and GFM examples.
+   1. All headers and [Markdown examples](#markdown-examples) should be in the standard format, which can be processed by the standard
       CommonMark tool [`spec_tests.py`](https://github.com/github/cmark-gfm/blob/master/test/spec_tests.py) used to perform
       [Markdown conformance testing](#markdown-conformance-testing)
       against all examples contained in a `spec.txt`.
 1. The GLFM parsers and HTML renderers for
    both the static backend (Ruby) and WYSIWYG frontend (JavaScript) implementations
    support _consistent_ rendering of all canonical Markdown + HTML examples in the
-   GLFM `spec.txt` specification, as verified by `spec_tests.py`.
+   specification, as verified by [`run-spec-tests.sh`](#run-spec-testssh-script).
 
    NOTE:
    Consistent does not mean that both of these implementations render
@@ -616,26 +617,41 @@ them from the corresponding implementation class entry point files under
 #### `update-specification.rb` script
 
 The `scripts/glfm/update-specification.rb` script uses [input specification files](#input-specification-files) to
-generate and update `spec.txt` (Markdown) and `spec.html` (HTML). The `spec.html` is
-generated by passing the generated (or updated) `spec.txt` Markdown to the backend API
-for rendering to static HTML:
+generate and update Markdown and HTML output files for the
+[`spec.txt`](#spectxt) and [`spec.html`](#spechtml)
+[output specification files](#output-specification-files) as well as the
+[`snapshot_spec.md`](#snapshot_specmd) and [`snapshot_spec.html`](#snapshot_spechtml)
+[output example snapshot files](#output-example-snapshot-files).
+
+The HTML files are created by passing the generated (or updated) Markdown to the backend API
+for rendering to HTML.
+
+```mermaid
+graph LR
+subgraph script:
+  S{update-specification.rb}
+end
+subgraph input - markdown files
+  I1[glfm_official_specification.md - GLFM official specification examples] --> S
+end
+subgraph output - specification files
+  S --> O1[spec.txt - GLFM official specification examples]
+  S --> O2[spec.html - GLFM official specification examples]
+end
+```
 
 ```mermaid
 graph LR
 subgraph script:
-  A{update-specification.rb}
-  A --> B{Backend Markdown API}
+  S{update-specification.rb}
 end
-subgraph input:<br/>input specification files
-  C[ghfm_spec_v_0.29.md] --> A
-  D[glfm_intro.md] --> A
-  E[glfm_official_specification.md] --> A
-  F[glfm_internal_extensions.md] --> A
+subgraph input - markdown files
+  I1[ghfm_spec_v_0.29.md - CommonMark and GHFM specification examples] --> S
+  I2[glfm_internal_extensions.md - GLFM internal extension examples] --> S
 end
-subgraph output:<br/>GLFM specification files
-  A --> G[spec.txt]
-  G --> B
-  B --> H[spec.html]
+subgraph output - example snapshot files
+  S --> O1[snapshot_spec.md - CommonMark, GHFM, GLFM internal extension examples]
+  S --> O2[snapshot_spec.html - CommonMark, GHFM, GLFM internal extension examples]
 end
 ```
 
@@ -655,7 +671,8 @@ script, which expects canonical HTML, against the GitLab renderer implementation
 
 `scripts/glfm/run-spec-tests.sh` is a convenience shell script which runs
 conformance specs via the CommonMark standard `spec_tests.py` script,
-which uses the `glfm_specification/output_spec/spec.txt` file and `scripts/glfm/canonicalize-html.rb`
+which uses the `ghfm_spec_v_0.29.md` and `glfm_specification/output_spec/spec.txt` files
+with the `scripts/glfm/canonicalize-html.rb`
 helper script to test the GLFM renderer implementations' support for rendering Markdown
 specification examples to canonical HTML.
 
@@ -669,7 +686,8 @@ subgraph scripts:
   end
 end
 subgraph input
-  D[spec.txt GLFM specification] --> C
+  D1[ghfm_spec_v_0.29.md GLFM specification] --> C
+  D2[spec.txt GLFM specification] --> C
   E((GLFM static<br/>renderer implementation)) --> B
   F((GLFM WYSIWYG<br/>renderer implementation)) --> B
 end
@@ -680,22 +698,28 @@ end
 
 #### `update-example-snapshots.rb` script
 
-The `scripts/glfm/update-example-snapshots.rb` script uses the GLFM
-`glfm_specification/output_spec/spec.txt` specification file and the
-`glfm_specification/input/gitlab_flavored_markdown/glfm_example_status.yml`
-file to create and update the [example snapshot](#output-example-snapshot-files)
-YAML files:
+The `scripts/glfm/update-example-snapshots.rb` script creates and updates the
+[example snapshot](#output-example-snapshot-files) YAML files.
+
+Its inputs are:
+
+- The `glfm_specification/output_spec/snapshot_spec.md` file, which contains the
+  superset of all CommonMark, GFM, and GLFM official and internal examples.
+- The `glfm_specification/input/gitlab_flavored_markdown/glfm_example_*.yml` YAML files, which
+  contain metadata to control how to generate the example snapshot files.
 
 ```mermaid
 graph LR
 subgraph script:
   A{update-example-snapshots.rb}
 end
-subgraph input:<br/>input specification file
-  B[spec.txt] --> A
-  C[glfm_example_status.yml] --> A
+subgraph input: markdown input specification files
+  B1[snapshot_spec.md] --> A
+  C1[glfm_example_status.yml] --> A
+  C2[glfm_example_normalizations.yml] --> A
+  C3[glfm_example_metadata.yml] --> A
 end
-subgraph output:<br/>example snapshot files
+subgraph output: YAML example snapshot files
   A --> E[examples_index.yml]
   A --> F[markdown.yml]
   A --> G[html.yml]
@@ -736,15 +760,15 @@ end
 subgraph script:
   A{run-snapshopt-tests.sh} -->|invokes| B
 end
+subgraph output:<br/>test results/output
+  B --> H[rspec+jest output]
+end
 subgraph input:<br/>YAML
   C[examples_index.yml] --> B
   D[markdown.yml] --> B
   E[html.yml] --> B
   F[prosemirror_json.yml] --> B
 end
-subgraph output:<br/>test results/output
-  B --> H[rspec+jest output]
-end
 ```
 
 #### `verify-all-generated-files-are-up-to-date.rb` script
@@ -1111,8 +1135,12 @@ move or copy a hosted version of the rendered HTML `spec.html` version to anothe
 is a Markdown specification file, in the standard format
 with prose and Markdown + canonical HTML examples.
 
+In the GLFM specification, `spex.txt` only contains the official specifiaction examples from
+[`glfm_official_specification.md`](#glfm_official_specificationmd). It does not contain
+the internal extension examples from [`glfm_internal_extensions.md`](#glfm_internal_extensionsmd).
+
 It also serves as input for other scripts such as
-`run-spec-tests.sh`.
+[`run-spec-tests.sh`](#run-spec-testssh-script).
 
 It is generated or updated by the `update-specification.rb` script, using the
 [input specification files](#input-specification-files) as input.