Re: [dev] Re: [dev] [dev] Usage, -h, --help, help, synopsis, …

On Tue, Aug 17, 2010 at 08:07:05PM +0200, Alexander Teinum wrote:
> > I think the best format for usage is something like what Plan 9
> > utilities use (BSD use the same):
> >
> > usage: cmd [-abcde] [-f file] [-g pattern] [file ...]
>
> Options without values are combined? Is that correct?

Yes. If you don't use getopt like most suckless projects then no.

> > With these rules flo usage should be
> >
> > usage: flo [-c id] [-f from] [-r id] [-t to] [-w what] [what[,from][-to]]
>
> What if the values are of the same type? -c and -r have id as value.
> -f and -t have date as value. I think your usage-text looks prettier,
> but out of curiosity, can they be combined like this?
>
> usage: flo [-cr id] [-ft date] …

Didn't see anything like that. Even when the types are same, options
mean different things so they are listed like [-f from] [-t to]. crop
utility from Plan 9 have two arguments that accept rgb colors and they
are listed separately.

> If I decide to ditch getopt(), then I’d like to be able to type “flo
> -c -f” to clear the from-field, which means that -f and -t have
> optional arguments. Is it valid for an option to have an optional
> argument?

No. If there is no argument but some option goes after it like

flo -c -f -t

then -t would become argument for -f. That way you always have to
make sure that -f is the last argument or write parser that don't
allow you to use -t as argument or something like this.

Most unix utilities use getopt() so you can look at Plan 9 utilities
for examples of man pages and usage. suckless.org utilities use their
own simple parsers that don't allow you to group options with one '-'
so they list their options like [-a] [-b] [-c]. If you write your own
parser that allow optional arguments and strange things like this,
then there can be no examples or guidelines.

> I found some guidelines here:
>
> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01c
>
> Do you agree with the guidelines listed in 12.2? I’ll find a pen and a
> paper and try to digest those.

Disagree with Guideline 6. awk can accept both -Farg and -F arg. I
think all options should be listed like '[-o arg]' but accept both
-oarg or '-o arg'. For ssuckless projects they should be listed like
'[-o arg]' and accept only '-o arg' form.

Guideline 8 is strange. crop utility from Plan 9 have options that
get 3 arguments and it is ok. But with GNU getopt it would fail
because it move 2nd and 3rd arguments to the end so they become
non-option arguments.

Guideline 9 is like BSD getopt work. GNU getopt allow you to put
options after arguments but I don't like it.

I wonder why glibc developers put arguments sorting in getopt. It
would be much better to place it in bash and enable only when runned
in interactive mode. I use mksh anyway :-p

Guideline 13 should be deprecated. It is not compatible with Plan 9
cat and only leads to additional code complexity. Use /dev/stdin
instead.
Received on Wed Aug 18 2010 - 13:15:26 CEST