[rfc-i] reference extensions

Paul Hoffman paul.hoffman at vpnc.org
Mon Feb 17 08:02:18 PST 2014

On Feb 16, 2014, at 11:18 PM, Julian Reschke <julian.reschke at gmx.de> wrote:

> On the proposed <reference> changes (<http://tools.ietf.org/html/draft-hoffman-xml2rfc-02#section-1.1.2>):
>>   This section describes one of the larger changes in the design of v3,
>>   namely the additions to make using references easier.  Most
>>   references in most recent RFCs are just to RFCs; sometimes they are
>>   Internet Drafts as work-in-progress; much less often they are
>>   pointers to standards of other SDOs, research articles, or just plain
>>   URLs.  There have been many complaints about how difficult it is for
>>   people who don't have strong XML skills to use references when making
>>   Internet Drafts.
> True, but then creating RFC references already is easy compared to the other series, as we *do* have preformatted entries.

You may find using ENTITY commands easy; many people have complained about them. It seems reasonable to listen to those people and make the v3 format easy to create for everyone, not just HTML/XML experts.

Further, using ENTITY commands either forces you to use the same anchor as what was pre-ordained, or for us to come up with a new feature that is a level of indirection for anchor names. Just making RFCs like the other references seems like a better answer.

And, to be clear: if you want to use ENTITYs to create a v3 document, you still will be able to. Nothing in the current spec prevents that.

>>   The two popular methods now for references to RFCs are entering the
>>   whole reference by hand (hopefully getting all the fiddly bits of
>>   <front> and <seriesinfo> correct), or using XML entities that call
>>   out the xml.resource.org.  Both work, but both have their faults.
>>   The first requires good copying skills and sometimes causes difficult
> What exactly do you mean by "good copying skills"? The ability to copy and paste from an XML document? Maybe that's something we can address by just creating easier-to-use libraries.

We could do that. How would it possibly be easier than using the new attributes?

>>   XML errors; the second prevents you from changing the anchor name
>>   and, less importantly, also requires that you be online when you run
>>   the xml2rfc processor.
> Unless there's a cache. But yes.
> Another drawback is that the document isn't self-contained anymore.

Another "yes".

>>   o  Thus, the contents of <reference> changes from requiring a <front>
>>      element to making the <front> element optional if a "series" is
>>      given.
> Well, not in the schema that you are using.

Please say more.

> If automatic validation remains a goal, this probably needs to be a new child element that can be used in place of <front>.

I considered that, but I figured you would not like it because it is not just a replacement for <front>, it is a replacement for <front> and <seriesinfo> and <format>. At that point, saying "the attribute is a replacement for all the content" is a lot easier to describe.

> Another alternative would be to keep <front> and to leverage <seriesInfo>.

Our views of what is easy to use for people not as versed in XML as you are differ sharply.

> That being said, this proposal tries to address a problem that is not specific to <reference>s; inclusion of external content.

No, it really doesn't. It tries to address exactly <reference>. It does more than just include external content: it allows the writer to give the anchor name that they want, it prevents the RFC Editor from having to check the exact contents of the <front> and <seriesinfo>, and it makes creating a document easier.

> I'd prefer to come up with something which works for other content as well, such as by defining a generic inclusion mechanism (such as XInclude or a subset of it).

Having a canonical RFC have an inclusion from an external source seems like a very bad idea for stability. Instead, we should keep requiring that the canonical RFC be complete and unchanging.

> It also does *not* address other problems with <reference>, such as the naming constraint on anchors (which makes it impossible to use a label such as [3GPP], nor the reference-to-a-document-series problem.

Correct, it does not address either of those. Both of those are valid requests for changes to the spec.

--Paul Hoffman

More information about the rfc-interest mailing list