[cmake-developers] Documentation style guide

[Brad King]

On 02/03/2014 08:32 AM, Stephen Kelly wrote:
> 1)
>   Command signatures should not be marked up as cmake code.

More specifically, they should be plain literal blocks.

> 2)
>   Signatures are introduced in prose after their appearance.

I've never been happy with this style.  The literal block with
a signature does not stand out as the beginning of a "section"
and looks more like the end.  It works cleanly only when there
is just one signature at the top.  I think preceding each
signature with prose, if only just "Usage::", is cleaner.
It also lets us put the "::" for the literal block at the end
of a paragraph instead of on its own so it looks nicer in the
plain reST source form.

> 3)
>   Use "``OFF``" and "``ON``" for boolean values
>   Use "``True``" and "``False``"for inherent values

Okay.

> 4)
>   Use two spaces for indentation.

In many cases the indentation is dictated by the context since
reST is a 2-d markup language.  The choice is primarily in
explicit markup blocks that start with a ".. " line or literal
blocks after "::".  The style guide should make this clear.

I've been in the habit of using only *one* space in such blocks.
Since they tend to contain pre-formatted literal text it is nice
to have the extra column width.  IMO it looks nice after the ".. "
explicit block start line too.  I don't feel strongly though.

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

Yes.

> 6)
>   Prefer to restrict the width of lines to 80 columns.  This is not a hard
>   restriction.

Yes.  Also new prose should start with fewer columns if possible to
reduce the need for future re-wrapping on small edits.

> 7)
>   Mark up self-references with ``syntax``.

Yes.  Perhaps use the wording

 Mark up self-references with ``inline-literal`` syntax.

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

Yes.

> 9)
>   Mark up references to keywords in signatures, file names, and other 
> technical
>   terms with ``syntax``, for example:

Yes.  Again, ``inline-literal`` syntax.

> 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 one is tricky because the C++--implemented reST processor used
for "cmake --help-*" options will not process :ref:`` syntax.  It
usually looks okay with that syntax in raw form anyway though.

Before establishing a style, please review how the results look in
command-line help output.  Of course one could enhance the C++ rst
processor if necessary, but I don't want it to get too complex.

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

Yes.

Thanks,
-Brad