Subject: [xml2rfc] can xref section= reference an anchor?

From: Robert Moskowitz <[email-masked]>
Date: Mon, 16 Dec 2019 11:47:42 -0500

I see examples of section=5 for RFCs, but for IDs, the section number 
will tend to be version specific.

Is there a way to reference the anchor label for the desired section?

I am missing it in the FAQs.

thanks

---

From: Julian Reschke <[email-masked]>
Date: Mon, 16 Dec 2019 18:01:12 +0100

> I am missing it in the FAQs.

You set anchor="label" on the section that you want to reference, and
then use <xref target="label"/> in order to reference it.

Best regards, Julian

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 16 Dec 2019 12:01:57 -0500

> I am missing it in the FAQs.

How do you imagine that working? When following the reference while 
reading, this will be looking at the html or txt version of the 
document. Does the html version use the same anchors as the xml version 
does? And in case of txt, the reader can't see the anchors.

	What did you have in mind?
	Paul

---

From: Robert Moskowitz <[email-masked]>
Date: Mon, 16 Dec 2019 12:07:59 -0500

> then use <xref target="label"/> in order to reference it.

I was not clear enough.

Consider:

<xref target="I-D.moskowitz-orchid-cshake" format="default"
     section="4" sectionFormat="of">"Using cSHAKE in ORCHIDs"</xref>

And in moskowitz-orchid-cshake I have:

<section anchor="Decode" numbered="true" toc="default"> <name>ORCHID 
Decoding</name>

I want to use that anchor, "Decode" from the xml, not the section # that 
ended up in the current ver of the draft's txt.

thanks

---

From: Julian Reschke <[email-masked]>
Date: Mon, 16 Dec 2019 18:18:23 +0100

On 16.12.2019 18:07, Robert Moskowitz wrote:
> ...

That's not currently possible in xml2rfc.

It *is* possible, if you run a preprocessor on the XML (such as the one
coming with rfc2629.xslt, but that in turn currently only supports a
subset of v3).

Best regards, Julian

---

From: Robert Moskowitz <[email-masked]>
Date: Mon, 16 Dec 2019 12:30:11 -0500

> coming with rfc2629.xslt, but that in turn currently only supports a

I kind of thought this would be the case.  You basically have to run 
xml2rfc to get the section # assigned to the section.

I remember times past struggling to kept all the sec # aligned in a set 
of cross-referenced drafts.

So put this into a feature request :)

---

From: Julian Reschke <[email-masked]>
Date: Mon, 16 Dec 2019 18:40:35 +0100

> So put this into a feature request :)

Well, my code *does* have that feature (as extension), because we needed
that for the HTTP specs...

We briefly discussed that for v3, but decided it to be out of scope back
then. (But then we also thought v3 would be put into production years
ago...).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 16 Dec 2019 18:53:14 +0100

On Dec 16, 2019, at 17:47, Robert Moskowitz <[email-masked]> wrote:
> 
> I see examples of section=5 for RFCs, but for IDs, the section number will tend to be version specific.
> 

To translate the anchor label into a section number (or a section title), the referencing spec would need access to the referenced spec.  To generate a standalone document, this could be implemented by including the referenced spec into the referencing document, or more reasonably just an abstraction of it that leaves only the information needed for that translation (a “side file” in traditional formatter jargon).

I believe the best way to handle this would be to keep extracted “side files” of this kind for all specs (drafts and RFCs), ready for inclusion just like we include the extracted reference information itself into a referencing spec.  This does not just require changes to xml2rfc and related tools, but also to the infrastructure we use to keep copies of specs and their reference extractions.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 16 Dec 2019 19:04:16 +0100

> I believe the best way to handle this would be to keep extracted “side files” of this kind for all specs (drafts and RFCs), ready for inclusion just like we include the extracted reference informat…

That wouldn't work well for specs that are revised and published in sync
(such as QUIC and http-core).

