Fix many broken links and prefer relative links within docs (#12463)

* Fix many broken links

Note that contrary to what docgen.rst currently says, the ids have
to match exactly or else most web browsers will not jump to the
intended symbol.

* Prefer relative links for Nim documentation

This is more friendly to those browsing the documentation without
a network connection. The nim-doc package in Debian allows this,
for example.

Also, the domain name being used was not consistent. It could have
been either nim-lang.org or nim-lang.github.io, and those reading
the stable docs could have found themselves suddenly reading the
devel docs instead.

* koch.rst: remove link to nonexistent section

* manual.rst: remove unintended link

cast[T](0) is interpreted as a link to id 0 with text T, so escape
the opening parentheses to display the intended output.

* asyncstreams: replace unintended link with emphasis

* Fix word wrapping

lib/core/macros.nim

@@ -13,8 +13,8 @@ include "system/inclrtl"
 ## tree (`AST`:idx:). Macros operate on this tree.
 ##
 ## See also:
-## * `macros tutorial <https://nim-lang.github.io/Nim/tut3.html>`_
-## * `macros section in Nim manual <https://nim-lang.github.io/Nim/manual.html#macros>`_
+## * `macros tutorial <tut3.html>`_
+## * `macros section in Nim manual <manual.html#macros>`_
 
 ## .. include:: ../../doc/astspec.txt
 

lib/js/dom.nim

@@ -8,7 +8,7 @@
 #
 
 ## Declaration of the Document Object Model for the `JavaScript backend
-## <backends.html#the-javascript-target>`_.
+## <backends.html#backends-the-javascript-target>`_.
 
 when not defined(js) and not defined(Nimdoc):
   {.error: "This module only works on the JavaScript platform".}

lib/js/jsconsole.nim

@@ -8,7 +8,7 @@
 #
 
 ## Wrapper for the `console` object for the `JavaScript backend
-## <backends.html#the-javascript-target>`_.
+## <backends.html#backends-the-javascript-target>`_.
 
 when not defined(js) and not defined(Nimdoc):
   {.error: "This module only works on the JavaScript platform".}

lib/packages/docutils/rstgen.nim

@@ -154,7 +154,8 @@ proc writeIndexFile*(g: var RstGenerator, outfile: string) =
   ## Writes the current index buffer to the specified output file.
   ##
   ## You previously need to add entries to the index with the `setIndexTerm()
-  ## <#setIndexTerm>`_ proc. If the index is empty the file won't be created.
+  ## <#setIndexTerm,RstGenerator,string,string,string,string,string>`_ proc.
+  ## If the index is empty the file won't be created.
   if g.theIndex.len > 0: writeFile(outfile, g.theIndex)
 
 proc addXmlChar(dest: var string, c: char) =
@@ -308,7 +309,7 @@ proc setIndexTerm*(d: var RstGenerator, htmlFile, id, term: string,
   ## The `id` will be appended with a hash character only if its length is not
   ## zero, otherwise no specific anchor will be generated. In general you
   ## should only pass an empty `id` value for the title of standalone rst
-  ## documents (they are special for the `mergeIndexes() <#mergeIndexes>`_
+  ## documents (they are special for the `mergeIndexes() <#mergeIndexes,string>`_
   ## proc, see `Index (idx) file format <docgen.html#index-idx-file-format>`_
   ## for more information). Unlike other index terms, title entries are
   ## inserted at the beginning of the accumulated buffer to maintain a logical
@@ -318,8 +319,9 @@ proc setIndexTerm*(d: var RstGenerator, htmlFile, id, term: string,
   ## columns with their contents will be added.
   ##
   ## The index won't be written to disk unless you call `writeIndexFile()
-  ## <#writeIndexFile>`_. The purpose of the index is documented in the `docgen
-  ## tools guide <docgen.html#index-switch>`_.
+  ## <#writeIndexFile,RstGenerator,string>`_. The purpose of the index is
+  ## documented in the `docgen tools guide
+  ## <docgen.html#related-options-index-switch>`_.
   var
     entry = term
     isTitle = false
@@ -472,8 +474,8 @@ proc generateSymbolIndex(symbols: seq[IndexEntry]): string =
 proc isDocumentationTitle(hyperlink: string): bool =
   ## Returns true if the hyperlink is actually a documentation title.
   ##
-  ## Documentation titles lack the hash. See `mergeIndexes() <#mergeIndexes>`_
-  ## for a more detailed explanation.
+  ## Documentation titles lack the hash. See `mergeIndexes()
+  ## <#mergeIndexes,string>`_ for a more detailed explanation.
   result = hyperlink.find('#') < 0
 
 proc stripTocLevel(s: string): tuple[level: int, text: string] =
@@ -650,8 +652,10 @@ proc mergeIndexes*(dir: string): string =
   ## This proc will first scan `dir` for index files with the ``.idx``
   ## extension previously created by commands like ``nim doc|rst2html``
   ## which use the ``--index:on`` switch. These index files are the result of
-  ## calls to `setIndexTerm() <#setIndexTerm>`_ and `writeIndexFile()
-  ## <#writeIndexFile>`_, so they are simple tab separated files.
+  ## calls to `setIndexTerm()
+  ## <#setIndexTerm,RstGenerator,string,string,string,string,string>`_
+  ## and `writeIndexFile() <#writeIndexFile,RstGenerator,string>`_, so they are
+  ## simple tab separated files.
   ##
   ## As convention this proc will split index files into two categories:
   ## documentation and API. API indices will be all joined together into a

lib/posix/posix.nim

@@ -584,7 +584,7 @@ proc fchmod*(a1: cint, a2: Mode): cint {.importc, header: "<sys/stat.h>".}
 proc fstat*(a1: cint, a2: var Stat): cint {.importc, header: "<sys/stat.h>".}
 proc lstat*(a1: cstring, a2: var Stat): cint {.importc, header: "<sys/stat.h>".}
 proc mkdir*(a1: cstring, a2: Mode): cint {.importc, header: "<sys/stat.h>".}
-  ## Use `os.createDir() <os.html#createDir>`_ and similar.
+  ## Use `os.createDir() <os.html#createDir,string>`_ and similar.
 
 proc mkfifo*(a1: cstring, a2: Mode): cint {.importc, header: "<sys/stat.h>".}
 proc mknod*(a1: cstring, a2: Mode, a3: Dev): cint {.

lib/pure/algorithm.nim

@@ -392,7 +392,7 @@ func sort*[T](a: var openArray[T],
   ##    sort(myStrArray, system.cmp)
   ##
   ## You can inline adhoc comparison procs with the `do notation
-  ## <manual.html#procedures-do-notation>`_. Example:
+  ## <manual_experimental.html#do-notation>`_. Example:
   ##
   ## .. code-block:: nim
   ##

lib/pure/asyncstreams.nim

@@ -60,7 +60,7 @@ proc `callback=`*[T](future: FutureStream[T],
 
 proc finished*[T](future: FutureStream[T]): bool =
   ## Check if a ``FutureStream`` is finished. ``true`` value means that
-  ## no more data will be placed inside the stream _and_ that there is
+  ## no more data will be placed inside the stream *and* that there is
   ## no data waiting to be retrieved.
   result = future.finished and future.queue.len == 0
 

lib/pure/base64.nim

@@ -175,8 +175,8 @@ proc decode*(s: string): string =
   ## The initial whitespace is skipped.
   ##
   ## **See also:**
-  ## * `encode proc<#encode,openArray[T],int,string>`_ for encoding an openarray
-  ## * `encode proc<#encode,string,int,string>`_ for encoding a string
+  ## * `encode proc<#encode,openArray[T]>`_ for encoding an openarray
+  ## * `encode proc<#encode,string>`_ for encoding a string
   runnableExamples:
     assert decode("SGVsbG8gV29ybGQ=") == "Hello World"
     assert decode("  SGVsbG8gV29ybGQ=") == "Hello World"

lib/pure/collections/lists.nim

@@ -69,8 +69,8 @@
 ## See also
 ## ========
 ##
-## * `deques module <#deques.html>`_ for double-ended queues
-## * `sharedlist module <#sharedlist.html>`_ for shared singly-linked lists
+## * `deques module <deques.html>`_ for double-ended queues
+## * `sharedlist module <sharedlist.html>`_ for shared singly-linked lists
 
 
 when not defined(nimhygiene):

lib/pure/collections/sequtils.nim

@@ -35,7 +35,7 @@
 ##   `filterIt<#filterIt.t,untyped,untyped>`_, etc.)
 ##
 ## The chaining of functions is possible thanks to the
-## `method call syntax<manual.html#procs-method-call-syntax>`_.
+## `method call syntax<manual.html#procedures-method-call-syntax>`_.
 ##
 ## .. code-block::
 ##   import sequtils, sugar

lib/pure/collections/sets.nim

@@ -99,8 +99,8 @@ proc init*[A](s: var HashSet[A], initialSize = defaultInitialSize) =
   ##
   ## The `initialSize` parameter needs to be a power of two (default: 64).
   ## If you need to accept runtime values for this, you can use
-  ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo>`_ or `rightSize proc
-  ## <#rightSize,Natural>`_ from this module.
+  ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo,int>`_ or
+  ## `rightSize proc <#rightSize,Natural>`_ from this module.
   ##
   ## Starting from Nim v0.20, sets are initialized by default and it is
   ## not necessary to call this function explicitly.
@@ -645,8 +645,8 @@ proc init*[A](s: var OrderedSet[A], initialSize = defaultInitialSize) =
   ##
   ## The `initialSize` parameter needs to be a power of two (default: 64).
   ## If you need to accept runtime values for this, you can use
-  ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo>`_ or `rightSize proc
-  ## <#rightSize,Natural>`_ from this module.
+  ## `math.nextPowerOfTwo proc <math.html#nextPowerOfTwo,int>`_ or
+  ## `rightSize proc <#rightSize,Natural>`_ from this module.
   ##
   ## Starting from Nim v0.20, sets are initialized by default and it is
   ## not necessary to call this function explicitly.

lib/pure/collections/tables.nim

@@ -134,7 +134,8 @@
 ##   # 'a': 5, 'b': 2, 'c': 1, 'd': 1, 'r': 2}
 ##
 ## The same could have been achieved by manually iterating over a container
-## and increasing each key's value with `inc proc<#inc,CountTable[A],A,int>`_:
+## and increasing each key's value with `inc proc
+## <#inc,CountTable[A],A,Positive>`_:
 ##
 ## .. code-block::
 ##   import tables
@@ -2236,7 +2237,7 @@ proc `[]=`*[A](t: var CountTable[A], key: A, val: int) =
   ##
   ## See also:
   ## * `[] proc<#[],CountTable[A],A>`_ for retrieving a value of a key
-  ## * `inc proc<#inc,CountTable[A],A,int>`_ for incrementing a
+  ## * `inc proc<#inc,CountTable[A],A,Positive>`_ for incrementing a
   ##   value of a key
   assert(not t.isSorted, "CountTable must not be used after sorting")
   assert val >= 0

lib/pure/concurrency/threadpool.nim

@@ -487,7 +487,7 @@ proc parallel*(body: untyped) {.magic: "Parallel".}
   ##
   ## ``body`` has to be in a DSL that is a particular subset of the language.
   ##
-  ## Please refer to `the manual <manual.html#parallel-amp-spawn>`_
+  ## Please refer to `the manual <manual_experimental.html#parallel-amp-spawn>`_
   ## for further information.
 
 var

lib/pure/htmlgen.nim

@@ -11,7 +11,7 @@
 ## as ``from htmlgen import nil`` and then fully qualify the macros.
 ##
 ## *Note*: The Karax project (``nimble install karax``) has a better
-## way to achieve the same, see `https://github.com/pragmagic/karax/blob/master/tests/nativehtmlgen.nim`_
+## way to achieve the same, see https://github.com/pragmagic/karax/blob/master/tests/nativehtmlgen.nim
 ## for an example.
 ##
 ##

lib/pure/math.nim

@@ -35,7 +35,7 @@
 ##   # nan   (use `complex` module)
 ##
 ## This module is available for the `JavaScript target
-## <backends.html#the-javascript-target>`_.
+## <backends.html#backends-the-javascript-target>`_.
 ##
 ## **See also:**
 ## * `complex module<complex.html>`_ for complex numbers and their

lib/pure/memfiles.nim

@@ -431,9 +431,9 @@ iterator memSlices*(mfile: MemFile, delim = '\l', eat = '\r'): MemSlice {.inline
 iterator lines*(mfile: MemFile, buf: var TaintedString, delim = '\l',
     eat = '\r'): TaintedString {.inline.} =
   ## Replace contents of passed buffer with each new line, like
-  ## `readLine(File) <system.html#readLine,File,TaintedString>`_.
-  ## `delim`, `eat`, and delimiting logic is exactly as for
-  ## `memSlices <#memSlices>`_, but Nim strings are returned.
+  ## `readLine(File) <io.html#readLine,File,TaintedString>`_.
+  ## `delim`, `eat`, and delimiting logic is exactly as for `memSlices
+  ## <#memSlices.i,MemFile,char,char>`_, but Nim strings are returned.
   ##
   ## Example:
   ##
@@ -450,9 +450,9 @@ iterator lines*(mfile: MemFile, buf: var TaintedString, delim = '\l',
 
 iterator lines*(mfile: MemFile, delim = '\l', eat = '\r'): TaintedString {.inline.} =
   ## Return each line in a file as a Nim string, like
-  ## `lines(File) <system.html#lines.i,File>`_.
-  ## `delim`, `eat`, and delimiting logic is exactly as for
-  ## `memSlices <#memSlices>`_, but Nim strings are returned.
+  ## `lines(File) <io.html#lines.i,File>`_.
+  ## `delim`, `eat`, and delimiting logic is exactly as for `memSlices
+  ## <#memSlices.i,MemFile,char,char>`_, but Nim strings are returned.
   ##
   ## Example:
   ##

lib/pure/parsecsv.nim

@@ -57,7 +57,7 @@
 ## ========
 ##
 ## * `streams module <streams.html>`_ for using
-##   `open proc <#open,CsvParser,Stream,string,Char,Char,Char>`_
+##   `open proc <#open,CsvParser,Stream,string,char,char,char>`_
 ##   and other stream processing (like `close proc <streams.html#close,Stream>`_)
 ## * `parseopt module <parseopt.html>`_ for a command line parser
 ## * `parsecfg module <parsecfg.html>`_ for a configuration file parser
@@ -117,7 +117,7 @@ proc open*(my: var CsvParser, input: Stream, filename: string,
   ##   `separator` is ignored.
   ##
   ## See also:
-  ## * `open proc <#open,CsvParser,string,Char,Char,Char>`_ which creates the
+  ## * `open proc <#open,CsvParser,string,char,char,char>`_ which creates the
   ##   file stream for you
   runnableExamples:
     import streams
@@ -139,7 +139,7 @@ proc open*(my: var CsvParser, input: Stream, filename: string,
 proc open*(my: var CsvParser, filename: string,
            separator = ',', quote = '"', escape = '\0',
            skipInitialSpace = false) =
-  ## Similar to the `other open proc<#open,CsvParser,Stream,string,Char,Char,Char>`_,
+  ## Similar to the `other open proc<#open,CsvParser,Stream,string,char,char,char>`_,
   ## but creates the file stream for you.
   runnableExamples:
     from os import removeFile

lib/pure/random.nim

@@ -75,7 +75,7 @@
 ##   generator
 ## * `stats module<stats.html>`_ for statistical analysis
 ## * `list of cryptographic and hashing modules
-##   <lib.html#pure-libraries-cryptography-and-hashing>`_
+##   <lib.html#pure-libraries-hashing>`_
 ##   in the standard library
 
 import algorithm #For upperBound

lib/pure/streams.nim

@@ -1223,7 +1223,7 @@ else:
     ## * `newStringStream proc <#newStringStream,string>`_ creates a new stream
     ##   from string.
     ## * `newFileStream proc <#newFileStream,string,FileMode,int>`_ is the same
-    ##   as using `open proc <system.html#open,File,string,FileMode,int>`_
+    ##   as using `open proc <io.html#open,File,string,FileMode,int>`_
     ##   on Examples.
     ## * `openFileStream proc <#openFileStream,string,FileMode,int>`_ creates a
     ##   file stream from the file name and the mode.

lib/pure/strutils.nim

@@ -50,7 +50,7 @@
 ##          "Beetlejuice Beetlejuice Beetlejuice"
 ##
 ## This module is available for the `JavaScript target
-## <backends.html#the-javascript-target>`_.
+## <backends.html#backends-the-javascript-target>`_.
 ##
 ## ----
 ##
@@ -209,7 +209,7 @@ proc toLowerAscii*(c: char): char {.noSideEffect, procvar,
   ## Returns the lower case version of character ``c``.
   ##
   ## This works only for the letters ``A-Z``. See `unicode.toLower
-  ## <unicode.html#toLower>`_ for a version that works for any Unicode
+  ## <unicode.html#toLower,Rune>`_ for a version that works for any Unicode
   ## character.
   ##
   ## See also:
@@ -233,7 +233,7 @@ proc toLowerAscii*(s: string): string {.noSideEffect, procvar,
   ## Converts string `s` into lower case.
   ##
   ## This works only for the letters ``A-Z``. See `unicode.toLower
-  ## <unicode.html#toLower>`_ for a version that works for any Unicode
+  ## <unicode.html#toLower,string>`_ for a version that works for any Unicode
   ## character.
   ##
   ## See also:
@@ -247,7 +247,7 @@ proc toUpperAscii*(c: char): char {.noSideEffect, procvar,
   ## Converts character `c` into upper case.
   ##
   ## This works only for the letters ``A-Z``.  See `unicode.toUpper
-  ## <unicode.html#toUpper>`_ for a version that works for any Unicode
+  ## <unicode.html#toUpper,Rune>`_ for a version that works for any Unicode
   ## character.
   ##
   ## See also:
@@ -267,7 +267,7 @@ proc toUpperAscii*(s: string): string {.noSideEffect, procvar,
   ## Converts string `s` into upper case.
   ##
   ## This works only for the letters ``A-Z``.  See `unicode.toUpper
-  ## <unicode.html#toUpper>`_ for a version that works for any Unicode
+  ## <unicode.html#toUpper,string>`_ for a version that works for any Unicode
   ## character.
   ##
   ## See also:
@@ -631,10 +631,10 @@ iterator rsplit*(s: string, sep: string, maxsplit: int = -1,
 iterator splitLines*(s: string, keepEol = false): string =
   ## Splits the string `s` into its containing lines.
   ##
-  ## Every `character literal <manual.html#character-literals>`_ newline
-  ## combination (CR, LF, CR-LF) is supported. The result strings contain no
-  ## trailing end of line characters unless parameter ``keepEol`` is set to
-  ## ``true``.
+  ## Every `character literal <manual.html#lexical-analysis-character-literals>`_
+  ## newline combination (CR, LF, CR-LF) is supported. The result strings
+  ## contain no trailing end of line characters unless parameter ``keepEol``
+  ## is set to ``true``.
   ##
   ## Example:
   ##
@@ -1308,8 +1308,8 @@ proc spaces*(n: Natural): string {.inline.} =
   ## to left align strings.
   ##
   ## See also:
-  ## * `align proc<#align,string,Natural,Char>`_
-  ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_
+  ## * `align proc<#align,string,Natural,char>`_
+  ## * `alignLeft proc<#alignLeft,string,Natural,char>`_
   ## * `indent proc<#indent,string,Natural,string>`_
   ## * `center proc<#center,string,int,char>`_
   runnableExamples:
@@ -1330,10 +1330,10 @@ proc align*(s: string, count: Natural, padding = ' '): string {.
   ## `padding` characters (by default spaces) are added before `s` resulting in
   ## right alignment. If ``s.len >= count``, no spaces are added and `s` is
   ## returned unchanged. If you need to left align a string use the `alignLeft
-  ## proc <#alignLeft,string,Natural,Char>`_.
+  ## proc <#alignLeft,string,Natural,char>`_.
   ##
   ## See also:
-  ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_
+  ## * `alignLeft proc<#alignLeft,string,Natural,char>`_
   ## * `spaces proc<#spaces,Natural>`_
   ## * `indent proc<#indent,string,Natural,string>`_
   ## * `center proc<#center,string,int,char>`_
@@ -1357,10 +1357,10 @@ proc alignLeft*(s: string, count: Natural, padding = ' '): string {.
   ## `padding` characters (by default spaces) are added after `s` resulting in
   ## left alignment. If ``s.len >= count``, no spaces are added and `s` is
   ## returned unchanged. If you need to right align a string use the `align
-  ## proc <#align,string,Natural,Char>`_.
+  ## proc <#align,string,Natural,char>`_.
   ##
   ## See also:
-  ## * `align proc<#align,string,Natural,Char>`_
+  ## * `align proc<#align,string,Natural,char>`_
   ## * `spaces proc<#spaces,Natural>`_
   ## * `indent proc<#indent,string,Natural,string>`_
   ## * `center proc<#center,string,int,char>`_
@@ -1387,8 +1387,8 @@ proc center*(s: string, width: int, fillChar: char = ' '): string {.
   ## to `s.len`.
   ##
   ## See also:
-  ## * `align proc<#align,string,Natural,Char>`_
-  ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_
+  ## * `align proc<#align,string,Natural,char>`_
+  ## * `alignLeft proc<#alignLeft,string,Natural,char>`_
   ## * `spaces proc<#spaces,Natural>`_
   ## * `indent proc<#indent,string,Natural,string>`_
   runnableExamples:
@@ -1420,8 +1420,8 @@ proc indent*(s: string, count: Natural, padding: string = " "): string
   ## **Note:** This does not preserve the new line characters used in ``s``.
   ##
   ## See also:
-  ## * `align proc<#align,string,Natural,Char>`_
-  ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_
+  ## * `align proc<#align,string,Natural,char>`_
+  ## * `alignLeft proc<#alignLeft,string,Natural,char>`_
   ## * `spaces proc<#spaces,Natural>`_
   ## * `unindent proc<#unindent,string,Natural,string>`_
   runnableExamples:
@@ -1445,8 +1445,8 @@ proc unindent*(s: string, count: Natural, padding: string = " "): string
   ## **Note:** This does not preserve the new line characters used in ``s``.
   ##
   ## See also:
-  ## * `align proc<#align,string,Natural,Char>`_
-  ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_
+  ## * `align proc<#align,string,Natural,char>`_
+  ## * `alignLeft proc<#alignLeft,string,Natural,char>`_
   ## * `spaces proc<#spaces,Natural>`_
   ## * `indent proc<#indent,string,Natural,string>`_
   runnableExamples:
@@ -1471,8 +1471,8 @@ proc unindent*(s: string): string
   ## Removes all indentation composed of whitespace from each line in ``s``.
   ##
   ## See also:
-  ## * `align proc<#align,string,Natural,Char>`_
-  ## * `alignLeft proc<#alignLeft,string,Natural,Char>`_
+  ## * `align proc<#align,string,Natural,char>`_
+  ## * `alignLeft proc<#alignLeft,string,Natural,char>`_
   ## * `spaces proc<#spaces,Natural>`_
   ## * `indent proc<#indent,string,Natural,string>`_
   runnableExamples:
@@ -1862,7 +1862,7 @@ proc find*(s: string, sub: char, start: Natural = 0, last = 0): int {.noSideEffe
   ## Use `s[start..last].rfind` for a ``start``-origin index.
   ##
   ## See also:
-  ## * `rfind proc<#rfind,string,char,int,int>`_
+  ## * `rfind proc<#rfind,string,char,Natural,int>`_
   ## * `replace proc<#replace,string,char,char>`_
   let last = if last == 0: s.high else: last
   when nimvm:
@@ -1890,7 +1890,7 @@ proc find*(s: string, chars: set[char], start: Natural = 0, last = 0): int {.noS
   ## Use `s[start..last].find` for a ``start``-origin index.
   ##
   ## See also:
-  ## * `rfind proc<#rfind,string,set[char],int,int>`_
+  ## * `rfind proc<#rfind,string,set[char],Natural,int>`_
   ## * `multiReplace proc<#multiReplace,string,varargs[]>`_
   let last = if last == 0: s.high else: last
   for i in int(start)..last:
@@ -1907,7 +1907,7 @@ proc find*(s, sub: string, start: Natural = 0, last = 0): int {.noSideEffect,
   ## Use `s[start..last].find` for a ``start``-origin index.
   ##
   ## See also:
-  ## * `rfind proc<#rfind,string,string,int,int>`_
+  ## * `rfind proc<#rfind,string,string,Natural,int>`_
   ## * `replace proc<#replace,string,string,string>`_
   if sub.len > s.len: return -1
   if sub.len == 1: return find(s, sub[0], start, last)
@@ -1927,7 +1927,7 @@ proc rfind*(s: string, sub: char, start: Natural = 0, last = -1): int {.noSideEf
   ## Use `s[start..last].find` for a ``start``-origin index.
   ##
   ## See also:
-  ## * `find proc<#find,string,char,int,int>`_
+  ## * `find proc<#find,string,char,Natural,int>`_
   let last = if last == -1: s.high else: last
   for i in countdown(last, start):
     if sub == s[i]: return i
@@ -2101,7 +2101,8 @@ proc replace*(s: string, sub, by: char): string {.noSideEffect,
   rtl, extern: "nsuReplaceChar".} =
   ## Replaces `sub` in `s` by the character `by`.
   ##
-  ## Optimized version of `replace <#replace,string,string>`_ for characters.
+  ## Optimized version of `replace <#replace,string,string,string>`_ for
+  ## characters.
   ##
   ## See also:
   ## * `find proc<#find,string,char,Natural,int>`_

lib/std/sha1.nim

@@ -211,7 +211,7 @@ proc secureHashFile*(filename: string): SecureHash =
   ## Generates a ``SecureHash`` from a file.
   ##
   ## **See also:**
-  ## * `secureHash proc <#secureHash,string>`_ for generating a ``SecureHash`` from a string
+  ## * `secureHash proc <#secureHash,openArray[char]>`_ for generating a ``SecureHash`` from a string
   ## * `parseSecureHash proc <#parseSecureHash,string>`_ for converting a string ``hash`` to ``SecureHash``
   secureHash(readFile(filename))
 
@@ -219,7 +219,7 @@ proc `$`*(self: SecureHash): string =
   ## Returns the string representation of a ``SecureHash``.
   ##
   ## **See also:**
-  ## * `secureHash proc <#secureHash,string>`_ for generating a ``SecureHash`` from a string
+  ## * `secureHash proc <#secureHash,openArray[char]>`_ for generating a ``SecureHash`` from a string
   runnableExamples:
     let hash = secureHash("Hello World")
     assert $hash == "0A4D55A8D778E5022FAB701977C5D840BBC486D0"
@@ -231,7 +231,7 @@ proc parseSecureHash*(hash: string): SecureHash =
   ## Converts a string ``hash`` to ``SecureHash``.
   ##
   ## **See also:**
-  ## * `secureHash proc <#secureHash,string>`_ for generating a ``SecureHash`` from a string
+  ## * `secureHash proc <#secureHash,openArray[char]>`_ for generating a ``SecureHash`` from a string
   ## * `secureHashFile proc <#secureHashFile,string>`_ for generating a ``SecureHash`` from a file
   runnableExamples:
     let

lib/system.nim

@@ -112,8 +112,8 @@ proc defined*(x: untyped): bool {.magic: "Defined", noSideEffect, compileTime.}
   ## defined.
   ##
   ## `x` is an external symbol introduced through the compiler's
-  ## `-d:x switch <nimc.html#compile-time-symbols>`_ to enable build time
-  ## conditionals:
+  ## `-d:x switch <nimc.html#compiler-usage-compile-time-symbols>`_ to enable
+  ## build time conditionals:
   ##
   ## .. code-block:: Nim
   ##   when not defined(release):
@@ -784,7 +784,8 @@ type
   AssertionError* = object of Defect ## \
     ## Raised when assertion is proved wrong.
     ##
-    ## Usually the result of using the `assert() template <#assert>`_.
+    ## Usually the result of using the `assert() template
+    ## <assertions.html#assert.t,untyped,string>`_.
   ValueError* = object of CatchableError ## \
     ## Raised for string and object conversion errors.
   KeyError* = object of ValueError ## \
@@ -2017,8 +2018,8 @@ when defined(boehmgc):
 when taintMode:
   type TaintedString* = distinct string ## A distinct string type that
                                         ## is `tainted`:idx:, see `taint mode
-                                        ## <manual.html#taint-mode>`_ for
-                                        ## details. It is an alias for
+                                        ## <manual_experimental.html#taint-mode>`_
+                                        ## for details. It is an alias for
                                         ## ``string`` if the taint mode is not
                                         ## turned on.
 
@@ -2026,8 +2027,8 @@ when taintMode:
 else:
   type TaintedString* = string          ## A distinct string type that
                                         ## is `tainted`:idx:, see `taint mode
-                                        ## <manual.html#taint-mode>`_ for
-                                        ## details. It is an alias for
+                                        ## <manual_experimental.html#taint-mode>`_
+                                        ## for details. It is an alias for
                                         ## ``string`` if the taint mode is not
                                         ## turned on.
 
@@ -2040,11 +2041,11 @@ else:
 
 const
   QuitSuccess* = 0
-    ## is the value that should be passed to `quit <#quit>`_ to indicate
+    ## is the value that should be passed to `quit <#quit,int>`_ to indicate
     ## success.
 
   QuitFailure* = 1
-    ## is the value that should be passed to `quit <#quit>`_ to indicate
+    ## is the value that should be passed to `quit <#quit,int>`_ to indicate
     ## failure.
 
 when defined(nodejs) and not defined(nimscript):
@@ -3460,14 +3461,15 @@ when defined(nimvarargstyped):
     ## Unlike other IO operations this is guaranteed to be thread-safe as
     ## ``echo`` is very often used for debugging convenience. If you want to use
     ## ``echo`` inside a `proc without side effects
-    ## <manual.html#pragmas-noSideEffect-pragma>`_ you can use `debugEcho <#debugEcho>`_
-    ## instead.
+    ## <manual.html#pragmas-nosideeffect-pragma>`_ you can use `debugEcho
+    ## <#debugEcho,varargs[typed,]>`_ instead.
 
   proc debugEcho*(x: varargs[typed, `$`]) {.magic: "Echo", noSideEffect,
                                             tags: [], raises: [].}
-    ## Same as `echo <#echo>`_, but as a special semantic rule, ``debugEcho``
-    ## pretends to be free of side effects, so that it can be used for debugging
-    ## routines marked as `noSideEffect <manual.html#pragmas-noSideEffect-pragma>`_.
+    ## Same as `echo <#echo,varargs[typed,]>`_, but as a special semantic rule,
+    ## ``debugEcho`` pretends to be free of side effects, so that it can be used
+    ## for debugging routines marked as `noSideEffect
+    ## <manual.html#pragmas-nosideeffect-pragma>`_.
 else:
   proc echo*(x: varargs[untyped, `$`]) {.magic: "Echo", tags: [WriteIOEffect],
     benign, sideEffect.}
@@ -4092,7 +4094,8 @@ proc staticExec*(command: string, input = "", cache = ""): string {.
   ## `gorge <#gorge,string,string,string>`_ is an alias for ``staticExec``.
   ##
   ## Note that you can use this proc inside a pragma like
-  ## `passc <nimc.html#passc-pragma>`_ or `passl <nimc.html#passl-pragma>`_.
+  ## `passc <manual.html#implementation-specific-pragmas-passc-pragma>`_ or
+  ## `passl <manual.html#implementation-specific-pragmas-passl-pragma>`_.
   ##
   ## If ``cache`` is not empty, the results of ``staticExec`` are cached within
   ## the ``nimcache`` directory. Use ``--forceBuild`` to get rid of this caching

lib/system/assertions.nim

@@ -45,7 +45,7 @@ template assert*(cond: untyped, msg = "") =
   ##
   ## The compiler may not generate any code at all for ``assert`` if it is
   ## advised to do so through the ``-d:release`` or ``--assertions:off``
-  ## `command line switches <nimc.html#command-line-switches>`_.
+  ## `command line switches <nimc.html#compiler-usage-command-line-switches>`_.
   const expr = astToStr(cond)
   assertImpl(cond, msg, expr, compileOption("assertions"))
 

lib/system/nimscript.nim

@@ -311,9 +311,9 @@ proc cd*(dir: string) {.raises: [OSError].} =
   ## Changes the current directory.
   ##
   ## The change is permanent for the rest of the execution, since this is just
-  ## a shortcut for `os.setCurrentDir()
-  ## <http://nim-lang.org/docs/os.html#setCurrentDir,string>`_ . Use the `withDir()
-  ## <#withDir>`_ template if you want to perform a temporary change only.
+  ## a shortcut for `os.setCurrentDir() <os.html#setCurrentDir,string>`_ . Use
+  ## the `withDir() <#withDir.t,string,untyped>`_ template if you want to
+  ## perform a temporary change only.
   setCurrentDir(dir)
   checkOsError()
 
@@ -326,7 +326,8 @@ proc findExe*(bin: string): string =
 template withDir*(dir: string; body: untyped): untyped =
   ## Changes the current directory temporarily.
   ##
-  ## If you need a permanent change, use the `cd() <#cd>`_ proc. Usage example:
+  ## If you need a permanent change, use the `cd() <#cd,string>`_ proc.
+  ## Usage example:
   ##
   ## .. code-block:: nim
   ##   withDir "foo":