[cmake-developers] Converting CMake documentation to reStructuredText and Sphinx

[Brad King]

On 10/11/2013 10:43 AM, Daniel Pfeifer wrote:
> Comparing the expressiveness, extensability, and supported backends,
> can you explain why you would prefer rST over AsciiDoc?

There is a good comparison chart here:

 http://en.wikipedia.org/wiki/Lightweight_markup_language#Comparison_of_language_features

I don't want to get into an extended debate about the choice.  They
all have similar expressive power.  I actually started with AsciiDoc
originally and moved to reST later due to reasons that include:

- License of supporting tools

- Sphinx provides mature support for x-refs across multiple documents,
  indexing, searching, and extensions for things like scanning markup
  out of .cmake module sources directly

- Personal preference for markup syntax

I understand that you're frustrated by DocBook support being dropped,
and that AsciiDoc supports DocBook, but trade-offs have to be made.
It is not impossible to add DocBook support to Sphinx.

-Brad