Re: please improve the documentation for install --compare (-C)

[Jim Meyering]

Florian Schlichting wrote:
> the -C (or --compare) option is currently not mentioned in the info
> documentation, and in man page it reads:
>
>     compare each pair of source and destination files, and
>     in some cases, do not modify the destination at all
>
> That's not very specific, making -C effectively unuseable. I found a
> nice description of what it does on this list, written by Kamil Dudka
> (http://lists.gnu.org/archive/html/bug-coreutils/2009-01/msg00122.html):
>
>     With this option install checks an existing destination file and if it
>     is not different (by content, owner, group and mode) from source, the
>     file is not installed. Preserving destination's original mtime can
>     significantly decrease time of building when a system library is
>     reinstalled but the header files are not changed at all.
>
> IMHO this is adequate for the info documentation. For the shorter
> manpage, the description could be changed to read:
>
>     compare each pair of source and destination files, and
>     if identical (by content, ownership and mode), do not
>     copy to preserve mtime

Thanks for the suggestion.
How about this?

>From f7d2526c1c6eea4ae92fa1ce0b8a4f507adcf214 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Thu, 3 Sep 2009 17:28:33 +0200
Subject: [PATCH] doc: improve install --help's description of --compare (-C)

* src/install.c (usage): Improve description of -C option,
based on a suggestion from Florian Schlichting.
---
 src/install.c |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/src/install.c b/src/install.c
index fafa21a..80cc5ef 100644
--- a/src/install.c
+++ b/src/install.c
@@ -964,7 +964,8 @@ Mandatory arguments to long options are mandatory for short 
options too.\n\
   -b                  like --backup but does not accept an argument\n\
   -c                  (ignored)\n\
   -C, --compare       compare each pair of source and destination files, and\n\
-                        in some cases, do not modify the destination at all\n\
+                        if they have identical content, owner, group and 
mode,\n\
+                        do not modify the destination at all\n\
   -d, --directory     treat all arguments as directory names; create all\n\
                         components of the specified directories\n\
 "), stdout);
--
1.6.4.2.395.ge3d52