Clarify the usage of `-U|--users` in the man pages for groupadd(8) and groupmod(8)
koshell opened this issue · 1 comments
I've been reading the man page for groupadd(8)
and I'm finding usage of -U|--users
, from #265, a bit ambiguous.
From man/groupadd.8.xml
:
<!--snip-->
<varlistentry>
<term>
<option>-U</option>, <option>--users</option>
</term>
<listitem>
<para>
A list of usernames to add as members of the group.
</para>
<para>
The default behavior (if the <option>-g</option>,
<option>-N</option>, and <option>-U</option> options are not
specified) is defined by the <option>USERGROUPS_ENAB</option>
variable in <filename>/etc/login.defs</filename>.
</para>
</listitem>
</varlistentry>
<!--snip-->
Specifically A list of usernames to add as members of the group.
doesn't clearly state the format of the 'list'. It is probably safe to assume this is referring to a 'comma-separated list' like --users USER1,USER2,USER3
. I had a look at the commit that added it and that does appear to be the case, however I don't know C so I might be reading it wrong.
It could be argued that a 'comma-separated list' would be the likely meaning of 'list' in a man page. But that relies on external experience and personally I think something like shadow
should be as explicit as is practical with it's documentation.
Ideally I would love to have an explicit usage example for the option but I would be willing to settle for just having
A list of usernames...
changed to A comma-separated list of usernames...
.
This would just be a change to the man pages for groupadd
and groupmod
, I would create a PR myself but since I don't know C I'm making an educated guess that it is in-fact a comma-separated list. Ideally someone who uses C could double check the implementation and make the PR.