[newlib-cygwin/main] Cygwin: doc: utils.xml: improve newgrp(1) documentation

[Corinna Vinschen]

https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=a212fd40a8deb9c75d4c433aef4cb007341fe1f7

commit a212fd40a8deb9c75d4c433aef4cb007341fe1f7
Author:     Corinna Vinschen <corinna@vinschen.de>
AuthorDate: Fri Dec 5 20:37:52 2025 +0100
Commit:     Corinna Vinschen <corinna@vinschen.de>
CommitDate: Wed Dec 10 18:10:10 2025 +0100

    Cygwin: doc: utils.xml: improve newgrp(1) documentation
    
    Especially document -l as primary option and - just for Linux
    compatibility.  Note that a command on the commandline is a
    Cygwin extension and incompatible with POSIX and Linux.
    
    Signed-off-by: Corinna Vinschen <corinna@vinschen.de>

Diff:
---
 winsup/doc/utils.xml | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml
index 6a55b3a0e790..5db1d630d56e 100644
--- a/winsup/doc/utils.xml
+++ b/winsup/doc/utils.xml
@@ -2108,13 +2108,13 @@ D: on /d type fat (binary,user,noumount)
 
     <refnamediv>
       <refname>newgrp</refname>
-      <refpurpose>change primary group for a command</refpurpose>
+      <refpurpose>change to a new primary group</refpurpose>
     </refnamediv>
 
     <refsynopsisdiv>
       <cmdsynopsis>
 	<command>newgrp</command>
-	<arg choice="opt">-</arg>
+	<arg choice="opt">-l</arg>
 	<arg choice="opt"><replaceable>group</replaceable></arg>
 	<arg><replaceable>command</replaceable>
 	<arg rep="repeat"><replaceable>args</replaceable></arg>
@@ -2124,22 +2124,27 @@ D: on /d type fat (binary,user,noumount)
 
     <refsect1 id="newgrp-desc">
       <title>Description</title>
-      <para><command>newgrp</command> changes the primary group for a
-        command.</para>
+      <para><command>newgrp</command> starts a new shell environment under
+      a new primary group.</para>
 
-      <para>If the <option>-</option> flag is given as first argument, the
+      <para>If the <option>-l</option> flag is given as first argument, the
 	user's environment will be reinitialized as though the user had logged
 	in, otherwise the current environment, including current working
-	directory, remains unchanged.</para>
+	directory, remains unchanged.  For Linux compatibility, the flag
+	<option>-</option> is allowed as well.</para>
 
       <para><command>newgrp</command> changes the current primary group to the
         named group, or to the default group listed in /etc/passwd if no group
-	name is given.</para>
+	name is given.  The user's standard shell is started, called as login
+        shell if the <option>-l</option> or <option>-</option> flag has been
+	specified.</para>
 
-      <para>By default, the user's standard shell is started, called as login
-        shell if the <option>-</option> flag has been specified.  If a group
-	has been given as argument, a command and its arguments can be
-	specified on the command line.</para>
+      <para>The group argument can be specified as group name from the
+      group database or a non-negative numeric group ID.</para>
+
+      <para> If a group has been given as argument, a command and its
+	arguments can be specified on the command line.  Note that this
+	usage is Cygwin-only and incompatible with POSIX and Linux.</para>
 
       <para>The new primary group must be either the old primary group, or
         it must be part of the supplementary group list.  Setting the primary