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

[dev+ietf at seantek.com (Sean Leonard)]

On 1/23/2015 12: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.
>
> 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.

As a technical matter, I believe that the vocabulary should support all 
three.

As an editorial matter, avoiding duplication is superior: duplicated 
content raises the risk of inconsistency.

Rather than wishing for interspersed rules in figures /plus/ a collected 
appendix, consider that a tool that processes the xml v3 format should 
be able to show various views of the content, including a view where all 
of the ABNF is concatenated together. Thus consider a RFC viewer 
(probably some web app) with three tabs: Specification, ABNF, and 
Attachments. The Specification tab just shows some regular text view(s). 
The ABNF tab collects all of the (inline) ABNF and displays them in a 
nice way--possibly with hyperlinks that show all cross-references to the 
main text. (Being ABNF-aware, the ABNF tab could also fold/eliminate 
duplicate rules, so if you really want to intersperse rules in the text 
AND have your appendix, the tool should be smart about that.) Similarly, 
the Attachments tab collects all of the attachments so they can all be 
saved to disk in one fell swoop.

Thus if you have an ABNF rule:

<sourcecode type="abnf">
abnfFooRule = 5*ALPHA
</sourcecode>

Then in some spec-text, you might say:

<t>The <named type="abnf">abnfFooRule</named> is an identifier for foo 
things. It MUST be at least 5 letters.</t>

...in which case, the tools can automatically generate anchors and links 
between the <named> element and the abnfFooRule in the figure 
(<sourcecode> element)...no need to create unnecessary anchors. This is 
a specific motivator for Improvement #3.

On 1/23/2015 3:17 PM, Nico Williams wrote:
> On Fri, Jan 23, 2015 at 06:11:33PM -0500, Paul Kyzivat wrote:
>> On 1/23/15 5:49 PM, Nico Williams wrote:
>>> 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?
> ASN.1 could look like:
>
>    -- <xml2rfc:fragment anchor="Foo">
>    Foo ::= SEQUENCE {
>      ...
>    }
>    -- </xml2rfc:fragment anchor="Foo">
>
> Yes, a bit ugly (OK, *very* ugly), but it would allow the author to keep
> all of a module in a single, cohesive file, without having to go update
> a bunch of figures every time he or she has to make a significant change
> (e.g., add a prefix to all defined entity names).

See above--much less ugly.

>   [...]
> Agreed.  ABNF needs a notion of modules, imports, and exports.  Like
> ASN.1.  Use URNs not OIDs to name modules though!  :)

I am wary of extending ABNF: the beauty of it is that it is simple and 
easy to understand. Most people believe that ASN.1 is "too complex" so 
there is a real risk of messing up a good thing. At the same time, I 
will not actively oppose such efforts if others want to attempt it.

The point of this thread is xml2rfc...at this juncture, ABNF doesn't 
have modules, imports, or exports; I interpret this to mean that ABNF 
isn't really appropriate for <attachment>, but is appropriate for inline 
<sourcecode> and <artwork> type elements.

Sean