Deferred handler for linking unresolved symbols
Submitted by Daniel Macks @dmacks
Link to original bug (#646684)
Description
Spawned from Bug #644687, this is s request for an improved way to handle linking symbols that are not documented at the time the docs are built, but whose documentation becomes available later. For the given example, glib is a low-level library that has documentation referring to libraries that are higher in the dependency tree. The gnome-vfs library cannot be built until the glib library is built, so the glib references to gnome-vfs symbols are not linkable unless one later rebuilds glib after installing gnome-vfs. I envision a one-build solution, one that would especially be useful in packaging environments, with the following two components:
-
gtkdoc-fixxref would write a file that lists all symbols that could not be linked. This would be an installable html file that states that the symbols could not be documented. The doc files that would link to the documentation for such a symbol instead either link to the undocumented-symbols file or else include some embedded comment indicating that they were not resolveable.
-
A new script that user/sysadmin/Debian-postinst runs after installing a new lib that attempts to find now-available links for the previously-unlinkable items. It would essentially be gtkdoc-fixxref, but operate on the previously-installed html file of undocumented symbols and adjust the already-installed doc files rather than being at a stage prior to actual installation.
For example, when I build glib first in the parent bug-report, gnome-vfs-find-directory would point to glib/missing-items.html rather than remaining unlinked. Then after I install glib and build and install gnome-vfs, gnome-vfs-find-directory is now documentable. So I would want the new tool to read glib/missing-items.html, then search for gnome-vfs-find-directory documentation, then adjust the link for that symbol (previously pointing to missing-items.html) to point to its documentation.