[rfc-i] reference extensions

Julian Reschke julian.reschke at gmx.de
Mon Feb 17 08:27:22 PST 2014


On 2014-02-17 17:02, Paul Hoffman wrote:
> 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.

I didn't say that using ENTITYs is easy. I even believe it is a bad idea 
to use them.

What I'm saying is that you can simple download the preformatted 
reference entry and paste it into your document.

> 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.

Nor can it, as it's basic XML functionality.

>>>    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?

It's easier in that it doesn't require anything new; it also avoids 
hardwiring knowledge about reference libraries into the processor.

>>>    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.

There's nothing in the RNG that makes it clear that you need either the 
series attribute or a <front> element. Everything has become optional.

If the series information was a child element instead of an attribute, 
it would be simple to express the constraint in the grammar (it might be 
possible with attributes in RNG, but then we'd have the first case of a 
grammar constraint that's not expressible in the DTD as well).

> ...
>> 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.

Apparently. <seriesInfo> already identifies a publication series plus an 
identifier. Why invent a new element?

>> 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.

Yes, the canonical document needs to be self-contained. Your proposal 
doesn't solve this, unless you assume that the new notation always 
identifies immutable information. That may be true for RFCs, but it's 
not true for many other things people want to reference, such as 
internet drafts.

> ...

Best regards, Julian


More information about the rfc-interest mailing list