man-pages and usage() howto

man-pages and usage() howto

[Karel Zak]

 Hi,

Sami is already working on some howtos, what we need is some
consensus about a way how describe options.

My suggestion:

 * argument required:

   -o, --option FILE    # usage()
   -o, --option file    # man page

 * optional argument:

   -o, --option[=FILE]  # usage()
   -o, --option[=file]  # man page


 * synopsis

   - without individual options, bad example:
   
        command [-o offset] [--sizelimit size] [-p pfd] [-r] file

   - [options] is better:

        command [options] file

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


 * common options:

   -V, --version
   -h, --help

 * suggestions:

   -a, --all
   -o, --output <list>
   -r, --raw
   -f, --force
   -b, --bytes   (don't print SIZE in human readable format)


 * We also need any consensus about groff formatting, the ideal
   solution would be add any Documentation/example.man

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: man-pages and usage() howto

[Sami Kerola]

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.

https://github.com/kerolasa/lelux-utiliteetit/blob/docs-dir/Documentation/h=
owto-usage-function.txt

> My suggestion:
>
> =A0* argument required:
>
> =A0 -o, --option FILE =A0 =A0# usage()
> =A0 -o, --option file =A0 =A0# man page

I used GNU notation which has 'unnecessary' equals sign.

-o, --option=3DFILE

The only reason I can think of why the equal sign is there is visual
similarity with optional argument...

> =A0* optional argument:
>
> =A0 -o, --option[=3DFILE] =A0# usage()
> =A0 -o, --option[=3Dfile] =A0# man page

...because with optional arguments one must use =3D and that make the
[=3DFILE] notation correct. For example see the output of the following.

lscpu -p=3DCPU
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.

> =A0* synopsis
>
> =A0 - without individual options, bad example:
>
> =A0 =A0 =A0 =A0command [-o offset] [--sizelimit size] [-p pfd] [-r] file
>
> =A0 - [options] is better:
>
> =A0 =A0 =A0 =A0command [options] file

I agree.

> =A0 - use more synopsis lines if the command supports more separated mode=
s.
>
> =A0 =A0 =A0 command --add file
> =A0 =A0 =A0 command --del file
>
> =A0 =A0 (use common sense! ... if there is too many modes, then use [opti=
ons])
>
> =A0 =A0 The options specific to the mode are allowed in the synopsis or
> =A0 =A0 in the man page should be per-mode section with description about
> =A0 =A0 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.

> =A0* common options:
>
> =A0 -V, --version
> =A0 -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.

> =A0* suggestions:
>
> =A0 -a, --all
> =A0 -o, --output <list>
> =A0 -r, --raw
> =A0 -f, --force
> =A0 -b, --bytes =A0 (don't print SIZE in human readable format)

Eric S. Raymond's The Art of Unix Programming is proposing something simila=
r.

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.

> =A0* We also need any consensus about groff formatting, the ideal
> =A0 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/h=
owto-man-page.txt

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Benno Schulenberg]

On Mon, 15 Aug 2011 21:12 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> On Mon, Aug 15, 2011 at 16:19, Karel Zak <kzak@redhat.com> wrote:
> > =C2=A0* argument required:
> >
> > =C2=A0 -o, --option FILE =C2=A0 =C2=A0# usage()
> > =C2=A0 -o, --option file =C2=A0 =C2=A0# man page
>=20
> I used GNU notation which has 'unnecessary' equals sign.
>=20
> -o, --option=3DFILE

The full GNU style seems to be this (for example in 'man grep'):

  -o FILE, --option=3DFILE

Since the util-linux man pages don't put the argument after the short
version of the option, the '  -o, --option FILE' variant would be for me
the logical condensed intersection.  Also, why give the impression
that the equals sign is needed when it is not?
=20
> The only reason I can think of why the equal sign is there is visual
> similarity with optional argument... [...]
>=20
> 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.

IMHO visual contrast is better.  When my fleeting glance sees an equals
sign OR square brackets, I know the argument is optional; when it does
not see an equals sign OR does not see square brackets, the argument is
required.  Redundancy is good.


> > =C2=A0 =C2=A0 =C2=A0 =C2=A0command [options] file

If in the usage() help text the arguments of options are written in
uppercase, wouldn't it be more consistent to then also write the
arguments of the command itself in uppercase (as for example
'man -h' and 'grep --help' do)?

        command [OPTIONS] FILE

(Also, to be fully correct, it would have to say "[OPTION...]" instead,
but I will let that go.)

About the other things I have not yet an opinion.

Regards,

Benno

--=20
http://www.fastmail.fm - Access all of your messages and folders
                          wherever you are

Re: man-pages and usage() howto

[Karel Zak]

On Tue, Aug 16, 2011 at 11:03:44AM +0200, Benno Schulenberg wrote:
> > >        command [options] file
> 
> If in the usage() help text the arguments of options are written in
> uppercase, wouldn't it be more consistent to then also write the

 It depends, Semi's version is uppercase, but my (findmnt, blkid,
 lsblk, ...) is <lowercase> :-) 

