[cmake-developers] Testing wanted for ImproveCPackDoc

[Eric Noulard]

Hi all,

I'm did do some work in order to enhance CPack builtin documentation
support.

see:
http://www.cmake.org/Bug/view.php?id=10067

this is located in stage branch "ImproveCPackDoc".

I think the first two commits of this branch are ready for master
so I did merge it to next.
Those basically adds support for
--help-command*
--help-variable*
to cpack.

Support with almost no content because...

the last commit (which is not merged to next)
propose to get the variable and (some) macro/command documentation
directly from CMake 'builtin' script files.

As a proof of concept I modified CPack.cmake and CPackComponent.cmake.

The idea is to add extra CMake comment markup, i.e.

#   CPACK_PACKAGE_NAME - The name of the package (or application). If
#   not specified, defaults to the project name.

becomes:

##variable
#   CPACK_PACKAGE_NAME - The name of the package (or application). If
#   not specified, defaults to the project name.
##end

this way we can extract variable documentation from the file itself.

I borrowed & modified the module documentation parser
 bool cmDocumentation::CreateSingleModule(const char* fname,
                          const char* moduleName,
                          cmDocumentationSection &sec);

and created
  int cmDocumentation::getStructuredDocFromFile(const char* fname,
                               std::vector<cmDocumentationEntry>& commands,
                               cmake* cm,
                               const char *docSection);

CreateSingleModule simply ignores the new markup lines (those beginning with ##)

getStructuredDocFromFile does transforms doc block surrounded by
##<keyword

##end
into appropriate doc item.

I'd like some feedback before trying go further into this.
My main objective behind this is to avoid to have to specify the doc
in two places:
macro file & C++ code.

And may be to help user to document their CMake macro file as well.

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