Port Source Map spec to Bikeshed

[mitsuhiko]

This is a work in progress transformation of the source map v3 with minimal edits to the .bs format, alongside with a Makefile to render it locally (make build and make watch).

Remaining work:

• indexed source maps are not addressed (same spec or separate spec?)
• reintroduce CSS references for sourceMappingURL
• who are the editors / former editors?
• set up github actions / publish to gh-pages

Changes made:

These (with the exception of the change to the URL standard) are marked in the document:

• JSON over HTTP Transport gives no longer relevant historic context to serving JSON over HTTP. Removed that reference but left the permission to prefix source maps with )]}' when served over HTTP.
• Clarified what a column is, specifically that this is counted in UTF-16 offsets which is what most tools do today. Tighten the definition of "column" #5
• Changed the URL reference to the WhatWG URL Standard
• Properly cited "Pavel Podivilov" (previously just mentioned as podivilov@)
• Removed the confusing HTTP header note ("An HTTP header would address this, but is not yet agreed upon.") as a SourceMap header is actually specified in the specification. Refs Do we support Multi-level mapping source map lookups for final source map consumption #11
• Strict reading of the spec allows multiple interpretations for version. I left a marked clarification there. This might be incorrect. See Hardening: version field #26

Followup work:

• Better explain what names is about. Document the meaning of the "names" array #6

Random notes:

• Not sure how the references should be done. Some references like sourceURL link to outdated resources. Maybe put into the spec?
• base64 and VLQ probably should be documented in the spec
• It turns out that web assembly source maps have a different proposed definition of a column. Is this canon? Should this be documented here? Source maps applied to wasm binaries WebAssembly/design#1051

Refs #23

[littledan]

This is a very good starting point--thanks for doing this conversion!

If you're willing to do slightly more editorial work, it'd be nice for discussion if we first landed just the text of source maps v3 (with references fixed up, and it's fine to add notes for TODOs, especially if they point to issues), and then considered clarifications like the definition of columns in PRs on top of that. This would give us a cleaner chance to build consensus as a group as to what we want to do.

(If you don't have time for such a division and just want to land this version, I'd also be OK with that.)

[mitsuhiko]

I can make at least a pass over it and clearly mark the edits and we can review if they are fine or should be backed out. I think that makes sense to do anyways.

//EDIT: i marked the edits. Would you be fine merging it like this? Otherwise I can take them out too. Some minor edits were just necessary to move this from the original google docs format to the annotated spec format (eg: table to list, headlines).

[littledan]

On second thought, can we move over this development to https://github.com/source-map/source-map-spec ? It's nice how that repo has the earlier spec versions for reference, and an explicit license (probably just for temporary use while we find a standards home).

[littledan]

Sounds like you have a preference for including the edits in-line, and no one else is expressing concerns, so I'm happy to land this as you have put it; we can always discuss the changes further later. and the source-map-spec repo contains a Markdown version of v3 for easy reference.

[mitsuhiko]

@littledan my preference for having the edits in-line is mostly just a forcing function :) Do you want me to re-open this on https://github.com/source-map/source-map-spec?