> About the other things I have not yet an opinion.

 I made the decision, --option <argument>. We can play with it little
 bit more in the next release. Now I'd like to release it...

 It would be also nice to sync man pages with usage() format. Note
 that man pages changes are acceptable for -rc2.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: man-pages and usage() howto

[Sami Kerola]

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

Diamond brackets make visual difference to look quite nice. I do
like this.

 -n, --no-argument     this option requires no_argument
 -o, --optional[=3Darg]  this option has optional_argument
 -r, --required <arg>  this option requires required_argument

>  You can hate me, but we need any decision. I'll cleanup the
>  usage() strings now.

Hate? No way! Decision after fair discussion is something I
greatly value, even I could have had heretic wrong opinions
during conversation. The hate is reserved for unjust decisions.

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

I likely made that sound over complicated. I know what I want to
mean, the next thing is to write it understandable way down. Key
word is not write but understandable, which makes this difficult
if anything.

>  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)

How putting to c.h the following?

#define USAGE_HEADER _("\nUsage:\n")
#define USAGE_OPTIONS _("\nOptions:\n")
#define USAGE_SHORT_TAIL _("\n")
#define USAGE_MAN_TAIL _("For more details see %s.")

Rest should be obvious.

Having also definition for OPTION_HELP && OPTION_VERSION would be
good.

>   - 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");

Assuming we end up using definitions this does not have to be
that specific.

>   - in the code all strings with options have to start at the same
>     position. It means:
>
>     fprintf(out, _(" -x[=3D<foo>]   default foo is %s"), x);
>     fputs(       _(" -y         some text"), out);

I agree.

>   - 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)."

Yes, and the definitions...

>   - use manageable chunks for the usage strings (one or few lines)

Sound reasonable, I'll add this to howto.

>   - separator between short and long options is comma and one space:
>     " -x, --long-x "

I agree, and adding to howto is needed.

On Tue, Aug 16, 2011 at 12:46, Karel Zak <kzak@redhat.com> wrote:
> On Tue, Aug 16, 2011 at 11:03:44AM +0200, Benno Schulenberg wrote:
>> >        command [options] file
>>
>> If in the usage() help text the arguments of options are
>> written in uppercase, wouldn't it be more consistent to then
>> also write the
>
>  It depends, Semi's version is uppercase, but my (findmnt,
>  blkid, lsblk, ...) is <lowercase> :-)

I made my own office vote. The seasoned command line guys, by
clear margin, voted for lower case. Explanation why I wrote
originally with upper case was a copy how GNU does it, but as the
results show people do not like it.

>> About the other things I have not yet an opinion.
>
>  I made the decision, --option <argument>. We can play with it
>  little bit more in the next release. Now I'd like to release
>  it...
>
>  It would be also nice to sync man pages with usage() format.
>  Note that man pages changes are acceptable for -rc2.

Sounds that the version 2.21 will have hefty amount of usage(),
man page and documentation changes. I hope all is done by Jan
2012.

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Benno Schulenberg]

On Wed, 17 Aug 2011 15:07 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> On Tue, Aug 16, 2011 at 12:39, Karel Zak <kzak@redhat.com> wrote:
> >
> >    --date <time>
> >
> >  the important is visual difference between static option name
> >  and variable option argument.
> 
> Diamond brackets make visual difference to look quite nice. I do
> like this.

Yes, it does look better than all uppercase, so I'll accept.
(That I stuck to uppercase is because it wastes less space,
and with just 80 characters width this sometimes matters,
plus it seemed widespread tradition.)

>  -n, --no-argument     this option requires no_argument
>  -o, --optional[=arg]  this option has optional_argument
>  -r, --required <arg>  this option requires required_argument

The middle one would need the pointy brackets, too, no?

 -o, --optional[=<arg>]  this option has optional_argument

> >  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)

