[rfc-i] v3imp #8 Fragment tagging on sourcecode
pkyzivat at alum.mit.edu
Fri Jan 23 08:24:28 PST 2015
Of all the things in this recent burst, this is the first one that
grabbed me. I have looked into extracting ABNF from drafts, and did
indeed encounter problems. I found the following variations:
1) a single figure containing a complete ABNF source
2) fragments of ABNF scattered through a document.
When consolidated these form a single complete ABNF source.
3) a combination of (1) and (2): fragments in the text
followed by a complete source that replicates the fragments.
4) multiple independent ABNF sources in the same document.
This is especially challenging if trying to extract from the .txt form.
But it is still challenging if extracting from an xml form that is
tagged with type.
My objective was to come up with a way that ABNF can be automatically
verified, including those cases where the ABNF in a document is an
extension to that in another document. (So that the ABNF from this
document must be merged with that from the base document before it can
be verified. (This would require some ABNF extensions to identify the base.)
Some of this might be accomplished by some conventions, though it seems
hacky. E.g. fragments could all be tagged with the same filename if the
extraction is understood to merge them into the same file. Some enhanced
tagging, or clarification of usage conventions like this, would help.
On 1/23/15 6:39 AM, Julian Reschke wrote:
> 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
>> (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
>> 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
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
More information about the rfc-interest