Help: Organize documentation style sections in cmake-developer.7

Now that the style guidelines have section titles instead of numbers,
organize them into more well-defined sections.

1 files changed, 73 insertions, 77 deletions

diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 53a4f56..9476d64 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -465,35 +465,19 @@ with an explicit target.
 Style
 -----
 
-Style: Command Signatures
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Command signatures should be marked up as plain literal blocks, not as
-cmake ``code-blocks``.
+Style: Section Headers
+^^^^^^^^^^^^^^^^^^^^^^
 
-Signatures are separated from preceding content by a horizontal
-line. That is, use:
+When marking section titles, make the section decoration line as long as
+the title text.  Use only a line below the title, not above. For
+example:
 
 .. code-block:: rst
 
-  ... preceding paragraph.
-
-  ---------------------------------------------------------------------
-
-  ::
-
-    add_library(<lib> ...)
-
-  This signature is used for ...
-
-Style: Boolean Constants
-^^^^^^^^^^^^^^^^^^^^^^^^
+  Title Text
+  ----------
 
-Use "``OFF``" and "``ON``" for boolean values which can be modified by
-the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
-may be "enabled" and "disabled". Use "``True``" and "``False``" for
-inherent values which can't be modified after being set, such as the
-:prop_tgt:`IMPORTED` property of a build target.
+Capitalize the first letter of each non-minor word in the title.
 
 Style: Whitespace
 ^^^^^^^^^^^^^^^^^
@@ -501,14 +485,6 @@ Style: Whitespace
 Use two spaces for indentation.  Use two spaces between sentences in
 prose.
 
-Style: Starting Literal Blocks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Prefer to mark the start of literal blocks with ``::`` at the end of
-the preceding paragraph. In cases where the following block gets
-a ``code-block`` marker, put a single ``:`` at the end of the preceding
-paragraph.
-
 Style: Line Length
 ^^^^^^^^^^^^^^^^^^
 
@@ -517,37 +493,60 @@ hard restriction, but writing new paragraphs wrapped at 75 columns
 allows space for adding minor content without significant re-wrapping of
 content.
 
-Style: Document Self-References
+Style: Prose
+^^^^^^^^^^^^
+
+Use American English spellings in prose.
+
+Style: Starting Literal Blocks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Prefer to mark the start of literal blocks with ``::`` at the end of
+the preceding paragraph. In cases where the following block gets
+a ``code-block`` marker, put a single ``:`` at the end of the preceding
+paragraph.
+
+Style: CMake Command Signatures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Mark up self-references with  ``inline-literal`` syntax. For example,
-within the add_executable command documentation, use
+Command signatures should be marked up as plain literal blocks, not as
+cmake ``code-blocks``.
+
+Signatures are separated from preceding content by a horizontal
+line. That is, use:
 
 .. code-block:: rst
 
-  ``add_executable``
+  ... preceding paragraph.
 
-not
+  ---------------------------------------------------------------------
 
-.. code-block:: rst
+  ::
 
-  :command:`add_executable`
+    add_library(<lib> ...)
 
-which is used elsewhere.
+  This signature is used for ...
 
-Style: Linkable References
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Signatures of commands should wrap optional parts with square brackets,
+and should mark list of optional arguments with an ellipsis (``...``).
+Elements of the signature which are specified by the user should be
+specified with angle brackets, and may be referred to in prose using
+``inline-literal`` syntax.
 
-Mark up all other linkable references as links, including repeats. An
-alternative, which is used by wikipedia (`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
-is to link to a reference only once per article. That style is not used
-in CMake documentation.
+Style: Boolean Constants
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use "``OFF``" and "``ON``" for boolean values which can be modified by
+the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
+may be "enabled" and "disabled". Use "``True``" and "``False``" for
+inherent values which can't be modified after being set, such as the
+:prop_tgt:`IMPORTED` property of a build target.
 
-Style: Technical Terms
+Style: Inline Literals
 ^^^^^^^^^^^^^^^^^^^^^^
 
 Mark up references to keywords in signatures, file names, and other
-technical terms with ``inline-literl`` syntax, for example:
+technical terms with ``inline-literal`` syntax, for example:
 
 .. code-block:: rst
 
@@ -555,8 +554,17 @@ technical terms with ``inline-literl`` syntax, for example:
   :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
   creates the file ``<name>.exe`` on Windows.
 
-Style: Referencing Concepts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Style: Cross-References
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Mark up linkable references as links, including repeats.
+An alternative, which is used by wikipedia
+(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
+is to link to a reference only once per article. That style is not used
+in CMake documentation.
+
+Style: Referencing CMake Concepts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If referring to a concept which corresponds to a property, and that
 concept is described in a high-level manual, prefer to link to the
@@ -598,26 +606,12 @@ link to the primary manual, which provides high-level information.  Only
 particular information relating to the command should be in the
 documentation of the command.
 
-Style: Section Titles
-^^^^^^^^^^^^^^^^^^^^^
-
-When marking section titles, make the section decoration line as long as
-the title text.  Use only a line below the title, not above. For
-example:
-
-.. code-block:: rst
-
-  Title Text
-  ----------
-
-Capitalize the first letter of each non-minor word in the title.
-
 Style: Referencing CMake Domain Objects
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When referring to properties, variables, commands etc, prefer to link
-to the target object and follow that with the type of object it is.
-For example:
+When referring to `CMake Domain`_ objects such as properties, variables,
+commands etc, prefer to link to the target object and follow that with
+the type of object it is.  For example:
 
 .. code-block:: rst
 
@@ -636,19 +630,21 @@ referred to before the link:
 
   If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
 
-Style: Command Signature Markup
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+However, markup self-references with ``inline-literal`` syntax.
+For example, within the :command:`add_executable` command
+documentation, use
 
-Signatures of commands should wrap optional parts with square brackets,
-and should mark list of optional arguments with an ellipsis (``...``).
-Elements of the signature which are specified by the user should be
-specified with angle brackets, and may be referred to in prose using
-``inline-literal`` syntax.
+.. code-block:: rst
 
-Style: Prose
-^^^^^^^^^^^^
+  ``add_executable``
 
-Use American English spellings in prose.
+not
+
+.. code-block:: rst
+
+  :command:`add_executable`
+
+which is used elsewhere.
 
 Modules
 =======