[tsvwg] Re: draft-ietf-tsvwg-udp-options

["[e-mail]" <[e-mail]>]

Hi, John,

We are using the IETF convention of isolated keywords (SAFE, UNSAFE, RESERVED, UNASSIGNED) in all caps, as (as you note) is the case for 2119 keywords. It makes it more clear when these words are used in their special sense, vs. (e.g.) at the beginning of a sentence.

We use all caps for option names for similar reasons (vs. Time), but also to avoid the use of awkward mixed case values (e.g., UExp, OAuth) or forced generation of “backcronyms”. This is consistent with TCP, e.g., using SACK rather than SAck for selective acknowledgements. This also makes lists of option names easier to see in running text, which we do in several places in the doc.

In other cases I could find, we use capitalization as per the original source - unless I missed any.

We could add an explanation to that effect in the terminology section if useful.

Joe

—
Dr. Joe Touch, temporal epistemologist
www.strayalpha.com

> On Jul 9, 2024, at 12:48 PM, John Scudder <jgs=[e-mail]> wrote:
> 
> Hi,
> 
> I looked briefly at this document as part of my review of draft-ietf-opsawg-tsvwg-udp-ipfix-13, which references it normatively. Because I’m not primarily reviewing this document, I haven’t checked to see if this drive-by comment has already been discussed; I apologize if it has. That having been said:
> 
> I notice you’re using all-caps SAFE and UNSAFE to denote different classes of options. Pretty please, consider using the more usual, and less SHOUTY, option of indicating a keyword by capitalizing it, as in Safe and Unsafe. To me at least, the SHOUTY CASE rendering makes the document less usable because (a) SHOUTY IN MY HEAD, (b) I keep reflexively wanting to know what it’s an acronym for, and (c) it bugs me that these aren’t RFC 2119 keywords but are styled like them. 
> 
> I acknowledge that this is a superficial complaint, that there’s no rule against ALL CAPS, and I won’t make a fuss if you choose not to change your convention, but I thought I should mention that for this reader at least, it makes the document less accessible and confers no advantage I can see vs. the intial-cap option. (OK there’s one: it’s clear when you’re using the keyword and not the common English word when it begins a sentence. But to me at least, that’s not a sufficient benefit.)
> 
> (The same goes for various other uses of ALL CAPS in the doc, this was just the most obvious and the one that tripped me up.)
> 
> $0.02,
> 
> —John