CSS pages missing formal syntax #18780

edent · 2022-07-25T14:01:51Z

MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient

What specific section or headline is this issue about?

https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient#formal_syntax

What information was incorrect, unhelpful, or incomplete?

Formal syntax
Error: could not find syntax for this item

What did you expect to see?

The formal syntax :-)

Do you have any supporting links, references, or citations?

https://www.w3.org/TR/css-images-3/#linear-gradients

Do you have anything more you want to share?

No response

MDN metadata

Page report details

Folder: en-us/web/css/gradient/linear-gradient
MDN URL: https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient
GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/css/gradient/linear-gradient/index.md
Last commit: 34cfc2d
Document last modified: 2022-04-18T21:54:44.000Z

The text was updated successfully, but these errors were encountered:

rubiesonthesky · 2022-07-26T09:32:44Z

Broken also on these pages

and many more.... https://developer.mozilla.org/en-US/search?q=%22Error%3A+could+not+find+syntax+for+this+item%22

What is the fix for these? Remove the block?

ghost · 2022-08-03T18:57:19Z

@sideshowbarker hi, this requires over 10,000 changes and it is time-consuming for me.
I did the first 7 ones of this issue. Is it possible to merge this only?

rubiesonthesky · 2022-08-03T19:07:34Z

There probably isn't that many issues. The search is also returning pages that just mention those words. There is no possibility to search with the exact phrase.

For what it's worth, I'd guess it would be okay to fix just some pages in same time and do multiple PRs. Makes it easier to review.

teoli2003 · 2022-08-03T19:56:15Z

Can we wait before trying to solve this issue? @wbamberg will know what the best course of action is.

ghost · 2022-08-04T04:03:19Z

Ok.

wbamberg · 2022-08-09T01:27:45Z

For CSS functions, we should update the CSSSyntax macro so it can find the formal syntax for those. From a quick look I think this is a really simple change, but I'm not sure whether it would be better to add it to mdn/yari#6618 or to wait for that to be merged, so as to keep PRs simpler and more focused.

For nonstandard things like https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-outline-radius it's a bit trickier because the syntax doesn't exist in webref. So we could either hardcode formal syntax in the pages, or remove the syntax.

ghost · 2022-08-09T04:34:42Z

@wbamberg Hi,

How can I track which documentation has the formal syntax and which one doesnt? (This can become confusing after couple of corrections)
Can I submit 5 formal syntax replacement per PR? (meaning I submit multiple PRs for this issue)

wbamberg · 2022-08-09T17:42:07Z

I've filed mdn/mdn-community#175 to decide how to proceed wrt nonstandard properties.

@najmiehsa , I think it would be best to wait until we have a resolution there.

wbamberg · 2022-08-12T15:21:05Z

I've taken a look at this, made a sheet listing all the pages under CSS that have the error message "Error: could not find syntax for this item": https://docs.google.com/spreadsheets/d/1tNRrwtG_Kx2JWROeTQhqVGKoJQxfHHxp8on0OtQXp9g/edit#gid=0 .

They seem to fall into three main categories:

the item is nonstandard (or deprecated and (presumably) removed from the standard)
the page is badly tagged, so the macro doesn't think it's a CSS property page, or there is some other content-side problem
the syntax is missing from webref for some other reason

wbamberg · 2022-08-12T15:25:32Z

Nonstandard items

For these items, according to the discussion in https://github.com/orgs/mdn/discussions/175, we should hardcode the formal syntax:

Additionally, this one:

https://developer.mozilla.org/en-US/docs/Web/CSS/ime-mode

