Pretty-printing the CSS formal syntax

MDN
#1

The CSS reference pages include a block containing the “formal syntax” for that item.

It’s inserted in the page using the {{csssyntax}} macro, and typically looks something like this:

[ <bg-layer> , ]* <final-bg-layer>

where 
<bg-layer> = <bg-image> || <bg-position> [ / <bg-size> ]? || <repeat-style> || 
<attachment> || <box> || <box>
<final-bg-layer> = <'background-color'> || <bg-image> || <bg-position>
 [ / <bg-size> ]? || <repeat-style> || <attachment> || <box> || <box>

where 
<bg-image> = none | <image>
<bg-position> = [ [ left | center | right | top | bottom | <length-percentage> ]
 | [ left | center | right | <length-percentage> ] [ top | center | bottom |
<length-percentage> ] | [ center | [ left | right ] <length-percentage>? ] &&
[ center | [ top | bottom ] <length-percentage>? ] ]
<bg-size> = [ <length-percentage> | auto ]{1,2} | cover | contain
<repeat-style> = repeat-x | repeat-y | [ repeat | space | round |
no-repeat ]{1,2}
<attachment> = scroll | fixed | local
<box> = border-box | padding-box | content-box
...

(only without the syntax highlighting).

I think formal syntax is potentially very useful for experienced web developers, but I’m interested in ways we could present it better. To scope this exercise, I’d like to limit it to things we could do in KumaScript macros: so I’m not going to consider ways to interactively explore the formal syntax.

One idea here is just to pretty-print the formal syntax. This would make it look less of a wall of text, and reveal the structure of a definition in a more visual manner.

Specifically, the suggestion is:

1. break a formal syntax definition into its constituent parts at the top level only

This means that, for example, this:

<position> = [[ left | center | right | top | bottom | <length-percentage> ] |
 [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-
percentage> ] | [ center | [ left | right ] <length-percentage>? ] && [ center | 
[ top | bottom ] <length-percentage>? ]]

…would look like this:

<position> = 
    [ left | center | right ] || [ top | center | bottom ]                                           |
    [ left | center | right | <length-percentage> ] [ top | center | bottom | <length-percentage> ]? |
    [ [ left | right ] <length-percentage> ] && [ [ top | bottom ] <length-percentage> ]

(It would be possible to iterate into these components, and pretty-print them too. But I think this might start to become less readable in many cases.)

And this:

mask-layer = <mask-reference> || <position> [ / <bg-size> ]? || <repeat-style> || <geometry-box>
 || [ <geometry-box> | no-clip ] || <compositing-operator> || <masking-mode>"

would look like this:

mask-layer =
    <position> [ / <bg-size> ]?  ||
    <repeat-style>               ||
    <geometry-box>               ||
    [ <geometry-box> | no-clip ] ||
    <compositing-operator>       ||
    <masking-mode>

2. break CSS function parameters

This means that, for example, this:

<rgb()> = rgb( [ [ <percentage>{3} | <number>{3} ] [ / <alpha-value> ]? ] | [ [ 
<percentage>#{3} | <number>#{3} ] , <alpha-value>? ] )

…would look like this:

<rgb()> = rgb(
  [ [ <percentage>{3} | <number>{3} ] [ / <alpha-value> ]? ] |
  [ [ <percentage>#{3} | <number>#{3} ] , <alpha-value>? ]
)

So I’m interested in feedback on this. I’m especially interested in specific suggestions for how we could format the formal syntax to make it more readable. Are these suggestions useful? Is there more we could be doing here?

There are some other possible formatting improvements. I can think of two: syntax highlighting and having legends, rather than tooltips, for combinators and multipliers and things like that. But those can wait for a future thread :).

Edited to add:

I should probably have started with this, but the reason I’ve brought this up now is that I’ve been looking at CSSTree. I’ve wanted to present the formal syntax in a more usable way for a while, but decided it wasn’t really possible to do it reliably without a parser for the formal syntax, and didn’t want to write one of those.

But this is exactly what CSSTree provides. So if we rewrite {{csssyntax}} using CSSTree, we could make the macro code much simpler and more reliable, and would be able to add features like pretty printing and syntax highlighting without too much difficulty.

However, this would mean making CSSTree a KumaScript dependency, and I’m not sure if that would be acceptable.

1 Like
Pretty-printing the CSS formal syntax, part 2
#2

I’ve not really got anything else to suggest here, but this all sounds like a good idea to me. I find the CSS formal syntax very hard to read.

I think having legends and tooltips would be good, in terms of explaining combinators, etc.

#3

Will – I think this is a pretty good proposal as a starting point. As everyone knows, I’m a fan of formal syntax (although I concede ours are pretty much an unreadable wall of text sometimes).

That said, I’m not sure how you use CSSTree to pretty-print CSS formal syntax, since it seems to be designed to parse CSS rather than the formal syntax text. Perhaps you’ve found information about it that I’m not seeing at a quick flip through its docs.

Sheppy

#4

Perhaps you’ve found information about it that I’m not seeing at a quick flip through its docs.

Yes, I have (I’m not just making this stuff up :slight_smile: ).

#5

Sorry – didn’t intend to imply that you were. :slight_smile:

Do you have a link to that info? I’m quite curious now. This is something that would be of special interest to me to see happen, so I’d love to know more.

Sheppy