As a translator I do not quite like the separation of the 
"\nUsage:\n" string from the actual synopsis -- it is good
to have some context in the string.  But I'll accept.  The
initial space of the actual synopsis strings will eventually
let translators understand what they are.

> How putting to c.h the following?
> 
> #define USAGE_HEADER _("\nUsage:\n")
> #define USAGE_OPTIONS _("\nOptions:\n")
> #define USAGE_SHORT_TAIL _("\n")
> #define USAGE_MAN_TAIL _("For more details see %s.")

Especially the latter would be nice: at the moment there are
many such lines with just a differing final word.

> Having also definition for OPTION_HELP && OPTION_VERSION would be
> good.

That won't work -- the amount of indentation for the option description
is not the same for all utilities.  And to make it the same for all would
create ugly and unneeded wide open text spaces for some tools.


> >  I made the decision, --option <argument>.  [...]
> >
> >  It would be also nice to sync man pages with usage() format.

Do you mean that you want to use "--option <argument>" also in the
man pages, Karel?  Or do we stick there to italics for arguments?
(Which translates to underlining on terminals.)

Regards,

Benno

-- 
http://www.fastmail.fm - Email service worth paying for. Try it for free

Re: man-pages and usage() howto

[Sami Kerola]

On Sat, Aug 20, 2011 at 11:10, Benno Schulenberg <bensberg@justemail.net> wrote:
> On Wed, 17 Aug 2011 15:07 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
>> On Tue, Aug 16, 2011 at 12:39, Karel Zak <kzak@redhat.com> wrote:
>>>
>>  -n, --no-argument     this option requires no_argument
>>  -o, --optional[=arg]  this option has optional_argument
>>  -r, --required <arg>  this option requires required_argument
>
> The middle one would need the pointy brackets, too, no?
>
>  -o, --optional[=<arg>]  this option has optional_argument

You are right. Fixed to howto-usage-function.txt

>> How putting to c.h the following?
>>
>> #define USAGE_HEADER _("\nUsage:\n")
>> #define USAGE_OPTIONS _("\nOptions:\n")
>> #define USAGE_SHORT_TAIL _("\n")
>> #define USAGE_MAN_TAIL _("For more details see %s.")
>
> Especially the latter would be nice: at the moment there are
> many such lines with just a differing final word.
>
>> Having also definition for OPTION_HELP && OPTION_VERSION would be
>> good.
>
> That won't work -- the amount of indentation for the option description
> is not the same for all utilities.  And to make it the same for all would
> create ugly and unneeded wide open text spaces for some tools.

To me it does not sound a big deal if --help and --version
description begins from different indent than rest of lines. I
wrote example output that way, so that you can judge how that
will look.

https://github.com/kerolasa/lelux-utiliteetit/blob/docs-dir/Documentation/howto-usage-function.txt

I do not understand why it would be sensible to ask translation
teams to make tens of versions near same help & usage strings
while these string could simply be a bit ugly.

>>>  I made the decision, --option <argument>.  [...]
>>>
>>>  It would be also nice to sync man pages with usage() format.
>
> Do you mean that you want to use "--option <argument>" also in the
> man pages, Karel?  Or do we stick there to italics for arguments?
> (Which translates to underlining on terminals.)

What ever was meant the howto is incomplete.

https://github.com/kerolasa/lelux-utiliteetit/blob/docs-dir/Documentation/howto-man-page.txt

IMHO the following looks quite ok, and not too different to
usage().

.TP
\fB\-n\fR, \fB\-\-no\-argument\fR
This option does not use argument.
.TP
\fB\-o\fR, \fB\-\-optional\fR[=<\fIarg\fR>]
This option uses optional argument.
.TP
\fB\-r\fR, \fB\-\-required\fR <\fIarg\fR>
This option requires an argument.

Comments?

-- 
   Sami Kerola
   http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Sami Kerola]

On Sat, Aug 20, 2011 at 21:08, Sami Kerola <kerolasa@iki.fi> wrote:
> What ever was meant the howto is incomplete.
>
> https://github.com/kerolasa/lelux-utiliteetit/blob/docs-dir/Documentation=
/howto-man-page.txt

I took another look of the howto-man-page, and changed bits here and
there. Is that now better or worse? Should there be more examples
about some common thing I missed?

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Karel Zak]

