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

[pkyzivat at alum.mit.edu (Paul Kyzivat)]

On 1/23/15 12:55 PM, Nico Williams wrote:
> On Fri, Jan 23, 2015 at 11:24:28AM -0500, Paul Kyzivat wrote:
>> 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.
>
> When authoring this can also be a problem.
>
> You might have a large module (ASN.1, XDR, ABNF, whatever) and you need
> to a) scatter it throughout the document so that the English prose can
> be read in context, b) gather it all into one appendix, c) be able to
> extract or inject the module so you can work on it outside the I-D
> (e.g., because the two are evolving).
>
> This is a bit pain.  It's the reason that RFC4120 was edited in nroff,
> IIRC.
>
> Keeping the canonical module scattered is not an answer.

Different strokes for different folks. This *can* work. It would work 
much better if you could automatically extract the collection of 
fragments when you want to process it.

	Thanks,
	Paul

> Addressing parts (of a canonical module in an Appendings) by line number
> seems lame.
>
> Annotating the module with anchors and start/end markers for extraction
> would require that the processor understand that markup in the figure,
> though at least the markup wouldn't have to be specific to the module
> language.  OR it would require breaking up the module into multiple
> CDATAs so that this markup can be XML (of course), but this is a PITA
> for authors.
>
> I don't have great answers.
>
> Nico
>