Media features are extracted as descriptors instead of value

[cdoublev]

Media features are extracted as descriptors. Do you want me to report the issue on w3c/csswg-drafts or do you think it can be fixed here?

I take this opportunity to ask an off topic question. Syntaxes of child at-rules are extracted by @webref/css, but not the top-level at-rules. Are you aware of this? Is it also because of a markup issue? Eg. for @keyframes:

@keyframes = @keyframes <keyframes-name> { <rule-list> }

This is not extracted.

<keyframe-block> = <keyframe-selector># { <declaration-list> }

This is extracted.

[tidoust]

Media features are extracted as descriptors. Do you want me to report the issue on w3c/csswg-drafts or do you think it can be fixed here?

The specs actually call them descriptors. Where would you expect to find them?

I take this opportunity to ask an off topic question. Syntaxes of child at-rules are extracted by @webref/css, but not the top-level at-rules. Are you aware of this? Is it also because of a markup issue?

We're both aware that CSS extraction is imperfect and unaware of all the places where there are issues, thanks for the report! In most cases, this is due to specs not containing enough clues for definitions to be picked up by Reffy, although code that extracts CSS definitions (in extract-cssdfn.mjs) could perhaps also be improved. In this particular case, I think that the problem is that @keyframes is not wrapped in a <dfn> (the <dfn> is in the prose).

It would be good to add additional tests to enforce additional guarantees such as "No valuespace that just hangs out there without being used" so as to catch these issues automatically and be able to curate the data (see #127). That would trigger some work on patches to specs and/or to webref data... Help welcome ;)

[cdoublev]

The specs actually call them descriptors. Where would you expect to find them?

It is weird. In Syntax, 5. Parsing:

Declarations are further categorized as property declarations or descriptor declarations, with the former setting CSS properties and appearing most often in qualified rules and the latter setting CSS descriptors, which appear only in at-rules.

CSS descriptors is anchored to its definition in 9.2 At-rules:

Block at-rules will typically contain a collection of (generic or at-rule–specific) at-rules, qualified rules, and/or descriptor declarations subject to limitations defined by the at-rule. Descriptors are similar to properties (and are declared with the same syntax) but are associated with a particular type of at-rule rather than with elements and boxes in the tree.

EDIT: oh maybe associated with a particular type of at-rule rather than with elements and boxes in the tree means that a descriptor can be used anywhere (prelude or value) in an at-rule?

The above suggests that descriptors should be contained by the at-rule: it can not be qualified as a descriptor if it is in its prelude. What do you think?

Below is an exemple that is syntactically invalid but it illustrates the above definitions:

@at-rule (media-feature: value) {
  descriptor: value;
  property: value;
}

Where would you expect to find them?

Ideally, I want to get a list of the descriptors allowed in a specific at-rules in order to discard a declaration whose name is not in the list of the properties/descriptors allowed in this specific at-rule, therefore it is not really an issue for me because I will use the for field of the descriptors to generate lists of descriptors by rule names.

Because @media is defined with <rule-list>, which means a list of rules without declarations (of properties or descriptors), I will never try to parse descriptors in @media.

To avoid generating a useless list of "descriptors" (media features) that would be allowed in @media, I just have to ignore descriptors whose for field value is @media.

Therefore I would say that I do not expect to find them, but they can exist in descriptors if they have to. :)

It would be good to add additional tests to enforce additional guarantees such as "No valuespace that just hangs out there without being used" [...] Help welcome ;)

Thank you!

I'm often tempted to look deeper into @webref/reffy and I have an exhaustive list of issues related to extracting property/type definitions from @webref/css. You can see some of them here as code comments. The project this file comes from has a npm build:report script that parses definition values from @webref/css to detect various issues.

I was planning to let you know about this when it is finished, because it is already taking too much of my time. But I definitely want to help on @webref/css!

[tidoust]

EDIT: oh maybe associated with a particular type of at-rule rather than with elements and boxes in the tree means that a descriptor can be used anywhere (prelude or value) in an at-rule?

The above suggests that descriptors should be contained by the at-rule: it can not be qualified as a descriptor if it is in its prelude. What do you think?

Below is an exemple that is syntactically invalid but it illustrates the above definitions:

I think you lost me. I'm not sure how to apply "prelude" and "value" to at-rules, but for me descriptors are tokens that you can only find between parentheses next to an @at-rule declaration. They cannot be used within the {}-block that follows it. Am I missing something?

I was planning to let you know about this when it is finished, because it is already taking too much of my time. But I definitely want to help on @webref/css!

I can only relate to the "taking too much of my time" part ;)

[cdoublev]

font-family, font-display, src, etc... in @font-face are probably the most famous/used descriptors imo. Interestingly, size is listed as the single descriptor of @page on MDN, but it is defined as a property in CSS Page 3 - 7.1. Page size: the size property, but listed as a descriptor at the end of the spec.

[tidoust]

Trying to reformulate the issue, the problem is that CSS specs use the term "descriptor" to mean

1. tokens that can be used within parentheses next to an at-rule, as aspect-ratio in @media (aspect-ratio: 1/1) {}
2. tokens that can be used within the final {}-block, as font-family in @font-face { font-family: sans-serif; } or size in @page { size: a4; }

... and you would like to have a way to separate both usages. Did I get it right this time?

I may miss something, but I don't see any way to do that with the data available, especially since production rules for the at-rules are typically defined in prose and thus not in a machine-readable format that could end up in CSS extracts to tell you where descriptors may appear.

Interestingly, size is listed as the single descriptor of @page on MDN, but it is defined as a property in CSS Page 3 - 7.1. Page size: the size property, but listed as a descriptor at the end of the spec.

That probably shows that the terminology is confusing for everyone ;) The table uses the descdef class, which suggests that "descriptor" is indeed intended. For consistency, the prose should probably use "descriptor" as well.

[cdoublev]

Yes, because I have to parse rule's contents to check they only contains valid descriptors: I don't really care about the descriptors are used in their prelude (ie. next to an at-rule).

Ok, then I'm closing this issue. I do not want to bother w3c/csswg-drafts editors/maintainers by asking for a clarification on the definition of a descriptor. It can be probably defined as data associated to a rule (descriptor) vs. (property) data that is a property of an HTML/SVG element, and it can be used anywhere in that rule (descriptor) vs. (property) in a style rule.

Thank you!

[dontcallmedom]

FWIW, there is already a filed bug about the misusage of "property" in the CSS page spec which acknowledges this is a mistake in the spec