[CMake] Documentation strategy

[Brandon Van Every]

On 7/12/07, Mike Jackson <imikejackson at gmail.com> wrote:
>
> Docs.. Lets talk about that for a second.
>      The only place I found that command was if I did a 'cmake --help-
> html /tmp/cmake.html' and then searched through the html file. I
> actually found the macro by looking through the "modules"
> installation directory at the filenames. That got me thinking about a
> "better" way to do the CMake Docs. (They are decent, just not easily
> searchable).
>
> 1. The Totally Awesome way - Use all the new found knowledge of the
> QtAssistant system and integrate the CMake docs into a QtAssistant
> Module. Then there would be universal way to search/index the docs
> and easily find what we are looking for.
>
> 2. The slightly better than what we have now way - I can get ALL the
> commands in ONE html file or I can get individual commands as text
> files. How about a set of HTML docs where we have a main page with a
> frame with all the commands listed on one side and when you click on
> the command the docs shows in the other frame. This would at least
> allow one to peruse the list and maybe some up with something.
>
> I think at this point I am going to generate the text files for each
> of the commands. Then OS X can use spotlight to index the files.
> Would be better if these commands were in HTML then I could basically
> write a quick shell script to generate the doc set.
>
> And before anyone asks me to "step up to the plate", I would be more
> than happy to, just show me where in the code the HTML is being
> produced and I'll make the changes.

Please see bug http://public.kitware.com/Bug/bug.php?op=show&bugid=3676
"Table Of Contents for documentation."  Also, the recent mail thread
titled "Documentation strategy."

CMake has a strategic problem that there is no easy way for  the CMake
community to edit, correct, and evolve the documentation.  I've
entered plenty of "Content" bugs in the bug tracker, for specific
things that should be documented, but Kitware doesn't act on them.
It's not a priority to them, and similarly, it's not a priority to me
to get in there and dig through the sources.  So it's an impasse; the
mechanism is too cumbersome for everyone involved.

What mechanism will lift the impasse?  It has to be easy for the
community to make doc improvements.

Alex recently suggested:
> http://wiki.docbook.org/topic/Wt2Db + some more scripting
> should probably do quite a lot.


Cheers,
Brandon Van Every