Hi Reese, Many thanks for your thorough check! Please see my answers below.
ALL: I give quite long answers to the “Cellular” and “Protocol Instance” ” questions below because they serve as a great example to explain what I’ve done, and why. Maybe you want to read this and chime in. > On Dec 19, 2024, at 7:23 AM, Reese Enghardt <i...@tenghardt.net> wrote: > > Hi Michael, Megan, all > > Thank you for taking on the monumental task of figuring out the > capitalization. We indeed owe you a beer, Michael. > > I looked at the differences in RFC-to-be-9622 and 9623, and most of the > changes look good to me, except for the cases below. > > > I'm not quite sure about the "Cellular" in 9622 in Section 6.2, shouldn't > this instance be kept lower case? > > "(i.e., > an interface type preference might be based on a user's preference to > avoid being charged more for a Cellular data plan)." > > I assume "Cellular" means a specific value set in the API, whereas "cellular" > refers to the concept of a cellular network in general. If that's true, > shouldn't "cellular" be kept lower case here, as this sentence refers to the > concept of a cellular network in general? > > I agree with all the other capitalization of "Cellular", as those refer to a > specific value set in the API. We have generally applied upper case for 1) *some* specific terms that we defined, and 2) for “more abstract” things in the API, to distinguish them from the concrete things below (“Connection” vs. “connection” is the typical example). Following this logic was my primary rule when doing the capitalization. Now, regarding “Cellular", this is a case 1), not a case 2). For such cases, I decided on the basis: - how often do which forms already appear? - what is the version in 9621, if it does appear there? (we should generally give precedence to the 9621 style, I think). Here is the corresponding "grep -c" output for “Cellular”: rfc9621-OLD.xml:1 rfc9622-OLD.xml:3 rfc9623-OLD.xml:1 and “cellular”: rfc9621-OLD.xml:0 rfc9622-OLD.xml:2 rfc9623-OLD.xml:0 So, my rationale was: not only is “Cellular” used more often, it is also the style we used in 9621. Hence I chose “Cellular” and I suggest to leave it like that. Does that make sense? > And in 9623 in Section 4.1.2, I see the following occurrence of the currently > unchanged "Protocol option", shouldn't that one be capitalized "Protocol > Options" as well? > > "Protocol options are next checked in order. " This was an oversight; I agree with your suggestion, thank you very much! > Further, shouldn't Protocol Instance stay upper-case in the following four > instances in Section 7.2 of 9623, as I assume we mean the Protocol Instance > as defined in 9261? > > "the Transport Services > Implementation is responsible for notifying the protocol instance of > the change." > > "For protocols that do not support multipath or migration, the > protocol instances should be informed of the path change," > > "Thus, while it is useful for a > protocol instance to be aware of a temporary loss of connectivity," > > " the Transport Services Implementation should > also inform the Protocol Instance about potentially new paths that > become permissible" > > Same for the two instances in Section 9.2: > > " In addition to protocol state, protocol instances should provide data > into a performance-oriented cache to help guide future protocol and > path selection" > > "Besides protocol instances, other system entities > may also provide data into performance-oriented caches." Short: I’d say “no”. Long: Should we capitalize ALL the terms that we define in section 1.4 of 9621? I don’t think so. For instance, this glossary includes very common terms such as “Application”. Also, the glossary itself doesn’t capitalize all of them. See our pre-AUTH48 version here: https://ietf-tapswg.github.io/api-drafts/draft-ietf-taps-arch.html#name-glossary-of-key-terms where, e.g., we have: "Preference: A preference to prohibit, avoid, ignore, prefer, or require a specific Transport Feature.” This word “Preference", by the way, appeared 12 times non-capitalized in 9621 and only once capitalized: as the defined term in the glossary itself. What I did for this particular word was to use the capitalized version only when it refers to the type that we defined. E.g., I would allow text like: “The application expresses its preference by using a Property of type Preference”. I think that “protocol instance" is also a “case 2” (see “cellular” above): just a term we define, not something that exists in a more abstract or concrete fashion. Occurrences of “Protocol Instance": 9621: 4 (including 2 in a definition list: the glossary and also section 4.2). 9622: 0. 9623: 6. Occurrences of “protocol instance": 9621: 4. 9622: 1. 9623: 5. So, I thought: we have more “normal” (not as headings or such) occurrences of the non-capitalized form in 9621, and otherwise it’s half-half; but it’s not an abstract concept, and IMO, we should only capitalize terms when there’s a good reason for it, or else the documents become really weird to read. => hence I opted for “protocol instance” everywhere, and I suggest to keep it like that. By the way, I kept any capitalized form for everything in section headings, tables, and other such things (e.g. also as the defined term itself (i.e., the text before the colon), in the glossary). > Plus, I found one typo in Section 10.3: > > " in response to Abort ations. " Thanks! Cheers, Michael
-- auth48archive mailing list -- auth48archive@rfc-editor.org To unsubscribe send an email to auth48archive-le...@rfc-editor.org
