Re: man-pages and usage() howto

["Benno Schulenberg" <bensberg@justemail.net>]

On Sat, 20 Aug 2011 21:08 +0200, "Sami Kerola" <kerolasa@iki.fi> 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:
> >> Having also definition for OPTION_HELP && OPTION_VERSION would be
> >> good.
> >
> > That won't work -- the amount of indentation for the option description
> > is not the same for all utilities.  And to make it the same for all would
> > create ugly and unneeded wide open text spaces for some tools.
> 
> To me it does not sound a big deal if --help and --version
> description begins from different indent than rest of lines. I
> wrote example output that way, so that you can judge how that
> will look.

When --help and --version are always the last two options of the
usage help text, a differing indentation is acceptable.  But if --help
is ordered alphabetically, it will look broken.

> \fB\-o\fR, \fB\-\-optional\fR[=<\fIarg\fR>]
> This option uses optional argument.

As Karel said, the majority convention now is to not use pointy brackets
for arguments in man pages.  The italics/underlining is enough to make
them stand out.

I would also suggest to not use "arg" but the full word "argument", so as
to encourage writers to not unnecessarily abbreviate the argument name,
to use for example "seconds" and not "secs", use "number" and not "num".

A thing about the formatting: why us \fB and \fR and \fB and \fR?
Why not use the macro .BR at the start of the line instead?
(I do not understand your comment about some macros not being
visually different from plain .B or .I.)

Another thing: the man page formatter itself puts a double space after a
period when in the man page source the next sentence begins on a new
line.  So when in the source a new sentence begins somewhere midline,
it should use a double space before its initial letter.

>From your usage howto:
>  -n, --no-argument option requires no_argument
>  -o, --optional[=<arg>] option has optional_argument
>  -r, --required <arg> option requires required_argument

Why the underscores?  I would suggest the following:

  -n, --no-argument       option takes no argument
  -o, --optional[=<arg>]  option takes optional argument
  -r, --required <arg>    option requires an argument

(As in a usage text space is limited, abbreviations are okay.)

Regards,

Benno

-- 
http://www.fastmail.fm - Access your email from home and the web