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

[Julian Reschke <[e-mail]>]

Am 07.12.2020 um 15:02 schrieb Michael Richardson:
>
> 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

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>

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

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

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

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.

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

Yes.

>    2) probably it involves revision to XMLv3 to make this possible,
>       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