Markdown links migration part 1 (#20319)

Markdown link migration part 1

Also the warning is improved a bit.

Local links (targeting inside its document) which had had a full anchor
were turned into concise form.
The very fact that they existed may be due to the bug in
reference to subsections fixed https://github.com/nim-lang/Nim/pull/20279,
now they are working well (both in RST syntax and
new Pandoc Markdown syntax implemented in
https://github.com/nim-lang/Nim/pull/20304)

1 files changed, 71 insertions, 77 deletions

diff --git a/doc/manual.md b/doc/manual.md
index 1455334ca..3034bc65f 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -22,16 +22,16 @@ About this document
 precise wording. This manual is constantly evolving into a proper specification.
 
 **Note**: The experimental features of Nim are
-covered `here <manual_experimental.html>`_.
+covered [here](manual_experimental.html).
 
 **Note**: Assignments, moves, and destruction are specified in
-the `destructors <destructors.html>`_ document.
+the [destructors](destructors.html) document.
 
 
 This document describes the lexis, the syntax, and the semantics of the Nim language.
 
 To learn how to compile Nim programs and generate documentation see
-the `Compiler User Guide <nimc.html>`_ and the `DocGen Tools Guide <docgen.html>`_.
+the [Compiler User Guide](nimc.html) and the [DocGen Tools Guide](docgen.html).
 
 The language constructs are explained using an extended BNF, in which `(a)*`
 means 0 or more `a`'s, `a+` means 1 or more `a`'s, and `(a)?` means an
@@ -94,8 +94,8 @@ In a typical Nim program, most of the code is compiled into the executable.
 However, some code may be executed at
 `compile-time`:idx:. This can include constant expressions, macro definitions,
 and Nim procedures used by macro definitions. Most of the Nim language is
-supported at compile-time, but there are some restrictions -- see `Restrictions
-on Compile-Time Execution <#restrictions-on-compileminustime-execution>`_ for
+supported at compile-time, but there are some restrictions -- see [Restrictions
+on Compile-Time Execution] for
 details. We use the term `runtime`:idx: to cover both compile-time execution
 and code execution in the executable.
 
@@ -111,7 +111,7 @@ A `panic`:idx: is an error that the implementation detects
 and reports at runtime. The method for reporting such errors is via
 *raising exceptions* or *dying with a fatal error*. However, the implementation
 provides a means to disable these `runtime checks`:idx:. See the section
-pragmas_ for details.
+[Pragmas] for details.
 
 Whether a panic results in an exception or in a fatal error is
 implementation specific. Thus, the following program is invalid; even though the
@@ -499,7 +499,7 @@ Rationale: It enables the efficient support of `array[char, int]` or
 `set[char]`.
 
 The `Rune` type can represent any Unicode character.
-`Rune` is declared in the `unicode module <unicode.html>`_.
+`Rune` is declared in the [unicode module](unicode.html).
 
 A character literal that does not end in `'` is interpreted as `'` if there
 is a preceding backtick token. There must be no whitespace between the preceding
@@ -507,7 +507,7 @@ backtick token and the character literal. This special case ensures that a decla
 like ``proc `'customLiteral`(s: string)`` is valid. ``proc `'customLiteral`(s: string)``
 is the same as ``proc `'\''customLiteral`(s: string)``.
 
-See also `custom numeric literals <#custom-numeric-literals>`_.
+See also [custom numeric literals].
 
 
 Numeric literals
@@ -713,7 +713,7 @@ Syntax
 ======
 
 This section lists Nim's standard syntax. How the parser handles
-the indentation is already described in the `Lexical Analysis`_ section.
+the indentation is already described in the [Lexical Analysis] section.
 
 Nim allows user-definable operators.
 Binary operators have 11 different levels of precedence.
@@ -1100,8 +1100,7 @@ if the literal's value fits this smaller type and such a conversion is less
 expensive than other implicit conversions, so `myInt16 + 34` produces
 an `int16` result.
 
-For further details, see `Convertible relation
-<#type-relations-convertible-relation>`_.
+For further details, see [Convertible relation].
 
 
 Subrange types
@@ -1148,8 +1147,7 @@ The following floating-point types are pre-defined:
 
 
 Automatic type conversion in expressions with different kinds of floating-point
-types is performed: See `Convertible relation
-<#type-relations-convertible-relation>`_ for further details. Arithmetic
+types is performed: See [Convertible relation] for further details. Arithmetic
 performed on floating-point types follows the IEEE standard. Integer types are
 not converted to floating-point types automatically and vice versa.
 
@@ -1229,7 +1227,7 @@ The character type is named `char` in Nim. Its size is one byte.
 Thus, it cannot represent a UTF-8 character, but a part of it.
 
 The `Rune` type is used for Unicode characters, it can represent any Unicode
-character. `Rune` is declared in the `unicode module <unicode.html>`_.
+character. `Rune` is declared in the [unicode module](unicode.html).
 
 
 
@@ -1315,7 +1313,7 @@ as `MyEnum.value`:
   echo MyEnum.amb # OK.
   ```
 
-To implement bit fields with enums see `Bit fields <#set-type-bit-fields>`_
+To implement bit fields with enums see [Bit fields].
 
 
 String type
@@ -1375,8 +1373,8 @@ arrays, they can be used in case statements:
 Per convention, all strings are UTF-8 strings, but this is not enforced. For
 example, when reading strings from binary files, they are merely a sequence of
 bytes. The index operation `s[i]` means the i-th *char* of `s`, not the
-i-th *unichar*. The iterator `runes` from the `unicode module
-<unicode.html>`_ can be used for iteration over all Unicode characters.
+i-th *unichar*. The iterator `runes` from the [unicode module](unicode.html)
+can be used for iteration over all Unicode characters.
 
 
 cstring type
@@ -1733,8 +1731,8 @@ introduce new object roots apart from `system.RootObj`.
   ```
 
 The assignment operator for tuples and objects copies each component.
-The methods to override this copying behavior are described `here
-<manual.html#procedures-type-bound-operations>`_.
+The methods to override this copying behavior are described [here][type
+bound operators].
 
 
 Object construction
@@ -1947,8 +1945,8 @@ dereferencing operations for reference types:
   ```
 
 Automatic dereferencing can be performed for the first argument of a routine
-call, but this is an experimental feature and is described `here
-<manual_experimental.html#automatic-dereferencing>`_.
+call, but this is an experimental feature and is described [here](
+manual_experimental.html#automatic-dereferencing).
 
 In order to simplify structural type checking, recursive tuples are not valid:
 
@@ -1973,7 +1971,7 @@ This feature is useful if an object should only gain reference semantics:
 
 To allocate a new traced object, the built-in procedure `new` has to be used.
 To deal with untraced memory, the procedures `alloc`, `dealloc` and
-`realloc` can be used. The documentation of the `system <system.html>`_ module
+`realloc` can be used. The documentation of the [system](system.html) module
 contains further information.
 
 
@@ -2225,7 +2223,7 @@ the proc that deals with the distinct type's base type, so no code is
 generated.
 
 But it seems all this boilerplate code needs to be repeated for the `Euro`
-currency. This can be solved with templates_.
+currency. This can be solved with [templates].
 
   ```nim  test = "nim c $1"
   template additive(typ: typedesc) =
@@ -2341,8 +2339,8 @@ conversions from `string` to `SQL` are allowed:
 Now we have compile-time checking against SQL injection attacks. Since
 `"".SQL` is transformed to `SQL("")` no new syntax is needed for nice
 looking `SQL` string literals. The hypothetical `SQL` type actually
-exists in the library as the `SqlQuery type <db_common.html#SqlQuery>`_ of
-modules like `db_sqlite <db_sqlite.html>`_.
+exists in the library as the [SqlQuery type](db_common.html#SqlQuery) of
+modules like [db_sqlite](db_sqlite.html).
 
 
 Auto type
@@ -2671,7 +2669,7 @@ metatypes `typed` and `typedesc` are not lazy.
 Varargs matching
 ----------------
 
-See `Varargs <#types-varargs>`_.
+See [Varargs].
 
 
 iterable
@@ -2989,8 +2987,7 @@ A const section declares constants whose values are constant expressions:
 
 Once declared, a constant's symbol can be used as a constant expression.
 
-See `Constants and Constant Expressions <#constants-and-constant-expressions>`_
-for details.
+See [Constants and Constant Expressions] for details.
 
 Static statement/expression
 ---------------------------
@@ -3018,8 +3015,7 @@ Even some code that has side effects is permitted in a static block:
   ```
 
 There are limitations on what Nim code can be executed at compile time;
-see `Restrictions on Compile-Time Execution
-<#restrictions-on-compileminustime-execution>`_ for details.
+see [Restrictions on Compile-Time Execution] for details.
 It's a static error if the compiler cannot execute the block at compile
 time.
 
@@ -3273,7 +3269,7 @@ The `yield` statement is used instead of the `return` statement in
 iterators. It is only valid in iterators. Execution is returned to the body
 of the for loop that called the iterator. Yield does not end the iteration
 process, but the execution is passed back to the iterator if the next iteration
-starts. See the section about iterators (`Iterators and the for statement`_)
+starts. See the section about iterators ([Iterators and the for statement])
 for further information.
 
 
@@ -3786,8 +3782,7 @@ The method call syntax conflicts with explicit generic instantiations:
 `p[T](x)` cannot be written as `x.p[T]` because `x.p[T]` is always
 parsed as `(x.p)[T]`.
 
-See also: `Limitations of the method call syntax
-<#templates-limitations-of-the-method-call-syntax>`_.
+See also: [Limitations of the method call syntax].
 
 The `[: ]` notation has been designed to mitigate this issue: `x.p[:T]`
 is rewritten by the parser to `p[T](x)`, `x.p[:T](y)` is rewritten to
@@ -3873,7 +3868,7 @@ more argument in this case:
   ```
 
 The command invocation syntax also can't have complex expressions as arguments.
-For example: (`anonymous procs <#procedures-anonymous-procs>`_), `if`,
+For example: [anonymous procedures], `if`,
 `case` or `try`. Function calls with no arguments still need () to
 distinguish between a call and the function itself as a first-class value.
 
@@ -3893,9 +3888,9 @@ or on the stack if the compiler determines that this would be safe.
 ### Creating closures in loops
 
 Since closures capture local variables by reference it is often not wanted
-behavior inside loop bodies. See `closureScope
-<system.html#closureScope.t,untyped>`_ and `capture
-<sugar.html#capture.m,varargs[typed],untyped>`_ for details on how to change this behavior.
+behavior inside loop bodies. See [closureScope](
+system.html#closureScope.t,untyped) and [capture](
+sugar.html#capture.m,varargs[typed],untyped) for details on how to change this behavior.
 
 Anonymous procedures
 --------------------
@@ -3912,7 +3907,7 @@ procedures:
 
 
 Procs as expressions can appear both as nested procs and inside top-level
-executable code. The  `sugar <sugar.html>`_ module contains the `=>` macro
+executable code. The  [sugar](sugar.html) module contains the `=>` macro
 which enables a more succinct syntax for anonymous procedures resembling
 lambdas as they are in languages like JavaScript, C#, etc.
 
@@ -3982,7 +3977,7 @@ Type bound operators
 
 A type bound operator is a `proc` or `func` whose name starts with `=` but isn't an operator
 (i.e. containing only symbols, such as `==`). These are unrelated to setters
-(see `properties <manual.html#procedures-properties>`_), which instead end in `=`.
+(see [Properties]), which instead end in `=`.
 A type bound operator declared for a type applies to the type regardless of whether
 the operator is in scope (including if it is private).
 
@@ -4024,7 +4019,7 @@ This also means that one cannot override `deepCopy` for both `ptr T` and
 used for one pointer type.
 
 For more details on some of those procs, see
-`Lifetime-tracking hooks <destructors.html#lifetimeminustracking-hooks>`_.
+[Lifetime-tracking hooks](destructors.html#lifetimeminustracking-hooks).
 
 Nonoverloadable builtins
 ------------------------
@@ -4037,7 +4032,8 @@ simplicity (they require specialized semantic checking)::
 
 Thus, they act more like keywords than like ordinary identifiers; unlike a
 keyword however, a redefinition may `shadow`:idx: the definition in
-the system_ module. From this list the following should not be written in dot
+the [system](system.html) module.
+From this list the following should not be written in dot
 notation `x.f` since `x` cannot be type-checked before it gets passed
 to `f`::
 
@@ -4589,14 +4585,13 @@ would. For example:
   ```
 
 
-See also see `iterable <#overloading-resolution-iterable>`_ for passing iterators to templates and macros.
+See also [iterable] for passing iterators to templates and macros.
 
 Converters
 ==========
 
 A converter is like an ordinary proc except that it enhances
-the "implicitly convertible" type relation (see `Convertible relation
-<#type-relations-convertible-relation>`_):
+the "implicitly convertible" type relation (see [Convertible relation]):
 
   ```nim
   # bad style ahead: Nim is not C.
@@ -4859,7 +4854,7 @@ exception.
 Exception hierarchy
 -------------------
 
-The exception tree is defined in the `system <system.html>`_ module.
+The exception tree is defined in the [system](system.html) module.
 Every exception inherits from `system.Exception`. Exceptions that indicate
 programming bugs inherit from `system.Defect` (which is a subtype of `Exception`)
 and are strictly speaking not catchable as they can also be mapped to an operation
@@ -5146,8 +5141,8 @@ or global variable and it does not call any routine that has a side effect.
 
 It is a static error to mark a proc/iterator to have no side effect if the compiler cannot verify this.
 
-As a special semantic rule, the built-in `debugEcho
-<system.html#debugEcho,varargs[typed,]>`_ pretends to be free of side effects
+As a special semantic rule, the built-in [debugEcho](
+system.html#debugEcho,varargs[typed,]) pretends to be free of side effects
 so that it can be used for debugging routines marked as `noSideEffect`.
 
 `func` is syntactic sugar for a proc with no side effects:
@@ -5202,7 +5197,7 @@ be used:
 
 See also:
 
-- `Shared heap memory management <mm.html>`_.
+- [Shared heap memory management](mm.html).
 
 
 
@@ -6146,8 +6141,8 @@ and are not looked up again. As the example shows, `bindSym` does work with
 overloaded symbols implicitly.
 
 Note that the symbol names passed to `bindSym` have to be constant. The
-experimental feature `dynamicBindSym` (`experimental manual
-<manual_experimental.html#dynamic-arguments-for-bindsym>`_)
+experimental feature `dynamicBindSym` ([experimental manual](
+manual_experimental.html#dynamic-arguments-for-bindsym))
 allows this value to be computed dynamically.
 
 Post-statement blocks
@@ -6287,8 +6282,8 @@ macro to call.
 Special Types
 =============
 
-static[T]
----------
+static\[T]
+----------
 
 As their name suggests, static parameters must be constant expressions:
 
@@ -6341,8 +6336,8 @@ expression by coercing it to a corresponding `static` type:
 The compiler will report any failure to evaluate the expression or a
 possible type mismatch error.
 
-typedesc[T]
------------
+typedesc\[T]
+------------
 
 In many contexts, Nim treats the names of types as regular
 values. These values exist only during the compilation phase, but since
@@ -7051,8 +7046,7 @@ extension the pragma is simply ignored.
 immediate pragma
 ----------------
 
-The immediate pragma is obsolete. See `Typed vs untyped parameters
-<#templates-typed-vs-untyped-parameters>`_.
+The immediate pragma is obsolete. See [Typed vs untyped parameters].
 
 redefine pragma
 ---------------
@@ -7230,7 +7224,7 @@ The `experimental` pragma enables experimental language features. Depending
 on the concrete feature, this means that the feature is either considered
 too unstable for an otherwise stable release or that the future of the feature
 is uncertain (it may be removed at any time). See the
-`experimental manual <manual_experimental.html>`_ for more details.
+[experimental manual](manual_experimental.html) for more details.
 
 Example:
 
@@ -7449,7 +7443,7 @@ compiler like one would use the command-line switch `--passc`:option:\:
   {.passc: "-Wall -Werror".}
   ```
 
-Note that one can use `gorge` from the `system module <system.html>`_ to
+Note that one can use `gorge` from the [system module](system.html) to
 embed parameters from an external command that will be executed
 during semantic analysis:
 
@@ -7480,7 +7474,7 @@ like one would be using the command-line switch `--passl`:option:\:
   {.passl: "-lSDLmain -lSDL".}
   ```
 
-Note that one can use `gorge` from the `system module <system.html>`_ to
+Note that one can use `gorge` from the [system module](system.html) to
 embed parameters from an external command that will be executed
 during semantic analysis:
 
@@ -7553,13 +7547,13 @@ the code should be emitted can be influenced via the prefixes
 ImportCpp pragma
 ----------------
 
-**Note**: `c2nim <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_ can parse a large subset of C++ and knows
+**Note**: [c2nim](https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst)
+can parse a large subset of C++ and knows
 about the `importcpp` pragma pattern language. It is not necessary
 to know all the details described here.
 
 
-Similar to the `importc pragma for C
-<#foreign-function-interface-importc-pragma>`_, the
+Similar to the [importc pragma] for C, the
 `importcpp` pragma can be used to import `C++`:idx: methods or C++ symbols
 in general. The generated code then uses the C++ method calling
 syntax: `obj->method(arg)`:cpp:. In combination with the `header` and `emit`
@@ -7791,7 +7785,7 @@ Produces:
 ImportJs pragma
 ---------------
 
-Similar to the `importcpp pragma for C++ <#implementation-specific-pragmas-importcpp-pragma>`_,
+Similar to the [importcpp pragma] for C++,
 the `importjs` pragma can be used to import Javascript methods or
 symbols in general. The generated code then uses the Javascript method
 calling syntax: ``obj.method(arg)``.
@@ -7799,8 +7793,7 @@ calling syntax: ``obj.method(arg)``.
 
 ImportObjC pragma
 -----------------
-Similar to the `importc pragma for C
-<#foreign-function-interface-importc-pragma>`_, the `importobjc` pragma can
+Similar to the [importc pragma] for C, the `importobjc` pragma can
 be used to import `Objective C`:idx: methods. The generated code then uses the
 Objective C method calling syntax: ``[obj method param1: arg]``.
 In addition with the `header` and `emit` pragmas this
@@ -8016,7 +8009,7 @@ definitions, statements, etc.
 
 The macros module includes helpers which can be used to simplify custom pragma
 access `hasCustomPragma`, `getCustomPragmaVal`. Please consult the
-`macros <macros.html>`_ module documentation for details. These macros are not
+[macros](macros.html) module documentation for details. These macros are not
 magic, everything they do can also be achieved by walking the AST of the object
 representation.
 
@@ -8084,8 +8077,8 @@ the same way.
 
 There are a few more applications of macro pragmas, such as in type,
 variable and constant declarations, but this behavior is considered to be
-experimental and is documented in the `experimental manual
-<manual_experimental.html#extended-macro-pragmas>`_ instead.
+experimental and is documented in the [experimental manual](
+manual_experimental.html#extended-macro-pragmas) instead.
 
 
 Foreign function interface
@@ -8123,9 +8116,9 @@ JS backend for JS objects and functions. Other backends do provide
 the same feature under the same name. Also, when the target language
 is not set to C, other pragmas are available:
 
- * `importcpp <manual.html#implementation-specific-pragmas-importcpp-pragma>`_
- * `importobjc <manual.html#implementation-specific-pragmas-importobjc-pragma>`_
- * `importjs <manual.html#implementation-specific-pragmas-importjs-pragma>`_
+ * [importcpp][importcpp pragma]
+ * [importobjc][importobjc pragma]
+ * [importjs][importjs pragma]
 
 The string literal passed to `importc` can be a format string:
 
@@ -8163,7 +8156,7 @@ is available and a literal dollar sign must be written as ``$$``.
 
 If the symbol should also be exported to a dynamic library, the `dynlib`
 pragma should be used in addition to the `exportc` pragma. See
-`Dynlib pragma for export <#foreign-function-interface-dynlib-pragma-for-export>`_.
+[Dynlib pragma for export].
 
 
 Extern pragma
@@ -8296,7 +8289,7 @@ because of order of initialization problems.
 
 **Note**: A `dynlib` import can be overridden with
 the `--dynlibOverride:name`:option: command-line option. The
-`Compiler User Guide <nimc.html>`_ contains further information.
+[Compiler User Guide](nimc.html) contains further information.
 
 
 Dynlib pragma for export
@@ -8319,10 +8312,10 @@ Threads
 =======
 
 To enable thread support the `--threads:on`:option: command-line switch needs to
-be used. The system_ module then contains several threading primitives.
-See the `channels <channels_builtin.html>`_ modules
+be used. The [system module](system.html) module then contains several threading primitives.
+See the [channels](channels_builtin.html) modules
 for the low-level thread API. There are also high-level parallelism constructs
-available. See `spawn <manual_experimental.html#parallel-amp-spawn>`_ for
+available. See [spawn](manual_experimental.html#parallel-amp-spawn) for
 further details.
 
 Nim's memory model for threads is quite different than that of other common
@@ -8452,7 +8445,8 @@ model low level lockfree mechanisms:
 
 The `locks` pragma takes a list of lock expressions `locks: [a, b, ...]`
 in order to support *multi lock* statements. Why these are essential is
-explained in the `lock levels <#guards-and-locks-lock-levels>`_ section.
+explained in the [lock levels](manual_experimental.md#lock-levels) section
+of experimental manual.
 
 
 ### Protecting general locations