exclude confusion: what does it match against?

[Andrew Pimlott]

The exact filename tested against include/exclude patterns is not always
obvious, and the documentation is somewhat ambiguous about it.  This
bites particularly when using patterns starting with '/'.  I just spent
an hour being confused by this.  Here are some suggested edits to the
documentation.

Current:

    The filenames matched against the exclude/include patterns are
    relative to the destination directory, or "top directory", so
    patterns should not include the path elements of the source or
    destination directories.  The only way in which a pattern will match
    the absolute path of a file or directory is if the source path is
    the root directory.

The first sentence up to the comma is (AFAICT) exactly accurate.  The
term "top directory" is vague and superfluous; stick with destination
directory.  The warning against including the source directory is
totally wrong when using --relative, and is even partly wrong for source
files that don't end with '/' (because then the last component of the
source is in the destination tree).  The last sentence is wrong with
--relative.

Suggested:

    The filenames matched against the exclude/include patterns are
    relative to the destination directory.  Note that different amounts
    of the source filename may be included, depending on how rsync is
    invoked.  For example, if you have a file /home/me/foo/bar, then for
    the rsync commands

        rsync -a /home/me /dest
        rsync -a /home/me/ /dest
        rsync -a --relative /home/me /dest

    this file is matched against as

        /me/foo/bar
        /foo/bar
        /home/me/foo/bar

    respectively.  The difference is particularly important when you use
    patterns starting with / (see below).

In the rest of the section, there is a reference to the "transferred
tree" (which is wrong) and three references to the "top directory"
(which, as above, is vague).  I think it would be better to say
"destination tree" and "destination directory".

Andrew