On 11/18/2013 02:56 PM, Stephen Kelly wrote: > 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.
This is really the start of several threads so I will branch out now. > 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. The conversion topic was massive as it was and I didn't want to handle this. I didn't know it was used for anything except local command-line help convenience. The old help infrastructure was certainly not ever intended for invocation in project build rules. Note that all the --help-* options dropped support for man-page-formatted output too: $ bin/cmake --help-modules cmake-modules.1 Warning: Man help format no longer supported I do not want to restore this behavior in general, but if you want to work on restoring the old --help-custom-modules behavior specifically for KDE's use case then please do so. It should be a bare-minimum implementation that extracts the old module documentation comment format and directly produces manual page content. It should work only when invoked as "--help-custom-modules some-man-page.1". That should restore support for building existing KDE release man pages. It should come with runtime and documentation warnings about not using the interface in new code. I do not want to try to expose and support a public interface to CMake's internal Sphinx configuration, Sphinx extensions, and .rst module comment scanning. That will again limit our ability to refactor in the future. If projects provide their own CMake modules they should do their own thing to generate documentation for them. -Brad -- 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
