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

4 files changed, 147 insertions, 120 deletions

diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst
index b14a2aa..2bc3287 100644
--- a/Help/command/cmake_policy.rst
+++ b/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
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 3e1f011..f3616fb 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/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
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index 81adea0..9851c12 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -465,168 +465,195 @@ with an explicit target.
 Style
 -----
 
-1)
-  Command signatures should be marked up as plain literal blocks, not as
-  cmake ``code-blocks``.
+Style: Section Headers
+^^^^^^^^^^^^^^^^^^^^^^
 
-2)
-  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
+.. 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.
 
-    ... preceding paragraph.
+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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      add_library(<lib> ...)
+Command signatures should be marked up as plain literal blocks, not as
+cmake ``code-blocks``.
 
-    This signature is used for ...
+Signatures are separated from preceding content by a horizontal
+line. That is, use:
 
-3)
-  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.
+.. code-block:: rst
 
-4)
-  Use two spaces for indentation.  Use two spaces between sentences in
-  prose.
+  ... preceding paragraph.
 
-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
+    add_library(<lib> ...)
 
-  .. code-block:: rst
+  This signature is used for ...
 
-    ``add_executable``
+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.
 
-  not
+Style: Boolean Constants
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-  .. code-block:: rst
+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.
 
-    :command:`add_executable`
+Style: Inline Literals
+^^^^^^^^^^^^^^^^^^^^^^
 
-  which is used elsewhere.
+Mark up references to keywords in signatures, file names, and other
+technical terms with ``inline-literal`` syntax, for example:
 
-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.
+.. code-block:: rst
 
-9)
-  Mark up references to keywords in signatures, file names, and other
-  technical terms with ``inline-literl`` syntax, for example:
+  If ``WIN32`` is used with :command:`add_executable`, the
+  :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
+  creates the file ``<name>.exe`` on Windows.
 
-  .. code-block:: rst
+Style: Cross-References
+^^^^^^^^^^^^^^^^^^^^^^^
 
-    If ``WIN32`` is used with :command:`add_executable`, the
-    :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
-    creates the file ``<name>.exe`` on Windows.
+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:
+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:
 
-  .. code-block:: rst
+.. code-block:: rst
 
-    This command creates an :ref:`Imported Target <Imported Targets>`.
+  This command creates an :ref:`Imported Target <Imported Targets>`.
 
-  instead of:
+instead of:
 
-  .. code-block:: rst
+.. code-block:: rst
 
-    This command creates an :prop_tgt:`IMPORTED` target.
+  This command creates an :prop_tgt:`IMPORTED` target.
 
-  The latter should be used only when referring specifically to the
-  property.
+The latter should be used only when referring specifically to the
+property.
 
-  References to manual sections are not automatically created by creating
-  a section, but code such as:
+References to manual sections are not automatically created by creating
+a section, but code such as:
 
-  .. code-block:: rst
+.. code-block:: rst
 
-    .. _`Imported Targets`:
+  .. _`Imported Targets`:
 
-  creates a suitable anchor.  Use an anchor name which matches the name
-  of the corresponding section.  Refer to the anchor using a
-  cross-reference with specified text.
+creates a suitable anchor.  Use an anchor name which matches the name
+of the corresponding section.  Refer to the anchor using a
+cross-reference with specified text.
 
-  Imported Targets need the ``IMPORTED`` term marked up with care in
-  particular because the term may refer to a command keyword
-  (``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
-  concept (:ref:`Imported Targets`).
+Imported Targets need the ``IMPORTED`` term marked up with care in
+particular because the term may refer to a command keyword
+(``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
-  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.
+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
+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.
 
-12)
-  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:
+Style: Referencing CMake Domain Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  .. 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
+the type of object it is.  For example:
 
-    Title Text
-    ----------
+.. code-block:: rst
 
-  Capitalize the first letter of each non-minor word in the title.
+  Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
 
-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:
+Instead of
 
-  .. code-block:: rst
+.. code-block:: rst
 
-    Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
+  Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
 
-  Instead of
+The ``policy`` directive is an exception, and the type us usually
+referred to before the link:
 
-  .. code-block:: rst
+.. code-block:: rst
 
-    Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
+  If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
 
-  The ``policy`` directive is an exception, and the type us usually
-  referred to before the link:
+However, markup self-references with ``inline-literal`` syntax.
+For example, within the :command:`add_executable` command
+documentation, use
 
-  .. code-block:: rst
+.. code-block:: rst
 
-    If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
+  ``add_executable``
 
-14)
-  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.
+not
+
+.. code-block:: rst
 
-15)
-  Use American English spellings in prose.
+  :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``.
diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst
index cad4951..fe8d62d 100644
--- a/Help/manual/cmake-qt.7.rst
+++ b/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