Subject: [rfc-i] changing [RFC1234] references to [RFC1234-XYZ]

From: Michael Richardson <[email-masked]>
Date: Tue, 13 Aug 2019 11:53:46 -0400

A document I am working on has references to both RFC7951
(JSON encoding of YANG), and RFC7159 (JSON) [now RFC8259 of course].

RFC7951 is an easy typo of RFC7159!

In XML, if I do all my own <references> sections, I could make up anchors
that might help me remember which one I wanted, and make the distinction
more obvious for others. It's one of the xml2rfc FAQs:
    https://xml2rfc.tools.ietf.org/xml2rfcFAQ.html#anchor13

But, since we have the include mechanism, and when using kramdown, even that
part can be short-cutted nicely, this would not be a very scalable thing.

Pretty much all non-trivial documents reference a dozen or more RFCs, all by
numbers. I think that some of this can be quite intimidating to reads new to
that area. (Even after 25 years of IETF work, I doubt I can read a SIP or
OSPF document without looking up every single RFCxxxx number).

I wonder if we should consider including some kind of slug into the []
reference.

So that [RFC8259] becomes [RFC8259-JSON] and [RFC7296] becomes [RFC7296-IKEv2].
That is, do both.  For this to happen I think that we need a few things.

1) a minimum is that the reference.XYZ.files would have to have their anchor=
   changed to include the slug.  But that would be annoying to those who
   didn't know the slug, so we really need an alternate anchor2= or
   something which would also be consulted.

2) we'd want to insert the "slug" part into the XML for new documents.
   The datatracker should probably know this on a per-document basis, and
   defaulting it to the WG name is probably a good first approximation.

3) We'd want to be able to reference <xref target="RFC8259-JSON" />, and
   have it find "RFC8259" if there is no slug, possibly warning us if there
   is a slug, and it isn't "JSON".

Maybe none of this is useful to anyone else.

-- 
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        |    IoT architect   [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

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

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 13 Aug 2019 18:04:00 +0200

> So that [RFC8259] becomes [RFC8259-JSON] and [RFC7296] becomes [RFC7296-IKEv2].

normative:
  RFC8259-JSON: RFC8259
  RFC7296-IKEv2: RFC7296

Done.

(I’m not sure I’m lining up to adopt this scheme, but at least it is trivial to use in kramdown-rfc.)

Grüße, Carsten

PS.:  If the references to {{RFC8259-JSON}} become tedious, this is a way to simplify it a bit in the text for a little bit more complexity in the YAML:

  RFC7296-IKEv2:
    =: RFC7296
    -: ikev2

You now can reference like … {{-ikev2}} … (note the leading dash, which activates the indirection).

Grüße, Carsten

---

From: Jim Schaad <[email-masked]>
Date: Tue, 13 Aug 2019 09:22:18 -0700

Are you looking for a string to type in the reference or just the displayed
output?  A method of changing the string displayed between the brackets has
been incorporated into the v3 vocabulary with 

<displayreference target="RFC7951" to="YANG-JSON"/>
<displayreference target="RFC7152" to="JSON"/>

There is not currently an easy way to change the target/anchor pair.

Jim

-----Original Message-----
From: rfc-interest <[email-masked]> On Behalf Of
Michael Richardson
Sent: Tuesday, August 13, 2019 8:54 AM
To: rfc-interest <[email-masked]>
Subject: [rfc-i] changing [RFC1234] references to [RFC1234-XYZ]

A document I am working on has references to both RFC7951 (JSON encoding of
YANG), and RFC7159 (JSON) [now RFC8259 of course].

So that [RFC8259] becomes [RFC8259-JSON] and [RFC7296] becomes
[RFC7296-IKEv2].
That is, do both.  For this to happen I think that we need a few things.

1) a minimum is that the reference.XYZ.files would have to have their
anchor=
   changed to include the slug.  But that would be annoying to those who
   didn't know the slug, so we really need an alternate anchor2= or
   something which would also be consulted.

