[cmake-developers] cmake --help-custom-modules compatibility

[Matthew Woehlke]

On 2014-01-08 12:57, Brad King wrote:
> On 01/08/2014 12:00 PM, Matthew Woehlke wrote:
>> Since you mentioned it, I was wondering if this is related to a feature
>> I was asking about, but I don't understand how it works; it seems to
>> only ever generate a short boilerplate text.
>>
>> Is this meant to take a CMake module that is not part of the CMake
>> distribution and extract and format the documentation from the same?
>
> The old documentation system exposed this feature through the old
> --help-custom-modules option.  The new documentation system does not.
> This commit is about making old builds not totally break.
>
>> Because that is a feature I really wish CMake 3.0 would provide. (I know
>> you (Brad) previously mentioned that you don't want to in order to avoid
>> committing to any sort of compatibility guarantees with respect to the
>> same. But it still seems to me that such decision makes it unnecessarily
>> hard for third parties to provide documented CMake modules.)
>
> Anyone could fork CMake's Utilities/Sphinx infrastructure and provide
> it as a separate distribution with support and compatibility guarantees.
> I just do not want to provide it with CMake and constrain CMake's own
> documentation from evolving just to support external documents.  The
> compatibility issue in this thread is a perfect example of why.

 From my perspective, that's sort-of the point here... CMake used to 
provide for generating documentation from external modules. Now it 
doesn't. And it seems that KDE is also feeling that pain.

I'm not convinced that's a good thing. I get that you don't want to make 
things harder for developers, but doing so at the expense of making 
things harder for users doesn't seem like the best trade-off.

I'm also not sure I'm convinced by the compatibility argument. If you 
can't guarantee compatibility, then don't. Projects that want to use 
CMake to generate documentation for their CMake modules simply must use 
the version of CMake their documentation was written for to do so. (And 
update as necessary to meet the previous condition. Or fork the 
documentation system anyway.)

-- 
Matthew