rsync.yo doc patch
jw schultz
jw at pegasys.ws
Fri Jan 23 01:13:33 GMT 2004
On Thu, Jan 22, 2004 at 07:00:17PM -0500, Aaron S. Hawley wrote:
> Patch includes fixes to man page including:
> - Typos/Spelling
> - Clarity
> - Special characters.
> - Moved around text explaining example.
>
> Make sure I didn't confuse the exclude list/file paragraph (line ~961
> after applying the patch), I haven't used the feature and the motive of
> that paragraph is a tad unclear.
>
> Hope the patch is helpful.
> Never had used yodl before.
Thanks for the patch.
Let's keep the examples in the example, description order.
There appear to be whitespace-only changes. If changing the
location of line breaks in the source do that as a seperate
patch so labeled. Then the actual text changes can be
considered.
There are more notes below but i've not reviewe the entire
patch because of the whitespace changes.
> http://www.uvm.edu/~ashawley/rsync/rsync.yo-ashawley.diff-u
>
> Index: rsync.yo
> ===================================================================
> RCS file: /cvsroot/rsync/rsync.yo,v
> retrieving revision 1.139
> diff -u -r1.139 rsync.yo
> --- rsync.yo 15 Jan 2004 17:45:53 -0000 1.139
> +++ rsync.yo 22 Jan 2004 23:52:11 -0000
> @@ -48,36 +48,36 @@
>
> itemize(
> it() for copying local files. This is invoked when neither
> - source nor destination path contains a : separator
> + source nor destination path contains a single colon (":") separator
>
> it() for copying from the local machine to a remote machine using
> a remote shell program as the transport (such as ssh or
> rsh). This is invoked when the destination path contains a
> - single : separator.
> + single colon (":") separator.
Parens or quotes but not both, please. I find the : or ::
set off by spaces to be perfectly clear, a bit easier to
read and have had some cases (not here) where there was some
doubt whether the surrounding characters intended as quotes
might not be part of the string. But if people want ":" or (:)
or even <:> i can live with it.
>
> it() for copying from a remote machine to the local machine
> using a remote shell program. This is invoked when the source
> - contains a : separator.
> + contains a single colon (":") separator.
>
> it() for copying from a remote rsync server to the local
> - machine. This is invoked when the source path contains a ::
> + machine. This is invoked when the source path contains a double colon ("::")
> separator or a rsync:// URL.
>
> it() for copying from the local machine to a remote rsync
> - server. This is invoked when the destination path contains a ::
> + server. This is invoked when the destination path contains a double colon ("::")
> separator or a rsync:// URL.
>
> it() for copying from a remote machine using a remote shell
> program as the transport, using rsync server on the remote
> - machine. This is invoked when the source path contains a ::
> + machine. This is invoked when the source path contains a double colon ("::")
> separator and the --rsh=COMMAND (aka "-e COMMAND") option is
> also provided.
>
> it() for copying from the local machine to a remote machine
> using a remote shell program as the transport, using rsync
> server on the remote machine. This is invoked when the
> - destination path contains a :: separator and the
> - --rsh=COMMMAND option is also provided.
> + destination path contains a double colon ("::") separator and the
> + --rsh=COMMAND option is also provided.
>
> it() for listing files on a remote machine. This is done the
> same way as rsync transfers except that you leave off the
> @@ -111,7 +111,7 @@
> You use rsync in the same way you use rcp. You must specify a source
> and a destination, one of which may be remote.
>
> -Perhaps the best way to explain the syntax is some examples:
> +Perhaps the best way to explain the syntax is with some examples:
>
> quote(rsync *.c foo:src/)
>
> @@ -121,38 +121,39 @@
> remote-update protocol is used to update the file by sending only the
> differences. See the tech report for details.
>
> +This would recursively transfer all files from the directory src/bar on the
> +machine foo into the /data/tmp/bar directory on the local machine.
> +
> quote(rsync -avz foo:src/bar /data/tmp)
>
> -This would recursively transfer all files from the directory src/bar on the
> -machine foo into the /data/tmp/bar directory on the local machine. The
> -files are transferred in "archive" mode, which ensures that symbolic
> -links, devices, attributes, permissions, ownerships etc are preserved
> -in the transfer. Additionally, compression will be used to reduce the
> -size of data portions of the transfer.
> +The files are transferred in "archive" mode, which ensures that
> +symbolic links, devices, attributes, permissions, ownerships etc are
> +preserved in the transfer. Additionally, compression will be used to
> +reduce the size of data portions of the transfer.
> +A trailing slash on the source changes this behavior to avoid creating an
> +additional directory level at the destination.
>
> quote(rsync -avz foo:src/bar/ /data/tmp)
>
> -A trailing slash on the source changes this behavior to avoid creating an
> -additional directory level at the destination. You can think of a trailing
> -/ on a source as meaning "copy the contents of this directory" as opposed
> -to "copy the directory by name", but in both cases the attributes of the
> -containing directory are transferred to the containing directory on the
> -destination. In other words, each of the following commands copies the
> -files in the same way, including their setting of the attributes of
> -/dest/foo:
> +You can think of a trailing slash ("/") on a source as meaning "copy the
> +contents of this directory" as opposed to "copy the directory by
> +name", but in both cases the attributes of the containing directory
> +are transferred to the containing directory on the destination. In
> +other words, each of the following commands copies the files in the
> +same way, including their setting of the attributes of /dest/foo:
>
> quote(rsync -avz /src/foo /dest)
> quote(rsync -avz /src/foo/ /dest/foo)
>
> You can also use rsync in local-only mode, where both the source and
> -destination don't have a ':' in the name. In this case it behaves like
> -an improved copy command.
> -
> -quote(rsync somehost.mydomain.com::)
> +destination don't have a colon (":") in the name. This behaves like an
> +improved copy command.
>
> This would list all the anonymous rsync modules available on the host
> somehost.mydomain.com. (See the following section for more details.)
>
> +quote(rsync somehost.mydomain.com::)
>
> manpagesection(CONNECTING TO AN RSYNC SERVER)
>
> @@ -163,14 +164,14 @@
> You may establish the connection via a web proxy by setting the
> environment variable RSYNC_PROXY to a hostname:port pair pointing to
> your web proxy. Note that your web proxy's configuration must allow
s/allow/support/ It isn't a passive thing.
> -proxying to port 873.
> +proxy connections to port 873.
>
> Using rsync in this way is the same as using it with a remote shell except
> that:
>
> itemize(
> - it() you use a double colon :: instead of a single colon to
> - separate the hostname from the path or a rsync:// URL.
> + it() you use a double colon ("::") instead of a single colon
> + (":") to separate the hostname from the path or a rsync:// URL.
>
> it() the remote server may print a message of the day when you
> connect.
> @@ -217,7 +218,7 @@
>
> manpagesection(RUNNING AN RSYNC SERVER)
>
> -An rsync server is configured using a config file. Please see the
> +An rsync server is configured using a configuration file. Please see the
> rsyncd.conf(5) man page for more information. By default the configuration
> file is called /etc/rsyncd.conf, unless rsync is running over a remote
> shell program and is not running as root; in that case, the default name
> @@ -261,10 +262,10 @@
> sync: get put)
>
> this allows me to sync with a CVS directory at the other end of the
> -connection. I then do cvs operations on the remote machine, which saves a
> -lot of time as the remote cvs protocol isn't very efficient.
> +connection. I then do CVS operations on the remote machine, which saves a
> +lot of time as the remote CVS protocol isn't very efficient.
>
> -I mirror a directory between my "old" and "new" ftp sites with the
> +I mirror a directory between my "old" and "new" FTP sites with the
> command
>
> quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
> @@ -395,7 +396,7 @@
> the timestamps as being equal if they are within the value of
> modify_window. This is normally zero, but you may find it useful to
> set this to a larger value in some situations. In particular, when
> -transferring to Windows FAT filesystems which cannot represent times
> +transferring to Windows FAT file systems which cannot represent times
"Filesystems" is correct usage. It might not be in your
spelling dictionary but is correct and semantically distinct
from "file systems". Even if it weren't for the semantic
difference this closed compound sould be consistant with the
Chicago Manual of Style (7.84)
> with a 1 second resolution --modify-window=1 is useful.
>
> dit(bf(-c, --checksum)) This forces the sender to checksum all files using
> @@ -514,7 +515,7 @@
> destination file to be the same as the source file. On most systems,
> only the super-user can set file ownership. Note that if the remote system
> is a daemon using chroot, the --numeric-ids option is implied because the
> -remote system cannot get access to the usernames from /etc/passwd.
> +remote system cannot get access to the user names from /etc/passwd.
Again, This is correct usage.
user name: George Washington
username: gwashin
Rsync is not going to extract user names from the comment
field and try to match them.
>
> dit(bf(-g, --group)) This option causes rsync to set the group of the
> destination file to be the same as the source file. If the receiving
> @@ -602,7 +603,7 @@
> default, but you may prefer to use rsh on a local network.
>
> If this option is used with bf([user@]host::module/path), then the
> -remote shell em(COMMMAND) will be used to run an rsync server on the
> +remote shell em(COMMAND) will be used to run an rsync server on the
> remote host, and all data will be transmitted through that remote
> shell connection, rather than through a direct socket connection to a
> running rsync server on the remote host. See the section "CONNECTING
> @@ -672,35 +673,36 @@
> If em(FILE) is bf(-) the list will be read from standard input.
>
> dit(bf(--files-from=FILE)) Using this option allows you to specify the
> -exact list of files to transfer (as read from the specified FILE or "-"
> -for stdin). It also tweaks the default behavior of rsync to make
> -transferring just the specified files and directories easier. For
> -instance, the --relative option is enabled by default when this option
> -is used (use --no-relative if you want to turn that off), all
> -directories specified in the list are created on the destination (rather
> -than being noisily skipped without -r), and the -a (--archive) option's
> -behavior does not imply -r (--recursive) -- specify it explicitly, if
> -you want it.
> +exact list of files to transfer as read from the specified FILE or if
> +a dash ("-") from standard input (stdin). It also tweaks the default
Pulling that out of the parenthetic is good but the choice
of term is one of:
stdin
standard input
stdin (standard input)
The last one only the first time stdin is used.
> +behavior of rsync to make transferring just the specified files and
> +directories easier. For instance, the --relative option is enabled by
> +default when this option is used (use --no-relative if you want to
> +turn that off), all directories specified in the list are created on
> +the destination (rather than being noisily skipped without -r), and
> +the -a (--archive) option's behavior does not imply -r (--recursive)
> +-- specify it explicitly, if you want it.
You haven't changed the description of the "tweaks" as far
as i can see but that whole section could do with an
adjustment.
It also alters the default behavior of rsync to make
transferring just the specified files and directories easier.
Specifically, the --relative option is enabled by default when this option
is used (use --no-relative if you want to turn that off), all
directories specified in the list are created on the destination (rather
than being noisily skipped without -r), and the -a (--archive) option's
behavior does not imply --recursive (specify it explicitly, if
you want it).
Note: em dashes (with no surrounding space) should be used instead
of parenthasees but i don't know yodl.
>
> The file names that are read from the FILE are all relative to the
> -source dir -- any leading slashes are removed and no ".." references are
> -allowed to go higher than the source dir. For example, take this
> -command:
> +source directory -- any leading slashes are removed and no parent
> +directory ("..") references are allowed to go higher than the source
> +directory. For example, take this command:
>
> quote(rsync -a --files-from=/tmp/foo /usr remote:/backup)
>
> If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
> directory will be created as /backup/bin on the remote host (but the
> -contents of the /usr/bin dir would not be sent unless you specified -r
> -or the names were explicitly listed in /tmp/foo). Also keep in mind
> -that the effect of the (enabled by default) --relative option is to
> -duplicate only the path info that is read from the file -- it does not
> -force the duplication of the source-spec path (/usr in this case).
> +contents of the /usr/bin directory would not be sent unless you
> +specified -r or the names were explicitly listed in /tmp/foo). Also
> +keep in mind that the effect of the (enabled by default) --relative
> +option is to duplicate only the path info that is read from the file
> +-- it does not force the duplication of the source-spec path (/usr in
> +this case).
Please make the minimum number of line-break changes. I
don't mind a short line here and there but trying to spot
the changes by comparing word-for-word is more work that it
is worth. On that score i would have to reject this change.
>
> In addition, the --files-from file can be read from the remote host
> instead of the local host if you specify a "host:" in front of the file
> (the host must match one end of the transfer). As a short-cut, you can
> -specify just a prefix of ":" to mean "use the remote end of the
> +specify just a prefix of colon (":") to mean "use the remote end of the
> transfer". For example:
Here you have the one case where adding parenthasees around
it made sense. That being because it became a parenthetic.
>
> quote(rsync -a --files-from=:/path/file-list src:/ /tmp/copy)
> @@ -867,7 +869,7 @@
> using rsync with large files (several megabytes and up). Due to the nature
> of rsync transfers, blocks of data are sent, then if rsync determines the
> transfer was too fast, it will wait before sending the next data block. The
> -result is an average transfer rate equalling the specified limit. A value
> +result is an average transfer rate equaling the specified limit. A value
> of zero specifies no limit.
>
> dit(bf(--write-batch=PREFIX)) Generate a set of files that can be
> @@ -912,50 +914,53 @@
>
> itemize(
>
> - it() if the pattern starts with a / then it is matched against the
> - start of the filename, otherwise it is matched against the end of
> - the filename.
> - This is the equivalent of a leading ^ in regular expressions.
> + it() if the pattern starts with a slash ("/") then it is matched
> + against the start of the filename, otherwise it is matched against
> + the end of the filename.
> + This is the equivalent of a leading caret ("^") in regular expressions.
> Thus "/foo" would match a file called "foo" at the top of the
> transferred tree.
> On the other hand, "foo" would match any file called "foo"
> anywhere in the tree because the algorithm is applied recursively from
> top down; it behaves as if each path component gets a turn at being the
> end of the file name.
> - The leading / does not make the pattern an absolute pathname.
> + The leading slash ("/") does not make the pattern an absolute pathname.
>
> - it() if the pattern ends with a / then it will only match a
> + it() if the pattern ends with a slash ("/") then it will only match a
> directory, not a file, link or device.
>
> it() if the pattern contains a wildcard character from the set
> - *?[ then expression matching is applied using the shell filename
> + "*?[" then expression matching is applied using the shell filename
Adding quotes here confuses the issue. The one thing that
might be done is to make the wildcard character list in
boldface as a literal expression.
> matching rules. Otherwise a simple string match is used.
>
> - it() the double asterisk pattern "**" will match slashes while a
> - single asterisk pattern "*" will stop at slashes.
> + it() the double asterisk pattern ("**") will match slashes while a
> + single asterisk pattern ("*") will stop at slashes.
>
> - it() if the pattern contains a / (not counting a trailing /) or a "**"
> - then it is matched against the full filename, including any leading
> - directory. If the pattern doesn't contain a / or a "**", then it is
> + it() if the pattern contains a slash ("/") (not counting a trailing
> + slash) or a double asterisk ("**") then it is matched against the full
> + filename, including any leading directory. If the pattern doesn't
> + contain a slash ("/") or a double asterisk ("**"), then it is
> matched only against the final component of the filename. Again,
> remember that the algorithm is applied recursively so "full filename" can
> actually be any portion of a path below the starting directory.
>
> - it() if the pattern starts with "+ " (a plus followed by a space)
> - then it is always considered an include pattern, even if specified as
> - part of an exclude option. The "+ " part is discarded before matching.
> -
> - it() if the pattern starts with "- " (a minus followed by a space)
> - then it is always considered an exclude pattern, even if specified as
> - part of an include option. The "- " part is discarded before matching.
> + it() if the pattern starts with plus-space ("+ ")--a plus followed
> + by a space--then it is always considered an include pattern, even if
> + specified as part of an exclude option. The plus-space ("+ ") part
> + is discarded before matching.
> +
> + it() if the pattern starts with minus-space ("- ")--a minus followed
> + by a space--then it is always considered an exclude pattern, even if
> + specified as part of an include option. The "- " part is discarded
> + before matching.
>
> - it() if the pattern is a single exclamation mark ! then the current
> + it() if the pattern is a single exclamation mark ("!") then the current
> include/exclude list is reset, removing all previously defined patterns.
> )
>
> -The +/- rules are most useful in a list that was read from a file, allowing
> -you to have a single exclude list that contains both include and exclude
> -options.
> +The plus-space ("+ ") and minus-space ("- ") rules are most useful in
> +a list that was read from a file, allowing you to have a single
> +exclude list that contains both include and exclude options.
>
> If you end an exclude list with --exclude '*', note that since the
> algorithm is applied recursively that unless you explicitly include
> @@ -1085,11 +1090,12 @@
> bf(/etc/passwd) in the public section of the site. Using
> bf(--copy-unsafe-links) will cause any links to be copied as the file
> they point to on the destination. Using bf(--safe-links) will cause
> -unsafe links to be ommitted altogether.
> +unsafe links to be omitted altogether.
>
> Symbolic links are considered unsafe if they are absolute symlinks
> -(start with bf(/)), empty, or if they contain enough bf("..")
> -components to ascend from the directory being copied.
> +(start with a slash ("bf(/)")), empty, or if they contain enough
> +parent directory (bf("..")) components to ascend from the directory
> +being copied.
>
> manpagesection(DIAGNOSTICS)
>
> @@ -1124,10 +1130,10 @@
> dit(bf(0)) Success
> dit(bf(1)) Syntax or usage error
> dit(bf(2)) Protocol incompatibility
> -dit(bf(3)) Errors selecting input/output files, dirs
> +dit(bf(3)) Errors selecting input/output files, directories
> dit(bf(4)) Requested action not supported: an attempt
> was made to manipulate 64-bit files on a platform that cannot support
> -them; or an option was speciifed that is supported by the client and
> +them; or an option was specified that is supported by the client and
> not by the server.
> dit(bf(5)) Error starting client-server protocol
> dit(bf(10)) Error in socket IO
> @@ -1165,7 +1171,7 @@
> password to a shell transport such as ssh.
>
> dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
> -are used to determine the default username sent to a rsync server.
> +are used to determine the default user name sent to a rsync server.
>
> dit(bf(HOME)) The HOME environment variable is used to find the user's
> default .cvsignore file.
> @@ -1186,7 +1192,7 @@
>
> times are transferred as unix time_t values
>
> -When transferring to FAT filesystmes rsync may resync
> +When transferring to FAT file systems rsync may resync
> unmodified files.
> See the comments on the --modify-window option.
>
> @@ -1195,7 +1201,7 @@
>
> see also the comments on the --delete option
>
> -Please report bugs! See the website at
> +Please report bugs! See the web site at
> url(http://rsync.samba.org/)(http://rsync.samba.org/)
>
> manpagesection(CREDITS)
> @@ -1208,7 +1214,7 @@
> includes an FAQ-O-Matic which may cover questions unanswered by this
> manual page.
>
> -The primary ftp site for rsync is
> +The primary FTP site for rsync is
> url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
>
> We would be delighted to hear from you if you like this program.
> --
> To unsubscribe or change options: http://lists.samba.org/mailman/listinfo/rsync
> Before posting, read: http://www.catb.org/~esr/faqs/smart-questions.html
>
--
________________________________________________________________
J.W. Schultz Pegasystems Technologies
email address: jw at pegasys.ws
Remember Cernan and Schmitt
More information about the rsync
mailing list