Subject: [rfc-i] Incorrect auto linking in html versions of drafts and RFCs

From: Mohit Sethi <[email-masked]>
Date: Wed, 23 May 2018 09:35:52 +0300

Hi all,

I have lately been implementing some drafts and RFCs related EAP and 
JSON Web formats (JWS/JWK/JWA etc.). While reading, I noticed an unusual 
problem with some of the hyper links in the HTML version of drafts/RFCs.

Sometimes, there is text in a draft/RFC saying "look at section x.y.z of 
some external document", the HTML version of the draft/RFC automatically 
generates a hyper link for the text "section x.y.z". This hyper link 
however points to the section x.y.z in the current document. In many 
cases, section x.y.z does not even exist in the current document.

Here is a couple of examples from RFC 7517 
(https://tools.ietf.org/html/rfc7517):

1. The text in section 4 reads "

returns only the lexically last duplicate member name, as specified
    inSection 15.12 <https://tools.ietf.org/html/rfc7517#section-15.12>  (The JSON Object) of ECMAScript 5.1 [ECMAScript <https://tools.ietf.org/html/rfc7517#ref-ECMAScript>].

"

The hyper link for "Section 15.12" tries to find section 15.12 in RFC 
7517 which clearly does not have such a section.

2. From the same text in section 4 "

  Section 6 <https://tools.ietf.org/html/rfc7517#section-6>  of the JSON Web Algorithms (JWA) [JWA <https://tools.ietf.org/html/rfc7517#ref-JWA>] specification
    defines multiple kinds of cryptographic keys and their associated
    members.
"

The hyper link for "Section 6"  links to Section 6 of the JWK document 
instead of linking it to the Section 6 of the JWA document as it should!

3. Here is another example from a randomly chosen RFC. This text is 
taken from RFC 8321 section 7 (https://tools.ietf.org/html/rfc8321): "

Performance Metric Definition
    template defined inSection 5.4 of [RFC6390] <https://tools.ietf.org/html/rfc6390#section-5.4>  and the Dependencies
    laid out inSection 5.5 <https://tools.ietf.org/html/rfc8321#section-5.5>  of that document.

"

Here the first link correctly points to Section 5.4 of RFC6390 but the 
second link points to "Section 5.5" of RFC 8321 instead of RFC6390.

Please note that I have encountered this problem several other drafts 
and RFCs. What's worse, there is no way for draft authors to control 
this behavior with xml2rfc. The txt and html outputs from xml2rfc do not 
show these automatic hyper links. I was hoping that this is something 
the RFC editor could resolve at least for all future RFCs and drafts if 
not retrospectively fix existing documents.

--Mohit

PS: I wasn't sure which was the right list. Please feel free to forward 
it to the right list.

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Ronald Tse <[email-masked]>
Date: Wed, 23 May 2018 06:42:37 +0000

Hi Mohit,

You are right — and this is a known problem. This issue stems from the fact that `rfcmarkup` is used to render the HTML of the I-D/sRFCs.

Specifically, rfcmarkup produces the final HTML using heuristics from the source TXT, such as by searching for the keyword “Section”. An obviously better approach is to have rfcmarkup create the HTML from the original source RFC XML, which includes semantics, or to use xml2rfc to create the HTML page directly.

For some reason it is not yet done this way; the RFC editors may be waiting for the new RFC XML v3 workflow before this.

Ron

_____________________________________

Ronald Tse
Ribose Inc.

On May 23, 2018, at 2:35 PM, Mohit Sethi <[email-masked]<mailto:[email-masked]>> wrote:

Hi all,

I have lately been implementing some drafts and RFCs related EAP and JSON Web formats (JWS/JWK/JWA etc.). While reading, I noticed an unusual problem with some of the hyper links in the HTML version of drafts/RFCs.

Sometimes, there is text in a draft/RFC saying "look at section x.y.z of some external document", the HTML version of the draft/RFC automatically generates a hyper link for the text "section x.y.z". This hyper link however points to the section x.y.z in the current document. In many cases, section x.y.z does not even exist in the current document.

Here is a couple of examples from RFC 7517 (https://tools.ietf.org/html/rfc7517):

returns only the lexically last duplicate member name, as specified
   in Section 15.12<https://tools.ietf.org/html/rfc7517#section-15.12> (The JSON Object) of ECMAScript 5.1 [ECMAScript<https://tools.ietf.org/html/rfc7517#ref-ECMAScript>].

"

The hyper link for "Section 15.12" tries to find section 15.12 in RFC 7517 which clearly does not have such a section.

 Section 6<https://tools.ietf.org/html/rfc7517#section-6> of the JSON Web Algorithms (JWA) [JWA<https://tools.ietf.org/html/rfc7517#ref-JWA>] specification
   defines multiple kinds of cryptographic keys and their associated
   members.
"

The hyper link for "Section 6"  links to Section 6 of the JWK document instead of linking it to the Section 6 of the JWA document as it should!

3. Here is another example from a randomly chosen RFC. This text is taken from RFC 8321 section 7 (https://tools.ietf.org/html/rfc8321): "

Performance Metric Definition
   template defined in Section 5.4 of [RFC6390]<https://tools.ietf.org/html/rfc6390#section-5.4> and the Dependencies
   laid out in Section 5.5<https://tools.ietf.org/html/rfc8321#section-5.5> of that document.

"

Here the first link correctly points to Section 5.4 of RFC6390 but the second link points to "Section 5.5" of RFC 8321 instead of RFC6390.

Please note that I have encountered this problem several other drafts and RFCs. What's worse, there is no way for draft authors to control this behavior with xml2rfc. The txt and html outputs from xml2rfc do not show these automatic hyper links. I was hoping that this is something the RFC editor could resolve at least for all future RFCs and drafts if not retrospectively fix existing documents.

--Mohit

PS: I wasn't sure which was the right list. Please feel free to forward it to the right list.

_______________________________________________
rfc-interest mailing list
[email-masked]<mailto:[email-masked]>
https://www.rfc-editor.org/mailman/listinfo/rfc-interest