Subject: Re: Language editing (was: tails and such)

From: Yaron Sheffer <[email-masked]>
Date: Fri, 03 May 2013 00:40:52 +0300

As a non-native English speaker, but a language pedant nonetheless, I 
can empathize with people who put Discusses on badly written documents.

I suggest that we budget for a number of WG drafts per year (say, 20 
IETF-wide) to go through professional, paid-for heavy-duty editing, with 
these goals in mind:

- Improve the readability of some of published documents, because if a 
document is *really* badly written, even the RFC Editor team will not 
save it.
- Improve the level of review, because people can understand the 
document better if they don't need to dig through incorrect or "strange" 
language.
- Allow more non-native speakers to participate in our primary activity 
(back to our "diversity" discussion).

I would suggest that the editing step should take place just before WG 
Last Call, upon a request by a WG chair and with AD approval.

Thanks,
	Yaron

> Date: Thu, 02 May 2013 21:14:39 +0300
> From: Hannes Tschofenig <[email-masked]>
> To: Jari Arkko <[email-masked]>
> Cc: Pete Resnick <[email-masked]>, IETF list
> 	<[email-masked]>
> Subject: Re: call for ideas: tail-heavy IETF process
> Message-ID: <[email-masked]>
> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>
[...]

>
> PS: I just want to add that I still dislike DISCUSSes that make me
> re-write documents just because an English native speaker believes
> (probably rightfully so) that he knows how to write the text better (or
> at least in a different way). (hint, hint)
>

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Thu, 02 May 2013 15:03:20 -0700

On 05/02/2013 02:40 PM, Yaron Sheffer wrote:
> As a non-native English speaker, but a language pedant nonetheless, I can 
> empathize with people who put Discusses on badly written documents.
> 
> document is *really* badly written, even the RFC Editor team will not save
> it. - Improve the level of review, because people can understand the
> language. - Allow more non-native speakers to participate in our primary
> activity (back to our "diversity" discussion).
> 

An alternative would be to have the RFC-editor doing copyediting of I-Ds for a
fee.  Depending on the cost, I would use such service for my I-Ds.  That would
be good for everybody:  I would spend less time trying to make my text legible
and more making the protocol described in it better.  And because the document
would have been copy-edited by the same people that will publish the RFC,
that's less work at the end.

> 
> Thanks, Yaron
> 
>> Date: Thu, 02 May 2013 21:14:39 +0300 From: Hannes Tschofenig
>> <[email-masked]> To: Jari Arkko <[email-masked]> Cc:
>> Pete Resnick <[email-masked]>, IETF list <[email-masked]> 
>> Subject: Re: call for ideas: tail-heavy IETF process Message-ID:
>> <[email-masked]> Content-Type: text/plain; charset=ISO-8859-1;
>> format=flowed
>> 
> [...]
> 
>> 

- -- 
Marc Petit-Huguenin
Email: [email-masked]
Blog: http://blog.marc.petit-huguenin.org
Profile: http://www.linkedin.com/in/petithug

---

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 02 May 2013 17:13:11 -0600

On 5/2/13 4:03 PM, Marc Petit-Huguenin wrote:
>> As a non-native English speaker, but a language pedant
>> nonetheless, I can empathize with people who put Discusses on
>> badly written documents.
> 
>> I suggest that we budget for a number of WG drafts per year (say,
>> 20 IETF-wide) to go through professional, paid-for heavy-duty
>> editing, with these goals in mind:
> 
>> - Improve the readability of some of published documents, because
>> if a document is *really* badly written, even the RFC Editor team
>> will not save it. - Improve the level of review, because people
>> can understand the document better if they don't need to dig
>> through incorrect or "strange" language. - Allow more non-native
>> speakers to participate in our primary activity (back to our
>> "diversity" discussion).
> 
>> I would suggest that the editing step should take place just
>> before WG Last Call, upon a request by a WG chair and with AD
>> approval.
> 
> An alternative would be to have the RFC-editor doing copyediting of
> I-Ds for a fee.  Depending on the cost, I would use such service
> for my I-Ds.  That would be good for everybody:  I would spend less
> time trying to make my text legible and more making the protocol
> described in it better.  And because the document would have been
> copy-edited by the same people that will publish the RFC, that's
> less work at the end.

Instead of imposing even more work on the RFC Editor team, I suggest
that you find someone in the WG, in your company, in the IETF
community (etc.) to help with the language issues. I did this recently
with a document in one of the WGs where I'm active and it worked quite
well (especially if the document is under source control and you can
just send a patch).

Peter

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 3 May 2013 03:41:04 +0200

On May 3, 2013, at 01:13, Peter Saint-Andre <[email-masked]> wrote:

> source control

I don't think it has been emphasized enough how important that is from a document quality perspective.

More importantly for this discussion, it also somewhat mitigates the document editor as a choking point.

People who aren't aware of it should look at the httpbis github experiment.
The pull request is a powerful model of WG collaboration.

Grüße, Carsten

