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

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

On 1/23/15 5:49 PM, Nico Williams wrote:
> On Fri, Jan 23, 2015 at 04:41:53PM -0500, Paul Kyzivat wrote:
>> On 1/23/15 3:22 PM, Ted Lemon wrote:
>>> 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.
>
> There's no ABNF "module", and who's to say that piece of any "module"
> must be discussed in prose in concat order anyways?
>
> (Maybe we should introduce a notion of ABNF module.)

Maybe, but that belongs in a discussion of ABNF, not of RFC format.

> IMO the right thing to do is to define markup in modules of various
> types, to be interpreted only by the xml2rfc processor, and which is to
> be used to define chunks (named by anchors) to be extracted into figures
> that call for them (by anchor).

I'm not following you. Are you talking about markup specific to each 
'type', or a single markup for all types that might be embedded in drafts?

A generic one seems a step too far to me. And doing it on a 
type-specific basis isn't in scope here.

> The tricky part of my proposal is: either this markup isn't pure XML (it
> being embedded in CDATA, in ASN.1/ABNF/... comments) or the modules must
> be broken up into CDATA chunks interspersed with XML markup (ugh).  The
> former would be no fun for the tools folks, the latter would be no fun
> for authors and editors.
>
> One alternative would be to support addressing of logical chunks of
> modules by type/whatever name/path (e.g., ASN.1 type and value names,
> ABNF rule names, ...).  This would not be ideal (think of a very large
> type that would be best described over several figures), but it wouldn't
> have the tricky problems of the preceding proposal.

I have indeed considered extending ABNF syntax with 'include' syntax and 
rulename scoping. This would not be "markup" - it would be first class 
syntax within ABNF. It could be defined so that 'include' references 
could be resolved to a module defined within a draft/rfc and extracted 
as needed. And it could handle self references to other modules within 
the document doing the including.

	Thanks,
	Paul