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

Brad King brad.king at kitware.com
Wed Jan 25 16:33:53 EST 2012


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



More information about the cmake-developers mailing list