---

From: Dave Crocker <[email-masked]>
Date: Thu, 02 May 2013 18:47:45 -0700

> well (especially if the document is under source control and you can

+1

This goes beyond the simple-but-expensive matter of having the work done 
by the RFC Editor.

With every opportunity, we should move work to the people who want its 
result.

IETF work that is successful has community support.  The community wants 
it and demonstrates this by working on it.  That can (and I think 
should) include ensuring basic writing quality.

If the community does not have enough interest in the work to write it 
well, it has bigger problems that won't be remedied by more RFC Editor 
effort...

d/

-- 
Dave Crocker
Brandenburg InternetWorking
bbiw.net

---

From: Ted Lemon <[email-masked]>
Date: Fri, 3 May 2013 01:50:31 +0000

> The pull request is a powerful model of WG collaboration.

Several authors in the dhc working group have been doing the same thing, to good effect.

---

From: Ted Lemon <[email-masked]>
Date: Fri, 3 May 2013 01:52:52 +0000

On May 2, 2013, at 9:47 PM, Dave Crocker <[email-masked]> wrote:
> If the community does not have enough interest in the work to write it well, it has bigger problems that won't be remedied by more RFC Editor effort...

Also worth considering is that if a document is hard to read, it is hard to review, and hence gets less review.   This can result in a really anemic WGLC, serious errors caught at the tail end of the process or not at all, or just a document that is not as useful as it could have been.

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Thu, 02 May 2013 19:13:39 -0700

On 05/02/2013 06:41 PM, Carsten Bormann wrote:
> People who aren't aware of it should look at the httpbis github
> experiment. The pull request is a powerful model of WG collaboration.

Friends do not let friends use github.

The pull request in github does not handle rebasing correctly.  The github Web
interface is useless, and you have to use the RESTful API for anything a bit
sophisticated.  I know, I spent 2 months of hell editing
draft-ietf-p2psip-base with this piece of crap.

Gerrit is far better at anything github does.  Unfortunately there is no
public repository supporting Gerrit and that's a shame.  People interested in
trying Gerrit can contact me directly.

- -- 
Marc Petit-Huguenin

---

From: t.p. <[email-masked]>
Date: Fri, 3 May 2013 09:24:39 +0100

----- Original Message -----
From: "Peter Saint-Andre" <[email-masked]>
To: "Marc Petit-Huguenin" <[email-masked]>
Cc: "Yaron Sheffer" <[email-masked]>; <[email-masked]>
Sent: Friday, May 03, 2013 12:13 AM
> well (especially if the document is under source control and you can

Ah, there's the rub.

I have done this on a number of occasions for a variety of people and
editing the text file of an I-D is almost trivial compared to then
incorporating the amendments, some agreed, some debated, some rejected,
into the XML, in doing so introducing the need for further amendments
(problem generates change generates problem generates ... the cycle
beloved of all software developers).

We really do need a tool, the like of which I was using 40 years ago
when writing code, that allows patches to be applied independently and
temporarily to see what it then looks like and if agreed that it looks
good, incorporating them permanently into the source (XML).  Ideally
such a tool would reverse engineer the amended text into XML patches as
well - text is so much easier to work with than XML (or any other markup
language).

Tom Petch

> Peter
>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG/MacGPG2 v2.0.19 (Darwin)
> Comment: GPGTools - http://gpgtools.org
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>
> iQIcBAEBAgAGBQJRgvMHAAoJEOoGpJErxa2p1WkP/Ao11JgbfdPk1+r5psycC4yW
> hc9qCTZeJEuXHHEG5mFLXyuEugkL1LKDjH7TAHql3o28iRYi1P+0LnR4l4Eg27u8
> Rfk8TrQ3pE0EHOiMhtX9b1G718iyQAR6bxjBJhR0Sc6f5Y2x4drqZQd4xwHggNCz
> uKp58+mrEizUBM3V6+JtCJAQj/mOv3HVbbSij8yWWYvJzuOP1nJ+rqEaI/0lBct5
> rkWrefJogtxRHIrwALKmV+BYV99MyDzmm4kwZj+rDzqy/epq77FkqvZUms9EkLZW
> HYLWE9RL/onV+XOLbjkSIvjqjCgKdaS1FpMH6zqYidNN491bLAQacyI0QS9d6dGw
> 9AbDMf1uTxWcfWyB4LrwFFVyA8ZVCWO+1d5up+LSRgfGR/u0WhbyiaJqN0JKy10t
> 0yJ30+4rwsYjtzsOWy1Zggn8bD4uXXdyjbw8X6Ze69A8ChBlIqticIf4mEd12qSO
> E6k8SqtsoX17QmEU8oa7RwNaIbQ59txVju0NHEDlYreBKdHeRrki1SuK5+VrOJAg
> yTqzNkpJskgwFukSfLBiX446c4luXkQ4XoSWT3NdkqxIq2ikpXh3WU2p0WgDTM+G
> EreYmGTQXP9YV2Ieb+nMsj1pNbD0gB5a8CpXWLe859IIu2ga1uCcxo99LqPymNJB
> hmkU2s1OJ2xuR1/d5Anx
> =JEpp
> -----END PGP SIGNATURE-----
>

---

From: TZI <[email-masked]>
Date: Fri, 3 May 2013 10:37:53 +0200

> when writing code, that allows patches to be applied independently

that's what pull requests (or gerrit) are about.

> and

try writing the draft in markdown and using Miek Gieben's or my tool (kramdown-rfc2629) to convert into XML.

it is so much easier to collaborate in markdown...

Grüße, Carsten

---

From: Ted Lemon <[email-masked]>
Date: Fri, 3 May 2013 10:51:53 +0000

> well - text is so much easier to work with than XML (or any other markup

Actually, what I'd like to see is a change approval process, where I can go in and make the edits I want to the document, submit those, and then the document editors can just go down the list of changes approving them or not.   I guess that's not too different from what you said, but with a better UI.

---

From: Scott Brim <[email-masked]>
Date: Fri, 3 May 2013 07:08:42 -0400

On 05/02/2013 02:40 PM, Yaron Sheffer wrote:
> editing

My experience is that unless the editors have some background in
protocols, this takes a surprising amount of effort, explaining it to
them and catching _their_ mistaken assumptions (which can be subtle).
 However,

On 05/02/13 19:13, Peter Saint-Andre allegedly wrote:
> Instead of imposing even more work on the RFC Editor team, I
> suggest that you find someone in the WG, in your company, in the
> IETF community (etc.) to help with the language issues.

... then you have quality control issues, uncertainty who to turn to,
finding someone who not only appears to be good but actually is, etc.

So how about a pool of volunteer editors, aka GEN-AET, with developed
reputations?

---

From: t.p. <[email-masked]>
Date: Fri, 3 May 2013 12:52:36 +0100

---- Original Message -----
From: "TZI" <[email-masked]>
To: "t.p." <[email-masked]>
Cc: "Peter Saint-Andre" <[email-masked]>; "Marc Petit-Huguenin"
<[email-masked]>; "Yaron Sheffer" <[email-masked]>; "ietf"
<[email-masked]>
Sent: Friday, May 03, 2013 9:37 AM
Subject: Re: Language editing

> well - text is so much easier to work with than XML (or any other
markup

try writing the draft in markdown and using Miek Gieben's or my tool
(kramdown-rfc2629) to convert into XML.

<tp>
Right, but the context is that after many years and several rounds of
editing, the I-D is ready for Last Call and someone who may not have
been previously involved in the editing goes through and proposes
enhancements for legibility.  It needs to be an available on the IETF
website tool and easy enough for many to use without much education.

Tom Petch

Grüße, Carsten

---

From: Ralph Droms <[email-masked]>
Date: Fri, 3 May 2013 11:34:48 -0400

On May 2, 2013, at 9:47 PM 5/2/13, Dave Crocker <[email-masked]> wrote:

> This goes beyond the simple-but-expensive matter of having the work done by the RFC Editor.
> 
> With every opportunity, we should move work to the people who want its result.

Dave, I agree with you and you make a very important point, that applies broadly to this conversation.

In particular, it should be the responsibility of the interested parties to engage community support, and it should be the responsibility of the community to put effort into producing a document that meets requirements of basic writing quality.

> 
> IETF work that is successful has community support.  The community wants it and demonstrates this by working on it.  That can (and I think should) include ensuring basic writing quality.

If you'll allow me to dive into process issues and solution engineering briefly, these writing quality issues should be caught well before the document reaches the IESG, in the abstract to ensure that the responsibility (and the work) in producing publishable documents rests with the people who want the document published, and pragmatically because a DISCUSS position of "returned for improvement in writing quality" is at the edge of what can be handled through routine processes.

> If the community does not have enough interest in the work to write it well, it has bigger problems that won't be remedied by more RFC Editor effort...

Yup.

> d/

- Ralph

---

From: [email-masked] (Dale R. Worley)
Date: Fri, 3 May 2013 14:01:56 -0400 (EDT)

> From: Scott Brim <[email-masked]>
> 

I'm told that the CCITT maintains a staff of technical writers.
Certainly, the *writing* in their standards is better.

Dale

---

From: Yaron Sheffer <[email-masked]>
Date: Sat, 04 May 2013 00:22:28 +0300

GEN-ART is a good example, but actual document editing is much more work 
and arguably, less rewarding than a review. So I think this can only 
succeed with professional (=paid) editors.

Thanks,
	Yaron

---

From: Doug Barton <[email-masked]>
Date: Fri, 03 May 2013 14:55:29 -0700

> succeed with professional (=paid) editors.

I'm not sure that's the right conclusion to draw.

In the past I have done extremely detailed copy editing for drafts that 
I was particularly excited about, and wanted to help become RFCs. In 
exactly 1 case that work was warmly received by the author. In all the 
other cases I was met with reactions anywhere from mild disinterest to 
open hostility. In the most extreme example I was told on the list that 
my efforts were not welcome, would not be incorporated into any future 
drafts, and that I should not be trying to do the RFC Editor's job for 
them. I was also accused in private of trying to make the author look 
stupid. As a result of the at best generally apathetic reaction I no 
longer bother doing that kind of detailed copy editing when I review 
drafts.

The conclusion I have drawn (based in part on my own limited experience, 
and in part in seeing the same thing played out in IETF LC) is that as a 
community we do not place sufficient value on high quality work at late 
stages in the process. This is unfortunate on several levels. First, 
while I have the highest respect for the quality of work that the RFC 
Editor does it's not realistic to expect them to catch everything. And 
even if we were willing to fund the next-highest level of 
review/editing, in the best case scenario that kind of work usually 
incurs additional delays due to having to go back and forth with the 
authors, WG, etc. But I think more importantly, by not engaging in a 
better class of refinement at the WG level we miss the opportunity to 
help bring everyone's skill set up to a higher level.

There is a serious caveat to this though, we do not want to generate a 
perception that "only perfect English text need apply." We should make 
clear that _initial_ versions of drafts can and should be submitted even 
if the prose isn't yet publishable. But we should also make clear that 
help will be provided to _get_ the text up to snuff, and we should value 
that goal as an institution.

Doug

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 04 May 2013 10:04:53 +1200

> succeed with professional (=paid) editors.

I think I disagree, if we can find the knack of effective crowd-sourcing.
We do after all have several hundred native English speakers active
in the IETF, which would mean each one would have to volunteer for
less than one draft per year and we'd be done.

I don't know how much experience you have with professional editors.
Apart from the RFC Editor crew, my experience has been "mixed". Somebody
a year or three ago (the last time we had this exact same discussion)
pointed out the differences between copy-editors and technical editors.
One difference is that the latter are much more expensive. Copy-editors
tend to be rule-driven; technical editors are supposed to understand
the material.

    Brian

---

From: joel jaeggli <[email-masked]>
Date: Fri, 03 May 2013 16:59:14 -0700

> less than one draft per year and we'd be done.
Variously as an individual contributor, shepherd and chair I have asked 
for source text so that I could provide large copy edits which the 
authors could then apply at their leisure. I have also asked for 
volunteers to help with heavy edits. IMHO polishing a document for 
consumption is a very useful form of contribution, which doesn't 
necessarily require either deep technical background in the area or 
personal involvement in the draft.
> tend to be rule-driven; technical editors are supposed to understand
Most working group participants already have a deeper background in the 
area and familiarity with the jargon than a copy-editor.

---

From: John C Klensin <[email-masked]>
Date: Sun, 05 May 2013 14:32:19 -0400

--On Saturday, May 04, 2013 10:04 +1200 Brian E Carpenter
<[email-masked]> wrote:

>> GEN-ART is a good example, but actual document editing is
>> much more work and arguably, less rewarding than a review. So
>> I think this can only succeed with professional (=paid)
>> editors.
> 
> I think I disagree, if we can find the knack of effective
> crowd-sourcing. We do after all have several hundred native
> English speakers active in the IETF, which would mean each one
> would have to volunteer for less than one draft per year and
> we'd be done.

And what we have found more times than I care to think about --
and I've found even more times than that when trying to read
undergraduate papers -- is that "native English speaker" does
not imply "ability to write good, clear, coherent technical
English".  In addition, the IETF includes a reasonable number of
people whose first language is not English but whose ability to
write high-quality technical documents in English generally
exceeds that of our typical native speaker.   So my first
concern is that we not start making plans based on the
population of native speakers -- if we are going to find
volunteers to pretend to be technical editors, or assess the
population of such people, we had better base our assumptions on
the right set of skills.

> I don't know how much experience you have with professional
> editors. Apart from the RFC Editor crew, my experience has
> been "mixed". Somebody a year or three ago (the last time we
> had this exact same discussion) pointed out the differences
> between copy-editors and technical editors. One difference is
> that the latter are much more expensive. Copy-editors tend to
> be rule-driven; technical editors are supposed to understand
> the material.

To be a little more precise, technical editors are supposed to
understand the nature of technical documents, to have good
intuitions about what is clear and precise and what isn't, and
so on.  Specific subject-matter expertise is yet another layer
of requirement and something we would be unlikely to find far
outside the relevant WG or Area.  I think the distinction
between copy editors and technical editors is very significant
(and I might have been the one who made the comment to which you
refer).  But one should not confuse that distinction with the
observation that there are probably as large a proportion of
poor editors who can't deal with material that requires some
skill (in either subcategory) in the world as there are poor
engineers who can't competently handle actual systems design
issues.

Having shepherded (and kicked, clawed, and dragged) a number of
documents through the system in the last few years that were
written by people whose engineering and protocol design skills
far exceeded their [English] technical writing skills, I'm less
optimistic about volunteer editing than several others seem to
be.  If a WG has surplus people with good technical editing
skills to pair with authors who may be better about the
technical details or tracking the WG discussions and getting
them into to document, then that is great.  But I have certainly
worked in or chaired WGs when there are no such people to spare
or who will volunteer.  In addition, it is really hard for
someone who cares enough about the subject matter of the WG to
be able to edit or translate a draft into good, clear, technical
English without injecting their own opinions about areas where
the original I-D may be unclear -- perhaps it is even harder
than writing the document with careful attention to WG consensus.

My guess is that we are going to need a mixed strategy that
involves volunteer (and adequately skilled) editors where we can
find them, professional technical editors where necessary (and a
good model for how they get paid), and oversight of the whole
process by the RFC Editor as well as relevant WG Chairs, ADs,
and the IESG.  We are also going to need to be much more clear
about what level of quality we, as a community (not just the
IESG), want and will insist on before a document goes into Last
Call.  

I've always hoped that the standard could be "absolutely clear
about what is being specified, but everything else can be fixed
by the RFC Editor after approval".  But that requirement is more
easily stated that interpreted and used: I've seen text in
documents that I thought were that good nit-picked by the IESG
and edited by large committees and, with other documents, not
fixed (or even made worse) by the RFC Editor.

There are probably no easy and comprehensive solutions or magic
bullets.

   john

---

From: <[email-masked]>
Date: Mon, 6 May 2013 15:10:40 +0100

http://labs.apnic.net/blabs/?p=309

an excellent detective story on badly-written, poorly edited, standards track RFCs leading to interop problems. Enjoy.

Lloyd Wood
http://sat-net.com/L.Wood/

Technical writer and editor, native English speaker, IELTS score of 9.0, vaguely appalled by this discussion.

________________________________________
From: [email-masked] [[email-masked]] On Behalf Of John C Klensin [[email-masked]]
Sent: 05 May 2013 19:32
To: Brian E Carpenter; Yaron Sheffer
Cc: [email-masked]
Subject: Re: Language editing

   john

---

From: [email-masked] (Dale R. Worley)
Date: Mon, 6 May 2013 14:01:00 -0400 (EDT)

> From: Brian E Carpenter <[email-masked]>
> 

In a sense you're right; if we could find sufficient members who are
good at editing technical English and motivate them to do so, then the
problem would be solved.  However, I don't see any of those conditions
becoming true.  As an organization, we don't place much value on
making the *words* of a document clear and correct, and neither do our
employers.  And relatively few engineers can write high-quality
English specifications.

More subtly, our process works against us, because we use technical
contributors as the document editors.  Improving writing is a matter
of zillions of relatively small changes, which is inefficient to do if
the person weilding the pen isn't the person who is working out the
corrections to the majority of the sentences in the document.

Dale

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 07 May 2013 08:23:28 +1200

> an excellent detective story on badly-written, poorly edited, standards track RFCs leading to interop problems. Enjoy.

I don't that is quite right. The problem in this case is not to do
with linguistic quality. It's due to a lack of formal verification
among a set of interacting and cross-area RFCs. (And the problem
is wider, because there are two distinct places in IETF standards
where ABNF for the text representation of IPv6 addresses can be
found.) This is a case where no amount of language editing would
have helped. Actually I used it a couple of months ago in a
discussion with some experts on formal verification, and they rather
liked it as a poster child for the need for formal methods in SDOs.

    Brian

---

From: John C Klensin <[email-masked]>
Date: Mon, 06 May 2013 18:14:03 -0400

--On Tuesday, May 07, 2013 08:23 +1200 Brian E Carpenter
<[email-masked]> wrote:

>> an excellent detective story on badly-written, poorly edited,
>> standards track RFCs leading to interop problems. Enjoy.
> 
> I don't that is quite right. The problem in this case is not
> to do with linguistic quality. It's due to a lack of formal
> verification among a set of interacting and cross-area RFCs.
> (And the problem is wider, because there are two distinct
> places in IETF standards where ABNF for the text
> representation of IPv6 addresses can be found.) This is a case
> where no amount of language editing would have helped.
> Actually I used it a couple of months ago in a discussion with
> some experts on formal verification, and they rather liked it
> as a poster child for the need for formal methods in SDOs.

And that is another oddity and perhaps another lesson.  The
robustness principle was formulated, not just as a general good
idea, but because of the understanding that there was little or
no aspiration in pre-IETF specifications to get every T crossed
and I dotted.   That level of precision is required for formal
verification (about which there are other problems) or formal
testing and certification (about which there are a different set
of other problems).  Not only was Jon aware that we often didn't
go into that level of detail, but there was a case to be made
that we didn't want to because it took too much time to get
after the documents right after the design and specification
were done (please reread that a few times).

Maybe things have changed, but, if one actually believes the
robustness principle, then, in the case Geoff cites, Exchange is
simply non-conforming -- not because the spec prohibits
rejecting on the basis of a fine distinction about IPv6 formats,
but because doing so is unnecessary, inconsistent with the
robustness principle, and, arguably, plain silly.

And that is the other thing we lost when "Proposed Standard"
went from "spec that might contain some problems, lack of
clarity, and less than wonderful writing as long as there were
no known technical defects" to "better get it right because it
is probably the last chance and people are going to build and
ship products on the basis of what it says".

We now have expectations consistent with specs that can be
formally verified and/or tested and that people will interpret
narrowly and a procedural model designed for specs that are much
less formal and complete.

    john

   john

---

From: SM <[email-masked]>
Date: Mon, 06 May 2013 15:08:24 -0700

>with linguistic quality. It's due to a lack of formal verification

Quoting from the detective story:

   "At [censored] we have changed our mail server configuration in the past few
    months, and are now using a mail server from [censored] namely the
    [censored] Server."

There isn't any mention of whether the mail server was tested.

   "Seemingly at random my efforts to send mail just fail."

There would likely be an error code with text providing an 
explanation.  I would probably follow a different debugging 
path.  Anyway, the session showed:

   "EHLO [IPv6:2001:df9::4015:1430:8367:2073:5d0]
    501 5.5.4 Invalid domain name"

This is where I go and read RFC 6409 and I find that:

   "The MSA SHOULD log message errors, especially apparent
    misconfigurations of client software."

And then follow up with RFC 5321 where I find a mention of address 
literals.  I go and read RFC 4291 which is a Draft Standard.  I see 
an update in RFC 5952 which is a Proposed Standard.  As I was told 
that the Internet runs on Proposed Standards that update must be 
right.  I see the following:

   "The recommendation in this section SHOULD be followed by systems
    when generating an address to be represented as text, but all
    implementations MUST accept and be able to handle any legitimate
    [RFC4291] format."

Back to the detective story:

   "The writing if RFC5952 is incredibly sloppy for a Proposed Standard"

I look at the write-up:

  "The 6MAN working group reviewed and discussed this document several
   times. There is a strong consensus to move this forward."

  "This document has been reviewed by key members of the 6MAN working
   group and the chairs."

I look at the IESG evaluation and I see:

  "Language & grammar are rough."

Between you and me, these Area Directors are trouble-makers.  :-)

I verify compliance (2010), RFC 2821, RFC 4409; there isn't any 
mention of the IPv6 specifications mentioned in the detective story.

There are people out there who have to fix problems like this.  There 
are people out there who have to read those specifications and figure 
out where is the head and where is the tail.

Regards,
-sm

---

From: Mark Andrews <[email-masked]>
Date: Tue, 07 May 2013 10:59:10 +1000

> liked it as a poster child for the need for formal methods in SDOs.

Apples mail client is broken [IPv6:2001:df9::4015:1430:8367:2073:5d0]
is not legal according to both RFC 5321 and RFC 2821 which is all
that applies here.  RFC 2821 was consistent with RFC 2373 and the
SMTP literal spec has remained frozen since then which you want
when you are trying to promote long term interoperability.

Now one could update RFC 5321 to accept the above :: instead of a
single :0: but you could never legally send it.

Note for IPv4 [070.0.0.0] is 70.0.0.0 not 56.0.0.0 despite the fact
that many system will take 070.0.0.0 and send to 56.0.0.0. 

Mark
-- 
Mark Andrews, ISC
1 Seymour St., Dundas Valley, NSW 2117, Australia
PHONE: +61 2 9871 4742                 INTERNET: [email-masked]

---

From: John Leslie <[email-masked]>
Date: Mon, 6 May 2013 21:29:24 -0400

Mark Andrews <[email-masked]> wrote:
> that applies here.

   I was until today unaware how strong the feelings are on this
"one-or-more" vs. "two-or-more" issue. I do not expect to change
anybody's mind. :^(

   But I do object to calling that EHLO string "not legal".

   The 5321 reference names RFC 4291 as the source of address syntax
(even if it gives BNF which says "two or more" if you delve deeply
enough).

   RFC 4921 is clear about saying "one or more". The Errata posted
against it claiming it should say "two or more" have been rejected.
It is silly to argue under these conditions that Apple's EHLO string
is "not legal".

   BTW, RFC 5321 still contains the language about
" if the verification fails, the server MUST NOT refuse to accept a
" message on that basis.

so IMHO enforcing any particular interpretation of what an IPv6
address literal should look like is double-plus-ungood.

====

   To the casual observer, it looks as if RFC 4291 relaxed a previous
"two or more" requirement, but there are folks who don't want to
accept that relaxing.

   One can accept the idea that this relaxing has failed, yet still
observe "liberal in what you accept" as trumping it. I truly wish the
folks in the "two or more" camp would do so!

--
John Leslie <[email-masked]>

---

From: Mark Andrews <[email-masked]>
Date: Tue, 07 May 2013 12:18:33 +1000

You missed the point RFC 5321 SMTP clients have to operate
	with RFC 2821 SMTP servers when sending address literal in
	the HELO/EHLO.  Code doesn't magically get updated when the
	spec is updated.  It takes years for changes to trickle
	through.  The code has to be written, then it has to be
	deployed.

	[The who SPF issue is about a WG that is too impatient to
	 wait for the updated code, that has been written, to be
	 deployed.  That will happen as OS's get update / replaced.]

	While RFC 4291 relaxed the address syntax, RFC 5321 didn't
	because to do so would break interoperability.

	RFC 5321's address literals are a subset of RFC 4291's
	permittable address formats.  So there is nothing wrong
	with referencing RFC 4291.

	Mark

---

From: [email-masked]
Date: Mon, 06 May 2013 19:37:23 -0700 (PDT)

>    But I do object to calling that EHLO string "not legal".

It's syntactically illegal according to the ABNF in RFC 5321 itself, which
specifically states:

 IPv6-comp      = [IPv6-hex *5(":" IPv6-hex)] "::"
                  [IPv6-hex *5(":" IPv6-hex)]
                    ; The "::" represents at least 2 16-bit groups of
                  ; zeros.  No more than 6 groups in addition to the
                  ; "::" may be present.

> (even if it gives BNF which says "two or more" if you delve deeply

It may be the source, but the formal syntax specified in the document at hand
has to be the definitive one.

> It is silly to argue under these conditions that Apple's EHLO string

No, what's silly is your argument that the ABNF in the actual specification of
how mail clients and servers are supposed to behave isn't the definitive
definition.

> " if the verification fails, the server MUST NOT refuse to accept a

And that language appears in the context of checking that the IP literal
in the HELO/EHLO actually corresponds to the IP address of the client. It
has nothing to do with syntactic validity.

> address literal should look like is double-plus-ungood.

Then you should be arguing for a change in RFC 5321, because it is *very*
clear that this usage is not allowed.

				Ned

---

From: Yoav Nir <[email-masked]>
Date: Tue, 7 May 2013 08:03:43 +0000

> There isn't any mention of whether the mail server was tested.

I don't know why you censored this, but that particular implementation is used by a vast majority of corporations. The one good thing about running with the crowd is that stuff pretty much just works.  And it does, unless you do <heresy> something weird like enabling IPv6 </heresy>.

> There would likely be an error code with text providing an explanation.  I would probably follow a different debugging path.  Anyway, the session showed:
> 

Yeah, I would also start with the tcpdump. But that part of the story sounded bogus. 2nd paragraph has this:

                                        To collect my mail I use IMAP, and to send my mail I use 
   STMP, both standard protocols. These days security can’t be ignored so we use TLS for channel 
   encryption. All pretty standard stuff.

So how did he get to see the server response, or test with telnet?

> And then follow up with RFC 5321 where I find a mention of address literals.  I go and read RFC 4291 which is a Draft Standard.  I see an update in RFC 5952 which is a Proposed Standard.  As I was told that the Internet runs on Proposed Standards that update must be right.  I see the following:
> 

Gee, you read a lot of RFCs when debugging network problems :-). I only do so if I'm going to file a bug report / support ticket

> Between you and me, these Area Directors are trouble-makers.  :-)

So they are. But the hard-to-read parts of this spec are mainly the motivational sections (everything but 4). It might have been clearer to state again that the whole point of this spec is "conservative in what you send". Liberal in what you accept is mentioned in the first paragraph of section 4.  

> I verify compliance (2010), RFC 2821, RFC 4409; there isn't any mention of the IPv6 specifications mentioned in the detective story.
> 
> There are people out there who have to fix problems like this.  There are people out there who have to read those specifications and figure out where is the head and where is the tail.

Yup. That's why those people get the big bucks.

---

From: [email-masked]
Date: Tue, 07 May 2013 08:08:14 -0700 (PDT)

> robustness principle, and, arguably, plain silly.

I'm afraid I'm going to have to disagree here. If you look at RFC 5321 and
are unaware of the history of how the text came about, it gives the definite
appearance of going out of its way to ban the use of :: to replace a single
0. A reasonable interpretation is therefore that such forms are disallowed
for a reason.

It's fine to be tolerant of stuff the relevant standard doesn't
allow but doesn't call out explicitly. But that's not the case here.

In any case, if you want to "fix" this, we could change RFC 5321 to accept this
form. But as Mark Andrews points out, you can't make it legal to send such
forms without breaking interoperability. I suppose we could make the change and
recycle at proposed, but that seems rather extreme to fix what is in fact a
nonissue.

I'll also point out that this has diddley-squat to do with formal verification
processes. Again as Mark Anrdrews points out, we deployed something with a
restriction that subsequently turned out to be unnecessary, and now we're stuck
with it. Indeed, had formal verification processes been properly used, they
would have flagged any attempt to change this as breaking interoperability.

				Ned

---

From: John C Klensin <[email-masked]>
Date: Tue, 07 May 2013 11:28:43 -0400

--On Tuesday, May 07, 2013 08:08 -0700 Ned Freed
<[email-masked]> wrote:

>> robustness principle, then, in the case Geoff cites, Exchange
>> is simply non-conforming -- not because the spec prohibits
>> rejecting on the basis of a fine distinction about IPv6
>> formats, but because doing so is unnecessary, inconsistent
>> with the robustness principle, and, arguably, plain silly.
 
> I'm afraid I'm going to have to disagree here. If you look at
> RFC 5321 and are unaware of the history of how the text came
> about, it gives the definite appearance of going out of its
> way to ban the use of :: to replace a single 0. A reasonable
> interpretation is therefore that such forms are disallowed for
> a reason.

I hadn't looked at the syntax (as you know, the other part of
that history of how the text came about is that I didn't write
it or even make an effort to check it carefully).  But, having
now done so, you are completely correct.

> allow but doesn't call out explicitly. But that's not the case

Of course, we have lots of implementations that allow things on
input that the standard explicitly prohibits and we rarely spend
much time complaining about them.  I suppose that tolerance for
bare LF is among the most common examples.
 
> In any case, if you want to "fix" this, we could change RFC
> 5321 to accept this form. But as Mark Andrews points out, you
> can't make it legal to send such forms without breaking
> interoperability. I suppose we could make the change and
> recycle at proposed, but that seems rather extreme to fix what
> is in fact a nonissue.

Agreed
 
> I'll also point out that this has diddley-squat to do with
> formal verification processes. Again as Mark Anrdrews points
> out, we deployed something with a restriction that
> subsequently turned out to be unnecessary, and now we're stuck
> with it. Indeed, had formal verification processes been
> properly used, they would have flagged any attempt to change
> this as breaking interoperability.

Also agreed.

best,
   john

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 08 May 2013 08:05:38 +1200

On 08/05/2013 03:28, John C Klensin wrote:
...
>> this as breaking interoperability.

To be clear, I'm no fan of formal verification either, but this
*is* a case where the IETF's lapse in formality has come back to
bite, and the Postel principle would have helped. Also, given the
original subject of the thread, I don't see how language editing
could have made any difference.

    Brian

---

From: [email-masked]
Date: Tue, 07 May 2013 13:33:12 -0700 (PDT)

> could have made any difference.

Reread the notes about the history behind this in this thread. You haven't even
come close to making a case that formal verification of the standards would
have prevented this from happening. (Formal verification of implementation
compliance to the standards would of course have prevented Apple's client bug,
but that's a very different thing.)

You are, however, correct that this has nothing to do with specification
editing.

				Ned

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 08 May 2013 09:19:34 +1200

On 08/05/2013 08:33, Ned Freed wrote:
> have prevented this from happening. 

You are correct if only considering the mail standards. I suspect
that a serious attempt at formal verification would have thrown
up an inconsistency between the set of mail-related standards and
the URI standard. However, I think the underlying problem here is
that we ended up defining the text representation of IPv6 addresses
in three different places, rather than having a single normative
source. (ABNF in the mail standards, ABNF in the URI standard,
and English in ipv6/6man standards.)

> (Formal verification of implementation

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 7 May 2013 14:40:40 -0700

Hi -

> From: "Brian E Carpenter" <[email-masked]>
> To: "Ned Freed" <[email-masked]>
> Cc: "John C Klensin" <[email-masked]>; <[email-masked]>; <[email-masked]>
> Sent: Tuesday, May 07, 2013 2:19 PM
...
> > You are, however, correct that this has nothing to do with specification

I'm not so sure about that.  To me this seems to be a case of
inappropriate use of MUST.  First a reminder from RFC 2119:

   In particular, they MUST only be used where it is
   actually required for interoperation or to limit behavior which has
   potential for causing harm (e.g., limiting retransmisssions)

The prohibition against using :: more than once is amply motivated.
Multiple occurrances would introduce ambiguities, so that prohibition
clearly warrants a MUST.

The prohibition against using :: for a single 0 seems to lack
such an obvious syntactic / semantic motivation.  Does anyone
remember why this syntactic limitation was added?

Randy

---

From: [email-masked]
Date: Tue, 07 May 2013 16:17:40 -0700 (PDT)

> the URI standard.

Which is relevant to the present situation... how exactly? And in any case, the
relevant URI standard incorporates the ABNF from RFC 2373, but doesn't
state whether or not it also inherits restrictions specified in prose
in that specification, which is where the restriction in RFC 2821
originated.

> However, I think the underlying problem here is

Except that wasn't the problem. The ABNF in the email standards is
consistent with what the other standards said when RFC 2821 was published. And
once that happened the die was cast as far as email usage was concerned. The
fact that the other standards later decided to loosen the rules in this
regard is what caused the inconsistency.

If you want to blame something, it has to be either the initial decision to
limit use of :: or the subsequent decision to remove that limit. And for
increased formalism to have helped it would have to have prevented one of those
from happening. I supose that's possible, but I certainly don't see it as
inevitable.

				Ned