Re: DEP-5: general file syntax
Lars Wirzenius <liw@liw.fi> writes:
> * 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.
I agree with all of this.
> * 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.
In the XML standards world, and everything touched by it, all standards
documents are strongly encouraged to have a URI that embeds the version of
the standard. I don't like the idea of separating the version from the
URL for a few reasons: it adds additional steps to the process of getting
exactly the corresponding version of the specification, two pieces of data
tend to get disconnected or not stored together, and it doesn't match how
standards are usually handled these days.
I think a better approach would be to, once the document has settled down,
publish it with a version number and give that version of the document a
permanent URL. So, for instance, we would publish DEP-5 1.0 and give it a
URL something like http://dep.debian.net/DEP-5/1.0 at which it would
always be found. If we publish a new version of the document, the new
version would be put at http://dep.debian.net/DEP-5/1.1, but the old
version wouldn't be changed.
See, for example, how the desktop entry specification is handled at:
http://standards.freedesktop.org/desktop-entry-spec/
I definitely agree with not using the VCS revision number of the document
as its version, since that number can increase frequently for changes that
aren't normative and that no consumer of the standard needs to care about.
> On to fields with multiline values. Well, every field can have
> multi-line values, but the generic rules suffice for most of them.
Note that you should say that explicitly, since in the control file format
not every field is multi-line (the default is that a field may not be
multi-line).
> 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).
I think there's something to be said for letting the License body text
wrap by default and requiring an extra space if it's intended to not wrap.
It means something else for people to be aware of and be sure to add two
spaces for many licenses, but it means that the various free-form text
that is used by many licenses can still be nicely wrapped in various
presentations. For example, the typical MIT/X Consortium license doesn't
need to have significant newlines.
That also lets the rule with License be consistent with the rule for other
fields, by requiring two leading spaces for any literal text. It also
means that we would be using essentially the same formatting conventions
as Description (Policy 5.6.13).
> 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.
I think we could merge all three of these into the same case by using the
Description syntax, with the note that blank lines don't really make sense
in some fields. (So, I guess, merge them into two cases.)
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: