Subject: New RFC Editor Style Guide

From: "Adrian Farrel" <[email-masked]>
Date: Mon, 6 Oct 2014 11:34:54 +0100

Hi,

All of you who are editing or authoring Internet-Drafts need to pay attention to
the latest revision of the RFC Editor's style guide. This document sets out the
layout for RFCs and the editorial style points that the RFC Editor will follow.

As before, Internet-Drafts are expected to follow these guidelines so that the
changes between the approved final revision of an Internet-Draft and the
published RFC are as small as possible. This helps both to reduce the cost to
the IETF of the RFC Editor function and (more important) reduces the risk of
technical errors being introduced during late-stage edits. it is also a little
easier for reviewers to read drafts if the material is always presented in a
consistent way.

Look at http://www.rfc-editor.org/rfc/rfc7322.txt and
http://www.rfc-editor.org/styleguide.html

Thanks,
Adrian

---

From: Stewart Bryant <[email-masked]>
Date: Mon, 06 Oct 2014 11:46:36 +0100

On 06/10/2014 11:34, Adrian Farrel wrote:
> _______________________________________________
> routing-discussion mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/routing-discussion
>
Two things that would be really useful to me would be:

1) A succinct description of what do I need to do differently compared 
to what I have done for the past lots of years.

2) Some information on what I need to do because xml2rfc will not do it 
for me.

In other words if I just take the defaults from xmlmind and shove the 
output into xml2rfc and make sure super picky ID-nits has calmed down 
how much of this do I care about?

- Stewart

---

From: Thomas Morin <[email-masked]>
Date: Mon, 06 Oct 2014 13:46:46 +0200

I totally agree with Stewart that the above 2 points would be useful.
I would go as far as to say that not having it will be inefficient and 
result in much duplicated effort.

-Thomas

Stewart Bryant:
> 2) Some information on what I need to do because xml2rfc will not do 
> it for me.
>

---

From: Loa Andersson <[email-masked]>
Date: Tue, 07 Oct 2014 11:07:49 +0200

Folks,

While a description of what is different would be welcome, I don't see
that many things that have any heavy impact on what you need to do.
What I see is

- all IETF RFC need to be referenced as [RFCxxxx], not [1] or
   [pneumonic]
- the statement on the number of authors on the first page is
   stronger and the decision is now with the stream
- all documents will need a table of content (but I guess that xml2rfc
   will fix that)

It would be good if as much as possible could be pushed into xml2rfc.

Much is gained by running the nits toll before posting a draft, I kind
of hope that it will align with the new style guide.

/Loa

-- 

Loa Andersson                        email: [email-masked]
Senior MPLS Expert                          [email-masked]
Huawei Technologies (consultant)     phone: +46 739 81 21 64

---

From: "Adrian Farrel" <[email-masked]>
Date: Tue, 7 Oct 2014 11:17:31 +0100

I agree, but what can you do?

Email to the RFC Editor to ask for help identifying what has changed.
Email to the xml2rfc team to ask them what the status is.

A

> -----Original Message-----
> From: routing-discussion [mailto:[email-masked]] On
Behalf
> Of Thomas Morin
> Sent: 06 October 2014 12:47
> To: [email-masked]
> Subject: Re: New RFC Editor Style Guide
>

---

From: Stewart Bryant <[email-masked]>
Date: Tue, 07 Oct 2014 14:04:54 +0100

Hi

Please can you help us understand what specific actions we need to take 
as a result of the new style guide. Specifically, if I just take the 
defaults from xmlmind and shove the output into xml2rfc and make sure 
super picky ID-nits has calmed down how much of this new style guide do 
we need to care about?

Thanks

Stewart

-------- Original Message --------
Subject: 	RE: New RFC Editor Style Guide
Date: 	Tue, 7 Oct 2014 11:17:31 +0100
From: 	Adrian Farrel <[email-masked]>
Reply-To: 	<[email-masked]>
To: 	'Thomas Morin' <[email-masked]>, 
<[email-masked]>

A

Behalf

---

From: Loa Andersson <[email-masked]>
Date: Tue, 07 Oct 2014 15:08:08 +0200

Folks,

