[2/4][mlir][doc] Fix links and references in documentation of Rationale

[zero9178]

Summary

This patch is the second in a series of patches fixing markdown links and references inside the mlir documentation. For the first see https://reviews.llvm.org/D103011.

This patch addresses all broken references to other markdown files and sections inside the Rationale folder.

In addition to fixing the links and references like in the previous patch, I also changed references which are URLs to the mlir.llvm.org/docs website, to proper relative markdown references instead.

[zero9178]

Remove anchor name from prior art in RationaleLinalgDialect. This way generated name to refer to the section in Markdown is just "prior-art"

mlir/docs/Rationale/MLIRForGraphAlgorithms.md

 dividing our efforts, etc. In order for this to be worth it, we should have a
 good sense that we are building towards an improved future that will make
 customers and TensorFlow engineers happier when it lands. Here we describe a few
 of the benefits that MLIR provides, in no particular order:
 
 ### A Lossless Human Editable Textual Representation
 
 The MLIR in-memory data structure has a human readable and writable format, as
-well as [a specification](LangRef.md) for that format - built just like any
+well as [a specification](../LangRef.md) for that format - built just like any
 other programming language. Important properties of this format are that it is
 compact, easy to read, and lossless. You can dump an MLIR program out to disk
 and munge around with it, then send it through a few more passes.
 
 If you haven't worked with a system that works this way, it is hard to overstate
 how big of a deal this in practice: it means that you can call `foo->dump()` on
 an IR object to see its full contents, it means you can diff the IR before and
 after a change, delta reduce IR files, and many other things.
