[Docs] Replace recommonmark with myst-parser

[luke]

Summary

Now that recommonmark is deprecated https://github.com/readthedocs/recommonmark/issues/221,
myst-parser seems to be the generally accepted drop in replacement.
This swaps recommonmark out of the sphinx config and upgrades any
markdown document that needs adjustment due to myst-parser's stricter
parsing.
In particular, these things needed addressed as myst-parser complained
about them:

• Broken references were replaced
• Invalid lexers in code blocks were replaced or removed (It didn't look like they were being syntax highlighted anyway)
• Non-contiguous headers (# -> #) were made contiguous (# -> )

Closes #55787

[luke]

flang/docs/DiagnosticsReference.md

2

This is pretty hairy and it will link users to a blank document. Open to any other ideas to workaround this

[tstellar]

flang/docs/ComplexOperations.md

37

Do these changes have any affected on the output html? Is there another way to specify the language?

[luke]

flang/docs/ComplexOperations.md

37

I’m not sure, I think I might be able to add this back in though since I suppressed a warning about highlight errors.
I had to remove the ones that specified MLIR as the lexer though since there didn’t seem to be an option to suppress those warnings. They didn’t seem to receive any syntax highlighting in the output html anyway

[luke]

flang/docs/ComplexOperations.md

37

Looks like these weren't being highlighted anyway: https://flang.llvm.org/docs/ComplexOperations.html?highlight=complex#fir-representation

Ideally there would eventually be an MLIR lexer added to pygments. Until then is it better to remove the incorrect lexers?

[luke]

Don't suppress misc.highlighting_failure warning

Instead just fix the flang code block that was failing to highlight

[tstellar]

LGTM. Can you add something to the release notes about this.

[luke]

Update release notes

[luke]

In D142199#4073815, @tstellar wrote:

LGTM. Can you add something to the release notes about this.

Done. Do any build machines need to be upgraded before this is landed?

[kiranchandramohan]

The flang website (flang.llvm.org) or flang.llvm.org/docs are built from these. Would you know whether there are changes required are there? https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/SphinxDocsBuilder.py

[luke]

In D142199#4076287, @kiranchandramohan wrote:

The flang website (flang.llvm.org) or flang.llvm.org/docs are built from these. Would you know whether there are changes required are there? https://github.com/llvm/llvm-zorg/blob/main/zorg/buildbot/builders/SphinxDocsBuilder.py

The docs-flang-html target should remain the same, I quickly checked that script and it seems fine. The main thing is that the builders would need to have myst-parser installed on them. Are these python dependencies installed via a script or is it done manually?

[tstellar]

@luke You'll need to contact the bot owners so they can update machine. The workers running the publish-sphinx-docs will need to be updated too. @gkistanova should be able to help.

.github/workflows/release-tasks.yml

- name: Validate Tag
         echo "::set-output name=release-version::$release_version"
 
     - name: Install Dependencies
       run: |
         sudo apt-get install -y \
             doxygen \
             graphviz \
             python3-github \
-            python3-recommonmark \
+            python3-myst-parser \
             python3-sphinx \
             ninja-build \
             texlive-font-utils
         pip3 install --user sphinx-markdown-tables
 
     - name: Checkout LLVM
       uses: actions/checkout@v3
 

clang/docs/conf.py

 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = {
     '.rst': 'restructuredtext',
 }
 
 try:
-  import recommonmark
+  import myst_parser
 except ImportError:
   # manpages do not use any .md sources
   if not tags.has('builder-man'):
     raise
 else:
   import sphinx
   if sphinx.version_info >= (3, 0):
     # This requires 0.5 or later.
-    extensions.append('recommonmark')
+    extensions.append('myst_parser')
   else:
-    source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+    source_parsers = {'.md': 'myst_parser.parsers.sphinx_.MystParser'}
   source_suffix['.md'] = 'markdown'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 

flang/docs/ComplexOperations.md

 function pow_self(c)
   complex, intent(in) :: c
   complex :: pow_self
   pow_self = c ** c
 end function pow_self
 ```
 
 **FIR**
-```c
+```
 func.func @_QPpow_self(%arg0: !fir.ref<!fir.complex<4>>) -> !fir.complex<4> {
     %0 = fir.alloca !fir.complex<4>
     %1 = fir.load %arg0 : !fir.ref<!fir.complex<4>>
     %2 = fir.load %arg0 : !fir.ref<!fir.complex<4>>
     %3 = fir.convert %1 : (!fir.complex<4>) -> complex<f32>
     %4 = fir.convert %2 : (!fir.complex<4>) -> complex<f32>
     %5 = complex.pow %3, %4 : complex<f32>
     %6 = fir.convert %5 : (complex<f32>) -> !fir.complex<4>

flang/docs/DiagnosticsReference.md

+% This file intentionally left blank. Silences a warning about a missing reference from the automatically generated FlangCommandLineReference.rst

flang/docs/FIRArrayOperations.md

 
 One can use `fir.array_load` to produce an ssa-value that captures an
 immutable value of the entire array `a`, as in the Fortran array expression
 shown above. Subsequent changes to the memory containing the array do not
 alter its composite value. This operation lets one load an array as a
 value while applying a runtime shape, shift, or slice to the memory
 reference, and its semantics guarantee immutability.
 
-```mlir
+```
 %s = fir.shape_shift %lb1, %ex1, %lb2, %ex2 : (index, index, index, index) -> !fir.shapeshift<2>
 // load the entire array 'a'
 %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shapeshift<2>) -> !fir.array<?x?xf32>
 // a fir.store here into array %a does not change %v
 ```
 
 # array_merge_store
 
 The `array_merge_store` operation stores a merged array value to memory. 
 
 
 ```fortran
   real :: a(n,m)
   ...
   a = ...
 ```
 
 One can use `fir.array_merge_store` to merge/copy the value of `a` in an
 array expression as shown above.
 
-```mlir
+```
   %v = fir.array_load %a(%shape) : ...
   %r = fir.array_update %v, %f, %i, %j : (!fir.array<?x?xf32>, f32, index, index) -> !fir.array<?x?xf32>
   fir.array_merge_store %v, %r to %a : !fir.ref<!fir.array<?x?xf32>>
 ```
 
 This operation merges the original loaded array value, `%v`, with the
 chained updates, `%r`, and stores the result to the array at address, `%a`.
 
```fortran
   ... a ...
   ... a(r,s+1) ...
 ```
 
 One can use `fir.array_fetch` to fetch the (implied) value of `a(i,j)` in
 an array expression as shown above. It can also be used to extract the
 element `a(r,s+1)` in the second expression.
 
-```mlir
+```
   %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
   // load the entire array 'a'
   %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>) -> !fir.array<?x?xf32>
   // fetch the value of one of the array value's elements
   %1 = fir.array_fetch %v, %i, %j : (!fir.array<?x?xf32>, index, index) -> f32
 ```
 
 It is only possible to use `array_fetch` on an `array_load` result value or a
```fortran
   real :: a(n,m)
   ...
   a = ...
 ```
 
 One can use `fir.array_update` to update the (implied) value of `a(i,j)`
 in an array expression as shown above.
 
-```mlir
+```
   %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
   // load the entire array 'a'
   %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>) -> !fir.array<?x?xf32>
   // update the value of one of the array value's elements
   // %r_{ij} = %f  if (i,j) = (%i,%j),   %v_{ij} otherwise
   %r = fir.array_update %v, %f, %i, %j : (!fir.array<?x?xf32>, f32, index, index) -> !fir.array<?x?xf32>
   fir.array_merge_store %v, %r to %a : !fir.ref<!fir.array<?x?xf32>>
 ```
```fortran
   ... a(r,s+1) ...
 ```
 
 One can use `fir.array_access` to recover the implied memory reference to
 the element `a(i,j)` in an array expression `a` as shown above. It can also
 be used to recover the reference element `a(r,s+1)` in the second
 expression.
 
-```mlir
+```
   %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
   // load the entire array 'a'
   %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>) -> !fir.array<?x?xf32>
   // fetch the value of one of the array value's elements
   %1 = fir.array_access %v, %i, %j : (!fir.array<?x?xf32>, index, index) -> !fir.ref<f32>
 ```
 
 It is only possible to use `array_access` on an `array_load` result value or a

 
 ## array_amend
 
 The `array_amend` operation marks an array value as having been changed via a 
 reference obtain by an `array_access`. It acts as a logical transaction log
 that is used to merge the final result back with an `array_merge_store`
 operation.
 
-```mlir
+```
   // fetch the value of one of the array value's elements
   %1 = fir.array_access %v, %i, %j : (!fir.array<?x?xT>, index, index) -> !fir.ref<T>
   // modify the element by storing data using %1 as a reference
   %2 = ... %1 ...
   // mark the array value
   %new_v = fir.array_amend %v, %2 : (!fir.array<?x?xT>, !fir.ref<T>) -> !fir.array<?x?xT>
 ```
 

flang/docs/FlangDriver.md

 | ![Frontend Driver](frontend_driver.png) |
 |:-:|
 | *Flang's frontend driver and the **libraries** that it drives* |
 
 Note that similarly to `-Xclang` in `clang`, you can use `-Xflang` to forward a
 frontend specific flag from the _compiler_ directly to the _frontend_ driver,
 e.g.:
 
-```lang=bash
+```bash
 flang-new -Xflang -fdebug-dump-parse-tree input.f95
 ```
 
 In the invocation above, `-fdebug-dump-parse-tree` is forwarded to `flang-new
 -fc1`. Without the forwarding flag, `-Xflang`, you would see the following
 warning:
 
-```lang=bash
+```bash
 flang-new: warning: argument unused during compilation:
 ```
 
 As `-fdebug-dump-parse-tree` is only supported by `flang-new -fc1`, `flang-new`
 will ignore it when used without `Xflang`.
 
 ## Why Do We Need Two Drivers?
 As hinted above, `flang-new` and `flang-new -fc1` are two separate tools. The

flang/docs/HighLevelFIR.md

 subroutine foo(a, b)
   real :: a(:), b(:)
   a = b
 end subroutine
 ```
 
 Lowering output:
 
-```HLFIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   hlfir.assign %b#0 to %a#0 : !fir.box<!fir.array<?xf32>>
   return
 }
 ```
 
 HLFIR array assignment lowering pass:
 -   Query: can %b value depend on %a? No, they are two different argument
     associated variables that are neither target nor pointers.
 -   Lower to assignment to loop:
 
-```HFLIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
 
   %ashape = hlfir.shape_of %a#0
   %bshape = hlfir.shape_of %b#0
   %shape = hlfir.shape_meet %ashape, %bshape
   %extent = hlfir.get_extent %shape, 0
subroutine foo(a, b, p, c)
   real :: b(:), c(100)
   real, pointer :: p(:)
   a = b*p + c
 end subroutine
 ```
 
 Lowering output:
 
-```HLFIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box<!fir.array<?xf32>, !fir.box<!fir.array<?xf32>
   %b =  hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   %p = hlfir.declare %arg2 {fir.def = "_QPfooEp", fir.ptr} : !fir.box<!fir.ptr<!fir.array<?xf32>>>, !fir.box<!fir.ptr<!fir.array<?xf32>>>
   %c =  hlfir.declare %arg3 {fir.def = "_QPfooEc"} : !fir.ref<!fir.array<100xf32>>, !fir.ref<!fir.array<100xf32>>
   %bshape = hlfir.shape_of %b#0
   %pshape = hlfir.shape_of %p#0
   %shape1 = hlfir.shape_meet %bshape, %pshape
func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   return
 }
 ```
 
 Step 1: hlfir.elemental inlining: inline the first hlfir.elemental into the
 second one at the hlfir.apply.
 
 
-```HLFIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box<!fir.array<?xf32>, !fir.box<!fir.array<?xf32>
   %b =  hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   %p = hlfir.declare %arg2 {fir.def = "_QPfooEp", fir.ptr} : !fir.box<!fir.ptr<!fir.array<?xf32>>>, !fir.box<!fir.ptr<!fir.array<?xf32>>>
   %c =  hlfir.declare %arg3 {fir.def = "_QPfooEc"} : !fir.ref<!fir.array<100xf32>>, !fir.ref<!fir.array<100xf32>>
   %bshape = hlfir.shape_of %b#0
   %pshape = hlfir.shape_of %p#0
   %shape1 = hlfir.shape_meet %bshape, %pshape
-   Gather references to %b, %p, and %c. %p is a pointer variable according to
     yes.
 -   Insert temporary, and duplicate array assignments, that can be lowered to
     loops at that point
 
 Note that the alias analysis could have already occurred without inlining the
 %add hlfir.elemental.
 
 
-```HLFIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box<!fir.array<?xf32>, !fir.box<!fir.array<?xf32>
   %b =  hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   %p = hlfir.declare %arg2 {fir.def = "_QPfooEp", fir.ptr} : !fir.box<!fir.ptr<!fir.array<?xf32>>>, !fir.box<!fir.ptr<!fir.array<?xf32>>>
   %c =  hlfir.declare %arg3 {fir.def = "_QPfooEc"} : !fir.ref<!fir.array<100xf32>>, !fir.ref<!fir.array<100xf32>>
   %bshape = hlfir.shape_of %b#0
   %pshape = hlfir.shape_of %p#0
   %shape1 = hlfir.shape_meet %bshape, %pshape
func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   fir.freemem %tempstorage
   return
 }
 ```
 
 Step 4: Lower assignments to regular loops since they have the no_overlap
 attribute, and inline the hlfir.elemental into the first loop nest.
 
-```HLFIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box<!fir.array<?xf32>, !fir.box<!fir.array<?xf32>
   %b =  hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.box<!fir.array<?xf32>>
   %p = hlfir.declare %arg2 {fir.def = "_QPfooEp", fir.ptr} : !fir.box<!fir.ptr<!fir.array<?xf32>>>, !fir.box<!fir.ptr<!fir.array<?xf32>>>
   %c =  hlfir.declare %arg3 {fir.def = "_QPfooEc"} : !fir.ref<!fir.array<100xf32>>, !fir.ref<!fir.array<100xf32>>
   %bshape = hlfir.shape_of %b#0
   %pshape = hlfir.shape_of %p#0
   %shape1 = hlfir.shape_meet %bshape, %pshape

 ```
 
 Step 5 (may also occur earlier or several times): shape propagation.
 -   %shape2 can be inferred from %cshape that has constant shape: the
     hlfir.shape_meet results can be replaced by it, and if the option is set,
     conformance checks can be added for %a, %b and %p.
 -   %temp is small, and its fir.allocmem can be promoted to a stack allocation
 
-```HLFIR
+```
 func.func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>, %arg1: !fir.box<!fir.array<?xf32>>, %arg2: !fir.box<!fir.ptr<!fir.array<?xf32>>>, %arg3: !fir.ref<!fir.array<100xf32>>) {
   // .....
   %cshape = fir.shape %c100
   %extent = %c100
   // updated fir.alloca
   %tempstorage = fir.alloca %extent : fir.ref<fir.array<100xf32>>
   %temp = hlfir.declare %tempstorage, shape %extent {fir.def = QPfoo.temp001} : (index) -> fir.box<fir.array<?xf32>>, fir.heap<fir.array<?xf32>>
   fir.do_loop %i = %c1 to %c100 step %c1 unordered {

 - vector subscripted entities would be lowered as a hlfir.elemental implementing
   the vector subscript addressing.
 - If the vector appears in a context where it can be modified (which can only
   be an assignment LHS, or in input IO), lowering could transform the
   hlfir.elemental into hlfir.forall (for assignments), or a fir.iter_while (for
   input IO) by inlining the elemental body into the created loops, and
   identifying the hlfir.designate producing the result.
 
-```HFLFIR
+```
 func.func @_QPfoo(%arg0: !fir.ref<!fir.array<?xf32>>, %arg1: !fir.ref<!fir.array<?xf32>>, %arg2: !fir.box<<!fir.array<?xi32>>) {
   %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} : !fir.box<!fir.array<?xf32>>, !fir.ref<!fir.array<?xf32>>
   %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box<!fir.array<?xf32>>, !fir.ref<!fir.array<?xf32>>
   %v = hlfir.declare %arg2 {fir.def = "_QPfooEv"} : !fir.box<!fir.array<?xi32>>, !fir.box<!fir.array<?xi32>>
   %vshape = hlfir.shape_of %v : fir.shape<1>
   %bsection =  hlfir.elemental(%i:index) %vshape : (fir.shape<1>) -> hlfir.expr<?xf32> {
     %v_elt = hlfir.designate %v#0, %i : (!fir.box<!fir.array<?xi32>>, index) -> fir.ref<i32>
     %v_val = fir.load %v_elt : fir.ref<i32>

flang/docs/OptionComparison.md

 <!--===- docs/OptionComparison.md 
   
    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
    See https://llvm.org/LICENSE.txt for license information.
    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   
 -->
 
 # Compiler options comparison
 
-This document catalogs the options processed by F18's peers/competitors.  Much of the document is taken up by a set of tables that list the options categorized into different topics.  Some of the table headings link to more information about the contents of the tables.  For example, the table on **Standards conformance** options links to [notes on Standards conformance](#standards).
+This document catalogs the options processed by F18's peers/competitors.  Much of the document is taken up by a set of tables that list the options categorized into different topics.  Some of the table headings link to more information about the contents of the tables.  For example, the table on **Standards conformance** options links to [notes on Standards conformance](standards).
 
 **There's also important information in the ___[Appendix section](#appendix)___ near the end of the document on how this data was gathered and what ___is___ and ___is not___ included in this document.**  
 
 Note that compilers may support language features without having an option for them.  Such cases are frequently, but not always noted in this document.
 
 ## Categorization of Options
 
 <table>
<table>
    </td>
   </tr>
 </table>
 
 
 
 ## Notes
 
-**<a name="standards"></a>Standards conformance:** 
+(standards)=
+**Standards conformance:** 
 
 All conformance options are similar -- they issue warnings if non-standard features are used.  All defaults are to allow extensions without warnings.  The GNU, IBM, and Intel compilers allow multiple standard levels to be specified.
 
 
 
 *   **Cray**: The capital "-eN" option specifies to issue error messages for non-compliance rather than warnings.  
 *   **GNU:** The "std=_level_" option specifies the standard to which the program is expected to conform.   The default value for std is 'gnu', which specifies a superset of the latest Fortran standard that includes all of the extensions supported by GNU Fortran, although warnings will be given for obsolete extensions not recommended for use in new code. The 'legacy' value is equivalent but without the warnings for obsolete extensions. The 'f95', 'f2003', 'f2008', and 'f2018' values specify strict conformance to the respective standards.  Errors are given for all extensions beyond the relevant language standard, and warnings are given for the Fortran 77 features that are permitted but obsolescent in later standards. '-std=f2008ts' allows the Fortran 2008 standard including the additions of the Technical Specification (TS) 29113 on Further Interoperability of Fortran with C and TS 18508 on Additional Parallel Features in Fortran.  Values for "_level_" are f_95, f2003, f2008, f2008ts, f2018, gnu,_ and _legacy._
 

flang/docs/ParameterizedDerivedTypes.md

 _note: C750 and C754 are partially enforced in the semantic at the moment._
 
 These expressions can be lowered into small simple functions. For example,
 the offset of `fld1` in `len_type1` could be 0; its size would be computed as
 `sizeof(char) * (i+j)`. `size` can be lowered into a compiler generated
 function.
 
 **FIR**
-```c
+```
 // Example of compiler generated functions to compute offsets, size, etc.
 // This is just an example and actual implementation might have more functions.
 
 // name field offset.
 func.func @_len_type3.offset.name() -> index {
   %0 = arith.constant 0 : index
   return %0 : index
 }

 ```
 
 Access a field
 ```fortran
 pdt_inlined_array(1)%field%fld2
 ```
 
 Example of offset computation in the PDTs.
-```c
+```
 %0 = call @_len_type3.field.typeparam.1(%i, %j) : (index, index) -> index
 %1 = call @_len_type3.field.typeparam.2(%i, %j) : (index, index) -> index
 %2 = call @_len_type3.offset.fld(%i, %j) : (index, index) -> index
 %3 = call @_len_type1.offset.fld2(%0, %1) : (index, index) -> index
 %offset_of_1st_element = arith.addi %2, %3 : index
 // Use the value computed offset_of_1st_element
 ```
 

 p => a(:)%i(5)
 ```
 
 When making a new descriptor like for pointer association, the `field_index`
 operation can take the length type parameters needed for size/offset
 computation.
 
 **FIR**
