CSS formal syntax for (some) types and functions

[wbamberg]

I just landed an upgrade (I hope) to the way we render formal syntax for CSS properties.

The way this currently works is: it fetches (from webref) the syntax for the property, and all the syntaxes defined in the specs for all the values that that property can take, recursively (i.e. where a value is defined in terms of other values).

It then writes out all these syntaxes. So for instance, for https://developer.mozilla.org/en-US/docs/Web/CSS/background-image#formal_syntax , we include not only the syntax for background-image, but also syntax for the <gradient> type, and then recursively for the <color> type..

If a value doesn't have a syntax in webref, it makes a link to MDN, expecting us to have a page for that type. For example, we do this for <length>.

I think we should adjust this a little. In particular, I think we should:

• include a CSS formal syntax section in the pages for some of our more complex types and functions, including for example <color> and <gradient>.

• for these types and functions, instead of listing their syntax in the pages for properties that use them, instead link from those property pages to the type page, as we currently do for types that don't have a defined syntax in webref. This would mean, for example, that rather than https://developer.mozilla.org/en-US/docs/Web/CSS/background-image#formal_syntax embedding the syntax for <gradient>, we instead link to https://developer.mozilla.org/en-US/docs/Web/CSS/gradient, and list its syntax there.

I think there would be a few benefits to this:

• people looking at the page for the type would be able to see its formal syntax

• the formal syntax for the property would be shorter, giving more of an overview, while still enabling people to get all the details if they needed it

• it would help emphasise the commonality across many properties: that is, the fact that <color> is always specified the same way, so any time a property can accept a <color>, the details of that part of he syntax are always the same.

[teoli2003]

I think this is a good idea. If we have a dedicated page for a type, we should link to it.

[Rumyra]

Yeh I agree - making the formal syntax shorter for property pages is a big win imo.

Would there (or is there) a way to find out any types we don't document?

[wbamberg]

There are many items in the webref "values" that we don't have pages for, and many of them we should not have pages for. In particular types that have a simple syntax, where the type is quite specific to a small number of properties. To me these are the CSS equivalent of Web/API typedefs or dictionaries, where it is better to document them inline.

For example, <box>: https://developer.mozilla.org/en-US/docs/Web/CSS/background-clip#formal_syntax.

There are also some that we do have pages for, but I'm not sure if we should always do this thing of not embedding the syntax for constituent types. I think the danger of never embedding it is that the experience for readers would get very fragmentary, so they would have to visit lots of pages to get a picture of the property.

For instance, look at https://developer.mozilla.org/en-US/docs/Web/CSS/background-image#formal_syntax .

If we only linked whenever we could, its complete formal syntax would just be:

...maybe this it too terse, and it would be helpful at least to expand out the syntax for <image>?

Maybe in fact we should only do the linking thing for <gradient> and <color>, since these are very common and very long? At least for now, and see how that feels?

[wbamberg]

I filed a PR for the first piece of this: mdn/yari#6618 - this just adds support for CSS types.

[wbamberg]

The second piece of this is done in mdn/yari#6871 .