Convert CSS2 to use Bikeshed

[gsnedders]

I would like to convert CSS2 to Bikeshed, for the following reasons:

• Stylistic consistency with other CSS specs (for the sake of readability, etc., especially including the xref box to other refs)
• Making it easier to xref things to/from other Bikeshed specs
• Getting rid of generated code from the repo (i.e., the built copy of the spec)

Risks:

• Accidental changes to normative text
• Not being able to generate a multipage version and breaking xref links to it (I think we can do this with post-processing with not too much difficulty, though)

https://github.com/gsnedders/csswg-drafts/commits/css2-bs is some vague start towards converting it, albeit with 488 linking errors, and obviously bogus references to other later CSS modules.

I'm happy to do further work on converting it if the group thinks this is useful.

[svgeesus]

Aren't we gradually getting rid of CSS2, bit by bit? I thought we had agreed to start removing sections and replace them with links to the Level 3+ specs that replaced each one.

I agree that having to edit a non-bikeshed spec and use an old, unmaintained preprocessor is a pain; plus we have a nice, bikeshed-driven index of all properties and CSS2 doesn't contribute to that. But a wholesale document conversion on a progressively-obsoleted spec seems like a lot of work for little payback, especially if it breaks existing links.

In other words I am not opposed but not sure it is worth it.

[gsnedders]

Aren't we gradually getting rid of CSS2, bit by bit? I thought we had agreed to start removing sections and replace them with links to the Level 3+ specs that replaced each one.

See https://github.com/w3c/csswg-drafts/issues/2224, related to this. (Also, deleting text makes it easier to move to Bikeshed!)

Note that it is very much bit-by-bit, given css-box-3 has scarcely been touched in over a decade, hence we're going to have some parts of CSS2 referred to relatively long term.

I agree that having to edit a non-bikeshed spec and use an old, unmaintained preprocessor is a pain; plus we have a nice, bikeshed-driven index of all properties and CSS2 doesn't contribute to that. But a wholesale document conversion on a progressively-obsoleted spec seems like a lot of work for little payback, especially if it breaks existing links.

To be clear here: I am happy to do the work and try and avoid it breaking links, because I think the gains are sufficient to justify it, even based purely on the parts that aren't going to be replaced any time soon.

[plinss]

plus we have a nice, bikeshed-driven index of all properties and CSS2 doesn't contribute to that

The index is based on data from Shepherd's spec parser, which does process CSS2.1. Granted the parser doesn't have quite the same fidelity as a bikeshed generated spec as most of the anchor definitions are based on heuristics rather than the clear data attributes bikeshed produces, so I expect a bunch are not being properly identified.

While I'd love to see 2.1 in biksehed format, I agree that I'm not sure it's worth the work, but if you're willing, then have at it, there will be benefit. That said, last I checked bikeshed didn't support generating multi-page specs... (maybe it does now? or can soon?)

[gsnedders]

That said, last I checked bikeshed didn't support generating multi-page specs... (maybe it does now? or can soon?)

