Refactor docs

retextjs · Sep 6, 2023 · d1175c0 · d1175c0
1 parent f586af3
commit d1175c0
Show file tree

Hide file tree

Showing 7 changed files with 250 additions and 184 deletions.
diff --git a/package.json b/package.json
@@ -48,6 +48,10 @@
   "remarkConfig": {
     "plugins": [
       "remark-preset-wooorm",
+      [
+        "remark-lint-no-html",
+        false
+      ],
       [
         "remark-retext",
         false

diff --git a/packages/retext-dutch/readme.md b/packages/retext-dutch/readme.md
@@ -18,7 +18,6 @@
 *   [Use](#use)
 *   [API](#api)
     *   [`unified().use(retextDutch)`](#unifieduseretextdutch)
-    *   [`Parser`](#parser)
 *   [Syntax tree](#syntax-tree)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
@@ -38,19 +37,17 @@ See [the monorepo readme][retext] for info on what the retext ecosystem is.
 ## When should I use this?
 
 This plugin adds support to unified for parsing Dutch.
-You can alternatively use [`retext`][retext-core] instead, which combines
-unified, this plugin, and [`retext-stringify`][retext-stringify].
-If the prose is in English, or any Latin-script language, use `unified` itself
-with [`retext-english`][retext-english] or [`retext-latin`][retext-latin],
-respectively.
+If the prose is not Dutch, use [`retext`][retext-core] for any Latin-script
+text, or for English use `unified` itself with
+[`retext-english`][retext-english] and [`retext-stringify`][retext-stringify].
 
-This plugin is built on [`parse-dutch`][parse-dutch], which is a level lower,
-but you could use that manually too.
+If you just want the syntax tree, you can use [`parse-dutch`][parse-dutch]
+directly.
 
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with [npm][]:
+In Node.js (version 16+), install with [npm][]:
 
 ```sh
 npm install retext-dutch
@@ -73,10 +70,10 @@ In browsers with [`esm.sh`][esmsh]:
 ## Use
 
 ```js
-import {reporter} from 'vfile-reporter'
-import {unified} from 'unified'
 import retextDutch from 'retext-dutch'
 import retextStringify from 'retext-stringify'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
 
 const file = await unified()
   .use(retextDutch)
@@ -100,34 +97,39 @@ no issues found
 
 ## API
 
-This package exports the identifier `Parser`.
-The default export is `retextDutch`.
+This package exports no identifiers.
+The default export is [`retextDutch`][api-retext-dutch].
 
 ### `unified().use(retextDutch)`
 
-Add support for parsing Dutch input.
+Add support for parsing Dutch natural language.
+
+###### Parameters
 
-There are no options.
+There are no parameters.
 
-### `Parser`
+###### Returns
 
-Access to the [parser][] ([`parse-dutch`][parse-dutch]).
+Nothing (`undefined`).
 
 ## Syntax tree
 
-The syntax tree format used in retext is [nlcst][].
+The syntax tree used in retext is [nlcst][].
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-There are no extra exported types.
+It exports no additional types.
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
+
+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, `retext-dutch@^4`,
+compatible with Node.js 12.
 
 ## Contribute
 
@@ -143,8 +145,6 @@ abide by its terms.
 
 Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
-<!--lint ignore no-html-->
-
 <table>
 <tr valign="middle">
 <td width="20%" align="center" rowspan="2" colspan="2">
@@ -262,22 +262,20 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
 [esmsh]: https://esm.sh
 
-[typescript]: https://www.typescriptlang.org
-
-[unified]: https://github.com/unifiedjs/unified
-
-[retext]: https://github.com/retextjs/retext
-
 [nlcst]: https://github.com/syntax-tree/nlcst
 
-[parser]: https://github.com/unifiedjs/unified#processorparser
-
 [parse-dutch]: https://github.com/wooorm/parse-dutch
 
+[retext]: https://github.com/retextjs/retext
+
 [retext-core]: https://github.com/retextjs/retext/tree/main/packages/retext
 
+[retext-english]: https://github.com/retextjs/retext/tree/main/packages/retext-english
+
 [retext-stringify]: https://github.com/retextjs/retext/tree/main/packages/retext-stringify
 
-[retext-latin]: https://github.com/retextjs/retext/tree/main/packages/retext-latin
+[typescript]: https://www.typescriptlang.org
 
-[retext-english]: https://github.com/retextjs/retext/tree/main/packages/retext-english
+[unified]: https://github.com/unifiedjs/unified
+
+[api-retext-dutch]: #unifieduseretextdutch
diff --git a/packages/retext-english/readme.md b/packages/retext-english/readme.md
@@ -18,7 +18,6 @@
 *   [Use](#use)
 *   [API](#api)
     *   [`unified().use(retextEnglish)`](#unifieduseretextenglish)
-    *   [`Parser`](#parser)
 *   [Syntax tree](#syntax-tree)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
@@ -38,19 +37,17 @@ See [the monorepo readme][retext] for info on what the retext ecosystem is.
 ## When should I use this?
 
 This plugin adds support to unified for parsing English.
-You can alternatively use [`retext`][retext-core] instead, which combines
-unified, this plugin, and [`retext-stringify`][retext-stringify].
-If the prose is in Dutch, or any Latin-script language, use `unified` itself
-with [`retext-dutch`][retext-dutch] or [`retext-latin`][retext-latin],
-respectively.
+If the prose is not English, use [`retext`][retext-core] for any Latin-script
+text, or for Dutch use `unified` itself with
+[`retext-dutch`][retext-dutch] and [`retext-stringify`][retext-stringify].
 
-This plugin is built on [`parse-english`][parse-english], which is a level
-lower, but you could use that manually too.
+If you just want the syntax tree, you can use [`parse-english`][parse-english]
+directly.
 
 ## Install
 
 This package is [ESM only][esm].
-In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with [npm][]:
+In Node.js (version 16+), install with [npm][]:
 
 ```sh
 npm install retext-english
@@ -73,17 +70,17 @@ In browsers with [`esm.sh`][esmsh]:
 ## Use
 
 ```js
-import {reporter} from 'vfile-reporter'
-import {unified} from 'unified'
 import retextEnglish from 'retext-english'
-import retextProfanities from 'retext-profanities'
 import retextEmoji from 'retext-emoji'
+import retextProfanities from 'retext-profanities'
 import retextStringify from 'retext-stringify'
+import {unified} from 'unified'
+import {reporter} from 'vfile-reporter'
 
 const file = await unified()
   .use(retextEnglish)
-  .use(retextProfanities)
   .use(retextEmoji, {convert: 'encode'})
+  .use(retextProfanities)
   .use(retextStringify)
   .process('He’s set on beating your butt for sheriff! :cop:')
 
@@ -98,41 +95,46 @@ He’s set on beating your butt for sheriff! 👮
 ```
 
 ```txt
-  1:26-1:30  warning  Be careful with “butt”, it’s profane in some cases  butt  retext-profanities
+1:26-1:30 warning Be careful with `butt`, it’s profane in some cases butt retext-profanities
 
 ⚠ 1 warning
 ```
 
 ## API
 
-This package exports the identifier `Parser`.
-The default export is `retextEnglish`.
+This package exports no identifiers.
+The default export is [`retextEnglish`][api-retext-english].
 
 ### `unified().use(retextEnglish)`
 
-Add support for parsing English input.
+Add support for parsing English natural language.
+
+###### Parameters
 
-There are no options.
+There are no parameters.
 
-### `Parser`
+###### Returns
 
-Access to the [parser][] ([`parse-english`][parse-english]).
+Nothing (`undefined`).
 
 ## Syntax tree
 
-The syntax tree format used in retext is [nlcst][].
+The syntax tree used in retext is [nlcst][].
 
 ## Types
 
 This package is fully typed with [TypeScript][].
-There are no extra exported types.
+It exports no additional types.
 
 ## Compatibility
 
-Projects maintained by the unified collective are compatible with all maintained
+Projects maintained by the unified collective are compatible with maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
-Our projects sometimes work with older versions, but this is not guaranteed.
+
+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, `retext-english@^4`,
+compatible with Node.js 12.
 
 ## Contribute
 
@@ -148,8 +150,6 @@ abide by its terms.
 
 Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
-<!--lint ignore no-html-->
-
 <table>
 <tr valign="middle">
 <td width="20%" align="center" rowspan="2" colspan="2">
@@ -267,22 +267,20 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
 [esmsh]: https://esm.sh
 
-[typescript]: https://www.typescriptlang.org
-
-[unified]: https://github.com/unifiedjs/unified
-
-[retext]: https://github.com/retextjs/retext
-
 [nlcst]: https://github.com/syntax-tree/nlcst
 
-[parser]: https://github.com/unifiedjs/unified#processorparser
-
 [parse-english]: https://github.com/wooorm/parse-english
 
+[retext]: https://github.com/retextjs/retext
+
 [retext-core]: https://github.com/retextjs/retext/tree/main/packages/retext
 
 [retext-stringify]: https://github.com/retextjs/retext/tree/main/packages/retext-stringify
 
-[retext-latin]: https://github.com/retextjs/retext/tree/main/packages/retext-latin
-
 [retext-dutch]: https://github.com/retextjs/retext/tree/main/packages/retext-dutch
+
+[typescript]: https://www.typescriptlang.org
+
+[unified]: https://github.com/unifiedjs/unified
+
+[api-retext-english]: #unifieduseretextenglish