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 that could contain a list of user set PATHS containing *.cmake files and then cmake ---help-command-list would also load and parse all *.cmake files found in "CMAKE_USER_DOC_PATHS". whatever the idea we should be able to share: - the markup for CMake/CTest/CPack **and** user scripts - the doc parser and formatter. > I don't know if others have an opinion though. Opinion/feedback from other are more than welcome. The limitation I personnally see in such kind of markup is that it cannot be very much enhanced (cross-link, more text formatting like bold, italic, etc...) without breaking current doc parser. So if we accept to break backward compatible module doc parser we could easily add more advance markup. An intermediate option would be to trap to more advanced markup only in a "new markup" section..... -- Erk Membre de l'April - « promouvoir et défendre le logiciel libre » - http://www.april.org -- 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
