GNOME Bugzilla – Bug 432991
developer docs for libpango are broken
Last modified: 2007-04-30 22:12:34 UTC
Documentation Section: API-reference of pango - open devhelp - hit Ctrl-s to get to the search-entry widget - enter pango_layout_set_justify - on the right side of the devhelp-window for the pango_layout_set_justify() prototype hit the link for the gboolean type. - be surprised by this error-message: "Firefox can't find the file at /home/behdad/.local/share/gtk-doc/html/glib/glib-Basic-Types.html#gboolean." Correct version: Opon hitting the link to the type gboolean devhelp should open /usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gboolean. Other information: The installed version of pango is: - libpango1.0-doc is 1.16.2-0ubuntu1 I ran into this on Ubuntu 7.04 and filed it also with LaunchPad here: - https://bugs.launchpad.net/ubuntu/+source/pango1.0/+bug/109641
2007-04-27 Behdad Esfahbod <behdad@gnome.org> * configure.in: Add --disable-doc-cross-references. * docs/Makefile.am: Make sure --disable-doc-cross-references is set in order to make dist. * Makefile.am: Add --disable-doc-cross-references to DISTCHECK_CONFIGURE_FLAGS. Releasing 1.16.4 soon that fixes this issue.
Are you sure this is a good idea? The neutral form of cross-linking is to the on-line documentation. It is annoying when you cannot get from Gtk+ docs to Pango docs, from Pango to GLib, etc. But removal of the cross-links hardly helps you to get there. If I create neutral links I do the exact opposite: build the documentation with all cross references and then postprocess the documentation with something like: my $gtkwww = 'http://developer.gnome.org/doc/API/2.0'; my $gtkglextwww = 'http://gtkglext.sourceforge.net/reference'; my $cairowww = 'http://www.cairographics.org/manual'; my %docmap = ( 'atk' => $gtkwww . '/atk', 'cairo' => $cairowww, 'gdk' => $gtkwww . '/gdk', 'gdk-pixbuf' => $gtkwww . '/gdk-pixbuf', 'glib' => $gtkwww . '/glib', 'gobject' => $gtkwww . '/gobject', 'gtk' => $gtkwww . '/gtk', 'gtkglext' => $gtkglextwww . '/gtkglext', 'pango' => $gtkwww . '/pango', ); my %unknowndoc; s#(<a\s+href=")/.*?/([^"/]+)(/[^"/]+")# if (defined $docmap{$2}) { $1.$docmap{$2}.$3 } else { $unknowndoc{$2} = 1; $1.$gtkwww.$2.'/'.$3 } #sge; if (%unknowndoc) { my $x; for $x (keys %unknowndoc) { warn "$x documentation location is unknown." } }
(In reply to comment #2) > Are you sure this is a good idea? The neutral form of cross-linking is to the > on-line documentation. > > It is annoying when you cannot get from Gtk+ docs to Pango docs, from Pango to > GLib, etc. But removal of the cross-links hardly helps you to get there. > > If I create neutral links I do the exact opposite: build the documentation with > all cross references and then postprocess the documentation with something > like: > > my $gtkwww = 'http://developer.gnome.org/doc/API/2.0'; > my $gtkglextwww = 'http://gtkglext.sourceforge.net/reference'; > my $cairowww = 'http://www.cairographics.org/manual'; > my %docmap = ( > 'atk' => $gtkwww . '/atk', > 'cairo' => $cairowww, > 'gdk' => $gtkwww . '/gdk', > 'gdk-pixbuf' => $gtkwww . '/gdk-pixbuf', > 'glib' => $gtkwww . '/glib', > 'gobject' => $gtkwww . '/gobject', > 'gtk' => $gtkwww . '/gtk', > 'gtkglext' => $gtkglextwww . '/gtkglext', > 'pango' => $gtkwww . '/pango', > ); > my %unknowndoc; > s#(<a\s+href=")/.*?/([^"/]+)(/[^"/]+")# > if (defined $docmap{$2}) { $1.$docmap{$2}.$3 } > else { $unknowndoc{$2} = 1; $1.$gtkwww.$2.'/'.$3 } > #sge; > if (%unknowndoc) { > my $x; > for $x (keys %unknowndoc) { warn "$x documentation location is unknown." } > } This is a fine suggestion. I try to implement it, so cloned this bug as bug 434720. But what I committed was fixing what I broke before, and is still valid.