GNOME Bugzilla – Bug 115530
deprecated index
Last modified: 2004-12-22 21:47:04 UTC
looking at javadoc for inspiration, I think it might be a nice idea to assemble all the deprecated stuff into a kind of index. Javadoc has "Deprecated classes", "Deprecated interfaces", "Deprecated exceptions", "Deprecated fields" and "Deprecated methods"
I'' append a patch which implements this by adding support for multiple indices to the docbook stylesheets. To use it, replace <index/> in gtk-docs.sgml by something like <index> <title>Index</title> </index> <index role="deprecated"> <title>Deprecated interfaces</title> </index> <index role="2.4"> <title>New in 2.4</title> </index> gtk-doc will emit indexterms like <indexterm> <primary>a regular symbol</primary> </indexterm> <indexterm role="deprecated"> <primary>a deprecated symbol</primary> </indexterm> <indexterm role="2.4"> <primary>something new</primary> </indexterm> <indexterm role="deprecated 2.4"> <primary>Huh ?! New yet old</primary> </indexterm> and the modified autoidx.xsl of the docbook stylesheets will sort the index entries in the proper indices. I've opened a feature request at docbook.sourceforge.net to get this feature into the stylesheets, but until then, we could simply ship a modified autoidx.xsl with gtk-doc. With the modified autoidx.xsl, it would also be possible to create separate indices for functions, classes, etc (by making gtk-doc put appropriate markers in the role attributes).
Created attachment 17661 [details] [review] the gtk-doc patch
Created attachment 17662 [details] the modified autoidx.xsl
It seems to me that you want the main index to have the deprecated and (especially) new symbols as welkl. Do you output such symbols multiple times with different roles?
Yes, the main index gets all symbols. But there is only one indexterm even for symbols which should appear in multiple indices. These get multiple roles: <indexterm role="deprecated 2.4">bah</indexterm> will appear in all three indices, since the role attribute contains the strings "" (for the main index), "deprecated" for the deprecated index and 2.4 for new stuff... as you can see, by choosing "" as the role for the main index, it is guaranteed that every symbol appears in the main index.
The filtered index stuff will appear in the next version of the xsl stylesheets. I've therefore committed the gtk-doc support with a version check for new enough stylesheets.