man: Add new dsc(5), deb-changelog(5) and deb-changes(5) man pages

TODO

@@ -16,13 +16,6 @@ TODO
  * Triage as much bugs as possible to get the bug count below 300 ;) and
    merge as much patches as possible.
 
- * Create dedicated manual pages for .changes and .dsc documenting the
-   format of the files. (deb-foo might not be apprioriate as those are
-   not inside of the .deb file, but changes(5) seems too generic.)
-   Explain that backwards incompatible change involve a major version bump
-   (1.x => 2.x) while minor version bump will be used for backwards
-   compatible extension (e.g. new fields).
-
  * Code cleanup / bug fixes:
    - Get rid of static variables inside functions.
    - Coalesce hash and checksum functions.

debian/changelog

@@ -6,6 +6,7 @@ dpkg (1.18.5) UNRELEASED; urgency=medium
     - Add references to man pages describing file formats.
     - Document missing Install-Size, Built-For-Profiles and Build-Profiles
       fields in man pages.
+    - Add new dsc(5), deb-changelog(5) and deb-changes(5) man pages.
 
  -- Guillem Jover <guillem@debian.org>  Fri, 25 Dec 2015 14:20:16 +0100
 

debian/dpkg-dev.manpages

@@ -1,3 +1,5 @@
+debian/tmp/usr/share/man/*/deb-changelog.5
+debian/tmp/usr/share/man/*/deb-changes.5
 debian/tmp/usr/share/man/*/deb-control.5
 debian/tmp/usr/share/man/*/deb-src-control.5
 debian/tmp/usr/share/man/*/deb-version.5
@@ -11,6 +13,7 @@ debian/tmp/usr/share/man/*/deb-symbols.5
 debian/tmp/usr/share/man/*/deb-triggers.5
 debian/tmp/usr/share/man/*/deb-old.5
 debian/tmp/usr/share/man/*/deb.5
+debian/tmp/usr/share/man/*/dsc.5
 debian/tmp/usr/share/man/*/dpkg-architecture.1
 debian/tmp/usr/share/man/*/dpkg-buildflags.1
 debian/tmp/usr/share/man/*/dpkg-buildpackage.1

man/Makefile.am

@@ -1,6 +1,8 @@
 ## Process this file with automake to produce Makefile.in
 
 dist_man_MANS = \
+	deb-changelog.5 \
+	deb-changes.5 \
 	deb-control.5 \
 	deb-src-control.5 \
 	deb-version.5 \
@@ -38,7 +40,9 @@ dist_man_MANS = \
 	dpkg-trigger.1 \
 	dpkg-vendor.1 \
 	dpkg.1 \
-	dpkg.cfg.5
+	dpkg.cfg.5 \
+	dsc.5 \
+	$(nil)
 
 if BUILD_DSELECT
 dist_man_MANS += \

man/deb-changelog.5

@@ -0,0 +1,169 @@
+.\" dpkg manual page - deb-changelog(5)
+.\"
+.\" Copyright © 1996-1998 Ian Jackson and Christian Schwarz
+.\" Copyright © 1998, 2001 Manoj Srivastava <srivasta@debian.org>
+.\" Copyright © 2001 Julian Gilbey <jdg@debian.org>
+.\" Copyright © 2003 Josip Rodin <joy@debian.org>
+.\" Copyright © 2008, 2010 Russ Allbery <rra@debian.org>
+.\" Copyright © 2010 Charles Plessy <plessy@debian.org>
+.\" Copyright © 2014 Bill Allombert <ballombe@debian.org>
+.\" Copyright © 2015 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH deb-changelog 5 "2015-06-01" "Debian Project" "Debian"
+.SH NAME
+deb\-changelog \- dpkg source packages' changelog file format
+.
+.SH SYNOPSIS
+changelog
+.
+.SH DESCRIPTION
+Changes in the packaged version of a project are explained in the
+changelog file \fIdebian/changelog\fP.
+This includes modifications made in the source package compared to the
+upstream one as well as other changes and updates to the package.
+.PP
+The format of the \fIdebian/changelog\fP allows the package building
+tools to discover which version of the package is being built and find
+out other release-specific information.
+.PP
+That format is a series of entries like this:
+
+.nf
+\fIpackage\fP (\fIversion\fP) \fIdistributions\fP; \fImetadata\fP
+          [optional blank line(s), stripped]
+  * \fIchange-details\fP
+    \fImore-change-details\fP
+          [blank line(s), included in output of \fBdpkg\-parsechangelog\fP(1)]
+  * \fIeven-more-change-details\fP
+          [optional blank line(s), stripped]
+ \-\- \fImaintainer-name\fP <\fIemail-address\fP>  \fIdate\fP
+.fi
+
+.PP
+\fIpackage\fP and \fIversion\fP are the source package name and version
+number.
+.PP
+\fIdistributions\fP lists one or more space-separated distributions where
+this version should be installed when it is uploaded; it is copied to the
+\fBDistribution\fP field in the \fI.changes\fP file.
+.PP
+\fImetadata\fP is a comma-separated list of \fIkeyword\fP=\fIvalue\fP items.
+The only \fIkeyword\fPs currently supported by \fBdpkg\fP are \fBurgency\fP
+and \fBbinary\-only\fP.
+\fBurgency\fP's value is used for the \fBUrgency\fP field in the
+\fI.changes\fP file for the upload.
+\fBbinary\-only\fP with a \fByes\fP value, is used to denote that this
+changelog entry is for a binary-only non-maintainer upload (an automatic
+binary rebuild with the only change being the changelog entry).
+.PP
+The change details may in fact be any series of lines starting with
+at least two spaces, but conventionally each change starts with an
+asterisk and a separating space and continuation lines are indented
+so as to bring them in line with the start of the text above.
+Blank lines may be used here to separate groups of changes, if desired.
+.PP
+If this upload resolves bugs recorded in the distribution bug tracking
+system, they may be automatically closed on the inclusion of this
+package into the distribution archive by including the string:
+.nf
+  \fBCloses: Bug#\fP\fInnnnn\fP
+.fi
+in the change details (the exact Perl regular expression is
+\fB/closes:\\s*(?:bug)?\\#?\\s?\\d+(?:,\\s*(?:bug)?\\#?\\s?\\d+)*/i\fP).
+This information is conveyed via the \fBCloses\fP field in the \fI.changes\fP
+file.
+.PP
+The maintainer name and email address used in the changelog should be the
+details of the person who prepared this release of the package.
+They are \fBnot\fP necessarily those of the uploader or usual package
+maintainer.
+The information here will be copied to the \fBChanged\-By\fP field in the
+\fI.changes\fP file, and then later might be used to send an acknowledgement
+when the upload has been installed in the distribution archive.
+.PP
+The \fIdate\fP has the following format (compatible and with the same
+semantics of RFC2822 and RFC5322, or what «date \-R» generates):
+.IP
+\fIday-of-week\fP\fB,\fP \fIdd\fP \fImonth\fP \fIyyyy\fP \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP \fB+\fP\fIzzzz\fP
+.PP
+where:
+.TP
+.I day-of-week
+Is one of:
+.BR Mon ", " Tue ", " Wed ", " Thu ", " Fri ", " Sat ", " Sun .
+.TP
+.I dd
+Is a one- or two-digit day of the month (\fB01\fP-\fB31\fP).
+.TP
+.I month
+Is one of:
+.BR Jan ", " Feb ", " Mar ", " Apr ", " May ", " Jun ", " Jul ", " Aug ", "
+.BR Sep ", " Oct ", " Nov ", " Dec .
+.TP
+.I yyyy
+Is the four-digit year (e.g. 2010).
+.TP
+.I hh
+Is the two-digit hour (\fB00\fP-\fB23\fP).
+.TP
+.I mm
+Is the two-digit minutes (\fB00\fP-\fB59\fP).
+.TP
+.I ss
+Is the two-digit seconds (\fB00\fP-\fB60\fP).
+.TP
+.RI [\fB+-\fP] zzzz
+Is the the time zone offset from Coordinated Universal Time (UTC).
+\(oq\fB+\fP\(cq indicates that the time is ahead of (i.e., east of) UTC and
+\(oq\fB\-\fP\(cq indicates that the time is behind (i.e., west of) UTC.
+The first two digits indicate the hour difference from UTC and the last
+two digits indicate the number of additional minutes difference from UTC.
+The last two digits must be in the range \fB00\fP-\fB59\fP.
+.PP
+The first \(lqtitle\(rq line with the package name must start at the left
+hand margin.
+The \(lqtrailer\(rq line with the maintainer and date details must be
+preceded by exactly one space.
+The maintainer details and the date must be separated by exactly two
+spaces.
+.PP
+The entire changelog must be encoded in UTF-8.
+.SH FILES
+.TP
+.I debian/changelog
+.SH EXAMPLES
+.nf
+dpkg (1.17.18) unstable; urgency=low
+
+  [ Guillem Jover ]
+  * Handle empty minimum versions when initializing dependency versions,
+    as the code is mapping the minimum version 0 to '' to avoid outputting
+    useless versions. Regression introduced in dpkg 1.17.17. Closes: #764929
+
+  [ Updated programs translations ]
+  * Catalan (Guillem Jover).
+
+  [ Updated dselect translations ]
+  * Catalan (Guillem Jover).
+  * German (Sven Joachim).
+
+ \-\- Guillem Jover <guillem@debian.org>  Sun, 12 Oct 2014 15:47:44 +0200
+.fi
+.
+.SH SEE ALSO
+.BR deb\-version (5),
+.BR deb\-changes (5),
+.BR dpkg\-parsechangelog (1).

man/deb-changes.5

@@ -0,0 +1,188 @@
+.\" dpkg manual page - deb-changes(5)
+.\"
+.\" Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+.\" Copyright © 2010 Russ Allbery <rra@debian.org>
+.\" Copyright © 2015 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH deb-changes 5 "2015-06-01" "Debian Project" "Debian"
+.SH NAME
+deb\-changes \- Debian changes file format
+.
+.SH SYNOPSIS
+.IB filename .changes
+.
+.SH DESCRIPTION
+Each Debian source package is composed of a .dsc control file, which
+contains a number of fields.
+Each field begins with a tag, such as
+.B Source
+or
+.B Binary
+(case insensitive), followed by a colon, and the body of the field.
+Fields are delimited only by field tags.
+In other words, field text may be multiple lines in length, but the
+installation tools will generally join lines when processing the body
+of the field (except in case of the multiline fields
+.BR Description ", " Changes ", " Files ", " Checksums-Sha1
+and
+.BR Checksums-Sha256 ,
+see below).
+.PP
+The control data might be enclosed in an OpenPGP ASCII Armored signature,
+as specified in RFC4880.
+.
+.SH FIELDS
+.TP
+.BR Format: " \fIformat-version\fP (required)"
+The value of this field declares the format version of the file.
+The syntax of the field value is a version number with a major and minor
+component.
+Backward incompatible changes to the format will bump the major version,
+and backward compatible changes (such as field additions) will bump the
+minor version.
+The current format version is \fB1.8\fP.
+.TP
+.BR Date: " \fIrelease-date\fP (required)"
+The date the package was built or last edited.
+It must be in the same format as the date in a \fBdeb\-changelog\fP(5)
+entry.
+
+The value of this field is usually extracted from the \fIdebian/changelog\fP
+file.
+.TP
+.BR Source: " \fIsource-name\fP [\fB(\fP\fIsource-version\fP\fB)\fP] (required)"
+The name of the source package.
+If the source version differs from the binary version, then the
+\fIsource-name\fP will be followed by a \fIsource-version\fP in parenthesis.
+This can happen when the upload is a binary-only non-maintainer upload.
+.TP
+.BR Binary: " \fIbinary-package-list\fP (required)"
+This folded field is a space-separated list of binary packages to upload.
+.TP
+.BR Architecture: " \fIarch-list\fP"
+Lists the architectures of the files currently being uploaded.
+Common architectures are \fBamd64\fP, \fBarmel\fP, \fBi386\fP, etc.
+Note that the \fBall\fP value is meant for packages that are architecture
+independent.
+If the source for the package is also being uploaded, the special entry
+\fBsource\fP is also present.
+Architecture wildcards must never be present in the list.
+.TP
+.BR Version: " \fIversion-string\fP (required)"
+Typically, this is the original package's version number in whatever form
+the program's author uses.
+It may also include a Debian revision number (for non-native packages).
+The exact format and sorting algorithm are described in
+.BR deb\-version (5).
+.TP
+.BR Distribution: " \fIdistribution\fPs (required)"
+Lists one or more space-separated distributions where this version should
+be installed when it is uploaded to the archive.
+.TP
+.BR Urgency: " \fIurgency\fP"
+The urgency of the upload.
+The currently known values, in increasing order of urgency, are:
+.BR low ", " medium ", " high ", " critical " and " emergency .
+.TP
+.BR Maintainer: " \fIfullname-email\fP (required)"
+Should be in the format \(lqJoe Bloggs <jbloggs@example.org>\(rq, and is
+typically the person who created the package, as opposed to the author of
+the software that was packaged.
+.TP
+.BI Changed\-By: " fullname-email"
+Should be in the format \(lqJoe Bloggs <jbloggs@example.org>\(rq, and is
+typically the person who prepared the package changes for this release.
+.TP
+.BR Description: " (required)"
+.TQ
+.RB " \fIbinary-package-name\fP " \fB\-\fP " \fIbinary-package-summary\fP"
+This multiline field contains a list of binary package names followed by
+a space, a dash (\(oq\fB\-\fP\(cq) and their possibly truncated short
+descriptions.
+.TP
+.BI Closes: " bug-number-list"
+A space-separated list of bug report numbers that have been resolved with
+this upload.
+The distribution archive software might use this field to automatically
+close the referred bug numbers in the distribution bug tracking system.
+.TP
+.B Binary\-Only: yes
+This field denotes that the upload is a binary-only non-maintainer build.
+It originates from the \fBbinary\-only=yes\fP key/value from the changelog
+matadata entry.
+.TP
+.BR Changes: " (required)"
+.TQ
+.I " changelog-entries"
+This multiline field contains the concatenated text of all changelog
+entries that are part of the upload.
+To make this a valid multiline field empty lines are replaced with a
+single full stop (\(oq.\(cq) and all lines are indented by one space
+character.
+The exact content depends on the changelog format.
+.TP
+.BR Files: " (required)"
+.TQ
+.RI " " md5sum " " size " " section " " priority " " filename
+This multiline field contains a list of files with a md5sum, size, section
+and priority for each one.
+
+The first line of the field value (the part on the same line as the field
+name followed by a colon) is always empty.
+The content of the field is expressed as continuation lines, one line per file.
+Each line consists of space-separated entries describing the file:
+the md5sum, the file size, the file section, the file priority, and
+the file name.
+
+This field lists all files that make up the upload.
+The list of files in this field must match the list of files in the
+other related \fBChecksums\fP fields.
+.TP
+.BR Checksums\-Sha1: " (required)"
+.TQ
+.BR Checksums\-Sha256: " (required)"
+.TQ
+.RI " " checksum " " size " " filename
+These multiline fields contain a list of files with a checksum and size
+for each one.
+These fields have the same syntax and differ only in the checksum algorithm
+used: SHA-1 for \fBChecksums\-Sha1\fP and SHA-256 for \fBChecksums\-Sha256\fP.
+
+The first line of the field value (the part on the same line as the field
+name followed by a colon) is always empty.
+The content of the field is expressed as continuation lines, one line per file.
+Each line consists of space-separated entries describing the file:
+the checksum, the file size, and the file name.
+
+These fields list all files that make up the upload.
+The list of files in these fields must match the list of files in the
+\fBFiles\fP field and the other related \fBChecksums\fP fields.
+.
+.\" .SH EXAMPLE
+.\" .RS
+.\" .nf
+.\"
+.\" .fi
+.\" .RE
+.
+.SH BUGS
+The \fBFiles\fP field is inconsistent with the other \fBChecksums\fP fields.
+The \fBChange\-By\fP and \fBMaintainer\fP fields have confusing names.
+The \fBDistribution\fP field contains information about what is commonly
+referred to as a suite.
+.SH SEE ALSO
+.BR deb\-src\-control (5),
+.BR deb\-version (5).

man/dpkg-genchanges.1

@@ -179,4 +179,6 @@ file.
 .ad l
 .nh
 .BR deb\-substvars (5),
-.BR deb\-src\-control (5).
+.BR deb\-src\-control (5),
+.BR deb\-changelog (5),
+.BR deb\-changes (5).

man/dpkg-gencontrol.1

@@ -163,4 +163,5 @@ generates here.
 .nh
 .BR deb\-substvars (5),
 .BR deb\-src\-control (5),
+.BR deb\-changelog (5),
 .BR deb\-control (5).

man/dpkg-parsechangelog.1

@@ -203,3 +203,6 @@ The changelog file, used to obtain version-dependent information about
 the source package, such as the urgency and distribution of an upload,
 the changes made since a particular release, and the source version
 number itself.
+.
+.SH SEE ALSO
+.BR deb\-changelog (5).

man/dpkg-source.1

@@ -813,6 +813,8 @@ standard output field settings is rather confused.
 .ad l
 .nh
 .BR deb\-src\-control (5),
+.BR deb\-changelog (5),
+.BR dsc (5),
 .BR dpkg\-deb (1),
 .BR dpkg (1),
 .BR dselect (1).

man/dsc.5

@@ -0,0 +1,228 @@
+.\" dpkg manual page - dsc(5)
+.\"
+.\" Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
+.\" Copyright © 2015 Guillem Jover <guillem@debian.org>
+.\"
+.\" This is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" This is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
+.
+.TH dsc 5 "2015-06-01" "Debian Project" "Debian"
+.SH NAME
+dsc \- Debian source packages' control file format
+.
+.SH SYNOPSIS
+.IB filename .dsc
+.
+.SH DESCRIPTION
+Each Debian source package is composed of a .dsc control file, which
+contains a number of fields.
+Each field begins with a tag, such as
+.B Source
+or
+.B Binary
+(case insensitive), followed by a colon, and the body of the field.
+Fields are delimited only by field tags.
+In other words, field text may be multiple lines in length, but the
+installation tools will generally join lines when processing the body
+of the field (except in case of the multiline fields
+.BR Package-List ", " Files ", " Checksums-Sha1 " and " Checksums-Sha256 ,
+see below).
+.PP
+The control data might be enclosed in an OpenPGP ASCII Armored signature,
+as specified in RFC4880.
+.
+.SH FIELDS
+.TP
+.BR Format: " \fIformat-version\fP (required)"
+The value of this field declares the format version of the source package.
+The field value is used by programs acting on a source package to
+interpret the list of files in the source package and determine how
+to unpack it.
+The syntax of the field value is a numeric major revision, a period,
+a numeric minor revision, and then an optional subtype after whitespace,
+which if specified is an alphanumeric word in parentheses.
+The subtype is optional in the syntax but may be mandatory for particular
+source format revisions.
+
+The source formats currently supported by \fBdpkg\fP are \fB1.0\fP,
+\fB2.0\fP, \fB3.0 (native)\fP, \fB3.0 (quilt)\fP, \fB3.0 (git)\fP,
+\fB3.0 (bzr)\fP and \fB3.0 (custom)\fP.
+.TP
+.BR Source: " \fIsource-name\fP (required)"
+The value of this field determines the package name, and is used to
+generate file names by most installation tools.
+.TP
+.BI Binary: " binary-package-list"
+This folded field lists binary packages which this source package can produce,
+separated by commas.
+
+This field has now been superseded by the \fBPackage\-List\fP field, which
+gives enough information about what binary packages are produced on which
+architecture, build-profile and other involved restrictions.
+.TP
+.BR Architecture: " \fIarch-list\fP"
+A list of architectures and architecture wildcards separated by spaces
+which specify the type of hardware this package can be compiled for.
+Common architecture names and architecture wildcards are \fBamd64\fP,
+\fBarmel\fP, \fBi386\fP, \fBlinux\-any\fP, \fBany\-amd64\fP, etc.
+
+Note that the \fBall\fP value is meant for packages that are architecture
+independent, and \fBany\fP for packages that are architecture dependent.
+The list may include (or consist solely of) the special value \fBall\fP.
+When the list contains the architecture wildcard \fBany\fP, the only
+other value allowed in the list is \fBall\fP.
+
+The field value is generally generated from \fBArchitecture\fP fields
+from in the \fIdebian/control\fP in the source package.
+.TP
+.BR Version: " \fIversion-string\fP (required)"
+Typically, this is the original package's version number in whatever form
+the program's author uses.
+It may also include a Debian revision number (for non-native packages).
+The exact format and sorting algorithm are described in
+.BR deb\-version (5).
+.TP
+.BI Origin: " name"
+The name of the distribution this package is originating from.
+.TP
+.BR Maintainer: " \fIfullname-email\fP (required)"
+Should be in the format \(lqJoe Bloggs <jbloggs@foo.com>\(rq, and is
+typically the person who created the package, as opposed to the author
+of the software that was packaged.
+.TP
+.BI Uploaders: " fullname-email-list"
+Lists all the names and email addresses of co-maintainers of the package,
+in the same format as the \fBMaintainer\fP field.
+Multiple co-maintainers should be separated by a comma.
+.TP
+.BI Homepage: " url"
+The upstream project home page \fIurl\fP.
+.TP
+.BI Standards\-Version:
+This documents the most recent version of the distribution policy standards
+this package complies with.
+.TP
+.BI Vcs\-Browser: " url"
+The \fIurl\fP of a web interface to browse the Version Control System
+repository.
+.TP
+.BI Vcs\-Arch: " url"
+.TQ
+.BI Vcs\-Bzr: " url"
+.TQ
+.BI Vcs\-Cvs: " url"
+.TQ
+.BI Vcs\-Darcs: " url"
+.TQ
+.BI Vcs\-Git: " url"
+.TQ
+.BI Vcs\-Hg: " url"
+.TQ
+.BI Vcs\-Mtn: " url"
+.TQ
+.BI Vcs\-Svn: " url"
+These fields declare the \fIurl\fP of the Version Control System repository
+used to maintain this package.
+See \fBdeb\-src\-control\fP(5) for more details.
+.TP
+.BI Testsuite: " name-list"
+This field declares that the soure package contains the specified test suites.
+The value is a space-separated list of test suites.
+If the \fBautopkgtest\fP value is present, a \fIdebian/tests/control\fP is
+expected to be present, if the file is present but not the value, then
+\fBdpkg\-source\fP will automatically add it, preserving previous values.
+.TP
+.BI Build\-Depends: " package-list"
+.TQ
+.BI Build\-Depends\-Arch: " package-list"
+.TQ
+.BI Build\-Depends\-Indep: " package-list"
+.TQ
+.BI Build\-Conflicts: " package-list"
+.TQ
+.BI Build\-Conflicts\-Arch: " package-list"
+.TQ
+.BI Build\-Conflicts\-Indep: " package-list"
+These fields declare relationships between the source package and packages
+used to build it.
+They are discussed in the \fBdeb\-src\-control\fP(5) manpage.
+.TP
+.BI Package\-List:
+.TQ
+.RI " " package " " package-type " " section " " priority " " key-value-list
+This multiline field contains a list of binary packages generated by this
+source package.
+
+The \fIpackage\fP is the binary package name.
+
+The \fIpackage-type\fP is the binary package type, usually \fBdeb\fP, another
+common value is \fBudeb\fP.
+
+The \fIsection\fP and \fIpriority\fP match the binary package fields of the
+same name.
+
+The \fIkey-value-list\fP is a space separated \fIkey\fP\fB=\fP\fIvalue\fP list,
+and the currently known optional keys are:
+
+.RS
+.TP
+.B arch
+The architecture restriction from the binary package \fBArchiteture\fP
+field, with spaces converted to \(oq,\(cq.
+.TP
+.B profile
+The normalized build-profile restriction formula from the binary package
+\fBBuild\-Profile\fP field, with ORs converted to \(oq+\(cq and ANDs to
+\(oq,\(cq.
+.TP
+.B essential
+If the binary package is essential, this key will contain the value of the
+\fBEssential\fP field, that is a \fByes\fP value.
+.RE
+.TP
+.BR Files: " (required)"
+.TQ
+.BR Checksums\-Sha1: " (required)"
+.TQ
+.BR Checksums\-Sha256: " (required)"
+.TQ
+.RI " " checksum " " size " " filename
+These multiline fields contain a list of files with a checksum and size
+for each one.
+These fields have the same syntax and differ only in the checksum algorithm
+used: MD5 for \fBFiles\fP, SHA-1 for \fBChecksums\-Sha1\fP and SHA-256 for
+\fBChecksums\-Sha256\fP.
+
+The first line of the field value (the part on the same line as the field
+name followed by a colon) is always empty.
+The content of the field is expressed as continuation lines, one line per file.
+Each line consists of the checksum, a space, the file size, a space, and the
+file name.
+
+These fields list all files that make up the source package.
+The list of files in these fields must match the list of files in the
+other related fields.
+.
+.\" .SH EXAMPLE
+.\" .RS
+.\" .nf
+.\" .fi
+.\" .RE
+.
+.SH BUGS
+The \fBFormat\fP field conflates the format for the \fB.dsc\fP file itself
+and the format of the extracted source package.
+.SH SEE ALSO
+.BR deb\-src\-control (5),
+.BR deb\-version (5),
+.BR dpkg\-source (1).

man/po/po4a.cfg

@@ -18,6 +18,12 @@
 [type:man] deb.5 $lang:$lang/deb.5 \
            add_$lang:po/$lang.add
 
+[type:man] deb-changelog.5 $lang:$lang/deb-changelog.5 \
+           add_$lang:po/$lang.add
+
+[type:man] deb-changes.5 $lang:$lang/deb-changes.5 \
+           add_$lang:po/$lang.add
+
 [type:man] deb-control.5 $lang:$lang/deb-control.5 \
            add_$lang:po/$lang.add
 
@@ -54,6 +60,9 @@
 [type:man] deb-triggers.5 $lang:$lang/deb-triggers.5 \
            add_$lang:po/$lang.add
 
+[type:man] dsc.5 $lang:$lang/dsc.5 \
+           add_$lang:po/$lang.add
+
 [type:man] dpkg.1 $lang:$lang/dpkg.1 \
            add_$lang:po/$lang.add