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

[Florian Schlichting]

Hi,

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

Florian