Commit 05bd31ab authored by Brad King's avatar Brad King
Browse files

Help: Organize documentation style sections in cmake-developer.7

Now that the style guidelines have section titles instead of numbers,
organize them into more well-defined sections.
parent eaafe756
......@@ -465,35 +465,19 @@ with an explicit target.
Style
-----
Style: Command Signatures
^^^^^^^^^^^^^^^^^^^^^^^^^
Command signatures should be marked up as plain literal blocks, not as
cmake ``code-blocks``.
Style: Section Headers
^^^^^^^^^^^^^^^^^^^^^^
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
... preceding paragraph.
---------------------------------------------------------------------
::
add_library(<lib> ...)
This signature is used for ...
Style: Boolean Constants
^^^^^^^^^^^^^^^^^^^^^^^^
Title Text
----------
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.
Capitalize the first letter of each non-minor word in the title.
Style: Whitespace
^^^^^^^^^^^^^^^^^
......@@ -501,14 +485,6 @@ 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
^^^^^^^^^^^^^^^^^^
......@@ -517,37 +493,60 @@ hard restriction, but writing new paragraphs wrapped at 75 columns
allows space for adding minor content without significant re-wrapping of
content.
Style: Document Self-References
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mark up self-references with ``inline-literal`` syntax. For example,
within the add_executable command documentation, use
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
``add_executable``
... preceding paragraph.
not
---------------------------------------------------------------------
.. code-block:: rst
::
:command:`add_executable`
add_library(<lib> ...)
which is used elsewhere.
This signature is used for ...
Style: Linkable References
^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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.
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: Technical Terms
Style: Inline Literals
^^^^^^^^^^^^^^^^^^^^^^
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
......@@ -555,8 +554,17 @@ technical terms with ``inline-literl`` syntax, for example:
:prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
creates the file ``<name>.exe`` on Windows.
Style: Referencing Concepts
^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
......@@ -598,26 +606,12 @@ 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.
Style: Section Titles
^^^^^^^^^^^^^^^^^^^^^
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.
Style: Referencing CMake Domain Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 `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:
.. code-block:: rst
......@@ -636,19 +630,21 @@ referred to before the link:
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
Style: Command Signature Markup
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
However, markup self-references with ``inline-literal`` syntax.
For example, within the :command:`add_executable` command
documentation, use
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.
.. code-block:: rst
Style: Prose
^^^^^^^^^^^^
``add_executable``
Use American English spellings in prose.
not
.. code-block:: rst
:command:`add_executable`
which is used elsewhere.
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