On Sat, Aug 20, 2011 at 09:08:08PM +0200, Sami Kerola wrote:
> On Sat, Aug 20, 2011 at 11:10, Benno Schulenberg <bensberg@justemail.net> wrote:
> > On Wed, 17 Aug 2011 15:07 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> >> On Tue, Aug 16, 2011 at 12:39, Karel Zak <kzak@redhat.com> wrote:
> >>>  It would be also nice to sync man pages with usage() format.
> >
> > Do you mean that you want to use "--option <argument>" also in the
> > man pages, Karel?  Or do we stick there to italics for arguments?
> > (Which translates to underlining on terminals.)

 I mean that we need to use the lowercase for the arguments in usage()
 as well as in man pages.

> IMHO the following looks quite ok, and not too different to
> usage().
> 
> .TP
> \fB\-n\fR, \fB\-\-no\-argument\fR
> This option does not use argument.
> .TP
> \fB\-o\fR, \fB\-\-optional\fR[=<\fIarg\fR>]
> This option uses optional argument.
> .TP
> \fB\-r\fR, \fB\-\-required\fR <\fIarg\fR>
> This option requires an argument.
> 
> Comments?

 I have no strong opinion about it. Benno is probably right that
 italics for the arguments is enough. 

 We already use option arguments without diamond brackets in our man
 pages, so let's continue with this convention to minimize number of
 changes in the man pages ;-)

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: man-pages and usage() howto

[Sami Kerola]

On Mon, Aug 22, 2011 at 10:16, Karel Zak <kzak@redhat.com> wrote:
>> IMHO the following looks quite ok, and not too different to
>> usage().
>>
>> .TP
>> \fB\-n\fR, \fB\-\-no\-argument\fR
>> This option does not use argument.
>> .TP
>> \fB\-o\fR, \fB\-\-optional\fR[=3D<\fIarg\fR>]
>> This option uses optional argument.
>> .TP
>> \fB\-r\fR, \fB\-\-required\fR <\fIarg\fR>
>> This option requires an argument.
>
> =A0I have no strong opinion about it. Benno is probably right that
> =A0italics for the arguments is enough.
>
> =A0We already use option arguments without diamond brackets in our man
> =A0pages, so let's continue with this convention to minimize number of
> =A0changes in the man pages ;-)

The howto-man-page.txt now has arguments underlined without diamond
brackets. Optional argument has square brackets surrounding it.

Is the patch set ready now? Have a look, and in absence of comments
merge might be reasonable thing to do after few days.

https://github.com/kerolasa/lelux-utiliteetit/tree/docs-dir/Documentation

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Benno Schulenberg]

On Sat, 20 Aug 2011 21:08 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> On Sat, Aug 20, 2011 at 11:10, Benno Schulenberg <bensberg@justemail.net> wrote:
> > On Wed, 17 Aug 2011 15:07 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> >> Having also definition for OPTION_HELP && OPTION_VERSION would be
> >> good.
> >
> > That won't work -- the amount of indentation for the option description
> > is not the same for all utilities.  And to make it the same for all would
> > create ugly and unneeded wide open text spaces for some tools.
> 
> To me it does not sound a big deal if --help and --version
> description begins from different indent than rest of lines. I
> wrote example output that way, so that you can judge how that
> will look.

When --help and --version are always the last two options of the
usage help text, a differing indentation is acceptable.  But if --help
is ordered alphabetically, it will look broken.

> \fB\-o\fR, \fB\-\-optional\fR[=<\fIarg\fR>]
> This option uses optional argument.

As Karel said, the majority convention now is to not use pointy brackets
for arguments in man pages.  The italics/underlining is enough to make
them stand out.

I would also suggest to not use "arg" but the full word "argument", so as
to encourage writers to not unnecessarily abbreviate the argument name,
to use for example "seconds" and not "secs", use "number" and not "num".

A thing about the formatting: why us \fB and \fR and \fB and \fR?
Why not use the macro .BR at the start of the line instead?
(I do not understand your comment about some macros not being
visually different from plain .B or .I.)

Another thing: the man page formatter itself puts a double space after a
period when in the man page source the next sentence begins on a new
line.  So when in the source a new sentence begins somewhere midline,
it should use a double space before its initial letter.

>From your usage howto:
>  -n, --no-argument option requires no_argument
>  -o, --optional[=<arg>] option has optional_argument
>  -r, --required <arg> option requires required_argument

Why the underscores?  I would suggest the following:

  -n, --no-argument       option takes no argument
  -o, --optional[=<arg>]  option takes optional argument
  -r, --required <arg>    option requires an argument

(As in a usage text space is limited, abbreviations are okay.)

Regards,

Benno

-- 
http://www.fastmail.fm - Access your email from home and the web

Re: man-pages and usage() howto

[Sami Kerola]

On Mon, Aug 22, 2011 at 22:38, Benno Schulenberg <bensberg@justemail.net> w=
rote:
> On Sat, 20 Aug 2011 21:08 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
>> To me it does not sound a big deal if --help and --version
>> description begins from different indent than rest of lines. I
>> wrote example output that way, so that you can judge how that
>> will look.
>
> When --help and --version are always the last two options of the
> usage help text, a differing indentation is acceptable. =A0But if --help
> is ordered alphabetically, it will look broken.

True, and that's why I wrote they should be last entries.

>> \fB\-o\fR, \fB\-\-optional\fR[=3D<\fIarg\fR>]
>> This option uses optional argument.
>
> As Karel said, the majority convention now is to not use pointy brackets
> for arguments in man pages. =A0The italics/underlining is enough to make
> them stand out.

I guess you did not read from git the section.

.SH OPTIONS
.TP
\fB\-n\fR, \fB\-\-no\-argument\fR
This option does not use argument.
.TP
\fB\-o\fR, \fB\-\-optional\fR [\fIarg\fR]
Tell in description an
.I arg
is optional, and what happens when is or is not given.
.TP
\fB\-r\fR, \fB\-\-required\fR \fIarg\fR
Tell in description option
.I arg
is required.

As you can see no diamond brackets there.

> I would also suggest to not use "arg" but the full word "argument", so as
> to encourage writers to not unnecessarily abbreviate the argument name,
> to use for example "seconds" and not "secs", use "number" and not "num".

Good point. I will fix that when I'm at home again.

> A thing about the formatting: why us \fB and \fR and \fB and \fR?
> Why not use the macro .BR at the start of the line instead?

No matter how I tried to use various .B, .BR

> (I do not understand your comment about some macros not being
> visually different from plain .B or .I.)

Either my term, groff or pager is/are broken, or I have wooden eyes or
the different highlights do not stand out, see yourself:

http://ut3.org/~kerolasa/groff-highlight.png

What I tried to say; Do not get fooled that different macros will look
different so that you can refer visually in between different text
elements. For example in the screen shot on top the required argument
has same appearance when it is next to switch & in text. I think that
sort of consistency in style makes things more understandable.

> Another thing: the man page formatter itself puts a double space after a
> period when in the man page source the next sentence begins on a new
> line. =A0So when in the source a new sentence begins somewhere midline,
> it should use a double space before its initial letter.

Are you sure it does that? See the screenshot notes section third
paragraph line two, words `macros. See' has only single space in
between them. Even there would be two spaces I do not agree that groff
input writer should imitate output. It should be enough that words and
sentences are white space separated, groff will take care the rest.

> From your usage howto:
>> =A0-n, --no-argument option requires no_argument
>> =A0-o, --optional[=3D<arg>] option has optional_argument
>> =A0-r, --required <arg> option requires required_argument
>
> Why the underscores? =A0I would suggest the following:
>
> =A0-n, --no-argument =A0 =A0 =A0 option takes no argument
> =A0-o, --optional[=3D<arg>] =A0option takes optional argument
> =A0-r, --required <arg> =A0 =A0option requires an argument
>
> (As in a usage text space is limited, abbreviations are okay.)

The weird underscores are used in option structure. Now when you
mention that I think having such unexplained reference is not good.
I'll write the description using ordinary text.

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Benno Schulenberg]

[-- Attachment #1: Type: text/plain, Size: 1992 bytes --]


On Tue, 23 Aug 2011 10:15 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
> On Mon, Aug 22, 2011 at 22:38, Benno Schulenberg <bensberg@justemail.net> wrote:
> > (I do not understand your comment about some macros not being
> > visually different from plain .B or .I.)
> 
> Either my term, groff or pager is/are broken, or I have wooden eyes or
> the different highlights do not stand out, see yourself:
> 
> http://ut3.org/~kerolasa/groff-highlight.png
> 
> What I tried to say; Do not get fooled that different macros will look
> different so that you can refer visually in between different text
> elements.

Hmm, maybe you misunderstand what for example the .BI macro does?
It does not mean "bold _plus_ italic" but "alternate bold and italic".  And it
does that perfectly.  See for example the attached example file.

> > Another thing: the man page formatter itself puts a double space after a
> > period when in the man page source the next sentence begins on a new
> > line.  So when in the source a new sentence begins somewhere midline,
> > it should use a double space before its initial letter.
> 
> Are you sure it does that?

Yes, it does that here, on Ubuntu Lucid 10.10, with man 2.5.7.

> See the screenshot notes section third
> paragraph line two, words `macros. See' has only single space in
> between them.

