CSS pages missing formal syntax

[edent]

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: https://github.com/mdn/content/commit/34cfc2d55367dc02da374dc95f0b9f307385382f * Document last modified: 2022-04-18T21:54:44.000Z

[rubiesonthesky]

Broken also on these pages

• https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/radial-gradient#formal_syntax
• https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/repeating-linear-gradient#formal_syntax
• https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/repeating-radial-gradient#formal_syntax
• https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/conic-gradient#formal_syntax
• https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/repeating-conic-gradient#formal_syntax
• https://developer.mozilla.org/en-US/docs/Web/CSS/cross-fade#formal_syntax
• https://developer.mozilla.org/en-US/docs/Web/CSS/image/image#syntax

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]

@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]

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]

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

[ghost]

Ok.

[wbamberg]

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 https://github.com/mdn/yari/pull/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]

@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]

I've filed https://github.com/mdn/mdn-community/discussions/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]

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:

1. the item is nonstandard (or deprecated and (presumably) removed from the standard)
2. 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
3. the syntax is missing from webref for some other reason

[wbamberg]

Nonstandard items

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

https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-float-edge https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-force-broken-image-icon https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-image-region https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-orient https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-outline-radius https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-outline-radius-bottomleft https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-outline-radius-bottomright https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-outline-radius-topleft https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-outline-radius-topright https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-user-focus https://developer.mozilla.org/en-US/docs/Web/CSS/-moz-user-input https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-border-before https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-box-reflect https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-attachment https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-box-image https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-composite https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-position-x https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-position-y https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-repeat-x https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-mask-repeat-y https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-overflow-scrolling https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-tap-highlight-color https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-text-security https://developer.mozilla.org/en-US/docs/Web/CSS/-webkit-touch-callout https://developer.mozilla.org/en-US/docs/Web/CSS/box-align https://developer.mozilla.org/en-US/docs/Web/CSS/box-direction https://developer.mozilla.org/en-US/docs/Web/CSS/box-flex https://developer.mozilla.org/en-US/docs/Web/CSS/box-flex-group https://developer.mozilla.org/en-US/docs/Web/CSS/box-lines https://developer.mozilla.org/en-US/docs/Web/CSS/box-ordinal-group https://developer.mozilla.org/en-US/docs/Web/CSS/box-orient https://developer.mozilla.org/en-US/docs/Web/CSS/box-pack https://developer.mozilla.org/en-US/docs/Web/CSS/font-smooth https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-coordinate https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-destination https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-points-x https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-points-y https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-type-x https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-type-y https://developer.mozilla.org/en-US/docs/Web/CSS/user-modify https://developer.mozilla.org/en-US/docs/Web/CSS/zoom

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]

Thanks, @wbamberg I continue with the google doc list and the second list mentioned here https://github.com/mdn/content/issues/18780#issuecomment-1213231721 Then I can check for any other instances that need an edit.

[wbamberg]

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]

Badly tagged pages

(or other content-side problems)

Badly tagged pages:

https://developer.mozilla.org/en-US/docs/Web/CSS/align-tracks https://developer.mozilla.org/en-US/docs/Web/CSS/justify-tracks https://developer.mozilla.org/en-US/docs/Web/CSS/masonry-auto-flow https://developer.mozilla.org/en-US/docs/Web/CSS/padding-block https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline https://developer.mozilla.org/en-US/docs/Web/CSS/paint-order https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-gutter https://developer.mozilla.org/en-US/docs/Web/CSS/text-decoration-thickness https://developer.mozilla.org/en-US/docs/Web/CSS/text-underline-offset

...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 https://github.com/mdn/content/pull/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 https://github.com/mdn/content/pull/19471 for that.

[wbamberg]

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]

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]

https://github.com/mdn/content/pull/19473#issuecomment-1213389638 I am a bit confused about how to do this properly. I need to review this issue again.

[wbamberg]

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]

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

[ghost]

@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 https://github.com/w3c/webref/issues/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 https://github.com/mdn/content/pull/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 https://github.com/mdn/content/pull/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]

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 https://github.com/w3c/reffy/issues/980)

[wbamberg]

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]

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 https://github.com/mdn/content/pull/21092 landed recently. Anything else that should be done to make math-depth and math-shift work?

[wbamberg]

@fred-wang , https://github.com/mdn/content/pull/21092 ought to fix all three of those pages, and seems to, but please let me know if it doesn't :).

[Josh-Cena]

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

• /en-us/docs/web/svg/attribute/font-stretch
• /en-us/docs/web/svg/attribute/unicode-bidi
• /en-us/docs/web/svg/attribute/display
• /en-us/docs/web/svg/attribute/transform-origin
• /en-us/docs/web/svg/attribute/font-family https://github.com/mdn/content/pull/33330
• /en-us/docs/web/css/gradient/repeating-linear-gradient
• /en-us/docs/web/css/gradient/repeating-radial-gradient
• /en-us/docs/web/css/gradient/repeating-conic-gradient
• /en-us/docs/web/css/-webkit-mask-box-image https://github.com/mdn/content/pull/25756
• /en-us/docs/web/css/scroll-snap-type-x
• /en-us/docs/web/css/user-modify
• /en-us/docs/web/css/minmax
• /en-us/docs/web/css/-moz-float-edge https://github.com/mdn/content/pull/25327
• /en-us/docs/web/css/-moz-force-broken-image-icon
• /en-us/docs/web/css/-webkit-text-security

[cdoublev]

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]

Update: we have a few remaining occurrences:

• /en-us/docs/web/css/@font-face/font-stretch - https://github.com/mdn/content/issues/34347
• /en-us/docs/web/css/@starting-style
• /en-us/docs/web/css/align-tracks - #34281
• /en-us/docs/web/css/calc-constant - https://github.com/mdn/content/issues/34348
• /en-us/docs/web/css/font-stretch - https://github.com/mdn/content/issues/34347
• /en-us/docs/web/css/justify-tracks - #34281
• /en-us/docs/web/css/user-modify (also no formal definition)
• /en-us/docs/web/css/-moz-force-broken-image-icon
• /en-us/docs/web/css/-webkit-text-security (also no formal definition)