[rfc-i] v3imp #8 Fragment tagging on sourcecode
pkyzivat at alum.mit.edu
Fri Jan 23 15:11:33 PST 2015
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.
More information about the rfc-interest