Re: Accompany index of deprecated symbols with GTK+ version?

[David Nečas (Yeti) <yeti physics muni cz>]

On Mon, Nov 13, 2006 at 01:02:57PM +0100, Jan-Oliver Wagner wrote:
> No, I do not have 2.4 at hand. It is not handy to always install
> the version that is the targetted minimum version of GTK+.
> Today it is 2.4, tomorrow (for another project) 2.2 etc.

I don't think downloading and unpacking one tarball is so
much work.  You don't have to actually compile and install
it, the documentation sits inside in a ready-to-use form.

> In practice it there is often the situation to upgrade a tool from e.g.
> GTK+ 2.2 to 2.4. Now I want a quick list of symbols I have to migrate.
> (I have a simple script that searches for occurances of deprecated symbols
> - it would be cool to have a parameter "--gtk-version 2.4" to comfortably find
> out  the TODOs for an GTK+ upgrade to 2.4.)

Note this has nothing to do with an upgrade to 2.4.  What
worked with 2.2 will very likely work with 2.4.  And in the
cases it breaks, it is not because something has been
deprecated.  It is because of some minor or marginal
run-time behaviour changes (or even bugfixes) that
unfortunately break certain assumptions your app makes.

On the other hand, what works with 2.4 using only 2.2
functions may not necessarily wotk with 2.2 because some 2.2
bugs were fixed in 2.4 and the thing works properly only
there.

Mass removal of deprecated symbols *only* for the purpose of
removal of deprecated symbols is a good method to waste time
and bring new bugs.

Now something more practical: I don't know where your script
takes information from, but it is probably present in Gtk+
source tarball.  So again, downloading and unpacking the
tarball should be everything you need.

> IMHO the ideal solution is to extend the table of deprecated symbols with
> this tiny information on the GTK+ version.

Deprecation information gets to the documentation from
conditional complation constructs such as

  #ifndef GTK_DISALBE_DEPRECATED
  ...
  #endif

and

  #ifdef GTK_ENABLE_BROKEN
  ...
  #endif

in header files.  In other words, unlike in Since marks in
gtk-doc comments that explicitly say `Since: SOME.VERSION'
(assuming someone has not forgot to place them there -- when
this happens, the new symbols index becomes skewed), there
is no version information.  The only way to get version
information for deprecation is from the corresponding Gtk+
version (or more versions and compare).

Now, if you think such an index would be so useful you can
write a gtk-doc patch to enable some kind of version info in
the conditional compilation constructs (the easy part) and
actually add the proper deprecation version info to the
headers (the hard part).  Or invent some other method to get
the information there, like semiautomatic extraction using
tarballs of previous Gtk+ versions...  But in my opinion it
does not worth the work.

Yeti


--
Whatever.