From: Wayne Davison Date: Thu, 13 Jan 2022 00:41:36 +0000 (-0800) Subject: Change manpage headings in html to use h2 tags with an id target. X-Git-Tag: v3.2.4pre2~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e841944b47613c242a016184255b6855c8181d32;p=thirdparty%2Frsync.git Change manpage headings in html to use h2 tags with an id target. --- diff --git a/md-convert b/md-convert index 7780d06b..d1266f45 100755 --- a/md-convert +++ b/md-convert @@ -32,7 +32,7 @@ import os, sys, re, argparse, subprocess, time from html.parser import HTMLParser -CONSUMES_TXT = set('h1 h2 p li pre'.split()) +CONSUMES_TXT = set('h1 h2 h3 p li pre'.split()) HTML_START = """\ @@ -332,6 +332,12 @@ class TransformHtml(HTMLParser): st.at_first_tag_in_dd = False + def add_anchor(self, txt): + st = self.state + txt = txt.lower().replace(' ', '-') + st.html_out.append('') + + def handle_endtag(self, tag): st = self.state if args.debug: @@ -342,10 +348,12 @@ class TransformHtml(HTMLParser): else: txt = None add_to_txt = None - if tag == 'h1': + if tag == 'h1' or tag == 'h2': st.man_out.append(st.p_macro + '.SH "' + manify(txt) + '"\n') - elif tag == 'h2': + self.add_anchor(txt) + elif tag == 'h3': st.man_out.append(st.p_macro + '.SS "' + manify(txt) + '"\n') + self.add_anchor(txt) elif tag == 'p': if st.dt_from == 'p': tag = 'dt' diff --git a/rsync-ssl.1.md b/rsync-ssl.1.md index 32ab31e2..c09603f9 100644 --- a/rsync-ssl.1.md +++ b/rsync-ssl.1.md @@ -1,14 +1,14 @@ -# NAME +## NAME rsync-ssl - a helper script for connecting to an ssl rsync daemon -# SYNOPSIS +## SYNOPSIS ``` rsync-ssl [--type=SSL_TYPE] RSYNC_ARGS ``` -# DESCRIPTION +## DESCRIPTION The rsync-ssl script helps you to run an rsync copy to/from an rsync daemon that requires ssl connections. @@ -20,7 +20,7 @@ environment. You can specify an overriding port via `--port` or by including it in the normal spot in the URL format, though both of those require your rsync version to be at least 3.2.0. -# OPTIONS +## OPTIONS If the **first** arg is a `--type=SSL_TYPE` option, the script will only use that particular program to open an ssl connection instead of trying to find an @@ -32,7 +32,7 @@ required for this particular option. All the other options are passed through to the rsync command, so consult the **rsync**(1) manpage for more information on how it works. -# ENVIRONMENT VARIABLES +## ENVIRONMENT VARIABLES The ssl helper scripts are affected by the following environment variables: @@ -60,7 +60,7 @@ The ssl helper scripts are affected by the following environment variables: connection type is set to stunnel. If unspecified, the $PATH is searched first for "stunnel4" and then for "stunnel". -# EXAMPLES +## EXAMPLES > rsync-ssl -aiv example.com::mod/ dest @@ -70,11 +70,11 @@ The ssl helper scripts are affected by the following environment variables: > rsync-ssl -aiv rsync://example.com:9874/mod/ dest -# SEE ALSO +## SEE ALSO **rsync**(1), **rsyncd.conf**(5) -# CAVEATS +## CAVEATS Note that using an stunnel connection requires at least version 4 of stunnel, which should be the case on modern systems. Also, it does not verify a @@ -87,15 +87,15 @@ release the gnutls-cli command was dropping output, making it unusable. If that bug has been fixed in your version, feel free to put gnutls into an exported RSYNC_SSL_TYPE environment variable to make its use the default. -# BUGS +## BUGS Please report bugs! See the web site at . -# VERSION +## VERSION This man page is current for version @VERSION@ of rsync. -# CREDITS +## CREDITS rsync is distributed under the GNU General Public License. See the file COPYING for details. @@ -103,7 +103,7 @@ COPYING for details. A web site is available at . The site includes an FAQ-O-Matic which may cover questions unanswered by this manual page. -# AUTHOR +## AUTHOR This manpage was written by Wayne Davison. diff --git a/rsync.1.md b/rsync.1.md index 73532573..0a4d5868 100644 --- a/rsync.1.md +++ b/rsync.1.md @@ -1,8 +1,8 @@ -# NAME +## NAME rsync - a fast, versatile, remote (and local) file-copying tool -# SYNOPSIS +## SYNOPSIS ``` Local: @@ -26,7 +26,7 @@ Access via rsync daemon: Usages with just one SRC arg and no DEST arg will list the source files instead of copying. -# DESCRIPTION +## DESCRIPTION Rsync is a fast and extraordinarily versatile file copying tool. It can copy locally, to/from another host over any remote shell, or to/from a remote rsync @@ -54,7 +54,7 @@ Some of the additional features of rsync are: - pipelining of file transfers to minimize latency costs - support for anonymous or authenticated rsync daemons (ideal for mirroring) -# GENERAL +## GENERAL Rsync copies files either to or from a remote host, or locally on the current host (it does not support copying files between two remote hosts). @@ -79,7 +79,7 @@ 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 server can be either a daemon or a remote-shell spawned process. -# SETUP +## SETUP See the file README.md for installation instructions. @@ -94,7 +94,7 @@ command line option, or by setting the RSYNC_RSH environment variable. Note that rsync must be installed on both the source and destination machines. -# USAGE +## USAGE You use rsync in the same way you use rcp. You must specify a source and a destination, one of which may be remote. @@ -151,7 +151,7 @@ rsync daemon by leaving off the module name: See the following section for more details. -# ADVANCED USAGE +## ADVANCED USAGE The syntax for requesting multiple files from a remote host is done by specifying additional remote-host args in the same style as the first, or with @@ -170,7 +170,7 @@ examples: 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. -# CONNECTING TO AN RSYNC DAEMON +## 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 @@ -227,7 +227,7 @@ Note also that if the RSYNC_SHELL environment variable is set, that program will be used to run the RSYNC_CONNECT_PROG command instead of using the default shell of the **system()** call. -# USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION +## USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION It is sometimes useful to use various features of an rsync daemon (such as named modules) without actually allowing any new socket connections into a @@ -260,7 +260,7 @@ example that uses the short version of the `--rsh` option: The "ssh-user" will be used at the ssh level; the "rsync-user" will be used to log-in to the "module". -# STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS +## STARTING AN RSYNC DAEMON TO ACCEPT CONNECTIONS In order to connect to an rsync daemon, the remote system needs to have a daemon already running (or it needs to have configured something like inetd to @@ -273,7 +273,7 @@ the daemon, and it contains the full details for how to run the daemon If you're using one of the remote-shell transports for the transfer, there is no need to manually start an rsync daemon. -# SORTED TRANSFER ORDER +## SORTED TRANSFER ORDER Rsync always sorts the specified filenames into its internal transfer list. This handles the merging together of the contents of identically named @@ -286,7 +286,7 @@ 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). -# EXAMPLES +## EXAMPLES Here are some examples of how I use rsync. @@ -316,7 +316,7 @@ I mirror a directory between my "old" and "new" ftp sites with the command: This is launched from cron every few hours. -# OPTION SUMMARY +## OPTION SUMMARY Here is a short summary of the options available in rsync. Please refer to the detailed description below for a complete description. @@ -492,7 +492,7 @@ accepted: --help, -h show this help (when used with --daemon) ``` -# OPTIONS +## OPTIONS Rsync accepts both long (double-dash + word) and short (single-dash + letter) options. The full list of the available options are described below. If an @@ -3429,7 +3429,7 @@ your home directory (remove the '=' for that). user wants a more random checksum seed. Setting NUM to 0 causes rsync to use the default of **time**() for checksum seed. -# DAEMON OPTIONS +## DAEMON OPTIONS The options allowed when starting an rsync daemon are as follows: @@ -3537,7 +3537,7 @@ The options allowed when starting an rsync daemon are as follows: When specified after `--daemon`, print a short help page describing the options available for starting an rsync daemon. -# FILTER RULES +## FILTER RULES The filter rules allow for flexible selection of which files to transfer (include) and which files to skip (exclude). The rules either directly specify @@ -3594,7 +3594,7 @@ rule/pattern each. To add multiple ones, you can repeat the options on the command-line, use the merge-file syntax of the `--filter` option, or the `--include-from` / `--exclude-from` options. -# INCLUDE/EXCLUDE PATTERN RULES +## INCLUDE/EXCLUDE PATTERN RULES You can include and exclude files by specifying patterns using the "+", "-", etc. filter rules (as introduced in the FILTER RULES section above). The @@ -3722,7 +3722,7 @@ The following modifiers are accepted after a "`+`" or "`-`": xattr-matching rules are specified, a default xattr filtering rule is used (see the `--xattrs` option). -# MERGE-FILE FILTER RULES +## MERGE-FILE FILTER RULES You can merge whole files into your filter rules by specifying either a merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES section @@ -3856,7 +3856,7 @@ $HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the `-C` command-line option and instead insert a "-C" rule into your filter rules; e.g. "`--filter=-C`". -# LIST-CLEARING FILTER RULE +## LIST-CLEARING FILTER RULE You can clear the current include/exclude list by using the "!" filter rule (as introduced in the FILTER RULES section above). The "current" list is either @@ -3864,7 +3864,7 @@ the global list of rules (if the rule is encountered while parsing the filter options) or a set of per-directory rules (which are inherited in their own sub-list, so a subdirectory can use this to clear out the parent's rules). -# ANCHORING INCLUDE/EXCLUDE PATTERNS +## ANCHORING INCLUDE/EXCLUDE PATTERNS As mentioned earlier, global include/exclude patterns are anchored at the "root of the transfer" (as opposed to per-directory patterns, which are anchored at @@ -3919,7 +3919,7 @@ The easiest way to see what name you should filter is to just look at the output when using `--verbose` and put a / in front of the name (use the `--dry-run` option if you're not yet ready to copy any files). -# PER-DIRECTORY RULES AND DELETE +## PER-DIRECTORY RULES AND DELETE Without a delete option, per-directory rules are only relevant on the sending side, so you can feel free to exclude the merge files themselves without @@ -3965,7 +3965,7 @@ one of these commands: > rsync -avFF --delete host:src/dir /dest > ``` -# BATCH MODE +## BATCH MODE Batch mode can be used to apply the same set of updates to many identical systems. Suppose one has a tree which is replicated on a number of hosts. Now @@ -4063,7 +4063,7 @@ this detail and just use the shell script as an easy way to run the appropriate The original batch mode in rsync was based on "rsync+", but the latest version uses a new implementation. -# SYMBOLIC LINKS +## SYMBOLIC LINKS Three basic behaviors are possible when rsync encounters a symbolic link in the source directory. @@ -4102,7 +4102,7 @@ first line that is a complete subset of your options: 0. `--links --safe-links` Duplicate safe symlinks and skip unsafe ones. 0. `--links` Duplicate all symlinks. -# DIAGNOSTICS +## DIAGNOSTICS rsync occasionally produces error messages that may seem a little cryptic. The one that seems to cause the most confusion is "protocol version mismatch -- is @@ -4125,7 +4125,7 @@ If you are having trouble debugging filter patterns, then try specifying the `-vv` option. At this level of verbosity rsync will show why each individual file is included or excluded. -# EXIT VALUES +## EXIT VALUES 0. **0** Success 0. **1** Syntax or usage error @@ -4150,7 +4150,7 @@ file is included or excluded. 0. **30** Timeout in data send/receive 0. **35** Timeout waiting for daemon connection -# ENVIRONMENT VARIABLES +## ENVIRONMENT VARIABLES 0. `CVSIGNORE` @@ -4206,15 +4206,15 @@ file is included or excluded. The HOME environment variable is used to find the user's default .cvsignore file. -# FILES +## FILES /etc/rsyncd.conf or rsyncd.conf -# SEE ALSO +## SEE ALSO **rsync-ssl**(1), **rsyncd.conf**(5) -# BUGS +## BUGS times are transferred as \*nix time_t values @@ -4229,11 +4229,11 @@ see also the comments on the `--delete` option Please report bugs! See the web site at . -# VERSION +## VERSION This man page is current for version @VERSION@ of rsync. -# INTERNAL OPTIONS +## INTERNAL OPTIONS The options `--server` and `--sender` are used internally by rsync, and should never be typed by a user under normal circumstances. Some awareness of these @@ -4242,7 +4242,7 @@ that can only run an rsync command. For instance, the support directory of the rsync distribution has an example script named rrsync (for restricted rsync) that can be used with a restricted ssh login. -# CREDITS +## CREDITS rsync is distributed under the GNU General Public License. See the file COPYING for details. @@ -4256,7 +4256,7 @@ contact the mailing-list at . This program uses the excellent zlib compression library written by Jean-loup Gailly and Mark Adler. -# THANKS +## THANKS Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our @@ -4265,7 +4265,7 @@ gone-but-not-forgotten compadre, J.W. Schultz. Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and David Bell. I've probably missed some people, my apologies if I have. -# AUTHOR +## AUTHOR rsync was originally written by Andrew Tridgell and Paul Mackerras. Many people have later contributed to it. It is currently maintained by Wayne diff --git a/rsyncd.conf.5.md b/rsyncd.conf.5.md index 258322bd..9d1ad14c 100644 --- a/rsyncd.conf.5.md +++ b/rsyncd.conf.5.md @@ -1,12 +1,12 @@ -# NAME +## NAME rsyncd.conf - configuration file for rsync in daemon mode -# SYNOPSIS +## SYNOPSIS rsyncd.conf -# DESCRIPTION +## DESCRIPTION The rsyncd.conf file is the runtime configuration file for rsync when run as an rsync daemon. @@ -14,7 +14,7 @@ rsync daemon. The rsyncd.conf file controls authentication, access, logging and available modules. -# FILE FORMAT +## FILE FORMAT The file consists of modules and parameters. A module begins with the name of the module in square brackets and continues until the next module begins. @@ -40,7 +40,7 @@ The values following the equals sign in parameters are all either a string (no quotes needed) or a boolean, which may be given as yes/no, 0/1 or true/false. Case is not significant in boolean values, but is preserved in string values. -# LAUNCHING THE RSYNC DAEMON +## LAUNCHING THE RSYNC DAEMON The rsync daemon is launched by specifying the `--daemon` option to rsync. @@ -69,7 +69,7 @@ reread its config file. Note that you should **not** send the rsync daemon a HUP signal to force it to reread the `rsyncd.conf` file. The file is re-read on each client connection. -# GLOBAL PARAMETERS +## GLOBAL PARAMETERS The first parameters in the file (before a [module] header) are the global parameters. Rsync also allows for the use of a "[global]" module name to @@ -136,7 +136,7 @@ a literal % into a value is to use %%. You can override the default backlog value when the daemon listens for connections. It defaults to 5. -# MODULE PARAMETERS +## MODULE PARAMETERS After the global parameters you should define a number of modules, each module exports a directory tree as a symbolic name. Modules are exported by specifying @@ -1038,7 +1038,7 @@ the values of parameters. See the GLOBAL PARAMETERS section for more details. **system()** call's default shell), and use RSYNC_NO_XFER_EXEC to disable both options completely. -# CONFIG DIRECTIVES +## CONFIG DIRECTIVES There are currently two config directives available that allow a config file to incorporate the contents of other files: `&include` and `&merge`. Both allow @@ -1093,7 +1093,7 @@ This would merge any `/etc/rsyncd.d/*.inc` files (for global values that should stay in effect), and then include any `/etc/rsyncd.d/*.conf` files (defining modules without any global-value cross-talk). -# AUTHENTICATION STRENGTH +## AUTHENTICATION STRENGTH The authentication protocol used in rsync is a 128 bit MD4 based challenge response system. This is fairly weak protection, though (with at least one @@ -1108,7 +1108,7 @@ authentication is provided. Use ssh as the transport if you want encryption. You can also make use of SSL/TLS encryption if you put rsync behind an SSL proxy. -# SSL/TLS Daemon Setup +## SSL/TLS Daemon Setup When setting up an rsync daemon for access via SSL/TLS, you will need to configure a proxy (such as haproxy or nginx) as the front-end that handles the @@ -1153,7 +1153,7 @@ An example nginx proxy setup is as follows: > } > ``` -# EXAMPLES +## EXAMPLES A simple rsyncd.conf file that allow anonymous rsync to a ftp area at `/home/ftp` would be: @@ -1202,24 +1202,24 @@ The /etc/rsyncd.secrets file would look something like this: > tridge:mypass > susan:herpass -# FILES +## FILES /etc/rsyncd.conf or rsyncd.conf -# SEE ALSO +## SEE ALSO **rsync**(1), **rsync-ssl**(1) -# BUGS +## BUGS Please report bugs! The rsync bug tracking system is online at . -# VERSION +## VERSION This man page is current for version @VERSION@ of rsync. -# CREDITS +## CREDITS rsync is distributed under the GNU General Public License. See the file COPYING for details. @@ -1233,12 +1233,12 @@ We would be delighted to hear from you if you like this program. This program uses the zlib compression library written by Jean-loup Gailly and Mark Adler. -# THANKS +## THANKS Thanks to Warren Stanley for his original idea and patch for the rsync daemon. Thanks to Karsten Thygesen for his many suggestions and documentation! -# AUTHOR +## AUTHOR rsync was written by Andrew Tridgell and Paul Mackerras. Many people have later contributed to it. diff --git a/support/rrsync.1.md b/support/rrsync.1.md index cbb76ef8..8108bbf4 100644 --- a/support/rrsync.1.md +++ b/support/rrsync.1.md @@ -1,14 +1,14 @@ -# NAME +## NAME rrsync - a script to setup restricted rsync users via ssh logins -# SYNOPSIS +## SYNOPSIS ``` rrsync [-ro|-rw] [-munge] [-no-del] [-no-lock] DIR ``` -# DESCRIPTION +## DESCRIPTION A user's ssh login can be restricted to only allow the running of an rsync transfer in one of two easy ways: forcing the running of the rrsync script @@ -49,7 +49,7 @@ file, each one with its own path setting. The remainder of this man page is dedicated to using the rrsync script. -# OPTION SUMMARY +## OPTION SUMMARY ``` -ro Allow only reading from the DIR. Implies -no-del and -no-lock. @@ -63,7 +63,7 @@ The remainder of this man page is dedicated to using the rrsync script. A single non-option argument specifies the restricted DIR to use. It can be relative to the user's home directory or an absolute path. -# SECURITY RESTRICTIONS +## SECURITY RESTRICTIONS The rrsync script validates the path arguments it is sent to try to restrict them to staying within the specified DIR. @@ -84,7 +84,7 @@ overrides. The script (or a copy of it) can be manually edited if you want it to customize the option handling. -# EXAMPLES +## EXAMPLES The `.ssh/authorized_keys` file might have lines in it like this: