docs: updates to faq, language guide and minor edits

docs/guides/debugging.md

@@ -12,7 +12,7 @@
 
 ## Logging
 
-Video.js includes a lightweight wrapper - `videojs.log` - around a subset of [the `console` API][console]. The available methods are `videojs.log`, `videojs.log.warn`, and `videojs.log.error`.
+Video.js includes `videojs.log`, a lightweight wrapper around a subset of [the `console` API][console]. The available methods are `videojs.log`, `videojs.log.warn`, and `videojs.log.error`.
 
 ### API Overview
 

docs/guides/event-target.md

@@ -10,7 +10,7 @@
 
 ## Overview
 
-Events in video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
+Events in Video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
 
 ## `on()` and `addEventListener()`
 

docs/guides/hooks.md

@@ -1,6 +1,6 @@
 # Hooks
 
-Hooks exist so that users can "hook" on to certain video.js player lifecycle
+Hooks exist so that users can "hook" on to certain Video.js player lifecycle
 
 ## Table of Contents
 
@@ -20,21 +20,21 @@ Currently, the following hooks are avialable:
 
 `beforesetup` is called just before the player is created. This allows:
 
-* modification of the options passed to the video.js function (`videojs('some-id, options)`)
+* modification of the options passed to the Video.js function (`videojs('some-id, options)`)
 * modification of the dom video element that will be used for the player
 
 `beforesetup` hook functions should:
 
 * take two arguments
-  1. videoEl: dom video element that video.js is going to use to create a player
-  1. options: options that video.js was intialized with and will later pass to the player during creation
-* return options that will merge and override options that video.js with intialized with
+  1. videoEl: dom video element that Video.js is going to use to create a player
+  1. options: options that Video.js was intialized with and will later pass to the player during creation
+* return options that will merge and override options that Video.js with intialized with
 
 Example: adding beforesetup hook
 
 ```js
 var beforeSetup = function(videoEl, options) {
-  // videoEl.id will be some-id here, since that is what video.js
+  // videoEl.id will be some-id here, since that is what Video.js
   // was created with
 
   videoEl.className += ' some-super-class';
@@ -58,16 +58,16 @@ videojs('some-id', {autoplay: true, controls: true});
 
 `setup` is called just after the player is created. This allows:
 
-* plugin or custom functionalify to intialize on the player
+* plugin or custom functionality to intialize on the player
 * changes to the player object itself
 
 `setup` hook functions:
 
 * Take one argument
-  * player: the player that video.js created
+  * player: the player that Video.js created
 * Don't have to return anything
 
-Example: adding setup hook
+Example: adding a setup hook
 
 ```js
     var setup = function(player) {
@@ -76,7 +76,7 @@ Example: adding setup hook
     };
     var foo = function() {};
 
-    videojs.plugin('foo', foo);
+    videojs.registerPlugin('foo', foo);
     videojs.hook('setup', setup);
     var player = videojs('some-id', {autoplay: true, controls: true});
 ```
@@ -85,7 +85,7 @@ Example: adding setup hook
 
 ### Adding
 
-In order to use hooks you must first include video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
+In order to use hooks you must first include Video.js in the page or script that you are using. Then you add hooks using `videojs.hook(<name>, function)` before running the `videojs()` function.
 
 Example: adding hooks
 
@@ -102,13 +102,13 @@ videojs.hook('setup', function(player) {
 var player = videojs('vid1', {autoplay: false});
 ```
 
-After adding your hooks they will automatically be run at the correct time in the video.js lifecycle.
+After adding your hooks they will automatically be run at the correct time in the Video.js lifecycle.
 
 ### Getting
 
-To access the array of hooks that currently exists and will be run on the video.js object you can use the `videojs.hooks` function.
+To access the array of hooks that currently exists and will be run on the Video.js object you can use the `videojs.hooks` function.
 
-Example: getting all hooks attached to video.js
+Example: getting all hooks attached to Video.js
 
 ```js
 var beforeSetupHooks = videojs.hooks('beforesetup');
@@ -117,7 +117,7 @@ var setupHooks = videojs.hooks('setup');
 
 ### Removing
 
-To stop hooks from being executed during the video.js lifecycle you will remove them using `videojs.removeHook`.
+To stop hooks from being executed during the Video.js lifecycle you will remove them using `videojs.removeHook`.
 
 Example: remove a hook that was defined by you
 

docs/guides/languages.md

@@ -1,8 +1,9 @@
 # Languages
 
-Multiple language support allows for users of non-English locales to natively interact with the Video.js player.
+Video.js includes localization support to present text in a language other than the default English where appropriate.
 
-For an up-to-date list of the languages Video.js supports, see the [languages folder (`lang`)][lang-supported]. These JSON files are converted to JavaScript during the Video.js build process.
+For an up-to-date list of the languages Video.js supports, see the [languages folder (`lang`)][lang-supported].
+Some translations may be less complete than others - see the [translations needed doc][translations-needed] for a table of strings that are missing from the translations available.  Contributions are welcome to update those that are incomplete.
 
 ## Table of Contents
 
@@ -22,7 +23,9 @@ For an up-to-date list of the languages Video.js supports, see the [languages fo
 
 ## Using Video.js Languages
 
-Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files. Each of these files can be included in a web page to provide support for that language in _all_ Video.js players:
+Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files.
+Add the lang script for each language you need to support.
+Each of these files can be included in a web page to provide support for that language in _all_ Video.js players:
 
 ```html
 <script src="//example.com/path/to/video.min.js"></script>
