The rsync man page SYNOPSIS line "rsync [OPTION]... SRC [SRC]... DEST" must be "rsync [OPTION]... SRC [SRC]... [DEST]" instead (for listing remote files). While I'm here, the SYNOPSIS seems less confusing this way (easier to see the pattern): rsync [OPTION]... SRC [SRC]... DEST rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST rsync [OPTION]... [USER@]HOST:SRC [DEST] rsync [OPTION]... [USER@]HOST::SRC [DEST] rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] Likewise, GENERAL requires the reader to carefully read everything and try to induce the logic behind it. It would be better if the reader would only need to use deduction instead. There's also the mismatch between :: equals rsync: for direct communication and only :: when using a remote shell to complicate matters. (This report's rsync version may be irrelevant, the man page mentions "30 Mar 2005".)
> "rsync [OPTION]... SRC [SRC]... [DEST]" instead (for listing remote files). No, that synopsis line is for a local copy, so the DEST is not optional (at least, not without changing rsync). All the remote-host accessing commands include a HOST on their synopsis line. As for the change of order of all the lines, I'll consider changing that. Can you clarify what you mean about the GENERAL section? Also, I think the mismatch comment is referring to an older restriction where an rsync://host/ URL would not use a remote shell (when specified) to start a fresh rsync daemon (like :: would do), but that is no longer the case in 2.6.4.
(In reply to comment #1) > > "rsync [OPTION]... SRC [SRC]... [DEST]" instead (for listing remote files). > > No, that synopsis line is for a local copy, so the DEST is not optional (at > least, not without changing rsync). All the remote-host accessing commands > include a HOST on their synopsis line. Sorry, I was probably already half asleep (different timezone): I meant "rsync [OPTION]... [USER@]HOST:SRC DEST", which must be "rsync [OPTION]... [USER@]HOST:SRC [DEST]". > >[...] > > Can you clarify what you mean about the GENERAL section? If you already know rsync, it's probably quite clear. Otherwise, from a technical writing point of view, it's too much work, relatively speaking, for the reader who doesn't know what rsync is all about to reason his way from a list of particular applications back to the big picture ("oh, why didn't they just say that?"). Of course, a man page is a reference, not a tutorial, but even as a reference there's little use for this reading fodder (which also seems to duplicates SYNOPSIS, but not quite, so what are the differences... and the work load increases yet again). I haven't included a rewriting attempt because a refusal then would be too cruel to suffer. :-) > > Also, I think the mismatch comment is referring to an older restriction where > an rsync://host/ URL would not use a remote shell (when specified) to start a > fresh rsync daemon (like :: would do), but that is no longer the case in > 2.6.4. Then GENERAL needs to be updated for that, because on items 4 and 5 it mentions :: or rsync:, and on items 6 and 7 it only mentions ::. Also, it suggests the exact opposite of your comment here ("using a remote shell program as the transport [to get through a firewall], using [a preexisting] rsync server on the remote machine"), not starting up a new server (not technically a persisting "daemon" as you write here, right?) at the remote end to communicate directly with that server's very own port (for efficiency, right?), which does seem to make more sense (it would require some further study to outright dismiss the first option, which might be relevant because of privileges issues, not unlike for a database server). It all matters for those who need to read this material. Not wholly unimportant either is the presentation on <http://rsync.samba.org/documentation.html>: why is the FAQ listed first, then a README, then the original technical report, and only then the man page? It seems better to direct the reader to either README or man page first (although, aren't they redundant, can't a user do without the README and know so... before having read it?), FAQ second, and technical report last. BTW, thanks for maintaining this software, I think I'll find it quite useful. Luckily it was pointed out to me before I started trying to write something like that myself. Which brings me to an additional question: it is not immediately clear whether rsync looks at the set of files as a whole or only considers them one pair at a time, which is relevant for knowing how efficiently it deals, e.g., with big, slightly modified files that were also renamed.
Thanks for the additional clarifications. I've just checked in a fix for the non-optional [DEST] in the appropriate files (since it was also wrong in the help text). I'm rewriting the GENERAL section to make it better. What do you think of this (raw yodl formatting follows, which is pretty close to plain text): ------------------------------------------------------------------------- Rsync copies files either to or from a remote host, or locally on the current host (it does not support copying files between two remote hosts). There are two different ways for rsync to contact a remote system: using a remote-shell program as the transport (such as ssh or rsh) or contacting an rsync daemon directly via TCP. The remote-shell transport is used whenever the source or destination path contains a single colon (:) separator after a host specification. Contacting an rsync daemon directly happens when the source or destination path contains a double colon (::) separator after a host specification, OR when an rsync:// URL is specified. As a special case, if a remote source is specified without a destination, the remote files are listed in an output format similar to "ls -l". As expected, if neither the source or destination path specify a remote host, the copy occurs locally (see also the bf(--list-only) option). Finally, it is possible to use a remote-shell transport to contact a remote host and then to spawn a single-use rsync daemon for those that want to make use of some of the daemon features (such as named modules) without having to run a daemon as a service. This occurs when rsync is invoked with an explicit bf(--rsh=COMMAND) (aka "bf(-e COMMAND)") option and either the source or destination path specifies an rsync daemon (e.g. either a :: separator or an rsync:// URL). In this case, rsync contacts the remote host specified using the specified remote shell, and then starts a single-use rsync daemon to deal with that copy request. ------------------------------------------------------------------------- (I'm also improving the --list-only option to make it clearer how it works to list the files in a local copy.) I've updated the documentation.html page -- thanks for the ideas. I'd suggest asking your final question on the mailing list, since bugzilla isn't really the place to have such a discussion. (See also the --fuzzy option.)
(In reply to comment #3) Great! BTW, sorry for not replying sooner. --- > There are two different ways for rsync to contact a remote system: using a > remote-shell program as the transport (such as ssh or rsh) or contacting an > rsync daemon directly via TCP. How about "mainly two" instead of just "two"? Better to forewarn the reader that this is not the whole picture yet. --- > Finally, it is possible to use a remote-shell transport to contact a remote > host and then to spawn a single-use rsync daemon for those that want to Throughout the documentation, it seems better not to say "daemon" when this rather well-defined Unix concept does not apply. The word "server" probably serves the general purpose equally well: "without having to run a daemon as a service" (in the quoted text) would then become "without having to run a server as a daemon" (on MS Windows o.t.o.h., "service" would indeed substitute for "daemon" in the corrected phrase). > make use of some of the daemon features (such as named modules) without > having to run a daemon as a service.
I just checked-in the reordering of the synopsis (usage) section, since it does read better that way. The suggestion for changing daemon to server is not desired because even a non-daemon connection spawns a server rsync and we're trying to distinguish between them.