dpkg-parsechangelog(1): Add alternative changelog formats documentation

Adapted from the policy manual.

Closes: #584141

debian/changelog

@@ -5,6 +5,8 @@ dpkg (1.16.4) UNRELEASED; urgency=low
     warning, as the format has several deficiencies that have been addressed
     by upstream in xz. Although unpacking will be kept being supported to
     handle existing lzma compressed .deb files.
+  * Add alternative changelog formats documentation from the policy manual
+    to dpkg-parsechangelog(1). Closes: #584141
 
   [ Updated man page translations ]
   * German (Helge Kreutzmann).

man/dpkg-genchanges.1

@@ -2,7 +2,7 @@
 .\"
 .\" Copyright © 1995-1996 Ian Jackson <ian@chiark.chu.cam.ac.uk>
 .\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
-.\" Copyright © 2007-2011 Guillem Jover <guillem@debian.org>
+.\" Copyright © 2006-2012 Guillem Jover <guillem@debian.org>
 .\" Copyright © 2008-2010 Raphaël Hertzog <hertzog@debian.org>
 .\"
 .\" This is free software; you can redistribute it and/or modify
@@ -18,7 +18,7 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .
-.TH dpkg\-genchanges 1 "2011-08-14" "Debian Project" "dpkg utilities"
+.TH dpkg\-genchanges 1 "2012-04-30" "Debian Project" "dpkg utilities"
 .SH NAME
 dpkg\-genchanges \- generate Debian .changes files
 .
@@ -126,9 +126,8 @@ Read the list of files to be uploaded here, rather than using
 .BR debian/files .
 .TP
 .BI \-F changelogformat
-Specifies the format of the changelog. By default the format is read
-from a special line near the bottom of the changelog or failing that
-defaults to the debian standard format.
+Specifies the format of the changelog. See \fBdpkg\-parsechangelog\fP(1)
+for information about alternative formats.
 .TP
 .BI \-u uploadfilesdir
 Look for the files to be uploaded in

man/dpkg-gencontrol.1

@@ -2,6 +2,7 @@
 .\"
 .\" Copyright © 1995-1996 Ian Jackson <ian@chiark.chu.cam.ac.uk>
 .\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
+.\" Copyright © 2006, 2012 Guillem Jover <guillem@debian.org>
 .\" Copyright © 2007-2008 Raphaël Hertzog <hertzog@debian.org>
 .\"
 .\" This is free software; you can redistribute it and/or modify
@@ -17,7 +18,7 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .
-.TH dpkg\-gencontrol 1 "2011-08-14" "Debian Project" "dpkg utilities"
+.TH dpkg\-gencontrol 1 "2012-04-30" "Debian Project" "dpkg utilities"
 .SH NAME
 dpkg\-gencontrol \- generate Debian control files
 .
@@ -91,9 +92,8 @@ Read or write the list of files to be uploaded here, rather than using
 .BR debian/files .
 .TP
 .BI \-F changelogformat
-Specifies the format of the changelog. By default the format is read
-from a special line near the bottom of the changelog or failing that
-defaults to the debian standard format.
+Specifies the format of the changelog. See \fBdpkg\-parsechangelog\fP(1)
+for information about alternative formats.
 .TP
 .BI \-p package
 Generate information for the binary package

man/dpkg-parsechangelog.1

@@ -2,6 +2,7 @@
 .\"
 .\" Copyright © 1995-1996 Ian Jackson <ian@chiark.chu.cam.ac.uk>
 .\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
+.\" Copyright © 2006, 2012 Guillem Jover <guillem@debian.org>
 .\" Copyright © 2007-2008 Frank Lichtenheld <djpig@debian.org>
 .\" Copyright © 2009 Raphaël Hertzog <hertzog@debian.org>
 .\"
@@ -18,7 +19,7 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .
-.TH dpkg\-parsechangelog 1 "2011-08-14" "Debian Project" "dpkg utilities"
+.TH dpkg\-parsechangelog 1 "2012-04-30" "Debian Project" "dpkg utilities"
 .SH NAME
 dpkg\-parsechangelog \- parse Debian changelog files
 .
@@ -42,7 +43,8 @@ default is
 .BI \-F changelogformat
 Specifies the format of the changelog. By default the format is read
 from a special line near the bottom of the changelog or failing that
-defaults to the debian standard format.
+defaults to the \fIdebian\fP standard format. See also
+\fBCHANGELOG FORMATS\fP.
 .TP
 .BI \-L libdir
 Specify an additional directory to search for parser scripts.
