[flang] Add new documentation main page

[richard.barton.arm]

Summary

Add a new index page to be the Flang documentation mainpage instead of
Overview.md, which jumps straight into the compiler Design. The index file
needs to be in .rst format to use the toctree directive to create table of
contents.

Also use the sphinx_markdown_tables extension to generate html tables form
markdown.

A number of additional style changes to the existing docs were needed to make
this work well:

• Convert all headings to the # style, which works better with toctree's titlesonly option. Ensure that there is only one top-level heading per document.
• Add a title to documents that don't have one for rendering on the index.
• Convert the grammar docs from .txt to .md. for better rendering
• Fixed broken link to a section in another document - sphinx does not seem to support anchor links in markdown files.

Depends on D87226

[sameeranjoshi]

I have a GettingInvolved.md can you include it as well if it makes sense to add it with this patch and the original authors agree.
Most of the content comes from mailing list meeting minutes from Gary(Thanks @gak).

GettingInvolved.md3 KBDownload

flang/docs/index.rst

1

Is there a hard requirement for using rst, can we instead use links from markdown syntax for generating TOC?
TOC generators could be used initially.

[richard.barton.arm]

In D87242#2259691, @sameeranjoshi wrote:

I have a GettingInvolved.md can you include it as well if it makes sense to add it with this patch and the original authors agree.
Most of the content comes from mailing list meeting minutes from Gary(Thanks @gak).

GettingInvolved.md3 KBDownload

Nice addition! I suggest doing what you have done and making D87270 depend on this change and we submit them in that order.

Is there a hard requirement for using rst, can we instead use links from markdown syntax for generating TOC?
TOC generators could be used initially.

From what I have seen of your recent work @sameeranjoshi, I think it is likely that you know more about this than I do so I went and had a look :-)

The internet suggests the AutoStructify recommonmark extension is the one. I will take a look.

flang/docs/index.rst

1

Is there a hard requirement for using rst, can we instead use links from markdown syntax for generating TOC?
TOC generators could be used initially.

[richard.barton.arm]

New version that uses recommonmark's AutoStructify plugin to re-write
the index page in markdown with toctrees in embedded rst blocks.

[sameeranjoshi]

The web-pages seem to work properly for me with below configurations.

Name: sphinx-markdown-tables
Version: 0.0.15
Name: recommonmark
Version: 0.6.0

$ sphinx-build --version
sphinx-build 3.2.0

The TOC tree is displayed in the right indexsidebar, if it could be displayed at the top (see http://llvm.org/docs/CMake.html for reference) of individual pages that would be better and it would help reader initially to navigate to the internal section in the respective page.
Further I went on to apply D87226(contains a fixed side bar index links ) and the TOC disappears probably due to above mentioned issue.

[richard.barton.arm]

The TOC tree is displayed in the right indexsidebar, if it could be displayed at the top (see http://llvm.org/docs/CMake.html for reference) of individual pages that would be better and it would help reader initially to navigate to the internal section in the respective page.
Further I went on to apply D87226(contains a fixed side bar index links ) and the TOC disappears probably due to above mentioned issue.

Can you help me understand what you mean here? When I build the pages they look like this to me:

Compare that to the reference page you linked me to (same browser, same computer):

I don't see a difference in the two for style. Both seem to have previous | next | index links in the top (and bottom) bars, as well as the indexsidebar as you point out. The indexsidebar seems to be a standard default from sphinx. LLVM uses a special one in llvm/docs/_templates/indexsidebar.html which does not have the previous/next topic links and instead has the permalinks to other articles.

[richard.barton.arm]

Rebasing over the top of the license header restoration.

[sameeranjoshi]

In D87242#2266411, @richard.barton.arm wrote:

The TOC tree is displayed in the right indexsidebar, if it could be displayed at the top (see http://llvm.org/docs/CMake.html for reference) of individual pages that would be better and it would help reader initially to navigate to the internal section in the respective page.
Further I went on to apply D87226(contains a fixed side bar index links ) and the TOC disappears probably due to above mentioned issue.

Can you help me understand what you mean here? When I build the pages they look like this to me:

Compare that to the reference page you linked me to (same browser, same computer):

I don't see a difference in the two for style. Both seem to have previous | next | index links in the top (and bottom) bars, as well as the indexsidebar as you point out. The indexsidebar seems to be a standard default from sphinx. LLVM uses a special one in llvm/docs/_templates/indexsidebar.html which does not have the previous/next topic links and instead has the permalinks to other articles.

I was talking about having the Table Of Contents which is in right pane to be in the center of page the way LLVM has.
Also when D87226 would be applied, it would remove the TOC and will add other contents there.

[richard.barton.arm]

I don't see a difference in the two for style. Both seem to have previous | next | index links in the top (and bottom) bars, as well as the indexsidebar as you point out. The indexsidebar seems to be a standard default from sphinx. LLVM uses a special one in llvm/docs/_templates/indexsidebar.html which does not have the previous/next topic links and instead has the permalinks to other articles.

I was talking about having the Table Of Contents which is in right pane to be in the center of page the way LLVM has.
Also when D87226 would be applied, it would remove the TOC and will add other contents there.

Ah, so a TOC in each page itself. Fair point.

Pushing a new version which adds a local toc to each document. I held off for a few of them as it did not seem to make sense to add one there (either doc too short, or just had one section.) The options comparison doc had a duplicat section title, so I fixed that up too.

Also fixed up some old-style title headings that slipped past the last rebase.

[sameeranjoshi]

Thanks ! Builds and pages Look good.

[richard.barton.arm]

@sameeranjoshi you happy to "accept this revision" :-) ?

[hans]

Sadly after this commit, I'm no longer able to build the Flang docs, my build failing like this:

cd /work/llvm.monorepo/build.docs/tools/flang/docs && /usr/bin/sphinx-build -b html -d /work/llvm.monorepo/build.docs/tools/flang/docs/_doctrees-flang-html -q -t builder-html /work/llvm.mo
norepo/flang/docs /work/llvm.monorepo/build.docs/tools/flang/docs/html                                                                                                                      
/usr/lib/python3/dist-packages/sphinx/util/compat.py:30: RemovedInSphinx30Warning: The config variable "source_parsers" is deprecated. Please update your extension for the parser and remov
e the setting.                                                                                                                                                                              
  warnings.warn('The config variable "source_parsers" is deprecated. '                                                                                                                      
/usr/lib/python3/dist-packages/sphinx/util/compat.py:36: RemovedInSphinx30Warning: app.add_source_parser() does not support suffix argument. Use app.add_source_suffix() instead.
  app.add_source_parser(suffix, parser)                                                                                                                                                     
/work/llvm.monorepo/flang/docs/ArrayComposition.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                                 
/work/llvm.monorepo/flang/docs/BijectiveInternalNameUniquing.md:1: WARNING: The "contents" directive may not be used within topics or body elements.           
/work/llvm.monorepo/flang/docs/C++17.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                                              
/work/llvm.monorepo/flang/docs/C++style.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                                            
/work/llvm.monorepo/flang/docs/Calls.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                                         
/work/llvm.monorepo/flang/docs/Character.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                              
/work/llvm.monorepo/flang/docs/ControlFlowGraph.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                       
/work/llvm.monorepo/flang/docs/Extensions.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                         
/work/llvm.monorepo/flang/docs/FortranForCProgrammers.md:1: WARNING: The "contents" directive may not be used within topics or body elements.            
/work/llvm.monorepo/flang/docs/FortranIR.md:1: WARNING: The "contents" directive may not be used within topics or body elements.                                      
                                                                                                                                                                                            
Exception occurred:                                                                                                                                                                         
  File "/usr/lib/python3/dist-packages/recommonmark/states.py", line 128, in run_role                                                                                                       
    vec, msg = role_fn(name,                                                                                                                                                                
TypeError: 'NoneType' object is not callable

I think it's only the last part that's actually a critical error, and I think what brought this on is the use of the AutoStructify thing.

Some searching suggests this is due to incompatibilities between certain sphinx and recommonmark versions (e.g. https://github.com/sphinx-doc/sphinx/issues/3800) but I really don't have time to debug this kind of stuff.

For now, my plan is to exclude the Flang docs from the build and link to the release notes as rendered by github here: https://github.com/llvm/llvm-project/blob/release/11.x/flang/docs/ReleaseNotes.md

If someone wants to fix the build, or even just send me the built html files once the release is ready, that would of course work too.

But I don't have time to fiddle around with these python packages, sorry.

[richard.barton.arm]

Hi @hans thanks for giving it a try. I think it is fair enough that you don't try to fix it yourself.

I would be happy to supply generated .html files if you ping me once the release is signed off. @sameeranjoshi might also be available.

Note also that the Flang docs need to be built with -DSPHINX_WARNINGS_AS_ERRORS=OFF, I was following this when I developed the patch. Is this also the case in your builds when you generate the docs?

@sameeranjoshi - I don't think we can easily work around this without losing the automatic content sections in the markdown docs, which would be a shame.

@hans - there is a hacky fix available online. I have pushed it for review here: https://reviews.llvm.org/D87714 would you mind giving it a try?

If it still causes problems then please can you share the output of

sphinx-build --version
pip3 show recommonmark

then I can try to reproduce.

flang/docs/ArrayComposition.md

+# Array Composition
+
 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:

 * `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.
 
-Arrays as functions
-===================
+## 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.
 
-Array expressions as functions
-==============================
+## 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)`).

 ```
 
 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
-============================================================
+## 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`.

 * `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.
 
-Determination of rank and shape
-===============================
+## 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.

 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
-======================================
+## 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
-===============
+## Rewriting rules
+
 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)})`.
 * Array constructors with multiple constituents are concatenations of
   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

flang/docs/BijectiveInternalNameUniquing.md

-## Bijective Internal Name Uniquing
+# 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`
+## 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
+## 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
+## 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
+## 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
+## Procedures/Subprograms
 
    * A procedure/subprogram is prefixed with `P`
 
 Given:
 ```
     subroutine sub
 ```
 The uniqued name of `sub` becomes:
 ```
     _QPsub
 ```
 
-### Derived types and related
+## 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.
 
```
 
    * 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
 
 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.md

-## 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.

 * `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

 * 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
   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.
 
 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.
 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
 be identified and accessed in terms of their types, and those tend to be
 distinct.
 
 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.md

+# Flang C++ Style Guide
+
+This document captures the style guide rules that are followed in the Flang codebase.
+
 ## 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)

flang/docs/Calls.md

+# Representation of Fortran function calls
+
 ## 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.
 

flang/docs/Character.md

-## Implementation of `CHARACTER` types in f18
+# Implementation of `CHARACTER` types in f18
 
-### Kinds and Character Sets
+## 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.
 
 We assume that code values 0 through 127 correspond to

 
 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
 besides Latin-1.
 
-### Lengths
+## Lengths
 
 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
 declaration in the calling scope.

 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
 strides.
 
-### Concatenation
+## Concatenation
 
 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.

 * 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()`
 and then progressively augmented in place by the values of each of the
 operands of the concatenation sequence in turn with calls to
 `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
 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.
 
 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.
 
-#### Optimized concatenation
+### Optimized concatenation
 
 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
 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`.
 
 `void CharacterPad()`adds any necessary trailing blank characters.

flang/docs/ControlFlowGraph.md

+# Control Flow Graph
+
 ## 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.
 
 This second representation of the subprogram's executable part is
 suitable for analysis and incremental modification as the subprogram

flang/docs/Directives.md

-Compiler directives supported by F18
-====================================
+# Compiler directives supported by Flang
+
+A list of non-standard directives supported by Flang
 
 * `!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.md

+# Fortran Extensions supported by Flang
+
 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
-======================================
+## Intentional violations of the standard
+
 * 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
   emitted when truncation is possible.
 * 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)
 
-Extensions, deletions, and legacy features supported by default
-===============================================================
+## 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`
 * Signed complex literal constants
 * DEC `STRUCTURE`, `RECORD`, `UNION`, and `MAP`

 * 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.
 * DATA statement initialization is allowed for procedure pointers outside
   structure constructors.
 
-Extensions supported when enabled by options
---------------------------------------------
+### 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.`
   [-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
   rule imposes an artificially small constraint in some cases
   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`
   [-fimplicit-none-type-always]
 * Ignore occurrences of `IMPLICIT NONE` and `IMPLICIT NONE(TYPE)`
   [-fimplicit-none-type-never]
 
-Extensions and legacy features deliberately not supported
----------------------------------------------------------
+### Extensions and legacy features deliberately not supported
+
 * `.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`

 * Type parameter declarations must come first in a derived type definition;
   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
-======================
+## 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.md

-Fortran For C Programmers
-=========================
+# 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
-------------------
+## 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
* 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`).
 * 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
----------------
+## 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 |

 | 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
-----------
+## Data Types
+
 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`

 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
+
 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.
 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
-------------
+## Allocatables
+
 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
 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,
 and follow up all the references that are made in the documentation
 from the description of `ALLOCATABLE` to other topics; it's a feature
 that interacts with much of the rest of the language.)
 
-I/O
----
+## 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
 "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.
 
 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
 of standard library functions.
 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
------------
+## 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
 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
--------
+## 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
 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
----------
+## 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.
 
```
   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
------------
+## 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
-------------
+## 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++.
 
 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.
 
-Pointers
---------
+## 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
 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
 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
--------------
+## 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
------------------------------
+## "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
 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)`.
 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`.
 
 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
---------
+## Pitfalls
+
 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,
 which perpetuates the interpretation as static data.
 (Derived type component initializers, however, do work as expected.)

flang/docs/IORuntimeInternals.md

-Fortran I/O Runtime Library Internal Design
-===========================================
+# 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

 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
-===================
+## 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`
-----------
+### `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`
---------------
+### `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`
-------------
+### `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`
---------
+### `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<>`
----------------
+### `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`
---------
+### `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`
----------------
+### `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`
-----------------------
+### `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<>`
------------
+### `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`
-----------------
+### `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`
----------------
+### `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

 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`
-----------------
+### `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

 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'`
-=================================================
+## 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

flang/docs/ImplementingASemanticCheck.md

+# How to implement a Sematic Check in Flang
+
 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
+## 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
+## 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

 
 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
+## 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
+### 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

 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
+### 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
+### 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`
+### 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

 `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
+### 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
+## Implementation
 
-## Adding a parse tree visitor
+### 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++

 ```
 
 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
+### 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`:

 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
+### 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";
```
   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
+### 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()`:
```
   Found a whole variable: ivar: ObjectEntity type: INTEGER(4)
   INTENT(OUT)
   In Leave for parser::Expr
   Number of arguments: 0
 ```
 
 Sweet.
 
-## Emitting the messages
+### 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) {
testfun.f90:6:12: error: Cannot redefine DO variable 'ivar'
                ^^^^^^^^^^^^^^^^^^^
   testfun.f90:5:6: Enclosing DO construct
       do ivar = 1, 10
          ^^^^
 ```
 
 Even sweeter.
 
-# Improving the test case
+## 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
function intentInOutFunc(dummyArg)
 
       dummyArg = 216
       intentInOutFunc = 343
     end function intentInOutFunc
 
   end subroutine s
 ```
 
-# Submitting the pull request
+## 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()}) {
for (const evaluate::ActualArgumentRef &argRef : argSet) {
         }
       }
     }
   }
 ```
 
 I then created a pull request to get review comments.  
 
-# Responding to pull request 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++

flang/docs/Intrinsics.md

 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
+## 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
+### 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.

 ```
 
 `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
+## 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
+### 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
+### 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
+### 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`.

 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
