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 -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers