Re: Editorial styling inconsistencies when referring to Structured Fields

Strongly agree.

I fought with that a bit in
https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-02.html

where I used sf- and abnf as building blocks to further define field syntax

My2c,
R


Il mer 16 feb 2022, 21:56 Lucas Pardue <lucaspardue.24.7@gmail.com> ha
scritto:

> Hey all,
>
> I'm a big fan of Structured Fields. They make a lot of things easier.
> However, I'm finding some editorial difficulties when working on documents
> that define HTTP Fields in a structured fields format. An ad-hoc survey of
> some of the active documents in this WG and elsewhere seem to show an
> inconsistent editorial approach. I've not even been consistent myself.
>
> To illustrate what I mean. Let's consider the types in Structured fields,
> I'll call these descriptors: List, Inner List, Parameters, Dictionaries,
> Item (of bare-item type Integer, Decimal, String, Token, Byte Sequence,
> Boolean). List, Inner List, and Dictionary contain Item(s). These types
> have the respective ABNF: sf-list, inner-list, parameters, sf-dictionary,
> sf-item (of bare-item time sf-integer, sf-decimal, sf-string, sf-token,
> sf-binary, sf-boolean).
>
> In the documents that use Structured Fields, there seems to be a mixed bag
> of usage of the descriptor format (e.g. Dictionary) and the ABNF format
> (e.g. sf-dict) in the prose. A common pattern seems to be, to declare the
> container type as Dictionary or List and then the contents of the
> dictionary using ABNF. This is especially important because the collections
> contain Item, and specs often need to subset Item to a specific type like
> Integer or Byte Sequence. That also leads to an annoying construct like
>
> > Foo-Field is a Structured Fields List. List members MUST be of type
> sf-string. No parameters are defined.
> >
> > Foo-Field: sf-list
>
> I wonder if anyone else feels the inconsistency is off-putting and or
> distracting when trying to write or read specs. Should we attempt to define
> a consistent house style?
>
> Cheers,
> Lucas
>