[Flang] Move mark down documentation(md) files to reStructuredText(rst) file format.

[sameeranjoshi]

Summary

Note: .md to .rst files were created using m2r
The tool was used by 1600+ users.
https://github.com/miyakogi/m2r

copy files to docs/ folder, delete /documentation folder.

Internal changes in files to modify bad occurances of ".md".

Remove licence headers.

[sameeranjoshi]

To ease in reviewing the output of files when merged in llvm-project.
I have pushed in my local fork of llvm-project.
https://github.com/Sameeranjoshi/llvm-project/blob/sam-docu-rst/flang/

[DavidTruby]

LGTM and they seem to render fine on github too, thanks for sharing that link so we can check that easily!

[richard.barton.arm]

I still see a few mentions of the old documentation dir location in the codebase:

llvm-project/flang$ git grep 'documentation/' .
README.md:Start with the [compiler overview](documentation/Overview.md).
README.md:read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
README.md:flang's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
README.md:the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).
README.md:in [this document](documentation/Extensions.md).
README.md:see the [discussion of intrinsics](documentation/Intrinsics.md).
README.md:see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md).
README.md:read the [style guide](documentation/C++style.md)
README.md:also review [how flang uses modern C++ features](documentation/C++17.md).
docs/Character.rst:   <!--===- documentation/Character.rst
docs/OpenMP-4.5-grammar.txt:#===-- documentation/OpenMP-4.5-grammar.txt --------------------------------===#
docs/f2018-grammar.txt:#===-- documentation/f2018-grammar.txt -------------------------------------===#
docs/flang-c-style.el:;;===-- documentation/flang-c-style.el ------------------------------------===;;
lib/Evaluate/intrinsics.cpp:// documentation/intrinsics.md and section 16 of the Fortran 2018 standard

[tskeith]

Could you please update the summary to indicate why you are making this change?

flang/docs/ArrayComposition.rst

11

What is the purpose of the backslash followed by space? It seems to occur in a lot of places.

[DavidTruby]

flang/docs/ArrayComposition.rst

11

I believe "extra" spaces are removed by rst when rendering to HTML, so the \ will preserve the space

[klausler]

Why are you doing this? *.rst files are ugly and harder than *.md to edit correctly. I don't see how this is any kind of improvement.

[sscalpone]

I think md is the wave of the future. Other llvm subproject use md. Let's stick with what we have unless there's a compelling advantage to using rst or another format.

[DavidTruby]

In D85828#2213245, @sscalpone wrote:

I think md is the wave of the future. Other llvm subproject use md. Let's stick with what we have unless there's a compelling advantage to using rst or another format.

It's not really correct to say that other llvm subprojects use md: with the exception of MLIR every LLVM subproject uses rst, including LLVM itself.

MLIR hosts a separate website elsewhere, which is why they aren't tied to the same format as everyone else. If we want to do that and render the .md files to html instead then we can, but if we want to be on the same website as the rest of LLVM (except MLIR) we need to use rst as the text format.

That is, at least, my understanding for the motivation behind the change. @sameeranjoshi can probably provide a better explanation as it's his change.

[sameeranjoshi]

+1 @DavidTruby - For pointing the reason for MLIR to use .md files.
It's correct that LLVM uses Sphinx infrastructure to build docs for any sub-project except MLIR.

" If we want to do that and render the .md files to html instead then we can, but if we want to be on the same website as the rest of LLVM (except MLIR) we need to use rst as the text format."

I remember we had a light on this issue long back(initial doxygen support) given that we want something like llvm.org/flang or more technically similar flang.llvm.org we would need to move to .rst from .md.
https://github.com/flang-compiler/f18/pull/1065#issuecomment-606721800
https://github.com/flang-compiler/f18/pull/1065#issuecomment-606532420

Here's one such reference recently
https://reviews.llvm.org/D85470#2207363

I tried hard to find any reference from the developers policy to use .rst as documentation formats, with no exact mentioning I found below page
http://llvm.org/docs/SphinxQuickstartTemplate.html
mentioning a few points as

1. Sphinx to be more powerful than markdown file formats.
2. Sending the .rst file to llvm-commits for review.

Neither I am against using .md files nor I have much details on .rst files, but I doubt Flang would render using their own website as MLIR, hence going with the option with LLVM(sphinx build and .rst files) seemed reasonable to be to come up with this patch.

This patch has basically 2 changes :

1. Move files to docs/ folder from documentation/
2. Change them to .rst

And I assume the first set of changes people agree upon & are the discussion seems to be around second point.
Thanks for reviewing all :)

[sameeranjoshi]

In D85828#2213020, @richard.barton.arm wrote:

I still see a few mentions of the old documentation dir location in the codebase:

llvm-project/flang$ git grep 'documentation/' .
README.md:Start with the [compiler overview](documentation/Overview.md).
README.md:read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
README.md:flang's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
README.md:the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).
README.md:in [this document](documentation/Extensions.md).
README.md:see the [discussion of intrinsics](documentation/Intrinsics.md).
README.md:see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md).
README.md:read the [style guide](documentation/C++style.md)
README.md:also review [how flang uses modern C++ features](documentation/C++17.md).
docs/Character.rst:   <!--===- documentation/Character.rst
docs/OpenMP-4.5-grammar.txt:#===-- documentation/OpenMP-4.5-grammar.txt --------------------------------===#
docs/f2018-grammar.txt:#===-- documentation/f2018-grammar.txt -------------------------------------===#
docs/flang-c-style.el:;;===-- documentation/flang-c-style.el ------------------------------------===;;
lib/Evaluate/intrinsics.cpp:// documentation/intrinsics.md and section 16 of the Fortran 2018 standard

Good catch. Thanks I was grepping in a sub directory which was removed later by me.

[schweitz]

In D85828#2213768, @sameeranjoshi wrote:

+1 @DavidTruby - For pointing the reason for MLIR to use .md files.
It's correct that LLVM uses Sphinx infrastructure to build docs for any sub-project except MLIR.

Maybe @mehdi_amini can shed some light on the rationale for the divergence. (The distinction between the links http://clang.llvm.org and http://mlir.llvm.org doesn't seem that large.)

[mehdi_amini]

In D85828#2213275, @DavidTruby wrote:

In D85828#2213245, @sscalpone wrote:

I think md is the wave of the future. Other llvm subproject use md. Let's stick with what we have unless there's a compelling advantage to using rst or another format.

It's not really correct to say that other llvm subprojects use md: with the exception of MLIR every LLVM subproject uses rst, including LLVM itself.

MLIR hosts a separate website elsewhere, which is why they aren't tied to the same format as everyone else. If we want to do that and render the .md files to html instead then we can, but if we want to be on the same website as the rest of LLVM (except MLIR) we need to use rst as the text format.

That is, at least, my understanding for the motivation behind the change. @sameeranjoshi can probably provide a better explanation as it's his change.

Both website are serving HTML: as long as you generate HTML you can serve easily either way.

LLVM is using Sphinx to turn its documentation from RST to HTML and copy this to the webserver.
MLIR is using Hugo (see mlir-www) to turn its .md into HTML and serve it directly from GitHub pages.

There aren't any real underlying technology from the website point of view, MLIR could be hosted with LLVM as well, and use the same theme, etc.

The use of Markdown in MLIR is mostly historical I believe (Google uses heavily markdown for its doc and MLIR started at Google).

The use of GitHub pages instead of llvm.org is because the admins told me back in the fall when I was setting up the website that "it would be nice to migrate llvm.org to GitHub pages".

[sameeranjoshi]

Thanks for detailed information @mehdi_amini and all folks.
TL;DR version:
There is a sweet spot on this issue.
Sphinx supports now .md files.
LLVM has as well added changes in config files to pick up .md files, needs to extend this to flang.

Long version:

Sphinx has a support for markdown format files, but it supports commonmark based markdown flavour[1].
As there are tons of implementations of markdown format, commonmark is a project which standardizes the way we write markdown files.
Github has commonmark flavour supported with some extra specifications/features which they call GFM(Github Flavored Markdown[2])
Github's way of writing markdown files is a subset of commonmark.

So I think that should not be an issue for rendering the current .md files unless people have unknowingly referred GFM and written some parts of the documentation, in that case some changes in documentation would be needed.

Unfortunately, there was a commit[3] in llvm-core long time back which supported this commonmark based format(to move towards .md files) into llvm sphinx builds and buildbots and I guess no sub-project ever used it except to some extent LLVM.

I have fragmented this patch into 2 patches:

1. To move files to docs/ folder - https://reviews.llvm.org/D85884
2. I plan to add support for .md files in sphinx using the way LLVM recommends[4] in a later patch.

[1] https://www.sphinx-doc.org/en/master/usage/markdown.html
[2] https://guides.github.com/features/mastering-markdown/
[3] https://reviews.llvm.org/D44910
[4] https://github.com/llvm/llvm-project/commits/master/llvm/docs/MarkdownQuickstartTemplate.md

[sameeranjoshi]

Sphinx support for .md files.
https://reviews.llvm.org/D86131

flang/docs/ArrayComposition.rst

-<!--===- documentation/ArrayComposition.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
-  
--->
-
 This note attempts to describe the motivation for and design of an
 implementation of Fortran 90 (and later) array expression evaluation that
 minimizes the use of dynamically allocated temporary storage for
 the results of calls to transformational intrinsic functions, and
 making them more amenable to acceleration.
 
 The transformational intrinsic functions of Fortran of interest to
 us here include:
 
-* Reductions to scalars (`SUM(X)`, also `ALL`, `ANY`, `COUNT`,
-  `DOT_PRODUCT`,
-  `IALL`, `IANY`, `IPARITY`, `MAXVAL`, `MINVAL`, `PARITY`, `PRODUCT`)
-* Axial reductions (`SUM(X,DIM=)`, &c.)
-* Location reductions to indices (`MAXLOC`, `MINLOC`, `FINDLOC`)
-* Axial location reductions (`MAXLOC(DIM=`, &c.)
-* `TRANSPOSE(M)` matrix transposition
-* `RESHAPE` without `ORDER=`
-* `RESHAPE` with `ORDER=`
-* `CSHIFT` and `EOSHIFT` with scalar `SHIFT=`
-* `CSHIFT` and `EOSHIFT` with array-valued `SHIFT=`
-* `PACK` and `UNPACK`
-* `MATMUL`
-* `SPREAD`
+
+* Reductions to scalars (\ ``SUM(X)``\ , also ``ALL``\ , ``ANY``\ , ``COUNT``\ ,
+  ``DOT_PRODUCT``\ ,
+  ``IALL``\ , ``IANY``\ , ``IPARITY``\ , ``MAXVAL``\ , ``MINVAL``\ , ``PARITY``\ , ``PRODUCT``\ )
+* Axial reductions (\ ``SUM(X,DIM=)``\ , &c.)
+* Location reductions to indices (\ ``MAXLOC``\ , ``MINLOC``\ , ``FINDLOC``\ )
+* Axial location reductions (\ ``MAXLOC(DIM=``\ , &c.)
+* ``TRANSPOSE(M)`` matrix transposition
+* ``RESHAPE`` without ``ORDER=``
+* ``RESHAPE`` with ``ORDER=``
+* ``CSHIFT`` and ``EOSHIFT`` with scalar ``SHIFT=``
+* ``CSHIFT`` and ``EOSHIFT`` with array-valued ``SHIFT=``
+* ``PACK`` and ``UNPACK``
+* ``MATMUL``
+* ``SPREAD``
 
 Other Fortran intrinsic functions are technically transformational (e.g.,
-`COMMAND_ARGUMENT_COUNT`) but not of interest for this note.
-The generic `REDUCE` is also not considered here.
+``COMMAND_ARGUMENT_COUNT``\ ) but not of interest for this note.
+The generic ``REDUCE`` is also not considered here.
 
 Arrays as functions
 ===================
+
 A whole array can be viewed as a function that maps its indices to the values
 of its elements.
 Specifically, it is a map from a tuple of integers to its element type.
 The rank of the array is the number of elements in that tuple,
 and the shape of the array delimits the domain of the map.
 
-`REAL :: A(N,M)` can be seen as a function mapping ordered pairs of integers
-`(J,K)` with `1<=J<=N` and `1<=J<=M` to real values.
+``REAL :: A(N,M)`` can be seen as a function mapping ordered pairs of integers
+``(J,K)`` with ``1<=J<=N`` and ``1<=J<=M`` to real values.
 
 Array expressions as functions
 ==============================
+
 The same perspective can be taken of an array expression comprising
 intrinsic operators and elemental functions.
 Fortran doesn't allow one to apply subscripts directly to an expression,
 but expressions have rank and shape, and one can view array expressions
 as functions over index tuples by applying those indices to the arrays
 and subexpressions in the expression.
 
-Consider `B = A + 1.0` (assuming `REAL :: A(N,M), B(N,M)`).
+Consider ``B = A + 1.0`` (assuming ``REAL :: A(N,M), B(N,M)``\ ).
 The right-hand side of that assignment could be evaluated into a
-temporary array `T` and then subscripted as it is copied into `B`.
-```
+temporary array ``T`` and then subscripted as it is copied into ``B``.
+
+.. code-block::
+
    REAL, ALLOCATABLE :: T(:,:)
    ALLOCATE(T(N,M))
    DO CONCURRENT(J=1:N,K=1:M)
      T(J,K)=A(J,K) + 1.0
    END DO
    DO CONCURRENT(J=1:N,K=1:M)
      B(J,K)=T(J,K)
    END DO
    DEALLOCATE(T)
-```
+
 But we can avoid the allocation, population, and deallocation of
 the temporary by treating the right-hand side expression as if it
-were a statement function `F(J,K)=A(J,K)+1.0` and evaluating
-```
+were a statement function ``F(J,K)=A(J,K)+1.0`` and evaluating
+
+.. code-block::
+
    DO CONCURRENT(J=1:N,K=1:M)
      A(J,K)=F(J,K)
    END DO
-```
 
 In general, when a Fortran array assignment to a non-allocatable array
 does not include the left-hand
 side variable as an operand of the right-hand side expression, and any
 function calls on the right-hand side are elemental or scalar-valued,
 we can avoid the use of a temporary.
 
 Transformational intrinsic functions as function composition
 ============================================================
+
 Many of the transformational intrinsic functions listed above
 can, when their array arguments are viewed as functions over their
 index tuples, be seen as compositions of those functions with
 functions of the "incoming" indices -- yielding a function for
 an entire right-hand side of an array assignment statement.
 
-For example, the application of `TRANSPOSE(A + 1.0)` to the index
-tuple `(J,K)` becomes `A(K,J) + 1.0`.
+For example, the application of ``TRANSPOSE(A + 1.0)`` to the index
+tuple ``(J,K)`` becomes ``A(K,J) + 1.0``.
 
 Partial (axial) reductions can be similarly composed.
-The application of `SUM(A,DIM=2)` to the index `J` is the
-complete reduction `SUM(A(J,:))`.
+The application of ``SUM(A,DIM=2)`` to the index ``J`` is the
+complete reduction ``SUM(A(J,:))``.
 
 More completely:
-* Reductions to scalars (`SUM(X)` without `DIM=`) become
+
+
+* Reductions to scalars (\ ``SUM(X)`` without ``DIM=``\ ) become
   runtime calls; the result needs no dynamic allocation,
   being a scalar.
-* Axial reductions (`SUM(X,DIM=d)`) applied to indices `(J,K)`
-  become scalar values like `SUM(X(J,K,:))` if `d=3`.
-* Location reductions to indices (`MAXLOC(X)` without `DIM=`)
+* Axial reductions (\ ``SUM(X,DIM=d)``\ ) applied to indices ``(J,K)``
+  become scalar values like ``SUM(X(J,K,:))`` if ``d=3``.
+* Location reductions to indices (\ ``MAXLOC(X)`` without ``DIM=``\ )
   do not require dynamic allocation, since their results are
-  either scalar or small vectors of length `RANK(X)`.
-* Axial location reductions (`MAXLOC(X,DIM=)`, &c.)
-  are handled like other axial reductions like `SUM(DIM=)`.
-* `TRANSPOSE(M)` exchanges the two components of the index tuple.
-* `RESHAPE(A,SHAPE=s)` without `ORDER=` must precompute the shape
-  vector `S`, and then use it to linearize indices into offsets
-  in the storage order of `A` (whose shape must also be captured).
+  either scalar or small vectors of length ``RANK(X)``.
+* Axial location reductions (\ ``MAXLOC(X,DIM=)``\ , &c.)
+  are handled like other axial reductions like ``SUM(DIM=)``.
+* ``TRANSPOSE(M)`` exchanges the two components of the index tuple.
+* ``RESHAPE(A,SHAPE=s)`` without ``ORDER=`` must precompute the shape
+  vector ``S``\ , and then use it to linearize indices into offsets
+  in the storage order of ``A`` (whose shape must also be captured).
   These conversions can involve division and/or modulus, which
   can be optimized into a fixed-point multiplication using the
   usual technique.
-* `RESHAPE` with `ORDER=` is similar, but must permute the
-  components of the index tuple; it generalizes `TRANSPOSE`.
-* `CSHIFT` applies addition and modulus.
-* `EOSHIFT` applies addition and a conditional move (`MERGE`).
-* `PACK` and `UNPACK` are likely to require a runtime call.
-* `MATMUL(A,B)` can become `DOT_PRODUCT(A(J,:),B(:,K))`, but
+* ``RESHAPE`` with ``ORDER=`` is similar, but must permute the
+  components of the index tuple; it generalizes ``TRANSPOSE``.
+* ``CSHIFT`` applies addition and modulus.
+* ``EOSHIFT`` applies addition and a conditional move (\ ``MERGE``\ ).
+* ``PACK`` and ``UNPACK`` are likely to require a runtime call.
+* ``MATMUL(A,B)`` can become ``DOT_PRODUCT(A(J,:),B(:,K))``\ , but
   might benefit from calling a highly optimized runtime
   routine.
-* `SPREAD(A,DIM=d,NCOPIES=n)` for compile-time `d` simply
-  applies `A` to a reduced index tuple.
+* ``SPREAD(A,DIM=d,NCOPIES=n)`` for compile-time ``d`` simply
+  applies ``A`` to a reduced index tuple.
 
 Determination of rank and shape
 ===============================
+
 An important part of evaluating array expressions without the use of
 temporary storage is determining the shape of the result prior to,
 or without, evaluating the elements of the result.
 
 The shapes of array objects, results of elemental intrinsic functions,
 and results of intrinsic operations are obvious.
 But it is possible to determine the shapes of the results of many
 transformational intrinsic function calls as well.
 
-* `SHAPE(SUM(X,DIM=d))` is `SHAPE(X)` with one element removed:
-  `PACK(SHAPE(X),[(j,j=1,RANK(X))]/=d)` in general.
-  (The `DIM=` argument is commonly a compile-time constant.)
-* `SHAPE(MAXLOC(X))` is `[RANK(X)]`.
-* `SHAPE(MAXLOC(X,DIM=d))` is `SHAPE(X)` with one element removed.
-* `SHAPE(TRANSPOSE(M))` is a reversal of `SHAPE(M)`.
-* `SHAPE(RESHAPE(..., SHAPE=S))` is `S`.
-* `SHAPE(CSHIFT(X))` is `SHAPE(X)`; same with `EOSHIFT`.
-* `SHAPE(PACK(A,VECTOR=V))` is `SHAPE(V)`
-* `SHAPE(PACK(A,MASK=m))` with non-scalar `m` and without `VECTOR=` is `[COUNT(m)]`.
-* `RANK(PACK(...))` is always 1.
-* `SHAPE(UNPACK(MASK=M))` is `SHAPE(M)`.
-* `SHAPE(MATMUL(A,B))` drops one value from `SHAPE(A)` and another from `SHAPE(B)`.
-* `SHAPE(SHAPE(X))` is `[RANK(X)]`.
-* `SHAPE(SPREAD(A,DIM=d,NCOPIES=n))` is `SHAPE(A)` with `n` inserted at
-  dimension `d`.
+
+* ``SHAPE(SUM(X,DIM=d))`` is ``SHAPE(X)`` with one element removed:
+  ``PACK(SHAPE(X),[(j,j=1,RANK(X))]/=d)`` in general.
+  (The ``DIM=`` argument is commonly a compile-time constant.)
+* ``SHAPE(MAXLOC(X))`` is ``[RANK(X)]``.
+* ``SHAPE(MAXLOC(X,DIM=d))`` is ``SHAPE(X)`` with one element removed.
+* ``SHAPE(TRANSPOSE(M))`` is a reversal of ``SHAPE(M)``.
+* ``SHAPE(RESHAPE(..., SHAPE=S))`` is ``S``.
+* ``SHAPE(CSHIFT(X))`` is ``SHAPE(X)``\ ; same with ``EOSHIFT``.
+* ``SHAPE(PACK(A,VECTOR=V))`` is ``SHAPE(V)``
+* ``SHAPE(PACK(A,MASK=m))`` with non-scalar ``m`` and without ``VECTOR=`` is ``[COUNT(m)]``.
+* ``RANK(PACK(...))`` is always 1.
+* ``SHAPE(UNPACK(MASK=M))`` is ``SHAPE(M)``.
+* ``SHAPE(MATMUL(A,B))`` drops one value from ``SHAPE(A)`` and another from ``SHAPE(B)``.
+* ``SHAPE(SHAPE(X))`` is ``[RANK(X)]``.
+* ``SHAPE(SPREAD(A,DIM=d,NCOPIES=n))`` is ``SHAPE(A)`` with ``n`` inserted at
+  dimension ``d``.
 
 This is useful because expression evaluations that *do* require temporaries
 to hold their results (due to the context in which the evaluation occurs)
 can be implemented with a separation of the allocation
 of the temporary array and the population of the array.
 The code that evaluates the expression, or that implements a transformational
 intrinsic in the runtime library, can be designed with an API that includes
 a pointer to the destination array as an argument.
 
-Statements like `ALLOCATE(A,SOURCE=expression)` should thus be capable
+Statements like ``ALLOCATE(A,SOURCE=expression)`` should thus be capable
 of evaluating their array expressions directly into the newly-allocated
 storage for the allocatable array.
 The implementation would generate code to calculate the shape, use it
 to allocate the memory and populate the descriptor, and then drive a
 loop nest around the expression to populate the array.
 In cases where the analyzed shape is known at compile time, we should
 be able to have the opportunity to avoid heap allocation in favor of
 stack storage, if the scope of the variable is local.
 
 Automatic reallocation of allocatables
 ======================================
+
 Fortran 2003 introduced the ability to assign non-conforming array expressions
 to ALLOCATABLE arrays with the implied semantics of reallocation to the
 new shape.
 The implementation of this feature also becomes more straightforward if
 our implementation of array expressions has decoupled calculation of shapes
 from the evaluation of the elements of the result.
 
 Rewriting rules
 ===============
-Let `{...}` denote an ordered tuple of 1-based indices, e.g. `{j,k}`, into
+
+Let ``{...}`` denote an ordered tuple of 1-based indices, e.g. ``{j,k}``\ , into
 the result of an array expression or subexpression.
 
+
 * Array constructors always yield vectors; higher-rank arrays that appear as
-  constituents are flattened; so `[X] => RESHAPE(X,SHAPE=[SIZE(X)})`.
+  constituents are flattened; so ``[X] => RESHAPE(X,SHAPE=[SIZE(X)})``.
 * Array constructors with multiple constituents are concatenations of
-  their constituents; so `[X,Y]{j} => MERGE(Y{j-SIZE(X)},X{j},J>SIZE(X))`.
+  their constituents; so ``[X,Y]{j} => MERGE(Y{j-SIZE(X)},X{j},J>SIZE(X))``.
 * Array constructors with implied DO loops are difficult when nested
   triangularly.
 * Whole array references can have lower bounds other than 1, so
-  `A => A(LBOUND(A,1):UBOUND(A,1),...)`.
-* Array sections simply apply indices: `A(i:...:n){j} => A(i1+n*(j-1))`.
-* Vector-valued subscripts apply indices to the subscript: `A(N(:)){j} => A(N(:){j})`.
-* Scalar operands ignore indices: `X{j,k} => X`.
+  ``A => A(LBOUND(A,1):UBOUND(A,1),...)``.
+* Array sections simply apply indices: ``A(i:...:n){j} => A(i1+n*(j-1))``.
+* Vector-valued subscripts apply indices to the subscript: ``A(N(:)){j} => A(N(:){j})``.
+* Scalar operands ignore indices: ``X{j,k} => X``.
   Further, they are evaluated at most once.
 * Elemental operators and functions apply indices to their arguments:
-  `(A(:,:) + B(:,:)){j,k}` => A(:,:){j,k} + B(:,:){j,k}`.
-* `TRANSPOSE(X){j,k} => X{k,j}`.
-* `SPREAD(X,DIM=2,...){j,k} => X{j}`; i.e., the contents are replicated.
+  ``(A(:,:) + B(:,:)){j,k}`` => A(:,:){j,k} + B(:,:){j,k}`.
+* ``TRANSPOSE(X){j,k} => X{k,j}``.
+* ``SPREAD(X,DIM=2,...){j,k} => X{j}``\ ; i.e., the contents are replicated.
   If X is sufficiently expensive to compute elementally, it might be evaluated
   into a temporary.
 
 (more...)

flang/docs/BijectiveInternalNameUniquing.rst

+
+Bijective Internal Name Uniquing
+--------------------------------
+
+FIR has a flat namespace.  No two objects may have the same name at
+the module level.  (These would be functions, globals, etc.)
+This necessitates some sort of encoding scheme to unique
+symbols from the front-end into FIR.
+
+Another requirement is
+to be able to reverse these unique names and recover the associated
+symbol in the symbol table.
+
+Fortran is case insensitive, which allows the compiler to convert the
+user's identifiers to all lower case.  Such a universal conversion implies
+that all upper case letters are available for use in uniquing.
+
+Prefix ``_Q``
+^^^^^^^^^^^^^^^^^
+
+All uniqued names have the prefix sequence ``_Q`` to indicate the name has
+been uniqued.  (Q is chosen because it is a
+`low frequency letter <http://pi.math.cornell.edu/~mec/2003-2004/cryptography/subs/frequencies.html>`_
+in English.)
+
+Scope Building
+^^^^^^^^^^^^^^
+
+Symbols can be scoped by the module, submodule, or procedure that contains
+that symbol.  After the ``_Q`` sigil, names are constructed from outermost to
+innermost scope as
+
+
+* Module name prefixed with ``M``
+* Submodule name prefixed with ``S``
+* Procedure name prefixed with ``F``
+
+Given:
+
+.. code-block::
+
+       submodule (mod:s1mod) s2mod
+         ...
+         subroutine sub
+           ...
+         contains
+           function fun
+
+The uniqued name of ``fun`` becomes:
+
+.. code-block::
+
+       _QMmodSs1modSs2modFsubPfun
+
+Common blocks
+^^^^^^^^^^^^^
+
+
+* A common block name will be prefixed with ``B``
+
+Given:
+
+.. code-block::
+
+      common /variables/ i, j
+
+The uniqued name of ``variables`` becomes:
+
+.. code-block::
+
+       _QBvariables
+
+Given:
+
+.. code-block::
+
+      common i, j
+
+The uniqued name in case of ``blank common block`` becomes:
+
+.. code-block::
+
+       _QB
+
+Module scope global data
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+* A global data entity is prefixed with ``E``
+* A global entity that is constant (parameter) will be prefixed with ``EC``
+
+Given:
+
+.. code-block::
+
+       module mod
+         integer :: intvar
+         real, parameter :: pi = 3.14
+       end module
+
+The uniqued name of ``intvar`` becomes:
+
+.. code-block::
+
+       _QMmodEintvar
+
+The uniqued name of ``pi`` becomes:
+
+.. code-block::
+
+       _QMmodECpi
+
+Procedures/Subprograms
+^^^^^^^^^^^^^^^^^^^^^^
+
+
+* A procedure/subprogram is prefixed with ``P``
+
+Given:
+
+.. code-block::
+
+       subroutine sub
+
+The uniqued name of ``sub`` becomes:
+
+.. code-block::
+
+       _QPsub
+
+Derived types and related
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+* A derived type is prefixed with ``T``
+* If a derived type has KIND parameters, they are listed in a consistent
+  canonical order where each takes the form ``Ki`` and where *i* is the
+  compile-time constant value. (All type parameters are integer.)  If *i*
+  is a negative value, the prefix ``KN`` will be used and *i* will reflect
+  the magnitude of the value.
+
+Given:
+
+.. code-block::
+
+       module mymodule
+         type mytype
+           integer :: member
+         end type
+         ...
+
+The uniqued name of ``mytype`` becomes:
+
+.. code-block::
+
+       _QMmymoduleTmytype
+
+Given:
+
+.. code-block::
+
+       type yourtype(k1,k2)
+         integer, kind :: k1, k2
+         real :: mem1
+         complex :: mem2
+       end type
+
+The uniqued name of ``yourtype`` where ``k1=4`` and ``k2=-6`` (at compile-time):
+
+.. code-block::
+
+       _QTyourtypeK4KN6
+
+
+* A derived type dispatch table is prefixed with ``D``.  The dispatch table
+  for ``type t`` would be ``_QDTt``
+* A type descriptor instance is prefixed with ``C``.  Intrinsic types can
+  be encoded with their names and kinds.  The type descriptor for the
+  type ``yourtype`` above would be ``_QCTyourtypeK4KN6``.  The type
+  descriptor for ``REAL(4)`` would be ``_QCrealK4``.
+
+Compiler generated names
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Compiler generated names do not have to be mapped back to Fortran.  These
+names will be prefixed with ``_QQ`` and followed by a unique compiler
+generated identifier. There is, of course, no mapping back to a symbol
+derived from the input source in this case as no such symbol exists.

flang/docs/C++17.rst

-<!--===- documentation/C++17.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
-  
--->
-
-## C++14/17 features used in f18
+C++14/17 features used in f18
+-----------------------------
 
 The C++ dialect used in this project constitutes a subset of the
 standard C++ programming language and library features.
 We want our dialect to be compatible with the LLVM C++ language
 subset that will be in use at the time that we integrate with that
 project.
 We also want to maximize portability, future-proofing,
 compile-time error checking, and use of best practices.
 
 To that end, we have a C++ style guide (q.v.) that lays
 out the details of how our C++ code should look and gives
 guidance about feature usage.
 
 We have chosen to use some features of the recent C++17
 language standard in f18.
 The most important of these are:
-* sum types (discriminated unions) in the form of `std::variant`
-* `using` template parameter packs
-* generic lambdas with `auto` argument types
-* product types in the form of `std::tuple`
-* `std::optional`
 
-(`std::tuple` is actually a C++11 feature, but I include it
+
+* sum types (discriminated unions) in the form of ``std::variant``
+* ``using`` template parameter packs
+* generic lambdas with ``auto`` argument types
+* product types in the form of ``std::tuple``
+* ``std::optional``
+
+(\ ``std::tuple`` is actually a C++11 feature, but I include it
 in this list because it's not particularly well known.)
 
-### Sum types
+Sum types
+^^^^^^^^^
 
 First, some background information to explain the need for sum types
 in f18.
 
 Fortran is notoriously problematic to lex and parse, as tokenization
 depends on the state of the partial parse;
 the language has no reserved words in the sense that C++ does.
 Fortran parsers implemented with distinct lexing and parsing phases
 (generated by hand or with tools) need to implement them as
 coroutines with complicated state, and experience has shown that
 it's hard to get them right and harder to extend them as the language
 evolves.
 
 Alternatively, with the use of backtracking, one can parse Fortran with
 a unified lexer/parser.
 We have chosen to do so because it is simpler and should reduce
 both initial bugs and long-term maintenance.
 
 Specifically, f18's parser uses the technique of recursive descent with
 backtracking.
 It is constructed as the incremental composition of pure parsing functions
 that each, when given a context (location in the input stream plus some state),
-either _succeeds_ or _fails_ to recognize some piece of Fortran.
+either *succeeds* or *fails* to recognize some piece of Fortran.
 On success, they return a new state and some semantic value, and this is
-usually an instance of a C++ `struct` type that encodes the semantic
+usually an instance of a C++ ``struct`` type that encodes the semantic
 content of a production in the Fortran grammar.
 
 This technique allows us to specify both the Fortran grammar and the
 representation of successfully parsed programs with C++ code
 whose functions and data structures correspond closely to the productions
 of Fortran.
 
 The specification of Fortran uses a form of BNF with alternatives,
 optional elements, sequences, and lists.  Each of these constructs
 in the Fortran grammar maps directly in the f18 parser to both
 the means of combining other parsers as alternatives, &c., and to
 the declarations of the parse tree data structures that represent
 the results of successful parses.
 Move semantics are used in the parsing functions to acquire and
 combine the results of sub-parses into the result of a larger
 parse.
 
 To represent nodes in the Fortran parse tree, we need a means of
 handling sum types for productions that have multiple alternatives.
-The bounded polymorphism supplied by the C++17 `std::variant` fits
+The bounded polymorphism supplied by the C++17 ``std::variant`` fits
 those needs exactly.
 For example, production R502 in Fortran defines the top-level
 program unit of Fortran as being a function, subroutine, module, &c.
-The `struct ProgramUnit` in the f18 parse tree header file
-represents each program unit with a member that is a `std::variant`
+The ``struct ProgramUnit`` in the f18 parse tree header file
+represents each program unit with a member that is a ``std::variant``
 over the six possibilities.
 Similarly, the parser for that type in the f18 grammar has six alternatives,
-each of which constructs an instance of `ProgramUnit` upon the result of
-parsing a `Module`, `FunctionSubprogram`, and so on.
+each of which constructs an instance of ``ProgramUnit`` upon the result of
+parsing a ``Module``\ , ``FunctionSubprogram``\ , and so on.
 
 Code that performs semantic analysis on the result of a successful
 parse is typically implemented with overloaded functions.
-A function instantiated on `ProgramUnit` will use `std::visit` to
+A function instantiated on ``ProgramUnit`` will use ``std::visit`` to
 identify the right alternative and perform the right actions.
-The call to `std::visit` must pass a visitor that can handle all
+The call to ``std::visit`` must pass a visitor that can handle all
 of the possibilities, and f18 will fail to build if one is missing.
 
-Were we unable to use `std::variant` directly, we would likely
-have chosen to implement a local `SumType` replacement; in the
-absence of C++17's abilities of `using` a template parameter pack
-and allowing `auto` arguments in anonymous lambda functions,
+Were we unable to use ``std::variant`` directly, we would likely
+have chosen to implement a local ``SumType`` replacement; in the
+absence of C++17's abilities of ``using`` a template parameter pack
+and allowing ``auto`` arguments in anonymous lambda functions,
 it would be less convenient to use.
 
 The other options for polymorphism in C++ at the level of C++11
 would be to:
+
+
 * loosen up compile-time type safety and use a unified parse tree node
   representation with an enumeration type for an operator and generic
   subtree pointers, or
 * define the sum types for the parse tree as abstract base classes from
   which each particular alternative would derive, and then use virtual
-  functions (or the forbidden `dynamic_cast`) to identify alternatives
+  functions (or the forbidden ``dynamic_cast``\ ) to identify alternatives
   during analysis
 
-### Product types
+Product types
+^^^^^^^^^^^^^
 
 Many productions in the Fortran grammar describe a sequence of various
 sub-parses.
 For example, R504 defines the things that may appear in the "specification
-part" of a subprogram in the order in which they are allowed: `USE`
-statements, then `IMPORT` statements, and so on.
+part" of a subprogram in the order in which they are allowed: ``USE``
+statements, then ``IMPORT`` statements, and so on.
 
 The parse tree node that represents such a thing needs to incorporate
 the representations of those parses, of course.
 It turns out to be convenient to allow these data members to be anonymous
-components of a `std::tuple` product type.
+components of a ``std::tuple`` product type.
 This type facilitates the automation of code that walks over all of the
 members in a type-safe fashion and avoids the need to invent and remember
-needless member names -- the components of a `std::tuple` instance can
+needless member names -- the components of a ``std::tuple`` instance can
 be identified and accessed in terms of their types, and those tend to be
 distinct.
 
-So we use `std::tuple` for such things.
+So we use ``std::tuple`` for such things.
 It has also been handy for template metaprogramming that needs to work
 with lists of types.
 
-### `std::optional`
+``std::optional``
+^^^^^^^^^^^^^^^^^^^^^
 
 This simple little type is used wherever a value might or might not be
 present.
 It is especially useful for function results and
 rvalue reference arguments.
 It corresponds directly to the optional elements in the productions
 of the Fortran grammar.
 It is also used as a wrapper around a parse tree node type to define the
 results of the various parsing functions, where presence of a value
 signifies a successful recognition and absence denotes a failed parse.
 It is used in data structures in place of nullable pointers to
 avoid indirection as well as the possible confusion over whether a pointer
 is allowed to be null.

flang/docs/C++style.rst

+In brief:
+---------
+
+
+* Use *clang-format*
+  from llvm 7
+  on all C++ source and header files before
+  every merge to master.  All code layout should be determined
+  by means of clang-format.
+* Where a clear precedent exists in the project, follow it.
+* Otherwise, where `LLVM's C++ style guide <https://llvm.org/docs/CodingStandards.html#style-issues>`_
+  is clear on usage, follow it.
+* Otherwise, where a good public C++ style guide is relevant and clear,
+  follow it.  `Google's <https://google.github.io/styleguide/cppguide.html>`_
+  is pretty good and comes with lots of justifications for its rules.
+* Reasonable exceptions to these guidelines can be made.
+* Be aware of some workarounds for known issues in older C++ compilers that should
+  still be able to compile f18. They are listed at the end of this document.
+
+In particular:
+--------------
+
+Use serial commas in comments, error messages, and documentation
+unless they introduce ambiguity.
+
+Error messages
+^^^^^^^^^^^^^^
+
+
+#. Messages should be a single sentence with few exceptions.
+#. Fortran keywords should appear in upper case.
+#. Names from the program appear in single quotes.
+#. Messages should start with a capital letter.
+#. Messages should not end with a period.
+
+Files
+^^^^^
+
+
+#. File names should use dashes, not underscores.  C++ sources have the
+   extension ".cpp", not ".C" or ".cc" or ".cxx".  Don't create needless
+   source directory hierarchies.
+#. Header files should be idempotent.  Use the usual technique:
+   .. code-block::
+
+      #ifndef FORTRAN_header_H_
+      #define FORTRAN_header_H_
+      // code
+      #endif  // FORTRAN_header_H_
+
+#. ``#include`` every header defining an entity that your project header or source
+   file actually uses directly.  (Exception: when foo.cpp starts, as it should,
+   with ``#include "foo.h"``\ , and foo.h includes bar.h in order to define the
+   interface to the module foo, you don't have to redundantly ``#include "bar.h"``
+   in foo.cpp.)
+#. In the source file "foo.cpp", put its corresponding ``#include "foo.h"``
+   first in the sequence of inclusions.
+   Then ``#include`` other project headers in alphabetic order; then C++ standard
+   headers, also alphabetically; then C and system headers.
+#. Don't use ``#include <iostream>``.  If you need it for temporary debugging,
+   remove the inclusion before committing.
+
+Naming
+^^^^^^
+
+
+#. C++ names that correspond to well-known interfaces from the STL, LLVM,
+   and Fortran standard
+   can and should look like their models when the reader can safely assume that
+   they mean the same thing -- e.g., ``clear()`` and ``size()`` member functions
+   in a class that implements an STL-ish container.
+   Fortran intrinsic function names are conventionally in ALL CAPS.
+#. Non-public data members should be named with leading miniscule (lower-case)
+   letters, internal camelCase capitalization, and a trailing underscore,
+   e.g. ``DoubleEntryBookkeepingSystem myLedger_;``.  POD structures with
+   only public data members shouldn't use trailing underscores, since they
+   don't have class functions from which data members need to be distinguishable.
+#. Accessor member functions are named with the non-public data member's name,
+   less the trailing underscore.  Mutator member functions are named ``set_...``
+   and should return ``*this``.  Don't define accessors or mutators needlessly.
+#. Other class functions should be named with leading capital letters,
+   CamelCase, and no underscores, and, like all functions, should be based
+   on imperative verbs, e.g. ``HaltAndCatchFire()``.
+#. It is fine to use short names for local variables with limited scopes,
+   especially when you can declare them directly in a ``for()``\ /\ ``while()``\ /\ ``if()``
+   condition.  Otherwise, prefer complete English words to abbreviations
+   when creating names.
+
+Commentary
+^^^^^^^^^^
+
+
+#. Use ``//`` for all comments except for short ``/*notes*/`` within expressions.
+#. When ``//`` follows code on a line, precede it with two spaces.
+#. Comments should matter.  Assume that the reader knows current C++ at least as
+   well as you do and avoid distracting her by calling out usage of new
+   features in comments.
+
+Layout
+^^^^^^
+
+Always run ``clang-format`` on your changes before committing code. LLVM
+has a ``git-clang-format`` script to facilitate running clang-format only
+on the lines that have changed.
+
+Here's what you can expect to see ``clang-format`` do:
+
+
+#. Indent with two spaces.
+#. Don't indent public:, protected:, and private:
+   accessibility labels.
+#. Never use more than 80 characters per source line.
+#. Don't use tabs.
+#. Don't indent the bodies of namespaces, even when nested.
+#. Function result types go on the same line as the function and argument
+   names.
+
+Don't try to make columns of variable names or comments
+align vertically -- they are maintenance problems.
+
+Always wrap the bodies of ``if()``\ , ``else``\ , ``while()``\ , ``for()``\ , ``do``\ , &c.
+with braces, even when the body is a single statement or empty.  The
+opening ``{`` goes on
+the end of the line, not on the next line.  Functions also put the opening
+``{`` after the formal arguments or new-style result type, not on the next
+line.  Use ``{}`` for empty inline constructors and destructors in classes.
+
+If any branch of an ``if``\ /\ ``else if``\ /\ ``else`` cascade ends with a return statement,
+they all should, with the understanding that the cases are all unexceptional.
+When testing for an error case that should cause an early return, do so with
+an ``if`` that doesn't have a following ``else``.
+
+Don't waste space on the screen with needless blank lines or elaborate block
+commentary (lines of dashes, boxes of asterisks, &c.).  Write code so as to be
+easily read and understood with a minimum of scrolling.
+
+Avoid using assignments in controlling expressions of ``if()`` &c., even with
+the idiom of wrapping them with extra parentheses.
+
+In multi-element initializer lists (especially ``common::visitors{...}``\ ),
+including a comma after the last element often causes ``clang-format`` to do
+a better jobs of formatting.
+
+C++ language
+^^^^^^^^^^^^
+
+Use *C++17*\ , unless some compiler to which we must be portable lacks a feature
+you are considering.
+However:
+
+
+#. Never throw or catch exceptions.
+#. Never use run-time type information or ``dynamic_cast<>``.
+#. Never declare static data that executes a constructor.
+   (This is why ``#include <iostream>`` is contraindicated.)
+#. Use ``{braced initializers}`` in all circumstances where they work, including
+   default data member initialization.  They inhibit implicit truncation.
+   Don't use ``= expr`` initialization just to effect implicit truncation;
+   prefer an explicit ``static_cast<>``.
+   With C++17, braced initializers work fine with ``auto`` too.
+   Sometimes, however, there are better alternatives to empty braces;
+   e.g., prefer ``return std::nullopt;`` to ``return {};`` to make it more clear
+   that the function's result type is a ``std::optional<>``.
+#. Avoid unsigned types apart from ``size_t``\ , which must be used with care.
+   When ``int`` just obviously works, just use ``int``.  When you need something
+   bigger than ``int``\ , use ``std::int64_t`` rather than ``long`` or ``long long``.
+#. Use namespaces to avoid conflicts with client code.  Use one top-level
+   ``Fortran`` project namespace.  Don't introduce needless nested namespaces within the
+   project when names don't conflict or better solutions exist.  Never use
+   ``using namespace ...;`` outside test code; never use ``using namespace std;``
+   anywhere.  Access STL entities with names like ``std::unique_ptr<>``\ ,
+   without a leading ``::``.
+#. Prefer ``static`` functions over functions in anonymous namespaces in source files.
+#. Use ``auto`` judiciously.  When the type of a local variable is known,
+   monomorphic, and easy to type, be explicit rather than using ``auto``.
+   Don't use ``auto`` functions unless the type of the result of an outlined member
+   function definition can be more clear due to its use of types declared in the
+   class.
+#. Use move semantics and smart pointers to make dynamic memory ownership
+   clear.  Consider reworking any code that uses ``malloc()`` or a (non-placement)
+   ``operator new``.
+   See the section on Pointers below for some suggested options.
+#. When defining argument types, use values when object semantics are
+   not required and the value is small and copyable without allocation
+   (e.g., ``int``\ );
+   use ``const`` or rvalue references for larger values (e.g., ``std::string``\ );
+   use ``const`` references to rather than pointers to immutable objects;
+   and use non-\ ``const`` references for mutable objects, including "output" arguments
+   when they can't be function results.
+   Put such output arguments last (\ *pace* the standard C library conventions for ``memcpy()`` & al.).
+#. Prefer ``typename`` to ``class`` in template argument declarations.
+#. Prefer ``enum class`` to plain ``enum`` wherever ``enum class`` will work.
+   We have an ``ENUM_CLASS`` macro that helps capture the names of constants.
+#. Use ``constexpr`` and ``const`` generously.
+#. When a ``switch()`` statement's labels do not cover all possible case values
+   explicitly, it should contain either a ``default:;`` at its end or a
+   ``default:`` label that obviously crashes; we have a ``CRASH_NO_CASE`` macro
+   for such situations.
+#. On the other hand, when a ``switch()`` statement really does cover all of
+   the values of an ``enum class``\ , please insert a call to the ``SWITCH_COVERS_ALL_CASES``
+   macro at the top of the block.  This macro does the right thing for G++ and
+   clang to ensure that no warning is emitted when the cases are indeed all covered.
+#. When using ``std::optional`` values, avoid unprotected access to their content.
+   This is usually by means of ``x.has_value()`` guarding execution of ``*x``.
+   This is implicit when they are function results assigned to local variables
+   in ``if``\ /\ ``while`` predicates.
+   When no presence test is obviously protecting a ``*x`` reference to the
+   contents, and it is assumed that the contents are present, validate that
+   assumption by using ``x.value()`` instead.
+#. We use ``c_str()`` rather than ``data()`` when converting a ``std::string``
+   to a ``const char *`` when the result is expected to be NUL-terminated.
+#. Avoid explicit comparisions of pointers to ``nullptr`` and tests of
+   presence of ``optional<>`` values with ``.has_value()`` in the predicate
+   expressions of control flow statements, but prefer them to implicit
+   conversions to ``bool`` when initializing ``bool`` variables and arguments,
+   and to the use of the idiom ``!!``.
+
+Classes
+~~~~~~~
+
+
+#. Define POD structures with ``struct``.
+#. Don't use ``this->`` in (non-static) member functions, unless forced to
+   do so in a template member function.
+#. Define accessor and mutator member functions (implicitly) inline in the
+   class, after constructors and assignments.  Don't needlessly define
+   (implicit) inline member functions in classes unless they really solve a
+   performance problem.
+#. Try to make class definitions in headers concise specifications of
+   interfaces, at least to the extent that C++ allows.
+#. When copy constructors and copy assignment are not necessary,
+   and move constructors/assignment is present, don't declare them and they
+   will be implicitly deleted.  When neither copy nor move constructors
+   or assignments should exist for a class, explicitly ``=delete`` all of them.
+#. Make single-argument constructors (other than copy and move constructors)
+   'explicit' unless you really want to define an implicit conversion.
+
+Pointers
+~~~~~~~~
+
+There are many -- perhaps too many -- means of indirect addressing
+data in this project.
+Some of these are standard C++ language and library features,
+while others are local inventions in ``lib/Common``\ :
+
+
+* Bare pointers (\ ``Foo *p``\ ): these are obviously nullable, non-owning,
+  undefined when uninitialized, shallowly copyable, reassignable, and often
+  not the right abstraction to use in this project.
+  But they can be the right choice to represent an optional
+  non-owning reference, as in a function result.
+  Use the ``DEREF()`` macro to convert a pointer to a reference that isn't
+  already protected by an explicit test for null.
+* References (\ ``Foo &r``\ , ``const Foo &r``\ ): non-nullable, not owning,
+  shallowly copyable, and not reassignable.
+  References are great for invisible indirection to objects whose lifetimes are
+  broader than that of the reference.
+  Take care when initializing a reference with another reference to ensure
+  that a copy is not made because only one of the references is ``const``\ ;
+  this is a pernicious C++ language pitfall!
+* Rvalue references (\ ``Foo &&r``\ ): These are non-nullable references
+  *with* ownership, and they are ubiquitously used for formal arguments
+  wherever appropriate.
+* ``std::reference_wrapper<>``\ : non-nullable, not owning, shallowly
+  copyable, and (unlike bare references) reassignable, so suitable for
+  use in STL containers and for data members in classes that need to be
+  copyable or assignable.
+* `common::Reference<>`: like `std::reference_wrapper<>\ ``, but also supports
+  move semantics, member access, and comparison for equality; suitable for use in``\ std::variant<>`.
+* ``std::unique_ptr<>``\ : A nullable pointer with ownership, null by default,
+  not copyable, reassignable.
+  F18 has a helpful ``Deleter<>`` class template that makes ``unique_ptr<>``
+  easier to use with forward-referenced data types.
+* ``std::shared_ptr<>``\ : A nullable pointer with shared ownership via reference
+  counting, null by default, shallowly copyable, reassignable, and slow.
+* ``Indirection<>``\ : A non-nullable pointer with ownership and
+  optional deep copy semantics; reassignable.
+  Often better than a reference (due to ownership) or ``std::unique_ptr<>``
+  (due to non-nullability and copyability).
+  Can be wrapped in ``std::optional<>`` when nullability is required.
+  Usable with forward-referenced data types with some use of ``extern template``
+  in headers and explicit template instantiation in source files.
+* ``CountedReference<>``\ : A nullable pointer with shared ownership via
+  reference counting, null by default, shallowly copyable, reassignable.
+  Safe to use *only* when the data are private to just one
+  thread of execution.
+  Used sparingly in place of ``std::shared_ptr<>`` only when the overhead
+  of that standard feature is prohibitive.
+
+A feature matrix:
+
+.. list-table::
+   :header-rows: 1
+
+   * - indirection
+     - nullable
+     - default null
+     - owning
+     - reassignable
+     - copyable
+     - undefined type ok?
+   * - ``*p``
+     - yes
+     - no
+     - no
+     - yes
+     - shallowly
+     - yes
+   * - ``&r``
+     - no
+     - n/a
+     - no
+     - no
+     - shallowly
+     - yes
+   * - ``&&r``
+     - no
+     - n/a
+     - yes
+     - no
+     - shallowly
+     - yes
+   * - ``reference_wrapper<>``
+     - no
+     - n/a
+     - no
+     - yes
+     - shallowly
+     - yes
+   * - ``Reference<>``
+     - no
+     - n/a
+     - no
+     - yes
+     - shallowly
+     - yes
+   * - ``unique_ptr<>``
+     - yes
+     - yes
+     - yes
+     - yes
+     - no
+     - yes, with work
+   * - ``shared_ptr<>``
+     - yes
+     - yes
+     - yes
+     - yes
+     - shallowly
+     - no
+   * - ``Indirection<>``
+     - no
+     - n/a
+     - yes
+     - yes
+     - optionally deeply
+     - yes, with work
+   * - ``CountedReference<>``
+     - yes
+     - yes
+     - yes
+     - yes
+     - shallowly
+     - no
+
+
+Overall design preferences
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Don't use dynamic solutions to solve problems that can be solved at
+build time; don't solve build time problems by writing programs that
+produce source code when macros and templates suffice; don't write macros
+when templates suffice.  Templates are statically typed, checked by the
+compiler, and are (or should be) visible to debuggers.
+
+Exceptions to these guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Reasonable exceptions will be allowed; these guidelines cannot anticipate
+all situations.
+For example, names that come from other sources might be more clear if
+their original spellings are preserved rather than mangled to conform
+needlessly to the conventions here, as Google's C++ style guide does
+in a way that leads to weirdly capitalized abbreviations in names
+like ``Http``.
+Consistency is one of many aspects in the pursuit of clarity,
+but not an end in itself.
+
+C++ compiler bug workarounds
+----------------------------
+
+Below is a list of workarounds for C++ compiler bugs met with f18 that, even
+if the bugs are fixed in latest C++ compiler versions, need to be applied so
+that all desired tool-chains can compile f18.
+
+Explicitly move noncopyable local variable into optional results
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following code is legal C++ but fails to compile with the
+default Ubuntu 18.04 g++ compiler (7.4.0-1ubuntu1~18.0.4.1):
+
+.. code-block::
+
+   class CantBeCopied {
+    public:
+    CantBeCopied(const CantBeCopied&) = delete;
+    CantBeCopied(CantBeCopied&&) = default;
+    CantBeCopied() {}
+   };
+   std::optional<CantBeCopied> fooNOK() {
+     CantBeCopied result;
+     return result; // Legal C++, but does not compile with Ubuntu 18.04 default g++
+   }
+   std::optional<CantBeCopied> fooOK() {
+     CantBeCopied result;
+     return {std::move(result)}; // Compiles OK everywhere
+   }
+
+The underlying bug is actually not specific to ``std::optional`` but this is the most common
+case in f18 where the issue may occur. The actual bug can be reproduced with any class ``B``
+that has a perfect forwarding constructor taking ``CantBeCopied`` as argument:
+``template<typename CantBeCopied> B(CantBeCopied&& x) x_{std::forward<CantBeCopied>(x)} {}``.
+In such scenarios, Ubuntu 18.04 g++ fails to instantiate the move constructor
+and to construct the returned value as it should, instead it complains about a
+missing copy constructor.
+
+Local result variables do not need to and should not be explicitly moved into optionals
+if they have a copy constructor.

flang/docs/Calls.rst

-<!--===- documentation/Calls.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
-
--->
-
-## Procedure reference implementation protocol
+Procedure reference implementation protocol
+-------------------------------------------
 
 Fortran function and subroutine references are complicated.
 This document attempts to collect the requirements imposed by the 2018
 standard (and legacy extensions) on programs and implementations, work
 through the implications of the various features, and propose both a
 runtime model and a compiler design.
 
 All section, requirement, and constraint numbers herein pertain to
 the Fortran 2018 standard.
 
 This note does not consider calls to intrinsic procedures, statement
 functions, or calls to internal runtime support library routines.
 
-## Quick review of terminology
+Quick review of terminology
+---------------------------
+
 
 * A *dummy argument* is a function or subroutine parameter.
   It is *associated* with an *effective argument* at each call
   to the procedure.
 * The *shape* of an array is a vector containing its extent (size)
   on each dimension; the *rank* of an array is the number of its
   dimensions (i.e., the shape of its shape).
   The absolute values of the lower and upper bounds of the dimensions
   of an array are not part of its shape, just their difference (plus 1).
 * An *explicit-shape* array has all of its bounds specified; lower
   bounds default to 1.  These can be passed by with a single address
   and their contents are contiguous.
-* An *assumed-size* array is an explicit-shape array with `*` as its
+* An *assumed-size* array is an explicit-shape array with ``*`` as its
   final dimension, which is the most-significant one in Fortran
   and whose value does not affect indexed address calculations.
-* A *deferred-shape* array (`DIMENSION::A(:)`) is a `POINTER` or `ALLOCATABLE`.
-  `POINTER` target data might not be contiguous.
-* An *assumed-shape* (not size!) array (`DIMENSION::A(:)`) is a dummy argument
-  that is neither `POINTER` nor `ALLOCATABLE`; its lower bounds can be set
+* A *deferred-shape* array (\ ``DIMENSION::A(:)``\ ) is a ``POINTER`` or ``ALLOCATABLE``.
+  ``POINTER`` target data might not be contiguous.
+* An *assumed-shape* (not size!) array (\ ``DIMENSION::A(:)``\ ) is a dummy argument
+  that is neither ``POINTER`` nor ``ALLOCATABLE``\ ; its lower bounds can be set
   by the procedure that receives them (defaulting to 1), and its
   upper bounds are functions of the lower bounds and the extents of
   dimensions in the *shape* of the effective argument.
-* An *assumed-length* `CHARACTER(*)` dummy argument
+* An *assumed-length* ``CHARACTER(*)`` dummy argument
   takes its length from the effective argument.
-* An *assumed-length* `CHARACTER(*)` *result* of an external function (C721)
+* An *assumed-length* ``CHARACTER(*)`` *result* of an external function (C721)
   has its length determined by its eventual declaration in a calling scope.
-* An *assumed-rank* `DIMENSION::A(..)` dummy argument array has an unknown
+* An *assumed-rank* ``DIMENSION::A(..)`` dummy argument array has an unknown
   number of dimensions.
-* A *polymorphic* `CLASS(t)` dummy argument, `ALLOCATABLE`, or `POINTER`
+* A *polymorphic* ``CLASS(t)`` dummy argument, ``ALLOCATABLE``\ , or ``POINTER``
   has a specific derived type or some extension of that type.
-  An *unlimited polymorphic* `CLASS(*)` object can have any
+  An *unlimited polymorphic* ``CLASS(*)`` object can have any
   intrinsic or derived type.
-* *Interoperable* `BIND(C)` procedures are written in C or callable from C.
+* *Interoperable* ``BIND(C)`` procedures are written in C or callable from C.
 
-## Interfaces
+Interfaces
+----------
 
 Referenced procedures may or may not have declared interfaces
 available to their call sites.
 
 Procedures with some post-Fortran '77 features *require* an
 explicit interface to be called (15.4.2.2) or even passed (4.3.4(5)):
 
+
 * use of argument keywords in a call
-* procedures that are `ELEMENTAL` or `BIND(C)`
-* procedures that are required to be `PURE` due to the context of the call
-  (specification expression, `DO CONCURRENT`, `FORALL`)
-* dummy arguments with these attributes: `ALLOCATABLE`, `POINTER`,
-  `VALUE`, `TARGET`, `OPTIONAL`, `ASYNCHRONOUS`, `VOLATILE`,
-  and, as a consequence of limitations on its use, `CONTIGUOUS`;
-  `INTENT()`, however, does *not* require an explicit interface
+* procedures that are ``ELEMENTAL`` or ``BIND(C)``
+* procedures that are required to be ``PURE`` due to the context of the call
+  (specification expression, ``DO CONCURRENT``\ , ``FORALL``\ )
+* dummy arguments with these attributes: ``ALLOCATABLE``\ , ``POINTER``\ ,
+  ``VALUE``\ , ``TARGET``\ , ``OPTIONAL``\ , ``ASYNCHRONOUS``\ , ``VOLATILE``\ ,
+  and, as a consequence of limitations on its use, ``CONTIGUOUS``\ ;
+  ``INTENT()``\ , however, does *not* require an explicit interface
 * dummy arguments that are coarrays
 * dummy arguments that are assumed-shape or assumed-rank arrays
 * dummy arguments with parameterized derived types
 * dummy arguments that are polymorphic
 * function result that is an array
-* function result that is `ALLOCATABLE` or `POINTER`
-* `CHARACTER` function result whose length is neither constant
+* function result that is ``ALLOCATABLE`` or ``POINTER``
+* ``CHARACTER`` function result whose length is neither constant
   nor assumed
-* derived type function result with `LEN` type parameter value that is
+* derived type function result with ``LEN`` type parameter value that is
   not constant
   (note that result derived type parameters cannot be assumed (C795))
 
 Module procedures, internal procedures, procedure pointers,
 type-bound procedures, and recursive references by a procedure to itself
 always have explicit interfaces.
-(Consequently, they cannot be assumed-length `CHARACTER(*)` functions;
-conveniently, assumed-length `CHARACTER(*)` functions are prohibited from
+(Consequently, they cannot be assumed-length ``CHARACTER(*)`` functions;
+conveniently, assumed-length ``CHARACTER(*)`` functions are prohibited from
 recursion (15.6.2.1(3))).
 
 Other uses of procedures besides calls may also require explicit interfaces,
 such as procedure pointer assignment, type-bound procedure bindings, &c.
 
 Note that non-parameterized monomorphic derived type arguments do
 *not* by themselves require the use of an explicit interface.
 However, dummy arguments with any derived type parameters *do*
-require an explicit interface, even if they are all `KIND` type
+require an explicit interface, even if they are all ``KIND`` type
 parameters.
 
-15.5.2.9(2) explicitly allows an assumed-length `CHARACTER(*)` function
+15.5.2.9(2) explicitly allows an assumed-length ``CHARACTER(*)`` function
 to be passed as an actual argument to an explicit-length dummy;
 this has implications for calls to character-valued dummy functions
 and function pointers.
-(In the scopes that reference `CHARACTER` functions, they must have
+(In the scopes that reference ``CHARACTER`` functions, they must have
 visible definitions with explicit result lengths.)
 
-### Implicit interfaces
+Implicit interfaces
+^^^^^^^^^^^^^^^^^^^
 
 In the absence of any characteristic or context that *requires* an
 explicit interface (see above), an external function or subroutine (R503)
-or `ENTRY` (R1541) can be called directly or indirectly via its implicit interface.
+or ``ENTRY`` (R1541) can be called directly or indirectly via its implicit interface.
 Each of the arguments can be passed as a simple address, including
 dummy procedures.
 Procedures that *can* be called via an implicit interface can
 undergo more thorough checking
 by semantics when an explicit interface for them exists, but they must be
 compiled as if all calls to them were through the implicit interface.
 This note will mention special handling for procedures that are exposed
 to the possibility of being called with an implicit interface as *F77ish* procedures
 below; this is of course not standard terminology.
 
 Internal and module subprograms that are ever passed as arguments &/or
 assigned as targets of procedure pointers may be F77ish.
 
 Every F77ish procedure can and must be distiguished at compilation time.
 Such procedures should respect the external naming conventions (when external)
 and any legacy ABI used for Fortran '77 programs on the target architecture,
 so that portable libraries can be compiled
 and used by distinct implementations (and their versions)
 of Fortran.
 
 Note that F77ish functions still have known result types, possibly by means
 of implicit typing of their names.
-They can also be `CHARACTER(*)` assumed-length character functions.
+They can also be ``CHARACTER(*)`` assumed-length character functions.
 
 In other words: these F77sh procedures that do not require the use of an explicit
 interface and that can possibly be referenced, directly or indirectly,
 with implicit interfaces are limited to argument lists that comprise
-only the addresses of effective arguments and the length of a `CHARACTER` function result
+only the addresses of effective arguments and the length of a ``CHARACTER`` function result
 (when there is one), and they can return only scalar values with constant
 type parameter values.
 None of their arguments or results need be (or can be) implemented
 with descriptors,
 and any internal procedures passed to them as arguments must be
 simple addresses of non-internal subprograms or trampolines for
 internal procedures.
 
-Note that the `INTENT` attribute does not, by itself,
+Note that the ``INTENT`` attribute does not, by itself,
 require the use of explicit interface; neither does the use of a dummy
 procedure (implicit or explicit in their interfaces).
 So the analyis of calls to F77ish procedures must allow for the
-invisible use of `INTENT(OUT)`.
+invisible use of ``INTENT(OUT)``.
 
-## Protocol overview
+Protocol overview
+-----------------
 
 Here is a summary script of all of the actions that may need to be taken
 by the calling procedure and its referenced procedure to effect
 the call, entry, exit, and return steps of the procedure reference
 protocol.
 The order of these steps is not particularly strict, and we have
 some design alternatives that are explored further below.
 
-### Before the call:
+Before the call:
+^^^^^^^^^^^^^^^^
+
 
-1. Compute &/or copy into temporary storage the values of
+#. Compute &/or copy into temporary storage the values of
    some effective argument expressions and designators (see below).
-1. Create and populate descriptors for arguments that use them
+#. Create and populate descriptors for arguments that use them
    (see below).
-1. Possibly allocate function result storage,
+#. Possibly allocate function result storage,
    when its size can be known by all callers; function results that are
-   neither `POINTER` nor `ALLOCATABLE` must have explicit shapes (C816).
-1. Create and populate a descriptor for the function result, if it
-   needs one (deferred-shape/-length `POINTER`, any `ALLOCATABLE`,
+   neither ``POINTER`` nor ``ALLOCATABLE`` must have explicit shapes (C816).
+#. Create and populate a descriptor for the function result, if it
+   needs one (deferred-shape/-length ``POINTER``\ , any ``ALLOCATABLE``\ ,
    derived type with non-constant length parameters, &c.).
-1. Capture the values of host-escaping local objects in memory;
+#. Capture the values of host-escaping local objects in memory;
    package them into single address (for calls to internal procedures &
    for calls that pass internal procedures as arguments).
-1. Resolve the target procedure's polymorphic binding, if any.
-1. Marshal effective argument addresses (or values for `%VAL()` and some
-   discretionary `VALUE` arguments) into registers.
-1. Marshal `CHARACTER` argument lengths in additional value arguments for
-   `CHARACTER` effective arguments not passed via descriptors.
+#. Resolve the target procedure's polymorphic binding, if any.
+#. Marshal effective argument addresses (or values for ``%VAL()`` and some
+   discretionary ``VALUE`` arguments) into registers.
+#. Marshal ``CHARACTER`` argument lengths in additional value arguments for
+   ``CHARACTER`` effective arguments not passed via descriptors.
    These lengths must be 64-bit integers.
-1. Marshal an extra argument for the length of a `CHARACTER` function
+#. Marshal an extra argument for the length of a ``CHARACTER`` function
    result if the function is F77ish.
-1. Marshal an extra argument for the function result's descriptor,
+#. Marshal an extra argument for the function result's descriptor,
    if it needs one.
-1. Set the "host instance" (static link) register when calling an internal
+#. Set the "host instance" (static link) register when calling an internal
    procedure from its host or another internal procedure, a procedure pointer,
    or dummy procedure (when it has a descriptor).
-1. Jump.
+#. Jump.
 
-### On entry:
-1. For subprograms with alternate `ENTRY` points: shuffle `ENTRY` dummy arguments
+On entry:
+^^^^^^^^^
+
+
+#. For subprograms with alternate ``ENTRY`` points: shuffle ``ENTRY`` dummy arguments
    set a compiler-generated variable to identify the alternate entry point,
-   and jump to the common entry point for common processing and a `switch()`
-   to the statement after the `ENTRY`.
-1. Capture `CHARACTER` argument &/or assumed-length result length values.
-1. Complete `VALUE` copying if this step will not always be done
+   and jump to the common entry point for common processing and a ``switch()``
+   to the statement after the ``ENTRY``.
+#. Capture ``CHARACTER`` argument &/or assumed-length result length values.
+#. Complete ``VALUE`` copying if this step will not always be done
    by the caller (as I think it should be).
-1. Finalize &/or re-initialize `INTENT(OUT)` non-pointer
+#. Finalize &/or re-initialize ``INTENT(OUT)`` non-pointer
    effective arguments (see below).
-1. For interoperable procedures called from C: compact discontiguous
-   dummy argument values when necessary (`CONTIGUOUS` &/or
-   explicit-shape/assumed-size arrays of assumed-length `CHARACTER(*)`).
-1. Optionally compact assumed-shape arguments for contiguity on one
+#. For interoperable procedures called from C: compact discontiguous
+   dummy argument values when necessary (\ ``CONTIGUOUS`` &/or
+   explicit-shape/assumed-size arrays of assumed-length ``CHARACTER(*)``\ ).
+#. Optionally compact assumed-shape arguments for contiguity on one
    or more leading dimensions to improve SIMD vectorization, if not
-   `TARGET` and not already sufficiently contiguous.
+   ``TARGET`` and not already sufficiently contiguous.
    (PGI does this in the caller, whether the callee needs it or not.)
-1. Complete allocation of function result storage, if that has
+#. Complete allocation of function result storage, if that has
    not been done by the caller.
-1. Initialize components of derived type local variables,
+#. Initialize components of derived type local variables,
    including the function result.
 
 Execute the callee, populating the function result or selecting
 the subroutine's alternate return.
 
-### On exit:
-1. Clean up local scope (finalization, deallocation)
-1. Deallocate `VALUE` argument temporaries.
+On exit:
+^^^^^^^^
+
+
+#. Clean up local scope (finalization, deallocation)
+#. Deallocate ``VALUE`` argument temporaries.
    (But don't finalize them; see 7.5.6.3(3)).
-1. Replace any assumed-shape argument data that were compacted on
+#. Replace any assumed-shape argument data that were compacted on
    entry for contiguity when the data were possibly
-   modified across the call (never when `INTENT(IN)` or `VALUE`).
-1. Identify alternate `RETURN` to caller.
-1. Marshal results.
-1. Jump
-
-### On return to the caller:
-1. Save the result registers, if any.
-1. Copy effective argument array designator data that was copied into
+   modified across the call (never when ``INTENT(IN)`` or ``VALUE``\ ).
+#. Identify alternate ``RETURN`` to caller.
+#. Marshal results.
+#. Jump
+
+On return to the caller:
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+#. Save the result registers, if any.
+#. Copy effective argument array designator data that was copied into
    a temporary back into its original storage (see below).
-1. Complete deallocation of effective argument temporaries (not `VALUE`).
-1. Reload definable host-escaping local objects from memory, if they
+#. Complete deallocation of effective argument temporaries (not ``VALUE``\ ).
+#. Reload definable host-escaping local objects from memory, if they
    were saved to memory by the host before the call.
-1. `GO TO` alternate return, if any.
-1. Use the function result in an expression.
-1. Eventually, finalize &/or deallocate the function result.
+#. ``GO TO`` alternate return, if any.
+#. Use the function result in an expression.
+#. Eventually, finalize &/or deallocate the function result.
 
 (I've omitted some obvious steps, like preserving/restoring callee-saved
 registers on entry/exit, dealing with caller-saved registers before/after
 calls, and architecture-dependent ABI requirements.)
 
-## The messy details
+The messy details
+-----------------
 
-### Copying effective argument values into temporary storage
+Copying effective argument values into temporary storage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are several conditions that require the compiler to generate
 code that allocates and populates temporary storage for an actual
 argument.
 
 First, effective arguments that are expressions, not designators, obviously
 need to be computed and captured into memory in order to be passed
 by reference.
-This includes parenthesized designators like `(X)`, which are
+This includes parenthesized designators like ``(X)``\ , which are
 expressions in Fortran, as an important special case.
 (This case also technically includes unparenthesized constants,
 but those are better implemented by passing addresses in read-only
 memory.)
-The dummy argument cannot be known to have `INTENT(OUT)` or
-`INTENT(IN OUT)`.
+The dummy argument cannot be known to have ``INTENT(OUT)`` or
+``INTENT(IN OUT)``.
 
-Small scalar or elemental `VALUE` arguments may be passed in registers,
-as should arguments wrapped in the legacy VMS `%VAL()` notation.
-Multiple elemental `VALUE` arguments might be packed into SIMD registers.
+Small scalar or elemental ``VALUE`` arguments may be passed in registers,
+as should arguments wrapped in the legacy VMS ``%VAL()`` notation.
+Multiple elemental ``VALUE`` arguments might be packed into SIMD registers.
 
 Effective arguments that are designators, not expressions, must also
 be copied into temporaries in the following situations.
 
-1. Coindexed objects need to be copied into the local image.
-   This can get very involved if they contain `ALLOCATABLE`
+
+#. Coindexed objects need to be copied into the local image.
+   This can get very involved if they contain ``ALLOCATABLE``
    components, which also need to be copied, along with their
-   `ALLOCATABLE` components, and may be best implemented with a runtime
+   ``ALLOCATABLE`` components, and may be best implemented with a runtime
    library routine working off a description of the type.
-1. Effective arguments associated with dummies with the `VALUE`
+#. Effective arguments associated with dummies with the ``VALUE``
    attribute need to be copied; this can be done on either
    side of the call, but there are optimization opportunities
    available when the caller's side bears the responsibility.
-1. In non-elemental calls, the values of array sections with
+#. In non-elemental calls, the values of array sections with
    vector-valued subscripts need to be gathered into temporaries.
    These effective arguments are not definable, and they are not allowed to
-   be associated with non-`VALUE` dummy arguments with the attributes
-   `INTENT(OUT)`, `INTENT(IN OUT)`, `ASYNCHRONOUS`, or `VOLATILE`
-   (15.5.2.4(21)); `INTENT()` can't always be checked.
-1. Non-simply-contiguous (9.5.4) arrays being passed to non-`POINTER`
-   dummy arguments that must be contiguous (due to a `CONTIGUOUS`
+   be associated with non-\ ``VALUE`` dummy arguments with the attributes
+   ``INTENT(OUT)``\ , ``INTENT(IN OUT)``\ , ``ASYNCHRONOUS``\ , or ``VOLATILE``
+   (15.5.2.4(21)); ``INTENT()`` can't always be checked.
+#. Non-simply-contiguous (9.5.4) arrays being passed to non-\ ``POINTER``
+   dummy arguments that must be contiguous (due to a ``CONTIGUOUS``
    attribute, or not being assumed-shape or assumed-rank; this
    is always the case for F77ish procedures).
    This should be a runtime decision, so that effective arguments
    that turn out to be contiguous can be passed cheaply.
    This rule does not apply to coarray dummies, whose effective arguments
    are required to be simply contiguous when this rule would otherwise
    force the use of a temporary (15.5.2.8); neither does it apply
-   to `ASYNCHRONOUS` and `VOLATILE` effective arguments, which are
+   to ``ASYNCHRONOUS`` and ``VOLATILE`` effective arguments, which are
    disallowed when copies would be necessary (C1538 - C1540).
    *Only temporaries created by this contiguity requirement are
    candidates for being copied back to the original variable after
    the call* (see below).
 
 Fortran requires (18.3.6(5)) that calls to interoperable procedures
 with dummy argument arrays with contiguity requirements
-handle the compaction of discontiguous data *in the Fortran callee*,
+handle the compaction of discontiguous data *in the Fortran callee*\ ,
 at least when called from C.
 And discontiguous data must be compacted on the *caller's* side
 when passed from Fortran to C (18.3.6(6)).
 
 We could perform all argument compaction (discretionary or
 required) in the callee, but there are many cases where the
 compiler knows that the effective argument data are contiguous
 when compiling the caller (a temporary is needed for other reasons,
 or the effective argument is simply contiguous) and a run-time test for
 discontiguity in the callee can be avoided by using a caller-compaction
 convention when we have the freedom to choose.
 
-While we are unlikely to want to _needlessly_ use a temporary for
+While we are unlikely to want to *needlessly* use a temporary for
 an effective argument that does not require one for any of these
 reasons above, we are specifically disallowed from doing so
 by the standard in cases where pointers to the original target
 data are required to be valid across the call (15.5.2.4(9-10)).
 In particular, compaction of assumed-shape arrays for discretionary
 contiguity on the leading dimension to ease SIMD vectorization
-cannot be done safely for `TARGET` dummies without `VALUE`.
+cannot be done safely for ``TARGET`` dummies without ``VALUE``.
 
-Effective arguments associated with known `INTENT(OUT)` dummies that
+Effective arguments associated with known ``INTENT(OUT)`` dummies that
 require allocation of a temporary -- and this can only be for reasons of
 contiguity -- don't have to populate it, but they do have to perform
-minimal initialization of any `ALLOCATABLE` components so that
+minimal initialization of any ``ALLOCATABLE`` components so that
 the runtime doesn't crash when the callee finalizes and deallocates
 them.
-`ALLOCATABLE` coarrays are prohibited from being affected by `INTENT(OUT)`
+``ALLOCATABLE`` coarrays are prohibited from being affected by ``INTENT(OUT)``
 (see C846).
 Note that calls to implicit interfaces must conservatively allow
-for the use of `INTENT(OUT)` by the callee.
+for the use of ``INTENT(OUT)`` by the callee.
 
-Except for `VALUE` and known `INTENT(IN)` dummy arguments, the original
+Except for ``VALUE`` and known ``INTENT(IN)`` dummy arguments, the original
 contents of local designators that have been compacted into temporaries
-could optionally have their `ALLOCATABLE` components invalidated
+could optionally have their ``ALLOCATABLE`` components invalidated
 across the call as an aid to debugging.
 
-Except for `VALUE` and known `INTENT(IN)` dummy arguments, the contents of
+Except for ``VALUE`` and known ``INTENT(IN)`` dummy arguments, the contents of
 the temporary storage will be copied back into the effective argument
 designator after control returns from the procedure, and it may be necessary
 to preserve addresses (or the values of subscripts and cosubscripts
 needed to recalculate them) of the effective argument designator, or its
 elements, in additional temporary storage if they can't be safely or
 quickly recomputed after the call.
 
-### `INTENT(OUT)` preparation
+``INTENT(OUT)`` preparation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Effective arguments that are associated with `INTENT(OUT)`
+Effective arguments that are associated with ``INTENT(OUT)``
 dummy arguments are required to be definable.
-This cannot always be checked, as the use of `INTENT(OUT)`
+This cannot always be checked, as the use of ``INTENT(OUT)``
 does not by itself mandate the use of an explicit interface.
 
-`INTENT(OUT)` arguments are finalized (as if) on entry to the called
+``INTENT(OUT)`` arguments are finalized (as if) on entry to the called
 procedure.  In particular, in calls to elemental procedures,
 the elements of an array are finalized by a scalar or elemental
-`FINAL` procedure (7.5.6.3(7)).
+``FINAL`` procedure (7.5.6.3(7)).
 
-Derived type components that are `ALLOCATABLE` are finalized
+Derived type components that are ``ALLOCATABLE`` are finalized
 and deallocated; they are prohibited from being coarrays.
 Components with initializers are (re)initialized.
 
-The preparation of effective arguments for `INTENT(OUT)` could be
+The preparation of effective arguments for ``INTENT(OUT)`` could be
 done on either side of the call.  If the preparation is
 done by the caller, there is an optimization opportunity
-in situations where unmodified incoming `INTENT(OUT)` dummy
-arguments whose types lack `FINAL` procedures are being passed
-onward as outgoing `INTENT(OUT)` arguments.
+in situations where unmodified incoming ``INTENT(OUT)`` dummy
+arguments whose types lack ``FINAL`` procedures are being passed
+onward as outgoing ``INTENT(OUT)`` arguments.
 
-### Arguments and function results requiring descriptors
+Arguments and function results requiring descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Dummy arguments are represented with the addresses of new descriptors
 when they have any of the following characteristics:
 
-1. assumed-shape array (`DIMENSION::A(:)`)
-1. assumed-rank array (`DIMENSION::A(..)`)
-1. parameterized derived type with assumed `LEN` parameters
-1. polymorphic (`CLASS(T)`, `CLASS(*)`)
-1. assumed-type (`TYPE(*)`)
-1. coarray dummy argument
-1. `INTENT(IN) POINTER` argument (15.5.2.7, C.10.4)
 
-`ALLOCATABLE` and other `POINTER` arguments can be passed by simple
+#. assumed-shape array (\ ``DIMENSION::A(:)``\ )
+#. assumed-rank array (\ ``DIMENSION::A(..)``\ )
+#. parameterized derived type with assumed ``LEN`` parameters
+#. polymorphic (\ ``CLASS(T)``\ , ``CLASS(*)``\ )
+#. assumed-type (\ ``TYPE(*)``\ )
+#. coarray dummy argument
+#. ``INTENT(IN) POINTER`` argument (15.5.2.7, C.10.4)
+
+``ALLOCATABLE`` and other ``POINTER`` arguments can be passed by simple
 address.
 
 Non-F77ish procedures use descriptors to represent two further
 kinds of dummy arguments:
 
-1. assumed-length `CHARACTER(*)`
-1. dummy procedures
+
+#. assumed-length ``CHARACTER(*)``
+#. dummy procedures
 
 F77ish procedures use other means to convey character length and host instance
 links (respectively) for these arguments.
 
 Function results are described by the caller & callee in
 a caller-supplied descriptor when they have any of the following
 characteristics, some which necessitate an explicit interface:
 
-1. deferred-shape array (so `ALLOCATABLE` or `POINTER`)
-1. derived type with any non-constant `LEN` parameter
+
+#. deferred-shape array (so ``ALLOCATABLE`` or ``POINTER``\ )
+#. derived type with any non-constant ``LEN`` parameter
    (C795 prohibit assumed lengths)
-1. procedure pointer result (when the interface must be explicit)
+#. procedure pointer result (when the interface must be explicit)
 
 Storage for a function call's result is allocated by the caller when
-possible: the result is neither `ALLOCATABLE` nor `POINTER`,
-the shape is scalar or explicit, and the type has `LEN` parameters
+possible: the result is neither ``ALLOCATABLE`` nor ``POINTER``\ ,
+the shape is scalar or explicit, and the type has ``LEN`` parameters
 that are constant expressions.
 In other words, the result doesn't require the use of a descriptor
 but can't be returned in registers.
 This allows a function result to be written directly into a local
 variable or temporary when it is safe to treat the variable as if
-it were an additional `INTENT(OUT)` argument.
-(Storage for `CHARACTER` results, assumed or explicit, is always
+it were an additional ``INTENT(OUT)`` argument.
+(Storage for ``CHARACTER`` results, assumed or explicit, is always
 allocated by the caller, and the length is always passed so that
 an assumed-length external function will work when eventually
 called from a scope that declares the length that it will use
 (15.5.2.9 (2)).)
 
-Note that the lower bounds of the dimensions of non-`POINTER`
-non-`ALLOCATABLE` dummy argument arrays are determined by the
+Note that the lower bounds of the dimensions of non-\ ``POINTER``
+non-\ ``ALLOCATABLE`` dummy argument arrays are determined by the
 callee, not the caller.
-(A Fortran pitfall: declaring `A(0:9)`, passing it to a dummy
-array `D(:)`, and assuming that `LBOUND(D,1)` will be zero
+(A Fortran pitfall: declaring ``A(0:9)``\ , passing it to a dummy
+array ``D(:)``\ , and assuming that ``LBOUND(D,1)`` will be zero
 in the callee.)
 If the declaration of an assumed-shape dummy argument array
 contains an explicit lower bound expression (R819), its value
 needs to be computed by the callee;
 it may be captured and saved in the incoming descriptor
 as long as we assume that argument descriptors can be modified
 by callees.
 Callers should fill in all of the fields of outgoing
-non-`POINTER` non-`ALLOCATABLE` argument
+non-\ ``POINTER`` non-\ ``ALLOCATABLE`` argument
 descriptors with the assumption that the callee will use 1 for
 lower bound values, and callees can rely on them being 1 if
 not modified.
 
-### Copying temporary storage back into argument designators
+Copying temporary storage back into argument designators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Except for `VALUE` and known `INTENT(IN)` dummy arguments and array sections
+Except for ``VALUE`` and known ``INTENT(IN)`` dummy arguments and array sections
 with vector-valued subscripts (15.5.2.4(21)), temporary storage into
 which effective argument data were compacted for contiguity before the call
 must be redistributed back to its original storage by the caller after
 the return.
 
 In conjunction with saved cosubscript values, a standard descriptor
 would suffice to represent a pointer to the original storage into which the
 temporary data should be redistributed;
 the descriptor need not be fully populated with type information.
 
-Note that coindexed objects with `ALLOCATABLE` ultimate components
+Note that coindexed objects with ``ALLOCATABLE`` ultimate components
 are required to be associated only with dummy arguments with the
-`VALUE` &/or `INTENT(IN)` attributes (15.6.2.4(6)), so there is no
+``VALUE`` &/or ``INTENT(IN)`` attributes (15.6.2.4(6)), so there is no
 requirement that the local image somehow reallocate remote storage
 when copying the data back.
 
-### Polymorphic bindings
+Polymorphic bindings
+^^^^^^^^^^^^^^^^^^^^
 
 Calls to the type-bound procedures of monomorphic types are
-resolved at compilation time, as are calls to `NON_OVERRIDABLE`
+resolved at compilation time, as are calls to ``NON_OVERRIDABLE``
 type-bound procedures.
 The resolution of calls to overridable type-bound procedures of
 polymorphic types must be completed at execution (generic resolution
 of type-bound procedure bindings from effective argument types, kinds,
 and ranks is always a compilation-time task (15.5.6, C.10.6)).
 
 Each derived type that declares or inherits any overridable
 type-bound procedure bindings must correspond to a static constant
 table of code addresses (or, more likely, a static constant type
 description containing or pointing to such a table, along with
 information used by the runtime support library for initialization,
 copying, finalization, and I/O of type instances).  Each overridable
 type-bound procedure in the type corresponds to an index into this table.
 
-### Host instance linkage
+Host instance linkage
+^^^^^^^^^^^^^^^^^^^^^
 
 Calls to dummy procedures and procedure pointers that resolve to
 internal procedures need to pass an additional "host instance" argument that
 addresses a block of storage in the stack frame of the their
 host subprogram that was active at the time they were passed as an
 effective argument or associated with a procedure pointer.
 This is similar to a static link in implementations of programming
 languages with nested subprograms, although Fortran only allows
 one level of nesting.
 The 64-bit x86 and little-endian OpenPower ABIs reserve registers
-for this purpose (`%r10` & `R11`); 64-bit ARM has a reserved register
-that can be used (`x18`).
+for this purpose (\ ``%r10`` & ``R11``\ ); 64-bit ARM has a reserved register
+that can be used (\ ``x18``\ ).
 
 The host subprogram objects that are visible to any of their internal
 subprograms need to be resident in memory across any calls to them
 (direct or not).  Any host subprogram object that might be defined
 during a call to an internal subprogram needs to be reloaded after
 a call or reside permanently in memory.
 A simple conservative analysis of the internal subprograms can
 identify all of these escaping objects and their definable subset.

 to F77ish procedures, so that
 a bare code address can serve to represent the effective argument.
 But targets that can only be called with an explicit interface
 have the option of using a "fat pointer" (or additional argument)
 to represent a dummy procedure closure so as
 to avoid the overhead of constructing and reclaiming a trampoline.
 Procedure descriptors can also support multiple code addresses.
 
-### Naming
+Naming
+^^^^^^
 
-External subroutines and functions (R503) and `ENTRY` points (R1541)
-with `BIND(C)` (R808) have linker-visible names that are either explicitly
+External subroutines and functions (R503) and ``ENTRY`` points (R1541)
+with ``BIND(C)`` (R808) have linker-visible names that are either explicitly
 specified in the program or determined by straightforward rules.
 The names of other F77ish external procedures should respect the conventions
 of the target architecture for legacy Fortran '77 programs; this is typically
-something like `foo_`.
+something like ``foo_``.
 
 In other cases, however, we have fewer constraints on external naming,
 as well as some additional requirements and goals.
 
 Module procedures need to be distinguished by the name of their module
 and (when they have one) the submodule where their interface was
 defined.
 Note that submodule names are distinct in their modules, not hierarchical,
 so at most two levels of qualification are needed.
 
-Pure `ELEMENTAL` functions (15.8) must use distinct names for any alternate
+Pure ``ELEMENTAL`` functions (15.8) must use distinct names for any alternate
 entry points used for packed SIMD arguments of various widths if we support
 calls to these functions in SIMD parallel contexts.
-There are already conventions for these names in `libpgmath`.
+There are already conventions for these names in ``libpgmath``.
 
 The names of non-F77ish external procedures
 should be distinguished as such so that incorrect attempts to call or pass
 them with an implicit interface will fail to resolve at link time.
 Fortran 2018 explicitly enables us to do this with a correction to Fortran
 2003 in 4.3.4(5).
 
 Last, there must be reasonably permanent naming conventions used
 by the F18 runtime library for those unrestricted specific intrinsic
 functions (table 16.2 in 16.8) and extensions that can be passed as
 arguments.
 
 In these cases where external naming is at the discretion
 of the implementation, we should use names that are not in the C language
 user namespace, begin with something that identifies
 the current incompatible version of F18, the module, the submodule, and
 elemental SIMD width, and are followed by the external name.
 The parts of the external name can be separated by some character that
 is acceptable for use in LLVM IR and assembly language but not in user
 Fortran or C code, or by switching case
 (so long as there's a way to cope with extension names that don't begin
 with letters).
 
-In particular, the period (`.`) seems safe to use as a separator character,
-so a `Fa.` prefix can serve to isolate these discretionary names from
+In particular, the period (\ ``.``\ ) seems safe to use as a separator character,
+so a ``Fa.`` prefix can serve to isolate these discretionary names from
 other uses and to identify the earliest link-compatible version.
-For examples: `Fa.mod.foo`, `Fa.mod.submod.foo`, and (for an external
-subprogram that requires an explicit interface) `Fa.foo`.
+For examples: ``Fa.mod.foo``\ , ``Fa.mod.submod.foo``\ , and (for an external
+subprogram that requires an explicit interface) ``Fa.foo``.
 When the ABI changes in the future in an incompatible way, the
-initial prefix becomes `Fb.`, `Fc.`, &c.
+initial prefix becomes ``Fb.``\ , ``Fc.``\ , &c.
 
-## Summary of checks to be enforced in semantics analysis
+Summary of checks to be enforced in semantics analysis
+------------------------------------------------------
 
-8.5.10 `INTENT` attributes
-* (C846) An `INTENT(OUT)` argument shall not be associated with an
+8.5.10 ``INTENT`` attributes
+
+
+* (C846) An ``INTENT(OUT)`` argument shall not be associated with an
   object that is or has an allocatable coarray.
-* (C847) An `INTENT(OUT)` argument shall not have `LOCK_TYPE` or `EVENT_TYPE`.
+* (C847) An ``INTENT(OUT)`` argument shall not have ``LOCK_TYPE`` or ``EVENT_TYPE``.
+
+8.5.18 ``VALUE`` attribute
+
 
-8.5.18 `VALUE` attribute
 * (C863) The argument cannot be assumed-size, a coarray, or have a coarray
   ultimate component.
-* (C864) The argument cannot be `ALLOCATABLE`, `POINTER`, `INTENT(OUT)`,
-  `INTENT(IN OUT)`, or `VOLATILE`.
-* (C865) If the procedure is `BIND(C)`, the argument cannot be `OPTIONAL`.
+* (C864) The argument cannot be ``ALLOCATABLE``\ , ``POINTER``\ , ``INTENT(OUT)``\ ,
+  ``INTENT(IN OUT)``\ , or ``VOLATILE``.
+* (C865) If the procedure is ``BIND(C)``\ , the argument cannot be ``OPTIONAL``.
 
 15.5.1 procedure references:
-* (C1533) can't pass non-intrinsic `ELEMENTAL` as argument
+
+
+* (C1533) can't pass non-intrinsic ``ELEMENTAL`` as argument
 * (C1536) alternate return labels must be in the inclusive scope
-* (C1537) coindexed argument cannot have a `POINTER` ultimate component
+* (C1537) coindexed argument cannot have a ``POINTER`` ultimate component
+
+15.5.2.4 requirements for non-\ ``POINTER`` non-\ ``ALLOCATABLE`` dummies:
+
 
-15.5.2.4 requirements for non-`POINTER` non-`ALLOCATABLE` dummies:
 * (2) dummy must be monomorphic for coindexed polymorphic actual
 * (2) dummy must be polymorphic for assumed-size polymorphic actual
-* (2) dummy cannot be `TYPE(*)` if effective is PDT or has TBPs or `FINAL`
+* (2) dummy cannot be ``TYPE(*)`` if effective is PDT or has TBPs or ``FINAL``
 * (4) character length of effective cannot be less than dummy
-* (6) coindexed effective with `ALLOCATABLE` ultimate component requires
-      `INTENT(IN)` &/or `VALUE` dummy
+* (6) coindexed effective with ``ALLOCATABLE`` ultimate component requires
+  .. code-block::
+
+
 * (13) a coindexed scalar effective requires a scalar dummy
 * (14) a non-conindexed scalar effective usually requires a scalar dummy,
   but there are some exceptions that allow elements of storage sequences
   to be passed and treated like explicit-shape or assumed-size arrays
   (see 15.5.2.11)
 * (16) array rank agreement
-* (20) `INTENT(OUT)` & `INTENT(IN OUT)` dummies require definable actuals
+* (20) ``INTENT(OUT)`` & ``INTENT(IN OUT)`` dummies require definable actuals
 * (21) array sections with vector subscripts can't be passed to definable dummies
-       (`INTENT(OUT)`, `INTENT(IN OUT)`, `ASYNCHRONOUS`, `VOLATILE`)
-* (22) `VOLATILE` attributes must match when dummy has a coarray ultimate component
-* (C1538 - C1540) checks for `ASYNCHRONOUS` and `VOLATILE`
+  .. code-block::
+
 
-15.5.2.5 requirements for `ALLOCATABLE` & `POINTER` arguments when both
+* (22) ``VOLATILE`` attributes must match when dummy has a coarray ultimate component
+* (C1538 - C1540) checks for ``ASYNCHRONOUS`` and ``VOLATILE``
+
+15.5.2.5 requirements for ``ALLOCATABLE`` & ``POINTER`` arguments when both
 the dummy and effective arguments have the same attributes:
+
+
 * (2) both or neither can be polymorphic
 * (2) both are unlimited polymorphic or both have the same declared type
 * (3) rank compatibility
 * (4) effective argument must have deferred the same type parameters as the dummy
 
-15.5.2.6 `ALLOCATABLE` dummy arguments:
-* (2) effective must be `ALLOCATABLE`
+15.5.2.6 ``ALLOCATABLE`` dummy arguments:
+
+
+* (2) effective must be ``ALLOCATABLE``
 * (3) corank must match
-* (4) coindexed effective requires `INTENT(IN)` dummy
-* (7) `INTENT(OUT)` & `INTENT(IN OUT)` dummies require definable actuals
+* (4) coindexed effective requires ``INTENT(IN)`` dummy
+* (7) ``INTENT(OUT)`` & ``INTENT(IN OUT)`` dummies require definable actuals
 
-15.5.2.7 `POINTER` dummy arguments:
-* (C1541) `CONTIGUOUS` dummy requires simply contiguous actual
+15.5.2.7 ``POINTER`` dummy arguments:
+
+
+* (C1541) ``CONTIGUOUS`` dummy requires simply contiguous actual
 * (C1542) effective argument cannot be coindexed unless procedure is intrinsic
-* (2) effective argument must be `POINTER` unless dummy is `INTENT(IN)` and
+* (2) effective argument must be ``POINTER`` unless dummy is ``INTENT(IN)`` and
   effective could be the right-hand side of a pointer assignment statement
 
 15.5.2.8 corray dummy arguments:
+
+
 * (1) effective argument must be coarray
-* (1) `VOLATILE` attributes must match
+* (1) ``VOLATILE`` attributes must match
 * (2) explicitly or implicitly contiguous dummy array requires a simply contiguous actual
 
 15.5.2.9 dummy procedures:
+
+
 * (1) explicit dummy procedure interface must have same characteristics as actual
-* (5) dummy procedure `POINTER` requirements on effective arguments
+* (5) dummy procedure ``POINTER`` requirements on effective arguments
 
 15.6.2.1 procedure definitions:
-* `NON_RECURSIVE` procedures cannot recurse.
-* Assumed-length `CHARACTER(*)` functions cannot be declared as `RECURSIVE`, array-valued,
-  `POINTER`, `ELEMENTAL`, or `PURE' (C723), and cannot be called recursively (15.6.2.1(3)).
+
+
+* ``NON_RECURSIVE`` procedures cannot recurse.
+* Assumed-length ``CHARACTER(*)`` functions cannot be declared as ``RECURSIVE``\ , array-valued,
+  ``POINTER``\ , ``ELEMENTAL``\ , or `PURE' (C723), and cannot be called recursively (15.6.2.1(3)).
 * (C823) A function result cannot be a coarray or contain a coarray ultimate component.
 
-`PURE` requirements (15.7): C1583 - C1599.
-These also apply to `ELEMENTAL` procedures that are not `IMPURE`.
+``PURE`` requirements (15.7): C1583 - C1599.
+These also apply to ``ELEMENTAL`` procedures that are not ``IMPURE``.
 
-`ELEMENTAL` requirements (15.8.1): C15100-C15103,
+``ELEMENTAL`` requirements (15.8.1): C15100-C15103,
 and C1533 (can't pass as effective argument unless intrinsic)
 
 For interoperable procedures and interfaces (18.3.6):
+
+
 * C1552 - C1559
 * function result is scalar and of interoperable type (C1553, 18.3.1-3)
-* `VALUE` arguments are scalar and of interoperable type
-* `POINTER` dummies cannot be `CONTIGUOUS` (18.3.6 paragraph 2(5))
-* assumed-type dummies cannot be `ALLOCATABLE`, `POINTER`, assumed-shape, or assumed-rank (18.3.6 paragraph 2 (5))
-* `CHARACTER` dummies that are `ALLOCATABLE` or `POINTER` must be deferred-length
+* ``VALUE`` arguments are scalar and of interoperable type
+* ``POINTER`` dummies cannot be ``CONTIGUOUS`` (18.3.6 paragraph 2(5))
+* assumed-type dummies cannot be ``ALLOCATABLE``\ , ``POINTER``\ , assumed-shape, or assumed-rank (18.3.6 paragraph 2 (5))
+* ``CHARACTER`` dummies that are ``ALLOCATABLE`` or ``POINTER`` must be deferred-length
+
+Further topics to document
+--------------------------
 
-## Further topics to document
 
 * Alternate return specifiers
-* `%VAL()`, `%REF()`, and `%DESCR()` legacy VMS interoperability extensions
+* ``%VAL()``\ , ``%REF()``\ , and ``%DESCR()`` legacy VMS interoperability extensions
 * Unrestricted specific intrinsic functions as effective arguments
-* SIMD variants of `ELEMENTAL` procedures (& unrestricted specific intrinsics)
+* SIMD variants of ``ELEMENTAL`` procedures (& unrestricted specific intrinsics)
 * Elemental subroutine calls with array arguments

flang/docs/Character.rst

-<!--===- documentation/Character.md
+
+
+.. raw:: html
+
+   <!--===- documentation/Character.rst
 
       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
 
    -->
 
-## Implementation of `CHARACTER` types in f18
 
-### Kinds and Character Sets
+
+Implementation of ``CHARACTER`` types in f18
+------------------------------------------------
+
+Kinds and Character Sets
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 The f18 compiler and runtime support three kinds of the intrinsic
-`CHARACTER` type of Fortran 2018.
-The default (`CHARACTER(KIND=1)`) holds 8-bit character codes;
-`CHARACTER(KIND=2)` holds 16-bit character codes;
-and `CHARACTER(KIND=4)` holds 32-bit character codes.
+``CHARACTER`` type of Fortran 2018.
+The default (\ ``CHARACTER(KIND=1)``\ ) holds 8-bit character codes;
+``CHARACTER(KIND=2)`` holds 16-bit character codes;
+and ``CHARACTER(KIND=4)`` holds 32-bit character codes.
 
 We assume that code values 0 through 127 correspond to
-the 7-bit ASCII character set (ISO-646) in every kind of `CHARACTER`.
+the 7-bit ASCII character set (ISO-646) in every kind of ``CHARACTER``.
 This is a valid assumption for Unicode (UCS == ISO/IEC-10646),
 ISO-8859, and many legacy character sets and interchange formats.
 
-`CHARACTER` data in memory and unformatted files are not in an
+``CHARACTER`` data in memory and unformatted files are not in an
 interchange representation (like UTF-8, Shift-JIS, EUC-JP, or a JIS X).
 Each character's code in memory occupies a 1-, 2-, or 4- byte
 word and substrings can be indexed with simple arithmetic.
-In formatted I/O, however, `CHARACTER` data may be assumed to use
+In formatted I/O, however, ``CHARACTER`` data may be assumed to use
 the UTF-8 variable-length encoding when it is selected with
-`OPEN(ENCODING='UTF-8')`.
+``OPEN(ENCODING='UTF-8')``.
 
-`CHARACTER(KIND=1)` literal constants in Fortran source files,
-Hollerith constants, and formatted I/O with `ENCODING='DEFAULT'`
+``CHARACTER(KIND=1)`` literal constants in Fortran source files,
+Hollerith constants, and formatted I/O with ``ENCODING='DEFAULT'``
 are not translated.
 
-For the purposes of non-default-kind `CHARACTER` constants in Fortran
-source files, formatted I/O with `ENCODING='UTF-8'` or non-default-kind
-`CHARACTER` value, and conversions between kinds of `CHARACTER`,
+For the purposes of non-default-kind ``CHARACTER`` constants in Fortran
+source files, formatted I/O with ``ENCODING='UTF-8'`` or non-default-kind
+``CHARACTER`` value, and conversions between kinds of ``CHARACTER``\ ,
 by default:
-* `CHARACTER(KIND=1)` is assumed to be ISO-8859-1 (Latin-1),
-* `CHARACTER(KIND=2)` is assumed to be UCS-2 (16-bit Unicode), and
-* `CHARACTER(KIND=4)` is assumed to be UCS-4 (full Unicode in a 32-bit word).
+
+
+* ``CHARACTER(KIND=1)`` is assumed to be ISO-8859-1 (Latin-1),
+* ``CHARACTER(KIND=2)`` is assumed to be UCS-2 (16-bit Unicode), and
+* ``CHARACTER(KIND=4)`` is assumed to be UCS-4 (full Unicode in a 32-bit word).
 
 In particular, conversions between kinds are assumed to be
 simple zero-extensions or truncation, not table look-ups.
 
 We might want to support one or more environment variables to change these
-assumptions, especially for `KIND=1` users of ISO-8859 character sets
+assumptions, especially for ``KIND=1`` users of ISO-8859 character sets
 besides Latin-1.
 
-### Lengths
+Lengths
+^^^^^^^
 
-Allocatable `CHARACTER` objects in Fortran may defer the specification
+Allocatable ``CHARACTER`` objects in Fortran may defer the specification
 of their lengths until the time of their allocation or whole (non-substring)
 assignment.
 Non-allocatable objects (and non-deferred-length allocatables) have
 lengths that are fixed or assumed from an actual argument, or,
-in the case of assumed-length `CHARACTER` functions, their local
+in the case of assumed-length ``CHARACTER`` functions, their local
 declaration in the calling scope.
 
-The elements of `CHARACTER` arrays have the same length.
+The elements of ``CHARACTER`` arrays have the same length.
 
 Assignments to targets that are not deferred-length allocatables will
 truncate or pad the assigned value to the length of the left-hand side
 of the assignment.
 
 Lengths and offsets that are used by or exposed to Fortran programs via
-declarations, substring bounds, and the `LEN()` intrinsic function are always
+declarations, substring bounds, and the ``LEN()`` intrinsic function are always
 represented in units of characters, not bytes.
 In generated code, assumed-length arguments, the runtime support library,
-and in the `elem_len` field of the interoperable descriptor `cdesc_t`,
+and in the ``elem_len`` field of the interoperable descriptor ``cdesc_t``\ ,
 lengths are always in units of bytes.
 The distinction matters only for kinds other than the default.
 
 Fortran substrings are rather like subscript triplets into a hidden
-"zero" dimension of a scalar `CHARACTER` value, but they cannot have
+"zero" dimension of a scalar ``CHARACTER`` value, but they cannot have
 strides.
 
-### Concatenation
+Concatenation
+^^^^^^^^^^^^^
 
-Fortran has one `CHARACTER`-valued intrinsic operator, `//`, which
+Fortran has one ``CHARACTER``\ -valued intrinsic operator, ``//``\ , which
 concatenates its operands (10.1.5.3).
 The operands must have the same kind type parameter.
 One or both of the operands may be arrays; if both are arrays, their
 shapes must be identical.
 The effective length of the result is the sum of the lengths of the
 operands.
-Parentheses may be ignored, so any `CHARACTER`-valued expression
+Parentheses may be ignored, so any ``CHARACTER``\ -valued expression
 may be "flattened" into a single sequence of concatenations.
 
-The result of `//` may be used
+The result of ``//`` may be used
+
+
 * as an operand to another concatenation,
-* as an operand of a `CHARACTER` relation,
+* as an operand of a ``CHARACTER`` relation,
 * as an actual argument,
 * as the right-hand side of an assignment,
-* as the `SOURCE=` or `MOLD=` of an `ALLOCATE` statemnt,
-* as the selector or case-expr of an `ASSOCIATE` or `SELECT` construct,
+* as the ``SOURCE=`` or ``MOLD=`` of an ``ALLOCATE`` statemnt,
+* as the selector or case-expr of an ``ASSOCIATE`` or ``SELECT`` construct,
 * as a component of a structure or array constructor,
 * as the value of a named constant or initializer,
-* as the `NAME=` of a `BIND(C)` attribute,
-* as the stop-code of a `STOP` statement,
+* as the ``NAME=`` of a ``BIND(C)`` attribute,
+* as the stop-code of a ``STOP`` statement,
 * as the value of a specifier of an I/O statement,
 * or as the value of a statement function.
 
 The f18 compiler has a general (but slow) means of implementing concatenation
 and a specialized (fast) option to optimize the most common case.
 
-#### General concatenation
+General concatenation
+~~~~~~~~~~~~~~~~~~~~~
 
 In the most general case, the f18 compiler's generated code and
 runtime support library represent the result as a deferred-length allocatable
-`CHARACTER` temporary scalar or array variable that is initialized
-as a zero-length array by `AllocatableInitCharacter()`
+``CHARACTER`` temporary scalar or array variable that is initialized
+as a zero-length array by ``AllocatableInitCharacter()``
 and then progressively augmented in place by the values of each of the
 operands of the concatenation sequence in turn with calls to
-`CharacterConcatenate()`.
+``CharacterConcatenate()``.
 Conformability errors are fatal -- Fortran has no means by which a program
 may recover from them.
 The result is then used as any other deferred-length allocatable
 array or scalar would be, and finally deallocated like any other
 allocatable.
 
-The runtime routine `CharacterAssign()` takes care of
+The runtime routine ``CharacterAssign()`` takes care of
 truncating, padding, or replicating the value(s) assigned to the left-hand
 side, as well as reallocating an nonconforming or deferred-length allocatable
 left-hand side.  It takes the descriptors of the left- and right-hand sides of
-a `CHARACTER` assignemnt as its arguments.
+a ``CHARACTER`` assignemnt as its arguments.
 
-When the left-hand side of a `CHARACTER` assignment is a deferred-length
+When the left-hand side of a ``CHARACTER`` assignment is a deferred-length
 allocatable and the right-hand side is a temporary, use of the runtime's
-`MoveAlloc()` subroutine instead can save an allocation and a copy.
+``MoveAlloc()`` subroutine instead can save an allocation and a copy.
 
-#### Optimized concatenation
+Optimized concatenation
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Scalar `CHARACTER(KIND=1)` expressions evaluated as the right-hand sides of
+Scalar ``CHARACTER(KIND=1)`` expressions evaluated as the right-hand sides of
 assignments to independent substrings or whole variables that are not
 deferred-length allocatables can be optimized into a sequence of
 calls to the runtime support library that do not allocate temporary
 memory.
 
-The routine `CharacterAppend()` copies data from the right-hand side value
+The routine ``CharacterAppend()`` copies data from the right-hand side value
 to the remaining space, if any, in the left-hand side object, and returns
 the new offset of the reduced remaining space.
-It is essentially `memcpy(lhs + offset, rhs, min(lhsLength - offset, rhsLength))`.
-It does nothing when `offset > lhsLength`.
+It is essentially ``memcpy(lhs + offset, rhs, min(lhsLength - offset, rhsLength))``.
+It does nothing when ``offset > lhsLength``.
 
-`void CharacterPad()`adds any necessary trailing blank characters.
+``void CharacterPad()``\ adds any necessary trailing blank characters.

flang/docs/ControlFlowGraph.rst

-<!--===- documentation/ControlFlowGraph.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
-  
--->
-
-## Concept
+Concept
+-------
 After a Fortran subprogram has been parsed, its names resolved, and all its
 semantic constraints successfully checked, the parse tree of its
 executable part is translated into another abstract representation,
-namely the _control flow graph_ described in this note.
+namely the *control flow graph* described in this note.
 
 This second representation of the subprogram's executable part is
 suitable for analysis and incremental modification as the subprogram
 is readied for code generation.
 Many high-level Fortran features are implemented by rewriting portions
 of a subprogram's control flow graph in place.
 
-### Control Flow Graph
-A _control flow graph_ is a collection of simple (_i.e.,_ "non-extended")
-basic _blocks_ that comprise straight-line sequences of _actions_ with a
+Control Flow Graph
+^^^^^^^^^^^^^^^^^^
+
+A *control flow graph* is a collection of simple (\ *i.e.,* "non-extended")
+basic *blocks* that comprise straight-line sequences of *actions* with a
 single entry point and a single exit point, and a collection of
-directed flow _edges_ (or _arcs_) denoting all possible transitions of
+directed flow *edges* (or *arcs*\ ) denoting all possible transitions of
 control flow that may take place during execution from the end of
 one basic block to the beginning of another (or itself).
 
 A block that has multiple distinct successors in the flow of control
 must end with an action that selects its successor.
 
 The sequence of actions that constitutes a basic block may
 include references to user and library procedures.
 Subprogram calls with implicit control flow afterwards, namely
-alternate returns and `END=`/`ERR=` labels on input/output,
+alternate returns and ``END=``\ /\ ``ERR=`` labels on input/output,
 will be lowered in translation to a representation that materializes
-that control flow into something similar to a computed `GO TO` or
-C language `switch` statement.
+that control flow into something similar to a computed ``GO TO`` or
+C language ``switch`` statement.
 
 For convenience in optimization and to simplify the implementation of
 data flow confluence functions, we may choose to maintain the
 property that each flow arc is the sole outbound arc emanating from
 its originating block, the sole inbound arc arriving at its destination,
 or both.
 Empty blocks would inserted to "split" arcs when necessary to maintain this
 invariant property.
 
 Fortran subprograms (other than internal subprograms) can have multiple
-entry points by using the obsolescent `ENTRY` statement.
+entry points by using the obsolescent ``ENTRY`` statement.
 We will implement such subprograms by constructing a union
 of their dummy argument lists and using it as part of the definition
 of a new subroutine or function that can be called by each of
 the entry points, which are then all converted into wrapper routines that
-pass a selector value as an additional argument to drive a `switch` on entry
+pass a selector value as an additional argument to drive a ``switch`` on entry
 to the new subprogram.
 
 This transformation ensures that every subprogram's control
-flow graph has a well-defined `START` node.
+flow graph has a well-defined ``START`` node.
 
 Statement labels can be used in Fortran on any statement, but only
-the labels that decorate legal destinations of `GO TO` statements
+the labels that decorate legal destinations of ``GO TO`` statements
 need to be implemented in the control flow graph.
-Specifically, non-executable statements like `DATA`, `NAMELIST`, and
-`FORMAT` statements will be extracted into data initialization
+Specifically, non-executable statements like ``DATA``\ , ``NAMELIST``\ , and
+``FORMAT`` statements will be extracted into data initialization
 records before or during the construction of the control flow
-graph, and will survive only as synonyms for `CONTINUE`.
+graph, and will survive only as synonyms for ``CONTINUE``.
 
-Nests of multiple labeled `DO` loops that terminate on the same
-label will be have that label rewritten so that `GO TO` within
+Nests of multiple labeled ``DO`` loops that terminate on the same
+label will be have that label rewritten so that ``GO TO`` within
 the loop nest will arrive at the copy that most closely nests
 the context.
 The Fortran standard does not require us to do this, but XLF
 (at least) works this way.
 
-### Expressions and Statements (Operations and Actions)
+Expressions and Statements (Operations and Actions)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Expressions are trees, not DAGs, of intrinsic operations,
 resolved function references, constant literals, and
 data designators.
 
 Expression nodes are represented in the compiler in a type-safe manner.
 There is a distinct class or class template for every category of
 intrinsic type, templatized over its supported kind type parameter values.
 
 Operands are storage-owning indirections to other instances
-of `Expression`, instances of constant values, and to representations
+of ``Expression``\ , instances of constant values, and to representations
 of data and function references.
 These indirections are not nullable apart from the situation in which
 the operands of an expression are being removed for use elsewhere before
 the expression is destructed.
 
 The ranks and the extents of the shapes of the results of expressions
 are explicit for constant arrays and recoverable by analysis otherwise.
 
 Parenthesized subexpressions are scrupulously preserved in accordance with
 the Fortran standard.
 
 The expression tree is meant to be a representation that is
 as equally well suited for use in the symbol table (e.g., for
 a bound of an explicit shape array) as it is for an action
 in a basic block of the control flow graph (e.g., the right
 hand side of an assignment statement).
 
-Each basic block comprises a linear sequence of _actions_.
+Each basic block comprises a linear sequence of *actions*.
 These are represented as a doubly-linked list so that insertion
 and deletion can be done in constant time.
 
 Only the last action in a basic block can represent a change
 to the flow of control.
 
-### Scope Transitions
+Scope Transitions
+^^^^^^^^^^^^^^^^^
+
 Some of the various scopes of the symbol table are visible in the control flow
-graph as `SCOPE ENTRY` and `SCOPE EXIT` actions.
-`SCOPE ENTRY` actions are unique for their corresponding scopes,
-while `SCOPE EXIT` actions need not be so.
+graph as ``SCOPE ENTRY`` and ``SCOPE EXIT`` actions.
+``SCOPE ENTRY`` actions are unique for their corresponding scopes,
+while ``SCOPE EXIT`` actions need not be so.
 It must be the case that
 any flow of control within the subprogram will enter only scopes that are
 not yet active, and exit only the most recently entered scope that has not
 yet been deactivated; i.e., when modeled by a push-down stack that is
-pushed by each traversal of a `SCOPE ENTRY` action,
+pushed by each traversal of a ``SCOPE ENTRY`` action,
 the entries of the stack are always distinct, only the scope at
-the top of the stack is ever popped by `SCOPE EXIT`, and the stack is empty
+the top of the stack is ever popped by ``SCOPE EXIT``\ , and the stack is empty
 when the subprogram terminates.
 Further, any references to resolved symbols must be to symbols whose scopes
 are active.
 
-The `DEALLOCATE` actions and calls to `FINAL` procedures implied by scoped
+The ``DEALLOCATE`` actions and calls to ``FINAL`` procedures implied by scoped
 lifetimes will be explicit in the sequence of actions in the control flow
 graph.
 
 Parallel regions might be partially represented by scopes, or by explicit
 operations similar to the scope entry and exit operations.
 
-### Data Flow Representation
+Data Flow Representation
+^^^^^^^^^^^^^^^^^^^^^^^^
+
 The subprogram text will be in static single assignment form by the time the
 subprogram arrives at the bridge to the LLVM IR builder.
 Merge points are actions at the heads of basic blocks whose operands
 are definition points; definition points are actions at the ends of
 basic blocks whose operands are expression trees (which may refer to
 merge points).
 
-### Rewriting Transformations
+Rewriting Transformations
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+I/O
+~~~
+
+Dynamic allocation
+~~~~~~~~~~~~~~~~~~
 
-#### I/O
-#### Dynamic allocation
-#### Array constructors
+Array constructors
+~~~~~~~~~~~~~~~~~~
+
+Derived type initialization, deallocation, and finalization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-#### Derived type initialization, deallocation, and finalization
 The machinery behind the complicated semantics of Fortran's derived types
-and `ALLOCATABLE` objects will be implemented in large part by the run time
+and ``ALLOCATABLE`` objects will be implemented in large part by the run time
 support library.
 
-#### Actual argument temporaries
-#### Array assignments, `WHERE`, and `FORALL`
+Actual argument temporaries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Array assignments, ``WHERE``\ , and ``FORALL``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Array operations have shape.
 
-`WHERE` masks have shape.
-Their effects on array operations are by means of explicit `MASK` operands that
+``WHERE`` masks have shape.
+Their effects on array operations are by means of explicit ``MASK`` operands that
 are part of array assignment operations.
 
-#### Intrinsic function and subroutine calls
+Intrinsic function and subroutine calls
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

flang/docs/Directives.rst

+Compiler directives supported by F18
+====================================
+
+
+* ``!dir$ fixed`` and ``!dir$ free`` select Fortran source forms.  Their effect
+  persists to the end of the current source file.
+* ``!dir$ ignore_tkr (tkr) var-list`` omits checks on type, kind, and/or rank.

flang/docs/Extensions.rst

-<!--===- documentation/Extensions.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
-  
--->
-
 As a general principle, this compiler will accept by default and
 without complaint many legacy features, extensions to the standard
 language, and features that have been deleted from the standard,
 so long as the recognition of those features would not cause a
 standard-conforming program to be rejected or misinterpreted.
 
 Other non-standard features, which do conflict with the current
 standard specification of the Fortran programming language, are
 accepted if enabled by command-line options.
 
 Intentional violations of the standard
 ======================================
-* Scalar `INTEGER` actual argument expressions (not variables!)
-  are converted to the kinds of scalar `INTEGER` dummy arguments
+
+
+* Scalar ``INTEGER`` actual argument expressions (not variables!)
+  are converted to the kinds of scalar ``INTEGER`` dummy arguments
   when the interface is explicit and the kinds differ.
   This conversion allows the results of the intrinsics like
-  `SIZE` that (as mentioned below) may return non-default
-  `INTEGER` results by default to be passed.  A warning is
+  ``SIZE`` that (as mentioned below) may return non-default
+  ``INTEGER`` results by default to be passed.  A warning is
   emitted when truncation is possible.
-* We are not strict on the contents of `BLOCK DATA` subprograms
+* We are not strict on the contents of ``BLOCK DATA`` subprograms
   so long as they contain no executable code, no internal subprograms,
-  and allocate no storage outside a named `COMMON` block.  (C1415)
+  and allocate no storage outside a named ``COMMON`` block.  (C1415)
 
 Extensions, deletions, and legacy features supported by default
 ===============================================================
+
+
 * Tabs in source
-* `<>` as synonym for `.NE.` and `/=`
-* `$` and `@` as legal characters in names
-* Initialization in type declaration statements using `/values/`
-* Kind specification with `*`, e.g. `REAL*4`
-* `DOUBLE COMPLEX`
+* ``<>`` as synonym for ``.NE.`` and ``/=``
+* ``$`` and ``@`` as legal characters in names
+* Initialization in type declaration statements using ``/values/``
+* Kind specification with ``*``\ , e.g. ``REAL*4``
+* ``DOUBLE COMPLEX``
 * Signed complex literal constants
-* DEC `STRUCTURE`, `RECORD`, `UNION`, and `MAP`
-* Structure field access with `.field`
-* `BYTE` as synonym for `INTEGER(KIND=1)`
-* Quad precision REAL literals with `Q`
-* `X` prefix/suffix as synonym for `Z` on hexadecimal literals
-* `B`, `O`, `Z`, and `X` accepted as suffixes as well as prefixes
+* DEC ``STRUCTURE``\ , ``RECORD``\ , ``UNION``\ , and ``MAP``
+* Structure field access with ``.field``
+* ``BYTE`` as synonym for ``INTEGER(KIND=1)``
+* Quad precision REAL literals with ``Q``
+* ``X`` prefix/suffix as synonym for ``Z`` on hexadecimal literals
+* ``B``\ , ``O``\ , ``Z``\ , and ``X`` accepted as suffixes as well as prefixes
 * Triplets allowed in array constructors
-* Old-style `PARAMETER pi=3.14` statement without parentheses
-* `%LOC`, `%VAL`, and `%REF`
+* Old-style ``PARAMETER pi=3.14`` statement without parentheses
+* ``%LOC``\ , ``%VAL``\ , and ``%REF``
 * Leading comma allowed before I/O item list
-* Empty parentheses allowed in `PROGRAM P()`
-* Missing parentheses allowed in `FUNCTION F`
-* Cray based `POINTER(p,x)` and `LOC()` intrinsic (with `%LOC()` as
+* Empty parentheses allowed in ``PROGRAM P()``
+* Missing parentheses allowed in ``FUNCTION F``
+* Cray based ``POINTER(p,x)`` and ``LOC()`` intrinsic (with ``%LOC()`` as
   an alias)
-* Arithmetic `IF`.  (Which branch should NaN take? Fall through?)
-* `ASSIGN` statement, assigned `GO TO`, and assigned format
-* `PAUSE` statement
+* Arithmetic ``IF``.  (Which branch should NaN take? Fall through?)
+* ``ASSIGN`` statement, assigned ``GO TO``\ , and assigned format
+* ``PAUSE`` statement
 * Hollerith literals and edit descriptors
-* `NAMELIST` allowed in the execution part
+* ``NAMELIST`` allowed in the execution part
 * Omitted colons on type declaration statements with attributes
-* COMPLEX constructor expression, e.g. `(x+y,z)`
-* `+` and `-` before all primary expressions, e.g. `x*-y`
-* `.NOT. .NOT.` accepted
-* `NAME=` as synonym for `FILE=`
+* COMPLEX constructor expression, e.g. ``(x+y,z)``
+* ``+`` and ``-`` before all primary expressions, e.g. ``x*-y``
+* ``.NOT. .NOT.`` accepted
+* ``NAME=`` as synonym for ``FILE=``
 * Data edit descriptors without width or other details
-* `D` lines in fixed form as comments or debug code
-* `CONVERT=` on the OPEN and INQUIRE statements
-* `DISPOSE=` on the OPEN and INQUIRE statements
+* ``D`` lines in fixed form as comments or debug code
+* ``CONVERT=`` on the OPEN and INQUIRE statements
+* ``DISPOSE=`` on the OPEN and INQUIRE statements
 * Leading semicolons are ignored before any statement that
   could have a label
-* The character `&` in column 1 in fixed form source is a variant form
+* The character ``&`` in column 1 in fixed form source is a variant form
   of continuation line.
 * Character literals as elements of an array constructor without an explicit
   type specifier need not have the same length; the longest literal determines
   the length parameter of the implicit type, not the first.
 * Outside a character literal, a comment after a continuation marker (&)
   need not begin with a comment marker (!).
-* Classic C-style /*comments*/ are skipped, so multi-language header
+* Classic C-style /\ *comments*\ / are skipped, so multi-language header
   files are easier to write and use.
-* $ and \ edit descriptors are supported in FORMAT to suppress newline
+* $ and edit descriptors are supported in FORMAT to suppress newline
   output on user prompts.
 * REAL and DOUBLE PRECISION variable and bounds in DO loops
 * Integer literals without explicit kind specifiers that are out of range
   for the default kind of INTEGER are assumed to have the least larger kind
   that can hold them, if one exists.
 * BOZ literals can be used as INTEGER values in contexts where the type is
   unambiguous: the right hand sides of assigments and initializations
   of INTEGER entities, and as actual arguments to a few intrinsic functions
   (ACHAR, BTEST, CHAR).  But they cannot be used if the type would not
-  be known (e.g., `IAND(X'1',X'2')`).
+  be known (e.g., ``IAND(X'1',X'2')``\ ).
 * BOZ literals can also be used as REAL values in some contexts where the
   type is unambiguous, such as initializations of REAL parameters.
 * EQUIVALENCE of numeric and character sequences (a ubiquitous extension)
 * Values for whole anonymous parent components in structure constructors
-  (e.g., `EXTENDEDTYPE(PARENTTYPE(1,2,3))` rather than `EXTENDEDTYPE(1,2,3)`
-   or `EXTENDEDTYPE(PARENTTYPE=PARENTTYPE(1,2,3))`).
+  (e.g., ``EXTENDEDTYPE(PARENTTYPE(1,2,3))`` rather than ``EXTENDEDTYPE(1,2,3)``
+   or ``EXTENDEDTYPE(PARENTTYPE=PARENTTYPE(1,2,3))``\ ).
 * Some intrinsic functions are specified in the standard as requiring the
   same type and kind for their arguments (viz., ATAN with two arguments,
   ATAN2, DIM, HYPOT, MAX, MIN, MOD, and MODULO);
   we allow distinct types to be used, promoting
-  the arguments as if they were operands to an intrinsic `+` operator,
+  the arguments as if they were operands to an intrinsic ``+`` operator,
   and defining the result type accordingly.
 * DOUBLE COMPLEX intrinsics DREAL, DCMPLX, DCONJG, and DIMAG.
 * INT_PTR_KIND intrinsic returns the kind of c_intptr_t.
 * Restricted specific conversion intrinsics FLOAT, SNGL, IDINT, IFIX, DREAL,
   and DCMPLX accept arguments of any kind instead of only the default kind or
   double precision kind. Their result kinds remain as specified.
 * Specific intrinsics AMAX0, AMAX1, AMIN0, AMIN1, DMAX1, DMIN1, MAX0, MAX1,
   MIN0, and MIN1 accept more argument types than specified. They are replaced by
   the related generics followed by conversions to the specified result types.
 * When a scalar CHARACTER actual argument of the same kind is known to
   have a length shorter than the associated dummy argument, it is extended
   on the right with blanks, similar to assignment.
-* When a dummy argument is `POINTER` or `ALLOCATABLE` and is `INTENT(IN)`, we
+* When a dummy argument is ``POINTER`` or ``ALLOCATABLE`` and is ``INTENT(IN)``\ , we
   relax enforcement of some requirements on actual arguments that must otherwise
   hold true for definable arguments.
-* Assignment of `LOGICAL` to `INTEGER` and vice versa (but not other types) is
+* Assignment of ``LOGICAL`` to ``INTEGER`` and vice versa (but not other types) is
   allowed.  The values are normalized.
 * An effectively empty source file (no program unit) is accepted and
   produces an empty relocatable output file.
-* A `RETURN` statement may appear in a main program.
+* A ``RETURN`` statement may appear in a main program.
 * DATA statement initialization is allowed for procedure pointers outside
   structure constructors.
 
 Extensions supported when enabled by options
 --------------------------------------------
+
+
 * C-style backslash escape sequences in quoted CHARACTER literals
   (but not Hollerith) [-fbackslash]
-* Logical abbreviations `.T.`, `.F.`, `.N.`, `.A.`, `.O.`, and `.X.`
+* Logical abbreviations ``.T.``\ , ``.F.``\ , ``.N.``\ , ``.A.``\ , ``.O.``\ , and ``.X.``
   [-flogical-abbreviations]
-* `.XOR.` as a synonym for `.NEQV.` [-fxor-operator]
-* The default `INTEGER` type is required by the standard to occupy
-  the same amount of storage as the default `REAL` type.  Default
-  `REAL` is of course 32-bit IEEE-754 floating-point today.  This legacy
+* ``.XOR.`` as a synonym for ``.NEQV.`` [-fxor-operator]
+* The default ``INTEGER`` type is required by the standard to occupy
+  the same amount of storage as the default ``REAL`` type.  Default
+  ``REAL`` is of course 32-bit IEEE-754 floating-point today.  This legacy
   rule imposes an artificially small constraint in some cases
-  where Fortran mandates that something have the default `INTEGER`
+  where Fortran mandates that something have the default ``INTEGER``
   type: specifically, the results of references to the intrinsic functions
-  `SIZE`, `LBOUND`, `UBOUND`, `SHAPE`, and the location reductions
-  `FINDLOC`, `MAXLOC`, and `MINLOC` in the absence of an explicit
-  `KIND=` actual argument.  We return `INTEGER(KIND=8)` by default in
-  these cases when the `-flarge-sizes` option is enabled.
-* Treat each specification-part like is has `IMPLICIT NONE`
+  ``SIZE``\ , ``LBOUND``\ , ``UBOUND``\ , ``SHAPE``\ , and the location reductions
+  ``FINDLOC``\ , ``MAXLOC``\ , and ``MINLOC`` in the absence of an explicit
+  ``KIND=`` actual argument.  We return ``INTEGER(KIND=8)`` by default in
+  these cases when the ``-flarge-sizes`` option is enabled.
+* Treat each specification-part like is has ``IMPLICIT NONE``
   [-fimplicit-none-type-always]
-* Ignore occurrences of `IMPLICIT NONE` and `IMPLICIT NONE(TYPE)`
+* Ignore occurrences of ``IMPLICIT NONE`` and ``IMPLICIT NONE(TYPE)``
   [-fimplicit-none-type-never]
 
 Extensions and legacy features deliberately not supported
 ---------------------------------------------------------
-* `.LG.` as synonym for `.NE.`
-* `REDIMENSION`
-* Allocatable `COMMON`
+
+
+* ``.LG.`` as synonym for ``.NE.``
+* ``REDIMENSION``
+* Allocatable ``COMMON``
 * Expressions in formats
-* `ACCEPT` as synonym for `READ *`
-* `TYPE` as synonym for `PRINT`
-* `ARRAY` as synonym for `DIMENSION`
-* `VIRTUAL` as synonym for `DIMENSION`
-* `ENCODE` and `DECODE` as synonyms for internal I/O
-* `IMPLICIT AUTOMATIC`, `IMPLICIT STATIC`
-* Default exponent of zero, e.g. `3.14159E`
+* ``ACCEPT`` as synonym for ``READ *``
+* ``TYPE`` as synonym for ``PRINT``
+* ``ARRAY`` as synonym for ``DIMENSION``
+* ``VIRTUAL`` as synonym for ``DIMENSION``
+* ``ENCODE`` and ``DECODE`` as synonyms for internal I/O
+* ``IMPLICIT AUTOMATIC``\ , ``IMPLICIT STATIC``
+* Default exponent of zero, e.g. ``3.14159E``
 * Characters in defined operators that are neither letters nor digits
-* `B` suffix on unquoted octal constants
-* `Z` prefix on unquoted hexadecimal constants (dangerous)
-* `T` and `F` as abbreviations for `.TRUE.` and `.FALSE.` in DATA (PGI/XLF)
+* ``B`` suffix on unquoted octal constants
+* ``Z`` prefix on unquoted hexadecimal constants (dangerous)
+* ``T`` and ``F`` as abbreviations for ``.TRUE.`` and ``.FALSE.`` in DATA (PGI/XLF)
 * Use of host FORMAT labels in internal subprograms (PGI-only feature)
 * ALLOCATE(TYPE(derived)::...) as variant of correct ALLOCATE(derived::...) (PGI only)
 * Defining an explicit interface for a subprogram within itself (PGI only)
 * USE association of a procedure interface within that same procedure's definition
 * NULL() as a structure constructor expression for an ALLOCATABLE component (PGI).
 * Conversion of LOGICAL to INTEGER in expressions.
 * IF (integer expression) THEN ... END IF  (PGI/Intel)
 * Comparsion of LOGICAL with ==/.EQ. rather than .EQV. (also .NEQV.) (PGI/Intel)
 * Procedure pointers in COMMON blocks (PGI/Intel)
 * Underindexing multi-dimensional arrays (e.g., A(1) rather than A(1,1)) (PGI only)
-* Legacy PGI `NCHARACTER` type and `NC` Kanji character literals
+* Legacy PGI ``NCHARACTER`` type and ``NC`` Kanji character literals
 * Using non-integer expressions for array bounds (e.g., REAL A(3.14159)) (PGI/Intel)
 * Mixing INTEGER types as operands to bit intrinsics (e.g., IAND); only two
   compilers support it, and they disagree on sign extension.
 * Module & program names that conflict with an object inside the unit (PGI only).
 * When the same name is brought into scope via USE association from
   multiple modules, the name must refer to a generic interface; PGI
   allows a name to be a procedure from one module and a generic interface
   from another.
 * Type parameter declarations must come first in a derived type definition;
-  some compilers allow them to follow `PRIVATE`, or be intermixed with the
+  some compilers allow them to follow ``PRIVATE``\ , or be intermixed with the
   component declarations.
 * Wrong argument types in calls to specific intrinsics that have different names than the
   related generics. Some accepted exceptions are listed above in the allowed extensions.
   PGI, Intel, and XLF support this in ways that are not numerically equivalent.
   PGI converts the arguments while Intel and XLF replace the specific by the related generic.
 
 Preprocessing behavior
 ======================
+
+
 * The preprocessor is always run, whatever the filename extension may be.
 * We respect Fortran comments in macro actual arguments (like GNU, Intel, NAG;
   unlike PGI and XLF) on the principle that macro calls should be treated
   like function references.  Fortran's line continuation methods also work.

flang/docs/FortranForCProgrammers.rst

-<!--===- documentation/FortranForCProgrammers.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
-
--->
-
 Fortran For C Programmers
 =========================
 
 This note is limited to essential information about Fortran so that
 a C or C++ programmer can get started more quickly with the language,
 at least as a reader, and avoid some common pitfalls when starting
 to write or modify Fortran code.
 Please see other sources to learn about Fortran's rich history,
 current applications, and modern best practices in new code.
 
 Know This At Least
 ------------------
+
+
 * There have been many implementations of Fortran, often from competing
   vendors, and the standard language has been defined by U.S. and
   international standards organizations.  The various editions of
   the standard are known as the '66, '77, '90, '95, 2003, 2008, and
   (now) 2018 standards.
 * Forward compatibility is important.  Fortran has outlasted many
   generations of computer systems hardware and software.  Standard
   compliance notwithstanding, Fortran programmers generally expect that
   code that has compiled successfully in the past will continue to
   compile and work indefinitely.  The standards sometimes designate
   features as being deprecated, obsolescent, or even deleted, but that
   can be read only as discouraging their use in new code -- they'll
   probably always work in any serious implementation.
 * Fortran has two source forms, which are typically distinguished by
-  filename suffixes.  `foo.f` is old-style "fixed-form" source, and
-  `foo.f90` is new-style "free-form" source.  All language features
+  filename suffixes.  ``foo.f`` is old-style "fixed-form" source, and
+  ``foo.f90`` is new-style "free-form" source.  All language features
   are available in both source forms.  Neither form has reserved words
   in the sense that C does.  Spaces are not required between tokens
   in fixed form, and case is not significant in either form.
 * Variable declarations are optional by default.  Variables whose
-  names begin with the letters `I` through `N` are implicitly
-  `INTEGER`, and others are implicitly `REAL`.  These implicit typing
+  names begin with the letters ``I`` through ``N`` are implicitly
+  ``INTEGER``\ , and others are implicitly ``REAL``.  These implicit typing
   rules can be changed in the source.
 * Fortran uses parentheses in both array references and function calls.
   All arrays must be declared as such; other names followed by parenthesized
   expressions are assumed to be function calls.
-* Fortran has a _lot_ of built-in "intrinsic" functions.  They are always
+* Fortran has a *lot* of built-in "intrinsic" functions.  They are always
   available without a need to declare or import them.  Their names reflect
   the implicit typing rules, so you will encounter names that have been
-  modified so that they have the right type (e.g., `AIMAG` has a leading `A`
-  so that it's `REAL` rather than `INTEGER`).
+  modified so that they have the right type (e.g., ``AIMAG`` has a leading ``A``
+  so that it's ``REAL`` rather than ``INTEGER``\ ).
 * The modern language has means for declaring types, data, and subprogram
   interfaces in compiled "modules", as well as legacy mechanisms for
   sharing data and interconnecting subprograms.
 
 A Rosetta Stone
 ---------------
+
 Fortran's language standard and other documentation uses some terminology
 in particular ways that might be unfamiliar.
 
-| Fortran | English |
-| ------- | ------- |
-| Association | Making a name refer to something else |
-| Assumed | Some attribute of an argument or interface that is not known until a call is made |
-| Companion processor | A C compiler |
-| Component | Class member |
-| Deferred | Some attribute of a variable that is not known until an allocation or assignment |
-| Derived type | C++ class |
-| Dummy argument | C++ reference argument |
-| Final procedure | C++ destructor |
-| Generic | Overloaded function, resolved by actual arguments |
-| Host procedure | The subprogram that contains a nested one |
-| Implied DO | There's a loop inside a statement |
-| Interface | Prototype |
-| Internal I/O | `sscanf` and `snprintf` |
-| Intrinsic | Built-in type or function |
-| Polymorphic | Dynamically typed |
-| Processor | Fortran compiler |
-| Rank | Number of dimensions that an array has |
-| `SAVE` attribute | Statically allocated |
-| Type-bound procedure | Kind of a C++ member function but not really |
-| Unformatted | Raw binary |
+.. list-table::
+   :header-rows: 1
+
+   * - Fortran
+     - English
+   * - Association
+     - Making a name refer to something else
+   * - Assumed
+     - Some attribute of an argument or interface that is not known until a call is made
+   * - Companion processor
+     - A C compiler
+   * - Component
+     - Class member
+   * - Deferred
+     - Some attribute of a variable that is not known until an allocation or assignment
+   * - Derived type
+     - C++ class
+   * - Dummy argument
+     - C++ reference argument
+   * - Final procedure
+     - C++ destructor
+   * - Generic
+     - Overloaded function, resolved by actual arguments
+   * - Host procedure
+     - The subprogram that contains a nested one
+   * - Implied DO
+     - There's a loop inside a statement
+   * - Interface
+     - Prototype
+   * - Internal I/O
+     - ``sscanf`` and ``snprintf``
+   * - Intrinsic
+     - Built-in type or function
+   * - Polymorphic
+     - Dynamically typed
+   * - Processor
+     - Fortran compiler
+   * - Rank
+     - Number of dimensions that an array has
+   * - ``SAVE`` attribute
+     - Statically allocated
+   * - Type-bound procedure
+     - Kind of a C++ member function but not really
+   * - Unformatted
+     - Raw binary
+
 
 Data Types
 ----------
-There are five built-in ("intrinsic") types: `INTEGER`, `REAL`, `COMPLEX`,
-`LOGICAL`, and `CHARACTER`.
+
+There are five built-in ("intrinsic") types: ``INTEGER``\ , ``REAL``\ , ``COMPLEX``\ ,
+``LOGICAL``\ , and ``CHARACTER``.
 They are parameterized with "kind" values, which should be treated as
 non-portable integer codes, although in practice today these are the
 byte sizes of the data.
-(For `COMPLEX`, the kind type parameter value is the byte size of one of the
-two `REAL` components, or half of the total size.)
-The legacy `DOUBLE PRECISION` intrinsic type is an alias for a kind of `REAL`
-that should be more precise, and bigger, than the default `REAL`.
+(For ``COMPLEX``\ , the kind type parameter value is the byte size of one of the
+two ``REAL`` components, or half of the total size.)
+The legacy ``DOUBLE PRECISION`` intrinsic type is an alias for a kind of ``REAL``
+that should be more precise, and bigger, than the default ``REAL``.
 
-`COMPLEX` is a simple structure that comprises two `REAL` components.
+``COMPLEX`` is a simple structure that comprises two ``REAL`` components.
 
-`CHARACTER` data also have length, which may or may not be known at compilation
+``CHARACTER`` data also have length, which may or may not be known at compilation
 time.
-`CHARACTER` variables are fixed-length strings and they get padded out
+``CHARACTER`` variables are fixed-length strings and they get padded out
 with space characters when not completely assigned.
 
 User-defined ("derived") data types can be synthesized from the intrinsic
-types and from previously-defined user types, much like a C `struct`.
+types and from previously-defined user types, much like a C ``struct``.
 Derived types can be parameterized with integer values that either have
 to be constant at compilation time ("kind" parameters) or deferred to
 execution ("len" parameters).
 
 Derived types can inherit ("extend") from at most one other derived type.
-They can have user-defined destructors (`FINAL` procedures).
+They can have user-defined destructors (\ ``FINAL`` procedures).
 They can specify default initial values for their components.
 With some work, one can also specify a general constructor function,
 since Fortran allows a generic interface to have the same name as that
 of a derived type.
 
 Last, there are "typeless" binary constants that can be used in a few
 situations, like static data initialization or immediate conversion,
 where type is not necessary.
 
 Arrays
 ------
+
 Arrays are not types in Fortran.
 Being an array is a property of an object or function, not of a type.
 Unlike C, one cannot have an array of arrays or an array of pointers,
 although can can have an array of a derived type that has arrays or
 pointers as components.
 Arrays are multidimensional, and the number of dimensions is called
-the _rank_ of the array.
+the *rank* of the array.
 In storage, arrays are stored such that the last subscript has the
 largest stride in memory, e.g. A(1,1) is followed by A(2,1), not A(1,2).
 And yes, the default lower bound on each dimension is 1, not 0.
 
 Expressions can manipulate arrays as multidimensional values, and
 the compiler will create the necessary loops.
 
 Allocatables
 ------------
-Modern Fortran programs use `ALLOCATABLE` data extensively.
+
+Modern Fortran programs use ``ALLOCATABLE`` data extensively.
 Such variables and derived type components are allocated dynamically.
 They are automatically deallocated when they go out of scope, much
-like C++'s `std::vector<>` class template instances are.
-The array bounds, derived type `LEN` parameters, and even the
+like C++'s ``std::vector<>`` class template instances are.
+The array bounds, derived type ``LEN`` parameters, and even the
 type of an allocatable can all be deferred to run time.
 (If you really want to learn all about modern Fortran, I suggest
-that you study everything that can be done with `ALLOCATABLE` data,
+that you study everything that can be done with ``ALLOCATABLE`` data,
 and follow up all the references that are made in the documentation
-from the description of `ALLOCATABLE` to other topics; it's a feature
+from the description of ``ALLOCATABLE`` to other topics; it's a feature
 that interacts with much of the rest of the language.)
 
 I/O
 ---
+
 Fortran's input/output features are built into the syntax of the language,
 rather than being defined by library interfaces as in C and C++.
 There are means for raw binary I/O and for "formatted" transfers to
 character representations.
 There are means for random-access I/O using fixed-size records as well as for
 sequential I/O.
-One can scan data from or format data into `CHARACTER` variables via
+One can scan data from or format data into ``CHARACTER`` variables via
 "internal" formatted I/O.
 I/O from and to files uses a scheme of integer "unit" numbers that is
 similar to the open file descriptors of UNIX; i.e., one opens a file
 and assigns it a unit number, then uses that unit number in subsequent
-`READ` and `WRITE` statements.
+``READ`` and ``WRITE`` statements.
 
 Formatted I/O relies on format specifications to map values to fields of
-characters, similar to the format strings used with C's `printf` family
+characters, similar to the format strings used with C's ``printf`` family
 of standard library functions.
-These format specifications can appear in `FORMAT` statements and
+These format specifications can appear in ``FORMAT`` statements and
 be referenced by their labels, in character literals directly in I/O
 statements, or in character variables.
 
 One can also use compiler-generated formatting in "list-directed" I/O,
 in which the compiler derives reasonable default formats based on
 data types.
 
 Subprograms
 -----------
-Fortran has both `FUNCTION` and `SUBROUTINE` subprograms.
+
+Fortran has both ``FUNCTION`` and ``SUBROUTINE`` subprograms.
 They share the same name space, but functions cannot be called as
 subroutines or vice versa.
-Subroutines are called with the `CALL` statement, while functions are
+Subroutines are called with the ``CALL`` statement, while functions are
 invoked with function references in expressions.
 
 There is one level of subprogram nesting.
 A function, subroutine, or main program can have functions and subroutines
 nested within it, but these "internal" procedures cannot themselves have
 their own internal procedures.
 As is the case with C++ lambda expressions, internal procedures can
 reference names from their host subprograms.
 
 Modules
 -------
+
 Modern Fortran has good support for separate compilation and namespace
 management.
 The *module* is the basic unit of compilation, although independent
 subprograms still exist, of course, as well as the main program.
 Modules define types, constants, interfaces, and nested
 subprograms.
 
 Objects from a module are made available for use in other compilation
-units via the `USE` statement, which has options for limiting the objects
+units via the ``USE`` statement, which has options for limiting the objects
 that are made available as well as for renaming them.
 All references to objects in modules are done with direct names or
 aliases that have been added to the local scope, as Fortran has no means
 of qualifying references with module names.
 
 Arguments
 ---------
+
 Functions and subroutines have "dummy" arguments that are dynamically
 associated with actual arguments during calls.
 Essentially, all argument passing in Fortran is by reference, not value.
 One may restrict access to argument data by declaring that dummy
-arguments have `INTENT(IN)`, but that corresponds to the use of
-a `const` reference in C++ and does not imply that the data are
-copied; use `VALUE` for that.
+arguments have ``INTENT(IN)``\ , but that corresponds to the use of
+a ``const`` reference in C++ and does not imply that the data are
+copied; use ``VALUE`` for that.
 
 When it is not possible to pass a reference to an object, or a sparse
 regular array section of an object, as an actual argument, Fortran
 compilers must allocate temporary space to hold the actual argument
 across the call.
 This is always guaranteed to happen when an actual argument is enclosed
 in parentheses.
 
 The compiler is free to assume that any aliasing between dummy arguments
 and other data is safe.
 In other words, if some object can be written to under one name, it's
 never going to be read or written using some other name in that same
 scope.
-```
+
+.. code-block::
+
      SUBROUTINE FOO(X,Y,Z)
      X = 3.14159
      Y = 2.1828
      Z = 2 * X ! CAN BE FOLDED AT COMPILE TIME
      END
-```
+
 This is the opposite of the assumptions under which a C or C++ compiler must
 labor when trying to optimize code with pointers.
 
 Overloading
 -----------
+
 Fortran supports a form of overloading via its interface feature.
 By default, an interface is a means for specifying prototypes for a
 set of subroutines and functions.
 But when an interface is named, that name becomes a *generic* name
 for its specific subprograms, and calls via the generic name are
 mapped at compile time to one of the specific subprograms based
 on the types, kinds, and ranks of the actual arguments.
 A similar feature can be used for generic type-bound procedures.
 
 This feature can be used to overload the built-in operators and some
 I/O statements, too.
 
 Polymorphism
 ------------
+
 Fortran code can be written to accept data of some derived type or
-any extension thereof using `CLASS`, deferring the actual type to
-execution, rather than the usual `TYPE` syntax.
-This is somewhat similar to the use of `virtual` functions in c++.
+any extension thereof using ``CLASS``\ , deferring the actual type to
+execution, rather than the usual ``TYPE`` syntax.
+This is somewhat similar to the use of ``virtual`` functions in c++.
 
-Fortran's `SELECT TYPE` construct is used to distinguish between
+Fortran's ``SELECT TYPE`` construct is used to distinguish between
 possible specific types dynamically, when necessary.  It's a
-little like C++17's `std::visit()` on a discriminated union.
+little like C++17's ``std::visit()`` on a discriminated union.
 
 Pointers
 --------
+
 Pointers are objects in Fortran, not data types.
 Pointers can point to data, arrays, and subprograms.
-A pointer can only point to data that has the `TARGET` attribute.
-Outside of the pointer assignment statement (`P=>X`) and some intrinsic
+A pointer can only point to data that has the ``TARGET`` attribute.
+Outside of the pointer assignment statement (\ ``P=>X``\ ) and some intrinsic
 functions and cases with pointer dummy arguments, pointers are implicitly
 dereferenced, and the use of their name is a reference to the data to which
 they point instead.
 
-Unlike C, a pointer cannot point to a pointer *per se*, nor can they be
+Unlike C, a pointer cannot point to a pointer *per se*\ , nor can they be
 used to implement a level of indirection to the management structure of
 an allocatable.
 If you assign to a Fortran pointer to make it point at another pointer,
 you are making the pointer point to the data (if any) to which the other
 pointer points.
 Similarly, if you assign to a Fortran pointer to make it point to an allocatable,
 you are making the pointer point to the current content of the allocatable,
 not to the metadata that manages the allocatable.
 
 Unlike allocatables, pointers do not deallocate their data when they go
 out of scope.
 
 A legacy feature, "Cray pointers", implements dynamic base addressing of
 one variable using an address stored in another.
 
 Preprocessing
 -------------
+
 There is no standard preprocessing feature, but every real Fortran implementation
 has some support for passing Fortran source code through a variant of
 the standard C source preprocessor.
 Since Fortran is very different from C at the lexical level (e.g., line
 continuations, Hollerith literals, no reserved words, fixed form), using
 a stock modern C preprocessor on Fortran source can be difficult.
 Preprocessing behavior varies across implementations and one should not depend on
 much portability.
 Preprocessing is typically requested by the use of a capitalized filename
 suffix (e.g., "foo.F90") or a compiler command line option.
 (Since the F18 compiler always runs its built-in preprocessing stage,
 no special option or filename suffix is required.)
 
 "Object Oriented" Programming
 -----------------------------
+
 Fortran doesn't have member functions (or subroutines) in the sense
 that C++ does, in which a function has immediate access to the members
 of a specific instance of a derived type.
-But Fortran does have an analog to C++'s `this` via *type-bound
+But Fortran does have an analog to C++'s ``this`` via *type-bound
 procedures*.
 This is a means of binding a particular subprogram name to a derived
 type, possibly with aliasing, in such a way that the subprogram can
-be called as if it were a component of the type (e.g., `X%F(Y)`)
-and receive the object to the left of the `%` as an additional actual argument,
-exactly as if the call had been written `F(X,Y)`.
+be called as if it were a component of the type (e.g., ``X%F(Y)``\ )
+and receive the object to the left of the ``%`` as an additional actual argument,
+exactly as if the call had been written ``F(X,Y)``.
 The object is passed as the first argument by default, but that can be
 changed; indeed, the same specific subprogram can be used for multiple
 type-bound procedures by choosing different dummy arguments to serve as
 the passed object.
-The equivalent of a `static` member function is also available by saying
-that no argument is to be associated with the object via `NOPASS`.
+The equivalent of a ``static`` member function is also available by saying
+that no argument is to be associated with the object via ``NOPASS``.
 
 There's a lot more that can be said about type-bound procedures (e.g., how they
 support overloading) but this should be enough to get you started with
 the most common usage.
 
 Pitfalls
 --------
-Variable initializers, e.g. `INTEGER :: J=123`, are _static_ initializers!
+
+Variable initializers, e.g. ``INTEGER :: J=123``\ , are *static* initializers!
 They imply that the variable is stored in static storage, not on the stack,
 and the initialized value lasts only until the variable is assigned.
 One must use an assignment statement to implement a dynamic initializer
 that will apply to every fresh instance of the variable.
-Be especially careful when using initializers in the newish `BLOCK` construct,
+Be especially careful when using initializers in the newish ``BLOCK`` construct,
 which perpetuates the interpretation as static data.
 (Derived type component initializers, however, do work as expected.)
 
 If you see an assignment to an array that's never been declared as such,
-it's probably a definition of a *statement function*, which is like
-a parameterized macro definition, e.g. `A(X)=SQRT(X)**3`.
+it's probably a definition of a *statement function*\ , which is like
+a parameterized macro definition, e.g. ``A(X)=SQRT(X)**3``.
 In the original Fortran language, this was the only means for user
 function definitions.
 Today, of course, one should use an external or internal function instead.
 
 Fortran expressions don't bind exactly like C's do.
-Watch out for exponentiation with `**`, which of course C lacks; it
-binds more tightly than negation does (e.g., `-2**2` is -4),
+Watch out for exponentiation with ``**``\ , which of course C lacks; it
+binds more tightly than negation does (e.g., ``-2**2`` is -4),
 and it binds to the right, unlike what any other Fortran and most
-C operators do; e.g., `2**2**3` is 256, not 64.
+C operators do; e.g., ``2**2**3`` is 256, not 64.
 Logical values must be compared with special logical equivalence
-relations (`.EQV.` and `.NEQV.`) rather than the usual equality
+relations (\ ``.EQV.`` and ``.NEQV.``\ ) rather than the usual equality
 operators.
 
 A Fortran compiler is allowed to short-circuit expression evaluation,
 but not required to do so.
-If one needs to protect a use of an `OPTIONAL` argument or possibly
-disassociated pointer, use an `IF` statement, not a logical `.AND.`
+If one needs to protect a use of an ``OPTIONAL`` argument or possibly
+disassociated pointer, use an ``IF`` statement, not a logical ``.AND.``
 operation.
 In fact, Fortran can remove function calls from expressions if their
 values are not required to determine the value of the expression's
-result; e.g., if there is a `PRINT` statement in function `F`, it
-may or may not be executed by the assignment statement `X=0*F()`.
+result; e.g., if there is a ``PRINT`` statement in function ``F``\ , it
+may or may not be executed by the assignment statement ``X=0*F()``.
 (Well, it probably will be, in practice, but compilers always reserve
 the right to optimize better.)
 
-Unless they have an explicit suffix (`1.0_8`, `2.0_8`) or a `D`
-exponent (`3.0D0`), real literal constants in Fortran have the
-default `REAL` type -- *not* `double` as in the case in C and C++.
+Unless they have an explicit suffix (\ ``1.0_8``\ , ``2.0_8``\ ) or a ``D``
+exponent (\ ``3.0D0``\ ), real literal constants in Fortran have the
+default ``REAL`` type -- *not* ``double`` as in the case in C and C++.
 If you're not careful, you can lose precision at compilation time
 from your constant values and never know it.

flang/docs/FortranIR.rst

-<!--===- documentation/FortranIR.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
-  
--->
-
-# Design: Fortran IR
-
-## Introduction
+Design: Fortran IR
+==================
+Introduction
+------------
 
 After semantic analysis is complete and it has been determined that the compiler has a legal Fortran program as input, the parse tree will be lowered to an intermediate representation for the purposes of high-level analysis and optimization.  In this document, that intermediate representation will be called Fortran IR or FIR.  The pass that converts from the parse tree and other data structures of the front-end to FIR will be called the "Burnside bridge".
 
 FIR will be an explicit, operational, and strongly-typed representation, which shall encapsulate control-flow as graphs.
 
-## Requirements
+Requirements
+------------
 
-### White Paper: [Control Flow Graph](ControlFlowGraph.md)<sup>1</sup>
+White Paper: `Control Flow Graph <ControlFlowGraph.rst>`_\ :raw-html-m2r:`<sup>1</sup>`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This is a list of requirements extracted from that document, which will be referred to as CFG-WP.
 
-1. Control flow to be explicit (e.g. ERR= specifiers)
-2. May need critical edge splitting
-3. Lowering of procedures with ENTRY statements is specified
-4. Procedures will have a start node
-5. Non-executable statements will be ignored
-6. Labeled DO loop execution with GOTO specified
-7. Operations and actions (statements) are defined
-8. The last statement in a basic block can represent a change in control flow
-9. Scope transitions to be made explicit (special actions)
-10. The IR will be in SSA form
 
-### Explicit Control Flow
+#. Control flow to be explicit (e.g. ERR= specifiers)
+#. May need critical edge splitting
+#. Lowering of procedures with ENTRY statements is specified
+#. Procedures will have a start node
+#. Non-executable statements will be ignored
+#. Labeled DO loop execution with GOTO specified
+#. Operations and actions (statements) are defined
+#. The last statement in a basic block can represent a change in control flow
+#. Scope transitions to be made explicit (special actions)
+#. The IR will be in SSA form
+
+Explicit Control Flow
+^^^^^^^^^^^^^^^^^^^^^
 
 In Fortran, there are a number of statements that result in control flow to statements other than the one immediately subsequent. These can be sorted these into two categories: structured and unstructured.
 
-#### Structured Control Flow
+Structured Control Flow
+~~~~~~~~~~~~~~~~~~~~~~~
 
-Fortran has executable constructs that imply three basic control flow forms.  The first form is a structured loop (DO construct)<sup>2</sup>. The second form is a structured cascade of conditional branches (IF construct, IF statement,<sup>3</sup> WHERE construct).  The third form is a structured multiway branch (SELECT CASE, SELECT RANK, and SELECT TYPE constructs).  The FORALL construct, while it implies a semantic model of interleaved iterations, can be modeled as a special single-entry single-exit region in FIR perhaps with backstage marker statements.<sup>4</sup>
+Fortran has executable constructs that imply three basic control flow forms.  The first form is a structured loop (DO construct)\ :raw-html-m2r:`<sup>2</sup>`. The second form is a structured cascade of conditional branches (IF construct, IF statement,\ :raw-html-m2r:`<sup>3</sup>` WHERE construct).  The third form is a structured multiway branch (SELECT CASE, SELECT RANK, and SELECT TYPE constructs).  The FORALL construct, while it implies a semantic model of interleaved iterations, can be modeled as a special single-entry single-exit region in FIR perhaps with backstage marker statements.\ :raw-html-m2r:`<sup>4</sup>`
 
-The CYCLE and EXIT statements interact with the above structured executable constructs by providing structured transfers of control.<sup>5</sup> CYCLE (possibly named) is only valid in DO constructs and creates an alternate backedge in the enclosing loop.  EXIT transfers control out of the enclosing (possibly named) construct, which need not be a DO construct.
+The CYCLE and EXIT statements interact with the above structured executable constructs by providing structured transfers of control.\ :raw-html-m2r:`<sup>5</sup>` CYCLE (possibly named) is only valid in DO constructs and creates an alternate backedge in the enclosing loop.  EXIT transfers control out of the enclosing (possibly named) construct, which need not be a DO construct.
 
-#### Unstructured Control Flow
+Unstructured Control Flow
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Fortran also has mechanisms of transferring control between a statement and another statement with a corresponding label.  The origin of these edges can be GOTO statements, computed GOTO statements, assigned GOTO statements, arithmetic IF statements, alt-return specifications, and END/EOR/ERR I/O specifiers.  These statements are "unstructured" in the sense that the target of the control-flow has fewer constraints and the labelled statements must be linked to their origins.
 
 Another category of unstructured control flow are statements that terminate execution.  These include RETURN, FAIL IMAGE, STOP and ERROR STOP statements.  The PAUSE statement can be modeled as a call to the runtime.
 
-### Operations
+Operations
+^^^^^^^^^^
 
 The compiler's to be determined optimization passes will inform us as to the exact composition of FIR at the operations level.  This details here will necessarily change, so please read them with a grain of salt.
 
-The plan (see CFG-WP) is that statements (actions) will be a veneer model of Fortran syntactical executable constructs. Fortran statements will correspond one to one with actions. Actions will be composed of and own objects of Fortran::evaluate::GenericExprWrapper. Values of type GenericExprWrapper will have Fortran types. This implies that actions will not be in an explicit data flow representation and have optional type information.<sup>6</sup> Initially, values will bind to symbols in a context and have an implicit use-def relation. An action statement may entail a "big step" operation with many side-effects. No semantics has been defined at this time.  Actions may reference other non-executable statements from the parse tree in some to be determined manner.
+The plan (see CFG-WP) is that statements (actions) will be a veneer model of Fortran syntactical executable constructs. Fortran statements will correspond one to one with actions. Actions will be composed of and own objects of Fortran::evaluate::GenericExprWrapper. Values of type GenericExprWrapper will have Fortran types. This implies that actions will not be in an explicit data flow representation and have optional type information.\ :raw-html-m2r:`<sup>6</sup>` Initially, values will bind to symbols in a context and have an implicit use-def relation. An action statement may entail a "big step" operation with many side-effects. No semantics has been defined at this time.  Actions may reference other non-executable statements from the parse tree in some to be determined manner.
 
 From the CFG-WP, it is stated that the FIR will ultimately be in an SSA form.  It is clear that a later pass can rewrite the values/expressions and construct a factored use-def version of the expressions. This may/should also involve expanding "big step" actions to a series of instructions and introducing typing information for all instructions. Again, the exact "lowered representation" will be informed from the requirements of the optimization passes and is presently to be determined.
 
-### Other
+Other
+^^^^^
 
 Overall project goals include becoming part of the LLVM ecosystem as well as using LLVM as a backend.
 
 Critical edge splitting can be constructed on-demand and as needed.
 
 Lowering of procedures with ENTRY statements is specified.  The plan is to lower procedures with ENTRY statements as specified in the CFG-WP.
 
 In FIR, a procedure will have a method that returns the start node.
 
 When lowering to FIR statements, non-executable statements will be discarded.
 
 Labeled DO loops are converted to non-labeled DO loops in the semantics processing.
 
-The last statement in a basic block can represent a change in control flow. LLVM-IR and SIL<sup>7</sup> require that basic blocks end with a terminator. FIR will also have terminators.
+The last statement in a basic block can represent a change in control flow. LLVM-IR and SIL\ :raw-html-m2r:`<sup>7</sup>` require that basic blocks end with a terminator. FIR will also have terminators.
 
 The CFG-WP states that scope transitions are to be made explicit. We will cover this more below.
 
 LLVM does not require the FIR to be in SSA form. LLVM's mem-to-reg pass does the conversion into SSA form. FIR can support SSA for optimization passes on-demand with its own mem-to-reg and reg-to-mem type passes.
 
 Data objects with process lifetime will be captured indirectly by a reference to the (global) symbol table.
 
-## Exploration
+Exploration
+-----------
 
-### Construction
+Construction
+^^^^^^^^^^^^
 
-Our aim to construct a CFG where all control-flow is explicitly modeled by relations. A basic block will be a sequence of statements for which if the first statement is executed then all other statements in the basic block will also be executed, in order.<sup>8</sup>  A CFG is therefore this set of basic blocks and the control-flow relations between those blocks.
+Our aim to construct a CFG where all control-flow is explicitly modeled by relations. A basic block will be a sequence of statements for which if the first statement is executed then all other statements in the basic block will also be executed, in order.\ :raw-html-m2r:`<sup>8</sup>`  A CFG is therefore this set of basic blocks and the control-flow relations between those blocks.
 
-#### Alternative: direct approach
+Alternative: direct approach
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The CFG can be directly constructed by traversing the parse tree, threading contextual state, and building basic blocks along with control-flow relationships.
 
+
 * Pro: Straightforward implementation when control-flow is well-structured as the contextual state parallels the syntax of the language closely.
 * Con: The contextual state needed can become large and difficult to manage in the presence of unstructured control-flow. For example, not every labeled statement in Fortran may be a control-flow destination.
 * Con: The contextual state must deal with the recursive nature of the parse tree. 
 * Con: Complexity. Since structured constructs cohabitate with unstructured constructs, the context needs to carry information about all combinations until the basic blocks and relations are fully elaborated.
 
-#### Alternative: linearized approach (decomposing the problem)
+Alternative: linearized approach (decomposing the problem)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Instead of constructing the CFG directly from a parse tree traversal, an intermediate form can be constructed to explicitly capture the executable statements, which ones give rise to control-flow graph edge sources, and which are control-flow graph edge targets.  This linearized form flattens the tree structure of the parse tree. The linearized form does not require recursive visitation of nested constructs and can be used to directly identify the entries and exits of basic blocks.
 
 While each control-flow source statement is explicit in the traversal, it can be the case that not all of the targets have been traversed yet (references to forward basic blocks), and those basic blocks will not yet have been created.  These relations can be captured at the time the source is traversed, added to a to do list, and then completed when all the basic blocks for the procedure have been created. Specifically, at the point when we create a terminator all information is known to create the FIR terminator, however all basic blocks that may be referenced may not have been created. Those are resolved in one final "clean up" pass over a list of closures.
 
+
 * Con: An extra representation must be defined and constructed.  
 * Pro: This representation reifies all the information that is referred to as contextual state in the direct approach.
 * Pro: Constructing the linearized form can be done with a simple traversal of the parse tree.
 * Pro: Once composed the linearized form can be traversed and a CFG directly constructed.  This greatly reduces bookkeeping of contextual state.
 
-### Details
+Details
+^^^^^^^
 
-#### Grappling with Control Flow
+Grappling with Control Flow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Above, various Fortran executable constructs were discussed with respect to how they (may) give rise to control flow.  These Fortran statements are mapped to a small number of FIR statements: ReturnStmt, BranchStmt, SwitchStmt, IndirectBrStmt, and UnreachableStmt.
 
-_ReturnStmt_: execution leaves the enclosing Procedure. A ReturnStmt can return an optional value. This would appear for RETURN statements or at END SUBROUTINE.
+*ReturnStmt*\ : execution leaves the enclosing Procedure. A ReturnStmt can return an optional value. This would appear for RETURN statements or at END SUBROUTINE.
 
-_BranchStmt_: execution of the current basic block ends. If the branch is unconditional then control transfers to exactly one successor basic block. If the branch is conditional then control transfers to exactly one of two successor blocks depending on the true/false value of the condition. All successors must be in the current Procedure. Unconditional branches would appear for GOTO statements. Conditional branches would appear for IF constructs, IF statements, etc.
+*BranchStmt*\ : execution of the current basic block ends. If the branch is unconditional then control transfers to exactly one successor basic block. If the branch is conditional then control transfers to exactly one of two successor blocks depending on the true/false value of the condition. All successors must be in the current Procedure. Unconditional branches would appear for GOTO statements. Conditional branches would appear for IF constructs, IF statements, etc.
 
-_SwitchStmt_: Exactly one of multiple successors is selected based on the control expression. Successors are pairs of case expressions and basic blocks.  If the control expression compares to the case expression and returns true, then that control transfers to that block. There may be one special block, the default block, that is selected if none of the case expressions compares true. This would appear for SELECT CASE, SELECT TYPE, SELECT RANK, COMPUTED GOTO, WRITE with exceptional condition label specificers, alternate return specifiers, etc.
+*SwitchStmt*\ : Exactly one of multiple successors is selected based on the control expression. Successors are pairs of case expressions and basic blocks.  If the control expression compares to the case expression and returns true, then that control transfers to that block. There may be one special block, the default block, that is selected if none of the case expressions compares true. This would appear for SELECT CASE, SELECT TYPE, SELECT RANK, COMPUTED GOTO, WRITE with exceptional condition label specificers, alternate return specifiers, etc.
 
-_IndirectBrStmt_: A variable is loaded with the address of a basic block in the containing Procedure. Control is transferred to the contents of this variable. An IndirectBrStmt also requires a complete list of potential basic blocks that may be loaded into the variable. This would appear for ASSIGNED GOTO.
+*IndirectBrStmt*\ : A variable is loaded with the address of a basic block in the containing Procedure. Control is transferred to the contents of this variable. An IndirectBrStmt also requires a complete list of potential basic blocks that may be loaded into the variable. This would appear for ASSIGNED GOTO.
 
 Supporting ASSIGNED GOTO offers a little extra challenge as the ASSIGN GOTO statement's list of target labels is optional.  If that list is not present, then the procedure must be analyzed to find ASSIGN statements. The implementation proactively looks for ASSIGN statements and keeps a dictionary mapping an assigned Symbol to its set of targets. When constructing the CFG, ASSIGNED GOTOs can be processed as to potential targets either from the list provided in the ASSIGNED GOTO or from the analysis pass.
 
-Alternatively, ASSIGNED GOTO could be implemented as a _SwitchStmt_ that tests on a compiler-defined value and fully elaborates all potential target basic blocks.
+Alternatively, ASSIGNED GOTO could be implemented as a *SwitchStmt* that tests on a compiler-defined value and fully elaborates all potential target basic blocks.
 
-_UnreachableStmt_: If control reaches an unreachable statement, then an error has occurred. Calls to library routines that do not return should be followed by an UnreachableStmt.  An example would be the STOP statement.
+*UnreachableStmt*\ : If control reaches an unreachable statement, then an error has occurred. Calls to library routines that do not return should be followed by an UnreachableStmt.  An example would be the STOP statement.
 
-#### Scope
+Scope
+~~~~~
 
 In the CFG-WP, scopes are meant to be captured by a pair of backstage statements for entering and exiting a particular scope. In structured code, these pairs would not be problematic; however, control flow in Fortran is ad hoc, particularly in legacy Fortran. In short, Fortran does not have a clean sense of structure with respect to scope.
 
 To separate concerns, FIR will construct the ad hoc CFG and impose bounding boxes over regions of that graph to demarcate and superimpose scope structures on that CFG. Any GOTO-like statements that are side-entries and side-exits to the region will be explicit.
 
 Once the basic blocks are constructed, CFG edges defined, and the CFG is simplified, a simple pass that analyzes the region bounding boxes can decorate the basic blocks with the SCOPE ENTER and SCOPE EXIT statements and flatten/remove the region structure. It will then be the burden of any optimization passes to guarantee legal orderings of SCOPE ENTER and SCOPE EXIT pairs.
 
+
 * Pro: Separation of concerns allows for simpler, easier to maintain code
 * Pro: Simplification of the CFG can be done without worrying about SCOPE markers
 * Pro: Allows a precise superimposing of all Fortran constructs with scoping considerations over an otherwise ad hoc CFG.
 * Con: Adds "an extra layer" to FIR as compared to SIL. However, that can be mitigated/made inconsequential by a pass that flattens the Region tree and inserts the backstage SCOPE marker statements.
 
-#### Structure
+Structure
+~~~~~~~~~
 
-_Program_: A program instance is the top-level object that contains the representation of all the code being compiled, the compilation unit. It contains a list of procedures and a reference to the global symbol table.
+*Program*\ : A program instance is the top-level object that contains the representation of all the code being compiled, the compilation unit. It contains a list of procedures and a reference to the global symbol table.
 
-_Procedure_: This is a named Fortran procedure (subroutine or function). It contains a (hierarchical) list of regions. It also owns the master list of all basic blocks for the procedure.
+*Procedure*\ : This is a named Fortran procedure (subroutine or function). It contains a (hierarchical) list of regions. It also owns the master list of all basic blocks for the procedure.
 
-_Region_: A region is owned by a procedure or by another region. A region owns a reference to a scope in the symbol table tree. The list of delineated basic blocks can also be requested from a region.
+*Region*\ : A region is owned by a procedure or by another region. A region owns a reference to a scope in the symbol table tree. The list of delineated basic blocks can also be requested from a region.
 
-_Basic block_: A basic block is owned by a procedure. A basic block owns a list of statements. The last statement in the list must be a terminator, and no other statement in the list can be a terminator. A basic block owns a list of its predecessors, which are also basic blocks. (Precisely, it is this level of FIR that is the CFG.)
+*Basic block*\ : A basic block is owned by a procedure. A basic block owns a list of statements. The last statement in the list must be a terminator, and no other statement in the list can be a terminator. A basic block owns a list of its predecessors, which are also basic blocks. (Precisely, it is this level of FIR that is the CFG.)
 
-_Statement_: An executable Fortran construct that owns/refers to expressions, symbols, scopes, etc. produced by the front-end.
+*Statement*\ : An executable Fortran construct that owns/refers to expressions, symbols, scopes, etc. produced by the front-end.
 
-_Terminator_: A statement that orchestrates control-flow. Terminator statements may reference other basic blocks and can be accessed by their parent basic block to discover successor blocks, if any.
+*Terminator*\ : A statement that orchestrates control-flow. Terminator statements may reference other basic blocks and can be accessed by their parent basic block to discover successor blocks, if any.
 
-#### Support
+Support
+~~~~~~~
 
 Since there is some state that needs to be maintained and forwarded as the FIR is constructed, a FIRBuilder can be used for convenience.  The FIRBuilder constructs statements and updates the CFG accordingly.
 
 To support visualization, there is a support class to dump the FIR to a dotty graph.
 
-### Data Structures
+Data Structures
+^^^^^^^^^^^^^^^
 
 FIR is intentionally similar to SIL from the statement level up to the level of a program.
 
-#### Alternative: LLVM
+Alternative: LLVM
+~~~~~~~~~~~~~~~~~
 
 Program, procedure, region, and basic block all leverage code from LLVM, in much the same way as SIL. These data structures have significant investment and engineering behind their use in compilers, and it makes sense to leverage that work.
 
+
 * Pro: Uses LLVM data structures, pervasive in compiler projects such as LLVM, SIL, etc.
 * Pro: Get used to seeing and using LLVM, as f18 aims to be an LLVM project
 * Con: Uses LLVM data structures, which the project has been avoiding
 
-#### Alternative: C++ Standard Template Library
+Alternative: C++ Standard Template Library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Clearly, the STL can be used to maintain lists, etc.
 
+
 * Pro: Keeps the number of libraries minimal
 * Con: The STL is general purpose and not necessarily tuned to support compiler construction
 
-#### Alternative: Boost, Library XYZ, etc.
+Alternative: Boost, Library XYZ, etc.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 
 * Con: Don't see a strong motivation at present for adding another library.
 
 Statements are a bit of a transition point. Instead of the LLVM-IR approach of strictly using subtype polymorphism (for hash consing, etc.), FIR statements are a hybrid between ad hoc/subtype polymorphism and parametric polymorphism. This gives us a middle ground of genericity through superclassing and the strong and exact type-safety of algebraic data types &mdash; effectively providing type casing and type classing.
 
 The operations (expressions) owned/referenced by a statement, variable references, etc. will be data structures from the Fortran::evaluate, Fortran::semantics, etc. namespaces.
 
 
+.. raw:: html
 
    <hr>
 
-<sup>1</sup> CFG paper. https://bit.ly/2q9IRaQ
 
-<sup>2</sup> All labeled DO sequences will have been translated to DO constructs by semantic analysis.
 
-<sup>3</sup> IF statements are handled like IF constructs with no ELSE alternatives.
+:raw-html-m2r:`<sup>1</sup>` CFG paper. https://bit.ly/2q9IRaQ
+
+:raw-html-m2r:`<sup>2</sup>` All labeled DO sequences will have been translated to DO constructs by semantic analysis.
+
+:raw-html-m2r:`<sup>3</sup>` IF statements are handled like IF constructs with no ELSE alternatives.
 
-<sup>4</sup> In a subsequent discussion, we may want to lower FORALL constructs to semantically distinct loops or even another canonical representation.
+:raw-html-m2r:`<sup>4</sup>` In a subsequent discussion, we may want to lower FORALL constructs to semantically distinct loops or even another canonical representation.
 
-<sup>5</sup> These statements are only valid in structured constructs and the branches are well-defined by that executable construct.
+:raw-html-m2r:`<sup>5</sup>` These statements are only valid in structured constructs and the branches are well-defined by that executable construct.
 
-<sup>6</sup> Unlike SIL and LLVM-IR.
+:raw-html-m2r:`<sup>6</sup>` Unlike SIL and LLVM-IR.
 
-<sup>7</sup> SIL is the Swift (high-level) intermediate language. https://bit.ly/2RHW0DQ
+:raw-html-m2r:`<sup>7</sup>` SIL is the Swift (high-level) intermediate language. https://bit.ly/2RHW0DQ
 
-<sup>8</sup> Single-threaded semantics.
+:raw-html-m2r:`<sup>8</sup>` Single-threaded semantics.

flang/docs/IORuntimeInternals.rst

+Fortran I/O Runtime Library Internal Design
+===========================================
+
+This note is meant to be an overview of the design of the *implementation*
+of the f18 Fortran compiler's runtime support library for I/O statements.
+
+The *interface* to the I/O runtime support library is defined in the
+C++ header file ``runtime/io-api.h``.
+This interface was designed to minimize the amount of complexity exposed
+to its clients, which are of course the sequences of calls generated by
+the compiler to implement each I/O statement.
+By keeping this interface as simple as possible, we hope that we have
+lowered the risk of future incompatible changes that would necessitate
+recompilation of Fortran codes in order to link with later versions of
+the runtime library.
+As one will see in ``io-api.h``\ , the interface is also directly callable
+from C and C++ programs.
+
+The I/O facilities of the Fortran 2018 language are specified in the
+language standard in its clauses 12 (I/O statements) and 13 (\ ``FORMAT``\ ).
+It's a complicated collection of language features:
+
+
+* Files can comprise *records* or *streams*.
+* Records can be fixed-length or variable-length.
+* Record files can be accessed sequentially or directly (random access).
+* Files can be *formatted*\ , or *unformatted* raw bits.
+* ``CHARACTER`` scalars and arrays can be used as if they were
+  fixed-length formatted sequential record files.
+* Formatted I/O can be under control of a ``FORMAT`` statement
+  or ``FMT=`` specifier, *list-directed* with default formatting chosen
+  by the runtime, or ``NAMELIST``\ , in which a collection of variables
+  can be given a name and passed as a group to the runtime library.
+* Sequential records of a file can be partially processed by one
+  or more *non-advancing* I/O statements and eventually completed by
+  another.
+* ``FORMAT`` strings can manipulate the position in the current
+  record arbitrarily, causing re-reading or overwriting.
+* Floating-point output formatting supports more rounding modes
+  than the IEEE standard for floating-point arithmetic.
+
+The Fortran I/O runtime support library is written in C++17, and
+uses some C++17 standard library facilities, but it is intended
+to not have any link-time dependences on the C++ runtime support
+library or any LLVM libraries.
+This is important because there are at least two C++ runtime support
+libraries, and we don't want Fortran application builders to have to
+build multiple versions of their codes; neither do we want to require
+them to ship LLVM libraries along with their products.
+
+Consequently, dynamic memory allocation in the Fortran runtime
+uses only C's ``malloc()`` and ``free()`` functions, and the few
+C++ standard class templates that we instantiate in the library have been
+modified with optional template arguments that override their
+allocators and deallocators.
+
+Conversions between the many binary floating-point formats supported
+by f18 and their decimal representations are performed with the same
+template library of fast conversion algorithms used to interpret
+floating-point values in Fortran source programs and to emit them
+to module files.
+
+Overview of Classes
+===================
+
+A suite of C++ classes and class templates are composed to construct
+the Fortran I/O runtime support library.
+They (mostly) reside in the C++ namespace ``Fortran::runtime::io``.
+They are summarized here in a bottom-up order of dependence.
+
+The header and C++ implementation source file names of these
+classes are in the process of being vigorously rearranged and
+modified; use ``grep`` or an IDE to discover these classes in
+the source for now.  (Sorry!)
+
+``Terminator``
+------------------
+
+A general facility for the entire library, ``Terminator`` latches a
+source program statement location in terms of an unowned pointer to
+its source file path name and line number and uses them to construct
+a fatal error message if needed.
+It is used for both user program errors and internal runtime library crashes.
+
+``IoErrorHandler``
+----------------------
+
+When I/O error conditions arise at runtime that the Fortran program
+might have the privilege to handle itself via ``ERR=``\ , ``END=``\ , or
+``EOR=`` labels and/or by an ``IOSTAT=`` variable, this subclass of
+``Terminator`` is used to either latch the error indication or to crash.
+It sorts out priorities in the case of multiple errors and determines
+the final ``IOSTAT=`` value at the end of an I/O statement.
+
+``MutableModes``
+--------------------
+
+Fortran's formatted I/O statements are affected by a suite of
+modes that can be configured by ``OPEN`` statements, overridden by
+data transfer I/O statement control lists, and further overridden
+between data items with control edit descriptors in a ``FORMAT`` string.
+These modes are represented with a ``MutableModes`` instance, and these
+are instantiated and copied where one would expect them to be in
+order to properly isolate their modifications.
+The modes in force at the time each data item is processed constitute
+a member of each ``DataEdit``.
+
+``DataEdit``
+----------------
+
+Represents a single data edit descriptor from a ``FORMAT`` statement
+or ``FMT=`` character value, with some hidden extensions to also
+support formatting of list-directed transfers.
+It holds an instance of ``MutableModes``\ , and also has a repetition
+count for when an array appears as a data item in the *io-list*.
+For simplicity and efficiency, each data edit descriptor is
+encoded in the ``DataEdit`` as a simple capitalized character
+(or two) and some optional field widths.
+
+``FormatControl<>``
+-----------------------
+
+This class template traverses a ``FORMAT`` statement's contents (or ``FMT=``
+character value) to extract data edit descriptors like ``E20.14`` to
+serve each item in an I/O data transfer statement's *io-list*\ ,
+making callbacks to an instance of its class template argument
+along the way to effect character literal output and record
+positioning.
+The Fortran language standard defines formatted I/O as if the ``FORMAT``
+string were driving the traversal of the data items in the *io-list*\ ,
+but our implementation reverses that perspective to allow a more
+convenient (for the compiler) I/O runtime support library API design
+in which each data item is presented to the library with a distinct
+type-dependent call.
+
+Clients of ``FormatControl`` instantiations call its ``GetNextDataEdit()``
+member function to acquire the next data edit descriptor to be processed
+from the format, and ``FinishOutput()`` to flush out any remaining
+output strings or record positionings at the end of the *io-list*.
+
+The ``DefaultFormatControlCallbacks`` structure summarizes the API
+expected by ``FormatControl`` from its class template actual arguments.
+
+``OpenFile``
+----------------
+
+This class encapsulates all (I hope) the operating system interfaces
+used to interact with the host's filesystems for operations on
+external units.
+Asynchronous I/O interfaces are faked for now with synchronous
+operations and deferred results.
+
+``ConnectionState``
+-----------------------
+
+An active connection to an external or internal unit maintains
+the common parts of its state in this subclass of ``ConnectionAttributes``.
+The base class holds state that should not change during the
+lifetime of the connection, while the subclass maintains state
+that may change during I/O statement execution.
+
+``InternalDescriptorUnit``
+------------------------------
+
+When I/O is being performed from/to a Fortran ``CHARACTER`` array
+rather than an external file, this class manages the standard
+interoperable descriptor used to access its elements as records.
+It has the necessary interfaces to serve as an actual argument
+to the ``FormatControl`` class template.
+
+``FileFrame<>``
+-------------------
+
+This CRTP class template isolates all of the complexity involved between
+an external unit's ``OpenFile`` and the buffering requirements
+imposed by the capabilities of Fortran ``FORMAT`` control edit
+descriptors that allow repositioning within the current record.
+Its interface enables its clients to define a "frame" (my term,
+not Fortran's) that is a contiguous range of bytes that are
+or may soon be in the file.
+This frame is defined as a file offset and a byte size.
+The ``FileFrame`` instance manages an internal circular buffer
+with two essential guarantees:
+
+
+#. The most recently requested frame is present in the buffer
+   and contiguous in memory.
+#. Any extra data after the frame that may have been read from
+   the external unit will be preserved, so that it's safe to
+   read from a socket, pipe, or tape and not have to worry about
+   repositioning and rereading.
+
+In end-of-file situations, it's possible that a request to read
+a frame may come up short.
+
+As a CRTP class template, ``FileFrame`` accesses the raw filesystem
+facilities it needs from ``*this``.
+
+``ExternalFileUnit``
+------------------------
+
+This class mixes in ``ConnectionState``\ , ``OpenFile``\ , and
+``FileFrame<ExternalFileUnit>`` to represent the state of an open
+(or soon to be opened) external file descriptor as a Fortran
+I/O unit.
+It has the contextual APIs required to serve as a template actual
+argument to ``FormatControl``.
+And it contains a ``std::variant<>`` suitable for holding the
+state of the active I/O statement in progress on the unit
+(see below).
+
+``ExternalFileUnit`` instances reside in a ``Map`` that is allocated
+as a static variable and indexed by Fortran unit number.
+Static member functions ``LookUp()``\ , ``LookUpOrCrash()``\ , and ``LookUpOrCreate()``
+probe the map to convert Fortran ``UNIT=`` numbers from I/O statements
+into references to active units.
+
+``IoStatementBase``
+-----------------------
+
+The subclasses of ``IoStatementBase`` each encapsulate and maintain
+the state of one active Fortran I/O statement across the several
+I/O runtime library API function calls it may comprise.
+The subclasses handle the distinctions between internal vs. external I/O,
+formatted vs. list-directed vs. unformatted I/O, input vs. output,
+and so on.
+
+``IoStatementBase`` inherits default ``FORMAT`` processing callbacks and
+an ``IoErrorHandler``.
+Each of the ``IoStatementBase`` classes that pertain to formatted I/O
+support the contextual callback interfaces needed by ``FormatControl``\ ,
+overriding the default callbacks of the base class, which crash if
+called inappropriately (e.g., if a ``CLOSE`` statement somehow
+passes a data item from an *io-list*\ ).
+
+The lifetimes of these subclasses' instances each begin with a user
+program call to an I/O API routine with a name like ``BeginExternalListOutput()``
+and persist until ``EndIoStatement()`` is called.
+
+To reduce dynamic memory allocation, *external* I/O statements allocate
+their per-statement state class instances in space reserved in the
+``ExternalFileUnit`` instance.
+Internal I/O statements currently use dynamic allocation, but
+the I/O API supports a means whereby the code generated for the Fortran
+program may supply stack space to the I/O runtime support library
+for this purpose.
+
+``IoStatementState``
+------------------------
+
+F18's Fortran I/O runtime support library defines and implements an API
+that uses a sequence of function calls to implement each Fortran I/O
+statement.
+The state of each I/O statement in progress is maintained in some
+subclass of ``IoStatementBase``\ , as noted above.
+The purpose of ``IoStatementState`` is to provide generic access
+to the specific state classes without recourse to C++ ``virtual``
+functions or function pointers, language features that may not be
+available to us in some important execution environments.
+``IoStatementState`` comprises a ``std::variant<>`` of wrapped references
+to the various possibilities, and uses ``std::visit()`` to
+access them as needed by the I/O API calls that process each specifier
+in the I/O *control-list* and each item in the *io-list*.
+
+Pointers to ``IoStatementState`` instances are the ``Cookie`` type returned
+in the I/O API for ``Begin...`` I/O statement calls, passed back for
+the *control-list* specifiers and *io-list* data items, and consumed
+by the ``EndIoStatement()`` call at the end of the statement.
+
+Storage for ``IoStatementState`` is reserved in ``ExternalFileUnit`` for
+external I/O units, and in the various final subclasses for internal
+I/O statement states otherwise.
+
+Since Fortran permits a ``CLOSE`` statement to reference a nonexistent
+unit, the library has to treat that (expected to be rare) situation
+as a weird variation of internal I/O since there's no ``ExternalFileUnit``
+available to hold its ``IoStatementBase`` subclass or ``IoStatementState``.
+
+A Narrative Overview Of ``PRINT *, 'HELLO, WORLD'``
+=======================================================
+
+
+#. When the compiled Fortran program begins execution at the ``main()``
+   entry point exported from its main program, it calls ``ProgramStart()``
+   with its arguments and environment.
+#. The generated code calls ``BeginExternalListOutput()`` to
+   start the sequence of calls that implement the ``PRINT`` statement.
+   Since the Fortran runtime I/O library has not yet been used in
+   this process, its data structures are initialized on this
+   first call, and Fortran I/O units 5 and 6 are connected with
+   the stadard input and output file descriptors (respectively).
+   The default unit code is converted to 6 and passed to
+   ``ExternalFileUnit::LookUpOrCrash()``\ , which returns a reference to
+   unit 6's instance.
+#. We check that the unit was opened for formatted I/O.
+#. ``ExternalFileUnit::BeginIoStatement<>()`` is called to initialize
+   an instance of ``ExternalListIoStatementState<false>`` in the unit,
+   point to it with an ``IoStatementState``\ , and return a reference to
+   that object whose address will be the ``Cookie`` for this statement.
+#. The generated code calls ``OutputAscii()`` with that cookie and the
+   address and length of the string.
+#. ``OutputAscii()`` confirms that the cookie corresponds to an output
+   statement and determines that it's list-directed.
+#. ``ListDirectedStatementState<false>::EmitLeadingSpaceOrAdvance()``
+   emits the required initial space on the new current output record
+   by calling ``IoStatementState::GetConnectionState()`` to locate
+   the connection state, determining from the record position state
+   that the space is necessary, and calling ``IoStatementState::Emit()``
+   to cough it out.  That call is redirected to ``ExternalFileUnit::Emit()``\ ,
+   which calls ``FileFrame<ExternalFileUnit>::WriteFrame()`` to extend
+   the frame of the current record and then ``memcpy()`` to fill its
+   first byte with the space.
+#. Back in ``OutputAscii()``\ , the mutable modes and connection state
+   of the ``IoStatementState`` are queried to see whether we're in an
+   ``WRITE(UNIT=,FMT=,DELIM=)`` statement with a delimited specifier.
+   If we were, the library would emit the appropriate quote marks,
+   double up any instances of that character in the text, and split the
+   text over multiple records if it's long.
+#. But we don't have a delimiter, so ``OutputAscii()`` just carves
+   up the text into record-sized chunks and emits them.  There's just
+   one chunk for our short ``CHARACTER`` string value in this example.
+   It's passed to ``IoStatementState::Emit()``\ , which (as above) is
+   redirected to ``ExternalFileUnit::Emit()``\ , which interacts with the
+   frame to extend the frame and ``memcpy`` data into the buffer.
+#. A flag is set in ``ListDirectedStatementState<false>`` to remember
+   that the last item emitted in this list-directed output statement
+   was an undelimited ``CHARACTER`` value, so that if the next item is
+   also an undelimited ``CHARACTER``\ , no interposing space will be emitted
+   between them.
+#. ``OutputAscii()`` return ``true`` to its caller.
+#. The generated code calls ``EndIoStatement()``\ , which is redirected to
+   ``ExternalIoStatementState<false>``\ 's override of that function.
+   As this is not a non-advancing I/O statement, ``ExternalFileUnit::AdvanceRecord()``
+   is called to end the record.  Since this is a sequential formatted
+   file, a newline is emitted.
+#. If unit 6 is connected to a terminal, the buffer is flushed.
+   ``FileFrame<ExternalFileUnit>::Flush()`` drives ``ExternalFileUnit::Write()``
+   to push out the data in maximal contiguous chunks, dealing with any
+   short writes that might occur, and collecting I/O errors along the way.
+   This statement has no ``ERR=`` label or ``IOSTAT=`` specifier, so errors
+   arriving at ``IoErrorHandler::SignalErrno()`` will cause an immediate
+   crash.
+#. ``ExternalIoStatementBase::EndIoStatement()`` is called.
+   It gets the final ``IOSTAT=`` value from ``IoStatementBase::EndIoStatement()``\ ,
+   tells the ``ExternalFileUnit`` that no I/O statement remains active, and
+   returns the I/O status value back to the program.
+#. Eventually, the program calls ``ProgramEndStatement()``\ , which
+   calls ``ExternalFileUnit::CloseAll()``\ , which flushes and closes all
+   open files.  If the standard output were not a terminal, the output
+   would be written now with the same sequence of calls as above.
+#. ``exit(EXIT_SUCCESS)``.

flang/docs/ImplementingASemanticCheck.rst

+Introduction
+============
+
+I recently added a semantic check to the f18 compiler front end.  This document
+describes my thought process and the resulting implementation.
+
+For more information about the compiler, start with the 
+`compiler overview <Overview.rst>`_.
+
+Problem definition
+==================
+
+In the 2018 Fortran standard, section 11.1.7.4.3, paragraph 2, states that:
+
+.. code-block::
+
+   Except for the incrementation of the DO variable that occurs in step (3), the DO variable 
+   shall neither be redefined nor become undefined while the DO construct is active.
+
+One of the ways that DO variables might be redefined is if they are passed to
+functions with dummy arguments whose ``INTENT`` is ``INTENT(OUT)`` or
+``INTENT(INOUT)``.  I implemented this semantic check.  Specifically, I changed
+the compiler to emit an error message if an active DO variable was passed to a
+dummy argument of a FUNCTION with INTENT(OUT).  Similarly, I had the compiler
+emit a warning if an active DO variable was passed to a dummy argument with
+INTENT(INOUT).  Previously, I had implemented similar checks for SUBROUTINE
+calls.
+
+Creating a test
+===============
+
+My first step was to create a test case to cause the problem.  I called it testfun.f90 and used it to check the behavior of other Fortran compilers.  Here's the initial version:
+
+.. code-block:: fortran
+
+     subroutine s()
+       Integer :: ivar, jvar
+
+       do ivar = 1, 10
+         jvar = intentOutFunc(ivar) ! Error since ivar is a DO variable
+       end do
+
+     contains
+       function intentOutFunc(dummyArg)
+         integer, intent(out) :: dummyArg
+         integer  :: intentOutFunc
+
+         dummyArg = 216
+       end function intentOutFunc
+     end subroutine s
+
+I verified that other Fortran compilers produced an error message at the point
+of the call to ``intentOutFunc()``\ :
+
+.. code-block:: fortran
+
+         jvar = intentOutFunc(ivar) ! Error since ivar is a DO variable
+
+I also used this program to produce a parse tree for the program using the command:
+
+.. code-block:: bash
+
+     f18 -fdebug-dump-parse-tree -fparse-only testfun.f90
+
+Here's the relevant fragment of the parse tree produced by the compiler:
+
+.. code-block::
+
+   | | ExecutionPartConstruct -> ExecutableConstruct -> DoConstruct
+   | | | NonLabelDoStmt
+   | | | | LoopControl -> LoopBounds
+   | | | | | Scalar -> Name = 'ivar'
+   | | | | | Scalar -> Expr = '1_4'
+   | | | | | | LiteralConstant -> IntLiteralConstant = '1'
+   | | | | | Scalar -> Expr = '10_4'
+   | | | | | | LiteralConstant -> IntLiteralConstant = '10'
+   | | | Block
+   | | | | ExecutionPartConstruct -> ExecutableConstruct -> ActionStmt -> AssignmentStmt = 'jvar=intentoutfunc(ivar)'
+   | | | | | Variable -> Designator -> DataRef -> Name = 'jvar'
+   | | | | | Expr = 'intentoutfunc(ivar)'
+   | | | | | | FunctionReference -> Call
+   | | | | | | | ProcedureDesignator -> Name = 'intentoutfunc'
+   | | | | | | | ActualArgSpec
+   | | | | | | | | ActualArg -> Expr = 'ivar'
+   | | | | | | | | | Designator -> DataRef -> Name = 'ivar'
+   | | | EndDoStmt ->
+
+Note that this fragment of the tree only shows four ``parser::Expr`` nodes,
+but the full parse tree also contained a fifth ``parser::Expr`` node for the
+constant 216 in the statement:
+
+.. code-block:: fortran
+
+         dummyArg = 216
+
+Analysis and implementation planning
+====================================
+
+I then considered what I needed to do.  I needed to detect situations where an
+active DO variable was passed to a dummy argument with ``INTENT(OUT)`` or
+``INTENT(INOUT)``.  Once I detected such a situation, I needed to produce a
+message that highlighted the erroneous source code.  
+
+Deciding where to add the code to the compiler
+----------------------------------------------
+
+This new semantic check would depend on several types of information -- the
+parse tree, source code location information, symbols, and expressions.  Thus I
+needed to put my new code in a place in the compiler after the parse tree had
+been created, name resolution had already happened, and expression semantic
+checking had already taken place.
+
+Most semantic checks for statements are implemented by walking the parse tree
+and performing analysis on the nodes they visit.  My plan was to use this
+method.  The infrastructure for walking the parse tree for statement semantic
+checking is implemented in the files ``lib/Semantics/semantics.cpp``.
+Here's a fragment of the declaration of the framework's parse tree visitor from
+``lib/Semantics/semantics.cpp``\ :
+
+.. code-block:: C++
+
+     // A parse tree visitor that calls Enter/Leave functions from each checker
+     // class C supplied as template parameters. Enter is called before the node's
+     // children are visited, Leave is called after. No two checkers may have the
+     // same Enter or Leave function. Each checker must be constructible from
+     // SemanticsContext and have BaseChecker as a virtual base class.
+     template<typename... C> class SemanticsVisitor : public virtual C... {
+     public:
+       using C::Enter...;
+       using C::Leave...;
+       using BaseChecker::Enter;
+       using BaseChecker::Leave;
+       SemanticsVisitor(SemanticsContext &context)
+         : C{context}..., context_{context} {}
+         ...
+
+Since FUNCTION calls are a kind of expression, I was planning to base my
+implementation on the contents of ``parser::Expr`` nodes.  I would need to define
+either an ``Enter()`` or ``Leave()`` function whose parameter was a ``parser::Expr``
+node.  Here's the declaration I put into ``lib/Semantics/check-do.h``\ :
+
+.. code-block:: C++
+
+     void Leave(const parser::Expr &);
+
+The ``Enter()`` functions get called at the time the node is first visited --
+that is, before its children.  The ``Leave()`` function gets called after the
+children are visited.  For my check the visitation order didn't matter, so I
+arbitrarily chose to implement the ``Leave()`` function to visit the parse tree
+node.
+
+Since my semantic check was focused on DO CONCURRENT statements, I added it to
+the file ``lib/Semantics/check-do.cpp`` where most of the semantic checking for
+DO statements already lived.
+
+Taking advantage of prior work
+------------------------------
+
+When implementing a similar check for SUBROUTINE calls, I created a utility
+functions in ``lib/Semantics/semantics.cpp`` to emit messages if
+a symbol corresponding to an active DO variable was being potentially modified:
+
+.. code-block:: C++
+
+     void WarnDoVarRedefine(const parser::CharBlock &location, const Symbol &var);
+     void CheckDoVarRedefine(const parser::CharBlock &location, const Symbol &var);
+
+The first function is intended for dummy arguments of ``INTENT(INOUT)`` and
+the second for ``INTENT(OUT)``.
+
+Thus I needed three pieces of
+information -- 
+
+
+#. the source location of the erroneous text, 
+#. the ``INTENT`` of the associated dummy argument, and
+#. the relevant symbol passed as the actual argument.
+
+The first and third are needed since they're required to call the utility
+functions.  The second is needed to determine whether to call them.
+
+Finding the source location
+---------------------------
+
+The source code location information that I'd need for the error message must
+come from the parse tree.  I looked in the file
+``include/flang/Parser/parse-tree.h`` and determined that a ``struct Expr``
+contained source location information since it had the field ``CharBlock
+source``.  Thus, if I visited a ``parser::Expr`` node, I could get the source
+location information for the associated expression.
+
+Determining the ``INTENT``
+------------------------------
+
+I knew that I could find the ``INTENT`` of the dummy argument associated with the
+actual argument from the function called ``dummyIntent()`` in the class
+``evaluate::ActualArgument`` in the file ``include/flang/Evaluate/call.h``.  So
+if I could find an ``evaluate::ActualArgument`` in an expression, I could
+  determine the ``INTENT`` of the associated dummy argument.  I knew that it was
+  valid to call ``dummyIntent()`` because the data on which ``dummyIntent()``
+  depends is established during semantic processing for expressions, and the
+  semantic processing for expressions happens before semantic checking for DO
+  constructs.
+
+In my prior work on checking the INTENT of arguments for SUBROUTINE calls,
+the parse tree held a node for the call (a ``parser::CallStmt``\ ) that contained
+an ``evaluate::ProcedureRef`` node.
+
+.. code-block:: C++
+
+     struct CallStmt {
+       WRAPPER_CLASS_BOILERPLATE(CallStmt, Call);
+       mutable std::unique_ptr<evaluate::ProcedureRef,
+           common::Deleter<evaluate::ProcedureRef>>
+           typedCall;  // filled by semantics
+     };
+
+The ``evaluate::ProcedureRef`` contains a list of ``evaluate::ActualArgument``
+nodes.  I could then find the INTENT of a dummy argument from the
+``evaluate::ActualArgument`` node.
+
+For a FUNCTION call, though, there is no similar way to get from a parse tree
+node to an ``evaluate::ProcedureRef`` node.  But I knew that there was an
+existing framework used in DO construct semantic checking that traversed an
+``evaluate::Expr`` node collecting ``semantics::Symbol`` nodes.  I guessed that I'd
+be able to use a similar framework to traverse an ``evaluate::Expr``  node to
+find all of the ``evaluate::ActualArgument`` nodes.  
+
+Note that the compiler has multiple types called ``Expr``.  One is in the
+``parser`` namespace.  ``parser::Expr`` is defined in the file
+``include/flang/Parser/parse-tree.h``.  It represents a parsed expression that
+maps directly to the source code and has fields that specify any operators in
+the expression, the operands, and the source position of the expression.
+
+Additionally, in the namespace ``evaluate``\ , there are ``evaluate::Expr<T>``
+template classes defined in the file ``include/flang/Evaluate/expression.h``.
+These are parameterized over the various types of Fortran and constitute a
+suite of strongly-typed representations of valid Fortran expressions of type
+``T`` that have been fully elaborated with conversion operations and subjected to
+constant folding.  After an expression has undergone semantic analysis, the
+field ``typedExpr`` in the ``parser::Expr`` node is filled in with a pointer that
+owns an instance of ``evaluate::Expr<SomeType>``\ , the most general representation
+of an analyzed expression.
+
+All of the declarations associated with both FUNCTION and SUBROUTINE calls are
+in ``include/flang/Evaluate/call.h``.  An ``evaluate::FunctionRef`` inherits from
+an ``evaluate::ProcedureRef`` which contains the list of
+``evaluate::ActualArgument`` nodes.  But the relationship between an
+``evaluate::FunctionRef`` node and its associated arguments is not relevant.  I
+only needed to find the ``evaluate::ActualArgument`` nodes in an expression.
+They hold all of the information I needed.
+
+So my plan was to start with the ``parser::Expr`` node and extract its
+associated ``evaluate::Expr`` field.  I would then traverse the
+``evaluate::Expr`` tree collecting all of the ``evaluate::ActualArgument``
+nodes.  I would look at each of these nodes to determine the ``INTENT`` of
+the associated dummy argument.
+
+This combination of the traversal framework and ``dummyIntent()`` would give
+me the ``INTENT`` of all of the dummy arguments in a FUNCTION call.  Thus, I
+would have the second piece of information I needed.
+
+Determining if the actual argument is a variable
+------------------------------------------------
+
+I also guessed that I could determine if the ``evaluate::ActualArgument``
+consisted of a variable.  
+
+Once I had a symbol for the variable, I could call one of the functions:
+
+.. code-block:: C++
+
+     void WarnDoVarRedefine(const parser::CharBlock &, const Symbol &);
+     void CheckDoVarRedefine(const parser::CharBlock &, const Symbol &);
+
+to emit the messages.
+
+If my plans worked out, this would give me the three pieces of information I
+needed -- the source location of the erroneous text, the ``INTENT`` of the dummy
+argument, and a symbol that I could use to determine whether the actual
+argument was an active DO variable.
+
+Implementation
+==============
+
+Adding a parse tree visitor
+---------------------------
+
+I started my implementation by adding a visitor for ``parser::Expr`` nodes.
+Since this analysis is part of DO construct checking, I did this in
+``lib/Semantics/check-do.cpp``.  I added a print statement to the visitor to
+verify that my new code was actually getting executed.  
+
+In ``lib/Semantics/check-do.h``\ , I added the declaration for the visitor:
+
+.. code-block:: C++
+
+     void Leave(const parser::Expr &);
+
+In ``lib/Semantics/check-do.cpp``\ , I added an (almost empty) implementation:
+
+.. code-block:: C++
+
+     void DoChecker::Leave(const parser::Expr &) {
+       std::cout << "In Leave for parser::Expr\n";
+     }
+
+I then built the compiler with these changes and ran it on my test program.
+This time, I made sure to invoke semantic checking.  Here's the command I used:
+
+.. code-block:: bash
+
+     f18 -fdebug-resolve-names -fdebug-dump-parse-tree -funparse-with-symbols testfun.f90
+
+This produced the output:
+
+.. code-block::
+
+     In Leave for parser::Expr
+     In Leave for parser::Expr
+     In Leave for parser::Expr
+     In Leave for parser::Expr
+     In Leave for parser::Expr
+
+This made sense since the parse tree contained five ``parser::Expr`` nodes.
+So far, so good.  Note that a ``parse::Expr`` node has a field with the
+source position of the associated expression (\ ``CharBlock source``\ ).  So I
+now had one of the three pieces of information needed to detect and report
+errors.
+
+Collecting the actual arguments
+-------------------------------
+
+To get the ``INTENT`` of the dummy arguments and the ``semantics::Symbol`` associated with the
+actual argument, I needed to find all of the actual arguments embedded in an
+expression that contained a FUNCTION call.  So my next step was to write the
+framework to walk the ``evaluate::Expr`` to gather all of the
+``evaluate::ActualArgument`` nodes.  The code that I planned to model it on
+was the existing infrastructure that collected all of the ``semantics::Symbol`` nodes from an
+``evaluate::Expr``.  I found this implementation in
+``lib/Evaluate/tools.cpp``\ :
+
+.. code-block:: C++
+
+     struct CollectSymbolsHelper
+       : public SetTraverse<CollectSymbolsHelper, semantics::SymbolSet> {
+       using Base = SetTraverse<CollectSymbolsHelper, semantics::SymbolSet>;
+       CollectSymbolsHelper() : Base{*this} {}
+       using Base::operator();
+       semantics::SymbolSet operator()(const Symbol &symbol) const {
+         return {symbol};
+       }
+     };
+     template<typename A> semantics::SymbolSet CollectSymbols(const A &x) {
+       return CollectSymbolsHelper{}(x);
+     }
+
+Note that the ``CollectSymbols()`` function returns a ``semantics::Symbolset``\ ,
+which is declared in ``include/flang/Semantics/symbol.h``\ :
+
+.. code-block:: C++
+
+     using SymbolSet = std::set<SymbolRef>;
+
+This infrastructure yields a collection based on ``std::set<>``.  Using an
+``std::set<>`` means that if the same object is inserted twice, the
+collection only gets one copy.  This was the behavior that I wanted.
+
+Here's a sample invocation of ``CollectSymbols()`` that I found:
+
+.. code-block:: C++
+
+       if (const auto *expr{GetExpr(parsedExpr)}) {
+         for (const Symbol &symbol : evaluate::CollectSymbols(*expr)) {
+
+I noted that a ``SymbolSet`` did not actually contain an
+``std::set<Symbol>``.  This wasn't surprising since we don't want to put the
+full ``semantics::Symbol`` objects into the set.  Ideally, we would be able to create an
+``std::set<Symbol &>`` (a set of C++ references to symbols).  But C++ doesn't
+support sets that contain references.  This limitation is part of the rationale
+for the f18 implementation of type ``common::Reference``\ , which is defined in
+  ``include/flang/Common/reference.h``.
+
+``SymbolRef``\ , the specialization of the template ``common::Reference`` for
+``semantics::Symbol``\ , is declared in the file
+``include/flang/Semantics/symbol.h``\ :
+
+.. code-block:: C++
+
+     using SymbolRef = common::Reference<const Symbol>;
+
+So to implement something that would collect ``evaluate::ActualArgument``
+nodes from an ``evaluate::Expr``\ , I first defined the required types
+``ActualArgumentRef`` and ``ActualArgumentSet``.  Since these are being
+used exclusively for DO construct semantic checking (currently), I put their
+definitions into ``lib/Semantics/check-do.cpp``\ :
+
+.. code-block:: C++
+
+     namespace Fortran::evaluate {
+       using ActualArgumentRef = common::Reference<const ActualArgument>;
+     }
+
+
+     using ActualArgumentSet = std::set<evaluate::ActualArgumentRef>;
+
+Since ``ActualArgument`` is in the namespace ``evaluate``\ , I put the
+definition for ``ActualArgumentRef`` in that namespace, too.
+
+I then modeled the code to create an ``ActualArgumentSet`` after the code to
+collect a ``SymbolSet`` and put it into ``lib/Semantics/check-do.cpp``\ :
+
+.. code-block:: C++
+
+     struct CollectActualArgumentsHelper
+       : public evaluate::SetTraverse<CollectActualArgumentsHelper,
+             ActualArgumentSet> {
+       using Base = SetTraverse<CollectActualArgumentsHelper, ActualArgumentSet>;
+       CollectActualArgumentsHelper() : Base{*this} {}
+       using Base::operator();
+       ActualArgumentSet operator()(const evaluate::ActualArgument &arg) const {
+         return ActualArgumentSet{arg};
+       }
+     };
+
+     template<typename A> ActualArgumentSet CollectActualArguments(const A &x) {
+       return CollectActualArgumentsHelper{}(x);
+     }
+
+     template ActualArgumentSet CollectActualArguments(const SomeExpr &);
+
+Unfortunately, when I tried to build this code, I got an error message saying
+``std::set`` requires the ``<`` operator to be defined for its contents.
+To fix this, I added a definition for ``<``.  I didn't care how ``<`` was
+defined, so I just used the address of the object:
+
+.. code-block:: C++
+
+     inline bool operator<(ActualArgumentRef x, ActualArgumentRef y) {
+       return &*x < &*y;
+     }
+
+I was surprised when this did not make the error message saying that I needed
+the ``<`` operator go away.  Eventually, I figured out that the definition of
+the ``<`` operator needed to be in the ``evaluate`` namespace.  Once I put
+it there, everything compiled successfully.  Here's the code that worked:
+
+.. code-block:: C++
+
+     namespace Fortran::evaluate {
+     using ActualArgumentRef = common::Reference<const ActualArgument>;
+
+     inline bool operator<(ActualArgumentRef x, ActualArgumentRef y) {
+       return &*x < &*y;
+     }
+     }
+
+I then modified my visitor for the parser::Expr to invoke my new collection
+framework.  To verify that it was actually doing something, I printed out the
+number of ``evaluate::ActualArgument`` nodes that it collected.  Note the
+call to ``GetExpr()`` in the invocation of ``CollectActualArguments()``.  I
+modeled this on similar code that collected a ``SymbolSet`` described above:
+
+.. code-block:: C++
+
+     void DoChecker::Leave(const parser::Expr &parsedExpr) {
+       std::cout << "In Leave for parser::Expr\n";
+       ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
+       std::cout << "Number of arguments: " << argSet.size() << "\n";
+     }
+
+I compiled and tested this code on my little test program.  Here's the output that I got:
+
+.. code-block::
+
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 1
+     In Leave for parser::Expr
+     Number of arguments: 0
+
+So most of the ``parser::Expr``\ nodes contained no actual arguments, but the
+fourth expression in the parse tree walk contained a single argument.  This may
+seem wrong since the third ``parser::Expr`` node in the file contains the
+``FunctionReference`` node along with the arguments that we're gathering.
+But since the tree walk function is being called upon leaving a
+``parser::Expr`` node, the function visits the ``parser::Expr`` node
+associated with the ``parser::ActualArg`` node before it visits the
+``parser::Expr`` node associated with the ``parser::FunctionReference``
+node.
+
+So far, so good.
+
+Finding the ``INTENT`` of the dummy argument
+------------------------------------------------
+
+I now wanted to find the ``INTENT`` of the dummy argument associated with the
+arguments in the set.  As mentioned earlier, the type
+``evaluate::ActualArgument`` has a member function called ``dummyIntent()``
+that gives this value.  So I augmented my code to print out the ``INTENT``\ :
+
+.. code-block:: C++
+
+     void DoChecker::Leave(const parser::Expr &parsedExpr) {
+       std::cout << "In Leave for parser::Expr\n";
+       ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
+       std::cout << "Number of arguments: " << argSet.size() << "\n";
+       for (const evaluate::ActualArgumentRef &argRef : argSet) {
+         common::Intent intent{argRef->dummyIntent()};
+         switch (intent) {
+           case common::Intent::In: std::cout << "INTENT(IN)\n"; break;
+           case common::Intent::Out: std::cout << "INTENT(OUT)\n"; break;
+           case common::Intent::InOut: std::cout << "INTENT(INOUT)\n"; break;
+           default: std::cout << "default INTENT\n";
+         }
+       }
+     }
+
+I then rebuilt my compiler and ran it on my test case.  This produced the following output:
+
+.. code-block::
+
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 1
+     INTENT(OUT)
+     In Leave for parser::Expr
+     Number of arguments: 0
+
+I then modified my test case to convince myself that I was getting the correct
+``INTENT`` for ``IN``\ , ``INOUT``\ , and default cases.
+
+So far, so good.
+
+Finding the symbols for arguments that are variables
+----------------------------------------------------
+
+The third and last piece of information I needed was to determine if a variable
+was being passed as an actual argument.  In such cases, I wanted to get the
+symbol table node (\ ``semantics::Symbol``\ ) for the variable.  My starting point was the
+``evaluate::ActualArgument`` node.  
+
+I was unsure of how to do this, so I browsed through existing code to look for
+how it treated ``evaluate::ActualArgument`` objects.  Since most of the code that deals with the ``evaluate`` namespace is in the lib/Evaluate directory, I looked there.  I ran ``grep`` on all of the ``.cpp`` files looking for
+uses of ``ActualArgument``.  One of the first hits I got was in ``lib/Evaluate/call.cpp`` in the definition of ``ActualArgument::GetType()``\ :
+
+.. code-block:: C++
+
+   std::optional<DynamicType> ActualArgument::GetType() const {
+     if (const Expr<SomeType> *expr{UnwrapExpr()}) {
+       return expr->GetType();
+     } else if (std::holds_alternative<AssumedType>(u_)) {
+       return DynamicType::AssumedType();
+     } else {
+       return std::nullopt;
+     }
+   }
+
+I noted the call to ``UnwrapExpr()`` that yielded a value of
+``Expr<SomeType>``.  So I guessed that I could use this member function to
+get an ``evaluate::Expr<SomeType>`` on which I could perform further analysis.
+
+I also knew that the header file ``include/flang/Evaluate/tools.h`` held many
+utility functions for dealing with ``evaluate::Expr`` objects.  I was hoping to
+find something that would determine if an ``evaluate::Expr`` was a variable.  So
+I searched for ``IsVariable`` and got a hit immediately.  
+
+.. code-block:: C++
+
+     template<typename A> bool IsVariable(const A &x) {
+       if (auto known{IsVariableHelper{}(x)}) {
+         return *known;
+       } else {
+         return false;
+       }
+     }
+
+But I actually needed more than just the knowledge that an ``evaluate::Expr`` was
+a variable.  I needed the ``semantics::Symbol`` associated with the variable.  So
+I searched in ``include/flang/Evaluate/tools.h`` for functions that returned a
+``semantics::Symbol``.  I found the following:
+
+.. code-block:: C++
+
+   // If an expression is simply a whole symbol data designator,
+   // extract and return that symbol, else null.
+   template<typename A> const Symbol *UnwrapWholeSymbolDataRef(const A &x) {
+     if (auto dataRef{ExtractDataRef(x)}) {
+       if (const SymbolRef * p{std::get_if<SymbolRef>(&dataRef->u)}) {
+         return &p->get();
+       }
+     }
+     return nullptr;
+   }
+
+This was exactly what I wanted.  DO variables must be whole symbols.  So I
+could try to extract a whole ``semantics::Symbol`` from the ``evaluate::Expr`` in my
+``evaluate::ActualArgument``.  If this extraction resulted in a ``semantics::Symbol``
+that wasn't a ``nullptr``\ , I could then conclude if it was a variable that I
+could pass to existing functions that would determine if it was an active DO
+variable.
+
+I then modified the compiler to perform the analysis that I'd guessed would
+work:
+
+.. code-block:: C++
+
+     void DoChecker::Leave(const parser::Expr &parsedExpr) {
+       std::cout << "In Leave for parser::Expr\n";
+       ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
+       std::cout << "Number of arguments: " << argSet.size() << "\n";
+       for (const evaluate::ActualArgumentRef &argRef : argSet) {
+         if (const SomeExpr * argExpr{argRef->UnwrapExpr()}) {
+           std::cout << "Got an unwrapped Expr\n";
+           if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
+             std::cout << "Found a whole variable: " << *var << "\n";
+           }
+         }
+         common::Intent intent{argRef->dummyIntent()};
+         switch (intent) {
+           case common::Intent::In: std::cout << "INTENT(IN)\n"; break;
+           case common::Intent::Out: std::cout << "INTENT(OUT)\n"; break;
+           case common::Intent::InOut: std::cout << "INTENT(INOUT)\n"; break;
+           default: std::cout << "default INTENT\n";
+         }
+       }
+     }
+
+Note the line that prints out the symbol table entry for the variable:
+
+.. code-block:: C++
+
+             std::cout << "Found a whole variable: " << *var << "\n";
+
+The compiler defines the "<<" operator for ``semantics::Symbol``\ , which is handy
+for analyzing the compiler's behavior.
+
+Here's the result of running the modified compiler on my Fortran test case:
+
+.. code-block::
+
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 1
+     Got an unwrapped Expr
+     Found a whole variable: ivar: ObjectEntity type: INTEGER(4)
+     INTENT(OUT)
+     In Leave for parser::Expr
+     Number of arguments: 0
+
+Sweet.
+
+Emitting the messages
+---------------------
+
+At this point, using the source location information from the original
+``parser::Expr``\ , I had enough information to plug into the exiting
+interfaces for emitting messages for active DO variables.  I modified the
+compiler code accordingly:
+
+.. code-block:: C++
+
+     void DoChecker::Leave(const parser::Expr &parsedExpr) {
+       std::cout << "In Leave for parser::Expr\n";
+       ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
+       std::cout << "Number of arguments: " << argSet.size() << "\n";
+       for (const evaluate::ActualArgumentRef &argRef : argSet) {
+         if (const SomeExpr * argExpr{argRef->UnwrapExpr()}) {
+           std::cout << "Got an unwrapped Expr\n";
+           if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
+             std::cout << "Found a whole variable: " << *var << "\n";
+             common::Intent intent{argRef->dummyIntent()};
+             switch (intent) {
+               case common::Intent::In: std::cout << "INTENT(IN)\n"; break;
+               case common::Intent::Out: 
+                 std::cout << "INTENT(OUT)\n"; 
+                 context_.CheckDoVarRedefine(parsedExpr.source, *var);
+                 break;
+               case common::Intent::InOut: 
+                 std::cout << "INTENT(INOUT)\n"; 
+                 context_.WarnDoVarRedefine(parsedExpr.source, *var);
+                 break;
+               default: std::cout << "default INTENT\n";
+             }
+           }
+         }
+       }
+     }
+
+I then ran this code on my test case, and miraculously, got the following
+output:
+
+.. code-block::
+
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 0
+     In Leave for parser::Expr
+     Number of arguments: 1
+     Got an unwrapped Expr
+     Found a whole variable: ivar: ObjectEntity type: INTEGER(4)
+     INTENT(OUT)
+     In Leave for parser::Expr
+     Number of arguments: 0
+     testfun.f90:6:12: error: Cannot redefine DO variable 'ivar'
+           jvar = intentOutFunc(ivar)
+                  ^^^^^^^^^^^^^^^^^^^
+     testfun.f90:5:6: Enclosing DO construct
+         do ivar = 1, 10
+            ^^^^
+
+Even sweeter.
+
+Improving the test case
+=======================
+
+At this point, my implementation seemed to be working.  But I was concerned
+about the limitations of my test case.  So I augmented it to include arguments
+other than ``INTENT(OUT)`` and more complex expressions.  Luckily, my
+augmented test did not reveal any new problems.   
+
+Here's the test I ended up with:
+
+.. code-block:: Fortran
+
+     subroutine s()
+
+       Integer :: ivar, jvar
+
+       ! This one is OK
+       do ivar = 1, 10
+         jvar = intentInFunc(ivar)
+       end do
+
+       ! Error for passing a DO variable to an INTENT(OUT) dummy
+       do ivar = 1, 10
+         jvar = intentOutFunc(ivar)
+       end do
+
+       ! Error for passing a DO variable to an INTENT(OUT) dummy, more complex 
+       ! expression
+       do ivar = 1, 10
+         jvar = 83 + intentInFunc(intentOutFunc(ivar))
+       end do
+
+       ! Warning for passing a DO variable to an INTENT(INOUT) dummy
+       do ivar = 1, 10
+         jvar = intentInOutFunc(ivar)
+       end do
+
+     contains
+       function intentInFunc(dummyArg)
+         integer, intent(in) :: dummyArg
+         integer  :: intentInFunc
+
+         intentInFunc = 343
+       end function intentInFunc
+
+       function intentOutFunc(dummyArg)
+         integer, intent(out) :: dummyArg
+         integer  :: intentOutFunc
+
+         dummyArg = 216
+         intentOutFunc = 343
+       end function intentOutFunc
+
+       function intentInOutFunc(dummyArg)
+         integer, intent(inout) :: dummyArg
+         integer  :: intentInOutFunc
+
+         dummyArg = 216
+         intentInOutFunc = 343
+       end function intentInOutFunc
+
+     end subroutine s
+
+Submitting the pull request
+===========================
+
+At this point, my implementation seemed functionally complete, so I stripped out all of the debug statements, ran ``clang-format`` on it and reviewed it
+to make sure that the names were clear.  Here's what I ended up with:
+
+.. code-block:: C++
+
+     void DoChecker::Leave(const parser::Expr &parsedExpr) {
+       ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
+       for (const evaluate::ActualArgumentRef &argRef : argSet) {
+         if (const SomeExpr * argExpr{argRef->UnwrapExpr()}) {
+           if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
+             common::Intent intent{argRef->dummyIntent()};
+             switch (intent) {
+               case common::Intent::Out: 
+                 context_.CheckDoVarRedefine(parsedExpr.source, *var);
+                 break;
+               case common::Intent::InOut: 
+                 context_.WarnDoVarRedefine(parsedExpr.source, *var);
+                 break;
+               default:; // INTENT(IN) or default intent
+             }
+           }
+         }
+       }
+     }
+
+I then created a pull request to get review comments.  
+
+Responding to pull request comments
+===================================
+
+I got feedback suggesting that I use an ``if`` statement rather than a
+``case`` statement.  Another comment reminded me that I should look at the
+code I'd previously writted to do a similar check for SUBROUTINE calls to see
+if there was an opportunity to share code.  This examination resulted in
+  converting my existing code to the following pair of functions:
+
+.. code-block:: C++
+
+     static void CheckIfArgIsDoVar(const evaluate::ActualArgument &arg,
+         const parser::CharBlock location, SemanticsContext &context) {
+       common::Intent intent{arg.dummyIntent()};
+       if (intent == common::Intent::Out || intent == common::Intent::InOut) {
+         if (const SomeExpr * argExpr{arg.UnwrapExpr()}) {
+           if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
+             if (intent == common::Intent::Out) {
+               context.CheckDoVarRedefine(location, *var);
+             } else {
+               context.WarnDoVarRedefine(location, *var);  // INTENT(INOUT)
+             }
+           }
+         }
+       }
+     }
+
+     void DoChecker::Leave(const parser::Expr &parsedExpr) {
+       if (const SomeExpr * expr{GetExpr(parsedExpr)}) {
+         ActualArgumentSet argSet{CollectActualArguments(*expr)};
+         for (const evaluate::ActualArgumentRef &argRef : argSet) {
+           CheckIfArgIsDoVar(*argRef, parsedExpr.source, context_);
+         }
+       }
+     }
+
+The function ``CheckIfArgIsDoVar()`` was shared with the checks for DO
+variables being passed to SUBROUTINE calls.
+
+At this point, my pull request was approved, and I merged it and deleted the
+associated branch.

flang/docs/Intrinsics.rst

+A categorization of standard (2018) and extended Fortran intrinsic procedures
+=============================================================================
+
+This note attempts to group the intrinsic procedures of Fortran into categories
+of functions or subroutines with similar interfaces as an aid to
+comprehension beyond that which might be gained from the standard's
+alphabetical list.
+
+A brief status of intrinsic procedure support in f18 is also given at the end.
+
+Few procedures are actually described here apart from their interfaces; see the
+Fortran 2018 standard (section 16) for the complete story.
+
+Intrinsic modules are not covered here.
+
+General rules
+-------------
+
+
+#. The value of any intrinsic function's ``KIND`` actual argument, if present,
+   must be a scalar constant integer expression, of any kind, whose value
+   resolves to some supported kind of the function's result type.
+   If optional and absent, the kind of the function's result is
+   either the default kind of that category or to the kind of an argument
+   (e.g., as in ``AINT``\ ).
+#. Procedures are summarized with a non-Fortran syntax for brevity.
+   Wherever a function has a short definition, it appears after an
+   equal sign as if it were a statement function.  Any functions referenced
+   in these short summaries are intrinsic.
+#. Unless stated otherwise, an actual argument may have any supported kind
+   of a particular intrinsic type.  Sometimes a pattern variable
+   can appear in a description (e.g., ``REAL(k)``\ ) when the kind of an
+   actual argument's type must match the kind of another argument, or
+   determines the kind type parameter of the function result.
+#. When an intrinsic type name appears without a kind (e.g., ``REAL``\ ),
+   it refers to the default kind of that type.  Sometimes the word
+   ``default`` will appear for clarity.
+#. The names of the dummy arguments actually matter because they can
+   be used as keywords for actual arguments.
+#. All standard intrinsic functions are pure, even when not elemental.
+#. Assumed-rank arguments may not appear as actual arguments unless
+   expressly permitted.
+#. When an argument is described with a default value, e.g. ``KIND=KIND(0)``\ ,
+   it is an optional argument.  Optional arguments without defaults,
+   e.g. ``DIM`` on many transformationals, are wrapped in ``[]`` brackets
+   as in the Fortran standard.  When an intrinsic has optional arguments
+   with and without default values, the arguments with default values
+   may appear within the brackets to preserve the order of arguments
+   (e.g., ``COUNT``\ ).
+
+Elemental intrinsic functions
+=============================
+
+Pure elemental semantics apply to these functions, to wit: when one or more of
+the actual arguments are arrays, the arguments must be conformable, and
+the result is also an array.
+Scalar arguments are expanded when the arguments are not all scalars.
+
+Elemental intrinsic functions that may have unrestricted specific procedures
+----------------------------------------------------------------------------
+
+When an elemental intrinsic function is documented here as having an
+*unrestricted specific name*\ , that name may be passed as an actual
+argument, used as the target of a procedure pointer, appear in
+a generic interface, and be otherwise used as if it were an external
+procedure.
+An ``INTRINSIC`` statement or attribute may have to be applied to an
+unrestricted specific name to enable such usage.
+
+When a name is being used as a specific procedure for any purpose other
+than that of a called function, the specific instance of the function
+that accepts and returns values of the default kinds of the intrinsic
+types is used.
+A Fortran ``INTERFACE`` could be written to define each of
+these unrestricted specific intrinsic function names.
+
+Calls to dummy arguments and procedure pointers that correspond to these
+specific names must pass only scalar actual argument values.
+
+No other intrinsic function name can be passed as an actual argument,
+used as a pointer target, appear in a generic interface, or be otherwise
+used except as the name of a called function.
+Some of these *restricted specific intrinsic functions*\ , e.g. ``FLOAT``\ ,
+provide a means for invoking a corresponding generic (\ ``REAL`` in the case of ``FLOAT``\ )
+with forced argument and result kinds.
+Others, viz. ``CHAR``\ , ``ICHAR``\ , ``INT``\ , ``REAL``\ , and the lexical comparisons like ``LGE``\ ,
+have the same name as their generic functions, and it is not clear what purpose
+is accomplished by the standard by defining them as specific functions.
+
+Trigonometric elemental intrinsic functions, generic and (mostly) specific
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All of these functions can be used as unrestricted specific names.
+
+.. code-block::
+
+   ACOS(REAL(k) X) -> REAL(k)
+   ASIN(REAL(k) X) -> REAL(k)
+   ATAN(REAL(k) X) -> REAL(k)
+   ATAN(REAL(k) Y, REAL(k) X) -> REAL(k) = ATAN2(Y, X)
+   ATAN2(REAL(k) Y, REAL(k) X) -> REAL(k)
+   COS(REAL(k) X) -> REAL(k)
+   COSH(REAL(k) X) -> REAL(k)
+   SIN(REAL(k) X) -> REAL(k)
+   SINH(REAL(k) X) -> REAL(k)
+   TAN(REAL(k) X) -> REAL(k)
+   TANH(REAL(k) X) -> REAL(k)
+
+These ``COMPLEX`` versions of some of those functions, and the
+inverse hyperbolic functions, cannot be used as specific names.
+
+.. code-block::
+
+   ACOS(COMPLEX(k) X) -> COMPLEX(k)
+   ASIN(COMPLEX(k) X) -> COMPLEX(k)
+   ATAN(COMPLEX(k) X) -> COMPLEX(k)
+   ACOSH(REAL(k) X) -> REAL(k)
+   ACOSH(COMPLEX(k) X) -> COMPLEX(k)
+   ASINH(REAL(k) X) -> REAL(k)
+   ASINH(COMPLEX(k) X) -> COMPLEX(k)
+   ATANH(REAL(k) X) -> REAL(k)
+   ATANH(COMPLEX(k) X) -> COMPLEX(k)
+   COS(COMPLEX(k) X) -> COMPLEX(k)
+   COSH(COMPLEX(k) X) -> COMPLEX(k)
+   SIN(COMPLEX(k) X) -> COMPLEX(k)
+   SINH(COMPLEX(k) X) -> COMPLEX(k)
+   TAN(COMPLEX(k) X) -> COMPLEX(k)
+   TANH(COMPLEX(k) X) -> COMPLEX(k)
+
+Non-trigonometric elemental intrinsic functions, generic and specific
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These functions *can* be used as unrestricted specific names.
+
+.. code-block::
+
+   ABS(REAL(k) A) -> REAL(k) = SIGN(A, 0.0)
+   AIMAG(COMPLEX(k) Z) -> REAL(k) = Z%IM
+   AINT(REAL(k) A, KIND=k) -> REAL(KIND)
+   ANINT(REAL(k) A, KIND=k) -> REAL(KIND)
+   CONJG(COMPLEX(k) Z) -> COMPLEX(k) = CMPLX(Z%RE, -Z%IM)
+   DIM(REAL(k) X, REAL(k) Y) -> REAL(k) = X-MIN(X,Y)
+   DPROD(default REAL X, default REAL Y) -> DOUBLE PRECISION = DBLE(X)*DBLE(Y)
+   EXP(REAL(k) X) -> REAL(k)
+   INDEX(CHARACTER(k) STRING, CHARACTER(k) SUBSTRING, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
+   LEN(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n
+   LOG(REAL(k) X) -> REAL(k)
+   LOG10(REAL(k) X) -> REAL(k)
+   MOD(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k) = A-P*INT(A/P)
+   NINT(REAL(k) A, KIND=KIND(0)) -> INTEGER(KIND)
+   SIGN(REAL(k) A, REAL(k) B) -> REAL(k)
+   SQRT(REAL(k) X) -> REAL(k) = X ** 0.5
+
+These variants, however *cannot* be used as specific names without recourse to an alias
+from the following section:
+
+.. code-block::
+
+   ABS(INTEGER(k) A) -> INTEGER(k) = SIGN(A, 0)
+   ABS(COMPLEX(k) A) -> REAL(k) = HYPOT(A%RE, A%IM)
+   DIM(INTEGER(k) X, INTEGER(k) Y) -> INTEGER(k) = X-MIN(X,Y)
+   EXP(COMPLEX(k) X) -> COMPLEX(k)
+   LOG(COMPLEX(k) X) -> COMPLEX(k)
+   MOD(REAL(k) A, REAL(k) P) -> REAL(k) = A-P*INT(A/P)
+   SIGN(INTEGER(k) A, INTEGER(k) B) -> INTEGER(k)
+   SQRT(COMPLEX(k) X) -> COMPLEX(k)
+
+Unrestricted specific aliases for some elemental intrinsic functions with distinct names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+   ALOG(REAL X) -> REAL = LOG(X)
+   ALOG10(REAL X) -> REAL = LOG10(X)
+   AMOD(REAL A, REAL P) -> REAL = MOD(A, P)
+   CABS(COMPLEX A) = ABS(A)
+   CCOS(COMPLEX X) = COS(X)
+   CEXP(COMPLEX A) -> COMPLEX = EXP(A)
+   CLOG(COMPLEX X) -> COMPLEX = LOG(X)
+   CSIN(COMPLEX X) -> COMPLEX = SIN(X)
+   CSQRT(COMPLEX X) -> COMPLEX = SQRT(X)
+   CTAN(COMPLEX X) -> COMPLEX = TAN(X)
+   DABS(DOUBLE PRECISION A) -> DOUBLE PRECISION = ABS(A)
+   DACOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = ACOS(X)
+   DASIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ASIN(X)
+   DATAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN(X)
+   DATAN2(DOUBLE PRECISION Y, DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN2(Y, X)
+   DCOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = COS(X)
+   DCOSH(DOUBLE PRECISION X) -> DOUBLE PRECISION = COSH(X)
+   DDIM(DOUBLE PRECISION X, DOUBLE PRECISION Y) -> DOUBLE PRECISION = X-MIN(X,Y)
+   DEXP(DOUBLE PRECISION X) -> DOUBLE PRECISION = EXP(X)
+   DINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = AINT(A)
+   DLOG(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG(X)
+   DLOG10(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG10(X)
+   DMOD(DOUBLE PRECISION A, DOUBLE PRECISION P) -> DOUBLE PRECISION = MOD(A, P)
+   DNINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = ANINT(A)
+   DSIGN(DOUBLE PRECISION A, DOUBLE PRECISION B) -> DOUBLE PRECISION = SIGN(A, B)
+   DSIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = SIN(X)
+   DSINH(DOUBLE PRECISION X) -> DOUBLE PRECISION = SINH(X)
+   DSQRT(DOUBLE PRECISION X) -> DOUBLE PRECISION = SQRT(X)
+   DTAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = TAN(X)
+   DTANH(DOUBLE PRECISION X) -> DOUBLE PRECISION = TANH(X)
+   IABS(INTEGER A) -> INTEGER = ABS(A)
+   IDIM(INTEGER X, INTEGER Y) -> INTEGER = X-MIN(X,Y)
+   IDNINT(DOUBLE PRECISION A) -> INTEGER = NINT(A)
+   ISIGN(INTEGER A, INTEGER B) -> INTEGER = SIGN(A, B)
+
+Generic elemental intrinsic functions without specific names
+------------------------------------------------------------
+
+(No procedures after this point can be passed as actual arguments, used as
+pointer targets, or appear as specific procedures in generic interfaces.)
+
+Elemental conversions
+^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+   ACHAR(INTEGER(k) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1)
+   CEILING(REAL() A, KIND=KIND(0)) -> INTEGER(KIND)
+   CHAR(INTEGER(any) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1)
+   CMPLX(COMPLEX(k) X, KIND=KIND(0.0D0)) -> COMPLEX(KIND)
+   CMPLX(INTEGER or REAL or BOZ X, INTEGER or REAL or BOZ Y=0, KIND=KIND((0,0))) -> COMPLEX(KIND)
+   DBLE(INTEGER or REAL or COMPLEX or BOZ A) = REAL(A, KIND=KIND(0.0D0))
+   EXPONENT(REAL(any) X) -> default INTEGER
+   FLOOR(REAL(any) A, KIND=KIND(0)) -> INTEGER(KIND)
+   IACHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND)
+   ICHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND)
+   INT(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0)) -> INTEGER(KIND)
+   LOGICAL(LOGICAL(any) L, KIND=KIND(.TRUE.)) -> LOGICAL(KIND)
+   REAL(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0.0)) -> REAL(KIND)
+
+Other generic elemental intrinsic functions without specific names
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+N.B. ``BESSEL_JN(N1, N2, X)`` and ``BESSEL_YN(N1, N2, X)`` are categorized
+below with the *transformational* intrinsic functions.
+
+.. code-block::
+
+   BESSEL_J0(REAL(k) X) -> REAL(k)
+   BESSEL_J1(REAL(k) X) -> REAL(k)
+   BESSEL_JN(INTEGER(n) N, REAL(k) X) -> REAL(k)
+   BESSEL_Y0(REAL(k) X) -> REAL(k)
+   BESSEL_Y1(REAL(k) X) -> REAL(k)
+   BESSEL_YN(INTEGER(n) N, REAL(k) X) -> REAL(k)
+   ERF(REAL(k) X) -> REAL(k)
+   ERFC(REAL(k) X) -> REAL(k)
+   ERFC_SCALED(REAL(k) X) -> REAL(k)
+   FRACTION(REAL(k) X) -> REAL(k)
+   GAMMA(REAL(k) X) -> REAL(k)
+   HYPOT(REAL(k) X, REAL(k) Y) -> REAL(k) = SQRT(X*X+Y*Y) without spurious overflow
+   IMAGE_STATUS(INTEGER(any) IMAGE [, scalar TEAM_TYPE TEAM ]) -> default INTEGER
+   IS_IOSTAT_END(INTEGER(any) I) -> default LOGICAL
+   IS_IOSTAT_EOR(INTEGER(any) I) -> default LOGICAL
+   LOG_GAMMA(REAL(k) X) -> REAL(k)
+   MAX(INTEGER(k) ...) -> INTEGER(k)
+   MAX(REAL(k) ...) -> REAL(k)
+   MAX(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...)))
+   MERGE(any type TSOURCE, same type FSOURCE, LOGICAL(any) MASK) -> type of FSOURCE
+   MIN(INTEGER(k) ...) -> INTEGER(k)
+   MIN(REAL(k) ...) -> REAL(k)
+   MIN(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...)))
+   MODULO(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k); P*result >= 0
+   MODULO(REAL(k) A, REAL(k) P) -> REAL(k) = A - P*FLOOR(A/P)
+   NEAREST(REAL(k) X, REAL(any) S) -> REAL(k)
+   OUT_OF_RANGE(INTEGER(any) X, scalar INTEGER or REAL(k) MOLD) -> default LOGICAL
+   OUT_OF_RANGE(REAL(any) X, scalar REAL(k) MOLD) -> default LOGICAL
+   OUT_OF_RANGE(REAL(any) X, scalar INTEGER(any) MOLD, scalar LOGICAL(any) ROUND=.FALSE.) -> default LOGICAL
+   RRSPACING(REAL(k) X) -> REAL(k)
+   SCALE(REAL(k) X, INTEGER(any) I) -> REAL(k)
+   SET_EXPONENT(REAL(k) X, INTEGER(any) I) -> REAL(k)
+   SPACING(REAL(k) X) -> REAL(k)
+
+Restricted specific aliases for elemental conversions &/or extrema with default intrinsic types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+   AMAX0(INTEGER ...) = REAL(MAX(...))
+   AMAX1(REAL ...) = MAX(...)
+   AMIN0(INTEGER...) = REAL(MIN(...))
+   AMIN1(REAL ...) = MIN(...)
+   DMAX1(DOUBLE PRECISION ...) = MAX(...)
+   DMIN1(DOUBLE PRECISION ...) = MIN(...)
+   FLOAT(INTEGER I) = REAL(I)
+   IDINT(DOUBLE PRECISION A) = INT(A)
+   IFIX(REAL A) = INT(A)
+   MAX0(INTEGER ...) = MAX(...)
+   MAX1(REAL ...) = INT(MAX(...))
+   MIN0(INTEGER ...) = MIN(...)
+   MIN1(REAL ...) = INT(MIN(...))
+   SNGL(DOUBLE PRECISION A) = REAL(A)
+
+Generic elemental bit manipulation intrinsic functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Many of these accept a typeless "BOZ" literal as an actual argument.
+It is interpreted as having the kind of intrinsic ``INTEGER`` type
+as another argument, as if the typeless were implicitly wrapped
+in a call to ``INT()``.
+When multiple arguments can be either ``INTEGER`` values or typeless
+constants, it is forbidden for *all* of them to be typeless
+constants if the result of the function is ``INTEGER``
+(i.e., only ``BGE``\ , ``BGT``\ , ``BLE``\ , and ``BLT`` can have multiple
+typeless arguments).
+
+.. code-block::
+
+   BGE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
+   BGT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
+   BLE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
+   BLT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
+   BTEST(INTEGER(n1) I, INTEGER(n2) POS) -> default LOGICAL
+   DSHIFTL(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k)
+   DSHIFTL(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k)
+   DSHIFTR(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k)
+   DSHIFTR(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k)
+   IAND(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
+   IAND(BOZ I, INTEGER(k) J) -> INTEGER(k)
+   IBCLR(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k)
+   IBITS(INTEGER(k) I, INTEGER(n1) POS, INTEGER(n2) LEN) -> INTEGER(k)
+   IBSET(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k)
+   IEOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
+   IEOR(BOZ I, INTEGER(k) J) -> INTEGER(k)
+   IOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
+   IOR(BOZ I, INTEGER(k) J) -> INTEGER(k)
+   ISHFT(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
+   ISHFTC(INTEGER(k) I, INTEGER(n1) SHIFT, INTEGER(n2) SIZE=BIT_SIZE(I)) -> INTEGER(k)
+   LEADZ(INTEGER(any) I) -> default INTEGER
+   MASKL(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND)
+   MASKR(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND)
+   MERGE_BITS(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK)))
+   MERGE_BITS(BOZ I, INTEGER(k) J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK)))
+   NOT(INTEGER(k) I) -> INTEGER(k)
+   POPCNT(INTEGER(any) I) -> default INTEGER
+   POPPAR(INTEGER(any) I) -> default INTEGER = IAND(POPCNT(I), Z'1')
+   SHIFTA(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
+   SHIFTL(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
+   SHIFTR(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
+   TRAILZ(INTEGER(any) I) -> default INTEGER
+
+Character elemental intrinsic functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See also ``INDEX`` and ``LEN`` above among the elemental intrinsic functions with
+unrestricted specific names.
+
+.. code-block::
+
+   ADJUSTL(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n)
+   ADJUSTR(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n)
+   LEN_TRIM(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n
+   LGE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
+   LGT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
+   LLE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
+   LLT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
+   SCAN(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
+   VERIFY(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
+
+``SCAN`` returns the index of the first (or last, if ``BACK=.TRUE.``\ ) character in ``STRING``
+that is present in ``SET``\ , or zero if none is.
+
+``VERIFY`` is essentially the opposite: it returns the index of the first (or last) character
+in ``STRING`` that is *not* present in ``SET``\ , or zero if all are.
+
+Transformational intrinsic functions
+====================================
+
+This category comprises a large collection of intrinsic functions that
+are collected together because they somehow transform their arguments
+in a way that prevents them from being elemental.
+All of them are pure, however.
+
+Some general rules apply to the transformational intrinsic functions:
+
+
+#. ``DIM`` arguments are optional; if present, the actual argument must be
+   a scalar integer of any kind.
+#. When an optional ``DIM`` argument is absent, or an ``ARRAY`` or ``MASK``
+   argument is a vector, the result of the function is scalar; otherwise,
+   the result is an array of the same shape as the ``ARRAY`` or ``MASK``
+   argument with the dimension ``DIM`` removed from the shape.
+#. When a function takes an optional ``MASK`` argument, it must be conformable
+   with its ``ARRAY`` argument if it is present, and the mask can be any kind
+   of ``LOGICAL``.  It can be scalar.
+#. The type ``numeric`` here can be any kind of ``INTEGER``\ , ``REAL``\ , or ``COMPLEX``.
+#. The type ``relational`` here can be any kind of ``INTEGER``\ , ``REAL``\ , or ``CHARACTER``.
+#. The type ``any`` here denotes any intrinsic or derived type.
+#. The notation ``(..)`` denotes an array of any rank (but not an assumed-rank array).
+
+Logical reduction transformational intrinsic functions
+------------------------------------------------------
+
+.. code-block::
+
+   ALL(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
+   ANY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
+   COUNT(LOGICAL(any) MASK(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
+   PARITY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
+
+Numeric reduction transformational intrinsic functions
+------------------------------------------------------
+
+.. code-block::
+
+   IALL(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
+   IANY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
+   IPARITY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
+   NORM2(REAL(k) X(..) [, DIM ]) -> REAL(k)
+   PRODUCT(numeric ARRAY(..) [, DIM, MASK ]) -> numeric
+   SUM(numeric ARRAY(..) [, DIM, MASK ]) -> numeric
+
+``NORM2`` generalizes ``HYPOT`` by computing ``SQRT(SUM(X*X))`` while avoiding spurious overflows.
+
+Extrema reduction transformational intrinsic functions
+------------------------------------------------------
+
+.. code-block::
+
+   MAXVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k)
+   MINVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k)
+
+Locational transformational intrinsic functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the optional ``DIM`` argument is absent, the result is an ``INTEGER(KIND)``
+vector whose length is the rank of ``ARRAY``.
+When the optional ``DIM`` argument is present, the result is an ``INTEGER(KIND)``
+array of rank ``RANK(ARRAY)-1`` and shape equal to that of ``ARRAY`` with
+the dimension ``DIM`` removed.
+
+The optional ``BACK`` argument is a scalar LOGICAL value of any kind.
+When present and ``.TRUE.``\ , it causes the function to return the index
+of the *last* occurence of the target or extreme value.
+
+For ``FINDLOC``\ , ``ARRAY`` may have any of the five intrinsic types, and ``VALUE``
+must a scalar value of a type for which ``ARRAY==VALUE`` or ``ARRAY .EQV. VALUE``
+is an acceptable expression.
+
+.. code-block::
+
+   FINDLOC(intrinsic ARRAY(..), scalar VALUE [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
+   MAXLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
+   MINLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
+
+Data rearrangement transformational intrinsic functions
+-------------------------------------------------------
+
+The optional ``DIM`` argument to these functions must be a scalar integer of
+any kind, and it takes a default value of 1 when absent.
+
+.. code-block::
+
+   CSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, DIM ]) -> same type/kind/shape as ARRAY
+
+Either ``SHIFT`` is scalar or ``RANK(SHIFT) == RANK(ARRAY) - 1`` and ``SHAPE(SHIFT)`` is that of ``SHAPE(ARRAY)`` with element ``DIM`` removed.
+
+.. code-block::
+
+   EOSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, BOUNDARY, DIM ]) -> same type/kind/shape as ARRAY
+
+
+* ``SHIFT`` is scalar or ``RANK(SHIFT) == RANK(ARRAY) - 1`` and ``SHAPE(SHIFT)`` is that of ``SHAPE(ARRAY)`` with element ``DIM`` removed.
+* If ``BOUNDARY`` is present, it must have the same type and parameters as ``ARRAY``.
+* If ``BOUNDARY`` is absent, ``ARRAY`` must be of an intrinsic type, and the default ``BOUNDARY`` is the obvious ``0``\ , ``' '``\ , or ``.FALSE.`` value of ``KIND(ARRAY)``.
+* If ``BOUNDARY`` is present, either it is scalar, or ``RANK(BOUNDARY) == RANK(ARRAY) - 1`` and ``SHAPE(BOUNDARY)`` is that of ``SHAPE(ARRAY)`` with element ``DIM``
+  removed.
+
+.. code-block::
+
+   PACK(any ARRAY(..), LOGICAL(any) MASK(..)) -> vector of same type and kind as ARRAY
+
+
+* ``MASK`` is conformable with ``ARRAY`` and may be scalar.
+* The length of the result vector is ``COUNT(MASK)`` if ``MASK`` is an array, else ``SIZE(ARRAY)`` if ``MASK`` is ``.TRUE.``\ , else zero.
+
+.. code-block::
+
+   PACK(any ARRAY(..), LOGICAL(any) MASK(..), any VECTOR(n)) -> vector of same type, kind, and size as VECTOR
+
+
+* ``MASK`` is conformable with ``ARRAY`` and may be scalar.
+* ``VECTOR`` has the same type and kind as ``ARRAY``.
+* ``VECTOR`` must not be smaller than result of ``PACK`` with no ``VECTOR`` argument.
+* The leading elements of ``VECTOR`` are replaced with elements from ``ARRAY`` as
+  if ``PACK`` had been invoked without ``VECTOR``.
+
+.. code-block::
+
+   RESHAPE(any SOURCE(..), INTEGER(k) SHAPE(n) [, PAD(..), INTEGER(k2) ORDER(n) ]) -> SOURCE array with shape SHAPE
+
+
+* If ``ORDER`` is present, it is a vector of the same size as ``SHAPE``\ , and
+  contains a permutation.
+* The element(s) of ``PAD`` are used to fill out the result once ``SOURCE``
+  has been consumed.
+
+.. code-block::
+
+   SPREAD(any SOURCE, DIM, scalar INTEGER(any) NCOPIES) -> same type as SOURCE, rank=RANK(SOURCE)+1
+   TRANSFER(any SOURCE, any MOLD) -> scalar if MOLD is scalar, else vector; same type and kind as MOLD
+   TRANSFER(any SOURCE, any MOLD, scalar INTEGER(any) SIZE) -> vector(SIZE) of type and kind of MOLD
+   TRANSPOSE(any MATRIX(n,m)) -> matrix(m,n) of same type and kind as MATRIX
+
+The shape of the result of ``SPREAD`` is the same as that of ``SOURCE``\ , with ``NCOPIES`` inserted
+at position ``DIM``.
+
+.. code-block::
+
+   UNPACK(any VECTOR(n), LOGICAL(any) MASK(..), FIELD) -> type and kind of VECTOR, shape of MASK
+
+``FIELD`` has same type and kind as ``VECTOR`` and is conformable with ``MASK``.
+
+Other transformational intrinsic functions
+------------------------------------------
+
+.. code-block::
+
+   BESSEL_JN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0))
+   BESSEL_YN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0))
+   COMMAND_ARGUMENT_COUNT() -> scalar default INTEGER
+   DOT_PRODUCT(LOGICAL(k) VECTOR_A(n), LOGICAL(k) VECTOR_B(n)) -> LOGICAL(k) = ANY(VECTOR_A .AND. VECTOR_B)
+   DOT_PRODUCT(COMPLEX(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(CONJG(VECTOR_A) * VECTOR_B)
+   DOT_PRODUCT(INTEGER(any) or REAL(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(VECTOR_A * VECTOR_B)
+   MATMUL(numeric ARRAY_A(j), numeric ARRAY_B(j,k)) -> numeric vector(k)
+   MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k)) -> numeric vector(j)
+   MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k,m)) -> numeric matrix(j,m)
+   MATMUL(LOGICAL(n1) ARRAY_A(j), LOGICAL(n2) ARRAY_B(j,k)) -> LOGICAL vector(k)
+   MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k)) -> LOGICAL vector(j)
+   MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k,m)) -> LOGICAL matrix(j,m)
+   NULL([POINTER/ALLOCATABLE MOLD]) -> POINTER
+   REDUCE(any ARRAY(..), function OPERATION [, DIM, LOGICAL(any) MASK(..), IDENTITY, LOGICAL ORDERED=.FALSE. ])
+   REPEAT(CHARACTER(k,n) STRING, INTEGER(any) NCOPIES) -> CHARACTER(k,n*NCOPIES)
+   SELECTED_CHAR_KIND('DEFAULT' or 'ASCII' or 'ISO_10646' or ...) -> scalar default INTEGER
+   SELECTED_INT_KIND(scalar INTEGER(any) R) -> scalar default INTEGER
+   SELECTED_REAL_KIND([scalar INTEGER(any) P, scalar INTEGER(any) R, scalar INTEGER(any) RADIX]) -> scalar default INTEGER
+   SHAPE(SOURCE, KIND=KIND(0)) -> INTEGER(KIND)(RANK(SOURCE))
+   TRIM(CHARACTER(k,n) STRING) -> CHARACTER(k)
+
+The type and kind of the result of a numeric ``MATMUL`` is the same as would result from
+a multiplication of an element of ARRAY_A and an element of ARRAY_B.
+
+The kind of the ``LOGICAL`` result of a ``LOGICAL`` ``MATMUL`` is the same as would result
+from an intrinsic ``.AND.`` operation between an element of ``ARRAY_A`` and an element
+of ``ARRAY_B``.
+
+Note that ``DOT_PRODUCT`` with a ``COMPLEX`` first argument operates on its complex conjugate,
+but that ``MATMUL`` with a ``COMPLEX`` argument does not.
+
+The ``MOLD`` argument to ``NULL`` may be omitted only in a context where the type of the pointer is known,
+such as an initializer or pointer assignment statement.
+
+At least one argument must be present in a call to ``SELECTED_REAL_KIND``.
+
+An assumed-rank array may be passed to ``SHAPE``\ , and if it is associated with an assumed-size array,
+the last element of the result will be -1.
+
+Coarray transformational intrinsic functions
+--------------------------------------------
+
+.. code-block::
+
+   FAILED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector
+   GET_TEAM([scalar INTEGER(?) LEVEL]) -> scalar TEAM_TYPE
+   IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n) [, scalar TEAM_TYPE TEAM ]) -> scalar default INTEGER
+   IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n), scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER
+   NUM_IMAGES([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER
+   NUM_IMAGES(scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER
+   STOPPED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector
+   TEAM_NUMBER([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER
+   THIS_IMAGE([COARRAY, DIM, scalar TEAM_TYPE TEAM]) -> default INTEGER
+
+The result of ``THIS_IMAGE`` is a scalar if ``DIM`` is present or if ``COARRAY`` is absent,
+and a vector whose length is the corank of ``COARRAY`` otherwise.
+
+Inquiry intrinsic functions
+===========================
+
+These are neither elemental nor transformational; all are pure.
+
+Type inquiry intrinsic functions
+--------------------------------
+
+All of these functions return constants.
+The value of the argument is not used, and may well be undefined.
+
+.. code-block::
+
+   BIT_SIZE(INTEGER(k) I(..)) -> INTEGER(k)
+   DIGITS(INTEGER or REAL X(..)) -> scalar default INTEGER
+   EPSILON(REAL(k) X(..)) -> scalar REAL(k)
+   HUGE(INTEGER(k) X(..)) -> scalar INTEGER(k)
+   HUGE(REAL(k) X(..)) -> scalar of REAL(k)
+   KIND(intrinsic X(..)) -> scalar default INTEGER
+   MAXEXPONENT(REAL(k) X(..)) -> scalar default INTEGER
+   MINEXPONENT(REAL(k) X(..)) -> scalar default INTEGER
+   NEW_LINE(CHARACTER(k,n) A(..)) -> scalar CHARACTER(k,1) = CHAR(10)
+   PRECISION(REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER
+   RADIX(INTEGER(k) or REAL(k) X(..)) -> scalar default INTEGER, always 2
+   RANGE(INTEGER(k) or REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER
+   TINY(REAL(k) X(..)) -> scalar REAL(k)
+
+Bound and size inquiry intrinsic functions
+------------------------------------------
+
+The results are scalar when ``DIM`` is present, and a vector of length=(co)rank(\ ``(CO)ARRAY``\ )
+when ``DIM`` is absent.
+
+.. code-block::
+
+   LBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
+   LCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
+   SIZE(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
+   UBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
+   UCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
+
+Assumed-rank arrays may be used with ``LBOUND``\ , ``SIZE``\ , and ``UBOUND``.
+
+Object characteristic inquiry intrinsic functions
+-------------------------------------------------
+
+.. code-block::
+
+   ALLOCATED(any type ALLOCATABLE ARRAY) -> scalar default LOGICAL
+   ALLOCATED(any type ALLOCATABLE SCALAR) -> scalar default LOGICAL
+   ASSOCIATED(any type POINTER POINTER [, same type TARGET]) -> scalar default LOGICAL
+   COSHAPE(COARRAY, KIND=KIND(0)) -> INTEGER(KIND) vector of length corank(COARRAY)
+   EXTENDS_TYPE_OF(A, MOLD) -> default LOGICAL
+   IS_CONTIGUOUS(any data ARRAY(..)) -> scalar default LOGICAL
+   PRESENT(OPTIONAL A) -> scalar default LOGICAL
+   RANK(any data A) -> scalar default INTEGER = 0 if A is scalar, SIZE(SHAPE(A)) if A is an array, rank if assumed-rank
+   SAME_TYPE_AS(A, B) -> scalar default LOGICAL
+   STORAGE_SIZE(any data A, KIND=KIND(0)) -> INTEGER(KIND)
+
+The arguments to ``EXTENDS_TYPE_OF`` must be of extensible derived types or be unlimited polymorphic.
+
+An assumed-rank array may be used with ``IS_CONTIGUOUS`` and ``RANK``.
+
+Intrinsic subroutines
+=====================
+
+(\ *TODO*\ : complete these descriptions)
+
+One elemental intrinsic subroutine
+----------------------------------
+
+.. code-block::
+
+   INTERFACE
+     SUBROUTINE MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)
+       INTEGER(k1) :: FROM, TO
+       INTENT(IN) :: FROM
+       INTENT(INOUT) :: TO
+       INTEGER(k2), INTENT(IN) :: FROMPOS
+       INTEGER(k3), INTENT(IN) :: LEN
+       INTEGER(k4), INTENT(IN) :: TOPOS
+     END SUBROUTINE
+   END INTERFACE
+
+Non-elemental intrinsic subroutines
+-----------------------------------
+
+.. code-block::
+
+   CALL CPU_TIME(REAL INTENT(OUT) TIME)
+
+The kind of ``TIME`` is not specified in the standard.
+
+.. code-block::
+
+   CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])
+
+
+* All arguments are ``OPTIONAL`` and ``INTENT(OUT)``.
+* ``DATE``\ , ``TIME``\ , and ``ZONE`` are scalar default ``CHARACTER``.
+* ``VALUES`` is a vector of at least 8 elements of ``INTEGER(KIND >= 2)``.
+  .. code-block::
+
+     CALL EVENT_QUERY(EVENT, COUNT [, STAT])
+     CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])
+     CALL GET_COMMAND([COMMAND, LENGTH, STATUS, ERRMSG ])
+     CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS, ERRMSG ])
+     CALL GET_ENVIRONMENT_VARIABLE(NAME [, VALUE, LENGTH, STATUS, TRIM_NAME, ERRMSG ])
+     CALL MOVE_ALLOC(ALLOCATABLE INTENT(INOUT) FROM, ALLOCATABLE INTENT(OUT) TO [, STAT, ERRMSG ])
+     CALL RANDOM_INIT(LOGICAL(k1) INTENT(IN) REPEATABLE, LOGICAL(k2) INTENT(IN) IMAGE_DISTINCT)
+     CALL RANDOM_NUMBER(REAL(k) INTENT(OUT) HARVEST(..))
+     CALL RANDOM_SEED([SIZE, PUT, GET])
+     CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])
+
+Atomic intrinsic subroutines
+----------------------------
+
+.. code-block::
+
+   CALL ATOMIC_ADD(ATOM, VALUE [, STAT=])
+   CALL ATOMIC_AND(ATOM, VALUE [, STAT=])
+   CALL ATOMIC_CAS(ATOM, OLD, COMPARE, NEW [, STAT=])
+   CALL ATOMIC_DEFINE(ATOM, VALUE [, STAT=])
+   CALL ATOMIC_FETCH_ADD(ATOM, VALUE, OLD [, STAT=])
+   CALL ATOMIC_FETCH_AND(ATOM, VALUE, OLD [, STAT=])
+   CALL ATOMIC_FETCH_OR(ATOM, VALUE, OLD [, STAT=])
+   CALL ATOMIC_FETCH_XOR(ATOM, VALUE, OLD [, STAT=])
+   CALL ATOMIC_OR(ATOM, VALUE [, STAT=])
+   CALL ATOMIC_REF(VALUE, ATOM [, STAT=])
+   CALL ATOMIC_XOR(ATOM, VALUE [, STAT=])
+
+Collective intrinsic subroutines
+--------------------------------
+
+.. code-block::
+
+   CALL CO_BROADCAST
+   CALL CO_MAX
+   CALL CO_MIN
+   CALL CO_REDUCE
+   CALL CO_SUM
+
+Non-standard intrinsics
+=======================
+
+PGI
+---
+
+.. code-block::
+
+   AND, OR, XOR
+   LSHIFT, RSHIFT, SHIFT
+   ZEXT, IZEXT
+   COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D
+   COMPL
+   DCMPLX
+   EQV, NEQV
+   INT8
+   JINT, JNINT, KNINT
+   LOC
+
+Intel
+-----
+
+.. code-block::
+
+   DCMPLX(X,Y), QCMPLX(X,Y)
+   DREAL(DOUBLE COMPLEX A) -> DOUBLE PRECISION
+   DFLOAT, DREAL
+   QEXT, QFLOAT, QREAL
+   DNUM, INUM, JNUM, KNUM, QNUM, RNUM - scan value from string
+   ZEXT
+   RAN, RANF
+   ILEN(I) = BIT_SIZE(I)
+   SIZEOF
+   MCLOCK, SECNDS
+   COTAN(X) = 1.0/TAN(X)
+   COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COTAND - degrees
+   AND, OR, XOR
+   LSHIFT, RSHIFT
+   IBCHNG, ISHA, ISHC, ISHL, IXOR
+   IARG, IARGC, NARGS, NUMARG
+   BADDRESS, IADDR
+   CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, LOC
+   MALLOC
+
+Intrinsic Procedure Support in f18
+==================================
+
+This section gives an overview of the support inside f18 libraries for the
+intrinsic procedures listed above.
+It may be outdated, refer to f18 code base for the actual support status.
+
+Semantic Analysis
+-----------------
+
+F18 semantic expression analysis phase detects intrinsic procedure references,
+validates the argument types and deduces the return types.
+This phase currently supports all the intrinsic procedures listed above but the ones in the table below.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Intrinsic Category
+     - Intrinsic Procedures Lacking Support
+   * - Coarray intrinsic functions
+     - LCOBOUND, UCOBOUND, FAILED_IMAGES, GET_TEAM, IMAGE_INDEX, STOPPED_IMAGES, TEAM_NUMBER, THIS_IMAGE, COSHAPE
+   * - Object characteristic inquiry functions
+     - ALLOCATED, ASSOCIATED, EXTENDS_TYPE_OF, IS_CONTIGUOUS, PRESENT, RANK, SAME_TYPE, STORAGE_SIZE
+   * - Type inquiry intrinsic functions
+     - BIT_SIZE, DIGITS, EPSILON, HUGE, KIND, MAXEXPONENT, MINEXPONENT, NEW_LINE, PRECISION, RADIX, RANGE, TINY
+   * - Non-standard intrinsic functions
+     - AND, OR, XOR, LSHIFT, RSHIFT, SHIFT, ZEXT, IZEXT, COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COMPL, DCMPLX, EQV, NEQV, INT8, JINT, JNINT, KNINT, LOC, QCMPLX, DREAL, DFLOAT, QEXT, QFLOAT, QREAL, DNUM, NUM, JNUM, KNUM, QNUM, RNUM, RAN, RANF, ILEN, SIZEOF, MCLOCK, SECNDS, COTAN, IBCHNG, ISHA, ISHC, ISHL, IXOR, IARG, IARGC, NARGS, NUMARG, BADDRESS, IADDR, CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, MALLOC
+   * - Intrinsic subroutines
+     - MVBITS (elemental), CPU_TIME, DATE_AND_TIME, EVENT_QUERY, EXECUTE_COMMAND_LINE, GET_COMMAND, GET_COMMAND_ARGUMENT, GET_ENVIRONMENT_VARIABLE, MOVE_ALLOC, RANDOM_INIT, RANDOM_NUMBER, RANDOM_SEED, SYSTEM_CLOCK
+   * - Atomic intrinsic subroutines
+     - ATOMIC_ADD &al.
+   * - Collective intrinsic subroutines
+     - CO_BROADCAST &al.
+
+
+Intrinsic Function Folding
+--------------------------
+
+Fortran Constant Expressions can contain references to a certain number of
+intrinsic functions (see Fortran 2018 standard section 10.1.12 for more details).
+Constant Expressions may be used to define kind arguments. Therefore, the semantic
+expression analysis phase must be able to fold references to intrinsic functions
+listed in section 10.1.12.
+
+F18 intrinsic function folding is either performed by implementations directly
+operating on f18 scalar types or by using host runtime functions and
+host hardware types. F18 supports folding elemental intrinsic functions over
+arrays when an implementation is provided for the scalars (regardless of whether
+it is using host hardware types or not).
+The status of intrinsic function folding support is given in the sub-sections below.
+
+Intrinsic Functions with Host Independent Folding Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Implementations using f18 scalar types enables folding intrinsic functions
+on any host and with any possible type kind supported by f18. The intrinsic functions
+listed below are folded using host independent implementations.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Return Type
+     - Intrinsic Functions with Host Independent Folding Support
+   * - INTEGER
+     - ABS(INTEGER(k)), DIM(INTEGER(k), INTEGER(k)), DSHIFTL, DSHIFTR, IAND, IBCLR, IBSET, IEOR, INT, IOR, ISHFT, KIND, LEN, LEADZ, MASKL, MASKR, MERGE_BITS, POPCNT, POPPAR, SHIFTA, SHIFTL, SHIFTR, TRAILZ
+   * - REAL
+     - ABS(REAL(k)), ABS(COMPLEX(k)), AIMAG, AINT, DPROD, REAL
+   * - COMPLEX
+     - CMPLX, CONJG
+   * - LOGICAL
+     - BGE, BGT, BLE, BLT
+
+
+Intrinsic Functions with Host Dependent Folding Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Implementations using the host runtime may not be available for all supported
+f18 types depending on the host hardware types and the libraries available on the host.
+The actual support on a host depends on what the host hardware types are.
+The list below gives the functions that are folded using host runtime and the related C/C++ types.
+F18 automatically detects if these types match an f18 scalar type. If so,
+folding of the intrinsic functions will be possible for the related f18 scalar type,
+otherwise an error message will be produced by f18 when attempting to fold related intrinsic functions.
+
+.. list-table::
+   :header-rows: 1
+
+   * - C/C++ Host Type
+     - Intrinsic Functions with Host Standard C++ Library Based Folding Support
+   * - float, double and long double
+     - ACOS, ACOSH, ASINH, ATAN, ATAN2, ATANH, COS, COSH, ERF, ERFC, EXP, GAMMA, HYPOT, LOG, LOG10, LOG_GAMMA, MOD, SIN, SQRT, SINH, SQRT, TAN, TANH
+   * - std::complex for float, double and long double
+     - ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH, COS, COSH, EXP, LOG, SIN, SINH, SQRT, TAN, TANH
+
+
+On top of the default usage of C++ standard library functions for folding described
+in the table above, it is possible to compile f18 evaluate library with
+`libpgmath <https://github.com/flang-compiler/flang/tree/master/runtime/libpgmath>`_
+so that it can be used for folding. To do so, one must have a compiled version
+of the libpgmath library available on the host and add
+``-DLIBPGMATH_DIR=<path to the compiled shared libpgmath library>`` to the f18 cmake command.
+
+Libpgmath comes with real and complex functions that replace C++ standard library
+float and double functions to fold all the intrinsic functions listed in the table above.
+It has no long double versions. If the host long double matches an f18 scalar type,
+C++ standard library functions will still be used for folding expressions with this scalar type.
+Libpgmath adds the possibility to fold the following functions for f18 real scalar
+types related to host float and double types.
+
+.. list-table::
+   :header-rows: 1
+
+   * - C/C++ Host Type
+     - Additional Intrinsic Function Folding Support with Libpgmath (Optional)
+   * - float and double
+     - BESSEL_J0, BESSEL_J1, BESSEL_JN (elemental only), BESSEL_Y0, BESSEL_Y1, BESSEL_Yn (elemental only), ERFC_SCALED
+
+
+Libpgmath comes in three variants (precise, relaxed and fast). So far, only the
+precise version is used for intrinsic function folding in f18. It guarantees the greatest numerical precision.
+
+Intrinsic Functions with Missing Folding Support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following intrinsic functions are allowed in constant expressions but f18
+is not yet able to fold them. Note that there might be constraints on the arguments
+so that these intrinsics can be used in constant expressions (see section 10.1.12 of Fortran 2018 standard).
+
+ALL, ACHAR, ADJUSTL, ADJUSTR, ANINT, ANY, BESSEL_JN (transformational only),
+BESSEL_YN (transformational only), BTEST, CEILING, CHAR, COUNT, CSHIFT, DOT_PRODUCT,
+DIM (REAL only), DOT_PRODUCT, EOSHIFT, FINDLOC, FLOOR, FRACTION, HUGE, IACHAR, IALL,
+IANY, IPARITY, IBITS, ICHAR, IMAGE_STATUS, INDEX, ISHFTC, IS_IOSTAT_END,
+IS_IOSTAT_EOR, LBOUND, LEN_TRIM, LGE, LGT, LLE, LLT, LOGICAL, MATMUL, MAX, MAXLOC,
+MAXVAL, MERGE, MIN, MINLOC, MINVAL, MOD (INTEGER only), MODULO, NEAREST, NINT,
+NORM2, NOT, OUT_OF_RANGE, PACK, PARITY, PRODUCT, REPEAT, REDUCE, RESHAPE,
+RRSPACING, SCAN, SCALE, SELECTED_CHAR_KIND, SELECTED_INT_KIND, SELECTED_REAL_KIND,
+SET_EXPONENT, SHAPE, SIGN, SIZE, SPACING, SPREAD, SUM, TINY, TRANSFER, TRANSPOSE,
+TRIM, UBOUND, UNPACK, VERIFY.
+
+Coarray, non standard, IEEE and ISO_C_BINDINGS intrinsic functions that can be
+used in constant expressions have currently no folding support at all.

flang/docs/LabelResolution.rst

+Semantics: Resolving Labels and Construct Names
+===============================================
+
+Overview
+--------
+
+After the Fortran input file(s) has been parsed into a syntax tree, the compiler must check that the program checks semantically.  Target labels must be checked and violations of legal semantics should be reported to the user.
+
+This is the detailed design document on how these labels will be semantically checked.  Legal semantics may result in rewrite operations on the syntax tree.  Semantics violations will be reported as errors to the user.
+
+Requirements
+------------
+
+
+* Input: a parse tree that decomposes the Fortran program unit
+* Output:
+
+  * **Success** returns true
+    (Additionally, the parse tree may be rewritten on success to capture the nested DO loop structure explicitly from any *label-do-stmt* type loops.)
+  * **Failure** returns false, instantiates (a container of) error message(s) to indicate the problem(s)
+
+Label generalities (6.2.5)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enforcement of the general label constraints.  There are three sorts of label usage. Labels can serve 
+
+
+#. as a *label-do-stmt* block range marker
+#. as branching (control flow) targets
+#. as specification annotations (\ ``FORMAT`` statements) for data transfer statements (I/O constructs)
+
+Labels are related to the standard definition of inclusive scope.  For example, control-flow arcs are not allowed to originate from one inclusive scope and target statements outside of that inclusive scope.
+
+Inclusive scope is defined as a tree structure of nested scoping constructs. A statement, *s*\ , is said to be *in* the same inclusive scope as another statement, *t*\ , if and only if *s* and *t* are in the same scope or *t* is in one of the enclosing scopes of *s*\ , otherwise *s* is *not in* the same inclusive scope as *t*. (Inclusive scope is unidirectional and is always from innermost scopes to outermost scopes.)
+
+Semantic Checks
+~~~~~~~~~~~~~~~
+
+
+* labels range from 1 to 99999, inclusive (6.2.5 note 2)
+
+  * handled automatically by the parser, but add a range check
+
+* labels must be pairwise distinct within their program unit scope (6.2.5 para 2)
+
+  * if redundant labels appear → error redundant labels
+  * the total number of unique statement labels may have a limit
+
+Labels Used for ``DO`` Loop Ranging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*label-do-stmt* (R1121)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A *label-do-stmt* is a control construct that results in the iterative execution of a number of statements.  A *label-do-stmt* has a (possibly shared, *nonblock-do-construct*\ ) *label* that will be called the loop target label.  The statements to be executed will be the range from the *label-do-stmt* to the statement identified by the loop target label, inclusive. This range of statements will be called the loop's body and logically forms a *do-block*.
+
+A *label-do-stmt* is quite similar to a *block-do-construct* in semantics, but the parse tree is different in that the parser does not impose a *do-block* structure on the loop body.
+
+In F18, the nonblock ``DO`` construct has been removed.  For legacy support (through F08), we will need to handle nonblock ``DO`` constructs.  In F18, the following legacy code is an error.
+
+.. code-block:: fortran
+
+     DO 100 I = 1, 100
+       DO 100 J = 1, 100
+         ...
+    100 CONTINUE
+
+Semantic Checks
+"""""""""""""""
+
+
+* the loop body target label must exist in the scope (F18:C1133; F08:C815, C817, C819)
+
+  * if the label does not appear, error of missing label
+
+* the loop body target label must be, lexically, after the *label-do-stmt* (R1119)
+
+  * if the label appears lexically preceding the ``DO``\ , error of malformed ``DO``
+
+* control cannot transfer into the body from outside the *do-block*
+
+  * Exceptions (errors demoted to warnings)
+
+    * some implementations relax enforcement of this and allow ``GOTO``\ s from the loop body to "extended ranges" and back again (PGI & gfortan appear to allow, NAG & Intel do not.)
+    * should some form of "extended ranges" for *do-constructs* be supported, it should still be limited and not include parallel loops such as ``DO CONCURRENT`` or loops annotated with OpenACC or OpenMP directives.
+
+  * ``GOTO``\ s into the ``DO``\ s inclusive scope, error/warn of invalid transfer of control
+
+* requires that the loop terminating statement for a *label-do-stmt* be either an ``END DO`` or a ``CONTINUE``
+
+  * Exception
+
+    * earlier standards allowed other statements to be terminators
+
+Semantics for F08 and earlier that support sharing the loop terminating statement in a *nonblock-do-construct* between multiple loops
+
+
+* some statements cannot be *do-term-action-stmt* (F08:C816)
+
+  * a *do-term-action-stmt* is an *action-stmt* but does not include *arithmetic-if-stmt*\ , *continue-stmt*\ , *cycle-stmt*\ , *end-function-stmt*\ , *end-mp-subprogram-stmt*\ , *end-program-stmt*\ , *end-subroutine-stmt*\ , *error-stop-stmt*\ , *exit-stmt*\ , *goto-stmt*\ , *return-stmt*\ , or *stop-stmt*
+
+    * if the term action statement is forbidden, error invalid statement in ``DO`` loop term position
+
+* some statements cannot be *do-term-shared-stmt* (F08:C818)
+
+  * this is the case as in our above example where two different nested loops share the same terminating statement (\ ``100 continue``\ )
+  * a *do-term-shared-stmt* is an *action-stmt* with all the same exclusions as a *do-term-action-stmt* except a *continue-stmt* **is** allowed
+
+    * if the term shared action statement is forbidden, error invalid statement in term position
+
+If the ``DO`` loop is a ``DO CONCURRENT`` construct, there are additional constraints (11.1.7.5).
+
+
+* a *return-stmt* is not allowed (C1136)
+* image control statements are not allowed (C1137)
+* branches must be from a statement and to a statement that both reside within the ``DO CONCURRENT`` (C1138)
+* impure procedures shall not be called (C1139)
+* deallocation of polymorphic objects is not allowed (C1140)
+* references to ``IEEE_GET_FLAG``\ , ``IEEE_SET_HALTING_MODE``\ , and ``IEEE_GET_HALTING_MODE`` cannot appear in the body of a ``DO CONCURRENT`` (C1141)
+* the use of the ``ADVANCE=`` specifier by an I/O statement in the body of a ``DO CONCURRENT`` is not allowed (11.1.7.5, para 5)
+
+Labels Used in Branching
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+*goto-stmt* (11.2.2, R1157)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ``GOTO`` statement is a simple, direct transfer of control from the ``GOTO`` to the labelled statement.
+
+Semantic Checks
+"""""""""""""""
+
+
+* the labelled statement that is the target of a ``GOTO`` (11.2.1 constraints)
+
+  * must refer to a label that is in inclusive scope of the computed ``GOTO`` statement (C1169)
+
+    * if a label does not exist, error nonexistent label
+    * if a label is out of scope, error out of inclusive scope
+
+  * the branch target statement must be valid
+
+    * if the statement is not allowed as a branch target, error not a valid branch target
+
+* the labelled statement must be a branch target statement
+
+  * a branch target statement is any of *action-stmt*\ , *associate-stmt*\ , *end-associate-stmt*\ , *if-then-stmt*\ , *end-if-stmt*\ , *select-case-stmt*\ , *end-select-stmt*\ , *select-rank-stmt*\ , *end-select-rank-stmt*\ , *select-type-stmt*\ , *end-select-type-stmt*\ , *do-stmt*\ , *end-do-stmt*\ , *block-stmt*\ , *end-block-stmt*\ , *critical-stmt*\ , *end-critical-stmt*\ , *forall-construct-stmt*\ , *forall-stmt*\ , *where-construct-stmt*\ , *end-function-stmt*\ , *end-mp-subprogram-stmt*\ , *end-program-stmt*\ , or *end-subroutine-stmt*. (11.2.1)
+  * Some deleted features that were *action-stmt* in older standards include *arithmetic-if-stmt*\ , *assign-stmt*\ , *assigned-goto-stmt*\ , and *pause-stmt*. For legacy mode support, these statements should be considered *action-stmt*.
+
+*computed-goto-stmt* (11.2.3, R1158)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The computed ``GOTO`` statement is analogous to a ``switch`` statement in C++.
+
+.. code-block:: fortran
+
+     GOTO ( label-list ) [,] scalar-int-expr
+
+Semantics Checks
+""""""""""""""""
+
+
+* each label in *label-list* (11.2.1 constraints, same as ``GOTO``\ )
+
+  * must refer to a label that is in inclusive scope of the computed ``GOTO`` statement (C1170)
+
+    * if a label does not exist, error nonexistent label
+    * if a label is out of scope, error out of inclusive scope
+
+  * the branch target statement must be valid
+
+    * if the statement is not allowed as a branch target, error not a valid branch target
+
+* the *scalar-int-expr* needs to have ``INTEGER`` type
+
+  * check the type of the expression (type checking done elsewhere)
+
+R853 *arithmetic-if-stmt* (F08:8.2.4)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This control-flow construct is deleted in F18.
+
+.. code-block:: fortran
+
+     IF (scalar-numeric-expr) label1,label2,label3
+
+The arithmetic if statement is like a three-way branch operator. If the scalar numeric expression is less than zero goto *label-1*\ , else if the variable is equal to zero goto *label-2*\ , else if the variable is greater than zero goto *label-3*.
+
+Semantics Checks
+""""""""""""""""
+
+
+* the labels in the *arithmetic-if-stmt* triple must all be present in the inclusive scope (F08:C848)
+
+  * if a label does not exist, error nonexistent label
+  * if a label is out of scope, error out of inclusive scope
+
+* the *scalar-numeric-expr* must not be ``COMPLEX`` (F08:C849)
+
+  * check the type of the expression (type checking done elsewhere)
+
+*alt-return-spec* (15.5.1, R1525)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are a Fortran control-flow construct for combining a return from a subroutine with a branch to a labelled statement in the calling routine all in one operation. A typical implementation is for the subroutine to return a hidden integer, which is used as a key in the calling code to then, possibly, branch to a labelled statement in inclusive scope.
+
+The labels are passed by the calling routine. We want to check those labels at the call-site, that is instances of *alt-return-spec*.
+
+Semantics Checks
+""""""""""""""""
+
+
+* each *alt-return-spec* (11.2.1 constraints, same as ``GOTO``\ )
+
+  * must refer to a label that is in inclusive scope of the ``CALL`` statement
+
+    * if a label does not exist, error nonexistent label
+    * if a label is out of scope, error out of inclusive scope
+
+  * the branch target statement must be valid
+
+    * if the statement is not allowed as a branch target, error not a valid branch target
+
+**END**\ , **EOR**\ , **ERR** specifiers (12.11)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These specifiers can appear in I/O statements and can transfer control to specific labelled statements under exceptional conditions like end-of-file, end-of-record, and other error conditions.  (The PGI compiler adds code to test the results from the runtime routines to determine if these branches should take place.)
+
+Semantics Checks
+""""""""""""""""
+
+
+* each END, EOR, and ERR specifier (11.2.1 constraints, same as ``GOTO``\ )
+
+  * must refer to a label that is in inclusive scope of the I/O statement
+
+    * if a label does not exist, error nonexistent label
+    * if a label is out of scope, error out of inclusive scope
+
+  * the branch target statement must be valid
+
+    * if the statement is not allowed as a branch target, error not a valid branch target
+
+*assigned-goto-stmt* and *assign-stmt* (F90:8.2.4)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Deleted feature since Fortran 95.
+
+The *assigned-goto-stmt* and *assign-stmt* were *action-stmt* in the Fortran 90 standard. They are included here for completeness. This pair of obsolete statements can (will) be enabled as part of the compiler's legacy Fortran support.
+
+The *assign-stmt* stores a *label* in an integer variable.  The *assigned-goto-stmt* will then transfer control to the *label* stored in that integer variable.
+
+.. code-block:: fortran
+
+     ASSIGN 10 TO i
+     ...
+     GOTO i (10,20,30)
+
+Semantic Checks
+"""""""""""""""
+
+
+* an *assigned-goto-stmt* cannot be a *do-term-action-stmt* (F90:R829)
+* an *assigned-goto-stmt* cannot be a *do-term-shared-stmt* (F90:R833)
+* constraints from (F90:R839)
+
+  * each *label* in an optional *label-list* must be the statement label of a branch target statement that appears in the same scoping unit as the *assigned-goto-stmt*
+  * *scalar-int-variable* (\ ``i`` in the example above) must be named and of type default integer
+  * an integer variable that has been assigned a label may only be referenced in an *assigned-goto* or as a format specifier in an I/O statement
+  * when an I/O statement with a *format-specifier* that is an integer variable is executed or when an *assigned-goto* is executed, the variable must have been assigned a *label*
+  * an integer variable can only be assigned a label via the ``ASSIGN`` statement
+  * the label assigned to the variable must be in the same scoping unit as the *assigned-goto* that branches to the *label* value
+  * if the parameterized list of labels is present, the label value assigned to the integer variable must appear in that *label-list*
+  * a distinct *label* can appear more than once in the *label-list*
+
+Some interpretation is needed as the terms of the older standard are different.
+
+A "scoping unit" is defined as
+
+
+* a derived-type definition
+* a procedure interface body, excluding derived-types and interfaces contained within it
+* a program unit or subprogram, excluding derived-types, interfaces, and subprograms contained within it
+
+This is a more lax definition of scope than inclusive scope.
+
+A *named variable* distinguishes a variable such as, ``i``\ , from an element of an array, ``a(i)``\ , for example.
+
+Labels used in I/O
+^^^^^^^^^^^^^^^^^^
+
+Data transfer statements
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In data transfer (I/O) statements (e.g., ``READ``\ ), the user can specify a ``FMT=`` specifier that can take a label as its argument. (R1215)
+
+Semantic Checks
+"""""""""""""""
+
+
+* if the ``FMT=`` specifier has a label as its argument (C1230)
+
+  * the label must correspond to a ``FORMAT`` statement
+
+    * if the statement is not a ``FORMAT``\ , error statement must be a ``FORMAT``
+
+  * the labelled ``FORMAT`` statement must be in the same inclusive scope as the originating data transfer statement (also in 2008)
+
+    * if the label statement does not exist, error label does not exist
+    * if the label statement is not in scope, error label is not in inclusive scope
+
+  * Exceptions (errors demoted to warnings)
+
+    * PGI extension: referenced ``FORMAT`` statements may appear in a host procedure
+    * Possible relaxation: the scope of the referenced ``FORMAT`` statement may be ignored, allowing a ``FORMAT`` to be referenced from any scope in the compilation.
+
+Construct Name generalities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Various Fortran constructs can have names. These include
+
+
+* the ``WHERE`` construct (10.2.3)
+* the ``FORALL`` construct (10.2.4)
+* the ``ASSOCIATE`` construct (11.1.3)
+* the ``BLOCK`` construct (11.1.4)
+* the ``CHANGE TEAM`` construct (11.1.5)
+* the ``CRITICAL`` construct (11.1.6)
+* the ``DO`` construct (11.1.7)
+* the ``IF`` construct (11.1.8)
+* the ``SELECT CASE`` construct (11.1.9)
+* the ``SELECT RANK`` construct (11.1.10)
+* the ``SELECT TYPE`` construct (11.1.11)
+
+Semantics Checks
+~~~~~~~~~~~~~~~~
+
+A construct name is a name formed under 6.2.2.  A name is an identifier. Identifiers are parsed by the parser.
+
+
+* the maximum length of a name is 63 characters (C601)
+
+Names must either not be given for the construct or used throughout when specified.
+
+
+* if a construct is given a name, the construct's ``END`` statement must also specify the same name (\ ``WHERE`` C1033, ``FORALL`` C1035, ...)
+* ``WHERE`` has additional ``ELSEWHERE`` clauses
+* ``IF`` has additional ``ELSE IF`` and ``ELSE`` clauses
+* ``SELECT CASE`` has additional ``CASE`` clauses
+* ``SELECT RANK`` has additional ``RANK`` clauses
+* ``SELECT TYPE`` has additional *type-guard-stmt*
+  These additional statements must meet the same constraint as the ``END`` of the construct. Names must match, if present, or there must be no names for any of the clauses.
+
+``CYCLE`` statement (11.1.7.4.4)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``CYCLE`` statement takes an optional *do-construct-name*.
+
+Semantics Checks
+~~~~~~~~~~~~~~~~
+
+
+* if the ``CYCLE`` has a *construct-name*\ , then the ``CYCLE`` statement must appear within that named *do-construct* (C1134)
+* if the ``CYCLE`` does not have a *do-construct-name*\ , the ``CYCLE`` statement must appear within a *do-construct* (C1134)
+
+``EXIT`` statement (11.1.12)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``EXIT`` statement takes an optional *construct-name*.
+
+Semantics Checks
+~~~~~~~~~~~~~~~~
+
+
+* if the ``EXIT`` has a *construct-name*\ , then the ``EXIT`` statement must appear within that named construct (C1166)
+* if the ``EXIT`` does not have a *construct-name*\ , the ``EXIT`` statement must appear within a *do-construct* (C1166)
+* an *exit-stmt* must not appear in a ``DO CONCURRENT`` if the ``EXIT`` belongs to the ``DO CONCURRENT`` or an outer construct enclosing the ``DO CONCURRENT`` (C1167)
+* an *exit-stmt* must not appear in a ``CHANGE TEAM`` (\ ``CRITICAL``\ ) if the ``EXIT`` belongs to an outer construct enclosing the ``CHANGE TEAM`` (\ ``CRITICAL``\ ) (C1168)

flang/docs/ModFiles.rst

-<!--===- documentation/ModFiles.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
-  
--->
-
-# Module Files
+Module Files
+============
 
 Module files hold information from a module that is necessary to compile 
 program units that depend on the module.
 
-## Name
+Name
+----
 
 Module files must be searchable by module name. They are typically named
-`<modulename>.mod`. The advantage of using `.mod` is that it is consistent with
+``<modulename>.mod``. The advantage of using ``.mod`` is that it is consistent with
 other compilers so users will know what they are. Also, makefiles and scripts
-often use `rm *.mod` to clean up.
+often use ``rm *.mod`` to clean up.
 
 The disadvantage of using the same name as other compilers is that it is not
-clear which compiler created a `.mod` file and files from multiple compilers
+clear which compiler created a ``.mod`` file and files from multiple compilers
 cannot be in the same directory. This could be solved by adding something
-between the module name and extension, e.g. `<modulename>-f18.mod`.
+between the module name and extension, e.g. ``<modulename>-f18.mod``.
 
-## Format
+Format
+------
 
 Module files will be Fortran source.
 Declarations of all visible entities will be included, along with private
 entities that they depend on.
 Entity declarations that span multiple statements will be collapsed into
 a single *type-declaration-statement*.
 Executable statements will be omitted.
 
-### Header
+Header
+^^^^^^
 
 There will be a header containing extra information that cannot be expressed
 in Fortran. This will take the form of a comment or directive
 at the beginning of the file.
 
 If it's a comment, the module file reader would have to strip it out and
 perform *ad hoc* parsing on it. If it's a directive the compiler could
 parse it like other directives as part of the grammar.
 Processing the header before parsing might result in better error messages
-when the `.mod` file is invalid.
+when the ``.mod`` file is invalid.
 
 Regardless of whether the header is a comment or directive we can use the
-same string to introduce it: `!mod$`.
+same string to introduce it: ``!mod$``.
 
 Information in the header:
-- Magic string to confirm it is an f18 `.mod` file
-- Version information: to indicate the version of the file format, in case it changes,
+
+
+* Magic string to confirm it is an f18 ``.mod`` file
+* Version information: to indicate the version of the file format, in case it changes,
   and the version of the compiler that wrote the file, for diagnostics.
-- Checksum of the body of the current file
-- Modules we depend on and the checksum of their module file when the current
+* Checksum of the body of the current file
+* Modules we depend on and the checksum of their module file when the current
   module file is created
-- The source file that produced the `.mod` file? This could be used in error messages.
+* The source file that produced the ``.mod`` file? This could be used in error messages.
 
-### Body
+Body
+^^^^
 
 The body will consist of minimal Fortran source for the required declarations.
 The order will match the order they first appeared in the source.
 
 Some normalization will take place:
-- extraneous spaces will be removed
-- implicit types will be made explicit
-- attributes will be written in a consistent order
-- entity declarations will be combined into a single declaration
-- function return types specified in a *prefix-spec* will be replaced by
+
+
+* extraneous spaces will be removed
+* implicit types will be made explicit
+* attributes will be written in a consistent order
+* entity declarations will be combined into a single declaration
+* function return types specified in a *prefix-spec* will be replaced by
   an entity declaration
-- etc.
+* etc.
 
-#### Symbols included
+Symbols included
+~~~~~~~~~~~~~~~~
 
 All public symbols from the module need to be included.
 
 In addition, some private symbols are needed:
-- private types that appear in the public API
-- private components of non-private derived types
-- private parameters used in non-private declarations (initial values, kind parameters)
-- others?
+
+
+* private types that appear in the public API
+* private components of non-private derived types
+* private parameters used in non-private declarations (initial values, kind parameters)
+* others?
 
 It might be possible to anonymize private names if users don't want them exposed
-in the `.mod` file. (Currently they are readable in PGI `.mod` files.)
+in the ``.mod`` file. (Currently they are readable in PGI ``.mod`` files.)
 
-#### USE association
+USE association
+~~~~~~~~~~~~~~~
 
-A module that contains `USE` statements needs them represented in the
-`.mod` file.
+A module that contains ``USE`` statements needs them represented in the
+``.mod`` file.
 Each use-associated symbol will be written as a separate *use-only* statement,
 possibly with renaming.
 
 Alternatives:
-- Emit a single `USE` for each module, listing all of the symbols that were
+
+
+* Emit a single ``USE`` for each module, listing all of the symbols that were
   use-associated in the *only-list*.
-- Detect when all of the symbols from a module are imported (either by a *use-stmt*
+* Detect when all of the symbols from a module are imported (either by a *use-stmt*
   without an *only-list* or because all of the public symbols of the module
-  have been listed in *only-list*s). In that case collapse them into a single *use-stmt*.
-- Emit the *use-stmt*s that appeared in the original source.
+  have been listed in *only-list*\ s). In that case collapse them into a single *use-stmt*.
+* Emit the *use-stmt*\ s that appeared in the original source.
 
-## Reading and writing module files
+Reading and writing module files
+--------------------------------
 
-### Options
+Options
+^^^^^^^
 
 The compiler will have command-line options to specify where to search
 for module files and where to write them. By default it will be the current
 directory for both.
 
-For PGI, `-I` specifies directories to search for include files and module
-files. `-module` specifics a directory to write module files in as well as to
-search for them. gfortran is similar except it uses `-J` instead of `-module`.
+For PGI, ``-I`` specifies directories to search for include files and module
+files. ``-module`` specifics a directory to write module files in as well as to
+search for them. gfortran is similar except it uses ``-J`` instead of ``-module``.
 
 The search order for module files is:
-1. The `-module` directory (Note: for gfortran the `-J` directory is not searched).
-2. The current directory
-3. The `-I` directories in the order they appear on the command line
 
-### Writing module files
+
+#. The ``-module`` directory (Note: for gfortran the ``-J`` directory is not searched).
+#. The current directory
+#. The ``-I`` directories in the order they appear on the command line
+
+Writing module files
+^^^^^^^^^^^^^^^^^^^^
 
 When writing a module file, if the existing one matches what would be written,
 the timestamp is not updated.
 
 Module files will be written after semantics, i.e. after the compiler has
-determined the module is valid Fortran.<br>
-**NOTE:** PGI does create `.mod` files sometimes even when the module has a
+determined the module is valid Fortran.\ :raw-html-m2r:`<br>`
+**NOTE:** PGI does create ``.mod`` files sometimes even when the module has a
 compilation error.
 
 Question: If the compiler can get far enough to determine it is compiling a module
-but then encounters an error, should it delete the existing `.mod` file?
+but then encounters an error, should it delete the existing ``.mod`` file?
 PGI does not, gfortran does.
 
-### Reading module files
+Reading module files
+^^^^^^^^^^^^^^^^^^^^
 
-When the compiler finds a `.mod` file it needs to read, it firsts checks the first
+When the compiler finds a ``.mod`` file it needs to read, it firsts checks the first
 line and verifies it is a valid module file. It can also verify checksums of
 modules it depends on and report if they are out of date.
 
 If the header is valid, the module file will be run through the parser and name
 resolution to recreate the symbols from the module. Once the symbol table is
 populated the parse tree can be discarded.
 
-When processing `.mod` files we know they are valid Fortran with these properties:
-1. The input (without the header) is already in the "cooked input" format.
-2. No preprocessing is necessary.
-3. No errors can occur.
+When processing ``.mod`` files we know they are valid Fortran with these properties:
+
+
+#. The input (without the header) is already in the "cooked input" format.
+#. No preprocessing is necessary.
+#. No errors can occur.
 
-## Error messages referring to modules
+Error messages referring to modules
+-----------------------------------
 
 With this design, diagnostics can refer to names in modules and can emit a
 normalized declaration of an entity but not point to its location in the
 source.
 
 If the header includes the source file it came from, that could be included in
 a diagnostic but we still wouldn't have line numbers.
 
 To provide line numbers and character positions or source lines as the user
 wrote them we would have to save some amount of provenance information in the
 module file as well.

flang/docs/OpenMP-4.5-grammar.txt

 #===-- documentation/OpenMP-4.5-grammar.txt --------------------------------===#
 #
 # 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
 #
 #===------------------------------------------------------------------------===#
 
 # OpenMP 4.5 Specifications
 
 2 omp-directive -> sentinel directive-name [clause[ [,] clause]...]
 2.1.1 sentinel -> !$omp | c$omp | *$omp
 2.1.2 sentinel -> !$omp
 
 # directive-name
 2.5 parallel -> PARALLEL [parallel-clause[ [,] parallel-clause]...]
     parallel-clause -> if-clause |
                        num-threads-clause |
                        default-clause |
                        private-clause |
                        firstprivate-clause |
                        shared-clause |
                        copyin-clause |
                        reduction-clause |
                        proc-bind-clause
 
 2.5 end-parallel -> END PARALLEL
 
 2.7.1 do -> DO [do-clause[ [,] do-clause]...]
       do-clause -> private-clause |
                    firstprivate-clause |
                    lastprivate-clause |
                    linear-clause |
                    reduction-clause |
                    schedule-clause |
                    collapse-clause |
                    ordered-clause
 
 2.7.1 end-do -> END DO [nowait-clause]
 
 2.7.2 sections -> SECTIONS [sections-clause[ [,] sections-clause]...]
       sections-clause -> private-clause |
                          firstprivate-clause |
                          lastprivate-clause |
                          reduction-clause
 
 2.7.2 section -> SECTION
 
 2.7.2 end-sections -> END SECTIONS [nowait-clause]
 
 2.7.3 single -> SINGLE [single-clause[ [,] single-clause]...]
       single-clause -> private-clause |
                        firstprivate-clause
 
 2.7.3 end-single -> END SINGLE [end-single-clause[ [,] end-single-clause]...]
       end-single-clause -> copyprivate-clause |
                            nowait-clause
 
 2.7.4 workshare -> WORKSHARE
 
 2.7.4 end-workshare -> END WORKSHARE [nowait-clause]
 
 2.8.1 simd -> SIMD [simd-clause[ [,] simd-clause]...]
       simd-clause -> safelen-clause |
                      simdlen-clause |
                      linear-clause |
                      aligned-clause |
                      private-clause |
                      lastprivate-clause |
                      reduction-clause |
                      collapse-clause
 
 2.8.1 end-simd -> END SIMD
 
 2.8.2 declare-simd -> DECLARE SIMD [(proc-name)] [declare-simd-clause[ [,] declare-simd-clause]...]
       declare-simd-clause -> simdlen-clause |
                              linear-clause |
                              aligned-clause |
                              uniform-clause |
                              inbranch-clause |
                              notinbranch-clause
 
 2.8.3 do-simd -> DO SIMD [do-simd-clause[ [,] do-simd-clause]...]
       do-simd-clause -> do-clause |
                         simd-clause
 
 2.8.3 end-do-simd -> END DO SIMD [nowait-clause]
 
 2.9.1 task -> TASK [task-clause[ [,] task-clause]...]
       task-clause -> if-clause |
                      final-clause |
                      untied-clause |
                      default-clause |
                      mergeable-clause |
                      private-clause |
                      firstprivate-clause |
                      shared-clause |
                      depend-clause |
                      priority-clause
 
 2.9.1 end-task -> END TASK
 
 2.9.2 taskloop -> TASKLOOP [taskloop-clause[ [,] taskloop-clause]...]
       taskloop-clause -> if-clause |
                          shared-clause |
                          private-clause |
                          firstprivate-clause |
                          lastprivate-clause |
                          default-clause |
                          grainsize-clause |
                          num-tasks-clause |
                          collapse-clause |
                          final-clause |
                          priority-clause |
                          untied-clause |
                          mergeable-clause |
                          nogroup-clause
 
 2.9.2 end-taskloop -> END TASKLOOP
 
 2.9.3 taskloop-simd -> TASKLOOP SIMD [taskloop-simd-clause[ [,] taskloop-simd-clause]...]
       taskloop-simd-clause -> taskloop-clause |
                               simd-clause
 
 2.9.3 end-taskloop-simd -> END TASKLOOP SIMD
 
 2.9.4 taskyield -> TASKYIELD
 
 2.10.1 target-data -> TARGET DATA target-data-clause[ [ [,] target-data-clause]...]
        target-data-clause -> if-clause |
                              device-clause |
                              map-clause |
                              use-device-ptr-clause
 
 2.10.1 end-target-data -> END TARGET DATA
 
 2.10.2 target-enter-data -> TARGET ENTER DATA [ target-enter-data-clause[ [,] target-enter-data-clause]...]
        target-enter-data-clause -> if-clause |
                                    device-clause |
                                    map-clause |
                                    depend-clause |
                                    nowait-clause
 
 2.10.3 target-exit-data -> TARGET EXIT DATA [ target-exit-data-clause[ [,] target-exit-data-clause]...]
        target-exit-data-clause -> if-clause |
                                   device-clause |
                                   map-clause |
                                   depend-clause |
                                   nowait-clause
 
 2.10.4 target -> TARGET [target-clause[ [,] target-clause]...]
        target-clause -> if-clause |
                         device-clause |
                         private-clause |
                         firstprivate-clause |
                         map-clause |
                         is-device-ptr-clause |
                         defaultmap-clause |
                         nowait-clause |
                         depend-clause
 
 2.10.4 end-target -> END TARGET
 
 2.10.5 target-update -> TARGET UPDATE target-update-clause[ [ [,] target-update-clause]...]
        target-update-clause -> motion-clause |
                                if-clause |
                                device-clause |
                                nowait-clause |
                                depend-clause
        motion-clause -> to-clause |
                         from-clause
 
 2.10.6 declare-target -> DECLARE TARGET (extended-list) |
                          DECLARE TARGET [declare-target-clause[ [,] declare-target-clause]...]
        declare-target-clause -> to-clause |
                                 link-clause
 
 2.10.7 teams -> TEAMS [teams-clause[ [,] teams-clause]...]
        teams-clause -> num-teams-clause |
                        thread-limit-clause |
                        default-clause |
                        private-clause |
                        firstprivate-clause |
                        shared-clause |
                        reduction-clause
 
 2.10.7 end-teams -> END TEAMS
 
 2.10.8 distribute -> DISTRIBUTE [distribute-clause[ [,] distribute-clause]...]
        distribute-clause -> private-clause |
                             firstprivate-clause |
                             lastprivate-clause |
                             collapse-clause |
                             dist-schedule-clause
 
 2.10.8 end-distribute -> END DISTRIBUTE
 
 2.10.9 distribute-simd -> DISTRIBUTE SIMD [distribute-simd-clause[ [,] distribute-simd-clause]...]
        distribute-simd-clause -> distribute-clause |
                                  simd-clause
 
 2.10.9 end-distribute-simd -> END DISTRIBUTE SIMD
 
 2.10.10 distribute-parellel-do ->
            DISTRIBUTE PARALLEL DO [distribute-parallel-do-clause[ [,] distribute-parallel-do-clause]...]
         distribute-parallel-do-clause -> distribute-clause |
                                          parallel-do-clause
 
 2.10.10 end-distribute-parellel-do -> END DISTRIBUTE PARALLEL DO
 
 2.10.11 distribute-parallel-do-simd ->
            DISTRIBUTE PARALLEL DO SIMD [distribute-parallel-do-simd-clause[ [,] distribute-parallel-do-simd-clause]...]
         distribute-parallel-do-simd-clause -> distribute-clause |
                                               parallel-do-simd-clause
 
 2.10.11 end-distribute-parallel-do-simd -> END DISTRIBUTE PARALLEL DO SIMD
 
 2.11.1 parallel-do -> PARALLEL DO [parallel-do-clause[ [,] parallel-do-clause]...]
        parallel-do-clause -> parallel-clause |
                              do-clause
 
 2.11.1 end-parallel-do -> END PARALLEL DO
 
 2.11.2 parallel-sections -> PARALLEL SECTIONS [parallel-sections-clause[ [,] parallel-sections-clause]...]
        parallel-sections-clause -> parallel-clause |
                                    sections-clause
 
 2.11.2 end-parallel-sections -> END PARALLEL SECTIONS
 
 2.11.3 parallel-workshare -> PARALLEL WORKSHARE [parallel-workshare-clause[ [,] parallel-workshare-clause]...]
        parallel-workshare-clause -> parallel-clause
 
 2.11.3 end-parallel-workshare -> END PARALLEL WORKSHARE
 
 2.11.4 parallel-do-simd -> PARALLEL DO SIMD [parallel-do-simd-clause[ [,] parallel-do-simd-clause]...]
        parallel-do-simd-clause -> parallel-clause |
                                   do-simd-clause
 
 2.11.4 end-parallel-do-simd -> END PARALLEL DO SIMD
 
 2.11.5 target-parallel -> TARGET PARALLEL [target-parallel-clause[ [,] target-parallel-clause]...]
        target-parallel-clause -> target-clause |
                                  parallel-clause
 
 2.11.5 end-target-parallel -> END TARGET PARALLEL
 
 2.11.6 target-parallel-do -> TARGET PARALLEL DO [target-parallel-do-clause[ [,] target-parallel-do-clause]...]
        target-parallel-do-clause -> target-clause |
                                     parallel-do-clause
 
 2.11.6 end-target-parallel-do -> END TARGET PARALLEL DO
 
 2.11.7 target-parallel-do-simd ->
           TARGET PARALLEL DO SIMD [target-parallel-do-simd-clause[ [,] target-parallel-do-simd-clause]...]
        target-parallel-do-simd-clause -> target-clause |
                                          parallel-do-simd-clause
 
 2.11.7 end-target-parallel-do-simd -> END TARGET PARALLEL DO SIMD
 
 2.11.8 target-simd -> TARGET SIMD [target-simd-clause[ [,] target-simd-clause]...]
        target-simd-clause -> target-clause |
                              simd-clause
 
 2.11.8 end-target-simd -> END TARGET SIMD
 
 2.11.9 target-teams -> TARGET TEAMS [target-teams-clause[ [,] target-teams-clause]...]
        target-teams-clause -> target-clause |
                               teams-clause
 
 2.11.9 end-target-teams -> END TARGET TEAMS
 
 2.11.10 teams-distribute -> TEAMS DISTRIBUTE [teams-distribute-clause[ [,] teams-distribute-clause]...]
         teams-distribute-clause -> teams-clause |
                                    distribute-clause
 
 2.11.10 end-teams-distribute -> END TEAMS DISTRIBUTE
 
 2.11.11 teams-distribute-simd ->
            TEAMS DISTRIBUTE SIMD [teams-distribute-simd-clause[ [,] teams-distribute-simd-clause]...]
         teams-distribute-simd-clause -> teams-clause |
                                         distribute-simd-clause
 
 2.11.11 end-teams-distribute-simd -> END TEAMS DISTRIBUTE SIMD
 
 2.11.12 target-teams-distribute ->
            TARGET TEAMS DISTRIBUTE [target-teams-distribute-clause[ [,] target-teams-distribute-clause]...]
         target-teams-distribute-clause -> target-clause |
                                           teams-distribute-clause
 
 2.11.12 end-target-teams-distribute -> END TARGET TEAMS DISTRIBUTE
 
 2.11.13 target-teams-distribute-simd ->
            TARGET TEAMS DISTRIBUTE SIMD [target-teams-distribute-simd-clause[ [,] target-teams-distribute-simd-clause]...]
         target-teams-distribute-simd-clause -> target-clause |
                                                teams-distribute-simd-clause
 
 2.11.13 end-target-teams-distribute-simd -> END TARGET TEAMS DISTRIBUTE SIMD
 
 2.11.14 teams-distribute-parallel-do ->
            TEAMS DISTRIBUTE PARALLEL DO [teams-distribute-parallel-do-clause[ [,] teams-distribute-parallel-do-clause]...]
         teams-distribute-parallel-do-clause -> teams-clause |
                                                distribute-parallel-do-clause
 
 2.11.14 end-teams-distribute-parallel-do -> END TEAMS DISTRIBUTE PARALLEL DO
 
 2.11.15 target-teams-distribute-parallel-do ->
            TARGET TEAMS DISTRIBUTE PARALLEL DO [target-teams-distribute-parallel-do-clause[ [,] target-teams-distribute-parallel-do-clause]...]
         target-teams-distribute-parallel-do-clause -> target-clause |
                                                       teams-distribute-parallel-do-clause
 
 2.11.15 end-target-teams-distribute-parallel-do -> END TARGET TEAMS DISTRIBUTE PARALLEL DO
 
 2.11.16 teams-distribute-parallel-do-simd ->
            TEAMS DISTRIBUTE PARALLEL DO SIMD [teams-distribute-parallel-do-simd-clause[ [,] teams-distribute-parallel-do-simd-clause]...]
         teams-distribute-parallel-do-simd-clause -> teams-clause |
                                                     distribute-parallel-do-simd-clause
 
 2.11.16 end-teams-distribute-parallel-do-simd -> END TEAMS DISTRIBUTE PARALLEL DO SIMD
 
 2.11.17 target-teams-distribute-parallel-do-simd ->
            TARGET TEAMS DISTRIBUTE PARALLEL DO SIMD [target-teams-distribute-parallel-do-simd-clause[ [,] target-teams-distribute-parallel-do-simd-clause]...]
         target-teams-distribute-parallel-do-simd-clause -> target-clause |
                                                            teams-distribute-parallel-do-simd-clause
 
 2.11.17 end-target-teams-distribute-parallel-do-simd -> END TARGET TEAMS DISTRIBUTE PARALLEL DO SIMD
 
 2.13.1 master -> MASTER
 
 2.13.1 end-master -> END MASTER
 
 2.13.2 critical -> CRITICAL [(name) [HINT(hint-expr)]]
 
 2.13.2 end-critical -> END CRITICAL [(name)]
 
 2.13.3 barrier -> BARRIER
 
 2.13.4 taskwait -> TASKWAIT
 
 2.13.5 taskgroup -> TASKGROUP
 
 2.13.5 end-taskgroup -> END TASKGROUP
 
 2.13.6 atomic -> ATOMIC [seq_cst[,]] atomic-clause [[,]seq_cst] |
                  ATOMIC [seq_cst]
        atomic-clause -> READ | WRITE | UPDATE | CAPTURE
 
 2.13.7 flush -> FLUSH [(variable-name-list)]
 
 2.13.8 ordered -> ORDERED ordered-construct-clause [[[,] ordered-construct-clause]...]
        ordered-construct-clause -> depend-clause
 
 2.13.8 end-ordered -> END ORDERED
 
 2.14.1 cancel -> CANCEL construct-type-clause [ [,] if-clause]
        construct-type-clause -> PARALLEL |
                                 SECTIONS |
                                 DO |
                                 TASKGROUP
 
 2.14.2 cancellation-point -> CANCELLATION POINT construct-type-clause
 
 2.15.2 threadprivate -> THREADPRIVATE (variable-name-list)
 
 2.16 declare-reduction -> DECLARE REDUCTION (reduction-identifier : type-list : combiner) [initializer-clause]
 
 # Clauses
 2.5 proc-bind-clause -> PROC_BIND (MASTER | CLOSE | SPREAD)
 
 2.5 num-threads-clause -> NUM_THREADS (scalar-int-expr)
 
 2.7.1 schedule-clause -> SCHEDULE ([sched-modifier] [, sched-modifier]:]
                                    kind[, chunk_size])
 
 2.7.1 kind -> STATIC | DYNAMIC | GUIDED | AUTO | RUNTIME
 
 2.7.1 sched-modifier -> MONOTONIC | NONMONOTONIC | SIMD
 
 2.7.1 chunk_size -> scalar-int-expr
 
 2.7.1 collapse-clause -> COLLAPSE (scalar-constant)
 
 2.7.1 ordered-clause -> ORDERED [(scalar-constant)]
 
 2.7.1 nowait-clause -> NOWAIT
 
 2.8.1 aligned-clause -> ALIGNED (variable-name-list[ : scalar-constant])
 
 2.8.1 safelen-clause -> SAFELEN (scalar-constant)
 
 2.8.1 simdlen-clause -> SIMDLEN (scalar-contant)
 
 2.8.2 uniform-clause -> UNIFORM (dummy-arg-name-list)
 
 2.8.2 inbranch-clause -> INBRANCH
 
 2.8.2 notinbranch-clause -> NOTINBRANCH
 
 2.13.9 depend-clause -> DEPEND (((IN | OUT | INOUT) : variable-name-list) |
                                 SOURCE |
                                 SINK : vec)
                  vec -> iterator [+/- scalar-int-expr],..., iterator[...]
 
 2.9.2 num-tasks-clause -> NUM_TASKS (scalar-int-expr)
 
 2.9.2 grainsize-clause -> GRAINSIZE (scalar-int-expr)
 
 2.9.2 nogroup-clause -> NOGROUP
 
 2.9.2 untied-clause -> UNTIED
 
 2.9.2 priority-clause -> PRIORITY (scalar-int-expr)
 
 2.9.2 mergeable-clause -> MERGEABLE
 
 2.9.2 final-clause -> FINAL (scalar-int-expr)
 
 2.10.1 use-device-ptr-clause -> USE_DEVICE_PTR (variable-name-list)
 
 2.10.1 device-clause -> DEVICE (scalar-integer-expr)
 
 2.10.4 is-device-ptr-clause -> IS_DEVICE_PTR (variable-name-list)
 
 2.10.5 to-clause -> TO (variable-name-list)
 
 2.10.5 from-clause -> FROM (variable-name-list)
 
 2.10.6 link-clause -> LINK (variable-name-list)
 
 2.10.7 num-teams-clause -> NUM_TEAMS (scalar-integer-expr)
 
 2.10.7 thread-limit-clause -> THREAD_LIMIT (scalar-integer-expr)
 
 2.10.8 dist-schedule-clause -> DIST_SCHEDULE (STATIC [ , chunk_size])
 
 2.12 if-clause -> IF ([ directive-name-modifier :] scalar-logical-expr)
 
 2.15.3.1 default-clause -> DEFAULT (PRIVATE | FIRSTPRIVATE | SHARED | NONE)
 
 2.15.3.2 shared-clause -> SHARED (variable-name-list)
 
 2.15.3.3 private-clause -> PRIVATE (variable-name-list)
 
 2.15.3.4 firstprivate-clause -> FIRSTPRIVATE (variable-name-list)
 
 2.15.3.5 lastprivate-clause -> LASTPRIVATE (variable-name-list)
 
 2.15.3.6 reduction-clause -> REDUCTION (reduction-identifier: variable-name-list)
          reduction-identifier -> + | - | * |
                                  .AND. | .OR. | .EQV. | .NEQV. |
                                  MAX | MIN | IAND | IOR | IEOR
 
 2.15.3.7 linear-clause -> LINEAR (linear-list[ : linear-step])
          linear-list -> list | modifier(list)
          modifier -> REF | VAL | UVAL
 
 2.15.4.1 copyin-clause -> COPYIN (variable-name-list)
 
 2.15.4.2 copyprivate-clause -> COPYPRIVATE (variable-name-list)
 
 2.15.5.1 map -> MAP ([ [ALWAYS[,]] map-type : ] variable-name-list)
          map-type -> TO | FROM | TOFROM |
                      ALLOC | RELEASE | DELETE
 
 2.15.5.2 defaultmap -> DEFAULTMAP (TOFROM:SCALAR)

flang/docs/OpenMP-semantics.rst

+OpenMP Semantic Analysis
+========================
+
+OpenMP for F18
+--------------
+
+
+#. Define and document the parse tree representation for
+
+   * Directives (listed below)
+   * Clauses (listed below)
+   * Documentation
+
+#. All the directives and clauses need source provenance for messages
+#. Define and document how an OpenMP directive in the parse tree
+   will be represented as the parent of the statement(s)
+   to which the directive applies.
+   The parser itself will not be able to construct this representation;
+   there will be subsequent passes that do so
+   just like for example *do-stmt* and *do-construct*.
+#. Define and document the symbol table extensions
+#. Define and document the module file extensions
+
+Directives
+^^^^^^^^^^
+
+OpenMP divides directives into three categories as follows.
+The directives that are in the same categories share some characteristics.
+
+Declarative directives
+~~~~~~~~~~~~~~~~~~~~~~
+
+An OpenMP directive may only be placed in a declarative context.
+A declarative directive results in one or more declarations only;
+it is not associated with the immediate execution of any user code.
+
+List of existing ones:
+
+
+* declare simd
+* declare target
+* threadprivate
+* declare reduction
+
+There is a parser node for each of these directives and
+the parser node saves information associated with the directive,
+for example,
+the name of the procedure-name in the ``declare simd`` directive.
+
+Each parse tree node keeps source provenance,
+one for the directive name itself and
+one for the entire directive starting from the directive name.
+
+A top-level class, ``OpenMPDeclarativeConstruct``\ ,
+holds all four of the node types as discriminated unions
+along with the source provenance for the entire directive
+starting from ``!$OMP``.
+
+In ``parser-tree.h``\ ,
+``OpenMPDeclarativeConstruct`` is part
+of the ``SpecificationConstruct`` and ``SpecificationPart``
+in F18 because
+a declarative directive can only be placed in the specification part
+of a Fortran program.
+
+All the ``Names`` or ``Designators`` associated
+with the declarative directive will be resolved in later phases.
+
+Executable directives
+~~~~~~~~~~~~~~~~~~~~~
+
+An OpenMP directive that is **not** declarative.
+That is, it may only be placed in an executable context.
+It contains stand-alone directives and constructs
+that are associated with code blocks.
+The stand-alone directive is described in the next section.
+
+The constructs associated with code blocks listed below
+share a similar structure:
+*Begin Directive*\ , *Clause List*\ , *Code Block*\ , *End Directive*.
+The *End Directive* is optional for constructs
+like Loop-associated constructs.
+
+
+* Block-associated constructs (\ ``OpenMPBlockConstruct``\ )
+* Loop-associated constructs (\ ``OpenMPLoopConstruct``\ )
+* Atomic construct (\ ``OpenMPAtomicConstruct``\ )
+* Sections Construct (\ ``OpenMPSectionsConstruct``\ ,
+  contains Sections/Parallel Sections constructs)
+* Critical Construct (\ ``OpenMPCriticalConstruct``\ )
+
+A top-level class, ``OpenMPConstruct``\ ,
+includes stand-alone directive and constructs
+listed above as discriminated unions.
+
+In the ``parse-tree.h``\ , ``OpenMPConstruct`` is an element
+of the ``ExecutableConstruct``.
+
+All the ``Names`` or ``Designators`` associated
+with the executable directive will be resolved in Semantic Analysis.
+
+When the backtracking parser can not identify the associated code blocks,
+the parse tree will be rewritten later in the Semantics Analysis.
+
+Stand-alone Directives
+~~~~~~~~~~~~~~~~~~~~~~
+
+An OpenMP executable directive that has no associated user code
+except for that which appears in clauses in the directive.
+
+List of existing ones:
+
+
+* taskyield
+* barrier
+* taskwait
+* target enter data
+* target exit data
+* target update
+* ordered
+* flush
+* cancel
+* cancellation point
+
+A higher-level class is created for each category
+which contains directives listed above that share a similar structure:
+
+
+* OpenMPSimpleStandaloneConstruct
+  (taskyield, barrier, taskwait,
+  target enter/exit data, target update, ordered)
+* OpenMPFlushConstruct
+* OpenMPCancelConstruct
+* OpenMPCancellationPointConstruct
+
+A top-level class, ``OpenMPStandaloneConstruct``\ ,
+holds all four of the node types as discriminated unions
+along with the source provenance for the entire directive.
+Also, each parser node for the stand-alone directive saves
+the source provenance for the directive name itself.
+
+Clauses
+^^^^^^^
+
+Each clause represented as a distinct class in ``parse-tree.h``.
+A top-level class, ``OmpClause``\ ,
+includes all the clauses as discriminated unions.
+The parser node for ``OmpClause`` saves the source provenance
+for the entire clause.
+
+All the ``Names`` or ``Designators`` associated
+with the clauses will be resolved in Semantic Analysis.
+
+Note that the backtracking parser will not validate
+that the list of clauses associated
+with a directive is valid other than to make sure they are well-formed.
+In particular,
+the parser does not check that
+the association between directive and clauses is correct
+nor check that the values in the directives or clauses are correct.
+These checks are deferred to later phases of semantics to simplify the parser.
+
+Symbol Table Extensions for OpenMP
+----------------------------------
+
+Name resolution can be impacted by the OpenMP code.
+In addition to the regular steps to do the name resolution,
+new scopes and symbols may need to be created
+when encountering certain OpenMP constructs.
+This section describes the extensions
+for OpenMP during Symbol Table construction.
+
+OpenMP uses the fork-join model of parallel execution and
+all OpenMP threads have access to
+a *shared* memory place to store and retrieve variables
+but each thread can also have access to
+its *threadprivate* memory that must not be accessed by other threads.
+
+For the directives and clauses that can control the data environments,
+compiler needs to determine two kinds of *access*
+to variables used in the directive’s associated structured block:
+**shared** and **private**.
+Each variable referenced in the structured block
+has an original variable immediately outside of the OpenMP constructs.
+Reference to a shared variable in the structured block
+becomes a reference to the original variable.
+However, each private variable referenced in the structured block,
+a new version of the original variable (of the same type and size)
+will be created in the threadprivate memory.
+
+There are exceptions that directives/clauses
+need to create a new ``Symbol`` without creating a new ``Scope``\ ,
+but in general,
+when encountering each of the data environment controlling directives
+(discussed in the following sections),
+a new ``Scope`` will be created.
+For each private variable referenced in the structured block,
+a new ``Symbol`` is created out of the original variable
+and the new ``Symbol`` is associated
+with original variable’s ``Symbol`` via ``HostAssocDetails``.
+A new set of OpenMP specific flags are added
+into ``Flag`` class in ``symbol.h`` to indicate the types of
+associations,
+data-sharing attributes,
+and data-mapping attributes
+in the OpenMP data environments.
+
+New Symbol without new Scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+OpenMP directives that require new ``Symbol`` to be created
+but not new ``Scope`` are listed in the following table
+in terms of the Symbol Table extensions for OpenMP:
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td rowspan="2" colspan="2" >Directives/Clauses
+      </td>
+      <td rowspan="2" >Create New
+   <p>
+   Symbol
+   <p>
+   w/
+      </td>
+      <td colspan="2" >Add Flag
+      </td>
+     </tr>
+     <tr>
+      <td>on Symbol of
+      </td>
+      <td>Flag
+      </td>
+     </tr>
+     <tr>
+      <td rowspan="4" >Declarative Directives
+      </td>
+      <td>declare simd [(proc-name)]
+      </td>
+      <td>-
+      </td>
+      <td>The name of the enclosing function, subroutine, or interface body
+      to which it applies, or proc-name
+      </td>
+      <td>OmpDeclareSimd
+      </td>
+     </tr>
+     <tr>
+      <td>declare target
+      </td>
+      <td>-
+      </td>
+      <td>The name of the enclosing function, subroutine, or interface body
+      to which it applies
+      </td>
+      <td>OmpDeclareTarget
+      </td>
+     </tr>
+     <tr>
+      <td>threadprivate(list)
+      </td>
+      <td>-
+      </td>
+      <td>named variables and named common blocks
+      </td>
+      <td>OmpThreadPrivate
+      </td>
+     </tr>
+     <tr>
+      <td>declare reduction
+      </td>
+      <td>*
+      </td>
+      <td>reduction-identifier
+      </td>
+      <td>OmpDeclareReduction
+      </td>
+     </tr>
+     <tr>
+      <td>Stand-alone directives
+      </td>
+      <td>flush
+      </td>
+      <td>-
+      </td>
+      <td>variable, array section or common block name
+      </td>
+      <td>OmpFlushed
+      </td>
+     </tr>
+     <tr>
+      <td colspan="2" >critical [(name)]
+      </td>
+      <td>-
+      </td>
+      <td>name (user-defined identifier)
+      </td>
+      <td>OmpCriticalLock
+      </td>
+     </tr>
+     <tr>
+      <td colspan="2" >if ([ directive-name-modifier :] scalar-logical-expr)
+      </td>
+      <td>-
+      </td>
+      <td>directive-name-modifier
+      </td>
+      <td>OmpIfSpecified
+      </td>
+     </tr>
+   </table>
+
+
+.. code-block::
+
+     -      No Action
+
+     *      Discussed in “Module File Extensions for OpenMP” section
+
+
+
+New Symbol with new Scope
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For the following OpenMP regions:
+
+
+* ``target`` regions
+* ``teams`` regions
+* ``parallel`` regions
+* ``simd`` regions
+* task generating regions (created by ``task`` or ``taskloop`` constructs)
+* worksharing regions
+  (created by ``do``\ , ``sections``\ , ``single``\ , or ``workshare`` constructs)
+
+A new ``Scope`` will be created
+when encountering the above OpenMP constructs
+to ensure the correct data environment during the Code Generation.
+To determine whether a variable referenced in these regions
+needs the creation of a new ``Symbol``\ ,
+all the data-sharing attribute rules
+described in OpenMP Spec [2.15.1] apply during the Name Resolution.
+The available data-sharing attributes are:
+**\ *shared*\ **\ ,
+**\ *private*\ **\ ,
+**\ *linear*\ **\ ,
+**\ *firstprivate*\ **\ ,
+and **\ *lastprivate*\ **.
+The attribute is represented as ``Flag`` in the ``Symbol`` object.
+
+More details are listed in the following table:
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td rowspan="2" >Attribute
+      </td>
+      <td rowspan="2" >Create New Symbol
+      </td>
+      <td colspan="2" >Add Flag
+      </td>
+     </tr>
+     <tr>
+      <td>on Symbol of
+      </td>
+      <td>Flag
+      </td>
+     </tr>
+     <tr>
+      <td>shared
+      </td>
+      <td>No
+      </td>
+      <td>Original variable
+      </td>
+      <td>OmpShared
+      </td>
+     </tr>
+     <tr>
+      <td>private
+      </td>
+      <td>Yes
+      </td>
+      <td>New Symbol
+      </td>
+      <td>OmpPrivate
+      </td>
+     </tr>
+     <tr>
+      <td>linear
+      </td>
+      <td>Yes
+      </td>
+      <td>New Symbol
+      </td>
+      <td>OmpLinear
+      </td>
+     </tr>
+     <tr>
+      <td>firstprivate
+      </td>
+      <td>Yes
+      </td>
+      <td>New Symbol
+      </td>
+      <td>OmpFirstPrivate
+      </td>
+     </tr>
+     <tr>
+      <td>lastprivate
+      </td>
+      <td>Yes
+      </td>
+      <td>New Symbol
+      </td>
+      <td>OmpLastPrivate
+      </td>
+     </tr>
+   </table>
+
+
+To determine the right data-sharing attribute,
+OpenMP defines that the data-sharing attributes
+of variables that are referenced in a construct can be
+*predetermined*\ , *explicitly determined*\ , or *implicitly determined*.
+
+Predetermined data-sharing attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+* Assumed-size arrays are **shared**
+* The loop iteration variable(s)
+  in the associated *do-loop(s)* of a
+  *do*\ ,
+  *parallel do*\ ,
+  *taskloop*\ ,
+  or *distributeconstruct*
+  is (are) **private**
+* A loop iteration variable
+  for a sequential loop in a *parallel* or task generating construct
+  is **private** in the innermost such construct that encloses the loop
+* Implied-do indices and *forall* indices are **private**
+* The loop iteration variable in the associated *do-loop*
+  of a *simd* construct with just one associated *do-loop*
+  is **linear** with a linear-step
+  that is the increment of the associated *do-loop*
+* The loop iteration variables in the associated *do-loop(s)* of a *simd*
+  construct with multiple associated *do-loop(s)* are **lastprivate**
+
+Explicitly determined data-sharing attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Variables with *explicitly determined* data-sharing attributes are:
+
+
+* Variables are referenced in a given construct
+* Variables are listed in a data-sharing attribute clause on the construct.
+
+The data-sharing attribute clauses are:
+
+
+* *default* clause
+  (discussed in “Implicitly determined data-sharing attributes”)
+* *shared* clause
+* *private* clause
+* *linear* clause
+* *firstprivate* clause
+* *lastprivate* clause
+* *reduction* clause
+  (new ``Symbol`` created with the flag ``OmpReduction`` set)
+
+Note that variables with *predetermined* data-sharing attributes
+may not be listed (with exceptions) in data-sharing attribute clauses.
+
+Implicitly determined data-sharing attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Variables with implicitly determined data-sharing attributes are:
+
+
+* Variables are referenced in a given construct
+* Variables do not have *predetermined* data-sharing attributes
+* Variables are not listed in a data-sharing attribute clause
+  on the construct.
+
+Rules for variables with *implicitly determined* data-sharing attributes:
+
+
+* In a *parallel* construct, if no *default* clause is present,
+  these variables are **shared**
+* In a task generating construct,
+  if no *default* clause is present,
+  a variable for which the data-sharing attribute
+  is not determined by the rules above
+  and that in the enclosing context is determined
+  to be shared by all implicit tasks
+  bound to the current team is **shared**
+* In a *target* construct,
+  variables that are not mapped after applying data-mapping attribute rules
+  (discussed later) are **firstprivate**
+* In an orphaned task generating construct,
+  if no *default* clause is present, dummy arguments are **firstprivate**
+* In a task generating construct, if no *default* clause is present,
+  a variable for which the data-sharing attribute is not determined
+  by the rules above is **firstprivate**
+* For constructs other than task generating constructs or *target* constructs,
+  if no *default* clause is present,
+  these variables reference the variables with the same names
+  that exist in the enclosing context
+* In a *parallel*\ , *teams*\ , or task generating construct,
+  the data-sharing attributes of these variables are determined
+  by the *default* clause, if present:
+
+  * *default(shared)*
+    clause causes all variables referenced in the construct
+    that have *implicitly determined* data-sharing attributes
+    to be **shared**
+  * *default(private)*
+    clause causes all variables referenced in the construct
+    that have *implicitly determined* data-sharing attributes
+    to be **private**
+  * *default(firstprivate)*
+    clause causes all variables referenced in the construct
+    that have *implicitly determined* data-sharing attributes
+    to be **firstprivate**
+  * *default(none)*
+    clause requires that each variable
+    that is referenced in the construct,
+    and that does not have a *predetermined* data-sharing attribute,
+    must have its data-sharing attribute *explicitly determined*
+    by being listed in a data-sharing attribute clause
+
+Data-mapping Attribute
+^^^^^^^^^^^^^^^^^^^^^^
+
+When encountering the *target data* and *target* directives,
+the data-mapping attributes of any variable referenced in a target region
+will be determined and represented as ``Flag`` in the ``Symbol`` object
+of the variable.
+No ``Symbol`` or ``Scope`` will be created.
+
+The basic steps to determine the data-mapping attribute are:
+
+
+#. If *map* clause is present,
+   the data-mapping attribute is determined by the *map-type*
+   on the clause and its corresponding ``Flag`` are listed below:
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td>
+   data-mapping attribute
+      </td>
+      <td>Flag
+      </td>
+     </tr>
+     <tr>
+      <td>to
+      </td>
+      <td>OmpMapTo
+      </td>
+     </tr>
+     <tr>
+      <td>from
+      </td>
+      <td>OmpMapFrom
+      </td>
+     </tr>
+     <tr>
+      <td>tofrom
+   (default if map-type is not present)
+      </td>
+      <td>OmpMapTo & OmpMapFrom
+      </td>
+     </tr>
+     <tr>
+      <td>alloc
+      </td>
+      <td>OmpMapAlloc
+      </td>
+     </tr>
+     <tr>
+      <td>release
+      </td>
+      <td>OmpMapRelease
+      </td>
+     </tr>
+     <tr>
+      <td>delete
+      </td>
+      <td>OmpMapDelete
+      </td>
+     </tr>
+   </table>
+
+
+
+#. Otherwise, the following data-mapping rules apply
+   for variables referenced in a *target* construct
+   that are *not* declared in the construct and
+   do not appear in data-sharing attribute or map clauses:
+
+   * If a variable appears in a *to* or *link* clause
+     on a *declare target* directive then it is treated
+     as if it had appeared in a *map* clause with a *map-type* of **tofrom**
+
+#. Otherwise, the following implicit data-mapping attribute rules apply:
+
+   * If a *defaultmap(tofrom:scalar)* clause is *not* present
+     then a scalar variable is not mapped,
+     but instead has an implicit data-sharing attribute of **firstprivate**
+   * If a *defaultmap(tofrom:scalar)* clause is present
+     then a scalar variable is treated as if it had appeared
+     in a map clause with a map-type of **tofrom**
+   * If a variable is not a scalar
+     then it is treated as if it had appeared in a map clause
+     with a *map-type* of **tofrom**
+
+After the completion of the Name Resolution phase,
+all the data-sharing or data-mapping attributes marked for the ``Symbols``
+may be used later in the Semantics Analysis and in the Code Generation.
+
+Module File Extensions for OpenMP
+---------------------------------
+
+After the successful compilation of modules and submodules
+that may contain the following Declarative Directives,
+the entire directive starting from ``!$OMP`` needs to be written out
+into ``.mod`` files in their corresponding Specification Part:
+
+
+* 
+  *declare simd* or *declare target*
+
+    In the “New Symbol without new Scope” section,
+    we described that when encountering these two declarative directives,
+    new ``Flag`` will be applied to the Symbol of the name of
+    the enclosing function, subroutine, or interface body to
+    which it applies, or proc-name.
+    This ``Flag`` should be part of the API information
+    for the given subroutine or function
+
+* 
+  *declare reduction*
+
+    The *reduction-identifier* in this directive
+    can be use-associated or host-associated.
+    However, it will not act like other Symbols
+    because user may have a reduction name
+    that is the same as a Fortran entity name in the same scope.
+    Therefore a specific data structure needs to be created
+    to save the *reduction-identifier* information
+    in the Scope and this directive needs to be written into ``.mod`` files
+
+Phases of OpenMP Analysis
+-------------------------
+
+
+#. Create the parse tree for OpenMP
+
+   #. Add types for directives and clauses
+
+      #. Add type(s) that will be used for directives
+      #. Add type(s) that will be used for clauses
+      #. Add other types, e.g. wrappers or other containers
+      #. Use std::variant to encapsulate meaningful types
+
+   #. Implemented in the parser for OpenMP (openmp-grammar.h)
+
+#. Create canonical nesting
+
+   #. Restructure parse tree to reflect the association
+      of directives and stmts
+
+      #. Associate ``OpenMPLoopConstruct``
+         with ``DoConstruct`` and ``OpenMPEndLoopDirective``
+
+   #. Investigate, and perhaps reuse,
+      the algorithm used to restructure do-loops
+   #. Add a pass near the code that restructures do-loops;
+      but do not extend the code that handles do-loop for OpenMP;
+      keep this code separate.
+   #. Report errors that prevent restructuring
+      (e.g. loop directive not followed by loop)
+      We should abort in case of errors
+      because there is no point to perform further checks
+      if it is not a legal OpenMP construct
+
+#. Validate the structured-block
+
+   #. Structured-block is a block of executable statements
+   #. Single entry and single exit
+   #. Access to the structured block must not be the result of a branch
+   #. The point of exit cannot be a branch out of the structured block
+
+#. Check that directive and clause combinations are legal
+
+   #. Begin and End directive should match
+   #. Simply check that the clauses are allowed by the directives
+   #. Write as a separate pass for simplicity and correctness of the parse tree
+
+#. Write parse tree tests
+
+   #. At this point, the parse tree should be perfectly formed
+   #. Write tests that check for correct form and provenance information
+   #. Write tests for errors that can occur during the restructuring
+
+#. Scope, symbol tables, and name resolution
+
+   #. Update the existing code to handle names and scopes introduced by OpenMP
+   #. Write tests to make sure names are properly implemented
+
+#. Check semantics that is specific to each directive
+
+   #. Validate the directive and its clauses
+   #. Some clause checks require the result of name resolution,
+      i.e. “A list item may appear in a *linear* or *firstprivate* clause
+      but not both.”
+   #. TBD:
+      Validate the nested statement for legality in the scope of the directive
+   #. Check the nesting of regions [OpenMP 4.5 spec 2.17]
+
+#. Module file utilities
+
+   #. Write necessary OpenMP declarative directives to ``.mod`` files
+   #. Update the existing code
+      to read available OpenMP directives from the ``.mod`` files

flang/docs/OptionComparison.rst

+Compiler options
+================
+
+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 **\ *\ `Notes section <#notes>`_\ *\ ** 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.
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#standards">Standards conformance</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong> </td>
+      <td><strong>Cray</strong> </td>
+      <td><strong>GNU</strong> </td>
+      <td><strong>IBM</strong> </td>
+      <td><strong>Intel</strong> </td>
+      <td><strong>PGI</strong> </td>
+      <td><strong>Flang</strong> </td>
+     </tr>
+     <tr>
+      <td>Overall conformance </td>
+      <td>en,
+   <p>
+   eN
+      </td>
+      <td>std=<em>level</em> </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=210">qlanglvl</a>, <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=257">qsaa</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-stand">stand level</a>
+      </td>
+      <td>Mstandard
+      </td>
+      <td>Mstandard
+      </td>
+     </tr>
+     <tr>
+      <td>Compatibility with previous standards or implementations
+      </td>
+      <td>N/A
+      </td>
+      <td>fdec,
+   <p>
+   fall-instrinsics
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=297">qxlf77</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=299">qxlf90</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=301">qxlf2003</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=305">qxfl2008</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=245">qport</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-f66">f66</a>,
+   <p>
+   <a href="https://software.intel.com/node/a8bfa478-22d5-4000-b0ac-b881804a7611">f77rtl</a>,
+   <p>
+   <a href="https://software.intel.com/node/647820a0-fc53-4252-a858-46feb012a281">fpscomp</a>,
+   <p>
+   <a href="https://software.intel.com/node/e610682a-00fe-4881-9cf7-8eee08c5f2a2">Intconstant</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-standard-realloc-lhs">nostandard-realloc-lhs</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-standard-semantics">standard-semantics</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume nostd_intent_in</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume nostd_value</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume norealloc_lhs</a>
+      </td>
+      <td>Mallocatable=95|03
+      </td>
+      <td>Mallocatable=95|03
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#source">Source format</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Fixed or free source
+      </td>
+      <td>f free,
+   <p>
+   f fixed
+      </td>
+      <td>ffree-form,
+   <p>
+   ffixed-form
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=179">qfree</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=169">qfixed</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-fixed">fixed</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-free">free</a>
+      </td>
+      <td>Mfree,
+   <p>
+   Mfixed
+      </td>
+      <td>Mfreeform,
+   <p>
+   Mfixed
+      </td>
+     </tr>
+     <tr>
+      <td>Source line length
+      </td>
+      <td>N <em>col</em>
+      </td>
+      <td>ffixed-line-length-n,
+   <p>
+   ffree-line-length-n
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=169">qfixed=n</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-extend-source">extend-source [size]</a>
+      </td>
+      <td>Mextend
+      </td>
+      <td>Mextend
+      </td>
+     </tr>
+     <tr>
+      <td>Column 1 comment specifier
+      </td>
+      <td>ed
+      </td>
+      <td>fd-lines-as-code,
+   <p>
+   fd-lines-as-comments
+      </td>
+      <td>D,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=161">qdlines</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=306">qxlines</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-d-lines-qd-lines">d-lines</a>
+      </td>
+      <td>Mdlines
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Don't treat CR character as a line terminator
+      </td>
+      <td>NA
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=153">qnocr</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Source file naming
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=282">qsuffix</a>
+      </td>
+      <td><a href="https://software.intel.com/node/84174680-3c7d-4225-9611-6083f496aa9b">extfor</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-tf">Tf filename</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#names">Names, Literals, and other tokens</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Max identifier length
+      </td>
+      <td>N/A
+      </td>
+      <td>fmax-identifier-length=<em>n</em>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>"$" in symbol names
+      </td>
+      <td>N/A
+      </td>
+      <td>fdollar-ok
+      </td>
+      <td>default
+      </td>
+      <td>default
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Allow names with leading "_"
+      </td>
+      <td>eQ
+      </td>
+      <td>N/A 
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Specify name format
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=296">U</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-names">names=keyword</a>
+      </td>
+      <td>Mupcase
+      </td>
+      <td>NA
+      </td>
+     </tr>
+     <tr>
+      <td>Escapes in literals
+      </td>
+      <td>N/A
+      </td>
+      <td>fbackslash
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=163">qescape</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume bscc</a>
+      </td>
+      <td>Mbackslash
+      </td>
+      <td>Mbackslash
+      </td>
+     </tr>
+     <tr>
+      <td>Allow multibyte characters in strings
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=223">qmbcs</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Create null terminated strings
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=228">qnullterm</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Character to use for "$"
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>Mdollar,<em>char</em>
+      </td>
+      <td>
+      </td>
+     </tr>
+     <tr>
+      <td>Allow PARAMETER statements without parentheses
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://software.intel.com/node/42e8ec08-64cc-44ba-a636-20ed50c682cd">altparam</a>
+      </td>
+      <td>N?A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#do">DO loop handling</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>One trip DO loops
+      </td>
+      <td>ej
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=113">1</a>,
+   <p>
+   <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=231">qonetrip</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-f66">f66</a>
+      </td>
+      <td>Monetrip
+      </td>
+      <td>N/A 
+      </td>
+     </tr>
+     <tr>
+      <td>Allow branching into loops
+      </td>
+      <td>eg
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#real">REAL, DOUBLE PRECISION, and COMPLEX Data</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Default REAL size
+      </td>
+      <td>s real32,
+   <p>
+   s real64,
+   <p>
+   s default32,
+   <p>
+   s default64
+      </td>
+      <td>fdefault-real-[8|10|16]
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=252">qrealsize=[4|8]</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-real-size">real-size [32|64|128]</a>
+      </td>
+      <td>r[4|8]
+      </td>
+      <td>r8,
+   <p>
+   fdefault-real-8
+      </td>
+     </tr>
+     <tr>
+      <td>Default DOUBLE PRECISION size
+      </td>
+      <td>ep
+      </td>
+      <td>fdefault-double-8
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-double-size">double-size[64|128]</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Make real constants DOUBLE PRECISION
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=161">qdpc</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Promote or demote REAL type sizes
+      </td>
+      <td>N/A
+      </td>
+      <td>freal-[4|8]-real[4|8|10|16]
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=144">qautodbl=size</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>Mr8,
+   <p>
+   Mr8intrinsics
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Rounding mode
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=190">qieee</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume std_minus0_rounding</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Treatment of -0.0
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume minus0</a>
+      </td>
+      <td>
+      </td>
+      <td>
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#integer">INTEGER and LOGICAL Data</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Default INTEGER size
+      </td>
+      <td>s integer32,
+   <p>
+   s integer64,
+   <p>
+   s default32,
+   <p>
+   s default64
+      </td>
+      <td>fdefault-integer-8
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=202">qintsize=[2|4|8]</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-integer-size">integer-size [32|64|128]</a>
+      </td>
+      <td>I[2|4|8],
+   <p>
+   Mi4,
+   <p>
+   Mnoi4
+      </td>
+      <td>i8,
+   <p>
+   fdefault-integer-8
+      </td>
+     </tr>
+     <tr>
+      <td>Promote INTEGER sizes
+      </td>
+      <td>N/A
+      </td>
+      <td>finteger-4-integer-8
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Enable 8 and 16 bit INTEGER and LOGICALS
+      </td>
+      <td>eh
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Change how the compiler treats LOGICAL
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>Munixlogical
+      </td>
+      <td>
+      </td>
+     </tr>
+     <tr>
+      <td>Treatment of numeric constants as arguments
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=297">qxlf77 oldboz</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume old_boz</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Treatment of assignment between numerics and logicals
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume old_logical_assign</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong>CHARACTER and Pointer Data</strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Use bytes for pointer arithmetic
+      </td>
+      <td>s byte_pointer
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Use words for pointer arithmetic
+      </td>
+      <td>S word_pointer
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Allow character constants for typeless constants
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=153">qctyplss</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong>Data types and allocation</strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Default to IMPLICIT NONE
+      </td>
+      <td>eI
+      </td>
+      <td>fimplicit-none
+      </td>
+      <td>u, <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=291">qundef</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-warn">warn declarations</a>
+      </td>
+      <td>Mdclchk
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Enable DEC STRUCTURE extensions
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://gcc.gnu.org/onlinedocs/gfortran/STRUCTURE-and-RECORD.html">fdec-structure</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www.pgroup.com/doc/pgi15fortref.pdf#page=86">default</a>
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Enable <a href="https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/types">Cray pointers</a>
+      </td>
+      <td>default
+      </td>
+      <td>fcray-pointer
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1#page=432">Default (near equivalent)</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-pointer-integer">Default (near equivalent)</a>
+      </td>
+      <td>Mcray
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Allow bitwise logical operations on numeric
+      </td>
+      <td>ee
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=201">qintlog</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Allow DEC STATIC and AUTOMATIC declarations
+      </td>
+      <td>default
+      </td>
+      <td>fdec-static
+      </td>
+      <td>Default, see <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1#page=393">IMPLICIT STATIC</a> and <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1#page=393">IMPLICIT AUTOMATIC</a>
+      </td>
+      <td>Default, see <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-automatic">AUTOMATIC</a> and <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-static-1#408BC4E6-7AA7-4475-A280-205D34AE2E4F">STATIC</a>
+      </td>
+      <td><a href="https://www.pgroup.com/doc/pgi15fortref.pdf#page=86">Default</a>
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Allocate variables to static storage
+      </td>
+      <td>ev
+      </td>
+      <td>fno-automatic
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=258">qsave</a>
+      </td>
+      <td><a href="https://software.intel.com/node/3ed16417-6eed-4e09-9edd-4ae03e77c6cf">save</a>,
+   <p>
+   <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-auto">noauto</a>
+      </td>
+      <td>Mnorecursive,
+   <p>
+   Msave
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Compile procedures as if RECURSIVE
+      </td>
+      <td>eR
+      </td>
+      <td>frecursive
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=254">q recur</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume recursion</a>,
+   <p>
+   <a href="https://software.intel.com/node/1c3820b4-42a1-48ea-887a-2cf39a41ce53">recursive</a>
+      </td>
+      <td>Mrecursive
+      </td>
+      <td>Mrecursive
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#arrays">Arrays</strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+     <tr>
+      <td>Enable coarrays
+      </td>
+      <td>h caf
+      </td>
+      <td>fcoarray=<em>key</em>
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-coarray-qcoarray">coarray[=keyword]</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Contiguous array pointers
+      </td>
+      <td>h contiguous
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=142">qassert=contig</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume contiguous_pointer</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Contiguous assumed shape dummy arguments
+      </td>
+      <td>h contiguous_assumed_shape
+      </td>
+      <td>frepack-arrays
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=142">qassert=contig</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume contiguous_assumed_shape</a>
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong>OpenACC, OpenMP, and CUDA</strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Enable OpenACC
+      </td>
+      <td> <a href="https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/program-model-specific-options">h acc</a>
+      </td>
+      <td>fopenacc
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td><a href="https://www.pgroup.com/resources/docs/19.1/x86/pgi-ref-guide/index.htm#acc">acc</a>
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Enable OpenMP
+      </td>
+      <td> <a href="https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/program-model-specific-options">h omp</a>
+      </td>
+      <td>fopenmp
+      </td>
+      <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=285">qswapomp</a>
+      </td>
+      <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-qopenmp-qopenmp">qopenmp</a>,
+   <p>
+   <a href="https://software.intel.com/node/26d2aef3-9c68-4ef2-9241-bce168a48629">qopenmp-lib</a>,
+   <p>
+   <a href="https://software.intel.com/node/f8d22e40-7ed0-4ec6-8e80-d4d27010ca8b">qopenmp-link</a>,
+   <p>
+   <a href="https://software.intel.com/node/2cc99a64-9605-44e2-b40a-1409ba459a62">qopenmp-offload</a>,
+   <p>
+   <a href="https://software.intel.com/node/02ef8658-3e66-4634-8a11-68eec60322c1">qopenmp-simd</a>,
+   <p>
+   <a href="https://software.intel.com/node/088272f2-5eae-42c2-a053-20f42022343d">qopenmp-stubs</a>,
+   <p>
+   <a href="https://software.intel.com/node/0ed8bee0-62b4-4266-8cbb-f25b585d4800">qopenmp-threadprivate</a>
+      </td>
+      <td><a href="https://www.pgroup.com/resources/docs/19.1/x86/pgi-ref-guide/index.htm#mp">mp</a>,
+   <p>
+   Mcuda
+      </td>
+      <td>-mp
+      </td>
+     </tr>
+   </table>
+
+
+
+.. raw:: html
+
+   <table>
+     <tr>
+      <td colspan="7" ><strong><a href="#miscellaneous">Miscellaneous</a></strong>
+      </td>
+     </tr>
+     <tr>
+      <td><strong>Option</strong>
+      </td>
+      <td><strong>Cray</strong>
+      </td>
+      <td><strong>GNU</strong>
+      </td>
+      <td><strong>IBM</strong>
+      </td>
+      <td><strong>Intel</strong>
+      </td>
+      <td><strong>PGI</strong>
+      </td>
+      <td><strong>Flang</strong>
+      </td>
+     </tr>
+     <tr>
+      <td>Disable compile time range checking
+      </td>
+      <td> N/A
+      </td>
+      <td>fno-range-check
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Disable call site checking
+      </td>
+      <td>dC
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Warn for bad call checking
+      </td>
+      <td>eb
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Set default accessibility of module entities to PRIVATE
+      </td>
+      <td>N/A
+      </td>
+      <td>fmodule-private
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+     <tr>
+      <td>Force FORALL to use temp
+      </td>
+      <td>N/A
+      </td>
+      <td>ftest-forall-temp
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+      <td>N/A
+      </td>
+     </tr>
+   </table>
+
+
+:raw-html-m2r:`<a name="notes"></a>`\ Notes
+---------------------------------------------
+
+**\ :raw-html-m2r:`<a name="standards"></a>`\ 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.*
+
+**\ :raw-html-m2r:`<a name="source"></a>`\ Source format:** 
+
+**Fixed or free source:**  Cray, IBM, and Intel default the source format based on the source file suffix as follows:
+
+
+* **Cray**
+
+  * **Free:** .f90, .F90, .f95, .F95, .f03, .F03, .f08, .F08, .ftn, .FTN
+  * **Fixed:** .f, .F, .for, .FOR
+
+* **Intel**
+
+  * **Free:** .f90, .F90, .i90
+  * **Fixed:** .f, .for, .FOR, .ftn, .FTN, .fpp, .FPP, .i
+
+IBM Fortran's options allow the source line length to be specified with the option, e.g., "-qfixed=72".  IBM bases the default on the name of the command used to invoke the compiler.  IBM has 16 different commands that invoke the Fortran compiler, and the default use of free or fixed format and the line length are based on the command name.  -qfixed=72 is the default for the xlf, xlf_r, f77, and fort77 commands. -qfree=f90is the default for the f90, xlf90, xlf90_r, f95, xlf95, xlf95_r, f2003, xlf2003, xlf2003_r, f2008, xlf2008, and xlf2008_r commands.  The maximum line length for either source format is 132 characters.
+
+**Column 1 comment specifier:**  All compilers allow "D" in column 1 to specify that the line contains a comment and have this as the default for fixed format source.  IBM also supports an "X" in column 1 with the option "-qxlines".
+
+**Source line length:**
+
+
+* **Cray:** The "-N *col*\ " option specifies the line width for fixed- and free-format source lines. The value used for col specifies the maximum number of columns per line.  For free form sources, col can be set to 132, 255, or 1023.  For fixed form sources, col can be set to 72, 80, 132, 255, or 1023.  Characters in columns beyond the col specification are ignored.  By default, lines are 72 characters wide for fixed-format sources and 255 characters wide for free-form sources.
+* **GNU:** For both "ffixed-line-length-\ *n*\ " and "ffree-line-length-\ *n*\ " options, characters are ignored after the specified length.  The default for fixed is 72.  The default for free is 132.  For free, you can specify 'none' as the length, which means that all characters in the line are meaningful.
+* **IBM:** For **fixed**\ , the default is 72.  For **free**\ , there's no default, but the maximum length for either form is 132.
+* **Intel:** The default is 72 for **fixed** and 132 for **free**.
+* **PGI, Flang:** 
+
+  * in free form, it is an error if the line is longer than 1000 characters
+  * in fixed form by default, characters after column 72 are ignored
+  * in fixed form with -Mextend, characters after column 132 are ignored
+
+**\ :raw-html-m2r:`<a name="names"></a>`\ Names, Literals, and other tokens**
+
+**Escapes in literals:**
+
+
+* **GNU:** The "-fbackslash" option the interpretation of backslashes in string literals from a single backslash character to "C-style" escape characters. The following combinations are expanded \a, \b, \f, \n, \r, \t, \v, \, and \0 to the ASCII characters alert, backspace, form feed, newline, carriage return, horizontal tab, vertical tab, backslash, and NUL, respectively. Additionally, \xnn, \unnnn and \Unnnnnnnn (where each n is a hexadecimal digit) are translated into the Unicode characters corresponding to the specified code points. All other combinations of a character preceded by are unexpanded.
+* **Intel:** The option "-assume bscc" tells the compiler to treat the backslash character () as a C-style control (escape) character syntax in character literals. "nobscc" specifies that the backslash character is treated as a normal character in character literals.  This is the default.
+
+**"$" in symbol names:** Allowing "$" in names is controlled by an option in GNU and is the default behavior in IBM and Intel.  Presumably, these compilers issue warnings when standard conformance options are enabled.  Dollar signs in names don't seem to be allowed in Cray, PGI, or Flang.
+
+**\ :raw-html-m2r:`<a name="do"></a>`\ DO loop handling**
+
+**One trip:**
+
+
+* **IBM:** IBM has two options that do the same thing: "-1" and "-qonetrip".
+* **Intel:** Intel used to support a "-onetrip" option, but it has been removed.  Intel now supports a "-f66" option that ensures that DO loops are executed at least once in addition to `several other Fortran 66 semantic features <https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-f66#320D769C-7C41-4A84-AE0E-50A72296A838>`_.
+
+**\ :raw-html-m2r:`<a name="real"></a>`\ REAL, DOUBLE PRECISION, and COMPLEX Data**
+
+These size options affect the sizes of variables, literals, and intrinsic function results.
+
+**Default REAL sizes:** These options do not affect the size of explicitly declared data (for example, REAL(KIND=4).
+
+
+* **Cray:** The "-s default32" and "-s default64" options affect both REAL, INTEGER, and LOGICAL types.
+
+**Default DOUBLE PRECISION:** These options allow control of the size of DOUBLE PRECISION types in conjunction with controlling REAL types.
+
+
+* **Cray:** The "-ep" option controls DOUBLE PRECISION. This option can only be enabled when the default data size is 64 bits ("-s default64" or "-s real64").  When "-s default64" or "-s real64" is specified, and double precision arithmetic is disabled, DOUBLE PRECISION variables and constants specified with the D exponent are converted to default real type (64-bit). If double precision is enabled ("-ep"), they are handled as a double precision type (128-bit).  Similarly when the "-s default64" or" -s real64" option is used, variables declared on a DOUBLE COMPLEX statement and complex constants specified with the D exponent are mapped to the complex type in which each part has a default real type, so the complex variable is 128-bit. If double precision is enabled ("-ep"), each part has double precision type, so the double complex variable is 256-bit.
+* **GNU:** The "-fdefault-double-8" option sets the DOUBLE PRECISION type to an 8 byte wide type. Do nothing if this is already the default. If "-fdefault-real-8" is given, DOUBLE PRECISION would instead be promoted to 16 bytes if possible, and "-fdefault-double-8" can be used to prevent this. The kind of real constants like 1.d0 will not be changed by "-fdefault-real-8" though, so also "-fdefault-double-8" does not affect it.
+
+**Promote or demote REAL type sizes:** These options change the meaning of data types specified by declarations of the form REAL(KIND=\ *N*\ ), except, perhaps for PGI.
+
+
+* **GNU:** The allowable combinations are "-freal-4-real-8", "-freal-4-real-10", "-freal-4-real-16", "-freal-8-real-4", "-freal-8-real-10", and "-freal-8-real-16".
+* **IBM:** The "-qautodbl" option  is documented `here <https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=144>`_.
+* **PGI:** The "-Mr8" option promotes REAL variables and constants to DOUBLE PRECISION variables and constants, respectively. DOUBLE PRECISION elements are 8 bytes in length.  The "-Mr8intrinsics" option promotes the intrinsics CMPLX and REAL as DCMPLX and DBLE, respectively.
+
+**\ :raw-html-m2r:`<a name="integer"></a>`\ INTEGER and LOGICAL Data**
+
+These size options affect the sizes of variables, literals, and intrinsic function results.
+
+**Default INTEGER sizes:** For all compilers, these options affect both INTEGER and LOGICAL types.
+
+**Enable 8 and 16 bit INTEGER and LOGICAL:** This Cray option ("-eh") enables support for 8-bit and 16-bit INTEGER and LOGICAL types that use explicit kind or star values.  By default ("-eh"), data objects declared as INTEGER(kind=1) or LOGICAL(kind=1) are 8 bits long, and objects declared as INTEGER(kind=2) or LOGICAL(kind=2) are 16 bits long. When this option is disabled ("-dh"), data objects declared as INTEGER(kind=1), INTEGER(kind=2), LOGICAL(kind=1), or LOGICAL(kind=2) are 32 bits long.
+
+**Intrinsic functions**
+
+GNU is the only compiler with options governing the use of non-standard intrinsics.  For more information on the GNU options, see `here <https://gcc.gnu.org/onlinedocs/gcc-8.3.0/gfortran/Fortran-Dialect-Options.html#Fortran-Dialect-Options>`_.  All compilers implement non-standard intrinsics but don't have options that affect access to them.
+
+**\ :raw-html-m2r:`<a name="arrays"></a>`\ Arrays**
+
+**Contiguous array pointers:** All vendors that implement this option (Cray, IBM, and Intel) seem to have apply to all pointer targets.  Assuming that the arrays that are targeted by the pointers allows greater optimization.
+
+**Contiguous assumed shape dummy arguments:** Cray and Intel have a separate argument that's specific to assumed shape dummy arguments.
+
+**\ :raw-html-m2r:`<a name="miscellaneous"></a>`\ Miscellaneous**
+
+**Disable call site checking:**  This Cray option ("-dC") disables some types of standard call site checking. The current Fortran standard requires that the number and types of arguments must agree between the caller and callee. These constraints are enforced in cases where the compiler can detect them, however, specifying "-dC" disables some of this error checking, which may be necessary in order to get some older Fortran codes to compile.  If error checking is disabled, unexpected compile-time or run time results may occur.  The compiler by default attempts to detect situations in which an interface block should be specified but is not. Specifying "-dC" disables this type of checking as well.
+
+**Warn for bad call checking**\ : This Cray option ("-eb") issues a warning message rather than an error message when the compiler detects a call to a procedure with one or more dummy arguments having the TARGET, VOLATILE or ASYNCHRONOUS attribute and there is not an explicit interface definition.
+
+Notes
+-----
+
+What is and is not included
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This document focuses on options relevant to the Fortran language.  This includes some features (such as recursion) that are only indirectly related.  Options related to the following areas are not included:
+
+
+* Input/Output
+* Optimization
+* Preprocessing
+* Inlining
+* Alternate library definition or linking
+* Choosing file locations for compiler input or output
+* Modules
+* Warning and error messages and listing output
+* Data initialization
+* Run time checks
+* Debugging
+* Specification of operating system
+* Target architecture
+* Assembler generation
+* Threads or parallelization
+* Profiling and code coverage
+
+Data sources
+^^^^^^^^^^^^
+
+Here's the list of compilers surveyed, hot linked to the source of data on it.  Note that this is the only mention of the Oracle and NAG compilers in this document.
+
+
+* `Cray Fortran Reference Manual version 8.7 <https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/compiler-command-line-options>`_
+* IBM  (XLF) version 14.1 -- `Compiler Referenc <https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=93>`_\ e, `Language Reference <https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1>`_
+* `Intel Fortran version 19.0 <https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-alphabetical-list-of-compiler-options>`_
+* `GNU Fortran Compiler version 8.3.0 <https://gcc.gnu.org/onlinedocs/gcc-8.3.0/gfortran/Option-Summary.html>`_
+* `NAG Fortran Release 6.2 <https://www.nag.co.uk/nagware/np/r62_doc/manual/compiler_2_4.html>`_
+* `Oracle Fortran version 819-0492-10 <https://docs.oracle.com/cd/E19059-01/stud.10/819-0492/3_options.html>`_
+* PGI -- `Compiler Reference version 19.1 <https://www.pgroup.com/resources/docs/19.1/x86/pgi-ref-guide/index.htm#cmdln-options-ref>`_\ , `Fortran Reference Guide version 17 <https://www.pgroup.com/doc/pgi17fortref.pdf>`_
+* `Flang <https://github.com/flang-compiler/flang/wiki/Using-Flang>`_ -- information from GitHub
+
+This document has been kept relatively small by providing links to much of the information about options rather than duplicating that information.  For IBM, Intel, and some PGI options, there are direct links.  But direct links were not possible for Cray, GNU and some PGI options.
+
+Many compilers have options that can either be enabled or disabled.  Some compilers indicate this by the presence or absence of the letters "no" in the option name (IBM, Intel, and PGI) while Cray precedes many options with either "e" for enabled or "d" for disabled.  This document only includes the enabled version of the option specification.
+
+Deprecated options were generally ignored, even though they were documented.

flang/docs/Overview.rst

+Overview of Compiler Phases
+===========================
+
+Each phase produces either correct output or fatal errors.
+
+Prescan and Preprocess
+----------------------
+
+See: `Preprocessing.rst <Preprocessing.rst>`_.
+
+**Input:** Fortran source and header files, command line macro definitions,
+  set of enabled compiler directives (to be treated as directives rather than
+  comments).
+
+**Output:**
+
+
+* A "cooked" character stream: the entire program as a contiguous stream of
+  normalized Fortran source.
+  Extraneous whitespace and comments are removed (except comments that are
+  compiler directives that are not disabled) and case is normalized.
+* Provenance information mapping each character back to the source it came from.
+  This is used in subsequent phases to issue errors messages that refer to source locations.
+
+**Entry point:** ``parser::Parsing::Prescan``
+
+**Command:** ``f18 -E src.f90`` dumps the cooked character stream
+
+Parse
+-----
+
+**Input:** Cooked character stream.
+
+**Output:** A parse tree representing a syntactically correct program,
+  rooted at a ``parser::Program``.
+  See: `Parsing.rst <Parsing.rst>`_ and `ParserCombinators.rst <ParserCombinators.rst>`_.
+
+**Entry point:** ``parser::Parsing::Parse``
+
+**Command:**
+
+
+* ``f18 -fdebug-dump-parse-tree -fparse-only src.f90`` dumps the parse tree
+* ``f18 -funparse src.f90`` converts the parse tree to normalized Fortran
+
+Validate Labels and Canonicalize Do Statements
+----------------------------------------------
+
+**Input:** Parse tree.
+
+**Output:** The parse tree with label constraints and construct names checked,
+  and each ``LabelDoStmt`` converted to a ``NonLabelDoStmt``.
+  See: `LabelResolution.rst <LabelResolution.rst>`_.
+
+**Entry points:** ``semantics::ValidateLabels``\ , ``parser::CanonicalizeDo``
+
+Resolve Names
+-------------
+
+**Input:** Parse tree (without ``LabelDoStmt``\ ) and ``.mod`` files from compilation
+  of USEd modules.
+
+**Output:**
+
+
+* Tree of scopes populated with symbols and types
+* Parse tree with some refinements:
+
+  * each ``parser::Name::symbol`` field points to one of the symbols
+  * each ``parser::TypeSpec::declTypeSpec`` field points to one of the types
+  * array element references that were parsed as function references or
+    statement functions are corrected
+
+**Entry points:** ``semantics::ResolveNames``\ , ``semantics::RewriteParseTree``
+
+**Command:** ``f18 -fdebug-dump-symbols -fparse-only src.f90`` dumps the
+  tree of scopes and symbols in each scope
+
+Check DO CONCURRENT Constraints
+-------------------------------
+
+**Input:** Parse tree with names resolved.
+
+**Output:** Parse tree with semantically correct DO CONCURRENT loops.
+
+Write Module Files
+------------------
+
+**Input:** Parse tree with names resolved.
+
+**Output:** For each module and submodule, a ``.mod`` file containing a minimal
+  Fortran representation suitable for compiling program units that depend on it.
+  See `ModFiles.rst <ModFiles.rst>`_.
+
+Analyze Expressions and Assignments
+-----------------------------------
+
+**Input:** Parse tree with names resolved.
+
+**Output:** Parse tree with ``parser::Expr::typedExpr`` filled in and semantic
+  checks performed on all expressions and assignment statements.
+
+**Entry points**\ : ``semantics::AnalyzeExpressions``\ , ``semantics::AnalyzeAssignments``
+
+Produce the Intermediate Representation
+---------------------------------------
+
+**Input:** Parse tree with names and labels resolved.
+
+**Output:** An intermediate representation of the executable program.
+  See `FortranIR.rst <FortranIR.rst>`_.

flang/docs/ParserCombinators.rst

+Concept
+-------
+
+The Fortran language recognizer here can be classified as an LL recursive
+descent parser.  It is composed from a *parser combinator* library that
+defines a few fundamental parsers and a few ways to compose them into more
+powerful parsers.
+
+For our purposes here, a *parser* is any object that attempts to recognize
+an instance of some syntax from an input stream.  It may succeed or fail.
+On success, it may return some semantic value to its caller.
+
+In C++ terms, a parser is any instance of a class that
+
+
+#. has a ``constexpr`` default constructor,
+#. defines a type named ``resultType``\ , and
+#. provides a function (\ ``const`` member or ``static``\ ) that accepts a reference to a
+   ``ParseState`` as its argument and returns a ``std::optional<resultType>`` as a
+   result, with the presence or absence of a value in the ``std::optional<>``
+   signifying success or failure, respectively.
+   .. code-block::
+
+      std::optional<resultType> Parse(ParseState &) const;
+   The ``resultType`` of a parser is typically the class type of some particular
+   node type in the parse tree.
+
+``ParseState`` is a class that encapsulates a position in the source stream,
+collects messages, and holds a few state flags that determine tokenization
+(e.g., are we in a character literal?).  Instances of ``ParseState`` are
+independent and complete -- they are cheap to duplicate whenever necessary to
+implement backtracking.
+
+The ``constexpr`` default constructor of a parser is important.  The functions
+(below) that operate on instances of parsers are themselves all ``constexpr``.
+This use of compile-time expressions allows the entirety of a recursive
+descent parser for a language to be constructed at compilation time through
+the use of templates.
+
+Fundamental Predefined Parsers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These objects and functions are (or return) the fundamental parsers:
+
+
+* ``ok`` is a trivial parser that always succeeds without advancing.
+* ``pure(x)`` returns a trivial parser that always succeeds without advancing,
+  returning some value ``x``.
+* ``pure<T>()`` is ``pure(T{})`` but does not require that T be copy-constructible.
+* ``fail<T>(msg)`` denotes a trivial parser that always fails, emitting the
+  given message as a side effect.  The template parameter is the type of
+  the value that the parser never returns.
+* ``nextCh`` consumes the next character and returns its location,
+  and fails at EOF.
+* ``"xyz"_ch`` succeeds if the next character consumed matches any of those
+  in the string and returns its location.  Be advised that the source
+  will have been normalized to lower case (miniscule) letters outside
+  character and Hollerith literals and edit descriptors before parsing.
+
+Combinators
+^^^^^^^^^^^
+
+These functions and operators combine existing parsers to generate new parsers.
+They are ``constexpr``\ , so they should be viewed as type-safe macros.
+
+
+* ``!p`` succeeds if p fails, and fails if p succeeds.
+* ``p >> q`` fails if p does, otherwise running q and returning its value when
+  it succeeds.
+* ``p / q`` fails if p does, otherwise running q and returning p's value
+  if q succeeds.
+* ``p || q`` succeeds if p does, otherwise running q.  The two parsers must
+  have the same type, and the value returned by the first succeeding parser
+  is the value of the combination.
+* ``first(p1, p2, ...)`` returns the value of the first parser that succeeds.
+  All of the parsers in the list must return the same type.
+  It is essentially the same as ``p1 || p2 || ...`` but has a slightly
+  faster implementation and may be easier to format in your code.
+* ``lookAhead(p)`` succeeds if p does, but doesn't modify any state.
+* ``attempt(p)`` succeeds if p does, safely preserving state on failure.
+* ``many(p)`` recognizes a greedy sequence of zero or more nonempty successes
+  of p, and returns ``std::list<>`` of their values.  It always succeeds.
+* ``some(p)`` recognized a greedy sequence of one or more successes of p.
+  It fails if p immediately fails.
+* ``skipMany(p)`` is the same as ``many(p)``\ , but it discards the results.
+* ``maybe(p)`` tries to match p, returning an ``std::optional<T>`` value.
+  It always succeeds.
+* ``defaulted(p)`` matches p, and when p fails it returns a
+  default-constructed instance of p's resultType.  It always succeeds.
+* ``nonemptySeparated(p, q)`` repeatedly matches "p q p q p q ... p",
+  returning a ``std::list<>`` of only the values of the p's.  It fails if
+  p immediately fails.
+* ``extension(p)`` parses p if strict standard compliance is disabled,
+   or with a warning if nonstandard usage warnings are enabled.
+* ``deprecated(p)`` parses p if strict standard compliance is disabled,
+  with a warning if deprecated usage warnings are enabled.
+* ``inContext(msg, p)`` runs p within an error message context; any
+  message that ``p`` generates will be tagged with ``msg`` as its
+  context.  Contexts may nest.
+* ``withMessage(msg, p)`` succeeds if ``p`` does, and if it does not,
+  it discards the messages from ``p`` and fails with the specified message.
+* ``recovery(p, q)`` is equivalent to ``p || q``\ , except that error messages
+  generated from the first parser are retained, and a flag is set in
+  the ParseState to remember that error recovery was necessary.
+* ``localRecovery(msg, p, q)`` is equivalent to
+  ``recovery(withMessage(msg, p), q >> pure<A>())`` where ``A`` is the
+  result type of 'p'.
+  It is useful for targeted error recovery situations within statements.
+
+Note that
+
+.. code-block::
+
+   a >> b >> c / d / e
+
+matches a sequence of five parsers, but returns only the result that was
+obtained by matching ``c``.
+
+Applicatives
+^^^^^^^^^^^^
+
+The following *applicative* combinators combine parsers and modify or
+collect the values that they return.
+
+
+* ``construct<T>(p1, p2, ...)`` matches zero or more parsers in succession,
+  collecting their results and then passing them with move semantics to a
+  constructor for the type T if they all succeed.
+  If there is a single parser as the argument and it returns no usable
+  value but only success or failure (\ *e.g.,* ``"IF"_tok``\ ), the default
+  nullary constructor of the type ``T`` is called.
+* ``sourced(p)`` matches p, and fills in its ``source`` data member with the
+  locations of the cooked character stream that it consumed
+* ``applyFunction(f, p1, p2, ...)`` matches one or more parsers in succession,
+  collecting their results and passing them as rvalue reference arguments to
+  some function, returning its result.
+* ``applyLambda([](&&x){}, p1, p2, ...)`` is the same thing, but for lambdas
+  and other function objects.
+* ``applyMem(mf, p1, p2, ...)`` is the same thing, but invokes a member
+  function of the result of the first parser for updates in place.
+
+Token Parsers
+^^^^^^^^^^^^^
+
+Last, we have these basic parsers on which the actual grammar of the Fortran
+is built.  All of the following parsers consume characters acquired from
+``nextCh``.
+
+
+* ``space`` always succeeds after consuming any spaces
+* ``spaceCheck`` always succeeds after consuming any spaces, and can emit
+  a warning if there was no space in free form code before a character
+  that could continue a name or keyword
+* ``digit`` matches one cooked decimal digit (0-9)
+* ``letter`` matches one cooked letter (A-Z)
+* ``"..."_tok`` match the content of the string, skipping spaces before and
+  after.  Internal spaces are optional matches.  The ``_tok`` suffix is
+  optional when the parser appears before the combinator ``>>`` or after
+  the combinator ``/``.
+* ``"..."_sptok`` is a string match in which the spaces are required in
+   free form source.
+* ``"..."_id`` is a string match for a complete identifier (not a prefix of
+   a longer identifier or keyword).
+* ``parenthesized(p)`` is shorthand for ``"(" >> p / ")"``.
+* ``bracketed(p)`` is shorthand for ``"[" >> p / "]"``.
+* ``nonEmptyList(p)`` matches a comma-separated list of one or more
+  instances of p.
+* ``nonEmptyList(errorMessage, p)`` is equivalent to
+  ``withMessage(errorMessage, nonemptyList(p))``\ , which allows one to supply
+  a meaningful error message in the event of an empty list.
+* ``optionalList(p)`` is the same thing, but can be empty, and always succeeds.
+
+Debugging Parser
+^^^^^^^^^^^^^^^^
+
+Last, a string literal ``"..."_debug`` denotes a parser that emits the string to
+``llvm::errs`` and succeeds.  It is useful for tracing while debugging a parser but should
+obviously not be committed for production code.

flang/docs/Parsing.rst

-<!--===- documentation/Parsing.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
-  
--->
-
 The F18 Parser
 ==============
+
 This program source code implements a parser for the Fortran programming
 language.
 
 The draft ISO standard for Fortran 2018 dated July 2017 was used as the
 primary definition of the language.  The parser also accepts many features
 from previous versions of the standard that are no longer part of the Fortran
 2018 language.
 

 The several major modules of the Fortran parser are composed into a
 top-level Parsing class, by means of which one may drive the parsing of a
 source file and receive its parse tree and error messages.  The interfaces
 of the Parsing class correspond to the two major passes of the parser,
 which are described below.
 
 Prescanning and Preprocessing
 -----------------------------
+
 The first pass is performed by an instance of the Prescanner class,
 with help from an instance of Preprocessor.
 
 The prescanner generates the "cooked character stream", implemented
 by a CookedSource class instance, in which:
+
+
 * line ends have been normalized to single ASCII LF characters (UNIX newlines)
-* all `INCLUDE` files have been expanded
+* all ``INCLUDE`` files have been expanded
 * all continued Fortran source lines have been unified
 * all comments and insignificant spaces have been removed
 * fixed form right margins have been clipped
 * extra blank card columns have been inserted into character literals
   and Hollerith constants
 * preprocessing directives have been implemented
 * preprocessing macro invocations have been expanded
-* legacy `D` lines in fixed form source have been omitted or included
+* legacy ``D`` lines in fixed form source have been omitted or included
 * except for the payload in character literals, Hollerith constants,
   and character and Hollerith edit descriptors, all letters have been
   normalized to lower case
 * all original non-ASCII characters in Hollerith constants have been
   decoded and re-encoded into UTF-8
 
 Lines in the cooked character stream can be of arbitrary length.
 
 The purpose of the cooked character stream is to enable the implementation
 of a parser whose sole concern is the recognition of the Fortran language
 from productions that closely correspond to the grammar that is presented
 in the Fortran standard, without having to deal with the complexity of
 all of the source-level concerns in the preceding list.
 
 The implementation of the preprocessor interacts with the prescanner by
-means of _token sequences_.  These are partitionings of input lines into
+means of *token sequences*.  These are partitionings of input lines into
 contiguous virtual blocks of characters, and are the only place in this
 Fortran compiler in which we have reified a tokenization of the program
 source; the parser proper does not have a tokenizer.  The prescanner
 builds these token sequences out of source lines and supplies them
 to the preprocessor, which interprets directives and expands macro
 invocations.  The token sequences returned by the preprocessor are then
 marshaled to constitute the cooked character stream that is the output of
 the prescanner.

 The preprocessor always runs.  There's no good reason for it not to.
 
 The content of the cooked character stream is available and useful
 for debugging, being as it is a simple value forwarded from the first major
 pass of the compiler to the second.
 
 Source Provenance
 -----------------
+
 The prescanner constructs a chronicle of every file that is read by the
 parser, viz. the original source file and all others that it directly
 or indirectly includes.  One copy of the content of each of these files
 is mapped or read into the address space of the parser.  Memory mapping
 is used initially, but files with DOS line breaks or a missing terminal
 newline are immediately normalized in a buffer when necessary.
 
 The virtual input stream, which marshals every appearance of every file
 and every expansion of every macro invocation, is not materialized as
 an actual stream of bytes.  There is, however, a mapping from each byte
 position in this virtual input stream back to whence it came (maintained
 by an instance of the AllSources class).  Offsets into this virtual input
 stream constitute values of the Provenance class.  Provenance values,
 and contiguous ranges thereof, are used to describe and delimit source
 positions for messaging.
 
 Further, every byte in the cooked character stream supplied by the
 prescanner to the parser can be inexpensively mapped to its provenance.
-Simple `const char *` pointers to characters in the cooked character
+Simple ``const char *`` pointers to characters in the cooked character
 stream, or to contiguous ranges thereof, are used as source position
 indicators within the parser and in the parse tree.
 
 Messages
 --------
+
 Message texts, and snprintf-like formatting strings for constructing
 messages, are instantiated in the various components of the parser with
-C++ user defined character literals tagged with `_err_en_US` and `_en_US`
+C++ user defined character literals tagged with ``_err_en_US`` and ``_en_US``
 (signifying fatality and language, with the default being the dialect of
 English used in the United States) so that they may be easily identified
 for localization.  As described above, messages are associated with
 source code positions by means of provenance values.
 
 The Parse Tree
 --------------
+
 Each of the ca. 450 numbered requirement productions in the standard
 Fortran language grammar, as well as the productions implied by legacy
 extensions and preserved obsolescent features, maps to a distinct class
 in the parse tree so as to maximize the efficacy of static type checking
 by the C++ compiler.
 
 A transcription of the Fortran grammar appears with production requirement
 numbers in the commentary before these class definitions, so that one
 may easily refer to the standard (or to the parse tree definitions while
 reading that document).
 
 Three paradigms collectively implement most of the parse tree classes:
-* *wrappers*, in which a single data member `v` has been encapsulated
+
+
+* *wrappers*\ , in which a single data member ``v`` has been encapsulated
   in a new type
 * *tuples* (or product types), in which several values of arbitrary
-  types have been encapsulated in a single data member `t` whose type
-  is an instance of `std::tuple<>`
+  types have been encapsulated in a single data member ``t`` whose type
+  is an instance of ``std::tuple<>``
 * *discriminated unions* (or sum types), in which one value whose type is
   a dynamic selection from a set of distinct types is saved in a data
-  member `u` whose type is an instance of `std::variant<>`
+  member ``u`` whose type is an instance of ``std::variant<>``
 
 The use of these patterns is a design convenience, and exceptions to them
 are not uncommon wherever it made better sense to write custom definitions.
 
 Parse tree entities should be viewed as values, not objects; their
 addresses should not be abused for purposes of identification.  They are
 assembled with C++ move semantics during parse tree construction.
 Their default and copy constructors are deliberately deleted in their
 declarations. 
 
 The std::list<> data type is used in the parse tree to reliably store pointers
 to other relevant entries in the tree. Since the tree lists are moved and
 spliced at certain points std::list<> provides the necessary guarantee of the
 stability of pointers into these lists.
 
 There is a general purpose library by means of which parse trees may
 be traversed.
 
 Parsing
 -------
+
 This compiler attempts to recognize the entire cooked character stream
 (see above) as a Fortran program.  It records the reductions made during
 a successful recognition as a parse tree value.  The recognized grammar
 is that of a whole source file, not just of its possible statements,
 so the parser has no global state that tracks the subprogram hierarchy
 or the structure of their nested block constructs.  The parser performs
 no semantic analysis along the way, deferring all of that work to the
 next pass of the compiler.
 
 The resulting parse tree therefore necessarily contains ambiguous parses
 that cannot be resolved without recourse to a symbol table.  Most notably,
 leading assignments to array elements can be misrecognized as statement
 function definitions, and array element references can be misrecognized
 as function calls.  The semantic analysis phase of the compiler performs
 local rewrites of the parse tree once it can be disambiguated by symbols
 and types.
 
 Formally speaking, this parser is based on recursive descent with
 localized backtracking (specifically, it will not backtrack into a
 successful reduction to try its other alternatives).  It is not generated
 as a table or code from a specification of the Fortran grammar; rather, it
-_is_ the grammar, as declaratively respecified in C++ constant expressions
+*is* the grammar, as declaratively respecified in C++ constant expressions
 using a small collection of basic token recognition objects and a library
 of "parser combinator" template functions that compose them to form more
 complicated recognizers and their correspondences to the construction
 of parse tree values.
 
 Unparsing
 ---------
+
 Parse trees can be converted back into free form Fortran source code.
 This formatter is not really a classical "pretty printer", but is
 more of a data structure dump whose output is suitable for compilation
 by another compiler.  It is also used for testing the parser, since a
 reparse of an unparsed parse tree should be an identity function apart from
 source provenance.

flang/docs/Preprocessing.rst

+Fortran Preprocessing
+=====================
+
+Behavior common to (nearly) all compilers:
+------------------------------------------
+
+
+* Macro and argument names are sensitive to case.
+* Fixed form right margin clipping after column 72 (or 132)
+  has precedence over macro name recognition, and also over
+  recognition of function-like parentheses and arguments.
+* Fixed form right margin clipping does not apply to directive lines.
+* Macro names are not recognized as such when spaces are inserted
+  into their invocations in fixed form.
+  This includes spaces at the ends of lines that have been clipped
+  at column 72 (or whatever).
+* Text is rescanned after expansion of macros and arguments.
+* Macros are not expanded within quoted character literals or
+  quoted FORMAT edit descriptors.
+* Macro expansion occurs before any effective token pasting via fixed form
+  space removal.
+* C-like line continuations with backslash-newline are allowed in
+  directives, including the definitions of macro bodies.
+* ``/* Old style C comments */`` are ignored in directives and
+  removed from the bodies of macro definitions.
+* ``// New style C comments`` are not removed, since Fortran has OPERATOR(//).
+* C-like line continuations with backslash-newline can appear in
+  old-style C comments in directives.
+* After ``#define FALSE TRUE``\ , ``.FALSE.`` is replaced by ``.TRUE.``\ ;
+  i.e., tokenization does not hide the names of operators or logical constants.
+* ``#define KWM c`` allows the use of ``KWM`` in column 1 as a fixed form comment
+  line indicator.
+* A ``#define`` directive intermixed with continuation lines can't
+  define a macro that's invoked earlier in the same continued statement.
+
+Behavior that is not consistent over all extant compilers but which
+
+probably should be uncontroversial:
+-----------------------------------
+
+
+* Invoked macro names can straddle a Fortran line continuation.
+* ... unless implicit fixed form card padding intervenes; i.e.,
+  in fixed form, a continued macro name has to be split at column
+  72 (or 132).
+* Comment lines may appear with continuations in a split macro names.
+* Function-like macro invocations can straddle a Fortran fixed form line
+  continuation between the name and the left parenthesis, and comment and
+  directive lines can be there too.
+* Function-like macro invocations can straddle a Fortran fixed form line
+  continuation between the parentheses, and comment lines can be there too.
+* Macros are not expanded within Hollerith constants or Hollerith
+  FORMAT edit descriptors.
+* Token pasting with ``##`` works in function-like macros.
+* Argument stringization with ``#`` works in function-like macros.
+* Directives can be capitalized (e.g., ``#DEFINE``\ ) in fixed form.
+* Fixed form clipping after column 72 or 132 is done before macro expansion,
+  not after.
+* C-like line continuation with backslash-newline can appear in the name of
+  a keyword-like macro definition.
+* If ``#`` is in column 6 in fixed form, it's a continuation marker, not a
+  directive indicator.
+* ``#define KWM !`` allows KWM to signal a comment.
+
+Judgement calls, where precedents are unclear:
+----------------------------------------------
+
+
+* Expressions in ``#if`` and ``#elif`` should support both Fortran and C
+  operators; e.g., ``#if 2 .LT. 3`` should work.
+* If a function-like macro does not close its parentheses, line
+  continuation should be assumed.
+* ... However, the leading parenthesis has to be on the same line as
+  the name of the function-like macro, or on a continuation line thereof.
+* If macros expand to text containing ``&``\ , it doesn't work as a free form
+  line continuation marker.
+* ``#define c 1`` does not allow a ``c`` in column 1 to be used as a label
+  in fixed form, rather than as a comment line indicator.
+* IBM claims to be ISO C compliant and therefore recognizes trigraph sequences.
+* Fortran comments in macro actual arguments should be respected, on
+  the principle that a macro call should work like a function reference.
+* If a ``#define`` or ``#undef`` directive appears among continuation
+  lines, it may or may not affect text in the continued statement that
+  appeared before the directive.
+
+Behavior that few compilers properly support (or none), but should:
+-------------------------------------------------------------------
+
+
+* A macro invocation can straddle free form continuation lines in all of their
+  forms, with continuation allowed in the name, before the arguments, and
+  within the arguments.
+* Directives can be capitalized in free form, too.
+* ``__VA_ARGS__`` and ``__VA_OPT__`` work in variadic function-like macros.
+
+In short, a Fortran preprocessor should work as if:
+---------------------------------------------------
+
+
+#. Fixed form lines are padded up to column 72 (or 132) and clipped thereafter.
+#. Fortran comments are removed.
+#. C-style line continuations are processed in preprocessing directives.
+#. C old-style comments are removed from directives.
+#. Fortran line continuations are processed (outside preprocessing directives).
+   Line continuation rules depend on source form.
+   Comment lines that are enabled compiler directives have their line
+   continuations processed.
+   Conditional compilation preprocessing directives (e.g., ``#if``\ ) may be
+   appear among continuation lines, and have their usual effects upon them.
+#. Other preprocessing directives are processed and macros expanded.
+   Along the way, Fortran ``INCLUDE`` lines and preprocessor ``#include`` directives
+   are expanded, and all these steps applied recursively to the introduced text.
+#. Any Fortran comments created by macro replacement are removed.
+
+Steps 5 and 6 are interleaved with respect to the preprocessing state.
+Conditional compilation preprocessing directives always reflect only the macro
+definition state produced by the active ``#define`` and ``#undef`` preprocessing directives
+that precede them.
+
+If the source form is changed by means of a compiler directive (i.e.,
+``!DIR$ FIXED`` or ``FREE``\ ) in an included source file, its effects cease
+at the end of that file.
+
+Last, if the preprocessor is not integrated into the Fortran compiler,
+new Fortran continuation line markers should be introduced into the final
+text.
+
+OpenMP-style directives that look like comments are not addressed by
+this scheme but are obvious extensions.
+
+Appendix
+========
+
+``N`` in the table below means "not supported"; this doesn't
+mean a bug, it just means that a particular behavior was
+not observed.
+``E`` signifies "error reported".
+
+The abbreviation ``KWM`` stands for "keyword macro" and ``FLM`` means
+"function-like macro".
+
+The first block of tests (\ ``pp0*.F``\ ) are all fixed-form source files;
+the second block (\ ``pp1*.F90``\ ) are free-form source files.
+
+.. code-block::
+
+   f18
+   | pgfortran
+   | | ifort
+   | | | gfortran
+   | | | | xlf
+   | | | | | nagfor
+   | | | | | |
+   . . . . . .   pp001.F  keyword macros
+   . . . . . .   pp002.F  #undef
+   . . . . . .   pp003.F  function-like macros
+   . . . . . .   pp004.F  KWMs case-sensitive
+   . N . N N .   pp005.F  KWM split across continuation, implicit padding
+   . N . N N .   pp006.F  ditto, but with intervening *comment line
+   N N N N N N   pp007.F  KWM split across continuation, clipped after column 72
+   . . . . . .   pp008.F  KWM with spaces in name at invocation NOT replaced
+   . N . N N .   pp009.F  FLM call split across continuation, implicit padding
+   . N . N N .   pp010.F  ditto, but with intervening *comment line
+   N N N N N N   pp011.F  FLM call name split across continuation, clipped
+   . N . N N .   pp012.F  FLM call name split across continuation
+   . E . N N .   pp013.F  FLM call split between name and (
+   . N . N N .   pp014.F  FLM call split between name and (, with intervening *comment
+   . E . N N .   pp015.F  FLM call split between name and (, clipped
+   . E . N N .   pp016.F  FLM call split between name and ( and in argument
+   . . . . . .   pp017.F  KLM rescan
+   . . . . . .   pp018.F  KLM rescan with #undef (so rescan is after expansion)
+   . . . . . .   pp019.F  FLM rescan
+   . . . . . .   pp020.F  FLM expansion of argument
+   . . . . . .   pp021.F  KWM NOT expanded in 'literal'
+   . . . . . .   pp022.F  KWM NOT expanded in "literal"
+   . . E E . E   pp023.F  KWM NOT expanded in 9HHOLLERITH literal
+   . . . E . .   pp024.F  KWM NOT expanded in Hollerith in FORMAT
+   . . . . . .   pp025.F  KWM expansion is before token pasting due to fixed-form space removal
+   . . . E . E   pp026.F  ## token pasting works in FLM
+   E . . E E .   pp027.F  #DEFINE works in fixed form
+   . N . N N .   pp028.F  fixed-form clipping done before KWM expansion on source line
+   . . . . . .   pp029.F  newline allowed in #define
+   . . . . . .   pp030.F  /* C comment */ erased from #define
+   E E E E E E   pp031.F   // C++ comment NOT erased from #define
+   . . . . . .   pp032.F  /* C comment */ newline erased from #define
+   . . . . . .   pp033.F  /* C comment newline */ erased from #define
+   . . . . . N   pp034.F  newline allowed in name on KWM definition
+   . E . E E .   pp035.F  #if 2 .LT. 3 works
+   . . . . . .   pp036.F  #define FALSE TRUE ...  .FALSE. -> .TRUE.
+   N N N N N N   pp037.F  fixed-form clipping NOT applied to #define
+   . . E . E E   pp038.F  FLM call with closing ')' on next line (not a continuation)
+   E . E . E E   pp039.F  FLM call with '(' on next line (not a continuation)
+   . . . . . .   pp040.F  #define KWM c, then KWM works as comment line initiator
+   E . E . . E   pp041.F  use KWM expansion as continuation indicators
+   N N N . . N   pp042.F  #define c 1, then use c as label in fixed-form
+   . . . . N .   pp043.F  #define with # in column 6 is a continuation line in fixed-form
+   E . . . . .   pp044.F  #define directive amid continuations
+   . . . . . .   pp101.F90  keyword macros
+   . . . . . .   pp102.F90  #undef
+   . . . . . .   pp103.F90  function-like macros
+   . . . . . .   pp104.F90  KWMs case-sensitive
+   . N N N N N   pp105.F90  KWM call name split across continuation, with leading &
+   . N N N N N   pp106.F90  ditto, with & ! comment
+   N N E E N .   pp107.F90  KWM call name split across continuation, no leading &, with & ! comment
+   N N E E N .   pp108.F90  ditto, but without & ! comment
+   . N N N N N   pp109.F90  FLM call name split with leading &
+   . N N N N N   pp110.F90  ditto, with & ! comment
+   N N E E N .   pp111.F90  FLM call name split across continuation, no leading &, with & ! comment
+   N N E E N .   pp112.F90  ditto, but without & ! comment
+   . N N N N E   pp113.F90  FLM call split across continuation between name and (, leading &
+   . N N N N E   pp114.F90  ditto, with & ! comment, leading &
+   N N N N N .   pp115.F90  ditto, with & ! comment, no leading &
+   N N N N N .   pp116.F90  FLM call split between name and (, no leading &
+   . . . . . .   pp117.F90  KWM rescan
+   . . . . . .   pp118.F90  KWM rescan with #undef, proving rescan after expansion
+   . . . . . .   pp119.F90  FLM rescan
+   . . . . . .   pp120.F90  FLM expansion of argument
+   . . . . . .   pp121.F90  KWM NOT expanded in 'literal'
+   . . . . . .   pp122.F90  KWM NOT expanded in "literal"
+   . . E E . E   pp123.F90  KWM NOT expanded in Hollerith literal
+   . . E E . E   pp124.F90  KWM NOT expanded in Hollerith in FORMAT
+   E . . E E .   pp125.F90  #DEFINE works in free form
+   . . . . . .   pp126.F90  newline works in #define
+   N . E . E E   pp127.F90  FLM call with closing ')' on next line (not a continuation)
+   E . E . E E   pp128.F90  FLM call with '(' on next line (not a continuation)
+   . . N . . N   pp129.F90  #define KWM !, then KWM works as comment line initiator
+   E . E . . E   pp130.F90  #define KWM &, use for continuation w/o pasting (ifort and nag seem to continue #define)

flang/docs/PullRequestChecklist.rst

+Pull request checklist
+======================
+
+Please review the following items before submitting a pull request.  This list
+can also be used when reviewing pull requests.
+
+
+* Verify that new files have a license with correct file name.
+* Run ``git diff`` on all modified files to look for spurious changes such as
+  ``#include <iostream>``.
+* If you added code that causes the compiler to emit a new error message, make
+  sure that you also added a test that causes that error message to appear
+  and verifies its correctness.
+* Annotate the code and tests with appropriate references to constraint and
+  requirement numbers from the Fortran standard.  Do not include the text of
+  the constraint or requirement, just its number.
+* Alphabetize arbitrary lists of names.
+* Check dereferences of pointers and optionals where necessary.
+* Ensure that the scopes of all functions and variables are as local as
+  possible.
+* Try to make all functions fit on a screen (40 lines).
+* Build and test with both GNU and clang compilers.
+* When submitting an update to a pull request, review previous pull request
+  comments and make sure that you've actually made all of the changes that
+  were requested.
+
+Follow the style guide
+----------------------
+
+The following items are taken from the `C++ style guide <C++style.rst>`_.  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.rst#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.rst>`_ 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/RuntimeDescriptor.rst

-<!--===- documentation/RuntimeDescriptor.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
-  
--->
-
-## Concept
+Concept
+-------
 The properties that characterize data values and objects in Fortran
 programs must sometimes be materialized when the program runs.
 
 Some properties are known during compilation and constant during
 execution, yet must be reified anyway for execution in order to
 drive the interfaces of a language support library or the mandated
 interfaces of interoperable (i.e., C) procedure calls.
 
 Note that many Fortran intrinsic subprograms have interfaces
 that are more flexible and generic than actual Fortran subprograms
 can be, so properties that must be known during compilation and
 are constant during execution may still need to be materialized
 for calls to the library, even if only by modifying names to
 distinguish types or their kind specializations.
 
 Other properties are deferred to execution, and need to be represented
 to serve the needs of compiled code and the run time support library.
 
 Previous implementations of Fortran have typically defined a small
-sheaf of _descriptor_ data structures for this purpose, and attached
+sheaf of *descriptor* data structures for this purpose, and attached
 these descriptors as additional hidden arguments, type components,
 and local variables so as to convey dynamic characteristics between
 subprograms and between user code and the run-time support library.
 
-### References
+References
+^^^^^^^^^^
+
 References are to the 12-2017 draft of the Fortran 2018 standard
 (N2146).
 
 Section 15.4.2.2 can be interpreted as a decent list of things that
 might need descriptors or other hidden state passed across a
 subprogram call, since such features (apart from assumed-length
-`CHARACTER` function results) trigger a requirement for the
+``CHARACTER`` function results) trigger a requirement for the
 subprogram to have an explicit interface visible to their callers.
 
 Section 15.5.2 has good laundry lists of situations that can arise
 across subprogram call boundaries.
 
-## A survey of dynamic characteristics
+A survey of dynamic characteristics
+-----------------------------------
+
+Length of assumed-length ``CHARACTER`` function results (B.3.6)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
 
-### Length of assumed-length `CHARACTER` function results (B.3.6)
-```
    CHARACTER*8 :: FOO
    PRINT *, FOO('abcdefghijklmnopqrstuvwxyz')
    ...
    CHARACTER*(*) FUNCTION FOO(STR)
      CHARACTER*26 STR
      FOO=STR
    END
-```
 
-prints `abcdefgh` because the length parameter of the character type
-of the result of `FOO` is passed across the call -- even in the absence
+prints ``abcdefgh`` because the length parameter of the character type
+of the result of ``FOO`` is passed across the call -- even in the absence
 of an explicit interface!
 
-### Assumed length type parameters (7.2)
-Dummy arguments and associate names for `SELECT TYPE` can have assumed length
+Assumed length type parameters (7.2)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Dummy arguments and associate names for ``SELECT TYPE`` can have assumed length
 type parameters, which are denoted by asterisks (not colons).
 Their values come from actual arguments or the associated expression (resp.).
 
-### Explicit-shape arrays (8.5.8.2)
+Explicit-shape arrays (8.5.8.2)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The expressions used for lower and upper bounds must be captured and remain
 invariant over the scope of an array, even if they contain references to
 variables that are later modified.
 
 Explicit-shape arrays can be dummy arguments, "adjustable" local variables,
 and components of derived type (using specification expressions in terms
 of constants and KIND type parameters).
 
-### Leading dimensions of assumed-size arrays (8.5.8.5)
-```
+Leading dimensions of assumed-size arrays (8.5.8.5)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
    SUBROUTINE BAR(A)
      REAL A(2,3,*)
    END
-```
+
 The total size and final dimension's extent do not constitute dynamic
 properties.
 The called subprogram has no means to extract the extent of the
 last (major) dimension, and may not depend upon it implicitly by using
 the array in any context that demands a known shape.
 
 The values of the expressions used as the bounds of the dimensions
 that appear prior to
 the last dimension are, however, effectively captured on entry to the
 subprogram, and remain invariant even if the variables that appear in
 those expressions have their values modified later.
 This is similar to the requirements for an explicit-shape array.
 
-### Some function results
-1. Deferred-shape
-2. Deferred length type parameter values
-3. Stride information for `POINTER` results
+Some function results
+^^^^^^^^^^^^^^^^^^^^^
+
+
+#. Deferred-shape
+#. Deferred length type parameter values
+#. Stride information for ``POINTER`` results
 
-Note that while function result variables can have the `ALLOCATABLE`
+Note that while function result variables can have the ``ALLOCATABLE``
 attribute, the function itself and the value returned to the caller
 do not possess the attribute.
 
-### Assumed-shape arrays
+Assumed-shape arrays
+^^^^^^^^^^^^^^^^^^^^
+
 The extents of the dimensions of assumed-shape dummy argument arrays
 are conveyed from those of the actual effective arguments.
 The bounds, however, are not.  The called subprogram can define the
 lower bound to be a value other than 1, but that is a local effect
 only.
 
-### Deferred-shape arrays
-The extents and bounds of `POINTER` and `ALLOCATABLE` arrays are
-established by pointer assignments and `ALLOCATE` statements.
-Note that dummy arguments and function results that are `POINTER`
-or `ALLOCATABLE` can be deferred-shape, not assumed-shape -- one cannot
+Deferred-shape arrays
+^^^^^^^^^^^^^^^^^^^^^
+
+The extents and bounds of ``POINTER`` and ``ALLOCATABLE`` arrays are
+established by pointer assignments and ``ALLOCATE`` statements.
+Note that dummy arguments and function results that are ``POINTER``
+or ``ALLOCATABLE`` can be deferred-shape, not assumed-shape -- one cannot
 supply a lower bound expression as a local effect.
 
-### Strides
+Strides
+^^^^^^^
+
 Some arrays can have discontiguous (or negative) strides.
 These include assumed-shape dummy arguments and deferred-shape
-`POINTER` variables, components, and function results.
+``POINTER`` variables, components, and function results.
 
 Fortran disallows some conceivable cases that might otherwise
 require implied strides, such as passing an array of an extended
 derived type as an actual argument that corresponds to a
 nonpolymorphic dummy array of a base type, or the similar
 case of pointer assignment to a base of an extended derived type.
 
-Other arrays, including `ALLOCATABLE`, can be assured to
+Other arrays, including ``ALLOCATABLE``\ , can be assured to
 be contiguous, and do not necessarily need to manage or
 convey dynamic stride information.
-`CONTIGUOUS` dummy arguments and `POINTER` arrays need not
+``CONTIGUOUS`` dummy arguments and ``POINTER`` arrays need not
 record stride information either.
-(The standard notes that a `CONTIGUOUS POINTER` occupies a
+(The standard notes that a ``CONTIGUOUS POINTER`` occupies a
 number of storage units that is distinct from that required
-to hold a non-`CONTIGUOUS` pointer.)
+to hold a non-\ ``CONTIGUOUS`` pointer.)
 
-Note that Fortran distinguishes the `CONTIGUOUS` attribute from
-the concept of being known or required to be _simply contiguous_ (9.5.4),
-which includes `CONTIGUOUS` entities as well as many others, and
-the concept of actually _being_ contiguous (8.5.7) during execution.
+Note that Fortran distinguishes the ``CONTIGUOUS`` attribute from
+the concept of being known or required to be *simply contiguous* (9.5.4),
+which includes ``CONTIGUOUS`` entities as well as many others, and
+the concept of actually *being* contiguous (8.5.7) during execution.
 I believe that the property of being simply contiguous implies
 that an entity is known at compilation time to not require the
 use or maintenance of hidden stride values.
 
-### Derived type component initializers
+Derived type component initializers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Fortran allows components of derived types to be declared with
 initial values that are to be assigned to the components when an
 instance of the derived type is created.
-These include `ALLOCATABLE` components, which are always initialized
+These include ``ALLOCATABLE`` components, which are always initialized
 to a deallocated state.
 
 These can be implemented with constructor subroutines, inline
 stores or block copies from static initializer blocks, or a sequence
 of sparse offset/size/value component initializers to be emplaced
 by the run-time library.
 
 N.B. Fortran allows kind type parameters to appear in component
 initialization constant expressions, but not length type parameters,
 so the initialization values are constants.
 
 N.B. Initialization is not assignment, and cannot be implemented
 with assignments to uninitialized derived type instances from
 static constant initializers.
 
-### Polymorphic `CLASS()`, `CLASS(*)`, and `TYPE(*)`
-Type identification for `SELECT TYPE`.
+Polymorphic ``CLASS()``\ , ``CLASS(*)``\ , and ``TYPE(*)``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Type identification for ``SELECT TYPE``.
 Default initializers (see above).
-Offset locations of `ALLOCATABLE` and polymorphic components.
-Presence of `FINAL` procedures.
+Offset locations of ``ALLOCATABLE`` and polymorphic components.
+Presence of ``FINAL`` procedures.
 Mappings to overridable type-bound specific procedures.
 
-### Deferred length type parameters
-Derived types with length type parameters, and `CHARACTER`, may be used
+Deferred length type parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Derived types with length type parameters, and ``CHARACTER``\ , may be used
 with the values of those parameters deferred to execution.
 Their actual values must be maintained as characteristics of the dynamic
 type that is associated with a value or object
 .
 A single copy of the deferred length type parameters suffices for
 all of the elements of an array of that parameterized derived type.
 
-### Components whose types and/or shape depends on length type parameters
+Components whose types and/or shape depends on length type parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Non-pointer, non-allocatable components whose types or shapes are expressed
 in terms of length type parameters will probably have to be implemented as
-if they had deferred type and/or shape and were `ALLOCATABLE`.
+if they had deferred type and/or shape and were ``ALLOCATABLE``.
 The derived type instance constructor must allocate them and possibly
 initialize them; the instance destructor must deallocate them.
 
-### Assumed rank arrays
+Assumed rank arrays
+^^^^^^^^^^^^^^^^^^^
+
 Rank is almost always known at compilation time and would be redundant
 in most circumstances if also managed dynamically.
-`DIMENSION(..)` dummy arguments (8.5.8.7), however, are a recent feature
+``DIMENSION(..)`` dummy arguments (8.5.8.7), however, are a recent feature
 with which the rank of a whole array is dynamic outside the cases of
-a `SELECT RANK` construct.
+a ``SELECT RANK`` construct.
 
 The lower bounds of the dimensions of assumed rank arrays
 are always 1.
 
-### Cached invariant subexpressions for addressing
+Cached invariant subexpressions for addressing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Implementations of Fortran have often maintained precalculated integer
 values to accelerate subscript computations.
-For example, given `REAL*8 :: A(2:4,3:5)`, the data reference `A(I,J)`
-resolves to something like `&A + 8*((I-2)+3*(J-3))`, and this can be
-effectively reassociated to `&A - 88 + 8*I + 24*J`
-or `&A - 88 + 8*(I + 3*J)`.
+For example, given ``REAL*8 :: A(2:4,3:5)``\ , the data reference ``A(I,J)``
+resolves to something like ``&A + 8*((I-2)+3*(J-3))``\ , and this can be
+effectively reassociated to ``&A - 88 + 8*I + 24*J``
+or ``&A - 88 + 8*(I + 3*J)``.
 When the offset term and coefficients are not compile-time constants,
 they are at least invariant and can be precomputed.
 
-In the cases of dummy argument arrays, `POINTER`, and `ALLOCATABLE`,
+In the cases of dummy argument arrays, ``POINTER``\ , and ``ALLOCATABLE``\ ,
 these addressing invariants could be managed alongside other dynamic
 information like deferred extents and lower bounds to avoid their
 recalculation.
 It's not clear that it's worth the trouble to do so, since the
 expressions are invariant and cheap.
 
-### Coarray state (8.5.6)
-A _coarray_ is an `ALLOCATABLE` variable or component, or statically
-allocated variable (`SAVE` attribute explicit or implied), or dummy
+Coarray state (8.5.6)
+^^^^^^^^^^^^^^^^^^^^^
+
+A *coarray* is an ``ALLOCATABLE`` variable or component, or statically
+allocated variable (\ ``SAVE`` attribute explicit or implied), or dummy
 argument whose ultimate effective argument is one of such things.
 
 Each image in a team maintains its portion of each coarray and can
 access those portions of the coarray that are maintained by other images
 in the team.
 Allocations and deallocations are synchronization events at which
 the several images can exchange whatever information is needed by
 the underlying intercommunication interface to access the data
 of their peers.
 (Strictly speaking, an implementation could synchronize
 images at allocations and deallocations with simple barriers, and defer
 the communication of remote access information until it is needed for a
 given coarray on a given image, so long as it could be acquired in a
 "one-sided" fashion.)
 
-### Presence of `OPTIONAL` dummy arguments
+Presence of ``OPTIONAL`` dummy arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Typically indicated with null argument addresses.
-Note that `POINTER` and `ALLOCATABLE` objects can be passed to
-non-`POINTER` non-`ALLOCATABLE` dummy arguments, and their
+Note that ``POINTER`` and ``ALLOCATABLE`` objects can be passed to
+non-\ ``POINTER`` non-\ ``ALLOCATABLE`` dummy arguments, and their
 association or allocation status (resp.) determines the presence
 of the dummy argument.
 
-### Stronger contiguity enforcement or indication
+Stronger contiguity enforcement or indication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Some implementations of Fortran guarantee that dummy argument arrays
 are, or have been made to be, contiguous on one or more dimensions
 when the language does not require them to be so (8.5.7 p2).
 Others pass a flag to identify contiguous arrays (or could pass the
 number of contiguous leading dimensions, although I know of no such
 implementation) so that optimizing transformations that depend on
 contiguity can be made conditional with multiple-version code generation
 and selected during execution.
 
 In the absence of a contiguity guarantee or flag, the called side
 would have to determine contiguity dynamically, if it cares,
 by calculating addresses of elements in the array whose subscripts
 differ by exactly 1 on exactly 1 dimension of interest, and checking
 whether that difference exactly matches the byte size of the type times
 the product of the extents of any prior dimensions.
 
-### Host instances for dummy procedures and procedure pointers
+Host instances for dummy procedures and procedure pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 A static link or other means of accessing the imported state of the
 host procedure must be available when an internal procedure is
 used as an actual argument or as a pointer assignment target.
 
-### Alternate returns
+Alternate returns
+^^^^^^^^^^^^^^^^^
+
 Subroutines (only) with alternate return arguments need a
 means, such as the otherwise unused function return value, by which
-to distinguish and identify the use of an alternate `RETURN` statement.
+to distinguish and identify the use of an alternate ``RETURN`` statement.
 The protocol can be a simple nonzero integer that drives a switch
 in the caller, or the caller can pass multiple return addresses as
 arguments for the callee to substitute on the stack for the original
-return address in the event of an alternate `RETURN`.
+return address in the event of an alternate ``RETURN``.
+
+Implementation options
+----------------------
 
-## Implementation options
+A note on array descriptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-### A note on array descriptions
 Some arrays require dynamic management of distinct combinations of
 values per dimension.
 
 One can extract the extent on a dimension from its bounds, or extract
 the upper bound from the extent and the lower bound.  Having distinct
 extent and upper bound would be redundant.
 
 Contiguous arrays can assume a stride of 1 on each dimension.
 
 Assumed-shape and assumed-size dummy argument arrays need not convey
 lower bounds.
 
 So there are examples of dimensions with
- * extent only (== upper bound): `CONTIGUOUS` assumed-shape, explict shape and multidimensional assumed-size with constant lower bound
- * lower bound and either extent or upper bound: `ALLOCATABLE`, `CONTIGUOUS` `POINTER`, general explicit-shape and multidimensional assumed-size
- * extent (== upper bound) and stride: general (non-`CONTIGUOUS`) assumed-shape
- * lower bound, stride, and either extent or upper bound: general (non-`CONTIGUOUS`) `POINTER`, assumed-rank
+
+
+* extent only (== upper bound): ``CONTIGUOUS`` assumed-shape, explict shape and multidimensional assumed-size with constant lower bound
+* lower bound and either extent or upper bound: ``ALLOCATABLE``\ , ``CONTIGUOUS`` ``POINTER``\ , general explicit-shape and multidimensional assumed-size
+* extent (== upper bound) and stride: general (non-\ ``CONTIGUOUS``\ ) assumed-shape
+* lower bound, stride, and either extent or upper bound: general (non-\ ``CONTIGUOUS``\ ) ``POINTER``\ , assumed-rank
 
 and these cases could be accompanied by precomputed invariant
 addressing subexpressions to accelerate indexing calculations.
 
-### Interoperability requirements
+Interoperability requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Fortran 2018 requires that a Fortran implementation supply a header file
-`ISO_Fortran_binding.h` for use in C and C++ programs that defines and
-implements an interface to Fortran objects from the _interoperable_
+``ISO_Fortran_binding.h`` for use in C and C++ programs that defines and
+implements an interface to Fortran objects from the *interoperable*
 subset of Fortran objects and their types suitable for use when those
 objects are passed to C functions.
 This interface mandates a fat descriptor that is passed by address,
 containing (at least)
- * a data base address
- * explicit rank and type
- * flags to distinguish `POINTER` and `ALLOCATABLE`
- * elemental byte size, and
- * (per-dimension) lower bound, extent, and byte stride
+
+
+* flags to distinguish ``POINTER`` and ``ALLOCATABLE``
 
 The requirements on the interoperability API do not mandate any
 support for features like derived type component initialization,
-automatic deallocation of `ALLOCATABLE` components, finalization,
+automatic deallocation of ``ALLOCATABLE`` components, finalization,
 derived type parameters, data contiguity flags, &c.
 But neither does the Standard preclude inclusion of additional
 interfaces to describe and support such things.
 
 Given a desire to fully support the Fortran 2018 language, we need
 to either support the interoperability requirements as a distinct
 specialization of the procedure call protocol, or use the
-`ISO_Fortran_binding.h` header file requirements as a subset basis for a
+``ISO_Fortran_binding.h`` header file requirements as a subset basis for a
 complete implementation that adds representations for all the
 missing capabilities, which would be isolated and named so as
 to prevent user C code from relying upon them.
 
-### Design space
+Design space
+^^^^^^^^^^^^
+
 There is a range of possible options for representing the
 properties of values and objects during the execution of Fortran
 programs.
 
 At one extreme, the amount of dynamic information is minimized,
 and is packaged in custom data structures or additional arguments
 for each situation to convey only the values that are unknown at
 compilation time and actually needed at execution time.

 Further, the requirements of the representation of dynamic
 properties of values and objects depend on the execution model:
 specifically, are the complicated semantics of intrinsic assignment,
 deallocation, and finalization of allocatables implemented entirely
 in the support library, in generated code for non-recursive cases,
 or by means of a combination of the two approaches?
 
 Consider how to implement the following:
-```
+
+.. code-block::
+
    TYPE :: LIST
      REAL :: HEAD
      TYPE(LIST), ALLOCATABLE :: REST
    END TYPE LIST
    TYPE(LIST), ALLOCATABLE :: A, B
    ...
    A = B
-```
 
-Fortran requires that `A`'s arbitrary-length linked list be deleted and
-replaced with a "deep copy" of `B`'s.
+Fortran requires that ``A``\ 's arbitrary-length linked list be deleted and
+replaced with a "deep copy" of ``B``\ 's.
 So either a complicated pair of loops must be generated by the compiler,
 or a sophisticated run time support library needs to be driven with
 an expressive representation of type information.
 
-## Proposal
-We need to write `ISO_Fortran_binding.h` in any event.
+Proposal
+--------
+
+We need to write ``ISO_Fortran_binding.h`` in any event.
 It is a header that is published for use in user C code for interoperation
 with compiled Fortran and the Fortran run time support library.
 
-There is a sole descriptor structure defined in `ISO_Fortran_binding.h`.
+There is a sole descriptor structure defined in ``ISO_Fortran_binding.h``.
 It is suitable for characterizing scalars and array sections of intrinsic
 types.
 It is essentially a "fat" data pointer that encapsulates a raw data pointer,
 a type code, rank, elemental byte size, and per-dimension bounds and stride.
 
 Please note that the mandated interoperable descriptor includes the data
 pointer.
 This design in the Standard precludes the use of static descriptors that
 could be associated with dynamic base addresses.
 
 The F18 runtime cannot use just the mandated interoperable
-`struct CFI_cdesc_t` argument descriptor structure as its
+``struct CFI_cdesc_t`` argument descriptor structure as its
 all-purpose data descriptor.
 It has no information about derived type components, overridable
 type-bound procedure bindings, type parameters, &c.
 
 However, we could extend the standard interoperable argument descriptor.
-The `struct CFI_cdesc_t` structure is not of fixed size, but we
+The ``struct CFI_cdesc_t`` structure is not of fixed size, but we
 can efficiently locate the first address after an instance of the
 standard descriptor and attach our own data record there to
 hold what we need.
 There's at least one unused padding byte in the standard argument
 descriptor that can be used to hold a flag indicating the presence
 of the addenda.
 
 The definitions of our additional run time data structures must
-appear in a header file that is distinct from `ISO_Fortran_binding.h`,
+appear in a header file that is distinct from ``ISO_Fortran_binding.h``\ ,
 and they should never be used by user applications.
 
 This expanded descriptor structure can serve, at least initially for
-simplicity, as the sole representation of `POINTER` variables and
-components, `ALLOCATABLE` variables and components, and derived type
+simplicity, as the sole representation of ``POINTER`` variables and
+components, ``ALLOCATABLE`` variables and components, and derived type
 instances, including length parameter values.
 
 An immediate concern with this concept is the amount of space and
 initialization time that would be wasted when derived type components
 needing a descriptor would have to be accompanied by an instance
 of the general descriptor.
 (In the linked list example close above, what could be done with a
-single pointer for the `REST` component would become at least
+single pointer for the ``REST`` component would become at least
 a four-word dynamic structure.)
 This concern is amplified when derived type instances
 are allocated as arrays, since the overhead is per-element.
 
 We can reduce this wastage in two ways.
 First, when the content of the component's descriptor is constant
 at compilation apart from its base address, a static descriptor
 can be placed in read-only storage and attached to the description
 of the derived type's components.
 Second, we could eventually optimize the storage requirements by
 omitting all static fields from the dynamic descriptor, and
 expand the compressed dynamic descriptor during execution when
 needed.

flang/docs/Semantics.rst

+Semantic Analysis
+=================
+
+The semantic analysis pass determines if a syntactically correct Fortran
+program is is legal by enforcing the constraints of the language.
+
+The input is a parse tree with a ``Program`` node at the root;
+and a "cooked" character stream, a contiguous stream of characters
+containing a normalized form of the Fortran source.
+
+The semantic analysis pass takes a parse tree for a syntactically
+correct Fortran program and determines whether it is legal by enforcing
+the constraints of the language.
+
+If the program is not legal, the results of the semantic pass will be a list of
+errors associated with the program.
+
+If the program is legal, the semantic pass will produce a (possibly modified)
+parse tree for the semantically correct program with each name mapped to a symbol
+and each expression fully analyzed.
+
+All user errors are detected either prior to or during semantic analysis.
+After it completes successfully the program should compile with no error messages.
+There may still be warnings or informational messages.
+
+Phases of Semantic Analysis
+---------------------------
+
+
+#. `Validate labels <#validate-labels>`_ -
+   Check all constraints on labels and branches
+#. `Rewrite DO loops <#rewrite-do-loops>`_ -
+   Convert all occurrences of ``LabelDoStmt`` to ``DoConstruct``.
+#. `Name resolution <#name-resolution>`_ -
+   Analyze names and declarations, build a tree of Scopes containing Symbols,
+   and fill in the ``Name::symbol`` data member in the parse tree
+#. `Rewrite parse tree <#rewrite-parse-tree>`_ -
+   Fix incorrect parses based on symbol information
+#. `Expression analysis <#expression-analysis>`_ -
+   Analyze all expressions in the parse tree and fill in ``Expr::typedExpr`` and
+   ``Variable::typedExpr`` with analyzed expressions; fix incorrect parses
+   based on the result of this analysis
+#. `Statement semantics <#statement-semantics>`_ -
+   Perform remaining semantic checks on the execution parts of subprograms
+#. `Write module files <#write-module-files>`_ -
+   If no errors have occurred, write out ``.mod`` files for modules and submodules
+
+If phase 1 or phase 2 encounter an error on any of the program units,
+compilation terminates. Otherwise, phases 3-6 are all performed even if
+errors occur.
+Module files are written (phase 7) only if there are no errors.
+
+Validate labels
+^^^^^^^^^^^^^^^
+
+Perform semantic checks related to labels and branches:
+
+
+* check that any labels that are referenced are defined and in scope
+* check branches into loop bodies
+* check that labeled ``DO`` loops are properly nested
+* check labels in data transfer statements
+
+Rewrite DO loops
+^^^^^^^^^^^^^^^^
+
+This phase normalizes the parse tree by removing all unstructured ``DO`` loops
+and replacing them with ``DO`` constructs.
+
+Name resolution
+^^^^^^^^^^^^^^^
+
+The name resolution phase walks the parse tree and constructs the symbol table.
+
+The symbol table consists of a tree of ``Scope`` objects rooted at the global scope.
+The global scope is owned by the ``SemanticsContext`` object.
+It contains a ``Scope`` for each program unit in the compilation.
+
+Each ``Scope`` in the scope tree contains child scopes representing other scopes
+lexically nested in it.
+Each ``Scope`` also contains a map of ``CharBlock`` to ``Symbol`` representing names
+declared in that scope. (All names in the symbol table are represented as
+``CharBlock`` objects, i.e. as substrings of the cooked character stream.)
+
+All ``Symbol`` objects are owned by the symbol table data structures.
+They should be accessed as ``Symbol *`` or ``Symbol &`` outside of the symbol
+table classes as they can't be created, copied, or moved.
+The ``Symbol`` class has functions and data common across all symbols, and a
+``details`` field that contains more information specific to that type of symbol.
+Many symbols also have types, represented by ``DeclTypeSpec``.
+Types are also owned by scopes.
+
+Name resolution happens on the parse tree in this order:
+
+
+#. Process the specification of a program unit:
+
+   #. Create a new scope for the unit
+   #. Create a symbol for each contained subprogram containing just the name
+   #. Process the opening statement of the unit (\ ``ModuleStmt``\ , ``FunctionStmt``\ , etc.)
+   #. Process the specification part of the unit
+
+#. Apply the same process recursively to nested subprograms
+#. Process the execution part of the program unit
+#. Process the execution parts of nested subprograms recursively
+
+After the completion of this phase, every ``Name`` corresponds to a ``Symbol``
+unless an error occurred.
+
+Rewrite parse tree
+^^^^^^^^^^^^^^^^^^
+
+The parser cannot build a completely correct parse tree without symbol information.
+This phase corrects mis-parses based on symbols:
+
+
+* Array element assignments may be parsed as statement functions: ``a(i) = ...``
+* Namelist group names without ``NML=`` may be parsed as format expressions
+* A file unit number expression may be parsed as a character variable
+
+This phase also produces an internal error if it finds a ``Name`` that does not
+have its ``symbol`` data member filled in. This error is suppressed if other
+errors have occurred because in that case a ``Name`` corresponding to an erroneous
+symbol may not be resolved.
+
+Expression analysis
+^^^^^^^^^^^^^^^^^^^
+
+Expressions that occur in the specification part are analyzed during name
+resolution, for example, initial values, array bounds, type parameters.
+Any remaining expressions are analyzed in this phase.
+
+For each ``Variable`` and top-level ``Expr`` (i.e. one that is not nested below
+another ``Expr`` in the parse tree) the analyzed form of the expression is saved
+in the ``typedExpr`` data member. After this phase has completed, the analyzed
+expression can be accessed using ``semantics::GetExpr()``.
+
+This phase also corrects mis-parses based on the result of expression analysis:
+
+
+* An expression like ``a(b)`` is parsed as a function reference but may need
+  to be rewritten to an array element reference (if ``a`` is an object entity)
+  or to a structure constructor (if ``a`` is a derive type)
+* An expression like ``a(b:c)`` is parsed as an array section but may need to be
+  rewritten as a substring if ``a`` is an object with type CHARACTER
+
+Statement semantics
+^^^^^^^^^^^^^^^^^^^
+
+Multiple independent checkers driven by the ``SemanticsVisitor`` framework
+perform the remaining semantic checks.
+By this phase, all names and expressions that can be successfully resolved
+have been. But there may be names without symbols or expressions without
+analyzed form if errors occurred earlier.
+
+Write module files
+^^^^^^^^^^^^^^^^^^
+
+Separate compilation information is written out on successful compilation
+of modules and submodules. These are used as input to name resolution
+in program units that ``USE`` the modules.
+
+Module files are stripped down Fortran source for the module.
+Parts that aren't needed to compile dependent program units (e.g. action statements)
+are omitted.
+
+The module file for module ``m`` is named ``m.mod`` and the module file for
+submodule ``s`` of module ``m`` is named ``m-s.mod``.

flang/docs/f2018-grammar.txt

 #===-- documentation/f2018-grammar.txt -------------------------------------===#
 #
 # 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
 #
 #===------------------------------------------------------------------------===#
 
 R0001 digit -> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 R0002 letter ->
         A | B | C | D | E | F | G | H | I | J | K | L | M |
         N | O | P | Q | R | S | T | U | V | W | X | Y | Z
 R0003 rep-char
 
 R401 xzy-list -> xzy [, xzy]...
 R402 xzy-name -> name
 R403 scalar-xyz -> xyz
 
 R501 program -> program-unit [program-unit]...
 R502 program-unit ->
        main-program | external-subprogram | module | submodule | block-data
 R503 external-subprogram -> function-subprogram | subroutine-subprogram
 R504 specification-part ->
        [use-stmt]... [import-stmt]... [implicit-part]
        [declaration-construct]...
 R505 implicit-part -> [implicit-part-stmt]... implicit-stmt
 R506 implicit-part-stmt ->
        implicit-stmt | parameter-stmt | format-stmt | entry-stmt
 R507 declaration-construct ->
        specification-construct | data-stmt | format-stmt | entry-stmt |
        stmt-function-stmt
 R508 specification-construct ->
        derived-type-def | enum-def | generic-stmt | interface-block |
        parameter-stmt | procedure-declaration-stmt |
        other-specification-stmt | type-declaration-stmt
 R509 execution-part -> executable-construct [execution-part-construct]...
 R510 execution-part-construct ->
        executable-construct | format-stmt | entry-stmt | data-stmt
 R511 internal-subprogram-part -> contains-stmt [internal-subprogram]...
 R512 internal-subprogram -> function-subprogram | subroutine-subprogram
 R513 other-specification-stmt ->
        access-stmt | allocatable-stmt | asynchronous-stmt | bind-stmt |
        codimension-stmt | contiguous-stmt | dimension-stmt | external-stmt |
        intent-stmt | intrinsic-stmt | namelist-stmt | optional-stmt |
        pointer-stmt | protected-stmt | save-stmt | target-stmt |
        volatile-stmt | value-stmt | common-stmt | equivalence-stmt
 R514 executable-construct ->
        action-stmt | associate-construct | block-construct | case-construct |
        change-team-construct | critical-construct | do-construct |
        if-construct | select-rank-construct | select-type-construct |
        where-construct | forall-construct
 R515 action-stmt ->
        allocate-stmt | assignment-stmt | backspace-stmt | call-stmt |
        close-stmt | continue-stmt | cycle-stmt | deallocate-stmt |
        endfile-stmt | error-stop-stmt | event-post-stmt | event-wait-stmt |
        exit-stmt | fail-image-stmt | flush-stmt | form-team-stmt |
        goto-stmt | if-stmt | inquire-stmt | lock-stmt | nullify-stmt |
        open-stmt | pointer-assignment-stmt | print-stmt | read-stmt |
        return-stmt | rewind-stmt | stop-stmt | sync-all-stmt |
        sync-images-stmt | sync-memory-stmt | sync-team-stmt | unlock-stmt |
        wait-stmt | where-stmt | write-stmt | computed-goto-stmt | forall-stmt
 R516 keyword -> name
 
 R601 alphanumeric-character -> letter | digit | underscore  @ | $
 R602 underscore -> _
 R603 name -> letter [alphanumeric-character]...
 R604 constant -> literal-constant | named-constant
 R605 literal-constant ->
        int-literal-constant | real-literal-constant |
        complex-literal-constant | logical-literal-constant |
        char-literal-constant | boz-literal-constant
 R606 named-constant -> name
 R607 int-constant -> constant
 R608 intrinsic-operator ->
        power-op | mult-op | add-op | concat-op | rel-op |
        not-op | and-op | or-op | equiv-op
 R609 defined-operator ->
        defined-unary-op | defined-binary-op | extended-intrinsic-op
 R610 extended-intrinsic-op -> intrinsic-operator
 R611 label -> digit [digit]...
 R620 delimiter -> ( | ) | / | [ | ] | (/ | /)
 
 R701 type-param-value -> scalar-int-expr | * | :
 R702 type-spec -> intrinsic-type-spec | derived-type-spec
 R703 declaration-type-spec ->
        intrinsic-type-spec | TYPE ( intrinsic-type-spec ) |
        TYPE ( derived-type-spec ) | CLASS ( derived-type-spec ) |
        CLASS ( * ) | TYPE ( * )
 R704 intrinsic-type-spec ->
        integer-type-spec | REAL [kind-selector] | DOUBLE PRECISION |
        COMPLEX [kind-selector] | CHARACTER [char-selector] |
        LOGICAL [kind-selector] @ DOUBLE COMPLEX
 R705 integer-type-spec -> INTEGER [kind-selector]
 R706 kind-selector ->
        ( [KIND =] scalar-int-constant-expr )  @ * scalar-int-constant-expr
 R707 signed-int-literal-constant -> [sign] int-literal-constant
 R708 int-literal-constant -> digit-string [_ kind-param]
 R709 kind-param -> digit-string | scalar-int-constant-name
 R710 signed-digit-string -> [sign] digit-string
 R711 digit-string -> digit [digit]...
 R712 sign -> + | -
 R713 signed-real-literal-constant -> [sign] real-literal-constant
 R714 real-literal-constant ->
        significand [exponent-letter exponent] [_ kind-param] |
        digit-string exponent-letter exponent [_ kind-param]
 R715 significand -> digit-string . [digit-string] | . digit-string
 R716 exponent-letter -> E | D  @ | Q
 R717 exponent -> signed-digit-string
 R718 complex-literal-constant -> ( real-part , imag-part )
 R719 real-part ->
        signed-int-literal-constant | signed-real-literal-constant |
        named-constant
 R720 imag-part ->
        signed-int-literal-constant | signed-real-literal-constant |
        named-constant
 R721 char-selector ->
        length-selector |
        ( LEN = type-param-value , KIND = scalar-int-constant-expr ) |
        ( type-param-value , [KIND =] scalar-int-constant-expr ) |
        ( KIND = scalar-int-constant-expr [, LEN = type-param-value] )
 R722 length-selector -> ( [LEN =] type-param-value ) | * char-length [,]
 R723 char-length -> ( type-param-value ) | digit-string
 R724 char-literal-constant ->
        [kind-param _] ' [rep-char]... ' | [kind-param _] " [rep-char]... "
 R725 logical-literal-constant ->
        .TRUE. [_ kind-param] | .FALSE. [_ kind-param] @ | .T. | .F.
 R726 derived-type-def ->
        derived-type-stmt [type-param-def-stmt]... [private-or-sequence]...
        [component-part] [type-bound-procedure-part] end-type-stmt
 R727 derived-type-stmt ->
        TYPE [[, type-attr-spec-list] ::] type-name [( type-param-name-list )]
 R728 type-attr-spec ->
        ABSTRACT | access-spec | BIND(C) | EXTENDS ( parent-type-name )
 R729 private-or-sequence -> private-components-stmt | sequence-stmt
 R730 end-type-stmt -> END TYPE [type-name]
 R731 sequence-stmt -> SEQUENCE
 R732 type-param-def-stmt ->
        integer-type-spec , type-param-attr-spec :: type-param-decl-list
 R733 type-param-decl -> type-param-name [= scalar-int-constant-expr]
 R734 type-param-attr-spec -> KIND | LEN
 R735 component-part -> [component-def-stmt]...
 R736 component-def-stmt -> data-component-def-stmt | proc-component-def-stmt
 R737 data-component-def-stmt ->
        declaration-type-spec [[, component-attr-spec-list] ::]
        component-decl-list
 R738 component-attr-spec ->
        access-spec | ALLOCATABLE |
        CODIMENSION lbracket coarray-spec rbracket | CONTIGUOUS |
        DIMENSION ( component-array-spec ) | POINTER
 R739 component-decl ->
        component-name [( component-array-spec )]
        [lbracket coarray-spec rbracket] [* char-length]
        [component-initialization]
 R740 component-array-spec ->
        explicit-shape-spec-list | deferred-shape-spec-list
 R741 proc-component-def-stmt ->
        PROCEDURE ( [proc-interface] ) , proc-component-attr-spec-list ::
         proc-decl-list
 R742 proc-component-attr-spec ->
        access-spec | NOPASS | PASS [(arg-name)] | POINTER
 R743 component-initialization ->
        = constant-expr | => null-init | => initial-data-target
 R744 initial-data-target -> designator
 R745 private-components-stmt -> PRIVATE
 R746 type-bound-procedure-part ->
        contains-stmt [binding-private-stmt] [type-bound-proc-binding]...
 R747 binding-private-stmt -> PRIVATE
 R748 type-bound-proc-binding ->
        type-bound-procedure-stmt | type-bound-generic-stmt |
        final-procedure-stmt
 R749 type-bound-procedure-stmt ->
        PROCEDURE [[, bind-attr-list] ::] type-bound-proc-decl-list |
        PROCEDURE ( interface-name ) , bind-attr-list :: binding-name-list
 R750 type-bound-proc-decl -> binding-name [=> procedure-name]
 R751 type-bound-generic-stmt ->
        GENERIC [, access-spec] :: generic-spec => binding-name-list
 R752 bind-attr ->
        access-spec | DEFERRED | NON_OVERRIDABLE | NOPASS | PASS [(arg-name)]
 R753 final-procedure-stmt -> FINAL [::] final-subroutine-name-list
 R754 derived-type-spec -> type-name [(type-param-spec-list)]
 R755 type-param-spec -> [keyword =] type-param-value
 R756 structure-constructor -> derived-type-spec ( [component-spec-list] )
 R757 component-spec -> [keyword =] component-data-source
 R758 component-data-source -> expr | data-target | proc-target
 R759 enum-def ->
        enum-def-stmt enumerator-def-stmt [enumerator-def-stmt]... end-enum-stmt
 R760 enum-def-stmt -> ENUM, BIND(C)
 R761 enumerator-def-stmt -> ENUMERATOR [::] enumerator-list
 R762 enumerator -> named-constant [= scalar-int-constant-expr]
 R763 end-enum-stmt -> END ENUM
 R764 boz-literal-constant -> binary-constant | octal-constant | hex-constant
 R765 binary-constant -> B ' digit [digit]... ' | B " digit [digit]... "
 R766 octal-constant -> O ' digit [digit]... ' | O " digit [digit]... "
 R767 hex-constant ->
        Z ' hex-digit [hex-digit]... ' | Z " hex-digit [hex-digit]... "
 R768 hex-digit -> digit | A | B | C | D | E | F
 R769 array-constructor -> (/ ac-spec /) | lbracket ac-spec rbracket
 R770 ac-spec -> type-spec :: | [type-spec ::] ac-value-list
 R771 lbracket -> [
 R772 rbracket -> ]
 R773 ac-value -> expr | ac-implied-do
 R774 ac-implied-do -> ( ac-value-list , ac-implied-do-control )
 R775 ac-implied-do-control ->
        [integer-type-spec ::] ac-do-variable = scalar-int-expr ,
        scalar-int-expr [, scalar-int-expr]
 R776 ac-do-variable -> do-variable
 
 R801 type-declaration-stmt ->
        declaration-type-spec [[, attr-spec]... ::] entity-decl-list
 R802 attr-spec ->
        access-spec | ALLOCATABLE | ASYNCHRONOUS |
        CODIMENSION lbracket coarray-spec rbracket | CONTIGUOUS |
        DIMENSION ( array-spec ) | EXTERNAL | INTENT ( intent-spec ) |
        INTRINSIC | language-binding-spec | OPTIONAL | PARAMETER |
        POINTER | PROTECTED | SAVE | TARGET | VALUE | VOLATILE
 R803 entity-decl ->
        object-name [( array-spec )] [lbracket coarray-spec rbracket]
          [* char-length] [initialization] |
        function-name [* char-length]
 R804 object-name -> name
 R805 initialization -> = constant-expr | => null-init | => initial-data-target
 R806 null-init -> function-reference
 R807 access-spec -> PUBLIC | PRIVATE
 R808 language-binding-spec ->
        BIND ( C [, NAME = scalar-default-char-constant-expr] )
 R809 coarray-spec -> deferred-coshape-spec-list | explicit-coshape-spec
 R810 deferred-coshape-spec -> :
 R811 explicit-coshape-spec ->
        [[lower-cobound :] upper-cobound ,]... [lower-cobound :] *
 R812 lower-cobound -> specification-expr
 R813 upper-cobound -> specification-expr
 R814 dimension-spec -> DIMENSION ( array-spec )
 R815 array-spec ->
        explicit-shape-spec-list | assumed-shape-spec-list |
        deferred-shape-spec-list | assumed-size-spec | implied-shape-spec |
        implied-shape-or-assumed-size-spec | assumed-rank-spec
 R816 explicit-shape-spec -> [lower-bound :] upper-bound
 R817 lower-bound -> specification-expr
 R818 upper-bound -> specification-expr
 R819 assumed-shape-spec -> [lower-bound] :
 R820 deferred-shape-spec -> :
 R821 assumed-implied-spec -> [lower-bound :] *
 R822 assumed-size-spec -> explicit-shape-spec-list , assumed-implied-spec
 R823 implied-shape-or-assumed-size-spec -> assumed-implied-spec
 R824 implied-shape-spec -> assumed-implied-spec , assumed-implied-spec-list
 R825 assumed-rank-spec -> ..
 R826 intent-spec -> IN | OUT | INOUT
 R827 access-stmt -> access-spec [[::] access-id-list]
 R828 access-id -> access-name | generic-spec
 R829 allocatable-stmt -> ALLOCATABLE [::] allocatable-decl-list
 R830 allocatable-decl ->
        object-name [( array-spec )] [lbracket coarray-spec rbracket]
 R831 asynchronous-stmt -> ASYNCHRONOUS [::] object-name-list
 R832 bind-stmt -> language-binding-spec [::] bind-entity-list
 R833 bind-entity -> entity-name | / common-block-name /
 R834 codimension-stmt -> CODIMENSION [::] codimension-decl-list
 R835 codimension-decl -> coarray-name lbracket coarray-spec rbracket
 R836 contiguous-stmt -> CONTIGUOUS [::] object-name-list
 R837 data-stmt -> DATA data-stmt-set [[,] data-stmt-set]...
 R838 data-stmt-set -> data-stmt-object-list / data-stmt-value-list /
 R839 data-stmt-object -> variable | data-implied-do
 R840 data-implied-do ->
        ( data-i-do-object-list , [integer-type-spec ::]
        data-i-do-variable = scalar-int-constant-expr ,
        scalar-int-constant-expr [, scalar-int-constant-expr] )
 R841 data-i-do-object ->
        array-element | scalar-structure-component | data-implied-do
 R842 data-i-do-variable -> do-variable
 R843 data-stmt-value -> [data-stmt-repeat *] data-stmt-constant
 R844 data-stmt-repeat -> scalar-int-constant | scalar-int-constant-subobject
 R845 data-stmt-constant ->
        scalar-constant | scalar-constant-subobject |
        signed-int-literal-constant | signed-real-literal-constant |
        null-init | initial-data-target | structure-constructor
 R846 int-constant-subobject -> constant-subobject
 R847 constant-subobject -> designator
 R848 dimension-stmt ->
        DIMENSION [::] array-name ( array-spec )
        [, array-name ( array-spec )]...
 R849 intent-stmt -> INTENT ( intent-spec ) [::] dummy-arg-name-list
 R850 optional-stmt -> OPTIONAL [::] dummy-arg-name-list
 R851 parameter-stmt -> PARAMETER ( named-constant-def-list )
 R852 named-constant-def -> named-constant = constant-expr
 R853 pointer-stmt -> POINTER [::] pointer-decl-list
 R854 pointer-decl ->
        object-name [( deferred-shape-spec-list )] | proc-entity-name
 R855 protected-stmt -> PROTECTED [::] entity-name-list
 R856 save-stmt -> SAVE [[::] saved-entity-list]
 R857 saved-entity -> object-name | proc-pointer-name | / common-block-name /
 R858 proc-pointer-name -> name
 R859 target-stmt -> TARGET [::] target-decl-list
 R860 target-decl ->
        object-name [( array-spec )] [lbracket coarray-spec rbracket]
 R861 value-stmt -> VALUE [::] dummy-arg-name-list
 R862 volatile-stmt -> VOLATILE [::] object-name-list
 R863 implicit-stmt ->
        IMPLICIT implicit-spec-list |
        IMPLICIT NONE [( [implicit-name-spec-list] )]
 R864 implicit-spec -> declaration-type-spec ( letter-spec-list )
 R865 letter-spec -> letter [- letter]
 R866 implicit-name-spec -> EXTERNAL | TYPE
 R867 import-stmt ->
        IMPORT [[::] import-name-list] | IMPORT , ONLY : import-name-list |
        IMPORT , NONE | IMPORT , ALL
 R868 namelist-stmt ->
        NAMELIST / namelist-group-name / namelist-group-object-list
        [[,] / namelist-group-name / namelist-group-object-list]...
 R869 namelist-group-object -> variable-name
 R870 equivalence-stmt -> EQUIVALENCE equivalence-set-list
 R871 equivalence-set -> ( equivalence-object , equivalence-object-list )
 R872 equivalence-object -> variable-name | array-element | substring
 R873 common-stmt ->
        COMMON [/ [common-block-name] /] common-block-object-list
        [[,] / [common-block-name] / common-block-object-list]...
 R874 common-block-object -> variable-name [( array-spec )]
 
 R901 designator ->
        object-name | array-element | array-section |
        coindexed-named-object | complex-part-designator |
        structure-component | substring
 R902 variable -> designator | function-reference
 R903 variable-name -> name
 R904 logical-variable -> variable
 R905 char-variable -> variable
 R906 default-char-variable -> variable
 R907 int-variable -> variable
 R908 substring -> parent-string ( substring-range )
 R909 parent-string ->
        scalar-variable-name | array-element | coindexed-named-object |
        scalar-structure-component | scalar-char-literal-constant |
        scalar-named-constant
 R910 substring-range -> [scalar-int-expr] : [scalar-int-expr]
 R911 data-ref -> part-ref [% part-ref]...
 R912 part-ref -> part-name [( section-subscript-list )] [image-selector]
 R913 structure-component -> data-ref
 R914 coindexed-named-object -> data-ref
 R915 complex-part-designator -> designator % RE | designator % IM
 R916 type-param-inquiry -> designator % type-param-name
 R917 array-element -> data-ref
 R918 array-section ->
        data-ref [( substring-range )] | complex-part-designator
 R919 subscript -> scalar-int-expr
 R920 section-subscript -> subscript | subscript-triplet | vector-subscript
 R921 subscript-triplet -> [subscript] : [subscript] [: stride]
 R922 stride -> scalar-int-expr
 R923 vector-subscript -> int-expr
 R924 image-selector ->
        lbracket cosubscript-list [, image-selector-spec-list] rbracket
 R925 cosubscript -> scalar-int-expr
 R926 image-selector-spec ->
        STAT = stat-variable | TEAM = team-value |
        TEAM_NUMBER = scalar-int-expr
 R927 allocate-stmt ->
        ALLOCATE ( [type-spec ::] allocation-list [, alloc-opt-list] )
 R928 alloc-opt ->
        ERRMSG = errmsg-variable | MOLD = source-expr |
        SOURCE = source-expr | STAT = stat-variable
 R929 stat-variable -> scalar-int-variable
 R930 errmsg-variable -> scalar-default-char-variable
 R931 source-expr -> expr
 R932 allocation ->
        allocate-object [( allocate-shape-spec-list )]
        [lbracket allocate-coarray-spec rbracket]
 R933 allocate-object -> variable-name | structure-component
 R934 allocate-shape-spec -> [lower-bound-expr :] upper-bound-expr
 R935 lower-bound-expr -> scalar-int-expr
 R936 upper-bound-expr -> scalar-int-expr
 R937 allocate-coarray-spec ->
        [allocate-coshape-spec-list ,] [lower-bound-expr :] *
 R938 allocate-coshape-spec -> [lower-bound-expr :] upper-bound-expr
 R939 nullify-stmt -> NULLIFY ( pointer-object-list )
 R940 pointer-object -> variable-name | structure-component | proc-pointer-name
 R941 deallocate-stmt ->
        DEALLOCATE ( allocate-object-list [, dealloc-opt-list] )
 R942 dealloc-opt -> STAT = stat-variable | ERRMSG = errmsg-variable
 
 R1001 primary ->
         literal-constant | designator | array-constructor |
         structure-constructor | function-reference | type-param-inquiry |
         type-param-name | ( expr )
 R1002 level-1-expr -> [defined-unary-op] primary
 R1003 defined-unary-op -> . letter [letter]... .
 R1004 mult-operand -> level-1-expr [power-op mult-operand]
 R1005 add-operand -> [add-operand mult-op] mult-operand
 R1006 level-2-expr -> [[level-2-expr] add-op] add-operand
 R1007 power-op -> **
 R1008 mult-op -> * | /
 R1009 add-op -> + | -
 R1010 level-3-expr -> [level-3-expr concat-op] level-2-expr
 R1011 concat-op -> //
 R1012 level-4-expr -> [level-3-expr rel-op] level-3-expr
 R1013 rel-op ->
         .EQ. | .NE. | .LT. | .LE. | .GT. | .GE. |
         == | /= | < | <= | > | >=  @ | <>
 R1014 and-operand -> [not-op] level-4-expr
 R1015 or-operand -> [or-operand and-op] and-operand
 R1016 equiv-operand -> [equiv-operand or-op] or-operand
 R1017 level-5-expr -> [level-5-expr equiv-op] equiv-operand
 R1018 not-op -> .NOT.
 R1019 and-op -> .AND.
 R1020 or-op -> .OR.
 R1021 equiv-op -> .EQV. | .NEQV.
 R1022 expr -> [expr defined-binary-op] level-5-expr
 R1023 defined-binary-op -> . letter [letter]... .
 R1024 logical-expr -> expr
 R1025 default-char-expr -> expr
 R1026 int-expr -> expr
 R1027 numeric-expr -> expr
 R1028 specification-expr -> scalar-int-expr
 R1029 constant-expr -> expr
 R1030 default-char-constant-expr -> default-char-expr
 R1031 int-constant-expr -> int-expr
 R1032 assignment-stmt -> variable = expr
 R1033 pointer-assignment-stmt ->
         data-pointer-object [( bounds-spec-list )] => data-target |
         data-pointer-object ( bounds-remapping-list ) => data-target |
         proc-pointer-object => proc-target
 R1034 data-pointer-object ->
         variable-name | scalar-variable % data-pointer-component-name
 R1035 bounds-spec -> lower-bound-expr :
 R1036 bounds-remapping -> lower-bound-expr : upper-bound-expr
 R1037 data-target -> expr
 R1038 proc-pointer-object -> proc-pointer-name | proc-component-ref
 R1039 proc-component-ref -> scalar-variable % procedure-component-name
 R1040 proc-target -> expr | procedure-name | proc-component-ref
 R1041 where-stmt -> WHERE ( mask-expr ) where-assignment-stmt
 R1042 where-construct ->
         where-construct-stmt [where-body-construct]...
         [masked-elsewhere-stmt [where-body-construct]...]...
         [elsewhere-stmt [where-body-construct]...] end-where-stmt
 R1043 where-construct-stmt -> [where-construct-name :] WHERE ( mask-expr )
 R1044 where-body-construct ->
         where-assignment-stmt | where-stmt | where-construct
 R1045 where-assignment-stmt -> assignment-stmt
 R1046 mask-expr -> logical-expr
 R1047 masked-elsewhere-stmt -> ELSEWHERE ( mask-expr ) [where-construct-name]
 R1048 elsewhere-stmt -> ELSEWHERE [where-construct-name]
 R1049 end-where-stmt -> END WHERE [where-construct-name]
 R1050 forall-construct ->
         forall-construct-stmt [forall-body-construct]... end-forall-stmt
 R1051 forall-construct-stmt ->
         [forall-construct-name :] FORALL concurrent-header
 R1052 forall-body-construct ->
         forall-assignment-stmt | where-stmt | where-construct |
         forall-construct | forall-stmt
 R1053 forall-assignment-stmt -> assignment-stmt | pointer-assignment-stmt
 R1054 end-forall-stmt -> END FORALL [forall-construct-name]
 R1055 forall-stmt -> FORALL concurrent-header forall-assignment-stmt
 
 R1101 block -> [execution-part-construct]...
 R1102 associate-construct -> associate-stmt block end-associate-stmt
 R1103 associate-stmt ->
         [associate-construct-name :] ASSOCIATE ( association-list )
 R1104 association -> associate-name => selector
 R1105 selector -> expr | variable
 R1106 end-associate-stmt -> END ASSOCIATE [associate-construct-name]
 R1107 block-construct ->
         block-stmt [block-specification-part] block end-block-stmt
 R1108 block-stmt -> [block-construct-name :] BLOCK
 R1109 block-specification-part ->
         [use-stmt]... [import-stmt]...
         [[declaration-construct]... specification-construct]
 R1110 end-block-stmt -> END BLOCK [block-construct-name]
 R1111 change-team-construct -> change-team-stmt block end-change-team-stmt
 R1112 change-team-stmt ->
         [team-construct-name :] CHANGE TEAM ( team-value
         [, coarray-association-list] [, sync-stat-list] )
 R1113 coarray-association -> codimension-decl => selector
 R1114 end-change-team-stmt ->
         END TEAM [( [sync-stat-list] )] [team-construct-name]
 R1115 team-value -> scalar-expr
 R1116 critical-construct -> critical-stmt block end-critical-stmt
 R1117 critical-stmt ->
         [critical-construct-name :] CRITICAL [( [sync-stat-list] )]
 R1118 end-critical-stmt -> END CRITICAL [critical-construct-name]
 R1119 do-construct -> do-stmt block end-do
 R1120 do-stmt -> nonlabel-do-stmt | label-do-stmt
 R1121 label-do-stmt -> [do-construct-name :] DO label [loop-control]
 R1122 nonlabel-do-stmt -> [do-construct-name :] DO [loop-control]
 R1123 loop-control ->
         [,] do-variable = scalar-int-expr , scalar-int-expr
           [, scalar-int-expr] |
         [,] WHILE ( scalar-logical-expr ) |
         [,] CONCURRENT concurrent-header concurrent-locality
 R1124 do-variable -> scalar-int-variable-name
 R1125 concurrent-header ->
         ( [integer-type-spec ::] concurrent-control-list [, scalar-mask-expr] )
 R1126 concurrent-control ->
         index-name = concurrent-limit : concurrent-limit [: concurrent-step]
 R1127 concurrent-limit -> scalar-int-expr
 R1128 concurrent-step -> scalar-int-expr
 R1129 concurrent-locality -> [locality-spec]...
 R1130 locality-spec ->
         LOCAL ( variable-name-list ) | LOCAL_INIT ( variable-name-list ) |
         SHARED ( variable-name-list ) | DEFAULT ( NONE )
 R1131 end-do -> end-do-stmt | continue-stmt
 R1132 end-do-stmt -> END DO [do-construct-name]
 R1133 cycle-stmt -> CYCLE [do-construct-name]
 R1134 if-construct ->
         if-then-stmt block [else-if-stmt block]... [else-stmt block]
         end-if-stmt
 R1135 if-then-stmt -> [if-construct-name :] IF ( scalar-logical-expr ) THEN
 R1136 else-if-stmt -> ELSE IF ( scalar-logical-expr ) THEN [if-construct-name]
 R1137 else-stmt -> ELSE [if-construct-name]
 R1138 end-if-stmt -> END IF [if-construct-name]
 R1139 if-stmt -> IF ( scalar-logical-expr ) action-stmt
 R1140 case-construct -> select-case-stmt [case-stmt block]... end-select-stmt
 R1141 select-case-stmt -> [case-construct-name :] SELECT CASE ( case-expr )
 R1142 case-stmt -> CASE case-selector [case-construct-name]
 R1143 end-select-stmt -> END SELECT [case-construct-name]
 R1144 case-expr -> scalar-expr
 R1145 case-selector -> ( case-value-range-list ) | DEFAULT
 R1146 case-value-range ->
         case-value | case-value : | : case-value | case-value : case-value
 R1147 case-value -> scalar-constant-expr
 R1148 select-rank-construct ->
         select-rank-stmt [select-rank-case-stmt block]... end-select-rank-stmt
 R1149 select-rank-stmt ->
         [select-construct-name :] SELECT RANK ( [associate-name =>] selector )
 R1150 select-rank-case-stmt ->
         RANK ( scalar-int-constant-expr ) [select-construct-name] |
         RANK ( * ) [select-construct-name] |
         RANK DEFAULT [select-construct-name]
 R1151 end-select-rank-stmt -> END SELECT [select-construct-name]
 R1152 select-type-construct ->
         select-type-stmt [type-guard-stmt block]... end-select-type-stmt
 R1153 select-type-stmt ->
         [select-construct-name :] SELECT TYPE ( [associate-name =>] selector )
 R1154 type-guard-stmt ->
         TYPE IS ( type-spec ) [select-construct-name] |
         CLASS IS ( derived-type-spec ) [select-construct-name] |
         CLASS DEFAULT [select-construct-name]
 R1155 end-select-type-stmt -> END SELECT [select-construct-name]
 R1156 exit-stmt -> EXIT [construct-name]
 R1157 goto-stmt -> GO TO label
 R1158 computed-goto-stmt -> GO TO ( label-list ) [,] scalar-int-expr
 R1159 continue-stmt -> CONTINUE
 R1160 stop-stmt -> STOP [stop-code] [, QUIET = scalar-logical-expr]
 R1161 error-stop-stmt -> ERROR STOP [stop-code] [, QUIET = scalar-logical-expr]
 R1162 stop-code -> scalar-default-char-expr | scalar-int-expr
 R1163 fail-image-stmt -> FAIL IMAGE
 R1164 sync-all-stmt -> SYNC ALL [( [sync-stat-list] )]
 R1165 sync-stat -> STAT = stat-variable | ERRMSG = errmsg-variable
 R1166 sync-images-stmt -> SYNC IMAGES ( image-set [, sync-stat-list] )
 R1167 image-set -> int-expr | *
 R1168 sync-memory-stmt -> SYNC MEMORY [( [sync-stat-list] )]
 R1169 sync-team-stmt -> SYNC TEAM ( team-value [, sync-stat-list] )
 R1170 event-post-stmt -> EVENT POST ( event-variable [, sync-stat-list] )
 R1171 event-variable -> scalar-variable
 R1172 event-wait-stmt -> EVENT WAIT ( event-variable [, event-wait-spec-list] )
 R1173 event-wait-spec -> until-spec | sync-stat
 R1174 until-spec -> UNTIL_COUNT = scalar-int-expr
 R1175 form-team-stmt ->
         FORM TEAM ( team-number , team-variable [, form-team-spec-list] )
 R1176 team-number -> scalar-int-expr
 R1177 team-variable -> scalar-variable
 R1178 form-team-spec -> NEW_INDEX = scalar-int-expr | sync-stat
 R1179 lock-stmt -> LOCK ( lock-variable [, lock-stat-list] )
 R1180 lock-stat -> ACQUIRED_LOCK = scalar-logical-variable | sync-stat
 R1181 unlock-stmt -> UNLOCK ( lock-variable [, sync-stat-list] )
 R1182 lock-variable -> scalar-variable
 
 R1201 io-unit -> file-unit-number | * | internal-file-variable
 R1202 file-unit-number -> scalar-int-expr
 R1203 internal-file-variable -> char-variable
 R1204 open-stmt -> OPEN ( connect-spec-list )
 R1205 connect-spec ->
         [UNIT =] file-unit-number | ACCESS = scalar-default-char-expr |
         ACTION = scalar-default-char-expr |
         ASYNCHRONOUS = scalar-default-char-expr |
         BLANK = scalar-default-char-expr |
         DECIMAL = scalar-default-char-expr | DELIM = scalar-default-char-expr |
         ENCODING = scalar-default-char-expr | ERR = label |
         FILE = file-name-expr | FORM = scalar-default-char-expr |
         IOMSG = iomsg-variable | IOSTAT = scalar-int-variable |
         NEWUNIT = scalar-int-variable | PAD = scalar-default-char-expr |
         POSITION = scalar-default-char-expr | RECL = scalar-int-expr |
         ROUND = scalar-default-char-expr | SIGN = scalar-default-char-expr |
         STATUS = scalar-default-char-expr
         @ | CONVERT = scalar-default-char-expr
           | DISPOSE = scalar-default-char-expr
 R1206 file-name-expr -> scalar-default-char-expr
 R1207 iomsg-variable -> scalar-default-char-variable
 R1208 close-stmt -> CLOSE ( close-spec-list )
 R1209 close-spec ->
         [UNIT =] file-unit-number | IOSTAT = scalar-int-variable |
         IOMSG = iomsg-variable | ERR = label |
         STATUS = scalar-default-char-expr
 R1210 read-stmt ->
         READ ( io-control-spec-list ) [input-item-list] |
         READ format [, input-item-list]
 R1211 write-stmt -> WRITE ( io-control-spec-list ) [output-item-list]
 R1212 print-stmt -> PRINT format [, output-item-list]
 R1213 io-control-spec ->
         [UNIT =] io-unit | [FMT =] format | [NML =] namelist-group-name |
         ADVANCE = scalar-default-char-expr |
         ASYNCHRONOUS = scalar-default-char-constant-expr |
         BLANK = scalar-default-char-expr | DECIMAL = scalar-default-char-expr |
         DELIM = scalar-default-char-expr | END = label | EOR = label |
         ERR = label | ID = id-variable | IOMSG = iomsg-variable |
         IOSTAT = scalar-int-variable | PAD = scalar-default-char-expr |
         POS = scalar-int-expr | REC = scalar-int-expr |
         ROUND = scalar-default-char-expr | SIGN = scalar-default-char-expr |
         SIZE = scalar-int-variable
 R1214 id-variable -> scalar-int-variable
 R1215 format -> default-char-expr | label | *
 R1216 input-item -> variable | io-implied-do
 R1217 output-item -> expr | io-implied-do
 R1218 io-implied-do -> ( io-implied-do-object-list , io-implied-do-control )
 R1219 io-implied-do-object -> input-item | output-item
 R1220 io-implied-do-control ->
         do-variable = scalar-int-expr , scalar-int-expr [, scalar-int-expr]
 R1221 dtv-type-spec -> TYPE ( derived-type-spec ) | CLASS ( derived-type-spec )
 R1222 wait-stmt -> WAIT ( wait-spec-list )
 R1223 wait-spec ->
         [UNIT =] file-unit-number | END = label | EOR = label | ERR = label |
         ID = scalar-int-expr | IOMSG = iomsg-variable |
         IOSTAT = scalar-int-variable
 R1224 backspace-stmt ->
         BACKSPACE file-unit-number | BACKSPACE ( position-spec-list )
 R1225 endfile-stmt -> ENDFILE file-unit-number | ENDFILE ( position-spec-list )
 R1226 rewind-stmt -> REWIND file-unit-number | REWIND ( position-spec-list )
 R1227 position-spec ->
         [UNIT =] file-unit-number | IOMSG = iomsg-variable |
         IOSTAT = scalar-int-variable | ERR = label
 R1228 flush-stmt -> FLUSH file-unit-number | FLUSH ( flush-spec-list )
 R1229 flush-spec ->
         [UNIT =] file-unit-number | IOSTAT = scalar-int-variable |
         IOMSG = iomsg-variable | ERR = label
 R1230 inquire-stmt ->
         INQUIRE ( inquire-spec-list ) |
         INQUIRE ( IOLENGTH = scalar-int-variable ) output-item-list
 R1231 inquire-spec ->
         [UNIT =] file-unit-number | FILE = file-name-expr |
         ACCESS = scalar-default-char-variable |
         ACTION = scalar-default-char-variable |
         ASYNCHRONOUS = scalar-default-char-variable |
         BLANK = scalar-default-char-variable |
         DECIMAL = scalar-default-char-variable |
         DELIM = scalar-default-char-variable |
         ENCODING = scalar-default-char-variable |
         ERR = label | EXIST = scalar-logical-variable |
         FORM = scalar-default-char-variable |
         FORMATTED = scalar-default-char-variable | ID = scalar-int-expr |
         IOMSG = iomsg-variable | IOSTAT = scalar-int-variable |
         NAME = scalar-default-char-variable |
         NAMED = scalar-logical-variable | NEXTREC = scalar-int-variable |
         NUMBER = scalar-int-variable | OPENED = scalar-logical-variable |
         PAD = scalar-default-char-variable |
         PENDING = scalar-logical-variable | POS = scalar-int-variable |
         POSITION = scalar-default-char-variable |
         READ = scalar-default-char-variable |
         READWRITE = scalar-default-char-variable |
         RECL = scalar-int-variable | ROUND = scalar-default-char-variable |
         SEQUENTIAL = scalar-default-char-variable |
         SIGN = scalar-default-char-variable | SIZE = scalar-int-variable |
         STREAM = scalar-default-char-variable |
         STATUS = scalar-default-char-variable |
         WRITE = scalar-default-char-variable
         @ | CONVERT = scalar-default-char-expr
           | DISPOSE = scalar-default-char-expr
 
 R1301 format-stmt -> FORMAT format-specification
 R1302 format-specification ->
         ( [format-items] ) | ( [format-items ,] unlimited-format-item )
 R1303 format-items -> format-item [[,] format-item]...
 R1304 format-item ->
         [r] data-edit-desc | control-edit-desc | char-string-edit-desc | [r] ( format-items )
 R1305 unlimited-format-item -> * ( format-items )
 R1306 r -> digit-string
 R1307 data-edit-desc ->
         I w [. m] | B w [. m] | O w [. m] | Z w [. m] | F w . d |
         E w . d [E e] | EN w . d [E e] | ES w . d [E e] | EX w . d [E e] |
         G w [. d [E e]] | L w | A [w] | D w . d |
         DT [char-literal-constant] [( v-list )]
 R1308 w -> digit-string
 R1309 m -> digit-string
 R1310 d -> digit-string
 R1311 e -> digit-string
 R1312 v -> [sign] digit-string
 R1313 control-edit-desc ->
         position-edit-desc | [r] / | : | sign-edit-desc | k P |
         blank-interp-edit-desc | round-edit-desc | decimal-edit-desc |
         @ $ | \
 R1314 k -> [sign] digit-string
 R1315 position-edit-desc -> T n | TL n | TR n | n X
 R1316 n -> digit-string
 R1317 sign-edit-desc -> SS | SP | S
 R1318 blank-interp-edit-desc -> BN | BZ
 R1319 round-edit-desc -> RU | RD | RZ | RN | RC | RP
 R1320 decimal-edit-desc -> DC | DP
 R1321 char-string-edit-desc -> char-literal-constant
 
 R1401 main-program ->
         [program-stmt] [specification-part] [execution-part]
         [internal-subprogram-part] end-program-stmt
 R1402 program-stmt -> PROGRAM program-name
 R1403 end-program-stmt -> END [PROGRAM [program-name]]
 R1404 module ->
         module-stmt [specification-part] [module-subprogram-part]
         end-module-stmt
 R1405 module-stmt -> MODULE module-name
 R1406 end-module-stmt -> END [MODULE [module-name]]
 R1407 module-subprogram-part -> contains-stmt [module-subprogram]...
 R1408 module-subprogram ->
         function-subprogram | subroutine-subprogram |
         separate-module-subprogram
 R1409 use-stmt ->
         USE [[, module-nature] ::] module-name [, rename-list] |
         USE [[, module-nature] ::] module-name , ONLY : [only-list]
 R1410 module-nature -> INTRINSIC | NON_INTRINSIC
 R1411 rename ->
         local-name => use-name |
         OPERATOR ( local-defined-operator ) =>
           OPERATOR ( use-defined-operator )
 R1412 only -> generic-spec | only-use-name | rename
 R1413 only-use-name -> use-name
 R1414 local-defined-operator -> defined-unary-op | defined-binary-op
 R1415 use-defined-operator -> defined-unary-op | defined-binary-op
 R1416 submodule ->
         submodule-stmt [specification-part] [module-subprogram-part]
         end-submodule-stmt
 R1417 submodule-stmt -> SUBMODULE ( parent-identifier ) submodule-name
 R1418 parent-identifier -> ancestor-module-name [: parent-submodule-name]
 R1419 end-submodule-stmt -> END [SUBMODULE [submodule-name]]
 R1420 block-data -> block-data-stmt [specification-part] end-block-data-stmt
 R1421 block-data-stmt -> BLOCK DATA [block-data-name]
 R1422 end-block-data-stmt -> END [BLOCK DATA [block-data-name]]
 
 R1501 interface-block ->
         interface-stmt [interface-specification]... end-interface-stmt
 R1502 interface-specification -> interface-body | procedure-stmt
 R1503 interface-stmt -> INTERFACE [generic-spec] | ABSTRACT INTERFACE
 R1504 end-interface-stmt -> END INTERFACE [generic-spec]
 R1505 interface-body ->
         function-stmt [specification-part] end-function-stmt |
         subroutine-stmt [specification-part] end-subroutine-stmt
 R1506 procedure-stmt -> [MODULE] PROCEDURE [::] specific-procedure-list
 R1507 specific-procedure -> procedure-name
 R1508 generic-spec ->
         generic-name | OPERATOR ( defined-operator ) |
         ASSIGNMENT ( = ) | defined-io-generic-spec
 R1509 defined-io-generic-spec ->
         READ ( FORMATTED ) | READ ( UNFORMATTED ) |
         WRITE ( FORMATTED ) | WRITE ( UNFORMATTED )
 R1510 generic-stmt ->
         GENERIC [, access-spec] :: generic-spec => specific-procedure-list
 R1511 external-stmt -> EXTERNAL [::] external-name-list
 R1512 procedure-declaration-stmt ->
         PROCEDURE ( [proc-interface] ) [[, proc-attr-spec]... ::]
         proc-decl-list
 R1513 proc-interface -> interface-name | declaration-type-spec
 R1514 proc-attr-spec ->
         access-spec | proc-language-binding-spec | INTENT ( intent-spec ) |
         OPTIONAL | POINTER | PROTECTED | SAVE
 R1515 proc-decl -> procedure-entity-name [=> proc-pointer-init]
 R1516 interface-name -> name
 R1517 proc-pointer-init -> null-init | initial-proc-target
 R1518 initial-proc-target -> procedure-name
 R1519 intrinsic-stmt -> INTRINSIC [::] intrinsic-procedure-name-list
 R1520 function-reference -> procedure-designator ( [actual-arg-spec-list] )
 R1521 call-stmt -> CALL procedure-designator [( [actual-arg-spec-list] )]
 R1522 procedure-designator ->
         procedure-name | proc-component-ref | data-ref % binding-name
 R1523 actual-arg-spec -> [keyword =] actual-arg
 R1524 actual-arg ->
         expr | variable | procedure-name | proc-component-ref | alt-return-spec
 R1525 alt-return-spec -> * label
 R1526 prefix -> prefix-spec [prefix-spec]...
 R1527 prefix-spec ->
         declaration-type-spec | ELEMENTAL | IMPURE | MODULE | NON_RECURSIVE |
         PURE | RECURSIVE
 R1528 proc-language-binding-spec -> language-binding-spec
 R1529 function-subprogram ->
         function-stmt [specification-part] [execution-part]
         [internal-subprogram-part] end-function-stmt
 R1530 function-stmt ->
         [prefix] FUNCTION function-name ( [dummy-arg-name-list] ) [suffix]
 R1531 dummy-arg-name -> name
 R1532 suffix ->
         proc-language-binding-spec [RESULT ( result-name )] |
         RESULT ( result-name ) [proc-language-binding-spec]
 R1533 end-function-stmt -> END [FUNCTION [function-name]]
 R1534 subroutine-subprogram ->
         subroutine-stmt [specification-part] [execution-part]
         [internal-subprogram-part] end-subroutine-stmt
 R1535 subroutine-stmt ->
         [prefix] SUBROUTINE subroutine-name
         [( [dummy-arg-list] ) [proc-language-binding-spec]]
 R1536 dummy-arg -> dummy-arg-name | *
 R1537 end-subroutine-stmt -> END [SUBROUTINE [subroutine-name]]
 R1538 separate-module-subprogram ->
         mp-subprogram-stmt [specification-part] [execution-part]
         [internal-subprogram-part] end-mp-subprogram-stmt
 R1539 mp-subprogram-stmt -> MODULE PROCEDURE procedure-name
 R1540 end-mp-subprogram-stmt -> END [PROCEDURE [procedure-name]]
 R1541 entry-stmt -> ENTRY entry-name [( [dummy-arg-list] ) [suffix]]
 R1542 return-stmt -> RETURN [scalar-int-expr]
 R1543 contains-stmt -> CONTAINS
 R1544 stmt-function-stmt ->
         function-name ( [dummy-arg-name-list] ) = scalar-expr

flang/docs/flang-c-style.el

 ;;===-- documentation/flang-c-style.el ------------------------------------===;;
 ;;
 ;; 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
 ;;
 ;;===----------------------------------------------------------------------===;;
 
 ;; Define a cc-mode style for editing C++ codes in Flang.
 ;;
 ;; Inspired from LLVM style in
 ;;    https://github.com/llvm-mirror/llvm/blob/master/utils/emacs/emacs.el
 ;;
 
 (c-add-style "flang"
              '("gnu"
          (fill-column . 80)
          (c++-indent-level . 2)
          (c-basic-offset . 2)
          (indent-tabs-mode . nil)
          (c-offsets-alist .
                    ((arglist-intro . ++) 
                     (innamespace . 0)
                     (member-init-intro . ++)
                     ))
                ))
 
 
 ;;
 ;; Use the following to make it the default.  
 ;;
 
 (defun flang-c-mode-hook ()
   (c-set-style "flang")
   )
 
 (add-hook 'c-mode-hook   'flang-c-mode-hook)
 (add-hook 'c++-mode-hook 'flang-c-mode-hook)

flang/documentation/BijectiveInternalNameUniquing.md

-## Bijective Internal Name Uniquing
-
-FIR has a flat namespace.  No two objects may have the same name at
-the module level.  (These would be functions, globals, etc.)
-This necessitates some sort of encoding scheme to unique
-symbols from the front-end into FIR.
-
-Another requirement is
-to be able to reverse these unique names and recover the associated
-symbol in the symbol table.
-
-Fortran is case insensitive, which allows the compiler to convert the
-user's identifiers to all lower case.  Such a universal conversion implies
-that all upper case letters are available for use in uniquing.
-
-### Prefix `_Q`
-
-All uniqued names have the prefix sequence `_Q` to indicate the name has
-been uniqued.  (Q is chosen because it is a
-[low frequency letter](http://pi.math.cornell.edu/~mec/2003-2004/cryptography/subs/frequencies.html)
-in English.)
-
-### Scope Building
-
-Symbols can be scoped by the module, submodule, or procedure that contains
-that symbol.  After the `_Q` sigil, names are constructed from outermost to
-innermost scope as
-
-   * Module name prefixed with `M`
-   * Submodule name prefixed with `S`
-   * Procedure name prefixed with `F`
-
-Given:
-```
-    submodule (mod:s1mod) s2mod
-      ...
-      subroutine sub
-        ...
-      contains
-        function fun
-```
-
-The uniqued name of `fun` becomes:
-```
-    _QMmodSs1modSs2modFsubPfun
-```
-
-### Common blocks
-
-   * A common block name will be prefixed with `B`
-
-Given:
-```
-   common /variables/ i, j
-```
-
-The uniqued name of `variables` becomes:
-```
-    _QBvariables
-```
-
-Given:
-```
-   common i, j
-```
-
-The uniqued name in case of `blank common block` becomes:
-```
-    _QB
-```
-
-### Module scope global data
-
-   * A global data entity is prefixed with `E`
-   * A global entity that is constant (parameter) will be prefixed with `EC`
-
-Given:
-```
-    module mod
-      integer :: intvar
-      real, parameter :: pi = 3.14
-    end module
-```
-
-The uniqued name of `intvar` becomes:
-```
-    _QMmodEintvar
-```
-
-The uniqued name of `pi` becomes:
-```
-    _QMmodECpi
-```
-
-### Procedures/Subprograms
-
-   * A procedure/subprogram is prefixed with `P`
-
-Given:
-```
-    subroutine sub
-```
-The uniqued name of `sub` becomes:
-```
-    _QPsub
-```
-
-### Derived types and related
-
-   * A derived type is prefixed with `T`
-   * If a derived type has KIND parameters, they are listed in a consistent
-     canonical order where each takes the form `Ki` and where _i_ is the
-     compile-time constant value. (All type parameters are integer.)  If _i_
-     is a negative value, the prefix `KN` will be used and _i_ will reflect
-     the magnitude of the value.
-
-Given:
-```
-    module mymodule
-      type mytype
-        integer :: member
-      end type
-      ...
-```
-The uniqued name of `mytype` becomes:
-```
-    _QMmymoduleTmytype
-```
-
-Given:
-```
-    type yourtype(k1,k2)
-      integer, kind :: k1, k2
-      real :: mem1
-      complex :: mem2
-    end type
-```
-
-The uniqued name of `yourtype` where `k1=4` and `k2=-6` (at compile-time):
-```
-    _QTyourtypeK4KN6
-```
-
-   * A derived type dispatch table is prefixed with `D`.  The dispatch table
-     for `type t` would be `_QDTt`
-   * A type descriptor instance is prefixed with `C`.  Intrinsic types can
-     be encoded with their names and kinds.  The type descriptor for the
-     type `yourtype` above would be `_QCTyourtypeK4KN6`.  The type
-     descriptor for `REAL(4)` would be `_QCrealK4`.
-
-### Compiler generated names
-
-Compiler generated names do not have to be mapped back to Fortran.  These
-names will be prefixed with `_QQ` and followed by a unique compiler
-generated identifier. There is, of course, no mapping back to a symbol
-derived from the input source in this case as no such symbol exists.

flang/documentation/C++style.md

-<!--===- documentation/C++style.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
-  
--->
-
-## In brief:
-* Use *clang-format*
-from llvm 7
-on all C++ source and header files before
-every merge to master.  All code layout should be determined
-by means of clang-format.
-* Where a clear precedent exists in the project, follow it.
-* Otherwise, where [LLVM's C++ style guide](https://llvm.org/docs/CodingStandards.html#style-issues)
-is clear on usage, follow it.
-* Otherwise, where a good public C++ style guide is relevant and clear,
-  follow it.  [Google's](https://google.github.io/styleguide/cppguide.html)
-  is pretty good and comes with lots of justifications for its rules.
-* Reasonable exceptions to these guidelines can be made.
-* Be aware of some workarounds for known issues in older C++ compilers that should
-  still be able to compile f18. They are listed at the end of this document.
-
-## In particular:
-
-Use serial commas in comments, error messages, and documentation
-unless they introduce ambiguity.
-
-### Error messages
-1. Messages should be a single sentence with few exceptions.
-1. Fortran keywords should appear in upper case.
-1. Names from the program appear in single quotes.
-1. Messages should start with a capital letter.
-1. Messages should not end with a period.
-
-### Files
-1. File names should use dashes, not underscores.  C++ sources have the
-extension ".cpp", not ".C" or ".cc" or ".cxx".  Don't create needless
-source directory hierarchies.
-1. Header files should be idempotent.  Use the usual technique:
-```
-#ifndef FORTRAN_header_H_
-#define FORTRAN_header_H_
-// code
-#endif  // FORTRAN_header_H_
-```
-1. `#include` every header defining an entity that your project header or source
-file actually uses directly.  (Exception: when foo.cpp starts, as it should,
-with `#include "foo.h"`, and foo.h includes bar.h in order to define the
-interface to the module foo, you don't have to redundantly `#include "bar.h"`
-in foo.cpp.)
-1. In the source file "foo.cpp", put its corresponding `#include "foo.h"`
-first in the sequence of inclusions.
-Then `#include` other project headers in alphabetic order; then C++ standard
-headers, also alphabetically; then C and system headers.
-1. Don't use `#include <iostream>`.  If you need it for temporary debugging,
-remove the inclusion before committing.
-
-### Naming
-1. C++ names that correspond to well-known interfaces from the STL, LLVM,
-and Fortran standard
-can and should look like their models when the reader can safely assume that
-they mean the same thing -- e.g., `clear()` and `size()` member functions
-in a class that implements an STL-ish container.
-Fortran intrinsic function names are conventionally in ALL CAPS.
-1. Non-public data members should be named with leading miniscule (lower-case)
-letters, internal camelCase capitalization, and a trailing underscore,
-e.g. `DoubleEntryBookkeepingSystem myLedger_;`.  POD structures with
-only public data members shouldn't use trailing underscores, since they
-don't have class functions from which data members need to be distinguishable.
-1. Accessor member functions are named with the non-public data member's name,
-less the trailing underscore.  Mutator member functions are named `set_...`
-and should return `*this`.  Don't define accessors or mutators needlessly.
-1. Other class functions should be named with leading capital letters,
-CamelCase, and no underscores, and, like all functions, should be based
-on imperative verbs, e.g. `HaltAndCatchFire()`.
-1. It is fine to use short names for local variables with limited scopes,
-especially when you can declare them directly in a `for()`/`while()`/`if()`
-condition.  Otherwise, prefer complete English words to abbreviations
-when creating names.
-
-### Commentary
-1. Use `//` for all comments except for short `/*notes*/` within expressions.
-1. When `//` follows code on a line, precede it with two spaces.
-1. Comments should matter.  Assume that the reader knows current C++ at least as
-well as you do and avoid distracting her by calling out usage of new
-features in comments.
-
-### Layout
-Always run `clang-format` on your changes before committing code. LLVM
-has a `git-clang-format` script to facilitate running clang-format only
-on the lines that have changed.
-
-Here's what you can expect to see `clang-format` do:
-1. Indent with two spaces.
-1. Don't indent public:, protected:, and private:
-accessibility labels.
-1. Never use more than 80 characters per source line.
-1. Don't use tabs.
-1. Don't indent the bodies of namespaces, even when nested.
-1. Function result types go on the same line as the function and argument
-names.
-
-Don't try to make columns of variable names or comments
-align vertically -- they are maintenance problems.
-
-Always wrap the bodies of `if()`, `else`, `while()`, `for()`, `do`, &c.
-with braces, even when the body is a single statement or empty.  The
-opening `{` goes on
-the end of the line, not on the next line.  Functions also put the opening
-`{` after the formal arguments or new-style result type, not on the next
-line.  Use `{}` for empty inline constructors and destructors in classes.
-
-If any branch of an `if`/`else if`/`else` cascade ends with a return statement,
-they all should, with the understanding that the cases are all unexceptional.
-When testing for an error case that should cause an early return, do so with
-an `if` that doesn't have a following `else`.
-
-Don't waste space on the screen with needless blank lines or elaborate block
-commentary (lines of dashes, boxes of asterisks, &c.).  Write code so as to be
-easily read and understood with a minimum of scrolling.
-
-Avoid using assignments in controlling expressions of `if()` &c., even with
-the idiom of wrapping them with extra parentheses.
-
-In multi-element initializer lists (especially `common::visitors{...}`),
-including a comma after the last element often causes `clang-format` to do
-a better jobs of formatting.
-
-### C++ language
-Use *C++17*, unless some compiler to which we must be portable lacks a feature
-you are considering.
-However:
-1. Never throw or catch exceptions.
-1. Never use run-time type information or `dynamic_cast<>`.
-1. Never declare static data that executes a constructor.
-   (This is why `#include <iostream>` is contraindicated.)
-1. Use `{braced initializers}` in all circumstances where they work, including
-default data member initialization.  They inhibit implicit truncation.
-Don't use `= expr` initialization just to effect implicit truncation;
-prefer an explicit `static_cast<>`.
-With C++17, braced initializers work fine with `auto` too.
-Sometimes, however, there are better alternatives to empty braces;
-e.g., prefer `return std::nullopt;` to `return {};` to make it more clear
-that the function's result type is a `std::optional<>`.
-1. Avoid unsigned types apart from `size_t`, which must be used with care.
-When `int` just obviously works, just use `int`.  When you need something
-bigger than `int`, use `std::int64_t` rather than `long` or `long long`.
-1. Use namespaces to avoid conflicts with client code.  Use one top-level
-`Fortran` project namespace.  Don't introduce needless nested namespaces within the
-project when names don't conflict or better solutions exist.  Never use
-`using namespace ...;` outside test code; never use `using namespace std;`
-anywhere.  Access STL entities with names like `std::unique_ptr<>`,
-without a leading `::`.
-1. Prefer `static` functions over functions in anonymous namespaces in source files.
-1. Use `auto` judiciously.  When the type of a local variable is known,
-monomorphic, and easy to type, be explicit rather than using `auto`.
-Don't use `auto` functions unless the type of the result of an outlined member
-function definition can be more clear due to its use of types declared in the
-class.
-1. Use move semantics and smart pointers to make dynamic memory ownership
-clear.  Consider reworking any code that uses `malloc()` or a (non-placement)
-`operator new`.
-See the section on Pointers below for some suggested options.
-1. When defining argument types, use values when object semantics are
-not required and the value is small and copyable without allocation
-(e.g., `int`);
-use `const` or rvalue references for larger values (e.g., `std::string`);
-use `const` references to rather than pointers to immutable objects;
-and use non-`const` references for mutable objects, including "output" arguments
-when they can't be function results.
-Put such output arguments last (_pace_ the standard C library conventions for `memcpy()` & al.).
-1. Prefer `typename` to `class` in template argument declarations.
-1. Prefer `enum class` to plain `enum` wherever `enum class` will work.
-We have an `ENUM_CLASS` macro that helps capture the names of constants.
-1. Use `constexpr` and `const` generously.
-1. When a `switch()` statement's labels do not cover all possible case values
-explicitly, it should contain either a `default:;` at its end or a
-`default:` label that obviously crashes; we have a `CRASH_NO_CASE` macro
-for such situations.
-1. On the other hand, when a `switch()` statement really does cover all of
-the values of an `enum class`, please insert a call to the `SWITCH_COVERS_ALL_CASES`
-macro at the top of the block.  This macro does the right thing for G++ and
-clang to ensure that no warning is emitted when the cases are indeed all covered.
-1. When using `std::optional` values, avoid unprotected access to their content.
-This is usually by means of `x.has_value()` guarding execution of `*x`.
-This is implicit when they are function results assigned to local variables
-in `if`/`while` predicates.
-When no presence test is obviously protecting a `*x` reference to the
-contents, and it is assumed that the contents are present, validate that
-assumption by using `x.value()` instead.
-1. We use `c_str()` rather than `data()` when converting a `std::string`
-to a `const char *` when the result is expected to be NUL-terminated.
-1. Avoid explicit comparisions of pointers to `nullptr` and tests of
-presence of `optional<>` values with `.has_value()` in the predicate
-expressions of control flow statements, but prefer them to implicit
-conversions to `bool` when initializing `bool` variables and arguments,
-and to the use of the idiom `!!`.
-
-#### Classes
-1. Define POD structures with `struct`.
-1. Don't use `this->` in (non-static) member functions, unless forced to
-do so in a template member function.
-1. Define accessor and mutator member functions (implicitly) inline in the
-class, after constructors and assignments.  Don't needlessly define
-(implicit) inline member functions in classes unless they really solve a
-performance problem.
-1. Try to make class definitions in headers concise specifications of
-interfaces, at least to the extent that C++ allows.
-1. When copy constructors and copy assignment are not necessary,
-and move constructors/assignment is present, don't declare them and they
-will be implicitly deleted.  When neither copy nor move constructors
-or assignments should exist for a class, explicitly `=delete` all of them.
-1. Make single-argument constructors (other than copy and move constructors)
-'explicit' unless you really want to define an implicit conversion.
-
-#### Pointers
-There are many -- perhaps too many -- means of indirect addressing
-data in this project.
-Some of these are standard C++ language and library features,
-while others are local inventions in `lib/Common`:
-* Bare pointers (`Foo *p`): these are obviously nullable, non-owning,
-undefined when uninitialized, shallowly copyable, reassignable, and often
-not the right abstraction to use in this project.
-But they can be the right choice to represent an optional
-non-owning reference, as in a function result.
-Use the `DEREF()` macro to convert a pointer to a reference that isn't
-already protected by an explicit test for null.
-* References (`Foo &r`, `const Foo &r`): non-nullable, not owning,
-shallowly copyable, and not reassignable.
-References are great for invisible indirection to objects whose lifetimes are
-broader than that of the reference.
-Take care when initializing a reference with another reference to ensure
-that a copy is not made because only one of the references is `const`;
-this is a pernicious C++ language pitfall!
-* Rvalue references (`Foo &&r`): These are non-nullable references
-*with* ownership, and they are ubiquitously used for formal arguments
-wherever appropriate.
-* `std::reference_wrapper<>`: non-nullable, not owning, shallowly
-copyable, and (unlike bare references) reassignable, so suitable for
-use in STL containers and for data members in classes that need to be
-copyable or assignable.
-* `common::Reference<>`: like `std::reference_wrapper<>`, but also supports
-move semantics, member access, and comparison for equality; suitable for use in
-`std::variant<>`.
-* `std::unique_ptr<>`: A nullable pointer with ownership, null by default,
-not copyable, reassignable.
-F18 has a helpful `Deleter<>` class template that makes `unique_ptr<>`
-easier to use with forward-referenced data types.
-* `std::shared_ptr<>`: A nullable pointer with shared ownership via reference
-counting, null by default, shallowly copyable, reassignable, and slow.
-* `Indirection<>`: A non-nullable pointer with ownership and
-optional deep copy semantics; reassignable.
-Often better than a reference (due to ownership) or `std::unique_ptr<>`
-(due to non-nullability and copyability).
-Can be wrapped in `std::optional<>` when nullability is required.
-Usable with forward-referenced data types with some use of `extern template`
-in headers and explicit template instantiation in source files.
-* `CountedReference<>`: A nullable pointer with shared ownership via
-reference counting, null by default, shallowly copyable, reassignable.
-Safe to use *only* when the data are private to just one
-thread of execution.
-Used sparingly in place of `std::shared_ptr<>` only when the overhead
-of that standard feature is prohibitive.
-
-A feature matrix:
-
-| indirection           | nullable | default null | owning | reassignable | copyable          | undefined type ok? |
-| -----------           | -------- | ------------ | ------ | ------------ | --------          | ------------------ |
-| `*p`                  | yes      | no           | no     | yes          | shallowly         | yes                |
-| `&r`                  | no       | n/a          | no     | no           | shallowly         | yes                |
-| `&&r`                 | no       | n/a          | yes    | no           | shallowly         | yes                |
-| `reference_wrapper<>` | no       | n/a          | no     | yes          | shallowly         | yes                |
-| `Reference<>`         | no       | n/a          | no     | yes          | shallowly         | yes                |
-| `unique_ptr<>`        | yes      | yes          | yes    | yes          | no                | yes, with work     |
-| `shared_ptr<>`        | yes      | yes          | yes    | yes          | shallowly         | no                 |
-| `Indirection<>`       | no       | n/a          | yes    | yes          | optionally deeply | yes, with work     |
-| `CountedReference<>`  | yes      | yes          | yes    | yes          | shallowly         | no                 |
-
-### Overall design preferences
-Don't use dynamic solutions to solve problems that can be solved at
-build time; don't solve build time problems by writing programs that
-produce source code when macros and templates suffice; don't write macros
-when templates suffice.  Templates are statically typed, checked by the
-compiler, and are (or should be) visible to debuggers.
-
-### Exceptions to these guidelines
-Reasonable exceptions will be allowed; these guidelines cannot anticipate
-all situations.
-For example, names that come from other sources might be more clear if
-their original spellings are preserved rather than mangled to conform
-needlessly to the conventions here, as Google's C++ style guide does
-in a way that leads to weirdly capitalized abbreviations in names
-like `Http`.
-Consistency is one of many aspects in the pursuit of clarity,
-but not an end in itself.
-
-## C++ compiler bug workarounds
-Below is a list of workarounds for C++ compiler bugs met with f18 that, even
-if the bugs are fixed in latest C++ compiler versions, need to be applied so
-that all desired tool-chains can compile f18.
-
-### Explicitly move noncopyable local variable into optional results
-
-The following code is legal C++ but fails to compile with the
-default Ubuntu 18.04 g++ compiler (7.4.0-1ubuntu1~18.0.4.1):
-
-```
-class CantBeCopied {
- public:
- CantBeCopied(const CantBeCopied&) = delete;
- CantBeCopied(CantBeCopied&&) = default;
- CantBeCopied() {}
-};
-std::optional<CantBeCopied> fooNOK() {
-  CantBeCopied result;
-  return result; // Legal C++, but does not compile with Ubuntu 18.04 default g++
-}
-std::optional<CantBeCopied> fooOK() {
-  CantBeCopied result;
-  return {std::move(result)}; // Compiles OK everywhere
-}
-```
-The underlying bug is actually not specific to `std::optional` but this is the most common
-case in f18 where the issue may occur. The actual bug can be reproduced with any class `B`
-that has a perfect forwarding constructor taking `CantBeCopied` as argument:
-`template<typename CantBeCopied> B(CantBeCopied&& x) x_{std::forward<CantBeCopied>(x)} {}`.
-In such scenarios, Ubuntu 18.04 g++ fails to instantiate the move constructor
-and to construct the returned value as it should, instead it complains about a
-missing copy constructor.
-
-Local result variables do not need to and should not be explicitly moved into optionals
-if they have a copy constructor.

flang/documentation/Directives.md

-<!--===- documentation/Directives.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 directives supported by F18
-====================================
-
-* `!dir$ fixed` and `!dir$ free` select Fortran source forms.  Their effect
-  persists to the end of the current source file.
-* `!dir$ ignore_tkr (tkr) var-list` omits checks on type, kind, and/or rank.

flang/documentation/IORuntimeInternals.md

-<!--===- documentation/IORuntimeInternals.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
-
--->
-
-Fortran I/O Runtime Library Internal Design
-===========================================
-
-This note is meant to be an overview of the design of the *implementation*
-of the f18 Fortran compiler's runtime support library for I/O statements.
-
-The *interface* to the I/O runtime support library is defined in the
-C++ header file `runtime/io-api.h`.
-This interface was designed to minimize the amount of complexity exposed
-to its clients, which are of course the sequences of calls generated by
-the compiler to implement each I/O statement.
-By keeping this interface as simple as possible, we hope that we have
-lowered the risk of future incompatible changes that would necessitate
-recompilation of Fortran codes in order to link with later versions of
-the runtime library.
-As one will see in `io-api.h`, the interface is also directly callable
-from C and C++ programs.
-
-The I/O facilities of the Fortran 2018 language are specified in the
-language standard in its clauses 12 (I/O statements) and 13 (`FORMAT`).
-It's a complicated collection of language features:
- * Files can comprise *records* or *streams*.
- * Records can be fixed-length or variable-length.
- * Record files can be accessed sequentially or directly (random access).
- * Files can be *formatted*, or *unformatted* raw bits.
- * `CHARACTER` scalars and arrays can be used as if they were
-fixed-length formatted sequential record files.
- * Formatted I/O can be under control of a `FORMAT` statement
-or `FMT=` specifier, *list-directed* with default formatting chosen
-by the runtime, or `NAMELIST`, in which a collection of variables
-can be given a name and passed as a group to the runtime library.
- * Sequential records of a file can be partially processed by one
-or more *non-advancing* I/O statements and eventually completed by
-another.
- * `FORMAT` strings can manipulate the position in the current
-record arbitrarily, causing re-reading or overwriting.
- * Floating-point output formatting supports more rounding modes
-than the IEEE standard for floating-point arithmetic.
-
-The Fortran I/O runtime support library is written in C++17, and
-uses some C++17 standard library facilities, but it is intended
-to not have any link-time dependences on the C++ runtime support
-library or any LLVM libraries.
-This is important because there are at least two C++ runtime support
-libraries, and we don't want Fortran application builders to have to
-build multiple versions of their codes; neither do we want to require
-them to ship LLVM libraries along with their products.
-
-Consequently, dynamic memory allocation in the Fortran runtime
-uses only C's `malloc()` and `free()` functions, and the few
-C++ standard class templates that we instantiate in the library have been
-modified with optional template arguments that override their
-allocators and deallocators.
-
-Conversions between the many binary floating-point formats supported
-by f18 and their decimal representations are performed with the same
-template library of fast conversion algorithms used to interpret
-floating-point values in Fortran source programs and to emit them
-to module files.
-
-Overview of Classes
-===================
-
-A suite of C++ classes and class templates are composed to construct
-the Fortran I/O runtime support library.
-They (mostly) reside in the C++ namespace `Fortran::runtime::io`.
-They are summarized here in a bottom-up order of dependence.
-
-The header and C++ implementation source file names of these
-classes are in the process of being vigorously rearranged and
-modified; use `grep` or an IDE to discover these classes in
-the source for now.  (Sorry!)
-
-`Terminator`
-----------
-A general facility for the entire library, `Terminator` latches a
-source program statement location in terms of an unowned pointer to
-its source file path name and line number and uses them to construct
-a fatal error message if needed.
-It is used for both user program errors and internal runtime library crashes.
-
-`IoErrorHandler`
---------------
-When I/O error conditions arise at runtime that the Fortran program
-might have the privilege to handle itself via `ERR=`, `END=`, or
-`EOR=` labels and/or by an `IOSTAT=` variable, this subclass of
-`Terminator` is used to either latch the error indication or to crash.
-It sorts out priorities in the case of multiple errors and determines
-the final `IOSTAT=` value at the end of an I/O statement.
-
-`MutableModes`
-------------
-Fortran's formatted I/O statements are affected by a suite of
-modes that can be configured by `OPEN` statements, overridden by
-data transfer I/O statement control lists, and further overridden
-between data items with control edit descriptors in a `FORMAT` string.
-These modes are represented with a `MutableModes` instance, and these
-are instantiated and copied where one would expect them to be in
-order to properly isolate their modifications.
-The modes in force at the time each data item is processed constitute
-a member of each `DataEdit`.
-
-`DataEdit`
---------
-Represents a single data edit descriptor from a `FORMAT` statement
-or `FMT=` character value, with some hidden extensions to also
-support formatting of list-directed transfers.
-It holds an instance of `MutableModes`, and also has a repetition
-count for when an array appears as a data item in the *io-list*.
-For simplicity and efficiency, each data edit descriptor is
-encoded in the `DataEdit` as a simple capitalized character
-(or two) and some optional field widths.
-
-`FormatControl<>`
----------------
-This class template traverses a `FORMAT` statement's contents (or `FMT=`
-character value) to extract data edit descriptors like `E20.14` to
-serve each item in an I/O data transfer statement's *io-list*,
-making callbacks to an instance of its class template argument
-along the way to effect character literal output and record
-positioning.
-The Fortran language standard defines formatted I/O as if the `FORMAT`
-string were driving the traversal of the data items in the *io-list*,
-but our implementation reverses that perspective to allow a more
-convenient (for the compiler) I/O runtime support library API design
-in which each data item is presented to the library with a distinct
-type-dependent call.
-
-Clients of `FormatControl` instantiations call its `GetNextDataEdit()`
-member function to acquire the next data edit descriptor to be processed
-from the format, and `FinishOutput()` to flush out any remaining
-output strings or record positionings at the end of the *io-list*.
-
-The `DefaultFormatControlCallbacks` structure summarizes the API
-expected by `FormatControl` from its class template actual arguments.
-
-`OpenFile`
---------
-This class encapsulates all (I hope) the operating system interfaces
-used to interact with the host's filesystems for operations on
-external units.
-Asynchronous I/O interfaces are faked for now with synchronous
-operations and deferred results.
-
-`ConnectionState`
----------------
-An active connection to an external or internal unit maintains
-the common parts of its state in this subclass of `ConnectionAttributes`.
-The base class holds state that should not change during the
-lifetime of the connection, while the subclass maintains state
-that may change during I/O statement execution.
-
-`InternalDescriptorUnit`
-----------------------
-When I/O is being performed from/to a Fortran `CHARACTER` array
-rather than an external file, this class manages the standard
-interoperable descriptor used to access its elements as records.
-It has the necessary interfaces to serve as an actual argument
-to the `FormatControl` class template.
-
-`FileFrame<>`
------------
-This CRTP class template isolates all of the complexity involved between
-an external unit's `OpenFile` and the buffering requirements
-imposed by the capabilities of Fortran `FORMAT` control edit
-descriptors that allow repositioning within the current record.
-Its interface enables its clients to define a "frame" (my term,
-not Fortran's) that is a contiguous range of bytes that are
-or may soon be in the file.
-This frame is defined as a file offset and a byte size.
-The `FileFrame` instance manages an internal circular buffer
-with two essential guarantees:
-
-1. The most recently requested frame is present in the buffer
-and contiguous in memory.
-1. Any extra data after the frame that may have been read from
-the external unit will be preserved, so that it's safe to
-read from a socket, pipe, or tape and not have to worry about
-repositioning and rereading.
-
-In end-of-file situations, it's possible that a request to read
-a frame may come up short.
-
-As a CRTP class template, `FileFrame` accesses the raw filesystem
-facilities it needs from `*this`.
-
-`ExternalFileUnit`
-----------------
-This class mixes in `ConnectionState`, `OpenFile`, and
-`FileFrame<ExternalFileUnit>` to represent the state of an open
-(or soon to be opened) external file descriptor as a Fortran
-I/O unit.
-It has the contextual APIs required to serve as a template actual
-argument to `FormatControl`.
-And it contains a `std::variant<>` suitable for holding the
-state of the active I/O statement in progress on the unit
-(see below).
-
-`ExternalFileUnit` instances reside in a `Map` that is allocated
-as a static variable and indexed by Fortran unit number.
-Static member functions `LookUp()`, `LookUpOrCrash()`, and `LookUpOrCreate()`
-probe the map to convert Fortran `UNIT=` numbers from I/O statements
-into references to active units.
-
-`IoStatementBase`
----------------
-The subclasses of `IoStatementBase` each encapsulate and maintain
-the state of one active Fortran I/O statement across the several
-I/O runtime library API function calls it may comprise.
-The subclasses handle the distinctions between internal vs. external I/O,
-formatted vs. list-directed vs. unformatted I/O, input vs. output,
-and so on.
-
-`IoStatementBase` inherits default `FORMAT` processing callbacks and
-an `IoErrorHandler`.
-Each of the `IoStatementBase` classes that pertain to formatted I/O
-support the contextual callback interfaces needed by `FormatControl`,
-overriding the default callbacks of the base class, which crash if
-called inappropriately (e.g., if a `CLOSE` statement somehow
-passes a data item from an *io-list*).
-
-The lifetimes of these subclasses' instances each begin with a user
-program call to an I/O API routine with a name like `BeginExternalListOutput()`
-and persist until `EndIoStatement()` is called.
-
-To reduce dynamic memory allocation, *external* I/O statements allocate
-their per-statement state class instances in space reserved in the
-`ExternalFileUnit` instance.
-Internal I/O statements currently use dynamic allocation, but
-the I/O API supports a means whereby the code generated for the Fortran
-program may supply stack space to the I/O runtime support library
-for this purpose.
-
-`IoStatementState`
-----------------
-F18's Fortran I/O runtime support library defines and implements an API
-that uses a sequence of function calls to implement each Fortran I/O
-statement.
-The state of each I/O statement in progress is maintained in some
-subclass of `IoStatementBase`, as noted above.
-The purpose of `IoStatementState` is to provide generic access
-to the specific state classes without recourse to C++ `virtual`
-functions or function pointers, language features that may not be
-available to us in some important execution environments.
-`IoStatementState` comprises a `std::variant<>` of wrapped references
-to the various possibilities, and uses `std::visit()` to
-access them as needed by the I/O API calls that process each specifier
-in the I/O *control-list* and each item in the *io-list*.
-
-Pointers to `IoStatementState` instances are the `Cookie` type returned
-in the I/O API for `Begin...` I/O statement calls, passed back for
-the *control-list* specifiers and *io-list* data items, and consumed
-by the `EndIoStatement()` call at the end of the statement.
-
-Storage for `IoStatementState` is reserved in `ExternalFileUnit` for
-external I/O units, and in the various final subclasses for internal
-I/O statement states otherwise.
-
-Since Fortran permits a `CLOSE` statement to reference a nonexistent
-unit, the library has to treat that (expected to be rare) situation
-as a weird variation of internal I/O since there's no `ExternalFileUnit`
-available to hold its `IoStatementBase` subclass or `IoStatementState`.
-
-A Narrative Overview Of `PRINT *, 'HELLO, WORLD'`
-=================================================
-1. When the compiled Fortran program begins execution at the `main()`
-entry point exported from its main program, it calls `ProgramStart()`
-with its arguments and environment.
-1. The generated code calls `BeginExternalListOutput()` to
-start the sequence of calls that implement the `PRINT` statement.
-Since the Fortran runtime I/O library has not yet been used in
-this process, its data structures are initialized on this
-first call, and Fortran I/O units 5 and 6 are connected with
-the stadard input and output file descriptors (respectively).
-The default unit code is converted to 6 and passed to
-`ExternalFileUnit::LookUpOrCrash()`, which returns a reference to
-unit 6's instance.
-1. We check that the unit was opened for formatted I/O.
-1. `ExternalFileUnit::BeginIoStatement<>()` is called to initialize
-an instance of `ExternalListIoStatementState<false>` in the unit,
-point to it with an `IoStatementState`, and return a reference to
-that object whose address will be the `Cookie` for this statement.
-1. The generated code calls `OutputAscii()` with that cookie and the
-address and length of the string.
-1. `OutputAscii()` confirms that the cookie corresponds to an output
-statement and determines that it's list-directed.
-1. `ListDirectedStatementState<false>::EmitLeadingSpaceOrAdvance()`
-emits the required initial space on the new current output record
-by calling `IoStatementState::GetConnectionState()` to locate
-the connection state, determining from the record position state
-that the space is necessary, and calling `IoStatementState::Emit()`
-to cough it out.  That call is redirected to `ExternalFileUnit::Emit()`,
-which calls `FileFrame<ExternalFileUnit>::WriteFrame()` to extend
-the frame of the current record and then `memcpy()` to fill its
-first byte with the space.
-1. Back in `OutputAscii()`, the mutable modes and connection state
-of the `IoStatementState` are queried to see whether we're in an
-`WRITE(UNIT=,FMT=,DELIM=)` statement with a delimited specifier.
-If we were, the library would emit the appropriate quote marks,
-double up any instances of that character in the text, and split the
-text over multiple records if it's long.
-1. But we don't have a delimiter, so `OutputAscii()` just carves
-up the text into record-sized chunks and emits them.  There's just
-one chunk for our short `CHARACTER` string value in this example.
-It's passed to `IoStatementState::Emit()`, which (as above) is
-redirected to `ExternalFileUnit::Emit()`, which interacts with the
-frame to extend the frame and `memcpy` data into the buffer.
-1. A flag is set in `ListDirectedStatementState<false>` to remember
-that the last item emitted in this list-directed output statement
-was an undelimited `CHARACTER` value, so that if the next item is
-also an undelimited `CHARACTER`, no interposing space will be emitted
-between them.
-1. `OutputAscii()` return `true` to its caller.
-1. The generated code calls `EndIoStatement()`, which is redirected to
-`ExternalIoStatementState<false>`'s override of that function.
-As this is not a non-advancing I/O statement, `ExternalFileUnit::AdvanceRecord()`
-is called to end the record.  Since this is a sequential formatted
-file, a newline is emitted.
-1. If unit 6 is connected to a terminal, the buffer is flushed.
-`FileFrame<ExternalFileUnit>::Flush()` drives `ExternalFileUnit::Write()`
-to push out the data in maximal contiguous chunks, dealing with any
-short writes that might occur, and collecting I/O errors along the way.
-This statement has no `ERR=` label or `IOSTAT=` specifier, so errors
-arriving at `IoErrorHandler::SignalErrno()` will cause an immediate
-crash.
-1. `ExternalIoStatementBase::EndIoStatement()` is called.
-It gets the final `IOSTAT=` value from `IoStatementBase::EndIoStatement()`,
-tells the `ExternalFileUnit` that no I/O statement remains active, and
-returns the I/O status value back to the program.
-1. Eventually, the program calls `ProgramEndStatement()`, which
-calls `ExternalFileUnit::CloseAll()`, which flushes and closes all
-open files.  If the standard output were not a terminal, the output
-would be written now with the same sequence of calls as above.
-1. `exit(EXIT_SUCCESS)`.

flang/documentation/ImplementingASemanticCheck.md

-<!--===- documentation/ImplementingASemanticCheck.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
-  
--->
-# Introduction
-I recently added a semantic check to the f18 compiler front end.  This document
-describes my thought process and the resulting implementation.
-
-For more information about the compiler, start with the 
-[compiler overview](Overview.md).
-
-# Problem definition
-
-In the 2018 Fortran standard, section 11.1.7.4.3, paragraph 2, states that:
-
-```
-Except for the incrementation of the DO variable that occurs in step (3), the DO variable 
-shall neither be redefined nor become undefined while the DO construct is active.
-```
-One of the ways that DO variables might be redefined is if they are passed to
-functions with dummy arguments whose `INTENT` is `INTENT(OUT)` or
-`INTENT(INOUT)`.  I implemented this semantic check.  Specifically, I changed
-the compiler to emit an error message if an active DO variable was passed to a
-dummy argument of a FUNCTION with INTENT(OUT).  Similarly, I had the compiler
-emit a warning if an active DO variable was passed to a dummy argument with
-INTENT(INOUT).  Previously, I had implemented similar checks for SUBROUTINE
-calls.
-
-# Creating a test
-
-My first step was to create a test case to cause the problem.  I called it testfun.f90 and used it to check the behavior of other Fortran compilers.  Here's the initial version:
-
-```fortran
-  subroutine s()
-    Integer :: ivar, jvar
-
-    do ivar = 1, 10
-      jvar = intentOutFunc(ivar) ! Error since ivar is a DO variable
-    end do
-
-  contains
-    function intentOutFunc(dummyArg)
-      integer, intent(out) :: dummyArg
-      integer  :: intentOutFunc
-
-      dummyArg = 216
-    end function intentOutFunc
-  end subroutine s
-```
-
-I verified that other Fortran compilers produced an error message at the point
-of the call to `intentOutFunc()`:
-
-```fortran
-      jvar = intentOutFunc(ivar) ! Error since ivar is a DO variable
-```
-
-
-I also used this program to produce a parse tree for the program using the command:
-```bash
-  f18 -fdebug-dump-parse-tree -fparse-only testfun.f90
-```
-
-Here's the relevant fragment of the parse tree produced by the compiler:
-
-```
-| | ExecutionPartConstruct -> ExecutableConstruct -> DoConstruct
-| | | NonLabelDoStmt
-| | | | LoopControl -> LoopBounds
-| | | | | Scalar -> Name = 'ivar'
-| | | | | Scalar -> Expr = '1_4'
-| | | | | | LiteralConstant -> IntLiteralConstant = '1'
-| | | | | Scalar -> Expr = '10_4'
-| | | | | | LiteralConstant -> IntLiteralConstant = '10'
-| | | Block
-| | | | ExecutionPartConstruct -> ExecutableConstruct -> ActionStmt -> AssignmentStmt = 'jvar=intentoutfunc(ivar)'
-| | | | | Variable -> Designator -> DataRef -> Name = 'jvar'
-| | | | | Expr = 'intentoutfunc(ivar)'
-| | | | | | FunctionReference -> Call
-| | | | | | | ProcedureDesignator -> Name = 'intentoutfunc'
-| | | | | | | ActualArgSpec
-| | | | | | | | ActualArg -> Expr = 'ivar'
-| | | | | | | | | Designator -> DataRef -> Name = 'ivar'
-| | | EndDoStmt -> 
-```
-
-Note that this fragment of the tree only shows four `parser::Expr` nodes,
-but the full parse tree also contained a fifth `parser::Expr` node for the
-constant 216 in the statement:
-
-```fortran
-      dummyArg = 216
-```
-# Analysis and implementation planning
-
-I then considered what I needed to do.  I needed to detect situations where an
-active DO variable was passed to a dummy argument with `INTENT(OUT)` or
-`INTENT(INOUT)`.  Once I detected such a situation, I needed to produce a
-message that highlighted the erroneous source code.  
-
-## Deciding where to add the code to the compiler
-This new semantic check would depend on several types of information -- the
-parse tree, source code location information, symbols, and expressions.  Thus I
-needed to put my new code in a place in the compiler after the parse tree had
-been created, name resolution had already happened, and expression semantic
-checking had already taken place.
-
-Most semantic checks for statements are implemented by walking the parse tree
-and performing analysis on the nodes they visit.  My plan was to use this
-method.  The infrastructure for walking the parse tree for statement semantic
-checking is implemented in the files `lib/Semantics/semantics.cpp`.
-Here's a fragment of the declaration of the framework's parse tree visitor from
-`lib/Semantics/semantics.cpp`:
-
-```C++
-  // A parse tree visitor that calls Enter/Leave functions from each checker
-  // class C supplied as template parameters. Enter is called before the node's
-  // children are visited, Leave is called after. No two checkers may have the
-  // same Enter or Leave function. Each checker must be constructible from
-  // SemanticsContext and have BaseChecker as a virtual base class.
-  template<typename... C> class SemanticsVisitor : public virtual C... {
-  public:
-    using C::Enter...;
-    using C::Leave...;
-    using BaseChecker::Enter;
-    using BaseChecker::Leave;
-    SemanticsVisitor(SemanticsContext &context)
-      : C{context}..., context_{context} {}
-      ...
-
-```
-
-Since FUNCTION calls are a kind of expression, I was planning to base my
-implementation on the contents of `parser::Expr` nodes.  I would need to define
-either an `Enter()` or `Leave()` function whose parameter was a `parser::Expr`
-node.  Here's the declaration I put into `lib/Semantics/check-do.h`:
-
-```C++
-  void Leave(const parser::Expr &);
-```
-The `Enter()` functions get called at the time the node is first visited --
-that is, before its children.  The `Leave()` function gets called after the
-children are visited.  For my check the visitation order didn't matter, so I
-arbitrarily chose to implement the `Leave()` function to visit the parse tree
-node.
-
-Since my semantic check was focused on DO CONCURRENT statements, I added it to
-the file `lib/Semantics/check-do.cpp` where most of the semantic checking for
-DO statements already lived.
-
-## Taking advantage of prior work
-When implementing a similar check for SUBROUTINE calls, I created a utility
-functions in `lib/Semantics/semantics.cpp` to emit messages if
-a symbol corresponding to an active DO variable was being potentially modified:
-
-```C++
-  void WarnDoVarRedefine(const parser::CharBlock &location, const Symbol &var);
-  void CheckDoVarRedefine(const parser::CharBlock &location, const Symbol &var);
-```
-
-The first function is intended for dummy arguments of `INTENT(INOUT)` and
-the second for `INTENT(OUT)`.
-
-Thus I needed three pieces of
-information -- 
-1. the source location of the erroneous text, 
-2. the `INTENT` of the associated dummy argument, and
-3. the relevant symbol passed as the actual argument.
-
-The first and third are needed since they're required to call the utility
-functions.  The second is needed to determine whether to call them.
-
-## Finding the source location
-The source code location information that I'd need for the error message must
-come from the parse tree.  I looked in the file
-`include/flang/Parser/parse-tree.h` and determined that a `struct Expr`
-contained source location information since it had the field `CharBlock
-source`.  Thus, if I visited a `parser::Expr` node, I could get the source
-location information for the associated expression.
-
-## Determining the `INTENT`
-I knew that I could find the `INTENT` of the dummy argument associated with the
-actual argument from the function called `dummyIntent()` in the class
-`evaluate::ActualArgument` in the file `include/flang/Evaluate/call.h`.  So
-if I could find an `evaluate::ActualArgument` in an expression, I could
-  determine the `INTENT` of the associated dummy argument.  I knew that it was
-  valid to call `dummyIntent()` because the data on which `dummyIntent()`
-  depends is established during semantic processing for expressions, and the
-  semantic processing for expressions happens before semantic checking for DO
-  constructs.
-
-In my prior work on checking the INTENT of arguments for SUBROUTINE calls,
-the parse tree held a node for the call (a `parser::CallStmt`) that contained
-an `evaluate::ProcedureRef` node.
-```C++
-  struct CallStmt {
-    WRAPPER_CLASS_BOILERPLATE(CallStmt, Call);
-    mutable std::unique_ptr<evaluate::ProcedureRef,
-        common::Deleter<evaluate::ProcedureRef>>
-        typedCall;  // filled by semantics
-  };
-```
-The `evaluate::ProcedureRef` contains a list of `evaluate::ActualArgument`
-nodes.  I could then find the INTENT of a dummy argument from the
-`evaluate::ActualArgument` node.
-
-For a FUNCTION call, though, there is no similar way to get from a parse tree
-node to an `evaluate::ProcedureRef` node.  But I knew that there was an
-existing framework used in DO construct semantic checking that traversed an
-`evaluate::Expr` node collecting `semantics::Symbol` nodes.  I guessed that I'd
-be able to use a similar framework to traverse an `evaluate::Expr`  node to
-find all of the `evaluate::ActualArgument` nodes.  
-
-Note that the compiler has multiple types called `Expr`.  One is in the
-`parser` namespace.  `parser::Expr` is defined in the file
-`include/flang/Parser/parse-tree.h`.  It represents a parsed expression that
-maps directly to the source code and has fields that specify any operators in
-the expression, the operands, and the source position of the expression.
-
-Additionally, in the namespace `evaluate`, there are `evaluate::Expr<T>`
-template classes defined in the file `include/flang/Evaluate/expression.h`.
-These are parameterized over the various types of Fortran and constitute a
-suite of strongly-typed representations of valid Fortran expressions of type
-`T` that have been fully elaborated with conversion operations and subjected to
-constant folding.  After an expression has undergone semantic analysis, the
-field `typedExpr` in the `parser::Expr` node is filled in with a pointer that
-owns an instance of `evaluate::Expr<SomeType>`, the most general representation
-of an analyzed expression.
-
-All of the declarations associated with both FUNCTION and SUBROUTINE calls are
-in `include/flang/Evaluate/call.h`.  An `evaluate::FunctionRef` inherits from
-an `evaluate::ProcedureRef` which contains the list of
-`evaluate::ActualArgument` nodes.  But the relationship between an
-`evaluate::FunctionRef` node and its associated arguments is not relevant.  I
-only needed to find the `evaluate::ActualArgument` nodes in an expression.
-They hold all of the information I needed.
-
-So my plan was to start with the `parser::Expr` node and extract its
-associated `evaluate::Expr` field.  I would then traverse the
-`evaluate::Expr` tree collecting all of the `evaluate::ActualArgument`
-nodes.  I would look at each of these nodes to determine the `INTENT` of
-the associated dummy argument.
-
-This combination of the traversal framework and `dummyIntent()` would give
-me the `INTENT` of all of the dummy arguments in a FUNCTION call.  Thus, I
-would have the second piece of information I needed.
-
-## Determining if the actual argument is a variable
-I also guessed that I could determine if the `evaluate::ActualArgument`
-consisted of a variable.  
-
-Once I had a symbol for the variable, I could call one of the functions:
-```C++
-  void WarnDoVarRedefine(const parser::CharBlock &, const Symbol &);
-  void CheckDoVarRedefine(const parser::CharBlock &, const Symbol &);
-```
-to emit the messages.
-
-If my plans worked out, this would give me the three pieces of information I
-needed -- the source location of the erroneous text, the `INTENT` of the dummy
-argument, and a symbol that I could use to determine whether the actual
-argument was an active DO variable.
-
-# Implementation
-
-## Adding a parse tree visitor
-I started my implementation by adding a visitor for `parser::Expr` nodes.
-Since this analysis is part of DO construct checking, I did this in
-`lib/Semantics/check-do.cpp`.  I added a print statement to the visitor to
-verify that my new code was actually getting executed.  
-
-In `lib/Semantics/check-do.h`, I added the declaration for the visitor:
-
-```C++
-  void Leave(const parser::Expr &);
-```
-
-In `lib/Semantics/check-do.cpp`, I added an (almost empty) implementation:
-
-```C++
-  void DoChecker::Leave(const parser::Expr &) {
-    std::cout << "In Leave for parser::Expr\n";
-  }
-```
-
-I then built the compiler with these changes and ran it on my test program.
-This time, I made sure to invoke semantic checking.  Here's the command I used:
-```bash
-  f18 -fdebug-resolve-names -fdebug-dump-parse-tree -funparse-with-symbols testfun.f90
-```
-
-This produced the output:
-
-```
-  In Leave for parser::Expr
-  In Leave for parser::Expr
-  In Leave for parser::Expr
-  In Leave for parser::Expr
-  In Leave for parser::Expr
-```
-
-This made sense since the parse tree contained five `parser::Expr` nodes.
-So far, so good.  Note that a `parse::Expr` node has a field with the
-source position of the associated expression (`CharBlock source`).  So I
-now had one of the three pieces of information needed to detect and report
-errors.
-
-## Collecting the actual arguments
-To get the `INTENT` of the dummy arguments and the `semantics::Symbol` associated with the
-actual argument, I needed to find all of the actual arguments embedded in an
-expression that contained a FUNCTION call.  So my next step was to write the
-framework to walk the `evaluate::Expr` to gather all of the
-`evaluate::ActualArgument` nodes.  The code that I planned to model it on
-was the existing infrastructure that collected all of the `semantics::Symbol` nodes from an
-`evaluate::Expr`.  I found this implementation in
-`lib/Evaluate/tools.cpp`:
-
-```C++
-  struct CollectSymbolsHelper
-    : public SetTraverse<CollectSymbolsHelper, semantics::SymbolSet> {
-    using Base = SetTraverse<CollectSymbolsHelper, semantics::SymbolSet>;
-    CollectSymbolsHelper() : Base{*this} {}
-    using Base::operator();
-    semantics::SymbolSet operator()(const Symbol &symbol) const {
-      return {symbol};
-    }
-  };
-  template<typename A> semantics::SymbolSet CollectSymbols(const A &x) {
-    return CollectSymbolsHelper{}(x);
-  }
-```
-
-Note that the `CollectSymbols()` function returns a `semantics::Symbolset`,
-which is declared in `include/flang/Semantics/symbol.h`:
-
-```C++
-  using SymbolSet = std::set<SymbolRef>;
-```
-
-This infrastructure yields a collection based on `std::set<>`.  Using an
-`std::set<>` means that if the same object is inserted twice, the
-collection only gets one copy.  This was the behavior that I wanted.
-
-Here's a sample invocation of `CollectSymbols()` that I found:
-```C++
-    if (const auto *expr{GetExpr(parsedExpr)}) {
-      for (const Symbol &symbol : evaluate::CollectSymbols(*expr)) {
-```
-
-I noted that a `SymbolSet` did not actually contain an
-`std::set<Symbol>`.  This wasn't surprising since we don't want to put the
-full `semantics::Symbol` objects into the set.  Ideally, we would be able to create an
-`std::set<Symbol &>` (a set of C++ references to symbols).  But C++ doesn't
-support sets that contain references.  This limitation is part of the rationale
-for the f18 implementation of type `common::Reference`, which is defined in
-  `include/flang/Common/reference.h`.
-
-`SymbolRef`, the specialization of the template `common::Reference` for
-`semantics::Symbol`, is declared in the file
-`include/flang/Semantics/symbol.h`:
-
-```C++
-  using SymbolRef = common::Reference<const Symbol>;
-```
-
-So to implement something that would collect `evaluate::ActualArgument`
-nodes from an `evaluate::Expr`, I first defined the required types
-`ActualArgumentRef` and `ActualArgumentSet`.  Since these are being
-used exclusively for DO construct semantic checking (currently), I put their
-definitions into `lib/Semantics/check-do.cpp`:
-
-
-```C++
-  namespace Fortran::evaluate {
-    using ActualArgumentRef = common::Reference<const ActualArgument>;
-  }
-
-
-  using ActualArgumentSet = std::set<evaluate::ActualArgumentRef>;
-```
-
-Since `ActualArgument` is in the namespace `evaluate`, I put the
-definition for `ActualArgumentRef` in that namespace, too.
-
-I then modeled the code to create an `ActualArgumentSet` after the code to
-collect a `SymbolSet` and put it into `lib/Semantics/check-do.cpp`:
-
-
-```C++
-  struct CollectActualArgumentsHelper
-    : public evaluate::SetTraverse<CollectActualArgumentsHelper,
-          ActualArgumentSet> {
-    using Base = SetTraverse<CollectActualArgumentsHelper, ActualArgumentSet>;
-    CollectActualArgumentsHelper() : Base{*this} {}
-    using Base::operator();
-    ActualArgumentSet operator()(const evaluate::ActualArgument &arg) const {
-      return ActualArgumentSet{arg};
-    }
-  };
-
-  template<typename A> ActualArgumentSet CollectActualArguments(const A &x) {
-    return CollectActualArgumentsHelper{}(x);
-  }
-
-  template ActualArgumentSet CollectActualArguments(const SomeExpr &);
-```
-
-Unfortunately, when I tried to build this code, I got an error message saying
-`std::set` requires the `<` operator to be defined for its contents.
-To fix this, I added a definition for `<`.  I didn't care how `<` was
-defined, so I just used the address of the object:
-
-```C++
-  inline bool operator<(ActualArgumentRef x, ActualArgumentRef y) {
-    return &*x < &*y;
-  }
-```
-
-I was surprised when this did not make the error message saying that I needed
-the `<` operator go away.  Eventually, I figured out that the definition of
-the `<` operator needed to be in the `evaluate` namespace.  Once I put
-it there, everything compiled successfully.  Here's the code that worked:
-
-```C++
-  namespace Fortran::evaluate {
-  using ActualArgumentRef = common::Reference<const ActualArgument>;
-
-  inline bool operator<(ActualArgumentRef x, ActualArgumentRef y) {
-    return &*x < &*y;
-  }
-  }
-```
-
-I then modified my visitor for the parser::Expr to invoke my new collection
-framework.  To verify that it was actually doing something, I printed out the
-number of `evaluate::ActualArgument` nodes that it collected.  Note the
-call to `GetExpr()` in the invocation of `CollectActualArguments()`.  I
-modeled this on similar code that collected a `SymbolSet` described above:
-
-```C++
-  void DoChecker::Leave(const parser::Expr &parsedExpr) {
-    std::cout << "In Leave for parser::Expr\n";
-    ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
-    std::cout << "Number of arguments: " << argSet.size() << "\n";
-  }
-```
-
-I compiled and tested this code on my little test program.  Here's the output that I got:
-```
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 1
-  In Leave for parser::Expr
-  Number of arguments: 0
-```
-
-So most of the `parser::Expr`nodes contained no actual arguments, but the
-fourth expression in the parse tree walk contained a single argument.  This may
-seem wrong since the third `parser::Expr` node in the file contains the
-`FunctionReference` node along with the arguments that we're gathering.
-But since the tree walk function is being called upon leaving a
-`parser::Expr` node, the function visits the `parser::Expr` node
-associated with the `parser::ActualArg` node before it visits the
-`parser::Expr` node associated with the `parser::FunctionReference`
-node.
-
-So far, so good.
-
-## Finding the `INTENT` of the dummy argument
-I now wanted to find the `INTENT` of the dummy argument associated with the
-arguments in the set.  As mentioned earlier, the type
-`evaluate::ActualArgument` has a member function called `dummyIntent()`
-that gives this value.  So I augmented my code to print out the `INTENT`:
-
-```C++
-  void DoChecker::Leave(const parser::Expr &parsedExpr) {
-    std::cout << "In Leave for parser::Expr\n";
-    ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
-    std::cout << "Number of arguments: " << argSet.size() << "\n";
-    for (const evaluate::ActualArgumentRef &argRef : argSet) {
-      common::Intent intent{argRef->dummyIntent()};
-      switch (intent) {
-        case common::Intent::In: std::cout << "INTENT(IN)\n"; break;
-        case common::Intent::Out: std::cout << "INTENT(OUT)\n"; break;
-        case common::Intent::InOut: std::cout << "INTENT(INOUT)\n"; break;
-        default: std::cout << "default INTENT\n";
-      }
-    }
-  }
-```
-
-I then rebuilt my compiler and ran it on my test case.  This produced the following output:
-
-```
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 1
-  INTENT(OUT)
-  In Leave for parser::Expr
-  Number of arguments: 0
-```
-
-I then modified my test case to convince myself that I was getting the correct
-`INTENT` for `IN`, `INOUT`, and default cases.
-
-So far, so good.
-
-## Finding the symbols for arguments that are variables
-The third and last piece of information I needed was to determine if a variable
-was being passed as an actual argument.  In such cases, I wanted to get the
-symbol table node (`semantics::Symbol`) for the variable.  My starting point was the
-`evaluate::ActualArgument` node.  
-
-I was unsure of how to do this, so I browsed through existing code to look for
-how it treated `evaluate::ActualArgument` objects.  Since most of the code that deals with the `evaluate` namespace is in the lib/Evaluate directory, I looked there.  I ran `grep` on all of the `.cpp` files looking for
-uses of `ActualArgument`.  One of the first hits I got was in `lib/Evaluate/call.cpp` in the definition of `ActualArgument::GetType()`:
-
-```C++
-std::optional<DynamicType> ActualArgument::GetType() const {
-  if (const Expr<SomeType> *expr{UnwrapExpr()}) {
-    return expr->GetType();
-  } else if (std::holds_alternative<AssumedType>(u_)) {
-    return DynamicType::AssumedType();
-  } else {
-    return std::nullopt;
-  }
-}
-```
-
-I noted the call to `UnwrapExpr()` that yielded a value of
-`Expr<SomeType>`.  So I guessed that I could use this member function to
-get an `evaluate::Expr<SomeType>` on which I could perform further analysis.
-
-I also knew that the header file `include/flang/Evaluate/tools.h` held many
-utility functions for dealing with `evaluate::Expr` objects.  I was hoping to
-find something that would determine if an `evaluate::Expr` was a variable.  So
-I searched for `IsVariable` and got a hit immediately.  
-```C++
-  template<typename A> bool IsVariable(const A &x) {
-    if (auto known{IsVariableHelper{}(x)}) {
-      return *known;
-    } else {
-      return false;
-    }
-  }
-```
-
-But I actually needed more than just the knowledge that an `evaluate::Expr` was
-a variable.  I needed the `semantics::Symbol` associated with the variable.  So
-I searched in `include/flang/Evaluate/tools.h` for functions that returned a
-`semantics::Symbol`.  I found the following:
-
-```C++
-// If an expression is simply a whole symbol data designator,
-// extract and return that symbol, else null.
-template<typename A> const Symbol *UnwrapWholeSymbolDataRef(const A &x) {
-  if (auto dataRef{ExtractDataRef(x)}) {
-    if (const SymbolRef * p{std::get_if<SymbolRef>(&dataRef->u)}) {
-      return &p->get();
-    }
-  }
-  return nullptr;
-}
-```
-
-This was exactly what I wanted.  DO variables must be whole symbols.  So I
-could try to extract a whole `semantics::Symbol` from the `evaluate::Expr` in my
-`evaluate::ActualArgument`.  If this extraction resulted in a `semantics::Symbol`
-that wasn't a `nullptr`, I could then conclude if it was a variable that I
-could pass to existing functions that would determine if it was an active DO
-variable.
-
-I then modified the compiler to perform the analysis that I'd guessed would
-work:
-
-```C++
-  void DoChecker::Leave(const parser::Expr &parsedExpr) {
-    std::cout << "In Leave for parser::Expr\n";
-    ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
-    std::cout << "Number of arguments: " << argSet.size() << "\n";
-    for (const evaluate::ActualArgumentRef &argRef : argSet) {
-      if (const SomeExpr * argExpr{argRef->UnwrapExpr()}) {
-        std::cout << "Got an unwrapped Expr\n";
-        if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
-          std::cout << "Found a whole variable: " << *var << "\n";
-        }
-      }
-      common::Intent intent{argRef->dummyIntent()};
-      switch (intent) {
-        case common::Intent::In: std::cout << "INTENT(IN)\n"; break;
-        case common::Intent::Out: std::cout << "INTENT(OUT)\n"; break;
-        case common::Intent::InOut: std::cout << "INTENT(INOUT)\n"; break;
-        default: std::cout << "default INTENT\n";
-      }
-    }
-  }
-```  
-
-Note the line that prints out the symbol table entry for the variable:
-
-```C++
-          std::cout << "Found a whole variable: " << *var << "\n";
-```  
-
-The compiler defines the "<<" operator for `semantics::Symbol`, which is handy
-for analyzing the compiler's behavior.
-
-Here's the result of running the modified compiler on my Fortran test case:
-
-```
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 1
-  Got an unwrapped Expr
-  Found a whole variable: ivar: ObjectEntity type: INTEGER(4)
-  INTENT(OUT)
-  In Leave for parser::Expr
-  Number of arguments: 0
-```
-
-Sweet.
-
-## Emitting the messages
-At this point, using the source location information from the original
-`parser::Expr`, I had enough information to plug into the exiting
-interfaces for emitting messages for active DO variables.  I modified the
-compiler code accordingly:
-
-
-```C++
-  void DoChecker::Leave(const parser::Expr &parsedExpr) {
-    std::cout << "In Leave for parser::Expr\n";
-    ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
-    std::cout << "Number of arguments: " << argSet.size() << "\n";
-    for (const evaluate::ActualArgumentRef &argRef : argSet) {
-      if (const SomeExpr * argExpr{argRef->UnwrapExpr()}) {
-        std::cout << "Got an unwrapped Expr\n";
-        if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
-          std::cout << "Found a whole variable: " << *var << "\n";
-          common::Intent intent{argRef->dummyIntent()};
-          switch (intent) {
-            case common::Intent::In: std::cout << "INTENT(IN)\n"; break;
-            case common::Intent::Out: 
-              std::cout << "INTENT(OUT)\n"; 
-              context_.CheckDoVarRedefine(parsedExpr.source, *var);
-              break;
-            case common::Intent::InOut: 
-              std::cout << "INTENT(INOUT)\n"; 
-              context_.WarnDoVarRedefine(parsedExpr.source, *var);
-              break;
-            default: std::cout << "default INTENT\n";
-          }
-        }
-      }
-    }
-  }
-```  
-
-I then ran this code on my test case, and miraculously, got the following
-output:
-
-```
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 0
-  In Leave for parser::Expr
-  Number of arguments: 1
-  Got an unwrapped Expr
-  Found a whole variable: ivar: ObjectEntity type: INTEGER(4)
-  INTENT(OUT)
-  In Leave for parser::Expr
-  Number of arguments: 0
-  testfun.f90:6:12: error: Cannot redefine DO variable 'ivar'
-        jvar = intentOutFunc(ivar)
-               ^^^^^^^^^^^^^^^^^^^
-  testfun.f90:5:6: Enclosing DO construct
-      do ivar = 1, 10
-         ^^^^
-```
-
-Even sweeter.
-
-# Improving the test case
-At this point, my implementation seemed to be working.  But I was concerned
-about the limitations of my test case.  So I augmented it to include arguments
-other than `INTENT(OUT)` and more complex expressions.  Luckily, my
-augmented test did not reveal any new problems.   
-
-Here's the test I ended up with:
-
-```Fortran
-  subroutine s()
-
-    Integer :: ivar, jvar
-
-    ! This one is OK
-    do ivar = 1, 10
-      jvar = intentInFunc(ivar)
-    end do
-
-    ! Error for passing a DO variable to an INTENT(OUT) dummy
-    do ivar = 1, 10
-      jvar = intentOutFunc(ivar)
-    end do
-
-    ! Error for passing a DO variable to an INTENT(OUT) dummy, more complex 
-    ! expression
-    do ivar = 1, 10
-      jvar = 83 + intentInFunc(intentOutFunc(ivar))
-    end do
-
-    ! Warning for passing a DO variable to an INTENT(INOUT) dummy
-    do ivar = 1, 10
-      jvar = intentInOutFunc(ivar)
-    end do
-
-  contains
-    function intentInFunc(dummyArg)
-      integer, intent(in) :: dummyArg
-      integer  :: intentInFunc
-
-      intentInFunc = 343
-    end function intentInFunc
-
-    function intentOutFunc(dummyArg)
-      integer, intent(out) :: dummyArg
-      integer  :: intentOutFunc
-
-      dummyArg = 216
-      intentOutFunc = 343
-    end function intentOutFunc
-
-    function intentInOutFunc(dummyArg)
-      integer, intent(inout) :: dummyArg
-      integer  :: intentInOutFunc
-
-      dummyArg = 216
-      intentInOutFunc = 343
-    end function intentInOutFunc
-
-  end subroutine s
-```
-
-# Submitting the pull request
-At this point, my implementation seemed functionally complete, so I stripped out all of the debug statements, ran `clang-format` on it and reviewed it
-to make sure that the names were clear.  Here's what I ended up with:
-
-```C++
-  void DoChecker::Leave(const parser::Expr &parsedExpr) {
-    ActualArgumentSet argSet{CollectActualArguments(GetExpr(parsedExpr))};
-    for (const evaluate::ActualArgumentRef &argRef : argSet) {
-      if (const SomeExpr * argExpr{argRef->UnwrapExpr()}) {
-        if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
-          common::Intent intent{argRef->dummyIntent()};
-          switch (intent) {
-            case common::Intent::Out: 
-              context_.CheckDoVarRedefine(parsedExpr.source, *var);
-              break;
-            case common::Intent::InOut: 
-              context_.WarnDoVarRedefine(parsedExpr.source, *var);
-              break;
-            default:; // INTENT(IN) or default intent
-          }
-        }
-      }
-    }
-  }
-```
-
-I then created a pull request to get review comments.  
-
-# Responding to pull request comments
-I got feedback suggesting that I use an `if` statement rather than a
-`case` statement.  Another comment reminded me that I should look at the
-code I'd previously writted to do a similar check for SUBROUTINE calls to see
-if there was an opportunity to share code.  This examination resulted in
-  converting my existing code to the following pair of functions:
-
-
-```C++
-  static void CheckIfArgIsDoVar(const evaluate::ActualArgument &arg,
-      const parser::CharBlock location, SemanticsContext &context) {
-    common::Intent intent{arg.dummyIntent()};
-    if (intent == common::Intent::Out || intent == common::Intent::InOut) {
-      if (const SomeExpr * argExpr{arg.UnwrapExpr()}) {
-        if (const Symbol * var{evaluate::UnwrapWholeSymbolDataRef(*argExpr)}) {
-          if (intent == common::Intent::Out) {
-            context.CheckDoVarRedefine(location, *var);
-          } else {
-            context.WarnDoVarRedefine(location, *var);  // INTENT(INOUT)
-          }
-        }
-      }
-    }
-  }
-
-  void DoChecker::Leave(const parser::Expr &parsedExpr) {
-    if (const SomeExpr * expr{GetExpr(parsedExpr)}) {
-      ActualArgumentSet argSet{CollectActualArguments(*expr)};
-      for (const evaluate::ActualArgumentRef &argRef : argSet) {
-        CheckIfArgIsDoVar(*argRef, parsedExpr.source, context_);
-      }
-    }
-  }
-```
-
-The function `CheckIfArgIsDoVar()` was shared with the checks for DO
-variables being passed to SUBROUTINE calls.
-
-At this point, my pull request was approved, and I merged it and deleted the
-associated branch.

flang/documentation/Intrinsics.md

-<!--===- documentation/Intrinsics.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
-  
--->
-
-# A categorization of standard (2018) and extended Fortran intrinsic procedures
-
-This note attempts to group the intrinsic procedures of Fortran into categories
-of functions or subroutines with similar interfaces as an aid to
-comprehension beyond that which might be gained from the standard's
-alphabetical list.
-
-A brief status of intrinsic procedure support in f18 is also given at the end.
-
-Few procedures are actually described here apart from their interfaces; see the
-Fortran 2018 standard (section 16) for the complete story.
-
-Intrinsic modules are not covered here.
-
-## General rules
-
-1. The value of any intrinsic function's `KIND` actual argument, if present,
-   must be a scalar constant integer expression, of any kind, whose value
-   resolves to some supported kind of the function's result type.
-   If optional and absent, the kind of the function's result is
-   either the default kind of that category or to the kind of an argument
-   (e.g., as in `AINT`).
-1. Procedures are summarized with a non-Fortran syntax for brevity.
-   Wherever a function has a short definition, it appears after an
-   equal sign as if it were a statement function.  Any functions referenced
-   in these short summaries are intrinsic.
-1. Unless stated otherwise, an actual argument may have any supported kind
-   of a particular intrinsic type.  Sometimes a pattern variable
-   can appear in a description (e.g., `REAL(k)`) when the kind of an
-   actual argument's type must match the kind of another argument, or
-   determines the kind type parameter of the function result.
-1. When an intrinsic type name appears without a kind (e.g., `REAL`),
-   it refers to the default kind of that type.  Sometimes the word
-   `default` will appear for clarity.
-1. The names of the dummy arguments actually matter because they can
-   be used as keywords for actual arguments.
-1. All standard intrinsic functions are pure, even when not elemental.
-1. Assumed-rank arguments may not appear as actual arguments unless
-   expressly permitted.
-1. When an argument is described with a default value, e.g. `KIND=KIND(0)`,
-   it is an optional argument.  Optional arguments without defaults,
-   e.g. `DIM` on many transformationals, are wrapped in `[]` brackets
-   as in the Fortran standard.  When an intrinsic has optional arguments
-   with and without default values, the arguments with default values
-   may appear within the brackets to preserve the order of arguments
-   (e.g., `COUNT`).
-
-# Elemental intrinsic functions
-
-Pure elemental semantics apply to these functions, to wit: when one or more of
-the actual arguments are arrays, the arguments must be conformable, and
-the result is also an array.
-Scalar arguments are expanded when the arguments are not all scalars.
-
-## Elemental intrinsic functions that may have unrestricted specific procedures
-
-When an elemental intrinsic function is documented here as having an
-_unrestricted specific name_, that name may be passed as an actual
-argument, used as the target of a procedure pointer, appear in
-a generic interface, and be otherwise used as if it were an external
-procedure.
-An `INTRINSIC` statement or attribute may have to be applied to an
-unrestricted specific name to enable such usage.
-
-When a name is being used as a specific procedure for any purpose other
-than that of a called function, the specific instance of the function
-that accepts and returns values of the default kinds of the intrinsic
-types is used.
-A Fortran `INTERFACE` could be written to define each of
-these unrestricted specific intrinsic function names.
-
-Calls to dummy arguments and procedure pointers that correspond to these
-specific names must pass only scalar actual argument values.
-
-No other intrinsic function name can be passed as an actual argument,
-used as a pointer target, appear in a generic interface, or be otherwise
-used except as the name of a called function.
-Some of these _restricted specific intrinsic functions_, e.g. `FLOAT`,
-provide a means for invoking a corresponding generic (`REAL` in the case of `FLOAT`)
-with forced argument and result kinds.
-Others, viz. `CHAR`, `ICHAR`, `INT`, `REAL`, and the lexical comparisons like `LGE`,
-have the same name as their generic functions, and it is not clear what purpose
-is accomplished by the standard by defining them as specific functions.
-
-### Trigonometric elemental intrinsic functions, generic and (mostly) specific
-All of these functions can be used as unrestricted specific names.
-
-```
-ACOS(REAL(k) X) -> REAL(k)
-ASIN(REAL(k) X) -> REAL(k)
-ATAN(REAL(k) X) -> REAL(k)
-ATAN(REAL(k) Y, REAL(k) X) -> REAL(k) = ATAN2(Y, X)
-ATAN2(REAL(k) Y, REAL(k) X) -> REAL(k)
-COS(REAL(k) X) -> REAL(k)
-COSH(REAL(k) X) -> REAL(k)
-SIN(REAL(k) X) -> REAL(k)
-SINH(REAL(k) X) -> REAL(k)
-TAN(REAL(k) X) -> REAL(k)
-TANH(REAL(k) X) -> REAL(k)
-```
-
-These `COMPLEX` versions of some of those functions, and the
-inverse hyperbolic functions, cannot be used as specific names.
-```
-ACOS(COMPLEX(k) X) -> COMPLEX(k)
-ASIN(COMPLEX(k) X) -> COMPLEX(k)
-ATAN(COMPLEX(k) X) -> COMPLEX(k)
-ACOSH(REAL(k) X) -> REAL(k)
-ACOSH(COMPLEX(k) X) -> COMPLEX(k)
-ASINH(REAL(k) X) -> REAL(k)
-ASINH(COMPLEX(k) X) -> COMPLEX(k)
-ATANH(REAL(k) X) -> REAL(k)
-ATANH(COMPLEX(k) X) -> COMPLEX(k)
-COS(COMPLEX(k) X) -> COMPLEX(k)
-COSH(COMPLEX(k) X) -> COMPLEX(k)
-SIN(COMPLEX(k) X) -> COMPLEX(k)
-SINH(COMPLEX(k) X) -> COMPLEX(k)
-TAN(COMPLEX(k) X) -> COMPLEX(k)
-TANH(COMPLEX(k) X) -> COMPLEX(k)
-```
-
-### Non-trigonometric elemental intrinsic functions, generic and specific
-These functions *can* be used as unrestricted specific names.
-```
-ABS(REAL(k) A) -> REAL(k) = SIGN(A, 0.0)
-AIMAG(COMPLEX(k) Z) -> REAL(k) = Z%IM
-AINT(REAL(k) A, KIND=k) -> REAL(KIND)
-ANINT(REAL(k) A, KIND=k) -> REAL(KIND)
-CONJG(COMPLEX(k) Z) -> COMPLEX(k) = CMPLX(Z%RE, -Z%IM)
-DIM(REAL(k) X, REAL(k) Y) -> REAL(k) = X-MIN(X,Y)
-DPROD(default REAL X, default REAL Y) -> DOUBLE PRECISION = DBLE(X)*DBLE(Y)
-EXP(REAL(k) X) -> REAL(k)
-INDEX(CHARACTER(k) STRING, CHARACTER(k) SUBSTRING, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
-LEN(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n
-LOG(REAL(k) X) -> REAL(k)
-LOG10(REAL(k) X) -> REAL(k)
-MOD(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k) = A-P*INT(A/P)
-NINT(REAL(k) A, KIND=KIND(0)) -> INTEGER(KIND)
-SIGN(REAL(k) A, REAL(k) B) -> REAL(k)
-SQRT(REAL(k) X) -> REAL(k) = X ** 0.5
-```
-
-These variants, however *cannot* be used as specific names without recourse to an alias
-from the following section:
-```
-ABS(INTEGER(k) A) -> INTEGER(k) = SIGN(A, 0)
-ABS(COMPLEX(k) A) -> REAL(k) = HYPOT(A%RE, A%IM)
-DIM(INTEGER(k) X, INTEGER(k) Y) -> INTEGER(k) = X-MIN(X,Y)
-EXP(COMPLEX(k) X) -> COMPLEX(k)
-LOG(COMPLEX(k) X) -> COMPLEX(k)
-MOD(REAL(k) A, REAL(k) P) -> REAL(k) = A-P*INT(A/P)
-SIGN(INTEGER(k) A, INTEGER(k) B) -> INTEGER(k)
-SQRT(COMPLEX(k) X) -> COMPLEX(k)
-```
-
-### Unrestricted specific aliases for some elemental intrinsic functions with distinct names
-
-```
-ALOG(REAL X) -> REAL = LOG(X)
-ALOG10(REAL X) -> REAL = LOG10(X)
-AMOD(REAL A, REAL P) -> REAL = MOD(A, P)
-CABS(COMPLEX A) = ABS(A)
-CCOS(COMPLEX X) = COS(X)
-CEXP(COMPLEX A) -> COMPLEX = EXP(A)
-CLOG(COMPLEX X) -> COMPLEX = LOG(X)
-CSIN(COMPLEX X) -> COMPLEX = SIN(X)
-CSQRT(COMPLEX X) -> COMPLEX = SQRT(X)
-CTAN(COMPLEX X) -> COMPLEX = TAN(X)
-DABS(DOUBLE PRECISION A) -> DOUBLE PRECISION = ABS(A)
-DACOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = ACOS(X)
-DASIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ASIN(X)
-DATAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN(X)
-DATAN2(DOUBLE PRECISION Y, DOUBLE PRECISION X) -> DOUBLE PRECISION = ATAN2(Y, X)
-DCOS(DOUBLE PRECISION X) -> DOUBLE PRECISION = COS(X)
-DCOSH(DOUBLE PRECISION X) -> DOUBLE PRECISION = COSH(X)
-DDIM(DOUBLE PRECISION X, DOUBLE PRECISION Y) -> DOUBLE PRECISION = X-MIN(X,Y)
-DEXP(DOUBLE PRECISION X) -> DOUBLE PRECISION = EXP(X)
-DINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = AINT(A)
-DLOG(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG(X)
-DLOG10(DOUBLE PRECISION X) -> DOUBLE PRECISION = LOG10(X)
-DMOD(DOUBLE PRECISION A, DOUBLE PRECISION P) -> DOUBLE PRECISION = MOD(A, P)
-DNINT(DOUBLE PRECISION A) -> DOUBLE PRECISION = ANINT(A)
-DSIGN(DOUBLE PRECISION A, DOUBLE PRECISION B) -> DOUBLE PRECISION = SIGN(A, B)
-DSIN(DOUBLE PRECISION X) -> DOUBLE PRECISION = SIN(X)
-DSINH(DOUBLE PRECISION X) -> DOUBLE PRECISION = SINH(X)
-DSQRT(DOUBLE PRECISION X) -> DOUBLE PRECISION = SQRT(X)
-DTAN(DOUBLE PRECISION X) -> DOUBLE PRECISION = TAN(X)
-DTANH(DOUBLE PRECISION X) -> DOUBLE PRECISION = TANH(X)
-IABS(INTEGER A) -> INTEGER = ABS(A)
-IDIM(INTEGER X, INTEGER Y) -> INTEGER = X-MIN(X,Y)
-IDNINT(DOUBLE PRECISION A) -> INTEGER = NINT(A)
-ISIGN(INTEGER A, INTEGER B) -> INTEGER = SIGN(A, B)
-```
-
-## Generic elemental intrinsic functions without specific names
-
-(No procedures after this point can be passed as actual arguments, used as
-pointer targets, or appear as specific procedures in generic interfaces.)
-
-### Elemental conversions
-
-```
-ACHAR(INTEGER(k) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1)
-CEILING(REAL() A, KIND=KIND(0)) -> INTEGER(KIND)
-CHAR(INTEGER(any) I, KIND=KIND('')) -> CHARACTER(KIND,LEN=1)
-CMPLX(COMPLEX(k) X, KIND=KIND(0.0D0)) -> COMPLEX(KIND)
-CMPLX(INTEGER or REAL or BOZ X, INTEGER or REAL or BOZ Y=0, KIND=KIND((0,0))) -> COMPLEX(KIND)
-DBLE(INTEGER or REAL or COMPLEX or BOZ A) = REAL(A, KIND=KIND(0.0D0))
-EXPONENT(REAL(any) X) -> default INTEGER
-FLOOR(REAL(any) A, KIND=KIND(0)) -> INTEGER(KIND)
-IACHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND)
-ICHAR(CHARACTER(KIND=k,LEN=1) C, KIND=KIND(0)) -> INTEGER(KIND)
-INT(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0)) -> INTEGER(KIND)
-LOGICAL(LOGICAL(any) L, KIND=KIND(.TRUE.)) -> LOGICAL(KIND)
-REAL(INTEGER or REAL or COMPLEX or BOZ A, KIND=KIND(0.0)) -> REAL(KIND)
-```
-
-### Other generic elemental intrinsic functions without specific names
-N.B. `BESSEL_JN(N1, N2, X)` and `BESSEL_YN(N1, N2, X)` are categorized
-below with the _transformational_ intrinsic functions.
-
-```
-BESSEL_J0(REAL(k) X) -> REAL(k)
-BESSEL_J1(REAL(k) X) -> REAL(k)
-BESSEL_JN(INTEGER(n) N, REAL(k) X) -> REAL(k)
-BESSEL_Y0(REAL(k) X) -> REAL(k)
-BESSEL_Y1(REAL(k) X) -> REAL(k)
-BESSEL_YN(INTEGER(n) N, REAL(k) X) -> REAL(k)
-ERF(REAL(k) X) -> REAL(k)
-ERFC(REAL(k) X) -> REAL(k)
-ERFC_SCALED(REAL(k) X) -> REAL(k)
-FRACTION(REAL(k) X) -> REAL(k)
-GAMMA(REAL(k) X) -> REAL(k)
-HYPOT(REAL(k) X, REAL(k) Y) -> REAL(k) = SQRT(X*X+Y*Y) without spurious overflow
-IMAGE_STATUS(INTEGER(any) IMAGE [, scalar TEAM_TYPE TEAM ]) -> default INTEGER
-IS_IOSTAT_END(INTEGER(any) I) -> default LOGICAL
-IS_IOSTAT_EOR(INTEGER(any) I) -> default LOGICAL
-LOG_GAMMA(REAL(k) X) -> REAL(k)
-MAX(INTEGER(k) ...) -> INTEGER(k)
-MAX(REAL(k) ...) -> REAL(k)
-MAX(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...)))
-MERGE(any type TSOURCE, same type FSOURCE, LOGICAL(any) MASK) -> type of FSOURCE
-MIN(INTEGER(k) ...) -> INTEGER(k)
-MIN(REAL(k) ...) -> REAL(k)
-MIN(CHARACTER(KIND=k) ...) -> CHARACTER(KIND=k,LEN=MAX(LEN(...)))
-MODULO(INTEGER(k) A, INTEGER(k) P) -> INTEGER(k); P*result >= 0
-MODULO(REAL(k) A, REAL(k) P) -> REAL(k) = A - P*FLOOR(A/P)
-NEAREST(REAL(k) X, REAL(any) S) -> REAL(k)
-OUT_OF_RANGE(INTEGER(any) X, scalar INTEGER or REAL(k) MOLD) -> default LOGICAL
-OUT_OF_RANGE(REAL(any) X, scalar REAL(k) MOLD) -> default LOGICAL
-OUT_OF_RANGE(REAL(any) X, scalar INTEGER(any) MOLD, scalar LOGICAL(any) ROUND=.FALSE.) -> default LOGICAL
-RRSPACING(REAL(k) X) -> REAL(k)
-SCALE(REAL(k) X, INTEGER(any) I) -> REAL(k)
-SET_EXPONENT(REAL(k) X, INTEGER(any) I) -> REAL(k)
-SPACING(REAL(k) X) -> REAL(k)
-```
-
-### Restricted specific aliases for elemental conversions &/or extrema with default intrinsic types
-
-```
-AMAX0(INTEGER ...) = REAL(MAX(...))
-AMAX1(REAL ...) = MAX(...)
-AMIN0(INTEGER...) = REAL(MIN(...))
-AMIN1(REAL ...) = MIN(...)
-DMAX1(DOUBLE PRECISION ...) = MAX(...)
-DMIN1(DOUBLE PRECISION ...) = MIN(...)
-FLOAT(INTEGER I) = REAL(I)
-IDINT(DOUBLE PRECISION A) = INT(A)
-IFIX(REAL A) = INT(A)
-MAX0(INTEGER ...) = MAX(...)
-MAX1(REAL ...) = INT(MAX(...))
-MIN0(INTEGER ...) = MIN(...)
-MIN1(REAL ...) = INT(MIN(...))
-SNGL(DOUBLE PRECISION A) = REAL(A)
-```
-
-### Generic elemental bit manipulation intrinsic functions
-Many of these accept a typeless "BOZ" literal as an actual argument.
-It is interpreted as having the kind of intrinsic `INTEGER` type
-as another argument, as if the typeless were implicitly wrapped
-in a call to `INT()`.
-When multiple arguments can be either `INTEGER` values or typeless
-constants, it is forbidden for *all* of them to be typeless
-constants if the result of the function is `INTEGER`
-(i.e., only `BGE`, `BGT`, `BLE`, and `BLT` can have multiple
-typeless arguments).
-
-```
-BGE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
-BGT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
-BLE(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
-BLT(INTEGER(n1) or BOZ I, INTEGER(n2) or BOZ J) -> default LOGICAL
-BTEST(INTEGER(n1) I, INTEGER(n2) POS) -> default LOGICAL
-DSHIFTL(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k)
-DSHIFTL(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k)
-DSHIFTR(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(any) SHIFT) -> INTEGER(k)
-DSHIFTR(BOZ I, INTEGER(k), INTEGER(any) SHIFT) -> INTEGER(k)
-IAND(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
-IAND(BOZ I, INTEGER(k) J) -> INTEGER(k)
-IBCLR(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k)
-IBITS(INTEGER(k) I, INTEGER(n1) POS, INTEGER(n2) LEN) -> INTEGER(k)
-IBSET(INTEGER(k) I, INTEGER(any) POS) -> INTEGER(k)
-IEOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
-IEOR(BOZ I, INTEGER(k) J) -> INTEGER(k)
-IOR(INTEGER(k) I, INTEGER(k) or BOZ J) -> INTEGER(k)
-IOR(BOZ I, INTEGER(k) J) -> INTEGER(k)
-ISHFT(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
-ISHFTC(INTEGER(k) I, INTEGER(n1) SHIFT, INTEGER(n2) SIZE=BIT_SIZE(I)) -> INTEGER(k)
-LEADZ(INTEGER(any) I) -> default INTEGER
-MASKL(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND)
-MASKR(INTEGER(any) I, KIND=KIND(0)) -> INTEGER(KIND)
-MERGE_BITS(INTEGER(k) I, INTEGER(k) or BOZ J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK)))
-MERGE_BITS(BOZ I, INTEGER(k) J, INTEGER(k) or BOZ MASK) = IOR(IAND(I,MASK),IAND(J,NOT(MASK)))
-NOT(INTEGER(k) I) -> INTEGER(k)
-POPCNT(INTEGER(any) I) -> default INTEGER
-POPPAR(INTEGER(any) I) -> default INTEGER = IAND(POPCNT(I), Z'1')
-SHIFTA(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
-SHIFTL(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
-SHIFTR(INTEGER(k) I, INTEGER(any) SHIFT) -> INTEGER(k)
-TRAILZ(INTEGER(any) I) -> default INTEGER
-```
-
-### Character elemental intrinsic functions
-See also `INDEX` and `LEN` above among the elemental intrinsic functions with
-unrestricted specific names.
-```
-ADJUSTL(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n)
-ADJUSTR(CHARACTER(k,LEN=n) STRING) -> CHARACTER(k,LEN=n)
-LEN_TRIM(CHARACTER(k,n) STRING, KIND=KIND(0)) -> INTEGER(KIND) = n
-LGE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
-LGT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
-LLE(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
-LLT(CHARACTER(k,n1) STRING_A, CHARACTER(k,n2) STRING_B) -> default LOGICAL
-SCAN(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
-VERIFY(CHARACTER(k,n) STRING, CHARACTER(k,m) SET, LOGICAL(any) BACK=.FALSE., KIND=KIND(0)) -> INTEGER(KIND)
-```
-
-`SCAN` returns the index of the first (or last, if `BACK=.TRUE.`) character in `STRING`
-that is present in `SET`, or zero if none is.
-
-`VERIFY` is essentially the opposite: it returns the index of the first (or last) character
-in `STRING` that is *not* present in `SET`, or zero if all are.
-
-# Transformational intrinsic functions
-
-This category comprises a large collection of intrinsic functions that
-are collected together because they somehow transform their arguments
-in a way that prevents them from being elemental.
-All of them are pure, however.
-
-Some general rules apply to the transformational intrinsic functions:
-
-1. `DIM` arguments are optional; if present, the actual argument must be
-   a scalar integer of any kind.
-1. When an optional `DIM` argument is absent, or an `ARRAY` or `MASK`
-   argument is a vector, the result of the function is scalar; otherwise,
-   the result is an array of the same shape as the `ARRAY` or `MASK`
-   argument with the dimension `DIM` removed from the shape.
-1. When a function takes an optional `MASK` argument, it must be conformable
-  with its `ARRAY` argument if it is present, and the mask can be any kind
-  of `LOGICAL`.  It can be scalar.
-1. The type `numeric` here can be any kind of `INTEGER`, `REAL`, or `COMPLEX`.
-1. The type `relational` here can be any kind of `INTEGER`, `REAL`, or `CHARACTER`.
-1. The type `any` here denotes any intrinsic or derived type.
-1. The notation `(..)` denotes an array of any rank (but not an assumed-rank array).
-
-## Logical reduction transformational intrinsic functions
-```
-ALL(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
-ANY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
-COUNT(LOGICAL(any) MASK(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
-PARITY(LOGICAL(k) MASK(..) [, DIM ]) -> LOGICAL(k)
-```
-
-## Numeric reduction transformational intrinsic functions
-```
-IALL(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
-IANY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
-IPARITY(INTEGER(k) ARRAY(..) [, DIM, MASK ]) -> INTEGER(k)
-NORM2(REAL(k) X(..) [, DIM ]) -> REAL(k)
-PRODUCT(numeric ARRAY(..) [, DIM, MASK ]) -> numeric
-SUM(numeric ARRAY(..) [, DIM, MASK ]) -> numeric
-```
-
-`NORM2` generalizes `HYPOT` by computing `SQRT(SUM(X*X))` while avoiding spurious overflows.
-
-## Extrema reduction transformational intrinsic functions
-```
-MAXVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k)
-MINVAL(relational(k) ARRAY(..) [, DIM, MASK ]) -> relational(k)
-```
-
-### Locational transformational intrinsic functions
-When the optional `DIM` argument is absent, the result is an `INTEGER(KIND)`
-vector whose length is the rank of `ARRAY`.
-When the optional `DIM` argument is present, the result is an `INTEGER(KIND)`
-array of rank `RANK(ARRAY)-1` and shape equal to that of `ARRAY` with
-the dimension `DIM` removed.
-
-The optional `BACK` argument is a scalar LOGICAL value of any kind.
-When present and `.TRUE.`, it causes the function to return the index
-of the *last* occurence of the target or extreme value.
-
-For `FINDLOC`, `ARRAY` may have any of the five intrinsic types, and `VALUE`
-must a scalar value of a type for which `ARRAY==VALUE` or `ARRAY .EQV. VALUE`
-is an acceptable expression.
-
-```
-FINDLOC(intrinsic ARRAY(..), scalar VALUE [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
-MAXLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
-MINLOC(relational ARRAY(..) [, DIM, MASK, KIND=KIND(0), BACK=.FALSE. ])
-```
-
-## Data rearrangement transformational intrinsic functions
-The optional `DIM` argument to these functions must be a scalar integer of
-any kind, and it takes a default value of 1 when absent.
-
-```
-CSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, DIM ]) -> same type/kind/shape as ARRAY
-```
-Either `SHIFT` is scalar or `RANK(SHIFT) == RANK(ARRAY) - 1` and `SHAPE(SHIFT)` is that of `SHAPE(ARRAY)` with element `DIM` removed.
-
-```
-EOSHIFT(any ARRAY(..), INTEGER(any) SHIFT(..) [, BOUNDARY, DIM ]) -> same type/kind/shape as ARRAY
-```
-* `SHIFT` is scalar or `RANK(SHIFT) == RANK(ARRAY) - 1` and `SHAPE(SHIFT)` is that of `SHAPE(ARRAY)` with element `DIM` removed.
-* If `BOUNDARY` is present, it must have the same type and parameters as `ARRAY`.
-* If `BOUNDARY` is absent, `ARRAY` must be of an intrinsic type, and the default `BOUNDARY` is the obvious `0`, `' '`, or `.FALSE.` value of `KIND(ARRAY)`.
-* If `BOUNDARY` is present, either it is scalar, or `RANK(BOUNDARY) == RANK(ARRAY) - 1` and `SHAPE(BOUNDARY)` is that of `SHAPE(ARRAY)` with element `DIM`
-  removed.
-
-```
-PACK(any ARRAY(..), LOGICAL(any) MASK(..)) -> vector of same type and kind as ARRAY
-```
-* `MASK` is conformable with `ARRAY` and may be scalar.
-* The length of the result vector is `COUNT(MASK)` if `MASK` is an array, else `SIZE(ARRAY)` if `MASK` is `.TRUE.`, else zero.
-
-```
-PACK(any ARRAY(..), LOGICAL(any) MASK(..), any VECTOR(n)) -> vector of same type, kind, and size as VECTOR
-```
-* `MASK` is conformable with `ARRAY` and may be scalar.
-* `VECTOR` has the same type and kind as `ARRAY`.
-* `VECTOR` must not be smaller than result of `PACK` with no `VECTOR` argument.
-* The leading elements of `VECTOR` are replaced with elements from `ARRAY` as
-  if `PACK` had been invoked without `VECTOR`.
-
-```
-RESHAPE(any SOURCE(..), INTEGER(k) SHAPE(n) [, PAD(..), INTEGER(k2) ORDER(n) ]) -> SOURCE array with shape SHAPE
-```
-* If `ORDER` is present, it is a vector of the same size as `SHAPE`, and
-  contains a permutation.
-* The element(s) of `PAD` are used to fill out the result once `SOURCE`
-  has been consumed.
-
-```
-SPREAD(any SOURCE, DIM, scalar INTEGER(any) NCOPIES) -> same type as SOURCE, rank=RANK(SOURCE)+1
-TRANSFER(any SOURCE, any MOLD) -> scalar if MOLD is scalar, else vector; same type and kind as MOLD
-TRANSFER(any SOURCE, any MOLD, scalar INTEGER(any) SIZE) -> vector(SIZE) of type and kind of MOLD
-TRANSPOSE(any MATRIX(n,m)) -> matrix(m,n) of same type and kind as MATRIX
-```
-
-The shape of the result of `SPREAD` is the same as that of `SOURCE`, with `NCOPIES` inserted
-at position `DIM`.
-
-```
-UNPACK(any VECTOR(n), LOGICAL(any) MASK(..), FIELD) -> type and kind of VECTOR, shape of MASK
-```
-`FIELD` has same type and kind as `VECTOR` and is conformable with `MASK`.
-
-## Other transformational intrinsic functions
-```
-BESSEL_JN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0))
-BESSEL_YN(INTEGER(n1) N1, INTEGER(n2) N2, REAL(k) X) -> REAL(k) vector (MAX(N2-N1+1,0))
-COMMAND_ARGUMENT_COUNT() -> scalar default INTEGER
-DOT_PRODUCT(LOGICAL(k) VECTOR_A(n), LOGICAL(k) VECTOR_B(n)) -> LOGICAL(k) = ANY(VECTOR_A .AND. VECTOR_B)
-DOT_PRODUCT(COMPLEX(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(CONJG(VECTOR_A) * VECTOR_B)
-DOT_PRODUCT(INTEGER(any) or REAL(any) VECTOR_A(n), numeric VECTOR_B(n)) = SUM(VECTOR_A * VECTOR_B)
-MATMUL(numeric ARRAY_A(j), numeric ARRAY_B(j,k)) -> numeric vector(k)
-MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k)) -> numeric vector(j)
-MATMUL(numeric ARRAY_A(j,k), numeric ARRAY_B(k,m)) -> numeric matrix(j,m)
-MATMUL(LOGICAL(n1) ARRAY_A(j), LOGICAL(n2) ARRAY_B(j,k)) -> LOGICAL vector(k)
-MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k)) -> LOGICAL vector(j)
-MATMUL(LOGICAL(n1) ARRAY_A(j,k), LOGICAL(n2) ARRAY_B(k,m)) -> LOGICAL matrix(j,m)
-NULL([POINTER/ALLOCATABLE MOLD]) -> POINTER
-REDUCE(any ARRAY(..), function OPERATION [, DIM, LOGICAL(any) MASK(..), IDENTITY, LOGICAL ORDERED=.FALSE. ])
-REPEAT(CHARACTER(k,n) STRING, INTEGER(any) NCOPIES) -> CHARACTER(k,n*NCOPIES)
-SELECTED_CHAR_KIND('DEFAULT' or 'ASCII' or 'ISO_10646' or ...) -> scalar default INTEGER
-SELECTED_INT_KIND(scalar INTEGER(any) R) -> scalar default INTEGER
-SELECTED_REAL_KIND([scalar INTEGER(any) P, scalar INTEGER(any) R, scalar INTEGER(any) RADIX]) -> scalar default INTEGER
-SHAPE(SOURCE, KIND=KIND(0)) -> INTEGER(KIND)(RANK(SOURCE))
-TRIM(CHARACTER(k,n) STRING) -> CHARACTER(k)
-```
-
-The type and kind of the result of a numeric `MATMUL` is the same as would result from
-a multiplication of an element of ARRAY_A and an element of ARRAY_B.
-
-The kind of the `LOGICAL` result of a `LOGICAL` `MATMUL` is the same as would result
-from an intrinsic `.AND.` operation between an element of `ARRAY_A` and an element
-of `ARRAY_B`.
-
-Note that `DOT_PRODUCT` with a `COMPLEX` first argument operates on its complex conjugate,
-but that `MATMUL` with a `COMPLEX` argument does not.
-
-The `MOLD` argument to `NULL` may be omitted only in a context where the type of the pointer is known,
-such as an initializer or pointer assignment statement.
-
-At least one argument must be present in a call to `SELECTED_REAL_KIND`.
-
-An assumed-rank array may be passed to `SHAPE`, and if it is associated with an assumed-size array,
-the last element of the result will be -1.
-
-## Coarray transformational intrinsic functions
-```
-FAILED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector
-GET_TEAM([scalar INTEGER(?) LEVEL]) -> scalar TEAM_TYPE
-IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n) [, scalar TEAM_TYPE TEAM ]) -> scalar default INTEGER
-IMAGE_INDEX(COARRAY, INTEGER(any) SUB(n), scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER
-NUM_IMAGES([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER
-NUM_IMAGES(scalar INTEGER(any) TEAM_NUMBER) -> scalar default INTEGER
-STOPPED_IMAGES([scalar TEAM_TYPE TEAM, KIND=KIND(0)]) -> INTEGER(KIND) vector
-TEAM_NUMBER([scalar TEAM_TYPE TEAM]) -> scalar default INTEGER
-THIS_IMAGE([COARRAY, DIM, scalar TEAM_TYPE TEAM]) -> default INTEGER
-```
-The result of `THIS_IMAGE` is a scalar if `DIM` is present or if `COARRAY` is absent,
-and a vector whose length is the corank of `COARRAY` otherwise.
-
-# Inquiry intrinsic functions
-These are neither elemental nor transformational; all are pure.
-
-## Type inquiry intrinsic functions
-All of these functions return constants.
-The value of the argument is not used, and may well be undefined.
-```
-BIT_SIZE(INTEGER(k) I(..)) -> INTEGER(k)
-DIGITS(INTEGER or REAL X(..)) -> scalar default INTEGER
-EPSILON(REAL(k) X(..)) -> scalar REAL(k)
-HUGE(INTEGER(k) X(..)) -> scalar INTEGER(k)
-HUGE(REAL(k) X(..)) -> scalar of REAL(k)
-KIND(intrinsic X(..)) -> scalar default INTEGER
-MAXEXPONENT(REAL(k) X(..)) -> scalar default INTEGER
-MINEXPONENT(REAL(k) X(..)) -> scalar default INTEGER
-NEW_LINE(CHARACTER(k,n) A(..)) -> scalar CHARACTER(k,1) = CHAR(10)
-PRECISION(REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER
-RADIX(INTEGER(k) or REAL(k) X(..)) -> scalar default INTEGER, always 2
-RANGE(INTEGER(k) or REAL(k) or COMPLEX(k) X(..)) -> scalar default INTEGER
-TINY(REAL(k) X(..)) -> scalar REAL(k)
-```
-
-## Bound and size inquiry intrinsic functions
-The results are scalar when `DIM` is present, and a vector of length=(co)rank(`(CO)ARRAY`)
-when `DIM` is absent.
-```
-LBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
-LCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
-SIZE(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
-UBOUND(any ARRAY(..) [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
-UCOBOUND(any COARRAY [, DIM, KIND=KIND(0) ]) -> INTEGER(KIND)
-```
-
-Assumed-rank arrays may be used with `LBOUND`, `SIZE`, and `UBOUND`.
-
-## Object characteristic inquiry intrinsic functions
-```
-ALLOCATED(any type ALLOCATABLE ARRAY) -> scalar default LOGICAL
-ALLOCATED(any type ALLOCATABLE SCALAR) -> scalar default LOGICAL
-ASSOCIATED(any type POINTER POINTER [, same type TARGET]) -> scalar default LOGICAL
-COSHAPE(COARRAY, KIND=KIND(0)) -> INTEGER(KIND) vector of length corank(COARRAY)
-EXTENDS_TYPE_OF(A, MOLD) -> default LOGICAL
-IS_CONTIGUOUS(any data ARRAY(..)) -> scalar default LOGICAL
-PRESENT(OPTIONAL A) -> scalar default LOGICAL
-RANK(any data A) -> scalar default INTEGER = 0 if A is scalar, SIZE(SHAPE(A)) if A is an array, rank if assumed-rank
-SAME_TYPE_AS(A, B) -> scalar default LOGICAL
-STORAGE_SIZE(any data A, KIND=KIND(0)) -> INTEGER(KIND)
-```
-The arguments to `EXTENDS_TYPE_OF` must be of extensible derived types or be unlimited polymorphic.
-
-An assumed-rank array may be used with `IS_CONTIGUOUS` and `RANK`.
-
-# Intrinsic subroutines
-
-(*TODO*: complete these descriptions)
-
-## One elemental intrinsic subroutine
-```
-INTERFACE
-  SUBROUTINE MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)
-    INTEGER(k1) :: FROM, TO
-    INTENT(IN) :: FROM
-    INTENT(INOUT) :: TO
-    INTEGER(k2), INTENT(IN) :: FROMPOS
-    INTEGER(k3), INTENT(IN) :: LEN
-    INTEGER(k4), INTENT(IN) :: TOPOS
-  END SUBROUTINE
-END INTERFACE
-```
-
-## Non-elemental intrinsic subroutines
-```
-CALL CPU_TIME(REAL INTENT(OUT) TIME)
-```
-The kind of `TIME` is not specified in the standard.
-
-```
-CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])
-```
-* All arguments are `OPTIONAL` and `INTENT(OUT)`.
-* `DATE`, `TIME`, and `ZONE` are scalar default `CHARACTER`.
-* `VALUES` is a vector of at least 8 elements of `INTEGER(KIND >= 2)`.
-```
-CALL EVENT_QUERY(EVENT, COUNT [, STAT])
-CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])
-CALL GET_COMMAND([COMMAND, LENGTH, STATUS, ERRMSG ])
-CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS, ERRMSG ])
-CALL GET_ENVIRONMENT_VARIABLE(NAME [, VALUE, LENGTH, STATUS, TRIM_NAME, ERRMSG ])
-CALL MOVE_ALLOC(ALLOCATABLE INTENT(INOUT) FROM, ALLOCATABLE INTENT(OUT) TO [, STAT, ERRMSG ])
-CALL RANDOM_INIT(LOGICAL(k1) INTENT(IN) REPEATABLE, LOGICAL(k2) INTENT(IN) IMAGE_DISTINCT)
-CALL RANDOM_NUMBER(REAL(k) INTENT(OUT) HARVEST(..))
-CALL RANDOM_SEED([SIZE, PUT, GET])
-CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])
-```
-
-## Atomic intrinsic subroutines
-```
-CALL ATOMIC_ADD(ATOM, VALUE [, STAT=])
-CALL ATOMIC_AND(ATOM, VALUE [, STAT=])
-CALL ATOMIC_CAS(ATOM, OLD, COMPARE, NEW [, STAT=])
-CALL ATOMIC_DEFINE(ATOM, VALUE [, STAT=])
-CALL ATOMIC_FETCH_ADD(ATOM, VALUE, OLD [, STAT=])
-CALL ATOMIC_FETCH_AND(ATOM, VALUE, OLD [, STAT=])
-CALL ATOMIC_FETCH_OR(ATOM, VALUE, OLD [, STAT=])
-CALL ATOMIC_FETCH_XOR(ATOM, VALUE, OLD [, STAT=])
-CALL ATOMIC_OR(ATOM, VALUE [, STAT=])
-CALL ATOMIC_REF(VALUE, ATOM [, STAT=])
-CALL ATOMIC_XOR(ATOM, VALUE [, STAT=])
-```
-
-## Collective intrinsic subroutines
-```
-CALL CO_BROADCAST
-CALL CO_MAX
-CALL CO_MIN
-CALL CO_REDUCE
-CALL CO_SUM
-```
-
-# Non-standard intrinsics
-## PGI
-```
-AND, OR, XOR
-LSHIFT, RSHIFT, SHIFT
-ZEXT, IZEXT
-COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D
-COMPL
-DCMPLX
-EQV, NEQV
-INT8
-JINT, JNINT, KNINT
-LOC
-```
-
-## Intel
-```
-DCMPLX(X,Y), QCMPLX(X,Y)
-DREAL(DOUBLE COMPLEX A) -> DOUBLE PRECISION
-DFLOAT, DREAL
-QEXT, QFLOAT, QREAL
-DNUM, INUM, JNUM, KNUM, QNUM, RNUM - scan value from string
-ZEXT
-RAN, RANF
-ILEN(I) = BIT_SIZE(I)
-SIZEOF
-MCLOCK, SECNDS
-COTAN(X) = 1.0/TAN(X)
-COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COTAND - degrees
-AND, OR, XOR
-LSHIFT, RSHIFT
-IBCHNG, ISHA, ISHC, ISHL, IXOR
-IARG, IARGC, NARGS, NUMARG
-BADDRESS, IADDR
-CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, LOC
-MALLOC
-```
-
-# Intrinsic Procedure Support in f18
-This section gives an overview of the support inside f18 libraries for the
-intrinsic procedures listed above.
-It may be outdated, refer to f18 code base for the actual support status.
-
-## Semantic Analysis
-F18 semantic expression analysis phase detects intrinsic procedure references,
-validates the argument types and deduces the return types.
-This phase currently supports all the intrinsic procedures listed above but the ones in the table below.
-
-| Intrinsic Category | Intrinsic Procedures Lacking Support |
-| --- | --- |
-| Coarray intrinsic functions | LCOBOUND, UCOBOUND, FAILED_IMAGES, GET_TEAM, IMAGE_INDEX, STOPPED_IMAGES, TEAM_NUMBER, THIS_IMAGE, COSHAPE |
-| Object characteristic inquiry functions | ALLOCATED, ASSOCIATED, EXTENDS_TYPE_OF, IS_CONTIGUOUS, PRESENT, RANK, SAME_TYPE, STORAGE_SIZE |
-| Type inquiry intrinsic functions | BIT_SIZE, DIGITS, EPSILON, HUGE, KIND, MAXEXPONENT, MINEXPONENT, NEW_LINE, PRECISION, RADIX, RANGE, TINY|
-| Non-standard intrinsic functions | AND, OR, XOR, LSHIFT, RSHIFT, SHIFT, ZEXT, IZEXT, COSD, SIND, TAND, ACOSD, ASIND, ATAND, ATAN2D, COMPL, DCMPLX, EQV, NEQV, INT8, JINT, JNINT, KNINT, LOC, QCMPLX, DREAL, DFLOAT, QEXT, QFLOAT, QREAL, DNUM, NUM, JNUM, KNUM, QNUM, RNUM, RAN, RANF, ILEN, SIZEOF, MCLOCK, SECNDS, COTAN, IBCHNG, ISHA, ISHC, ISHL, IXOR, IARG, IARGC, NARGS, NUMARG, BADDRESS, IADDR, CACHESIZE, EOF, FP_CLASS, INT_PTR_KIND, ISNAN, MALLOC |
-| Intrinsic subroutines |MVBITS (elemental), CPU_TIME, DATE_AND_TIME, EVENT_QUERY, EXECUTE_COMMAND_LINE, GET_COMMAND, GET_COMMAND_ARGUMENT, GET_ENVIRONMENT_VARIABLE, MOVE_ALLOC, RANDOM_INIT, RANDOM_NUMBER, RANDOM_SEED, SYSTEM_CLOCK |
-| Atomic intrinsic subroutines | ATOMIC_ADD &al. |
-| Collective intrinsic subroutines | CO_BROADCAST &al. |
-
-
-## Intrinsic Function Folding
-Fortran Constant Expressions can contain references to a certain number of
-intrinsic functions (see Fortran 2018 standard section 10.1.12 for more details).
-Constant Expressions may be used to define kind arguments. Therefore, the semantic
-expression analysis phase must be able to fold references to intrinsic functions
-listed in section 10.1.12.
-
-F18 intrinsic function folding is either performed by implementations directly
-operating on f18 scalar types or by using host runtime functions and
-host hardware types. F18 supports folding elemental intrinsic functions over
-arrays when an implementation is provided for the scalars (regardless of whether
-it is using host hardware types or not).
-The status of intrinsic function folding support is given in the sub-sections below.
-
-### Intrinsic Functions with Host Independent Folding Support
-Implementations using f18 scalar types enables folding intrinsic functions
-on any host and with any possible type kind supported by f18. The intrinsic functions
-listed below are folded using host independent implementations.
-
-| Return Type | Intrinsic Functions with Host Independent Folding Support|
-| --- | --- |
-| INTEGER| ABS(INTEGER(k)), DIM(INTEGER(k), INTEGER(k)), DSHIFTL, DSHIFTR, IAND, IBCLR, IBSET, IEOR, INT, IOR, ISHFT, KIND, LEN, LEADZ, MASKL, MASKR, MERGE_BITS, POPCNT, POPPAR, SHIFTA, SHIFTL, SHIFTR, TRAILZ |
-| REAL | ABS(REAL(k)), ABS(COMPLEX(k)), AIMAG, AINT, DPROD, REAL |
-| COMPLEX | CMPLX, CONJG |
-| LOGICAL | BGE, BGT, BLE, BLT |
-
-### Intrinsic Functions with Host Dependent Folding Support
-Implementations using the host runtime may not be available for all supported
-f18 types depending on the host hardware types and the libraries available on the host.
-The actual support on a host depends on what the host hardware types are.
-The list below gives the functions that are folded using host runtime and the related C/C++ types.
-F18 automatically detects if these types match an f18 scalar type. If so,
-folding of the intrinsic functions will be possible for the related f18 scalar type,
-otherwise an error message will be produced by f18 when attempting to fold related intrinsic functions.
-
-| C/C++ Host Type | Intrinsic Functions with Host Standard C++ Library Based Folding Support |
-| --- | --- |
-| float, double and long double | ACOS, ACOSH, ASINH, ATAN, ATAN2, ATANH, COS, COSH, ERF, ERFC, EXP, GAMMA, HYPOT, LOG, LOG10, LOG_GAMMA, MOD, SIN, SQRT, SINH, SQRT, TAN, TANH |
-| std::complex for float, double and long double| ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH, COS, COSH, EXP, LOG, SIN, SINH, SQRT, TAN, TANH |
-
-On top of the default usage of C++ standard library functions for folding described
-in the table above, it is possible to compile f18 evaluate library with
-[libpgmath](https://github.com/flang-compiler/flang/tree/master/runtime/libpgmath)
-so that it can be used for folding. To do so, one must have a compiled version
-of the libpgmath library available on the host and add
-`-DLIBPGMATH_DIR=<path to the compiled shared libpgmath library>` to the f18 cmake command.
-
-Libpgmath comes with real and complex functions that replace C++ standard library
-float and double functions to fold all the intrinsic functions listed in the table above.
-It has no long double versions. If the host long double matches an f18 scalar type,
-C++ standard library functions will still be used for folding expressions with this scalar type.
-Libpgmath adds the possibility to fold the following functions for f18 real scalar
-types related to host float and double types.
-
-| C/C++ Host Type | Additional Intrinsic Function Folding Support with Libpgmath (Optional) |
-| --- | --- |
-|float and double| BESSEL_J0, BESSEL_J1, BESSEL_JN (elemental only), BESSEL_Y0, BESSEL_Y1, BESSEL_Yn (elemental only), ERFC_SCALED |
-
-Libpgmath comes in three variants (precise, relaxed and fast). So far, only the
-precise version is used for intrinsic function folding in f18. It guarantees the greatest numerical precision.
-
-### Intrinsic Functions with Missing Folding Support
-The following intrinsic functions are allowed in constant expressions but f18
-is not yet able to fold them. Note that there might be constraints on the arguments
-so that these intrinsics can be used in constant expressions (see section 10.1.12 of Fortran 2018 standard).
-
-ALL, ACHAR, ADJUSTL, ADJUSTR, ANINT, ANY, BESSEL_JN (transformational only),
-BESSEL_YN (transformational only), BTEST, CEILING, CHAR, COUNT, CSHIFT, DOT_PRODUCT,
-DIM (REAL only), DOT_PRODUCT, EOSHIFT, FINDLOC, FLOOR, FRACTION, HUGE, IACHAR, IALL,
-IANY, IPARITY, IBITS, ICHAR, IMAGE_STATUS, INDEX, ISHFTC, IS_IOSTAT_END,
-IS_IOSTAT_EOR, LBOUND, LEN_TRIM, LGE, LGT, LLE, LLT, LOGICAL, MATMUL, MAX, MAXLOC,
-MAXVAL, MERGE, MIN, MINLOC, MINVAL, MOD (INTEGER only), MODULO, NEAREST, NINT,
-NORM2, NOT, OUT_OF_RANGE, PACK, PARITY, PRODUCT, REPEAT, REDUCE, RESHAPE,
-RRSPACING, SCAN, SCALE, SELECTED_CHAR_KIND, SELECTED_INT_KIND, SELECTED_REAL_KIND,
-SET_EXPONENT, SHAPE, SIGN, SIZE, SPACING, SPREAD, SUM, TINY, TRANSFER, TRANSPOSE,
-TRIM, UBOUND, UNPACK, VERIFY.
-
-Coarray, non standard, IEEE and ISO_C_BINDINGS intrinsic functions that can be
-used in constant expressions have currently no folding support at all.

flang/documentation/LabelResolution.md

-<!--===- documentation/LabelResolution.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
-  
--->
-
-# Semantics: Resolving Labels and Construct Names
-
-## Overview
-
-After the Fortran input file(s) has been parsed into a syntax tree, the compiler must check that the program checks semantically.  Target labels must be checked and violations of legal semantics should be reported to the user.
-
-This is the detailed design document on how these labels will be semantically checked.  Legal semantics may result in rewrite operations on the syntax tree.  Semantics violations will be reported as errors to the user.
-
-## Requirements
-
-- Input: a parse tree that decomposes the Fortran program unit
-- Output:
-   * **Success** returns true
-     (Additionally, the parse tree may be rewritten on success to capture the nested DO loop structure explicitly from any _label-do-stmt_ type loops.)
-   * **Failure** returns false, instantiates (a container of) error message(s) to indicate the problem(s)
-
-
-### Label generalities (6.2.5)
-
-Enforcement of the general label constraints.  There are three sorts of label usage. Labels can serve 
-   1. as a _label-do-stmt_ block range marker
-   1. as branching (control flow) targets
-   1. as specification annotations (`FORMAT` statements) for data transfer statements (I/O constructs)
-
-Labels are related to the standard definition of inclusive scope.  For example, control-flow arcs are not allowed to originate from one inclusive scope and target statements outside of that inclusive scope.
-
-Inclusive scope is defined as a tree structure of nested scoping constructs. A statement, _s_, is said to be *in* the same inclusive scope as another statement, _t_, if and only if _s_ and _t_ are in the same scope or _t_ is in one of the enclosing scopes of _s_, otherwise _s_ is *not in* the same inclusive scope as _t_. (Inclusive scope is unidirectional and is always from innermost scopes to outermost scopes.)
-
-#### Semantic Checks
-
-- labels range from 1 to 99999, inclusive (6.2.5 note 2)
-  * handled automatically by the parser, but add a range check
-- labels must be pairwise distinct within their program unit scope (6.2.5 para 2)
-  * if redundant labels appear &rarr; error redundant labels
-  * the total number of unique statement labels may have a limit
-
-
-### Labels Used for `DO` Loop Ranging
-
-#### _label-do-stmt_ (R1121)
-
-A _label-do-stmt_ is a control construct that results in the iterative execution of a number of statements.  A _label-do-stmt_ has a (possibly shared, _nonblock-do-construct_) _label_ that will be called the loop target label.  The statements to be executed will be the range from the _label-do-stmt_ to the statement identified by the loop target label, inclusive. This range of statements will be called the loop's body and logically forms a _do-block_.
-
-A _label-do-stmt_ is quite similar to a _block-do-construct_ in semantics, but the parse tree is different in that the parser does not impose a _do-block_ structure on the loop body.
-
-In F18, the nonblock `DO` construct has been removed.  For legacy support (through F08), we will need to handle nonblock `DO` constructs.  In F18, the following legacy code is an error.
-
-```fortran
-  DO 100 I = 1, 100
-    DO 100 J = 1, 100
-      ...
- 100 CONTINUE
-```
-
-##### Semantic Checks
-
-- the loop body target label must exist in the scope (F18:C1133; F08:C815, C817, C819)
-  * if the label does not appear, error of missing label
-- the loop body target label must be, lexically, after the _label-do-stmt_ (R1119)
-  * if the label appears lexically preceding the `DO`, error of malformed `DO`
-- control cannot transfer into the body from outside the _do-block_
-  * Exceptions (errors demoted to warnings)
-    - some implementations relax enforcement of this and allow `GOTO`s from the loop body to "extended ranges" and back again (PGI & gfortan appear to allow, NAG & Intel do not.)
-    - should some form of "extended ranges" for _do-constructs_ be supported, it should still be limited and not include parallel loops such as `DO CONCURRENT` or loops annotated with OpenACC or OpenMP directives.
-  * `GOTO`s into the `DO`s inclusive scope, error/warn of invalid transfer of control
-- requires that the loop terminating statement for a _label-do-stmt_ be either an `END DO` or a `CONTINUE`
-  * Exception
-    - earlier standards allowed other statements to be terminators
-
-Semantics for F08 and earlier that support sharing the loop terminating statement in a _nonblock-do-construct_ between multiple loops
-- some statements cannot be _do-term-action-stmt_ (F08:C816)
-  * a _do-term-action-stmt_ is an _action-stmt_ but does not include _arithmetic-if-stmt_, _continue-stmt_, _cycle-stmt_, _end-function-stmt_, _end-mp-subprogram-stmt_, _end-program-stmt_, _end-subroutine-stmt_, _error-stop-stmt_, _exit-stmt_, _goto-stmt_, _return-stmt_, or _stop-stmt_
-    - if the term action statement is forbidden, error invalid statement in `DO` loop term position
-- some statements cannot be _do-term-shared-stmt_ (F08:C818)
-  * this is the case as in our above example where two different nested loops share the same terminating statement (`100 continue`)
-  * a _do-term-shared-stmt_ is an _action-stmt_ with all the same exclusions as a _do-term-action-stmt_ except a _continue-stmt_ **is** allowed
-    - if the term shared action statement is forbidden, error invalid statement in term position
-
-If the `DO` loop is a `DO CONCURRENT` construct, there are additional constraints (11.1.7.5).
-- a _return-stmt_ is not allowed (C1136)
-- image control statements are not allowed (C1137)
-- branches must be from a statement and to a statement that both reside within the `DO CONCURRENT` (C1138)
-- impure procedures shall not be called (C1139)
-- deallocation of polymorphic objects is not allowed (C1140)
-- references to `IEEE_GET_FLAG`, `IEEE_SET_HALTING_MODE`, and `IEEE_GET_HALTING_MODE` cannot appear in the body of a `DO CONCURRENT` (C1141)
-- the use of the `ADVANCE=` specifier by an I/O statement in the body of a `DO CONCURRENT` is not allowed (11.1.7.5, para 5)
-
-### Labels Used in Branching
-
-#### _goto-stmt_ (11.2.2, R1157)
-
-A `GOTO` statement is a simple, direct transfer of control from the `GOTO` to the labelled statement.
-
-##### Semantic Checks
-
-- the labelled statement that is the target of a `GOTO` (11.2.1 constraints)
-  - must refer to a label that is in inclusive scope of the computed `GOTO` statement (C1169)
-    * if a label does not exist, error nonexistent label
-    * if a label is out of scope, error out of inclusive scope
-  - the branch target statement must be valid
-    * if the statement is not allowed as a branch target, error not a valid branch target
-- the labelled statement must be a branch target statement
-  * a branch target statement is any of _action-stmt_, _associate-stmt_, _end-associate-stmt_, _if-then-stmt_, _end-if-stmt_, _select-case-stmt_, _end-select-stmt_, _select-rank-stmt_, _end-select-rank-stmt_, _select-type-stmt_, _end-select-type-stmt_, _do-stmt_, _end-do-stmt_, _block-stmt_, _end-block-stmt_, _critical-stmt_, _end-critical-stmt_, _forall-construct-stmt_, _forall-stmt_, _where-construct-stmt_, _end-function-stmt_, _end-mp-subprogram-stmt_, _end-program-stmt_, or _end-subroutine-stmt_. (11.2.1)
-  * Some deleted features that were _action-stmt_ in older standards include _arithmetic-if-stmt_, _assign-stmt_, _assigned-goto-stmt_, and _pause-stmt_. For legacy mode support, these statements should be considered _action-stmt_.
-
-
-#### _computed-goto-stmt_ (11.2.3, R1158)
-
-The computed `GOTO` statement is analogous to a `switch` statement in C++.
-
-```fortran
-  GOTO ( label-list ) [,] scalar-int-expr
-```
-
-##### Semantics Checks
-
-- each label in _label-list_ (11.2.1 constraints, same as `GOTO`)
-  - must refer to a label that is in inclusive scope of the computed `GOTO` statement (C1170)
-    * if a label does not exist, error nonexistent label
-    * if a label is out of scope, error out of inclusive scope
-  - the branch target statement must be valid
-    * if the statement is not allowed as a branch target, error not a valid branch target
-- the _scalar-int-expr_ needs to have `INTEGER` type
-  * check the type of the expression (type checking done elsewhere)
-
-
-#### R853 _arithmetic-if-stmt_ (F08:8.2.4)
-
-This control-flow construct is deleted in F18.
-
-```fortran
-  IF (scalar-numeric-expr) label1,label2,label3
-```
-
-The arithmetic if statement is like a three-way branch operator. If the scalar numeric expression is less than zero goto _label-1_, else if the variable is equal to zero goto _label-2_, else if the variable is greater than zero goto _label-3_.
-
-##### Semantics Checks
-
-- the labels in the _arithmetic-if-stmt_ triple must all be present in the inclusive scope (F08:C848)
-  * if a label does not exist, error nonexistent label
-  * if a label is out of scope, error out of inclusive scope
-- the _scalar-numeric-expr_ must not be `COMPLEX` (F08:C849)
-  * check the type of the expression (type checking done elsewhere)
-
-
-#### _alt-return-spec_ (15.5.1, R1525)
-
-These are a Fortran control-flow construct for combining a return from a subroutine with a branch to a labelled statement in the calling routine all in one operation. A typical implementation is for the subroutine to return a hidden integer, which is used as a key in the calling code to then, possibly, branch to a labelled statement in inclusive scope.
-
-The labels are passed by the calling routine. We want to check those labels at the call-site, that is instances of _alt-return-spec_.
-
-##### Semantics Checks
-
-- each _alt-return-spec_ (11.2.1 constraints, same as `GOTO`)
-  - must refer to a label that is in inclusive scope of the `CALL` statement
-    * if a label does not exist, error nonexistent label
-    * if a label is out of scope, error out of inclusive scope
-  - the branch target statement must be valid
-    * if the statement is not allowed as a branch target, error not a valid branch target
-
-
-#### **END**, **EOR**, **ERR** specifiers (12.11)
-
-These specifiers can appear in I/O statements and can transfer control to specific labelled statements under exceptional conditions like end-of-file, end-of-record, and other error conditions.  (The PGI compiler adds code to test the results from the runtime routines to determine if these branches should take place.)
-
-##### Semantics Checks
-
-- each END, EOR, and ERR specifier (11.2.1 constraints, same as `GOTO`)
-  - must refer to a label that is in inclusive scope of the I/O statement
-    * if a label does not exist, error nonexistent label
-    * if a label is out of scope, error out of inclusive scope
-  - the branch target statement must be valid
-    * if the statement is not allowed as a branch target, error not a valid branch target
-
-#### _assigned-goto-stmt_ and _assign-stmt_ (F90:8.2.4)
-
-Deleted feature since Fortran 95.
-
-The _assigned-goto-stmt_ and _assign-stmt_ were _action-stmt_ in the Fortran 90 standard. They are included here for completeness. This pair of obsolete statements can (will) be enabled as part of the compiler's legacy Fortran support.
-
-The _assign-stmt_ stores a _label_ in an integer variable.  The _assigned-goto-stmt_ will then transfer control to the _label_ stored in that integer variable.
-
-```fortran
-  ASSIGN 10 TO i
-  ...
-  GOTO i (10,20,30)
-```
-
-##### Semantic Checks
-
-- an _assigned-goto-stmt_ cannot be a _do-term-action-stmt_ (F90:R829)
-- an _assigned-goto-stmt_ cannot be a _do-term-shared-stmt_ (F90:R833)
-- constraints from (F90:R839)
-  - each _label_ in an optional _label-list_ must be the statement label of a branch target statement that appears in the same scoping unit as the _assigned-goto-stmt_
-  - _scalar-int-variable_ (`i` in the example above) must be named and of type default integer
-  - an integer variable that has been assigned a label may only be referenced in an _assigned-goto_ or as a format specifier in an I/O statement
-  - when an I/O statement with a _format-specifier_ that is an integer variable is executed or when an _assigned-goto_ is executed, the variable must have been assigned a _label_
-  - an integer variable can only be assigned a label via the `ASSIGN` statement
-  - the label assigned to the variable must be in the same scoping unit as the _assigned-goto_ that branches to the _label_ value
-  - if the parameterized list of labels is present, the label value assigned to the integer variable must appear in that _label-list_
-  - a distinct _label_ can appear more than once in the _label-list_
-
-Some interpretation is needed as the terms of the older standard are different.
-
-A "scoping unit" is defined as
-  - a derived-type definition
-  - a procedure interface body, excluding derived-types and interfaces contained within it
-  - a program unit or subprogram, excluding derived-types, interfaces, and subprograms contained within it
-
-This is a more lax definition of scope than inclusive scope.
-
-A _named variable_ distinguishes a variable such as, `i`, from an element of an array, `a(i)`, for example.
-
-### Labels used in I/O
-
-#### Data transfer statements
-
-In data transfer (I/O) statements (e.g., `READ`), the user can specify a `FMT=` specifier that can take a label as its argument. (R1215)
-
-##### Semantic Checks
-
-- if the `FMT=` specifier has a label as its argument (C1230)
-  - the label must correspond to a `FORMAT` statement
-    * if the statement is not a `FORMAT`, error statement must be a `FORMAT`
-  - the labelled `FORMAT` statement must be in the same inclusive scope as the originating data transfer statement (also in 2008)
-    * if the label statement does not exist, error label does not exist
-    * if the label statement is not in scope, error label is not in inclusive scope
-  - Exceptions (errors demoted to warnings)
-    - PGI extension: referenced `FORMAT` statements may appear in a host procedure
-    - Possible relaxation: the scope of the referenced `FORMAT` statement may be ignored, allowing a `FORMAT` to be referenced from any scope in the compilation.
-
-### Construct Name generalities
-
-Various Fortran constructs can have names. These include
-  - the `WHERE` construct (10.2.3)
-  - the `FORALL` construct (10.2.4)
-  - the `ASSOCIATE` construct (11.1.3)
-  - the `BLOCK` construct (11.1.4)
-  - the `CHANGE TEAM` construct (11.1.5)
-  - the `CRITICAL` construct (11.1.6)
-  - the `DO` construct (11.1.7)
-  - the `IF` construct (11.1.8)
-  - the `SELECT CASE` construct (11.1.9)
-  - the `SELECT RANK` construct (11.1.10)
-  - the `SELECT TYPE` construct (11.1.11)
-
-#### Semantics Checks
-
-A construct name is a name formed under 6.2.2.  A name is an identifier. Identifiers are parsed by the parser.
-  - the maximum length of a name is 63 characters (C601)
-
-Names must either not be given for the construct or used throughout when specified.
-- if a construct is given a name, the construct's `END` statement must also specify the same name (`WHERE` C1033, `FORALL` C1035, ...)
-- `WHERE` has additional `ELSEWHERE` clauses
-- `IF` has additional `ELSE IF` and `ELSE` clauses
-- `SELECT CASE` has additional `CASE` clauses
-- `SELECT RANK` has additional `RANK` clauses
-- `SELECT TYPE` has additional _type-guard-stmt_
-These additional statements must meet the same constraint as the `END` of the construct. Names must match, if present, or there must be no names for any of the clauses.
-
-### `CYCLE` statement (11.1.7.4.4)
-
-The `CYCLE` statement takes an optional _do-construct-name_.
-
-#### Semantics Checks
-
-- if the `CYCLE` has a _construct-name_, then the `CYCLE` statement must appear within that named _do-construct_ (C1134)
-- if the `CYCLE` does not have a _do-construct-name_, the `CYCLE` statement must appear within a _do-construct_ (C1134)
-
-### `EXIT` statement (11.1.12)
-
-The `EXIT` statement takes an optional _construct-name_.
-
-#### Semantics Checks
-
-- if the `EXIT` has a _construct-name_, then the `EXIT` statement must appear within that named construct (C1166)
-- if the `EXIT` does not have a _construct-name_, the `EXIT` statement must appear within a _do-construct_ (C1166)
-- an _exit-stmt_ must not appear in a `DO CONCURRENT` if the `EXIT` belongs to the `DO CONCURRENT` or an outer construct enclosing the `DO CONCURRENT` (C1167)
-- an _exit-stmt_ must not appear in a `CHANGE TEAM` (`CRITICAL`) if the `EXIT` belongs to an outer construct enclosing the `CHANGE TEAM` (`CRITICAL`) (C1168)
-

flang/documentation/OpenMP-semantics.md

-<!--===- documentation/OpenMP-semantics.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
-  
--->
-
-# OpenMP Semantic Analysis
-
-## OpenMP for F18
-
-1. Define and document the parse tree representation for
-    * Directives (listed below)
-    * Clauses (listed below)
-    * Documentation
-1. All the directives and clauses need source provenance for messages
-1. Define and document how an OpenMP directive in the parse tree
-will be represented as the parent of the statement(s)
-to which the directive applies.
-The parser itself will not be able to construct this representation;
-there will be subsequent passes that do so
-just like for example _do-stmt_ and _do-construct_.
-1. Define and document the symbol table extensions
-1. Define and document the module file extensions
-
-
-### Directives
-
-OpenMP divides directives into three categories as follows.
-The directives that are in the same categories share some characteristics.
-
-
-
-#### Declarative directives
-
-An OpenMP directive may only be placed in a declarative context.
-A declarative directive results in one or more declarations only;
-it is not associated with the immediate execution of any user code.
-
-List of existing ones:
-* declare simd
-* declare target
-* threadprivate
-* declare reduction
-
-There is a parser node for each of these directives and
-the parser node saves information associated with the directive,
-for example,
-the name of the procedure-name in the `declare simd` directive.
-
-Each parse tree node keeps source provenance,
-one for the directive name itself and
-one for the entire directive starting from the directive name.
-
-A top-level class, `OpenMPDeclarativeConstruct`,
-holds all four of the node types as discriminated unions
-along with the source provenance for the entire directive
-starting from `!$OMP`.
-
-In `parser-tree.h`,
-`OpenMPDeclarativeConstruct` is part
-of the `SpecificationConstruct` and `SpecificationPart`
-in F18 because
-a declarative directive can only be placed in the specification part
-of a Fortran program.
-
-All the `Names` or `Designators` associated
-with the declarative directive will be resolved in later phases.
-
-#### Executable directives
-
-An OpenMP directive that is **not** declarative.
-That is, it may only be placed in an executable context.
-It contains stand-alone directives and constructs
-that are associated with code blocks.
-The stand-alone directive is described in the next section.
-
-The constructs associated with code blocks listed below
-share a similar structure:
-_Begin Directive_, _Clause List_, _Code Block_, _End Directive_.
-The _End Directive_ is optional for constructs
-like Loop-associated constructs.
-
-* Block-associated constructs (`OpenMPBlockConstruct`)
-* Loop-associated constructs (`OpenMPLoopConstruct`)
-* Atomic construct (`OpenMPAtomicConstruct`)
-* Sections Construct (`OpenMPSectionsConstruct`,
-  contains Sections/Parallel Sections constructs)
-* Critical Construct (`OpenMPCriticalConstruct`)
-
-A top-level class, `OpenMPConstruct`,
-includes stand-alone directive and constructs
-listed above as discriminated unions.
-
-In the `parse-tree.h`, `OpenMPConstruct` is an element
-of the `ExecutableConstruct`.
-
-All the `Names` or `Designators` associated
-with the executable directive will be resolved in Semantic Analysis.
-
-When the backtracking parser can not identify the associated code blocks,
-the parse tree will be rewritten later in the Semantics Analysis.
-
-#### Stand-alone Directives
-
-An OpenMP executable directive that has no associated user code
-except for that which appears in clauses in the directive.
-
-List of existing ones:
-* taskyield
-* barrier
-* taskwait
-* target enter data
-* target exit data
-* target update
-* ordered
-* flush
-* cancel
-* cancellation point
-
-A higher-level class is created for each category
-which contains directives listed above that share a similar structure:
-* OpenMPSimpleStandaloneConstruct
-(taskyield, barrier, taskwait,
-target enter/exit data, target update, ordered)
-* OpenMPFlushConstruct
-* OpenMPCancelConstruct
-* OpenMPCancellationPointConstruct
-
-A top-level class, `OpenMPStandaloneConstruct`,
-holds all four of the node types as discriminated unions
-along with the source provenance for the entire directive.
-Also, each parser node for the stand-alone directive saves
-the source provenance for the directive name itself.
-
-### Clauses
-
-Each clause represented as a distinct class in `parse-tree.h`.
-A top-level class, `OmpClause`,
-includes all the clauses as discriminated unions.
-The parser node for `OmpClause` saves the source provenance
-for the entire clause.
-
-All the `Names` or `Designators` associated
-with the clauses will be resolved in Semantic Analysis.
-
-Note that the backtracking parser will not validate
-that the list of clauses associated
-with a directive is valid other than to make sure they are well-formed.
-In particular,
-the parser does not check that
-the association between directive and clauses is correct
-nor check that the values in the directives or clauses are correct.
-These checks are deferred to later phases of semantics to simplify the parser.
-
-## Symbol Table Extensions for OpenMP
-
-Name resolution can be impacted by the OpenMP code.
-In addition to the regular steps to do the name resolution,
-new scopes and symbols may need to be created
-when encountering certain OpenMP constructs.
-This section describes the extensions
-for OpenMP during Symbol Table construction.
-
-OpenMP uses the fork-join model of parallel execution and
-all OpenMP threads have access to
-a _shared_ memory place to store and retrieve variables
-but each thread can also have access to
-its _threadprivate_ memory that must not be accessed by other threads.
-
-For the directives and clauses that can control the data environments,
-compiler needs to determine two kinds of _access_
-to variables used in the directive’s associated structured block:
-**shared** and **private**.
-Each variable referenced in the structured block
-has an original variable immediately outside of the OpenMP constructs.
-Reference to a shared variable in the structured block
-becomes a reference to the original variable.
-However, each private variable referenced in the structured block,
-a new version of the original variable (of the same type and size)
-will be created in the threadprivate memory.
-
-There are exceptions that directives/clauses
-need to create a new `Symbol` without creating a new `Scope`,
-but in general,
-when encountering each of the data environment controlling directives
-(discussed in the following sections),
-a new `Scope` will be created.
-For each private variable referenced in the structured block,
-a new `Symbol` is created out of the original variable
-and the new `Symbol` is associated
-with original variable’s `Symbol` via `HostAssocDetails`.
-A new set of OpenMP specific flags are added
-into `Flag` class in `symbol.h` to indicate the types of
-associations,
-data-sharing attributes,
-and data-mapping attributes
-in the OpenMP data environments.
-
-### New Symbol without new Scope
-
-OpenMP directives that require new `Symbol` to be created
-but not new `Scope` are listed in the following table
-in terms of the Symbol Table extensions for OpenMP:
-
-<table>
-  <tr>
-   <td rowspan="2" colspan="2" >Directives/Clauses
-   </td>
-   <td rowspan="2" >Create New
-<p>
-Symbol
-<p>
-w/
-   </td>
-   <td colspan="2" >Add Flag
-   </td>
-  </tr>
-  <tr>
-   <td>on Symbol of
-   </td>
-   <td>Flag
-   </td>
-  </tr>
-  <tr>
-   <td rowspan="4" >Declarative Directives
-   </td>
-   <td>declare simd [(proc-name)]
-   </td>
-   <td>-
-   </td>
-   <td>The name of the enclosing function, subroutine, or interface body
-   to which it applies, or proc-name
-   </td>
-   <td>OmpDeclareSimd
-   </td>
-  </tr>
-  <tr>
-   <td>declare target
-   </td>
-   <td>-
-   </td>
-   <td>The name of the enclosing function, subroutine, or interface body
-   to which it applies
-   </td>
-   <td>OmpDeclareTarget
-   </td>
-  </tr>
-  <tr>
-   <td>threadprivate(list)
-   </td>
-   <td>-
-   </td>
-   <td>named variables and named common blocks
-   </td>
-   <td>OmpThreadPrivate
-   </td>
-  </tr>
-  <tr>
-   <td>declare reduction
-   </td>
-   <td>*
-   </td>
-   <td>reduction-identifier
-   </td>
-   <td>OmpDeclareReduction
-   </td>
-  </tr>
-  <tr>
-   <td>Stand-alone directives
-   </td>
-   <td>flush
-   </td>
-   <td>-
-   </td>
-   <td>variable, array section or common block name
-   </td>
-   <td>OmpFlushed
-   </td>
-  </tr>
-  <tr>
-   <td colspan="2" >critical [(name)]
-   </td>
-   <td>-
-   </td>
-   <td>name (user-defined identifier)
-   </td>
-   <td>OmpCriticalLock
-   </td>
-  </tr>
-  <tr>
-   <td colspan="2" >if ([ directive-name-modifier :] scalar-logical-expr)
-   </td>
-   <td>-
-   </td>
-   <td>directive-name-modifier
-   </td>
-   <td>OmpIfSpecified
-   </td>
-  </tr>
-</table>
-
-
-      -      No Action
-
-      *      Discussed in “Module File Extensions for OpenMP” section
-
-
-### New Symbol with new Scope
-
-For the following OpenMP regions:
-
-* `target` regions
-* `teams` regions
-* `parallel` regions
-* `simd` regions
-* task generating regions (created by `task` or `taskloop` constructs)
-* worksharing regions
-(created by `do`, `sections`, `single`, or `workshare` constructs)
-
-A new `Scope` will be created
-when encountering the above OpenMP constructs
-to ensure the correct data environment during the Code Generation.
-To determine whether a variable referenced in these regions
-needs the creation of a new `Symbol`,
-all the data-sharing attribute rules
-described in OpenMP Spec [2.15.1] apply during the Name Resolution.
-The available data-sharing attributes are:
-**_shared_**,
-**_private_**,
-**_linear_**,
-**_firstprivate_**,
-and **_lastprivate_**.
-The attribute is represented as `Flag` in the `Symbol` object.
-
-More details are listed in the following table:
-
-<table>
-  <tr>
-   <td rowspan="2" >Attribute
-   </td>
-   <td rowspan="2" >Create New Symbol
-   </td>
-   <td colspan="2" >Add Flag
-   </td>
-  </tr>
-  <tr>
-   <td>on Symbol of
-   </td>
-   <td>Flag
-   </td>
-  </tr>
-  <tr>
-   <td>shared
-   </td>
-   <td>No
-   </td>
-   <td>Original variable
-   </td>
-   <td>OmpShared
-   </td>
-  </tr>
-  <tr>
-   <td>private
-   </td>
-   <td>Yes
-   </td>
-   <td>New Symbol
-   </td>
-   <td>OmpPrivate
-   </td>
-  </tr>
-  <tr>
-   <td>linear
-   </td>
-   <td>Yes
-   </td>
-   <td>New Symbol
-   </td>
-   <td>OmpLinear
-   </td>
-  </tr>
-  <tr>
-   <td>firstprivate
-   </td>
-   <td>Yes
-   </td>
-   <td>New Symbol
-   </td>
-   <td>OmpFirstPrivate
-   </td>
-  </tr>
-  <tr>
-   <td>lastprivate
-   </td>
-   <td>Yes
-   </td>
-   <td>New Symbol
-   </td>
-   <td>OmpLastPrivate
-   </td>
-  </tr>
-</table>
-
-To determine the right data-sharing attribute,
-OpenMP defines that the data-sharing attributes
-of variables that are referenced in a construct can be
-_predetermined_, _explicitly determined_, or _implicitly determined_.
-
-#### Predetermined data-sharing attributes
-
-* Assumed-size arrays are **shared**
-* The loop iteration variable(s)
-in the associated _do-loop(s)_ of a
-_do_,
-_parallel do_,
-_taskloop_,
-or _distributeconstruct_
-is (are) **private**
-* A loop iteration variable
-for a sequential loop in a _parallel_ or task generating construct
-is **private** in the innermost such construct that encloses the loop
-* Implied-do indices and _forall_ indices are **private**
-* The loop iteration variable in the associated _do-loop_
-of a _simd_ construct with just one associated _do-loop_
-is **linear** with a linear-step
-that is the increment of the associated _do-loop_
-* The loop iteration variables in the associated _do-loop(s)_ of a _simd_
-construct with multiple associated _do-loop(s)_ are **lastprivate**
-
-#### Explicitly determined data-sharing attributes
-
-Variables with _explicitly determined_ data-sharing attributes are:
-
-* Variables are referenced in a given construct
-* Variables are listed in a data-sharing attribute clause on the construct.
-
-The data-sharing attribute clauses are:
-* _default_ clause
-(discussed in “Implicitly determined data-sharing attributes”)
-* _shared_ clause
-* _private_ clause
-* _linear_ clause
-* _firstprivate_ clause
-* _lastprivate_ clause
-* _reduction_ clause
-(new `Symbol` created with the flag `OmpReduction` set)
-
-Note that variables with _predetermined_ data-sharing attributes
-may not be listed (with exceptions) in data-sharing attribute clauses.
-
-#### Implicitly determined data-sharing attributes
-
-Variables with implicitly determined data-sharing attributes are:
-
-* Variables are referenced in a given construct
-* Variables do not have _predetermined_ data-sharing attributes
-* Variables are not listed in a data-sharing attribute clause
-on the construct.
-
-Rules for variables with _implicitly determined_ data-sharing attributes:
-
-* In a _parallel_ construct, if no _default_ clause is present,
-these variables are **shared**
-* In a task generating construct,
-if no _default_ clause is present,
-a variable for which the data-sharing attribute
-is not determined by the rules above
-and that in the enclosing context is determined
-to be shared by all implicit tasks
-bound to the current team is **shared**
-* In a _target_ construct,
-variables that are not mapped after applying data-mapping attribute rules
-(discussed later) are **firstprivate**
-* In an orphaned task generating construct,
-if no _default_ clause is present, dummy arguments are **firstprivate**
-* In a task generating construct, if no _default_ clause is present,
-a variable for which the data-sharing attribute is not determined
-by the rules above is **firstprivate**
-* For constructs other than task generating constructs or _target_ constructs,
-if no _default_ clause is present,
-these variables reference the variables with the same names
-that exist in the enclosing context
-* In a _parallel_, _teams_, or task generating construct,
-the data-sharing attributes of these variables are determined
-by the _default_ clause, if present:
-    * _default(shared)_
-    clause causes all variables referenced in the construct
-    that have _implicitly determined_ data-sharing attributes
-    to be **shared**
-    * _default(private)_
-    clause causes all variables referenced in the construct
-    that have _implicitly determined_ data-sharing attributes
-    to be **private**
-    * _default(firstprivate)_
-    clause causes all variables referenced in the construct
-    that have _implicitly determined_ data-sharing attributes
-    to be **firstprivate**
-    * _default(none)_
-    clause requires that each variable
-    that is referenced in the construct,
-    and that does not have a _predetermined_ data-sharing attribute,
-    must have its data-sharing attribute _explicitly determined_
-    by being listed in a data-sharing attribute clause
-
-
-### Data-mapping Attribute
-
-When encountering the _target data_ and _target_ directives,
-the data-mapping attributes of any variable referenced in a target region
-will be determined and represented as `Flag` in the `Symbol` object
-of the variable.
-No `Symbol` or `Scope` will be created.
-
-The basic steps to determine the data-mapping attribute are:
-
-1. If _map_ clause is present,
-the data-mapping attribute is determined by the _map-type_
-on the clause and its corresponding `Flag` are listed below:
-
-<table>
-  <tr>
-   <td>
-data-mapping attribute
-   </td>
-   <td>Flag
-   </td>
-  </tr>
-  <tr>
-   <td>to
-   </td>
-   <td>OmpMapTo
-   </td>
-  </tr>
-  <tr>
-   <td>from
-   </td>
-   <td>OmpMapFrom
-   </td>
-  </tr>
-  <tr>
-   <td>tofrom
-(default if map-type is not present)
-   </td>
-   <td>OmpMapTo & OmpMapFrom
-   </td>
-  </tr>
-  <tr>
-   <td>alloc
-   </td>
-   <td>OmpMapAlloc
-   </td>
-  </tr>
-  <tr>
-   <td>release
-   </td>
-   <td>OmpMapRelease
-   </td>
-  </tr>
-  <tr>
-   <td>delete
-   </td>
-   <td>OmpMapDelete
-   </td>
-  </tr>
-</table>
-
-2. Otherwise, the following data-mapping rules apply
-for variables referenced in a _target_ construct
-that are _not_ declared in the construct and
-do not appear in data-sharing attribute or map clauses:
-    * If a variable appears in a _to_ or _link_ clause
-    on a _declare target_ directive then it is treated
-    as if it had appeared in a _map_ clause with a _map-type_ of **tofrom**
-3. Otherwise, the following implicit data-mapping attribute rules apply:
-    * If a _defaultmap(tofrom:scalar)_ clause is _not_ present
-    then a scalar variable is not mapped,
-    but instead has an implicit data-sharing attribute of **firstprivate**
-    * If a _defaultmap(tofrom:scalar)_ clause is present
-    then a scalar variable is treated as if it had appeared
-    in a map clause with a map-type of **tofrom**
-    * If a variable is not a scalar
-    then it is treated as if it had appeared in a map clause
-    with a _map-type_ of **tofrom**
-
-After the completion of the Name Resolution phase,
-all the data-sharing or data-mapping attributes marked for the `Symbols`
-may be used later in the Semantics Analysis and in the Code Generation.
-
-## Module File Extensions for OpenMP
-
-After the successful compilation of modules and submodules
-that may contain the following Declarative Directives,
-the entire directive starting from `!$OMP` needs to be written out
-into `.mod` files in their corresponding Specification Part:
-
-* _declare simd_ or _declare target_
-
-    In the “New Symbol without new Scope” section,
-    we described that when encountering these two declarative directives,
-    new `Flag` will be applied to the Symbol of the name of
-    the enclosing function, subroutine, or interface body to
-    which it applies, or proc-name.
-    This `Flag` should be part of the API information
-    for the given subroutine or function
-
-* _declare reduction_
-
-    The _reduction-identifier_ in this directive
-    can be use-associated or host-associated.
-    However, it will not act like other Symbols
-    because user may have a reduction name
-    that is the same as a Fortran entity name in the same scope.
-    Therefore a specific data structure needs to be created
-    to save the _reduction-identifier_ information
-    in the Scope and this directive needs to be written into `.mod` files
-
-## Phases of OpenMP Analysis
-
-1. Create the parse tree for OpenMP
-    1. Add types for directives and clauses
-        1. Add type(s) that will be used for directives
-        2. Add type(s) that will be used for clauses
-        3. Add other types, e.g. wrappers or other containers
-        4. Use std::variant to encapsulate meaningful types
-    2. Implemented in the parser for OpenMP (openmp-grammar.h)
-2. Create canonical nesting
-    1. Restructure parse tree to reflect the association
-    of directives and stmts
-        1. Associate `OpenMPLoopConstruct`
-        with `DoConstruct` and `OpenMPEndLoopDirective`
-    1. Investigate, and perhaps reuse,
-    the algorithm used to restructure do-loops
-    2. Add a pass near the code that restructures do-loops;
-    but do not extend the code that handles do-loop for OpenMP;
-    keep this code separate.
-    3. Report errors that prevent restructuring
-    (e.g. loop directive not followed by loop)
-    We should abort in case of errors
-    because there is no point to perform further checks
-    if it is not a legal OpenMP construct
-3. Validate the structured-block
-    1. Structured-block is a block of executable statements
-    1. Single entry and single exit
-    1. Access to the structured block must not be the result of a branch
-    1. The point of exit cannot be a branch out of the structured block
-4. Check that directive and clause combinations are legal
-    1. Begin and End directive should match
-    1. Simply check that the clauses are allowed by the directives
-    1. Write as a separate pass for simplicity and correctness of the parse tree
-5. Write parse tree tests
-    1. At this point, the parse tree should be perfectly formed
-    1. Write tests that check for correct form and provenance information
-    1. Write tests for errors that can occur during the restructuring
-6. Scope, symbol tables, and name resolution
-    1. Update the existing code to handle names and scopes introduced by OpenMP
-    1. Write tests to make sure names are properly implemented
-7. Check semantics that is specific to each directive
-    1. Validate the directive and its clauses
-    1. Some clause checks require the result of name resolution,
-    i.e. “A list item may appear in a _linear_ or _firstprivate_ clause
-    but not both.”
-    1. TBD:
-    Validate the nested statement for legality in the scope of the directive
-    1. Check the nesting of regions [OpenMP 4.5 spec 2.17]
-8. Module file utilities
-    1.  Write necessary OpenMP declarative directives to `.mod` files
-    2. Update the existing code
-    to read available OpenMP directives from the `.mod` files

flang/documentation/OptionComparison.md

-<!--===- documentation/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
-
-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 ___[Notes section](#notes)___ 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.
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#standards">Standards conformance</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong> </td>
-   <td><strong>Cray</strong> </td>
-   <td><strong>GNU</strong> </td>
-   <td><strong>IBM</strong> </td>
-   <td><strong>Intel</strong> </td>
-   <td><strong>PGI</strong> </td>
-   <td><strong>Flang</strong> </td>
-  </tr>
-  <tr>
-   <td>Overall conformance </td>
-   <td>en,
-<p>
-eN
-   </td>
-   <td>std=<em>level</em> </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=210">qlanglvl</a>, <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=257">qsaa</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-stand">stand level</a>
-   </td>
-   <td>Mstandard
-   </td>
-   <td>Mstandard
-   </td>
-  </tr>
-  <tr>
-   <td>Compatibility with previous standards or implementations
-   </td>
-   <td>N/A
-   </td>
-   <td>fdec,
-<p>
-fall-instrinsics
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=297">qxlf77</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=299">qxlf90</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=301">qxlf2003</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=305">qxfl2008</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=245">qport</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-f66">f66</a>,
-<p>
-<a href="https://software.intel.com/node/a8bfa478-22d5-4000-b0ac-b881804a7611">f77rtl</a>,
-<p>
-<a href="https://software.intel.com/node/647820a0-fc53-4252-a858-46feb012a281">fpscomp</a>,
-<p>
-<a href="https://software.intel.com/node/e610682a-00fe-4881-9cf7-8eee08c5f2a2">Intconstant</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-standard-realloc-lhs">nostandard-realloc-lhs</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-standard-semantics">standard-semantics</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume nostd_intent_in</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume nostd_value</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume norealloc_lhs</a>
-   </td>
-   <td>Mallocatable=95|03
-   </td>
-   <td>Mallocatable=95|03
-   </td>
-  </tr>
-</table>
-
-
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#source">Source format</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Fixed or free source
-   </td>
-   <td>f free,
-<p>
-f fixed
-   </td>
-   <td>ffree-form,
-<p>
-ffixed-form
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=179">qfree</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=169">qfixed</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-fixed">fixed</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-free">free</a>
-   </td>
-   <td>Mfree,
-<p>
-Mfixed
-   </td>
-   <td>Mfreeform,
-<p>
-Mfixed
-   </td>
-  </tr>
-  <tr>
-   <td>Source line length
-   </td>
-   <td>N <em>col</em>
-   </td>
-   <td>ffixed-line-length-n,
-<p>
-ffree-line-length-n
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=169">qfixed=n</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-extend-source">extend-source [size]</a>
-   </td>
-   <td>Mextend
-   </td>
-   <td>Mextend
-   </td>
-  </tr>
-  <tr>
-   <td>Column 1 comment specifier
-   </td>
-   <td>ed
-   </td>
-   <td>fd-lines-as-code,
-<p>
-fd-lines-as-comments
-   </td>
-   <td>D,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=161">qdlines</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=306">qxlines</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-d-lines-qd-lines">d-lines</a>
-   </td>
-   <td>Mdlines
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Don't treat CR character as a line terminator
-   </td>
-   <td>NA
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=153">qnocr</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Source file naming
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=282">qsuffix</a>
-   </td>
-   <td><a href="https://software.intel.com/node/84174680-3c7d-4225-9611-6083f496aa9b">extfor</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-tf">Tf filename</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#names">Names, Literals, and other tokens</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Max identifier length
-   </td>
-   <td>N/A
-   </td>
-   <td>fmax-identifier-length=<em>n</em>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>"$" in symbol names
-   </td>
-   <td>N/A
-   </td>
-   <td>fdollar-ok
-   </td>
-   <td>default
-   </td>
-   <td>default
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Allow names with leading "_"
-   </td>
-   <td>eQ
-   </td>
-   <td>N/A 
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Specify name format
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=296">U</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-names">names=keyword</a>
-   </td>
-   <td>Mupcase
-   </td>
-   <td>NA
-   </td>
-  </tr>
-  <tr>
-   <td>Escapes in literals
-   </td>
-   <td>N/A
-   </td>
-   <td>fbackslash
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=163">qescape</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume bscc</a>
-   </td>
-   <td>Mbackslash
-   </td>
-   <td>Mbackslash
-   </td>
-  </tr>
-  <tr>
-   <td>Allow multibyte characters in strings
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=223">qmbcs</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Create null terminated strings
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=228">qnullterm</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Character to use for "$"
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>Mdollar,<em>char</em>
-   </td>
-   <td>
-   </td>
-  </tr>
-  <tr>
-   <td>Allow PARAMETER statements without parentheses
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://software.intel.com/node/42e8ec08-64cc-44ba-a636-20ed50c682cd">altparam</a>
-   </td>
-   <td>N?A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#do">DO loop handling</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>One trip DO loops
-   </td>
-   <td>ej
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=113">1</a>,
-<p>
-<a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=231">qonetrip</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-f66">f66</a>
-   </td>
-   <td>Monetrip
-   </td>
-   <td>N/A 
-   </td>
-  </tr>
-  <tr>
-   <td>Allow branching into loops
-   </td>
-   <td>eg
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#real">REAL, DOUBLE PRECISION, and COMPLEX Data</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Default REAL size
-   </td>
-   <td>s real32,
-<p>
-s real64,
-<p>
-s default32,
-<p>
-s default64
-   </td>
-   <td>fdefault-real-[8|10|16]
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=252">qrealsize=[4|8]</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-real-size">real-size [32|64|128]</a>
-   </td>
-   <td>r[4|8]
-   </td>
-   <td>r8,
-<p>
-fdefault-real-8
-   </td>
-  </tr>
-  <tr>
-   <td>Default DOUBLE PRECISION size
-   </td>
-   <td>ep
-   </td>
-   <td>fdefault-double-8
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-double-size">double-size[64|128]</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Make real constants DOUBLE PRECISION
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=161">qdpc</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Promote or demote REAL type sizes
-   </td>
-   <td>N/A
-   </td>
-   <td>freal-[4|8]-real[4|8|10|16]
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=144">qautodbl=size</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>Mr8,
-<p>
-Mr8intrinsics
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Rounding mode
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=190">qieee</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume std_minus0_rounding</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Treatment of -0.0
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume minus0</a>
-   </td>
-   <td>
-   </td>
-   <td>
-   </td>
-  </tr>
-</table>
-
-
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#integer">INTEGER and LOGICAL Data</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Default INTEGER size
-   </td>
-   <td>s integer32,
-<p>
-s integer64,
-<p>
-s default32,
-<p>
-s default64
-   </td>
-   <td>fdefault-integer-8
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=202">qintsize=[2|4|8]</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-integer-size">integer-size [32|64|128]</a>
-   </td>
-   <td>I[2|4|8],
-<p>
-Mi4,
-<p>
-Mnoi4
-   </td>
-   <td>i8,
-<p>
-fdefault-integer-8
-   </td>
-  </tr>
-  <tr>
-   <td>Promote INTEGER sizes
-   </td>
-   <td>N/A
-   </td>
-   <td>finteger-4-integer-8
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Enable 8 and 16 bit INTEGER and LOGICALS
-   </td>
-   <td>eh
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Change how the compiler treats LOGICAL
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>Munixlogical
-   </td>
-   <td>
-   </td>
-  </tr>
-  <tr>
-   <td>Treatment of numeric constants as arguments
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=297">qxlf77 oldboz</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume old_boz</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Treatment of assignment between numerics and logicals
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume old_logical_assign</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong>CHARACTER and Pointer Data</strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Use bytes for pointer arithmetic
-   </td>
-   <td>s byte_pointer
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Use words for pointer arithmetic
-   </td>
-   <td>S word_pointer
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Allow character constants for typeless constants
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=153">qctyplss</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-<table>
-  <tr>
-   <td colspan="7" ><strong>Data types and allocation</strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Default to IMPLICIT NONE
-   </td>
-   <td>eI
-   </td>
-   <td>fimplicit-none
-   </td>
-   <td>u, <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=291">qundef</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-warn">warn declarations</a>
-   </td>
-   <td>Mdclchk
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Enable DEC STRUCTURE extensions
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://gcc.gnu.org/onlinedocs/gfortran/STRUCTURE-and-RECORD.html">fdec-structure</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www.pgroup.com/doc/pgi15fortref.pdf#page=86">default</a>
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Enable <a href="https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/types">Cray pointers</a>
-   </td>
-   <td>default
-   </td>
-   <td>fcray-pointer
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1#page=432">Default (near equivalent)</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-pointer-integer">Default (near equivalent)</a>
-   </td>
-   <td>Mcray
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Allow bitwise logical operations on numeric
-   </td>
-   <td>ee
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=201">qintlog</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Allow DEC STATIC and AUTOMATIC declarations
-   </td>
-   <td>default
-   </td>
-   <td>fdec-static
-   </td>
-   <td>Default, see <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1#page=393">IMPLICIT STATIC</a> and <a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1#page=393">IMPLICIT AUTOMATIC</a>
-   </td>
-   <td>Default, see <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-automatic">AUTOMATIC</a> and <a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-static-1#408BC4E6-7AA7-4475-A280-205D34AE2E4F">STATIC</a>
-   </td>
-   <td><a href="https://www.pgroup.com/doc/pgi15fortref.pdf#page=86">Default</a>
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Allocate variables to static storage
-   </td>
-   <td>ev
-   </td>
-   <td>fno-automatic
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=258">qsave</a>
-   </td>
-   <td><a href="https://software.intel.com/node/3ed16417-6eed-4e09-9edd-4ae03e77c6cf">save</a>,
-<p>
-<a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-auto">noauto</a>
-   </td>
-   <td>Mnorecursive,
-<p>
-Msave
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Compile procedures as if RECURSIVE
-   </td>
-   <td>eR
-   </td>
-   <td>frecursive
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=254">q recur</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume recursion</a>,
-<p>
-<a href="https://software.intel.com/node/1c3820b4-42a1-48ea-887a-2cf39a41ce53">recursive</a>
-   </td>
-   <td>Mrecursive
-   </td>
-   <td>Mrecursive
-   </td>
-  </tr>
-</table>
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#arrays">Arrays</strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-  <tr>
-   <td>Enable coarrays
-   </td>
-   <td>h caf
-   </td>
-   <td>fcoarray=<em>key</em>
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-coarray-qcoarray">coarray[=keyword]</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Contiguous array pointers
-   </td>
-   <td>h contiguous
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=142">qassert=contig</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume contiguous_pointer</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Contiguous assumed shape dummy arguments
-   </td>
-   <td>h contiguous_assumed_shape
-   </td>
-   <td>frepack-arrays
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=142">qassert=contig</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-assume">assume contiguous_assumed_shape</a>
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong>OpenACC, OpenMP, and CUDA</strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Enable OpenACC
-   </td>
-   <td> <a href="https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/program-model-specific-options">h acc</a>
-   </td>
-   <td>fopenacc
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td><a href="https://www.pgroup.com/resources/docs/19.1/x86/pgi-ref-guide/index.htm#acc">acc</a>
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Enable OpenMP
-   </td>
-   <td> <a href="https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/program-model-specific-options">h omp</a>
-   </td>
-   <td>fopenmp
-   </td>
-   <td><a href="https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=285">qswapomp</a>
-   </td>
-   <td><a href="https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-qopenmp-qopenmp">qopenmp</a>,
-<p>
-<a href="https://software.intel.com/node/26d2aef3-9c68-4ef2-9241-bce168a48629">qopenmp-lib</a>,
-<p>
-<a href="https://software.intel.com/node/f8d22e40-7ed0-4ec6-8e80-d4d27010ca8b">qopenmp-link</a>,
-<p>
-<a href="https://software.intel.com/node/2cc99a64-9605-44e2-b40a-1409ba459a62">qopenmp-offload</a>,
-<p>
-<a href="https://software.intel.com/node/02ef8658-3e66-4634-8a11-68eec60322c1">qopenmp-simd</a>,
-<p>
-<a href="https://software.intel.com/node/088272f2-5eae-42c2-a053-20f42022343d">qopenmp-stubs</a>,
-<p>
-<a href="https://software.intel.com/node/0ed8bee0-62b4-4266-8cbb-f25b585d4800">qopenmp-threadprivate</a>
-   </td>
-   <td><a href="https://www.pgroup.com/resources/docs/19.1/x86/pgi-ref-guide/index.htm#mp">mp</a>,
-<p>
-Mcuda
-   </td>
-   <td>-mp
-   </td>
-  </tr>
-</table>
-
-
-
-<table>
-  <tr>
-   <td colspan="7" ><strong><a href="#miscellaneous">Miscellaneous</a></strong>
-   </td>
-  </tr>
-  <tr>
-   <td><strong>Option</strong>
-   </td>
-   <td><strong>Cray</strong>
-   </td>
-   <td><strong>GNU</strong>
-   </td>
-   <td><strong>IBM</strong>
-   </td>
-   <td><strong>Intel</strong>
-   </td>
-   <td><strong>PGI</strong>
-   </td>
-   <td><strong>Flang</strong>
-   </td>
-  </tr>
-  <tr>
-   <td>Disable compile time range checking
-   </td>
-   <td> N/A
-   </td>
-   <td>fno-range-check
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Disable call site checking
-   </td>
-   <td>dC
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Warn for bad call checking
-   </td>
-   <td>eb
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Set default accessibility of module entities to PRIVATE
-   </td>
-   <td>N/A
-   </td>
-   <td>fmodule-private
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-  <tr>
-   <td>Force FORALL to use temp
-   </td>
-   <td>N/A
-   </td>
-   <td>ftest-forall-temp
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-   <td>N/A
-   </td>
-  </tr>
-</table>
-
-
-
-## <a name="notes"></a>Notes
-
-**<a name="standards"></a>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._
-
-**<a name="source"></a>Source format:** 
-
-**Fixed or free source:**  Cray, IBM, and Intel default the source format based on the source file suffix as follows:
-
-
-
-*   **Cray**
-    *   **Free:** .f90, .F90, .f95, .F95, .f03, .F03, .f08, .F08, .ftn, .FTN
-    *   **Fixed:** .f, .F, .for, .FOR
-*   **Intel**
-    *   **Free:** .f90, .F90, .i90
-    *   **Fixed:** .f, .for, .FOR, .ftn, .FTN, .fpp, .FPP, .i
-
-IBM Fortran's options allow the source line length to be specified with the option, e.g., "-qfixed=72".  IBM bases the default on the name of the command used to invoke the compiler.  IBM has 16 different commands that invoke the Fortran compiler, and the default use of free or fixed format and the line length are based on the command name.  -qfixed=72 is the default for the xlf, xlf_r, f77, and fort77 commands. -qfree=f90is the default for the f90, xlf90, xlf90_r, f95, xlf95, xlf95_r, f2003, xlf2003, xlf2003_r, f2008, xlf2008, and xlf2008_r commands.  The maximum line length for either source format is 132 characters.
-
-**Column 1 comment specifier:**  All compilers allow "D" in column 1 to specify that the line contains a comment and have this as the default for fixed format source.  IBM also supports an "X" in column 1 with the option "-qxlines".
-
-**Source line length:**
-
-
-*   **Cray:** The "-N _col_" option specifies the line width for fixed- and free-format source lines. The value used for col specifies the maximum number of columns per line.  For free form sources, col can be set to 132, 255, or 1023.  For fixed form sources, col can be set to 72, 80, 132, 255, or 1023.  Characters in columns beyond the col specification are ignored.  By default, lines are 72 characters wide for fixed-format sources and 255 characters wide for free-form sources.
-*   **GNU:** For both "ffixed-line-length-_n_" and "ffree-line-length-_n_" options, characters are ignored after the specified length.  The default for fixed is 72.  The default for free is 132.  For free, you can specify 'none' as the length, which means that all characters in the line are meaningful.
-*   **IBM:** For **fixed**, the default is 72.  For **free**, there's no default, but the maximum length for either form is 132.
-*   **Intel:** The default is 72 for **fixed** and 132 for **free**.
-*   **PGI, Flang:** 
-    * in free form, it is an error if the line is longer than 1000 characters
-    * in fixed form by default, characters after column 72 are ignored
-    * in fixed form with -Mextend, characters after column 132 are ignored
-
-**<a name="names"></a>Names, Literals, and other tokens**
-
-**Escapes in literals:**
-
-
-*   **GNU:** The "-fbackslash" option the interpretation of backslashes in string literals from a single backslash character to "C-style" escape characters. The following combinations are expanded \a, \b, \f, \n, \r, \t, \v, \\, and \0 to the ASCII characters alert, backspace, form feed, newline, carriage return, horizontal tab, vertical tab, backslash, and NUL, respectively. Additionally, \xnn, \unnnn and \Unnnnnnnn (where each n is a hexadecimal digit) are translated into the Unicode characters corresponding to the specified code points. All other combinations of a character preceded by \ are unexpanded.
-*   **Intel:** The option "-assume bscc" tells the compiler to treat the backslash character (\) as a C-style control (escape) character syntax in character literals. "nobscc" specifies that the backslash character is treated as a normal character in character literals.  This is the default.
-
-**"$" in symbol names:** Allowing "$" in names is controlled by an option in GNU and is the default behavior in IBM and Intel.  Presumably, these compilers issue warnings when standard conformance options are enabled.  Dollar signs in names don't seem to be allowed in Cray, PGI, or Flang.
-
-**<a name="do"></a>DO loop handling**
-
-**One trip:**
-
-
-
-*   **IBM:** IBM has two options that do the same thing: "-1" and "-qonetrip".
-*   **Intel:** Intel used to support a "-onetrip" option, but it has been removed.  Intel now supports a "-f66" option that ensures that DO loops are executed at least once in addition to [several other Fortran 66 semantic features](https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-f66#320D769C-7C41-4A84-AE0E-50A72296A838).
-
-**<a name="real"></a>REAL, DOUBLE PRECISION, and COMPLEX Data**
-
-These size options affect the sizes of variables, literals, and intrinsic function results.
-
-**Default REAL sizes:** These options do not affect the size of explicitly declared data (for example, REAL(KIND=4).
-
-
-
-*   **Cray:** The "-s default32" and "-s default64" options affect both REAL, INTEGER, and LOGICAL types.
-
-**Default DOUBLE PRECISION:** These options allow control of the size of DOUBLE PRECISION types in conjunction with controlling REAL types.
-
-
-
-*   **Cray:** The "-ep" option controls DOUBLE PRECISION. This option can only be enabled when the default data size is 64 bits ("-s default64" or "-s real64").  When "-s default64" or "-s real64" is specified, and double precision arithmetic is disabled, DOUBLE PRECISION variables and constants specified with the D exponent are converted to default real type (64-bit). If double precision is enabled ("-ep"), they are handled as a double precision type (128-bit).  Similarly when the "-s default64" or" -s real64" option is used, variables declared on a DOUBLE COMPLEX statement and complex constants specified with the D exponent are mapped to the complex type in which each part has a default real type, so the complex variable is 128-bit. If double precision is enabled ("-ep"), each part has double precision type, so the double complex variable is 256-bit.
-*   **GNU:** The "-fdefault-double-8" option sets the DOUBLE PRECISION type to an 8 byte wide type. Do nothing if this is already the default. If "-fdefault-real-8" is given, DOUBLE PRECISION would instead be promoted to 16 bytes if possible, and "-fdefault-double-8" can be used to prevent this. The kind of real constants like 1.d0 will not be changed by "-fdefault-real-8" though, so also "-fdefault-double-8" does not affect it.
-
-**Promote or demote REAL type sizes:** These options change the meaning of data types specified by declarations of the form REAL(KIND=_N_), except, perhaps for PGI.
-
-*   **GNU:** The allowable combinations are "-freal-4-real-8", "-freal-4-real-10", "-freal-4-real-16", "-freal-8-real-4", "-freal-8-real-10", and "-freal-8-real-16".
-*   **IBM:** The "-qautodbl" option  is documented [here](https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=144).
-*   **PGI:** The "-Mr8" option promotes REAL variables and constants to DOUBLE PRECISION variables and constants, respectively. DOUBLE PRECISION elements are 8 bytes in length.  The "-Mr8intrinsics" option promotes the intrinsics CMPLX and REAL as DCMPLX and DBLE, respectively.
-
-**<a name="integer"></a>INTEGER and LOGICAL Data**
-
-These size options affect the sizes of variables, literals, and intrinsic function results.
-
-**Default INTEGER sizes:** For all compilers, these options affect both INTEGER and LOGICAL types.
-
-**Enable 8 and 16 bit INTEGER and LOGICAL:** This Cray option ("-eh") enables support for 8-bit and 16-bit INTEGER and LOGICAL types that use explicit kind or star values.  By default ("-eh"), data objects declared as INTEGER(kind=1) or LOGICAL(kind=1) are 8 bits long, and objects declared as INTEGER(kind=2) or LOGICAL(kind=2) are 16 bits long. When this option is disabled ("-dh"), data objects declared as INTEGER(kind=1), INTEGER(kind=2), LOGICAL(kind=1), or LOGICAL(kind=2) are 32 bits long.
-
-**Intrinsic functions**
-
-GNU is the only compiler with options governing the use of non-standard intrinsics.  For more information on the GNU options, see [here](https://gcc.gnu.org/onlinedocs/gcc-8.3.0/gfortran/Fortran-Dialect-Options.html#Fortran-Dialect-Options).  All compilers implement non-standard intrinsics but don't have options that affect access to them.
-
-**<a name="arrays"></a>Arrays**
-
-**Contiguous array pointers:** All vendors that implement this option (Cray, IBM, and Intel) seem to have apply to all pointer targets.  Assuming that the arrays that are targeted by the pointers allows greater optimization.
-
-**Contiguous assumed shape dummy arguments:** Cray and Intel have a separate argument that's specific to assumed shape dummy arguments.
-
-**<a name="miscellaneous"></a>Miscellaneous**
-
-**Disable call site checking:**  This Cray option ("-dC") disables some types of standard call site checking. The current Fortran standard requires that the number and types of arguments must agree between the caller and callee. These constraints are enforced in cases where the compiler can detect them, however, specifying "-dC" disables some of this error checking, which may be necessary in order to get some older Fortran codes to compile.  If error checking is disabled, unexpected compile-time or run time results may occur.  The compiler by default attempts to detect situations in which an interface block should be specified but is not. Specifying "-dC" disables this type of checking as well.
-
-**Warn for bad call checking**: This Cray option ("-eb") issues a warning message rather than an error message when the compiler detects a call to a procedure with one or more dummy arguments having the TARGET, VOLATILE or ASYNCHRONOUS attribute and there is not an explicit interface definition.
-
-
-## Notes
-
-
-### What is and is not included
-
-This document focuses on options relevant to the Fortran language.  This includes some features (such as recursion) that are only indirectly related.  Options related to the following areas are not included:
-
-
-
-*   Input/Output
-*   Optimization
-*   Preprocessing
-*   Inlining
-*   Alternate library definition or linking
-*   Choosing file locations for compiler input or output
-*   Modules
-*   Warning and error messages and listing output
-*   Data initialization
-*   Run time checks
-*   Debugging
-*   Specification of operating system
-*   Target architecture
-*   Assembler generation
-*   Threads or parallelization
-*   Profiling and code coverage
-
-
-### Data sources
-
-Here's the list of compilers surveyed, hot linked to the source of data on it.  Note that this is the only mention of the Oracle and NAG compilers in this document.
-
-
-
-*   [Cray Fortran Reference Manual version 8.7](https://pubs.cray.com/content/S-3901/8.7/cray-fortran-reference-manual/compiler-command-line-options)
-*   IBM  (XLF) version 14.1 -- [Compiler Referenc](https://www-01.ibm.com/support/docview.wss?uid=swg27024803&aid=1#page=93)e, [Language Reference](https://www-01.ibm.com/support/docview.wss?uid=swg27024776&aid=1)
-*   [Intel Fortran version 19.0](https://software.intel.com/en-us/fortran-compiler-developer-guide-and-reference-alphabetical-list-of-compiler-options)
-*   [GNU Fortran Compiler version 8.3.0](https://gcc.gnu.org/onlinedocs/gcc-8.3.0/gfortran/Option-Summary.html)
-*   [NAG Fortran Release 6.2](https://www.nag.co.uk/nagware/np/r62_doc/manual/compiler_2_4.html)
-*   [Oracle Fortran version 819-0492-10](https://docs.oracle.com/cd/E19059-01/stud.10/819-0492/3_options.html)
-*   PGI -- [Compiler Reference version 19.1](https://www.pgroup.com/resources/docs/19.1/x86/pgi-ref-guide/index.htm#cmdln-options-ref), [Fortran Reference Guide version 17](https://www.pgroup.com/doc/pgi17fortref.pdf)
-*   [Flang](https://github.com/flang-compiler/flang/wiki/Using-Flang) -- information from GitHub
-
-This document has been kept relatively small by providing links to much of the information about options rather than duplicating that information.  For IBM, Intel, and some PGI options, there are direct links.  But direct links were not possible for Cray, GNU and some PGI options.
-
-Many compilers have options that can either be enabled or disabled.  Some compilers indicate this by the presence or absence of the letters "no" in the option name (IBM, Intel, and PGI) while Cray precedes many options with either "e" for enabled or "d" for disabled.  This document only includes the enabled version of the option specification.
-
-Deprecated options were generally ignored, even though they were documented.

flang/documentation/Overview.md

-<!--===- documentation/Overview.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
-  
--->
-
-# Overview of Compiler Phases
-
-Each phase produces either correct output or fatal errors.
-
-## Prescan and Preprocess
-
-See: [Preprocessing.md](Preprocessing.md).
-
-**Input:** Fortran source and header files, command line macro definitions,
-  set of enabled compiler directives (to be treated as directives rather than
-  comments).
-
-**Output:**
-- A "cooked" character stream: the entire program as a contiguous stream of
-  normalized Fortran source.
-  Extraneous whitespace and comments are removed (except comments that are
-  compiler directives that are not disabled) and case is normalized.
-- Provenance information mapping each character back to the source it came from.
-  This is used in subsequent phases to issue errors messages that refer to source locations.
-
-**Entry point:** `parser::Parsing::Prescan`
-
-**Command:** `f18 -E src.f90` dumps the cooked character stream
-
-## Parse
-
-**Input:** Cooked character stream.
-
-**Output:** A parse tree representing a syntactically correct program,
-  rooted at a `parser::Program`.
-  See: [Parsing.md](Parsing.md) and [ParserCombinators.md](ParserCombinators.md).
-
-**Entry point:** `parser::Parsing::Parse`
-
-**Command:**
-  - `f18 -fdebug-dump-parse-tree -fparse-only src.f90` dumps the parse tree
-  - `f18 -funparse src.f90` converts the parse tree to normalized Fortran
-
-## Validate Labels and Canonicalize Do Statements
-
-**Input:** Parse tree.
-
-**Output:** The parse tree with label constraints and construct names checked,
-  and each `LabelDoStmt` converted to a `NonLabelDoStmt`.
-  See: [LabelResolution.md](LabelResolution.md).
-
-**Entry points:** `semantics::ValidateLabels`, `parser::CanonicalizeDo`
-
-## Resolve Names
-
-**Input:** Parse tree (without `LabelDoStmt`) and `.mod` files from compilation
-  of USEd modules.
-
-**Output:**
-- Tree of scopes populated with symbols and types
-- Parse tree with some refinements:
-  - each `parser::Name::symbol` field points to one of the symbols
-  - each `parser::TypeSpec::declTypeSpec` field points to one of the types
-  - array element references that were parsed as function references or
-    statement functions are corrected
-
-**Entry points:** `semantics::ResolveNames`, `semantics::RewriteParseTree`
-
-**Command:** `f18 -fdebug-dump-symbols -fparse-only src.f90` dumps the
-  tree of scopes and symbols in each scope
-
-## Check DO CONCURRENT Constraints
-
-**Input:** Parse tree with names resolved.
-
-**Output:** Parse tree with semantically correct DO CONCURRENT loops.
-
-## Write Module Files
-
-**Input:** Parse tree with names resolved.
-
-**Output:** For each module and submodule, a `.mod` file containing a minimal
-  Fortran representation suitable for compiling program units that depend on it.
-  See [ModFiles.md](ModFiles.md).
-
-## Analyze Expressions and Assignments
-
-**Input:** Parse tree with names resolved.
-
-**Output:** Parse tree with `parser::Expr::typedExpr` filled in and semantic
-  checks performed on all expressions and assignment statements.
-
-**Entry points**: `semantics::AnalyzeExpressions`, `semantics::AnalyzeAssignments`
-
-## Produce the Intermediate Representation
-
-**Input:** Parse tree with names and labels resolved.
-
-**Output:** An intermediate representation of the executable program.
-  See [FortranIR.md](FortranIR.md).

flang/documentation/ParserCombinators.md

-<!--===- documentation/ParserCombinators.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
-  
--->
-
-## Concept
-The Fortran language recognizer here can be classified as an LL recursive
-descent parser.  It is composed from a *parser combinator* library that
-defines a few fundamental parsers and a few ways to compose them into more
-powerful parsers.
-
-For our purposes here, a *parser* is any object that attempts to recognize
-an instance of some syntax from an input stream.  It may succeed or fail.
-On success, it may return some semantic value to its caller.
-
-In C++ terms, a parser is any instance of a class that
-1. has a `constexpr` default constructor,
-1. defines a type named `resultType`, and
-1. provides a function (`const` member or `static`) that accepts a reference to a
-`ParseState` as its argument and returns a `std::optional<resultType>` as a
-result, with the presence or absence of a value in the `std::optional<>`
-signifying success or failure, respectively.
-```
-std::optional<resultType> Parse(ParseState &) const;
-```
-The `resultType` of a parser is typically the class type of some particular
-node type in the parse tree.
-
-`ParseState` is a class that encapsulates a position in the source stream,
-collects messages, and holds a few state flags that determine tokenization
-(e.g., are we in a character literal?).  Instances of `ParseState` are
-independent and complete -- they are cheap to duplicate whenever necessary to
-implement backtracking.
-
-The `constexpr` default constructor of a parser is important.  The functions
-(below) that operate on instances of parsers are themselves all `constexpr`.
-This use of compile-time expressions allows the entirety of a recursive
-descent parser for a language to be constructed at compilation time through
-the use of templates.
-
-### Fundamental Predefined Parsers
-These objects and functions are (or return) the fundamental parsers:
-
-* `ok` is a trivial parser that always succeeds without advancing.
-* `pure(x)` returns a trivial parser that always succeeds without advancing,
-  returning some value `x`.
-* `pure<T>()` is `pure(T{})` but does not require that T be copy-constructible.
-* `fail<T>(msg)` denotes a trivial parser that always fails, emitting the
-  given message as a side effect.  The template parameter is the type of
-  the value that the parser never returns.
-* `nextCh` consumes the next character and returns its location,
-  and fails at EOF.
-* `"xyz"_ch` succeeds if the next character consumed matches any of those
-  in the string and returns its location.  Be advised that the source
-  will have been normalized to lower case (miniscule) letters outside
-  character and Hollerith literals and edit descriptors before parsing.
-
-### Combinators
-These functions and operators combine existing parsers to generate new parsers.
-They are `constexpr`, so they should be viewed as type-safe macros.
-
-* `!p` succeeds if p fails, and fails if p succeeds.
-* `p >> q` fails if p does, otherwise running q and returning its value when
-  it succeeds.
-* `p / q` fails if p does, otherwise running q and returning p's value
-  if q succeeds.
-* `p || q` succeeds if p does, otherwise running q.  The two parsers must
-  have the same type, and the value returned by the first succeeding parser
-  is the value of the combination.
-* `first(p1, p2, ...)` returns the value of the first parser that succeeds.
-  All of the parsers in the list must return the same type.
-  It is essentially the same as `p1 || p2 || ...` but has a slightly
-  faster implementation and may be easier to format in your code.
-* `lookAhead(p)` succeeds if p does, but doesn't modify any state.
-* `attempt(p)` succeeds if p does, safely preserving state on failure.
-* `many(p)` recognizes a greedy sequence of zero or more nonempty successes
-  of p, and returns `std::list<>` of their values.  It always succeeds.
-* `some(p)` recognized a greedy sequence of one or more successes of p.
-  It fails if p immediately fails.
-* `skipMany(p)` is the same as `many(p)`, but it discards the results.
-* `maybe(p)` tries to match p, returning an `std::optional<T>` value.
-  It always succeeds.
-* `defaulted(p)` matches p, and when p fails it returns a
-  default-constructed instance of p's resultType.  It always succeeds.
-* `nonemptySeparated(p, q)` repeatedly matches "p q p q p q ... p",
-  returning a `std::list<>` of only the values of the p's.  It fails if
-  p immediately fails.
-* `extension(p)` parses p if strict standard compliance is disabled,
-   or with a warning if nonstandard usage warnings are enabled.
-* `deprecated(p)` parses p if strict standard compliance is disabled,
-  with a warning if deprecated usage warnings are enabled.
-* `inContext(msg, p)` runs p within an error message context; any
-  message that `p` generates will be tagged with `msg` as its
-  context.  Contexts may nest.
-* `withMessage(msg, p)` succeeds if `p` does, and if it does not,
-  it discards the messages from `p` and fails with the specified message.
-* `recovery(p, q)` is equivalent to `p || q`, except that error messages
-  generated from the first parser are retained, and a flag is set in
-  the ParseState to remember that error recovery was necessary.
-* `localRecovery(msg, p, q)` is equivalent to
-  `recovery(withMessage(msg, p), q >> pure<A>())` where `A` is the
-  result type of 'p'.
-  It is useful for targeted error recovery situations within statements.
-
-Note that
-```
-a >> b >> c / d / e
-```
-matches a sequence of five parsers, but returns only the result that was
-obtained by matching `c`.
-
-### Applicatives
-The following *applicative* combinators combine parsers and modify or
-collect the values that they return.
-
-* `construct<T>(p1, p2, ...)` matches zero or more parsers in succession,
-  collecting their results and then passing them with move semantics to a
-  constructor for the type T if they all succeed.
-  If there is a single parser as the argument and it returns no usable
-  value but only success or failure (_e.g.,_ `"IF"_tok`), the default
-  nullary constructor of the type `T` is called.
-* `sourced(p)` matches p, and fills in its `source` data member with the
-  locations of the cooked character stream that it consumed
-* `applyFunction(f, p1, p2, ...)` matches one or more parsers in succession,
-  collecting their results and passing them as rvalue reference arguments to
-  some function, returning its result.
-* `applyLambda([](&&x){}, p1, p2, ...)` is the same thing, but for lambdas
-  and other function objects.
-* `applyMem(mf, p1, p2, ...)` is the same thing, but invokes a member
-  function of the result of the first parser for updates in place.
-
-### Token Parsers
-Last, we have these basic parsers on which the actual grammar of the Fortran
-is built.  All of the following parsers consume characters acquired from
-`nextCh`.
-
-* `space` always succeeds after consuming any spaces
-* `spaceCheck` always succeeds after consuming any spaces, and can emit
-  a warning if there was no space in free form code before a character
-  that could continue a name or keyword
-* `digit` matches one cooked decimal digit (0-9)
-* `letter` matches one cooked letter (A-Z)
-* `"..."_tok` match the content of the string, skipping spaces before and
-  after.  Internal spaces are optional matches.  The `_tok` suffix is
-  optional when the parser appears before the combinator `>>` or after
-  the combinator `/`.
-* `"..."_sptok` is a string match in which the spaces are required in
-   free form source.
-* `"..."_id` is a string match for a complete identifier (not a prefix of
-   a longer identifier or keyword).
-* `parenthesized(p)` is shorthand for `"(" >> p / ")"`.
-* `bracketed(p)` is shorthand for `"[" >> p / "]"`.
-* `nonEmptyList(p)` matches a comma-separated list of one or more
-  instances of p.
-* `nonEmptyList(errorMessage, p)` is equivalent to
-  `withMessage(errorMessage, nonemptyList(p))`, which allows one to supply
-  a meaningful error message in the event of an empty list.
-* `optionalList(p)` is the same thing, but can be empty, and always succeeds.
-
-### Debugging Parser
-Last, a string literal `"..."_debug` denotes a parser that emits the string to
-`llvm::errs` and succeeds.  It is useful for tracing while debugging a parser but should
-obviously not be committed for production code.

flang/documentation/Preprocessing.md

-<!--===- documentation/Preprocessing.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
-  
--->
-
-Fortran Preprocessing
-=====================
-
-Behavior common to (nearly) all compilers:
-------------------------------------------
-* Macro and argument names are sensitive to case.
-* Fixed form right margin clipping after column 72 (or 132)
-  has precedence over macro name recognition, and also over
-  recognition of function-like parentheses and arguments.
-* Fixed form right margin clipping does not apply to directive lines.
-* Macro names are not recognized as such when spaces are inserted
-  into their invocations in fixed form.
-  This includes spaces at the ends of lines that have been clipped
-  at column 72 (or whatever).
-* Text is rescanned after expansion of macros and arguments.
-* Macros are not expanded within quoted character literals or
-  quoted FORMAT edit descriptors.
-* Macro expansion occurs before any effective token pasting via fixed form
-  space removal.
-* C-like line continuations with backslash-newline are allowed in
-  directives, including the definitions of macro bodies.
-* `/* Old style C comments */` are ignored in directives and
-  removed from the bodies of macro definitions.
-* `// New style C comments` are not removed, since Fortran has OPERATOR(//).
-* C-like line continuations with backslash-newline can appear in
-  old-style C comments in directives.
-* After `#define FALSE TRUE`, `.FALSE.` is replaced by `.TRUE.`;
-  i.e., tokenization does not hide the names of operators or logical constants.
-* `#define KWM c` allows the use of `KWM` in column 1 as a fixed form comment
-  line indicator.
-* A `#define` directive intermixed with continuation lines can't
-  define a macro that's invoked earlier in the same continued statement.
-
-Behavior that is not consistent over all extant compilers but which
-probably should be uncontroversial:
------------------------------------
-* Invoked macro names can straddle a Fortran line continuation.
-* ... unless implicit fixed form card padding intervenes; i.e.,
-  in fixed form, a continued macro name has to be split at column
-  72 (or 132).
-* Comment lines may appear with continuations in a split macro names.
-* Function-like macro invocations can straddle a Fortran fixed form line
-  continuation between the name and the left parenthesis, and comment and
-  directive lines can be there too.
-* Function-like macro invocations can straddle a Fortran fixed form line
-  continuation between the parentheses, and comment lines can be there too.
-* Macros are not expanded within Hollerith constants or Hollerith
-  FORMAT edit descriptors.
-* Token pasting with `##` works in function-like macros.
-* Argument stringization with `#` works in function-like macros.
-* Directives can be capitalized (e.g., `#DEFINE`) in fixed form.
-* Fixed form clipping after column 72 or 132 is done before macro expansion,
-  not after.
-* C-like line continuation with backslash-newline can appear in the name of
-  a keyword-like macro definition.
-* If `#` is in column 6 in fixed form, it's a continuation marker, not a
-  directive indicator.
-* `#define KWM !` allows KWM to signal a comment.
-
-Judgement calls, where precedents are unclear:
-----------------------------------------------
-* Expressions in `#if` and `#elif` should support both Fortran and C
-  operators; e.g., `#if 2 .LT. 3` should work.
-* If a function-like macro does not close its parentheses, line
-  continuation should be assumed.
-* ... However, the leading parenthesis has to be on the same line as
-  the name of the function-like macro, or on a continuation line thereof.
-* If macros expand to text containing `&`, it doesn't work as a free form
-  line continuation marker.
-* `#define c 1` does not allow a `c` in column 1 to be used as a label
-  in fixed form, rather than as a comment line indicator.
-* IBM claims to be ISO C compliant and therefore recognizes trigraph sequences.
-* Fortran comments in macro actual arguments should be respected, on
-  the principle that a macro call should work like a function reference.
-* If a `#define` or `#undef` directive appears among continuation
-  lines, it may or may not affect text in the continued statement that
-  appeared before the directive.
-
-Behavior that few compilers properly support (or none), but should:
--------------------------------------------------------------------
-* A macro invocation can straddle free form continuation lines in all of their
-  forms, with continuation allowed in the name, before the arguments, and
-  within the arguments.
-* Directives can be capitalized in free form, too.
-* `__VA_ARGS__` and `__VA_OPT__` work in variadic function-like macros.
-
-In short, a Fortran preprocessor should work as if:
----------------------------------------------------
-1. Fixed form lines are padded up to column 72 (or 132) and clipped thereafter.
-2. Fortran comments are removed.
-3. C-style line continuations are processed in preprocessing directives.
-4. C old-style comments are removed from directives.
-5. Fortran line continuations are processed (outside preprocessing directives).
-   Line continuation rules depend on source form.
-   Comment lines that are enabled compiler directives have their line
-   continuations processed.
-   Conditional compilation preprocessing directives (e.g., `#if`) may be
-   appear among continuation lines, and have their usual effects upon them.
-6. Other preprocessing directives are processed and macros expanded.
-   Along the way, Fortran `INCLUDE` lines and preprocessor `#include` directives
-   are expanded, and all these steps applied recursively to the introduced text.
-7. Any Fortran comments created by macro replacement are removed.
-
-Steps 5 and 6 are interleaved with respect to the preprocessing state.
-Conditional compilation preprocessing directives always reflect only the macro
-definition state produced by the active `#define` and `#undef` preprocessing directives
-that precede them.
-
-If the source form is changed by means of a compiler directive (i.e.,
-`!DIR$ FIXED` or `FREE`) in an included source file, its effects cease
-at the end of that file.
-
-Last, if the preprocessor is not integrated into the Fortran compiler,
-new Fortran continuation line markers should be introduced into the final
-text.
-
-OpenMP-style directives that look like comments are not addressed by
-this scheme but are obvious extensions.
-
-Appendix
-========
-`N` in the table below means "not supported"; this doesn't
-mean a bug, it just means that a particular behavior was
-not observed.
-`E` signifies "error reported".
-
-The abbreviation `KWM` stands for "keyword macro" and `FLM` means
-"function-like macro".
-
-The first block of tests (`pp0*.F`) are all fixed-form source files;
-the second block (`pp1*.F90`) are free-form source files.
-
-```
-f18
-| pgfortran
-| | ifort
-| | | gfortran
-| | | | xlf
-| | | | | nagfor
-| | | | | |
-. . . . . .   pp001.F  keyword macros
-. . . . . .   pp002.F  #undef
-. . . . . .   pp003.F  function-like macros
-. . . . . .   pp004.F  KWMs case-sensitive
-. N . N N .   pp005.F  KWM split across continuation, implicit padding
-. N . N N .   pp006.F  ditto, but with intervening *comment line
-N N N N N N   pp007.F  KWM split across continuation, clipped after column 72
-. . . . . .   pp008.F  KWM with spaces in name at invocation NOT replaced
-. N . N N .   pp009.F  FLM call split across continuation, implicit padding
-. N . N N .   pp010.F  ditto, but with intervening *comment line
-N N N N N N   pp011.F  FLM call name split across continuation, clipped
-. N . N N .   pp012.F  FLM call name split across continuation
-. E . N N .   pp013.F  FLM call split between name and (
-. N . N N .   pp014.F  FLM call split between name and (, with intervening *comment
-. E . N N .   pp015.F  FLM call split between name and (, clipped
-. E . N N .   pp016.F  FLM call split between name and ( and in argument
-. . . . . .   pp017.F  KLM rescan
-. . . . . .   pp018.F  KLM rescan with #undef (so rescan is after expansion)
-. . . . . .   pp019.F  FLM rescan
-. . . . . .   pp020.F  FLM expansion of argument
-. . . . . .   pp021.F  KWM NOT expanded in 'literal'
-. . . . . .   pp022.F  KWM NOT expanded in "literal"
-. . E E . E   pp023.F  KWM NOT expanded in 9HHOLLERITH literal
-. . . E . .   pp024.F  KWM NOT expanded in Hollerith in FORMAT
-. . . . . .   pp025.F  KWM expansion is before token pasting due to fixed-form space removal
-. . . E . E   pp026.F  ## token pasting works in FLM
-E . . E E .   pp027.F  #DEFINE works in fixed form
-. N . N N .   pp028.F  fixed-form clipping done before KWM expansion on source line
-. . . . . .   pp029.F  \ newline allowed in #define
-. . . . . .   pp030.F  /* C comment */ erased from #define
-E E E E E E   pp031.F   // C++ comment NOT erased from #define
-. . . . . .   pp032.F  /* C comment */ \ newline erased from #define
-. . . . . .   pp033.F  /* C comment \ newline */ erased from #define
-. . . . . N   pp034.F  \ newline allowed in name on KWM definition
-. E . E E .   pp035.F  #if 2 .LT. 3 works
-. . . . . .   pp036.F  #define FALSE TRUE ...  .FALSE. -> .TRUE.
-N N N N N N   pp037.F  fixed-form clipping NOT applied to #define
-. . E . E E   pp038.F  FLM call with closing ')' on next line (not a continuation)
-E . E . E E   pp039.F  FLM call with '(' on next line (not a continuation)
-. . . . . .   pp040.F  #define KWM c, then KWM works as comment line initiator
-E . E . . E   pp041.F  use KWM expansion as continuation indicators
-N N N . . N   pp042.F  #define c 1, then use c as label in fixed-form
-. . . . N .   pp043.F  #define with # in column 6 is a continuation line in fixed-form
-E . . . . .   pp044.F  #define directive amid continuations
-. . . . . .   pp101.F90  keyword macros
-. . . . . .   pp102.F90  #undef
-. . . . . .   pp103.F90  function-like macros
-. . . . . .   pp104.F90  KWMs case-sensitive
-. N N N N N   pp105.F90  KWM call name split across continuation, with leading &
-. N N N N N   pp106.F90  ditto, with & ! comment
-N N E E N .   pp107.F90  KWM call name split across continuation, no leading &, with & ! comment
-N N E E N .   pp108.F90  ditto, but without & ! comment
-. N N N N N   pp109.F90  FLM call name split with leading &
-. N N N N N   pp110.F90  ditto, with & ! comment
-N N E E N .   pp111.F90  FLM call name split across continuation, no leading &, with & ! comment
-N N E E N .   pp112.F90  ditto, but without & ! comment
-. N N N N E   pp113.F90  FLM call split across continuation between name and (, leading &
-. N N N N E   pp114.F90  ditto, with & ! comment, leading &
-N N N N N .   pp115.F90  ditto, with & ! comment, no leading &
-N N N N N .   pp116.F90  FLM call split between name and (, no leading &
-. . . . . .   pp117.F90  KWM rescan
-. . . . . .   pp118.F90  KWM rescan with #undef, proving rescan after expansion
-. . . . . .   pp119.F90  FLM rescan
-. . . . . .   pp120.F90  FLM expansion of argument
-. . . . . .   pp121.F90  KWM NOT expanded in 'literal'
-. . . . . .   pp122.F90  KWM NOT expanded in "literal"
-. . E E . E   pp123.F90  KWM NOT expanded in Hollerith literal
-. . E E . E   pp124.F90  KWM NOT expanded in Hollerith in FORMAT
-E . . E E .   pp125.F90  #DEFINE works in free form
-. . . . . .   pp126.F90  \ newline works in #define
-N . E . E E   pp127.F90  FLM call with closing ')' on next line (not a continuation)
-E . E . E E   pp128.F90  FLM call with '(' on next line (not a continuation)
-. . N . . N   pp129.F90  #define KWM !, then KWM works as comment line initiator
-E . E . . E   pp130.F90  #define KWM &, use for continuation w/o pasting (ifort and nag seem to continue #define)
-```

flang/documentation/PullRequestChecklist.md

-<!--===- documentation/PullRequestChecklist.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
-
--->
-
-# Pull request checklist
-Please review the following items before submitting a pull request.  This list
-can also be used when reviewing pull requests.
-*  Verify that new files have a license with correct file name.
-*  Run `git diff` on all modified files to look for spurious changes such as
-   `#include <iostream>`.
-*  If you added code that causes the compiler to emit a new error message, make
-   sure that you also added a test that causes that error message to appear
-   and verifies its correctness.
-*  Annotate the code and tests with appropriate references to constraint and
-   requirement numbers from the Fortran standard.  Do not include the text of
-   the constraint or requirement, just its number.
-*  Alphabetize arbitrary lists of names.
-*  Check dereferences of pointers and optionals where necessary.
-*  Ensure that the scopes of all functions and variables are as local as
-   possible.
-*  Try to make all functions fit on a screen (40 lines).
-*  Build and test with both GNU and clang compilers.
-*  When submitting an update to a pull request, review previous pull request
-   comments and make sure that you've actually made all of the changes that
-   were requested.
-
-## 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.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/documentation/Semantics.md

-<!--===- documentation/Semantics.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
-  
--->
-
-# Semantic Analysis
-
-The semantic analysis pass determines if a syntactically correct Fortran
-program is is legal by enforcing the constraints of the language.
-
-The input is a parse tree with a `Program` node at the root;
-and a "cooked" character stream, a contiguous stream of characters
-containing a normalized form of the Fortran source.
-
-The semantic analysis pass takes a parse tree for a syntactically
-correct Fortran program and determines whether it is legal by enforcing
-the constraints of the language.
-
-If the program is not legal, the results of the semantic pass will be a list of
-errors associated with the program.
-
-If the program is legal, the semantic pass will produce a (possibly modified)
-parse tree for the semantically correct program with each name mapped to a symbol
-and each expression fully analyzed.
-
-All user errors are detected either prior to or during semantic analysis.
-After it completes successfully the program should compile with no error messages.
-There may still be warnings or informational messages.
-
-## Phases of Semantic Analysis
-
-1. [Validate labels](#validate-labels) -
-   Check all constraints on labels and branches
-2. [Rewrite DO loops](#rewrite-do-loops) -
-   Convert all occurrences of `LabelDoStmt` to `DoConstruct`.
-3. [Name resolution](#name-resolution) -
-   Analyze names and declarations, build a tree of Scopes containing Symbols,
-   and fill in the `Name::symbol` data member in the parse tree
-4. [Rewrite parse tree](#rewrite-parse-tree) -
-   Fix incorrect parses based on symbol information
-5. [Expression analysis](#expression-analysis) -
-   Analyze all expressions in the parse tree and fill in `Expr::typedExpr` and
-   `Variable::typedExpr` with analyzed expressions; fix incorrect parses
-   based on the result of this analysis
-6. [Statement semantics](#statement-semantics) -
-   Perform remaining semantic checks on the execution parts of subprograms
-7. [Write module files](#write-module-files) -
-   If no errors have occurred, write out `.mod` files for modules and submodules
-
-If phase 1 or phase 2 encounter an error on any of the program units,
-compilation terminates. Otherwise, phases 3-6 are all performed even if
-errors occur.
-Module files are written (phase 7) only if there are no errors.
-
-### Validate labels
-
-Perform semantic checks related to labels and branches:
-- check that any labels that are referenced are defined and in scope
-- check branches into loop bodies
-- check that labeled `DO` loops are properly nested
-- check labels in data transfer statements
-
-### Rewrite DO loops
-
-This phase normalizes the parse tree by removing all unstructured `DO` loops
-and replacing them with `DO` constructs.
-
-### Name resolution
-
-The name resolution phase walks the parse tree and constructs the symbol table.
-
-The symbol table consists of a tree of `Scope` objects rooted at the global scope.
-The global scope is owned by the `SemanticsContext` object.
-It contains a `Scope` for each program unit in the compilation.
-
-Each `Scope` in the scope tree contains child scopes representing other scopes
-lexically nested in it.
-Each `Scope` also contains a map of `CharBlock` to `Symbol` representing names
-declared in that scope. (All names in the symbol table are represented as
-`CharBlock` objects, i.e. as substrings of the cooked character stream.)
-
-All `Symbol` objects are owned by the symbol table data structures.
-They should be accessed as `Symbol *` or `Symbol &` outside of the symbol
-table classes as they can't be created, copied, or moved.
-The `Symbol` class has functions and data common across all symbols, and a
-`details` field that contains more information specific to that type of symbol.
-Many symbols also have types, represented by `DeclTypeSpec`.
-Types are also owned by scopes.
-
-Name resolution happens on the parse tree in this order:
-1. Process the specification of a program unit:
-   1. Create a new scope for the unit
-   2. Create a symbol for each contained subprogram containing just the name
-   3. Process the opening statement of the unit (`ModuleStmt`, `FunctionStmt`, etc.)
-   4. Process the specification part of the unit
-2. Apply the same process recursively to nested subprograms
-3. Process the execution part of the program unit
-4. Process the execution parts of nested subprograms recursively
-
-After the completion of this phase, every `Name` corresponds to a `Symbol`
-unless an error occurred.
-
-### Rewrite parse tree
-
-The parser cannot build a completely correct parse tree without symbol information.
-This phase corrects mis-parses based on symbols:
-- Array element assignments may be parsed as statement functions: `a(i) = ...`
-- Namelist group names without `NML=` may be parsed as format expressions
-- A file unit number expression may be parsed as a character variable
-
-This phase also produces an internal error if it finds a `Name` that does not
-have its `symbol` data member filled in. This error is suppressed if other
-errors have occurred because in that case a `Name` corresponding to an erroneous
-symbol may not be resolved.
-
-### Expression analysis
-
-Expressions that occur in the specification part are analyzed during name
-resolution, for example, initial values, array bounds, type parameters.
-Any remaining expressions are analyzed in this phase.
-
-For each `Variable` and top-level `Expr` (i.e. one that is not nested below
-another `Expr` in the parse tree) the analyzed form of the expression is saved
-in the `typedExpr` data member. After this phase has completed, the analyzed
-expression can be accessed using `semantics::GetExpr()`.
-
-This phase also corrects mis-parses based on the result of expression analysis:
-- An expression like `a(b)` is parsed as a function reference but may need
-  to be rewritten to an array element reference (if `a` is an object entity)
-  or to a structure constructor (if `a` is a derive type)
-- An expression like `a(b:c)` is parsed as an array section but may need to be
-  rewritten as a substring if `a` is an object with type CHARACTER
-
-### Statement semantics
-
-Multiple independent checkers driven by the `SemanticsVisitor` framework
-perform the remaining semantic checks.
-By this phase, all names and expressions that can be successfully resolved
-have been. But there may be names without symbols or expressions without
-analyzed form if errors occurred earlier.
-
-### Write module files
-
-Separate compilation information is written out on successful compilation
-of modules and submodules. These are used as input to name resolution
-in program units that `USE` the modules.
-
-Module files are stripped down Fortran source for the module.
-Parts that aren't needed to compile dependent program units (e.g. action statements)
-are omitted.
-
-The module file for module `m` is named `m.mod` and the module file for
-submodule `s` of module `m` is named `m-s.mod`.