Subject: [rfc-i] Fwd: New Version Notification for draft-flanagan-7322bis-00.txt

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Fri, 10 Mar 2017 12:27:00 -0800

FYI, I am kicking off the refresh of the RFC Style Guide. Significant
changes include:

1. Style guidance for figures/images

2. Inclusion of the Musts and several of the Recommendations from the
web portion of the style guide
(https://www.rfc-editor.org/styleguide/part2/)
- guidance on RFCs as Compounds
- adding DOI numbers to references
- noting where the Index should go (if an RFC actually has one)
- guidance on in-text citations
- encouraging the use of HTTPS over HTTP
- specific note on IEEE references
- guidance on referenceing individual email messages on mailing lists
- removing the two spaces after a period requirement
- removing the "we will remove empty IANA considerations" guidance

3. Changing the reference format to include stream info

This is just a first pass. Additional changes being thought about (but
which aren't in the doc yet, assuming they get added at all) include:
- BibTex citation format
- more citation tag guidance, particularly around using non-ASCII
characters in a citation
- header/footer guidance given the new format changes
- guidance on the use of annotations in references
- adding back the Protocol Data Definitions template

If you have particular opinions on any of the above items, please start
a thread and discuss.

-Heather

-------- Forwarded Message --------
Subject: 	New Version Notification for draft-flanagan-7322bis-00.txt
Date: 	Fri, 10 Mar 2017 09:28:19 -0800
From: 	[email-masked]
To: 	RFC Editor <[email-masked]>, Heather Flanagan
<[email-masked]>, Sandy Ginoza <[email-masked]>

A new version of I-D, draft-flanagan-7322bis-00.txt
has been successfully submitted by Heather Flanagan and posted to the
IETF repository.

Name:		draft-flanagan-7322bis
Revision:	00
Title:		RFC Style Guide
Document date:	2017-03-10
Group:		Individual Submission
Pages:		26
URL:            https://www.ietf.org/internet-drafts/draft-flanagan-7322bis-00.txt
Status:         https://datatracker.ietf.org/doc/draft-flanagan-7322bis/
Htmlized:       https://tools.ietf.org/html/draft-flanagan-7322bis-00

Abstract:
   This document describes the fundamental and unique style conventions
   and editorial policies currently in use for the RFC Series.  It
   captures the RFC Editor's basic requirements and offers guidance
   regarding the style and structure of an RFC.  Additional guidance is
   captured on a website that reflects the experimental nature of that
   guidance and prepares it for future inclusion in the RFC Style Guide.
   This document obsoletes RFC 7322, "RFC Style Guide".

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

The IETF Secretariat

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

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 14:55:16 +0100

<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.5>:

> 4.8.6.5.  Referencing Errata
>
>    The following format is required when a reference to an erratum
>    report is necessary:
>
>    [ErrNumber]  RFC Errata, Erratum ID number, RFC number, <URI>.
>
>    [Err1912]  RFC Errata, Erratum ID 1912, RFC 2978, xxx.

In V3, we'd format that as:

> <reference anchor="Err1912" quoteTitle="false" target="xxx">
>   <front>
>     <title>Errata ID 1912</title>
>     <author><organization>RFC Errata</organization></author>
>   </front>
>   <seriesInfo name="RFC" value="2978"/>
> </reference>

Observations:

1) That makes it look like this references actually RFC 2978, so the 
seriesInfo element is very misleading.

2) No date is specified.

Proposal:

<reference anchor="Err1912" quoteTitle="false" 
target="https://www.rfc-editor.org/errata_search.php?eid=1912">
   <front>
     <title>RFC 2978 Erratum 1912</title>
     <author><organization>RFC Errata</organization></author>
   </front>
   <seriesInfo name="RFC Errata" value="1912"/>
   <date year="2009" month="October"/>
</reference>

Giving:

[Err1912]  RFC Errata, RFC 2978 Erratum 1912, RFC Errata 1912, October
            2009, <https://www.rfc-editor.or/errata_search.php?eid=1912>

a) This make seriesInfo actually meaningful.

b) The URI of course should be aligned with what the future format is; 
for instance <https://www.rfc-editor.org/errata/1912>.

c) 
<https://greenbytes.de/tech/webdav/rfc7991.html#element.reference.attribute.quoteTitle> 
allows us to have an unquoted title, but I'd like to question whether we 
*really* need a special case here.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 15:05:06 +0100

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

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 15:20:54 +0100

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

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 15:37:12 +0100

<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.4>:

> 4.8.6.4.  Referencing Internet-Drafts
>
>    References to Internet-Drafts may only appear as informative
>    references.  Given that several revisions of an I-D may be produced
>    in a short time frame, references must include the posting date
>    (month and year), the full Internet-Draft file name (including the
>    version number), and the phrase "Work in Progress".  Authors may
>    reference multiple versions of an I-D.  If the referenced I-D was
>    also later published as an RFC, then that RFC must also be listed.
>
>    [SYMBOLIC-TAG]  Last name, First initial., Ed. (if applicable) and
>    First initial.  Last name, Ed. (if applicable), "I-D Title", Work in
>    Progress, draft-string-NN, Month Year.
>
>    Example:
>
>    [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide", Work in
>    Progress, draft-flanagan-style-01, June 2013.

That's the same as in RFC 7322, but doesn't reflect what we actually do:

 > [RFC-STYLE] Flanagan, H. and S.  Ginoza, "RFC Style Guide",
 > draft-flanagan-style-01 (work in progress), June 2013.

If you're serious about that, you should open a change request for xml2rfc.

(FWIW, I don't see how the format proposed here is better than the one 
we've been using for ages).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 16:04:09 +0100

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

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 16:35:20 +0100

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

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

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

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 16:38:20 +0100

...furthermore:

<https://tools.ietf.org/html/draft-flanagan-7322bis-00#section-4.8.6.4>:

>    (...)  If the referenced I-D was

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?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 11 Mar 2017 16:43:39 +0100

> formatting error caused by xml2rfc not processing the <eref> in the

and 3): what exactly should go in for the independent stream?

Best regards, Julian

---

From: Martin J. Dürst <[email-masked]>
Date: Sun, 12 Mar 2017 10:43:49 +0900

On 2017/03/11 23:20, Julian Reschke wrote:
> 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://github.com/rfc-format/draft-iab-xml2rfc-v3-bis>).

Even better, can we just make sure that the index is at the very end of 
the document? That's the case in all good books and other publications I 
know. The reason for this is very clear: If one wants to find something 
in the document, one goes to the index. But that means one has to find 
the index first. So the index has to be at a place where it's easy to 
find, and the end of the document assures that. That in no way applies 
to any of the appendices.

Regards,   Martin.