Merge topic 'doc-section-header-convention'

793b64e4 Help: Document section header underline hierarchy in cmake-developer.7
05bd31ab Help: Organize documentation style sections in cmake-developer.7
eaafe756 Help: Add documentation style section headers to cmake-developer.7
4207b3a3 Help: Use "^^^^" for subsubsection headers

Help/command/cmake_policy.rst

@@ -18,7 +18,7 @@ setting is available the ``OLD`` behavior is assumed and a warning is
 produced requesting that the policy be set.
 
 Setting Policies by CMake Version
-'''''''''''''''''''''''''''''''''
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW``
 behavior.  While setting policies individually is supported, we
@@ -40,7 +40,7 @@ Note that the :command:`cmake_minimum_required(VERSION)`
 command implicitly calls ``cmake_policy(VERSION)`` too.
 
 Setting Policies Explicitly
-'''''''''''''''''''''''''''
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -54,7 +54,7 @@ one may fix the project to work with the new behavior and set the
 policy state to ``NEW``.
 
 Checking Policy Settings
-''''''''''''''''''''''''
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -65,7 +65,7 @@ The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the
 policy is set, and empty otherwise.
 
 CMake Policy Stack
-''''''''''''''''''
+^^^^^^^^^^^^^^^^^^
 
 CMake keeps policy settings on a stack, so changes made by the
 cmake_policy command affect only the top of the stack.  A new entry on

Help/manual/cmake-buildsystem.7.rst

@@ -551,7 +551,7 @@ exporting see the :manual:`cmake-packages(7)` manual.
 .. _`Include Directories and Usage Requirements`:
 
 Include Directories and Usage Requirements
-''''''''''''''''''''''''''''''''''''''''''
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Include directories require some special consideration when specified as usage
 requirements and when used with generator expressions.  The

Help/manual/cmake-developer.7.rst

@@ -465,11 +465,62 @@ with an explicit target.
 Style
 -----
 
-1)
+Style: Section Headers
+^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+The section header underline character hierarchy is
+
+* ``#``: Manual group (part) in the master document
+* ``*``: Manual (chapter) title
+* ``=``: Section within a manual
+* ``-``: Subsection or `CMake Domain`_ object document title
+* ``^``: Subsubsection or `CMake Domain`_ object document section
+* ``"``: Paragraph or `CMake Domain`_ object document subsection
+
+Style: Whitespace
+^^^^^^^^^^^^^^^^^
+
+Use two spaces for indentation.  Use two spaces between sentences in
+prose.
+
+Style: Line Length
+^^^^^^^^^^^^^^^^^^
+
+Prefer to restrict the width of lines to 75-80 columns.  This is not a
+hard restriction, but writing new paragraphs wrapped at 75 columns
+allows space for adding minor content without significant re-wrapping of
+content.
+
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Command signatures should be marked up as plain literal blocks, not as
 cmake ``code-blocks``.
 
-2)
 Signatures are separated from preceding content by a horizontal
 line. That is, use:
 
@@ -485,54 +536,26 @@ Style
 
   This signature is used for ...
 
-3)
+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.
+
+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.
 
-4)
+Style: Inline Literals
-  Use two spaces for indentation.  Use two spaces between sentences in
+^^^^^^^^^^^^^^^^^^^^^^
-  prose.
 
-5)
-  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.
-
-6)
-  Prefer to restrict the width of lines to 75-80 columns.  This is not a
-  hard restriction, but writing new paragraphs wrapped at 75 columns
-  allows space for adding minor content without significant re-wrapping of
-  content.
-
-7)
-  Mark up self-references with  ``inline-literal`` syntax. For example,
-  within the add_executable command documentation, use
-
-  .. code-block:: rst
-
-    ``add_executable``
-
-  not
-
-  .. code-block:: rst
-
-    :command:`add_executable`
-
-  which is used elsewhere.
-
-8)
-  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.
-
-9)
 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
 
@@ -540,8 +563,18 @@ Style
   :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
   creates the file ``<name>.exe`` on Windows.
 
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-10)
 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
 manual section instead of the property. For example:
@@ -575,7 +608,6 @@ Style
 (``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
 concept (:ref:`Imported Targets`).
 
-11)
 Where a property, command or variable is related conceptually to others,
 by for example, being related to the buildsystem description, generator
 expressions or Qt, each relevant property, command or variable should
@@ -583,22 +615,12 @@ Style
 particular information relating to the command should be in the
 documentation of the command.
 
-12)
+Style: Referencing CMake Domain Objects
-  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
+When referring to `CMake Domain`_ objects such as properties, variables,
-
+commands etc, prefer to link to the target object and follow that with
-    Title Text
+the type of object it is.  For example:
-    ----------
-
-  Capitalize the first letter of each non-minor word in the title.
-
-13)
-  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:
 
 .. code-block:: rst
 
@@ -617,16 +639,21 @@ Style
 
   If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
 
-14)
+However, markup self-references with ``inline-literal`` syntax.
-  Signatures of commands should wrap optional parts with square brackets,
+For example, within the :command:`add_executable` command
-  and should mark list of optional arguments with an ellipsis (``...``).
+documentation, use
-  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.
 
-15)
+.. code-block:: rst
-  Use American English spellings in prose.
 
+  ``add_executable``
+
+not
+
+.. code-block:: rst
+
+  :command:`add_executable`
+
+which is used elsewhere.
 
 Modules
 =======
@@ -808,7 +835,7 @@ Documentation`_ section above.
 
 
 Standard Variable Names
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 For a ``FindXxx.cmake`` module that takes the approach of setting
 variables (either instead of or in addition to creating imported
@@ -914,7 +941,7 @@ them.
 
 
 A Sample Find Module
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 We will describe how to create a simple find module for a library
 ``Foo``.

Help/manual/cmake-qt.7.rst

@@ -54,7 +54,7 @@ CMake.  Target dependencies may be added to that custom target by adding them
 to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
 
 AUTOMOC
-'''''''
+^^^^^^^
 
 The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)`
 inspects the C++ files in the target to determine if they require ``moc`` to
@@ -84,7 +84,7 @@ variable may be populated to pre-set the options for all following targets.
 .. _`Qt AUTOUIC`:
 
 AUTOUIC
-'''''''
+^^^^^^^
 
 The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)`
 inspects the C++ files in the target to determine if they require ``uic`` to
@@ -147,7 +147,7 @@ result of linking with the :prop_tgt:`IMPORTED` target:
 .. _`Qt AUTORCC`:
 
 AUTORCC
-'''''''
+^^^^^^^
 
 The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)`
 creates rules to execute ``rcc`` at the appropriate time on source files