...although it seems to be standard, is marked as deprecated and is not in webref AFAICT. Perhaps it has been removed? (It's hard to check because the CSS specs are not currently available). So maybe we should hardcode this one as well.

ghost · 2022-08-12T15:29:46Z

Thanks, @wbamberg I continue with the google doc list and the second list mentioned here #18780 (comment)
Then I can check for any other instances that need an edit.

wbamberg · 2022-08-12T15:36:06Z

Thanks, @wbamberg I continue with the google doc list and the second list mentioned here #18780 (comment) Then I can check for any other instances that need an edit.

Thank you @najmiehsa , that would be great! You should be able to find the syntax in https://github.com/mdn/data/blob/main/css/properties.json , and just copy it into a Markdown <pre> block, like:

```plain
// syntax here
```

If you want to start with just one, to get the general idea, then do the rest, that might be a good plan.

wbamberg · 2022-08-12T15:47:24Z

Badly tagged pages

(or other content-side problems)

Badly tagged pages:

...these should be fixed by updating the pages with the correct tags, notably "CSS Property".

https://developer.mozilla.org/en-US/docs/Web/CSS/image/image

...this one provides an argument to CSSSyntax, but it's malformed.

I've filed #19469 to fix all these.

Edited to add: I just realized that https://developer.mozilla.org/en-US/docs/Web/CSS/sign_function is also a content-side problem, so filed #19471 for that.

wbamberg · 2022-08-12T17:16:11Z

Syntax not in webref

This includes the following syntaxes that aren't given in webref:

https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/repeating-conic-gradient
https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/repeating-linear-gradient
https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/repeating-radial-gradient
https://developer.mozilla.org/en-US/docs/Web/CSS/math-depth
https://developer.mozilla.org/en-US/docs/Web/CSS/math-style
https://developer.mozilla.org/en-US/docs/Web/CSS/minmax

The math-depth and math-style properties are defined in the MathML Core spec (https://w3c.github.io/mathml-core/#the-math-style-property), which doesn't appear in the webref CSS specs. Should it?

The repeating-x-gradient functions are listed in webref, but only a prose description is given:

"<repeating-linear-gradient()>": {
  "prose": "In addition to linear-gradient(), radial-gradient(), and conic-gradient(), this specification defines repeating-linear-gradient(), repeating-radial-gradient(), and repeating-conic-gradient() values. These notations take the same values and are interpreted the same as their respective non-repeating siblings defined previously."
},
"<repeating-radial-gradient()>": {
    "prose": "In addition to linear-gradient(), radial-gradient(), and conic-gradient(), this specification defines repeating-linear-gradient(), repeating-radial-gradient(), and repeating-conic-gradient() values. These notations take the same values and are interpreted the same as their respective non-repeating siblings defined previously."
},
"<repeating-conic-gradient()>": {
    "prose": "In addition to linear-gradient(), radial-gradient(), and conic-gradient(), this specification defines repeating-linear-gradient(), repeating-radial-gradient(), and repeating-conic-gradient() values. These notations take the same values and are interpreted the same as their respective non-repeating siblings defined previously."
},

We can't just extract the prose description because of translated content. We could I suppose omit csssyntax here and just add some prose along these lines.

Note that there are other cases like this, such as <repeat()>, but we don't see an error there because our page does not attempt to list formal syntax: https://developer.mozilla.org/en-US/docs/Web/CSS/repeat.

Finally <minmax()> doesn't seem to have an entry at all although it is listed as a component of some other types. Again, the same applies to some other functions, like <fit-content()>, where we don't see an error because our fit-content() page does not attempt to include formal syntax.

I think there are a couple of things here.

From the webref side, would it be better to have values for some of these items? @tidoust , do you have opinions about this?
From the MDN side, we should have a more consistent policy about what to do when formal syntax is not present in webref. We could simply omit formal syntax, or simply provide a less "error-like" message in the page.

teoli2003 · 2022-08-12T18:15:31Z

The math-depth and math-style properties are defined in the MathML Core spec (https://w3c.github.io/mathml-core/#the-math-style-property), which doesn't appear in the webref CSS specs. Should it?

It should, see w3c/webref#681 for how to fix it (I was waiting for an answer from @fred-wang to know if he wanted to do it or not)

ghost · 2022-08-12T18:29:55Z

#19473 (comment) I am a bit confused about how to do this properly. I need to review this issue again.

wbamberg · 2022-08-12T18:44:31Z

Custom CSS property

I forgot, there is one left over: https://developer.mozilla.org/en-US/docs/Web/CSS/--_star_ .

I'm not sure this should be a CSS property page at all. It isn't describing a specific CSS property, it's describing the syntax for a CSS feature (custom properties).

fred-wang · 2022-08-12T19:06:31Z

@teoli2003 Sorry I forgot about that issue. I plan to take a look indeed.

ghost · 2022-08-13T12:06:23Z

@wbamberg hi, ~~here is an example I attempted to cover:~~

~~This should be hardcoded but in the JSON file we have the same exact syntax:~~

https://github.com/mdn/data/blob/80aedce42a7f3a523a17e54ba87b0680ee171daf/css/properties.json#L936

Still, this shows formal syntax not found on the page.
And one thing I am not sure about is whether I should only cover those that need to be hard coded? Those from google docs

~~As I attempted to do so, I can tell some are identical to the JSON file and I shouldn't have hard-coded them.~~

~~- Do I need to double-check the list I have?~~

~~And If I need to edit the JSON file according to this w3c/webref#681 some need a table and some have other formats. How should I make sure I am doing each based on its standard?~~

~~and - Do I need to remove this one as well? custom CSS property~~

Updated the google doc: In PR #19473 I fixed the tags for these properties:

~~Custom properties~~
~~align-tracks~~
~~justify-tracks~~
~~masonry-auto-flow~~
~~padding-block~~
~~padding-inline~~
~~paint-order~~
~~scrollbar-gutter~~
~~text-decoration-thickness~~
~~text-underline-offset~~

8/15, 8/22 updated the docs in this PR #19067 I added syntax for these properties:

(-moz-force-broken-image-icon)
(-moz-image-region)
(-moz-orient)
(-moz-outline-radius)
(-moz-outline-radius-bottomleft)
(-moz-outline-radius-bottomright)
(-moz-outline-radius-topleft)
(-moz-outline-radius-topright)
(-moz-user-focus)
(-moz-user-input)
(-webkit-border-before)
(-webkit-box-reflect)
(-webkit-mask-attachment)
(-webkit-mask-composite)
(-webkit-mask-position-x)
(-webkit-mask-position-y)
(-webkit-mask-repeat-x)
(-webkit-mask-repeat-y)
(-webkit-overflow-scrolling)
(-webkit-tap-highlight-color)
(-webkit-text-security)
(-webkit-touch-callout)

8/20 I updated this PR #19416 . I covered:

box-align
box-direction
box-flex
box-flex-group
box-lines
box-ordinal-group
box-orient
box-pack
font-smooth
ime-mode
scroll-snap-coordinate
scroll-snap-destination
scroll-snap-points-x
scroll-snap-points-y
scroll-snap-type-x
scroll-snap-type-y
zoom

These are the instances that I have not covered and pointed out the reason in front of it:

(--star) (no syntax in JSON file)
(-webkit-mask-box-image) (no syntax in JSON file)
(-webkit-text-security) (no syntax in JSON file)
(repeating-conic-gradient) (no syntax in JSON file)
(repeating-linear-gradient) (no syntax in JSON file)
(repeating-radial-gradient) (no syntax in JSON file)
(image) (no syntax in JSON file)
(math-depth) (unsure)
(math-style) (unsure)
(minmax) (unsure)
(sign_function) (unsure)
(text-decoration-thickness) (unsure)
(user-modify) (no syntax in JSON file)

And 15 CSS functions at the end of the docs

tidoust · 2022-08-16T17:05:06Z

From the webref side, would it be better to have values for some of these items? @tidoust , do you have opinions about this?

We're trying to avoid maintaining formal syntax in webref that does not exist in the specs but if it's only for the repeating-x-gradient functions, I think we can easily make an exception to the rule. To stick with the way these are defined in the spec, I think I would define them as:

  { 
    "<repeating-linear-gradient()>": {
      "value": "<linear-gradient()>"
    },
    "<repeating-radial-gradient()>": {
      "value": "<radial-gradient()>"
    },
    "<repeating-conic-gradient()>": {
      "value": "<conic-gradient()>"
    }
  }

That may not be fantastic for MDN though as you might prefer to see the expansion of the non-repeating functions?

For other cases where Webref currently has prose because there is no formal syntax, I'm not sure there is much we can do at the Webref level. One possible improvement could be to extract HTML extracts from the spec instead of raw text, as this may be more directly reusable in MDN?

Finally <minmax()> doesn't seem to have an entry at all although it is listed as a component of some other types. Again, the same applies to some other functions, like <fit-content()>, where we don't see an error because our fit-content() page does not attempt to include formal syntax.

Both minmax() and fit-content() look like CSS functions but they are not defined as CSS functions (the spec defines them with a data-dfn-type="value" and not a data-dfn-type="function"). They are rather defined as "simple" values as auto or inherit. If they were real CSS functions, the definition of <track-size> would not be:

<track-breadth> | minmax( <inflexible-breadth> , <track-breadth> ) | fit-content( <length-percentage> )

... but rather

<track-breadth> | <minmax()> | <fit-content()>

Why is that? I don't know :) You may want to ask the CSS working group why they sometimes decide to create functions and sometimes decide to leave them as pure textual syntax. It may not be intentional.

I would prefer to only list functions in Webref that are defined as functions in CSS specs. We could complete the extracts with additional values though (provided we also extract the context under which these values are allowed, see w3c/reffy#980)

wbamberg · 2022-09-01T03:05:40Z

I would prefer to only list functions in Webref that are defined as functions in CSS specs. We could complete the extracts with additional values though (provided we also extract the context under which these values are allowed, see w3c/reffy#980)

Thanks for your reply, @tidoust , and sorry to be late responding. It seems like @fred-wang is going to take care of the MathML ones.

Regarding <repeating-*-gradient()>:

We're trying to avoid maintaining formal syntax in webref that does not exist in the specs

Yes, I can understand that for sure! We could just use some prose in these three cases instead of the syntax.

but if it's only for the repeating-x-gradient functions, I think we can easily make an exception to the rule. To stick with the way these are defined in the spec, I think I would define them as:
  { 
    "<repeating-linear-gradient()>": {
      "value": "<linear-gradient()>"
    },
    "<repeating-radial-gradient()>": {
      "value": "<radial-gradient()>"
    },
    "<repeating-conic-gradient()>": {
      "value": "<conic-gradient()>"
    }
  }
That may not be fantastic for MDN though as you might prefer to see the expansion of the non-repeating functions?

This should work fine, because we'd find (e.g.) <linear-gradient()> in valuespaces, and expand that. I just checked with a hacked version of webref:

Both minmax() and fit-content() look like CSS functions but they are not defined as CSS functions (the spec defines them with a data-dfn-type="value" and not a data-dfn-type="function"). They are rather defined as "simple" values as auto or inherit. If they were real CSS functions, the definition of <track-size> would not be:
<track-breadth> | minmax( <inflexible-breadth> , <track-breadth> ) | fit-content( <length-percentage> )
... but rather
<track-breadth> | <minmax()> | <fit-content()>
Why is that? I don't know :) You may want to ask the CSS working group why they sometimes decide to create functions and sometimes decide to leave them as pure textual syntax. It may not be intentional.

I'll see what they say :). Thanks again.

fred-wang · 2022-10-03T07:11:20Z

It should, see w3c/webref#681 for how to fix it (I was waiting for an answer from @fred-wang to know if he wanted to do it or not)

I see that https://developer.mozilla.org/en-US/docs/Web/CSS/math-style is now rendered correctly and that #21092 landed recently. Anything else that should be done to make math-depth and math-shift work?

wbamberg · 2022-10-03T17:17:58Z

@fred-wang , #21092 ought to fix all three of those pages, and seems to, but please let me know if it doesn't :).

Josh-Cena · 2022-12-23T20:52:57Z

Update: these pages still contain "Error: could not find syntax for this item". Some are SVG pages.

cdoublev · 2022-12-29T07:41:03Z

I would define them as:

  { 
    "<repeating-linear-gradient()>": {
      "value": "<linear-gradient()>"
    },
    "<repeating-radial-gradient()>": {
      "value": "<radial-gradient()>"
    },
    "<repeating-conic-gradient()>": {
      "value": "<conic-gradient()>"
    }
  }

I do not think they are valid definitions because repeating and non-repeating function names do not match. But there may be an intent to define <repeating-*-gradient> with a proper basic syntax, cf. the thread starting from this comment.

Josh-Cena · 2024-06-10T18:32:17Z

Update: we have a few remaining occurrences:

github-actions bot added needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. Content:CSS Cascading Style Sheets docs labels Jul 25, 2022

sideshowbarker added help wanted If you know something about this topic, we would love your help! effort: small This task is a small effort. and removed needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. labels Jul 26, 2022

ghost mentioned this issue Aug 2, 2022

Correction for the Formal syntax not found issue - 01 #19067

Merged

3 tasks

Josh-Cena mentioned this issue Aug 4, 2022

Several CSS Reference pages lack "Formal syntax" #19149

Closed

wbamberg mentioned this issue Aug 9, 2022

Update the syntax of CSS sin() function #19277

Merged

3 tasks

wbamberg mentioned this issue Aug 9, 2022

Support formal syntax for types and functions as well as properties mdn/yari#6618

Merged

ghost mentioned this issue Aug 11, 2022

Correction for the formal syntax not found issue - 02 #19416

Merged

3 tasks

wbamberg changed the title ~~linear-gradient missing formal syntax~~ CSS pages missing formal syntax Aug 12, 2022

wbamberg mentioned this issue Aug 12, 2022

Fix tags for CSS Syntax #19469

Merged

ghost mentioned this issue Aug 12, 2022

Correction for the formal syntax not found issue - 03 #19473

Closed

wbamberg mentioned this issue Sep 2, 2022

[css-grid] Mark up minmax() and fit-content() as functions in the spec? w3c/csswg-drafts#7682

Closed

wbamberg mentioned this issue Sep 26, 2022

Fix tags for CSS MathML properties #21092

Merged

fred-wang mentioned this issue Oct 3, 2022

Formal syntax of math-style is missing #18641

Closed

Josh-Cena mentioned this issue Oct 10, 2022

Missing “Formal syntax” for CSS minmax #21439

Closed

tidoust mentioned this issue Dec 13, 2022

CSS types only defined and extracted as values w3c/reffy#1146

Open

Josh-Cena added effort: large This task is large effort. and removed effort: small This task is a small effort. labels Jul 11, 2023

SphinxKnight mentioned this issue Jul 21, 2023

Syntaxe Error: could not find syntax for this item mdn/translated-content#13942

Closed

quentin-rey mentioned this issue Mar 22, 2024

The page on CSS :active has a broken french version mdn/translated-content#18265

Open

This was referenced Jun 22, 2024

font-stretch renamed to font-width #34347

Open

calc-constant renamed to calc-keyword #34348

Closed

Fix all remaining formal syntax errors #34358

Merged

sideshowbarker closed this as completed in #34358 Jun 23, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CSS pages missing formal syntax #18780

CSS pages missing formal syntax #18780

edent commented Jul 25, 2022

rubiesonthesky commented Jul 26, 2022 •

edited

Loading

ghost commented Aug 3, 2022

rubiesonthesky commented Aug 3, 2022

teoli2003 commented Aug 3, 2022

ghost commented Aug 4, 2022

wbamberg commented Aug 9, 2022

ghost commented Aug 9, 2022 •

edited by ghost

Loading

wbamberg commented Aug 9, 2022

wbamberg commented Aug 12, 2022 •

edited

Loading

wbamberg commented Aug 12, 2022

ghost commented Aug 12, 2022 •

edited by ghost

Loading

wbamberg commented Aug 12, 2022

wbamberg commented Aug 12, 2022 •

edited

Loading

wbamberg commented Aug 12, 2022

teoli2003 commented Aug 12, 2022

ghost commented Aug 12, 2022

wbamberg commented Aug 12, 2022

fred-wang commented Aug 12, 2022

ghost commented Aug 13, 2022 •

edited by ghost

Loading

tidoust commented Aug 16, 2022

wbamberg commented Sep 1, 2022

fred-wang commented Oct 3, 2022

wbamberg commented Oct 3, 2022

Josh-Cena commented Dec 23, 2022 •

edited

Loading

cdoublev commented Dec 29, 2022

Josh-Cena commented Jun 10, 2024 •

edited

Loading

CSS pages missing formal syntax #18780

CSS pages missing formal syntax #18780

Comments

edent commented Jul 25, 2022

MDN URL

What specific section or headline is this issue about?

What information was incorrect, unhelpful, or incomplete?

What did you expect to see?

Do you have any supporting links, references, or citations?

Do you have anything more you want to share?

MDN metadata

rubiesonthesky commented Jul 26, 2022 • edited Loading

ghost commented Aug 3, 2022

rubiesonthesky commented Aug 3, 2022

teoli2003 commented Aug 3, 2022

ghost commented Aug 4, 2022

wbamberg commented Aug 9, 2022

ghost commented Aug 9, 2022 • edited by ghost Loading

wbamberg commented Aug 9, 2022

wbamberg commented Aug 12, 2022 • edited Loading

wbamberg commented Aug 12, 2022

Nonstandard items

ghost commented Aug 12, 2022 • edited by ghost Loading

wbamberg commented Aug 12, 2022

wbamberg commented Aug 12, 2022 • edited Loading

Badly tagged pages

wbamberg commented Aug 12, 2022

Syntax not in webref

teoli2003 commented Aug 12, 2022

ghost commented Aug 12, 2022

wbamberg commented Aug 12, 2022

Custom CSS property

fred-wang commented Aug 12, 2022

ghost commented Aug 13, 2022 • edited by ghost Loading

tidoust commented Aug 16, 2022

wbamberg commented Sep 1, 2022

fred-wang commented Oct 3, 2022

wbamberg commented Oct 3, 2022

Josh-Cena commented Dec 23, 2022 • edited Loading

cdoublev commented Dec 29, 2022

Josh-Cena commented Jun 10, 2024 • edited Loading

rubiesonthesky commented Jul 26, 2022 •

edited

Loading

ghost commented Aug 9, 2022 •

edited by ghost

Loading

wbamberg commented Aug 12, 2022 •

edited

Loading

ghost commented Aug 12, 2022 •

edited by ghost

Loading

wbamberg commented Aug 12, 2022 •

edited

Loading

ghost commented Aug 13, 2022 •

edited by ghost

Loading

Josh-Cena commented Dec 23, 2022 •

edited

Loading

Josh-Cena commented Jun 10, 2024 •

edited

Loading