Warning: Undefined property: stdClass::$ip in /home/public/blog/class.comment.php on line 31

Warning: Undefined property: stdClass::$ip in /home/public/blog/class.comment.php on line 31

Translating an old spec to the new processor

Last updated:

This post records the conversion experience of taking a large, complicated older spec (CSS Image Values Level 4) and putting it on my new preprocessor.

  1. Adding the metadata, as usual, is easy. Had to look up what the required keys are, but that's what the docs are for.
  2. Stripped out a bunch of boilerplate, as usual. Deleting stuff, yay!
  3. Spent a long while converting over to Markdown-style paragraphs. This isn't necessary, but it makes the source prettier.
  4. Run some regexes to convert older markup patterns into the new shortcuts, like ''&lt;foo>'' to <<foo>>. These are simple, but do produce a few bits of weirdness that I fix as I go along.
  5. Adjusted all of my function definitions. Previously, they looked like <dfn id=foo-type>&lt;foo></dfn> = foo(...). To make autolinking work better, I switch them to <dfn>foo()</dfn> = foo(...). Still unsure if I want to have a type for functions like this - maybe an auto-genned one, so <<foo-function>> first tries to autolink to <dfn>foo()</dfn>?
  6. While I'm at it, just remove the manually-specified IDs from nearly every definition. The auto-genned ones are fine. (The main reason I had so many defined was because the old processor didn't include the definition type in the id, so there were more collisions.)
  7. Convert all the propdef tables into the <pre class=propdef> format. Simple and easy, and makes the source prettier.
  8. Finally, fix up all the value definitions. Change them all to be just <dfn>foo</dfn>, and add dfn-type=value dfn-for=foo to their containers, so I don't have to specify that stuff manually on each.
  9. All right, reached the bottom, cleared out the last of the boilerplate. Run the processor for the first time... and hit errors. This is expected. Run it with --debug to see how bad it is, and it's bad. Gulp.
  10. Actually, not all that bad. I ignore all the warnings at first, and just deal with the errors one by one. They're real errors in my document - things marked up wrong, multiple definitions of the same term, attempted links to terms that aren't defined, etc. A few are attempted links to terms that don't exist in other specs, but should. I mark these as ignored for now by putting them in an "Ignored Terms" metadata, so I can deal with them later. This all takes about 20 minutes to do, but it's useful work.
  11. Okay, now time for the warnings, all about the processor having multiple specs defining a term and not being able to decide which to choose. Some were between CSS2.1 and a spec that replaces part of that, so I added those to autolinker-config.md to the "CSS 2.1 Replacements" section. One was split between the real definition and an "additional values" definition, which I don't auto-handle yet, so I added it to the the autolinker config too. Another was split between the real definition and a duplicate definition in another spec, done solely to hack around the lack of cross-links. Another addition to the autolinker config.

And that's that! Spec now processes cleanly, with no warnings or errors.

(a limited set of Markdown is supported)

I'm curious what this was for. A private project? Was this double-checking inconsistencies at the W3C? Does this work make its way into Chrome?

Reply?

(a limited set of Markdown is supported)

When writing CSS specs for the W3C, we initially write the documents in a simplified format, then run it through a preprocessor to do a lot of automatable things, like creating a ToC and Index, linking up terms, etc.

I've been working for a little while on a new processor to replace our current one. Now, a lot of the specs in the CSSWG are processed using this new processor (named Bikeshed).

Bikeshed is more powerful than the old processor, and has a side effect of enforcing much better hygiene in the specs.

Reply?

(a limited set of Markdown is supported)