Subject: bug#10369: coreutils: [PATCH] doc: homologize ch{con, grp, mod, own} option descriptions

From: Pádraig Brady <[email-masked]>
Date: Mon, 26 Dec 2011 19:37:46 +0000

On 12/26/2011 11:11 AM, Pádraig Brady wrote:
> On 12/26/2011 10:25 AM, Paul Eggert wrote:
>> On 12/26/11 02:20, Pádraig Brady wrote:
>>
>>> chcon, chgrp need the same adjustment.
>>> Note I'd prefer to keep -R and -v together
>>> as they're more general than --ref and
>>> can use the same translations.
>>
>> If we're going to list options in some order
>> than alphabetically (which often makes sense),
>> shouldn't -c, -f, and -v be kept together?
>> This would be for the same reason that --no-preserve-root
>> and --preserve-root are kept together: they're related
>> options.
> 
> Agreed. I'll adjust like:
> 
> -c, -f, -v
> --{no-,}preserve-root
> --recursive
> --reference
> --$command_specific
> --help
> --version

That attached patch handles this,
and fixes an issue where --dereference
was not documented in `chcon`

cheers,
Pádraig.
From 8e0128a50209a35245f7c3c21880165939b3b871 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Mon, 26 Dec 2011 19:20:04 +0000
Subject: [PATCH] doc: homologize ch{con,grp,mod,own} option descriptions

* src/chgrp.c (usage): Group associated options together
and minimize the individual messages between these four utils.
* src/chmod.c: Likewise.
* src/chown.c: Likewise.
* src/chcon.c (usage): Likewise.  Add documention for
the --dereference option.

Suggested by Paul Eggert and Jari Aalto
---
 src/chcon.c |   20 ++++++++++++++------
 src/chgrp.c |   16 +++++++++++-----
 src/chmod.c |   17 +++++++++++------
 src/chown.c |   16 +++++++++++-----
 4 files changed, 47 insertions(+), 22 deletions(-)

diff --git a/src/chcon.c b/src/chcon.c
index 5174a46..f1c0018 100644
--- a/src/chcon.c
+++ b/src/chcon.c
@@ -359,22 +359,30 @@ Usage: %s [OPTION]... CONTEXT FILE...\n\
 Change the security context of each FILE to CONTEXT.\n\
 With --reference, change the security context of each FILE to that of RFILE.\n\
 \n\
