Question

我正在尝试使用DocBook创建Linux手册（man）页面，特别是我在Fedora 20盒子上使用'docbook2man'，我一直无法想出如何创建手册的标题文本。< / p>

例如，如果我打开手册页（7）手册页，则手册的标题为MAN-PAGES(7)，手册的标题文字为Linux Programmer's Manual。

为进一步说明，man-pages（7）将 TH 命令定义为

.TH title section date source manual

这是manual元素 - 例如，Linux Programmer's Manual - 我正试图弄清楚如何使用docbook2man创建。

我一直在试验Using DocBook网站上第4.6节“生成手册页”中的示例代码。下面提供了该代码示例的相关部分（参见清单1）。我在这个示例代码中使用的文件名是foo-ref.sgml。我正在使用的命令行是

docbook2man foo-ref.sgml

清单1.示例SGML手册页

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<refentry>

<refentryinfo>
    <date>2001-01-01</date>
</refentryinfo>

<refmeta>
    <refentrytitle>
        <application>foo</application>
    </refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>foo 1.0</refmiscinfo>
</refmeta>

<refnamediv>
    <refname>
        <application>foo</application>
    </refname>
    <refpurpose>
    Does nothing useful.
    </refpurpose>
</refnamediv>

<refsynopsisdiv>
    <refsynopsisdivinfo>
        <date>2001-01-01</date>
    </refsynopsisdivinfo>
    <cmdsynopsis>
    <command>foo</command>
<arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
<arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
<arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
    </cmdsynopsis>
</refsynopsisdiv>

<refsect1>
    <refsect1info>
        <date>2001-01-01</date>
    </refsect1info>
    <title>DESCRIPTION</title>
    <para>
    <command>foo</command> does nothing useful.
    </para>
</refsect1>
<!-- etc. -->
</refentry>

当我使用docbook2man处理此源代码时，会生成一个名为“foo.1”的手册页，其.TH宏呈现如下所示，但手册的标题文本元素为空""字符串：

.TH "FOO" "1" "2001-01-01" "foo 1.0" ""

我在DocBook5 refentry refernece手册中进行了挖掘，尝试了各种标签，但到目前为止，我还没有发现任何产生标题文本的内容。我还搜索了Interwebs for DocBook手册页示例，但我找到的所有示例都没有生成手册标题文本。所以我开始怀疑这对docbook2man来说是否可行？

有什么建议吗？

Answer 1

经过一些实验并且没有达到预期效果后，我决定放弃docbook2man程序，而是使用doclifter(1)和xsltproc(1)程序来创建我的Linux手册页。

示例1）在Fedora 20主机上，使用doclifter将现有手册页man-pages(7)翻译成DocBook＆quot; refentry＆＃39;兼容的XML文件。这非常有用，因为它呈现的XML文件可以用作创建自己的DocBook＆quot; refentry＆＃39;的示例参考。 XML源文件。

清单1. doclifter示例（man-＆gt; XML）

# Install the doclifter package
sudo yum -y install doclifter
# Create a temporary directory in which to experiment, and go to it
mkdir ~/tmp
cd ~/tmp/
# Copy the existing man-pages.7.gz file into the temporary directory
# and uncompress it.
cp /usr/share/man/man7/man-pages.7.gz ~/tmp/
gunzip man-pages.7.gz
# Convert the man page into DocBook XML format
doclifter man-pages.7
# There should now be a file named 'man-pages.7.xml'.
ls man-pages.7.xml

示例2）在Fedora Linux 20主机上，使用xsltproc将包含DocBook refentry内容的XML文件~/tmp/foo.xml转换为Linux手册（man）页面~/tmp/foo.1。

下面的清单2是示例文件~/tmp/foo.xml的XML源代码，它将由xsltproc翻译到手册页文件~/tmp/foo.1中（参见下面的清单3）。此XML源代码是（1）第4.6节＆＃34;生成手册页＆＃34;中提供的SGML示例代码的衍生作品。在Using DocBook网站上，以及（2）各种代码片段 - 一些经过修改，一些是逐字复制的 - 来自上文示例1中由doclifter创建的XML文件。

清单2.示例DocBook＆＃39; refentry＆＃39; XML文件~/tmp/foo.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<refentry id='foo'>

