[Bug 2690] Manpage suggestions

[samba-bugs at samba.org]

https://bugzilla.samba.org/show_bug.cgi?id=2690





------- Additional Comments From Raf_Schietekat at 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.