[rfc-i] New Version Notification for draft-hoffman-xml2rfc-18.txt

Paul Hoffman paul.hoffman at vpnc.org
Wed May 27 07:09:13 PDT 2015


On May 26, 2015, at 11:11 PM, Julian Reschke <julian.reschke at gmx.de> wrote:
> After reading further, I see that I missed additional attributes that weren't mentioned in the introduction.

Yes; I am assuming that people will read the draft.

> So apparently:
> 
>> The frequent idiom of
>> 
>>    See Section x of [RFCyyyy]
>> 
>> previously was
>> 
>>    See <xref section="x" format="of" target="RFCyyyy"/>
>> 
>> now becomes:
>> 
>>    See <relref section="x" target="RFCyyyy"/> of <xref target="RFCyyyy"/>
> 
> you can use
> 
>      See <relref section="x" sectionFormat="of" target="RFCyyyy"/>
> 
> while in the previous draft you'd have used:
> 
>      See <xref section="x" sectionFormat="of" target="RFCyyyy"/>

The previous draft was incomplete about the processing of the extended <xref>. When I went to expand it so that it was complete, I discovered that it became much more complicated, with a lot of twisted "except" clauses. Adding <relref> made the flow significantly easier to follow. I consider it important to make this feature accessible to less-experienced Internet-Draft writers.

> So <xref> was simplified, but <relref> was added which has exactly the same complexity as <xref> with respect to crossreferencing <references>.

No; see above. If you believe I'm wrong, feel free to use the text from this draft to fold the functionality back into <xref> and post the result here so that others can compare them for understandability.

> (It also lost two sectionFormat values, but that's a different story.)

No, it's actually not. Those were part of the problem.

> For authors this means that when they make their <xref> more specific, they need to switch to a different element.

Yes. The tradeoff is that when they do that, the are more likely to do it correctly because the result will be more predictable.

> For implementers of tools this means that they have two distinct elements that overlap in functionality.

In the design team, you argued that the difficulty of writing tools once should not be a determining factor, and we all agreed.

> I still have no clue how this is better than what we had before.


See above. When you actually describe to the user what will happen (as compared to just putting a stub in, as I had done before), this is a better design. If you disagree, show all the work for the earlier design and folks can compare.

--Paul Hoffman


More information about the rfc-interest mailing list