Use bikeshed to manage the spec?

[davelab6]

https://tabatkins.github.io/bikeshed/ seems suitable for this kind of project

[alerque]

Bikesed looks pretty good actually, although I have some concerns with how well it translates to other formats. Obviously going to HTML is easy, but because it implements a lot of non standard things on top of Markdown (including things there are standard Markdown ways of doing) it can't easily be converted to random other formats. I suspect either writing a translator to convert the HTML or writing a bunch of Lua filters for Pandoc to convert from source could get the job done and map to any other output format desired, it just isn't baked in. (And yes I saw the mailing list comments about Markdown conversion and passing around docx files.)

Minor concerns aside, it does look like the most promising suggestion so far.

cf #27.

[simoncozens]

I like that a lot.

[alerque]

I can't do it this weekend, but I'll prototype a conversion using Pandoc & some filters to catch as much "spec-ish" formatting from the current Docbook sources as possible. I think it will be possible to map most of it across. While this proof of concept is in progress (and ⓐ the result looks really solid and ⓑ we commmit to going format that way) content can still be manipulated in the current format. The conversion will be scripted transformation of the repo so no need to hold up anything while the mechanics is in progress. If all goes well even work from early branches can be applied after transition by applying the same transformation to the PRs before merger.

[simoncozens]

I've started playing with this already, and to be honest it's not worth investing time in automated tooling. pandoc to markdown gets you most of the way there and the rest would need to be manually fixed, but since a goal of this whole process is going through the complete spec by hand, you're going to be doing that anyway. (In fact, if the automated translation is good enough you might not stop and read through the whole thing!)

So I'm starting by converting a chapter at a time with pandoc, pasting that into a new file, and making changes from there. It does all I need.

[simoncozens]

In fact, let me underline that: I don't think we want automated conversion, because I don't think want to use the existing spec, whether 1.4/AOTS/whatever, at all. Behdad's idea of an "MDN for OpenType" has given me an idea about how we should be approaching this, and a clean-room reimplementation without any of the existing spec documentation will be a better start point structurally, as well as avoiding any possible copyright claims. I'll have something to show in a few days.

[davelab6]

Hmm. Do you expect Peter and Vlad will transfer a new spec page for a given table into the copies of the spec they are the chairs of?

[simoncozens]

If what we make here is substantially better, then one of two things will happen:

• the industry coalesces around CommonType as a de facto standard.
• the de jure standard takes the best bits from CommonType.

I don't really care which one it is. :-)

[simoncozens]

If anyone has any spare cycles to help with automation, the best use of them would be to work on tabatkins/bikeshed#269. I've only written a few chapters and the document is getting impossibly long aready.

[alerque]

Ouch! That was one of my original concerns and a quick skim of the documentation suggested it had include functionality. Apparently I skimmed too fast, that has to do with output templating.

So my suggestion for starters would be to go ahead and keep them in separate files per chapter --- you want the Git history to be that way from the start. I can write a couple liner makefile that concatenates them together properly to be a valid full spec for exporting, that will work for building a site from the spec for now.

And then yes I'll have a look an what upstream needs for first class support.

[simoncozens]

No, other way around. You can include multiple input files without a problem. You can't produce split per-chapter output files, which I need to do.

[alerque]

Paginating monolithic output shouldn't be too hard. Post-processing semantically consistent HTML and re-linking it into chunks shouldn't be too much of an exercise. For the sake of editors and change tracking having the input file split up by chapter will be a good thing. We can get the output split later and it won't retro-actively change much if anything in the source data.

[simoncozens]

Yeah, I'm sure we can sort it later. I'm pushing along with each chapter in a separate file (or directory, for heavily segmented stuff like cmap). See the bikeshed branch.

[simoncozens]

Switching over to the bikeshed branch as master has implemented this.

[tabatkins]

Please feel free to comment on that big with your requirements for multi-page output. If it's just "one file per top-level heading", I've been planning to do that for a long while anyway, and yeah, the coding won't be too difficult.