[ncc-services-wg] Pre-PDP discussion: "All RIPE documents should be plain text"
Tore Anderson tore at fud.no
Fri Mar 15 22:01:23 CET 2013
* Richard Hartmann > this is the first in a series of emails which I hope will advance into > PDPs and then updated policies. Some of them are closely related, but > I submit them individually so that if there are any hold-ups with a > specific one, the other ones can still progress. > > My first suggestion is: > > The canonical and binding format of all documents is plain text in > UTF-8 encoding. > If a document can not reasonably be stored as plain text, > PDF/A-1a will be used. > If any document exists in both plain text and PDF/A-1a, plain text is binding. > Any other form is considered non-binding as soon as a plain text or > PDF/A-1a variant exist. > All legacy documents which are still valid or relevant to current > policies will be transformed within a year of this proposal becoming > policy. > > The reasoning behind this should be obvious: Ensure that all documents > will be in the most simple-to-parse format now and forever. Having recently authored a rather intrusive policy proposal that touches a lot of text, I can only strongly agree with this. The pre-publication procedure appears to be to send complete versions of the proposed new policy document back and forth by e-mail (sometimes in different document formats), with no easy way to pinpoint exactly what has changed between the various versions. This makes the entire process needlessly time-consuming, and increases the risk that some typo or mistake accidentally sneaks into the proposal and makes it all through the PDP. So there should definitively be an authoritative, easy to collaborate on source format for all RIPE documents. Plain text is one obvious alternative, but would preclude text formatting and inclusion of figures, so a document such as ripe-500 can not be converted into plain text without loss of information. I do not like the idea of using PDF for documents like ripe-500 though. PDFs are hard to collaborate on; standard tools like diff cannot meaningfully represent the differences between two versions of a document. I would prefer something like HTML, where you could download an archive file containing the main policy text as a HTML file and any figure or image files referred to by it. I'd also suggest that a conventional 80-character line length limit would be used in the source format, as limiting the line length makes reading diffs easier. That doesn't mean the published document's web page cannot be reformatted to have longer lines of course (something that would happen automatically with HTML). -- Tore Anderson