My plan was just to do post-processing of the Bikeshed spec, similar to how the HTML multipage edition used to be done. (See https://github.com/whatwg/old-google-code-html5/blob/master/spec-splitter/spec-splitter.py for the script that did that.)

[plinss]

Well that precludes relying on the server to generate the spec, unless we add the spec splitter to the draft server...

I imaging Tab would be willing to add multipage support to bikeshed to support this effort, provided he has the bandwidth.

[gsnedders]

@plinss Well, the drafts server can just serve the single page version (and only the single page version). I don't think it's too much of a problem to not have the multipage spec there?

[plinss]

No, that would be a problem, as all of the current links are to the multipage version. If we lost the multipage version on the draft server they'd all break. It's also painful to use the single page version.

[frivoal]

I love bikeshed as much as the next person, but it doesn't seem like a great idea.

• typing "make" in csswg-drafts/css2/ will build the spec, so it's not like using that processor is hard.
• If we convert to bikeshed, we will no longer be able to trivially cherry-pick changes from the staging "csswg-drafts/css2/" spec to the stable "csswg-drafts/css21/" spec, as we've repeatedly said would we do, unless someone also bikesheds "csswg-drafts/css21/" in a way that's guaranteed to convince W3M that it is the same spec and that we can republish it as is.

[tantek]

In short: the cost of switching CSS2 to use Bikeshed (and the likely fixes / changes needed to Bikeshed to handle producing a multipage spec like CSS2) is not worth the benefits.

@gsnedders has been able to create a branch of CSS2 (see https://github.com/w3c/csswg-drafts/pull/2544) that he can use to regenerate the existing CSS 2.1 REC with 2016 updates.

That is, at this point it is likely easier (less work) to incrementally maintain the tool setup that @gsnedders has setup to build CSS2, than it is to do the work to change CSS2 to use Bikeshed.

My understanding is that @plinss is also able to run the CSS2 build tools, and even do so automatically on the server whenever a commit is made to the /css2/ directory to rebuild the spec accordingly.

PROPOSED: Automate and incrementally maintain existing CSS2 build tools instead of converting to use Bikeshed.

(Originally published at: http://tantek.com/2018/102/t6/)

[tabatkins]

PROPOSED: Automate and incrementally maintain existing CSS2 build tools instead of converting to use Bikeshed.

Not "instead of", but rather "until it becomes more feasible to". All specs should at minimum be taken off of obsolete processing tools eventually, and ideally be in Bikeshed.

[gsnedders]

@tabatkins do you want us to file feature requests for everything needed to build CSS2 in Bikeshed?

Closing because as per @tantek's comment using the old build system seems like the right option.

[tabatkins]

@tabatkins do you want us to file feature requests for everything needed to build CSS2 in Bikeshed?

Yeah, that'd be great.

[frivoal]

I think using CSS2 as a learning opportunity and a source of feature requests for bikeshed is a good idea, regardless of whether we actually convert it. CSS2 is a large spec, so it probably exercises the build tool quite extensively, and being able to write similar specs in bikeshed would be nice.

I am not convinced the actual conversion is worth the effort, though.

Because of that, if some of the feature requests we end up with look like weird quirks of 2.1 rather than generally useful features, I don't think bikeshed needs to bend over backwards to accommodate them.

If we eventually get to the point where a bikeshed conversion becomes trivial, we can consider it then, but I don't think it would be all that bad if we never got to that point.

[gsnedders]

I'm reopening this, because I am increasingly convinced this is feasible.

https://github.com/gsnedders/csswg-drafts/blob/26db35abcbdb7d1ba654baa560a75ddb1351e14e/css2/Makefile#L321 has a bunch of regex that generate a css2.bs which can then be built. Bikeshed does produce fatal errors, but they're largely things we should fix anyway.

At a textual level at least, there appears at this point to be very little breakage. See https://deploy-preview-2--unruffled-galileo-5a0f9a.netlify.com/css2.bs.html if you want to see what I currently have built from that branch.

It's not perfect, and the Bikeshed file is kinda a grotesque mess of HTML compared with anything currently maintained, but it does at least seem to imply there's a practical path forward from here to Bikeshed without having a huge upfront cost to convert the spec, thereby not blocking further work on CSS2 for an unknown period of time.

[gsnedders]

As for URL stability: there are almost no duplicate anchors in CSS2 across the different pages (the total list in 2011/6 was: content, ignore, img-clip; there's also q4 shared between one spec subsection and one subsection of the Changes appendix, plus various auto-generated numeric ids used for the index, and in 2016 annoying-warning).

Those three are:

• content: "Content" in the definitions (for our abstract tree) and the content property
• ignore: "Ignore" in the definitions and "ignore" as in what you do when there's a syntax error
• img-clip: Appears both in the spec and in the Changes appendix for where it was added

The first two I think we can just get by making the (§3.1) "definitions" point at both (it already does for "ignore"), and the last we've solved by getting rid of the pre-2.1 REC changes.

At that point, we can just redirect all pages to /Overview.html, and rely on the anchor being preserved upon redirect.