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. -- To UNSUBSCRIBE, email to debian-project-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/1282080573.12989.179.ca...@havelock