DEP-5: general file syntax
There would seem to be at least a rough consensus that DEP-5 should
follow Policy 5.1 on control file syntax. The open question how to
specify that: it is my understanding that most people favor just
referring to the relevant Policy section and not duplicate things in
DEP-5, but since that is also my strong preference, I want to be
careful.
Here's my current suggestion:
* We refer to Policy 5.1 by section number, section title, and URL. I
don't think the policy version is necessary: if they make incompatible
changes, then all Debian control files will potentially break, and DEP-5
copyright files are no exception. Including the 5.1 section verbatim in
DEP-5, on the other hand, results in duplication, which is likely to
result in divergence between the policy and DEP-5.
* We add to DEP-5 details of how to handle values of multiline fields.
We can discuss exact wording of that later (see below), if we can get
consensus on the overall topic of file syntax.
* Once DEP-5 is accepted, we move it into the debian-policy package; it
will then be maintained via the normal policy amendment process on the
debian-policy mailing list. If section 5.1 changes (including just
number), the DEP-5 spec shall be changed at the same time.
* We specify the debian/control Format: field to include an identifier
that is not dependent on the DEP-5 URL. Currently, the spec includes a
URL to the specific version of itself; this is obviously problematic. I
suggest we change it by having two "words" in the Format: value: an
unversioned URL to the spec (currently to the DEP site, but later to the
debian-policy site), and a date.
Comments on the above? The rest of this e-mail proposes a specific way
of handling multiline values.
- - -
On to fields with multiline values. Well, every field can have
multi-line values, but the generic rules suffice for most of them. There
are three important details here: for specific fields, are newlines
significant, can word-wrapping happen, and how empty lines are handled.
For License, the text in the field (except the first line) should
probably not be word-wrapped, newlines are significant, and definitely
empty lines need to be handled in some way. The reason word-wrapping
shouldn't happen is that in many cases upstream licenses use ad hoc
plain text formatting conventions, such as bulleted lists, and any word
wrapping will mess that up. There is already rough consensus on how to
handle empty line markup (read: same as Description in debian/control).
For Disclaimer, and Comment if we add that, it might be helpful to have
empty lines, but word-wrapping is definitely needed. Newlines are not
significant.
For simplicity, I will introduce a new term, "desc-escape". This refers
to the escaping of content similar to the way Description does it in
debian/control: each line is prefixed with a space, except empty lines
are replaced with a space and period. The Policy's specification is not
usable for this, I think, because it goes much further than what DEP-5
needs.
Note that I've dropped the possibility of prefixing escaped lines with a
TAB character. It is a needless difference from Description, and would
complicate parsers.
So there are three cases:
* License: newlines are significant, no word-wrapping, desc-escape is
used.
* Disclaimer (and Comment in the future): newlines are not significant,
word-wrapping is OK, desc-escape is used.
* Everything else: newlines are not significant, word-wrapping is OK,
desc-escape is not used. Normal RFC822-style handling of line
continuations applies.
In other words, for Disclaimer, a formatter would un-escape (remove
leading space, replace lines with just period with empty ones), then
split the resulting text into paragraphs at empty lines, and format
those paragraphs in whatever manner it sees fit.
I echo Charles's suggestion that we specify the way escaping is done in
the section that describes the overall syntax, and then specify for each
field if they use desc-escape or not, whether newlines are significant
or not, whether the content can be word-wrapped or not.
Comments on this part? I haven't got specific wording changes to suggest
yet, I want to know if this approach is acceptable first, before we
spend time on wording details.
Reply to: