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

Re: Editorial styling inconsistencies when referring to Structured Fields

From: Mark Nottingham <mnot@mnot.net>
Date: Thu, 17 Feb 2022 09:27:58 +1100
Cc: HTTP Working Group <ietf-http-wg@w3.org>
Message-Id: <23EF4BE4-C7BA-401D-8341-43964168D9CE@mnot.net>
To: Lucas Pardue <lucaspardue.24.7@gmail.com>
I wasn't terribly happy about including ABNF in SF, but IIRC some really wanted it because it's expected for HTTP headers. *shrug*

I'd recommend avoiding it if possible, or at least only using it in separate ABNF blocks (not prose).

Cheers,


> On 17 Feb 2022, at 7:53 am, Lucas Pardue <lucaspardue.24.7@gmail.com> wrote:
> 
> 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

--
Mark Nottingham   https://www.mnot.net/
Received on Wednesday, 16 February 2022 22:28:19 UTC

This archive was generated by hypermail 2.4.0 : Wednesday, 16 February 2022 22:28:20 UTC