CODEWITHSUNDEEP
command-linedocumentation
Mr. Boy
Mr. Boy

Reputation: 63728

How to document command-line which requires one of two options?

I'm familiar how to specify optional and required command-line parameters e.g:

MyApp <inputPath> [logging]

But what if the user has to specify exactly one of two (or more) options, e.g. they must either specify numRepetitions=<num-reps> or stopTime=<stop-time>? How would this be documented in an unambiguous way?

Upvotes: 0

Views: 597

Answers (1)

JosefZ
JosefZ

Reputation: 30123

Use {} curly brackets. 

{ Learn by [an | the | next [self-explanatory]] example }

Learn by next self-explanatory example:

=>prompt $Q$G

=>taskkill
ERROR: Invalid syntax. Neither /FI nor /PID nor /IM were specified.
Type "TASKKILL /?" for usage.

=>taskkill /?

TASKKILL [/S system [/U username [/P [password]]]]
         { [/FI filter] [/PID processid | /IM imagename] } [/T] [/F]

Command-Line Syntax Key

  • Notation ​​ Description
  • Text without brackets or braces​​ Items you must type as shown
  • <Text inside angle brackets> ​​ Placeholder for which you must supply a value
  • [Text inside square brackets] ​​ Optional items
  • {Text inside braces} ​​ Set of required items; choose one
  • Vertical bar (|) ​​ Separator for mutually exclusive items; choose one
  • Ellipsis (…) ​​ Items that can be repeated

Upvotes: 4

Related Questions