DocBook: How to link to another man page?

Question

I am writing a couple of man pages in DocBook. I would also like to convert them to HTML for display on the web. How can I insert a link from one man page to another, such that it appears in man as target(1) but appears on the web as a hyperlink to the other man page, which has also been converted to a separate HTML file in the same directory?

Answer 1

I think I have figured this out. You should use a <citerefentry/> in the document, which appears as expected in a man page. It isn't hyperlinked in a HTML document unless you provide a method for generating the target URL, which you do in a customisation layer.

Here is an example document snippet for the "See Also" section in a man page:

<refsect1 id="seealso">
    <title>See Also</title>
    <simplelist type="inline">
        <member><citerefentry><refentrytitle>grep</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
        <member><citerefentry><refentrytitle>awk</refentrytitle><manvolnum>1P</manvolnum></citerefentry></member>
    </simplelist>
</refsect1>

Coupled with this customisation template (saved as custom.xsl)

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

    <!-- Ignore spaces between elements (without this, the URL is "grep    .html" -->
    <xsl:strip-space elements="*"/>

    <!-- Turn citerefentry elements into HTML links -->
    <xsl:param name="citerefentry.link" select="1"/>

    <!-- Code to generate the URL for a given citerefentry element -->
    <xsl:template name="generate.citerefentry.link">
        <xsl:value-of select="refentrytitle"/>
        <xsl:text>.html</xsl:text>
    </xsl:template>
</xsl:stylesheet>

Using the xmlto program to process the DocBook XML, specifying the customisation layer for HTML:

$ xmlto man input.xml
$ xmlto html-nochunks -m custom.xsl input.xml

In a manpage, this produces:

SEE ALSO
       grep(1), awk(1P)

And in HTML it produces this: (all the <span> elements have been removed for clarity)

<h2>See Also</h2>
<a href="grep.html">grep(1)</a>, <a href="awk.html">awk(1)</a>

The actual URLs generated can be adjusted by editing the content of the generate.citerefentry.link template in custom.xsl. The example above just uses the value of the <refentrytitle> from the DocBook XML and appends ".html" to it.