[SCM] The rsync repository. - branch master updated
Rsync CVS commit messages
rsync-cvs at lists.samba.org
Sun Jan 16 00:39:35 UTC 2022
The branch, master has been updated
via 995ce719 Man page improvments, including html cross-links.
from 38ffa522 A few more man page format tweaks.
https://git.samba.org/?p=rsync.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit 995ce7198bbc4cbb05ebfc3ed6e14e7574c8dc39
Author: Wayne Davison <wayne at opencoder.net>
Date: Sat Jan 15 15:48:14 2022 -0800
Man page improvments, including html cross-links.
-----------------------------------------------------------------------
Summary of changes:
md-convert | 94 ++-
rsync-ssl.1.md | 7 +-
rsync.1.md | 1574 +++++++++++++++++++++++++++------------------------
rsyncd.conf.5.md | 131 +++--
support/rrsync.1.md | 24 +
5 files changed, 1006 insertions(+), 824 deletions(-)
Changeset truncated at 500 lines:
diff --git a/md-convert b/md-convert
index 70ad9b1f..f95f34b7 100755
--- a/md-convert
+++ b/md-convert
@@ -114,6 +114,8 @@ NBR_SPACE = ('\xa0', r"\ ")
md_parser = None
env_subs = { }
+warning_count = 0
+
def main():
for mdfn in args.mdfiles:
parse_md_file(mdfn)
@@ -231,6 +233,8 @@ class TransformHtml(HTMLParser):
def __init__(self, fi):
HTMLParser.__init__(self, convert_charrefs=True)
+ self.fn = fi.fn
+
st = self.state = argparse.Namespace(
list_state = [ ],
p_macro = ".P\n",
@@ -243,6 +247,13 @@ class TransformHtml(HTMLParser):
man_out = [ ],
txt = '',
want_manpage = fi.want_manpage,
+ created_hashtags = set(),
+ derived_hashtags = set(),
+ referenced_hashtags = set(),
+ bad_hashtags = set(),
+ prior_target = None,
+ opt_prefix = 'opt',
+ a_txt_start = None,
)
if st.want_manpage:
@@ -265,6 +276,20 @@ class TransformHtml(HTMLParser):
fi.man_out = ''.join(st.man_out)
st.man_out = None
+ for href, txt in st.derived_hashtags:
+ derived = txt2target(txt, href[1:])
+ if derived not in st.created_hashtags:
+ txt = re.sub(r'[\1-\7]+', '', txt.replace(NBR_DASH[0], '-').replace(NBR_SPACE[0], ' '))
+ warn('Unknown derived hashtag link in', self.fn, 'based on:', (href, txt))
+
+ for bad in st.bad_hashtags:
+ if bad in st.created_hashtags:
+ warn('Missing "#" in hashtag link in', self.fn + ':', bad)
+ else:
+ warn('Unknown non-hashtag link in', self.fn + ':', bad)
+
+ for bad in st.referenced_hashtags - st.created_hashtags:
+ warn('Unknown hashtag link in', self.fn + ':', '#' + bad)
def handle_starttag(self, tag, attrs_list):
st = self.state
@@ -333,24 +358,23 @@ class TransformHtml(HTMLParser):
st.man_out.append(".l\n")
st.html_out.append("<hr />")
return
+ elif tag == 'a':
+ st.a_href = None
+ for var, val in attrs_list:
+ if var == 'href':
+ if val in ('#', '#opt', '#daemon-opt'):
+ st.a_href = val
+ elif val.startswith('#'):
+ st.referenced_hashtags.add(val[1:])
+ if val[1:] == st.prior_target:
+ warn('Found link to the current section in', self.fn + ':', val)
+ elif not val.startswith(('https://', 'http://', 'mailto:', 'ftp:', './')):
+ st.bad_hashtags.add(val)
+ st.a_txt_start = len(st.txt)
st.html_out.append('<' + tag + ''.join(' ' + var + '="' + htmlify(val) + '"' for var, val in attrs_list) + '>')
st.at_first_tag_in_dd = False
- def add_target(self, txt):
- st = self.state
- txt = re.sub(r'[%s](.+?)[=%s].*' % (BOLD_FONT[0], NORM_FONT[0]), r'\1', txt.strip())
- txt = re.sub(r'[%s]' % NBR_DASH[0], '-', txt)
- txt = re.sub(r'[\1-\7]+', '', txt)
- txt = re.sub(r'[^-A-Za-z0-9._]', '_', txt)
- if txt.startswith('-'):
- txt = 'opt' + txt
- else:
- txt = re.sub(r'^([^A-Za-z])', r't\1', txt)
- if txt:
- st.html_out.append('<a id="' + txt + '" href="#' + txt + '" class="tgt"></a>')
-
-
def handle_endtag(self, tag):
st = self.state
if args.debug:
@@ -364,6 +388,7 @@ class TransformHtml(HTMLParser):
if tag == 'h1' or tag == 'h2':
st.man_out.append(st.p_macro + '.SH "' + manify(txt) + '"\n')
self.add_target(txt)
+ st.opt_prefix = 'daemon-opt' if txt == 'DAEMON OPTIONS' else 'opt'
elif tag == 'h3':
st.man_out.append(st.p_macro + '.SS "' + manify(txt) + '"\n')
self.add_target(txt)
@@ -408,6 +433,20 @@ class TransformHtml(HTMLParser):
st.at_first_tag_in_dd = False
elif tag == 'hr':
return
+ elif tag == 'a':
+ if st.a_href:
+ atxt = st.txt[st.a_txt_start:]
+ find = 'href="' + st.a_href + '"'
+ for j in range(len(st.html_out)-1, 0, -1):
+ if find in st.html_out[j]:
+ derived = txt2target(atxt, st.a_href[1:])
+ if derived == st.prior_target:
+ warn('Found link to the current section in', self.fn + ':', derived)
+ st.derived_hashtags.add((st.a_href, atxt))
+ st.html_out[j] = st.html_out[j].replace(find, 'href="#' + derived + '"')
+ break
+ else:
+ die('INTERNAL ERROR: failed to find href in html data:', find)
st.html_out.append('</' + tag + '>')
if add_to_txt:
if txt is None:
@@ -426,6 +465,8 @@ class TransformHtml(HTMLParser):
def handle_data(self, txt):
st = self.state
+ if '](' in txt:
+ warn('Malformed link in', self.fn + ':', txt)
if args.debug:
self.output_debug('DATA', (txt,))
if st.in_pre:
@@ -441,6 +482,15 @@ class TransformHtml(HTMLParser):
st.txt += txt
+ def add_target(self, txt):
+ st = self.state
+ txt = txt2target(txt, st.opt_prefix)
+ if txt:
+ st.html_out.append('<a id="' + txt + '" href="#' + txt + '" class="tgt"></a>')
+ st.created_hashtags.add(txt)
+ st.prior_target = txt
+
+
def output_debug(self, event, extra):
import pprint
st = self.state
@@ -454,6 +504,18 @@ class TransformHtml(HTMLParser):
pprint.PrettyPrinter(indent=2).pprint(vars(st))
+def txt2target(txt, opt_prefix):
+ txt = re.sub(r'[%s](.+?)[=%s].*' % (BOLD_FONT[0], NORM_FONT[0]), r'\1', txt.strip())
+ txt = re.sub(r'[%s]' % NBR_DASH[0], '-', txt)
+ txt = re.sub(r'[\1-\7]+', '', txt)
+ txt = re.sub(r'[^-A-Za-z0-9._]', '_', txt)
+ if opt_prefix and txt.startswith('-'):
+ txt = opt_prefix + txt
+ else:
+ txt = re.sub(r'^([^A-Za-z])', r't\1', txt)
+ return txt
+
+
def manify(txt):
return re.sub(r"^(['.])", r'\&\1', txt.replace('\\', '\\\\')
.replace(NBR_SPACE[0], NBR_SPACE[1])
@@ -469,6 +531,8 @@ def htmlify(txt):
def warn(*msg):
print(*msg, file=sys.stderr)
+ global warning_count
+ warning_count += 1
def die(*msg):
@@ -497,3 +561,5 @@ if __name__ == '__main__':
gfm_parser = None
main()
+ if warning_count:
+ sys.exit(1)
diff --git a/rsync-ssl.1.md b/rsync-ssl.1.md
index a8d9f0f2..dcd3b9f1 100644
--- a/rsync-ssl.1.md
+++ b/rsync-ssl.1.md
@@ -8,6 +8,9 @@ rsync-ssl - a helper script for connecting to an ssl rsync daemon
rsync-ssl [--type=SSL_TYPE] RSYNC_ARGS
```
+The online version of this man page (that includes cross-linking of topics)
+is available at <https://download.samba.org/pub/rsync/rsync.1>.
+
## DESCRIPTION
The rsync-ssl script helps you to run an rsync copy to/from an rsync daemon
@@ -93,7 +96,7 @@ The ssl helper scripts are affected by the following environment variables:
## SEE ALSO
-**rsync**(1), **rsyncd.conf**(5)
+[**rsync**(1)](./rsync.1), [**rsyncd.conf**(5)](./rsyncd.conf.5)
## CAVEATS
@@ -119,7 +122,7 @@ This man page is current for version @VERSION@ of rsync.
## CREDITS
rsync is distributed under the GNU General Public License. See the file
-COPYING for details.
+[COPYING](./COPYING) for details.
A web site is available at <https://rsync.samba.org/>. The site includes an
FAQ-O-Matic which may cover questions unanswered by this manual page.
diff --git a/rsync.1.md b/rsync.1.md
index 238ed7c8..315109a5 100644
--- a/rsync.1.md
+++ b/rsync.1.md
@@ -26,6 +26,9 @@ Access via rsync daemon:
Usages with just one SRC arg and no DEST arg will list the source files instead
of copying.
+The online version of this man page (that includes cross-linking of topics)
+is available at <https://download.samba.org/pub/rsync/rsync.1>.
+
## DESCRIPTION
Rsync is a fast and extraordinarily versatile file copying tool. It can copy
@@ -65,15 +68,15 @@ 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 (see also the "USING
-RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for an exception
-to this latter rule).
+specification, OR when an rsync:// URL is specified (see also the [USING
+RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION](#) section for an
+exception to this latter rule).
As a special case, if a single source arg is specified without a destination,
the 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 `--list-only` option).
+the copy occurs locally (see also the [`--list-only`](#opt) option).
Rsync refers to the local side as the client and the remote side as the server.
Don't confuse server with an rsync daemon. A daemon is always a server, but a
@@ -89,7 +92,7 @@ protocol). For remote transfers, a modern rsync uses ssh for its
communications, but it may have been configured to use a different remote shell
by default, such as rsh or remsh.
-You can also specify any remote shell you like, either by using the `-e`
+You can also specify any remote shell you like, either by using the [`-e`](#opt--rsh)
command line option, or by setting the RSYNC_RSH environment variable.
Note that rsync must be installed on both the source and destination machines.
@@ -167,16 +170,17 @@ examples:
> rsync -av host:'dir1/file1 dir2/file2' /dest
> rsync host::'modname/dir1/file1 modname/dir2/file2' /dest
-This word-splitting only works in a modern rsync by using `--old-args` (or its
-environment variable) and making sure that `--protect-args` is not enabled.
+This word-splitting only works in a modern rsync by using [`--old-args`](#opt)
+(or its environment variable) and making sure that [`--protect-args`](#opt) is
+not enabled.
## CONNECTING TO AN RSYNC DAEMON
It is also possible to use rsync without a remote shell as the transport. In
this case you will directly connect to a remote rsync daemon, typically using
TCP port 873. (This obviously requires the daemon to be running on the remote
-system, so refer to the STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS section
-below for information on that.)
+system, so refer to the [STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS](#)
+section below for information on that.)
Using rsync in this way is the same as using it with a remote shell except
that:
@@ -189,9 +193,9 @@ that:
paths on the daemon will be shown.
- if you specify no local destination then a listing of the specified files on
the remote daemon is provided.
-- you must not specify the `--rsh` (`-e`) option (since that overrides the
- daemon connection to use ssh -- see USING RSYNC-DAEMON FEATURES VIA A
- REMOTE-SHELL CONNECTION below).
+- you must not specify the [`--rsh`](#opt) (`-e`) option (since that overrides
+ the daemon connection to use ssh -- see [USING RSYNC-DAEMON FEATURES VIA A
+ REMOTE-SHELL CONNECTION](#) below).
An example that copies all the files in a remote module named "src":
@@ -200,11 +204,11 @@ An example that copies all the files in a remote module named "src":
Some modules on the remote daemon may require authentication. If so, you will
receive a password prompt when you connect. You can avoid the password prompt
by setting the environment variable RSYNC_PASSWORD to the password you want to
-use or using the `--password-file` option. This may be useful when scripting
-rsync.
+use or using the [`--password-file`](#opt) option. This may be useful when
+scripting rsync.
WARNING: On some systems environment variables are visible to all users. On
-those systems using `--password-file` is recommended.
+those systems using [`--password-file`](#opt) is recommended.
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
@@ -244,7 +248,7 @@ on that remote host to only allow connections from "localhost".)
From the user's perspective, a daemon transfer via a remote-shell connection
uses nearly the same command-line syntax as a normal rsync-daemon transfer,
with the only exception being that you must explicitly set the remote shell
-program on the command-line with the `--rsh=COMMAND` option. (Setting the
+program on the command-line with the [`--rsh=COMMAND`](#opt) option. (Setting the
RSYNC_RSH in the environment will not turn on this functionality.) For example:
> rsync -av --rsh=ssh host::module /dest
@@ -253,7 +257,7 @@ If you need to specify a different remote-shell user, keep in mind that the
user@ prefix in front of the host is specifying the rsync-user value (for a
module that requires user-based authentication). This means that you must give
the '-l user' option to ssh when specifying the remote-shell, as in this
-example that uses the short version of the `--rsh` option:
+example that uses the short version of the [`--rsh`](#opt) option:
> rsync -av -e "ssh -l ssh-user" rsync-user at host::module /dest
@@ -283,8 +287,8 @@ on the command-line.
If you need a particular file to be transferred prior to another, either
separate the files into different rsync calls, or consider using
-`--delay-updates` (which doesn't affect the sorted transfer order, but does
-make the final file-updating phase happen much more rapidly).
+[`--delay-updates`](#opt) (which doesn't affect the sorted transfer order, but
+does make the final file-updating phase happen much more rapidly).
## EXAMPLES
@@ -318,8 +322,8 @@ This is launched from cron every few hours.
## OPTION SUMMARY
-Here is a short summary of the options available in rsync. Please refer to the
-detailed description below for a complete description.
+Here is a short summary of the options available in rsync. Each option also
+has its own detailed description later in this man page.
[comment]: # (help-rsync.h)
[comment]: # (Keep these short enough that they'll be under 80 chars when indented by 7 chars.)
@@ -512,7 +516,7 @@ your home directory (remove the '=' for that).
Print a short help page describing the options available in rsync and exit.
(*) The `-h` short option will only invoke `--help` when used without other
- options since it normally means `--human-readable`.
+ options since it normally means [`--human-readable`](#opt).
0. `--version`, `-V`
@@ -540,15 +544,15 @@ your home directory (remove the '=' for that).
value, which is a ratio of the total file size divided by the sum of the
sent and received bytes (which is really just a feel-good bigger-is-better
number). Note that these byte values can be made more (or less)
- human-readable by using the `--human-readable` (or `--no-human-readable`)
- options.
+ human-readable by using the [`--human-readable`](#opt) (or
+ `--no-human-readable`) options.
In a modern rsync, the `-v` option is equivalent to the setting of groups
- of `--info` and `--debug` options. You can choose to use these newer
- options in addition to, or in place of using `--verbose`, as any
- fine-grained settings override the implied settings of `-v`. Both `--info`
- and `--debug` have a way to ask for help that tells you exactly what flags
- are set for each increase in verbosity.
+ of [`--info`](#opt) and [`--debug`](#opt) options. You can choose to use
+ these newer options in addition to, or in place of using `--verbose`, as
+ any fine-grained settings override the implied settings of `-v`. Both
+ [`--info`](#opt) and [`--debug`](#opt) have a way to ask for help that
+ tells you exactly what flags are set for each increase in verbosity.
However, do keep in mind that a daemon's "`max verbosity`" setting will limit
how high of a level the various individual flags can be set on the daemon
@@ -569,9 +573,9 @@ your home directory (remove the '=' for that).
> rsync -a --info=progress2 src/ dest/
> rsync -avv --info=stats2,misc1,flist0 src/ dest/
- Note that `--info=name`'s output is affected by the `--out-format` and
- `--itemize-changes` (`-i`) options. See those options for more information
- on what is output and when.
+ Note that `--info=name`'s output is affected by the [`--out-format`](#opt)
+ and [`--itemize-changes`](#opt) (`-i`) options. See those options for more
+ information on what is output and when.
This option was added to 3.1.0, so an older rsync on the server side might
reject your attempts at fine-grained control (if one or more flags needed
@@ -591,8 +595,8 @@ your home directory (remove the '=' for that).
> rsync -avvv --debug=none src/ dest/
> rsync -avA --del --debug=del2,acl src/ dest/
- Note that some debug messages will only be output when `--stderr=all` is
- specified, especially those pertaining to I/O and buffer debugging.
+ Note that some debug messages will only be output when the [`--stderr=all`](#opt)
+ option is specified, especially those pertaining to I/O and buffer debugging.
Beginning in 3.2.0, this option is no longer auto-forwarded to the server
side in order to allow you to specify different debug values for each side
@@ -622,8 +626,8 @@ your home directory (remove the '=' for that).
divide up the info and error messages by file handle. For those doing
debugging or using several levels of verbosity, this option can help to
avoid clogging up the transfer stream (which should prevent any chance of
- a deadlock bug hanging things up). It also allows `--debug` to enable
- some extra I/O related messages.
+ a deadlock bug hanging things up). It also allows [`--debug`](#opt) to
+ enable some extra I/O related messages.
- `client` - causes all rsync messages to be sent to the client side
via the protocol stream. One client process outputs all messages, with
@@ -660,9 +664,9 @@ your home directory (remove the '=' for that).
the same modification timestamp. This option turns off this "quick check"
behavior, causing all files to be updated.
- This option can be a little confusing compared to `--ignore-existing` and
- `--ignore-non-existing` in that that they cause rsync to transfer fewer
- files, while this option causes rsync to transfer more files.
+ This option can be confusing compared to [`--ignore-existing`](#opt) and
+ [`--ignore-non-existing`](#opt) in that that they cause rsync to transfer
+ fewer files, while this option causes rsync to transfer more files.
0. `--size-only`
@@ -718,8 +722,9 @@ your home directory (remove the '=' for that).
before-the-transfer "Does this file need to be updated?" check.
The checksum used is auto-negotiated between the client and the server, but
- can be overridden using either the `--checksum-choice` (`--cc`) option or an
- environment variable that is discussed in that option's section.
+ can be overridden using either the [`--checksum-choice`](#opt) (`--cc`)
+ option or an environment variable that is discussed in that option's
+ section.
0. `--archive`, `-a`
@@ -728,8 +733,8 @@ your home directory (remove the '=' for that).
**not** include preserving ACLs (`-A`), xattrs (`-X`), atimes (`-U`),
crtimes (`-N`), nor the finding and preserving of hardlinks (`-H`).
- The only exception to the above equivalence is when
- `--files-from` is specified, in which case `-r` is not implied.
+ The only exception to the above equivalence is when [`--files-from`](#opt)
+ is specified, in which case [`-r`](#opt--recursive) is not implied.
0. `--no-OPTION`
@@ -741,39 +746,70 @@ your home directory (remove the '=' for that).
long option name after the "no-" prefix (e.g. `--no-R` is the same as
`--no-relative`).
- For example: if you want to use `-a` (`--archive`) but don't want `-o`
- (`--owner`), instead of converting `-a` into `-rlptgD`, you could specify
- `-a --no-o` (or `-a --no-owner`).
+ For example: if you want to use [`--archive`](#opt) (`-a`) but don't want
+ [`--owner`](#opt) (`-o`), instead of converting `-a` into `-rlptgD`, you
+ could specify `-a --no-o` (or `-a --no-owner`).
- The order of the options is important: if you specify `--no-r -a`, the
- `-r` option would end up being turned on, the opposite of `-a --no-r`.
- Note also that the side-effects of the `--files-from` option are NOT
+ The order of the options is important: if you specify `--no-r -a`, the `-r`
+ option would end up being turned on, the opposite of `-a --no-r`. Note
+ also that the side-effects of the [`--files-from`](#opt) option are NOT
positional, as it affects the default state of several options and slightly
- changes the meaning of `-a` (see the `--files-from` option for more
- details).
+ changes the meaning of [`-a`](#opt--archive) (see the
+ [`--files-from`](#opt) option for more details).
0. `--recursive`, `-r`
- This tells rsync to copy directories recursively. See also `--dirs` (`-d`).
+ This tells rsync to copy directories recursively. See also
+ [`--dirs`](#opt) (`-d`) for an option that allows the scanning of a single
+ directory.
- Beginning with rsync 3.0.0, the recursive algorithm used is now an
- incremental scan that uses much less memory than before and begins the
- transfer after the scanning of the first few directories have been
- completed. This incremental scan only affects our recursion algorithm, and
- does not change a non-recursive transfer. It is also only possible when
- both ends of the transfer are at least version 3.0.0.
+ See the [`--inc-recursive`](#opt) option for a discussion of the
+ incremental recursion for creating the list of files to transfer.
- Some options require rsync to know the full file list, so these options
- disable the incremental recursion mode. These include: `--delete-before`,
- `--delete-after`, `--prune-empty-dirs`, and `--delay-updates`. Because of
- this, the default delete mode when you specify `--delete` is now
- `--delete-during` when both ends of the connection are at least 3.0.0 (use
- `--del` or `--delete-during` to request this improved deletion mode
- explicitly). See also the `--delete-delay` option that is a better choice
- than using `--delete-after`.
+0. `--inc-recursive`, `--i-r`
+
--
The rsync repository.
More information about the rsync-cvs
mailing list