1

I'm writing a specification for a tool that needs a -f / --foo option with a mandatory argument BAR, so for example these are valid calls:

tool -f BAR
tool --foo BAR

How do I specify this syntax in the invocation section of a manpage or another formal definition?

This would mean the options are not required, which is not what I intend:

tool [-f BAR | --foo BAR]

But simply omitting the brackets would not make sense either, since the pipe could be mistaken for an actual shell pipe.

POSIX does not have long options, and I cannot find a GNU reference for that either.

Gilles 'SO- stop being evil'
  • 829,060
slhck
  • 473

1 Answers1

1

I don't think it'd be common to interpret tool -f BAR | --foo BAR as «pipe the output of tool -f BAR into the command --foo BAR». So I'd use simply

tool -f BAR | --foo BAR

There's other possibilities in the wild using additional markup, specially if the invocation is more complex, to make it more obvious. Unlike with optional arguments and [] though, none of them are universally understood as mandatory argument, e.g.:

tool {-f BAR | --foo BAR}

or

tool <-f BAR | --foo BAR>

and even

tool (-f BAR | --foo BAR)

If you want to make sure that no one misreads the invocation specification, simply duplicate it:

tool -f BAR
tool --foo BAR

You'll see many manpages and help from programs use this multiple approach, although it's usually for different invocations instead of equivalent ones.

outlyer
  • 1,103