On Thu, 24 Aug 2000, Peter Blomgren wrote:

>Maybe I'm too used to reading cryptic man pages, but this one
>seems pretty clear to me...

Well it wasn't to me until someone pointed it out.  Thanks to all
that pointed this out to me.


>> The groupadd command lists a "-o" option.
>> 
>> SYNOPSIS
>>        groupadd [-g gid [-o]] [-r] [-f] group
>> [SNIP]
>>        -g gid The  numerical value of the group's ID.  This value
>>               must be unique, unless the -o option is used.
>
>Hence, 'groupadd -g 0 haXX0r' will fail (groupadd: gid 0 is not unique),
>but 'groupadd -g 0 -o haXX0r' will successfully add the group haXX0r
>with gid=0 (as an alias for the "root" group).

Right, I got it now.

>> [SNIP]
>>        -f     [SNIP] This  option also modifies the way -g option works.
>>               When you request a gid that it is  not  unique  and
>>               you  don't  give  -o option too, the group creation
>>               will fall back to the standard behavior  (adding  a
>[UNSNIP]        group  as neither -g or -o options were specified).
>[UNSNIP]        This is an option added by Red Hat Software.
>
>Hence, 'groupadd -g 0 -f haxx0r' will add the group haxx0r, with
>a GID is that in _new_ AND _unique_ (gid>500 unless the "-r" option
>is given, in which case gid<500...).
>Finally 'groupadd -g 0 -o -f haxx0r' is equivalent to
>'groupadd -g 0 -o haxx0r' since there is nothing to force.

Yep, I got that now too.  The message learned here is that just
because documentation exists, doesn't mean it is well written at
all.  The defacto standard for manpages and other documentation
when listing command line options seems to be:

-a  does this
-b  does that
-f  blah blah
-o  is this


When I saw "-o" on the commandline, I looked in the manpage.  I
read the whole thing once over, but when I spotted the
"-o" option reference in the above for -f and -g, I looked for
"-o" documentation below which was a very intuitive and natural
thing to look for.  Not finding it, means either:

1) it is not documented
2) it is documented poorly and non-intuitively.

In this case the latter is true.  Consider an application having
50 commanline options for example.  It makes the most sense
they'd be listed in the manpage in alphabetical order.  Starting
off not knowing what ANY of them do, and being told to use
"-o" you'd scroll down the page looking for "-o" most likely, and
not find it under "-z" because you weren't looking for -z.

As long as the GNU manpages and info documents expect you to read
the entire manual and then try to interpret it in 30 different
ways, people will not in general be able to grok what they are
saying.  I'm reading a lot more docs lately than normal, and I'm
finding things increasingly poorly written or referenced.

Pointing that out to people though you often get back a response
saying "why don't you fix it then?".  Pretty hard to fix
documentation that you don't understand though.  A paradox at
best... 

<sigh>

Well, thanks for your explanation..  I have it klunked into my
thinker now.  ;o)

Once again, we've proved here, the best documentation is the
human experience.  (and mailing lists).  ;o)

Take care,
TTYL

-- 
Mike A. Harris                                     Linux advocate     
Computer Consultant                                  GNU advocate  
Capslock Consulting                          Open Source advocate

       Try out Red Hat Linux today:  http://www.redhat.com
           ftp://ftp.redhat.com/pub/redhat/redhat-6.2/




_______________________________________________
Redhat-devel-list mailing list
[EMAIL PROTECTED]
https://listman.redhat.com/mailman/listinfo/redhat-devel-list

Reply via email to