1

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:

  • [-w<>width],
  • [-w[ ]width], or
  • [-wwidth|-w width]?

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?

user3405743
  • 97
  • 5
  • Personally, I recommend choosing one to be preferred. Keep the implementation as it is and in the documentation mention that the other version is obsolete but supported for compatibility. – William Pursell Jun 08 '18 at 20:34
  • Also see Posix's [Utility Argument Syntax](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html). GNU does not have the same at [Standards for Command Line Interfaces](https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html). I wrote to GNU several years ago asking them to document the syntax in the manual. This is probably a duplicate of [Is there a “standard” format for command line/shell help text?](https://stackoverflow.com/q/9725675/608639). – jww Jun 08 '18 at 21:22
  • After posting my question, I've noticed that the HP-UX intro(1) man page uses <> to represent optional white space, as in -arg_letter<>opt_arg. As no HP-UX man pages for actual commands use <> for this purpose, I think the intent in intro(1) is that it is optional for command synopses to have white space between an argument letter and its option argument, and **not** that there should be a <> in command synopses to indicate optional white space at that point in command lines. – user3405743 Jun 09 '18 at 21:08

1 Answers1

1

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.

melpomene
  • 84,125
  • 8
  • 85
  • 148