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

Riccardo Bernardini framefritti at gmail.com
Sat Jul 13 23:22:13 PDT 2013


On Sat, Jul 13, 2013 at 6:34 PM, Nico Williams <nico at cryptonector.com> wrote:
> On Sat, Jul 13, 2013 at 3:53 AM, Riccardo Bernardini
> <framefritti at gmail.com> wrote:
>>>> RFC5662 should be the canonical RFC *today* for code extraction.
>>>
>>> +1
>>
>> Let me emphasize that there are not many differences between the
>> RFC5662 approach and mine: in both cases we mark each line to be
>> extracted with a special punctuation: /// in RFC5662, "!." and "!," in
>> mine.  It is true that the RFC5662 is simpler and it requires only a
>> shell line for extraction; however, the RFC5662 approach
>>
>>   * cannot handle more than one file
>>   * cannot handle lines longer than 60-something characters
>> (considering the margin and the marker)
>>   * cannot handle non-7-bit octects
>
> I think this is just too much for our little text format.
>

Actually, believe it or not, I think we are aligned here.  As I said
in a previous e-mail of mine, I am not a fan of embedding long amounts
of code in text-based RFC, but I saw that someone raised the issue and
tried to provide a simple and general solution to the problem.

> This might be a great argument to make XML the canonical format (where
> XML is used as the input format anyways), since there's no need to
> make the text-format RFC ugly.
>
> (Just to be clear: I hate writing I-Ds in xml2rfc, but I think XML is
> the correct answer for this problem.)
>

Yes, XML or some other "high level" description (but since we already
have the XML version, I do not see reasons for inventing another
format).

Should I start working today on this, I would see the XML version more
like an internal, reference format.  I-D authors could, of course,
write XML directly with an editor, but they could also work with other
tools that produce a format that it is converted to XML (e.g., LaTeX,
HTML [as recently saw on this ML], a LibreOffice plugin, ...).  Those
authoring tools do not need to be produced and maintained by IETF, but
they can be third-part tools.

Also, the XML format would not  be used directly by the RFC users
(only the most masochistic ones... :-), but it would automatically
converted to TXT (for the nostalgic), PDF, HTML, ODT, ...

I would say that it is almost everything in place, maybe it could be
worth making the last step.


> Alternatively we should do the tarball URI thing.

I do not think that the two things are really mutually exclusive.  If
you have very long source code (maybe several hundreds of KB),
embedding it in XML would be troublesome.  Having an external
repository under the IETF control would be the best solution.

>
>> Those limitations were not a problem in RFC5662 because of the
>> specific nature of the files to be extracted.  If we want a system
>
> Because it was one RFC for one file.
>
> If you had ten files for one RFC and so it turned into 11 RFCs, that
> would kinda suck.  It'd be manageable, but it'd suck.

I agree also on this.  I think that the issue here is where we put the
threshold in the trade-off  "usefulness of having embedded code" vs.
"RFC ugliness". Let me use again the RFC 6716 as an example (just
because it is the only one that I know that embeds a complex
software): the source targzipped-archive converted in base64 produces
almost 160 pages (~ half RFC) of text like this

###CS55u+U+4xAxMpAkF/xwskEk0cAClEqDdyEPbJlnGdS0XBWHNmlekm/Jwlx/IvbR
###2z8EJ6fSvtYFvqb6J2hMI+drzqI0Z/TFmSJHVqg8ngw6o3wHb1XyV02/1FQyJvHV
###Bty0+KOMYa98efuPMOAORl/I+FNo/3m6udnctuw/4dOn4YP95y+y/zSfpu0/hycv

Would my proposal be better than this? It is not obvious...  while
with my proposal the source code would remain readable (ugly, but
readable), with the RFC6716 solution they were able to compress it,
possibly saving some space.  (Note however, that the moment you use a
tar-archive, you must convert to base64 anyway since the tar format is
not "pure printable").

Yes, definitively for cases like this the URI tar is the best solution
(also because you can update the software with bug corrections, bugs
in SW are much more frequent than bugs in RFC).  Every solution
invented so far is just a tentative to do our best with the tools we
have....


Let me conclude by adding a consideration: I guess that the discussion
could get complicated by the fact that there are many different cases
of "code embedding" and every case has its best solution.  Some
differences that could matter

  * Code length/complexity: it is just a short file/snippet? a long
file, but a single one? A collection of files?  A *large* collection
of pachydermic files?

  * Goal: source code? Test data? other?

  * Normative:  is the code normative or informative?  In the first
case, it is nice if it remains under IETF control, in the second case
it can be hosted somewhere else

  * Need of updates: if we expect to update the code (e.g., bug
corrections), maybe it is better if the code is separated from (but
linked to) the RFC; otherwise the code can be embedded in the RFC

Thanks

Riccardo

>
> Nico
> --


More information about the rfc-interest mailing list