Re: how to get rid of [] in manpages?

[Colin Watson <cjwatson@debian.org>]

On Sat, Sep 14, 2002 at 09:29:54PM +0200, martin f krafft wrote:
>   <refsynopsisdiv>
>     <cmdsynopsis>
>       <command>&dhpackage;</command>
>         <group>-o <replaceable>outputfile</replaceable></group>
>         <group><replaceable>input files ...</replaceable></group>
>     </cmdsynopsis>
>     <cmdsynopsis>
>       <command>&dhpackage;</command>
>         <group choice="opt"><arg>--help</arg></group>
>     </cmdsynopsis>
>     <cmdsynopsis>
>       <command>&dhpackage;</command>
>         <group choice="opt"><arg>--version</arg></group>
>     </cmdsynopsis>
>   </refsynopsisdiv>

That doesn't conform to the DTD anyway:

/usr/bin/nsgmls:manpage.example.sgml:61:15:E: character data is not allowed here
/usr/bin/nsgmls:manpage.example.sgml:61:15: open elements: REFENTRY REFSYNOPSISDIV[1] CMDSYNOPSIS[1] GROUP[1]

(In my file, line 61 is '<group>-o
<replaceable>outputfile</replaceable></group>'. You probably need an
extra <arg>.)

<group choice="opt"> means that the argument is optional, and therefore
that you want brackets around it. You should probably remove it.
However, even if you do you still get the brackets. A little debugging
indicates that it occurs at this point in the transpec:

  GI:             ARG
  AttValue:       CHOICE OPT
  StartText:      \s[
  EndText:        ${_attval REP REPEAT 505}]\s

This really shouldn't fire when the <group choice="opt"> is removed - I
suggest you file a bug against docbook-to-man.

> > It should be possible to get rid of the brackets, but I don't know about
> > the blank lines. For finer control, use plain groff rather than DocBook.
> 
> I don't have the time to learn that too.

Then you don't get to have fine control of formatting. :)

> Aside, I believe in meta-formats.

This demonstrates that you haven't used groff much, I think ... look at
the mdoc macro set, for instance. It provides an excellent logical
formatting framework.

Also, groff can generate text in various formats, DVI, PostScript, HTML,
and output for various printers. How much more meta do you want? :) In
my opinion, SGML's only advantage over groff for manual pages is that it
provides a more systematic framework for validation, not that's it's a
"meta-format". However, my validation usually consists of running groff
over the page and making sure there are no errors, which is generally
good enough.

Cheers,

-- 
Colin Watson                                  [cjwatson@flatline.org.uk]