[rfc-i] Containment considered harmful

Martin Rex mrex at sap.com
Sat May 26 04:43:01 PDT 2012

> Iljitsch van Beijnum wrote:
>> So: there MUST NOT be a containment requirement in the I-D / RFC
>> submission format. If people find it useful to have containment
>> in RFCs, then this should be added during the publication process,
>> but not before. (This means that tools making use of this would
>> work on RFCs but not drafts.) Containment also MUST NOT be
>> optional in I-Ds, because that way, re-editing a draft will still
>> lead to brokennes.

I'm perfectly OK with people using authoring tools that support all
kinds of fancy and weird stuff, including containment.  But I'm
absolutely opposed to any requirement that the submission format
must have containment, because that would require _all_ authoring
tools to support fancy and weird stuff and all authors to create
and maintain such data -- although that data is completely irrelevant
for the readers and will be missing from the printed copies anyway.

Brian E Carpenter wrote:
> Lack of containment for sections means that processing software cannot
> be fully aware of the document structure, and that is serious restriction.

The richmess of the document contents shuffling features of an authors
favorite editor is a very personal matter of taste, and entirely
irrelevant to the reader.  Authors that shuffle around a lot regular
get GEN-ART review complaints that they use a term that is defined
only a few sections later and should rearrange their document.

When authors totally rely on their authoring software to keep track
of cross-references, they often loose track of where they define what
and the result is a hard to read I-D.  I-Ds and RFCs are information
designed for consumption by humans.  It's not a program source code,
where the compiler does _not_ care in which order the modules appear
in the source.  

Writing documents is different from writing software, although some
documents bear a certain resemblance with poor code.

> I would agree with a requirement that the authoring tools should not
> require the author to set up the containment manually. With xml2rfc,
> I've learnt the hard way always to annotate the </section>:
> <section anchor="intro" title="Introduction">
> ...
> </section> <!-- intro -->

The only thing that is necessary in the submission format is the stuff
that is actually visible to readers in the printout.  That is the part
that must (a) still have all of the information and (b) still be very
comprehensible to the reader.

If the document structure is not "apparent" to a tool like rfcmarkup,
then it doesn't really matter how beautiful, rich and consistent
the invisible meta-data is, the document will need fixing of the
information that is actually rendered.


More information about the rfc-interest mailing list