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

Question

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

实际生成的 URL 可以通过编辑 generate.citerefentry.link 的内容进行调整。 custom.xsl 中的模板.上面的例子只是使用了 <refentrytitle> 的值。来自 DocBook XML 并将“.html”附加到它。