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

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

On 1/23/15 3:22 PM, Ted Lemon wrote:
> On Jan 23, 2015, at 2:44 PM, Sean Leonard <dev+ietf at seantek.com> wrote:
>> To eliminate transcription errors, don't attempt to stitch disparate <sourcecode> and <artwork> elements together. The standards author SHOULD provide normative modules, such as in <attachment> elements. Making sure that "inline" content (<sourcecode> and <artwork>) matches normative "attachment" content is an editorial matter.
>
> Actually, I think there can be a number of different approaches that make sense:
>
> 1. The RFC in a sense annotates the ABNF, which is presented in labeled chunks marked for order, or else defaulting to being in order.   The document processor could in principle extract the ABNF, concatenate it, and present you with what you need.
>
> 2. The RFC has ABNF interspersed, which may or may not be complete, and the full ABNF is presented in an appendix.   It would be ideal if the appendix could be generated as a concatenation of the ABNF in the main text, possibly with additional fragments.   Failing that, the fragments should be automatically checkable against the complete ABNF to make sure that they are consistent.   Either of these approaches are straightforward.

I think it may be worth discussing how important this would be if there 
was a straightforward and consistent way to extract the full ABNF. ISTM 
that this style exists primarily because of a lack of that tool.

OTOH, there are times when I just want to look at the syntax, and having 
it there in one place is nice.

It is a bit of an editorial burden to manually maintain the consistency 
between the two. But whether that justifies tooling to avoid it is 
debatable.

If you can extract all the fragments as one file, and the appendix as 
another file, then it is pretty trivial to compare them, without any 
specific tooling.

> 3. The RFC has ABNF in an appendix, and references the ABNF in the appendix appear throughout the document.   Now you need anchor tags for the references.   I don't think this is actually very usable, though, so I'm not sure we really need to support this mode.   But I agree that we need to support anchor tags.

This seems largely unworkable.

	Thanks,
	Paul