@@ -31,7 +34,7 @@ Video.js ships with multiple translations (in `dist/lang/`) in JavaScript files.
 
 ## Contributing to Video.js Translations
 
-We welcome new translations and improvements to existing ones! Please see the [contributing document](../../CONTRIBUTING.md) to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js...
+We welcome new translations and improvements to existing ones! Please see the [contributing document](../../CONTRIBUTING.md) to get started contributing to Video.js and continue reading for specifics on how to contribute to translations of Video.js.
 
 ### JSON Format
 
@@ -50,11 +53,9 @@ Video.js uses a JSON object to describe a language, where the keys are English a
 
 ### File Naming
 
-Translations are always found in the `lang/` directory.
+Translations are found in the `lang/` directory.
 
-Each file's name should be the [standard language code][lang-codes] that is most appropriate. For example, "es" for Spanish or "zh-CN" for Chinese.
-
-Finally, each file's extension is always `.json`.
+Each file's name should be the [standard language code][lang-codes] that is most appropriate, with a `.json` extension. For example, "es.json" for Spanish or "zh-CN.json" for simplified Chinese.
 
 ### Updating an Existing Translation
 
@@ -80,60 +81,59 @@ cp lang/en.json lang/${NEW_LANG_CODE}.json
 
 Otherwise, the process is the same as [updating an existing translation](#updating-an-existing-translation).
 
-## Advanced Language Usage
-
-The instructions above for [using Video.js languages](#using-videojs-languages) should be sufficient for the majority of use-cases. However, languages can be provided at runtime.
-
-In each case, these custom language definitions _take precedence over any Video.js-provided languages!_
-
 ### Adding Languages via the API
 
 In addition to the stand-alone scripts provided by Video.js, the API supports manual definition of new languages via the `addLanguage` method. It takes two arguments: the [standard language code][lang-codes] and a [language definition object](#json-format).
 
 ```js
 videojs.addLanguage('es', {
-  'Play': 'Reproducción',
-  'Pause': 'Pausa',
+  Play: 'Reproducción',
+  Pause: 'Pausa',
   'Current Time': 'Tiempo reproducido',
   'Duration Time': 'Duración total',
   'Remaining Time': 'Tiempo restante',
   ...
 });
 ```
 
-### Per-Player Languages
+`addLanguage()` will overwrite existing translations if the object includes strings previously translated. However text that has already been localised will not be updated after generation.
+
+### Per-Player Translations
 
 In addition to providing languages to Video.js itself, individual `Player` instances can be provided custom language support via [the `languages` option](/docs/guides/options.md#languages):
 
 ```js
 // Provide a custom definition of Spanish to this player.
 videojs('my-player', {
   languages: {
-    es: {...}
+    es: {
+      Play: 'Reproducir'
+    }
   }
 });
 ```
 
-### Setting Default Player Language
+### Setting Player Language
 
-Player instances can also have a default language via [the `language` option](/docs/guides/options.md#language):
+The language used by a player instance may be set via [the `language` option](/docs/guides/options.md#language):
 
 ```js
-// Set the default language to Spanish for this player.
+// Set the language to Spanish for this player.
 videojs('my-player', {
   language: 'es'
 });
 ```
 
-Additionally, the `language` method of the player can be used to set the language after instantiation (e.g., `language('es')`). However, this is not recommended as it does not update the UI in place. _Setting the language via options is always preferred._
+The `language` method of the player _can_ be used to set the language after instantiation with `language('es')`. However, this is generally not useful as it does not update text that is already in place.
 
 ### Determining Player Language
 
 The player language is set to one of the following in descending priority:
 
 * The language [specified in options](#setting-default-player-language)
-* The language specified by the closest element with a `lang` attribute. This could be the player itself or a parent element. Usually, the document language is specified on the `<html>` tag.
-* Browser language preference; the first language if more than one is configured
+* The language specified by a `lang` attribute on the player element.
+* The language specified by the closest parent element with a `lang` attribute, up to and including the `<html>` element.
+* The browser language preference; the first language if more than one is configured
 * English
 
 #### Internal Language Selection
@@ -147,10 +147,12 @@ For information on translation/localization in plugins, see [the plugins guide](
 
 Standard languages codes [are defined by the IANA][lang-codes].
 
-For all existing/supported languages, please see the [languages lolder (`lang/`)][lang-supported] folder located in the project root.
+For all existing/supported languages, please see the [languages folder (`lang/`)][lang-supported] folder located in the project root.
 
 [lang-en]: /lang/en.json
 
 [lang-supported]: /lang
 
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
+
+[translations-needed]: https://github.com/videojs/video.js/blob/master/docs/translations-needed.md

docs/guides/options.md

@@ -36,8 +36,13 @@
   * [${componentName}](#componentname)
 * [Tech Options](#tech-options)
   * [${techName}](#techname)
+  * [flash](#flash)
+    * [swf](#swf)
+  * [html5](#html5)
     * [nativeControlsForTouch](#nativecontrolsfortouch-1)
+    * [nativeAudioTracks](#nativeaudiotracks)
     * [nativeTextTracks](#nativetexttracks)
+    * [nativeVideoTracks](#nativevideotracks)
 
 ## Standard `<video>` Element Options
 
@@ -205,47 +210,24 @@ See [the plugins guide][plugins] for more information on Video.js plugins.
 
 ### `sourceOrder`
 
-> Type: `boolean`, Default: `false`
+> Type: `boolean`, Default: `true`
 >
-> **Note:** In video.js 6.0, this option will default to `true`. and that [videojs-flash](https://github.com/videojs/videojs-flash) will be required to use the flash tech.
+> **Note:** In Video.js 6.0, this option will default to `true`. and that [videojs-flash](https://github.com/videojs/videojs-flash) will be required to use the flash tech.
 
 Tells Video.js to prefer the order of [`sources`](#sources) over [`techOrder`](#techorder) in selecting a source and playback tech.
 
-Given the following example:
+The default algorithm is:
 
-```js
-videojs('my-player', {
-  sourceOrder: true,
-  sources: [{
-    src: '//path/to/video.flv',
-    type: 'video/x-flv'
-  }, {
-    src: '//path/to/video.mp4',
-    type: 'video/mp4'
-  }, {
-    src: '//path/to/video.webm',
-    type: 'video/webm'
-  }],
-  techOrder: ['html5', 'flash']
-});
-```
-
-Normally, the fact that HTML5 comes before Flash in the `techOrder` would mean Video.js would look for a compatible _source_ for HTML5 and would pick either the MP4 or WebM video (depending on browser support) only falling back to Flash if no compatible source for HTML5 was found.
-
-However, because the `sourceOrder` is `true`, Video.js flips that process around. It will look for a compatible _tech_ for each source in order. Presumably, it would first find a match between the FLV (since it's first in the source order) and the Flash tech.
+* for each source:
+  * for each tech:
+    * if tech can play source, use this tech/source combo
 
-In summary, the default algorithm is:
+With `sourceOrder: false`, the algorithm becomes:
 
 * for each tech:
   * for each source:
     * if tech can play source, use this tech/source combo
 
-With `sourceOrder: true`, the algorithm becomes:
-
-* for each source:
-  * for each tech:
-    * if tech can play source, use this tech/source combo
-
 ### `sources`
 
 > Type: `Array`
@@ -285,7 +267,7 @@ Defines the order in which Video.js techs are preferred. By default, this means
 
 Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for `WebVTT`.
 
-This option will be used in the "novtt" build of video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with video.js.
+This option will be used in the "novtt" build of Video.js (i.e. `video.novtt.js`). Otherwise, vtt.js is bundled with Video.js.
 
 ## Component Options
 
@@ -346,7 +328,11 @@ videojs('my-player', {
 
 Video.js playback technologies (i.e. "techs") can be given custom options as part of the options passed to the `videojs` function. They should be passed under the _lower-case variant of the tech name_ (e.g. `"flash"` or `"html5"`).
 
-This is not used in most implementations, but one case where it may be is dictating where the Video.js SWF file is located for the `Flash` tech:
+### `flash`
+
+#### `swf`
+
+Specifies where the Video.js SWF file is located for the `Flash` tech:
 
 ```js
 videojs('my-player', {
@@ -356,24 +342,38 @@ videojs('my-player', {
 });
 ```
 
-However, this is a case where changing the global defaults is more useful:
+However, changing the global defaults is generally more appropriate:
 
 ```js
 videojs.options.flash.swf = '//path/to/videojs.swf'
 ```
 
+### `html5`
+
 #### `nativeControlsForTouch`
 
 > Type: `boolean`
 
 Only supported by the `Html5` tech, this option can be set to `true` to force native controls for touch devices.
 
+#### `nativeAudioTracks`
+
+> Type: `boolean`
+
+Can be set to `false` to disable native audio track support. Most commonly used with [videojs-contrib-hls][videojs-contrib-hls].
+
 #### `nativeTextTracks`
 
 > Type: `boolean`
 
 Can be set to `false` to force emulation of text tracks instead of native support. The `nativeCaptions` option also exists, but is simply an alias to `nativeTextTracks`.
 
+#### `nativeVideoTracks`
+
+> Type: `boolean`
+
+Can be set to `false` to disable native video track support. Most commonly used with [videojs-contrib-hls][videojs-contrib-hls].
+
 [plugins]: /docs/guides/plugins.md
 
 [languages]: /docs/guides/languages.md
@@ -383,3 +383,5 @@ Can be set to `false` to force emulation of text tracks instead of native suppor
 [lang-codes]: http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
 
 [video-attrs]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#Attributes
+
+[videojs-contrib-hls]: https://github.com/videojs/videojs-contrib-hls