Update readme Add examples section

readme.md

@@ -56,14 +56,35 @@ Then:
 ## Add examples
 
 The examples are located in the `examples` directory. Adding a new example
-implies creating two files in this directory, a `.html` file and `.js` file.
+implies creating two files in this directory, an `.html` file and a `.js` file.
 See `examples/full-screen.html` and `examples/full-screen.js` for instance.
 
 The `.html` file needs to include a script tag with
 `loader.js?id=<example_name>` as its `src`. For example, if the two files for
-the examples are `myexample.js` and `myexample.html` then `id` should be set to
-`myexample` in the `loader.js` URL.
+the example are `myexample.js` and `myexample.html` then the script tag's `src`
+should be set to `myexample`.
 
 `build.py serve` should be stopped and restarted for the
-`loader.js?id=<example_name>` script tag to refer to a valid URL. `build.py serve`
-triggers the `examples` target which creates Plovr JSON file for each example.
+`loader.js?id=<example_name>` script tag to refer to a valid URL. `build.py
+serve` triggers the `examples` target which creates a Plovr JSON file for each
+example.
+
+A note on the use of the `goog` namespace in the examples:
+
+Short story: the OL3 examples should not use the `goog` namespace, except
+for `goog.require`.
+
+Longer story:
+
+We want that the OL3 examples work in multiple modes: with the standalone lib
+(which has implications of the symbols and properties we export), with Plovr in
+ADVANCED mode, and with Plovr in RAW (debug) mode.
+
+Running the examples with Plovr makes it mandatory to declare dependencies with
+`goog.require` statements. And for the examples to also run with the standalone
+lib we [export](https://github.com/openlayers/ol3/blob/master/src/goog.exports)
+`goog.require` as the null function.
+
+Exporting `goog.require` has a side effect: it adds the `goog` namespace object
+to the global object. This is why we can, for example, have `if (goog.DEBUG)`
+statements in the code of the examples.