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 #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 #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.