-- 
]               Never tell me the odds!                 | ipv6 mesh networks
[
]   Michael Richardson, Sandelman Software Works        |    IoT architect
[
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails
[

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 13 Aug 2019 12:23:32 -0400

>     is a slug, and it isn't "JSON".

I would much prefer to have the visible anchor in the text be [JSON] 
rather than [[RFC8259-JSON].

I think the key here is to decouple the visible anchor from the target 
used for reference in the xml.

But if that was all, then every document that uses include for 
references would be forced to use the anchor used when the reference 
file is created. That might not always be desirable. Ideally I would 
like a way to include the definition of a reference but override the 
visible anchor.

	Thanks,
	Paul

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 13 Aug 2019 18:28:44 +0200

On Aug 13, 2019, at 18:23, Paul Kyzivat <[email-masked]> wrote:
> 
> Ideally I would like a way to include the definition of a reference but override the visible anchor.

kramdown-rfc does that for you.

If, for some reason, you want xml2rfc do the including, you have to rely on the server doing it.
Right now, the bibxml servers only can do that for DOI and IANA references; you trigger it by adding an ?anchor= query parameter to the URI.
I think it is on the to-do-list to enable that for other references, too.

Grüße, Carsten

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 13 Aug 2019 13:09:09 -0400

> I think it is on the to-do-list to enable that for other references, too.

I'm unclear about what you are saying it does.

I can already do <xref target="RFC8259">[JSON]</xref>. But that only 
changes the what appears at the point of use, not what appears in the 
reference list. To be useful it needs to change both places.

	Thanks,
	Paul

---

From: Julian Reschke <[email-masked]>
Date: Wed, 14 Aug 2019 00:18:59 +0200

Am 13.08.2019 um 18:23 schrieb Paul Kyzivat:
> ... > But if that was all, then every document that uses include for
> ...

<https://greenbytes.de/tech/webdav/rfc7991.html#element.displayreference>

Best regards, Julian

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 13 Aug 2019 19:56:55 -0400

> <https://greenbytes.de/tech/webdav/rfc7991.html#element.displayreference>

Perfect!

Now I just need to get to a point when using v3 is feasible.

	Thanks,
	Paul

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 14 Aug 2019 10:28:01 +1000

On Wed, Aug 14, 2019, at 02:28, Carsten Bormann wrote:
> Right now, the bibxml servers only can do that for DOI and IANA 
> references; you trigger it by adding an ?anchor= query parameter to the 
> URI.

>From memory of doing the {{?JSON=RFC8159}} thing, kramdown-rfc2629 just rewrites the XML that it gets if ?anchor= isn't supported.

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 14 Aug 2019 09:23:10 +0200

On Aug 14, 2019, at 02:28, Martin Thomson <[email-masked]> wrote:
> From memory of doing the {{?JSON=RFC8159}} thing, kramdown-rfc2629 just rewrites the XML that it gets if ?anchor= isn’t supported.

Yes.  The to-do list item is for those people who want to directly include bibxml information via XML entity references (or the RFCXML PIs created for this); these cannot massage the XML returned from the web service.  The massaging can easily be done by an authoring tool such as kramdown-rfc or when including the bibxml manually.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 14 Aug 2019 15:19:28 +0200

> Now I just need to get to a point when using v3 is feasible.

clean-for-DTD.xslt converts many V3 features to V2, so if a preprocessor
is ok for you, you can use this right now.

Best regards, Julian

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 14 Aug 2019 12:12:22 -0400

> is ok for you, you can use this right now.

My main current work is RFC4566bis. It has been in progress for 12 
years, is a beast, and has already been to the iesg. So it isn't changing!

I'll wait for the next one.

	Thanks,
	Paul

---

From: Michael Richardson <[email-masked]>
Date: Wed, 14 Aug 2019 17:42:23 -0400

> <displayreference target="RFC7152" to="JSON"/>

That's useful, because I don't have to hack the reference.* files.

    > There is not currently an easy way to change the target/anchor pair.

So, my .xml file has to continue to say <xref target="RFC7951" />,
but it will say "YANG-JSON".

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-