[cmake-developers] cmake --help-custom-modules compatibility (was: RST and documentation)

[Alexander Neundorf]

On Monday 18 November 2013, Brad King wrote:
> 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.

the author of the --help-custom-modules command line option certainly intended 
this to be used by other projects. ;-)
I don't know whether this is used only in KDE or also in other projects.

Alex