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.

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.