Hi Michael,
Thanks for the answers, please see inline:
On 12/18/24 21:01, Michael Welzl wrote:
On Dec 19, 2024, at 7:23 AM, Reese Enghardt <i...@tenghardt.net> wrote:
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?
I agree we should generally give precedence to the 9621 style, and I'm
fine with having "Cellular" always be upper case. I guess we don't
define a specific "Cellular" value in the API so we don't need to
distinguish the "case 2" here.
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.
If "protocol instance" is just a term we define and we don't need to
distinguish between abstract API concepts VS concrete things, that makes
it "case 1" per your distinction above, right?
I thought we generally capitalized all the terms we define including the
Transport Services Implementation concepts, but I guess that's not
necessary, and indeed I don't see these terms capitalized in most
instances in 9623. I'm fine with staying with your suggestion.
Best,
Reese
--
auth48archive mailing list -- auth48archive@rfc-editor.org
To unsubscribe send an email to auth48archive-le...@rfc-editor.org