-```c
+```
 %5 = fir.field_index i, !fir.type<_QMmod1Tt{l:i32,i:!fir.array<?xi32>}>(%n : i32)
 ```
 
 ### Length type parameter with expression
 
 The component of a PDT can be defined with expressions including the length
 type parameters.
 

 with a compiler generated name and a default value of `n*m`. All instance of the
 expression would then reference the new name.
 
 **Fortran**
 ```fortran
 type t1(n, m)
   integer, len :: n = 2
   integer, len :: m = 4
-  integer, len :: _t1_n_m = 8 ! hidden extra length type parameter
-  real :: data(_t1_n_m)
+  integer, len :: t1_n_m = 8 ! hidden extra length type parameter
+  real :: data(t1_n_m)
 end type
 ```
 
 At any place where the a PDT is initialized, the lowering would make the
 evaluation and their values saved in the addendum and pointed to by the
 descriptor.
 
 ### `ALLOCATE`/`DEALLOCATE` statements

 type(t1), allocatable :: t
 type(t1), pointer :: p
 
 allocate(t1(2)::t)
 allocate(t1(2)::p)
 ```
 
 **FIR**
-```c
+```
 // For allocatable
 %5 = fir.call @_FortranAAllocatableInitDerived(%desc, %type) : (!fir.box<none>, ) -> ()
 // The AllocatableSetDerivedLength functions is called for each length type parameters.
 %6 = fir.call @_FortranAAllocatableSetDerivedLength(%desc, %pos, %value) : (!fir.box<none>, i32, i64) -> ()
 %7 = fir.call @_FortranAAllocatableAllocate(%3) : (!fir.box<none>) -> ()
 
 // For pointer
 %5 = fir.call @_FortranAPointerNullifyDerived(%desc, %type) : (!fir.box<none>, ) -> ()
 // The PointerSetDerivedLength functions is called for each length type parameters.
 %6 = fir.call @_FortranAPointerSetDerivedLength(%desc, %pos, %value) : (!fir.box<none>, i32, i64) -> ()
 %7 = fir.call @_FortranAPointerAllocate(%3) : (!fir.box<none>) -> ()
 ```
 
 `DEALLOCATE`
 
 The `DEALLOCATE` statement is lowered to a runtime call to
 `AllocatableDeallocate` and `PointerDeallocate` for pointers.
 
 **Fortran**
 ```fortran
 deallocate(pdt1)
 ```
 
 **FIR** 
-```c
+```
 // For allocatable
 %8 = fir.call @_FortranAAllocatableDeallocate(%desc1) : (!fir.box<none>) -> (i32)
 
 // For pointer
 %8 = fir.call @_FortranAPointerDeallocate(%desc1) : (!fir.box<none>) -> (i32)
 ```
 
 ### `NULLIFY`
 
 The `NULLIFY` statement is lowered to a call to the corresponding runtime
 function `PointerNullifyDerived` in `flang/include/flang/Runtime/pointer.h`.
 
 **Fortran**
 ```fortran
 NULLIFY(p)
 ```
 
 **FIR**
-```c
+```
 %0 = fir.call @_FortranAPointerNullifyDerived(%desc, %type) : (!fir.box<none>, !fir.tdesc) -> ()
 ```
 
 ### Formatted I/O
 
 The I/O runtime internals are described in this file:
 `flang/docs/IORuntimeInternals.md`.
 

 
 subroutine print_pdt
   type(t(10)) :: x
   print*, x
 end subroutine
 ```
 
 **FIR**
