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

On Tue, Aug 17, 2010 at 05:40:40PM +0200, Alexander Teinum wrote:
> What is the most concise way of outputting a usage and help text?
>
> Must the usage text be unambiguous when it comes to valid combinations?

No, compatibility of options should be described in man page.

> What should the program option or options be named that show the usage
> or help text?

There should be no help options at all: if you need help, use man
page. Usage should be displayed when program is called with wrong
options.

> Are there any existing standards for usage and help text?
>
> How should the usage text and help text be formatted?
>
> – Keep it within 80 characters?
> – Use of whitespace
> – Use of lower- and uppercase
> – Wether to use “typographical correct” punctuation marks (“, ”, ‘, ’,
> … instead of ", ", ', ', ...) or not

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 ...]

With these rules flo usage should be

usage: flo [-c id] [-f from] [-r id] [-t to] [-w what] [what[,from][-to]]

> E-mail from pancake:
>
> > The help messages in unix have different standards. And they aim to be
> > short, simple and keep some common rules. The reason is because this way you
> > can read them faster.
> >
> > In bsd. Help message is just one line. If you want description you have to
> > refer to the manpage or readme.
> >
> > In gnu they tend to display a 4screenscrolling help message which is really
> > anoying.
> >
> > Theorically the help length is another way to measure the complexity of the
> > program.
> >
> > feel free to fwd this mail to the mailing list and continue the discussion
> > there. It can be another interesting topic.
> >
> > For flo. I would suggest a oneline help or maybe somethung like this:
> >
> > flo [-r id] [-wch] [msg]
> > -r id : remove reminder with id.
> > ...
> >
> > Im just telling the flags as an idea.
> >
> > another thing..is that in suckless sw we usually prefer to not use getopt.
> > The code looks ok. But the implementation in libc is horrendous. So a single
> > switchcase would be better.

That depends on what libc you use. GNU libc sort arguments so options
go first, BSD implementation is simplier.
Received on Tue Aug 17 2010 - 18:52:37 CEST