```mlir
   // CHECK-LABEL: func @test_subi_zero_cfg(%arg0: i32)
   // CHECK-NEXT: %c0_i32 = constant 0 : i32
   // CHECK-NEXT: return %c0
 ```
 
 The "CHECK" comments are interpreted by the
 [LLVM FileCheck tool](https://llvm.org/docs/CommandGuide/FileCheck.html), which
 is sort of like a really advanced grep. This test is fully self-contained: it
-feeds the input into the [canonicalize pass](Canonicalization.md), and checks
+feeds the input into the [canonicalize pass](../Canonicalization.md), and checks
 that the output matches the CHECK lines. See the `test/Transforms` directory for
 more examples. In contrast, standard unit testing exposes the API of the
 underlying framework to lots and lots of tests (making it harder to refactor and
 move the API), typically requires a lot more code, and exacerbates issues with
 link time. For examples, see
 [the TEST_F functions in TensorFlow's testsuite](https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/grappler/optimizers/arithmetic_optimizer_test.cc).
 
 MLIR has been pervasively designed with this sort of design by testability,

 system (TF_DataType) in which each value is a tensor of unknown rank and
 dimensions. At the same time, many graphs have static shapes easily knowable for
 wide swaths of the computation, and even dynamically shaped operations often
 have statically knowable dimensions. Many analyses and transformations benefit
 and use this information when available, but because TensorFlow graphs don't
 capture this (e.g. serialize it to proto), passes have to recompute it on demand
 with ShapeRefiner.
 
-The [MLIR Tensor Type](LangRef.md#tensor-type) directly captures shape
+The [MLIR Tensor Type](../Dialects/Builtin.md/#rankedtensortype) directly captures shape
 information, so you can have things like:
 
 ```mlir
   %x = tf.Add %x, %y : tensor<128 x 8 x ? x f32>
 ```
 
 Capturing this in the IR is expected to speed up transformations (avoiding
 recomputing the same info over and over again) which therefore makes it

mlir/docs/Rationale/Rationale.md

 ### Loads and stores
 
 The 'load' and 'store' instructions are specifically crafted to fully resolve to
 an element of a memref. These instructions take as arguments n+1 indices for an
 n-ranked tensor. This disallows the equivalent of pointer arithmetic or the
 ability to index into the same memref in other ways (something which C arrays
 allow for example). Furthermore, for the affine constructs, the compiler can
 follow use-def chains (e.g. through
-[affine.apply operations](../Dialects/Affine.md#affineapply-operation)) or through
-the map attributes of [affine operations](../Dialects/Affine.md#Operations)) to
+[affine.apply operations](../Dialects/Affine.md/#affineapply-affineapplyop)) or through
+the map attributes of [affine operations](../Dialects/Affine.md/#operations)) to
 precisely analyze references at compile-time using polyhedral techniques. This
-is possible because of the [restrictions on dimensions and symbols](../Dialects/Affine.md#restrictions-on-dimensions-and-symbols).
+is possible because of the [restrictions on dimensions and symbols](../Dialects/Affine.md/#restrictions-on-dimensions-and-symbols).
 
 A scalar of element-type (a primitive type or a vector type) that is stored in
 memory is modeled as a 0-d memref. This is also necessary for scalars that are
 live out of for loops and if conditionals in a function, for which we don't yet
 have an SSA representation --
-[an extension](#mlfunction-extensions-for-"escaping-scalars") to allow that is
+[an extension](#affineif-and-affinefor-extensions-for-escaping-scalars) to allow that is
 described later in this doc.
 
 ### Symbols and types
 
 The current MLIR disallows use of symbols in types. For example, when a tensor
 or memref dimension is statically unknown, it is denoted in the type as '?'. An
 SSA symbol is then bound to it when a memref is created. The actual value of the
 unknown dimension can be queried using the "dim" builtin as shown below.

 
 An alternative design is to embed the reference to symbols directly in the
 type - memref<8x%Nxf32>. We went for the current approach in MLIR because it
 simplifies the design --- types remain immutable when the values of symbols
 change.
 
 ### Block Arguments vs PHI nodes
 
-MLIR Regions represent SSA using "[block arguments](../LangRef.md#blocks)" rather
+MLIR Regions represent SSA using "[block arguments](../LangRef.md/#blocks)" rather
 than [PHI instructions](http://llvm.org/docs/LangRef.html#i-phi) used in LLVM.
 This choice is representationally identical (the same constructs can be
 represented in either form) but block arguments have several advantages:
 
 1.  LLVM PHI nodes always have to be kept at the top of a block, and
     transformations frequently have to manually skip over them. This is defined
     away with BB arguments.
 1.  LLVM has a separate function Argument node. This is defined away with BB

 rather design it in from the beginning.
 
 Note that this rationale only applies to the "standard ops" dialect in which we
 can express an opinion about its design. Other dialects generally try to model
 an external system, and should aim to reflect its design as closely as possible.
 
 ### Specifying sign in integer comparison operations
 
-Since integers are [signless](#signless-types), it is necessary to define the
+Since integers are [signless](#integer-signedness-semantics), it is necessary to define the
 sign for integer comparison operations. This sign indicates how to treat the
 foremost bit of the integer: as sign bit or as most significant bit. For
 example, comparing two `i4` values `0b1000` and `0b0010` yields different
 results for unsigned (`8 > 3`) and signed (`-8 < 3`) interpretations. This
 difference is only significant for _order_ comparisons, but not for _equality_
 comparisons. Indeed, for the latter all bits must have the same value
 independently of the sign. Since both arguments have exactly the same bit width
 and cannot be padded by this operation, it is impossible to compare two values

 
 Unlike operations, types generally do not have a formal canonical name. For
 example, function types have no defined keyword and integer types are defined by
 a regular expression to support arbitrary bitwidth. Dialects with existing type
 systems, e.g. LLVM, are likely to provide wrappers around their existing type
 systems. For these wrapper types there is no simple canonical name, it's logical
 to think of these types as existing within the namespace of the dialect. If a
 dialect wishes to assign a canonical name to a type, it can be done via
-[type aliases](../LangRef.md#type-aliases).
+[type aliases](../LangRef.md/#type-aliases).
 
 ### Tuple types
 
 The MLIR type system provides first class support for defining
-[tuple types](../LangRef.md#tuple-type). This is due to the fact that `Tuple`
+[tuple types](../Dialects/Builtin/#tupletype). This is due to the fact that `Tuple`
 represents a universal concept that is likely to, and has already begun to,
 present itself in many different dialects. Though this type is first class in
 the type system, it merely serves to provide a common mechanism in which to
 represent this concept in MLIR. As such, MLIR provides no standard operations
 for interfacing with `tuple` types. It is up to dialect authors to provide
 operations, e.g. extract_tuple_element, to interpret and manipulate them. When
 possible, operations should prefer to use multiple results instead. These
 provide a myriad of benefits, such as alleviating any need for tuple-extract

mlir/docs/Rationale/RationaleGenericDAGRewriter.md

 
 ### Constant folding
 
 A degenerate but pervasive case of DAG-to-DAG pattern matching is constant
 folding: an operation whose operands contain constants can often be folded to a
 result constant value.
 
 MLIR operations may override a
-[`fold`](../Canonicalization.md/#canonicalizing-with-fold) routine, which
+[`fold`](../Canonicalization.md/#canonicalizing-with-the-fold-method) routine, which
 exposes a simpler API compared to a general DAG-to-DAG pattern matcher, and
 allows for it to be applicable in cases that a generic matcher would not. For
 example, a DAG-rewrite can remove arbitrary nodes in the current function, which
 could invalidate iterators. Constant folding as an API does not remove any
 nodes, it just provides a (list of) constant values and allows the clients to
 update their data structures as necessary.
 
 ## Related Work

mlir/docs/Rationale/RationaleLinalgDialect.md

 This document describes the key design principles
 that led to the existing implementation of Linalg and aims at exposing
 the tradeoffs involved when building higher-level Intermediate
 Representations (IR) and Dialects to facilitate code
 generation. Consider the simplified schema describing codegen in MLIR.
 Linalg is designed to solve the High-level Hierarchical Optimization
 (HHO box) and to interoperate nicely within a
 *Mixture Of Expert Compilers* environment (i.e. the *CGSel* box).
-This work is inspired by a wealth of [prior art](#prior_art) in
+This work is inspired by a wealth of [prior art](#prior-art) in
 the field, from which it seeks to learn key lessons. This documentation
 and introspection effort also comes in the context of the proposal for a
 working group for discussing the [Development of high-level Tensor Compute
 Primitives dialect(s) and
 transformations](https://llvm.discourse.group/t/development-of-high-level-tensor-compute-primitives-dialect-s-and-transformations/388/3).
 We hope that the lessons from prior art, the design principles outlined in
 this doc and the architecture of Linalg can help inform the community on a
 path to defining these High-Level Tensor Compute Primitives.

 The first incarnation of these ideas was presented as an example at the
 EuroLLVM 2019 developer's meeting as part of the
 [Linalg section](https://llvm.org/devmtg/2019-04/slides/Tutorial-AminiVasilacheZinenko-MLIR.pdf)
 of the first [MLIR Tutorial](https://www.youtube.com/watch?v=cyICUIZ56wQ).
 
 ### Evolution
 Since the initial implementation, the design has evolved with, and partially
 driven the evolution of the core MLIR infrastructure to use
-[Regions](https://mlir.llvm.org/docs/LangRef/#regions),
-[OpInterfaces](https://mlir.llvm.org/docs/Interfaces/),
-[ODS](https://mlir.llvm.org/docs/OpDefinitions/) and
-[Declarative Rewrite Rules](https://mlir.llvm.org/docs/DeclarativeRewrites/)
+[Regions](../LangRef.md/#regions),
+[OpInterfaces](../Interfaces.md),
+[ODS](../OpDefinitions.md) and
+[Declarative Rewrite Rules](../DeclarativeRewrites.md)
 among others. The approach adopted by Linalg was extended to become
 [StructuredOps abstractions](
 https://drive.google.com/drive/u/0/folders/1sRAsgsd8Bvpm_IxREmZf2agsGU2KvrK-),
 with Linalg becoming its incarnation on tensors and buffers.
 It is complemented by the
-[Vector dialect](https://mlir.llvm.org/docs/Dialects/Vector/),
+[Vector dialect](../Dialects/Vector.md),
 which defines structured operations on vectors, following the same rationale and
 design principles as Linalg. (Vector dialect includes the higher-level
 operations on multi-dimensional vectors and abstracts away the lowering to
 single-dimensional vectors).
 
 The Linalg dialect itself grew beyond linear algebra-like operations to become
 more expressive, in particular by providing an abstraction of a loop nest
 supporting parallelism, reductions and sliding windows around arbitrary MLIR
-[regions](https://mlir.llvm.org/docs/LangRef/#regions). It also has the
+[regions](../LangRef.md/#regions). It also has the
 potential of growing beyond *dense* linear-algebra to support richer data
 types, such as sparse and ragged tensors and buffers.
 
 Linalg design remains open to evolution and cross-pollination with other
 dialects and approaches. It has been successfully used as the staging ground
 for code generation-related abstractions, spinning off the generalization of
 the following:
 - the `!linalg.view` type folded into the *"Strided MemRef"* type while
 preserving structure to allow calling into external C++ libraries with
 unsurprising ABI conventions;
 - the `linalg.view` and `linalg.subview` ops evolved into the standard dialect;
 - the `linalg.for`, `linalg.load` and `linalg.store` ops evolved into a prelude
 to the *structured control flow* dialect (named `LoopOps`).
 More components can be extracted, redesigned and generalized when new uses or
 requirements arise.
 
-Several [design questions](#open_issues) remain open in Linalg, which does not
+Several [design questions](../Dialects/Linalg.md/#open_issues) remain open in Linalg, which does not
 claim to be a general solution to all compilation problems.
 It does aim at driving thinking and implementations of domain-specific
 abstractions where programmer's intent can be captured at a very high level,
 directly in the IR.
 
 Given the evolution of the scope, it becomes apparent that a better name than
 "Linalg" could remove some of the confusions related to the dialect (and the
 underlying approach), its goals and limitations.
 
-## Prior Art<a name=""></a>
+## Prior Art
 Linalg draws inspiration from decades of prior art to design a modern a
 pragmatic solution. The following non-exhaustive list refers to some of the
 projects that influenced Linalg design:
 
 - [ONNX](https://onnx.ai/),
 - [LIFT](https://www.lift-project.org/),
 - [XLA](https://www.tensorflow.org/xla/architecture),
 - [Halide](https://halide-lang.org/) and [TVM](https://tvm.apache.org/),

 kernels based on functional abstractions. Transformations are
 represented by additional nodes in the IR, whose semantics are at the
 level of the algorithm (e.g. `partialReduce`).
 LIFT applies and composes transformations by using [local rewrite
 rules](https://www.lift-project.org/presentations/2015/ICFP-2015.pdf) that
 embed these additional nodes directly in the functional abstraction.
 
 Similarly to LIFT, Linalg uses local rewrite rules implemented with the MLIR
-[Declarative Rewrite Rules](https://mlir.llvm.org/docs/DeclarativeRewrites/)
+[Declarative Rewrite Rules](../DeclarativeRewrites.md)
 mechanisms.
 
 Linalg builds on, and helps separate concerns in the LIFT approach as follows:
 - transformations are either separated from the representation or expressed as
   composable attributes that are independent of the actual computation,
   avoiding intricate effects on performance;
 - abstractions are split into smaller components (e.g., control flow and data
   structure abstractions) potentially reusable across different dialects in the

 The problem at hand is fundamentally driven by compilation of domain-specific
 workloads for high-performance and parallel hardware architectures: **this is
 an HPC compilation problem**.
 
 The selection of relevant transformations follows a co-design approach and
 involves considerations related to:
 - concrete current and future needs of the application domain,
 - concrete current and future hardware properties and ISAs,
-- understanding of strengths and limitations of [existing approaches](#prior_art),
+- understanding of strengths and limitations of [existing approaches](#prior-art),
 - taking advantage of the coexistence of multiple levels of IR in MLIR,
 
 One needs to be methodical to avoid proliferation and redundancy. A given
 transformation could exist at multiple levels of abstraction but **just
 because one can write transformation X at level Y absolutely does not mean
 one should**. This is where evaluation of existing
 systems and acknowledgement of their strengths and weaknesses is crucial:
 simplicity and maintainability aspects must be first-order concerns. Without

 requirements when producing an implementation based on MLIR.
 
 ### Algorithms + Data Structures = Programs<a name="data_and_compute"></a>
 This is a twist on Niklaus Wirth's formulation but captures the essence of the
 design of Linalg: control-flow does not exist in a vacuum, independently of
 data.
 On the contrary, there is a very strong relationship between control-flow and
 data structures: one cannot exist without the other. This has multiple
-implications on the [semantics of Linalg Ops](#linalg_ops) and their
+implications on the [semantics of Linalg Ops](../Dialects/Linalg.md/#linalg_op) and their
 transformations. In particular, this observation influences whether
 certain transformations are better done:
 - as control flow or data structure manipulation,
 - on Linalg ops attributes or on loops after some partial lowering
 occurred,
 - as extensions to the Linalg dialect in terms of new ops or attributes.
 
 ### The Dialect Need not be Closed Under Transformations<a name="dialect_not_closed"></a>

 Considering the *potential* described during the discussion on
 [Progressive Lowering](#progressive_lowering), closed-ness under
 transformation would dictate that the potential remains constant.
 In contrast, Linalg advocates for ***monotonicity*** under
 transformations.
 
 ### Summary of Existing Alternatives a Picture<a name="observationssummary"></a>
 Lastly, we summarize our observations of lessons from [Prior
-Art](#prior_art)---when viewed under the lense of our [Core Guiding
+Art](#prior-art)---when viewed under the lense of our [Core Guiding
 Principles](#guiding_principles)---with the following picture.
 
 <img width="1200" alt="MLIR Codegen Flow"
 src="https://user-images.githubusercontent.com/10148468/73613904-2f720a00-45c8-11ea-8265-1c856c02525b.png">
 
 This figure is not meant to be perfectly accurate but a rough map of
 how we view the distribution of structural information in existing
 systems, from a codegen-friendly angle. Unsurprisingly, the
-[Linalg Dialect](../Dialects/Linalg/) and its
+[Linalg Dialect](../Dialects/Linalg.md) and its
 future evolutions aspire to a position in the top-right of this map.