[rfc-i] Embedding stuff (code, etc.) in RFCs

Riccardo Bernardini framefritti at gmail.com
Fri Jul 12 10:36:14 PDT 2013


On Fri, Jul 12, 2013 at 6:46 PM, Paul Kyzivat <pkyzivat at alum.mit.edu> wrote:
> On 7/12/13 12:39 PM, Dearlove, Christopher (UK) wrote:
>>
>> The .txt is the definitive RFC, so extracting from that has its
>> advantages.
>
>
> It is definitive *now*. But the limitations of that are also clear.
> This is one of them.
>
>
>> Perhaps we should have a <code> or whatever in the XML, and then xml2rfc
>> to map that to something distinctive, plus a tool to pull the distinctive
>> text out of the .txt, while extracting the code from <code> ... </code> in
>> the XML would be trivial.
>
>
> I don't want the support for code extraction to impact the readability of
> the draft. Having to put special punctuation into the draft, especially on
> every line of code, does, IMO, detract from readability.

I agree that the solution is far from ideal, but you cannot go far if
we start from the hypothesis that we want to rely on the .txt format,
since it is the official format and the only one we are granted to
have.

I agree that the punctuation at the begin of each line clutters
somehow the text. The choice of having !. and !, as marker are
actually because "." and "," are small and they reduce the clutter at
a minimum.  The first version was with !+ and != and the clutter was
more evident.  Now it looks like some kind of "border" around the
code.

Compare this with the solution employed for RFC 6716: they
base64-encoded a tar archive of the sources and embedded the result in
the RFC prefixing every line with "###", see

     http://tools.ietf.org/html/rfc6716#appendix-A

It should be said that the 6716 solution has the advantage that
archive is compressed and maybe the compression compensates the
expansion done by base64 encoding.

I think that if we suppose to work on the .txt we cannot avoid marking
each line with a marker, because we need to separate headers/footers
from the embedded code.  The only help could come from xml2rfc that
could put some marker at the beginning and at the end of sections of
codes.

Let us not forget, moreover, the problem with the long lines: it is
not unusual (even in C) having lines longer that 69 (72 - 3 char of
margin) characters: how do you break them? The point where you can
break a line depends on the language and it does not look too
practical embedding in xml2rfc a parser for every commonly used
programming language in order to find where to split the lines.

There is also the problem with out-of-range characters: if I remember
correctly RFCs can contain only characters in the range 32..126, with
some control characters used for formatting only.  If you have in a
comment a name with, say, an umlaut, what are you going to do?

Summarizing, if we start from the requirement to use the currently
only official format, I do not see much space to maneuver; if you say
that the .txt is antiquated and we should introduce new official
formats, I agree, but that is a different problem.

Lastly, let me add that I am not, myself, a fan of the idea of
embedding code in the RFCs.  I understand that there are some cases
where a reference code is useful, but I do not like two facts about
embedded code: (i) it tends to "bloat" the RFC since even a fairly
simple code can take many pages and (ii) it "freezes" the code
forever; if you discover a bug (maybe a security one) the day after
the RFC is published, what are you going to do?  Publish an errata?

If you ask me for a solution, I have none...  Publishing the code
externally, in a third-part site and putting the link in the RFC
exposes us to the risk of "link volatility."  Maybe the code should be
"official published" like RFCs are, only the format would not be TXT,
but (say) compressed tar.  Newer versions would be published after
something similar to a LC and they would obsolete the old ones, like
with RFCs.  However, this is again a different problem (albeit a
correlated one).

Thanks

Riccardo



>
>         Thanks,
>         Paul
>
>
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest


More information about the rfc-interest mailing list