GNOME Bugzilla – Bug 310494
*-sections.txt should be autogenerated / autoupdated
Last modified: 2011-03-29 12:50:20 UTC
moving from http://bugzilla.gnome.org/show_bug.cgi?id=124213 would be nice if gtk-doc could sort new documentation it lists in the unused file into the section file. First idea is to check if the symbol prefix and see if there are other sysmbols with this prefix somewhere. Second idea is to have a list of source-files associated with each section: <SECTION> <SOURCES> xyz.{c,h} </SOURCES> ... </SECTION>
I think they are auto-generated when you first run the tool ... if they don't already exist. (<foo>-decl-list.txt is basically the same thing as <foo>-sections.txt in unsorted form.) I'm skeptical about auto-updating of sections.txt ... most projects I work on *don't* have sections.txt corresponding exactly to the header files in ordering or even in division to sections, so it would be a a real pain to have gtk-doc inserting stuff into the *wrong* place; much more annyoying then having them in <foo>-unused.txt. Maybe it could be done optionally in some fashion.
Owen, projects with sane header files (GLib & co. are encumbered with historical cruft and thus do not fall into this category) can have fully autogenerated *-sections.txt because headers naturaly form sections. And in my opinion people should be encouraged to write header files that make sense, not to manually update monsters like *-sections.txt. For example in my project (Gwyddion) _everything_ is generated, except *-docs.sgml and *-overrides.txt. To rebuild documentation I just nuke everything else, including *-sections.txt, *.types and templates, rebuid from scratch and that's it (yes, it currently needs some custom auxiliary tools like a 10line python script to generate *.types). It would be nice if gtk-doc supported a less brutal approach, though.
I'm sure you can figure out how to add some sort of command line option...
Created attachment 73713 [details] [review] proposed patch Well, my last two patches just sit in the bugzilla so I'm reluctant to make more. Anyway, I recalled how much I hate Perl and here's a patch. It adds an option --rebuild-sections which makes it write *-sections.txt even if it already exists.
I've committed the patch, though it doesn't fix all of this bug so I'll leave it open.
I am closing this, as I rather would like to proceed with the idea in bug #646094 to get rid of the section file.