[cmake-developers] Documentation style guide

[Stephen Kelly]

Brad King wrote:
> 
>> 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.

What seems to be needed is a transition:

 http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#transitions

I added another commit to my clone making some use of this.

Another possibility may be a custom directive to create such a transition by 
transforming while at the same time denoting a signature:

 .. signature::

   add_library(<name> ALIAS <target>)

>> 4)
>>   Use two spaces for indentation.
> 
> In many cases the indentation is dictated by the context since
> reST is a 2-d markup language.

I discovered that while writing this list. I couldn't use

 2) This is 
   a multi-line item

(with two spaces indentation) but would have needed 3 spaces indentation, 
presumably to match the start of 'This'. That's why the text in this list 
starts below the line with the number.

> The choice is primarily in
> explicit markup blocks that start with a ".. " line or literal
> blocks after "::".  The style guide should make this clear.

It also has come up in description lists. 

See eg cmake-generator-expressions(7), which I wrote with two spaces 
indentation and compare with cmake-developer(7), which you wrote with one 
space. I find two preferable.

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

I'd prefer to recommend two in that case. It's the same as cmake c++ code, 
so it's a more familiar and consistent indent, and the indentation is more 
obvious when it is two instead of one.

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

The output in my topic for target_link_libraries contains:

(assumed if omitted).  Higher granularity may be achieved for
per-configuration rules by creating and linking to
:ref:`IMPORTED library targets <Imported Targets>`.

CMake will also propagate :ref:`usage requirements <Target Usage 
Requirements>`
from linked library targets.

I think it's fine, and I'm not sure what the cmRST would transform it into 
if we go down that road.

Thanks,

Steve.