shadow-maint/shadow

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.