RST conventions RST fixes

doc/rst-conventions.rst

@@ -14,16 +14,21 @@ Section markers
 
 Book level:
 
-  #. Over- and underlined hash marks (``#``) for book title
-  #. Over- and underlines stars (``*``) for book sub-title
+#. Over- and underlined hash marks (``#``) for book title
+
+#. Over- and underlines stars (``*``) for book sub-title
 
 File level:
 
-  #. Over- and underlined equals signs (``=``) once at top of file (file topic)
-  #. Underlined equals signs (``=``)
-  #. Underlined minus signs (``-``)
-  #. Underlined colons (``:``)
-  #. Underlined periods (``.``)
+#. Over- and underlined equals signs (``=``) once at top of file (file topic)
+
+#. Underlined equals signs (``=``)
+
+#. Underlined minus signs (``-``)
+
+#. Underlined colons (``:``)
+
+#. Underlined periods (``.``)
 
 The book level notation is reserved for future use.  It allows the
 internal documentation to be easily built into a single HTML/PDF
@@ -40,3 +45,93 @@ You can use::
   
      \newpage
 
+Lists
+=====
+
+Numbering
+---------
+
+List numbering styles can be mixed, e.g.::
+
+  1. Foo
+
+    a. Bar
+
+       1. Quux
+
+However, e.g. GitHub will renumber the bullets and may also change the
+numbering style.  This will make references to list elements confusing;
+e.g. if you refer to Quux as element 1.a.1 above, the reference is quite
+confusing if Quux was renumbered to 1.1.1 or 1.a.iii.  Even so, such
+references are sometimes necessary so they can be used.
+Start at zero indent
+
+--------------------
+
+Start lists at zero indent, e.g.::
+
+  * Foo
+
+  * Bar
+
+If you don't, GitHub will render the list as a quoted block.
+
+Empty lines
+-----------
+
+Use empty lines between elements and sub-elements for readability and to
+minimize formatting issues::
+
+  1. Foo
+
+    a. sub-foo
+
+       + sub-sub-foo
+
+    b. sub-bar
+
+  2. Bar
+
+  3. Quux
+
+Nested lists and GitHub
+-----------------------
+
+While ``rst2pdf`` and friends are somewhat lenient with respect to nested
+lists, GitHub RST formatter is a bit more picky.  To work with the GitHub
+formatter, make sure that a nested list's bullet mark is intended to the
+level of the previous level's body, e.g.::
+
+  1. Foo
+
+     a. sub-foo
+
+     b. sub-bar
+
+  2. Bar
+
+The following is **incorrect** and GitHub will render the nested list as
+a quoted block::
+
+  1. Foo
+
+    a. sub-foo
+
+    b. sub-bar
+
+  2. Bar
+
+Note that the required level depends on the length of the parent bullet.
+This matters for numbered lists::
+
+  9. Foo
+
+     a. sub-foo
+
+     b. sub-bar
+
+  10. Bar
+
+      a. sub-foo (with one more indent than above)
+
+      b. sub-bar