<!-- HEADER & FOOTER INFO -->
<refmeta>
    <!-- see also: man 7 man-pages -->
    <!-- .TH title section date source manual -->
        <!-- title -->
    <refentrytitle>FOO</refentrytitle>
        <!-- section -->
    <manvolnum>1</manvolnum>
        <!-- date -->
    <refmiscinfo class='date'>2015-06-26</refmiscinfo>
        <!-- source -->
    <refmiscinfo class='source'>SOURCE TEXT</refmiscinfo>
        <!-- manual -->
    <refmiscinfo class='manual'>MANUAL TEXT</refmiscinfo>
</refmeta>

<!-- Section: NAME -->
<refnamediv>
    <refname>foo</refname>
    <refpurpose>
    Does nothing useful.
    </refpurpose>
</refnamediv>

<!-- Section: SYNOPSYS -->
<refsynopsisdiv id='synopsis'>
    <cmdsynopsis>
        <command>foo</command>
        <arg><option>-f </option><replaceable class="parameter">bar</replaceable></arg>
        <arg><option>-d<replaceable class="parameter">n</replaceable></option></arg>
        <arg rep="repeat"><replaceable class="parameter">file</replaceable></arg>
    </cmdsynopsis>
</refsynopsisdiv>

<!-- Section: DESCRIPTION | OPTIONS | ... -->
<refsect1 id='description'><title>DESCRIPTION</title>
    <para>
    <command>foo</command> does nothing useful.
    </para>
</refsect1>

<refsect1 id='authors'><title>AUTHORS</title>
    <para>Jim Fischer</para>
</refsect1>

</refentry>

下面的清单3显示了使用xsltproc命令（在Fedora 20主机上）将文件~/tmp/foo.xml转换为手册页文件~/tmp/foo.1。

清单3. xsltproc示例（foo.xml - ＆gt; foo.1）

# Change to the temporary directory
cd ~/tmp/
# Use xsltproc to convert foo.xml into foo.1
$ xsltproc /usr/share/sgml/docbook/xsl-stylesheets-1.78.1/manpages/docbook.xsl foo.xml 
# Verify foo.1 was created 
ls foo.1
man ./foo.1

Answer 2

仍在尝试整个XML-＆gt; MAN转换过程。这是执行转换的另一种方法，我认为我更喜欢上一次回复中显示的xsltproc版本。

清单1.使用db2x_xsltproc和db2x_manxml

进行XML-＆gt; MAN转换

#!/bin/bash
# vim: ft=sh:tw=75:ts=4:sw=4

clear

MANDIR=${HOME}/tmp/

MANUAL=foo
SECTION=1
MAN_FILE="${MANUAL}.${SECTION}"
XML_FILE="${MANUAL}.xml"

cd "${MANDIR}"

# [Optional] Sanity check to ensure the man page build actually occurs.
rm -f "${MAN_FILE}"

# XML -> MAN
# n.b. The option '--to-stdout' allows full control over the 
# man page's file name. Otherwise, the man page's file name is 
# defined implicitly via the refentry.refmeta.refentrytitle 
# value in the XML source file. Note that (1) the refentrytitle
# value corresponds to ".TH title" and should be written in
# all-caps--e.g., 'FOO'--in accordance with man-pages(7), and 
# (2) one typically does not want the man page's file name to
# be all-caps (preferred file name is 'foo.1' and not 'FOO.1').
#
db2x_xsltproc -s man "${XML_FILE}" | db2x_manxml --to-stdout > "${MAN_FILE}"

exit_code=("${PIPESTATUS[@]}")
if [ ${exit_code[0]} -ne 0 ]; then
    echo ":: ERROR :: db2x_xlstproc returned exit code ${exit_code[0]}; aborting..." >&2
    exit "${exit_code[0]}"
elif [ ${exit_code[1]} -ne 0 ]; then
    echo ":: ERROR :: db2x_manxml returned exit code ${exit_code[1]}; aborting..." >&2
    exit "${exit_code[1]}"
fi

# Display the man file
man ./"${MAN_FILE}"

使用docbook2man时定义Linux手册页的TITLE文本？

2 个答案: