Subject: Re: [rfc-i] Referencing Emails

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 13 Jun 2017 13:43:52 -0700

On 3/11/17 6:05 AM, Julian Reschke wrote:
> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.7>:
> 
>> 4.8.6.7.  Referencing Email on Mailing Lists
>>
>>    When referencing emails to mailing lists, the template provided here
>>    should be used:
>>
>>       [reftag] Sender, A., "Subject: Subject line", message to the
>>
>>       listname mailing list, DD Month YYYY, <URL >.
> 
> Including the day of month in a reference is something we haven't done
> before, and which xml2rc won't do in references by default.
> 
> Given that we already have <reference>s that contain a day-of-month (for
> internet drafts), is your suggestion to have this in ID references as
> well? (that would at least be consistent, and consistency is good)
> 

Internet Draft references are styled after RFC references, which do not
include a specific day of publication. I think email is a very different
beast, and having a date specified helps the reader find the correct
message. We're trying to being consistent in like-to-like things.

I understand this may require a feature request for the next xml2rfc.

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

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 13 Jun 2017 13:44:55 -0700

On 3/11/17 6:20 AM, Julian Reschke wrote:
> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.10>:
> 
>> 4.10.  Index
>>
>>    If included, an index appears directly after any appendices and
>>    before the Acknowledgements (if any).  Where applicable, it appears
>>    before the "IAB Members at the Time of Approval" section.
> 
> From an xml2rfc point of view, that's hard to implement, as "IAB Members
> at the Time of Approval" and "Acknowledgements" are regular appendices
> that happen to be unnumbered (using
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.section.attribute.numbered>).
> 
> 
> Can we generalize this to: "it appears before any unnumbered appendix,
> such as..."? Otherwise we'll need to come up with new markup to define
> where to place the index (in which case you should raise an issue at
> <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis>).
> 

What I would like to see is the index as the second to last thing; I
think Author's Address should be last. I'm assuming, however, that will
result in the same problem re: unnumbered appendixes?

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 13 Jun 2017 13:49:37 -0700

On 3/11/17 7:04 AM, Julian Reschke wrote:
> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.2>:
> 
>>    [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core,"
>>    IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, http://www.rfc-
>>    editor.org/info/rfc3080 .
> 
> I see two chaanges from RFC 7322 here:
> 
> 1) The addition of the stream name (which I believe is a good change).
> In V3, this could be implemented using (a)
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.refcontent> or
> (b) using
> <https://greenbytes.de/tech/webdav/rfc7991.html#element.seriesInfo.attribute.stream>:
> 
> 
> a) would look like:
> 
> <reference  anchor='RFC3080'
> target='http://www.rfc-editor.org/info/rfc3080'>
>   <front>
>     <title>The Blocks Extensible Exchange Protocol Core</title>
>     <author initials='M.' surname='Rose' fullname='M. Rose'/>
>     <date year='2001' month='March' />
>   </front>
>   <refcontent>IETF</refconfent>
>   <seriesInfo name='RFC' value='3080'/>
>   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
> </reference>
> 
> b) would look like:
> 
> <reference  anchor='RFC3080'
> target='http://www.rfc-editor.org/info/rfc3080'>
>   <front>
>     <title>The Blocks Extensible Exchange Protocol Core</title>
>     <author initials='M.' surname='Rose' fullname='M. Rose'/>
>     <date year='2001' month='March' />
>   </front>
>   <seriesInfo name='RFC' value='3080' stream='IETF'/>
>   <seriesInfo name='DOI' value='10.17487/RFC3080'/>
> </reference>
> 
> Both format require changes to the citations library.
> 
> Format (b) has the drawback of being ambiguous, because multiple
> seriesInfo elements might carry conflicting information. We'd also have
> to define the special cases, both for the vocabulary (what if a W3C
> document says stream="IETF"???) and the HTML spec.
> 
> 2) The URI appears without angle brackets. I'll guess that's a
> formatting error caused by xml2rfc not processing the <eref> in the
> source as intended.
> 

We can't use submissionType because it's not allowed in <reference>?

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 13 Jun 2017 13:54:45 -0700

On 3/11/17 7:35 AM, Julian Reschke wrote:
> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.3>:
> 
>>    For an STD or BCP that contains two or more RFCs:
>>
>>    [STDXXX]  Last name, First initial., Ed. (if applicable), "RFC
>>    Title", Stream, Sub-series number, RFC number, DOI, Date of
>>    publication.
>>
>>             Last name, First initial., Ed. (if applicable)
>>             and First initial. Last name, Ed. (if applicable),
>>             "RFC Title", Stream, Sub-series number, RFC number, DOI,
>>             Date of publication.
>>
>>             <http://www.rfc-editor.org/info/std#>
>>
>>    Example:
>>
>>    [STD13]  Mockapetris, P., "Domain names - concepts and facilities",
>>    STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987.
>>
>>      Mockapetris, P., "Domain names - implementation and
>>      specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
>>      November 1987.
>>
>>             <http://www.rfc-editor.org/info/std13>
> 
> (1) It seems the formatting is broken? Is the first entry really
> supposed to be different from the second one?

Yes, the formatting is broken. Subseries references have long been a
pain to implement; they're still not right.

> 
> (2) Why do the individual entries not have a link to
> <http://www.rfc-editor.org/info/rfc#>?

Because if someone is referring to the subseries, then they should go to
the subseries info page for the full list of RFCs and errata associated
with that document set.

> 
> (3) What if the spec prose actually wants to refer to one of the
> documents in the document set?

They they shouldn't refer to the subseries; they should just reference
the individual RFC. If they want to do both (reference the subseries and
later specifically reference an RFC within that subseries) then I think
we're going to have a discussion with the author to figure out what
exactly they are trying to do. Are they trying to point someone to
whatever the current standard or best practice is, or are they trying to
point to a snapshot in time? Both are perfectly reasonable things to do,
and we'd adjust the references accordingly.

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 13 Jun 2017 14:02:29 -0700

On 3/11/17 7:38 AM, Julian Reschke wrote:
> ...furthermore:
> 
> <https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.4>:
> 
>>    (...)  If the referenced I-D was
>>    also later published as an RFC, then that RFC must also be listed.
> 
> There are cases where this doesn't make a lot of sense - if one cites a
> specific historic Internet Draft because something that was later
> removed or changed, why would it be relevant whether a later draft was
> subsequently published as RFC?

I can see a situation, in a purely historic context, where this might be
unnecessary. I can see many more situations where having the information
that an I-D became an RFC, and the fact that material was removed before
approval to publish means that the material should be considered
carefully in a larger context, is important. I think it's more likely to
have the latter situation than the former, and so the guidance makes sense.

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 13 Jun 2017 14:03:34 -0700

On 3/11/17 7:43 AM, Julian Reschke wrote:
> On 2017-03-11 16:04, Julian Reschke wrote:
> and 3): what exactly should go in for the independent stream?
> 
> 

"independent" (the same thing we have in submissionType)

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Wed, 14 Jun 2017 08:48:31 +0200

> the subseries info page for the full list of RFCs and errata associated

This creates a special case for these entries, which I believe is a bad 
thing.

> and we'd adjust the references accordingly.

Which doesn't answer the case what to do when both is happening. Leaving 
this undefined until it happens is just asking for trouble.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 14 Jun 2017 08:50:24 +0200

> We can't use submissionType because it's not allowed in <reference>?

Correct.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 14 Jun 2017 08:51:35 +0200

> have the latter situation than the former, and so the guidance makes sense.

Is it "guidance" or a requirement? In the former case, please avoid the 
term "must".

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 14 Jun 2017 08:57:31 +0200

> I understand this may require a feature request for the next xml2rfc.

