Bug 2690 - Manpage suggestions
Summary: Manpage suggestions
Status: CLOSED FIXED
Alias: None
Product: rsync
Classification: Unclassified
Component: core (show other bugs)
Version: 2.6.4
Hardware: All All
: P3 enhancement (vote)
Target Milestone: ---
Assignee: Wayne Davison
QA Contact: Rsync QA Contact
URL: http://rsync.samba.org/ftp/rsync/rsyn...
Keywords:
Depends on:
Blocks:
 
Reported: 2005-05-08 13:02 UTC by Raf Schietekat
Modified: 2006-03-12 02:56 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Raf Schietekat 2005-05-08 13:02:14 UTC
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".)
Comment 1 Wayne Davison 2005-05-08 22:13:40 UTC
> "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.
Comment 2 Raf Schietekat 2005-05-09 02:31:59 UTC
(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.
Comment 3 Wayne Davison 2005-05-09 09:31:50 UTC
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.)
Comment 4 Raf Schietekat 2005-07-17 02:21:33 UTC
(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.
Comment 5 Wayne Davison 2005-09-21 15:41:34 UTC
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.