CODEWITHSUNDEEP
linuxunixmanpage
Michael Aramini
Michael Aramini

Reputation: 185

use of <> in man page to indicate optional white space

I'm maintaining an old KornShell shell script and its man page.

The shell script's command line options include both -wwidth (no intervening space) and -w width (with intervening white space), which have the same effect. In the man page this is documented in the SYNOPSIS section as [-w<>width], apparently using <> to mean optional white space.

I haven't been able to find on the Web other UNIX or Linux man pages that use <> for this purpose, so I presume that this doesn't follow a convention that UNIX or Linux users expect, and thus users may be confused by <> in the man page.

Which of the following representations in a man page makes it most clear that white space between the -w and width is optional:

Is it better to just have one of either [-wwidth] or [-w width] in the man page, on the basis that they do the same thing so there is little or no value added to the user to document that both of these alternatives are available?

Upvotes: 1

Views: 260

Answers (1)

melpomene
melpomene

Reputation: 85767

I would just document -w width because it's a universal convention that options with arguments can take the argument either in the same command-line argument (-w80) or the following command-line argument (-w 80).

Any tool/option that does not follow the convention should document it, but your case looks pretty standard.

Upvotes: 1

Related Questions