+### 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.
 

 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
+### 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)

 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
+### 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
+## Inquiry intrinsic functions
 These are neither elemental nor transformational; all are pure.
 
-## Type inquiry intrinsic functions
+### 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
+### 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
+### 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
+## Intrinsic subroutines
 
 (*TODO*: complete these descriptions)
 
-## One elemental intrinsic subroutine
+### 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
+### 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
+### 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
+### Collective intrinsic subroutines
 ```
 CALL CO_BROADCAST
 CALL CO_MAX
 CALL CO_MIN
 CALL CO_REDUCE
 CALL CO_SUM
 ```
 
-# Non-standard intrinsics
-## PGI
+## 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
+### 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
+## 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
+### 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
+### 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
+#### 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
+#### 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.
 

flang/docs/OpenMP-4.5-grammar.md

-#===-- docs/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 Grammar
 
-# OpenMP 4.5 Specifications
+Grammar used by Flang to parse OpenMP 4.5.
 
+## 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
+## 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 |

 
 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/OptionComparison.md

-# Compiler options
+# Compiler options comparison
 
 This document catalogs the options processed by F18's peers/competitors.  Much of the document is taken up by a set of tables that list the options categorized into different topics.  Some of the table headings link to more information about the contents of the tables.  For example, the table on **Standards conformance** options links to [notes on Standards conformance](#standards).
 
 **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>

