On 6/21/07, Philippe Fremy <[EMAIL PROTECTED]> wrote:
To see an example of a project taking advantage of doxygen for general documentation, you can check Yzis - http://doc.yzis.org .
Doxygen is certainly a broadly accepted standard in open source. I just don't know if anyone has done wiki <--> Doxygen in an off-the-shelf reproducible way.
> 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.
This has a history in the bug tracker, which you can read about at bug #3757, "ship FAQ as part of documentation." At that time, Kitware said it's too much work to maintain a shipped FAQ or other wiki information. I agree that without an infrastructure to handle wiki <--> docs, it is too much work. We got URLs to the wiki in the documentation, at the very end of the docs. This works fine for Unix man pages, where they're the last thing you see as you scroll the man page, and it's in the expected place for that sort of information in a man page. It is not fine when reading the docs in a HTML browser on Windows. It's at the very end of the docs and will almost never be read. I entered a content bug some time ago, #3907 "Windows start menu links for online documentation." That's a logical place that Windows users go to look for docs. I've entered a new one, #5225 "put wiki URLs at top and bottom of docs."
> 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.
Yep. That's bug #3676, "Table of Contents for documentation." Recently, Bill and I had a long, private discussion about all the content bugs, and what is to be done about them. My conclusion is that Kitware doesn't have the resources to address these things, and the community has to find a way to do it. The process for modifying the docs is too cumbersome for the community at present. The community has to devise a better infrastructure, or this situation will persist indefinitely.
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 ?
Not at all. The vast majority of mature commercial products out there, open source ones included, have high quality electronic documentation. CMake can either provide that like everyone else does, or fall by the wayside over time. There's too much competition out there for people to accept this situation indefinitely. Cheers, Brandon Van Every _______________________________________________ CMake mailing list [email protected] http://www.cmake.org/mailman/listinfo/cmake
