On Wednesday 25 January 2012, Eric Noulard wrote: > 2012/1/25 Brad King <brad.k...@kitware.com>: > > On 1/24/2012 5:50 PM, Eric Noulard wrote: > >> cmake --help-module CPackComponent > >> or any other (untouched module) > >> cmake --help-module FindQt4 > >> > >> you'll see that the extra space are there as well. > >> So yes there is too much space, but this is not due to > >> my current proposal, it was there before. > >> We can handle that separately. > > > > Agreed. Sorry, I forgot that this problem already existed. > > It was created by the original module documentation extractor. > > It inconsistently treats transitions from paragraph text to > > preformatted text and back, giving the latter extra blank lines. > > Now we can't fix it without changing the formatting of all the > > existing documentation. (Perhaps the markup can help with that > > later.) > > > >> I won't be doing this now I'd rather agree on the new markup > >> feature first. > > > > The markup feature looks fine to me. The markup syntax adds > > some information even for those reading the raw source. > > Yes and I forgot to mention that it has a extra feature compared > to the current module doc parser. > > It does look for markup on the **whole** file unlike > current module doc parser which only parse the header > (at the beginning of the file). > > So with my proposal you can perfectly document a script in the middle > of the file or as usual just in front of the concerned > macro/function/var. This may be easier for doc maintenance because > the function/macro would be closer to its doc. > > This could be further used for user script that could be > documented this way as well. > > My idea for user script doc support may be to add an extra > "cdoc" command that would be dedicated to documentation > of script files: > > a) cdoc --help-command-list yourscript.cmake > b) cdoc --help-variable-list yourscript.cmake > c) cdoc --help yourscript.cmake > > may spit out: > a) the doc for macro/function in the concerned script > b) the doc for variables > c) all doc > > this command may have more versatile option to include > or exclude (cmake/ctest/cpack) doc and/or add some path > where to parse all *.cmake files etc.... > > An alternative would be to defined something like: > CMAKE_USER_DOC_PATHS > CPACK_USER_DOC_PATHS > CTEST_USER_DOC_PATHS
cmake already supports CMAKE_MODULE_PATH for generating help, e.g. like this: $ cmake -DCMAKE_MODULE_PATH=$HOME/src/kdelibs/cmake/modules/ --help-custom- modules This generates docs for all cmake files in CMAKE_MODULE_PATH. --help-module also looks in CMAKE_MODULE_PATH. I'm not sure it needs a new variable. Alex -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
