Update docs

wooorm · Nov 4, 2021 · dc6fc5f · dc6fc5f
1 parent affa68b
commit dc6fc5f
Showing 1 changed file with 148 additions and 90 deletions.
diff --git a/readme.md b/readme.md
@@ -7,34 +7,60 @@
 [![Downloads][downloads-badge]][downloads]
 [![Size][size-badge]][size]
 
-Match [BCP 47][spec] language tags with “language ranges” per [RFC 4647][match],
-as done by the `:lang()` pseudo-class in CSS, or the `Accept-Language` HTTP
-header.
-
-Related to [`bcp-47`][bcp47].
+Match BCP 47 language tags with language ranges per RFC 4647.
 
 ## Contents
 
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
 *   [Install](#install)
 *   [Use](#use)
 *   [API](#api)
     *   [`basicFilter(tags[, ranges='*'])`](#basicfiltertags-ranges)
     *   [`extendedFilter(tags[, ranges='*'])`](#extendedfiltertags-ranges)
     *   [`lookup(tags, ranges)`](#lookuptags-ranges)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
 *   [Related](#related)
+*   [Contribute](#contribute)
 *   [License](#license)
 
-## Install
+## What is this?
+
+This package can match [BCP 47][spec] language tags with “language ranges” per
+[RFC 4647][match].
+This is done by the `:lang()` pseudo class in CSS, the `Accept-Language` HTTP
+header, and a few other places.
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+## When should I use this?
+
+You can use this package if you want to choose a certain document based on
+language tags.
+
+## Install
 
-[npm][]:
+This package is [ESM only][esm].
+In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
 
 ```sh
 npm install bcp-47-match
 ```
 
+In Deno with [Skypack][]:
+
+```js
+import * as bcp47Match from 'https://cdn.skypack.dev/bcp-47-match@2?dts'
+```
+
+In browsers with [Skypack][]:
+
+```html
+<script type="module">
+  import * as bcp47Match from 'https://cdn.skypack.dev/bcp-47-match@2?min'
+</script>
+```
+
 ## Use
 
 ```js
@@ -65,12 +91,13 @@ console.log(lookup(tags, 'jp')) // => undefined
 ## API
 
 This package exports the following identifiers: `basicFilter`, `extendedFilter`,
-`lookup`.
+and `lookup`.
 There is no default export.
 
 ### `basicFilter(tags[, ranges='*'])`
 
-> [See Basic Filtering spec](https://tools.ietf.org/html/rfc4647#section-3.3.1)
+> 👉 **Note**: See
+> [Basic Filtering spec](https://tools.ietf.org/html/rfc4647#section-3.3.1)
 
 Match language tags to a list of simple ranges.
 Searches for matches between the first range and all tags, and continues
@@ -79,87 +106,92 @@ Returns a list of matching tags in the order they matched.
 
 <details><summary>View matching table</summary>
 
-| Basic Filter | \* | de | de-CH | de-DE | de-\*-DE | \*-CH |
+| Basic Filter | `*` | `de` | `de-CH` | `de-DE` | `de-*-DE` | `*-CH` |
 | - | - | - | - | - | - | - |
-| de | ✔︎ | ✔︎ | | | | |
-| de-CH | ✔︎ | ✔︎ | ✔︎ | | | |
-| de-CH-1996 | ✔︎ | ✔︎ | ✔︎ | | | |
-| de-DE | ✔︎ | ✔︎ | | ✔︎ | | |
-| de-DE-1996 | ✔︎ | ✔︎ | | ✔︎ | | |
-| de-DE-x-goethe | ✔︎ | ✔︎ | | ✔︎ | | |
-| de-Deva | ✔︎ | ✔︎ | | | | |
-| de-Deva-DE | ✔︎ | ✔︎ | | | | |
-| de-Latf-DE | ✔︎ | ✔︎ | | | | |
-| de-Latn-DE | ✔︎ | ✔︎ | | | | |
-| de-Latn-DE-1996 | ✔︎ | ✔︎ | | | | |
-| de-x-DE | ✔︎ | ✔︎ | | | | |
-| en | ✔︎ | | | | | |
-| en-GB | ✔︎ | | | | | |
-| zh | ✔︎ | | | | | |
-| zh-Hans | ✔︎ | | | | | |
-| zh-Hant | ✔︎ | | | | | |
+| `de` | ✔︎ | ✔︎ | | | | |
+| `de-CH` | ✔︎ | ✔︎ | ✔︎ | | | |
+| `de-CH-1996` | ✔︎ | ✔︎ | ✔︎ | | | |
+| `de-DE` | ✔︎ | ✔︎ | | ✔︎ | | |
+| `de-DE-1996` | ✔︎ | ✔︎ | | ✔︎ | | |
+| `de-DE-x-goethe` | ✔︎ | ✔︎ | | ✔︎ | | |
+| `de-Deva` | ✔︎ | ✔︎ | | | | |
+| `de-Deva-DE` | ✔︎ | ✔︎ | | | | |
+| `de-Latf-DE` | ✔︎ | ✔︎ | | | | |
+| `de-Latn-DE` | ✔︎ | ✔︎ | | | | |
+| `de-Latn-DE-1996` | ✔︎ | ✔︎ | | | | |
+| `de-x-DE` | ✔︎ | ✔︎ | | | | |
+| `en` | ✔︎ | | | | | |
+| `en-GB` | ✔︎ | | | | | |
+| `zh` | ✔︎ | | | | | |
+| `zh-Hans` | ✔︎ | | | | | |
+| `zh-Hant` | ✔︎ | | | | | |
 
 </details>
 
 ###### Parameters
 
-*   `tags` (`string` or `Array.<string>`) — List of BCP-47 tags
-*   `ranges` (`string` or `Array.<string>`) — List of RFC 4647
+*   `tags` (`string` or `Array<string>`)
+    — list of BCP 47 tags
+*   `ranges` (`string` or `Array<string>`)
+    — list of RFC 4647
     [basic ranges][basic-range]
     (aka, matching `/^(\*|[a-z]{1,8}(-[a-z0-9]{1,8})*)$/i`)
 
 ###### Returns
 
-`Array.<string>` — Possibly empty list of matching tags in the order they
-matched.
+Possibly empty list of matching tags in the order they matched
+(`Array<string>`).
 
 ### `extendedFilter(tags[, ranges='*'])`
 
-> [See Extended Filtering spec](https://tools.ietf.org/html/rfc4647#section-3.3.2)
+> 👉 **Note**: See
+> [Extended Filtering spec](https://tools.ietf.org/html/rfc4647#section-3.3.2)
 
 Match language tags to a list of extended ranges.
 Searches for matches between the first range and all tags, and continues
 with further ranges.
 
 <details><summary>View matching table</summary>
 
-| Extended Filter | \* | de | de-CH | de-DE | de-\*-DE | \*-CH |
+| Extended Filter | `*` | `de` | `de-CH` | `de-DE` | `de-*-DE` | `*-CH` |
 | - | - | - | - | - | - | - |
-| de | ✔︎ | ✔︎ | | | | |
-| de-CH | ✔︎ | ✔︎ | ✔︎ | | | ✔︎ |
-| de-CH-1996 | ✔︎ | ✔︎ | ✔︎ | | | ✔︎ |
-| de-DE | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-DE-1996 | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-DE-x-goethe | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-Deva | ✔︎ | ✔︎ | | | | |
-| de-Deva-DE | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-Latf-DE | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-Latn-DE | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-Latn-DE-1996 | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
-| de-x-DE | ✔︎ | ✔︎ | | | | |
-| en | ✔︎ | | | | | |
-| en-GB | ✔︎ | | | | | |
-| zh | ✔︎ | | | | | |
-| zh-Hans | ✔︎ | | | | | |
-| zh-Hant | ✔︎ | | | | | |
+| `de` | ✔︎ | ✔︎ | | | | |
+| `de-CH` | ✔︎ | ✔︎ | ✔︎ | | | ✔︎ |
+| `de-CH-1996` | ✔︎ | ✔︎ | ✔︎ | | | ✔︎ |
+| `de-DE` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-DE-1996` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-DE-x-goethe` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-Deva` | ✔︎ | ✔︎ | | | | |
+| `de-Deva-DE` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-Latf-DE` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-Latn-DE` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-Latn-DE-1996` | ✔︎ | ✔︎ | | ✔︎ | ✔︎ | |
+| `de-x-DE` | ✔︎ | ✔︎ | | | | |
+| `en` | ✔︎ | | | | | |
+| `en-GB` | ✔︎ | | | | | |
+| `zh` | ✔︎ | | | | | |
+| `zh-Hans` | ✔︎ | | | | | |
+| `zh-Hant` | ✔︎ | | | | | |
 
 </details>
 
 ###### Parameters
 
-*   `tags` (`string` or `Array.<string>`) — List of BCP-47 tags
-*   `ranges` (`string` or `Array.<string>`) — List of RFC 4647
-    [extended ranges][extended-range]
+*   `tags` (`string` or `Array<string>`)
+    — list of BCP 47 tags
+*   `ranges` (`string` or `Array<string>`)
+    — list of RFC 4647 [extended ranges][extended-range]
     (aka, matching `/^(\*|[a-z]{1,8})(-(\*|[a-z0-9]{1,8}))*$/i`)
 
 ###### Returns
 
-`Array.<string>` — Possibly empty list of matching tags in the order they
-matched.
+Possibly empty list of matching tags in the order they matched
+(`Array<string>`).
 
 ### `lookup(tags, ranges)`
 
-> [See Lookup spec](https://tools.ietf.org/html/rfc4647#section-3.4)
+> 👉 **Note**: See
+> [Lookup spec](https://tools.ietf.org/html/rfc4647#section-3.4)
 
 Find the best language tag that matches a list of ranges.
 Searches for a match between the first range and all tags, and continues
@@ -168,55 +200,75 @@ Returns the first match, if any.
 
 <details><summary>View matching table</summary>
 
-| Lookup | \* | de | de-CH | de-DE | de-\*-DE | \*-CH |
+| Lookup | `*` | `de` | `de-CH` | `de-DE` | `de-*-DE` | `*-CH` |
 | - | - | - | - | - | - | - |
-| de | | ✔︎︎ | ✔︎︎ | ✔︎ | ✔︎ | ✔︎ |
-| de-CH | | | ✔︎ | | | ✔︎ |
-| de-CH-1996 | | | | | | ✔︎ |
-| de-DE | | | | ✔︎ | | ✔︎ |
-| de-DE-1996 | | | | | | ✔︎ |
-| de-DE-x-goethe | | | | | | ✔︎ |
-| de-Deva | | | | | | ✔︎ |
-| de-Deva-DE | | | | | | ✔︎ |
-| de-Latf-DE | | | | | | ✔︎ |
-| de-Latn-DE | | | | | | ✔︎ |
-| de-Latn-DE-1996 | | | | | | ✔︎ |
-| de-x-DE | | | | | | ✔︎ |
-| en | | | | | | ✔︎ |
-| en-GB | | | | | | ✔︎ |
-| zh | | | | | | ✔︎ |
-| zh-Hans | | | | | | ✔︎ |
-| zh-Hant | | | | | | ✔︎ |
+| `de` | | ✔︎︎ | ✔︎︎ | ✔︎ | ✔︎ | ✔︎ |
+| `de-CH` | | | ✔︎ | | | ✔︎ |
+| `de-CH-1996` | | | | | | ✔︎ |
+| `de-DE` | | | | ✔︎ | | ✔︎ |
+| `de-DE-1996` | | | | | | ✔︎ |
+| `de-DE-x-goethe` | | | | | | ✔︎ |
+| `de-Deva` | | | | | | ✔︎ |
+| `de-Deva-DE` | | | | | | ✔︎ |
+| `de-Latf-DE` | | | | | | ✔︎ |
+| `de-Latn-DE` | | | | | | ✔︎ |
+| `de-Latn-DE-1996` | | | | | | ✔︎ |
+| `de-x-DE` | | | | | | ✔︎ |
+| `en` | | | | | | ✔︎ |
+| `en-GB` | | | | | | ✔︎ |
+| `zh` | | | | | | ✔︎ |
+| `zh-Hans` | | | | | | ✔︎ |
+| `zh-Hant` | | | | | | ✔︎ |
 
 </details>
 
 ###### Parameters
 
-*   `tags` (`string` or `Array.<string>`) — List of BCP-47 tags
-*   `ranges` (`string` or `Array.<string>`) — List of RFC 4647 basic ranges
-    (but `*` is ignored)
+*   `tags` (`string` or `Array<string>`)
+    — list of BCP 47 tags
+*   `ranges` (`string` or `Array<string>`)
+    — list of RFC 4647 basic ranges (but `*` is ignored)
 
 ###### Returns
 
-`string?` — The first matching tag in `tags`, or `undefined` otherwise.
+First matching tag in `tags`, `undefined` otherwise (`string?`).
+
+## Types
+
+This package is fully typed with [TypeScript][].
+
+## Compatibility
+
+This package is at least compatible with all maintained versions of Node.js.
+As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+It also works in Deno and modern browsers.
+
+## Security
+
+This package is safe.
 
 ## Related
 
-*   [`bcp-47`](https://github.com/wooorm/bcp-47)
-    — Parse and serialize BCP 47 language tags
-*   [`bcp-47-normalize`](https://github.com/wooorm/bcp-47-normalize)
-    — Normalize, canonicalize, and format BCP 47 tags
-*   [`iso-3166`](https://github.com/wooorm/iso-3166)
+*   [`wooorm/bcp-47`](https://github.com/wooorm/bcp-47)
+    — parse and serialize BCP 47 language tags
+*   [`wooorm/bcp-47-normalize`](https://github.com/wooorm/bcp-47-normalize)
+    — normalize, canonicalize, and format BCP 47 tags
+*   [`wooorm/iso-3166`](https://github.com/wooorm/iso-3166)
     — ISO 3166 codes
-*   [`iso-639-2`](https://github.com/wooorm/iso-639-2)
+*   [`wooorm/iso-639-2`](https://github.com/wooorm/iso-639-2)
     — ISO 639-2 codes
-*   [`iso-639-3`](https://github.com/wooorm/iso-639-3)
+*   [`wooorm/iso-639-3`](https://github.com/wooorm/iso-639-3)
     — ISO 639-3 codes
-*   [`iso-15924`](https://github.com/wooorm/iso-15924)
+*   [`wooorm/iso-15924`](https://github.com/wooorm/iso-15924)
     — ISO 15924 codes
-*   [`un-m49`](https://github.com/wooorm/un-m49)
+*   [`wooorm/un-m49`](https://github.com/wooorm/un-m49)
     — UN M49 codes
 
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
 ## License
 
 [MIT][license] © [Titus Wormer][author]
@@ -241,11 +293,17 @@ Returns the first match, if any.
 
 [npm]: https://docs.npmjs.com/cli/install
 
+[skypack]: https://www.skypack.dev
+
 [license]: license
 
 [author]: https://wooorm.com
 
-[bcp47]: https://github.com/wooorm/bcp-47
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[typescript]: https://www.typescriptlang.org
+
+[contribute]: https://opensource.guide/how-to-contribute/
 
 [spec]: https://tools.ietf.org/html/bcp47