https://bugzilla.samba.org/show_bug.cgi?id=2690
wayned@samba.org changed:
What |Removed |Added
----------------------------------------------------------------------------
Severity|trivial |enhancement
Status|NEW |ASSIGNED
Summary|SYNOPSIS "rsync [OPTION]... |Manpage suggestions
|SRC [SRC]... DEST" incorrect|
------- Additional Comments From wayned@samba.org 2005-05-08 22:13
-------> "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.
--
Configure bugmail: https://bugzilla.samba.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug, or are watching the QA contact.
https://bugzilla.samba.org/show_bug.cgi?id=2690 ------- Additional Comments From Raf_Schietekat@ieee.org 2005-05-09 02:31 ------- (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. -- Configure bugmail: https://bugzilla.samba.org/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the QA contact for the bug, or are watching the QA contact.
https://bugzilla.samba.org/show_bug.cgi?id=2690 ------- Additional Comments From wayned@samba.org 2005-05-09 09:31 ------- 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.) -- Configure bugmail: https://bugzilla.samba.org/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the QA contact for the bug, or are watching the QA contact.