[devscripts] 12/12: uscan: new improved manpage with POD
Osamu Aoki
osamu at moszumanska.debian.org
Wed Sep 23 16:43:30 UTC 2015
This is an automated email from the git hooks/post-receive script.
osamu pushed a commit to branch multitar
in repository devscripts.
commit 0753c2fe6628d1599d1d20917647fbc4c72969b6
Author: Osamu Aoki <osamu at debian.org>
Date: Tue Sep 8 15:41:13 2015 +0000
uscan: new improved manpage with POD
* remove old uscan.1
* update Makefile
* update devscripts-po4a.conf
---
po4a/devscripts-po4a.conf | 4 +-
scripts/Makefile | 2 +-
scripts/uscan.1 | 596 --------------------
scripts/uscan.pl | 1313 +++++++++++++++++++++++++++++++++++++++++++--
4 files changed, 1268 insertions(+), 647 deletions(-)
diff --git a/po4a/devscripts-po4a.conf b/po4a/devscripts-po4a.conf
index ff6c490..6d8c845 100644
--- a/po4a/devscripts-po4a.conf
+++ b/po4a/devscripts-po4a.conf
@@ -120,8 +120,8 @@
$lang:$lang/tagpending.$lang.pl add_$lang:?add_$lang/translator_pod.add
[type:pod] ../scripts/transition-check.pl \
$lang:$lang/transition-check.$lang.pl add_$lang:?add_$lang/translator_pod.add
-[type:man] ../scripts/uscan.1 \
- $lang:$lang/uscan.$lang.1 add_$lang:?add_$lang/translator_man.add
+[type:pod] ../scripts/uscan.pl \
+ $lang:$lang/uscan.$lang.pod add_$lang:?add_$lang/translator_pod.add
[type:man] ../scripts/uupdate.1 \
$lang:$lang/uupdate.$lang.1 add_$lang:?add_$lang/translator_man.add
[type:man] ../doc/what-patch.1 \
diff --git a/scripts/Makefile b/scripts/Makefile
index 797c78f..872f9d2 100644
--- a/scripts/Makefile
+++ b/scripts/Makefile
@@ -22,7 +22,7 @@ COMPL_FILES := $(wildcard *.bash_completion)
COMPLETION = $(patsubst %.bash_completion,devscripts.%,$(COMPL_FILES))
COMPL_DIR := $(shell pkg-config --variable=completionsdir bash-completion)
-GEN_MAN1S += devscripts.1 mk-origtargz.1
+GEN_MAN1S += devscripts.1 mk-origtargz.1 uscan.1
all: $(SCRIPTS) $(GEN_MAN1S) $(CWRAPPERS) $(COMPLETION)
diff --git a/scripts/uscan.1 b/scripts/uscan.1
deleted file mode 100644
index bd9d2a7..0000000
--- a/scripts/uscan.1
+++ /dev/null
@@ -1,596 +0,0 @@
-.TH USCAN 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
-.SH NAME
-uscan \- scan/watch upstream sources for new releases of software
-.SH SYNOPSIS
-\fBuscan\fR [\fIoptions\fR] [\fIpath-to-debian-source-packages\fR ...]
-.SH DESCRIPTION
-\fBuscan\fR scans the given directories (or the current directory if
-none are specified) and all of their subdirectories for packages
-containing a control file \fIdebian/watch\fR. Parameters are then
-read from those control files and upstream ftp or http sites are
-inspected for newly available updates (as compared with the upstream
-version number retrieved from the \fIdebian/changelog\fR file in the
-same directory). The newest updates are retrieved (as determined by
-their version numbers) and if specified in the \fIwatch\fR file, a program
-may then be executed on the newly downloaded source.
-.PP
-The traditional \fIdebian/watch\fR files can still be used, but the
-current format offers both simpler and more flexible services. We do
-not describe the old format here; for their documentation, see the
-source code for \fRuscan\fR.
-
-.SH FORMAT of debian/watch files
-
-The following demonstrates the type of entries which can appear in a
-\fIdebian/watch\fR file. Obviously, not all of these would appear in
-one such file; usually, one would have one line for the current
-package.
-
-.PP
-.nf
-# format version number, currently 3; this line is compulsory!
-version=3
-
-# Line continuations are performed with \fB\e\fR
-
-# This is the format for an FTP site:
-# Full-site-with-pattern [Version [Action]]
-ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\e.tar\e.gz \e
- debian uupdate
-
-# This is the format for an FTP site with regex special characters in
-# the filename part
-ftp://ftp.worldforge.org/pub/worldforge/libs/Atlas-C++/transitional/Atlas-C\e+\e+-(.+)\e.tar\e.gz
-
-# This is the format for an FTP site with directory pattern matching
-ftp://ftp.nessus.org/pub/nessus/nessus-([\ed\e.]+)/src/nessus-core-([\ed\e.]+)\e.tar\e.gz
-
-# This can be used if you want to override the PASV setting
-# for a specific site
-# opts=pasv ftp://.../...
-
-# This is one format for an HTTP site, which is the same
-# as the FTP format. \fBuscan\fR starts by downloading the homepage,
-# obtained by removing the last component of the URL; in this case,
-# \fIhttp://www.cpan.org/modules/by-module/Text/\fR
-http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\e.tar\e.gz
-
-# This is a variant HTTP format which allows direct specification of
-# the homepage:
-# Homepage Pattern [Version [Action]]
-http://www.dataway.ch/~lukasl/amph/amph.html \e
- files/amphetamine-([\ed\e.]*).tar.bz2
-
-# This one shows that recursive directory scanning works, in either of
-# two forms, as long as the website can handle requests of the form
-# \fIhttp://site/inter/mediate/dir/\fR
-http://tmrc.mit.edu/mirror/twisted/Twisted/(\ed\e.\ed)/ \e
- Twisted-([\ed\e.]*)\e.tar\e.bz2
-http://tmrc.mit.edu/mirror/twisted/Twisted/(\ed\e.\ed)/Twisted-([\ed\e.]*)\e.tar\e.bz2
-
-# For maximum flexibility with upstream tarball formats, use this:
-http://example.com/example-(\ed[\ed\.]*)\e.(?:zip|tgz|tbz2|txz|tar\e.(?:gz|bz2|xz))
-
-# qa.debian.org runs a redirector which allows a simpler form of URL
-# for SourceForge based projects. The format below will automatically
-# be rewritten to use the redirector.
-http://sf.net/audacity/audacity-src-(.+)\e.tar\e.gz
-
-# For GitHub projects you can use the tags or releases page. Since the archive
-# URLs use only the version as the name, it is recommended to use a
-# filenamemangle to adjust the name of the downloaded file:
-opts="filenamemangle=s/(?:.*?\/)?v?(\ed[\ed.]*)\e.tar\e.gz/<project>-$1.tar.gz/" \e
- https://github.com/<user>/<project>/tags (?:.*?/)?v?(\ed[\ed.]*)\e.tar\e.gz
-
-# For Google Code projects you should use the downloads page like this:
-https://code.google.com/p/<project>/downloads/list?can=1 \e
- .*/<project>-(\ed[\ed.]*)\e.tar\e.gz
-
-# This is the format for a site which has funny version numbers;
-# the parenthesised groups will be joined with dots to make a
-# sanitised version number
-http://www.site.com/pub/foobar/foobar_v(\ed+)_(\ed+)\e.tar\e.gz
-
-# This is another way of handling site with funny version numbers,
-# this time using mangling. (Note that multiple groups will be
-# concatenated before mangling is performed, and that mangling will
-# only be performed on the basename version number, not any path
-# version numbers.)
-opts="uversionmangle=s/^/0.0./" \e
- ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/Wine-(.+)\e.tar\e.gz
-
-# Similarly, the upstream part of the Debian version number can be
-# mangled:
-opts=dversionmangle=s/\e+dfsg\ed*$// \e
- http://some.site.org/some/path/foobar-(.+)\e.tar\e.gz
-
-# The filename is found by taking the last component of the URL and
-# removing everything after any '\fB?\fR'. If this would not make a usable
-# filename, use filenamemangle. For example,
-# <A href="http://foo.bar.org/download/?path=&download=foo-0.1.1.tar.gz">
-# could be handled as:
-# opts=filenamemangle=s/.*=(.*)/$1/ \e
-# http://foo.bar.org/download/\e?path=&download=foo-(.+)\e.tar\e.gz
-#
-# <A href="http://foo.bar.org/download/?path=&download_version=0.1.1">
-# could be handled as:
-# opts=filenamemangle=s/.*=(.*)/foo-$1\e.tar\e.gz/ \e
-# http://foo.bar.org/download/\e?path=&download_version=(.+)
-
-# The option downloadurlmangle can be used to mangle the URL of the file
-# to download. This can only be used with http:// URLs. This may be
-# necessary if the link given on the web page needs to be transformed in
-# some way into one which will work automatically, for example:
-# opts=downloadurlmangle=s/prdownload/download/ \e
-# http://developer.berlios.de/project/showfiles.php?group_id=2051 \e
-# http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz
-
-.fi
-.PP
-Comment lines may be introduced with a `\fB#\fR' character. Continuation
-lines may be indicated by terminating a line with a backslash
-character.
-.PP
-The first (non-comment) line of the file must begin `version=3'. This
-allows for future extensions without having to change the name of the
-file.
-.PP
-There are two possibilities for the syntax of an HTTP \fIwatch\fR file line,
-and only one for an FTP line. We begin with the common (and simpler)
-format. We describe the optional opts=... first field below, and
-ignore it in what follows.
-.PP
-The first field gives the full pattern of URLs being searched for. In
-the case of an FTP site, the directory listing for the requested
-directory will be requested and this will be scanned for files
-matching the basename (everything after the trailing `\fB/\fR'). In the
-case of an HTTP site, the URL obtained by stripping everything after
-the trailing slash will be downloaded and searched for hrefs (links of
-the form <a href=...>) to either the full URL pattern given, or to the
-absolute part (everything without the http://host.name/ part), or to
-the basename (just the part after the final `\fB/\fR'). Everything up to
-the final slash is taken as a verbatim URL, as long as there are no
-parentheses (`\fB(\fR' and '\fB)\fR') in this part of the URL: if it does, the
-directory name will be matched in the same way as the final component
-of the URL as described below. (Note that regex metacharacters such
-as `\fB+\fR' are regarded literally unless they are in a path component
-containing parentheses; see the Atlas-C++ example above. Also, the
-parentheses must match within each path component.)
-.PP
-The pattern (after the final slash) is a Perl regexp (see
-\fBperlre\fR(1) for details of these). You need to make the pattern
-so tight that it matches only the upstream software you are interested
-in and nothing else. Also, the pattern will be anchored at the
-beginning and at the end, so it must match the full filename. (Note
-that for HTTP URLs, the href may include the absolute path or full
-site and path and still be accepted.) The pattern must contain at
-least one Perl group as explained in the next paragraph.
-.PP
-Having got a list of `files' matching the pattern, their version
-numbers are extracted by treating the part matching the Perl regexp
-groups, demarcated by `\fB(...)\fR', joining them with `\fB.\fR' as a separator,
-and using the result as the version number of the file. The version
-number will then be mangled if required by the uversionmangle option
-described below. Finally, the file versions are then compared to find
-the one with the greatest version number, as determined by \fBdpkg
-\-\-compare-versions\fR. Note that if you need Perl groups which are
-not to be used in the version number, either use `\fB(?:...)\fR' or use the
-uversionmangle option to clean up the mess!
-.PP
-The current (upstream) version can be specified as the second
-parameter in the \fIwatch\fR file line. If this is \fIdebian\fR or absent,
-then the current Debian version (as determined by
-\fIdebian/changelog\fR) is used to determine the current upstream
-version. The current upstream version may also be specified by the
-command-line option \fB\-\-upstream-version\fR, which specifies the
-upstream version number of the currently installed package (i.e., the
-Debian version number without epoch and Debian revision). The
-upstream version number will then be mangled using the dversionmangle
-option if one is specified, as described below. If the newest version
-available is newer than the current version, then it is downloaded
-into the parent directory, unless the \fB\-\-report\fR or
-\fB\-\-report-status\fR option has been used. Once the file has been
-downloaded, then a symlink to the file is made from
-\fI<package>_<version>.orig.tar.{gz|bz2|lzma|xz}\fR as described by the help
-for the \fB\-\-symlink\fR option.
-.PP
-Finally, if a third parameter (an action) is given in the \fIwatch\fR file
-line, this is taken as the name of a command, and the command
-.nf
- \fIcommand \fB\-\-upstream-version\fI version filename\fR
-.fi
-is executed, using either the original file or the symlink name. A
-common such command would be \fBuupdate\fR(1). (Note that the calling
-syntax was slightly different when using \fIwatch\fR file without a
-`\fBversion=\fR...' line; there the command executed was `\fIcommand filename
-version\fR'.) If the command is \fBuupdate\fR, then the
-\fB\-\-no\-symlink\fR option is given to \fBuupdate\fR as a first
-option, since any requested symlinking will already be done by
-\fBuscan\fR.
-.PP
-The alternative version of the \fIwatch\fR file syntax for HTTP URLs is as
-follows. The first field is a homepage which should be downloaded and
-then searched for hrefs matching the pattern given in the second
-field. (Again, this pattern will be anchored at the beginning and the
-end, so it must match the whole href. If you want to match just the
-basename of the href, you can use a pattern like
-".*/name-(.+)\e.tar\e.gz" if you know that there is a full URL, or
-better still: "(?:.*/)?name-(.+)\e.tar\e.gz" if there may or may not
-be. Note the use of (?:...) to avoid making a backreference.) If any
-of the hrefs in the homepage which match the (anchored) pattern are
-relative URLs, they will be taken as being relative to the base URL of
-the homepage (i.e., with everything after the trailing slash removed),
-or relative to the base URL specified in the homepage itself with a
-<base href="..."> tag. The third and fourth fields are the version
-number and action fields as before.
-.SH "PER-SITE OPTIONS"
-A \fIwatch\fR file line may be prefixed with `\fBopts=\fIoptions\fR', where
-\fIoptions\fR is a comma-separated list of options. The whole
-\fIoptions\fR string may be enclosed in double quotes, which is
-necessary if \fIoptions\fR contains any spaces. The recognised
-options are as follows:
-.TP
-\fBactive\fR and \fBpassive\fR (or \fBpasv\fR)
-If used on an FTP line, these override the choice of whether to use
-PASV mode or not, and force the use of the specified mode for this
-site.
-.TP
-\fBuversionmangle=\fIrules\fR
-This is used to mangle the upstream version number as matched by the
-ftp://... or http:// rules as follows. First, the \fIrules\fR string
-is split into multiple rules at every `\fB;\fR'. Then the upstream version
-number is mangled by applying \fIrule\fR to the version, in a similar
-way to executing the Perl command:
-.nf
- $version =~ \fIrule\fR;
-.fi
-for each rule. Thus, suitable rules might be `\fBs/^/0./\fR' to prepend
-`\fB0.\fR' to the version number and `\fBs/_/./g\fR' to change underscores into
-periods. Note that the \fIrule\fR string may not contain commas;
-this should not be a problem.
-
-\fIrule\fR may only use the '\fBs\fR', '\fBtr\fR' and '\fBy\fR' operations. When the '\fBs\fR'
-operation is used, only the '\fBg\fR', '\fBi\fR' and '\fBx\fR' flags are available and
-\fIrule\fR may not contain any expressions which have the potential to
-execute code (i.e. the (?{}) and (??{}) constructs are not supported).
-
-If the '\fBs\fR' operation is used, the replacement can contain
-backreferences to expressions within parenthesis in the matching regexp,
-like `\fBs/-alpha(\ed*)/.a$1/\fR'. These backreferences must use the
-`\fB$1\fR' syntax, as the `\fB\e1\fR' syntax is not supported.
-.TP
-\fBdversionmangle=\fIrules\fR
-This is used to mangle the Debian version number of the currently
-installed package in the same way as the \fBuversionmangle\fR option.
-Thus, a suitable rule might be `\fBs/\e+dfsg\ed*$//\fR' to remove a
-`\fB+dfsg1\fR' suffix from the Debian version number, or to handle `\fB.pre6\fR'
-type version numbers. Again, the \fIrules\fR string may not contain
-commas; this should not be a problem.
-.TP
-\fBversionmangle=\fIrules\fR
-This is a syntactic shorthand for
-\fBuversionmangle=\fIrules\fB,dversionmangle=\fIrules\fR, applying the
-same rules to both the upstream and Debian version numbers.
-.TP
-\fBfilenamemangle=\fIrules\fR
-This is used to mangle the filename with which the downloaded file
-will be saved, and is parsed in the same way as the
-\fBuversionmangle\fR option. Examples of its use are given in the
-examples section above.
-.TP
-\fBdownloadurlmangle=\fIrules\fR
-This is used to mangle the URL to be used for the download. The URL
-is first computed based on the homepage downloaded and the pattern
-matched, then the version number is determined from this URL.
-Finally, any rules given by this option are applied before the actual
-download attempt is made. An example of its use is given in the
-examples section above.
-.TP
-\fBpgpsigurlmangle=\fIrules\fR
-If present, the supplied rules will be applied to the downloaded URL
-(after any downloadurlmangle rules, if present) to craft a new URL
-that will be used to fetch the detached OpenPGP signature file for the
-upstream tarball. Some common rules might be `\fBs/$/.asc/\fR' or
-`\fBs/$/.pgp/\fR' or `\fBs/$/.gpg/\fR'. This signature must be made
-by a key found in the keyring \fBdebian/upstream/signing-key.pgp\fR or
-the armored keyring \fBdebian/upstream/signing-key.asc\fR. If it is not
-valid, or not made by one of the listed keys, uscan will report an
-error.
-.TP
-\fBrepacksuffix=\fIsuffix\fR
-If the upstream sources are modified because \fIdebian/copyright\fR contains
-the \fBFiles-Excluded\fR field, \fIsuffix\fR will be appended to the upstream
-version of the repacked tar archive. Common suffixes might be \fB+dfsg1\fR to
-indicate the removal of files that are not DFSG-compliant or \fB+ds1\fR for
-other reasons such as removal of prebuilt files or large embedded code copies.
-.SH "Directory name checking"
-Similarly to several other scripts in the \fBdevscripts\fR package,
-\fBuscan\fR explores the requested directory trees looking for
-\fIdebian/changelog\fR and \fIdebian/watch\fR files. As a safeguard
-against stray files causing potential problems, and in order to
-promote efficiency, it will examine the name of the parent directory
-once it finds the \fIdebian/changelog\fR file, and check that the
-directory name corresponds to the package name. It will only attempt
-to download newer versions of the package and then perform any
-requested action if the directory name matches the package name.
-Precisely how it does this is controlled by two configuration file
-variables \fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR and
-\fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR, and their corresponding command-line
-options \fB\-\-check-dirname-level\fR and
-\fB\-\-check-dirname-regex\fR.
-.PP
-\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR can take the following values:
-.TP
-.B 0
-Never check the directory name.
-.TP
-.B 1
-Only check the directory name if we have had to change directory in
-our search for \fIdebian/changelog\fR, that is, the directory
-containing \fIdebian/changelog\fR is not the directory from which
-\fBuscan\fR was invoked. This is the default behaviour.
-.TP
-.B 2
-Always check the directory name.
-.PP
-The directory name is checked by testing whether the current directory
-name (as determined by \fBpwd\fR(1)) matches the regex given by the
-configuration file option \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR or by the
-command line option \fB\-\-check-dirname-regex\fR \fIregex\fR. Here
-\fIregex\fR is a Perl regex (see \fBperlre\fR(3perl)), which will be
-anchored at the beginning and the end. If \fIregex\fR contains a '/',
-then it must match the full directory path. If not, then it must
-match the full directory name. If \fIregex\fR contains the string
-\'PACKAGE', this will be replaced by the source package name, as
-determined from the \fIchangelog\fR. The default value for the regex is:
-\'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and
-PACKAGE-version.
-.SH EXAMPLE
-This script will perform a fully automatic upstream update.
-
-.nf
-#!/bin/sh \-e
-# called with '\-\-upstream-version' <version> <file>
-uupdate "$@"
-package=`dpkg\-parsechangelog | sed \-n 's/^Source: //p'`
-cd ../$package-$2
-debuild
-.fi
-
-Note that we don't call \fBdupload\fR or \fBdput\fR automatically, as
-the maintainer should perform sanity checks on the software before
-uploading it to Debian.
-.SH OPTIONS
-.TP
-.B \-\-report\fP, \fB\-\-no\-download
-Only report about available newer versions but do not download anything.
-.TP
-.B \-\-report\-status
-Report on the status of all packages, even those which are up-to-date,
-but do not download anything.
-.TP
-.B \-\-download
-Report and download. (This is the default behaviour.)
-.TP
-.B \-\-destdir
-Path of directory to which to download. If the specified path is not
-absolute, it will be relative to one of the current directory or, if directory
-scanning is enabled, the package's source directory.
-.TP
-.B \-\-force-download
-Download upstream even if up to date (will not overwrite local files, however)
-.TP
-.B \-\-pasv
-Force PASV mode for FTP connections.
-.TP
-.B \-\-no\-pasv
-Do not use PASV mode for FTP connections.
-.TP
-\fB\-\-timeout\fR \fIN\fR
-Set timeout to N seconds (default 20 seconds).
-.TP
-.B \-\-no\-symlink
-Do not call \fBmk\-origtargz\fR.
-.P
-The following options are passed to \fBmk\-origtargz\fR:
-.RS
-.TP
-.B \-\-symlink
-Make \fIorig.tar.gz\fR (with the appropriate extension) symlinks to the
-downloaded files.
-(This is the default behaviour.)
-.TP
-.B \-\-copy
-Instead of symlinking as described above, copy the downloaded files.
-.TP
-.B \-\-rename
-Instead of symlinking as described above, rename the downloaded files.
-.TP
-.B \-\-repack
-After having downloaded an lzma tar, xz tar, bzip tar or zip archive,
-repack it to a gzip tar archive, if required.
-The \fBunzip\fR package must be installed in order to repack .zip archives, the
-\fBxz-utils\fR package must be installed to repack lzma or xz tar archives.
-.TP
-\fB\-\-compression\fR [ \fBgzip\fR | \fBbzip2\fR | \fBlzma\fR | \fBxz\fR ]
-In the case where the upstream sources are repacked (either because
-\fB\-\-repack\fR option is given or \fIdebian/copyright\fR contains the
-field \fBFiles-Excluded\fR), it is possible to control the compression
-method via the parameter (defaults to \fBgzip\fR).
-.TP
-.B \-\-copyright\-file \fIcopyright-file\fR
-Exclude files mentioned in \fBFiles-Excluded\fR in the given copyright file.
-This is useful when running uscan not within a source package directory.
-.RE
-.TP
-.B \-\-dehs
-Use an XML format for output, as required by the DEHS system.
-.TP
-.B \-\-no-dehs
-Use the traditional uscan output format. (This is the default behaviour.)
-.TP
-\fB\-\-package\fR \fIpackage\fR
-Specify the name of the package to check for rather than examining
-\fIdebian/changelog\fR; this requires the \fB\-\-upstream-version\fR
-(unless a version is specified in the \fIwatch\fR file)
-and \fB\-\-watchfile\fR options as well. Furthermore, no directory
-scanning will be done and nothing will be downloaded. This option is
-probably most useful in conjunction with the DEHS system (and
-\fB\-\-dehs\fR).
-.TP
-\fB\-\-upstream-version\fR \fIupstream-version\fR
-Specify the current upstream version rather than examine the \fIwatch\fR file
-or \fIchangelog\fR to determine it. This is ignored if a directory scan is
-being performed and more than one \fIwatch\fR file is found.
-.TP
-\fB\-\-watchfile\fR \fIwatchfile\fR
-Specify the \fIwatchfile\fR rather than perform a directory scan to
-determine it. If this option is used without \fB\-\-package\fR, then
-\fBuscan\fR must be called from within the Debian package source tree
-(so that \fIdebian/changelog\fR can be found simply by stepping up
-through the tree).
-.TP
-\fB\-\-download\-version\fR \fIversion\fR
-Specify the version which the upstream release must match in order to be
-considered, rather than using the release with the highest version.
-.TP
-\fB\-\-download\-current\-version\fR
-Download the currently packaged version
-.TP
-.B \-\-verbose
-Give verbose output.
-.TP
-.B \-\-no\-verbose
-Don't give verbose output. (This is the default behaviour.)
-.TP
-.B \-\-no\-exclusion
-Do not automatically exclude files mentioned in
-\fIdebian/copyright\fR field \fBFiles-Excluded\fR
-.TP
-.B \-\-debug
-Dump the downloaded web pages to stdout for debugging your watch file.
-.TP
-\fB\-\-check-dirname-level\fR \fIN\fR
-See the above section \fBDirectory name checking\fR for an explanation of
-this option.
-.TP
-\fB\-\-check-dirname-regex\fR \fIregex\fR
-See the above section \fBDirectory name checking\fR for an explanation of
-this option.
-.TP
-\fB\-\-user-agent\fR, \fB\-\-useragent\fR
-Override the default user agent header.
-.TP
-\fB\-\-no-conf\fR, \fB\-\-noconf\fR
-Do not read any configuration files. This can only be used as the
-first option given on the command-line.
-.TP
-.B \-\-help
-Give brief usage information.
-.TP
-.B \-\-version
-Display version information.
-.SH "CONFIGURATION VARIABLES"
-The two configuration files \fI/etc/devscripts.conf\fR and
-\fI~/.devscripts\fR are sourced by a shell in that order to set
-configuration variables. These may be overridden by command line
-options. Environment variable settings are ignored for this purpose.
-If the first command line option given is \fB\-\-noconf\fR, then these
-files will not be read. The currently recognised variables are:
-.TP
-.B USCAN_DOWNLOAD
-If this is set to \fIno\fR, then newer upstream files will not be
-downloaded; this is equivalent to the \fB\-\-report\fR or
-\fB\-\-no\-download\fR options.
-.TP
-.B USCAN_PASV
-If this is set to \fIyes\fR or \fIno\fR, this will force FTP
-connections to use PASV mode or not to, respectively. If this is set
-to \fIdefault\fR, then \fBNet::FTP\fR(3) makes the choice (primarily based on
-the \fBFTP_PASSIVE\fR environment variable).
-.TP
-.B USCAN_TIMEOUT
-If set to a number \fIN\fR, then set the timeout to \fIN\fR seconds.
-This is equivalent to the \fB\-\-timeout\fR option.
-.TP
-.B USCAN_SYMLINK
-If this is set to \fIno\fR, then a pkg_version.orig.tar.{gz|bz2|lzma|xz}
-symlink will not be made (equivalent to the \fB\-\-no\-symlink\fR
-option). If it is set to \fIyes\fR or \fIsymlink\fR, then the
-symlinks will be made. If it is set to \fIrename\fR, then the files
-are renamed (equivalent to the \fB\-\-rename\fR option).
-.TP
-.B USCAN_DEHS_OUTPUT
-If this is set to \fIyes\fR, then DEHS-style output will be used.
-This is equivalent to the \fB\-\-dehs\fR option.
-.TP
-.B USCAN_VERBOSE
-If this is set to \fIyes\fR, then verbose output will be given. This
-is equivalent to the \fB\-\-verbose\fR option.
-.TP
-.B USCAN_USER_AGENT
-If set, the specified user agent string will be used in place of the
-default. This is equivalent to the \fB\-\-user-agent\fR option.
-.TP
-.B USCAN_DESTDIR
-If set, the downloaded files will be placed in this directory. This is
-equivalent to the \fB\-\-destdir\fR option.
-.TP
-.B USCAN_REPACK
-If this is set to \fIyes\fR, then after having downloaded a bzip tar,
-lzma tar, xz tar, or zip archive, \fBuscan\fR will repack it to a gzip tar.
-This is equivalent to the \fB\-\-repack\fR option.
-.TP
-.B USCAN_EXCLUSION
-If this is set to \fIno\fR, files mentioned in the field \fBFiles-Excluded\fR
-of \fIdebian/copyright\fR will be ignored and no exclusion of files will be
-tried. This is equivalent to the \fB\-\-no-exclusion\fR option.
-.SH "EXIT STATUS"
-The exit status gives some indication of whether a newer version was
-found or not; one is advised to read the output to determine exactly
-what happened and whether there were any warnings to be noted.
-.TP
-0
-Either \fB\-\-help\fR or \fB\-\-version\fR was used, or for some
-\fIwatch\fR file which was examined, a newer upstream version was located.
-.TP
-1
-No newer upstream versions were located for any of the \fIwatch\fR files
-examined.
-.SH "HISTORY AND UPGRADING"
-This section briefly describes the backwards-incompatible \fIwatch\fR file
-features which have been added in each \fIwatch\fR file version, and the
-first version of the \fBdevscripts\fR package which understood them.
-.TP
-.I Pre-version 2
-The \fIwatch\fR file syntax was significantly different in those days. Don't
-use it. If you are upgrading from a pre-version 2 \fIwatch\fR file, you are
-advised to read this manpage and to start from scratch.
-.TP
-.I Version 2
-devscripts version 2.6.90: The first incarnation of the current style
-of \fIwatch\fR files.
-.TP
-.I Version 3
-devscripts version 2.8.12: Introduced the following: correct handling
-of regex special characters in the path part, directory/path pattern
-matching, version number in several parts, version number mangling.
-Later versions have also introduced URL mangling.
-
-If you are upgrading from version 2, the key incompatibility is if you
-have multiple groups in the pattern part; whereas only the first one
-would be used in version 2, they will all be used in version 3. To
-avoid this behaviour, change the non-version-number groups to be
-(?:...) instead of a plain (...) group.
-.SH "SEE ALSO"
-.BR dpkg (1),
-.BR mk\-origtargz (1),
-.BR perlre (1),
-.BR uupdate (1),
-.BR devscripts.conf (5)
-.SH AUTHOR
-The original version of \fBuscan\fR was written by Christoph Lameter
-<clameter at debian.org>. Significant improvements, changes and bugfixes
-were made by Julian Gilbey <jdg at debian.org>. HTTP support was added
-by Piotr Roszatycki <dexter at debian.org>. The program was rewritten
-in Perl by Julian Gilbey.
diff --git a/scripts/uscan.pl b/scripts/uscan.pl
index df30f72..55c5b0f 100755
--- a/scripts/uscan.pl
+++ b/scripts/uscan.pl
@@ -22,6 +22,1270 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
+=pod
+
+=head1 NAME
+
+uscan - scan/watch upstream sources for new releases of software
+
+=head1 SYNOPSIS
+
+B<uscan> [I<options>] [I<path>]
+
+=head1 DESCRIPTION
+
+For the basic usage, B<uscan> is executed without any arguments from the root
+of the Debianized source tree where you see the F<debian/> directory. Then
+typically the following happens:
+
+=over
+
+=item * B<uscan> reads the first entry in F<debian/changelog> to determine the
+source package name I<< <spkg> >> and the last upstream version.
+
+=item * B<uscan> process the watch lines F<debian/watch> from the top to the
+bottom in 1 pass.
+
+=over
+
+=item * B<uscan> downloads a web page from the specified I<URL> in
+F<debian/watch>.
+
+=item * B<uscan> extracts hrefs pointing to the upstream tarball(s) from the
+web page using the specified I<matching-pattern> in F<debian/watch>.
+
+=item * B<uscan> downloads the upstream tarball with the highest version newer
+than the last upstream version.
+
+=item * B<uscan> saves the downloaded tarball to the parent B<../> directory:
+I<< ../<upkg>-<uversion>.tar.gz >>
+
+=item * B<uscan> invokes B<mk-origtargz> to create the source tarball: I<<
+../<spkg>_<oversion>.orig.tar.gz >>
+
+=over
+
+=item * Here, I<< ../<spkg>_<oversion>.orig-<component>.tar.gz >> instead for
+the secondary upstream tarball of the multiple upstream tarball (MUT) package.
+
+=back
+
+=item * Repeat until all lines in F<debian/watch> are processed.
+
+=back
+
+=item * B<uscan> invokes B<uupdate> to create the Debianized source tree: I<<
+../<spkg>-<oversion>/* >>
+
+=back
+
+Please note the following.
+
+=over
+
+=item * For simplicity, the compression method used in examples is B<gzip> with
+B<.gz> suffix. Other methods such as B<xz>, B<bzip2>, and B<lzma> may also be
+used.
+
+=item * The new B<version=4> enables to handle the MUT package but it is a rare
+case for the Debian packaging. For the single upstream tarball package, there
+is only one watch line and no I<< ../<spkg>_<oversion>.orig-<component>.tar.gz
+>> .
+
+=item * B<uscan> with the B<--report> option produces a human readable report
+without downloading the upstream tarball.
+
+=item * B<uscan> with the B<--verbose> option produces a human readable report
+of the B<uscan> execution.
+
+=item * B<uscan> with the B<--debug> option produces a human readable report of
+the B<uscan> execution with the internal variable states.
+
+=item * B<uscan> with the B<--dehs> option produces the upstream package status
+report without downloading the upstream tarball in an XML format for other
+programs such as the Debian External Health System.
+
+=back
+
+=head1 FORMAT OF THE WATCH FILE
+
+The current version 4 format of F<debian/watch> can be summarized as follows:
+
+=over
+
+=item * Leading spaces and tabs are dropped.
+
+=item * Empty lines are dropped.
+
+=item * A line started by B<#> (hash) is a comment line and dropped.
+
+=item * Single B<\> (back slash) at the end of a line is dropped and the
+next line is concatenated after removing leading spaces and tabs. The
+concatenated line is parsed as a single line. (The existence and non-existence
+of the space before the tailing single B<\> is significant.)
+
+=item * The first non-comment line is:
+
+=over
+
+=item B<version=4>
+
+=back
+
+This is required.
+
+=item * The following non-comment lines (watch lines) specify the rule for the
+selection of the candidate upstream tarball URLs and are in one of the
+following 3 formats:
+
+=over
+
+=item * B<opts="> I<...> B<"> B<http://>I<URL> I<matching-pattern> [I<version> [I<script>]]
+
+=item * B<http://>I<URL> I<matching-pattern> [I<version> [I<script>]]
+
+=item * B<opts="> I<...> B<">
+
+=back
+
+Here,
+
+=over
+
+=item * B<opts="> I<...> B<"> specifies the behavior of B<uscan>. See L<WATCH
+FILE OPTIONS>.
+
+=item * B<http://>I<URL> specifies the web page where the upstream publishes
+the link to the latest upstream source archive.
+
+=over
+
+=item * B<https://>I<URL> instead may be used, too.
+
+=item * B<ftp://>I<URL> pointing to the archive directory instead may be used,
+too.
+
+=item * Some parts of I<URL> may be in the regex match pattern surrounded
+between B<(> and B<)> such as B</foo/bar-([\.\d]+)/>. (If multiple
+directories match, the highest version one is picked.) Otherwise, the I<URL>
+is taken as verbatim.
+
+=back
+
+=item * I<matching-pattern> specifies the full string matching pattern for
+hrefs in the web page. See L<WATCH FILE EXAMPLES>.
+
+=over
+
+=item * All matching parts in B<(> and B<)> are concatenated with B<.> (period)
+to form the upstream version.
+
+=item * If the hrefs do not contain directory, you can combine this with the
+previous entry. I.e., B<http://>I<URL>B</>I<matching-pattern> .
+
+=back
+
+=item * I<version> limits the downloading upstream tarball. The newest
+available version is chosen for the download.
+
+=over
+
+=item * B<debian> limits the downloading upstream tarball to be newer than the
+version obtained from F<debian/changelog>.
+
+=item * I<version-number> such as B<12.5> limits the downloading upstream
+tarball to be newer than the I<version-number>.
+
+=item * B<same> limits the downloading version of the secondary tarballs to be
+exactly the same as the one for the first upstream tarball downloaded. (useful
+only for MUT)
+
+=item * B<previous> limits the downloading version of the signature
+file. (used with sigmode=previous)
+
+=item * B<ignore> does not limit the downloading version of the secondary
+tarballs. (maybe useful for MUT)
+
+=back
+
+=item * I<script> is executed at the end of B<uscan> execution with appropriate
+arguments provided by the B<uscan>.
+
+=over
+
+=item * The typical Debian package is the non-native package made from one
+upstream tarball. Only a single line of the watch line in one of the first 2
+formats is usually used with its I<version> set to B<debian> and I<script>
+set to B<uupdate>.
+
+=item * The native package should skip specifying I<script>.
+
+=item * The multiple upstream tarball package should specify B<uupdate> as
+I<script> at the last watch line and should skip specifying I<script> at
+the rest of the watch lines.
+
+=back
+
+=item * The last format of the watch line is useful to set the persistent
+parameters. If this is used, this must be followed by the I<URL> defining
+watch line(s).
+
+=item * [ and ] in the above format are there to mark the optional parts and
+should not be typed.
+
+=back
+
+=back
+
+=head1 WATCH FILE OPTIONS
+
+B<uscan> reads the watch options specified in B<opts="> I<...> B<"> to
+customize its behavior. Multiple options I<option1>, I<option2>, I<option3>,
+... can be set as B<opts=">I<option1>B<,> I<option2>B<,> I<option3>B<,> I< ...
+>B<"> . The double quotes are necessary if options contain any spaces.
+
+Unless otherwise noted as persistent, most options are valid only within the
+watch line.
+
+The available watch options are:
+
+=over
+
+=item B<component=>I<component>
+
+Set the name of the secondary source tarball as I<<
+<spkg>_<oversion>.orig-<component>.tar.gz >> for the MUT package
+
+=item B<compression=>I<method>
+
+Set the compression I<method> when it is repacked. (persistent)
+
+Available I<method> values are B<xz>, B<gzip> (alias B<gz>), B<bzip2> (alias
+B<bz2>), and B<lzma>.
+
+Please note the repack of the upstream tarballs happen in several cases:
+
+=over
+
+=item * B<USCAN_REPACK> is set in the devscript configuration. See L<DEVSCRIPT
+CONFIGURATION VARIABLES>.
+
+=item * B<--repack> is set in the commandline. See <COMMANDLINE OPTIONS>.
+
+=item * The upstream tarballs contain files listed under the B<Files-Excluded>
+and B<Files-Excluded->I<component> stanza of F<debian/copyright>. See
+mk-origtargz(1).
+
+=back
+
+=item B<repack>
+
+Force to repack the upstream tarball using the compression I<mathod>.
+
+=item B<repacksuffix=>I<suffix>
+
+Add I<suffix> to the version as suffix when the source tarball is repackaged.
+(persistent) This rule should be used only for the single upstream package.
+
+=item B<sigmode=>I<mode>
+
+Set the pgp/gpg signature verification I<mode>.
+
+=over
+
+=item B<mangle>
+
+Use B<pgpsigurlmangle=>I<rules> to generate the candidate upstream signature file
+URL string from the upstream tarball URL. (default)
+
+=item B<next>
+
+Verify this downloaded file by the next downloaded signature file. The next watch line must be B<previous>. Otherwise, no verification.
+
+=item B<previous>
+
+Verify the previous downloaded file by this signature file. The previous watch line must be B<next>.
+
+=item B<self>
+
+Verify the file by the self signature (not implemented yet)
+
+=item B<none>
+
+No signature available. (No warning.)
+
+=back
+
+=item B<user-agent=>I<user-agent-string>
+
+Set the user-agent string used to contact the HTTP(S) server as
+I<user-agent-string>. (persistent)
+
+B<user-agent> option should be specified by itself in the watch line without
+I<URL> and other options to allow using semicolons and commas in it.
+
+=item B<pasv>, B<passsive>
+
+Use PASV mode for the FTP connection.
+
+If the PASV mode is required due to the client side network environment, set
+B<uscan> to use PASV mode via L<COMMANDLINE OPTIONS> or L<DEVSCRIPT
+CONFIGURATION VARIABLES> instead.
+
+=item B<active>, B<nopasv>
+
+Don't use PASV mode for the FTP connection.
+
+=item B<dversionmangle=>I<rules>
+
+Normalize the last upstream version string found in
+F<debian/changelog>
+
+=item B<pagemangle=>I<rules>
+
+Normalize the downloaded web page string
+
+=item B<uversionmangle=>I<rules>
+
+Normalize the candidate upstream version strings
+extracted from hrefs in the source of the web page.
+
+=item B<versionmangle=>I<rules>
+
+Syntactic shorthand for B<uversionmangle=>I<rules>B<,dversionmangle=>I<rules>
+
+=item B<filenamemangle=>I<rules>
+
+Normalize the downloaded tarball filename string I<< <upkg>-<uversion>.tar.gz
+>>.
+
+=item B<oversionmangle=>I<rules>
+
+Generate the version string I<< <oversion> >> of the source tarball I<<
+<spkg>_<oversion>.orig.tar.gz >> from I<< <uversion> >>.
+
+=item B<downloadurlmangle=>I<rules>
+
+Normalize the candidate upstream tarball URL
+string
+
+=item B<pgpsigurlmangle=>I<rules>
+
+Generate the candidate upstream signature file
+URL string from the upstream tarball URL.
+
+=back
+
+Here, the mangling rules apply the I<rules> to the pertinent string. Multiple
+rules can be specified in a mangling rule by making a concatenated string of
+each mangling I<rule> separated by B<;> (semicolon).
+
+Each mangling I<rule> can not contain B<;> (semicolon) nor B<,> (comma).
+
+Each mangling I<rule> behaves as if a Perl command "I<$string> B<~=>
+I<rule>" is executed. There are some notable details.
+
+=over
+
+=item * I<rule> may only use the B<s>, B<tr>, and B<y> operations.
+
+=over
+
+=item B<s/>I<regex>B</>I<replacement>B</>I<options>
+
+Regex pattern match and replace the target string. Only the B<g>, B<i> and
+B<x> flags are available. Use the B<$1> syntax for the back reference (No
+B<\1> syntax). Code execution is not allowed (i.e. No B<(?{})> nor B<(??{})>
+constructs).
+
+=item B<y/>I<source>B</>I<dest>B</> or B<tr/>I<source>B</>I<dest>B</>
+
+Transliterate the characters in the target string.
+
+=back
+
+=back
+
+=head1 EXAMPLE OF EXECUTION
+
+B<uscan> reads the first entry in F<debian/changelog> to determine the source
+package name and the last upstream version.
+
+For example, if the first entry of F<debian/changelog> may be:
+
+=over
+
+=item * I<< bar >> (B<3:2.03+dfsg1-4>) unstable; urgency=low
+
+=back
+
+then, the source package name is I<< bar >> and the last upstream version
+is B<3:2.03+dfsg1-4>.
+
+The last upstream version is normalized to B<2.03+dfsg1> by removing the epoch
+and the Debian revision.
+
+If the B<dversionmangle> rule exists, the last upstream version is further
+normalized by applying this rule to it. For example, if the last upstream
+version is B<2.03+dfsg1> indicating the source tarball is repackaged, the
+suffix B<+dfsg1> is removed by the string substitution B<s/\+dfsg\d*$//> to
+make the (dversionmangled) last upstream version B<2.03> and it is compared to
+the candidate upstream tarball versions such as B<2.03>, B<2.04>, ... found in
+the remote site. Thus, set this rule as:
+
+=over
+
+=item * B<opts="dversionmangle=s/\+dfsg\d*$//">
+
+=back
+
+B<uscan> downloads a web page from B<http://>I<URL> specified in
+F<debian/watch>.
+
+=over
+
+=item * If the directory name part of I<URL> has no parentheses, B<(> and B<)>,
+it is taken as verbatim.
+
+=item * If the directory name part of I<URL> has parentheses, B<(> and B<)>,
+then B<uscan> recursively searches all possible directories to find a page for
+the newest version.
+
+=back
+
+For example, this B<http://>I<URL> may be specified as:
+
+=over
+
+=item * B<http://www.example.org/DL(.+)/>
+
+=back
+
+Please note the trailing B</> in the above.
+
+If the B<pagemangle> rule exists, the whole downloaded web page as a string is
+normalized by applying this rule to it. This is very powerful tool and needs to
+be used with caution. If other mangling rules can be used to address your
+objective, do not use this rule.
+
+The downloaded web page is scanned for hrefs defined in the B<< <a href=" >>
+I<...> B<< "> >> tag to locate the candidate upstream tarball URLs. These
+candidate upstream tarball URLs are matched by the Perl regex pattern
+I<matching-pattern> such as B<< DL-(?:[\d\.]+?)/foo-(.+)\.tar\.gz >> to
+narrow down the candidates. This pattern match needs to be anchored at the
+beginning and the end. For example, candidate URLs may be:
+
+=over
+
+=item * B<< DL-2.02/foo-2.02.tar.gz >>
+
+=item * B<< DL-2.03/foo-2.03.tar.gz >>
+
+=item * B<< DL-2.04/foo-2.04.tar.gz >>
+
+=back
+
+Here the matching string of B<(.+)> in I<matching-pattern> is considered as the
+candidate upstream version. If there are multiple matching strings of
+capturing patterns in I<matching-pattern>, they are all concatenated with B<.>
+(period) to form the candidate upstream version. Make sure to use the
+non-capturing regex such as B<(?:[\d\.]+?)> instead for the variable text
+matching part unrelated to the version.
+
+Then, the candidate upstream versions are:
+
+=over
+
+=item * B<2.02>
+
+=item * B<2.03>
+
+=item * B<2.04>
+
+=back
+
+The downloaded tarball filename is basically set to the same as its filename in
+the remote URL.
+
+If the B<uversionmangle> rule exists, the candidate upstream versions are
+normalized by applying this rule to them. (This rule may be useful if the
+upstream version scheme doesn't sort correctly to identify the newest
+version.)
+
+The upstream tarball URL corresponding to the newest (uversionmangled) candidate
+upstream version newer than the (dversionmangled) last upstream version is
+selected to be the candidate upstream tarball URL.
+
+Here, the order of the version is decided by B<dpkg --compare-versions>.
+
+If the B<filenamemangle> rule exists, the downloaded tarball filename is
+normalized by applying this rule to it. (This rule may not be as significant
+for modern use cases. B<mk-origtargz> takes care the proper renaming of the
+source tarballs into <spkg>_<oversion>.orig.tar.gz based on the source package
+name in F<debian/changelog> without relying on the filename of the remote URL.
+Now, B<uupdate> is invoked by B<uscan> with B<--find> option and is not
+expected to rename the downloaded tarball anymore.)
+
+If the candidate upstream tarball URL is a relative URL, it is converted to a
+absolute URL using the base URL of the web page. If the B<< <base href=" >> I<
+... > B<< "> >> tag exists in the web page, the candidate upstream tarball URL
+is converted to the absolute URL using the specified base URL in the base tag,
+instead.
+
+If the B<downloadurlmangle> rule exists, the candidate upstream tarball URL is
+normalized by applying this rule to it. (This is useful for some sites with the
+obfuscated download URL.)
+
+B<uscan> downloads the candidate upstream tarball to the parent B<../>
+directory. For example, the downloaded file may be:
+
+=over
+
+=item * F<../foo-2.04.tar.gz>
+
+=back
+
+Let's call this downloaded version B<2.04> in the above example generically as
+I<< <uversion> >> in the following.
+
+If the B<pgpsignurlmangle> rule exists, the upstream signature file URL is
+generated by applying this rule to the (downloadurlmangled) candidate upstream
+tarball URL and the signature file is tried to be downloaded.
+
+If the B<pgpsignurlmangle> rule doesn't exist, B<uscan> tries to download the
+matching upstream signature file assuming they are available from the same URL
+with their filename being suffixed by the 4 common suffix B<asc>, B<gpg>,
+B<pgp>, and B<sig>.
+
+If the signature file is downloaded, the downloaded upstream tarball is checked
+for its authenticity against the downloaded signature file using the keyring
+F<debian/upstream/signing-key.pgp> or the armored keyring
+F<debian/upstream/signing-key.asc>. If its signature is not valid, or not made
+by one of the listed keys, B<uscan> will report an error.
+
+If the B<oversionmangle> rule exists, the source tarball version I<oversion> is
+generated from the downloaded upstream version I<uversion> by applying this
+rule. This rule is useful to add suffix such as B<+dfsg1> to the version of all
+the source packages of the MUT package for which the repacksuffix mechanism
+doesn't work well.
+
+B<uscan> invokes B<mk-origtargz> to create the source tarball properly named
+for the source package with B<.orig.> in its filename.
+
+=over
+
+=item case A: packaging of the upstream tarball as is
+
+B<mk-origtargz> creates a symlink I<< ../bar_<oversion>.orig.tar.gz >>
+linked to the downloaded local upstream tarball. Here, I<< bar >> is the source
+package name found in F<debian/changelog>. The generated symlink may be:
+
+=over
+
+=item * F<../bar_2.04.orig.tar.gz> -> F<foo-2.04.tar.gz> (as is)
+
+=back
+
+Usually, there is no need to set up B<opts="dversionmangle=> I<...> B<"> for
+this case.
+
+=item case B: packaging of the upstream tarball after removing non-DFSG files
+
+B<mk-origtargz> checks the filename glob of the B<Files-Excluded> stanza in the
+first section of F<debian/copyright>, removes matching files to create a
+repacked upstream tarball. Normally, the repacked upstream tarball is renamed
+with I<suffix> to I<< ../bar_<oversion><suffix>.orig.tar.gz >> using
+the B<repacksuffix> option for the single upstream package. Here I<< <oversion> >>
+is updated to be I<< <oversion><suffix> >>.
+
+The removal of files is required if files are not DFSG-compliant. For such
+case, B<+dfsg1> is used as I<suffix>.
+
+So the combined options are set as
+B<opts="dversionmangle=s/\+dfsg\d*$// ,repacksuffix=+dfsg1">, instead.
+
+For example, the repacked upstream tarball may be:
+
+=over
+
+=item * F<../bar_2.04+dfsg1.orig.tar.gz> (repackaged)
+
+=back
+
+=back
+
+B<uscan> normally invokes "B<uupdate> B<--find --upstream-version>
+I<oversion> " for the version=4 watch file.
+
+Please note that B<--find> option is used here since B<mk-origtargz> has been
+invoked to make B<*.orig.tar.gz> file already. B<uscan> picks I<< bar >> from
+F<debian/changelog>.
+
+It creates the new upstream source tree under the
+I<< ../bar-<oversion> >> directory and Debianize it leveraging the
+last package contents.
+
+=head1 WATCH FILE EXAMPLES
+
+When writing the watch file, you should rely on the latest upstream source
+announcement web page. You should not try to second guess the upstream archive
+structure if possible. Here are the typical F<debian/watch> files.
+
+The existance and non-existance of a space before tailing B<\> (back slash) are
+significant.
+
+=head2 HTTP site (basic)
+
+For the basic single upstream tarball case:
+
+ version=4
+ http://example.com/~user/release/foo.html \
+ files/foo-([\d\.]*).tar.gz debian uupdate
+
+If source package name is B<foo> and downloaded version of the main upstream
+tarball is B<2.0>, then B<foo_2.0.orig.tar.gz>.
+
+=head2 HTTP site (basic MUT)
+
+For the basic 2 upstream tarball case:
+
+ version=4
+ http://example.com/~user/release/foo.html \
+ files/foo-([\d\.]*).tar.gz debian true
+ opts=component=baz \
+ http://example.com/~user/release/foo.html \
+ files/baz-([\d\.]*).tar.gz same uupdate
+
+If source package name is B<foo> and downloaded version of the main upstream
+tarball is B<2.0>, then B<foo_2.0.orig.tar.gz> and B<foo_2.0.orig-baz.tar.gz>
+are created.
+
+=head2 HTTP site (flexible)
+
+For the maximum flexibility of upstream tarball formats:
+
+ version=4
+ http://example.com/example-(\d[\d.]*)\.\
+ (?:zip|tgz|tbz2|txz|tar\.(?:gz|bz2|xz)) debian uupdate
+
+=head2 HTTP site (recursive directory scanning)
+
+For recursive directory scanning:
+
+ version=4
+ http://tmrc.mit.edu/mirror/twisted/Twisted/(\d\.\d)/ \
+ Twisted-([\d\.]*)\.tar\.xz debian uupdate
+
+or in one string style variant
+
+ version=4
+ http://tmrc.mit.edu/mirror/twisted/\
+ Twisted/(\d\.\d)/Twisted-([\d\.]*)\.tar\.xz debian uupdate
+
+Here, the web site should be able to handle requests to:
+
+ http://tmrc.mit.edu/mirror/twisted/Twisted/
+
+=head2 HTTP site (alternative)
+
+For one string style:
+
+ version=4
+ http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-(.+)\.tar\.gz \
+ debian uupdate
+
+This is the same as
+
+ version=4
+ http://www.cpan.org/modules/by-module/Text Text-CSV_XS-(.+)\.tar\.gz \
+ debian uupdate
+
+=head2 HTTP site (sf.net)
+
+For SourceForge based projects, qa.debian.org runs a redirector which allows a
+simpler form of URL. The format below will automatically be rewritten to use
+the redirector.
+
+ version=4
+ http://sf.net/audacity/audacity-src-(.+)\.tar\.gz uupdate
+
+=head2 HTTP site (github.com)
+
+For GitHub projects, you can use the tags or releases page. The archive URLs
+use only the version as the filename. You can rename the downloaded upstream
+tarball into standard I<project>B<->I<version>B<.tar.gz> using
+B<filenamemangle>:
+
+ version=4
+ opts="filenamemangle=\
+ s/(?:.*?)?v?(\d[\d.]*)\.tar\.gz/<project>-$1.tar.gz/" \
+ https://github.com/<user>/<project>/tags \
+ (?:.*?/)?v?(\d[\d.]*)\.tar\.gz debian uupdate
+
+=head2 HTTP site (code.google.com)
+
+Sites which used to be hosted on the Google Code service should have migrated
+to elsewhere (github?). Please look for the newer upstream site.
+
+=head2 HTTP site (funny version)
+
+For a site which has funny version numbers, the parenthesized groups will be
+joined with B<.> (period) to make a sanitized version number.
+
+ version=4
+ http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)\.tar\.gz \
+ debian uupdate
+
+=head2 HTTP site (DFSG)
+
+The upstream part of the Debian version number can be mangled to indicate the
+source package was repackaged to clean up non-DFSG files:
+
+ version=4
+ opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg1" \
+ http://some.site.org/some/path/foobar-(.+)\.tar\.gz debian uupdate
+
+See L<COPYRIGHT FILE EXAMPLES>.
+
+=head2 HTTP site (filenamemangle)
+
+The upstream tarball filename is found by taking the last component of the URL
+and removing everything after any '?'. If that leaves nothing for filename,
+B<uscan> generate filename using the source package name in
+B<debian/changelog>, the new version, and suffix B<.download> .
+
+If this does not fit to you, use B<filenamemangle>. For example, F<< <A
+href="http://foo.bar.org/dl/?path=&dl=foo-0.1.1.tar.gz"> >> could be handled
+as:
+
+ version=4
+ opts=filenamemangle=s/.*=(.*)/$1/ \
+ http://foo.bar.org/dl/\?path=&dl=foo-(.+)\.tar\.gz \
+ debian uupdate
+
+F<< <A href="http://foo.bar.org/dl/?path=&dl_version=0.1.1"> >>
+could be handled as:
+
+ version=4
+ opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
+ http://foo.bar.org/dl/\?path=&dl_version=(.+) \
+ debian uupdate
+
+=head2 HTTP site (downloadurlmangle)
+
+The option B<downloadurlmangle> can be used to mangle the URL of the file
+to download. This can only be used with B<http://> URLs. This may be
+necessary if the link given on the web page needs to be transformed in
+some way into one which will work automatically, for example:
+
+ version=4
+ opts=downloadurlmangle=s/prdownload/download/ \
+ http://developer.berlios.de/project/showfiles.php?group_id=2051 \
+ http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz \
+ debian uupdate
+
+=head2 HTTP site (origversionmangle, MUT)
+
+The option B<origversionmangle> can be used to mangle the version of the source
+tarball (B<.orig.tar.gz> and B<.orig-bar.tar.gz>). For example, B<+dfsg1> can
+be added to the upstream version as:
+
+ version=4
+ opts=origversionmangle=s/(.*)/$1+dfsg1/ \
+ http://example.com/~user/release/foo.html \
+ files/foo-([\d\.]*).tar.gz debian
+ opts="component=bar" \
+ http://example.com/~user/release/foo.html \
+ files/bar-([\d\.]*).tar.gz same uupdate
+
+See L<COPYRIGHT FILE EXAMPLES>.
+
+=head2 HTTP site (pagemangle)
+
+The option B<pagemangle> can be used to mangle the downloaded web page before
+applying other rules. The non-standard web page without proper B<< <a href="
+>> << ... >> B<< "> >> entries can be converted. For example, if F<foo.html>
+uses B<< <a bogus=" >> I<< ... >> B<< "> >>, this can be converted to the
+standard page format with:
+
+ version=4
+ opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
+ http://example.com/release/foo.html \
+ files/foo-([\d\.]*).tar.gz debian uupdate
+
+Please note the use of B<g> here to replace all occurrences.
+
+If F<foo.html> uses B<< <Key> >> I<< ... >> B<< </Key> >>, this can be
+converted to the standard page format with:
+
+ version=4
+ opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \\
+ http://localhost:$PORT/ \
+ (?:.*)/$PKG-([\d\.]+).tar.gz debian uupdate
+
+=head2 FTP site (basic):
+
+ version=4
+ ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-(.+)\.tar\.gz \
+ debian uupdate
+
+=head2 FTP site (regex special characters):
+
+ version=4
+ ftp://ftp.worldforge.org/pub/worldforge/libs/\
+ Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz debian uupdate
+
+Please note that this URL is connected to be I< ... >B<libs/Atlas-C++/>I< ... >
+. For B<++>, the first one in the directory path is verbatim while the one in
+the filename is escaped by B<\>.
+
+=head2 FTP site (funny version)
+
+This is another way of handling site with funny version numbers,
+this time using mangling. (Note that multiple groups will be
+concatenated before mangling is performed, and that mangling will
+only be performed on the basename version number, not any path
+version numbers.)
+
+ version=4
+ opts="uversionmangle=s/^/0.0./" \
+ ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
+ development/Wine-(.+)\.tar\.gz debian uupdate
+
+
+=head1 COPYRIGHT FILE EXAMPLES
+
+Here is an example for the F<debian/copyright> file which initiates automatic repackaging of the upstream tarball into I<< <spkg>_<oversion>.orig.tar.gz >>:
+
+ Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+ Files-Excluded: exclude-this
+ exclude-dir
+ */exclude-dir
+ .*
+ */js/jquery.js
+
+ ...
+
+Here is another example for the F<debian/copyright> file which initiates automatic repackaging of the multiple upstream tarballs into I<< <spkg>_<oversion>.orig.tar.gz >> and I<< <spkg>_<oversion>.orig-bar.tar.gz >>:
+
+ Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+ Files-Excluded: exclude-this
+ exclude-dir
+ */exclude-dir
+ .*
+ */js/jquery.js
+ Files-Excluded-bar: exclude-this
+ exclude-dir
+ */exclude-dir
+ .*
+ */js/jquery.js
+
+ ...
+
+See mk-origtargz(1).
+
+=head1 COMMANDLINE OPTIONS
+
+For the basic usage, B<uscan> does not require to set these options.
+
+=over
+
+=item B<--report>, B<--no-download>
+
+Only report about available newer versions but do not download
+anything.
+
+=item B<--report-status>
+
+Report on the status of all packages, even those which are up-to-date,
+but do not download anything.
+
+=item B<--download>
+
+Report and download. (This is the default behavior.)
+
+=item B<--destdir>
+
+Path of directory to which to download. If the specified path is not absolute,
+it will be relative to one of the current directory or, if directory scanning
+is enabled, the package's
+source directory.
+
+=item B<--force-download>
+
+Download upstream even if up-to-date (will not overwrite local files, however)
+
+=item B<--pasv>
+
+Force PASV mode for FTP connections.
+
+=item B<--no-pasv>
+
+Do not use PASV mode for FTP connections.
+
+=item B<--timeout> I<N>
+
+Set timeout to I<N> seconds (default 20 seconds).
+
+=item B<--no-symlink>
+
+Do not call B<mk-origtargz>.
+
+=item B<--dehs>
+
+Use an XML format for output, as required by the DEHS system.
+
+=item B<--no-dehs>
+
+Use the traditional uscan output format. (This is the default behavior.)
+
+=item B<--package> I<package>
+
+Specify the name of the package to check for rather than examining
+F<debian/changelog>; this requires the B<--upstream-version> (unless a version
+is specified in the F<watch> file) and B<--watchfile> options as well.
+Furthermore, no directory scanning will be done and nothing will be downloaded.
+This option is probably most useful in conjunction with the DEHS system (and
+B<--dehs>).
+
+=item B<--upstream-version> I<upstream-version>
+
+Specify the current upstream version rather than examine F<debian/watch> or
+F<debian/changelog> to determine it. This is ignored if a directory scan is being
+performed and more than one F<debian/watch> file is found.
+
+=item B<--watchfile> I<watchfile>
+
+Specify the I<watchfile> rather than perform a directory scan to
+determine it. If this option is used without B<--package>, then
+B<uscan> must be called from within the Debian package source tree
+(so that F<debian/changelog> can be found simply by stepping up
+through the tree).
+
+=item B<--download-version> I<version>
+
+Specify the I<version> which the upstream release must match in order to be
+considered, rather than using the release with the highest version.
+
+=item B<--download-current-version>
+
+Download the currently packaged version
+
+=item B<--verbose>
+
+Give verbose output.
+
+=item B<--no-verbose>
+
+Don't give verbose output. (This is the default behavior.)
+
+=item B<--no-exclusion>
+
+Do not automatically exclude files mentioned in F<debian/copyright> field B<Files-Excluded>
+
+=item B<--debug>
+
+Dump the downloaded web pages to stdout for debugging your F<watch> file.
+
+=item B<--check-dirname-level> I<N>
+
+See the below section L<Directory name checking> for an explanation of this option.
+
+=item B<--check-dirname-regex> I<regex>
+
+See the below section L<Directory name checking> for an explanation of this option.
+
+=item B<--user-agent>, B<--useragent>
+
+Override the default user agent header.
+
+=item B<--no-conf>, B<--noconf>
+
+Do not read any configuration files. This can only be used as the first option
+given on the command-line.
+
+=item B<--help>
+
+Give brief usage information.
+
+=item B<--version>
+
+Display version information.
+
+=back
+
+B<uscan> also accepts following options and passes them to B<mk-origtargz>:
+
+=over
+
+=item B<--symlink>
+
+Make B<orig.tar.gz> (with the appropriate extension) symlink to the downloaded
+files. (This is the default behavior.)
+
+=item B<--copy>
+
+Instead of symlinking as described above, copy the downloaded files.
+
+=item B<--rename>
+
+Instead of symlinking as described above, rename the downloaded files.
+
+=item B<--repack>
+
+After having downloaded an lzma tar, xz tar, bzip tar or zip archive, repack it
+to a gzip tar archive, if required. The unzip package must be installed in
+order to repack .zip archives, the xz-utils package must be installed to repack
+lzma or xz tar archives.
+
+=item B<--compression> [ B<gzip> | B<bzip2> | B<lzma> | B<xz> ]
+
+In the case where the upstream sources are repacked (either because B<--repack>
+option is given or F<debian/copyright> contains the field B<Files-Excluded>), it is
+possible to control the compression method via the parameter (defaults to
+B<gzip>).
+
+=item B<--copyright-file> I<copyright-file>
+
+Exclude files mentioned in B<Files-Excluded> in the given I<copyright-file>.
+This is useful when running B<uscan> not within a source package directory.
+
+=back
+
+=head1 DEVSCRIPT CONFIGURATION VARIABLES
+
+For the basic usage, B<uscan> does not require to set these configuration
+variables.
+
+The two configuration files F</etc/devscripts.conf> and F<~/.devscripts> are
+sourced by a shell in that order to set configuration variables. These
+may be overridden by command line options. Environment variable settings are
+ignored for this purpose. If the first command line option given is
+B<--noconf>, then these files will not be read. The currently recognized
+variables are:
+
+=over
+
+=item B<USCAN_DOWNLOAD>
+
+If this is set to B<no>, then newer upstream files will not be downloaded; this
+is equivalent to the B<--report> or B<--no-download> options.
+
+=item B<USCAN_PASV>
+
+If this is set to yes or no, this will force FTP connections to use PASV mode
+or not to, respectively. If this is set to default, then B<Net::FTP(3)> makes
+the choice (primarily based on the B<FTP_PASSIVE> environment variable).
+
+=item B<USCAN_TIMEOUT>
+
+If set to a number I<N>, then set the timeout to I<N> seconds. This is
+equivalent to the B<--timeout> option.
+
+=item B<USCAN_SYMLINK>
+
+If this is set to no, then a I<pkg>_I<version>B<.orig.tar.{gz|bz2|lzma|xz}>
+symlink will not be made (equivalent to the B<--no-symlink> option). If it is
+set to B<yes> or B<symlink>, then the symlinks will be made. If it is set to
+rename, then the files are renamed (equivalent to the B<--rename> option).
+
+=item B<USCAN_DEHS_OUTPUT>
+
+If this is set to B<yes>, then DEHS-style output will be used. This is
+equivalent to the B<--dehs> option.
+
+=item B<USCAN_VERBOSE>
+
+If this is set to B<yes>, then verbose output will be given. This is
+equivalent to the B<--verbose> option.
+
+=item B<USCAN_USER_AGENT>
+
+If set, the specified user agent string will be used in place of the default.
+This is equivalent to the B<--user-agent> option.
+
+=item B<USCAN_DESTDIR>
+
+If set, the downloaded files will be placed in this directory. This is
+equivalent to the B<--destdir> option.
+
+=item B<USCAN_REPACK>
+
+If this is set to yes, then after having downloaded a bzip tar, lzma tar, xz
+tar, or zip archive, uscan will repack it to a gzip tar. This is equivalent to
+the B<--repack> option.
+
+=item B<USCAN_EXCLUSION>
+
+If this is set to no, files mentioned in the field B<Files-Excluded> of
+F<debian/copyright> will be ignored and no exclusion of files will be tried.
+This is equivalent to the B<--no-exclusion> option.
+
+=back
+
+=head1 EXIT STATUS
+
+The exit status gives some indication of whether a newer version was found or
+not; one is advised to read the output to determine exactly what happened and
+whether there were any warnings to be noted.
+
+=over
+
+=item B<0>
+
+Either B<--help> or B<--version> was used, or for some F<watch> file which was
+examined, a newer upstream version was located.
+
+=item B<1>
+
+No newer upstream versions were located for any of the F<watch> files examined.
+
+=back
+
+=head1 ADVANCED FEATURES
+
+B<uscan> has many other enhanced features which are skipped in the above
+section for the simplicity. Let's check their highlights.
+
+B<uscan> actually scans not just the current directory but all its
+subdirectories looking for F<debian/watch> to process them all.
+See L<Directory name checking>.
+
+B<uscan> can be executed with I<path> as its argument to change the starting
+directory of search from the current directory to I<path> .
+
+See L<COMMANDLINE OPTIONS> and L<DEVSCRIPT CONFIGURATION VARIABLES> for other
+variations.
+
+=head2 Custom script
+
+The optional I<script> parameter F<debian/watch> means to execute I<script>
+with options after processing this line. You can customize this by specifying
+F<debian/myuupdate> as I<script> and create executable file F<debian/myuupdate>
+with the following content.
+
+ #!/bin/sh -e
+ # called with --upstream-version <version>
+ uupdate --find "$@"
+ package=`dpkg-parsechangelog | sed -n 's/^Source: //p'`
+ cd ../$package-$2
+ debuild
+
+Then B<uscan> invokes "I<debian/myuupdate> B<--upstream-version> I<version>" to
+perform a fully automatic upstream update of Debian binary packages.
+
+Note that we don't call B<dupload> or B<dput> automatically, as the maintainer
+should perform sanity checks on the software before uploading it to Debian.
+
+=head2 Directory name checking
+
+Similarly to several other scripts in the B<devscripts> package, B<uscan>
+explores the requested directory trees looking for F<debian/changelog> and
+F<debian/watch> files. As a safeguard against stray files causing potential
+problems, and in order to promote efficiency, it will examine the name of the
+parent directory once it finds the F<debian/changelog> file, and check that the
+directory name corresponds to the package name. It will only attempt to
+download newer versions of the package and then perform any requested action if
+the directory name matches the package name. Precisely how it does this is
+controlled by two configuration file variables
+B<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> and B<DEVSCRIPTS_CHECK_DIRNAME_REGEX>, and
+their corresponding command-line options B<--check-dirname-level> and
+B<--check-dirname-regex>.
+
+B<DEVSCRIPTS_CHECK_DIRNAME_LEVEL> can take the following values:
+
+=over
+
+=item B<0>
+
+Never check the directory name.
+
+=item B<1>
+
+Only check the directory name if we have had to change directory in
+our search for F<debian/changelog>, that is, the directory containing
+F<debian/changelog> is not the directory from which B<uscan> was invoked. This
+is the default behavior.
+
+=item B<2>
+
+Always check the directory name.
+
+=back
+
+The directory name is checked by testing whether the current directory name (as
+determined by pwd(1)) matches the regex given by the configuration file
+option B<DEVSCRIPTS_CHECK_DIRNAME_REGEX> or by the command line option
+B<--check-dirname-regex> I<regex>. Here regex is a Perl regex (see
+perlre(3perl)), which will be anchored at the beginning and the end. If regex
+contains a B</>, then it must match the full directory path. If not, then
+it must match the full directory name. If regex contains the string I<package>,
+this will be replaced by the source package name, as determined from the
+F<debian/changelog>. The default value for the regex is: I<package>B<(-.+)?>, thus matching
+directory names such as I<package> and I<package>-I<version>.
+
+=head1 HISTORY AND UPGRADING
+
+This section briefly describes the backwards-incompatible F<watch> file features
+which have been added in each F<watch> file version, and the first version of the
+B<devscripts> package which understood them.
+
+=over
+
+=item Pre-version 2
+
+The F<watch> file syntax was significantly different in those days. Don't use it.
+If you are upgrading from a pre-version 2 F<watch> file, you are advised to read
+this manpage and to start from scratch.
+
+=item Version 2
+
+B<devscripts> version 2.6.90: The first incarnation of the current style of
+F<watch> files.
+
+=item Version 3
+
+B<devscripts> version 2.8.12: Introduced the following: correct handling of
+regex special characters in the path part, directory/path pattern matching,
+version number in several parts, version number mangling. Later versions
+have also introduced URL mangling.
+
+If you are upgrading from version 2, the key incompatibility is if you have
+multiple groups in the pattern part; whereas only the first one would be used
+in version 2, they will all be used in version 3. To avoid this behavior,
+change the non-version-number groups to be B<(?:> I< ...> B<)> instead of a
+plain B<(> I< ... > B<)> group.
+
+B<uscan> invokes the custom I<script> as "I<script> B<--upstream-version>
+I<version> B<../>I<spkg>B<_>I<version>B<.orig.tar.gz>".
+
+B<uscan> invokes the standard B<uupdate> as "B<uupdate> B<--no-symlink
+--upstream-version> I<version> B<../>I<spkg>B<_>I<version>B<.orig.tar.gz>".
+
+=item Version 4
+
+B<uscan> invokes the custom I<script> as "I<script> B<--upstream-version>
+I<version>".
+
+B<uscan> invokes the standard B<uupdate> as "B<uupdate> B<--find>
+B<--upstream-version> I<version>".
+
+=back
+
+=head1 SEE ALSO
+
+dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
+
+=head1 AUTHOR
+
+The original version of uscan was written by Christoph Lameter
+<clameter at debian.org>. Significant improvements, changes and bugfixes were
+made by Julian Gilbey <jdg at debian.org>. HTTP support was added by Piotr
+Roszatycki <dexter at debian.org>. The program was rewritten in Perl by Julian
+Gilbey.
+
+=cut
+
use 5.010; # defined-or (//)
use strict;
use warnings;
@@ -681,54 +1945,7 @@ exit ($found ? 0 : 1);
# greatest version number (as determined by the (...) group), using the
# Debian version number comparison algorithm described below.
#
-# watch_version=3:
-#
-# Correct handling of regex special characters in the path part:
-# ftp://ftp.worldforge.org/pub/worldforge/libs/Atlas-C++/transitional/Atlas-C\+\+-(.+)\.tar\.gz
-#
-# Directory pattern matching:
-# ftp://ftp.nessus.org/pub/nessus/nessus-([\d\.]+)/src/nessus-core-([\d\.]+)\.tar\.gz
-#
-# The pattern in each part may contain several (...) groups and
-# the version number is determined by joining all groups together
-# using "." as separator. For example:
-# ftp://site/dir/path/pattern-(\d+)_(\d+)_(\d+)\.tar\.gz
-#
-# This is another way of handling site with funny version numbers,
-# this time using mangling. (Note that multiple groups will be
-# concatenated before mangling is performed, and that mangling will
-# only be performed on the basename version number, not any path version
-# numbers.)
-# opts=uversionmangle=s/^/0.0./ \
-# ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/Wine-(.+)\.tar\.gz
-#
-# Similarly, the upstream part of the Debian version number can be
-# mangled:
-# opts=dversionmangle=s/\.dfsg\.\d+$// \
-# http://some.site.org/some/path/foobar-(.+)\.tar\.gz
-#
-# The versionmangle=... option is a shorthand for saying uversionmangle=...
-# and dversionmangle=... and applies to both upstream and Debian versions.
-#
-# The option filenamemangle can be used to mangle the name under which
-# the downloaded file will be saved:
-# href="http://foo.bar.org/download/?path=&download=foo-0.1.1.tar.gz"
-# could be handled as:
-# opts=filenamemangle=s/.*=(.*)/$1/ \
-# http://foo.bar.org/download/\?path=&download=foo-(.+)\.tar\.gz
-# and
-# href="http://foo.bar.org/download/?path=&download_version=0.1.1"
-# as:
-# opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
-# http://foo.bar.org/download/\?path=&download_version=(.+)
-#
-# The option downloadurlmangle can be used to mangle the URL of the file
-# to download. This can only be used with http:// URLs. This may be
-# necessary if the link given on the webpage needs to be transformed in
-# some way into one which will work automatically, for example:
-# opts=downloadurlmangle=s/prdownload/download/ \
-# http://developer.berlios.de/project/showfiles.php?group_id=2051 \
-# http://prdownload.berlios.de/softdevice/vdr-softdevice-(.+).tgz
+# watch_version=3 and 4: See POD.
sub process_watchline ($$$$$$)
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/collab-maint/devscripts.git
More information about the devscripts-devel
mailing list