Hi, We've had a while now to get used to the new docs system. Mostly I like it, though I haven't really looked much into what rst offers.
1) Indentation Something that I liked about the previous system was that the output from cmake --help-* was indented. Can we indent the rst output too? 2) Compatibility KDE relied on --help-custom-modules for creating a man page of the kde cmake modules. That does not work with CMake 3.0.0: http://quickgit.kde.org/?p=kdelibs.git&a=commitdiff&h=804d35394c366 I am left wondering why it would be difficult to process the existing (and very simple) markup in custom modules and generate rst on the fly for output from --help-module MyCustomModule and similar. Is there a reason not to restore compatibility like that? Otherwise any distro which upgrades to cmake 3 will lose those man pages in the KDE case, and probably similar in other cases. I think it would be best to avoid situations like distros packaging cmake 2.8 and cmake 3.0, possibly renaming executables etc etc so that KDE4 and other packages can continue to rely on cmake 2.8. Restoring and keeping compatibility with issues like this would be important to prevent that. 3) Language documentation I have a started a branch adding generic language documentation. +Languages are enabled by the :command:`project` command. If no project command is in your CMakeLists file, one will be implicitly generated. + +By default the enabled languages are C and CXX. A special value of NONE can also be used to enable no languages. + +The :command:`enable_language` command can also be used to enable languages after the project command. I'd also mention some language-specific variables (like CMAKE_CXX_COMPILER_LOADED) and language-relevant commands (such as target_compile_features whenever it gets in). Currently my branch adds that as a separate manual cmake-languages.7. That has far less content than most other manuals. Maybe if documentation about adding a new language were added it would be more justified. Or should such generic language documentation belong somewhere else, and not in a manual of its own? 4) Concept documentation My intention was to work down a typical CMakeLists file to add conceptual documentation where it makes sense. * cmake_minumum_required/policies * project/languages * find_package/Find modules/Config modules * build targets, various library types, target properties like PIC etc * imported and other pseudo/special targets, and exporting them * usage requirements * cross-compiling/toolchain files etc. Obviously, there are N ways one could split the above into M manuals. Any thoughts on how to do that? Group the build targets and psuedo targets together? Document the imported targets in the same manual as the Config modules? Document the usage requirements in the same manual as the build targets? Document the cross-compiling/toolchain items in the same manual as the language stuff? What other concepts should be documented, as a goal? Thanks, Steve. -- 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
