docs: Describe the time zone data generator

Author: prantlf

README.md

@@ -83,7 +83,8 @@ In lieu of a formal styleguide, take care to maintain the existing coding style.
 
 ## Release History
 
-* 2018-11-17   v1.7.0   Include full time zone data separately and data for years 1970-2038.
+* 2018-11-17   v1.8.0   Include time zone data for years 1970-2038.
+* 2018-11-17   v1.7.0   Include full time zone data separately loadable.
 * 2018-11-06   v1.6.0   Upgrade the time zone database to the version 2018g.
 * 2018-10-08   v1.5.5   Fix compatibility with IE. Thanks, [Andrii](https://github.com/AndriiDidkivsky)!
 * 2018-10-06   v1.5.0   Add TypeScript export declarations.

docs/API.md

@@ -21,6 +21,7 @@ This library contains pure, immutable functions to query time zones, convert dat
   - [parseZonedTime](#parsezonedtime)
   - [populateTimeZones](#populatetimezones)
   - [setTimeZone](#settimezone)
+- [Data Generator](#data-generator)
 
 ## Loading
 
@@ -49,7 +50,7 @@ Load the main module in the browser with plain JavaScript:
 </script>
 ```
 
-You can also load a specific version from CDN, for example: https://unpkg.com/timezone-support@1.6.0/dist/index.umd.js.
+You can also load a specific version from CDN, for example: https://unpkg.com/timezone-support@1.8.0/dist/index.umd.js.
 
 ## Modules
 
@@ -428,7 +429,7 @@ const berlinTime = setTimeZone(date, berlin, { useUTC: true })
 // }
 ```
 
-`Date` objects in the last two scenarios are initialized only for formatting or conversion purposes, because other methods, than the date part getters, deliver wrong results. Such "invalid" `Date` instances should exist only temporarily in a restricted scope. They should not be shared widely in the application to prevent mistakes from happening. The local time in a valid `Date` object has to match the UTC time maintained by the same object.
+`Date` objects in the last two scenarios are initialized only for formatting or conversion purposes, because other methods, than the date part getters, deliver wrong results. Such "invalid" `Date` instances should exist only temporarily in a restricted scope. They should not be shared widely in the application to prevent mistakes from  happening. The local time in a valid `Date` object has to match the UTC time maintained by the same object.
 
 ## Data Generator
 
@@ -437,24 +438,26 @@ If you want to [limit the time zone data](#limit-the-loaded-time-zone-data) to i
 ```txt
 Usage: create-timezone-data [options] <first year> <last year>
 
+Generates time zone data for a selected year range.
+
 Options:
   -V, --version             output the version number
   -a, --all-years           includes all available years
   -c, --as-cjs-module       format the time zone data as a CommonJS module
   -d, --as-amd-module       format the time zone data as an AMD module
   -m, --as-module           format the time zone data as a JavaScript module
-  -n, --umd-name            UMD global export name, if not "timeZoneData"
+  -n, --umd-name <name>     UMD global export name, if not "timeZoneData"
   -o, --output-file <file>  write the time zone data to a file
   -u, --as-umd-module       format the time zone data as an UMD module
   -o, --output-file <file>  write the time zone data to a file
   -h, --help                output usage information
 
-Time zone data are printed on the standard output as JSON by default.
+  Time zone data are printed on the standard output as JSON by default.
 
-Examples:
+  Examples:
 
-  $ create-timezone-data 2012 2022
-  $ create-timezone-data -m -o custom-data.js 1970 2038
+    $ create-timezone-data 2012 2022
+    $ create-timezone-data -m -o custom-data.js 1970 2038
 ```
 
 The module generated by this tool exposes a data object as a default export, which is expected bu the function[populatePluralData](#populatepluraldata).

docs/usage.md

@@ -183,8 +183,8 @@ Data for 2012-2022:  27 KB minified,  6.5 KB gzipped
 Custom time zone data can be used if the module `lookup-convert` is loaded instead of the default `index` module.
 
 ```html
-<script src="https://unpkg.com/timezone-support@1.6.0/dist/lookup-convert.umd.js"></script>
-<script src="https://unpkg.com/timezone-support@1.6.0/dist/data-2012-2022.umd.js"></script>
+<script src="https://unpkg.com/timezone-support@1.8.0/dist/lookup-convert.umd.js"></script>
+<script src="https://unpkg.com/timezone-support@1.8.0/dist/data-2012-2022.umd.js"></script>
 <script>
   (() => {
     const { populateTimeZones, findTimeZone, getZonedTime } = window['timezone-lookup-convert']
@@ -202,7 +202,7 @@ Custom time zone data can be used if the module `lookup-convert` is loaded inste
 If you want to use the time zone data for years 2012-2022 published by this project, you can simplify your code by using a bundled package with both data and code.
 
 ```html
-<script src="https://unpkg.com/timezone-support@1.6.0/dist/index-2012-2022.umd.js"></script>
+<script src="https://unpkg.com/timezone-support@1.8.0/dist/index-2012-2022.umd.js"></script>
 <script>
   (() => {
     const { findTimeZone, getZonedTime } = window['timezone-support']
@@ -236,4 +236,54 @@ See the function [populateTimeZones](./API.md#populatetimezones) for more inform
 
 ## Generate custom time zone data
 
+Except for the time zone data for the three year spans bundled with this module, other data modules can be generated to customize the year span and thus the overall package size. There is a command line tool [`create-timezone-data`](./API.md#data-generator) for this included in this package.
+
+For example, you can generate time zone data for years 1978-2028 and save it to the module `data-1978-2028.js` in the CommonJS format, which you wil bundle to your application:
+
+```sh
+create-timezone-data -c -o custom-data-1978-2028.js 1978 2028
+```
+
+And then load them instead of the default full time zone data. You need to require `timezone-support/dist/lookup-convert` instead of `timezone-support` everywhere in your application and populate the library with the custom data, when your application starts:
+
+```js
+const { populateTimeZones } = require('timezone-support/dist/lookup-convert')
+const data = require('./data-1978-2028')
+
+populateTimeZones(data)
+```
+
+Let us have alook, how the same would work in an application loading their assets directly in the browser. You would generate a UMD module instead:
+
+```sh
+create-timezone-data -u -o custom-data-1978-2028.js -n timeZoneData10782028 1978 2028
+```
+
+And then load them at the beginning of a plain JavaScript application:
+
+```html
+<script src="https://unpkg.com/timezone-support/dist/lookup-convert.umd.js"></script>
+<script src="./data-1978-2028.js"></script>
+<script>
+  (() => {
+    const { populateTimeZones } = window['timezone-lookup-convert']
+
+    populateTimeZones(window.timeZoneData10782028)
+  })()
+</script>
+```
+
+Or load it in an application using AMD modules:
+
+```html
+<script src="https://unpkg.com/requirejs/require.js"></script>
+<script src="https://unpkg.com/timezone-support/dist/lookup-convert.umd.js"></script>
+<script src="./data-1978-2028.js"></script>
+<script>
+  require(['timezone-lookup-convert', 'timeZoneData10782028'], function (tz, data) {
+    tz.populateTimeZones(data)
+  })()
+</script>
+```
+
 [IANA time zone database]: https://www.iana.org/time-zones

package-lock.json

@@ -7,6 +7,9 @@
     "email": "[email protected]",
     "url": "http://prantl.tk"
   },
+  "contributors": [
+    "CrisColamb <[email protected]>"
+  ],
   "license": "MIT",
   "licenses": [
     {