Commit eaafe756 authored by Brad King's avatar Brad King
Browse files

Help: Add documentation style section headers to cmake-developer.7

Give the style guides titles instead of numbers so we can link to them.
parent 4207b3a3
......@@ -465,168 +465,190 @@ with an explicit target.
Style
-----
1)
Command signatures should be marked up as plain literal blocks, not as
cmake ``code-blocks``.
Style: Command Signatures
^^^^^^^^^^^^^^^^^^^^^^^^^
2)
Signatures are separated from preceding content by a horizontal
line. That is, use:
Command signatures should be marked up as plain literal blocks, not as
cmake ``code-blocks``.
.. code-block:: rst
Signatures are separated from preceding content by a horizontal
line. That is, use:
... preceding paragraph.
.. code-block:: rst
... preceding paragraph.
---------------------------------------------------------------------
::
add_library(<lib> ...)
This signature is used for ...
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: 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
^^^^^^^^^^^^^^^^^^
add_library(<lib> ...)
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.
This signature is used for ...
Style: Document Self-References
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
Mark up self-references with ``inline-literal`` syntax. For example,
within the add_executable command documentation, use
4)
Use two spaces for indentation. Use two spaces between sentences in
prose.
.. code-block:: rst
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.
``add_executable``
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.
not
7)
Mark up self-references with ``inline-literal`` syntax. For example,
within the add_executable command documentation, use
.. code-block:: rst
.. code-block:: rst
:command:`add_executable`
``add_executable``
which is used elsewhere.
not
Style: Linkable References
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: rst
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.
:command:`add_executable`
Style: Technical Terms
^^^^^^^^^^^^^^^^^^^^^^
which is used elsewhere.
Mark up references to keywords in signatures, file names, and other
technical terms with ``inline-literl`` 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: Referencing Concepts
^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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
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:
This command creates an :ref:`Imported Target <Imported Targets>`.
.. code-block:: rst
instead of:
This command creates an :ref:`Imported Target <Imported Targets>`.
.. code-block:: rst
instead of:
This command creates an :prop_tgt:`IMPORTED` target.
.. code-block:: rst
The latter should be used only when referring specifically to the
property.
This command creates an :prop_tgt:`IMPORTED` target.
References to manual sections are not automatically created by creating
a section, but code such as:
The latter should be used only when referring specifically to the
property.
.. code-block:: rst
References to manual sections are not automatically created by creating
a section, but code such as:
.. _`Imported Targets`:
.. code-block:: rst
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`:
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`).
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.
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.
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`).
Style: Section Titles
^^^^^^^^^^^^^^^^^^^^^
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.
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:
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:
.. code-block:: rst
.. code-block:: rst
Title Text
----------
Title Text
----------
Capitalize the first letter of each non-minor word in the title.
Capitalize the first letter of each non-minor word in the title.
Style: Referencing CMake Domain Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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:
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
.. code-block:: rst
Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
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``.
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:
The ``policy`` directive is an exception, and the type us usually
referred to before the link:
.. code-block:: rst
.. code-block:: rst
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
Style: Command Signature Markup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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)
Use American English spellings in prose.
Style: Prose
^^^^^^^^^^^^
Use American English spellings in prose.
Modules
=======
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment