[rfc-i] reference extensions
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.
>> o Thus, the contents of <reference> changes from requiring a <front>
>> element to making the <front> element optional if a "series" is
> 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.
More information about the rfc-interest