@@ -69,7 +71,7 @@ Set the output format. Currently supported values are
 option existed) and the default. It consists of one paragraph
 in Debian control format (see \fBdeb\-control\fP(5)). If more
 than one entry is requested, then most fields are taken from the
-latest entry, except otherwise stated:
+most recent entry, except otherwise stated:
 .RS
 .TP
 .BI Source: " pkg-name"
@@ -79,7 +81,8 @@ latest entry, except otherwise stated:
 .BI Distribution: " target-distribution"
 .TP
 .BI Urgency: " urgency"
-The highest urgency of all included entries is used.
+The highest urgency of all included entries is used, followed by the
+concatenated (space-separated) comments from all the versions requested.
 .TP
 .BI Maintainer: " author"
 .TP
@@ -96,6 +99,9 @@ is intended by one space character. The exact content depends
 on the changelog format.
 .RE
 .IP
+The \fBVersion\fP, \fBDistribution\fP, \fBUrgency\fP, \fBMaintainer\fP and
+\fBChanges\fP fields are mandatory.
+.IP
 There might be additional user-defined fields present.
 .IP
 The \fBrfc822\fP format uses the same fields but outputs
@@ -126,6 +132,46 @@ change the starting point for \-\-count, counted from the top
 include all changes. Note: other options have no effect when this is in
 use.
 .
+.SH CHANGELOG FORMATS
+It is possible to use a different format to the standard one, by providing
+a parser for that alternative format.
+
+In order to have \fBdpkg\-parsechangelog\fP run the new parser, a line must
+be included within the last 40 lines of the changelog file, matching the Perl
+regular expression: \(lq\fB\\schangelog-format:\\s+([0-9a-z]+)\\W\fP\(rq.
+The part in parentheses should be the name of the format. For example:
+
+       @@@ changelog-format: \fIotherformat\fP @@@
+
+Changelog format names are non-empty strings of alphanumerics.
+
+If such a line exists then \fBdpkg\-parsechangelog\fP will look for
+the parser as \fB/usr/lib/dpkg/parsechangelog/\fP\fIotherformat\fP
+or \fB/usr/local/lib/dpkg/parsechangelog/\fP\fIotherformat\fP; it is
+an error for it not being present or not being an executable program.
+The default changelog format is \fBdebian\fP, and a parser for it is
+provided by default.
+
+The parser will be invoked with the changelog open on standard input at
+the start of the file. It should read the file (it may seek if it wishes)
+to determine the information required and return the parsed information
+to standard output in the format specified by the \fB\-\-format\fP option.
+It should accept all \fBParser Options\fP.
+
+If the changelog format which is being parsed always or almost always
+leaves a blank line between individual change notes, these blank lines
+should be stripped out, so as to make the resulting output compact.
+
+If the changelog format does not contain date or package name information
+this information should be omitted from the output. The parser should not
+attempt to synthesize it or find it from other sources.
+
+If the changelog does not have the expected format the parser should exit
+with a nonzero exit status, rather than trying to muddle through and
+possibly generating incorrect output.
+
+A changelog parser may not interact with the user at all.
+.
 .SH CAVEATS
 All \fBParser Options\fP except for \-v are only supported in
 \fBdpkg\fP, version 1.14.16 and later. Third party parsers for

man/dpkg-source.1

@@ -3,7 +3,7 @@
 .\" Copyright © 1995-1996 Ian Jackson <ian@chiark.chu.cam.ac.uk>
 .\" Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
 .\" Copyright © 2006-2007 Frank Lichtenheld <djpig@debian.org>
-.\" Copyright © 2006-2011 Guillem Jover <guillem@debian.org>
+.\" Copyright © 2006-2012 Guillem Jover <guillem@debian.org>
 .\" Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org>
 .\" Copyright © 2010 Joey Hess <joeyh@debian.org>
 .\"
@@ -20,7 +20,7 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
 .
-.TH dpkg\-source 1 "2012-04-03" "Debian Project" "dpkg utilities"
+.TH dpkg\-source 1 "2012-04-30" "Debian Project" "dpkg utilities"
 .SH NAME
 dpkg\-source \- Debian source package (.dsc) manipulation tool
 .
@@ -138,9 +138,8 @@ If given with relative pathname this is interpreted starting at
 the source tree's top level directory.
 .TP
 .BI \-F changelogformat
-Specifies the format of the changelog. By default the format is read
-from a special line near the bottom of the changelog or failing that
-defaults to the debian standard format.
+Specifies the format of the changelog. See \fBdpkg\-parsechangelog\fP(1)
+for information about alternative formats.
 .TP
 .BI \-\-format= value
 Use the given format for building the source package. It does