Re: [docbook-apps] Extending ulink

[Warren Young <warren@etr-usa.com>]

David Nedrow wrote:
> <ulink type="apiref" url="foo"/>

Okay, that takes care of the syntax.  So how to do the grunt work?

...Several hours of reading and coding later:

<!-- Special ulink types, to reduce boilerplate link code -->
<xsl:template match="ulink" name="refman_ulink">
   <xsl:choose>
     <!-- type=mysqlapi: makes hyperlinks to MySQL C API reference
          manual, given only the function name with dashes instead of
          underscores as the URL. -->
     <xsl:when test="@type = 'mysqlapi'">
       <tt>
         <a>
           <xsl:variable name="fn_dash" select="@url"/>
           <xsl:variable name="fn_name"
             select="translate($fn_dash, '-', '_')"/>
           <xsl:attribute name="href">
             <xsl:text>http://dev.mysql.com/doc/mysql/en/</xsl:text>
             <xsl:value-of select="$fn_dash"/>
             <xsl:text>.html</xsl:text>
           </xsl:attribute>
           <xsl:value-of select="$fn_name"/>
           <xsl:text>()</xsl:text>
         </a>
       </tt>
     </xsl:when>

     <xsl:otherwise>
       <xsl:call-template name="ulink"/>
     </xsl:otherwise>
   </xsl:choose>
</xsl:template>


This goes in your HTML XSL customization layer file.

Cool things about this template: I was able to get it to do the dashes-
to-underscores translation thing.  Yippee.

Not-so-cool things: it hard-codes a few things where it should be 
possible to leverage existing DocBook stylesheet mechanisms.  The main 
one is that a lot of the code could be obviated if I could figure out 
how to call the standard <function> template handler with the right 
parameters.  It handles the type face change, and the optional parens. 
Any ideas how I can do this?



P.S. With that done, I then went and defined some more ulink types, to 
shorten links to my own library's reference manual.  It is generated by 
Doxygen, so the URLs follow simple patterns that made it an ideal task 
for an XSL template.  (The DocBook document is the library's user 
manual, for what that's worth.)  Just add this 'when' clause above the 
'otherwise' clause above:

     <!-- type=classref: makes hyperlinks to a class in the MySQL++
          reference manual, given its name. -->
     <xsl:when test="@type = 'classref'">
       <tt>
         <a>
           <xsl:attribute name="href">
             <xsl:text>../../refman/html/classmysqlpp_1_1</xsl:text>
             <xsl:value-of select="@url"/>
             <xsl:text>.html</xsl:text>
           </xsl:attribute>
           <xsl:choose>
             <xsl:when test="count(child::node())=0">
               <xsl:value-of select="@url"/>
             </xsl:when>
             <xsl:otherwise>
               <xsl:apply-templates/>
             </xsl:otherwise>
           </xsl:choose>
         </a>
       </tt>
     </xsl:when>

There's also one for 'struct', which is only trivially different.  The 
practical upshot is that this:

	<ulink url="../../refman/html/classmysqlpp_1_1FooClass">FooClass</ulink>

becomes:

	<ulink type="classref" url="FooClass"/>

Nice and short, just like I wanted!


P.P.S. Up to now, I viewed DocBook as a "better HTML" that gave me the 
option of easy PDF generation; and also, as an alternative to LaTeX, 
which gave prettier output than latextohtml.  With this kind of power in 
the customization layer, it got kicked up to a whole new level.  This 
ROCKS.  Thanks to all the giants whose shoulders I am standing upon!