deprecation (and a perl hacking task)

[Havoc Pennington <hp redhat com>]

Hi,

My previously proposed deprecation policy was totally overambitious;
and, Owen points out, would end up taking 10 years to get anything out
of GTK. Also, we have a couple large-scale architectural breakages in
mind for the future, and this means that effectively gradual phaseout
of facilities doesn't work very well. Maybe a better solution is to
depend on allowing parallel install of all GTK versions, so that
upgrades are not forced, and just use common sense to try to make
upgrades as easy as possible.

Still, would like to keep a couple features of the previous policy: 
 - a GTK_DISABLE_DEPRECATED that strips all deprecated declarations
 - a GTK_DISABLE_BROKEN that strips GtkText and GtkTree

Stuff marked deprecated is subject to disappear in any future version
subject to maintainer's best judgment.

Then, I'd suggest an addition to gtk-doc, which is a Deprecation:
field. e.g.:
 
  Deprecation: this function has been replaced by foo()

Should be allowed in inline docs and in the tmpl/ stuff. 

Any volunteers to add that? ;-)

If you want to get fancy, also allowing Deprecation: for a whole tmpl
file (e.g. the GtkTree page) would be good. And ideally adding that
would automatically result in a small notation by each function
documented in the file ("Note that this function is deprecated" where
"deprecated" links to the file-wide deprecation docs).

The main thing I think we should get out of this is docs of
deprecation, and allowing app developers to GTK_DISABLE_DEPRECATED if
they like.

Havoc