[rfc-i] draft-iab-streams-headers-boilerplates-06 : overlooked details?

John C Klensin john+rfc at jck.com
Fri Jan 30 10:22:35 PST 2009



--On Monday, January 26, 2009 10:52 +0100 Olaf Kolkman
<olaf at NLnetLabs.nl> wrote:

>...
> I propose to _not_ have this information in the boilerplate
> but include
> it explicitly in where the "Updates to this Reference" refers
> to (in section 3.4).
>...

Olaf,

I don't recall this ever being seriously discussed on-list, but
I want to renew my objection to creating a separate "Updates to
this Reference" component of the document boilerplate.

One of the big advantages of the approach of the "headers and
boilerplate" document, as well as that of some recent IPR
changes, has been to eliminate fragmented boilerplate
(historically, in the front, but after the abstract, and at the
end).  Putting boilerplate material in the front of the document
and additional boilerplate material in a section in the middle
of the document actually makes things worse, since the latter is
not in a predictable place.

The argument that the separate section is needed to permit
inclusion of stream-specific material doesn't hold up since
there is already stream-specific material in the front-page
boilerplate.  If the intent is to include a URI that points to
additional material, that URI could go in front too (and, again,
vary with the other stream-specific information as needed).

I also note that, while the boilerplate material in the document
(Section 3.2.3 of -06) points explicitly to an "Updates to the
RFC" section of the document, that section is described only in
Section 3.4 under a caption that says

   "Currently the following structural information is available
   or is being considered for inclusion in RFCs"

that Section is not now available.  If the front-matter
boilerplate forces its creation, it is no longer under
consideration either, so this is an inconsistency.

There are also a few operational reasons to not separate the
material:

(1) While the prototype style guide is not explicit about it,
the RFC Editor has traditionally strongly preferred that cross
references to sections include (or be exclusively) the Section
number, not just the Section name.  Unless a special exception
is made for the "Updates to this Reference" section, the
reference required by Section 3.2.3 of -06 will need to cite a
specific Section identifier ("anchor" in XML terms).   That
requires additional (in addition to the track-specific stuff),
and non-obvious, changes to the <rfc> or <front> elements of
xml2rfc.  If I recall the handling of references to sections
that Word itself does not generate, it is even more complex in
Word.

(2) It appears from the description of that "Updates to this..."
section that it will almost certainly have to consist of one or
more URLs or citations.  While the originating stream is
certainly stable (and presumably reflected in the boilerplate,
so does not need to be repeated in this section) and information
about errata submission might be (although I'd recommend against
it), information about current status and a list of errata can
obviously not be known when the RFC is published.   Although the
prototype style manual is not explicit about it, the RFC Editor
has traditionally preferred URLs being referenced (as distinct
from those that appear in examples) to appear in cited
references (normative or non-normative) rather than in running
text.  The reasons for that are obvious: it makes them much
easier to track.   

The net result is that this section is likely to look like
either:

   N. Updates to this RFC
   This document was produced and approved in the FOO stream.
   Errata for this document can be submitted following the
procedures in [Errata-submission].
   Current errata for this document, if any, can be found via
[Errata-list].
   Information about updates and current status of the document
may be found at [Update-info].

or

   N. Updates to this RFC
   This document was produced and approved in the FOO stream.
   Information about the current status of this document, any
relevant errata, and about how to submit additional errata and
suggestions may be found at [Updates-to-RFC].

Any tools will have to be smart enough to generate or include
the appropriate citation(s) and should be smart enough to
generate the references.   At minimum, a tool such as xml2rfc
would presumably need an entirely new element, e.g.,

  <updatesToDoc errataSubmit="xxx" errataList="yyy" 
     updateInfo="zzz" />

where "xxx", "yyy", and "zzz" are target values for the relevant
anchored references.  I would assume that the content generated
by that element would be standardized so that the element itself
would not need any content -- otherwise, you are just going to
have confusion.  Or, put differently, that section really is
boilerplate and the headers and boilerplates draft is
insufficient for people to start updating tools unless that
boilerplate is specified (either as part of the draft or by the
RFC Editor, which has never before felt the need for such a
section).  Again, this is even harder for the author with most
(or all) versions of Word and no fun with nroff.

By contrast, assume that, instead of the reference called for by
3.2.3, it simply said, e.g.,

	Information about the current status of this document
	and any errata to it may be obtained at <URL>.

(please note the symmetry between this and the existing forward
pointer for standards-track documents, which reads:

    'Please refer to the current edition of the "Internet
    Official Protocol Standards" (STD 1) for the
    standardization state and status...'
) 

and the entire story becomes part of the front-matter
boilerplate, perhaps with a track-dependent URL, without any of
the complexity of cross-references to sections, additional
clutter, need for rules about what authors can and cannot add to
specified material in the section, etc.

(3) This draft is almost entirely about RFCs.  As noted on the
list, it doesn't address the difference between I-Ds and RFCs
very much at all.  In fact, the term "Internet-Draft" appears in
it only in its headers and boilerplate.  There are enough issues
about the differences --including what should be done about the
Updates section and the associated references from the
boilerplate-- that approval and publication of this document
without nailing those details down would be a serious disservice
to authors and editors.  Indeed, if the intent were to _require_
boilerplate based on this document in RFCs, waiting why authors
and tool-developers got the details sorted out with the IAB and
RFC Editor might introduce document flow constipation fully as
serious as the case we have had with IPR.

regards,
   john







More information about the rfc-interest mailing list