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

Julian Reschke julian.reschke at gmx.de
Wed May 27 07:41:17 PDT 2015


On 2015-05-27 16:09, Paul Hoffman wrote:
> ...
>> 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.

IMHO the problem behind this is that <xref> is used for many different 
kinds of references, such as to sections, tables, figures, references, 
list items. Some of these have titles, some have some type of counter 
(not necessary decimal), some have symbolic names.

Of course adding new stuff to <xref> makes that element harder to 
implement and document (not necessarily to use). But adding *another* 
element with overlapping functionality doesn't solve this problem.At 
least not for me.

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

Functionality was lost, as far as I can tell.

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

The result was supposed to be predictable before as well. If it wasn't, 
then it was a failure of the text defining it (and no, I'm not trying to 
blame you for that; it would be a collective failure of the design group).

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

I will do that.

Best regards, Julian



More information about the rfc-interest mailing list