2

My script can be called like this:

myScript -a some_name
myScript -a all
myScript -b some_name
myScript -b all
myScript -c

How do I write its usage notes? I know [] mean optional arguments and | means alternative but in my case I would need nested alternative, something like:

usage myScript (-a some_name | all) | (-b some_name | all) | -c

Now I don't think I can use () for this purpose so how else can I write this? Do I have to write it in multiple lines instead or is there a better way?

myScript -a some_name | all
myScript -b some_name | all
myScript -c

I mean this would still be ok in my case but if I had more nested alternatives it would get really verbose.

Also is there any exhaustive source describing the standard unix/linux usage notes?

NPS
  • 6,003
  • 11
  • 53
  • 90
  • 1
    Possible duplicate of [Is there a specification for a man page's SYNOPSIS section?](http://stackoverflow.com/questions/8716047/is-there-a-specification-for-a-man-pages-synopsis-section) – Christian.K Jul 18 '16 at 10:26
  • That's not the same question. Sure, the syntax of `man` page's SYNOPSIS section is similar/the same but overall layout is different. I don't want to create a `man` page, just simple (and short) usage notes when a user provides incorrect arguments. And to be honest I'd also like to learn if there's any standard layout/indentation in usage notes. – NPS Jul 18 '16 at 11:15
  • I was not implied that this is the _same_ question, hence the _possible_ duplicate. It was not about the man page in general, but about the (suggested) syntax/notation for optional, mandatory, etc. parameters. YMMV, of course. – Christian.K Jul 18 '16 at 11:32

1 Answers1

0

Docopt provides a good resource for figuring out how these sorts of things should go, as it is an argument parser based on usage documentation.

If you want to get it all in one line, you could do it this way:

myScript ((-a|-b) (some_name|all) | -c)

but that's rather messy. I'd prefer to do it in two:

myScript (-a|-b) (some_name|all)
myScript -c

or actually three, as you should add myScript --help into there.

If I find myself struggling to explain a program's cli, I stop to think whether I've designed it well. Are -a, -b and -c actually commands, of which you can only choose one? Then it'd make more sense to structure your program as having subcommands, like git:

myScript <command> [<args>]

Commands:
    a    Attach an aardvark.
    b    Belay the border.
    c    Capture the castle.

with subcommands having their own help output:

[$]> myScript a --help
Usage:
    myScript a <target>
    myScript a --help

Using options only for optional values helps reduce confusion ("Can I run myScript -a some_name -b all?"), and splitting up the API into components reduces the complexity of what a user has to look at.

Xiong Chiamiov
  • 13,076
  • 9
  • 63
  • 101
  • So the gist of it is - yes, I can use parentheses to group, is that correct? – NPS Jul 20 '16 at 09:20
  • You can do anything that you would like. However, the point of usage documentation is to make it clear to users how to use your program. Whether or not what you've written adheres to any particular standard, it doesn't matter; whether people *understand it* matters. Keep that goal in mind as you write it, and keep that goal in mind as you test the software and see how people use it. – Xiong Chiamiov Jul 21 '16 at 18:10
  • Of course, what you write is true but if there's an agreed upon convention and I try to write usage notes that are against it then this might cause confusion. That's the case I wanted to avoid. – NPS Jul 22 '16 at 07:21
  • Yes, using parentheses to group items is a reasonably well-spread convention. It gets less common when you start considering nested parens, although I imagine most people would be able to extrapolate to understand it. – Xiong Chiamiov Jul 22 '16 at 17:51