gtk-doc changes

[Matthias Clasen <mclasen redhat com>]

Hi,

I've worked a bit on gtk-doc in the past few days, and thought it might
be a good idea to mention here what I've done.

- Default values and allowed values of properties are now documented,
and the formatting of the Properties section is nicer. This is all done
by introspection.

- gtk-doc.xsl checks the version number of the xsl stylesheets now and
refuses to work with stylesheets older than 1.36. I don't actually know
if 1.36 is new enough to work sufficently well, so the number may need
adjustment.

- Multiple, filtered indices. gtk-doc now adds role attributes to the
indexterms it emits, and you can use something like the following: 

  <index>
    <title>Index</title>
  </index>
  <index role="deprecated">
    <title>Index of deprectated symbols</title>
  </index>
  <index role="2.2">
    <title>Index of new symbols in 2.2</title>
  </index>
  <index role="2.4">
    <title>Index of new symbols in 2.4</title>
  </index>

To create four indices: one containing all symbols, and three more
containing only deprecated, new in 2.2 and new in 2.4 symbols. Note that
this feature depends on support in the xsl stylesheets which is
currently only in the cvs version of the stylesheets and will appear in
the next version, 1.62. I've added code to prevent the generation of
multiple indices if the stylesheets don't support filtered indices, so
you can add the additional <index> elements to your templates now, and
the filtered indices will start to appear as soon as you install version
1.62 of the xsl stylesheets.

- Pruning the object hierarchy. An old problem of gtk-doc was that
foreign and private types would appear in the object hierarchy and in
the lists of implemented or required interfaces. These are now filtered
out, ie foreign or private types will appear in the object hierarchy
only if they have to, and private types will not appear in the lists of
implemented or required interfaces. Note that "private" here means types
which are mentioned in a Private or Standard subsection of the
$MODULE-sections.txt file,  and "foreign" means types which are not
mentioned at all. So, in order to make private types disappear from the
lists of implemented or required interfaces, you may have to add them to
a Private subsection.

Regards, Matthias