[flang][docs] Fix broken flang website (llvm#80363)

These are several fixes for the flang site. The look has been changed to
match clang since flang, like clang, is a frontend. Some broken links
were removed. Most fixes are to secton titles so the table of contents
is generated correctly. A minor typo has been fixed.

Author: tarunprabhu

flang/docs/AliasingAnalysisFIR.md

@@ -74,12 +74,12 @@ Because of block arguments, a memory reference may have multiple sources. If a b
 ### Pointer type
 A type `fir.box<fir.ptr<T>>` or `fir.ptr<T>`
 
-# Aliasing rules
+## Aliasing rules
 The goal is to match [Fortran’s rule for aliasing](Aliasing.md). However FIR is all we have at this stage so the hope is that we can define an algorithm using the information from FIR to properly model Fortran’s aliasing rules. Wherever there is a gap, we may have to refine the algorithm, add information in FIR or both. Though, with the introduction of the fir.declare operation, most of the source level information relevant to aliasing will be populated in FIR.
 
 The first attempt to determine aliasing will be at the coarsest level: the source level. The answer to the query will be ‘yes’, ‘no’, ‘maybe’. If the answer is ‘yes’ or ‘no’, the query is complete. If the answer is ‘maybe’ then further analysis is required until a definite answer is reached. If no finer analysis is available then 'maybe' is returned.
 
-## Coarse rules
+### Coarse rules
 Distinct sources are assumed to not alias except in the following cases:
 1. A pointer type source may alias with any other pointer type source.
 1. A source with the fir.target attribute may alias with any other pointer type source.

flang/docs/FIRArrayOperations.md

@@ -90,7 +90,7 @@ reference, and its semantics guarantee immutability.
 // a fir.store here into array %a does not change %v
 ```
 
-# array_merge_store
+## array_merge_store
 
 The `array_merge_store` operation stores a merged array value to memory.
 

flang/docs/FlangDriver.md

@@ -383,7 +383,7 @@ At this point you should be able to trigger that frontend action that you have
 just added using your new frontend option.
 
 
-# CMake Support
+## CMake Support
 As of [#7246](https://gitlab.kitware.com/cmake/cmake/-/merge_requests/7246)
 (and soon to be released CMake 3.24.0), `cmake` can detect `flang-new` as a
 supported Fortran compiler. You can configure your CMake projects to use
@@ -397,7 +397,7 @@ You should see the following in the output:
 ```
 where `<version>` corresponds to the LLVM Flang version.
 
-# Testing
+## Testing
 In LIT, we define two variables that you can use to invoke Flang's drivers:
 * `%flang` is expanded as `flang-new` (i.e. the compiler driver)
 * `%flang_fc1` is expanded as `flang-new -fc1` (i.e. the frontend driver)
@@ -416,7 +416,7 @@ test as only available on Unix-like systems (i.e. systems that contain a Unix
 shell). In practice this means that the corresponding test is skipped on
 Windows.
 
-# Frontend Driver Plugins
+## Frontend Driver Plugins
 Plugins are an extension to the frontend driver that make it possible to run
 extra user defined frontend actions, in the form of a specialization of a
 `PluginParseTreeAction`. These actions are run during compilation, after
@@ -429,7 +429,7 @@ plugins. The process for using plugins includes:
 Flang plugins are limited to `flang-new -fc1` and are currently only available /
 been tested on Linux.
 
-## Creating a Plugin
+### Creating a Plugin
 There are three parts required for plugins to work:
 1. [`PluginParseTreeAction` subclass](#a-pluginparsetreeaction-subclass)
 1. [Implementation of `ExecuteAction`](#implementation-of-executeaction)
@@ -439,7 +439,7 @@ There is an example plugin located in `flang/example/PrintFlangFunctionNames`
 that demonstrates these points by using the `ParseTree` API to print out
 function and subroutine names declared in the input file.
 
-### A `PluginParseTreeAction` Subclass
+#### A `PluginParseTreeAction` Subclass
 This subclass will wrap everything together and represent the `FrontendAction`
 corresponding to your plugin. It will need to inherit from
 `PluginParseTreeAction` (defined in `flang/include/flang/FrontendActions.h`), in
@@ -449,7 +449,7 @@ can be registered, e.g.
 class PrintFunctionNamesAction : public PluginParseTreeAction
 ```
 
-### Implementation of `ExecuteAction`
+#### Implementation of `ExecuteAction`
 Like in other frontend actions, the driver looks for an `ExecuteAction` function
 to run, so in order for your plugin to do something, you will need to implement
 the `ExecuteAction` method in your plugin class. This method will contain the
@@ -494,7 +494,7 @@ defined in `flang/include/flang/Parser/parse-tree.h`. In the example, there is a
 the `FunctionStmt` struct and prints it. This function will be run after every
 `FunctionStmt` node is visited in the parse tree.
 
-### Plugin Registration
+#### Plugin Registration
 A plugin registry is used to store names and descriptions of a collection of
 plugins. The Flang plugin registry, defined in
 `flang/include/flang/Frontend/FrontendPluginRegistry.h`, is an alias of
@@ -509,7 +509,7 @@ static FrontendPluginRegistry::Add<PrintFunctionNamesAction> X(
     "print-fns", "Print Function names");
 ```
 
-## Loading and Running a Plugin
+### Loading and Running a Plugin
 In order to use plugins, there are 2 command line options made available to the
 frontend driver, `flang-new -fc1`:
 * [`-load <dsopath>`](#the--load-dsopath-option) for loading the dynamic shared
@@ -525,19 +525,19 @@ Both these options are parsed in `flang/lib/Frontend/CompilerInvocation.cpp` and
 fulfil their actions in
 `flang/lib/FrontendTool/ExecuteCompilerInvocation.cpp`
 
-### The `-load <dsopath>` option
+#### The `-load <dsopath>` option
 This loads the plugin shared object library, with the path given at `<dsopath>`,
 using `LoadLibraryPermantly` from LLVM's `llvm::sys::DynamicLibrary`, which
 itself uses `dlopen`. During this stage, the plugin is registered with the
 registration line from the plugin, storing the name and description.
 
-### The `-plugin <name>` option
+#### The `-plugin <name>` option
 This sets `frontend::ActionKind programAction` in `FrontendOptions` to
 `PluginAction`, through which it searches the plugin registry for the plugin
 name from `<name>`. If found, it returns the instantiated plugin, otherwise it
 reports an error diagnostic and returns `nullptr`.
 
-## Enabling In-Tree Plugins
+### Enabling In-Tree Plugins
 For in-tree plugins, there is the CMake flag `FLANG_PLUGIN_SUPPORT`, enabled by
 default, that controls the exporting of executable symbols from `flang-new`,
 which plugins need access to. Additionally, there is the CMake flag
@@ -547,7 +547,7 @@ example programs are built. This includes plugins that are in the
 `flang/examples/CMakeLists.txt`, for example, the `PrintFlangFunctionNames`
 plugin. It is also possible to develop plugins out-of-tree.
 
-## Limitations
+### Limitations
 Note that the traversal API presented here is under active development and
 might change in the future. We expect it to evolve as support for new
 language features are added. This document and the examples will be updated
@@ -564,7 +564,7 @@ to re-analyze expressions and modify scope or symbols. You can check
 [Semantics.md](Semantics.md) for more details on how `ParseTree` is edited
 e.g. during the semantic checks.
 
-# LLVM Pass Plugins
+## LLVM Pass Plugins
 
 Pass plugins are dynamic shared objects that consist of one or more LLVM IR
 passes. The `-fpass-plugin` option enables these passes to be passed to the

flang/docs/HighLevelFIR.md

@@ -1,3 +1,5 @@
+# High-Level Fortran IR (HLFIR)
+
 The approach of FIR and lowering design so far was to start with the minimal set
 of IR operations that could allow implementing the core aspects of Fortran (like
 memory allocations, array addressing, runtime descriptors, and structured
@@ -41,9 +43,9 @@ The core impact on lowering will be:
     relevant.
 
 
-# Variable and Expression value concepts in HLFIR
+## Variable and Expression value concepts in HLFIR
 
-## Strengthening the variable concept
+### Strengthening the variable concept
 
 Fortran variables are currently represented in FIR as mlir::Value with reference
 or box type coming from special operations or block arguments. They are either
@@ -128,7 +130,7 @@ from the caller scope name and the function name.). In general, fir.declare
 will allow to view every memory storage as a variable, and this will be used to
 describe and use compiler created array temporaries.
 
-## Adding an expression value concept in HLFIR
+### Adding an expression value concept in HLFIR
 
 Currently, Fortran expressions can be represented as SSA values for scalar
 logical, integer, real, and complex expressions. Scalar character or
@@ -1353,9 +1355,9 @@ will be inlined, hlfir.forall will be rewritten into normal loops taking into
 account the alias analysis, and hlfir.assign/hlfir.designate operations will be
 lowered to fir.array_coor and fir.store operations).
 
-# Alternatives that were not retained
+## Alternatives that were not retained
 
-## Using a non-MLIR based mutable CFG representation
+### Using a non-MLIR based mutable CFG representation
 
 An option would have been to extend the PFT to describe expressions in a way
 that can be annotated and modified with the ability to introduce temporaries.
@@ -1364,9 +1366,9 @@ infrastructure and data structures while FIR is already using MLIR
 infrastructure, so enriching FIR seems a smoother approach and will benefit from
 the MLIR infrastructure experience that was gained.
 
-## Using symbols for HLFIR variables
+### Using symbols for HLFIR variables
 
-### Using attributes as pseudo variable symbols
+#### Using attributes as pseudo variable symbols
 
 Instead of restricting the memory types an HLFIR variable can have, it was
 force the defining operation of HLFIR variable SSA values to always be
@@ -1390,7 +1392,7 @@ doing code motion, and whose complexity would be increased by the naming
 constraints.
 
 
-### Using MLIR symbols for variables
+#### Using MLIR symbols for variables
 
 Using MLIR symbols for HLFIR variables has been rejected because MLIR symbols
 are mainly intended to deal with globals and functions that may refer to each
@@ -1407,9 +1409,9 @@ Using SSA values also makes the transition and mixture with lower-level FIR
 operations smoother: a variable SSA usage can simply be replaced by lower-level
 FIR operations using the same SSA value.
 
-## Using some existing MLIR dialects for the high-level Fortran.
+### Using some existing MLIR dialects for the high-level Fortran.
 
-### Why not using Linalg dialect?
+#### Why not using Linalg dialect?
 
 The linalg dialects offers a powerful way to represent array operations: the
 linalg.generic operation takes a set of input and output arrays, a related set
@@ -1438,7 +1440,7 @@ semi-affine cases).
 So using linalg is for now left as an optimization pass opportunity in some
 cases that could be experimented.
 
-### Why not using Shape dialect?
+#### Why not using Shape dialect?
 
 MLIR shape dialect gives a set of operations to manipulate shapes. The
 shape.meet operation is exactly similar with hlfir.shape_meet, except that it
@@ -1451,7 +1453,7 @@ shape.meet The shape dialect is a lot more complex because it is intended to
 deal with computations involving dynamically ranked entity, which is not the
 case in Fortran (assumed rank usage in Fortran is greatly limited).
 
-## Using embox/rebox and box as an alternative to fir.declare/hlfir.designate and hlfir.expr/ variable concept
+### Using embox/rebox and box as an alternative to fir.declare/hlfir.designate and hlfir.expr/ variable concept
 
 All Fortran entities (*) can be described at runtime by a fir.box, except for
 some attributes that are not part of the runtime descriptors (like TARGET,

flang/docs/OpenACC-descriptor-management.md

@@ -429,6 +429,6 @@ All the "is-present" checks and the data actions for the auxiliary pointers must
 
 The API relies on the primitives provided by `liboffload`, so it is provided by a new F18 runtime library, e.g. `FortranOffloadRuntime`, that depends on `FortranRuntime` and `liboffload`.  The F18 driver adds `FortranOffloadRuntime` for linking under `-fopenacc`/`-fopenmp` (and maybe additional switches like `-fopenmp-targets`).
 
-# TODOs:
+## TODOs:
 
 * Cover the detach action.

flang/docs/Overview.md

@@ -39,12 +39,12 @@ produce a readable version of the outputs.
 
 Each detailed phase produces either correct output or fatal errors.
 
-# Analysis
+## Analysis
 
 This high level phase validates that the program is correct and creates all of
 the information needed for lowering.
 
-## Prescan and Preprocess
+### Prescan and Preprocess
 
 See [Preprocessing.md](Preprocessing.md).
 
@@ -69,7 +69,7 @@ See [Preprocessing.md](Preprocessing.md).
  - `flang-new -fc1 -fdebug-dump-provenance src.f90` dumps provenance
    information
 
-## Parsing
+### Parsing
 
 **Input:** Cooked character stream
 
@@ -85,7 +85,7 @@ representing a syntactically correct program, rooted at the program unit.  See:
   - `flang-new -fc1 -fdebug-dump-parsing-log src.f90` runs an instrumented parse and dumps the log
   - `flang-new -fc1 -fdebug-measure-parse-tree src.f90` measures the parse tree
 
-## Semantic processing
+### Semantic processing
 
 **Input:** the parse tree, the cooked character stream, and provenance
 information
@@ -125,12 +125,12 @@ At the end of semantic processing, all validation of the user's program is compl
   - `flang-new -fc1 -fdebug-dump-symbols src.f90` dumps the symbol table
   - `flang-new -fc1 -fdebug-dump-all src.f90` dumps both the parse tree and the symbol table
 
-# Lowering
+## Lowering
 
 Lowering takes the parse tree and symbol table produced by analysis and
 produces LLVM IR.
 
-## Create the lowering bridge
+### Create the lowering bridge
 
 **Inputs:** 
   - the parse tree
@@ -148,7 +148,7 @@ The lowering bridge is a container that holds all of the information needed for
 
 **Entry point:** lower::LoweringBridge::create
 
-## Initial lowering
+### Initial lowering
 
 **Input:** the lowering bridge
 
@@ -166,7 +166,7 @@ parse tree.  The compiler walks the PFT generating FIR.
   - `flang-new -fc1 -fdebug-dump-pft src.f90` dumps the pre-FIR tree
   - `flang-new -fc1 -emit-mlir src.f90` dumps the FIR to the files src.mlir
 
-## Transformation passes
+### Transformation passes
 
 **Input:** initial version of the FIR code
 
@@ -183,7 +183,7 @@ LLVM IR representation of the program.
   - `flang-new -mmlir --mlir-print-ir-after-all -S src.f90` dumps the FIR code after each pass to standard error
   - `flang-new -fc1 -emit-llvm src.f90` dumps the LLVM IR to src.ll
 
-# Object code generation and linking
+## Object code generation and linking
 
 After the LLVM IR is created, the flang driver invokes LLVM's existing
 infrastructure to generate object code and invoke a linker to create the