-```c
+```
 func.func @_QMpdtPprint_pdt() {
   %l = arith.constant = 10
   %0 = fir.alloca !fir.type<_QMpdtTt{l:i32,i:!fir.array<?xi32>}> (%l : i32) {bindc_name = "x", uniq_name = "_QMpdt_initFlocalEx"}
   %1 = fir.embox %0 : (!fir.ref<!fir.type<_QMpdtTt{l:i32,i:!fir.array<?xi32>}>>) (typeparams %l : i32) -> !fir.box<!fir.type<_QMpdt_initTt{l:i32,i:!fir.array<2xi32>}>> 
   %2 = fir.address_of(@_QQcl.2E2F6669725F7064745F6578616D706C652E66393000) : !fir.ref<!fir.char<1,22>>
   %c8_i32 = arith.constant 8 : i32
   %3 = fir.convert %1 : (!fir.box<!fir.type<_QMpdtTt{l:i32,i:!fir.array<?xi32>}>>) -> !fir.box<none>
   %4 = fir.convert %2 : (!fir.ref<!fir.char<1,22>>) -> !fir.ref<i8>

 
 #### `fir.alloca`
 
 This primitive operation is used to allocate an object on the stack. When
 allocating a PDT, the length type parameters are passed to the
 operation so its size can be computed accordingly.
 
 **FIR**
-```c
+```
 %i = arith.constant 10 : i32
 %0 = fir.alloca !fir.type<_QMmod1Tpdt{i:i32,data:!fir.array<?xf32>}> (%i : i32)
 // %i is the ssa value of the length type parameter
 ```
 
 #### `fir.allocmem`
 
 This operation is used to create a heap memory reference suitable for storing a
 value of the given type. When creating a PDT, the length type parameters are
 passed so the size can be computed accordingly.
 
 **FIR**
-```c
+```
 %i = arith.constant 10 : i32
 %0 = fir.alloca !fir.type<_QMmod1Tpdt{i:i32,data:!fir.array<?xf32>}> (%i : i32)
 // ...
 fir.freemem %0 : !fir.type<_QMmod1Tpdt{i:i32,data:!fir.array<?xf32>}>
 ```
 
 #### `fir.embox`
 
 The `fir.embox` operation create a boxed reference value. In the case of PDTs
 the length type parameters can be passed as well to the operation.
 
 **Fortran**
 ```fortran
 subroutine local()
   type(t(2)) :: x ! simple local PDT
   ! ...
 end subroutine
 ```
 
 **FIR**
-```c
+```
 func.func @_QMpdt_initPlocal() {
   %c2_i32 = arith.constant 2 : i32
   %0 = fir.alloca !fir.type<_QMpdt_initTt{l:i32,i:!fir.array<?xi32>}> (%c2 : i32)
        {bindc_name = "x", uniq_name = "_QMpdt_initFlocalEx"}
   // The fir.embox operation is responsible to place the provided length type
   // parameters in the descriptor addendum so they are available to the runtime
   // call later.
   %1 = fir.embox %0 : (!fir.ref<!fir.type<_QMpdt_initTt{l:i32,i:!fir.array<?xi32>}>>) (typeparams %c2 : i32)

 
 #### `fir.field_index`
 
 The `fir.field_index` operation is used to generate a field offset value from
 a field identifier in a derived-type. The operation takes length type parameter
 values with a PDT so it can compute a correct offset.
 
 **FIR**
-```c
+```
 %l = arith.constant 10 : i32
 %1 = fir.field_index i, !fir.type<_QMpdt_initTt{l:i32,i:i32}> (%l : i32)
 %2 = fir.coordinate_of %ref, %1 : (!fir.type<_QMpdt_initTt{l:i32,i:i32}>, !fir.field) -> !fir.ref<i32>
 %3 = fir.load %2 : !fir.ref<i32>
 return %3
 ```
 
 #### `fir.len_param_index`
 
 This operation is used to get the length type parameter offset in from a PDT.
 
 **FIR**
-```c
+```
 func.func @_QPpdt_len_value(%arg0: !fir.box<!fir.type<t1{l:i32,!fir.array<?xi32>}>>) -> i32 {
   %0 = fir.len_param_index l, !fir.box<!fir.type<t1{l:i32,!fir.array<?xi32>}>>
   %1 = fir.coordinate_of %arg0, %0 : (!fir.box<!fir.type<t1{l:i32,!fir.array<?xi32>}>>, !fir.len) -> !fir.ref<i32>
   %2 = fir.load %1 : !fir.ref<i32>
   return %2 : i32
 }
 ```
 
 #### `fir.save_result`
 
 Save the result of a function returning an array, box, or record type value into
 a memory location given the shape and LEN parameters of the result. Length type
 parameters is passed if the PDT is not boxed.
 
 **FIR**
-```c
+```
 func.func @return_pdt(%buffer: !fir.ref<!fir.type<t2(l1:i32,l2:i32){x:f32}>>) {
   %l1 = arith.constant 3 : i32
   %l2 = arith.constant 5 : i32
   %res = fir.call @foo() : () -> !fir.type<t2(l1:i32,l2:i32){x:f32}>
   fir.save_result %res to %buffer typeparams %l1, %l2 : !fir.type<t2(l1:i32,l2:i32){x:f32}>, !fir.ref<!fir.type<t2(l1:i32,l2:i32){x:f32}>>, i32, i32
   return
 }
 ```
 
 #### `fir.array_*` operations
 
 The current design of the different `fir.array_*` operations include length type
 parameters operands. This is designed to use PDT without descriptor directly in
 FIR.
 
 **FIR**
-```c
+```
 // Operation used with a boxed PDT does not need the length type parameters as
 // they are directly retrieved from the box.
 %0 = fir.array_coor %boxed_pdt, %i, %j  (fir.box<fir.array<?x?xfir.type<!fir.type<_QMpdt_initTt{l:i32,i:!fir.array<?xi32>}>>>>, index, index) -> !fir.ref<fir.type<!fir.type<_QMpdt_initTt{l:i32,i:!fir.array<?xi32>}>>>
 
 // In case the PDT would not be boxed, the length type parameters are needed to
 // compute the correct addressing.
 %0 = fir.array_coor %pdt_base, %i, %j typeparams %l  (fir.ref<fir.array<?x?xfir.type<!fir.type<_QMpdt_initTt{l:i32,i:!fir.array<?xi32>}>>>>, index, index, index) -> !fir.ref<fir.type<PDT>>
 ```

flang/docs/PolymorphicEntities.md

 
 subroutine foo(p)
   class(point) :: p
   ! code of the subroutine
 end subroutine
 ```
 
 **FIR**
-```c
+```
 func.func @foo(%p : !fir.class<!fir.type<_QTpoint{x:f32,y:f32}>>)
 ```
 
 ### Unlimited polymorphic entities `CLASS(*)`
 
 The unlimited polymorphic entity is represented as a class type with `none` as
 element type.
 
 **Fortran**
 ```fortran
 subroutine bar(x)
   class(*) :: x
   ! code of the subroutine
 end subroutine
 ```
 
 **FIR**
-```c
+```
 func.func @bar(%x : !fir.class<none>)
 ```
 
 ### Assumed-type `TYPE(*)`
 
 Assumed type is added in Fortran 2018 and it is available only for dummy
 arguments. It's mainly used for interfaces to non-Fortran code and is similar
 to C's `void`.

 example.
 
 **Fortran**
 ```fortran
 get_all_area = get_all_area + shapes(i)%item%get_area()
 ```
 
 **FIR**
-```c
+```
 %1 = fir.convert %0 : !fir.ref<!fir.class<!fir.type<_QMgeometryTtriangle{color:i32,isFilled:!fir.logical<4>,base:f32,height:f32>>>
 %2 = fir.dispatch "get_area"(%1 : !fir.class<!fir.type<_QMgeometryTtriangle{color:i32,isFilled:!fir.logical<4>,base:f32,height:f32>>) -> f32
 ```
 
 The type information is stored in the `f18Addendum` of the descriptor. The
 format is defined in `flang/runtime/type-info.h` and part of its representation
 in LLVM IR is shown below. The binding is comparable to a vtable. Each derived
 type has a complete type-bound procedure table in which all of the bindings of
 its ancestor types appear first.
 
 **LLVMIR**
 
 Representation of the derived type information with the bindings.
-```c
+```
 %_QM__fortran_type_infoTderivedtype = type { { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8 }, i64, { ptr, i64, i32, i8, i8, i8, i8, ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, i32, i8, i8, i8, i8, [4 x i8] }
 %_QM__fortran_type_infoTbinding = type { %_QM__fortran_builtinsT__builtin_c_funptr, { ptr, i64, i32, i8, i8, i8, i8 } }
 %_QM__fortran_builtinsT__builtin_c_funptr = type { i64 }
 ```
 
 The `fir.dispatch` is then lowered to use the runtime information to extract the
 correct function from the vtable and to perform the actual call. Here is
 what it can look like in pseudo LLVM IR code.
 
 **LLVMIR**
-```c
+```
 // Retrieve the bindings (vtable) from the type information from the descriptor
 %1 = call %_QM__fortran_type_infoTbinding* @_FortranAGetBindings(%desc)
 // Retrieve the position of the specific bindings in the table
 %2 = call i32 @_FortranAGetBindingOffset(%1, "get_area")
 // Get the binding from the table
 %3 = getelementptr %_QM__fortran_type_infoTbinding, %_QM__fortran_type_infoTbinding* %1, i32 0, i32 %2
 // Get the function pointer from the binding
 %4 = getelementptr %_QM__fortran_builtinsT__builtin_c_funptr, %_QM__fortran_type_infoTbinding %3, i32 0, i32 0

 END TYPE
 ```
 
 1) Dummy argument is fixed type and actual argument is fixed type.
     - `TYPE(t1)` to `TYPE(t1)`: Nothing special to take into consideration.
 2) Dummy argument is polymorphic and actual argument is fixed type. In these
    cases, the actual argument need to be boxed to be passed to the
    subroutine/function since those are expecting a descriptor.
-   ```c
+   ```
    func.func @_QMmod1Ps(%arg0: !fir.class<!fir.type<_QMmod1Tshape{x:i32,y:i32}>>)
    func.func @_QQmain() {
      %0 = fir.alloca !fir.type<_QMmod1Tshape{x:i32,y:i32}> {uniq_name = "_QFEsh"}
      %1 = fir.embox %0 : (!fir.ref<!fir.type<_QMmod1Tshape{x:i32,y:i32}>>) -> !fir.class<!fir.type<_QMmod1Tshape{x:i32,y:i32}>>
      fir.call @_QMmod1Ps(%1) : (!fir.class<!fir.type<_QMmod1Tshape{x:i32,y:i32}>>) -> ()
      return
    }
    ```

 
 **Fortran**
 ```fortran
 type(t) :: x
 write(10), x
 ```
 
 **FIR**
-```c
+```
 %5 = fir.call @_FortranAioBeginUnformattedOutput(%c10_i32, %4, %c56_i32) : (i32, !fir.ref<i8>, i32) -> !fir.ref<i8>
 %6 = fir.embox %2 : (!fir.ref<!fir.type<_QTt>>) -> !fir.class<!fir.type<_QTt>>
 %7 = fir.convert %6 : (!fir.class<!fir.type<_QTt>>) -> !fir.box<none>
 %8 = fir.call @_FortranAioOutputDescriptor(%5, %7) : (!fir.ref<i8>, !fir.box<none>) -> i1
 %9 = fir.call @_FortranAioEndIoStatement(%5) : (!fir.ref<i8>) -> i32
 ```
 
 When dealing with polymorphic entities the call to IO runtime can stay
 unchanged. The runtime function `OutputDescriptor` can make the dynamic dispatch
 to the correct binding stored in the descriptor.
 
 ### Finalization
 
 The `FINAL` specifies a final subroutine that might  be executed when a data
 entity of that type is finalized. Section 7.5.6.3 defines when finalization
 occurs.
 
 Final subroutines like User-Defined Derived Type Input/Output are stored as
 special bindings in the type descriptor. The runtime is able to handle the
 finalization with a call the the `@_FortranADestroy` function
 (`flang/include/flang/Runtime/derived-api.h`).
 
 **FIR**
-```c
+```
 %5 = fir.call @_FortranADestroy(%desc) : (!fir.box<none>) -> none
 ```
 
 The `@_FortranADestroy` function will take care to call the final subroutines
 and the ones from the parent type.
 
 Appropriate call to finalization have to be lowered at the right places (7.5.6.3
 When finalization occurs).
subroutine get_only_triangle_area(sh)
   end select
 
 end subroutine
 ```
 
 **FIR**
 
 The call to `get_area` in the `type is (triangle)` guard can be replaced.
-```c
+```
 %3 = fir.dispatch "get_area"(%desc)
 // Replaced by
 %3 = fir.call @get_area_triangle(%desc)
 ```
 
 Another example would be the one below. In this case as well, a dynamic dispatch
 is not necessary and a `fir.call` can be emitted instead.
 

 
 **Fortran**
 ```fortran
 allocate(triangle::shapes(1)%item)
 allocate(rectangle::shapes(2)%item)
 ```
 
 **FIR**
-```c
+```
 %0 = fir.address_of(@_QMgeometryE.dt.triangle) : !fir.ref<!fir.type<_QM__fortran_type_infoTderivedtype>>
 %1 = fir.convert %item1 : (!fir.ref<!fir.class<!fir.type<_QMgeometryTtriangle{color:i32,isFilled:!fir.logical<4>,base:f32,height:f32>>>) -> !fir.ref<!fir.box<none>>
 %2 = fir.call @_FortranAAllocatableInitDerived(%1, %0)
 %3 = fir.call @_FortranAAllocatableAllocate(%1, ...)
 
 %4 = fir.address_of(@_QMgeometryE.dt.rectangle) : !fir.ref<!fir.type<_QM__fortran_type_infoTderivedtype>>
 %5 = fir.convert %item2 : (!fir.ref<!fir.class<_QMgeometryTtriangle{color:i32,isFilled:!fir.logical<4>,base:f32,height:f32}>>>) -> !fir.ref<!fir.box<none>>
 %6 = fir.call @_FortranAAllocatableInitDerived(%5, %4)

 
 **Fortran**
 ```fortran
 deallocate(shapes(1)%item)
 deallocate(shapes(2)%item)
 ```
 
 **FIR**
-```c
+```
 %8 = fir.call @_FortranAAllocatableDeallocate(%desc1)
 %9 = fir.call @_FortranAAllocatableDeallocate(%desc2)
 ```
 
 ### `EXTENDS_TYPE_OF`/`SAME_TYPE_AS` intrinsics
 
 `EXTENDS_TYPE_OF` and `SAME_TYPE_AS` intrinsics have implementation in the
 runtime. Respectively `SameTypeAs` and `ExtendsTypeOf` in
- `fir.load`/`fir.store`
   end subroutine
   end module
   ```
 
   In the example above, the dynamic type of `a` and `b` might be different. The
   dynamic type of `a` must be copied when it is associated on `b`.
 
   **FIR**
-  ```c
+  ```
   // fir.load must copy the dynamic type from the pointer `a`
   %0 = fir.address_of(@_QMmod1Ea) : !fir.ref<!fir.class<!fir.ptr<!fir.type<_QMmod1Tshape{x:i32,y:i32}>>>>
   %1 = fir.load %0 : !fir.ref<!fir.class<!fir.ptr<!fir.type<_QMmod1Tshape{x:i32,y:i32}>>>>
   ```
 
 - `fir.embox`
   - The embox operation is used to create a descriptor from a reference. With
     polymorphic entities, it is used to create a polymorphic descriptor from

flang/docs/PullRequestChecklist.md

 ## Follow the style guide
 The following items are taken from the [C++ style guide](C++style.md).  But
 even though I've read the style guide, they regularly trip me up.
 *  Run clang-format using the git-clang-format script from LLVM HEAD.
 *  Make sure that all source lines have 80 or fewer characters.  Note that
    clang-format will do this for most code.  But you may need to break up long
    strings.
 *  Review declarations for proper use of `constexpr` and `const`.
-*  Follow the C++ [naming guidelines](C++style.html#naming)
+*  Follow the C++ [naming guidelines](C++style.md#naming)
 *  Ensure that the names evoke their purpose and are consistent with existing code.
 *  Used braced initializers.
 *  Review pointer and reference types to make sure that you're using them
    appropriately.  Note that the [C++ style guide](C++style.md) contains a
    section that describes all of the pointer types along with their
    characteristics.
 *  Declare non-member functions ```static``` when possible.  Prefer
    ```static``` functions over functions in anonymous namespaces.

flang/docs/conf.py

 # -*- coding: utf-8 -*-
 # Flang documentation build configuration file.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
 import sys, os
 from datetime import date
-from recommonmark.parser import CommonMarkParser
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
-# https://github.com/readthedocs/recommonmark/issues/177
-#Method used to remove the warning message.
-class CustomCommonMarkParser(CommonMarkParser):
-    def visit_document(self, node):
-        pass
-
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = {
     '.rst': 'restructuredtext',
 }
 try:
-  import recommonmark
+  import myst_parser
 except ImportError:
   # manpages do not use any .md sources
   if not tags.has('builder-man'):
     raise
 else:
   import sphinx
   if sphinx.version_info >= (3, 0):
     # This requires 0.5 or later.
-    extensions.append('recommonmark')
+    extensions.append('myst_parser')
   else:
-    source_parsers = {'.md': CustomCommonMarkParser}
+    source_parsers = {'.md': 'myst_parser.parsers.sphinx_.MystParser'}
   source_suffix['.md'] = 'markdown'
+
+  myst_heading_anchors = 7
+  
   extensions.append('sphinx_markdown_tables')
 
+  # Don't warn about markdown headers going from h1 -> h3
+  suppress_warnings = ['myst.header']
+
   # Setup AutoStructify for inline .rst toctrees in index.md
   from recommonmark.transform import AutoStructify
 
   # Stolen from https://github.com/readthedocs/recommonmark/issues/93
   # Monkey patch to fix recommonmark 0.4 doc reference issues.
   from recommonmark.states import DummyStateMachine
   orig_run_role = DummyStateMachine.run_role
   def run_role(self, name, options=None, content=None):
     if name == 'doc':
       name = 'any'
       return orig_run_role(self, name, options, content)
   DummyStateMachine.run_role = run_role
 
   def setup(app):
-    # Disable inline math to avoid
-    # https://github.com/readthedocs/recommonmark/issues/120 in Extensions.md
-    app.add_config_value('recommonmark_config', {
-      'enable_inline_math': False
-    }, True)
     app.add_transform(AutoStructify)
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 

flang/docs/index.md

 ```
 
 # Design Documents
 
 ```eval_rst
 .. toctree::
    :titlesonly:
 
+   Aliasing
+   AliasingAnalysisFIR
    ArrayComposition
    BijectiveInternalNameUniquing
    Calls
    Character
+   ComplexOperations
    ControlFlowGraph
+   DesignGuideline
    Directives
    DoConcurrent
    Extensions
+   FIRArrayOperations
    FIRLangRef
    FlangCommandLineReference
    FlangDriver
+   FortranFeatureHistory
    FortranIR
    FortranLLVMTestSuite
+   HighLevelFIR
    IORuntimeInternals
    Intrinsics
    IntrinsicTypes
    LabelResolution
    ModFiles
    OpenMP-4.5-grammar.md
    OpenMP-semantics
    OptionComparison
    Overview
+   ParameterizedDerivedTypes
    ParserCombinators
    Parsing
+   PolymorphicEntities
    Preprocessing
+   ProcedurePointer
    RuntimeDescriptor
    RuntimeTypeInfo
    Semantics
    f2018-grammar.md
 ```
 
 # Indices and tables
 
 ```eval_rst
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 ```
+
+```eval_rst
+.. toctree::
+   :hidden:
+   
+   FIR/FIRLangRef_Header
+   DiagnosticsReference
+```

flang/include/flang/Optimizer/Dialect/FIROps.td

def fir_AllocaOp : fir_Op<"alloca", [AttrSizedOperandSegments,
   let summary = "allocate storage for a temporary on the stack given a type";
   let description = [{
     This primitive operation is used to allocate an object on the stack.  A
     reference to the object of type `!fir.ref<T>` is returned.  The returned
     object has an undefined/uninitialized state.  The allocation can be given
     an optional name.  The allocation may have a dynamic repetition count
     for allocating a sequence of locations for the specified type.
 
-    ```mlir
+    ```
       %c = ... : i64
       %x = fir.alloca i32
       %y = fir.alloca !fir.array<8 x i64>
       %z = fir.alloca f32, %c
 
       %i = ... : i16
       %j = ... : i32
       %w = fir.alloca !fir.type<PT(len1:i16, len2:i32)> (%i, %j : i16, i32)
def fir_AllocMemOp : fir_Op<"allocmem",
   let summary = "allocate storage on the heap for an object of a given type";
 
   let description = [{
     Creates a heap memory reference suitable for storing a value of the
     given type, T.  The heap refernce returned has type `!fir.heap<T>`.
     The memory object is in an undefined state.  `allocmem` operations must
     be paired with `freemem` operations to avoid memory leaks.
 
-    ```mlir
+    ```
       %0 = fir.allocmem !fir.array<10 x f32>
       fir.freemem %0 : !fir.heap<!fir.array<10 x f32>>
     ```
   }];
 
   let arguments = (ins
     TypeAttr:$in_type,
     OptionalAttr<StrAttr>:$uniq_name,
def fir_FreeMemOp : fir_Op<"freemem", [MemoryEffects<[MemFree]>]> {
 
   let description = [{
     Deallocates a heap memory reference that was allocated by an `allocmem`.
     The memory object that is deallocated is placed in an undefined state
     after `fir.freemem`.  Optimizations may treat the loading of an object
     in the undefined state as undefined behavior.  This includes aliasing
     references, such as the result of an `fir.embox`.
 
-    ```mlir
+    ```
       %21 = fir.allocmem !fir.type<ZT(p:i32){field:i32}>
       ...
       fir.freemem %21 : !fir.heap<!fir.type<ZT>>
     ```
   }];
 
   let arguments = (ins Arg<fir_HeapType, "", [MemFree]>:$heapref);
 
   let assemblyFormat = "$heapref attr-dict `:` qualified(type($heapref))";
 }
 
 def fir_LoadOp : fir_OneResultOp<"load", [MemoryEffects<[MemRead]>]> {
   let summary = "load a value from a memory reference";
   let description = [{
     Load a value from a memory reference into an ssa-value (virtual register).
     Produces an immutable ssa-value of the referent type. A memory reference
     has type `!fir.ref<T>`, `!fir.heap<T>`, or `!fir.ptr<T>`.
 
-    ```mlir
+    ```
       %a = fir.alloca i32
       %l = fir.load %a : !fir.ref<i32>
     ```
 
     The ssa-value has an undefined value if the memory reference is undefined
     or null.
   }];
 

 def fir_StoreOp : fir_Op<"store", [MemoryEffects<[MemWrite]>]> {
   let summary = "store an SSA-value to a memory location";
 
   let description = [{
     Store an ssa-value (virtual register) to a memory reference.  The stored
     value must be of the same type as the referent type of the memory
     reference.
 
-    ```mlir
+    ```
       %v = ... : f64
       %p = ... : !fir.ptr<f64>
       fir.store %v to %p : !fir.ptr<f64>
     ```
 
     The above store changes the value to which the pointer is pointing and not
     the pointer itself. The operation is undefined if the memory reference,
     `%p`, is undefined or null.
let description = [{
 
     For arrays, result, it is required to provide the shape of the result. For
     character arrays and derived types with LEN parameters, the LEN parameter
     values must be provided.
 
     The fir.save_result associated to a function call must immediately follow
     the call and be in the same block.
 
-    ```mlir
+    ```
       %buffer = fir.alloca fir.array<?xf32>, %c100
       %shape = fir.shape %c100
       %array_result = fir.call @foo() : () -> fir.array<?xf32>
       fir.save_result %array_result to %buffer(%shape)
       %coor = fir.array_coor %buffer%(%shape), %c5
       %fifth_element = fir.load %coor : f32
     ```
 
let description = [{
     Copy a CHARACTER (must be in memory) of KIND _k1_ to a CHARACTER (also must
     be in memory) of KIND _k2_ where _k1_ != _k2_ and the buffers do not
     overlap. This latter restriction is unchecked, as the Fortran language
     definition eliminates the overlapping in memory case.
 
     The number of code points copied is specified explicitly as the second
     argument. The length of the !fir.char type is ignored.
 
-    ```mlir
+    ```
       fir.char_convert %1 for %2 to %3 : !fir.ref<!fir.char<1,?>>, i32,
           !fir.ref<!fir.char<2,20>>
     ```
 
     Should future support for encodings other than ASCII be supported, codegen
     can generate a call to a runtime helper routine which will map the code
     points from UTF-8 to UCS-2, for example. Such remappings may not always
     be possible as they may involve the creation of more code points than the

 
 def fir_UndefOp : fir_OneResultOp<"undefined", [NoMemoryEffect]> {
   let summary = "explicit undefined value of some type";
   let description = [{
     Constructs an ssa-value of the specified type with an undefined value.
     This operation is typically created internally by the mem2reg conversion
     pass. An undefined value can be of any type except `!fir.ref<T>`.
 
-    ```mlir
+    ```
       %a = fir.undefined !fir.array<10 x !fir.type<T>>
     ```
 
     The example creates an array shaped ssa-value. The array is rank 1, extent
     10, and each element has type `!fir.type<T>`.
   }];
 
   let results = (outs AnyType:$intype);
 
   let assemblyFormat = "type($intype) attr-dict";
 
   // Note: we allow `undef : ref<T>` since it is a possible from transformations.
   let hasVerifier = 0;
 }
 
 def fir_ZeroOp : fir_OneResultOp<"zero_bits", [NoMemoryEffect]> {
   let summary = "explicit polymorphic zero value of some type";
   let description = [{
     Constructs an ssa-value of the specified type with a value of zero for all
     bits.
 
-    ```mlir
+    ```
       %a = fir.zero_bits !fir.box<!fir.array<10 x !fir.type<T>>>
     ```
 
     The example creates a value of type box where all bits are zero.
   }];
 
   let results = (outs AnyType:$intype);
 
def fir_SelectOp : fir_IntegralSwitchTerminatorOp<"select"> {
   let description = [{
     A multiway branch terminator with similar semantics to C's `switch`
     statement.  A selector value is matched against a list of constants
     of the same type for a match.  When a match is found, control is
     transferred to the corresponding basic block.  A `select` must have
     at least one basic block with a corresponding `unit` match, and
     that block will be selected when all other conditions fail to match.
 
-    ```mlir
+    ```
       fir.select %arg:i32 [1, ^bb1(%0 : i32),
                            2, ^bb2(%2,%arg,%arg2 : i32,i32,i32),
                           -3, ^bb3(%arg2,%2 : i32,i32),
                            4, ^bb4(%1 : i32),
                         unit, ^bb5]
     ```
   }];
   let hasCustomAssemblyFormat = 1;
   let hasVerifier = 1;
 
 }
 
 def fir_SelectRankOp : fir_IntegralSwitchTerminatorOp<"select_rank"> {
   let summary = "Fortran's SELECT RANK statement";
 
   let description = [{
     Similar to `select`, `select_rank` provides a way to express Fortran's
     SELECT RANK construct.  In this case, the rank of the selector value
     is matched against constants of integer type.  The structure is the
     same as `select`, but `select_rank` determines the rank of the selector
     variable at runtime to determine the best match.
 
-    ```mlir
+    ```
       fir.select_rank %arg:i32 [1, ^bb1(%0 : i32),
                                 2, ^bb2(%2,%arg,%arg2 : i32,i32,i32),
                                 3, ^bb3(%arg2,%2 : i32,i32),
                                -1, ^bb4(%1 : i32),
                              unit, ^bb5]
     ```
   }];
   let hasCustomAssemblyFormat = 1;
   let hasVerifier = 1;
 }
 
 def fir_SelectCaseOp : fir_SwitchTerminatorOp<"select_case"> {
   let summary = "Fortran's SELECT CASE statement";
 
   let description = [{
     Similar to `select`, `select_case` provides a way to express Fortran's
     SELECT CASE construct.  In this case, the selector value is matched
     against variables (not just constants) and ranges.  The structure is
     the same as `select`, but `select_case` allows for the expression of
     more complex match conditions.
 
-    ```mlir
+    ```
       fir.select_case %arg : i32 [
             #fir.point, %0, ^bb1(%0 : i32),
             #fir.lower, %1, ^bb2(%2,%arg,%arg2,%1 : i32,i32,i32,i32),
             #fir.interval, %2, %3, ^bb3(%2,%arg2 : i32,i32),
             #fir.upper, %arg, ^bb4(%1 : i32),
             unit, ^bb5]
     ```
   }];
def fir_SelectTypeOp : fir_SwitchTerminatorOp<"select_type"> {
 
   let description = [{
     Similar to `select`, `select_type` provides a way to express Fortran's
     SELECT TYPE construct.  In this case, the type of the selector value
     is matched against a list of type descriptors.  The structure is the
     same as `select`, but `select_type` determines the type of the selector
     variable at runtime to determine the best match.
 
-    ```mlir
+    ```
       fir.select_type %arg : !fir.box<()> [
           #fir.type_is<!fir.type<type1>>, ^bb1(%0 : i32),
           #fir.type_is<!fir.type<type2>>, ^bb2(%2 : i32),
           #fir.class_is<!fir.type<type3>>, ^bb3(%2 : i32),
           #fir.type_is<!fir.type<type4>>, ^bb4(%1,%3 : i32,f32),
           unit, ^bb5]
     ```
   }];
def fir_UnreachableOp : fir_Op<"unreachable", [Terminator]> {
 
   let description = [{
     Terminates a basic block with the assertion that the end of the block
     will never be reached at runtime.  This instruction can be used
     immediately after a call to the Fortran runtime to terminate the
     program, for example.  This instruction corresponds to the LLVM IR
     instruction `unreachable`.
 
-    ```mlir
+    ```
       fir.unreachable
     ```
   }];
 
   let assemblyFormat = [{ attr-dict }];
 
 }
 
 def fir_FirEndOp : fir_Op<"end", [Terminator]> {
   let summary = "the end instruction";
 
   let description = [{
     The end terminator is a special terminator used inside various FIR
     operations that have regions.  End is thus the custom invisible terminator
     for these operations.  It is implicit and need not appear in the textual
     representation.
   }];
 }
 
 def fir_HasValueOp : fir_Op<"has_value", [Terminator, HasParent<"GlobalOp">]> {
   let summary = "terminator for GlobalOp";
   let description = [{
     The terminator for a GlobalOp with a body.
 
-    ```mlir
+    ```
       global @variable : tuple<i32, f32> {
         %0 = arith.constant 45 : i32
         %1 = arith.constant 100.0 : f32
         %2 = fir.undefined tuple<i32, f32>
         %3 = arith.constant 0 : index
         %4 = fir.insert_value %2, %0, %3 : (tuple<i32, f32>, i32, index) -> tuple<i32, f32>
         %5 = arith.constant 1 : index
         %6 = fir.insert_value %4, %1, %5 : (tuple<i32, f32>, f32, index) -> tuple<i32, f32>
def fir_EmboxOp : fir_Op<"embox", [NoMemoryEffect, AttrSizedOperandSegments]> {
   let summary = "boxes a given reference and (optional) dimension information";
 
   let description = [{
     Create a boxed reference value. In Fortran, the implementation can require
     extra information about an entity, such as its type, rank, etc.  This
     auxiliary information is packaged and abstracted as a value with box type
     by the calling routine. (In Fortran, these are called descriptors.)
 
-    ```mlir
+    ```
       %c1 = arith.constant 1 : index
       %c10 = arith.constant 10 : index
       %5 = ... : !fir.ref<!fir.array<10 x i32>>
       %6 = fir.embox %5 : (!fir.ref<!fir.array<10 x i32>>) -> !fir.box<!fir.array<10 x i32>>
     ```
 
     The descriptor tuple may contain additional implementation-specific
     information through the use of additional attributes.
let description = [{
     A slice argument can be provided to build a reference to part of a boxed
     value. In this case, the shape operand must be absent or be a fir.shift
     that can be used to provide a non default origin for the slice.
 
     The following example illustrates creating a fir.box for x(10:33:2)
     where x is described by a fir.box and has non default lower bounds,
     and then applying a new 2-dimension shape to this fir.box.
 
-    ```mlir
+    ```
       %0 = fir.slice %c10, %c33, %c2 : (index, index, index) -> !fir.slice<1>
       %1 = fir.shift %c0 : (index) -> !fir.shift<1>
       %2 = fir.rebox %x(%1) [%0] : (!fir.box<!fir.array<?xf32>>, !fir.shift<1>, !fir.slice<1>) -> !fir.box<!fir.array<?xf32>>
       %3 = fir.shape %c3, %c4 : (index, index) -> !fir.shape<2>
       %4 = fir.rebox %2(%3) : (!fir.box<!fir.array<?xf32>>, !fir.shape<2>) -> !fir.box<!fir.array<?x?xf32>>
     ```
   }];
 
let description = [{
     Create a boxed CHARACTER value. The CHARACTER type has the LEN type
     parameter, the value of which may only be known at runtime.  Therefore,
     a variable of type CHARACTER has both its data reference as well as a
     LEN type parameter.
 
     ```fortran
       CHARACTER(LEN=10) :: var
     ```
-    ```mlir
+    ```
       %4 = ...         : !fir.ref<!fir.array<10 x !fir.char<1>>>
       %5 = arith.constant 10 : i32
       %6 = fir.emboxchar %4, %5 : (!fir.ref<!fir.array<10 x !fir.char<1>>>, i32) -> !fir.boxchar<1>
     ```
 
     In the above `%4` is a memory reference to a buffer of 10 CHARACTER units.
     This buffer and its LEN value (10) are wrapped into a pair in `%6`.
   }];
def fir_EmboxProcOp : fir_Op<"emboxproc", [NoMemoryEffect]> {
   let summary = "boxes a given procedure and optional host context";
 
   let description = [{
     Creates an abstract encapsulation of a PROCEDURE POINTER along with an
     optional pointer to a host instance context. If the pointer is not to an
     internal procedure or the internal procedure does not need a host context
     then the form takes only the procedure's symbol.
 
-    ```mlir
+    ```
       %f = ... : (i32) -> i32
       %0 = fir.emboxproc %f : ((i32) -> i32) -> !fir.boxproc<(i32) -> i32>
     ```
 
     An internal procedure requiring a host instance for correct execution uses
     the second form. The closure of the host procedure's state is passed as a
     reference to a tuple. It is the responsibility of the host to manage the
     context's values accordingly, up to and including inhibiting register
     promotion of local values.
 
-    ```mlir
+    ```
       %4 = ... : !fir.ref<tuple<!fir.ref<i32>, !fir.ref<i32>>>
       %g = ... : (i32) -> i32
       %5 = fir.emboxproc %g, %4 : ((i32) -> i32, !fir.ref<tuple<!fir.ref<i32>, !fir.ref<i32>>>) -> !fir.boxproc<(i32) -> i32>
     ```
   }];
 
   let arguments = (ins FuncType:$func, Optional<fir_ReferenceType>:$host);
 
   let results = (outs fir_BoxProcType);
 
   let assemblyFormat = [{
     $func (`,` $host^)? attr-dict `:` functional-type(operands, results)
   }];
 
   let hasVerifier = 1;
 }
 
 def fir_UnboxCharOp : fir_SimpleOp<"unboxchar", [NoMemoryEffect]> {
   let summary = "unbox a boxchar value into a pair value";
 
   let description = [{
     Unboxes a value of `boxchar` type into a pair consisting of a memory
     reference to the CHARACTER data and the LEN type parameter.
 
-    ```mlir
+    ```
       %45   = ... : !fir.boxchar<1>
       %46:2 = fir.unboxchar %45 : (!fir.boxchar<1>) -> (!fir.ref<!fir.char<1>>, i32)
     ```
   }];
 
   let arguments = (ins fir_BoxCharType:$boxchar);
 
   let results = (outs fir_ReferenceType, AnyIntegerLike);
 }
 
 def fir_UnboxProcOp : fir_SimpleOp<"unboxproc", [NoMemoryEffect]> {
   let summary = "unbox a boxproc value into a pair value";
 
   let description = [{
     Unboxes a value of `boxproc` type into a pair consisting of a procedure
     pointer and a pointer to a host context.
 
-    ```mlir
+    ```
       %47   = ... : !fir.boxproc<() -> i32>
       %48:2 = fir.unboxproc %47 : (!fir.ref<() -> i32>, !fir.ref<tuple<f32, i32>>)
     ```
   }];
 
   let hasVerifier = 1;
 
   let arguments = (ins fir_BoxProcType:$boxproc);
 
   let results = (outs FunctionType, fir_ReferenceType:$refTuple);
 }
 
 def fir_BoxAddrOp : fir_SimpleOneResultOp<"box_addr", [NoMemoryEffect]> {
   let summary = "return a memory reference to the boxed value";
 
   let description = [{
     This operator is overloaded to work with values of type `box`,
     `boxchar`, and `boxproc`.  The result for each of these
     cases, respectively, is the address of the data, the address of the
     `CHARACTER` data, and the address of the procedure.
 
-    ```mlir
+    ```
       %51 = fir.box_addr %box : (!fir.box<f64>) -> !fir.ref<f64>
       %52 = fir.box_addr %boxchar : (!fir.boxchar<1>) -> !fir.ref<!fir.char<1>>
       %53 = fir.box_addr %boxproc : (!fir.boxproc<!P>) -> !P
     ```
   }];
 
   let arguments = (ins AnyBoxLike:$val);
 
   let results = (outs AnyCodeOrDataRefLike);
 
   let hasFolder = 1;
 
   let builders = [OpBuilder<(ins "mlir::Value":$val)>];
 }
 
 def fir_BoxCharLenOp : fir_SimpleOp<"boxchar_len", [NoMemoryEffect]> {
   let summary = "return the LEN type parameter from a boxchar value";
 
   let description = [{
     Extracts the LEN type parameter from a `boxchar` value.
 
-    ```mlir
+    ```
       %45 = ... : !boxchar<1>  // CHARACTER(20)
       %59 = fir.boxchar_len %45 : (!fir.boxchar<1>) -> i64  // len=20
     ```
   }];
 
   let arguments = (ins fir_BoxCharType:$val);
 
   let results = (outs AnyIntegerLike);
 
   let hasFolder = 1;
 }
 
 def fir_BoxDimsOp : fir_Op<"box_dims", [NoMemoryEffect]> {
   let summary = "return the dynamic dimension information for the boxed value";
 
   let description = [{
     Returns the triple of lower bound, extent, and stride for `dim` dimension
     of `val`, which must have a `box` type.  The dimensions are enumerated from
     left to right from 0 to rank-1. This operation has undefined behavior if
     `dim` is out of bounds.
 
-    ```mlir
+    ```
       %c1   = arith.constant 0 : i32
       %52:3 = fir.box_dims %40, %c1 : (!fir.box<!fir.array<*:f64>>, i32) -> (index, index, index)
     ```
 
     The above is a request to return the left most row (at index 0) triple from
     the box. The triple will be the lower bound, extent, and byte-stride, which
     are the values encoded in a standard descriptor.
   }];

 
 def fir_BoxEleSizeOp : fir_SimpleOneResultOp<"box_elesize", [NoMemoryEffect]> {
   let summary = "return the size of an element of the boxed value";
 
   let description = [{
     Returns the size of an element in an entity of `box` type.  This size may
     not be known until runtime.
 
-    ```mlir
+    ```
       %53 = fir.box_elesize %40 : (!fir.box<f32>) -> i32  // size=4
       %54 = fir.box_elesize %40 : (!fir.box<!fir.array<*:f32>>) -> i32
     ```
 
     In the above example, `%53` may box an array of REAL values while `%54`
     must box an array of REAL values (with dynamic rank and extent).
   }];
 
   let arguments = (ins BoxOrClassType:$val);
 
   let results = (outs AnyIntegerLike);
 }
 
 def fir_BoxTypeCodeOp : fir_SimpleOneResultOp<"box_typecode", [NoMemoryEffect]>
 {
   let summary = "return the type code the boxed value";
 
   let description = [{
     Returns the descriptor type code of an entity of `box` type.
 
-    ```mlir
+    ```
       %1 = fir.box_typecode %0 : (!fir.box<T>) -> i32
     ```
   }];
 
   let arguments = (ins BoxOrClassType:$box);
 
   let results = (outs AnyIntegerLike);
 }
 
 def fir_BoxIsAllocOp : fir_SimpleOp<"box_isalloc", [NoMemoryEffect]> {
   let summary = "is the boxed value an ALLOCATABLE?";
 
   let description = [{
     Determine if the boxed value was from an ALLOCATABLE entity. This will
     return true if the originating box value was from a `fir.embox` op
     with a mem-ref value that had the type !fir.heap<T>.
 
-    ```mlir
+    ```
       %r = ... : !fir.heap<i64>
       %b = fir.embox %r : (!fir.heap<i64>) -> !fir.box<i64>
       %a = fir.box_isalloc %b : (!fir.box<i64>) -> i1  // true
     ```
 
     The canonical descriptor implementation will carry a flag to record if the
     variable is an `ALLOCATABLE`.
   }];
 
   let arguments = (ins fir_BoxType:$val);
 
   let results = (outs BoolLike);
 }
 
 def fir_BoxIsArrayOp : fir_SimpleOp<"box_isarray", [NoMemoryEffect]> {
   let summary = "is the boxed value an array?";
 
   let description = [{
     Determine if the boxed value has a positive (> 0) rank. This will return
     true if the originating box value was from a fir.embox with a memory
     reference value that had the type !fir.array<T> and/or a shape argument.
 
-    ```mlir
+    ```
       %r = ... : !fir.ref<i64>
       %c_100 = arith.constant 100 : index
       %d = fir.shape %c_100 : (index) -> !fir.shape<1>
       %b = fir.embox %r(%d) : (!fir.ref<i64>, !fir.shape<1>) -> !fir.box<i64>
       %a = fir.box_isarray %b : (!fir.box<i64>) -> i1  // true
     ```
   }];
 
   let arguments = (ins fir_BoxType:$val);
 
   let results = (outs BoolLike);
 }
 
 def fir_BoxIsPtrOp : fir_SimpleOp<"box_isptr", [NoMemoryEffect]> {
   let summary = "is the boxed value a POINTER?";
 
   let description = [{
     Determine if the boxed value was from a POINTER entity.
 
-    ```mlir
+    ```
       %p = ... : !fir.ptr<i64>
       %b = fir.embox %p : (!fir.ptr<i64>) -> !fir.box<i64>
       %a = fir.box_isptr %b : (!fir.box<i64>) -> i1  // true
     ```
   }];
 
   let arguments = (ins fir_BoxType:$val);
 
   let results = (outs BoolLike);
 }
 
 def fir_BoxProcHostOp : fir_SimpleOp<"boxproc_host", [NoMemoryEffect]> {
   let summary = "returns the host instance pointer (or null)";
 
   let description = [{
     Extract the host context pointer from a boxproc value.
 
-    ```mlir
+    ```
       %8 = ... : !fir.boxproc<(!fir.ref<!fir.type<T>>) -> i32>
       %9 = fir.boxproc_host %8 : (!fir.boxproc<(!fir.ref<!fir.type<T>>) -> i32>) -> !fir.ref<tuple<i32, i32>>
     ```
 
     In the example, the reference to the closure over the host procedure's
     variables is returned. This allows an internal procedure to access the
     host's variables. It is up to lowering to determine the contract between
     the host and the internal procedure.
   }];
 
   let arguments = (ins fir_BoxProcType:$val);
 
   let results = (outs fir_ReferenceType);
 }
 
 def fir_BoxRankOp : fir_SimpleOneResultOp<"box_rank", [NoMemoryEffect]> {
   let summary = "return the number of dimensions for the boxed value";
 
   let description = [{
     Return the rank of a value of `box` type.  If the value is scalar, the
     rank is 0.
 
-    ```mlir
+    ```
       %57 = fir.box_rank %40 : (!fir.box<!fir.array<*:f64>>) -> i32
       %58 = fir.box_rank %41 : (!fir.box<f64>) -> i32
     ```
 
     The example `%57` shows how one would determine the rank of an array that
     has deferred rank at runtime. This rank should be at least 1. In %58, the
     descriptor may be either an array or a scalar, so the value is nonnegative.
   }];
 
   let arguments = (ins fir_BoxType:$val);
 
   let results = (outs AnyIntegerType);
 }
 
 def fir_BoxTypeDescOp : fir_SimpleOneResultOp<"box_tdesc", [NoMemoryEffect]> {
   let summary = "return the type descriptor for the boxed value";
 
   let description = [{
     Return the opaque type descriptor of a value of `box` type. A type
     descriptor is an implementation defined value that fully describes a type
     to the Fortran runtime.
 
-    ```mlir
+    ```
       %7 = fir.box_tdesc %41 : (!fir.box<f64>) -> !fir.tdesc<f64>
     ```
   }];
 
   let arguments = (ins BoxOrClassType:$box);
 
   let results = (outs fir_TypeDescType);
 }
let description = [{
 
     One can use `fir.array_load` to produce an ssa-value that captures an
     immutable value of the entire array `a`, as in the Fortran array expression
     shown above. Subsequent changes to the memory containing the array do not
     alter its composite value. This operation lets one load an array as a
     value while applying a runtime shape, shift, or slice to the memory
     reference, and its semantics guarantee immutability.
 
-    ```mlir
+    ```
       %s = fir.shape_shift %o, %n, %p, %m : (index, index, index, index) -> !fir.shapeshift<2>
       // load the entire array 'a'
       %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shapeshift<2>) -> !fir.array<?x?xf32>
       // a fir.store here into array %a does not change %v
     ```
   }];
 
   let arguments = (ins
```fortran
       ... a ...
       ... a(r,s+1) ...
     ```
 
     One can use `fir.array_fetch` to fetch the (implied) value of `a(i,j)` in
     an array expression as shown above. It can also be used to extract the
     element `a(r,s+1)` in the second expression.
 
-    ```mlir
+    ```
       %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
       // load the entire array 'a'
       %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>) -> !fir.array<?x?xf32>
       // fetch the value of one of the array value's elements
       %1 = fir.array_fetch %v, %i, %j : (!fir.array<?x?xf32>, index, index) -> f32
     ```
 
     It is only possible to use `array_fetch` on an `array_load` result value.
```fortran
       real :: a(n,m)
       ...
       a = ...
     ```
 
     One can use `fir.array_update` to update the (implied) value of `a(i,j)`
     in an array expression as shown above.
 
-    ```mlir
+    ```
       %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
       // load the entire array 'a'
       %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>) -> !fir.array<?x?xf32>
       // update the value of one of the array value's elements
       // %r_{ij} = %f  if (i,j) = (%i,%j),   %v_{ij} otherwise
       %r = fir.array_update %v, %f, %i, %j : (!fir.array<?x?xf32>, f32, index, index) -> !fir.array<?x?xf32>
       fir.array_merge_store %v, %r to %a : !fir.ref<!fir.array<?x?xf32>>
     ```
```fortran
       ...
       ! Elemental user defined assignment from type(SomeType) to real.
       a = value_of_some_type
     ```
 
     One can use `fir.array_modify` to update the (implied) value of `a(i)`
     in an array expression as shown above.
 
-    ```mlir
+    ```
       %s = fir.shape %n : (index) -> !fir.shape<1>
       // Load the entire array 'a'.
       %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?xf32>>, !fir.shape<1>) -> !fir.array<?xf32>
       // Update the value of one of the array value's elements with a user
       // defined assignment from %rhs.
       %new = fir.do_loop %i = ... (%inner = %v) {
         %rhs = ...
         %addr, %r = fir.array_modify %inner, %i : (!fir.array<?xf32>, index) -> (fir.ref<f32>, !fir.array<?xf32>)
```fortran
       ... a(r,s+1) ...
     ```
 
     One can use `fir.array_access` to recover the implied memory reference to
     the element `a(i,j)` in an array expression `a` as shown above. It can also
     be used to recover the reference element `a(r,s+1)` in the second
     expression.
 
-    ```mlir
+    ```
       %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
       // load the entire array 'a'
       %v = fir.array_load %a(%s) : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>) -> !fir.array<?x?xf32>
       // fetch the value of one of the array value's elements
       %1 = fir.array_access %v, %i, %j : (!fir.array<?x?xf32>, index, index) -> !fir.ref<f32>
     ```
 
     It is only possible to use `array_access` on an `array_load` result value or
def fir_ArrayAmendOp : fir_Op<"array_amend", [NoMemoryEffect]> {
   let summary = "Mark an array value as having been changed by reference.";
 
   let description = [{
     The `array_amend` operation marks an array value as having been changed via
     a reference obtained by an `array_access`. It acts as a logical transaction
     log that is used to merge the final result back with an `array_merge_store`
     operation.
 
-    ```mlir
+    ```
       // fetch the value of one of the array value's elements
       %1 = fir.array_access %v, %i, %j : (!fir.array<?x?xT>, index, index) -> !fir.ref<T>
       // modify the element by storing data using %1 as a reference
       %2 = ... %1 ...
       // mark the array value
       %new_v = fir.array_amend %v, %2 : (!fir.array<?x?xT>, !fir.ref<T>) -> !fir.array<?x?xT>
     ```
 
```fortran
       real :: a(n,m)
       ...
       a = ...
     ```
 
     One can use `fir.array_merge_store` to merge/copy the value of `a` in an
     array expression as shown above.
 
-    ```mlir
+    ```
       %v = fir.array_load %a(%shape) : ...
       %r = fir.array_update %v, %f, %i, %j : (!fir.array<?x?xf32>, f32, index, index) -> !fir.array<?x?xf32>
       fir.array_merge_store %v, %r to %a : !fir.ref<!fir.array<?x?xf32>>
     ```
 
     This operation merges the original loaded array value, `%v`, with the
     chained updates, `%r`, and stores the result to the array at address, `%a`.
   }];
let description = [{
     ```fortran
       real :: a(n,m)
       ...
       ... a(i,j) ...
     ```
 
     One can use `fir.array_coor` to determine the address of `a(i,j)`.
 
-    ```mlir
+    ```
       %s = fir.shape %n, %m : (index, index) -> !fir.shape<2>
       %1 = fir.array_coor %a(%s) %i, %j : (!fir.ref<!fir.array<?x?xf32>>, !fir.shape<2>, index, index) -> !fir.ref<f32>
     ```
   }];
 
   let arguments = (ins
     AnyRefOrBox:$memref,
     Optional<AnyShapeOrShiftType>:$shape,
let description = [{
     coordinate of an array element, the rank of the array must be known and
     the number of indexing expressions must not exceed the rank of the array.
 
     This operation will apply the access map from a boxed value implicitly.
 
     Unlike LLVM's GEP instruction, one cannot stride over the outermost
     reference; therefore, the leading 0 index must be omitted.
 
-    ```mlir
+    ```
       %i = ... : index
       %h = ... : !fir.heap<!fir.array<100 x f32>>
       %p = fir.coordinate_of %h, %i : (!fir.heap<!fir.array<100 x f32>>, index) -> !fir.ref<f32>
     ```
 
     In the example, `%p` will be a pointer to the `%i`-th f32 value in the
     array `%h`.
   }];
let description = [{
     and/or derived types. Returns the value from entity with the type of the
     specified component. Cannot be used on values of `!fir.box` type.
     It can also be used to access complex parts and elements of a character
     string.
 
     Note that the entity ssa-value must be of compile-time known size in order
     to use this operation.
 
-    ```mlir
+    ```
       %f = fir.field_index field, !fir.type<X{field:i32}>
       %s = ... : !fir.type<X>
       %v = fir.extract_value %s, %f : (!fir.type<X>, !fir.field) -> i32
     ```
   }];
 
   let arguments = (ins
     AnyCompositeLike:$adt,
def fir_FieldIndexOp : fir_OneResultOp<"field_index", [NoMemoryEffect]> {
   let description = [{
     Generate a field (offset) value from an identifier.  Field values may be
     lowered into exact offsets when the layout of a Fortran derived type is
     known at compile-time. The type of a field value is `!fir.field` and
     these values can be used with the `fir.coordinate_of`, `fir.extract_value`,
     or `fir.insert_value` instructions to compute (abstract) addresses of
     subobjects.
 
-    ```mlir
+    ```
       %f = fir.field_index field, !fir.type<X{field:i32}>
     ```
   }];
 
   let arguments = (ins
     StrAttr:$field_id,
     TypeAttr:$on_type,
     Variadic<AnyIntegerType>:$typeparams
def fir_ShapeOp : fir_Op<"shape", [NoMemoryEffect]> {
 
   let description = [{
     The arguments are an ordered list of integral type values that define the
     runtime extent of each dimension of an array. The shape information is
     given in the same row-to-column order as Fortran. This abstract shape value
     must be applied to a reified object, so all shape information must be
     specified.  The extent must be nonnegative.
 
-    ```mlir
+    ```
       %d = fir.shape %row_sz, %col_sz : (index, index) -> !fir.shape<2>
     ```
   }];
 
   let arguments = (ins Variadic<AnyIntegerType>:$extents);
 
   let results = (outs fir_ShapeType);
 
def fir_ShapeShiftOp : fir_Op<"shape_shift", [NoMemoryEffect]> {
   let description = [{
     The arguments are an ordered list of integral type values that is a multiple
     of 2 in length. Each such pair is defined as: the lower bound and the
     extent for that dimension. The shifted shape information is given in the
     same row-to-column order as Fortran. This abstract shifted shape value must
     be applied to a reified object, so all shifted shape information must be
     specified.  The extent must be nonnegative.
 
-    ```mlir
+    ```
       %d = fir.shape_shift %lo, %extent : (index, index) -> !fir.shapeshift<1>
     ```
   }];
 
   let arguments = (ins Variadic<AnyIntegerType>:$pairs);
 
   let results = (outs fir_ShapeShiftType);
 
def fir_ShiftOp : fir_Op<"shift", [NoMemoryEffect]> {
 
   let description = [{
     The arguments are an ordered list of integral type values that define the
     runtime lower bound of each dimension of an array. The shape information is
     given in the same row-to-column order as Fortran. This abstract shift value
     must be applied to a reified object, so all shift information must be
     specified.
 
-    ```mlir
+    ```
       %d = fir.shift %row_lb, %col_lb : (index, index) -> !fir.shift<2>
     ```
   }];
 
   let arguments = (ins Variadic<AnyIntegerType>:$origins);
 
   let results = (outs fir_ShiftType);
 
let description = [{
     The array slicing arguments are an ordered list of integral type values
     that must be a multiple of 3 in length.  Each such triple is defined as:
     the lower bound, the upper bound, and the stride for that dimension, as in
     Fortran syntax. Both bounds are inclusive. The array slice information is
     given in the same row-to-column order as Fortran. This abstract slice value
     must be applied to a reified object, so all slice information must be
     specified.  The extent must be nonnegative and the stride must not be zero.
 
-    ```mlir
+    ```
       %d = fir.slice %lo, %hi, %step : (index, index, index) -> !fir.slice<1>
     ```
 
     To support generalized slicing of Fortran's dynamic derived types, a slice
     op can be given a component path (narrowing from the product type of the
     original array to the specific elemental type of the sliced projection).
 
-    ```mlir
+    ```
       %fld = fir.field_index component, !fir.type<t{...component:ct...}>
       %d = fir.slice %lo, %hi, %step path %fld :
           (index, index, index, !fir.field) -> !fir.slice<1>
     ```
 
     Projections of `!fir.char` type can be further narrowed to invariant
     substrings.
 
-    ```mlir
+    ```
       %d = fir.slice %lo, %hi, %step substr %offset, %width :
           (index, index, index, index, index) -> !fir.slice<1>
     ```
   }];
 
   let arguments = (ins
     Variadic<AnyIntegerType>:$triples,
     Variadic<AnyComponentType>:$fields,
let description = [{
     and/or derived types. Returns a new ssa-value with the same type as the
     original entity. Cannot be used on values of `!fir.box` type.
     It can also be used to set complex parts and elements of a character
     string.
 
     Note that the entity ssa-value must be of compile-time known size in order
     to use this operation.
 
-    ```mlir
+    ```
       %a = ... : !fir.array<10xtuple<i32, f32>>
       %f = ... : f32
       %o = ... : i32
       %c = arith.constant 1 : i32
       %b = fir.insert_value %a, %f, %o, %c : (!fir.array<10x20xtuple<i32, f32>>, f32, i32, i32) -> !fir.array<10x20xtuple<i32, f32>>
     ```
   }];
 
def fir_InsertOnRangeOp : fir_OneResultOp<"insert_on_range", [NoMemoryEffect]> {
   let description = [{
     Insert copies of a value into an entity with an array type of constant shape
     and size.
     Returns a new ssa-value with the same type as the original entity.
     The values are inserted at a contiguous range of indices in Fortran
     row-to-column element order as specified by lower and upper bound
     coordinates.
 
-    ```mlir
+    ```
       %a = fir.undefined !fir.array<10x10xf32>
       %c = arith.constant 3.0 : f32
       %1 = fir.insert_on_range %a, %c from (0, 0) to (7, 2) : (!fir.array<10x10xf32>, f32) -> !fir.array<10x10xf32>
     ```
 
     The first 28 elements of %1, with coordinates from (0,0) to (7,2), have
     the value 3.0.
   }];
let summary =
     "create a field index value from a LEN type parameter identifier";
 
   let description = [{
     Generate a LEN parameter (offset) value from a LEN parameter identifier.
     The type of a LEN parameter value is `!fir.len` and these values can be
     used with the `fir.coordinate_of` instructions to compute (abstract)
     addresses of LEN parameters.
 
-    ```mlir
+    ```
       %e = fir.len_param_index len1, !fir.type<X(len1:i32)>
       %p = ... : !fir.box<!fir.type<X>>
       %q = fir.coordinate_of %p, %e : (!fir.box<!fir.type<X>>, !fir.len) -> !fir.ref<i32>
     ```
   }];
 
   let arguments = (ins
     StrAttr:$field_id,

 
 def fir_DoLoopOp : region_Op<"do_loop",
     [DeclareOpInterfaceMethods<LoopLikeOpInterface>]> {
   let summary = "generalized loop operation";
   let description = [{
     Generalized high-level looping construct. This operation is similar to
     MLIR's `scf.for`.
 
-    ```mlir
+    ```
       %l = arith.constant 0 : index
       %u = arith.constant 9 : index
       %s = arith.constant 1 : index
       fir.do_loop %i = %l to %u step %s unordered {
         %x = fir.convert %i : (index) -> i32
         %v = fir.call @compute(%x) : (i32) -> f32
         %p = fir.coordinate_of %A, %i : (!fir.ref<!fir.array<?xf32>>, index) -> !fir.ref<f32>
         fir.store %v to %p : !fir.ref<f32>

 }
 
 def fir_IfOp : region_Op<"if", [NoRegionArguments]> {
   let summary = "if-then-else conditional operation";
   let description = [{
     Used to conditionally execute operations. This operation is the FIR
     dialect's version of `loop.if`.
 
-    ```mlir
+    ```
       %56 = ... : i1
       %78 = ... : !fir.ref<!T>
       fir.if %56 {
         fir.store %76 to %78 : !fir.ref<!T>
       } else {
         fir.store %77 to %78 : !fir.ref<!T>
       }
     ```
let description = [{
     An example iterate_while that returns the counter value, the early
     termination condition, and an extra loop-carried value is shown here. This
     loop counts from %lo to %up (inclusive), stepping by %c1, so long as the
     early exit (%ok) is true. The iter_args %sh value is also carried by the
     loop. The result triple is the values of %i=phi(%lo,%i+%c1),
     %ok=phi(%okIn,%okNew), and %sh=phi(%shIn,%shNew) from the last executed
     iteration.
 
-    ```mlir
+    ```
       %v:3 = fir.iterate_while (%i = %lo to %up step %c1) and (%ok = %okIn) iter_args(%sh = %shIn) -> (index, i1, i16) {
         %shNew = fir.call @bar(%sh) : (i16) -> i16
         %okNew = fir.call @foo(%sh) : (i16) -> i1
         fir.result %i, %okNew, %shNew : index, i1, i16
       }
     ```
   }];
 
def fir_CallOp : fir_Op<"call",
   let summary = "call a procedure";
 
   let description = [{
     Call the specified function or function reference.
 
     Provides a custom parser and pretty printer to allow a more readable syntax
     in the FIR dialect, e.g. `fir.call @sub(%12)` or `fir.call %20(%22,%23)`.
 
-    ```mlir
+    ```
       %a = fir.call %funcref(%arg0) : (!fir.ref<f32>) -> f32
       %b = fir.call @function(%arg1, %arg2) : (!fir.ref<f32>, !fir.ref<f32>) -> f32
     ```
   }];
 
   let arguments = (ins
     OptionalAttr<SymbolRefAttr>:$callee,
     Variadic<AnyType>:$args,
def fir_DispatchOp : fir_Op<"dispatch", []> {
   let summary = "call a type-bound procedure";
 
   let description = [{
     Perform a dynamic dispatch on the method name via the dispatch table
     associated with the first operand.  The attribute `pass_arg_pos` can be
     used to select a dispatch operand other than the first one.  The absence of
     `pass_arg_pos` attribute means nopass.
 
-    ```mlir
+    ```
       // fir.dispatch with no attribute.
       %r = fir.dispatch "methodA"(%o) : (!fir.class<T>) -> i32
 
       // fir.dispatch with the `pass_arg_pos` attribute.
       %r = fir.dispatch "methodA"(%o : !fir.class<T>) (%o : !fir.class<T>) -> i32 {pass_arg_pos = 0 : i32}
     ```
   }];
 

 def fir_StringLitOp : fir_Op<"string_lit", [NoMemoryEffect]> {
   let summary = "create a string literal constant";
 
   let description = [{
     An FIR constant that represents a sequence of characters that correspond
     to Fortran's CHARACTER type, including a LEN.  We support CHARACTER values
     of different KINDs (different constant sizes).
 
-    ```mlir
+    ```
       %1 = fir.string_lit "Hello, World!"(13) : !fir.char<1> // ASCII
       %2 = fir.string_lit [158, 2345](2) : !fir.char<2>      // Wide chars
     ```
   }];
 
   let results = (outs fir_CharacterType);
 
   let hasCustomAssemblyFormat = 1;

 def fir_AddrOfOp : fir_OneResultOp<"address_of", [NoMemoryEffect]> {
   let summary = "convert a symbol to an SSA value";
 
   let description = [{
     Convert a symbol (a function or global reference) to an SSA-value to be
     used in other operations. References to Fortran symbols are distinguished
     via this operation from other arbitrary constant values.
 
-    ```mlir
+    ```
       %p = fir.address_of(@symbol) : !fir.ref<f64>
     ```
   }];
 
   let arguments = (ins SymbolRefAttr:$symbol);
 
   let results = (outs AnyAddressableLike:$resTy);
 
   let assemblyFormat = "`(` $symbol `)` attr-dict `:` type($resTy)";
 }
 
 def fir_ConvertOp : fir_OneResultOp<"convert", [NoMemoryEffect]> {
   let summary = "encapsulates all Fortran entity type conversions";
 
   let description = [{
     Generalized type conversion. Convert the ssa-value from type T to type U.
     Not all pairs of types have conversions. When types T and U are the same
     type, this instruction is a NOP and may be folded away. This also supports
     integer to pointer conversion and pointer to integer conversion.
 
-    ```mlir
+    ```
       %v = ... : i64
       %w = fir.convert %v : (i64) -> i32
     ```
 
     The example truncates the value `%v` from an i64 to an i32.
   }];
 
   let arguments = (ins AnyType:$value);

 
 def fir_GenTypeDescOp : fir_OneResultOp<"gentypedesc", [NoMemoryEffect]> {
   let summary = "generate a type descriptor for a given type";
   let description = [{
     Generates a constant object that is an abstract type descriptor of the
     specified type.  The meta-type of a type descriptor for the type `T`
     is `!fir.tdesc<T>`.
 
-    ```mlir
+    ```
       !T = !fir.type<T{...}>
       %t = fir.gentypedesc !T  // returns value of !fir.tdesc<!T>
     ```
   }];
 
   let arguments = (ins FortranTypeAttr:$in_type);
 
   let hasCustomAssemblyFormat = 1;
let description = [{
     Primitive operation meant to intrusively prevent operator reassociation.
     The operation is otherwise a nop and the value returned is the same as the
     argument.
 
     The presence of this operation prevents any local optimizations. In the
     example below, this would prevent possibly replacing the multiply and add
     operations with a single FMA operation.
 
-    ```mlir
+    ```
       %98 = arith.mulf %96, %97 : f32
       %99 = fir.no_reassoc %98 : f32
       %a0 = arith.addf %99, %95 : f32
     ```
   }];
 
   let arguments = (ins AnyType:$val);
 
   let assemblyFormat = "$val attr-dict `:` type($val)";
 }
 
 class AtMostRegion<int numBlocks> : Region<
   CPred<"$_self.getBlocks().size() <= " # numBlocks>,
   "region with " # numBlocks # " blocks">;
 
 def fir_GlobalOp : fir_Op<"global", [IsolatedFromAbove, Symbol]> {
   let summary = "Global data";
   let description = [{
     A global variable or constant with initial values.
 
     The example creates a global variable (writable) named
     `@_QV_Mquark_Vvarble` with some initial values. The initializer should
     conform to the variable's type.
 
-    ```mlir
+    ```
       fir.global @_QV_Mquark_Vvarble : tuple<i32, f32> {
         %1 = arith.constant 1 : i32
         %2 = arith.constant 2.0 : f32
         %3 = fir.undefined tuple<i32, f32>
         %z = arith.constant 0 : index
         %o = arith.constant 1 : index
         %4 = fir.insert_value %3, %1, %z : (tuple<i32, f32>, i32, index) -> tuple<i32, f32>
         %5 = fir.insert_value %4, %2, %o : (tuple<i32, f32>, f32, index) -> tuple<i32, f32>

 
 def fir_GlobalLenOp : fir_Op<"global_len", []> {
   let summary = "map a LEN parameter to a global";
   let description = [{
     A global entity (that is not an automatic data object) can have extra LEN
     parameter (compile-time) constants associated with the instance's type.
     These values can be bound to the global instance used `fir.global_len`.
 
-    ```mlir
+    ```
       global @g : !fir.type<t(len1:i32)> {
         fir.global_len len1, 10 : i32
         %1 = fir.undefined !fir.type<t(len1:i32)>
         fir.has_value %1 : !fir.type<t(len1:i32)>
       }
     ```
   }];
 
def fir_DispatchTableOp : fir_Op<"dispatch_table",
   let description = [{
     Define a dispatch table for a derived type with type-bound procedures.
 
     A dispatch table is an untyped symbol that contains a list of associations
     between method identifiers and corresponding `FuncOp` symbols.
 
     The ordering of associations in the map is determined by the front end.
 
-    ```mlir
+    ```
       fir.dispatch_table @_QDTMquuzTfoo {
         fir.dt_entry method1, @_QFNMquuzTfooPmethod1AfooR
         fir.dt_entry method2, @_QFNMquuzTfooPmethod2AfooII
       }
     ```
   }];
 
   let arguments = (ins
def fir_DTEntryOp : fir_Op<"dt_entry", [HasParent<"DispatchTableOp">]> {
 
   let description = [{
     An entry in a dispatch table.  Allows a function symbol to be bound
     to a specifier method identifier.  A dispatch operation uses the dynamic
     type of a distinguished argument to determine an exact dispatch table
     and uses the method identifier to select the type-bound procedure to
     be called.
 
-    ```mlir
+    ```
       fir.dt_entry method_name, @uniquedProcedure
     ```
   }];
 
   let arguments = (ins StrAttr:$method, SymbolRefAttr:$proc);
 
   let hasCustomAssemblyFormat = 1;
 
   let extraClassDeclaration = [{
     static constexpr llvm::StringRef getMethodAttrNameStr() { return "method"; }
     static constexpr llvm::StringRef getProcAttrNameStr() { return "proc"; }
   }];
 }
 
 def fir_AbsentOp : fir_OneResultOp<"absent", [NoMemoryEffect]> {
   let summary = "create value to be passed for absent optional function argument";
   let description = [{
     Given the type of a function argument, create a value that will signal that
     an optional argument is absent in the call. On the caller side, fir.is_present
     can be used to query if the value of an optional argument was created with
     a fir.absent operation.
     It is undefined to use a value that was created by a fir.absent op in any other
     operation than fir.call and fir.is_present.
-    ```mlir
+    ```
       %1 = fir.absent fir.box<fir.array<?xf32>>
       fir.call @_QPfoo(%1) : (fir.box<fir.array<?xf32>>) -> ()
     ```
   }];
 
   let results = (outs AnyRefOrBoxLike:$intype);
 
   let assemblyFormat = "type($intype) attr-dict";
 }
 
 def fir_IsPresentOp : fir_SimpleOp<"is_present", [NoMemoryEffect]> {
   let summary = "is this optional function argument present?";
 
   let description = [{
     Determine if an optional function argument is PRESENT (i.e. that it was not
     created by a fir.absent op on the caller side).
-    ```mlir
+    ```
       func @_QPfoo(%arg0: !fir.box<!fir.array<?xf32>>) {
         %0 = fir.is_present %arg0 : (!fir.box<!fir.array<?xf32>>) -> i1
         ...
     ```
   }];
 
   let arguments = (ins AnyRefOrBoxLike:$val);
 

llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md

 # Allow Location Descriptions on the DWARF Expression Stack <!-- omit in toc -->
 
-- [1. Extension](#extension)
-- [2. Heterogeneous Computing Devices](#heterogeneous-computing-devices)
-- [3. DWARF 5](#dwarf-5)
-  - [3.1 How DWARF Maps Source Language To Hardware](#how-dwarf-maps-source-language-to-hardware)
-  - [3.2 Examples](#examples)
-    - [3.2.1 Dynamic Array Size](#dynamic-array-size)
-    - [3.2.2 Variable Location in Register](#variable-location-in-register)
-    - [3.2.3 Variable Location in Memory](#variable-location-in-memory)
-    - [3.2.4 Variable Spread Across Different Locations](#variable-spread-across-different-locations)
-    - [3.2.5 Offsetting a Composite Location](#offsetting-a-composite-location)
-    - [3.2.6 Pointer to Member](#pointer-to-member)
-    - [3.2.7 Virtual Base Class](#virtual-base-class)
-  - [3.3 Limitations](#limitations)
-- [4. Extension Solution](#extension-solution)
-  - [4.1 Location Description](#location-description)
-  - [4.2 Stack Location Description Operations](#stack-location-description-operations)
-  - [4.3 Examples](#examples-1)
-    - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#source-language-variable-spilled-to-part-of-a-vector-register)
-    - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#source-language-variable-spread-across-multiple-vector-registers)
-    - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#source-language-variable-spread-across-multiple-kinds-of-locations)
-    - [4.3.4 Address Spaces](#address-spaces)
-    - [4.3.5 Bit Offsets](#bit-offsets)
-  - [4.4 Call Frame Information (CFI)](#call-frame-information-cfi)
-  - [4.5 Objects Not In Byte Aligned Global Memory](#objects-not-in-byte-aligned-global-memory)
-  - [4.6 Higher Order Operations](#higher-order-operations)
-  - [4.7 Objects In Multiple Places](#objects-in-multiple-places)
-- [5. Conclusion](#conclusion)
+- [1. Extension](#1-extension)
+- [2. Heterogeneous Computing Devices](#2-heterogeneous-computing-devices)
+- [3. DWARF 5](#3-dwarf-5)
+  - [3.1 How DWARF Maps Source Language To Hardware](#31-how-dwarf-maps-source-language-to-hardware)
+  - [3.2 Examples](#32-examples)
+    - [3.2.1 Dynamic Array Size](#321-dynamic-array-size)
+    - [3.2.2 Variable Location in Register](#322-variable-location-in-register)
+    - [3.2.3 Variable Location in Memory](#323-variable-location-in-memory)
+    - [3.2.4 Variable Spread Across Different Locations](#324-variable-spread-across-different-locations)
+    - [3.2.5 Offsetting a Composite Location](#325-offsetting-a-composite-location)
+    - [3.2.6 Pointer to Member](#326-pointer-to-member)
+    - [3.2.7 Virtual Base Class](#327-virtual-base-class)
+  - [3.3 Limitations](#33-limitations)
+- [4. Extension Solution](#4-extension-solution)
+  - [4.1 Location Description](#41-location-description)
+  - [4.2 Stack Location Description Operations](#42-stack-location-description-operations)
+  - [4.3 Examples](#43-examples)
+    - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#431-source-language-variable-spilled-to-part-of-a-vector-register)
+    - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#432-source-language-variable-spread-across-multiple-vector-registers)
+    - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#433-source-language-variable-spread-across-multiple-kinds-of-locations)
+    - [4.3.4 Address Spaces](#434-address-spaces)
+    - [4.3.5 Bit Offsets](#435-bit-offsets)
+  - [4.4 Call Frame Information (CFI)](#44-call-frame-information-cfi)
+  - [4.5 Objects Not In Byte Aligned Global Memory](#45-objects-not-in-byte-aligned-global-memory)
+  - [4.6 Higher Order Operations](#46-higher-order-operations)
+  - [4.7 Objects In Multiple Places](#47-objects-in-multiple-places)
+- [5. Conclusion](#5-conclusion)
 - [A. Changes to DWARF Debugging Information Format Version 5](#a-changes-to-dwarf-debugging-information-format-version-5)
-  - [A.2 General Description](#a-2-general-description)
-    - [A.2.5 DWARF Expressions](#a-2-5-dwarf-expressions)
-      - [A.2.5.1 DWARF Expression Evaluation Context](#a-2-5-1-dwarf-expression-evaluation-context)
-      - [A.2.5.2 DWARF Expression Value](#a-2-5-2-dwarf-expression-value)
-      - [A.2.5.3 DWARF Location Description](#a-2-5-3-dwarf-location-description)
-      - [A.2.5.4 DWARF Operation Expressions](#a-2-5-4-dwarf-operation-expressions)
-        - [A.2.5.4.1 Stack Operations](#a-2-5-4-1-stack-operations)
-        - [A.2.5.4.2 Control Flow Operations](#a-2-5-4-2-control-flow-operations)
-        - [A.2.5.4.3 Value Operations](#a-2-5-4-3-value-operations)
-          - [A.2.5.4.3.1 Literal Operations](#a-2-5-4-3-1-literal-operations)
-          - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a-2-5-4-3-2-arithmetic-and-logical-operations)
-          - [A.2.5.4.3.3 Type Conversion Operations](#a-2-5-4-3-3-type-conversion-operations)
-          - [A.2.5.4.3.4 Special Value Operations](#a-2-5-4-3-4-special-value-operations)
-        - [A.2.5.4.4 Location Description Operations](#a-2-5-4-4-location-description-operations)
-          - [A.2.5.4.4.1 General Location Description Operations](#a-2-5-4-4-1-general-location-description-operations)
-          - [A.2.5.4.4.2 Undefined Location Description Operations](#a-2-5-4-4-2-undefined-location-description-operations)
-          - [A.2.5.4.4.3 Memory Location Description Operations](#a-2-5-4-4-3-memory-location-description-operations)
-          - [A.2.5.4.4.4 Register Location Description Operations](#a-2-5-4-4-4-register-location-description-operations)
-          - [A.2.5.4.4.5 Implicit Location Description Operations](#a-2-5-4-4-5-implicit-location-description-operations)
-          - [A.2.5.4.4.6 Composite Location Description Operations](#a-2-5-4-4-6-composite-location-description-operations)
-      - [A.2.5.5 DWARF Location List Expressions](#a-2-5-5-dwarf-location-list-expressions)
-  - [A.3 Program Scope Entries](#a-3-program-scope-entries)
-    - [A.3.3 Subroutine and Entry Point Entries](#a-3-3-subroutine-and-entry-point-entries)
-      - [A.3.3.5 Low-Level Information](#a-3-3-5-low-level-information)
-    - [A.3.4 Call Site Entries and Parameters](#a-3-4-call-site-entries-and-parameters)
-      - [A.3.4.2 Call Site Parameters](#a-3-4-2-call-site-parameters)
-    - [A.3.5 Lexical Block Entries](#a-3-5-lexical-block-entries)
-  - [A.4 Data Object and Object List Entries](#a-4-data-object-and-object-list-entries)
-    - [A.4.1 Data Object Entries](#a-4-1-data-object-entries)
-  - [A.5 Type Entries](#a-5-type-entries)
-    - [A.5.7 Structure, Union, Class and Interface Type Entries](#a-5-7-structure-union-class-and-interface-type-entries)
-      - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a-5-7-3-derived-or-extended-structures-classes-and-interfaces)
-      - [A.5.7.8 Member Function Entries](#a-5-7-8-member-function-entries)
-    - [A.5.14 Pointer to Member Type Entries](#a-5-14-pointer-to-member-type-entries)
-    - [A.5.16 Dynamic Type Entries](#a-5-16-dynamic-type-entries)
-  - [A.6 Other Debugging Information](#a-6-other-debugging-information)
-    - [A.6.2 Line Number Information](#a-6-2-line-number-information)
-    - [A.6.4 Call Frame Information](#a-6-4-call-frame-information)
-      - [A.6.4.1 Structure of Call Frame Information](#a-6-4-1-structure-of-call-frame-information)
-      - [A.6.4.2 Call Frame Instructions](#a-6-4-2-call-frame-instructions)
-        - [A.6.4.2.1 Row Creation Instructions](#a-6-4-2-1-row-creation-instructions)
-        - [A.6.4.2.2 CFA Definition Instructions](#a-6-4-2-2-cfa-definition-instructions)
-        - [A.6.4.2.3 Register Rule Instructions](#a-6-4-2-3-register-rule-instructions)
-        - [A.6.4.2.4 Row State Instructions](#a-6-4-2-4-row-state-instructions)
-        - [A.6.4.2.5 Padding Instruction](#a-6-4-2-5-padding-instruction)
-      - [A.6.4.3 Call Frame Instruction Usage](#a-6-4-3-call-frame-instruction-usage)
-      - [A.6.4.4 Call Frame Calling Address](#a-6-4-4-call-frame-calling-address)
-  - [A.7 Data Representation](#a-7-data-representation)
-    - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a-7-4-32-bit-and-64-bit-dwarf-formats)
-    - [A.7.5 Format of Debugging Information](#a-7-5-format-of-debugging-information)
-      - [A.7.5.5 Classes and Forms](#a-7-5-5-classes-and-forms)
-    - [A.7.7 DWARF Expressions](#a-7-7-dwarf-expressions)
-      - [A.7.7.1 Operation Expressions](#a-7-7-1-operation-expressions)
-      - [A.7.7.3 Location List Expressions](#a-7-7-3-location-list-expressions)
+  - [A.2 General Description](#a2-general-description)
+    - [A.2.5 DWARF Expressions](#a25-dwarf-expressions)
+      - [A.2.5.1 DWARF Expression Evaluation Context](#a251-dwarf-expression-evaluation-context)
+      - [A.2.5.2 DWARF Expression Value](#a252-dwarf-expression-value)
+      - [A.2.5.3 DWARF Location Description](#a253-dwarf-location-description)
+      - [A.2.5.4 DWARF Operation Expressions](#a254-dwarf-operation-expressions)
+        - [A.2.5.4.1 Stack Operations](#a2541-stack-operations)
+        - [A.2.5.4.2 Control Flow Operations](#a2542-control-flow-operations)
+        - [A.2.5.4.3 Value Operations](#a2543-value-operations)
+          - [A.2.5.4.3.1 Literal Operations](#a25431-literal-operations)
+          - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a25432-arithmetic-and-logical-operations)
+          - [A.2.5.4.3.3 Type Conversion Operations](#a25433-type-conversion-operations)
+          - [A.2.5.4.3.4 Special Value Operations](#a25434-special-value-operations)
+        - [A.2.5.4.4 Location Description Operations](#a2544-location-description-operations)
+          - [A.2.5.4.4.1 General Location Description Operations](#a25441-general-location-description-operations)
+          - [A.2.5.4.4.2 Undefined Location Description Operations](#a25442-undefined-location-description-operations)
+          - [A.2.5.4.4.3 Memory Location Description Operations](#a25443-memory-location-description-operations)
+          - [A.2.5.4.4.4 Register Location Description Operations](#a25444-register-location-description-operations)
+          - [A.2.5.4.4.5 Implicit Location Description Operations](#a25445-implicit-location-description-operations)
+          - [A.2.5.4.4.6 Composite Location Description Operations](#a25446-composite-location-description-operations)
+      - [A.2.5.5 DWARF Location List Expressions](#a255-dwarf-location-list-expressions)
+  - [A.3 Program Scope Entries](#a3-program-scope-entries)
+    - [A.3.3 Subroutine and Entry Point Entries](#a33-subroutine-and-entry-point-entries)
+      - [A.3.3.5 Low-Level Information](#a335-low-level-information)
+    - [A.3.4 Call Site Entries and Parameters](#a34-call-site-entries-and-parameters)
+      - [A.3.4.2 Call Site Parameters](#a342-call-site-parameters)
+    - [A.3.5 Lexical Block Entries](#a35-lexical-block-entries)
+  - [A.4 Data Object and Object List Entries](#a4-data-object-and-object-list-entries)
+    - [A.4.1 Data Object Entries](#a41-data-object-entries)
+  - [A.5 Type Entries](#a5-type-entries)
+    - [A.5.7 Structure, Union, Class and Interface Type Entries](#a57-structure-union-class-and-interface-type-entries)
+      - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a573-derived-or-extended-structures-classes-and-interfaces)
+      - [A.5.7.8 Member Function Entries](#a578-member-function-entries)
+    - [A.5.14 Pointer to Member Type Entries](#a514-pointer-to-member-type-entries)
+    - [A.5.18 Dynamic Properties of Types](#a518-dynamic-properties-of-types)
+  - [A.6 Other Debugging Information](#a6-other-debugging-information)
+    - [A.6.2 Line Number Information](#a62-line-number-information)
+    - [A.6.4 Call Frame Information](#a64-call-frame-information)
+      - [A.6.4.1 Structure of Call Frame Information](#a641-structure-of-call-frame-information)
+      - [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions)
+        - [A.6.4.2.1 Row Creation Instructions](#a6421-row-creation-instructions)
+        - [A.6.4.2.2 CFA Definition Instructions](#a6422-cfa-definition-instructions)
+        - [A.6.4.2.3 Register Rule Instructions](#a6423-register-rule-instructions)
+        - [A.6.4.2.4 Row State Instructions](#a6424-row-state-instructions)
+        - [A.6.4.2.5 Padding Instruction](#a6425-padding-instruction)
+      - [A.6.4.3 Call Frame Instruction Usage](#a643-call-frame-instruction-usage)
+      - [A.6.4.4 Call Frame Calling Address](#a644-call-frame-calling-address)
+  - [A.7 Data Representation](#a7-data-representation)
+    - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a74-32-bit-and-64-bit-dwarf-formats)
+    - [A.7.5 Format of Debugging Information](#a75-format-of-debugging-information)
+      - [A.7.5.5 Classes and Forms](#a755-classes-and-forms)
+    - [A.7.7 DWARF Expressions](#a77-dwarf-expressions)
+      - [A.7.7.1 Operation Expressions](#a771-operation-expressions)
+      - [A.7.7.3 Location List Expressions](#a773-location-list-expressions)
 - [B. Further Information](#b-further-information)
 
 # 1. Extension
 
 In DWARF 5, expressions are evaluated using a typed value stack, a separate
 location area, and an independent loclist mechanism. This extension unifies all
 three mechanisms into a single generalized DWARF expression evaluation model
 that allows both typed values and location descriptions to be manipulated on the

 rules. However, these resulted in the need for more operations that did not
 compose. It also resulted in operations with context sensitive semantics and
 corner cases that had to be defined. The observation was that numerous
 specialized context sensitive operations are harder for both producers and
 consumers than a smaller number of general composable operations that have
 consistent semantics regardless of context.
 
 First, section [2. Heterogeneous Computing
-Devices](#heterogeneous-computing-devices) describes heterogeneous devices and
+Devices](#2-heterogeneous-computing-devices) describes heterogeneous devices and
 the features they have that are not addressed by DWARF 5. Then section [3. DWARF
-5](#dwarf-5) presents a brief simplified overview of the DWARF 5 expression
+5](#3-dwarf-5) presents a brief simplified overview of the DWARF 5 expression
 evaluation model that highlights the difficulties for supporting the
 heterogeneous features. Next, section [4. Extension
-Solution](#extension-solution) provides an overview of the proposal, using
+Solution](#4-extension-solution) provides an overview of the proposal, using
 simplified examples to illustrate how it can address the issues of heterogeneous
 devices and also benefit non-heterogeneous devices. Then overall conclusions are
-covered in section [5. Conclusion](#conclusion). Appendix [A. Changes to DWARF
+covered in section [5. Conclusion](#5-conclusion). Appendix [A. Changes to DWARF
 Debugging Information Format Version
 5](#a-changes-to-dwarf-debugging-information-format-version-5) gives changes
 relative to the DWARF Version 5 standard. Finally, appendix [B. Further
 Information](#b-further-information) has references to further information.
 
 # 2. Heterogeneous Computing Devices
 
 GPUs and other heterogeneous computing devices have features not common to CPU

 of the expression is the location description in the location area.
 
 ![Variable Spread Across Different Locations Example: Step 7](images/04-composite.example.frame.7.png)
 
 ### 3.2.5 Offsetting a Composite Location
 
 This example attempts to extend the previous example to offset the composite
 location description it created. The [3.2.3 Variable Location in
-Memory](#variable-location-in-memory) example conveniently used the DW_OP_plus
+Memory](#323-variable-location-in-memory) example conveniently used the DW_OP_plus
 operation to offset a memory address.
 
     DW_OP_regx SGPR3
     DW_OP_piece 4
     DW_OP_piece 2
     DW_OP_bregx SGPR0 0x10
     DW_OP_piece 2
     DW_OP_plus_uconst 5

 
 ```
 (gdb) p x.*p
 Address requested for identifier "x" which is in register $rdi
 ```
 
 With location descriptions on the stack, the definition of `DW_OP_use_location`
 can be modified by replacing every instance of "address" with "location
-description", as is described in [A.5 Type Entries](#a-5-type-entries).
+description", as is described in [A.5 Type Entries](#a5-type-entries).
 
 To implement the fully generalized version of this attribute, GCC would only
 need to change the expression from `DW_OP_plus` to `DW_OP_swap,
 DW_OP_LLVM_offset`.
 
 ### 3.2.7 Virtual Base Class
 
 > NOTE: Without loss of generality, DWARF 4 is used in this example as full

 `vptr B` is offset by the statically determined value `-24`.
 
 Thus, in order to implement `DW_AT_data_member_location` for `A`-in-`B`, the
 expression needs to index to a statically known byte offset of `-24` through
 `vptr B` to lookup `vbase_offset` for `A`-in-`B`. It must then offset the
 location of `B` by the dynamic value of `vbase_offset` (in this case `8`) to
 arrive at the location of the inherited subobject.
 
-This definition shares the same problem as example [3.2.6](#pointer-to-member)
-in that it relies on the address of the derived object and inherited subobject,
-when there is no guarantee either or both have any address at all.
+This definition shares the same problem as example
+[3.2.6](#326-pointer-to-member) in that it relies on the address of the derived
+object and inherited subobject, when there is no guarantee either or both have
+any address at all.
 
 To demonstrate the problem, consider a program which GCC chooses to optimize in
 such a way that the derived object is not in memory at all:
 
 f.h:
 ```cpp
 class A {
 public:

 > NOTE: The `vptr B` which should occupy the first 8 bytes of the object `b`
 > are undefined in the DWARF, but could be described as an implicit value by
 > the compiler. This change would be trivial and would directly expose the
 > issue in DWARF 5 described here.
 
 With location descriptions on the stack, the definition of
 `DW_OP_data_member_location` can be modified by replacing every instance of
 "address" with "location description", as is described in [A.5 Type
-Entries](#a-5-type-entries).
+Entries](#a5-type-entries).
 
 To implement the fully generalized version of this attribute, GCC would only
 need to change the last operation in the expression from `DW_OP_plus` to
 `DW_OP_LLVM_offset`.
 
 ## 3.3 Limitations
 
 DWARF 5 is unable to describe variables in runtime indexed parts of registers.

 descriptions.
 
 Similarly, the DWARF expression associated with attributes such as
 DW_AT_data_member_location that are evaluated with an initial stack containing a
 location description, or a DWARF operation expression that uses the
 DW_OP_push_object_address operation, may want to act on the result of another
 expression that returned a location description involving multiple places.
 
-Therefore, the extension needs to define how expression operations that use those
-results will behave. The extension does this by generalizing the expression stack
-to allow an entry to be one or more single location descriptions. In doing this,
-it unifies the definitions of DWARF operation expressions and loclist
-expressions in a natural way.
+Therefore, the extension needs to define how expression operations that use
+those results will behave. The extension does this by generalizing the
+expression stack to allow an entry to be one or more single location
+descriptions. In doing this, it unifies the definitions of DWARF operation
+expressions and loclist expressions in a natural way.
 
 All operations that act on location descriptions are extended to act on multiple
 single location descriptions. For example, the DW_OP_offset operation adds the
 offset to each single location description. The DW_OP_deref* operations simply
 read the storage of one of the single location descriptions, since multiple
 single location descriptions must all hold the same value. Similarly, if the
 evaluation of a DWARF expression results in multiple single location
 descriptions, the consumer can ensure any updates are done to all of them, and

 
 DWARF expressions describe how to compute a value or specify a location.
 
 <i>The evaluation of a DWARF expression can provide the location of an object,
 the value of an array bound, the length of a dynamic string, the desired value
 itself, and so on.</i>
 
 If the evaluation of a DWARF expression does not encounter an error, then it can
-either result in a value (see [2.5.2 DWARF Expression
-Value](#dwarf-expression-value)) or a location description (see [2.5.3 DWARF
-Location Description](#dwarf-location-description)). When a DWARF expression
-is evaluated, it may be specified whether a value or location description is
-required as the result kind.
+either result in a value (see [A.2.5.2 DWARF Expression
+Value](#a252-dwarf-expression-value)) or a location description (see [A.2.5.3
+DWARF Location Description](#a253-dwarf-location-description)). When a DWARF
+expression is evaluated, it may be specified whether a value or location
+description is required as the result kind.
 
 If a result kind is specified, and the result of the evaluation does not match
-the specified result kind, then the implicit conversions described in [2.5.4.4.3
-Memory Location Description
-Operations](#memory-location-description-operations) are performed if
+the specified result kind, then the implicit conversions described in
+[A.2.5.4.4.3 Memory Location Description
+Operations](#a25443-memory-location-description-operations) are performed if
 valid. Otherwise, the DWARF expression is ill-formed.
 
 If the evaluation of a DWARF expression encounters an evaluation error, then the
 result is an evaluation error.
 
 > NOTE: Decided to define the concept of an evaluation error. An alternative is
 > to introduce an undefined value base type in a similar way to location
 > descriptions having an undefined location description. Then operations that
 > encounter an evaluation error can return the undefined location description or
 > value with an undefined base type.
 >
 > All operations that act on values would return an undefined entity if given an
 > undefined value. The expression would then always evaluate to completion, and
 > can be tested to determine if it is an undefined entity.
 >
 > However, this would add considerable additional complexity and does not match
 > that GDB throws an exception when these evaluation errors occur.
 
 If a DWARF expression is ill-formed, then the result is undefined.
 
 The following sections detail the rules for when a DWARF expression is
 ill-formed or results in an evaluation error.
 
-A DWARF expression can either be encoded as an operation expression (see [2.5.4
-DWARF Operation Expressions](#dwarf-operation-expressions)), or as a
-location list expression (see [2.5.5 DWARF Location List
-Expressions](#dwarf-location-list-expressions)).
+A DWARF expression can either be encoded as an operation expression (see
+[A.2.5.4 DWARF Operation Expressions](#a254-dwarf-operation-expressions)), or as
+a location list expression (see [A.2.5.5 DWARF Location List
+Expressions](#a255-dwarf-location-list-expressions)).
 
 #### A.2.5.1 DWARF Expression Evaluation Context
 
 A DWARF expression is evaluated in a context that can include a number of
 context elements. If multiple context elements are specified then they must be
 self consistent or the result of the evaluation is undefined. The context
 elements that can be specified are:
 

 
 3.  <i>A current call frame</i>
 
     The target architecture call frame identifier. It identifies a call frame
     that corresponds to an active invocation of a subprogram in the current
     thread. It is identified by its address on the call stack. The address is
     referred to as the Canonical Frame Address (CFA). The call frame information
     is used to determine the CFA for the call frames of the current thread's
-    call stack (see [6.4 Call Frame Information](#call-frame-information)).
+    call stack (see [A.6.4 Call Frame
+    Information](#a64-call-frame-information)).
 
     It is required for operations that specify target architecture registers to
     support virtual unwinding of the call stack.
 
     <i>For example, the `DW_OP_*reg*` operations.</i>
 
     If specified, it must be an active call frame in the current thread.
     Otherwise the result is undefined.
 
     If it is the currently executing call frame, then it is termed the top call
     frame.
 
 4.  <i>A current program location</i>
 
     The target architecture program location corresponding to the current call
     frame of the current thread.
 
     The program location of the top call frame is the target architecture
     program counter for the current thread. The call frame information is used
     to obtain the value of the return address register to determine the program
-    location of the other call frames (see [6.4 Call Frame
-    Information](#call-frame-information)).
+    location of the other call frames (see [A.6.4 Call Frame
+    Information](#a64-call-frame-information)).
 
     It is required for the evaluation of location list expressions to select
     amongst multiple program location ranges. It is required for operations that
     specify target architecture registers to support virtual unwinding of the
-    call stack (see [6.4 Call Frame Information](#call-frame-information)).
+    call stack (see [A.6.4 Call Frame Information](#a64-call-frame-information)).
 
     If specified:
 
     - If the current call frame is the top call frame, it must be the current
       target architecture program location.
     - If the current call frame F is not the top call frame, it must be the
       program location associated with the call site in the current caller frame
       F that invoked the callee frame.
- If the current frame is specified and is the top frame, and if the current
       as the target architecture of the current thread.
 
     - If the current compilation unit is specified, then the current target
       architecture default address space address size must be the same as the
       `address_size` field in the header of the current compilation unit and any
       associated entry in the `.debug_aranges` section.
     - If the current program location is specified, then the current target
       architecture must be the same as the target architecture of any line
-      number information entry (see [6.2 Line Number
-      Information](#line-number-information)) corresponding to the current
+      number information entry (see [A.6.2 Line Number
+      Information](#a62-line-number-information)) corresponding to the current
       program location.
     - If the current program location is specified, then the current target
       architecture default address space address size must be the same as the
       `address_size` field in the header of any entry corresponding to the
       current program location in the `.debug_addr`, `.debug_line`,
       `.debug_rnglists`, `.debug_rnglists.dwo`, `.debug_loclists`, and
       `.debug_loclists.dwo` sections.
     - Otherwise the result is undefined.
 
 7.  <i>A current object</i>
 
     The location description of a program object.
 
     It is required for the `DW_OP_push_object_address` operation.
 
     <i>For example, the `DW_AT_data_location` attribute on type debug
     information entries specifies the program object corresponding to a runtime
     descriptor as the current object when it evaluates its associated
     expression.</i>
 
-    The result is undefined if the location description is invalid (see [2.5.3
-    DWARF Location Description](#dwarf-location-description)).
+    The result is undefined if the location description is invalid (see [A.2.5.3
+    DWARF Location Description](#a253-dwarf-location-description)).
 
 8.  <i>An initial stack</i>
 
     This is a list of values or location descriptions that will be pushed on the
     operation expression evaluation stack in the order provided before
     evaluation of an operation expression starts.
 
     Some debugger information entries have attributes that evaluate their DWARF
     expression value with initial stack entries. In all other cases the initial
     stack is empty.
 
-    The result is undefined if any location descriptions are invalid (see [2.5.3
-    DWARF Location Description](#dwarf-location-description)).
+    The result is undefined if any location descriptions are invalid (see
+    [A.2.5.3 DWARF Location Description](#a253-dwarf-location-description)).
 
 If the evaluation requires a context element that is not specified, then the
 result of the evaluation is an error.
 
 <i>A DWARF expression for a location description may be able to be evaluated
 without a thread, call frame, program location, or architecture context. For
 example, the location of a global variable may be able to be evaluated without
 such context. If the expression evaluates with an error then it may indicate the
 variable has been optimized and so requires more context.</i>
 
-<i>The DWARF expression for call frame information (see [6.4 Call Frame
-Information](#call-frame-information)) operations are restricted to those
+<i>The DWARF expression for call frame information (see [A.6.4 Call Frame
+Information](#a64-call-frame-information)) operations are restricted to those
 that do not require the compilation unit context to be specified.</i>
 
 The DWARF is ill-formed if all the `address_size` fields in the headers of all
 the entries in the `.debug_info`, `.debug_addr`, `.debug_line`,
 `.debug_rnglists`, `.debug_rnglists.dwo`, `.debug_loclists`, and
 `.debug_loclists.dwo` sections corresponding to any given program location do
 not match.
 

 > information entry and byte offset provided by the operations.
 
 <i>Location descriptions are a language independent representation of addressing
 rules.</i>
 
 - <i>They can be the result of evaluating a debugger information entry attribute
   that specifies an operation expression of arbitrary complexity. In this usage
   they can describe the location of an object as long as its lifetime is either
-  static or the same as the lexical block (see [3.5 Lexical Block
-  Entries](#lexical-block-entries)) that owns it, and it does not move during
-  its lifetime.</i>
+  static or the same as the lexical block (see [A.3.5 Lexical Block
+  Entries](#a35-lexical-block-entries)) that owns it, and it does not move
+  during its lifetime.</i>
 
 - <i>They can be the result of evaluating a debugger information entry attribute
   that specifies a location list expression. In this usage they can describe the
   location of an object that has a limited lifetime, changes its location during
   its lifetime, or has multiple locations over part or all of its lifetime.</i>
 
 If a location description has more than one single location description, the
 DWARF expression is ill-formed if the object value held in each single location

 An operation expression is comprised of a stream of operations, each consisting
 of an opcode followed by zero or more operands. The number of operands is
 implied by the opcode.
 
 Operations represent a postfix operation on a simple stack machine. Each stack
 entry can hold either a value or a location description. Operations can act on
 entries on the stack, including adding entries and removing entries. If the kind
 of a stack entry does not match the kind required by the operation and is not
-implicitly convertible to the required kind (see [2.5.4.4.3 Memory Location
-Description Operations](#memory-location-description-operations)), then
+implicitly convertible to the required kind (see [A.2.5.4.4.3 Memory Location
+Description Operations](#a25443-memory-location-description-operations)), then
 the DWARF operation expression is ill-formed.
 
 Evaluation of an operation expression starts with an empty stack on which the
 entries from the initial stack provided by the context are pushed in the order
 provided. Then the operations are evaluated, starting with the first operation
 of the stream. Evaluation continues until either an operation has an evaluation
 error, or until one past the last operation of the stream is reached.
 
 The result of the evaluation is:
 
 - If an operation has an evaluation error, or an operation evaluates an
   expression that has an evaluation error, then the result is an evaluation
   error.
 - If the current result kind specifies a location description, then:
   - If the stack is empty, the result is a location description with one
     undefined location description.
 
     <i>This rule is for backwards compatibility with DWARF Version 5 which uses
     an empty operation expression for this purpose.</i>
 
   - If the top stack entry is a location description, or can be converted to one
-    (see [2.5.4.4.3 Memory Location Description
-    Operations](#memory-location-description-operations)), then the result
-    is that, possibly converted, location description. Any other entries on the
-    stack are discarded.
+    (see [A.2.5.4.4.3 Memory Location Description
+    Operations](#a25443-memory-location-description-operations)), then the
+    result is that, possibly converted, location description. Any other entries
+    on the stack are discarded.
   - Otherwise the DWARF expression is ill-formed.
 
     > NOTE: Could define this case as returning an implicit location description
     > as if the `DW_OP_implicit` operation is performed.
 
 - If the current result kind specifies a value, then:
   - If the top stack entry is a value, or can be converted to one (see
-    [2.5.4.4.3 Memory Location Description
-    Operations](#memory-location-description-operations)), then the result is
-    that, possibly converted, value. Any other entries on the stack are
-    discarded.
+    [A.2.5.4.4.3 Memory Location Description
+    Operations](#a25443-memory-location-description-operations)), then the
+    result is that, possibly converted, value. Any other entries on the stack
+    are discarded.
   - Otherwise the DWARF expression is ill-formed.
 - If the current result kind is not specified, then:
   - If the stack is empty, the result is a location description with one
     undefined location description.
 
     <i>This rule is for backwards compatibility with DWARF Version 5 which uses
     an empty operation expression for this purpose.</i>
 
     > NOTE: This rule is consistent with the rule above for when a location
     > description is requested. However, GDB appears to report this as an error
     > and no GDB tests appear to cause an empty stack for this case.
 
   - Otherwise, the top stack entry is returned. Any other entries on the stack
     are discarded.
 
 An operation expression is encoded as a byte block with some form of prefix that
 specifies the byte count. It can be used:
 
 - as the value of a debugging information entry attribute that is encoded using
-  class `exprloc` (see [7.5.5 Classes and Forms](#classes-and-forms)),
+  class `exprloc` (see [A.7.5.5 Classes and Forms](#a755-classes-and-forms)),
 - as the operand to certain operation expression operations,
-- as the operand to certain call frame information operations (see [6.4 Call
-  Frame Information](#call-frame-information)),
-- and in location list entries (see [2.5.5 DWARF Location List
-  Expressions](#dwarf-location-list-expressions)).
+- as the operand to certain call frame information operations (see [A.6.4 Call
+  Frame Information](#a64-call-frame-information)),
+- and in location list entries (see [A.2.5.5 DWARF Location List
+  Expressions](#a255-dwarf-location-list-expressions)).
 
 ##### A.2.5.4.1 Stack Operations
 
 > NOTE: This section replaces DWARF Version 5 section 2.5.1.3.
 
 The following operations manipulate the DWARF stack. Operations that index the
 stack assume that the top of the stack (most recently added entry) has index 0.
 They allow the stack entries to be either a value or location description.
 
 If any stack entry accessed by a stack operation is an incomplete composite
-location description (see [2.5.4.4.6 Composite Location Description
-Operations](#composite-location-description-operations)), then the DWARF
+location description (see [A.2.5.4.4.6 Composite Location Description
+Operations](#a25446-composite-location-description-operations)), then the DWARF
 expression is ill-formed.
 
 > NOTE: These operations now support stack entries that are values and location
 > descriptions.
 
 > NOTE: If it is desired to also make them work with incomplete composite
 > location descriptions, then would need to define that the composite location
 > storage specified by the incomplete composite location description is also
4.  `DW_OP_deref_type`
 
     > NOTE: This definition allows the base type to be a bit size since there
     > seems no reason to restrict it.
 
     It is an evaluation error if any bit of the value is retrieved from the
     undefined location storage or the offset of any bit exceeds the size of the
     location storage LS specified by any single location description SL of L.
 
-    See [2.5.4.4.5 Implicit Location Description
-    Operations](#implicit-location-description-operations) for special
+    See [A.2.5.4.4.5 Implicit Location Description
+    Operations](#a25445-implicit-location-description-operations) for special
     rules concerning implicit location descriptions created by the
     `DW_OP_implicit_pointer` operation.
 
 5.  `DW_OP_xderef`
 
     `DW_OP_xderef` pops two stack entries. The first must be an integral type
     value that represents an address A. The second must be an integral type
     value that represents a target architecture specific address space
8.  `DW_OP_entry_value` <i>Deprecated</i>
     is a block of bytes, with a length equal S, interpreted as a DWARF operation
     expression E.
 
     E is evaluated with the current context, except the result kind is
     unspecified, the call frame is the one that called the current frame, the
     program location is the call site in the calling frame, the object is
     unspecified, and the initial stack is empty. The calling frame information
     is obtained by virtually unwinding the current call frame using the call
-    frame information (see [6.4 Call Frame
-    Information](#call-frame-information)).
+    frame information (see [A.6.4 Call Frame
+    Information](#a64-call-frame-information)).
 
-    If the result of E is a location description L (see [2.5.4.4.4 Register
+    If the result of E is a location description L (see [A.2.5.4.4.4 Register
     Location Description
-    Operations](#register-location-description-operations)), and the last
+    Operations](#a25444-register-location-description-operations)), and the last
     operation executed by E is a `DW_OP_reg*` for register R with a target
     architecture specific base type of T, then the contents of the register are
     retrieved as if a `DW_OP_deref_type DR` operation was performed where DR is
     the offset of a hypothetical debug information entry in the current
     compilation unit for T. The resulting value V is pushed on the stack.
 
     <i>Using `DW_OP_reg*` provides a more compact form for the case where the
     value was in a register on entry to the subprogram.</i>

 > error. Otherwise, GDB zero-extends V to 64 bits. If the GDB target defines a
 > hook function, then it is called. The target specific hook function can modify
 > the 64-bit value, possibly sign extending based on the original value type.
 > Finally, GDB treats the 64-bit value V as a memory location address.
 
 If a stack entry is required to be a location description, but it is an implicit
 pointer value IPV with the target architecture default address space, then it is
 implicitly converted to a location description with one single location
-description specified by IPV. See [2.5.4.4.5 Implicit Location Description
-Operations](#implicit-location-description-operations).
+description specified by IPV. See [A.2.5.4.4.5 Implicit Location Description
+Operations](#a25445-implicit-location-description-operations).
 
 If a stack entry is required to be a value, but it is a location description L
 with one memory location description SL in the target architecture default
 address space with a bit offset B that is a multiple of 8, then it is implicitly
 converted to a value equal to B divided by 8 (the byte size) with the generic
 type.
 
 1.  `DW_OP_addr`
3.  `DW_OP_form_tls_address`
     complex thread-local storage calculations into the DWARF expressions, the
     `DW_OP_form_tls_address` allows the consumer to perform the computation
     based on the target architecture specific run-time environment.</i>
 
 4.  `DW_OP_call_frame_cfa`
 
     `DW_OP_call_frame_cfa` pushes the location description L of the Canonical
     Frame Address (CFA) of the current subprogram, obtained from the call frame
-    information on the stack. See [6.4 Call Frame
-    Information](#call-frame-information).
+    information on the stack. See [A.6.4 Call Frame
+    Information](#a64-call-frame-information).
 
     <i>Although the value of the `DW_AT_frame_base` attribute of the debugger
     information entry corresponding to the current subprogram can be computed
     using a location list expression, in some cases this would require an
     extensive location list because the values of the registers used in
     computing the CFA change during a subprogram execution. If the call frame
     information is present, then it already encodes such changes, and it is
     space efficient to reference that using the `DW_OP_call_frame_cfa`
     operation.</i>
 
 5.  `DW_OP_fbreg`
 
     `DW_OP_fbreg` has a single signed LEB128 integer operand that represents a
     byte displacement B.
 
     The location description L for the <i>frame base</i> of the current
     subprogram is obtained from the `DW_AT_frame_base` attribute of the debugger
     information entry corresponding to the current subprogram as described in
-    [3.3.5 Low-Level Information](#low-level-information).
+    [A.3.3.5 Low-Level Information](#a335-low-level-information).
 
     The location description L is updated by bit offset B scaled by 8 (the byte
     size) and pushed on the stack.
 
 6.  `DW_OP_breg0`, `DW_OP_breg1`, ..., `DW_OP_breg31`
 
     The `DW_OP_breg<N>` operations encode the numbers of up to 32 registers,
     numbered from 0 through 31, inclusive. The register number R corresponds to
2.  `DW_OP_regx`
     target architecture register number R.
 
     If the current call frame is the top call frame, it pushes a location
     description L that specifies one register location description SL on the
     stack. SL specifies the register location storage that corresponds to R with
     a bit offset of 0 for the current thread.
 
     If the current call frame is not the top call frame, call frame information
-    (see [6.4 Call Frame Information](#call-frame-information)) is used to
+    (see [A.6.4 Call Frame Information](#a64-call-frame-information)) is used to
     determine the location description that holds the register for the current
     call frame and current program location of the current thread. The resulting
     location description L is pushed.
 
     <i>Note that if call frame information is used, the resulting location
     description may be register, memory, or undefined.</i>
 
     <i>An implementation may evaluate the call frame information immediately, or
- Otherwise, the operation expression E of each matching location list entry is
   evaluation of E.
 
   The result is a location description that is comprised of the union of the
   single location descriptions of the location description result of each
   matching location list entry.
 
 A location list expression can only be used as the value of a debugger
 information entry attribute that is encoded using class `loclist` or
-`loclistsptr` (see [7.5.5 Classes and Forms](#classes-and-forms)). The value of
-the attribute provides an index into a separate object file section called
-`.debug_loclists` or `.debug_loclists.dwo` (for split DWARF object files) that
-contains the location list entries.
+`loclistsptr` (see [A.7.5.5 Classes and Forms](#a755-classes-and-forms)). The
+value of the attribute provides an index into a separate object file section
+called `.debug_loclists` or `.debug_loclists.dwo` (for split DWARF object files)
+that contains the location list entries.
 
 A `DW_OP_call*` and `DW_OP_implicit_pointer` operation can be used to specify a
 debugger information entry attribute that has a location list expression.
 Several debugger information entry attributes allow DWARF expressions that are
 evaluated with an initial stack that includes a location description that may
 originate from the evaluation of a location list expression.
 
 <i>This location list representation, the `loclist` and `loclistsptr` class, and
3.  If a `DW_TAG_subprogram` or `DW_TAG_entry_point` debugger information entry
     is lexically nested, it may have a `DW_AT_static_link` attribute, whose
     value is a DWARF expression E.
 
     The result of the attribute is obtained by evaluating E with a context that
     has a result kind of a location description, an unspecified object, the
     compilation unit that contains E, an empty initial stack, and other context
     elements corresponding to the source language thread of execution upon which
     the user is focused, if any. The result of the evaluation is the location
-    description L of the <i>canonical frame address</i> (see [6.4 Call Frame
-    Information](#call-frame-information)) of the relevant call frame of the
+    description L of the <i>canonical frame address</i> (see [A.6.4 Call Frame
+    Information](#a64-call-frame-information)) of the relevant call frame of the
     subprogram instance that immediately lexically encloses the current call
     frame's subprogram or entry point.
 
     The DWARF is ill-formed if L is is not comprised of one memory location
     description for one of the target architecture specific address spaces.
 
 ### A.3.4 Call Site Entries and Parameters
 
1.  A `DW_TAG_call_site_parameter` debugger information entry may have a
     value in L<sub>2</sub> at the time of the call made by the call site.
 
     The result of these attributes is undefined if the current call frame is not for
     the subprogram containing the `DW_TAG_call_site_parameter` debugger information
     entry or the current program location is not for the call site containing the
     `DW_TAG_call_site_parameter` debugger information entry in the current call
     frame.
 
-    <i>The consumer may have to virtually unwind to the call site (see [6.4 Call
-    Frame Information](#call-frame-information)) in order to evaluate these
-    attributes. This will ensure the source language thread of execution upon which
-    the user is focused corresponds to the call site needed to evaluate the
-    expression.</i>
+    <i>The consumer may have to virtually unwind to the call site (see [A.6.4
+    Call Frame Information](#a64-call-frame-information)) in order to evaluate
+    these attributes. This will ensure the source language thread of execution
+    upon which the user is focused corresponds to the call site needed to
+    evaluate the expression.</i>
 
     If it is not possible to avoid the expressions of these attributes from
     accessing registers or memory locations that might be clobbered by the
     subprogram being called by the call site, then the associated attribute should
     not be provided.
 
     <i>The reason for the restriction is that the parameter may need to be accessed
     during the execution of the callee. The consumer may virtually unwind from the
     called subprogram back to the caller and then evaluate the attribute
-    expressions. The call frame information (see [6.4 Call Frame
-    Information](#call-frame-information)) will not be able to restore registers
+    expressions. The call frame information (see [A.6.4 Call Frame
+    Information](#a64-call-frame-information)) will not be able to restore registers
     that have been clobbered, and clobbered memory will no longer have the value at
     the time of the call.</i>
 
 ### A.3.5 Lexical Block Entries
 
 > NOTE: This section is the same as DWARF Version 5 section 3.5.
 
 ## A.4 Data Object and Object List Entries
1.  A `DW_AT_location` attribute, whose value is a DWARF expression E that
 
     The result of the attribute is obtained by evaluating E with a context that
     has a result kind of a location description, an unspecified object, the
     compilation unit that contains E, an empty initial stack, and other context
     elements corresponding to the source language thread of execution upon which
     the user is focused, if any. The result of the evaluation is the location
     description of the base of the data object.
 
-    See [2.5.4.2 Control Flow Operations](#control-flow-operations) for special
-    evaluation rules used by the `DW_OP_call*` operations.
+    See [A.2.5.4.2 Control Flow Operations](#a2542-control-flow-operations) for
+    special evaluation rules used by the `DW_OP_call*` operations.
 
     > NOTE: Delete the description of how the `DW_OP_call*` operations evaluate
     > a `DW_AT_location` attribute as that is now described in the operations.
 
     > NOTE: See the discussion about the `DW_AT_location` attribute in the
     > `DW_OP_call*` operation. Having each attribute only have a single purpose
     > and single execution semantics seems desirable. It makes it easier for the
     > consumer that no longer have to track the context. It makes it easier for

 #### A.6.4.1 Structure of Call Frame Information
 
 The register rules are:
 
 1.  <i>undefined</i>
 
     A register that has this rule has no recoverable value in the previous
     frame. The previous value of this register is the undefined location
-    description (see [2.5.4.4.2 Undefined Location Description
-    Operations](#undefined-location-description-operations)).
+    description (see [A.2.5.4.4.2 Undefined Location Description
+    Operations](#a25442-undefined-location-description-operations)).
 
     <i>By convention, the register is not preserved by a callee.</i>
 
 2.  <i>same value</i>
 
     This register has not been modified from the previous caller frame.
 
     If the current frame is the top frame, then the previous value of this
     register is the location description L that specifies one register location
     description SL. SL specifies the register location storage that corresponds
     to the register with a bit offset of 0 for the current thread.
 
     If the current frame is not the top frame, then the previous value of this
     register is the location description obtained using the call frame
     information for the callee frame and callee program location invoked by the
     current caller frame for the same register.
 
     <i>By convention, the register is preserved by the callee, but the callee
     has not modified it.</i>
 
 3.  <i>offset(N)</i>
 
     N is a signed byte offset. The previous value of this register is saved at
     the location description L. Where L is the location description of the
-    current CFA (see [2.5.4 DWARF Operation
-    Expressions](#dwarf-operation-expressions)) updated with the bit offset N
-    scaled by 8 (the byte size).
+    current CFA (see [A.2.5.4 DWARF Operation
+    Expressions](#a254-dwarf-operation-expressions)) updated with the bit offset
+    N scaled by 8 (the byte size).
 
 4.  <i>val_offset(N)</i>
 
     N is a signed byte offset. The previous value of this register is the memory
     byte address of the location description L. Where L is the location
-    description of the current CFA (see [2.5.4 DWARF Operation
-    Expressions](#dwarf-operation-expressions)) updated with the bit offset N
-    scaled by 8 (the byte size).
+    description of the current CFA (see [A.2.5.4 DWARF Operation
+    Expressions](#a254-dwarf-operation-expressions)) updated with the bit offset
+    N scaled by 8 (the byte size).
 
     The DWARF is ill-formed if the CFA location description is not a memory byte
     address location description, or if the register size does not match the
     size of an address in the target architecture default address space.
 
     <i>Since the CFA location description is required to be a memory byte
     address location description, the value of val_offset(N) will also be a
     memory byte address location description since it is offsetting the CFA
5.  <i>register(R)</i>
 
     > NOTE: Should this also allow R to be larger than this register? If so is
     > the value stored in the low order bits and it is undefined what is stored
     > in the extra upper bits?
 
 6.  <i>expression(E)</i>
 
     The previous value of this register is located at the location description
-    produced by evaluating the DWARF operation expression E (see [2.5.4 DWARF
-    Operation Expressions](#dwarf-operation-expressions)).
+    produced by evaluating the DWARF operation expression E (see [A.2.5.4 DWARF
+    Operation Expressions](#a254-dwarf-operation-expressions)).
 
     E is evaluated with the current context, except the result kind is a
     location description, the compilation unit is unspecified, the object is
     unspecified, and an initial stack comprising the location description of the
-    current CFA (see [2.5.4 DWARF Operation
-    Expressions](#dwarf-operation-expressions)).
+    current CFA (see [A.2.5.4 DWARF Operation
+    Expressions](#a254-dwarf-operation-expressions)).
 
 7.  <i>val_expression(E)</i>
 
     The previous value of this register is located at the implicit location
     description created from the value produced by evaluating the DWARF
-    operation expression E (see [2.5.4 DWARF Operation
-    Expressions](#dwarf-operation-expressions)).
+    operation expression E (see [A.2.5.4 DWARF Operation
+    Expressions](#a254-dwarf-operation-expressions)).
 
     E is evaluated with the current context, except the result kind is a value,
     the compilation unit is unspecified, the object is unspecified, and an
     initial stack comprising the location description of the current CFA (see
-    [2.5.4 DWARF Operation Expressions](#dwarf-operation-expressions)).
+    [A.2.5.4 DWARF Operation Expressions](#a254-dwarf-operation-expressions)).
 
     The DWARF is ill-formed if the resulting value type size does not match the
     register size.
 
     > NOTE: This has limited usefulness as the DWARF expression E can only
     > produce values up to the size of the generic type. This is due to not
     > allowing any operations that specify a type in a CFI operation expression.
     > This makes it unusable for registers that are larger than the generic

 
 1.  `length` (initial length)
 
     A constant that gives the number of bytes of the CIE structure, not
     including the length field itself. The size of the length field plus the
     value of length must be an integral multiple of the address size specified
     in the `address_size` field.
 
-2.  `CIE_id` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF
-    Formats](#32-bit-and-64-bit-dwarf-formats))
+2.  `CIE_id` (4 or 8 bytes, see [A.7.4 32-Bit and 64-Bit DWARF
+    Formats](#a74-32-bit-and-64-bit-dwarf-formats))
 
     A constant that is used to distinguish CIEs from FDEs.
 
     In the 32-bit DWARF format, the value of the CIE id in the CIE header is
     0xffffffff; in the 64-bit DWARF format, the value is 0xffffffffffffffff.
 
 3.  `version` (ubyte)
 

 6.  `segment_selector_size` (ubyte)
 
     The size of a segment selector in this CIE and any FDEs that use it, in
     bytes.
 
 7.  `code_alignment_factor` (unsigned LEB128)
 
     A constant that is factored out of all advance location instructions (see
-    [6.4.2.1 Row Creation Instructions](#row-creation-instructions)). The
-    resulting value is `(operand * code_alignment_factor)`.
+    [A.6.4.2.1 Row Creation
+    Instructions](#a6421-row-creation-instructions)). The resulting value is
+    `(operand * code_alignment_factor)`.
 
 8.  `data_alignment_factor` (signed LEB128)
 
-    A constant that is factored out of certain offset instructions (see [6.4.2.2
-    CFA Definition Instructions](#cfa-definition-instructions) and [6.4.2.3
-    Register Rule Instructions](#register-rule-instructions)). The
-    resulting value is `(operand * data_alignment_factor)`.
+    A constant that is factored out of certain offset instructions (see
+    [A.6.4.2.2 CFA Definition Instructions](#a6422-cfa-definition-instructions)
+    and [A.6.4.2.3 Register Rule
+    Instructions](#a6423-register-rule-instructions)). The resulting value is
+    `(operand * data_alignment_factor)`.
 
 9.  `return_address_register` (unsigned LEB128)
 
     An unsigned LEB128 constant that indicates which column in the rule table
     represents the return address of the subprogram. Note that this column might
     not correspond to an actual machine register.
 
     The value of the return address register is used to determine the program

 
 1.  `length` (initial length)
 
     A constant that gives the number of bytes of the header and instruction
     stream for this subprogram, not including the length field itself. The size
     of the length field plus the value of length must be an integral multiple of
     the address size.
 
-2.  `CIE_pointer` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF
-    Formats](#32-bit-and-64-bit-dwarf-formats))
+2.  `CIE_pointer` (4 or 8 bytes, see [A.7.4 32-Bit and 64-Bit DWARF
+    Formats](#a74-32-bit-and-64-bit-dwarf-formats))
 
     A constant offset into the `.debug_frame` section that denotes the CIE that
     is associated with this FDE.
 
 3.  `initial_location` (segment selector and target address)
 
     The address of the first location associated with this table entry. If the
     segment_selector_size field of this FDE's CIE is non-zero, the initial
     location is preceded by a segment selector of the given length.
 
 4.  `address_range` (target address)
 
     The number of bytes of program instructions described by this entry.
 
 5.  `instructions` (array of ubyte)
 
-    A sequence of table defining instructions that are described in [6.4.2 Call
-    Frame Instructions](#call-frame-instructions).
+    A sequence of table defining instructions that are described in [A.6.4.2 Call
+    Frame Instructions](#a642-call-frame-instructions).
 
 6.  `padding` (array of ubyte)
 
     Enough `DW_CFA_nop` instructions to make the size of this entry match the
     length value above.
 
 #### A.6.4.2 Call Frame Instructions
 
 Some call frame instructions have operands that are encoded as DWARF operation
-expressions E (see [2.5.4 DWARF Operation
-Expressions](#dwarf-operation-expressions)). The DWARF operations that can be
+expressions E (see [A.2.5.4 DWARF Operation
+Expressions](#a254-dwarf-operation-expressions)). The DWARF operations that can be
 used in E have the following restrictions:
 
 - `DW_OP_addrx`, `DW_OP_call2`, `DW_OP_call4`, `DW_OP_call_ref`,
   `DW_OP_const_type`, `DW_OP_constx`, `DW_OP_convert`, `DW_OP_deref_type`,
   `DW_OP_fbreg`, `DW_OP_implicit_pointer`, `DW_OP_regval_type`,
   `DW_OP_reinterpret`, and `DW_OP_xderef_type` operations are not allowed
   because the call frame information must not depend on other debug sections.
 - `DW_OP_push_object_address` is not allowed because there is no object context
6.  `DW_CFA_def_cfa_expression`
 
     The `DW_CFA_def_cfa_expression` instruction takes a single operand encoded
     as a `DW_FORM_exprloc` value representing a DWARF operation expression E.
     The required action is to define the current CFA rule to be equivalent to
     the result of evaluating E with the current context, except the result kind
     is a location description, the compilation unit is unspecified, the object
     is unspecified, and an empty initial stack.
 
-    <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
-    restrictions on the DWARF expression operations that can be used in E.</i>
+    <i>See [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions)
+    regarding restrictions on the DWARF expression operations that can be used
+    in E.</i>
 
     The DWARF is ill-formed if the result of evaluating E is not a memory byte
     address location description.
 
 ##### A.6.4.2.3 Register Rule Instructions
 
 1.  `DW_CFA_undefined`
 
9.  `DW_CFA_expression`
     value representing a register number R, and a `DW_FORM_block` value
     representing a DWARF operation expression E. The required action is to
     change the rule for the register specified by R to be an
     <i>expression(E)</i> rule.
 
     <i>That is, E computes the location description where the register value can
     be retrieved.</i>
 
-    <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
-    restrictions on the DWARF expression operations that can be used in E.</i>
+    <i>See [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions)
+    regarding restrictions on the DWARF expression operations that can be used
+    in E.</i>
 
 10. `DW_CFA_val_expression`
 
     The `DW_CFA_val_expression` instruction takes two operands: an unsigned
     LEB128 value representing a register number R, and a `DW_FORM_block` value
     representing a DWARF operation expression E. The required action is to
     change the rule for the register specified by R to be a
     <i>val_expression(E)</i> rule.
 
     <i>That is, E computes the value of register R.</i>
 
-    <i>See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding
-    restrictions on the DWARF expression operations that can be used in E.</i>
+    <i>See [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions)
+    regarding restrictions on the DWARF expression operations that can be used
+    in E.</i>
 
     If the result of evaluating E is not a value with a base type size that
     matches the register size, then the DWARF is ill-formed.
 
 11. `DW_CFA_restore`
 
     The `DW_CFA_restore` instruction takes a single operand (encoded with the
     opcode) that represents a register number R. The required action is to

llvm/docs/DeveloperPolicy.rst

 6. After the initial merge, the target community can stop numbering patches and
    start working asynchronously on the target to complete support. They should
    still seek review from those who helped them in the initial phase, to make
    sure the progress is still consistent.
 7. Once all official requirements have been fulfilled (as above), the code owner
    should request the target to be enabled by default by sending another RFC to
    the `LLVM Discourse forums`_.
 
+.. _adding an established project to the LLVM monorepo:
+
 Adding an Established Project To the LLVM Monorepo
 --------------------------------------------------
 
 The `LLVM monorepo <https://github.com/llvm/llvm-project>`_ is the centerpoint
 of development in the LLVM world, and has all of the primary LLVM components,
 including the LLVM optimizer and code generators, Clang, LLDB, etc.  `Monorepos
 in general <https://en.wikipedia.org/wiki/Monorepo>`_ are great because they
 allow atomic commits to the project, simplify CI, and make it easier for

llvm/docs/GitRepositoryPolicy.md

 * The repo contains a `CONTRIBUTING.md`, ideally copy this from
   [llvm-project](https://github.com/llvm/llvm-project/blob/main/CONTRIBUTING.md).
 * The repo contains a `LICENSE.TXT`, preferably copy this from
   [llvm-project](https://github.com/llvm/llvm-project/blob/main/LICENSE.TXT).
   Other licences need to be discussed case-by-case.
 
 If you want to integrate your project as part of the Monorepo, please take a
 look at the
-[Developer Policy](DeveloperPolicy.html#adding-an-established-project-to-the-llvm-monorepo>).
+[Developer Policy](adding an established project to the LLVM monorepo).
 
 To request a new repository, please create an issue with the
 [Infrastructure Working Group](https://github.com/llvm/llvm-iwg/issues).
 
 ## Repo access on GitHub
 
 Some 3rd party applications require write access to our GitHub organisation in
 order to work properly. Typical examples are continuous integration services
 reporting build results back to GitHub. We consider granting access to such
 application if they provide benefits to the LLVM community and do not raise
 privacy or security concerns.
 
 To request access please run an RFC on the mailing list and get community
 feedback.

llvm/docs/MarkdownQuickstartTemplate.md

......+:.                    ..
                       ...+. .: .
                          .++:..
                           ...
 
 ##### Hopefully you won't need to be this deep
 
 If you need to do fancier things than what has been shown in this document,
 you can mail the list or check the [Common Mark spec].  Sphinx specific
-integration documentation can be found in the [recommonmark docs].
+integration documentation can be found in the [MyST docs].
 
 [Common Mark spec]: http://spec.commonmark.org/0.28/
-[recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html
+[MyST docs]: https://myst-parser.readthedocs.io/en/latest/
 
 ## Generating the documentation
 
-see [Sphinx Quickstart Template](SphinxQuickstartTemplate.html#generating-the-documentation)
+see [Sphinx Quickstart Template](generating the documentation)

llvm/docs/PointerAuth.md

 used to replace the signed pointer value.
 
 At the IR level, it is represented using:
 
 * a [set of intrinsics](#intrinsics) (to sign/authenticate pointers)
 * a [call operand bundle](#operand-bundle) (to authenticate called pointers)
 
 The current implementation leverages the
-[Armv8.3-A PAuth/Pointer Authentication Code](#armv8-3-a-pauth-pointer-authentication-code)
+[Armv8.3-A PAuth/Pointer Authentication Code](#armv83-a-pauth-pointer-authentication-code)
 instructions in the [AArch64 backend](#aarch64-support).
 This support is used to implement the Darwin arm64e ABI, as well as the
 [PAuth ABI Extension to ELF](https://github.com/ARM-software/abi-aa/blob/main/pauthabielf64/pauthabielf64.rst).
 
 
 ## LLVM IR Representation
 
 ### Intrinsics

 
 ##### Semantics:
 
 The '``llvm.ptrauth.strip``' intrinsic implements the `strip`_ operation.
 It returns a raw pointer value.  It does **not** check that the
 signature is valid.
 
 ``key`` should identify a key that is appropriate for ``value``, as defined
-by the target-specific [keys](#key)).
+by the target-specific [keys](#keys)).
 
 If ``value`` is a raw pointer value, it is returned as-is (provided the ``key``
 is appropriate for the pointer).
 
 If ``value`` is not a pointer value for which ``key`` is appropriate, the
 behavior is target-specific.
 
 If ``value`` is a signed pointer value, but ``key`` does not identify the

 ##### Semantics:
 
 The '``llvm.ptrauth.sign_generic``' intrinsic computes the signature of a given
 combination of value and additional diversity data.
 
 It returns a full signature value (as opposed to a signed pointer value, with
 an embedded partial signature).
 
-As opposed to [``llvm.ptrauth.sign``](#llvm-ptrauth-sign), it does not interpret
+As opposed to [``llvm.ptrauth.sign``](#llvmptrauthsign), it does not interpret
 ``value`` as a pointer value.  Instead, it is an arbitrary data value.
 
 
 #### '``llvm.ptrauth.blend``'
 
 ##### Syntax:
 
 ```llvm

 with a pointer address discriminator, in a way that is specified by the target
 implementation.
 
 
 ### Operand Bundle
 
 Function pointers used as indirect call targets can be signed when materialized,
 and authenticated before calls.  This can be accomplished with the
-[``llvm.ptrauth.auth``](#llvm-ptrauth-auth) intrinsic, feeding its result to
+[``llvm.ptrauth.auth``](#llvmptrauthauth) intrinsic, feeding its result to
 an indirect call.
 
 However, that exposes the intermediate, unauthenticated pointer, e.g., if it
 gets spilled to the stack.  An attacker can then overwrite the pointer in
 memory, negating the security benefit provided by pointer authentication.
 To prevent that, the ``ptrauth`` operand bundle may be used: it guarantees that
 the intermediate call target is kept in a register and never stored to memory.
 This hardening benefit is similar to that provided by
-[``llvm.ptrauth.resign``](#llvm-ptrauth-resign)).
+[``llvm.ptrauth.resign``](#llvmptrauthresign)).
 
 Concretely:
 
 ```llvm
 define void @f(void ()* %fp) {
   call void %fp() [ "ptrauth"(i32 <key>, i64 <data>) ]
   ret void
 }

 
 Of those, 4 keys are interchangeably usable to specify the key used in IR
 constructs:
 * ``ASIA``/``ASIB`` are instruction keys (encoded as respectively 0 and 1).
 * ``ASDA``/``ASDB`` are data keys (encoded as respectively 2 and 3).
 
 ``ASGA`` is a special key that cannot be explicitly specified, and is only ever
 used implicitly, to implement the
-[``llvm.ptrauth.sign_generic``](#llvm-ptrauth-sign-generic) intrinsic.
+[``llvm.ptrauth.sign_generic``](#llvmptrauthsign_generic) intrinsic.
 
 #### Instructions
 
 The IR [Intrinsics](#intrinsics) described above map onto these
 instructions as such:
-* [``llvm.ptrauth.sign``](#llvm-ptrauth-sign): ``PAC{I,D}{A,B}{Z,SP,}``
-* [``llvm.ptrauth.auth``](#llvm-ptrauth-auth): ``AUT{I,D}{A,B}{Z,SP,}``
-* [``llvm.ptrauth.strip``](#llvm-ptrauth-strip): ``XPAC{I,D}``
-* [``llvm.ptrauth.blend``](#llvm-ptrauth-blend): The semantics of the blend
+* [``llvm.ptrauth.sign``](#llvmptrauthsign): ``PAC{I,D}{A,B}{Z,SP,}``
+* [``llvm.ptrauth.auth``](#llvmptrauthauth): ``AUT{I,D}{A,B}{Z,SP,}``
+* [``llvm.ptrauth.strip``](#llvmptrauthstrip): ``XPAC{I,D}``
+* [``llvm.ptrauth.blend``](#llvmptrauthblend): The semantics of the blend
   operation are specified by the ABI.  In both the ELF PAuth ABI Extension and
   arm64e, it's a ``MOVK`` into the high 16 bits.  Consequently, this limits
   the width of the integer discriminator used in blends to 16 bits.
-* [``llvm.ptrauth.sign_generic``](#llvm-ptrauth-sign-generic): ``PACGA``
-* [``llvm.ptrauth.resign``](#llvm-ptrauth-resign): ``AUT*+PAC*``.  These are
+* [``llvm.ptrauth.sign_generic``](#llvmptrauthsign_generic): ``PACGA``
+* [``llvm.ptrauth.resign``](#llvmptrauthresign): ``AUT*+PAC*``.  These are
   represented as a single pseudo-instruction in the backend to guarantee that
   the intermediate raw pointer value is not spilled and attackable.

llvm/docs/ReleaseNotes.rst

 
 * lit no longer supports using substrings of the default target triple as
   feature names in ``UNSUPPORTED:`` and ``XFAIL:`` directives. These have been
   replaced by the ``target=<triple>`` feature, and tests can use regex
   matching to achieve the same effect. For example, ``UNSUPPORTED: arm``
   would now be ``UNSUPPORTED: target=arm{{.*}}`` and ``XFAIL: windows``
   would now be ``XFAIL: target={{.*}}-windows{{.*}}``.
 
+* The HTML documentation now uses myst-parser instead of recommonmark, since the
+  `latter has been sunset
+  <https://github.com/readthedocs/recommonmark/issues/221>`_.
+  It can be installed via either apt or pip:
+
+  .. code-block:: bash
+
+     apt install python3-myst-parser
+     pip install myst-parser
+
 External Open Source Projects Using LLVM 15
 ===========================================
 
 * A project...
 
 Additional Information
 ======================
 

llvm/docs/SpeculativeLoadHardening.md

 # Speculative Load Hardening
 
-### A Spectre Variant #1 Mitigation Technique
+## A Spectre Variant #1 Mitigation Technique
 
 Author: Chandler Carruth - [[e-mail]](mailto:[e-mail])
 
 ## Problem Statement
 
 Recently, Google Project Zero and other researchers have found information leak
 vulnerabilities by exploiting speculative execution in modern CPUs. These
 exploits are currently broken down into three variants:

llvm/docs/SphinxQuickstartTemplate.rst

......+:.                    ..
           :++.    ..              :
             .+:::+::              :
             ..   . .+            ::
                      +.:      .::+.
                       ...+. .: .
                          .++:..
                           ...
 
+.. _generating the documentation:
        
 Generating the documentation
 ============================
 
 You can generate the HTML documentation from the sources locally if you want to
 see what they would look like. In addition to the normal
 `build tools <docs/GettingStarted.html>`_
 you need to install `Sphinx`_ and the
-`recommonmark <https://recommonmark.readthedocs.io/en/latest/>`_ extension.
+`myst-parser <https://myst-parser.readthedocs.io/en/latest/>`_ extension.
 
 On Debian you can install these with:
 
 .. code-block:: console
 
-   sudo apt install -y sphinx-doc python-recommonmark-doc
+   sudo apt install -y sphinx-doc python3-myst-parser
 
-On Ubuntu use pip to get an up-to-date version of recommonmark:
+On Ubuntu use pip to get an up-to-date version of myst-parser:
 
 .. code-block:: console
 
-   sudo pip install sphinx recommonmark
+   sudo pip install sphinx myst-parser
 
 Then run cmake to build the documentation inside the ``llvm-project`` checkout:
 
 .. code-block:: console
 
    mkdir build
    cd build
    cmake -DLLVM_ENABLE_SPHINX=On ../llvm
    cmake --build . --target docs-llvm-html
 
 In case you already have the Cmake build set up and want to reuse that,
 just set the CMake variable ``LLVM_ENABLE_SPHINX=On``.
 
 After that you find the generated documentation in ``build/docs/html``
 folder.

llvm/docs/conf.py

 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = {
     '.rst': 'restructuredtext',
 }
 
 try:
-  import recommonmark
+  import myst_parser
 except ImportError:
   # manpages do not use any .md sources
   if not tags.has('builder-man'):
     raise
 else:
   import sphinx
   if sphinx.version_info >= (3, 0):
     # This requires 0.5 or later.
-    extensions.append('recommonmark')
+    extensions.append('myst_parser')
   else:
-    source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+    source_parsers = {'.md': 'myst_parser.parsers.sphinx_.MystParser'}
   source_suffix['.md'] = 'markdown'
+  myst_heading_anchors = 7
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.

llvm/utils/release/build-docs.sh

 # Build documentation for LLVM releases.
 #
 # Required Packages:
 # * Fedora:
 #   * dnf install doxygen python3-sphinx texlive-epstopdf ghostscript \
 #                 ninja-build gcc-c++
 #   * pip install sphinx-markdown-tables
 # * Ubuntu:
-#   * apt-get install doxygen sphinx-common python3-recommonmark \
+#   * apt-get install doxygen sphinx-common python3-myst-parser \
 #             ninja-build graphviz texlive-font-utils
 #   * pip install sphinx-markdown-tables
 #===------------------------------------------------------------------------===#
 
 set -ex
 
 builddir=docs-build
 srcdir=$(readlink -f $(dirname "$(readlink -f "$0")")/../..)