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 rsync.
/a
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.
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
-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
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.
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
+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.
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).
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:
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
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.
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 allows/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 defaultPulling 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 filenameAdding 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@pegasys.ws Remember Cernan and Schmitt
On Fri, Jan 23, 2004 at 01:43:41AM -0800, Wayne Davison wrote:> On Thu, Jan 22, 2004 at 06:50:35PM -0800, jw schultz wrote: > > I'd leave it as is except to replace the paranthetic with > > the text regarding --numeric-ids in the --owner section > > Unfortunately the text in the --owner section is wrong -- the > --numeric-ids option is not implied by anything. If the chroot > area contains its own etc/passwd and etc/group files, the names > will be mapped even when chroot is enabled. I've updated the > sections on --owner, --group, --numeric-ids, and the "use chroot" > setting. See how you like it.You are right, it isn't "implied"; it is "compelled" unless the configuration allows name and ID lookups. The only objection i have to your --owner, and --group text is "The preservation is done primarily by name". It is only primarily by name when --numeric-ids isn't selected and passwd and group lookup is possible. I say "passwd and group lookup is possible" and not that "/etc/passwd and /etc/group files are readable" because the precise behaviour is dependant on the libraries and most often /etc/nsswitch.conf (if readable). On FreeBSD it is pwd.db that has to be readable. People using NIS or, i assume, LDAP don't need passwd and group files so don't need to keep them up-to-date. As i think about it i'm inclined to suggest we put only a reference to --numeric-ids in the --owner and --group sections and put a more detailed description in the --numeric-ids section. The more detailed description in --numeric-ids (as a central point for the rsync.1 manpage) could cover the issue of names that aren't on both ends and files owned by IDs not in the database, much as it does already. It also should perhaps not go into chroot issues but merely reference the chroot section of rsyncd.conf.5 with a mention that rsync daemons might not be configured to support ID preservation by name. The chroot section of rsync.conf.5 could cover the issue of database availability for name<->ID lookups. As i think on it if we refer to the issue as being of identification database availability instead of specific files in /etc the text gets much simpler, more portable, and might be included on both manpages. -- ________________________________________________________________ J.W. Schultz Pegasystems Technologies email address: jw@pegasys.ws Remember Cernan and Schmitt
On Fri, 23 Jan 2004, jw schultz scribbled:> 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. > > Let's keep the examples in the example, description order.this seems to have been taken up later in the thread and is not included in the patch below.> 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.Here are residual fixes from my initial patch for rsync.yo against version 1.144 (I noticed 1.145 was just checked-in. the patch still worked for me.) Whitespace-only changes were minimized (couldn't get diff's -w and -b options working to my liking, any suggestions?) again: Make sure I didn't confuse the exclude list/file paragraph (line ~969 after applying the patch), I haven't used the feature and the details of that paragraph are a tad unclear. responses to J.W. Schultz below. patch at very bottom of message and at: http://www.uvm.edu/~ashawley/rsync/rsync.yo-1.144-ashawley.diff-u /a> 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.I went with (:), seemed to be the choice of a few other man pages.> "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)Don't have a copy of Chicago Manual of Style handy, but the google test gave me "file systems". Those fixes are removed from the initial patch.> 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.agreed. not in patch.> 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.went with last in patch.> > - *?[ 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.in patch. speaking of which: Index: rsync.yo ==================================================================RCS file: /cvsroot/rsync/rsync.yo,v retrieving revision 1.144 diff -u -r1.144 rsync.yo --- rsync.yo 23 Jan 2004 09:34:04 -0000 1.144 +++ rsync.yo 23 Jan 2004 16:19:31 -0000 @@ -48,35 +48,35 @@ 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. 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 an 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 an 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 + 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 @@ -134,7 +134,7 @@ 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 +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 @@ -145,7 +145,7 @@ 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 +destination don't have a colon (:) in the name. This behaves like an improved copy command. quote(rsync somehost.mydomain.com::) @@ -169,8 +169,8 @@ that: itemize( - it() you use a double colon :: instead of a single colon to - separate the hostname from the path or an rsync:// URL. + it() you use a double colon (::) instead of a single colon (:) to + separate the hostname from the path or an rsync:// URL. it() the remote server may print a message of the day when you connect. @@ -261,10 +261,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") @@ -677,8 +677,8 @@ 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 +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 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 @@ -688,15 +688,15 @@ you want it. 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 +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 +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 @@ -705,7 +705,7 @@ 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: quote(rsync -a --files-from=:/path/file-list src:/ /tmp/copy) @@ -918,48 +918,49 @@ itemize( - it() if the pattern starts with a / then it is matched against the + 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 ^ in regular expressions. + 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 + bf(*?[) then expression matching is applied using the shell filename 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 "**" + 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 / or a "**", then it is + 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) + 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 "+ " part is discarded before matching. + part of an exclude option. The plus-space (+ ) part is discarded before matching. - it() if the pattern starts with "- " (a minus followed by a space) + 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. + part of an include option. The minus-space (- ) 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 +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. @@ -1094,8 +1095,9 @@ 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) @@ -1130,10 +1132,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 specifed 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 I/O @@ -1201,7 +1203,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) @@ -1214,7 +1216,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.