2012/1/25 Brad King <brad.k...@kitware.com>: > On 1/25/2012 3:20 PM, Eric Noulard wrote: >> >> 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. > > > Nice. > > >> My idea for user script doc support may be to add an extra >> "cdoc" command that would be dedicated to documentation >> of script files: > > > I think "cmake --doc" is better than a new command tool in the PATH. > > >> An alternative would be to defined something like: >> CMAKE_USER_DOC_PATHS >> CPACK_USER_DOC_PATHS >> CTEST_USER_DOC_PATHS > > > If a module does not come with CMake I'd rather ask the user to > explicitly list the modules to be included in a documentation request > on the command line. > > >> 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. > > > I'd rather switch to a real documentation engine like asciidoc than > implement all those markup capabilities. We'd need one that can handle > literate programming for .cmake modules though.
Brad, Do you mean that I should drop the current work and go for asciidoc (and leaving backward compatibility alltogether) or that the current markup is ok (and could be merged to next) and that we could go a step further by using asciidoc later or only inside the current preformatted doc? Concerning asciidoc, do you want to examine alternative like RST http://blog.ser1.net/2011/06/restructuredtext-vs-asciidoc.html I did gave some example back in october: http://www.cmake.org/pipermail/cmake/2011-October/047071.html The main trouble with asciidoc or RST is that I didn't find a C/C++ parser to easily embed in CMake and it doesn't seem that easy to implement by hand. My "personal" best choice would be to keep the proposed markup and use "asciidoc/RST" inside the free text block. Such that --help-xxxx command could spit out asiidoc/RST that can be further processed by appropriate tools external to CMake. -- 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
