HTML rendering of the spec (bikeshed/ReSpec)

[MikeRalphson]

There has been some discussion, on twitter and within the TSC about providing a HTML-rendered version of the specification (in addition to, and not replacing the markdown source-of-truth). This would provide an easier-to-use ToC, referenceable section numbers and a bibliography.

This also builds on the earlier discussion in #829 - cc @apowers313 @adrianhopebailie & @philsturgeon

Two examples have been generated, using Bikeshed and ReSpec.

The following pros/cons/differences are noted, but further feedback is greatly welcomed. Particular areas of interest are accessibility (s.508 and WCAG compliance) - please recommend good tools in this area, browser/mobile compatibility and ToC/section number rendering. Minor formatting tweaks can probably be accommodated, so these would not be a show-stopper, but please do call them out in comments.

I have also added a comment for each option, purely to gauge GitHub reactions. Please feel free to use 👍 👎 ❤️ etc. Please avoid one-line comments simply voting for either option - these may be deleted.

Note	Bikeshed version	ReSpec version
a11y	pending	pending
Size	342k	160k + 394k JS
w/o javascript	Renders fully	Renders without header/ToC
Anchors	Inline	ToC only Inline
Version number	Further down	Prominent
Logo	Further down	Prominent
Copyright	Present	Pending
Former Editors	Supported	Not supported Supported in later versions
Front matter format	Custom	JSON
Conformance	Repeated	Once
GitHub Links	Repo / Issues	Repo / Issues / Commit history
Mobile preview	Bikeshed	ReSpec
Implementation	Python 2	Node.js

[MikeRalphson]

Prefer Bikeshed version.

[MikeRalphson]

Prefer ReSpec version.

[darrelmiller]

So far Bikeshed is my preferred choice. Beyond the points listed above, Bikeshed includes anchors in the text for getting a link to the text and most importantly the tables in Respec look terrible in Edge ;-)

But that "Living Standard" is going to have to go.

[MikeRalphson]

most importantly the tables in Respec look terrible in Edge ;-)

The CSS styling should be easy to duplicate from one to the other. Edit: I've added some more 'github-y' CSS to the ReSpec version.

But that "Living Standard" is going to have to go.

This may be trickier as Bikeshed only seems to allow one from a fixed set of 'document statuses'.

I'm going to come out in favour of ReSpec, as the JSON header would be much easier to work with in Travis and the Python 2 dependency may come back to bite us.

[philsturgeon]

Oh boy, bikeshed is rather protective over statuses. Can we regex the HTML?

They both seem really similar other than style. Although bikeshed initially seemed better (and currently looks to have better style), perhaps we can slap enough paint on ReSpec that it starts to look like a RESPECtful enough option?

[apowers313]

Just FYI, I ended up having to solve most of these problems for FIDO's use of Bikeshed. We started with regex'ing the HTML to replace statuses; then we forked bikeshed and updated our statuses there (which was honestly about 5 minutes worth of work and much easier than regex); finally, it turns out that @tabatkins is a very nice and accessible guy and willing to collaborate and include statuses from other organizations.

As far as rendering issues go, you can use bikeshed boilerplate to update any of the formatting, logos, etc. For FIDO we ended up having a copyright.include, header.include and logo.include. Note that the .include files have to be in the same directory as the .bs file. You can find boilerplate for different groups in the bikeshed source.

One last thing, which you don't seem to have stumbled upon yet is managing references. If you include a biblio.json in the same directory as your .bs file, then you can add references that aren't included in the specref database. (Although, submitting specs to specref is always the preferred route and I've found that the w3c team is pretty easy to collaborate with.)

Hope that helps. If you need help throwing together a proof of concept, let me know.

[MikeRalphson]

Thanks @apowers313 - all good to know!

[tabatkins]

I'm also happy to host your boilerplate files in Bikeshed, if you're going to be using them for several specs. That way you don't have to keep track of them yourself.

If you go that route, just PR me with the additions to the bikeshed/boilerplate folder.

[MikeRalphson]

Thanks @tabatkins - initially it would be just multiple versions of the one OAS spec.

[DavidBiesack]

I prefer the Bikeshed version numbering and depth in the TOC. Can ReSpec version be updated so that the sections are not all subsections of 1., and that subsections are numbered? i.e. 1.3.1 Versions should appear as 3.1 Versions, and in the document, the sections numbers also show up ("3.1 Versions" not just "Versions") uniformly in the body. Why is Definitions expanded in the BikeShed TOC but not in ReSpec TOC? TOC / navigation is an important factor.

[MikeRalphson]

@DavidBiesack - both tools have specific mechanisms for generating ToCs. From memory, bikeshed uses the actual headings (but insists they step in and out by one level each time - I believe this is not always the case in the spec. markdown, where headings have sometimes been chosen for their visual appearance, so they are massaged by a pre-processing step). ReSpec requires the use of <section> tags, so these are also added by the pre-processor. No attempt was made to alter the markdown header level nesting to create a ToC with particular numbering - though I'm sure we can iterate on this.

Note: the Bikeshed ToC seems to stutter within the 'Definitions' (sections 3.1.1 and 3.1.1.1) - I'm not sure why this is.

and in the document, the sections numbers also show up ("3.1 Versions" not just "Versions")

I'm not sure I follow this. Both renderings show the section numbers in both the ToC and in the text.

Why is Definitions expanded in the BikeShed TOC but not in ReSpec TOC?

This just seems to be one of the differences between the tools. Both understand definitions and create links to them, but obviously choose to render them in the ToCs differently - some specs may of course have many more definitions than the OAS, perhaps this is a factor?

[MikeRalphson]

@DavidBiesack I've attempted to re-align the ReSpec ToC somewhat. Please take another look.

@darrelmiller It turns out permalink anchors was an optional feature in ReSpec which is off by default. I've enabled this now and re-rendered.

But that "Living Standard" is going to have to go.

@OAI/tsc - do we have a view on the correct 'document status' description for a published version of the OAS?

[darrelmiller]

@MikeRalphson Anchors are excellent. And the new version of Edge made the table rendering in Respec look much better :-)