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

Question

我使用的DocBook在Linux手册（man）页面创建的实验，具体我使用“docbook2man”关于在Fedora 20中，我一直无法弄清楚如何创建手册的标题文字。

例如，如果我打开该男子的页面（7）手册，手册的标题是MAN-PAGES(7)和手动的标题文本是Linux Programmer's Manual。

为了进一步澄清，人的页面（7）定义TH命令

.TH title section date source manual 

这是manual元素 - 例如，Linux Programmer's Manual凹口 - 我试图找出如何创建使用docbook2man。

我一直在尝试与部分4.6 Using DocBook网站上的“生成手册页”找到示例代码。该代码示例的相关部分在下面提供（参见清单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 'REFENTRY' 兼容的XML文件。这非常有用，因为它呈现的XML文件可以用作创建自己的DocBook'refentry'XML源文件的示例参考。

清单1。doclifter例子（人为> 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是将由xsltproc翻译成手册页面文件~/tmp/foo.1例如文件~/tmp/foo.xml XML源代码（见下文清单3）。此XML源代码，是由（1）在第4.6节中提供的Using DocBook网站上“生成手册页”的SGML示例代码衍生作品，和（2）各种代码片段 - 一些修改，一些逐字拷贝 - 从XML文件通过doclifter上述实施例1中创建的。

下面清单2。实施例的DocBook 'REFENTRY' 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 - > 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-> MAN转换过程仍然试验。下面是执行，我想我宁愿在我以前的答复所示xsltproc版的转换的另一种方法。

清单1. XML->使用db2x_xsltproc和db2x_manxml

#!/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}" 

MAN转换