Actually, what's *more* helpful to the reader would be an archive URL 
(and potentially the mid).

That said, is there any proposal to use the day in month in other 
references as well? For instance, W3C specs do have it in their 
boilerplate, so it's not clear why we wouldn't include that as well...

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 14 Jun 2017 10:37:04 +0200

On Jun 13, 2017, at 23:02, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> unnecessary. 

(Ceterum censeo:)

I believe it would be a good thing to clearly identify “historical”(*) references (as in: here you can find out how this document came to be the way it is) as a separate class from other “informative” (as in: here is more information that helps in processing the technical content of this document) ones.

The rule being discussed would then apply to informative, not to historical, references.

Grüße, Carsten

(*) “historical" as in documented, archival, chronicled, not “historic" as in significant, notable, momentous, consequential, memorable, unforgettable, remarkable; famous, famed, celebrated, renowned, legendary; landmark, sensational, groundbreaking, epoch-making, earth-shattering.

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 15 Jun 2017 12:03:26 +1200

> The rule being discussed would then apply to informative, not to historical, references.

This triggers one of my hobby-horses, I'm afraid.

If I refer to an I-D because it's useful reading but not yet published, I'm happy with it being tagged as "Work in progress". A smart reader may even have the idea to look for a corresponding RFC.

If I refer to an I-D because it has historical value, I would prefer it to be tagged as "Unpublished draft" and have an exact version number (and date). Calling it "Work in progress" is either inappropriate or simply untrue.

Today we have no metadata to separate the two cases.

   Brian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 15 Jun 2017 10:37:34 +0200

On 2017-06-15 02:03, Brian E Carpenter wrote:
>...
> ...

+1

Best regard, Julian

---

From: Bob Hinden <[email-masked]>
Date: Thu, 15 Jun 2017 11:38:48 -0700

> On Jun 15, 2017, at 1:37 AM, Julian Reschke <[email-masked]> wrote:
> 

I tend to agree as well.  Though I am not sure “unpublished draft” is exactly right since the draft is available online.  We treat Internet Drafts as temporary, and at the same time permanent.  Starting to seem more like the later.

Why don’t we include a link to the Internet Draft in the reference like we do for RFCs?

Thanks,
Bob

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:06:47 -0700

On 6/13/17 11:48 PM, Julian Reschke wrote:
> This creates a special case for these entries, which I believe is a
> bad thing.

I don't think it is a special case, per se. I think this is the case of
how to handle sub-series. They are a slightly different beast than just
straight RFCs.

> Which doesn't answer the case what to do when both is happening.
> Leaving this undefined until it happens is just asking for trouble.

So, you're asking about when someone wants to refer to the current
documents in the subseries, AND refer to a specific RFC that happens to
be in the subseries at the time of publication? I don't see anything
preventing that, though it likely will result in a conversation between
the authors and RPC to make sure the intent is clear.

-HEather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:07:32 -0700

>> We can't use submissionType because it's not allowed in <reference>?

Can we change the vocabulary to allow that? What would that break?

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:11:45 -0700

> (and potentially the mid).

I'm not sure if you and I are thinking the same thing when it comes to
an archive URL. I think of services like perma.cc. Could you explain
further what you're thinking here?

> boilerplate, so it's not clear why we wouldn't include that as well...

At this point in time, no, we don't have a proposal for that. To be
honest, I need to research a bit more of the history as to why we don't
include the full date. The only RFCs that use the full date are April 1
RFCs.

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:16:21 -0700

> Why don’t we include a link to the Internet Draft in the reference like we do for RFCs?

Historically, it's to enforce the face that I-Ds are not equal to RFCs,
and because I-D URLs were ephemeral (since I-Ds would disappear after
six months). The latter is no longer true. How do you feel about the former?

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:19:10 -0700

> Today we have no metadata to separate the two cases.

Who would make the call as to whether an I-D is a work in progress or a
[stale|historic|overtaken by events|your favorite term here] I-D? It's
not a simple case of time, and the author of the I-D being referenced
might have a difference of opinion than the author doing the referencing.

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Fri, 16 Jun 2017 20:24:01 +0200

> how to handle sub-series. They are a slightly different beast than just

In the optimal case, we can define something that is not restricted to 
IETF document series...

> the authors and RPC to make sure the intent is clear.

Right now, it will fail because the anchor elements would be in conflict.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 16 Jun 2017 20:25:00 +0200

> Can we change the vocabulary to allow that? What would that break?

I don't think anything would break. It just needs to be added.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 16 Jun 2017 20:31:12 +0200

> further what you're thinking here?

Mailing list archives that assign stable URIs to mails. Example: 
http://www.w3.org/mid/[email-masked]

> include the full date. The only RFCs that use the full date are April 1

Interesting. xml2rfc is unlikely to produce this correctly, unless it 
knows how to identify an April 1st RFC...

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 16 Jun 2017 20:33:14 +0200

> might have a difference of opinion than the author doing the referencing.

There'll be edge cases, right. But if an ID hasn't been updated in 
years, it's likely abandoned, right?

---

From: Jim Schaad <[email-masked]>
Date: Fri, 16 Jun 2017 11:40:44 -0700

-----Original Message-----
From: rfc-interest [mailto:[email-masked]] On Behalf Of Heather Flanagan (RFC Series Editor)
Sent: Friday, June 16, 2017 11:19 AM
To: [email-masked]
Subject: Re: [rfc-i] Referencing Internet Drafts

On 6/14/17 5:03 PM, Brian E Carpenter wrote:
>>> I can see a situation, in a purely historic context, where this 
>>> might be unnecessary.
>>
>> (Ceterum censeo:)
>>

Who would make the call as to whether an I-D is a work in progress or a [stale|historic|overtaken by events|your favorite term here] I-D? It's not a simple case of time, and the author of the I-D being referenced might have a difference of opinion than the author doing the referencing.

[JLS] However, there are some easy cases.  For example any document which has had a replacement document is definitely no longer a WIP.

Jim

-Heather

---

From: Paul Kyzivat <[email-masked]>
Date: Fri, 16 Jun 2017 14:42:56 -0400

> years, it's likely abandoned, right?

Isn't it sufficient to define that an ID that is the most recent version 
and hasn't expired is a work in progress, and that others are historic?

	Thanks,
	Paul

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:43:02 -0700

> years, it's likely abandoned, right?

Almost certainly. But I think this whole discussion is a bit of an edge
case in and of itself. It's rare that authors point to draft that old in
current docs. I'm not saying it isn't done, but it is rare. So, if we're
going to add terms here, we may as well consider the whole scenario.

-Heather

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 11:54:06 -0700

> Right now, it will fail because the anchor elements would be in conflict.

How? The anchor element can (should!) be unique, differentiating between
a reference to STD### versus a reference to RFC####.

(I hate that feeling that I must be missing something obvious.)

-Heather

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 16 Jun 2017 21:07:52 +0200

On Jun 16, 2017, at 20:31, Julian Reschke <[email-masked]> wrote:
> 
> Mailing list archives that assign stable URIs to mails. Example: http://www.w3.org/mid/[email-masked]

(Or any IETF mailing list, e.g.:
https://mailarchive.ietf.org/arch/msg/xml2rfc/6pQr_ZWZt42w6W9UDOS2WTTMkSo
)

Grüße, Carsten

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 12:13:01 -0700

> and hasn't expired is a work in progress, and that others are historic?

