Subject: [Tools-discuss] page number-less, section-number-less references to Internet-Drafts

From: Michael Richardson <[email-masked]>
Date: Mon, 07 Dec 2020 09:02:41 -0500

In the great pagination debate, it was asserted that people ought to be
writing reviews, and the like against section anchors rather than page
numbers, line numbers or maybe even section numbers.

Right now, one typically refers to another *RFC* as:
      <xref target="RFC1234"/> section 1.2.3.4

This is tolerable because once published, RFCs can't change so the numbers
are stable.  I don't think that we ever link directly the section itself.
(Or does htmlize do that for us...)

In internet-drafts it seems that this is really fragile thing.
Particularly among a group of documents that are co-evolving, I've often had
to figure out what the section numbers are after a change, and it's not
always obvious until some months later when a reviewer is confused.

So my questions are:
  1) is this something anyone other than me cares about?

  2) probably it involves revision to XMLv3 to make this possible,
     and I assume that is a hard thing still.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Julian Reschke <[email-masked]>
Date: Mon, 7 Dec 2020 15:22:32 +0100

>        <xref target="RFC1234"/> section 1.2.3.4

Typically, it should be

          <xref target="RFC1234" section="1.2.3.4"/>

or

          <xref target="RFC1234" section="1.2.3.4" sectionFormat="comma"/>

which would yield

          Section 1.2.3.4 of [RFC1234]

or

          [RFC1234], Section 1.2.3.4

And no, this syntax is neither in RFC 7991 nor 7991bis, a proposal is
here:
<https://www.ietf.org/archive/id/draft-levkowetz-xml2rfc-v3-implementation-notes-11.html#section-3.1.26>

> (Or does htmlize do that for us...)

Yes it does, so does xml2rfc v3's HTML output.

> always obvious until some months later when a reviewer is confused.

WHich is why I recommend to reference concrete versions, so that the act
of updating the reference is something that doesn't happen in an
uncontrolled way.

>    1) is this something anyone other than me cares about?

Yes.

>       and I assume that is a hard thing still.

The vocabulary itself doesn't help here yet.

For specs that co-evolve (such as the three HTTP core specs), I have my
own extensions in rfc2629.xslt, so that I can use the section anchors
instead of section numbers. This requires a preprocessing step if you
want to feed the output into xml2rfc.

For other specs (QUIC), I locally run a filter on the XML which embeds
section link target metadata (anchor name and section title) as
processing instructions, so at least it becomes clear *what* the link
target is, and it's easier to track if something changes (if you're
interested in this, I can publish it).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 7 Dec 2020 15:25:37 +0100

Yes.

If you make references to the HTML, these need not have section numbers, but can be based on the anchor names defined by the author (which now leak out, which they didn’t before, by the way).

So instead of referencing Section 4.7 of draft-ietf-asdf-sdf, just reference

https://www.ietf.org/archive/id/draft-ietf-asdf-sdf-01.html#name-data-qualities

Remaining homework: Get a stable URL for the draft’s HTML, instead of for a specific version.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 10 Dec 2020 15:26:12 +0100

Am 07.12.2020 um 15:22 schrieb Julian Reschke:
> ...
In the meantime I realized that I left out a few things. Here we go.

In xml2rfc, it *is* possible to link to a specific anchor in the target
document. However, it still requires specifying the section number,
because, *in general*, the processor can't know how to compute it.

For instance:

    <xref target="XML" section="2.3" rel="#sec-common-syn"/>

and

   <reference anchor='XML'
target='https://www.w3.org/TR/2008/REC-xml-20081126/'>
      ...
   </reference>

resulting in something like:

   <a
href="https://www.w3.org/TR/2008/REC-xml-20081126/#sec-common-syn">Section
2.3</a> of <a href="#XML"><cite title="Extensible Markup Language (XML)
1.0 (Fifth Edition)">[XML]</cite></a>)

Now *if* the document being linked to is generated by xml2rfc, it *is*
possible to compute the section number, as long as the XML source is
available.

rfc2629.xslt supports that using an extension element, see
<https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#ext.element.source>.
With that, the section number can be left out.

This works for rfc2629.xslt used "stand-alone", but also when run as a
preprocessor for xml2rfc.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 10 Dec 2020 15:30:37 +0100

> 1.0 (Fifth Edition)">[XML]</cite></a>)

That is not exactly section-number-less.

This is also not really the example we were looking at, as it points to a specific past document; there is no point in having section-number-less references there.
What I was trying to do was to point to a draft that evolves, from an email.
Of course, the same is useful from another draft that evolves.  (The RFC-Editor will then, at as late a point as possible, have to pin this.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 10 Dec 2020 15:42:18 +0100

> Of course, the same is useful from another draft that evolves.  (The RFC-Editor will then, at as late a point as possible, have to pin this.)

I should have added another example, using the rfc2629.xslt extensions I
mentioned.

With that, you can do something like:

   <t>
     <xref target="Semantics" x:rel="#conformance"/> defines conformance
criteria and contains considerations regarding error handling.
   </t>

...generating...

                <p>
                   <a
href="draft-ietf-httpbis-semantics-latest.xhtml#conformance"
title="Conformance">Section 2</a> of <a href="#Semantics">
                      <cite title="HTTP Semantics">[Semantics]</cite>
                   </a> defines conformance criteria and contains
considerations regarding error handling.
                </p>

...so document A (here draft-ietf-httpbis-caching-latest) refers to
sibling document B (draft-ietf-httpbis-semantics-latest), and the
*source* does not need to include the section number (the HTML output
does though).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 10 Dec 2020 15:44:33 +0100

On 2020-12-10, at 15:42, Julian Reschke <[email-masked]> wrote:
> 
> draft-ietf-httpbis-semantics-latest.xhtml#conformance

Of course, there is some name-mangling going on in the HTML production, so this is still, er, interesting, but that is exactly what I had in mind.

Grüße, Carsten