| [<<] [<] Page 1 of 1 [>] [>>] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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'?
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Subject:
Re: Man Page Adventures in DocBook and Jade
From: Dan York ####@####.#### Date: 22 Jun 2001 13:12:44 -0000 Message-Id: <20010622091212.I5798@e-smith.com> Dennis, > 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. Unfortunately, I have no experience working with generating man pages, so I can't help... but I thought I'd mention the 'docbook-apps' list as well. I've been a subscriber there for quite some time and found it extremely useful. Subscription instructions on down the page on: http://www.oasis-open.org/docbook/ (send to ####@####.#### with body of "subscribe") and the (searchable) archives are at: http://lists.oasis-open.org/archives/docbook-apps/ I personally have not generated man pages from DocBook, but would love to learn more about doing so. Regards, Dan -- Dan York, Director of Training ####@####.#### Ph: +1-613-751-4401 Mobile: +1-613-263-4312 Fax: +1-613-564-7739 e-smith, inc. 150 Metcalfe St., Suite 1500, Ottawa,ON K2P 1P1 Canada http://www.e-smith.com/ open source, open mind | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Subject:
Man Page Adventures in DocBook and Jade
From: "Dennis Grace" ####@####.#### Date: 23 Jun 2001 01:23:44 -0000 Message-Id: <OF321BFE6C.6CDF3A1B-ON85256A71.005F94D4@raleigh.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
####@####.####
Is there another word for 'synonym'?
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Subject:
Re: Man Page Adventures in DocBook and Jade
From: David Merrill ####@####.#### Date: 23 Jun 2001 02:01:09 -0000 Message-Id: <20010622220028.A25218@lupercalia.net> On Fri, Jun 22, 2001 at 09:11:52AM -0400, Dan York wrote: > I personally have not generated man pages from DocBook, but would love > to learn more about doing so. At the risk of sounding like an AOL'er, me too. Please post back and let us know if you get it working. Thanks, -- Dr. David C. Merrill http://www.lupercalia.net Linux Documentation Project ####@####.#### Collection Editor & Coordinator http://www.linuxdoc.org E Pluribus Unix | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| [<<] [<] Page 1 of 1 [>] [>>] | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||