[cmake-developers] Improving CPack Documentation (and may be others as well)

[Brad King]

On Tue, Jan 31, 2012 at 9:42 AM, Eric Noulard <eric.noulard at gmail.com> wrote:
> 2012/1/25 Brad King <brad.king at kitware.com>:
>> I'd rather switch to a real documentation engine like asciidoc than
>> implement all those markup capabilities.  We'd need one that can handle
>> literate programming for .cmake modules though.
>
> Do you mean that I should drop the current work and go for asciidoc
> (and leaving backward compatibility alltogether) or that the current
> markup is ok (and could be merged to next) and that we could
> go a step further by using asciidoc later or only inside the current
> preformatted doc?

The current work is fine for its purpose.  I just don't want to
implement yet another markup language with all the bells and whistles
instead of using an existing one.

> Concerning asciidoc, do you want to examine alternative like RST
> http://blog.ser1.net/2011/06/restructuredtext-vs-asciidoc.html
>
> I did gave some example back in october:
> http://www.cmake.org/pipermail/cmake/2011-October/047071.html
>
> The main trouble with asciidoc or RST is that I didn't find a C/C++
> parser to easily embed in CMake and it doesn't seem that easy to
> implement by hand.

The solution to that may be to hand the documentation request over to
a man page viewer or html viewer.

Let's leave this problem for another time/discussion.  The markup
you're currently proposing has semantics meaningful to CMake in that
it identifies the purpose of a block of documentation.

Thanks,
-Brad