Re: [tcpm] Please review 793bis!

[Wesley Eddy <[e-mail]>]

Thanks for looking at this, and trying to figure out how to make it feel 
less dated.

I fully agree with you that people doing new implementations are one of 
the important targets for doing this work.  When we initially adopted 
it, we mentioned IoT and userspace code as being likely to "get it 
wrong" if people needed to slog through 793 + 1122 + errata (if they 
even found them) + all the other relevant RFCs coming later that make 
little tweaks here and there.

At high level, I think purely editorial changes are "ok", but we need to 
be vigilant that they're actually purely editorial!  (actually, one of 
your suggestions below is not quite technically correct, so it is a good 
example of how this is harder than it seems and innocent mistakes are 
easy to creep in ... I have tried to avoid it as much as possible for 
exactly this reason)

More specific thoughts on your examples below:


On 7/27/2019 9:43 PM, Tommy Pauly wrote:
> Some initial examples of changes that came to mind:
>
> - Structure; there is both a Terminology section (3.2) relatively early on, and a glossary (3.11) near the end. It seems more typical nowadays to have a terminology section up front, and just refer inline to supporting documents (like IP, for example).

These are a bit different, and the section 3.2 labelled "terminology" 
really is more of a quick overview of a few of the variables that 
reoccur frequently, along with the state machine states.  It could be 
split into subsections like "Key Connection State Variables" and "State 
Machine Overview", if that would be more clear (and that would be purely 
editorial).  The glossary is more like an actual terminology section ... 
whether it goes up front or not is not something I have a strong opinion 
on. Personally, I have never liked the style in some more recent RFCs 
where terms are defined before a reader has much clue what they're 
relevant to, so have slight preference to leave it alone at the end.


> - Many of the RFCs referenced are the older or obsoleted versions

Those cases should probably be fixed, unless there is a reason for 
them.  If you indicate them, I'll happily make updates.


> - Consistency and freshness; some of the terminology feels dated, such as "the local and remote socket numbers" for referring to what is called "port numbers" elsewhere in the document and in current parlance.

That's a case of not rewriting text from 793/1122.  Do you think it 
would confuse anyone?

To correct you though, the socket numbers are not just the port numbers, 
they also include the IP addresses.  That might be something good to put 
in the glossary?  It's explained in RFC 793 at top of page 5 (but this 
was a section of 793 that we originally decided to leave out, because it 
was very basic content that people working in the Internet protocols 
today learn from textbooks - that they didn't have in 1981, so was in 
the RFC, and it would be harder to update accurately with regard to all 
the things that have changed in IP, link layers, other transports, etc, 
in the meantime).