[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/24/2012 5:50 PM, Eric Noulard wrote:
>>
>> cmake --help-module CPackComponent
>> or any other (untouched module)
>> cmake --help-module FindQt4
>>
>> you'll see that the extra space are there as well.
>> So yes there is too much space, but this is not due to
>> my current proposal, it was there before.
>> We can handle that separately.
>
>
> Agreed.  Sorry, I forgot that this problem already existed.
> It was created by the original module documentation extractor.
> It inconsistently treats transitions from paragraph text to
> preformatted text and back, giving the latter extra blank lines.
> Now we can't fix it without changing the formatting of all the
> existing documentation.  (Perhaps the markup can help with that
> later.)
>
>
>> I won't be doing this now I'd rather agree on the new markup
>> feature first.
>
>
> The markup feature looks fine to me.  The markup syntax adds
> some information even for those reading the raw source.

Yes and I forgot to mention that it has a extra feature compared
to the current module doc parser.

It does look for markup on the **whole** file unlike
current module doc parser which only parse the header
(at the beginning of the file).

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.

This could be further used for user script that could be
documented this way as well.

My idea for user script doc support may be to add an extra
"cdoc" command that would be dedicated to documentation
of script files:

a) cdoc --help-command-list yourscript.cmake
b) cdoc --help-variable-list yourscript.cmake
c) cdoc --help yourscript.cmake

may spit out:
  a) the doc for macro/function in the concerned script
  b) the doc for variables
  c) all doc

this command may have more versatile option to include
or exclude (cmake/ctest/cpack) doc and/or add some path
where to parse all *.cmake files etc....

An alternative would be to defined something like:
   CMAKE_USER_DOC_PATHS
   CPACK_USER_DOC_PATHS
   CTEST_USER_DOC_PATHS

that could contain a list of user set PATHS containing *.cmake files
and then
cmake ---help-command-list
would also load and parse all *.cmake files found in "CMAKE_USER_DOC_PATHS".

whatever the idea we should be able to share:
   - the markup for CMake/CTest/CPack **and** user scripts
   - the doc parser and formatter.

> I don't know if others have an opinion though.

Opinion/feedback from other are more than welcome.

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.

So if we accept to break backward compatible module doc parser
we could easily add more advance markup.

An intermediate option would be to trap to more advanced markup
only in a "new markup" section.....


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