Use of value definition type for terms that are not CSS values

[tidoust]

The spec uses value definition types for some of its definitions, e.g. av01.

It's tempting to use the value type for such values but, despite the generic name, that type was defined for CSS values, see Bikeshed's documentation. The use of value confuses tools that parse specs to extract semantic information, because that makes them think that the spec defines CSS terms.

There is no better definition type than dfn for now for such values. The possiblity to create one is being tracked in speced/spec-dfn-contract#6

[cconcolato]

Are there tools that parse the AOM specifications? and that cannot associate a non-CSS semantic for "value" definitions?

[tidoust]

We added the AOM specs to browser-specs, which means they now get crawled to produce data in Webref. Webref powers the cross-references database used in Bikeshed and ReSpec. The data and CSS extracts in Webref are also used in some IDEs and analysis tools. Whether the use of value creates an actual problem for them, I do not know!

For the CSS extract, we're trapping the problem through a patch in Webref to forget about the values for now. The definitions still reach Bikeshed and ReSpec as CSS definitions. That's slightly incorrect but that should not create any major issue!

[leo-barnes]

@tidoust

I'm taking a look at this right now. I'm not very familiar with BikeShed, so some newbie questions:

1. When you say we should dfn rather than value, do you mean we should do <dfn dfn export> or simply <dfn export> (since dfn does not export by default)?
2. I see in some of the other AOM specs that <dfn> without any attributes is used. Does this mean those definitions are not exported? From the BikeShed spec, dfn definitions are not exported by default from what I understand.
3. (Maybe question for @cconcolato ) I see in our spec that we have a bunch of <dfn export="">, but I don't see anything within the BikeShed spec that allows for providing attributes to export. Should this simply be <dfn export>? Or are those meant to be noexport?

[leo-barnes]

@tidoust
And a follow-up question:

Looking through the AV1-ISOBMFF spec, I see that AV1CodecConfigurationBox is marked as <dfn>AV1CodecConfigurationBox</dfn>. Going through the Webref data, I see the following in the AV1-ISOBMFF scraped data:

    {
      "id": "av1codecconfigurationbox",
      "href": "https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox",
      "linkingText": [
        "AV1CodecConfigurationBox"
      ],
      "localLinkingText": [],
      "type": "dfn",
      "for": [],
      "access": "private",
      "informative": false,
      "heading": {
        "id": "av1codecconfigurationbox-description",
        "href": "https://aomediacodec.github.io/av1-isobmff/#av1codecconfigurationbox-description",
        "title": "Description",
        "number": "2.3.2"
      },
      "definedIn": "prose"
    },

Note the "access": "private", snippet.

Is this the reason why we are manually "importing" these definitions in AVIF?

url: https://aomediacodec.github.io/av1-isobmff/; spec: AV1-ISOBMFF; type: dfn;
    text: AV1CodecConfigurationBox
    text: AV1 Sample
    text: AV1 Track

If AV1-ISOBMFF used <dfn export>, do I understand it correct that we would then simply be able to do [=AV1CodecConfigurationBox=] in AVIF without having to explicitly specify the term like above?

[tidoust]

1. When you say we should dfn rather than value, do you mean we should do <dfn dfn export> or simply <dfn export> (since dfn does not export by default)?

Yes, dfn is the default type so no need to "duplicate" it, <dfn export> is the recommended syntax.

2. I see in some of the other AOM specs that <dfn> without any attributes is used. Does this mean those definitions are not exported? From the BikeShed spec, dfn definitions are not exported by default from what I understand.

That's correct, dfn definitions are not exported by default, these definitions create private terms.

3. (Maybe question for @cconcolato ) I see in our spec that we have a bunch of <dfn export="">, but I don't see anything within the BikeShed spec that allows for providing attributes to export. Should this simply be <dfn export>? Or are those meant to be noexport?

From a Bikeshed perspective, export and export="" are the same thing. Whether you intended to export these definitions, I do not know ;)

[...]
Note the "access": "private", snippet.

Is this the reason why we are manually "importing" these definitions in AVIF?
[...]
If AV1-ISOBMFF used <dfn export>, do I understand it correct that we would then simply be able to do [=AV1CodecConfigurationBox=] in AVIF without having to explicitly specify the term like above?

That's correct as well. Note that you can force Bikeshed to create a link to a private term by adding a spec attribute, see Linking to unexported definitions:

<a spec="AV1-ISOBMFF">AV1CodecConfigurationBox</a>

Exporting definitions should be the preferred route whenever possible. It may make sense to keep definitions private if links are expected to be only from "related" specs, e.g., under the control of the same group of people, as a way to create the equivalent of the friend setting in object oriented languages.