[CMake] Documentation strategy

[Philippe Fremy]

Brandon Van Every wrote:
> On 6/20/07, Philippe Fremy <phil at freehackers.org> wrote:
>>
>> All in all, CMake is a good and powerful tool, but I find that the
>> documentation is lacking behind. More structure, more usage example,
>> more common cases would in my opinion really help the user experience.
> 
> Well, you can buy the "Mastering CMake" book.
> 
> There's this strategic problem that modifying the CMake docs and
> submitting patches for them is cumbersome.  The auto-doc structure is
> fine for documenting individual functions, but it provides no
> structure at all for general concepts encompassing many functions, or
> CMake operative principles in general.  I haven't looked into whether
> there's a good answer for this, although at some point I may.  It's a
> basic infrastructure problem.

What comes to my mind is to play with doxygen and a pre-processor, to
convert CMake documentation structure to something that doxygen can consume.

Then you get a nice html-linked documentation, that you can group by
structure. You can have warnings issued if you didn't explain every
argument of your function, or if you did not specified the return type.

Doxygen doc can convert to pdf, html, windows help files and man pages.
You put generic documentation and detailed design documengation in doxygen.

To see an example of a project taking advantage of doxygen for general
documentation, you can check Yzis - http://doc.yzis.org .

> I'm not sure wikis are the answer either.  I do add things to the
> wiki, but I don't think wikis really cause a lot of people to make
> significant doc contributions. 

Given the current quality of the doc, I think it would work better if
the cmake doc would simply be imported into the wiki, so that people can
improve it.

> Then you run into the problem of "how
> do we ship wiki docs?"

That's the real question. Given the content of the wiki now, it would
already be a valuable addition to ship with the existing documentation.

> What people really want is docs that work
> well with their chosen IDE.

Before that, a slightly more generic documentation of CMake concepts
would be welcome. Quoting and variables is for example a topic that is
not really covered anywhere. For me, the behavior was quite strange
(different than what I expected). I had to rely on lot of
experimentations to understand what CMake is doing.

That's probably covered in the book, but I find it strange that you need
a book to be able to use an open source tool like CMake. Maybe I am too
used to high quality documentation ?


	Philippe