kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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
This commit is contained in:
Brad King 2014-06-02 14:10:00 -04:00 committed by CMake Topic Stage
parent 7b888a5624 793b64e499
commit 02d540c758
4 changed files with 147 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Help/command/cmake_policy.rst
View File

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

2
Help/manual/cmake-buildsystem.7.rst
View File

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

251
Help/manual/cmake-developer.7.rst
View File

@ -465,168 +465,195 @@ with an explicit target.
Style 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
... preceding paragraph. Title Text
----------
--------------------------------------------------------------------- Capitalize the first letter of each non-minor word in the title.
:: The section header underline character hierarchy is
add_library(<lib> ...) * ``#``: 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
This signature is used for ... Style: Whitespace
^^^^^^^^^^^^^^^^^
3) Use two spaces for indentation. Use two spaces between sentences in
Use "``OFF``" and "``ON``" for boolean values which can be modified by prose.
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: Line Length
Use two spaces for indentation. Use two spaces between sentences in ^^^^^^^^^^^^^^^^^^
prose.
5) Prefer to restrict the width of lines to 75-80 columns. This is not a
Prefer to mark the start of literal blocks with ``::`` at the end of hard restriction, but writing new paragraphs wrapped at 75 columns
the preceding paragraph. In cases where the following block gets allows space for adding minor content without significant re-wrapping of
a ``code-block`` marker, put a single ``:`` at the end of the preceding content.
paragraph.
6) Style: Prose
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) Use American English spellings in prose.
Mark up self-references with ``inline-literal`` syntax. For example,
within the add_executable command documentation, use
.. code-block:: rst Style: Starting Literal Blocks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``add_executable`` 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.
not Style: CMake Command Signatures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: rst Command signatures should be marked up as plain literal blocks, not as
cmake ``code-blocks``.
:command:`add_executable` Signatures are separated from preceding content by a horizontal
line. That is, use:
which is used elsewhere. .. code-block:: rst
8) ... preceding paragraph.
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 add_library(<lib> ...)
:prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
creates the file ``<name>.exe`` on Windows.
This signature is used for ...
10) Signatures of commands should wrap optional parts with square brackets,
If referring to a concept which corresponds to a property, and that and should mark list of optional arguments with an ellipsis (``...``).
concept is described in a high-level manual, prefer to link to the Elements of the signature which are specified by the user should be
manual section instead of the property. For example: specified with angle brackets, and may be referred to in prose using
``inline-literal`` syntax.
.. code-block:: rst Style: Boolean Constants
^^^^^^^^^^^^^^^^^^^^^^^^
This command creates an :ref:`Imported Target <Imported Targets>`. 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.
instead of: Style: Inline Literals
^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: rst Mark up references to keywords in signatures, file names, and other
technical terms with ``inline-literal`` syntax, for example:
This command creates an :prop_tgt:`IMPORTED` target. .. code-block:: rst
The latter should be used only when referring specifically to the If ``WIN32`` is used with :command:`add_executable`, the
property. :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
creates the file ``<name>.exe`` on Windows.
References to manual sections are not automatically created by creating Style: Cross-References
a section, but code such as: ^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: rst 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.
.. _`Imported Targets`: Style: Referencing CMake Concepts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
creates a suitable anchor. Use an anchor name which matches the name If referring to a concept which corresponds to a property, and that
of the corresponding section. Refer to the anchor using a concept is described in a high-level manual, prefer to link to the
cross-reference with specified text. manual section instead of the property. For example:
Imported Targets need the ``IMPORTED`` term marked up with care in .. code-block:: rst
particular because the term may refer to a command keyword
(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
concept (:ref:`Imported Targets`).
11) This command creates an :ref:`Imported Target <Imported Targets>`.
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) instead of:
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 This command creates an :prop_tgt:`IMPORTED` target.
----------
Capitalize the first letter of each non-minor word in the title. The latter should be used only when referring specifically to the
property.
13) References to manual sections are not automatically created by creating
When referring to properties, variables, commands etc, prefer to link a section, but code such as:
to the target object and follow that with the type of object it is.
For example:
.. code-block:: rst .. code-block:: rst
Set the :prop_tgt:`AUTOMOC` target property to ``ON``. .. _`Imported Targets`:
Instead of 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.
.. code-block:: rst 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`).
Set the target property :prop_tgt:`AUTOMOC` to ``ON``. 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.
The ``policy`` directive is an exception, and the type us usually Style: Referencing CMake Domain Objects
referred to before the link: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. 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:
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... .. code-block:: rst
14) Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
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.
15) Instead of
Use American English spellings in prose.
.. code-block:: rst
Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
The ``policy`` directive is an exception, and the type us usually
referred to before the link:
.. code-block:: rst
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
However, markup self-references with ``inline-literal`` syntax.
For example, within the :command:`add_executable` command
documentation, use
.. code-block:: rst
``add_executable``
not
.. code-block:: rst
:command:`add_executable`
which is used elsewhere.
Modules Modules
======= =======
@ -808,7 +835,7 @@ Documentation`_ section above.
Standard Variable Names Standard Variable Names
~~~~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^
For a ``FindXxx.cmake`` module that takes the approach of setting For a ``FindXxx.cmake`` module that takes the approach of setting
variables (either instead of or in addition to creating imported variables (either instead of or in addition to creating imported
@ -914,7 +941,7 @@ them.
A Sample Find Module A Sample Find Module
~~~~~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^
We will describe how to create a simple find module for a library We will describe how to create a simple find module for a library
``Foo``. ``Foo``.

6
Help/manual/cmake-qt.7.rst
View File

@ -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. to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
AUTOMOC AUTOMOC
''''''' ^^^^^^^
The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)` 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 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`: .. _`Qt AUTOUIC`:
AUTOUIC AUTOUIC
''''''' ^^^^^^^
The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)` 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 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`: .. _`Qt AUTORCC`:
AUTORCC AUTORCC
''''''' ^^^^^^^
The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)` The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)`
creates rules to execute ``rcc`` at the appropriate time on source files creates rules to execute ``rcc`` at the appropriate time on source files