On Mon, Aug 15, 2011 at 09:12:16PM +0200, Sami Kerola wrote:
> 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.
Yep, I think we can make it "perfect" in your githup repository
before we merge it upstream ;-)
> I used GNU notation which has 'unnecessary' equals sign.
[...]
> IMHO the visual unity is better.
I understand, but I'm not sure about readability... well, I have asked
my colleagues and the winer is:
--date <time>
the important is visual difference between static option name and variable
option argument.
You can hate me, but we need any decision. I'll cleanup the usage()
strings now.
> 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.
I think we have to use common sense here. Sometimes multiple synopsis
lines makes sense (losetup -h ?). There is not necessary any strict
rule.
[...]
> 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.
Sure, I agree.
I'm just working on Benno's patches and I found that we need some
explicitly defined rules for usage():
- "Usage:" and "Options:" use separate lines and strings, before
the sections has to be empty line:
fputs(_("\nUsage:\n"), out);
...
fputs(_("\nOptions:\n"), out);
(so this two string will be translated only once)
- all lines with options and synopsis are prefixed
by ***one*** space (0x40):
fputs(_("\nUsage:\n"), out);
fprintf(out,
_(" %s [options]\n"), something);
fputs(_("\nOptions:\n"), out);
fputs(_(" -b, --bar this is bar\n");
- in the code all strings with options have to start at the same
position. It means:
fprintf(out, _(" -x[=<foo>] default foo is %s"), x);
fputs( _(" -y some text"), out);
- the first and last usage() output line is empty
- the last line does not have to be empty if there is additional
info about a man page "For more details see foo(1)."
- use manageable chunks for the usage strings (one or few lines)
- separator between short and long options is comma and one space:
" -x, --long-x "
Comments?
--
Karel Zak <kzak@xxxxxxxxxx>
http://karelzak.blogspot.com
--
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
