使用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轉換