[rfc-i] v3imp #8 Fragment tagging on sourcecode

Julian Reschke julian.reschke at gmx.de
Fri Jan 23 03:39:40 PST 2015

On 2015-01-23 10:08, Sean Leonard wrote:
> Minor Improvement Need
> #8 Fragment tagging on sourcecode
> This improvement calls for fragment tagging on the <sourcecode> element.
> This is a follow-up to Jim Schaad's request
> <mid:051301cffde1$ebd07590$c37160b0$@augustcellars.com>
> <http://www.rfc-editor.org/pipermail/rfc-interest/2014-November/008328.html>
> (Subject: Allow fragment tagging on sourcecode).
> The gist of jimsch's original improvement seems to be that fragments of
> a syntax (e.g., part of an ASN.1 module, such as a single definition)
> should be treated differently than a fig that includes a complete
> compilation unit. For example, many security RFCs include an "Appendix
> A. ASN.1 Module", where the primary figure is a complete ASN.1 module
> (regrettably punctuated with paging artifacts in the current text format).
> My improvement should be considered in light of Improvements #5 and #6,
> which permit including discrete files or Internet message content. One
> should assume that such elements are complete units. Therefore, the use
> of <sourcecode> should be restricted to fragments only—nobody should
> need to extract the <sourcecode> figs out of an RFC and stitch it
> together in order to feed it through some software process. As Paul
> noted in his response, there are ordering problems when piecing such
> fragmented figures back together, and tools may make bad assumptions.
> Nothing prevents an author from putting a "complete code unit" in a fig,
> of course, but the point is that a software process (e.g., a syntax
> highlighter) should assume that the fig is a fragment of the syntax
> rather than a complete unit.
> ...

Do you have a concrete proposal?

<artwork> already allows labeling with @name and @type, and I believe 
this provides sufficient metadata for automatic extraction.

Labeling things for the purpose of syntax highlighting is interesting, 
but there are more caveats than complete vs fragment. For instance, you 
might have examples that are known to be incorrect syntactically; would 
that be another hint?

Best regards, Julian

More information about the rfc-interest mailing list