docbook: Man Page Adventures in DocBook and Jade
Subject:
Man Page Adventures in DocBook and Jade
From:
"Dennis Grace" ####@####.####
Date:
21 Jun 2001 15:48:42 -0000
Message-Id: <OF321BFE6C.6CDF3A1B-ON85256A71.005F94D4@raleigh.ibm.com>
Greetings Linux DocuPeople,
I have a question for anyone who has any expertise in DocBook, Jade, and
man page production. Please forgive my lengthy introduction, but I think
it necessary to explain where my problems lie.
My task appeared fairly straightforward: I had to produce a man page for
the Event Logging command evlview, the synopsis for which was supposed to
look like this:
evlview [(1)source (defaults to /var/evlog/event_log)]
[(2)destination (defaults to stdout)] [-filter filter] | -help
(1) -new [-timeout nsec] | [-log srclogfile] [-tail nrec] [-reverse]
(2) -out destlogfile | [-spec formatstr] [-specf formatfile] [-compact] [
-separator sep]
After consulting the O'Reilly DocBook (Walsh and Muellner), I was fairly
certain I could get
that result using the following code inside a <refentry>:
<refsynopsisdiv>
<cmdsynopsis>
<command>evlview</command>
<group choice="plain">
<arg>
<group>
<synopfragmentref linkend="source">source (defaults to
/var/evlog/event_log)</synopfragmentref>
</group>
<group>
<synopfragmentref linkend="destination">destination
(defaults to stdout)</synopfragmentref>
</group>
<arg choice="opt">-filter
<replaceable>filter</replaceable></arg>
</arg>
<arg choice="plain">-help>/arg>
</group>
<synopfragment id="source">
<group choice="plain">
<arg choice="plain">
<arg choice="plain">-new</arg>
<arg choice="opt">-timeout
<replaceable>nsec</replaceable>
</arg>
</arg>
<arg choice="plain">
<arg choice="opt">-log
<replaceable>srclogfile</replaceable>
</arg>
<arg choice="opt">-tail
<replaceable>nrec</replaceable></arg>
<arg choice="opt">-reverse</arg>
</arg>
</group>
</synopfragment>
<synopfragment id="destination">
<group choice="plain">
<arg choice="plain">
<arg choice="plain">-out
<replaceable>destlogfile</replaceable>
</arg>
</arg>
<arg choice="plain">
<arg choice="opt">
-spec<replaceable>formatstr</replaceable>
</arg>
<arg choice="opt">-specf
<replaceable>formatfile</replaceable>
</arg>
<arg choice="opt">-compact</arg>
<arg choice="opt">-separator
<replaceable>sep</replaceable>
</arg>
</arg>
</group>
</synopfragment>
</cmdsynopsis>
</refsynopsisdiv>
When I ran the Jade command docbook2html on this DocBook file, I got
exactly what I expected. When I ran docbook2man, however, I got this
garbled synopsis:
evlview [ [ source (defaults to
/var/evlog/event_log)]
[ destination (defaults to stdout)]
[-filter filter] ] -help
-new
[ -timeout nsec]
[-log srclogfile]
[ -tail nrec]
[ -reverse]
-out destlogfile
[ -spec formatstr]
[ -specf formatfile]
[ -compact]
[ -serarator sep]
In addition to being damned difficult to read, this grouping is incorrect.
Not only does it not indicate that source and destination are groups, this
man page output does not clearly identify which lines correspond to source
and which to destination. Moreover, the square brackets separating the
other options from -help misidentify those options as an optional grouping
(the relationship of the group to -help is exclusive).
I considered altering the parser scripts to produce the desired results,
but the actual conversion script at the heart of docbook2man is perl,
and I don't know perl. Ultimately, in order to meet deadlines, I decided
to
modify the troff file directly, changing it from:
\fBevlview\fR \fB [ [ source (defaults
to /var/evlog/event_log)]
[ destination (defaults to stdout)]
[ -filter
\fIfilter\fB]
] -help
\fR \fB -new
[ -timeout
\fInsec\fB]
[ -log \fIsrclogfile\fB]
[ -tail \fInrec\fB]
[ -reverse]
\fR
\fB -out \fIdestlogfile\fB
[ -spec \fIformatstr\fB]
[
-specf \fIformatfile\fB]
[ -compact]
[ -separator
\fIsep\fB]
\fR
to:
\fBevlview\fR \fB [\fR(1) \fBsource \fR(defaults to
\fI/var/evlog/event_log\fR)\fB]
[\fR(2) \fBdestination \fR(defaults to \fIstdout\fR)\fB] [ -filter
\fIfilter\fB] | -help
\fR (1)\fB-new [ -timeout \fInsec\fB] | [ -log \fIsrclogfile\fB] [ -tail
\fInrec\fB] [ -reverse]
\fR (2)\fB-out \fIdestlogfile\fB | [ -spec \fIformatstr\fB] [ -specf
\fIformatfile\fB]
[ -compact] [ -separator \fIsep\fB] \fR
So here are my questions: am I missing something? Am I making this harder
than it has to be? Is there a better parser than docbook2man available
for producing man pages from DocBook? Does Jade/DocBook require a special
annotation in the sgml in order to enable the <group> functions and
produce
a man page consistent with the html and ps outputs?
Thanks.
Dennis Grace
IBM Information Developer
(512) 838-4977 T/L 678-4977 cell: (512)-296-7830
####@####.####
Is there another word for 'synonym'?
