doc for --compare-dest could be clearer

[jw schultz]

On Mon, Jun 23, 2003 at 11:12:03PM -0400, Stephen Gildea wrote:
> I have a suggestion for how to make the documentation of rsync's
> "--compare-dest" option clearer.
> 
> Maybe it would be clearer if I had some problem this option would solve,
> but as it is, I couldn't figure it out from the manual.  The description
> in the rsync 2.5.6 manual page starts:

Lets clarify one thing first.  That isn't a manual it is a
manpage.  In manpages we emphasise brevity, listing options
and what they do with key topics also covered.  Somewhat like a
quick reference guide.  They are written primarily for those
who are already familiar with the tool although often may be
the only documentation available.  Implications and indirect
effects are only discussed when necessary.  If you would
like to write a users manual or guide that would be great
and we could refer to that for more extensive discussions of
features.

That said, clarity is of utmost import so suggestions or
patches to improve that are helpful, particularly for those
of us who are too good at understanding the innards to
be troubled by what may be obscure to others.

>     This option instructs rsync to use DIR on the destination machine
>     as an additional directory to compare destination files against
>     when doing transfers if the files are missing in the destination
>     directory.  This is useful for ...
> 
> I figured out what --compare-dest does only after reading Dave Dykstra's
> April 2001 posting in the archives.  He wrote:
> 
>     ... --compare-dest only comes into play when a file does not exist
>     in the target directory....  Any time rsync finds a file with a
>     matching timestamp and size (when not using -I) in either the target
>     or compare-dest directory, it will skip the file.  If it finds a
>     file that does not match the timestamp and size (looking first in
>     target, then in compare-dest), it will then apply the "rsync
>     algorithm" to that file and write output into the target directory.
> 
> Now it's clear: compare-dest is a second place to look when trying to
> find a file to compare with the source when deciding whether to update
> the destination file.  I suggest something like this for the manual:
> 
>     If the destination file does not exist, this option instructs rsync
>     to compare the source file with the corresponding file in DIR before
>     deciding it needs to copy.  If they match, rsync will skip copying
>     the file.  If the destination file exists, it is always used for
>     comparison.

There is a style to manpages and to the rsync manpage in
particular.  Each option definition has an initial
declarative of the option's effect.  While i'm not fond of
rsync's redundant "this option" clause we should stick with
the general formula.  That means that we don't use a
conditional in the subject (indicative).  It would be
permissable in the predicate.  My own opening sentence would
be "This option specifies an alternate directory for
comparison when a file is absent from the destination
directory."  But i don't know if that quite does it for you.

If we had a manual i would add to it something to the effect
that a file in DIR is completely ignored if there is one in
the destination even if the one in DIR is identical to source.

>     This is useful for ...
> 
> The current manual goes on to try to explain what this is useful for,
> but the scenario described doesn't make sense to me; I can't figure out
> what --compare-dest buys you here.  So I cannot offer a specific
> re-write of that part.
> 
> (--link-dest, on the other hand, is quite useful to me.)

I have to agree somewhat regarding the example.  Creating a
sparse tree is the last thing one would want to do for a
instant cutover.  I'd drop the example but add a comment
that the result of using --compare-dest is a sparse tree.

It does strike me that despite the comparative newness of
--link-dest it may be the dominant option.  Perhaps they
should be swapped and compare-dest should be defined
relative to link-dest (doesn't create links).


-- 
________________________________________________________________
	J.W. Schultz            Pegasystems Technologies
	email address:		jw at pegasys.ws

		Remember Cernan and Schmitt