GNOME Bugzilla – Bug 310542
Improve the gtk-doc devhelp format
Last modified: 2006-08-18 19:36:37 UTC
it would be nice to mark deprecated API symbols in the search list on the left. Idea #1 is to make them gray. Idea two is a filter option to show/hide them. The big question is wheter this information (deprecated or not) is available from the index files you use. A quick glance told me it is not. Any ideas of what it needs to put this in there. (Thinking forward some people might would like to filter on since-tags too).
Yes, this is planned together with a bunch of other improvements to the .devhelp file format. Problem is that it's quite complicated to add this to gtk-doc and we simply had not had the time to look into it closely enough to see exactly where in the gtk-doc process it should be inserted. Other planned improvements are better information about what a certain symbol represents (function, enum, macro etc) so that those can be displayed better. You can read more about those planned improvements on: http://developer.imendio.com/wiki/Scratchpad/Devhelp/Format
Cool, as I hack on gtk-doc a little I'll see if I can help you with finding out how to get the information into the .devhelp file and leve using it to you. Sounds this like a plan for you?
That sounds like a great plan, we cooked up how such an improved fileformat could look in the example file: http://developer.imendio.com/svn/devhelp/trunk/data/gtk.devhelp
is the suggestion in http://mail.gnome.org/archives/gtk-doc-list/2005-August/msg00006.html okay with you? Any ideas about handling up/downwards compatibillity. Should we just continue to produce the old <function> tags by default and devhelp merges information (not producing two entries for one symbol). Gtkdoc could check for the devhelp version at installation time and if there is a devhelp recent enough, it could turn of the generation of the old tags.
It looks very good to me. About keeping the <function> tag, I guess it's best to keep it for older versions of devhelp, at least for now.
I did some experiments with xslt. I am now able to process xml like <symbol role="macro" condition="since:2.2|deprecated|stability:stable"> and produce from that <macro since="2.2" deprecated="" stability="stable"> Means boolean attributes result in empty strings. You need to ensure that devhelp ignore unknow attributes (to keep this extensible). If this is okay, i'll start doing the changes in gtk-doc.
Yeah, that should work out nicely, I think.
Devhelp now supports the old and new formats, but still does not take advantage of the added information.
Implemented the suggestion for deprecated keywords as suggested.