Subject: Re: XML2RFC submission (was Re: ASCII art)

From: Jeffrey Hutzelman <[email-masked]>
Date: Fri, 02 Dec 2005 22:48:48 -0500

On Monday, November 28, 2005 12:00:44 PM -0800 Bob Braden <[email-masked]> 
wrote:

> The RFC Editor has experimented with using xml2rfc for this purpose,
> and found it awkward and inefficent for producing properly formatted
> ASCII text.  But the two issues of primary concern to the IETF should
> be the acceptable input formats (currently ASCII text and/or RFC 2629
> XML) and the desired publication format(s).

And, perhaps, the interchange formats used between authors and the RFC 
Editor during AUTH48.

But I think you've made an important point here, and it surprises me 
somewhat that it needs to be said aloud among people who spend so much time 
designing network protocols.

The formats of documents...
- submitted the I-D repository
- discussed in working groups
- in last call
- submitted for publication
- exchanged during AUTH48
- published as RFC's

... are all _interchange_ formats.  They are network protocol elements, of 
a sort, and it is approriate to require for them a particular, well-defined 
format.  It's appropriate to require them to use a particular natural 
language, a particular file format, and particular conventions for document 
structure, layout, etc.

We could use different sets of requirements for each stage of the process, 
or the same set for all.  Currently, we're not at either extreme.  We have 
a fairly loose set of requirements for things submitted to the I-D 
repository, and somewhat more stringent requirements by the time a document 
is sent to the RFC Editor.  And, the _output_ of the RFC Editor process is 
yet another format which is slightly different and a lot more stringent.

The formats of documents being edited by authors and editors, or by the RFC 
Editor, are _not_ interchange formats.  They are what in protocol design we 
call "implementation details", and they are best left up to the individuals 
involved, not dictated centrally.

We don't tell implementors what language or compiler to use.
We don't tell people what MUA they must use to participate in IETF lists.
We shouldn't tell authors and editors what tools they must use, either.

So, we need to ask ourselves some questions:

- What interchange format do we want to use at each stage of the process?
- Are there stages at which we want more than one interchange format,
  and, if so, which one is authoritative?

Personally, I think the following are reasonable requirements:

- For documents at every stage up to and including RFC-Editor input:
  - Documents MUST be plain english text, encoded in US-ASCII.
  - Aside from the required header at the top of the document, no
    particular formatting is required.
  - Headers, footers, and page breaks are not required (if people really
    want them, so be it; I find them of marginal use and a source of much
    pain in computing diffs, even with good tools).
  - We can argue about line length limits; I happen to find them
    convenient, but they probably don't matter much any more.
  - Documents MAY include references to diagrams, etc., using one of
    the popular image formats of the day (JPEG? PNG?).  However, it MUST
    be possible to correctly understand the document and to comply with
    its requirements without referring to the image (this can perhaps
    be waived early in the process, but I'd certainly want to see it
    met by last call).
  - Documents SHOULD include copies of whatever source form the editor
    is using, to facilitate transfer to a new editor if necessary.  The
    preferred form is WHATEVER THE AUTHOR IS ACTUALLY USING; the idea is
    to avoid information loss by using something as close as possible to
    the source.
  - The document, images, and source are published as a group.  IMHO it
    should be possible to retrieve the whole set or just the text.

- For documents published by the RFC Editor:
  - Plain English text, UTF-8, formatted in some reasonable fashion
  - Associated images published alongside the text
  - Presentation form (PDF?) published alongside the text, with images
  - Structured source in a standard format, suitable for use as a starting
    point in creating new versions.
  - Author's original source should be archived and available on request.
  - Embedded code, MIB's, ASN.1 modules (anything that today would have
    to compile to get past the IESG) available as separate files.

Both during last call and when an RFC is published, the authoritative 
version should be the plain text version, for several reasons:

- It is the most future-proof
- Many people will review that version (not the source) anyway
- Different people reviewing the document might see something different
  due to differences in their tools or environment.  This inconsistency
  is problematic when we are trying to get a large number of people to
  agree on the _same_ text.
- It is imperative that the published authoritative version have the same
  content as the version that was reviewed.  This seems most easily
  achieved by using formats which are similar enough that it is possible
  to verify the content is the same(*).

I believe that diagrams should be handled similarly.  While they should 
always be considered non-normative, diagrams will often be consulted by the 
users of our specifications, and thus should be subject to the same review 
as the text itself.

Both the reviewed and published "authoritative" versions of diagrams should 
be images, not the structured data used to create them (though that should 
be made available as well, where feasible).  This allows someone to look at 
the published diagram and insure it is the same as what was reviewed.

-- Jeff

(*) Note that this verification _does_ happen prior to publication, during
    AUTH48.  So, the authors need to see what the final published version
    will look like.  They don't so much need to see the RFC Editor's
    internal representation, because the authors don't edit that directly.

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Frank Ellermann <[email-masked]>
Date: Sat, 03 Dec 2005 17:24:35 +0100

Jeffrey Hutzelman wrote:

> Headers, footers, and page breaks are not required (if people
> really want them, so be it; I find them of marginal use and a
> source of much pain in computing diffs, even with good tools)

The new "unpaginated" output option of xml2rfc helps.  OTOH
a script like rfcmarkup can't handle everything automatically,
if I want an URL for say "application as defined in FYI 18" the
nearest I can get is <http://tools.ietf.org/html/1983#page-5>

The page numbers are no complete waste of time in this case.

> Documents SHOULD include copies of whatever source form the
> editor is using, to facilitate transfer to a new editor if
> necessary.

Maybe s/include/link to/ or s/include/also offer/ or similar,
in addition to any rfc4321.txt there could be the rfc4321.src
(any src used by the authors) in the "official" archives (IETF
and / or rfc-editor).

> The preferred form is WHATEVER THE AUTHOR IS ACTUALLY USING;
> the idea is to avoid information loss by using something as
> close as possible to the source.

With the usual caveats for src-formats like DOC.

> The document, images, and source are published as a group.

Details TBD by the publishers (rfc-editor and / or IETF),
they should be free to decide how they "implement" this.

For "IETF" read Bill or Henrik or whoever is responsible
for the relevant IETF tools, and IETF ftp + http servers.

> documents published by the RFC Editor:
> Plain English text, UTF-8, formatted in some reasonable
> fashion

That's apparently what Paul proposes in his new -01 draft:
http://tools.ietf.org/html/draft-hoffman-utf8-rfcs

If you want UTF-8 anyway, why only at this late stage ?
The discussed, last-called, and appproved ASCII version
will then be different from the published UTF-8 version:

It's not difficult to get something wrong at this point.
An UTF-8 version of RFC 3987 could be very different
from http://tools.ietf.org/html/3987 (just an example).

                       Bye, Frank

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Sat, 03 Dec 2005 23:51:14 -0500

> If you want UTF-8 anyway, why only at this late stage ?

Actually, that was an error on my part.  I meant to propose using UTF-8 
from the start, not just at publication time.