Refactor readmes

wooorm · Nov 3, 2023 · 122a828 · 122a828
1 parent 3f1e321
commit 122a828
Show file tree

Hide file tree

Showing 97 changed files with 6,772 additions and 2,693 deletions.
diff --git a/.remarkignore b/.remarkignore
@@ -1,3 +1,2 @@
 script/template/readme.md
-dictionaries/
 source/
diff --git a/dictionaries/bg/readme.md b/dictionaries/bg/readme.md
@@ -2,22 +2,39 @@
 
 Bulgarian spelling dictionary.
 
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`Dictionary`](#dictionary)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [License](#license)
+
 ## What is this?
 
 This is a Bulgarian dictionary,
-generated by [`wooorm/dictionaries`][dictionaries] from
+generated by [`wooorm/dictionaries`][github-dictionaries] from
 [`bgoffice.sourceforge.net`][source],
 normalized and packaged so that it can be installed and used like other
 dictionaries.
 
 ## When should I use this?
 
 You can use this package when integrating with tools that perform spell checking
-(such as [`nodehun`][nodehun], [`nspell`][nspell]) or when making such tools.
+(such as [`nodehun`][github-nodehun] or [`nspell`][github-nspell]) or when
+making such tools.
 
 ## Install
 
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
 
 ```sh
 npm install dictionary-bg
@@ -26,13 +43,10 @@ npm install dictionary-bg
 ## Use
 
 ```js
-import dictionaryBg from 'dictionary-bg'
+import bg from 'dictionary-bg'
 
-dictionaryBg(function (error, bg) {
- if (error) throw error
- console.log(bg)
- // To do: use `bg` somehow
-})
+console.log(bg)
+// To do: use `bg` somehow
 ```
 
 Yields:
@@ -41,47 +55,77 @@ Yields:
 {aff: <Buffer>, dic: <Buffer>}
 ```
 
-Where `dic` and `aff` are [`Buffer`][buffer]s for `index.dic` and `index.aff`
-respectively.
+## API
+
+This package exports no identifiers.
+The default export is a [`Dictionary`][api-dictionary].
+
+It exports the [TypeScript][] type
+[`Dictionary`][api-dictionary].
+
+### `Dictionary`
+
+[Hunspell][] dictionary.
+
+###### Fields
+
+* `aff` ([`Buffer`][node-buffer])
+ — data for the affix file (defines the language, keyboard, flags, and more)
+* `dic` ([`Buffer`][node-buffer])
+ — data for the dictionary file (contains words and flags applying to those
+ words)
 
 ## Examples
 
-See the [monorepo readme][dictionaries] for examples.
+See the [monorepo readme][github-dictionaries] for examples.
+
+## Compatibility
 
-## Types
+This projects is compatible with maintained versions of Node.js.
 
-This package is typed with [TypeScript][].
+When we cut a new major release,
+we drop support for unmaintained versions of Node.
+This means we try to keep the current release line,
+compatible with Node.js 12.
+
+## Security
+
+This package is safe.
 
 ## Contribute
 
-See the [monorepo readme][dictionaries] for how to contribute.
+See the [monorepo readme][github-dictionaries] for how to contribute.
 
 > 👉 **Note**: dictionaries are not maintained here.
-> Report spelling problems upstream ([`bgoffice.sourceforge.net`][source]).
+> Report spelling problems upstream
+> ([`bgoffice.sourceforge.net`][source]).
 
 ## License
 
-Dictionary and affix file: [(GPL-2.0 OR LGPL-2.1 OR MPL-1.1)](https://github.com/wooorm/dictionaries/blob/main/dictionaries/bg/license).
-Rest: [MIT][] © [Titus Wormer][home].
+Dictionary and affix file:
+[(GPL-2.0 OR LGPL-2.1 OR MPL-1.1)](https://github.com/wooorm/dictionaries/blob/main/dictionaries/bg/license).
+Rest: [MIT][file-license] © [Titus Wormer][wooorm].
 
-[hunspell]: https://hunspell.github.io
+[api-dictionary]: #dictionary
 
-[nodehun]: https://github.com/nathanjsweet/nodehun
+[file-license]: https://github.com/wooorm/dictionaries/blob/main/license
 
-[nspell]: https://github.com/wooorm/nspell
+[github-dictionaries]: https://github.com/wooorm/dictionaries
 
-[macos]: https://github.com/wooorm/dictionaries#example-use-with-macos
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
-[source]: http://bgoffice.sourceforge.net
+[github-nodehun]: https://github.com/nathanjsweet/nodehun
 
-[npm]: https://docs.npmjs.com/cli/install
+[github-nspell]: https://github.com/wooorm/nspell
 
-[dictionaries]: https://github.com/wooorm/dictionaries
+[hunspell]: https://hunspell.github.io
 
-[mit]: https://github.com/wooorm/dictionaries/blob/main/license
+[node-buffer]: https://nodejs.org/api/buffer.html#buffer_buffer
 
-[buffer]: https://nodejs.org/api/buffer.html#buffer_buffer
+[npm-install]: https://docs.npmjs.com/cli/install
 
-[home]: https://wooorm.com
+[source]: http://bgoffice.sourceforge.net
 
 [typescript]: https://www.typescriptlang.org
+
+[wooorm]: https://wooorm.com
diff --git a/dictionaries/br/readme.md b/dictionaries/br/readme.md
@@ -2,22 +2,39 @@
 
 Breton spelling dictionary.
 
+## Contents
+
+* [What is this?](#what-is-this)
+* [When should I use this?](#when-should-i-use-this)
+* [Install](#install)
+* [Use](#use)
+* [API](#api)
+ * [`Dictionary`](#dictionary)
+* [Examples](#examples)
+* [Compatibility](#compatibility)
+* [Security](#security)
+* [Contribute](#contribute)
+* [License](#license)
+
 ## What is this?
 
 This is a Breton dictionary,
-generated by [`wooorm/dictionaries`][dictionaries] from
+generated by [`wooorm/dictionaries`][github-dictionaries] from
 [`Drouizig/hunspell-br`][source],
 normalized and packaged so that it can be installed and used like other
 dictionaries.
 
 ## When should I use this?
 
 You can use this package when integrating with tools that perform spell checking
-(such as [`nodehun`][nodehun], [`nspell`][nspell]) or when making such tools.
+(such as [`nodehun`][github-nodehun] or [`nspell`][github-nspell]) or when
+making such tools.
 
 ## Install
 
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+This package is [ESM only][github-gist-esm].
+In Node.js (version 16+),
+install with [npm][npm-install]:
 
 ```sh
 npm install dictionary-br
@@ -26,13 +43,10 @@ npm install dictionary-br
 ## Use
 
 ```js
-import dictionaryBr from 'dictionary-br'
+import br from 'dictionary-br'
 
-dictionaryBr(function (error, br) {
- if (error) throw error
- console.log(br)
- // To do: use `br` somehow
-})
+console.log(br)
+// To do: use `br` somehow
 ```
 
 Yields:
@@ -41,47 +55,77 @@ Yields:
 {aff: <Buffer>, dic: <Buffer>}
 ```
 
-Where `dic` and `aff` are [`Buffer`][buffer]s for `index.dic` and `index.aff`
-respectively.
+## API
+
+This package exports no identifiers.
+The default export is a [`Dictionary`][api-dictionary].
+
+It exports the [TypeScript][] type
+[`Dictionary`][api-dictionary].
+
+### `Dictionary`
+
+[Hunspell][] dictionary.
+
+###### Fields
+
+* `aff` ([`Buffer`][node-buffer])
+ — data for the affix file (defines the language, keyboard, flags, and more)
+* `dic` ([`Buffer`][node-buffer])
+ — data for the dictionary file (contains words and flags applying to those
+ words)
 
 ## Examples
 
-See the [monorepo readme][dictionaries] for examples.
+See the [monorepo readme][github-dictionaries] for examples.
+
+## Compatibility
 
-## Types
+This projects is compatible with maintained versions of Node.js.
 
-This package is typed with [TypeScript][].
+When we cut a new major release,
+we drop support for unmaintained versions of Node.
+This means we try to keep the current release line,
+compatible with Node.js 12.
+
+## Security
+
+This package is safe.
 
 ## Contribute
 
-See the [monorepo readme][dictionaries] for how to contribute.
+See the [monorepo readme][github-dictionaries] for how to contribute.
 
 > 👉 **Note**: dictionaries are not maintained here.
-> Report spelling problems upstream ([`Drouizig/hunspell-br`][source]).
+> Report spelling problems upstream
+> ([`Drouizig/hunspell-br`][source]).
 
 ## License
 
-Dictionary and affix file: [(GPL-2.0 OR LGPL-2.1 OR MPL-1.1)](https://github.com/wooorm/dictionaries/blob/main/dictionaries/br/license).
-Rest: [MIT][] © [Titus Wormer][home].
+Dictionary and affix file:
+[(GPL-2.0 OR LGPL-2.1 OR MPL-1.1)](https://github.com/wooorm/dictionaries/blob/main/dictionaries/br/license).
+Rest: [MIT][file-license] © [Titus Wormer][wooorm].
 
-[hunspell]: https://hunspell.github.io
+[api-dictionary]: #dictionary
 
-[nodehun]: https://github.com/nathanjsweet/nodehun
+[file-license]: https://github.com/wooorm/dictionaries/blob/main/license
 
-[nspell]: https://github.com/wooorm/nspell
+[github-dictionaries]: https://github.com/wooorm/dictionaries
 
-[macos]: https://github.com/wooorm/dictionaries#example-use-with-macos
+[github-gist-esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
 
-[source]: https://github.com/Drouizig/hunspell-br
+[github-nodehun]: https://github.com/nathanjsweet/nodehun
 
-[npm]: https://docs.npmjs.com/cli/install
+[github-nspell]: https://github.com/wooorm/nspell
 
-[dictionaries]: https://github.com/wooorm/dictionaries
+[hunspell]: https://hunspell.github.io
 
-[mit]: https://github.com/wooorm/dictionaries/blob/main/license
+[node-buffer]: https://nodejs.org/api/buffer.html#buffer_buffer
 
-[buffer]: https://nodejs.org/api/buffer.html#buffer_buffer
+[npm-install]: https://docs.npmjs.com/cli/install
 
-[home]: https://wooorm.com
+[source]: https://github.com/Drouizig/hunspell-br
 
 [typescript]: https://www.typescriptlang.org
+
+[wooorm]: https://wooorm.com