html - DocBook:如何链接到另一个手册页？

Question

我正在 DocBook 中编写几个手册页。我还想将它们转换为 HTML 以在网络上显示。如何插入从一个手册页到另一个手册页的链接，使其在 man 中显示为 target(1)，但在网络上显示为指向另一个手册的超链接页面，它也已转换为同一目录中的单独 HTML 文件？

Answer 1

我想我已经明白了这一点。您应该使用 <citerefentry/>在文档中，它按预期出现在手册页中。除非您提供生成目标 URL 的方法(在自定义层中执行此操作)，否则它不会在 HTML 文档中形成超链接。

以下是手册页中“另请参阅”部分的示例文档片段:

<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>

加上这个自定义模板(另存为 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>

使用xmlto处理 DocBook XML 的程序，指定 HTML 的定制层:

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

在联机帮助页中，这会产生:

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

在 HTML 中，它会生成以下内容:(为了清楚起见，所有 <span> 元素已被删除)

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

可以通过编辑 generate.citerefentry.link 的内容来调整实际生成的 URL。模板位于 custom.xsl 。上面的示例仅使用 <refentrytitle> 的值来自 DocBook XML 并向其附加“.html”。