[cmake-developers] [PATCH] split the cmake man page into four man pages

[Alexander Neundorf]

Hi,

back in the times when I got to know cmake (must have been 1.8 or so) it was 
easy to have a look at the cmake man page and just check out which commands 
there are.

Now we have cmake 2.4.6 and a lot has happened.
Documentation for the modules has been added, which is a very good thing.
New and more powerful commands have been implemented superseeding old 
commands.
Recently documentation for properties has been added.

While all this is very good, it also has the side effect that the man page has 
grown very much and has become to big to overview it.
That's why here comes a patch which splits the man page into four man pages:
cmake - command line options and commands (as in the good old times ;-)
cmakecompat - compatibility (discouraged) commands only
cmakeprops - the properties
cmakemodules - the modules

The names have been deliberately chosen, as they are they are easy and fast to 
type, IMO important for man pages.

Maybe even one or two more manpages could be generated:
-either an all-in-one page (as it is without the patch)
-or an all-in-one page (cmakeall) and additionally split the command line 
options off from the cmake man page (-> cmakecli)

The patch does quite a lot of things.
It uses the IsDiscouraged() member to separate between current and 
compatibility commands. These commands are collected into a separate list of 
commands.
The patch also introduces a new internal class cmDocumentation::cmSection, 
which represent one section in the documentation and handles e.g. the 
different section names depending on the output form. This simplifies the 
code in some places. 
cmDocumentation::CurrentForm is now used much more.
New command line options --help-modules-man, --help-props-html etc. have been 
added. What do you think about changing them to "--help-modules [html|man|
text] [filename]" ? Then 6 command line options less exist, which makes for  
shorter documentation :-)

So, what do you think about this ?

One issue is IMO still left, the docs for FIND_PATH, FIND_PROGRAM, 
FIND_LIBRARY and FIND_FILE are quite long and detailed, but all four are 
quite similar. Maybe these four could somehow be shortened or unified a bit ? 
The long documentation might be a bit discouraging for newbies. 

Bye
Alex
-- 
Work: alexander.neundorf AT jenoptik.com - http://www.jenoptik-los.de
Home: neundorf AT kde.org                - http://www.kde.org
      alex AT neundorf.net               - http://www.neundorf.net
-------------- next part --------------
A non-text attachment was scrubbed...
Name: cmake-manpage-split.patch
Type: text/x-diff
Size: 42172 bytes
Desc: not available
URL: <http://public.kitware.com/pipermail/cmake-developers/attachments/20070123/ac81ba1d/attachment.patch>