[cmake-developers] kwrobot changing documentation

Brad King brad.king at kitware.com
Wed Jan 29 14:28:41 EST 2014


On 01/29/2014 01:16 PM, James Bigler wrote:
> I noticed in the git history that the kitware robot changed the
> documentation in the source files to something with "::" characters
> between paragraphs.

That was the automatic conversion of documentation to reStructuredText.
The automatic conversion was done by extending the old documentation
formatters (that generated man, html, etc.) with a short-lived formatter
generating reStructuredText.

The '::' characters are markup indicating that the following indented
block is literal.  The conversion process placed them in front of any
block that came from a preformatted block in the old markup format.
This would be any block of text that begins in indentation.

One can see in the 2.8.12 documentation that most of FindCUDA's
documentation was in indented preformatted blocks:

 http://www.cmake.org/cmake/help/v2.8.12/cmake.html#module:FindCUDA

That is why the automatic conversion added '::'.

Several modules whose original documentation was not written with
careful attention paid to the old markup format need manual tuning
after conversion.  I've just now updated FindCUDA:

 FindCUDA: Fix literal block formatting
 http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=1f8eb5db

with minimum reformatting.

-Brad




More information about the cmake-developers mailing list