Re: man-pages and usage() howto

[Karel Zak <kzak@redhat.com>]

On Sat, Aug 20, 2011 at 09:08:08PM +0200, Sami Kerola wrote:
> On Sat, Aug 20, 2011 at 11:10, Benno Schulenberg <bensberg@justemail.net> wrote:
> > On Wed, 17 Aug 2011 15:07 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> >> On Tue, Aug 16, 2011 at 12:39, Karel Zak <kzak@redhat.com> wrote:
> >>>  It would be also nice to sync man pages with usage() format.
> >
> > Do you mean that you want to use "--option <argument>" also in the
> > man pages, Karel?  Or do we stick there to italics for arguments?
> > (Which translates to underlining on terminals.)

 I mean that we need to use the lowercase for the arguments in usage()
 as well as in man pages.

> IMHO the following looks quite ok, and not too different to
> usage().
> 
> .TP
> \fB\-n\fR, \fB\-\-no\-argument\fR
> This option does not use argument.
> .TP
> \fB\-o\fR, \fB\-\-optional\fR[=<\fIarg\fR>]
> This option uses optional argument.
> .TP
> \fB\-r\fR, \fB\-\-required\fR <\fIarg\fR>
> This option requires an argument.
> 
> Comments?

 I have no strong opinion about it. Benno is probably right that
 italics for the arguments is enough. 

 We already use option arguments without diamond brackets in our man
 pages, so let's continue with this convention to minimize number of
 changes in the man pages ;-)

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com