Package: debmirror Version: 1:2.5 This is a patch against the current git (which has 1:2.5 as the upcoming version). It improves the markup for the manual page's option section. Primarily it makes option names be in bold face, but there's a bunch of other fixes as well, to make the manpage (or this section) correspond more closely to manpage conventions.
diff --git a/debmirror b/debmirror index 41640b8..9988030 100755 --- a/debmirror +++ b/debmirror @@ -7,7 +7,7 @@ rsync and package pool support =head1 SYNOPSIS -debmirror [options] <mirrordir> +B<debmirror> [I<options>] I<mirrordir> =head1 DESCRIPTION @@ -60,70 +60,70 @@ EOF =over 4 -=item <mirrordir> +=item I<mirrordir> This required (unless defined in a configuration file) parameter specifies where the local mirror directory is. If the directory does not exist, it will be created. Be careful; telling this program that your home directory is the mirrordir is guaranteed to replace your home directory with a Debian mirror! -=item --progress -p +=item B<-p>, B<--progress> Displays progress bars as files are downloaded. -=item --verbose -v +=item B<-v>, B<--verbose> Displays progress between file downloads. -=item --debug +=item B<--debug> Enables verbose debug output, including ftp protocol dump. -=item --dry-run +=item B<--dry-run> Simulate a mirror run. This will still download the meta files to the F<./.temp> working directory, but won't replace the old meta files, won't download debs and source files and only simulates cleanup. -=item --help +=item B<--help> Display a usage summary. -=item --host=remotehost -h +=item B<-h>, B<--host>=I<remotehost> -Specify the remote host to mirror from. Defaults to 'ftp.debian.org', +Specify the remote host to mirror from. Defaults to I<ftp.debian.org>, you are strongly encouraged to find a closer mirror. -=item --root=directory -r directory +=item B<-r>, B<--root>=I<directory> Specifies the directory on the remote host that is the root of the Debian -archive. Defaults to "debian", which will work for most mirrors. The root -directory has a F<./dists> subdirectory. +archive. Defaults to F<debian>, which will work for most mirrors. The root +directory has a F<dists> subdirectory. -=item --method=ftp|http|rsync -e +=item B<--method>=I<method> Specify the method to download files. Currently, supported methods are -ftp, http or rsync. +B<ftp>, B<http>, and B<rsync>. -=item --passive +=item B<--passive> Download in passive mode when using ftp. -=item --user=remoteusername -u +=item B<-u>, B<--user>=I<remoteusername> Specify the remote user name to use to log into the remote host. Helpful when -dealing with brain damaged proxy servers. Defaults to anonymous. +dealing with brain damaged proxy servers. Defaults to C<anonymous>. -=item --passwd=remoteuserpassword +=item B<--passwd>=I<remoteuserpassword> Specify the remote user password to use to log into the remote ftp host. -It is used with --user and defaults to anonym...@. +It is used with B<--user> and defaults to C<anonymous@>. -=item --proxy=http://user:p...@url:port/ +=item B<--proxy>=I<http://user:p...@url:port/> Specifies the http proxy (like Squid) to use for http or ftp methods. -=item --dist=foo[,bar,..] -d foo +=item B<-d>, B<--dist>=I<foo[,bar,..]> Specify the distribution (etch, lenny, squeeze, sid) of Debian to mirror. This switch may be used multiple times, and multiple @@ -131,33 +131,35 @@ distributions may be specified at once, separated by commas. You may also use the stable, testing, unstable, names. -=item --omit-suite-symlinks +=item B<--omit-suite-symlinks> -With this option set, debmirror will not create the 'S<suite -E<gt> codename>' -symlink. This is needed for example when mirroring archived Debian -releases as they will all have either 'stable' or 'oldstable' as +With this option set, B<debmirror> will not create the +symlink from I<suite> to I<codename>. +This is needed for example when mirroring archived Debian +releases as they will all have either C<stable> or C<oldstable> as suite in their F<Release> files. -=item --section=foo[,bar,..] -s foo +=item B<-s>, B<--section>=I<foo[,bar,..]> Specify the section of Debian to mirror. Defaults to -main,contrib,non-free,main/debian-installer. +C<main,contrib,non-free,main/debian-installer>. -=item --arch=foo[,bar,..] -a foo +=item B<-a>, B<--arch>=I<foo[,bar,..]> -Specify the architectures to mirror. The default is --arch=i386. -Specifying --arch=none will mirror no archs. +Specify the architectures to mirror. The default is B<--arch=i386>. +Specifying B<--arch=none> will mirror no archs. -=item --rsync-extra=foo[,bar,..] +=item B<--rsync-extra>=I<foo[,bar,..]> Allows to also mirror files from a number of directories that are not part of the package archive itself. -Debmirror will B<always> use rsync for the transfer of these files, -irrespective of what transfer method is specified in the --method option. This +B<Debmirror> will B<always> use rsync for the transfer of these files, +irrespective of what transfer method is specified in the B<--method> option. +This will therefore not work if your remote mirror does not support rsync, or if -the mirror needs a different --root option for rsync than for the main -transfer method specified with --method. +the mirror needs a different B<--root> option for rsync than for the main +transfer method specified with B<--method>. Note that excluding individual files in the directories is not supported. @@ -165,27 +167,27 @@ The following values are supported. =over 2 -=item doc +=item B<doc> -Download all files and subdirectories in F<./doc> directory, and all README +Download all files and subdirectories in F<doc> directory, and all README files in the root directory of the archive. -=item indices +=item B<indices> -Download all files and subdirectories in F<./indices> directory. Note that +Download all files and subdirectories in F<indices> directory. Note that this directory can contain some rather large files; don't include this type unless you know you need these files. -=item tools +=item B<tools> -Download all files and subdirectories in F<./tools> directory. +Download all files and subdirectories in F<tools> directory. -=item trace +=item B<trace> -Download the remote mirror's trace files for the archive (F<./project/trace/*>). +Download the remote mirror's trace files for the archive (F<project/trace/*>). This is enabled by default. -=item none +=item B<none> This can be used to disable getting extra files with rsync. @@ -197,99 +199,100 @@ the mirror run; the other types are done near the end. This switch may be used multiple times, and multiple values may be specified at once, separated by commas; unknown values are ignored. -=item --di-dist=dists | foo[,bar,..] +=item B<--di-dist>=I<dists | foo[,bar,..]> -Mirror "current" Debian Installer images for the specified dists. +Mirror current Debian Installer images for the specified dists. See further the section L<Mirroring Debian Installer images> below. -=item --di-arch=arches | foo[,bar,..] +=item B<--di-arch>=I<arches | foo[,bar,..]> -Mirror "current" Debian Installer images for the specified architectures. +Mirror current Debian Installer images for the specified architectures. See further the section L<Mirroring Debian Installer images> below. -=item --source +=item B<--source> Include source in the mirror (default). -=item --nosource +=item B<--nosource> Do not include source. -=item --i18n +=item B<--i18n> Additionally download F<Translation-E<lt>langE<gt>.bz2> files, which contain translations of package descriptions. Selection of specific translations is -possible using the --include and --exclude options. +possible using the B<--include> and B<--exclude> options. -=item --getcontents +=item B<--getcontents> Additionally download F<Contents.E<lt>archE<gt>.gz> files. Note that these files can be relatively big and can change frequently, especially for the testing and unstable suites. Use of the available diff files is strongly -recommended (see the --diff option). +recommended (see the B<--diff> option). -=item --md5sums -m +=item B<-m>, B<--md5sums> -Use md5sums to determine if files on the local mirror that are the correct +Use MD5 checksums to determine if files on the local mirror that are +the correct size actually have the correct content. Not enabled by default, because it is too paranoid, and too slow. -When the state cache is used, debmirror will only check md5sums during runs +When the state cache is used, B<debmirror> will only check checksums +during runs where the cache has expired or been invalidated, so it is worth considering to use these two options together. -=item --ignore-missing-release +=item B<--ignore-missing-release> Don't fail if the F<Release> file is missing. -=item --check-gpg -=item --no-check-gpg +=item B<--check-gpg>, B<--no-check-gpg> Controls whether gpg signatures from the F<Release.gpg> file should be checked. The default is to check signatures. -=item --ignore-release-gpg +=item B<--ignore-release-gpg> Don't fail if the F<Release.gpg> file is missing. If the file does exist, it is mirrored and verified, but any errors are ignored. -=item --ignore=regex +=item B<--ignore>=I<regex> Never delete any files whose filenames match the regex. May be used multiple times. -=item --exclude=regex +=item B<--exclude>=B<regex> Never download any files whose filenames match the regex. May be used multiple times. -=item --include=regex +=item B<--include>=I<regex> Don't exclude any files whose filenames match the regex. May be used multiple times. -=item --exclude-deb-section=regex +=item B<--exclude-deb-section>=I<regex> Never download any files whose Debian Section (games, doc, oldlibs, science, ...) match the regex. May be used multiple times. -=item --limit-priority=regex +=item B<--limit-priority>=I<regex> Limit download to files whose Debian Priority (required, extra, optional, ...) match the regex. May be used multiple times. -=item --timeout=seconds -t +=item B<-t>, B<--timeout>=I<seconds> Specifies the timeout to use for network operations (either FTP or rsync). Set this to a higher value if you experience failed downloads. Defaults to 300 seconds. -=item --max-batch=number +=item B<--max-batch>=I<number> Download at most max-batch number of files (and ignore rest). -=item --rsync-batch=number +=item B<--rsync-batch>=I<number> Download at most number of files with each rsync call and then loop. -=item --rsync-options=options +=item B<--rsync-options>=I<options> Specify alternative rsync options to be used. Default options are "-aIL --partial". Care must be taken when specifying alternative @@ -299,7 +302,7 @@ options. The most likely option to add is "--bwlimit=x" to avoid saturating the bandwidth of your link. -=item --postcleanup +=item B<--postcleanup> Clean up the local mirror but only after mirroring is complete and only if there was no error. @@ -307,68 +310,69 @@ only if there was no error. This is the default, because it ensures that the mirror is consistent at all times. -=item --precleanup +=item B<--precleanup> Clean up the local mirror before starting mirroring. This option may be useful if you have limited disk space, but it will result in an inconsistent mirror when debmirror is running. -The deprecated --cleanup option also enables this mode. +The deprecated B<--cleanup> option also enables this mode. -=item --nocleanup +=item B<--nocleanup> Do not clean up the local mirror. -=item --skippackages +=item B<--skippackages> -Don't re-download Packages and Sources files. Useful if you know they are -up-to-date. +Don't re-download F<Packages> and F<Sources> files. +Useful if you know they are up-to-date. -=item --diff=use|mirror|none +=item B<--diff>=I<use|mirror|none> -If --diff=use is specified and the F<Release> file contains entries for -diff files, then debmirror will attempt to use them to update Packages, -Sources and Contents files (which can significantly reduce the download +If B<--diff=use> is specified and the F<Release> file contains entries for +diff files, then debmirror will attempt to use them to update F<Packages>, +F<Sources>, and F<Contents> files (which can significantly reduce the download size for meta files), but will not include them in the mirror. This is the default behavior and avoids having time consuming diff files for a fast local mirror. -Specifying --diff=mirror does the same as 'use', but will also include -the downloaded diff files in the local mirror. Specify --diff=none to +Specifying B<--diff=mirror> does the same as B<use>, but will also include +the downloaded diff files in the local mirror. Specify B<--diff=none> to completely ignore diff files. Note that if rsync is used as method to download files and the archive -being mirrored has "rsyncable" gzipped meta files, then using --diff=none -may be the most efficient way to download them. See the gzip(1) man page +being mirrored has "rsyncable" gzipped meta files, then using B<--diff=none> +may be the most efficient way to download them. See the B<gzip>(1) man page for information about its rsyncable option. -=item --gzip-options=options +=item B<--gzip-options>=I<options> -Specify alternative options to be used when calling gzip to compress meta -files after applying diffs. The default options are "-9 -n --rsyncable" +Specify alternative options to be used when calling B<gzip>(1) to compress meta +files after applying diffs. The default options are C<-9 -n --rsyncable> which corresponds with the options used to gzip meta files for the main Debian archive. -These options may need to be modified if the md5sum of the file as gzipped -by debmirror does not match the md5sum listed in the Release file (which +These options may need to be modified if the MD5 checksum of the file as +gzipped +by debmirror does not match the md5sum listed in the F<Release> file (which will result in the gzipped file being downloaded unnecessarily after diffs were successfully applied). -=item --slow-cpu +=item B<--slow-cpu> By default debmirror saves some bandwidth by performing cpu-intensive tasks, such as compressing files to generate .gz and .bz2 files. Use this mode if the computer's CPU is slow, and it makes more sense to use more bandwidth and less CPU. -This option implies --diff=none. +This option implies B<--diff=none>. -=item --state-cache-days=number +=item B<--state-cache-days>=I<number> Save the state of the mirror in a cache file between runs. The cache will expire after the specified number of days, at which time a full check and -cleanup of the mirror will be done. While the cache is valid, debmirror +cleanup of the mirror will be done. While the cache is valid, B<debmirror> will trust that the mirror is consistent with this cache. The cache is only used for files that have a unique name, i.e. binary @@ -379,22 +383,23 @@ Main advantage of using the state cache is that it avoids a large amount of disk access while checking which files need to be fetched. It may also reduce the time required for mirror updates. -=item --ignore-small-errors +=item B<--ignore-small-errors> -Normally debmirror will report an error if any deb files or sources +Normally B<debmirror> will report an error if any deb files or sources fail to download and refuse to update the meta data to an inconsistent mirror. Normally this is a good things as it indicates something went wrong during download and should be retried. But sometimes the -upstream mirror actually is broken. Specifying --ignore-small-errors -causes debmirror to ignore missing or broken deb and source files but +upstream mirror actually is broken. Specifying B<--ignore-small-errors> +causes B<debmirror> to ignore missing or broken deb and source files but still be pedantic about checking meta files. -=item --allow-dist-rename +=item B<--allow-dist-rename> The directory name for a dist should be equal to its Codename and not to a Suite. If the local mirror currently has directories named after Suites, -debmirror can rename them automatically. -An existing symlink S<codename -E<gt> suite> will be removed, but debmirror +B<debmirror> can rename them automatically. +An existing symlink from I<codename> to I<suite> will be removed, +but B<debmirror> will automatically create a new symlink S<suite -E<gt> codename> (immediately after moving meta files in place). This conversion should only be needed once.