The simplest possible approach for *that* use case is an extension of
<reference> that provides the location of the XML source; the formatter
can then read the source and derive the section number.

Best regards, Julian

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 16 Dec 2019 13:26:12 -0500

> can then read the source and derive the section number.

This will only work when the reference is bound to a single immutable 
version of the document. It won't work for a wildcard reference to the 
"latest" version.

	Thanks,
	Paul

---

From: Robert Moskowitz <[email-masked]>
Date: Mon, 16 Dec 2019 13:59:37 -0500

> version of the document. It won't work for a wildcard reference to the 

I disagree.  that is often EXACTLY what you want.  I don't control 
draft-x, but I need to reference a specific section in my draft-y. The 
author(s) of draft-x have sent me the anchor they will maintain for the 
section I am concerned with.  I will always want my draft-y to point to 
the current section in the current draft.

They could have published 5 min before me, and I will want my section 
reference to match.

Been there.  Done that.

---

From: Julian Reschke <[email-masked]>
Date: Mon, 16 Dec 2019 20:02:49 +0100

> version of the document. It won't work for a wildcard reference to the

Well, it *does* work for the "latest" version, if you have the URI of
the "latest" XML.

Believe me, we (the HTTPBIS WG) have been doing this for a decade.

Best regards, Julian

---

From: Paul Kyzivat <[email-masked]>
Date: Mon, 16 Dec 2019 15:26:24 -0500

> Believe me, we (the HTTPBIS WG) have been doing this for a decade.

I don't see how you are going to make that work.

Suppose we have draft-foo that contains a reference to section-xyz of 
draft-bar. Now at the time draft-foo-00.xml is submitted the most recent 
version of draft-bar is -00 and in that section-xyz is Section 6. When 
it is posted, draft-foo-00.txt and draft-foo-00.html are generated.

Later, draft-bar-01 is posted in which section-xyz is Section 8. 
Subsequently, what will the reference look like when I view 
draft-foo-00.txt and draft-foo-00.html in a browser? Note that these 
have not been regenerated from the xml since the original submission.

	Thanks,
	Paul

---

From: Julian Reschke <[email-masked]>
Date: Tue, 17 Dec 2019 06:58:06 +0100

> have not been regenerated from the xml since the original submission.

IDs and RFCs, once published, are immutable.

A *published* draft usually should not reference parts of editor's copy
of another draft.

What *does* work (and that's what I was referring to) is having
auto-computed references between drafts that are published in sync, such
as currently the three http-core specs.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 17 Dec 2019 07:17:19 +0100

> as currently the three http-core specs.

As usual, there is confusion between the authoring language and the publishing language.

The desired feature here is to have references to other documents in the authoring language that update automatically.  

The time of commit is the time of publishing.  In the publishing language, there must not be references to information that changes, such as an unnumbered reference to an I-D.  Converting to plain text previously made sure that the commitment process happens.  Now, the conversion from the authoring language to the publishing language needs to be done by separate tool, which we tend to call “prep tool”.

Julian, you are familiar with doing this between drafts published at the same time, but synchronized publishing is not at all a prerequisite to references (bibxml, section numbers/names) that auto-update.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Tue, 17 Dec 2019 08:17:15 +0100

> Julian, you are familiar with doing this between drafts published at the same time, but synchronized publishing is not at all a prerequisite to references (bibxml, section numbers/names) that auto-…

Yes, but.

In the case of independant submission times and for draft-foo
referencing draft-bar, you need to freeze the reference to draft-bar whe
  publishing draft-foo.

That is something that needs to be done at submission time, and it *can*
be automated. We don't *need* vocabulary support for that (but of course
we can discuss what could be done to simplify this).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 17 Dec 2019 08:29:15 +0100

> Believe me, we (the HTTPBIS WG) have been doing this for a decade.

FWIW; I just checked whether I have documentation for that, and I do so
indeed:

<https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#ext.element.source>

Best regards, Julian