Migrate spec text to bikeshed.

[yellowdoge]

This PR addresses #53, by:

• Adding index.bs with the same contents as 03 Nov 2016 ED;
• Adding a compiled index.html;
• Removing fromelement.js and fromelement.css.
• Removing .travis.yml

For the curious/impatient (like me!), an instantaneous rendering can be found at http://rawgit.com/Miguelao/mediacapture-fromelement/pr3__bikeshed/index.html

[yellowdoge]

@uysalere I couldn't add you to the reviewers list -- please comment on this migration.

[martinthomson]

I'm against this. Can you explain why you think this is necessary?

For me, aside from the questionable benefits provided by BS, there are material downsides. Critically, it requires that people contributing patches also update the HTML, which makes PRs harder to both create and review.

[yellowdoge]

With pleasure.

The number 1 reason for me is that the .bs version is better at producing a legible specification, since most of the links to e.g. HTMLVideoElement can be simplified as {{HTMLVideoElement}}, {{HTMLVideoElement/ended}} etc, versus the ultra-verbose <a href="...">. Having a mix of markup, links and text makes the Spec hard to read and, specially, to maintain.

PR reviews also suffer with the current verbose situation since, for reviewers like yourselves, comparing the wording turns into an obstacle race for the eyes. For example, the table of contents now is incorrect, but none of us has seen it because the section headers are buried in the markup.

Re. The added friction that you comment on the second paragraph. A simple line is enough to compile bikeshed to html (from the README.md): curl https://api.csswg.org/bikeshed/ -F file=@index.bs -F force=1 > index.html so IMHO it's a price worth paying. Bikeshed is used pervasively in WICG specs and in MediaRecorder and ImageCapture Specs of this WG. We even have the boilerplate in place (https://github.com/tabatkins/bikeshed/pull/891) thanks to @dontcallmedom .

@alvestrand mentioned the possibility of a Travis job to generate the .html from the .bs and compare to the uploaded one to confirm that the user had not forgotten the compilation. That would address your concerns, right?

[martinthomson]

generate the .html from the .bs and compare to the uploaded one to confirm that the user had not forgotten the compilation. That would address your concerns, right?

Not really. It would help with policing the now awful situation, but it makes it harder to get contributions because contributors need to run bs.

BTW, that line is not simple, give me a script.

[yellowdoge]

As another comparison, let me put together two paragraphs, one in the current Spec (https://github.com/w3c/mediacapture-fromelement/blob/gh-pages/index.html#L76):

    <p>
      Both <code>MediaStream</code> and <code>HTMLMediaElement</code> expose the
      concept of a <q>track</q>.  Since there is no common type used for
      <code>HTMLMediaElement</code>, this document uses the term
      <dfn>track</dfn> to refer to either <code><dfn><a href="http://www.w3.org/TR/html5/embedded-content-0.html#videotrack">VideoTrack</a></dfn></code>
      or <code><dfn><a href="http://www.w3.org/TR/html5/embedded-content-0.html#audiotrack">AudioTrack</a></dfn></code>.
      <code><dfn><a href="https://w3c.github.io/mediacapture-main/#idl-def-MediaStreamTrack">MediaStreamTrack</a></dfn></code>
      is used to identify the media in a <code><dfn><a href="https://w3c.github.io/mediacapture-main/#idl-def-MediaStream">MediaStream</a></dfn></code>.
    </p>

versus Bikeshed:

Both {{MediaStream}} and {{HTMLMediaElement}} expose the concept of a <code>track</code>. 
Since there is no common type used for {{HTMLMediaElement}}, this document uses the term
<dfn>track</dfn> to refer to either a {{VideoTrack}} or an {{AudioTrack}}.
{{MediaStreamTrack}}  is used to identify the media in a {{MediaStream}}.

@martinthomson, you mention as a negative point that Bikeshed needs an extra cycle of compilation, however the current Spec suffers from the possibility of uploading a Respec incomplete HTML, e.g. some <dfn>s are incomplete in the current Spec:

No <dfn> for HTMLMediaElement.
No <dfn> for captureStream in HTMLCanvasElement.
No <dfn> for HTMLCanvasElement.

and

[yellowdoge]

Ping.

[yellowdoge]

@martinthomson ping and I learned how to run a Travis job to compile automagically bs --> html, with that, do you have any other concerns preventing the migration?

[martinthomson]

That would make me much happier.

[yellowdoge]

ping dontcallmedom@

[yellowdoge]

@martinthomson I finally landed the auto-compile-bikeshed-and-commit-to-gh-pages for both mediacapture-record and mediacapture-image specs, fully automatic etc. The .bs file would go to master and a travis job would compile that file and automatically check it into gh-pages (@dontcallmedom RS this process).

I can go ahead and do it here, but since the only way to try it out is by doing, it'll replace the current index.html; do I have you lgtm? (I will give you guys a heads up). Or I can start by landing the .travis.yml etc, here in this PR, but leave commented out the actual ssh-commit to gh-pages, whichever you prefer.