Re: [tcpm] Please review 793bis!

[Tommy Pauly <[e-mail]>]

> On Jul 29, 2019, at 11:53 AM, Wesley Eddy <[e-mail]> wrote:
> 
> 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)

Yes, I absolutely agree that it's critical to make sure that the editorial changes don't change the meaning. These are good opportunities to tease apart the terminology for things that may be confusing to a current audience, as is the example you cite.

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

+1 to splitting up the terminology section into subsections with titles.

I do agree that just placing the full glossary at the front would be a bit much. Usually, the terminology up front is most useful for defining the most common terms that would otherwise lead to misinterpretation. For example, terms that the glossary defines that are otherwise generic, like "connection", may be good to just define in a rigorous manner up front as what "connection" means in this document.

Some of the other glossary entries are already in the terminology section, like RCV.NXT... it's possible they're not needed twice.

A couple of the glossary entries likely should just be RFC references—such as for FTP and IP.

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

I can run through these in a review pass, yes.
> 
> 
>> - 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?

Yes, I think it is a bit confusing, since it is not a clear definition in the current version of the document, and doesn't reference anything else. It's fairly particular to the environment in which TCP was implemented when designed.
> 
> 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).

That's a great clarification to make. I don't see exactly how the previous explanation in RFC 793 on page 5 introduces the concept of a "socket number" particularly. I get that a local socket structure contains both the local/remote ports and addresses, and there is also a local fd number allocated to the socket, but there generally isn't just one "remote socket number" that represents both a port and address in my experience.

Elaborating the text to say that the TCB contains the local address, local port, remote address, and remote port, would be the most clear, I would argue.

> 
>