From 452e977e2b58ab67f20ab971fddf470c2fe24a8d Mon Sep 17 00:00:00 2001
From: "L. Krause" <eska@eska.me>
Date: Sun, 16 Jul 2017 15:17:42 +0200
Subject: [PATCH] Update and clarify HTML5 doc

(cherry picked from commit 734db354d187d1d024e228f0280a7d4f83bdacf7)
---
 .../workflow/export/exporting_for_web.rst     | 54 +++++++++++++------
 1 file changed, 38 insertions(+), 16 deletions(-)

diff --git a/learning/workflow/export/exporting_for_web.rst b/learning/workflow/export/exporting_for_web.rst
index 7c4b04ab7..4c516abab 100644
--- a/learning/workflow/export/exporting_for_web.rst
+++ b/learning/workflow/export/exporting_for_web.rst
@@ -12,6 +12,11 @@ parts of the canvas when the browser window is scaled to the game's dimensions.
 This way it can be inserted into an ``<iframe>`` with the game's size, as is
 common on most web game hosting sites.
 
+Web export uses *asm.js*, a highly optimizable subset of JavaScript.
+A 64-bit browser is required to run games in asm.js format. Most notably,
+this is a problem with Firefox, which on Windows is shipped as a
+32-bit application by default.
+
 Serving the files
 -----------------
 
@@ -21,8 +26,11 @@ It can also be inserted into another HTML file as an ``<iframe>`` element.
 Users must allow **third-party** cookies when playing a game presented in an
 iframe.
 
-The ``.mem`` and ``.pck`` files are binary, usually delivered with MIME-type
-``application/octet-stream``.
+The other exported files are served as they are next to the ``.html`` file,
+names unchanged.
+
+The ``.mem`` and ``.pck`` files are binary, usually delivered with the
+MIME-type ``application/octet-stream``.
 
 Delivering the files with gzip compression is recommended especially for the
 ``.pck``, ``.asm.js`` and ``.mem`` files, which are usually large in size.
@@ -63,23 +71,37 @@ output display in debug mode and a fullscreen button.
 In the default page, the controls are displayed in the top-right corner on top
 of the canvas, which can get in the way in games that use the cursor.
 
-Security restrictions
----------------------
+Web export limitations
+----------------------
 
-Browsers do not allow arbitrarily **entering full screen** at any time.
-Instead, these actions have to occur as a response to a JavaScript input event.
-In Godot, this is most easily done by entering full screen from within an
-``_input()`` callback.
+Exported files must not be reused
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Chromium-derived browsers will not load exported projects when
-**opened locally** per ``file://`` protocol. To get around this, you can start
-the browser with the ``--allow-file-access-from-files`` flag, or use a local
-server. Python offers an easy way for this, using ``python -m SimpleHTTPServer``
-with Python 2 or ``python -m http.server`` with Python 3 will serve the
-current working directory on ``http://localhost:8000``.
+The exported files ending with ``.html`` and ``fs.js`` are adjusted on export
+specifically for that game's version and the given export options. They must
+not be reused in futher exports.
 
-Locale
-------
+Some functions must be called from input callbacks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Browsers do not allow arbitrarily **entering full screen** at any time. The same
+goes for **capturing the cursor**. Instead, these actions have to occur as a
+response to a JavaScript input event. In Godot, this is most easily done by
+entering full screen from within an input callback such as ``_input`` or
+``_unhandled_input``.
+
+Starting exported games from the local file system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many browsers will not load exported projects when **opened locally**
+per ``file://`` protocol. To get around this, use a local server.
+
+Python offers an easy method for this, using ``python -m SimpleHTTPServer``
+with Python 2 or ``python -m http.server`` with Python 3 will serve the current
+working directory on ``http://localhost:8000``.
+
+Locale lookup
+~~~~~~~~~~~~~
 
 Godot tries to detect the user's locale using information provided by the
 browser, but this is rather unreliable. A better way is to use CGI to read the