Document acceptable formats for video macro

[mojavelinux]

Not all video formats can be used with the video tag. Make a note of this in the documentation / writer's guide. Something along the lines of:

The HTML 5 video tag does not support the Quicktime/Sorenson format for video. It first needs to be converted to a "web-friendly" video format. That explains why nothing happens when you press the play button.

The following article is an excellent resource for explaining how to prepare video for an HTML 5 page.

http://www.htmlgoodies.com/html5/client/how-to-embed-video-using-html5.html#fbid=ensvc_rW_lt

You can ignore the parts about the HTML elements since Asciidoctor is already generates that. What's important are the video formats.

* While there are ways to embed Quicktime/Sorenson using object/embed tags, these are considered deprecated and using a web-friendly video format is strongly recommended.

[graphitefriction]

Additional discussion: http://discuss.asciidoctor.org/Including-Vimeo-videos-in-a-document-td492.html

[mojavelinux]

I think the way we should approach this is to downplay the use of local videos for "popular" uses of AsciiDoc (i.e., non-specialty). Serving videos properly is a complex and ever-changing web issue (that's why sites like Vimeo exist). It's not just about getting the video embedded properly, but the fact that it's going to consume tons of bandwidth and browser support is questionable at best.

To summarize, we should encourage the use of the YouTube or Vimeo service in the video macro, citing that this way, the complexity is offloaded to a third-party and portability is highest. Then, we can say that if you are well-versed in self-hosting videos and that is a requirement for your docs, then that's when you want to use the video tag without a service.

[jaredmorgs]

http://asciidoctor.org/docs/user-manual/#video is where this content should go. It is currently not mentioned explicitly, so this guidance needs to be added.

[mojavelinux]

Support for video formats depends on the browser and the year. The best strategy here is to link to a resource that maintains and updates such information. MDN comes to mind. https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats

[jaredmorgs]

Sounds like a good approach. I'll likely take this one once I finish
reading all the other responses from my ticket spam. :P

On Tue, 26 Jan 2016 at 10:33 Dan Allen [email protected] wrote:

Support for video formats depends on the browser and the year. The best
strategy here is to link to a resource that maintains and updates such
information. MDN comes to mind.
https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats

—
Reply to this email directly or view it on GitHub
#79 (comment)
.

Sent from Mobile.

[mojavelinux]

Thanks @jaredmorgs!

[mojavelinux]

Btw, I love MDN. I think we should take notes from that site and model some of our own docs on their practices. I practically live at MDN these days.

[mojavelinux]

Merged as 7298fd1.

I did some minor revisions on the intro and I moved to recommendation to use a hosted service into a TIP.

[mojavelinux]

See http://asciidoctor.org/docs/user-manual/#video.