Yes, but in the source it says "appropriate groff macros. See" on a single
line.  When you put the "See" on a line by itself, you wil see two spaces
appear before it.  See the attached example file.

> Even there would be two spaces I do not agree that groff
> input writer should imitate output. It should be enough that words and
> sentences are white space separated, groff will take care the rest.

Well, being a doublespacer myself, I notice it when some sentences are
single-spaced and others double; it irks.  But never mind.

Regards,

Benno

-- 
http://www.fastmail.fm - A fast, anti-spam email service.


[-- Attachment #2: junk.1 --]
[-- Type: application/octet-stream, Size: 549 bytes --]

.TH JUNK 1 "Today" "Example" "Spaciousness"
.SH NAME
junk \- do nothing
.SH DESCRIPTION
.B junk
does nothing.
Just show.
That.
After.
.PP
Each period.
Plus newline.
Follow two spaces.
.SH FORMATTING
.PP
.BR \.BR\  alternate\  bold\  and\  normal\  and\  so\  on\  and\  so\  on
.PP
.BI \.BI\  alternate\  bold\  and\  italic
.PP
.IB \.IB\  alternate\  italic\  and\  bold
.PP
.IR \.IR\  alternate\  italic\  and\  normal
.PP
.RB \.RB\  alternate\  normal\  and\  bold
.PP
.RI \.RI\  alternate\  normal\  and\  italic\  and\  so\  on\  and\  so\  on

Re: man-pages and usage() howto

[Sami Kerola]

On Tue, Aug 23, 2011 at 20:55, Benno Schulenberg <bensberg@justemail.net> w=
rote:
> On Tue, 23 Aug 2011 10:15 +0200, "Sami Kerola" <kerolasa@iki.fi> wrote:
>> On Mon, Aug 22, 2011 at 22:38, Benno Schulenberg <bensberg@justemail.net=
> wrote:
>> > (I do not understand your comment about some macros not being
>> > visually different from plain .B or .I.)
>>
>> Either my term, groff or pager is/are broken, or I have wooden eyes or
>> the different highlights do not stand out, see yourself:
>>
>> http://ut3.org/~kerolasa/groff-highlight.png
>>
>> What I tried to say; Do not get fooled that different macros will look
>> different so that you can refer visually in between different text
>> elements.
>
> Hmm, maybe you misunderstand what for example the .BI macro does?
> It does not mean "bold _plus_ italic" but "alternate bold and italic". =
=A0And it
> does that perfectly. =A0See for example the attached example file.

Indeed I have. Thank you clarifying that, and as obvious the strange
(wrong) instruction in howto-man-page.txt is gone.

>> > Another thing: the man page formatter itself puts a double space after=
 a
>> > period when in the man page source the next sentence begins on a new
>> > line. =A0So when in the source a new sentence begins somewhere midline=
,
>> > it should use a double space before its initial letter.
>>
>> Are you sure it does that?
>
> Yes, it does that here, on Ubuntu Lucid 10.10, with man 2.5.7.
>
>> See the screenshot notes section third
>> paragraph line two, words `macros. See' has only single space in
>> between them.
>
> Yes, but in the source it says "appropriate groff macros. See" on a singl=
e
> line. =A0When you put the "See" on a line by itself, you wil see two spac=
es
> appear before it. =A0See the attached example file.

I'm quite near to say groff is a stupid program. Well, it seems that
the instructions should indeed tell to use french spacing e.g. two
spaces after a dot. After all it would be even more ridiculous to ask
people to use dot only at middle of line so that groff will never add
two spaces.

>> Even there would be two spaces I do not agree that groff
>> input writer should imitate output. It should be enough that words and
>> sentences are white space separated, groff will take care the rest.
>
> Well, being a doublespacer myself, I notice it when some sentences are
> single-spaced and others double; it irks. =A0But never mind.

Quite the opposite, I did not know I where talking. Thanks again
pointing out how wrong I where.

p.s. The usage() option thing is fixed as well.

--=20
=A0=A0 Sami Kerola
=A0=A0 http://www.iki.fi/kerolasa/

Re: man-pages and usage() howto

[Karel Zak]

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