Make formal CSS syntax more understandable

[SebastianZ]

Previously, there were already discussions about what to do with the formal syntax shown on CSS pages.

Because the syntax isn't intuitive, it is obviously something that confuses readers as well as contributors as @hamishwillee noted in #2202 (comment).

With the rise of CSS Houdini and its CSS Properties and Values API to define custom properties the formal syntax becomes more important, though. Authors need to understand it to some extent in order to be able to define the syntax for their custom properties.

Therefore, I believe we should find a way to make the syntax more understandable. At some point we displayed some info icon when hovering the syntax box. Somehow linking to an explanatory page like the value definition syntax page would surely help people getting to know about it.

Besides that, the different parts of the syntax are actually already linking to that page. That feature is just broken at the moment, see mdn/yari#2963.

Sebastian

[wbamberg]

Hi Sebastian :)

I'm not sure exactly what you're suggesting here - we do already show info on hover and link to the syntax documentation in places like https://developer.mozilla.org/en-US/docs/Web/CSS/mask#formal_syntax don't we (I mean, given a fix for mdn/yari#2963)? Or are you asking about something else?

About a hundred years ago I looked into pretty-printing the formal syntax: https://discourse.mozilla.org/t/pretty-printing-the-css-formal-syntax-part-2/27330. I thought it was quite nice but there wasn't enough interest to make it ship. I think there's also a lot of potential to use css-tree to make formal syntax more interactive, so you could explore a bit of syntax and drill down into its components. It seems like it would be a significant amount of work to spec and implement though. There would also be a question about how much of this should be done in a macro rather than in the platform directly.

[SebastianZ]

Hi Will! Great to read from you again! 😃

Basically, I just wanted to (re)start a discussion here on how to improve its display as I am hearing for years now that it's hard to understand for readers.

Thank you for sharing the Discourse link! I see now that you already put much thought into it. And I totally agree with all what you wrote there and here.

I guess with "not enough interest" you mean that it wasn't a priority because everyone in the thread seemed to be very positive about the suggested changes and your prototype.

Just to sum up the points from that thread here:

• Break the syntax into its constituent parts
• Break function parameters
• Initially collapse it and allow to expand it (i.e. use summary/details)
• Use CSSTree for pretty-printing and syntax highlighting
• Keep the links and (translated) tooltips to basic data types, combinators, and multipliers
• Maybe add a legend for combinators and multipliers

Please let me know if I missed something!

I don't know what the final decision about macros was. I thought you wanted to get rid of them completely at some point. Though if they are going to stay, the {{csssyntax}} macro could be extended to do most of this.

Sebastian

[SebastianZ]

With the rise of CSS Houdini and its CSS Properties and Values API to define custom properties the formal syntax becomes more important, though. Authors need to understand it to some extent in order to be able to define the syntax for their custom properties.

To clarify this, CSS Properties and Values allows authors to define custom properties using the same formal syntax for their values as for the predefined properties.

The specification also provides some examples:

@property --radius {
  syntax: "<length>";
  inherits: false;
  initial-value: 0px;
}

Where the syntax descriptor can take any kind of formal syntax.

The spec. also has this example for a syntax definition:

"foo | <color># | <integer>"

@hamishwillee That's what I meant in #2202.

Sebastian

[wbamberg]

I guess with "not enough interest" you mean that it wasn't a priority because everyone in the thread seemed to be very positive about the suggested changes and your prototype.

Basically people didn't (don't?) think formal syntax is important enough to spend much time improving, and/or just wanted to remove it or hide it in some way. I have some sympathy with that, it definitely only serves a niche among our users, so if you user-test it 95% of people will just say "this is baffling", and it's then hard to prioritise. But I can also see the argument that serving the 5% is important as well. Also I think we both agree that we could do a much better job of presenting it. So it's a bit chicken and egg: it looks not very useful, which makes it hard to invest time into making it more useful :).

Just to sum up the points from that thread here:

• Break the syntax into its constituent parts
• Break function parameters
• Initially collapse it and allow to expand it (i.e. use summary/details)
• Use CSSTree for pretty-printing and syntax highlighting
• Keep the links and (translated) tooltips to basic data types, combinators, and multipliers
• Maybe add a legend for combinators and multipliers

Yeah, something like that :). As past-me said in that post, I tried using legends and I think the problem is that when the syntax is big, the legend is a long way away from the syntax, if you see what I mean. But, legends are more accessible, so maybe worth more thought.

The prototype code is at https://github.com/wbamberg/kumascript/blob/better-formal-syntax/macros/csssyntax.ejs. I guess it might be challenging convincing people to allow css-tree as a new dependency in the platform, but I do think it's worth using css-tree if we can, it would make life much easier.

I don't know what the final decision about macros was. I thought you wanted to get rid of them completely at some point. Though if they are going to stay, the {{csssyntax}} macro could be extended to do most of this.

I think eventually something like csssyntax could become platform code (as is the code to render compat tables today actually) but that's a long way off.