Hi!
On Wed, 2019-12-18 at 02:19:36 +0100, Guillem Jover wrote:
> On Sun, 2019-12-15 at 11:15:47 -0800, Josh Triplett wrote:
> > The deb-changelog manpage defines the first line of the format as:
> >
> >package (version) distributions; metadata
> >
> > This line, and the subsequent description, doesn't make the following
> > clear:
> >
> > - Is a package required to have at least one metadata field?
> > - If a package can have no metadata, does the first line require a
> > semicolon (immediately preceding the newline), or can it omit the
> > semicolon?
> >
> > (I don't want to assume that the behavior of any particular
> > changelog-parsing tool describes the requirements of the standard; I'd
> > like to know what the standard allows/requires.)
>
> Well, dpkg being the canonical implementation for parsers of most of
> these formats, limits at least what it is currently allowed anyway.
> Which does not mean Debian might be as permissive, or other current
> implementations.
>
> I've queued the following change, which I guess should clarify the
> above points:
Actually, make that the attached patch.
Thanks,
Guillem
From d34bf7f21dc195948d9a051b7ccfc5ebba5cc4da Mon Sep 17 00:00:00 2001
From: Guillem Jover
Date: Wed, 18 Dec 2019 03:05:43 +0100
Subject: [PATCH] man: Clarify deb-changelog(5) format
Specify that the semicolon is required, that zero or more key/values
are allowed, the format of the keys, and the exact Unicode characters
used for the delimiters.
Closes: #946780
---
man/deb-changelog.man | 16
1 file changed, 12 insertions(+), 4 deletions(-)
diff --git a/man/deb-changelog.man b/man/deb-changelog.man
index 6d57a8a9d..6b2ee7849 100644
--- a/man/deb-changelog.man
+++ b/man/deb-changelog.man
@@ -57,12 +57,18 @@ That format is a series of entries like this:
.PP
\fIpackage\fP and \fIversion\fP are the source package name and version
number.
+\fIversion\fP is delimited by parenthesis U+00028 ‘\fB(\fP’ and
+U+0029 ‘\fB)\fP’.
.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.
+\fIdistributions\fP must be terminated by a semicolon (U+003B ‘\fB;\fP’).
.PP
-\fImetadata\fP is a comma-separated list of \fIkeyword\fP=\fIvalue\fP items.
+\fImetadata\fP lists zero or more comma-separated \fIkeyword\fP=\fIvalue\fP
+items.
+Each keyword can contain only minus and case insensitive alphanumeric
+characters, as they need to be mapped to \fBdeb822\fP(5) field names.
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
@@ -72,7 +78,8 @@ 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
+at least two spaces (U+0020 \fBSPACE\fP), 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.
@@ -138,9 +145,9 @@ The last two digits must be in the range \fB00\fP-\fB59\fP.
The first “title” line with the package name must start at the left
hand margin.
The “trailer” line with the maintainer and date details must be
-preceded by exactly one space.
+preceded by exactly one space (U+0020 \fBSPACE\fP).
The maintainer details and the date must be separated by exactly two
-spaces.
+spaces (U+0020 \fBSPACE\fP).
.PP
Any line that consists entirely (i.e., no leading whitespace) of \fB#\fP
or \fB/* */\fP style comments or RCS keywords.
@@ -174,6 +181,7 @@ dpkg (1.17.18) unstable; urgency=low
.fi
.
.SH SEE ALSO
+.BR deb822 (5),
.BR deb\-version (7),
.BR deb\-changes (5),
.BR dpkg\-parsechangelog (1).
--
2.24.1.658.g99f4b37f93
