Refine documentation

README.md

@@ -5,65 +5,109 @@ Paged.js - Paged Media Tools
 
 Paged.js is an open-source library to display paginated content in the browser and to generate print books using web technology.
 
-It contains a set of handlers for CSS transformations and fragmented layout which polyfill the [Paged Media](https://www.w3.org/TR/css-page-3/) and [Generated Content](https://www.w3.org/TR/css-gcpm-3/) CSS modules, along with hooks to create new handlers for custom properties.
+It contains a set of handlers for CSS transformations and fragmented layout which polyfill the [CSS Paged Media][] and [CSS Generated Content][] CSS modules, along with hooks to create new handlers for custom properties.
 
 The currently supported properties can be found on [the wiki](https://gitlab.pagedmedia.org/tools/pagedjs/wikis/Support-of-specifications).
 
 A quick overview to getting started with Paged Media CSS and Paged.js is available on [pagedmedia.org](https://www.pagedmedia.org/paged-js/).
 
-## NPM Module
-```sh
-$ npm install pagedjs
-```
+## Install
 
-```js
-import { Previewer } from 'pagedjs';
+Paged.js is available via a CDN like [jsDelivr][] or [unpkg][] for a quick use.
+See below for how to use it.
 
-let paged = new Previewer();
-let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
-	console.log("Rendered", flow.total, "pages.");
-})
+You can also integrate Paged.js with your toolchain [via NPM][npm].
+
+```bash
+$ npm install pagedjs
 ```
 
+
 ## Polyfill
 
-Add the the `paged.polyfill.js` script to replace all `@page` css and render the html page with the Paged Media styles applied:
+The polyfill is the easiest way to replace all `@page` css. It renders the html page according to the [CSS Paged Media][] spec.
+The polyfill runs automatically as soon as the DOM is ready.
 
 ```html
 <script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
 ```
 
-Try the [polyfill with Aurorae](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html).
+See it in action with the [Aurorae book](https://s3.amazonaws.com/pagedmedia/pagedjs/examples/polyfill.html).
+
+Use the `auto` configuration property of the `PagedConfig` object to render only when `PagedPolyfill.preview()` is called.
+
+```html
+<script>
+	// disable the polyfill before loading its script
+	window.PagedConfig = {
+		auto: false
+	};
+</script>
+<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
+<script>
+	// do something else
+	// ...
+
+	// then runs the pollyfill manually
+	PagedPolyfill.preview();
+</script>
+```
 
-By default the polyfill will run automatically as soon as the DOM is ready.
-However, you can add an async `before` function or return a Promise to delay the polyfill starting.
+Alternativelly, delay the rendering until the `before` configuration property of the `PagedConfig` object is resolved.
 
 ```html
 <script>
 	window.PagedConfig = {
 		before: () => {
-			return new Promise(resolve, reject) {
-				setTimeout(() => { resolve() }, 1000);
+			return new Promise(resolve) {
+				// do something before the rendering
+				// ...
+
+				// then runs the polyfill
+				resolve();
 			}
-		},
-		after: (flow) => { console.log("after", flow) },
+		}
 	};
 </script>
+<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
 ```
 
-Otherwise you can disable `auto` running the previewer and call `window.PagedPolyfill.preview();`
-whenever you want to start.
+### ECMAScript Module
 
 ```html
 <script>
 	window.PagedConfig = {
 		auto: false
-		after: (flow) => { console.log("after", flow) },
 	};
+</script>
+<script>
+	import PagedPolyfill from 'https://unpkg.com/pagedjs/dist/paged.polyfill.esm.js';
 
-	setTimeout(() => {
-		window.PagedPolyfill.preview();
-	}, 1000);
+	// ...
+
+	PagedPolyfill.preview();
+</script>
+```
+
+## Previewer
+
+```js
+import { Previewer } from 'pagedjs';
+
+let paged = new Previewer();
+let flow = paged.preview(DOMContent, ["path/to/css/file.css"], document.body).then((flow) => {
+	console.log("Rendered", flow.total, "pages.");
+});
+```
+
+### ECMAScript Module
+
+```html
+<script type="module">
+	import { Previewer } from 'https://unpkg.com/pagedjs/dist/paged.polyfill.esm.js';
+
+	let paged = new Previewer();
+	// ...
 </script>
 ```
 
@@ -84,7 +128,7 @@ Examples:
 
 ### CLI
 
-Command line interface to render out PDFs of HTML files using Puppeteer: [https://gitlab.pagedmedia.org/polyfills/pagedjs-cli](https://gitlab.pagedmedia.org/polyfills/pagedjs-cli).
+[`pagedjs-cli`](https://gitlab.pagedmedia.org/polyfills/pagedjs-cli) is a command line interface to render out PDFs of HTML files. It uses [Puppeteer][] under the hood.
 
 ## Modules
 
@@ -93,9 +137,10 @@ Modules are groups of handlers for that apply the layout and styles of a CSS mod
 New handlers can be registered from `import { registerHandlers } from 'pagedjs'` or by calling `Paged.registerHandlers` on an html page.
 
 ```html
-<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
-<script>
-	class MyHandler extends Paged.Handler {
+<script type="module">
+	import {Handler, registerHandlers} from 'https://unpkg.com/pagedjs/dist/paged.polyfill.esm.js';
+
+	class MyHandler extends Handler {
 		constructor(chunker, polisher, caller) {
 			super(chunker, polisher, caller);
 		}
@@ -104,7 +149,8 @@ New handlers can be registered from `import { registerHandlers } from 'pagedjs'`
 			console.log(pageFragment);
 		}
 	}
-	Paged.registerHandlers(MyHandler);
+
+	registerHandlers(MyHandler);
 </script>
 ```
 
@@ -135,14 +181,15 @@ onOverflow(overflow, rendered, bounds)
 onBreakToken(breakToken, overflow, rendered)
 ```
 
-## Setup
+## Local Development
+
 Install dependencies
 ```sh
 $ npm install
 ```
 
-## Development
 Run the local dev-server with livereload and autocompile on [http://localhost:9090/](http://localhost:9090/)
+
 ```sh
 $ npm start
 ```
@@ -220,12 +267,12 @@ npm run specs -- --updateSnapshot
 
 ### Docker
 
-A `pagedmedia/pagedjs` docker image contains all the dependencies needed to run the `pagedjs` development server, as well as the pdf comparison tests.
+A [`pagedmedia/pagedjs` docker image][docker-image] contains all the dependencies needed to run the `pagedjs` development server, as well as the pdf comparison tests.
 
 To build the image run
 
 ```bash
-docker build -t pagedmedia/pagedjs .  
+docker build -t pagedmedia/pagedjs .
 ```
 
 By default the container will run the development server with `npm start`
@@ -248,3 +295,13 @@ The core team behind paged.js includes [Adam Hyde](https://adamhyde.net), [Julie
 ## Licence
 
 MIT License (MIT), which you can read [here](https://gitlab.pagedmedia.org/tools/pagedjs/blob/master/LICENSE.md)
+
+
+[CSS Paged Media]: https://www.w3.org/TR/css-page-3/
+[CSS Generated Content]: https://www.w3.org/TR/css-gcpm-3/
+[Puppeteer]: https://pptr.dev/
+
+[docker-image]: https://hub.docker.com/r/pagedmedia/pagedjs
+[jsDelivr]: https://www.jsdelivr.com/package/npm/pagedjs
+[unpkg]: https://unpkg.com/pagedjs
+[via NPM]: https://npmjs.com/pagedjs