Subject: [xml2rfc] Filling out templates in XML

From: Sean Leonard <[email-masked]>
Date: Tue, 28 Jun 2016 20:24:25 -0700

Just curious if people have thought about using XML elements to fill out 
templates, in xml2rfc, rather than sticking the template instance in an 
artwork blob.

Consider <draft-ietf-netconf-restconf-14.xml> (which I just reviewed). 
In #media-types, the RFC 6838 templates are instantiated as artwork. 
Wouldn't it be better to put the things in some basic XML blocks? I have 
seen very long registration templates elsewhere, like URNs and URIs, 
that can spill over to multiple pages. It would be helpful if these 
could be treated (at least in part) as regular runs of text so that they 
are subject to page breaking automatically, etc.

There is a temptation to over-specify the details of every registration 
template. Perhaps a quick survey could be done, to see some common 
IETF/IANA registration templates, and if there is enough common to them 
to permit a small handful of elements. 6 elements or less, I would say. 
For example:

<instance schema="RFC6838">
   <field name="Type name">application</field>
   <field name="Subtype name">yang-data+xml</field>
   <field name="Required parameters">none</field>
   ...
   <field name="Security considerations"><t>Security considerations related
       to the generation and consumption of RESTCONF messages
       are discussed in Section NN of <xref target="RFCXXXX" />.
       Additional security considerations are specific to the
       semantics of particular YANG data models. Each YANG module
       is expected to specify security considerations for the
       YANG data defined in that module.</t>

   <additional>blah blah blah at end of instance</additional>
</instance>

That yields 3 elements: instance, field, and additional.

An alternate approach is to have some XML namespace/schema and embed it 
in a <figure>, similar to <svg> (in <artwork>) and <sourcecode>. Could 
get needlessly complex, but would limit arbitrary placement. Depends on 
whether one feels that registration templates need to be in <figure> 
elements or not. I believe that template instances can be part of the 
main specification text (first, because template instances can contain 
normative specification language; second, because it's possible that 
template fields might have figures inside); therefore, they should not 
be required to be in <figure> elements.

Just my 2¢.

Sean

---

From: Julian Reschke <[email-masked]>
Date: Wed, 29 Jun 2016 07:18:13 +0200

> templates, in xml2rfc, rather than sticking the template instance in an

I have always put registrations either into tables or lists. I agree 
that using artwork is a very bad thing.

Best regards, Julian