How do drafts get section links?

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

How do drafts get section links?

Jeffrey Yasskin
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
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: How do drafts get section links?

Carsten Bormann
Hi Jeffrey,

On Dec 8, 2017, at 01:11, Jeffrey Yasskin <[hidden email]> 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

_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: How do drafts get section links?

Jeffrey Yasskin
On Thu, Dec 7, 2017 at 4:47 PM Carsten Bormann <[hidden email]> wrote:
Hi Jeffrey,

On Dec 8, 2017, at 01:11, Jeffrey Yasskin <[hidden email]> 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.

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


(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

_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: [Rfc-markdown] How do drafts get section links?

Julian Reschke
In reply to this post by Carsten Bormann
On 2017-12-08 01:47, Carsten Bormann wrote:
> Hi Jeffrey,
>
> On Dec 8, 2017, at 01:11, Jeffrey Yasskin <[hidden email]> 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.

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.

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

Right.

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

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
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest
Reply | Threaded
Open this post in threaded view
|

Re: How do drafts get section links?

Julian Reschke
In reply to this post by Jeffrey Yasskin
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,
> 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

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
_______________________________________________
rfc-interest mailing list
[hidden email]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest