Dangling links in gtk-doc output

[Matthias Clasen <maclas gmx de>]

gtk-doc produces quite a few dangling intra-document links, since it
emits <link linkend="$symbol"> for links to an object struct named
$symbol, but <anchor id="$symbol-struct"/> for the object documentation.
The reasoning is that <refentry id="$symbol"> is used for the refentry
containtaing the object, and the links are supposed to point to the top 
of the refentry. But this is only true, if the <TITLE> line in the
sections.txt file has not been changed from the default
<TITLE>$symbol</TITLE> initially produced by gtk-doc. The gdk and gtk
docs contain quite a few sections, where the titles have been changed,
e.g.: GdkPixmap, GdkDrawable, GdkGC, GdkWindow and GdkKeymap  in gdk. 

Yesterday I committed a workaround for this problem to gdk, which
consists of manually adding <anchor id="GdkPixmap"/>, etc in the
templates. 

It would of course be much nicer if gtk-doc could get this right on its
own. Here is a patch which adds the missing anchors as early as possible
in the refentry. Ok to commit ?

Matthias 


Index: gtkdoc-mkdb.in
===================================================================
RCS file: /cvs/gnome/gtk-doc/gtkdoc-mkdb.in,v
retrieving revision 1.68
diff -u -b -B -p -r1.68 gtkdoc-mkdb.in
--- gtkdoc-mkdb.in	8 Dec 2002 22:50:24 -0000	1.68
+++ gtkdoc-mkdb.in	11 Dec 2002 22:47:08 -0000
@@ -319,6 +319,7 @@ sub OutputSGML {
     my $hierarchy = "";
     my $interfaces = "";
     my $prerequisites = "";
+    my @file_objects = ();
 
     while (<INPUT>) {
 	if (m/^#/) {
@@ -329,6 +330,7 @@ sub OutputSGML {
 	    $details = "";
 	    $num_symbols = 0;
 	    $in_section = 1;
+	    @file_objects = ();
 
 	} elsif (m/^<SUBSECTION\s*(.*)>/i) {
 	    $synopsis .= "\n";
@@ -474,7 +476,7 @@ EOF
 						    \$signals_synop, \$signals_desc,
 						    \$args_synop, \$args_desc,
 						    \$hierarchy, \$interfaces,
-						    \$prerequisites);
+						    \$prerequisites, \ file_objects);
 		if ($file_changed) {
 		    $changed = 1;
 		}
@@ -504,6 +506,9 @@ EOF
 		# We don't want standard macros/functions of GtkObjects,
 		# or private declarations.
 		if ($subsection ne "Standard" && $subsection ne "Private") {
+		    if (&CheckIsObject ($symbol)) {
+			push @file_objects, $symbol;
+		    }
 		    my ($synop, $desc) = &OutputDeclaration ($symbol,
 							     $declaration);
 		    my ($sig_synop, $sig_desc) = &GetSignals ($symbol);
@@ -1179,10 +1184,11 @@ EOF
 #               $hierarchy - reference to the DocBook for the Object Hierarchy part
 #               $interfaces - reference to the DocBook for the Interfaces part
 #               $prerequisites - reference to the DocBook for the Prerequisites part
+#               $file_objects - reference to an array of objects in this file
 #############################################################################
 
 sub OutputSGMLFile {
-    my ($file, $title, $section_id, $includes, $synopsis, $details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $prerequisites) = @_;
+    my ($file, $title, $section_id, $includes, $synopsis, $details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $prerequisites, $file_objects) = @_;
 
     # The edited title overrides the one from the sections file.
     my $new_title = $SymbolDocs{"$TMPL_DIR/$file:Title"};
@@ -1233,6 +1239,14 @@ sub OutputSGMLFile {
     open (OUTPUT, ">$new_sgml_file")
 	|| die "Can't create $new_sgml_file";
 
+    my $object_anchors = "";
+    foreach my $object (@$file_objects) {
+	next if ($object eq $section_id);
+	my $id = CreateValidSGMLID($object);
+#	print "Debug: Adding anchor for $object\n";
+	$object_anchors .= "<anchor id=\"$id\"$empty_element_end";
+    }
+
     # Note: The refname and refpurpose are on the same line to stop
     # docbook-to-man 1.08 putting them on separate lines.
     #
@@ -1247,7 +1261,7 @@ sub OutputSGMLFile {
     print OUTPUT <<EOF;
 <refentry id="$section_id">
 <refmeta>
-<refentrytitle>$title</refentrytitle>
+<refentrytitle>$object_anchors$title</refentrytitle>
 <manvolnum>3</manvolnum>
 <refmiscinfo>\U$MODULE\E Library</refmiscinfo>
 </refmeta>