I don't think it's quite that tidy. For example, there are drafts that
are expired but which are in one of the stream manager's queue for
consideration (e.g.,
https://datatracker.ietf.org/doc/draft-young-entity-category/).

There's also a certain consideration about how useful it is to make this
distinction when someone reads the RFC referencing these I-Ds in a year;
all the I-Ds may be historic, or may be revised, or may be replaced, or
a mix of all the above. Unless the author of the RFC doing the
referencing is careful to explain the context in which he or she is
referencing the I-D (which they should do regardless) I'm not sure we're
helping the reader with an "the I-D being referenced was older than six
months at the time this RFC was published".

-Heather

---

From: Bob Hinden <[email-masked]>
Date: Fri, 16 Jun 2017 12:37:30 -0700

Heather,

> On Jun 16, 2017, at 11:16 AM, Heather Flanagan (RFC Series Editor) <[email-masked]> wrote:
> 

Certainly I-Ds are not equal to RFCs, though there are a bunch of sub cases depending on if the ID is just an individual submission w/ no review, an active w.g. document, or approved by a stream for publication.  I conclude that calling them “work in progress” may or may not be correct when an RFC is published with a reference to an ID, and certainly not true 10 years later.

I don’t think we want to have labels for each stage of an IDs life because it changes over time.  Perhaps calling them something like “working draft” or similar might be better than “work in progress”.  It doesn’t imply it is changing.

Since they don’t appear to be ephemeral any longer, including a link in the reference might be useful.

Bob

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 16 Jun 2017 12:49:39 -0700

> I don’t think we want to have labels for each stage of an IDs life because it changes over time.  Perhaps calling them something like “working draft” or similar might be better than “work in progre…

Process question: Does this suggest we need to do something special to
update RFC 2026 (which is where the "Work in Progress" term for I-Ds
comes from)? (See Section 2.2).

> Since they don’t appear to be ephemeral any longer, including a link in the reference might be useful.

I'm fine with that.

-Heather

---

From: Paul Kyzivat <[email-masked]>
Date: Fri, 16 Jun 2017 16:09:51 -0400

> https://datatracker.ietf.org/doc/draft-young-entity-category/).

*That* is a whole different issue. IMO those should not expire!

> months at the time this RFC was published".

Yeah, guess so.

If change description from "Work in Progress" to "Working Draft" then it 
ages better, and maybe no need to make a distinction for historic.

	Thanks,
	Paul

---

From: Julian Reschke <[email-masked]>
Date: Fri, 16 Jun 2017 22:22:03 +0200

> (I hate that feeling that I must be missing something obvious.)

If we follow the syntax defined in 
<https://www.greenbytes.de/tech/webdav/rfc7991.html#element.referencegroup>, 
then yes, we might have duplicate anchors.

Best regards, Julian

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 17 Jun 2017 08:49:11 +1200

> ages better, and maybe no need to make a distinction for historic.

Yes, that would work, I think. Heather is correct that this issue is
rare, and the distinction is a judgment call. But it disturbs me (mildly)
that the phrase "Work in Progress" is occasionally used when it's
manifestly untrue.

    Brian

---

From: Andrew Sullivan <[email-masked]>
Date: Fri, 16 Jun 2017 16:51:27 -0400

> that the phrase "Work in Progress" is occasionally used when it's

It isn't really.  The document in question was in progress when work
halted.  There's no way to know whether it'll ever be picked up again.

I don't really care about this, but I sort of hate opening important
procedural documents needlessly.

A

-- 
Andrew Sullivan
[email-masked]

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 17 Jun 2017 09:50:55 +1200

> procedural documents needlessly.

Agreed. There are many more important issues in BCP9 that we leave
untouched. But IMHO the way "Work in Progress" is mentioned in
RFC2026 leaves the RFC Editor discretion to use a different phrase
for purely historical references. If the RFC Editor doesn't want to,
I will not sulk.

    Brian

---

From: Bob Hinden <[email-masked]>
Date: Sun, 18 Jun 2017 12:26:35 +0300

> On Jun 17, 2017, at 12:50 AM, Brian E Carpenter <[email-masked]> wrote:
> 

I think it would be good to file an errata on RFC2026 in any case.  What’s happing now does not match the text in RFC2026.

Bob