First skeleton for textual spec #391
Conversation
| @@ -0,0 +1,16 @@ | |||
| This uses [Sphinx](http://www.sphinx-doc.org/). To install that: | |||
There was a problem hiding this comment.
I would normally expect to see some kind of title at the top of a README.md
| .. todo:: | ||
|
|
||
| Describe algorithm, state correctness properties (soundness, completeness) | ||
|
|
| @@ -0,0 +1,3 @@ | |||
| _build | |||
| _static | |||
|
|
|||
|
I've found that @tabatkins' bikeshed works really well for this (much better than rst), and it's used for a bunch of web specs. It link to other specs, does definitions, etc. It's very close to markdown, so it's trivial to learn. I'd really recommend not using rst for this. |
|
@jfbastien, Bikeshed is fine but much less mature. It can neither do formulas or other advanced content, nor produce PDFs, so it does not meet our requirements, I'm afraid. What advantages do you see? |
| } | ||
|
|
||
| a.reference { | ||
| border-bottom: none; |
There was a problem hiding this comment.
Indentation consistency (2 spaces, 1 tab or four spaces), but not all three in one file :P
|
Might this thread bring some light to the discussion? |
How is it not mature? You can embed HTML and do all of that. I don't see PDF as useful, but it'll Just Work. It's a tool designed specifically for specs. Whatever is missing we can add easily (I added some for C++ standards papers). |
|
@jfbastien, mature in the sense that it has more functionality, supports many formats, and is backed by a substantial dev community. Functionality like support for formulas, more layout options, or additional backends is highly non-trivial. |
|
@rossberg-chromium I think you misunderstand how bikeshed works. I recommend chatting with co-Chromie @tabatkins, who's done a pretty great job. In particular, HTML has all you say bikeshed lacks. |
|
@jfbastien, not sure how that addresses the points I mentioned. Sadly, HTML can neither do math nor produce PDFs, you need complex tooling for that, like MathJax and LaTeX. Sphinx has all that integrated at the push of a button. Even if you don't care about either, there are enough people here who do. You haven't explained yet what concrete benefit you see in using Bikeshed. AFAICT, the main thing it provides is some automation for the W3C database. But the Wasm spec needs very little of that, the only standards it has a dependency on are IEEE-754 and (probably in another doc than this one) Ecma-262. |
| @@ -0,0 +1,2 @@ | |||
| _build | |||
There was a problem hiding this comment.
Any particular reason why this is _build as opposed to something like out or build (no underscore)?
This generally looks good to me. I like the PDF option, as I think that makes the spec very professional looking, although the current output haslotsofhorizontallines in the PDF |
|
@titzer, yeah, those lines are from the way it renders todos, which currently are the only content. :) |
rossberg
force-pushed
the
master
branch
2 times, most recently
from
bace049
to
e7632dc
Compare
Why is PDF important? I find it odd that you don't find web pages professional and entirely sufficient, as well as accessible, open, device-scalable, etc. You can link, navigate, it's easily indexed, etc. I'm pretty baffled at making a case for using the web... We're making a thing for the web, and you (and others?) are seriously advocating for PDF? 😕 Math: sure, not perfect, but in my experience rst breaks down severely when you try anything interesting. If math is the only thing you want that's missing (and honestly I don't see why wasm needs much) then I'm happy to bring bikeshed up to speed on that. It already has support for algorithms and railroad diagrams.
So, please, if you don't trust me for some reason, talk to @tabatkins. He works in your team. He's helpful. |
|
|
Sphinx can generate both the HTML and PDF renderings of the same spec. IMO, they both look nice, but PDF is nice for printing out and keeping for reference. |
|
|
|
Hiya @rossberg-chromium! I'm of course biased, as the author of the tool, but yes, it would definitely benefit you to use Bikeshed to write the spec. Maybe I can convince you. ^_^ JF has already provided several reasons, and I'd like to reiterate the linking thing, because it's a unique and central feature of Bikeshed. In any other document processor, you might have some helpful shorthand syntax for linking to things you've defined in the same document. But on the web, you commonly want to link to something defined by another spec. In other processors (including Sphinx), the only way to do this is by manually linking to the term you want, which is fragile, and more importantly, sufficiently annoying that you'll only do it for a handful of "important" things. (This "nobody ever cross-links enough" failure mode was extremely prevalent in web specs for a long time.) Bikeshed is the only processor that maintains a database of cross-spec definitions for the web, letting you link to other specs' terms as easily as you link to internal terms (and if the spec is republished, or the definition moves to another spec, it'll automatically update next time you build the doc). This is really important for writing good web specs. Bikeshed also natively supports markup of IDL, automatically dfn/linking things as appropriate. This is a huge amount of busywork to do on your own (and Sphinx, being designed for Python docs, definitely doesn't do it). There are a number of nice document-hygiene features of Bikeshed, too (and I'm happy to add more linting!). All your definitions and headings get permalinks, as do list items/etc with IDs. Internal links are automatically checked for existence; external links can be checked with a linting option. Algorithms have their variable names typo-checked automatically. Etc. Finally, it supports a large subset of Markdown, which covers everything that reST does, afaict. Now, to your complaints: Math rendering isn't yet built into Bikeshed. I recommend just using KaTeX, which is an extremely fast JS math renderer. You can put that into your boilerplate and never have to think about it again. Porting KaTeX to Python and including it natively in Bikeshed is on the roadmap, tho. PDF generation isn't part of Bikeshed because, well, why? You can print to PDF from any browser; the only thing you would really get from a native generator is a native PDF ToC, but Bikeshed's default styling gives you a side-by-side ToC automatically. (And if you're printing, as @titzer says, you don't even get that PDF function; printing a well-formatted HTML vs PDF is basically identical.) One complaint you didn't voice but that I can see from your example is that Bikeshed doesn't yet support generating multi-page documents from a single source. (It does support the opposite - using several source document for organizational purposes, and combining them into a single output document.) This is also on my roadmap, but has been low priority, as nobody's written a spec yet that really needs multipage support. (And doing it properly involves things like what the HTML multipage spec does, where it intercepts hashes and redirects you to the appropriate page.) |
|
Actually finally, also: Bikeshed is the officially recommended tool of the standards team. Literally everyone else at Google is either using Bikeshed already, or is planning on converting their spec to Bikeshed (usually from ReSpec). Using it means that other Googlers will be familiar with your tooling, and probably already have it installed. There's a good chance that other browser engineers will be familiar with it, too, as it's consuming the W3C right now. |
|
Prodded by @jfbastien, I consulted some standardsy Mozillians today on Bikeshed and they also supported the value of cross-spec linking as @tabatkins is describing above. While I think the core wasm spec will be (on purpose) pretty self-contained, the wasm-to-web bindings (which I'm expecting to help spec-ify from JS.md) will contain a bunch of outward links (esp. once we get to WebIDL bindings), so if we want to play well with the spec ecosystem, I think we should at least use Bikeshed for the bindings portion of the spec (which we've talked about having as some sort of separate "annex" anyway). Now, we could keep the core spec Sphinx (using the bindings annex to, well, bind the wasm spec to the rest of web specs; double binding!) but then we have to ask if it's worth the friction. On a side note: poking around some Bikeshed specs today, I especially like the feature of being able to jump directly from definitions to references; that's something I often want in tc39.github.io/ecma262. |
|
@jfbastien, when I hear that a feature can be added easily or we can fall back to HTML then all my alarm bells go off. Should we really risk blocking on path dependencies? For example, I wasn't even aware that Bikeshed can't do multi-page docs (thanks @tabatkins for pointing out), and proper support for that would likely take considerable time. And raw HTML is not an authoring format, resorting to hacking it manually, even for bits, sounds like the worst possible scenario. There is a lot to be said for using an off-the-shelf solution that requires no work and maintenance on our end (my take-away from Ecma-262 is that that ends up sucking badly). And that properly abstracts from any lower-level output format. I'm not tied to Sphinx specifically, but it has all the features and just works. |
|
@tabatkins, thanks for chiming in. I appreciate your work with Bikeshed, but I'm afraid you haven't quite dispelled my concerns (I wouldn't call them "complaints", since that's not what you designed Bikeshed for). On the other hand, while certainly nice, I'm not sure how most of the specific features you describe will help us. Wasm is not a typical web spec. It doesn't use WebIDL (perhaps it will in the JS API annex, but it's probably not worth it), and there is no other web spec to link into (except Ecma-262 for the annex, which is it's own universe). In fact, I'm not even sure we should frame the core Wasm spec as a web spec at all, as it is (intentionally) completely agnostic to the web, the name notwithstanding. As for PDF: flashy web pages are all great, but PDF is still the gold standard for professional docs, esp offline. Browser-side printing or conversion doesn't cut it, not even close. The result is super-crappy, let alont that it plain doesn't work for multi-page docs. The level of professionalism to aspire to is a LaTeX type-set paper or book, not the typographical horrors of most W3C pages. :) |
|
Folks, how do we want to proceed? May I suggest that we keep going with Sphinx for now and figure out the Bikeshed story in parallel? Most of the markup is similar, so it shouldn't be difficult to convert over later, once we know if and how we can address the functionality gap. I just don't think it makes sense to block on this now -- ideally I'd like to get a draft spec by the end of the year, and this has already cost a week. |
|
I would like to proceed with bikeshed from the start. |
|
This seems like one of those clash-of-worlds problems. In the web standards world, HTML specs are the usual practice, and linkability between specs is enough of a killer feature to make everyone switch to bikeshed (likewise there is little need for math rendering). In language and architecture specs it is much more common for "virtual paper" (or actual paper) be the norm. Wasm may not a be typical web spec, nor is it a typical architecture or VM or language spec. We have use cases from both worlds, so we will end up doing extra work or something that doesn't quite fit the expected use case of whatever toolset we end up using (e.g. math in bikeshed). It's possible that we or someone can update the tools to ensure the extra work is just a one-off. Personally, I can't think of any use case where I would prefer PDF (or maybe even multipage rendering) over what bikeshed generates. That's probably always going to be a personal preference. Also I'm not likely to be the one trying to work around or fix limitations in bikeshed, so maybe my opinion on how significant those limitations are isn't relevant. However, I do not buy the argument that PDF is some sort of gold standard, or that we need typesetting to be "professional", whatever that means. The spec is a product which needs to be useful, and we can argue about the use cases, but appealing to professionalism or that we need to look like paper doesn't cut it (unless you claim that actually printing the spec and using that as a reference is an important use case, in which case I just disagree with you :) ) Other than math and printing, is there requirements or use cases that we have missed? Since it doesn't look like we are just going to get a simple consensus, we should probably specify a little more precisely what the desires and requirements are and how they are met or not met by the various options. That way at least we can argue a little more concretely. |
|
Also, how similar is the markup, really? If it's really as trivial as @rossberg-chromium implies, then could we start out with something that's neither sphinx nor bikeshed, just to get text to review and keep things from getting blocked? |
|
@jfbastien, what is your constructive suggestion then? The absolute minimum of what we need right now is:
PDF is less pressing, but there should be a path forward. I agree with @dschuff that there is a bit of a cultural gap, and language land is different from Web land. Why is that so? For example, a language definition is not just for looking up APIs. First approaching it may require sitting down and just reading it. And yes, for many people that still requires a (printable) document version, as reading long texts via web pages is well-known to be less ergonomic and effective. It's instructive to look at other contenders in this space that have proper specs. I looked at:
There isn't a single one among them that isn't available as a stand-alone document -- usually in PDF, or ePub in case of Apple. (Rust looks like the only recent exception, but its manual explicitly isn't considered a spec yet.) From that perspective, being the outlier would indeed seem somewhat unprofessional. We want to reach these communities, so we should follow standard practice. |
|
Merged following earlier off-line discussion. |
…w_data Fix spec.fix-array.new_data
After some offline discussion, here is a first rough stab at a spec layout and skeleton (all pages are empty right now). For a demo rendering, see:
https://webassembly.github.io/spec/
Some remarks:
Publishing is not automated yet, but there are a couple of possible options (depending on how we want to host).