Inconsistent use of Bikeshed dfn and property references

[y-guyon]

There is no consistent pattern of using dfn or property as anchor definitions:

https://github.com/AOMediaCodec/av1-avif/blob/2286f6c1a642310f8d42523a1a784b0a8e7dfb8b/index.bs#L71-L148

There is no consistent pattern of referencing to anchors:

https://github.com/AOMediaCodec/av1-avif/blob/2286f6c1a642310f8d42523a1a784b0a8e7dfb8b/index.bs#L173

https://github.com/AOMediaCodec/av1-avif/blob/2286f6c1a642310f8d42523a1a784b0a8e7dfb8b/index.bs#L178

https://github.com/AOMediaCodec/av1-avif/blob/2286f6c1a642310f8d42523a1a784b0a8e7dfb8b/index.bs#L341

https://github.com/AOMediaCodec/av1-avif/blob/2286f6c1a642310f8d42523a1a784b0a8e7dfb8b/index.bs#L384

---

I suggest replacing all occurrences by:

• type: dfn+[=token=] for a concept (example "AV1 Image Item")
• type: dfn+<code>token</code> for a struct name, field name or literal value (examples AV1ItemConfigurationProperty, still_picture, avif)
• Optional: type: property+'token' strictly for an image item property (example 'colr')
  This is optional because I am not so sure Bikeshed properties were designed for something such as image item properties. I believe it is just a coincidence if the word "property" is used for both what Bikeshed was initially designed to support and the concept of an image item property.

Thoughts?

[leo-barnes]

Agreed. It's pretty inconsistent.

@tidoust Any comments on what Bikeshed expects property to be used for? Should we exclusively stick to dfn given that we're not really dealing with CSS?

@y-guyon If I understand you right you propose doing this?

Concepts: Defined in AVIF: An <dfn export>AV1 Alpha Image Item</dfn> .... Defined in YYYY spec: url: XXXX; spec: YYYY; type: dfn; .... AV1 Alpha Image Item Referenced in AVIF: If an [=AV1 Alpha Image Item=] ....

Name/field/literal: Defined in AVIF: The <dfn export><code>still_picture</code></dfn> field .... Defined in YYYY spec: url: XXXX; spec: YYYY; type: dfn; .... still_picture Referenced in AVIF: If the <code>[=still_picture=]</code> .... (Or do you not want the [==] when referencing? Does <code></code> automatically add a reference? '' seems to do so.)

Item property: Defined in AVIF: The '<dfn export>colr</dfn>' item property .... Defined in YYYY spec: url: XXXX; spec: YYYY; type: property; .... colr Referenced in AVIF: If the 'colr' box ....

[leo-barnes]

Let's try to address this for v1.2.0 as well.

[y-guyon]

If I understand you right you propose doing this?

Yes and why not the following to be extra specific and future-proof:

-Referenced in AVIF: `If an [=AV1 Alpha Image Item=] ....`
+Referenced in AVIF: `If an [=AVIF/AV1 Alpha Image Item=] ....`
-Referenced in AVIF: `If the <code>[=still_picture=]</code> ....`
+Referenced in AVIF: `If the <code>[=AVIF/still_picture=]</code> ....`

Does automatically add a reference?

I assumed so but I just checked and it does not work. It should be <code>[=token=]</code> indeed.

Item property:

It should be <dfn export property> right?
I suggest not relying on properties at all for consistency (or only on properties and not on dfn), unless they bring significant added value (shorter 'token' syntax may be one).

[tidoust]

@tidoust Any comments on what Bikeshed expects property to be used for? Should we exclusively stick to dfn given that we're not really dealing with CSS?

Yes, sticking to dfn would be good, the property type is meant to be used for CSS properties, see Definition types.