New TechBase for Documenting our CMake Stuff

[Alexander Neundorf]

On Tuesday 18 September 2007 22:31, Alexander Neundorf wrote:
> Hi,
>
> On Tuesday 18 September 2007 09:22, Allen Winter wrote:
> ...
>
> > Oh, now I get it.  cmake already has the --help-man, --help-html, --help
> > options. But you want to:
> >  1) add a new --help-docbook option
>
> So is docbook the format we would want to have or is there something else
> which can serve as generic markup format ?
>
> >  2) extend the help options to look in a specified dir to extract even
> > more help info
>
> Maybe the code could check also look in the directories listed in
> CMAKE_MODULE_PATH and generate documentation for the files found there.
> This documentation should be put into an own help "page" "Custom modules"
> or something like this (cmake cvs generates one all-in-one man page and man
> pages split into commands, compatibility commands, properties and
> variables, modules).
> I didn't check yet whether CMAKE_MODULE_PATH is available when running
> cmake for generating documentation.
>
> Any change for this won't make it into any cmake 2.4.x release anymore, but
> will be in 2.6.0. But I think having an additional feature only available
> if you have a very recent cmake version is ok (actually there is no other
> option).


Ok, I worked on both issues.

1) cmake cvs HEAD is now able to generate documentation for custom modules, 
you have to set CMAKE_MODULE_PATH:

cmake -DCMAKE_MODULE_PATH=/path/to/kdelibs/cmake/modules --help-custom-modules

will print the docs to stdout, adding a filename will print it in this file 
(as HTML if the name ends with .html, as man page if it ends with .[0-9], 
plain text otherwise).

Brad suggested to have cmake generate additional files like 
CMakeFiles/CMakeModulePath.cmake in every subdirectory, which contain for 
every directory the current CMAKE_MODULE_PATH. This way cmake could check for 
the existence of this file and get the CMAKE_MODULE_PATH from it. This way 
cmake would automatically know the directories of additional modules if it is 
run in a build tree.
(This can also help editors which want to offer advanced autocompletion for 
cmake, since they will also have a way to detect available cmake modules.)

2) Currently cmake supports plain text, html and man as output formats. These 
have now been factored out into separate classes 
(cmDocumentationFormatter(HTML|Man|Plain).cxx. This should make it much 
easier to add an additional output format like docbook. I don't know docbook, 
so I really can't do this. Somebody else has to come up with a patch for this 
against cmake cvs HEAD.

Bye
Alex