flang/docs/ParserCombinators.md

+# Parser Combinators
+
+This document is a primer on Parser Combinators and their use in Flang.
+
 ## 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.

flang/docs/Preprocessing.md

-Fortran Preprocessing
-=====================
+# Fortran Preprocessing
+
+## Behavior common to (nearly) all compilers:
 
-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
* 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:
------------------------------------
+## 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:
-----------------------------------------------
+## 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:
--------------------------------------------------------------------
+## 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:
----------------------------------------------------
+## 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.

 
 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
-========
+## 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".
 

flang/docs/PullRequestChecklist.md

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

flang/docs/RuntimeDescriptor.md

+# Runtime Descriptors
+
 ## 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.

flang/docs/conf.py

 else:
   import sphinx
   if sphinx.version_info >= (3, 0):
     # This requires 0.5 or later.
     extensions.append('recommonmark')
   else:
     source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
   source_suffix['.md'] = 'markdown'
+  extensions.append('sphinx_markdown_tables')
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'Overview'
+master_doc = 'index'
 
 # General information about the project.
 project = u'Flang'
 copyright = u'2017-%d, The Flang Team' % date.today().year
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents. These are currently set to zero because we don't use them.

flang/docs/f2018-grammar.md

-#===-- docs/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
-#
-#===------------------------------------------------------------------------===#
+# Fortran 2018 Grammar
 
+Grammar used by Flang to parse Fortran 2018.
+
+```
 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
R1538 separate-module-subprogram ->
         [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/index.rst

+.. Flang documentation master file.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. title:: Flang Documentation
+
+Welcome to Flang's documentation
+================================
+
+Flang is LLVM's Fortran frontend
+
+.. toctree::
+   :titlesonly:
+
+   ReleaseNotes
+
+Contributing to Flang
+=====================
+
+.. toctree::
+   :titlesonly:
+
+   FortranForCProgrammers
+   C++style
+   C++17
+   PullRequestChecklist
+   ImplementingASemanticCheck
+
+Design Documents
+================
+
+.. toctree::
+   :titlesonly:
+
+   Overview
+   Preprocessing
+   Parsing
+   LabelResolution
+   ModFiles
+   Semantics
+   OpenMP-semantics
+   ControlFlowGraph
+   FortranIR
+   IORuntimeInternals
+   f2018-grammar.md
+   OpenMP-4.5-grammar.md
+   Directives
+   Extensions
+   Intrinsics
+   OptionComparison
+   ParserCombinators
+   RuntimeDescriptor
+   Calls
+   Character
+   ArrayComposition
+   BijectiveInternalNameUniquing
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+