[PATCH] Re: [cmake-developers] splitting the man page ?

[Alexander Neundorf]

On Tuesday 29 August 2006 14:56, Brad King wrote:
> 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.

Ok, I added a virtual bool IsDiscouraged() to cmCommand (as a non-native 
speaker the difference between obsolete and deprecated isn't quite clear to 
me). So these commands are now only "discouraged". This term is used through 
the whole patch, the new man pages are also called "cmake-modules" and 
"cmake-discouraged". Maybe "cmake-compat" or "cmake-deprecated" would be 
better.

The patch is not perfect, it probably needs some tuning, e.g. for the see-also 
section or the description at the top of each man page.

Opinions ?

Bye
Alex
-- 
Work: alexander.neundorf AT jenoptik.com - http://www.jenoptik-los.de
Home: neundorf AT kde.org                - http://www.kde.org
      alex AT neundorf.net               - http://www.neundorf.net
-------------- next part --------------
A non-text attachment was scrubbed...
Name: split-man-page.patch
Type: text/x-diff
Size: 26273 bytes
Desc: not available
URL: <http://public.kitware.com/pipermail/cmake-developers/attachments/20060829/b6946d1f/attachment.patch>