Subject: [rfc-i] How do drafts get section links?

From: Jeffrey Yasskin <[email-masked]>
Date: Fri, 08 Dec 2017 00:11:05 +0000

Hi RFC folks,

We noticed in
https://lists.w3.org/Archives/Public/ietf-http-wg/2017OctDec/0401.html that
some drafts (
https://tools.ietf.org/html/draft-ietf-httpbis-origin-frame-04#section-1,
https://tools.ietf.org/html/draft-ietf-httpbis-expect-ct-02#page-5) have
text like "([RFC7540], Section 9.1.2)" or "Section 3.2.6 of RFC 7230"
deep-linked to the right section in the target RFC, while other drafts (
https://tools.ietf.org/id/draft-yasskin-http-origin-signed-responses-01.html#proposal),
the editors' draft at
http://httpwg.org/http-extensions/origin-frame.html#introduction, and the
output of
https://xml2rfc.tools.ietf.org/cgi-bin/xml2rfc-dev.cgi?url=https://github.com/httpwg/http-extensions/raw/master/draft-ietf-httpbis-origin-frame.md&inputtype=kramdown&modeAsFormat=html/ascii#the-origin-http2-frame
don't have these deep links.

What's the right way to get deep links to sections from kramdown-rfc2629
source?

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

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 8 Dec 2017 01:47:30 +0100

Hi Jeffrey,

On Dec 8, 2017, at 01:11, Jeffrey Yasskin <[email-masked]> wrote:
> 
> What's the right way to get deep links to sections from kramdown-rfc2629 source?

(Sections of other documents, that is.)

RFCXML version 2 has no way to do this, so kramdown-rfc doesn’t support it.

So why are you seeing links on tools.ietf.org (and only there) where there aren’t any?
The .txt to .html converter at tools.ietf.org has some heuristics that allow it to identify references to sections of other RFCs.  These heuristics sometimes fail to notice (and famously sometimes point to the wrong document, leading to spurious errata about problems that aren’t even in the RFC), but they are better than nothing.

Now how is the syntax for deep links into documents going to look like in kramdown-rfc when we add RFCXML v3 support?
I don’t know yet.  But I note that essentially the same heuristics that work on .txt files on tools.ietf.org might work in a markdown source document (and, if they don’t, the author can still set a manual xref [er, relref, if that thing stays in v3]).

(CCing rfc-markdown, as the question is of interest there, too; please trim the CC list if you just want to vent about relref, as you probably should at this point.)

Grüße, Carsten

---

From: Jeffrey Yasskin <[email-masked]>
Date: Fri, 08 Dec 2017 04:45:25 +0000

> RFCXML version 2 has no way to do this, so kramdown-rfc doesn’t support it.

Yeah, I mostly mentioned kramdown-rfc to make sure any answers like "use
https://www.greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#ext-rfc2629.xref"
included instructions for how to get the right attributes into the XML from
.md source.

So why are you seeing links on tools.ietf.org (and only there) where there
> aren’t any?
> The .txt to .html converter at tools.ietf.org has some heuristics that
> allow it to identify references to sections of other RFCs.  These
> heuristics sometimes fail to notice (and famously sometimes point to the
> wrong document, leading to spurious errata about problems that aren’t even
> in the RFC), but they are better than nothing.
>

Ah, I see: https://tools.ietf.org/tools/rfcmarkup/ does this for URLs under
https://tools.ietf.org/html/, but the id/ URLs only use xml2rfc or
rfc2629.xslt and so don't get the benefit. That answers my question of how
to test that my source gives the right section links, and in fact
https://tools.ietf.org/html/draft-yasskin-http-origin-signed-responses-01#section-2
has decent deep links, while
https://tools.ietf.org/id/draft-ietf-httpbis-origin-frame-04.html#rfc.section.1
doesn't.

I'm happy to conclude that my mistake was in sending out the wrong links,
and that this list doesn't need to do anything until RFCXML v3 support
comes along.

Now how is the syntax for deep links into documents going to look like in
> kramdown-rfc when we add RFCXML v3 support?
> I don’t know yet.  But I note that essentially the same heuristics that
> work on .txt files on tools.ietf.org might work in a markdown source
> document (and, if they don’t, the author can still set a manual xref [er,
> relref, if that thing stays in v3]).
>

(https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/26)

(CCing rfc-markdown, as the question is of interest there, too; please trim
> the CC list if you just want to vent about relref, as you probably should
> at this point.)

Thanks,
Jeffrey

---

From: Julian Reschke <[email-masked]>
Date: Fri, 8 Dec 2017 06:46:41 +0100

> RFCXML version 2 has no way to do this, so kramdown-rfc doesn’t support it.

FWFW, rfc2629.xslt does, see 
<https://www.greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#ext-rfc2629.xref>, 
so kramdown-rfc in theory could support it for that backend.

> The .txt to .html converter at tools.ietf.org has some heuristics that allow it to identify references to sections of other RFCs.  These heuristics sometimes fail to notice (and famously sometimes…

Right.

> (CCing rfc-markdown, as the question is of interest there, too; please trim the CC list if you just want to vent about relref, as you probably should at this point.)

I did some experiments with the output of kramdown-rfc as used in HTTP 
and QUIC WG documents (for instance: 
<https://www.greenbytes.de/tech/webdav/draft-ietf-quic-http-08.html#rfc.section.3.1>), 
and heuristics work a bit better if you do not have to worry about line 
breaks. But it's still only heuristics.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 8 Dec 2017 07:02:25 +0100

On 2017-12-08 01:11, Jeffrey Yasskin wrote:
> Hi RFC folks,
> 
> We noticed in 
> https://lists.w3.org/Archives/Public/ietf-http-wg/2017OctDec/0401.html 
> that some drafts 
> (https://tools.ietf.org/html/draft-ietf-httpbis-origin-frame-04#section-1, 
> deep-linked to the right section in the target RFC, while other drafts 
> (https://tools.ietf.org/id/draft-yasskin-http-origin-signed-responses-01.html#proposal), 
> the editors' draft at 
> http://httpwg.org/http-extensions/origin-frame.html#introduction, and 
> the output of 

These are produced by different processors:

- rfcmarkup operates on plain text source and attempts to add the links; 
most of the times it gets it right, but only most of the time

- xml2rfc operates on the XML, which currently has no way to express 
this (without extensions), and does not attempt heuristics

- rfc2629.xslt operates on the XML and supports this through an 
extension, but kramdown-rfc would need to use it

That said, I'm experimenting with a post processor that applies these 
heuristics at the XML level; see for instance 
<https://www.greenbytes.de/tech/webdav/draft-ietf-httpbis-origin-frame-04.html>.

Best regards, Julian