Pretty-printing the CSS formal syntax, part 2

MDN
#1

For a while I’ve been talking about making the CSS formal syntax more usable. See the previous post Pretty-printing the CSS formal syntax for more context.

I’ve been working on this and now have something to show for it. Here’s what the old formal syntax for color looks like:

color-old
color-old.png2094×1066 141 KB

Here’s what the new macro produces:

color-new
color-new.png2092×2296 166 KB

Here are a couple more examples:

It makes 2 main changes:

  • some basic indentation/pretty printing
  • some syntax highlighting

It uses the (amazing) css-tree npm package to parse formal syntax definitions. This enables us to do more with shorter, simpler macro code.

If you want to try it out

  1. install a local Kuma: https://kuma.readthedocs.io/en/latest/installation.html

  2. point its kumascript directory at the “better-formal-syntax” branch of https://github.com/wbamberg/kumascript/

cd kumascript/
git remote set-url origin https://github.com/wbamberg/kumascript
git fetch origin better-formal-syntax
git checkout better-formal-syntax

(https://github.com/mdn/kumascript#updating-macros)

  1. rebuild the KumaScript image:
cd ..; KS_VERSION=latest make build-kumascript; cd kumascript

(https://github.com/mdn/kumascript#updating-the-dockerfile-andor-packagejson-file)

  1. restart the Docker containers:
docker-compose stop
docker-compose up -d
  1. scrape some CSS reference pages:
docker exec kuma_web_1 python manage.py scrape_document https://developer.mozilla.org/en-US/docs/Web/CSS/border
  1. open the pages, and look at the “Formal syntax” block. The new macro keeps the old name (csssyntax.ejs) and the same interface, so you don’t need to edit any MDN pages for you to see the difference.

Questions, notes, and stuff

  1. It’s not finished yet. It only supports CSS properties, it only adds links for types that are in the same block (e.g. it doesn’t add links to basic types), it doesn’t add tooltips, or support l10n. But these should all be fairly simple to add. Oh, and it has bugs, and no tests.

  2. In the first version of this, I wanted to use a “legend” section at the bottom (for things like combinator syntax help) instead of tooltips. Having tried this out, I think tooltips are probably a better option whenever the formal syntax is more than a screenful (which it often is). I still don’t like tooltips, but can’t think of a better approach that doesn’t involve front-end work.

  3. For the syntax highlighting, I’ve used the same classes that we already use for CSS syntax highlighting, so we get the same colours. I don’t like these colours very much (in particular, the blue-on-blue contrast is poor, and I think blue and red are too much like links and links-to-nonexistent-pages). But I wanted to be consistent.

  4. Having tried it out, the most obvious regression from the original is that the formal syntax is much longer - it seems to come out around three times as long on average. This is OK for shorter items, but for long ones like mask it’s about 7 screenfuls. It would perhaps be better to hide the whole thing (or at least everything after the first, top-level, type) under a “Details” disclosure arrow.

4 Likes
#2

Great work Will — this is a lot more readable than the original. There is nothing here that I don’t agree with. I do think tooltips are better, and links definitely need to be added.

And yes, I really think that we should couple this with working out how to hide the section in some way so it doesn’t freak out people who aren’t interested in it. Using summary/details would be a good cheap way to achieve this.

I also wondered if at some later date we could have a preference available in user options to show it by default, for those who want that?

#3

From my point of view hiding the section and only displaying it on demand is the highest priority. We know from user interviews that some people are scared away by long pages and almost nobody we asked had used this section in the past. There is certainly a use case for it, but for almost all users the better option would be to only display it when explicitly asked. That would also be a way to tell what the demand is for it.

#4

I feel that what should happen is that the header for the Formal syntax
section should become a toggleable section you can open and close,
defaulting to closed.

In fact, I sort of wonder if we should actually make all sections
toggleable open and closed, defaulting to open unless otherwise stated by
adding an option in the page (say, a data-* attribute on the header). But
that’s not really relevant at the moment.

I generally really like this direction for the pretty-printing of the
formal syntax. Possibly the only thing I wonder is if a more graphical form
might be clearer, by using railroad diagrams.