On Mon, Aug 15, 2011 at 16:19, Karel Zak <kzak@xxxxxxxxxx> wrote: > Sami is already working on some howtos, what we need is some > consensus about a way how describe options. What I wrote about various things can be found from github. I'd say that so far the Documentation directory patch set is a proposal, which can and should change. https://github.com/kerolasa/lelux-utiliteetit/blob/docs-dir/Documentation/howto-usage-function.txt > My suggestion: > > * argument required: > > -o, --option FILE # usage() > -o, --option file # man page I used GNU notation which has 'unnecessary' equals sign. -o, --option=FILE The only reason I can think of why the equal sign is there is visual similarity with optional argument... > * optional argument: > > -o, --option[=FILE] # usage() > -o, --option[=file] # man page ...because with optional arguments one must use = and that make the [=FILE] notation correct. For example see the output of the following. lscpu -p=CPU lscpu -p CPU I also acknowledge the fact that no-one will ever use equals sign when giving required argument. The practise of dropping it is a rational reason not to specify it to usage() or man. I would say this is a question of choosing a convention in between visual symmetry or actual habits of people. IMHO the visual unity is better. > * synopsis > > - without individual options, bad example: > > command [-o offset] [--sizelimit size] [-p pfd] [-r] file > > - [options] is better: > > command [options] file I agree. > - use more synopsis lines if the command supports more separated modes. > > command --add file > command --del file > > (use common sense! ... if there is too many modes, then use [options]) > > The options specific to the mode are allowed in the synopsis or > in the man page should be per-mode section with description about > the options. I did not think multiple modes when I wrote howto-usage. Manual page of man seems to be good example of extensive synopsis. If I've not gone crazy the point of modes seems to point out that some options, arguments, etc mean outcome of an execution is fundamentally different, for example man -k basename man -w basename So the howto should tell how do you know you are dealing with fundamental difference of outcome, which requires multiple synopsis lines. Obvious trap seems to be such hermeneutic circle that no-one understands what the howto tries to say. Rigour rejection until the text is good is needed. > * common options: > > -V, --version > -h, --help I would call these two options explicitly reserved. The `-?' should not be a synonym of `-h' but an invalid option in common case. > * suggestions: > > -a, --all > -o, --output <list> > -r, --raw > -f, --force > -b, --bytes (don't print SIZE in human readable format) Eric S. Raymond's The Art of Unix Programming is proposing something similar. http://www.faqs.org/docs/artu/ch10s05.html In nutshell one should think carefully before using a short option against it's well known other use. I can think immediately an annoyance in the rule of well known. Well known to who, in what context and is it even relevant? Could good go around for this problem is to give a concrete list of short & long options which in context of this package are well-known, and nothing else is. That will also allow several well known definitions to a single short option, which I like. For example -s, --size -s, --silent (prefer -q) -q, --quiet Assuming this approach sounds good the question is shall we write shortest or longest possible list of well known options list? I'm in favour of short list because it requires less maintenance. > * We also need any consensus about groff formatting, the ideal > solution would be add any Documentation/example.man Here's my proposal, which without doubt needs honing. https://github.com/kerolasa/lelux-utiliteetit/blob/docs-dir/Documentation/howto-man-page.txt -- Sami Kerola http://www.iki.fi/kerolasa/ -- To unsubscribe from this list: send the line "unsubscribe util-linux" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
