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

Nico Williams nico at cryptonector.com
Fri Jul 12 13:14:35 PDT 2013


On Fri, Jul 12, 2013 at 2:39 PM, Paul Kyzivat <pkyzivat at alum.mit.edu> wrote:
> I think it is a little more complicated than that. And details may vary
> depending on who you are talking to.
>
> Some drafts "contain" (embed) *renderings* of material that may wish to be
> used outside the context of the draft. Use outside the draft may require the
> original form, not the rendered form.
>
> Coherence is essential - that what uses outside the draft see is identical
> to what was used to render the draft. (Extracting the code from the .txt is
> one way to achieve coherence. But IMO its not the ideal way.)
>
> Renderings for the draft may include indenting, line folding, escaping of
> problematic characters, pagination including page headers/footers in the
> midst of the rendering, and interspersing of draft commentary with the
> rendered material.
>
> (For instance, some drafts intersperse commentary with ABNF.)

This.   This has been a problem in many cases, such as, for example
RFC4120 authoring.

It's essential to be able to define large amounts of ABNF/ASN.1/XDR,
... and then pick out little bits of said code for interspersing with
comments.  This requires a fundamental re-think of how we approach
code in xml2rfc.

Ideally we could have a series of <artwork> (or <code>) that gets put
together in order for extraction (and for display of the whole), but
which allows for referencing from prose such that the snippets can be
embedded in prose.

Something like:

<t>The type FOO:</t>
<figure><artwork target="asn1_type_decl_FOO"/></figure>
<t>is used like so and so....</t>
...

then in an appendix:

<figure><artwork anchor="...">...</artwork><artwork
anchor=äsn1_type_decl_FOO">...</artwork>...</figure>

I'd like that.

Nico
--


More information about the rfc-interest mailing list