-  -h, --no-dereference   affect symbolic links instead of any referenced file\n\
 "), stdout);
       fputs (_("\
-      --reference=RFILE  use RFILE's security context rather than specifying\n\
-                         a CONTEXT value\n\
-  -R, --recursive        operate on files and directories recursively\n\
-  -v, --verbose          output a diagnostic for every file processed\n\
+      --dereference      affect the referent of each symbolic link (this is\n\
+                         the default), rather than the symbolic link itself\n\
+  -h, --no-dereference   affect symbolic links instead of any referenced file\n\
 "), stdout);
       fputs (_("\
   -u, --user=USER        set user USER in the target security context\n\
   -r, --role=ROLE        set role ROLE in the target security context\n\
   -t, --type=TYPE        set type TYPE in the target security context\n\
   -l, --range=RANGE      set range RANGE in the target security context\n\
-\n\
 "), stdout);
       fputs (_("\
+      --reference=RFILE  use RFILE's security context rather than specifying\n\
+                         a CONTEXT value\n\
+"), stdout);
+      fputs (_("\
+  -R, --recursive        operate on files and directories recursively\n\
+"), stdout);
+      fputs (_("\
+  -v, --verbose          output a diagnostic for every file processed\n\
+"), stdout);
+      fputs (_("\
+\n\
 The following options modify how a hierarchy is traversed when the -R\n\
 option is also specified.  If more than one is specified, only the final\n\
 one takes effect.\n\
diff --git a/src/chgrp.c b/src/chgrp.c
index 1b4847d..63dcc63 100644
--- a/src/chgrp.c
+++ b/src/chgrp.c
@@ -115,13 +115,19 @@ Usage: %s [OPTION]... GROUP FILE...\n\
 Change the group of each FILE to GROUP.\n\
 With --reference, change the group of each FILE to that of RFILE.\n\
 \n\
+"), stdout);
+      fputs (_("\
   -c, --changes          like verbose but report only when a change is made\n\
+  -f, --silent, --quiet  suppress most error messages\n\
+  -v, --verbose          output a diagnostic for every file processed\n\
+"), stdout);
+      fputs (_("\
       --dereference      affect the referent of each symbolic link (this is\n\
                          the default), rather than the symbolic link itself\n\
+  -h, --no-dereference   affect symbolic links instead of any referenced file\n\
 "), stdout);
       fputs (_("\
-  -h, --no-dereference   affect each symbolic link instead of any referenced\n\
-                         file (useful only on systems that can change the\n\
+                         (useful only on systems that can change the\n\
                          ownership of a symlink)\n\
 "), stdout);
       fputs (_("\
@@ -129,14 +135,14 @@ With --reference, change the group of each FILE to that of RFILE.\n\
       --preserve-root    fail to operate recursively on `/'\n\
 "), stdout);
       fputs (_("\
-  -f, --silent, --quiet  suppress most error messages\n\
       --reference=RFILE  use RFILE's group rather than specifying a\n\
                          GROUP value\n\
+"), stdout);
+      fputs (_("\
   -R, --recursive        operate on files and directories recursively\n\
-  -v, --verbose          output a diagnostic for every file processed\n\
-\n\
 "), stdout);
       fputs (_("\
+\n\
 The following options modify how a hierarchy is traversed when the -R\n\
 option is also specified.  If more than one is specified, only the final\n\
 one takes effect.\n\
diff --git a/src/chmod.c b/src/chmod.c
index 6fec84a..70e7aaa 100644
--- a/src/chmod.c
+++ b/src/chmod.c
@@ -377,18 +377,23 @@ Usage: %s [OPTION]... MODE[,MODE]... FILE...\n\
               program_name, program_name, program_name);
       fputs (_("\
 Change the mode of each FILE to MODE.\n\
+With --reference, change the mode of each FILE to that of RFILE.\n\
 \n\
-  -c, --changes           like verbose but report only when a change is made\n\
+"), stdout);
+      fputs (_("\
+  -c, --changes          like verbose but report only when a change is made\n\
+  -f, --silent, --quiet  suppress most error messages\n\
+  -v, --verbose          output a diagnostic for every file processed\n\
 "), stdout);
       fputs (_("\
       --no-preserve-root  do not treat `/' specially (the default)\n\
-      --preserve-root     fail to operate recursively on `/'\n\
+      --preserve-root    fail to operate recursively on `/'\n\
+"), stdout);
+      fputs (_("\
+      --reference=RFILE  use RFILE's mode instead of MODE values\n\
 "), stdout);
       fputs (_("\
-  -f, --silent, --quiet   suppress most error messages\n\
-  -v, --verbose           output a diagnostic for every file processed\n\
-      --reference=RFILE   use RFILE's mode instead of MODE values\n\
-  -R, --recursive         change files and directories recursively\n\
+  -R, --recursive        change files and directories recursively\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
diff --git a/src/chown.c b/src/chown.c
index 4b0bf86..40340ae 100644
--- a/src/chown.c
+++ b/src/chown.c
@@ -86,13 +86,19 @@ Usage: %s [OPTION]... [OWNER][:[GROUP]] FILE...\n\
 Change the owner and/or group of each FILE to OWNER and/or GROUP.\n\
 With --reference, change the owner and group of each FILE to those of RFILE.\n\
 \n\
+"), stdout);
+      fputs (_("\
   -c, --changes          like verbose but report only when a change is made\n\
+  -f, --silent, --quiet  suppress most error messages\n\
+  -v, --verbose          output a diagnostic for every file processed\n\
+"), stdout);
+      fputs (_("\
       --dereference      affect the referent of each symbolic link (this is\n\
                          the default), rather than the symbolic link itself\n\
+  -h, --no-dereference   affect symbolic links instead of any referenced file\n\
 "), stdout);
       fputs (_("\
-  -h, --no-dereference   affect each symbolic link instead of any referenced\n\
-                         file (useful only on systems that can change the\n\
+                         (useful only on systems that can change the\n\
                          ownership of a symlink)\n\
 "), stdout);
       fputs (_("\
@@ -107,14 +113,14 @@ With --reference, change the owner and group of each FILE to those of RFILE.\n\
       --preserve-root    fail to operate recursively on `/'\n\
 "), stdout);
       fputs (_("\
-  -f, --silent, --quiet  suppress most error messages\n\
       --reference=RFILE  use RFILE's owner and group rather than\n\
                          specifying OWNER:GROUP values\n\
+"), stdout);
+      fputs (_("\
   -R, --recursive        operate on files and directories recursively\n\
-  -v, --verbose          output a diagnostic for every file processed\n\
-\n\
 "), stdout);
       fputs (_("\
+\n\
 The following options modify how a hierarchy is traversed when the -R\n\
 option is also specified.  If more than one is specified, only the final\n\
 one takes effect.\n\
-- 
1.7.6.4