Restructure README

Author: bwrrp

README.md

@@ -5,7 +5,7 @@
 
 Fast, tiny, standards-compliant XML DOM implementation for node and the browser.
 
-This is a (partial) implementation of the [DOM living standard][domstandard], as last updated 1 March 2019, and the [DOM Parsing and Serialization W3C Editor's Draft][domparsing], as last updated 11 February 2019. See the 'Features' and 'Limitations' sections below for details on what's included and what's not.
+This is a (partial) implementation of the [DOM living standard][domstandard], as last updated 1 March 2019, and the [DOM Parsing and Serialization W3C Editor's Draft][domparsing], as last updated 11 February 2019. See the 'Features and Limitations' section below for details on what's included and what's not.
 
 [domstandard]: https://dom.spec.whatwg.org/
 [domparsing]: https://w3c.github.io/DOM-Parsing/
@@ -24,26 +24,28 @@ or
 yarn add slimdom
 ```
 
-The package includes both a commonJS bundle (`dist/slimdom.js`) and an ES6 module (`dist/slimdom.mjs`).
+The package includes both a commonJS-compatible UMD bundle (`dist/slimdom.js`) and an ES6 module (`dist/slimdom.mjs`). This means it should work in most JavaScript environments that support the ES2017 standard or newer.
 
 ## Usage
 
 Create documents using the slimdom.Document constructor, and manipulate them using the [standard DOM API][domstandard].
 
 ```javascript
 import * as slimdom from 'slimdom';
+// alternatively, in node and other commonJS environments:
+// const slimdom = require('slimdom');
 
 const document = new slimdom.Document();
 document.appendChild(document.createElementNS('http://www.example.com', 'root'));
 const xml = slimdom.serializeToWellFormedString(document);
 // -> '<root xmlns="http://www.example.com"/>'
 ```
 
-Some DOM API's, such as the `DocumentFragment` constructor, require the presence of a global document. In these cases, slimdom will use the instance exposed through `slimdom.document`. Although you could mutate this document, it is recommended to create your own to avoid conflicts with other code using slimdom in your application.
+Some DOM API's, such as the `DocumentFragment` constructor, require the presence of a global document, for instance to set their initial `ownerDocument` property. In these cases, slimdom will use the instance exposed through `slimdom.document`. Although you could mutate this document, it is recommended to always create your own documents (using the `Document` constructor) to avoid conflicts with other code using slimdom in your application.
 
-When using a `Range`, make sure to call `detach` when you don't need it anymore. As JavaScript currently does not have a way to detect when the instance can be garbage collected, we don't have any other way of detecting when we can stop updating the range for mutations to the surrounding nodes.
+When using a `Range`, make sure to call `detach` when you don't need it anymore. As we do not have a way to detect when a Range is no longer used, this library needs to be notified when it can stop updating the range for mutations to the surrounding nodes.
 
-## Features
+## Features and limitations
 
 This library implements:
 
@@ -52,34 +54,54 @@ This library implements:
 -   `MutationObserver`
 -   `XMLSerializer`, and read-only versions of `innerHTML` / `outerHTML` on `Element`.
 
-## Limitations
+This library is currently aimed at providing a lightweight and consistent experience for dealing with XML and XML-like data. For simplicity and efficiency, this implementation deviates from the spec in a few minor ways. Most notably, normal JavaScript arrays are used instead of `HTMLCollection` / `NodeList` and `NamedNodeMap`, HTML documents are treated no different from other documents and a number of features from in the DOM spec are missing. In most cases, this is because alternatives are available that can be used together with slimdom with minimal effort.
 
-For simplicity and efficiency, this implementation deviates from the spec in a few minor ways. Most notably, normal JavaScript arrays are used instead of `HTMLCollection` / `NodeList` and `NamedNodeMap`.
+Do not rely on the behavior or presence of any methods and properties not specified in the DOM standard. For example, do not use JavaScript array methods exposed on properties that should expose a NodeList and do not use Element as a constructor. This behavior is _not_ considered public API and may change without warning in a future release.
+
+### Parsing
+
+This library does not implement the `DOMParser` interface, nor `insertAdjacentHTML` on `Element`, nor `createContextualFragment` on `Range`. The `innerHTML` and `outerHTML` properties are read-only,
+
+If you need to parse XML, use [slimdom-sax-parser][slimdom-sax-parser]. See its README for examples.
+
+If you need to parse HTML, see [this example][parse5-example] which shows how to connect the [parse5][parse5] HTML parser with the help of the [dom-treeadapter][dom-treeadapter] library.
+
+### CSS Selectors and XPath
+
+This library does not implement CSS selectors, which means no `querySelector` / `querySelectorAll` on `ParentNode` and no `closest` / `matches` / `webkitMatchesSelector` on `Element`.
+
+To query a slimdom document using XPath or XQuery, use [FontoXPath][fontoxpath].
+
+### HTML & browser-specific features and behavior
 
-The following features have not yet been implemented:
+Emulating a full browser environment is not the goal of this library. Consider using [jsdom][jsdom] instead if you need that.
 
--   No XML parsing (no `DOMParser`, `innerHTML` and `outerHTML` are read-only, no `insertAdjacentHTML` on `Element`, no `createContextualFragment` on `Range`). If you need to parse XML, consider using [slimdom-sax-parser][slimdom-sax-parser].
--   No CSS selectors, so no `querySelector` / `querySelectorAll` on `ParentNode`, no `closest` / `matches` / `webkitMatchesSelector` on `Element`. The older non-CSS query methods (`getElementById` for interface `NonElementParentNode`, and `getElementsByTagName` / `getElementsByTagNameNS` / `getElementsByClassName` on `Document`) have not yet been implemented either. To query the DOM, consider using [FontoXPath][fontoxpath].
--   No HTML parsing / serialization, but see [this example][parse5-example] which shows how to connect the [parse5][parse5] HTML parser with the help of the [dom-treeadapter][dom-treeadapter] library.
--   No special treatment of HTML documents, including `HTMLElement` and its subclasses. This also includes HTML casing behavior for attributes and tagNames, as well as the `id` / `className` / `classList` properties on `Element` and `compatMode` / `contentType` on `Document`.
--   No events, no `createEvent` on `Document`.
--   No support for shadow DOM, `Slotable` / `ShadowRoot`, no `slot` / `attachShadow` / `shadowRoot` on `Element`.
--   No support for custom elements or the `is` option on `createElement` / `createElementNS`.
--   No iteration helpers (`NodeIterator` / `TreeWalker` / `NodeFilter`, and the `createNodeIterator` / `createTreeWalker` methods on `Document`).
--   No DOM modifying methods on Range (`deleteContents` / `extractContents` / `cloneContents` / `insertNode` / `surroundContents`).
--   No `attributeFilter` for mutation observers.
--   No `isConnected` / `getRootNode` / `isEqualNode` / `isSameNode` / `compareDocumentPosition` on `Node`
--   No notion of URLs (`baseURI` on `Node`, and `URL` / `documentURI` / `origin` on `Document`).
--   No notion of encodings (`characterSet` / `charset` / `inputEncoding` on `Document`). This library only deals with JavaScript strings, not raw byte streams.
--   No properties / methods that exist mainly for web compatibility reasons (`insertAdjacentElement` / `insertAdjacentText` on `Element`, `hasFeature` on `DOMImplementation`, and `specified` on `Attr`).
+This implementation offers no special treatment of HTML documents, which means there are no implementations of `HTMLElement` and its subclasses. This also affects HTML-specific casing behavior for attributes and tagNames. The `id` / `className` / `classList` properties on `Element` and `compatMode` / `contentType` on `Document` have not been implemented. HTML-specific query methods (`getElementById` for interface `NonElementParentNode`, `getElementsByClassName` on `Document`) are also missing.
+
+This library also does not currently implement events, including the `Event` / `EventTarget` interfaces. It also currently does not contain an implementation of `AbortController` / `AbortSignal`. As these may have wider applications than browser-specific use cases, please file an issue if you have a use for these in your application and would like support for them to be added.
+
+There is currently no support for shadow DOM, so no `Slotable` / `ShadowRoot` interfaces and no `slot` / `attachShadow` / `shadowRoot` on `Element`. Slimdom also does not support the APIs for custom elements using the `is` option on `createElement` / `createElementNS`.
+
+This library has no notion of URLs (`baseURI` on `Node`, and `URL` / `documentURI` / `origin` on `Document`), nor of encodings (`characterSet` / `charset` / `inputEncoding` on `Document`). This library only deals with JavaScript strings, not raw byte streams.
+
+This library omits properties and methods that exist mainly for web compatibility reasons (`insertAdjacentElement` / `insertAdjacentText` on `Element`, `hasFeature` on `DOMImplementation`, and `specified` on `Attr`).
+
+### Miscellaneous
+
+The following features are missing simply because I have not yet had a need for them. If you do need one, feel free to create a feature request issue or even submit a pull request.
+
+-   Older non-CSS, non-HTML query methods (`getElementsByTagName` / `getElementsByTagNameNS` on `Document`).
+-   Iteration helpers (`NodeIterator` / `TreeWalker` / `NodeFilter`, and the `createNodeIterator` / `createTreeWalker` methods on `Document`).
+-   DOM-modifying methods on Range (`deleteContents` / `extractContents` / `cloneContents` / `insertNode` / `surroundContents`).
+-   `attributeFilter` for mutation observers.
+-   `isConnected` / `getRootNode` / `isEqualNode` / `isSameNode` / `compareDocumentPosition` on `Node`
 
 [slimdom-sax-parser]: https://github.com/wvbe/slimdom-sax-parser
 [fontoxpath]: https://github.com/FontoXML/fontoxpath/
 [parse5-example]: https://github.com/bwrrp/slimdom.js/tree/master/test/examples/parse5
 [parse5]: https://github.com/inikulin/parse5
 [dom-treeadapter]: https://github.com/RReverser/dom-treeadapter
-
-Do not rely on the behavior or presence of any methods and properties not specified in the DOM standard. For example, do not use JavaScript array methods exposed on properties that should expose a NodeList and do not use Element as a constructor. This behavior is _not_ considered public API and may change without warning in a future release.
+[jsdom]: https://github.com/jsdom/jsdom
 
 ## Contributing