Allowing docbook markup in inline docs (2)

["Matthias Clasen" <matthiasc poet de>]

Here is another patch, this time against the CVS version of gtk-doc. The
purpose
of this patch is to reduce the need for docbook markup in inline docs by
making
the foo() and #foo shortrefs work as expected for functions and types which
can not be linked to.

Faced with the following example text:

The function isdigit() takes an #int argument,

gtk-doc would previously expand the abbreviations to

 The function <link linkend="isdigit">isdigit</link>() takes an <link
linkend="int">int</link> argument.

which would become

The function <GTKDOCLINK HREF="isdigit">isdigit</GTKDOCLINK>() takes an
<GTKDOCLINK HREF="int">int</GTKDOCLINK> argument.

and finally be reduced to

The function isdigit() takes an int argument.

by the fixxref step. My patch modifies gtk-doc so that the initial expansion
of the abbreviations comes out as:

The function <function><link linkend="isdigit">isdigit</link>()</function>
takes an <type><link linkend="int">int</link></type> argument.

This allows the stylesheets to insert proper markup for functions/types
which stays in place when the link stuff is
finally stripped out again. Making this work requires a small addition to
the dtd, since links are not normally allowed
inside types, but we ship a modified dtd anyway.

 A slightly ugly aspect of this patch is that the expansion of the ()
abbreviation
is done regardless of surrounding markup, so stuff in templates like
<function>strlen()</function> will be expanded
to <function><function><link
linkend="strlen">strlen</link>()</function></function>, but this seems to be
valid
docbook and is formatted just fine.

Even with this patch in place, I would still like to use explicit docbook
markup for emphasis, filenames, envvars, etc
in inline comments.

Matthias

PS I would really appreciate if someone with the necessary privileges could
create a gtk-doc bugzilla category, so
that I can stick my patches there.

--- gtkdoc-mkdb.in.orig Thu Sep 27 01:01:31 2001
+++ gtkdoc-mkdb.in Thu Sep 27 01:05:23 2001
@@ -1233,7 +1233,7 @@
     my ($text) = @_;

     # Convert 'function()' or 'macro()'
-    $text =~ s/(\w+)\s*\(\)/&MakeXRef($1) . "()";/eg;
+    $text =~ s/(\w+)\s*\(\)/&_tagify(&MakeXRef($1) . "()", "function");/eg;

     # Convert '@param'
     $text =~ s/\@(\w+)/<parameter>$1<\/parameter>/g;
@@ -1242,11 +1242,15 @@
     $text =~ s/\%(-?\w+)/<literal>$1<\/literal>/g;

     # Convert '#symbol'
-    $text =~ s/#([\w-]+)/&MakeXRef($1);/eg;
+    $text =~ s/#([\w-]+)/&_tagify(&MakeXRef($1), "type");/eg;

     return $text;
 }

+sub _tagify {
+   my ($text, $elem) = @_;
+   return "<" . $elem . ">" . $text . "</" . $elem . ">";
+}


############################################################################
#
 # Function    : MakeXRef
--- gtk-doc.dtd.orig Thu Sep 27 00:59:20 2001
+++ gtk-doc.dtd Thu Sep 27 01:01:10 2001
@@ -1,8 +1,10 @@
 <!-- Add an href attribute to the ANCHOR element -->

-<!ENTITY % local.anchor.attrib
-"HRef      CDATA      #IMPLIED">
+<!ENTITY % local.anchor.attrib "HRef      CDATA      #IMPLIED">

+<!-- Allow LINK elements in TYPE elements -->
+
+<!ENTITY % local.smallcptr.char.mix "|Link">
 <!--
...................................................................... -->
  <!-- Original DTD
......................................................... -->