Move markup concerns from style to markup (#1292)

Author: nedbat

Diff for: documentation/markup.rst

@@ -52,6 +52,22 @@ language, this will not take too long.
     Documentation <https://docutils.sourceforge.io/rst.html>`_.
 
 
+Use of whitespace
+-----------------
+
+All reST files use an indentation of 3 spaces; no tabs are allowed.  The
+maximum line length is 80 characters for normal text, but tables, deeply
+indented code samples and long links may extend beyond that.  Code example
+bodies should use normal Python 4-space indentation.
+
+Make use of multiple blank lines where applicable to clarify the structure of
+the reST file.  Extra blank lines help group sections together to make the
+organization of the file clearer.
+
+A sentence-ending period may be followed by one or two spaces. While reST
+ignores the second space, it is customarily put in by some users, for example
+to aid Emacs' auto-fill mode.
+
 Paragraphs
 ----------
 
@@ -289,6 +305,28 @@ There are some problems one commonly runs into while authoring reST documents:
   separated from the surrounding text by non-word characters, you have to use
   an escaped space to get around that.
 
+
+Typographic conventions
+=======================
+
+Big *O* notation
+----------------
+
+Big *O* notation is used to describe the performance of algorithms.
+
+Use italics for the big *O* and variables. For example:
+
+======================== ====================
+reStructuredText         Rendered
+======================== ====================
+``*O*\ (1)``             *O*\ (1)
+``*O*\ (log *n*)``       *O*\ (log *n*)
+``*O*\ (*n*)``           *O*\ (*n*)
+``*O*\ (*n* log *n*)``   *O*\ (*n* log *n*)
+``*O*\ (*n*\ :sup:`2`)`` *O*\ (*n*\ :sup:`2`)
+======================== ====================
+
+
 .. _additional-markup-constructs:
 
 Additional markup constructs

Diff for: documentation/style-guide.rst

@@ -4,26 +4,12 @@
 Style guide
 ===========
 
-.. highlight::  rest
+.. highlight:: rest
 
-This document describes the style guide for our documentation.
+This page describes the linguistic style guide for our documentation.
+For markup details in reST files, see :ref:`markup`.
 
 
-Use of whitespace
-=================
-
-All reST files use an indentation of 3 spaces; no tabs are allowed.  The
-maximum line length is 80 characters for normal text, but tables, deeply
-indented code samples and long links may extend beyond that.  Code example
-bodies should use normal Python 4-space indentation.
-
-Make generous use of blank lines where applicable; they help group things
-together.
-
-A sentence-ending period may be followed by one or two spaces; while reST
-ignores the second space, it is customarily put in by some users, for example
-to aid Emacs' auto-fill mode.
-
 Footnotes
 =========
 
@@ -264,20 +250,3 @@ errors ("I made a mistake, therefore the docs must be wrong ...").  Typically,
 the documentation wasn't consulted until after the error was made.  It is
 unfortunate, but typically no documentation edit would have saved the user from
 making false assumptions about the language ("I was surprised by ...").
-
-Big *O* notation
-================
-
-Big *O* notation is used to describe the performance of algorithms.
-
-Use italics for the big *O* and variables. For example:
-
-======================== ====================
-reStructuredText         Rendered
-======================== ====================
-``*O*\ (1)``             *O*\ (1)
-``*O*\ (log *n*)``       *O*\ (log *n*)
-``*O*\ (*n*)``           *O*\ (*n*)
-``*O*\ (*n* log *n*)``   *O*\ (*n* log *n*)
-``*O*\ (*n*\ :sup:`2`)`` *O*\ (*n*\ :sup:`2`)
-======================== ====================