Merge pull request #657 from openlayers/update_documentation

Update integration documentation

README.md

@@ -6,7 +6,8 @@ ES6 modules
 -----------
 
 Since version 2.0, the code is entirely based on ES6 modules and syntax.
-That package requires OpenLayers 5.x.
+It requires OpenLayers 5.x.
+A convenient ES6 package `olcs` is available on npm.
 
 Features
 --------
@@ -30,35 +31,47 @@ Integration in your application
 
 There are several ways to use OL-Cesium in your application.
 
-### As an ES6 library
-
-See the examples for how it was done with webpack. It should work equally well
-with other bundlers, please create an issue if it is not the case. See also the
-[ol-cesium-webpack-example](https://github.com/gberaudo/ol-cesium-webpack-example)
-based on the official Cesium With Webpack example.
-
-### As an old-fashioned independant library (if you are interested, get in touch with us)
+### As an ES6 library (recommended method)
 ```bash
-npm i --save ol-cesium
+npm i --save olcs
 ```
 
-See [old fashioned example](https://openlayers.org/ol-cesium/examples/oldfashioned.html).
+Then import the parts you need. Example:
+```js
+import OLCesium from 'olcs/OLCesium.js';
+const ol3d = new OLCesium({map: ol2dMap}); // ol2dMap is the ol.Map instance
+ol3d.setEnabled(true);
+```
 
-### As an UMD library (need documentation, if you are interested, get in touch with us)
+For Cesium integration see [ol-cesium-webpack-example](https://github.com/gberaudo/ol-cesium-webpack-example)
+based on the official `Cesium With Webpack` example.
 
-Use your webpack / require.js / ... as usual.
+### As an old-fashioned independant library
 
+- build the library in dist/olcs.js:
+```bash
+npm i --save olcs
+npm run build-library
+```
 
-Getting started
---------------
+- get the CSS from css/olcs.css;
 
-An OpenLayers map can be switched to a 3d globe view by running the code below after the map has been created:
+- if needed build a [full OL5 build](https://github.com/geoblocks/legacylib/tree/master/ol5);
+
+- use as follow:
 ```js
-import OLCesium from 'olcs/OLCesium.js';
-const ol3d = new OLCesium({map: map}); // map is the ol.Map instance
+const ol3d = new olcs.OLCesium({map: ol2dMap}); // ol2dMap is the ol.Map instance
 ol3d.setEnabled(true);
 ```
 
+In addition, see the [old fashioned example](https://openlayers.org/ol-cesium/examples/oldfashioned.html).
+
+### As an UMD library (not supported at the moment, if you have propositions get in touch with us)
+
+
+Going further
+-------------
+
 See the [examples](https://openlayers.org/ol-cesium/examples/).
 
 If you are new to Cesium, you should also check the [Cesium tutorials](https://cesiumjs.org/tutorials).
@@ -85,10 +98,12 @@ also loaded.
 Limitations
 -----------
 
-OpenLayers unmanaged layers are not discoverable and as a consequence not
+- OpenLayers unmanaged layers are not discoverable and as a consequence not
 supported. Plain layers should be used instead or the synchronization managed
 manually. See https://github.com/openlayers/ol-cesium/issues/350.
 
+- OpenLayers interactions are not supported in 3d. See https://github.com/openlayers/ol-cesium/issues/655.
+
 Release process
 ---------------