[cmake-developers] splitting the man page ?

[Brad King]

Alexander Neundorf wrote:
> On Monday 28 August 2006 16:24, you wrote:
>> Alexander Neundorf wrote:
>>> I had a look at the code, and found that there is already a
>>> cmCommand::IsDeprecated(int major, int minor); which currently for all
>>> commands returns false.
>>> If I would now make it return true for the deprecated commands, I would
>>> be able to use this to generated the documentation of all/only the
>>> deprecated/only the not deprecated commands.
>>> The problem here is that if I would do this, then cmake would report an
>>> error (in cmMakefile::ExecuteCommand() ) everytime a deprecated command
>>> is used, so many cmake scripts out there would break.
>>>
>>> So what do you suggest ?
>>> Add another function IsObsolete() to cmCommand and use this only for the
>>> docs ?
>>> Make IsDeprecated return true for the appropriate commands but don't let
>>> cmMakefile::ExecuteCommand() generate an error for this case ?
>> Don't hard-code the return value of IsDeprecated.  Instead we should
>> check the value of CMAKE_BACKWARDS_COMPATIBILITY and return true from
>> IsDeprecated if the value is set high enough.  However we don't want to
>> parse this variable every time a command is invoked, so we may want to
>> make sure there is a fast way to get this value from cmMakefile too.
> 
> Ok, but even if I would do this, marking some commands now as deprecated would 
> break many scripts, wouldn't it ?
> So e.g. if CMAKE_BACKWARDS_COMPATIBILITY is set e.g. to 1.6, no command should 
> return true for IsObsolete() right ?
> I guess when building cmake CMAKE_BACKWARDS_COMPATIBILITY isn't set, so this 
> would work.

On second thought, commands like INSTALL_TARGETS will probably never be
deprecated because they are so widely used.  Adding a separate
IsObsolete sounds fine to me.

-Brad