Convert CSS2 to Bikeshed #5196
Convert CSS2 to Bikeshed #5196
Conversation
This primarily marks up many (but not all) property value definitions as being property values for their respective properties. The choice is mostly those keywords that exist in other specs; this should be further completed in due course.
This is in preparation for conversion to Bikeshed; both because the forthcoming conversion relies on parse/serialize cycles (using html5lib, which doesn't support preserving case) and because Bikeshed itself relies on tags when they appear in BSMD being lowercase.
This is done for the same reason as the previous commit (both Bikeshed conversion tooling does this, so this limits the diff in that single commit making blame more workable, and because Bikeshed does not handle tags split across multiple lines). Note that this doesn't deal with new lines within attributes yet.
This is, similar to parent commits, prior to the Bikeshed conversion to make more easily ignored from blame (plus also is easier to review). Most of this just gets rid of ambiguous ampersands and makes quoting of elements consistent (the choice of quotes is done to minimize the size of this diff).
Plus get rid of all the old source files (to git can correctly notice the lines have moved) as well as the old build system and the committed output.
This doesn't actually produce a particularly large diff, contrary to
what one might expect. This primarily just gets rid of head elements.
The algorithm used here is pretty simple:
1. Start with cover.src, then for each chapter/appendix:
2. Append the contents of the body element to the existing body
3. If the style element in the head has content not yet seen, add it to
the existing head.
These BSMD blocks were generated with a modified version of the old propdef generator, but should be trivially correct.
The q0 anchors date back to the original 2011 publication of CSS 2.1 and are all applied to the top-level headings within each page. As such, they're essentially unused (because everywhere just links to the top of the page). Additionally, the q0 anchors were removed when CSS 2.1 was edited in place in 2016 (see w3c#2551).
The old build system always took the first anchor within the header as the header's anchor, but Bikeshed (very reasonably) expects the anchor to be on the header itself. Note in many cases we also provide "legacy" anchors as spans within the header; these are unchanged.
In plenty of places we have strong directly nested within dfn or dfn directly nested within strong; in both cases this is unnecessary as the goal here is purely presentational and the current TR stylesheet boldens all dfns anyawy.
The old build system generated its index through specific markup rather than using all dfns. In reality, most of the things marked up for the index are actually generally useful dfns (this is unsurprising, given the index contains things people might want to lookup!).
This is needed as moving the IDs got rid fo a number of spans, therefore making new strong elements now adjacent.
There's no need for this.
Amusingly, some of the index instances are never actually defined.
The former produces quotes around the element in the BS output; the latter enables CSS syntax highlighting. The latter seems like the better behaviour.
This just adds lang-xml to pre elements with no lang-* class whose contents can be parsed as XML, as it is unlikely for arbitrary content to parse as XML (potentially some of this is intended to be HTML, but highlighting it as if it is XML is unlikely to be harmful).
This, similar to the previous commit, adds lang-css when there is no lang-* class already and the content parses as CSS without any parse errors. As CSS is more permissive, the automated script added slightly too much here and a little was manually reverted.
This happens to only be in img[alt]
The old built system added an ID to all imgs, so we should to.
The old CSS2 build system used [[FOO]] for a normative reference and [[-FOO]] for a non-normative one. BSMD uses [[!FOO]] for a normative reference and [[FOO] for a non-normative one.
This drops IDs for: index xrefs (x[n]), bits of generated content (annoying-warning, minitoc, W3C-doctype), refs (ref-*), and the index sections (index-[A]). Only the first might be referenced at all, and unfortunately they are not unique across all pages unlike all other anchors.
|
I'm a bit concerned about concatenating all the files. I accept that Bikeshed doesn't support multipage specs yet, but I expect it to eventually. And CSS2 is large enough that there's benefit to having both single page and multipage versions. It depends on how Bikeshed will handle multipage specs, whether it will be able to split a single source file to produce a multipage version or it will concatenate multiple sources itself to produce the single page version. And it's likely too soon to know which of those approaches it may require. There's also author and reviewer pain in having a single large source file rather than a number of more manageable files. I'm wondering if, in the meanwhile, it would be better to preserve the individual source files and have a singe additional file that's nothing but a set of includes. cc @tabatkins for any insights into how Bikeshed may wind up supporting multipage specs. |
|
@plinss by way of comparison, the ten largest |
|
@gsnedders good data, but if anything that tells me there are more specs that we should consider having multipage versions of when Bikeshed can handle it (and maybe multipage support should get bumped in priority). To be clear, I'm perfectly fine with re-releasing CSS2 as only a single page spec until Bikeshed gets multipage support. I highly value the work you're doing here, and think the value in the Bikeshed conversion outweighs the pain of a large single page spec for those that read it (though it may violate the priority of constituencies in some regards, the improved cross-linking and consistent presentation offsets that). I just want to be sure that when Bikeshed does support multipage, we're not in a situation where converting CSS2 back into a multipage spec is too much of a burden. If Bikeshed will be able to support auto-splitting a single input file, then this is mostly a non-issue (except for potential editor/reviewer pain of dealing with a large source file). Keeping the source files split just feels like keeping our options open. I accept that it could also cause editor pain if updates often need to span files, but I don't expect it to get updated much after the conversion. All in all, please take this for what it is, a concern, not an objection. |
|
My intent is indeed that multipage output will be supported from a single source file; having each "page" be a separate file that you include in is possible (and probable!), but won't be necessary. So don't take that as a concern here. That said, I do agree that keeping the chapters as separate files which are included together into the final document probably makes for an easier editting experience most of the time (unless you're doing find-and-replace across the whole thing, but even then, a good editor can do that across multiple files in a folder). And yeah, those very large specs should be split; I've thought about doing precisely that for Flexbox, Grid, Color, and Selectors, because they're very difficult to navigate currently. On the other hand, I'm not the one doing this work, so if it would be a pain to reverse the combining, whatever. ^_^ However, I would at minimum ask for some big-text section separators (https://tabatkins.github.io/bikeshed/#big-text) so it can be reasonably navigated by editors with minimaps. |
The Editor's Draft of CSS2 was converted to Bikeshed recently: w3c/csswg-drafts#5196 This means that the spec becomes single page for now (at least until Bikeshed supports multipage specs). This update drops `cover.html` as "common" filename, since it was only used there, and adjusts tests to only expect multiple page from the published CSS 2.1 version. Note the published version of CSS 2.2 still has multiple pages, so the spec still needs to retain the `multipage` flag in `specs.json`.
The Editor's Draft of CSS2 was converted to Bikeshed recently: w3c/csswg-drafts#5196 This means that the spec becomes single page for now (at least until Bikeshed supports multipage specs). This update drops `cover.html` as "common" filename, since it was only used there, and adjusts tests to only expect multiple page from the published CSS 2.1 version. Note the published version of CSS 2.2 still has multiple pages, so the spec still needs to retain the `multipage` flag in `specs.json`.
The sub-pages of the spec now 404, as of w3c/csswg-drafts#5196. This replaces all links with the singlepage version.
The sub-pages of the spec now 404, as of w3c/csswg-drafts#5196. This replaces all links with the singlepage version.
Fixes #2220.
While in total this is a big change, each of these commits individually is comparatively small and reviewable. The only exception is 82079cb, but the main change there is "just" concatenating all the *.src files, so should be easily reproducible.