I've spotted one more change that you have to edit into the xml yourself
(depending a bit on the template you use. If you start from
http://tools.ietf.org/tools/templates/draft-davies-template-bare.xml
it is not really updated. I've asked Elwyn to do a couple of minor
updates to align with RFC 7322.

The section the include the RFC 2119 words and reference RFC 2119,
are now normative Section 2.

/Loa

--

---

From: William Atwood <[email-masked]>
Date: Tue, 07 Oct 2014 10:17:41 -0400

Loa,

No, the RFC 2119 text is not "normative Section 2".  Here's the RFC 7322
text:

 This section must appear as part of the body of the memo (as defined
by this document). It must appear as part of, or subsequent to, the
Introduction section.

So, it can be in Section 1 or in a subsequent section.

  Bill

-- 
Dr. J.W. Atwood, Eng.             tel:   +1 (514) 848-2424 x3046
Distinguished Professor Emeritus  fax:   +1 (514) 848-2830
Department of Computer Science
   and Software Engineering
Concordia University EV 3.185     email:[email-masked]
1455 de Maisonneuve Blvd. West    http://users.encs.concordia.ca/~bill
Montreal, Quebec Canada H3G 1M8

---

From: Loa Andersson <[email-masked]>
Date: Wed, 08 Oct 2014 11:44:06 +0200

Bill,

Yes you are right, my bad.

/Loa

--

---

From: t.petch <[email-masked]>
Date: Fri, 10 Oct 2014 17:27:29 +0100

---- Original Message -----
From: "Loa Andersson" <[email-masked]>
To: <[email-masked]>
Sent: Tuesday, October 07, 2014 10:07 AM
> - all documents will need a table of content (but I guess that xml2rfc

Looking some more, and using 'RFC Document Style Dec 2007' as a base
(more recent than any of my copies of rfc2223bis but you may have used
something more recent still), what I think I see is
- a set of  documents has become a cluster as per the RFC-Editor website
- the reference to permissible characters has been removed
- details of page size have been removed, along with details of page
headers and footers
-  punctuation should be within quotes when quoting general text (was
outside)
-  angle brackets strongly recommended around URIs
-  Section titles that are in sentence form will follow typical sentence
capitalization (was title case)
- abbreviations should be expanded upon first use (was must)
- cross references within the body of the text must use section numbers
(was should)
- notes on the use of 'emphasis', 'i.e.', 'e.g.' all removed
- document structure brought in line with current practice
- appendices should be labelled (was numbered or labelled)
- front matter now references RFC5741 for layout
- the stream determines who is author or editor (not just how many
thereof)
- Abstract not limited to 20 lines
- IANA considerations should used TBD1, TBD2 etc not TBA or XXX
- i18n section should be included when appropriate - see BCP18
- references will generally appear in alphameric order of tag
- URIs acceptable (was discouraged)
- reference format defined for errata and other SDO
- authors must have an e-mail address (was just one of several options)
- appendices on
  Additional Data about the Contents of RFC Elements
  Postscript Format Rules
  End-of-Line and End-of-Page
removed

Tom Petch

---

From: RFC Editor <[email-masked]>
Date: Thu, 16 Oct 2014 17:35:44 -0700

Hi Stewart,

For the most part, the RFC Editor will make the needed adjustments to
conform with the new Style Guide: a number of them are still outside
the current ability of xml2rfc.  However, we recommend reviewing the
updated Style Guide because it includes some recommendations (rather
than requirements) that	may have an impact on the authors'
stylistic choices.

Some highlights of formatting items from RFC 7322 that authors can
implement now are:

* placing Acknowledgements and Contributors sections after the
  References section (Section 4)
* including a table of contents in all documents, no matter the length (Section 4.7)
* using angle brackets around URLs (Section 3.3)
* listing the "country short name" in the postal address (if listed) in
  the Authors' Addresses section (Section 4.12)

<http://www.rfc-editor.org/styleguide.html> provides a summary of the
manual fixes the RFC Editor will make during the final stages of
production (just before publication) because xml2rfc does not yet
provide the proper functionality.  It also contains a pointer to the
Web Portion of the Style Guide 
(http://www.rfc-editor.org/rfc-style-guide/part2.html) that highlights
items that have not yet made it into the Style Guide but are helpful
for authors.  

We are creating a list to highlight a number of common updates that
authors may want to make while drafting their document in accordance
with the new Style Guide.  We will let you know when the page is
available online.

Thank you,
RFC Editor/sg

On Tue, Oct 07, 2014 at 02:04:54PM +0100, Stewart Bryant wrote:
> Hi
> 
> Please can you help us understand what specific actions we need to
> take as a result of the new style guide. Specifically, if I just
> take the defaults from xmlmind and shove the output into xml2rfc and
> make sure super picky ID-nits has calmed down how much of this new
> style guide do we need to care about?
> 
> Thanks
> 
> Stewart
>

---

From: Francis Dupont <[email-masked]>
Date: Tue, 21 Oct 2014 00:01:59 +0200

>    the Authors' Addresses section (Section 4.12)

=> I have a concern about this because the "country short name" aka
ISO IS 3166 two letter code is explicitely *not* recommended by the
UPU which has the authority about *postal* addresses (what is recommended
is the full country name in capital letters in the dispatching country
language or an internationally recognized language (i.e., read English)).

Regards

[email-masked]