Re: how to make the man formatting better.
On Sat, Sep 14, 2002 at 09:22:14PM +0200, martin f krafft wrote:
> I have just simply filled in a manpage.sgml.ex template, and the
> OPTIONS section doesn't look all that great:
>
> OPTIONS
> These programs follow the usual GNU command line syntax,
> with long options starting with two dashes (`-'). A sum?
> mary of options is included below.
>
>
> -o outputfile
> Selects the output method according to the
> extension of outputfile and causes psconcat to
> write the concatenation into this file, over?
> writing it if necessary.
>
> -h --help
> Shows a summary of the available options.
>
> -V --version
> Shows the version of the program.
>
>
> I can't seem to get rid of the newline between the text and the first
> option, and the long options corresponding to -h and -V should be
> written right underneath their short counterparts, not shifted over to
> the right that much. I wonder if this is my incompetence, or an error
> in the manpage.sgml.ex file. I also wouldn't mind to help commenting
> it a little better with your help. I know jack about SGML, and since
> I want to write manpages to help keep Debian's quality as high as it
> is, I don't have the time or patience to work myself into the matter.
Here's a sample of groff that would generate that. It is much briefer
and generates much higher-quality output. Really, it isn't difficult to
learn! I've used the man macro set because it's simpler; you could use
mdoc if you prefer that.
You'll need to have the usual .TH and .SH NAME headers at the start of
the page, of course. See /usr/share/doc/man-db/examples/manpage.example.
Most of Debian's man pages are written this way.
.SH OPTIONS
These programs follow the usual GNU command line syntax,
with long options starting with two dashes (\(oq\-\(cq).
A summary of options is included below.
.TP
.BI \-o " outputfile"
Selects the output method according to the
extension of outputfile and causes psconcat to
write the concatenation into this file,
overwriting it if necessary.
.TP
.BR \-h ", " \-\-help
Shows a summary of the available options.
.TP
.BR \-v ", " \-\-version
Shows the version of the program.
--
Colin Watson [cjwatson@flatline.org.uk]
Reply to: