Re: man-pages and usage() howto

[Karel Zak <kzak@redhat.com>]

On Mon, Aug 15, 2011 at 09:12:16PM +0200, Sami Kerola wrote:
> On Mon, Aug 15, 2011 at 16:19, Karel Zak <kzak@redhat.com> 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@redhat.com>
 http://karelzak.blogspot.com