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,15 +465,66 @@ with an explicit target.
 Style
 -----
 
-1)
+Style: Section Headers
-  Command signatures should be marked up as plain literal blocks, not as
+^^^^^^^^^^^^^^^^^^^^^^
-  cmake ``code-blocks``.
 
-2)
+When marking section titles, make the section decoration line as long as
-  Signatures are separated from preceding content by a horizontal
+the title text.  Use only a line below the title, not above. For
-  line. That is, use:
+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.
+
+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``.
+
+Signatures are separated from preceding content by a horizontal
+line. That is, use:
+
+.. code-block:: rst
 
   ... preceding paragraph.
 
@@ -485,148 +536,124 @@ Style
 
   This signature is used for ...
 
-3)
+Signatures of commands should wrap optional parts with square brackets,
-  Use "``OFF``" and "``ON``" for boolean values which can be modified by
+and should mark list of optional arguments with an ellipsis (``...``).
-  the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
+Elements of the signature which are specified by the user should be
-  may be "enabled" and "disabled". Use "``True``" and "``False``" for
+specified with angle brackets, and may be referred to in prose using
-  inherent values which can't be modified after being set, such as the
+``inline-literal`` syntax.
-  :prop_tgt:`IMPORTED` property of a build target.
 
-4)
+Style: Boolean Constants
-  Use two spaces for indentation.  Use two spaces between sentences in
+^^^^^^^^^^^^^^^^^^^^^^^^
-  prose.
 
-5)
+Use "``OFF``" and "``ON``" for boolean values which can be modified by
-  Prefer to mark the start of literal blocks with ``::`` at the end of
+the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
-  the preceding paragraph. In cases where the following block gets
+may be "enabled" and "disabled". Use "``True``" and "``False``" for
-  a ``code-block`` marker, put a single ``:`` at the end of the preceding
+inherent values which can't be modified after being set, such as the
-  paragraph.
+:prop_tgt:`IMPORTED` property of a build target.
 
-6)
+Style: Inline Literals
-  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 references to keywords in signatures, file names, and other
-  Mark up self-references with  ``inline-literal`` syntax. For example,
+technical terms with ``inline-literal`` syntax, for example:
-  within the add_executable command documentation, use
 
-  .. code-block:: rst
+.. 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:
-
-  .. code-block:: rst
 
   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.
 
+Style: Cross-References
+^^^^^^^^^^^^^^^^^^^^^^^
 
-10)
+Mark up linkable references as links, including repeats.
-  If referring to a concept which corresponds to a property, and that
+An alternative, which is used by wikipedia
-  concept is described in a high-level manual, prefer to link to the
+(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
-  manual section instead of the property. For example:
+is to link to a reference only once per article. That style is not used
+in CMake documentation.
 
-  .. code-block:: rst
+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
+manual section instead of the property. For example:
+
+.. code-block:: rst
 
   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.
 
-  The latter should be used only when referring specifically to the
+The latter should be used only when referring specifically to the
-  property.
+property.
 
-  References to manual sections are not automatically created by creating
+References to manual sections are not automatically created by creating
-  a section, but code such as:
+a section, but code such as:
 
-  .. code-block:: rst
+.. code-block:: rst
 
   .. _`Imported Targets`:
 
-  creates a suitable anchor.  Use an anchor name which matches the name
+creates a suitable anchor.  Use an anchor name which matches the name
-  of the corresponding section.  Refer to the anchor using a
+of the corresponding section.  Refer to the anchor using a
-  cross-reference with specified text.
+cross-reference with specified text.
 
-  Imported Targets need the ``IMPORTED`` term marked up with care in
+Imported Targets need the ``IMPORTED`` term marked up with care in
-  particular because the term may refer to a command keyword
+particular because the term may refer to a command keyword
-  (``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
+(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
-  concept (:ref:`Imported Targets`).
+concept (:ref:`Imported Targets`).
 
-11)
+Where a property, command or variable is related conceptually to others,
-  Where a property, command or variable is related conceptually to others,
+by for example, being related to the buildsystem description, generator
-  by for example, being related to the buildsystem description, generator
+expressions or Qt, each relevant property, command or variable should
-  expressions or Qt, each relevant property, command or variable should
+link to the primary manual, which provides high-level information.  Only
-  link to the primary manual, which provides high-level information.  Only
+particular information relating to the command should be in the
-  particular information relating to the command should be in the
+documentation of the command.
-  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
+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.
-
-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
 
   Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
 
-  Instead of
+Instead of
 
-  .. code-block:: rst
+.. code-block:: rst
 
   Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
 
-  The ``policy`` directive is an exception, and the type us usually
+The ``policy`` directive is an exception, and the type us usually
-  referred to before the link:
+referred to before the link:
 
-  .. code-block:: rst
+.. code-block:: rst
 
   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