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.
- Adding the metadata, as usual, is easy. Had to look up what the required keys are, but that's what the docs are for.
- Stripped out a bunch of boilerplate, as usual. Deleting stuff, yay!
- Spent a long while converting over to Markdown-style paragraphs. This isn't necessary, but it makes the source prettier.
- Run some regexes to convert older markup patterns into the new shortcuts, like
<<foo>>. These are simple, but do produce a few bits of weirdness that I fix as I go along.
- Adjusted all of my function definitions. Previously, they looked like
<dfn id=foo-type><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
- 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.)
- Convert all the propdef tables into the
<pre class=propdef>format. Simple and easy, and makes the source prettier.
- Finally, fix up all the value definitions. Change them all to be just
<dfn>foo</dfn>, and add
dfn-type=value dfn-for=footo their containers, so I don't have to specify that stuff manually on each.
- 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
--debugto see how bad it is, and it's bad. Gulp.
- 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.
- 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.mdto 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.
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?
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.