W3C home > Mailing lists > Public > ietf-http-wg@w3.org > January to March 2022

Editorial styling inconsistencies when referring to Structured Fields

From: Lucas Pardue <lucaspardue.24.7@gmail.com>
Date: Wed, 16 Feb 2022 20:53:44 +0000
Message-ID: <CALGR9oYapHa6+ySHboypZ03+Px4QcRQtJWZQKzahyVrxGbx-gA@mail.gmail.com>
To: HTTP Working Group <ietf-http-wg@w3.org>
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
Received on Wednesday, 16 February 2022 20:54:08 UTC

This archive was generated by hypermail 2.4.0 : Wednesday, 16 February 2022 20:54:10 UTC