[rfc-i] Proposal for v3 to simplify most referneces

Heather Flanagan (RFC Series Editor) rse at rfc-editor.org
Mon Feb 10 09:02:45 PST 2014


On 2/9/14 8:53 AM, Julian Reschke wrote:
> On 2014-02-09 04:57, Paul Hoffman wrote:
>> Greetings again. 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.
>>
>> 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 have their faults. The first requires good
>> copying skills and sometimes causes difficult XML errors; the second
>> prevents you from changing the anchor name and also requires that you
>> be online when you run the xml2rfc processor.
>>
>> The following is a proposed addition to the v3 format. It supplements
>> the current options, but anyone wanting to use the current options can
>> continue to do so.
>>
>> The <reference> element can take another optional attribute: "rfc",
>> "fyi", "id" "bcp", or "std". Each takes a string that is a number. If
>> "bcp" or "std" are given, an additional optional "expanded" attribute
>> can be given: it is a comma-separated list of numbers. At the same
>> time, the contents of <reference> goes from requiring <front> to
>> making <front> optional.
>>
>> Examples of entire references could be:
>>     <reference anchor="SMIME-OID" rfc="7107"/>
>>     <reference anchor="IPRNEW" bcp="79"/>  # Will expand to RFC 3979
>> and RFC 4879
>>     <reference anchor="IPROLD" bcp="79" expanded="3668"/>   # *Old*
>> contents of the BCP
>>     <reference anchor="ABFAB-USECASES" id="draft-ietf-abfab-usecases"/>
>>
>> Clearly, this proposal would require some smarts (and hopefully good
>> error messages) in the processor. The processor would need to make
>> sure that exactly zero or one of "rfc", "fyi", "id" "bcp", or "std" is
>> given. It would also have to do a sanity check on the "expanded" list
>> to see if that list matches the present or a previous set of values
>> for the BCP or STD. It would then emit the properly-formatted output
>> for the reference.
>>
>> This would make it much easier to create RFCs that have the desired
>> anchor names. It would also prevent the RFC Editor from having to
>> check and/or replace the <reference> contents for Internet Drafts that
>> come to them. (Ideas for simplifying references to documents from
>> outside the IETF can be handled at a different time.)
>>
>> Are there any objections to this addition to the v3 vocabulary?
> 
> I think you're trying to solve several different problems at the same
> time, with the result of it not being generic enough.
> 
> For instance, we know that people are unhappy with 3GPP references,
> because "3GPP" is a prefix not allowed in an anchor, yet your proposal
> addresses just IETF document references.

If I read Paul's suggestion correctly (and Paul, I'm trusting you'll
correct me if I have not), he's talking about adding another way to
handle references that focuses on IETF documents.  Since it does not
replace the previous versions, it should not impact how non-IETF
documents are referenced.

> 
> I believe we need to come up with solutions that address each of the
> problems we have in an orthogonal way, so that they apply to "other"
> documents as well.

I'm sorry, I am not sure what you mean by this.  Are you saying each
problem needs an independent, unrelated solution so we have the option
of mixing-and-matching solutions without having them impact one another?
 That seems an interesting ideal, but rather inefficient and potentially
confusing for the authors.

-Heather


More information about the rfc-interest mailing list