[cmake-developers] Documentation style guide

[Stephen Kelly]

Hi,

I pushed update-buildsystem-docs to my clone. Generally, I want to make sure 
that the links one hop away from the primary new manuals are properly marked 
up as rst for the release.

I need a style guide for that, so I wrote one as a starting point for 
discussion.


Style
-----

1)
  Command signatures should not be marked up as cmake code.
2)
  Signatures are introduced in prose after their appearance. That is, use:

  .. code-block:: rst

    ... preceding paragraph.

    ::

      add_library(<lib> ...)

    This signature is used for ...

  instead of:

  .. code-block:: rst

    ... preceding paragraph.

    The signature::

        add_library(<lib> ...)

    is used for ...

  The ``::`` is a sufficient delimiter.

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.

4)
  Use two spaces for indentation.

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 80 columns.  This is not a hard
  restriction.

7)
  Mark up self-references with ``syntax``. For example, within the
  add_executable command documentation, use

  .. 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 ``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.


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:

  .. code-block:: rst

    This command creates an :ref:`Imported Target`.

  instead of:

  .. code-block:: rst

    This command creates an :prop_tgt:`IMPORTED` target.

  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:

  .. code-block:: rst

    .. _`Imported Targets`:

  creates a suitable anchor.

  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 (`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 (It might make sense to move some of the
  :command:`target_link_libraries` documentation to :manual:`cmake-
buildsystem(7)`)


Comments?

Thanks,

Steve.