DOCBOOK-APPS: Man Page Adventures in DocBook and Jade

[Dennis Grace <dgrace@us.ibm.com>]

Greetings Oasis DocuPeople,

I have a question for anyone who has any expertise in DocBook (sgml), 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 Linux 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 some semblance of 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 sgml 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
 dgrace@us.ibm.com

 Is there another word for 'synonym'?