Am 01.03.2010 19:19, schrieb Shaun McCance: > On Mon, 2010-03-01 at 14:31 +0000, Philip Withnall wrote: >> On Sun, 2010-02-28 at 21:05 -0600, Shaun McCance wrote: >>> Comments, suggestions, and flames are absolutely welcome. Our >>> community is what makes us who we are. >> >> I don't think I'll have time to work on any of this (sorry), but I had a >> few thoughts when reading through your plan: >> >> How does the rearrangement/splitting up of reference pages tie in with >> Devhelp? The new hierarchy seems to be a lot more non-linear, with links >> going between tree branches, and I can foresee a little awkwardness >> trying to fit that into Devhelp's current navigation model (i.e. >> entirely tree-based). At the very least, Devhelp's tab support will have >> to be improved for this to be usable. > > Good question. My initial focus is on library.gnome.org. It's not > that I don't think Devhelp is important. It absolutely is. But I > don't want to get bogged down on too many fronts.
It might be easier to do some changes closer to the source. I can check the feasibiloty from gtk-doc side. > > So I'd like to get the changes on library with post-processing tools, > involving little to no changes to gtk-doc and other API documentation > tools. Our experiences in doing this will help us better understand > how gtk-doc could be changed. Since Devhelp works with generated HTML, > there's not much it can do without gtk-doc changes. > > One thing I've been working on is splitting Yelp's transformation and > display engine into a separate library, libyelp. We could use libyelp > in Devhelp to display the intros, howtos, and guides, so that Devhelp > becomes a very complete developer documentation viewer. Any I was thinking about (optionally) generating omf files in gtk-doc and allowing to install the plain docbook documents as well (so that they show up in yelp). > >> I like the idea of hiding the documentation for getters/setters with the >> documentation for their respective properties, but what should be done >> about getters/setters which affect more than one property, or properties >> which are affected by more than one getter/setter? (e.g. An object has X >> and Y coordinate properties, but it makes sense for it to only have >> get_coordinate_pair() and set_coordinate_pair() functions.) > > In this case, I would leave the function in the functions synopsis, > and not hide it behind the property. A lot of functions are just > convenience APIs for dealing with multiple properties. For example, > gtk_label_set_markup basically just sets "text" and "use-markup". > > I'm not even sure how well we can match properties to accessors > programmatically. I also did an HTML mockup of GtkLabel, with > more content than in my image mockup, and I didn't hide > gtk_label_get_line_wrap and gtk_label_get_line_wrap_mode behind > the "wrap" and "line-wrap" properties. They don't match this > productions: > > label + "_get_" + tr(property, "-", "_") > > So I don't know if we could even catch them. There may just be > some quirks. That's OK. A 90% solution is better than nothing. In the long-run we could use a new section for accessor methods in gtk-docs <lib>-section.txt file. Stefan _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
