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

[Eric Noulard]

2012/1/25 Brad King <brad.king at kitware.com>:
> On 1/25/2012 3:20 PM, Eric Noulard wrote:
>>
>> So with my proposal you can perfectly document a script in the middle
>> of the file or as usual just in front of the concerned
>> macro/function/var. This may be easier for doc maintenance because
>> the function/macro would be closer to its doc.
>
>
> Nice.
>
>
>> My idea for user script doc support may be to add an extra
>> "cdoc" command that would be dedicated to documentation
>> of script files:
>
>
> I think "cmake --doc" is better than a new command tool in the PATH.
>
>
>> An alternative would be to defined something like:
>>    CMAKE_USER_DOC_PATHS
>>    CPACK_USER_DOC_PATHS
>>    CTEST_USER_DOC_PATHS
>
>
> If a module does not come with CMake I'd rather ask the user to
> explicitly list the modules to be included in a documentation request
> on the command line.
>
>
>> The limitation I personnally see in such kind of markup is that
>> it cannot be very much enhanced
>> (cross-link, more text formatting like bold, italic, etc...)
>> without breaking current doc parser.
>
>
> 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.

Brad,

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?

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.

My "personal" best choice would be to keep the proposed markup
and use "asciidoc/RST" inside the free text block.
Such that --help-xxxx command could spit out asiidoc/RST that can be further
processed by appropriate tools external to CMake.

-- 
Erk
Membre de l'April - « promouvoir et défendre le logiciel libre » -
http://www.april.org