RST: improve simple tables (#19859)

* RST: improve simple tables

* nim 1.0 gotchas

* Still allow legacy boundaries like `----`

7 files changed, 34 insertions, 28 deletions

diff --git a/doc/apis.rst b/doc/apis.rst
index e8313749d..f0b8c93e5 100644
--- a/doc/apis.rst
+++ b/doc/apis.rst
@@ -18,9 +18,9 @@ been renamed to fit this scheme. The ultimate goal is that the programmer can
 *guess* a name.
 
 
--------------------     ------------   --------------------------------------
+===================     ============   ======================================
 English word            To use         Notes
--------------------     ------------   --------------------------------------
+===================     ============   ======================================
 initialize              initT          `init` is used to create a
                                        value type `T`
 new                     newP           `new` is used to create a
@@ -82,4 +82,4 @@ literal                 lit
 string                  str
 identifier              ident
 indentation             indent
--------------------     ------------   --------------------------------------
+===================     ============   ======================================
diff --git a/doc/astspec.txt b/doc/astspec.txt
index 6d3fa1f8c..dbbe2799d 100644
--- a/doc/astspec.txt
+++ b/doc/astspec.txt
@@ -50,9 +50,9 @@ A leaf of the AST often corresponds to a terminal symbol in the concrete
 syntax. Note that the default ``float`` in Nim maps to ``float64`` such that
 the default AST for a float is ``nnkFloat64Lit`` as below.
 
------------------                ---------------------------------------------
+=================                =============================================
 Nim expression                   Corresponding AST
------------------                ---------------------------------------------
+=================                =============================================
 ``42``                           ``nnkIntLit(intVal = 42)``
 ``42'i8``                        ``nnkInt8Lit(intVal = 42)``
 ``42'i16``                       ``nnkInt16Lit(intVal = 42)``
@@ -72,7 +72,7 @@ Nim expression                   Corresponding AST
 ``nil``                          ``nnkNilLit()``
 ``myIdentifier``                 ``nnkIdent(strVal = "myIdentifier")``
 ``myIdentifier``                 after lookup pass: ``nnkSym(strVal = "myIdentifier", ...)``
------------------                ---------------------------------------------
+=================                =============================================
 
 Identifiers are ``nnkIdent`` nodes. After the name lookup pass these nodes
 get transferred into ``nnkSym`` nodes.
@@ -1211,9 +1211,9 @@ AST:
 In general, declaring types mirrors this syntax (i.e., ``nnkStaticTy`` for
 ``static``, etc.). Examples follow (exceptions marked by ``*``):
 
--------------                ---------------------------------------------
+=============                =============================================
 Nim type                     Corresponding AST
--------------                ---------------------------------------------
+=============                =============================================
 ``static``                   ``nnkStaticTy``
 ``tuple``                    ``nnkTupleTy``
 ``var``                      ``nnkVarTy``
@@ -1226,7 +1226,7 @@ Nim type                     Corresponding AST
 ``proc``                     ``nnkProcTy``
 ``iterator``                 ``nnkIteratorTy``
 ``object``                   ``nnkObjectTy``
--------------                ---------------------------------------------
+=============                =============================================
 
 Take special care when declaring types as ``proc``. The behavior is similar
 to ``Procedure declaration``, below, but does not treat ``nnkGenericParams``.
diff --git a/doc/manual.rst b/doc/manual.rst
index 5ab257fec..82c9f5758 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -363,7 +363,7 @@ contain the following `escape sequences`:idx:\ :
   ``\\``                   `backslash`:idx:
   ``\"``                   `quotation mark`:idx:
   ``\'``                   `apostrophe`:idx:
-  ``\`` '0'..'9'+         `character with decimal value d`:idx:;
+  ``\`` '0'..'9'+          `character with decimal value d`:idx:;
                            all decimal digits directly
                            following are used for the character
   ``\a``                   `alert`:idx:
diff --git a/doc/nep1.rst b/doc/nep1.rst
index 8eb31332f..9627071bf 100644
--- a/doc/nep1.rst
+++ b/doc/nep1.rst
@@ -153,9 +153,9 @@ The library uses a simple naming scheme that makes use of common abbreviations
 to keep the names short but meaningful.
 
 
--------------------     ------------   --------------------------------------
+===================     ============   ======================================
 English word            To use         Notes
--------------------     ------------   --------------------------------------
+===================     ============   ======================================
 initialize              initFoo        initializes a value type `Foo`
 new                     newFoo         initializes a reference type `Foo`
                                        via `new` or a value type `Foo`
@@ -220,7 +220,7 @@ literal                 lit
 string                  str
 identifier              ident
 indentation             indent
--------------------     ------------   --------------------------------------
+===================     ============   ======================================
 
 
 Coding Conventions
diff --git a/doc/nimdoc.cls b/doc/nimdoc.cls
index 271dc5dc9..37039f130 100644
--- a/doc/nimdoc.cls
+++ b/doc/nimdoc.cls
@@ -63,7 +63,7 @@
 
 \usepackage{scrextend}  % for the `addmargin` environment
 
-\usepackage{xcolor}
+\usepackage[table]{xcolor}
 \usepackage[urlbordercolor=blue,linkbordercolor=cyan,
             pdfborderstyle={/S/U/W 1}]{hyperref}
 \usepackage{enumitem}  % for option list, enumList, and rstfootnote
@@ -84,6 +84,11 @@
 
 \definecolor{rstframecolor}{rgb}{0.85, 0.8, 0.6}
 
+\usepackage{booktabs}
+\belowrulesep=0ex
+\aboverulesep=0ex
+\renewcommand{\arraystretch}{1.1}
+
 \newtcolorbox{rstprebox}[1][]{blanker, breakable,
      left=3mm, right=3mm, top=1mm, bottom=1mm,
      borderline ={0.1em}{0pt}{rstframecolor},
@@ -127,6 +132,7 @@
 \newenvironment{rstoptlist}{%
 \begin{description}[font=\sffamily\bfseries,style=nextline,leftmargin=\rstoptleftmargin,labelwidth=\rstoptlabelwidth]}{\end{description}}
 
+\usepackage{multirow}
 \usepackage{tabulary}  % tables with adjustable cell width and no overflow
 % make tabulary prevent overflows (https://tex.stackexchange.com/a/195088)
 \tymin=60pt
diff --git a/doc/niminst.rst b/doc/niminst.rst
index 8fff1f0e8..2da8664a9 100644
--- a/doc/niminst.rst
+++ b/doc/niminst.rst
@@ -49,20 +49,20 @@ contain the following key-value pairs:
 ====================   =======================================================
 Key                    description
 ====================   =======================================================
-`Name`               the project's name; this needs to be a single word
-`DisplayName`        the project's long name; this can contain spaces. If
+`Name`                 the project's name; this needs to be a single word
+`DisplayName`          the project's long name; this can contain spaces. If
                        not specified, this is the same as `Name`.
-`Version`            the project's version
-`OS`                 the OSes to generate C code for; for example:
+`Version`              the project's version
+`OS`                   the OSes to generate C code for; for example:
                        `"windows;linux;macosx"`
-`CPU`                the CPUs to generate C code for; for example:
+`CPU`                  the CPUs to generate C code for; for example:
                        `"i386;amd64;powerpc"`
-`Authors`            the project's authors
-`Description`        the project's description
-`App`                the application's type: "Console" or "GUI". If
+`Authors`              the project's authors
+`Description`          the project's description
+`App`                  the application's type: "Console" or "GUI". If
                        "Console", niminst generates a special batch file
                        for Windows to open up the command-line shell.
-`License`            the filename of the application's license
+`License`              the filename of the application's license
 ====================   =======================================================
 
 
@@ -149,9 +149,9 @@ Possible options are:
 ====================   =======================================================
 Key                    description
 ====================   =======================================================
-`InstallScript`      boolean flag whether an installation shell script
+`InstallScript`        boolean flag whether an installation shell script
                        should be generated. Example: `InstallScript: "Yes"`
-`UninstallScript`    boolean flag whether a de-installation shell script
+`UninstallScript`      boolean flag whether a de-installation shell script
                        should be generated.
                        Example: `UninstallScript: "Yes"`
 ====================   =======================================================
diff --git a/doc/tut1.rst b/doc/tut1.rst
index 405df57b1..66a4c3274 100644
--- a/doc/tut1.rst
+++ b/doc/tut1.rst
@@ -1185,9 +1185,9 @@ subranges) are called ordinal types. Ordinal types have quite
 a few special operations:
 
 
------------------     --------------------------------------------------------
+=================     ========================================================
 Operation             Comment
------------------     --------------------------------------------------------
+=================     ========================================================
 `ord(x)`              returns the integer value that is used to
                       represent `x`'s value
 `inc(x)`              increments `x` by one
@@ -1198,7 +1198,7 @@ Operation             Comment
 `succ(x, n)`          returns the `n`'th successor of `x`
 `pred(x)`             returns the predecessor of `x`
 `pred(x, n)`          returns the `n`'th predecessor of `x`
------------------     --------------------------------------------------------
+=================     ========================================================
 
 
 The `inc <system.html#inc,T,int>`_, `dec <system.html#dec,T,int>`_, `succ