Define a Linux manual page's TITLE text when using docbook2man?

Question

I'm experimenting with Linux manual (man) page creation using DocBook, and specifically I'm using 'docbook2man' on a Fedora 20 box, and I've been unable to figure how to create the manual's title text.

For example, if I open the man-pages(7) manual page, the manual's title is MAN-PAGES(7) and the manual's title text is Linux Programmer's Manual.

For further clarification, man-pages(7) defines the TH command as

.TH title section date source manual

It's the manual element--e.g., Linux Programmer's Manual--that I'm trying to figure out how to create using docbook2man.

I've been experimenting with the example code found in section 4.6 "Generating a man page" on the Using DocBook website. The pertinent sections of that code example are provided below (see Listing 1). The file name I'm using for this example code is foo-ref.sgml. The command line I'm using is

docbook2man foo-ref.sgml

---

Listing 1. Example SGML manual page

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

---

When I process this source code with docbook2man, a man page named 'foo.1' is generated whose .TH macro is rendered as shown below, but with an empty string "" for the manual's title text element:

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

I've dug around in the DocBook5 refentry refernece manual, trying various tags, but so far I haven't found anything that produces the title text. I've also searched the Interwebs for DocBook manual page examples, but none of the examples I've found produces the manual title text. So I'm starting to wonder if this is even doable with docbook2man?

Any suggestions?

Answer 1

After some more experimenting and without the desired results, I decided to abandon the docbook2man program and use instead the doclifter(1) and xsltproc(1) programs to create my Linux manual pages.

---

Example 1) On a Fedora 20 host, use doclifter to translate an existing man page man-pages(7) into a DocBook 'refentry' compatible XML file. This is VERY USEFUL because it renders an XML file that can can be used as a example reference for creating one's own DocBook 'refentry' XML source files.

Listing 1. doclifter example (man->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

---

Example 2) On a Fedora Linux 20 host, use xsltproc to convert an XML file ~/tmp/foo.xml containing DocBook refentry content into a Linux manual (man) page ~/tmp/foo.1.

Listing 2 below is the XML source code for example file ~/tmp/foo.xml that will be translated by xsltproc into the manual page file ~/tmp/foo.1 (see Listing 3 below). This XML source code is a derivative work from (1) the SGML example code provided in section 4.6 "Generating a man page" on the Using DocBook website, and (2) various code snippets--some modified, some copied verbatim--from the XML file created by doclifter in Example 1 above.

Listing 2. Example DocBook 'refentry' XML file ~/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>

Listing 3 below shows the xsltproc commands to use (on a Fedora 20 host) to translate the file ~/tmp/foo.xml into the manual page file ~/tmp/foo.1.

Listing 3. xsltproc example (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

Still experimenting with this whole XML->MAN conversion process. Here's another method for performing the conversion that I think I prefer to the xsltproc version shown in my previous reply.

Listing 1. XML->MAN conversion using db2x_xsltproc and 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}"