Refactor wording

readme.md

@@ -9,10 +9,10 @@ and manipulating natural language in JavaScript. Node and the browser.
 
 > Rather than being a do-all library for Natural Language Processing (such as
 > [NLTK](http://www.nltk.org) or [OpenNLP](https://opennlp.apache.org)),
-> **retext** aims to be useful for more practical use cases (such as censoring
-> [insensitive words](https://github.com/wooorm/alex) or decoding emoticons,
-> but the possibilities are endless) instead of more academic goals (research
-> purposes).
+> **retext** aims to be useful for more practical use cases (such as checking
+> for [insensitive words](https://github.com/wooorm/alex) or decoding
+> [emoticons](https://github.com/wooorm/retext-emoji)) instead of more academic
+> goals (research purposes).
 > **retext** is inherently modular—it uses plugins (similar to
 > [mdast](https://github.com/wooorm/mdast/) for markdown) instead of providing
 > everything out of the box (such as
@@ -34,8 +34,8 @@ globals module, [uncompressed](retext.js) and [compressed](retext.min.js).
 ## Usage
 
 The following example uses [**retext-emoji**](https://github.com/wooorm/retext-emoji)
-(to show emoji) and [**retext-smartypants**](https://github.com/wooorm/retext-smartypants)
-(for smart punctuation).
+to show emoji and [**retext-smartypants**](https://github.com/wooorm/retext-smartypants)
+for smart punctuation.
 
 Require dependencies:
 
@@ -56,28 +56,27 @@ var processor = retext().use(smartypants).use(emoji, {
 Process a document:
 
 ```javascript
-var doc = processor.process(
-    'The three wise monkeys [. . .] sometimes called the ' +
-    'three mystic apes--are a pictorial maxim. Together ' +
-    'they embody the proverbial principle to ("see no evil, ' +
-    'hear no evil, speak no evil"). The three monkeys are ' +
-    'Mizaru (:see_no_evil:), covering his eyes, who sees no ' +
-    'evil; Kikazaru (:hear_no_evil:), covering his ears, ' +
-    'who hears no evil; and Iwazaru (:speak_no_evil:), ' +
-    'covering his mouth, who speaks no evil.'
-);
+var doc = processor.process([
+    'The three wise monkeys [. . .] sometimes called the three mystic',
+    'apes--are a pictorial maxim. Together they embody the proverbial',
+    'principle to ("see no evil, hear no evil, speak no evil"). The',
+    'three monkeys are Mizaru (:see_no_evil:), covering his eyes, who',
+    'sees no evil; Kikazaru (:hear_no_evil:), covering his ears, who',
+    'hears no evil; and Iwazaru (:speak_no_evil:), covering his mouth,',
+    'who speaks no evil.'
+].join('\n'));
 ```
 
 Yields (you need a browser which supports emoji to see them):
 
 ```text
-The three wise monkeys […] sometimes called the three
-mystic apes—are a pictorial maxim. Together they
-embody the proverbial principle to (“see no evil,
-hear no evil, speak no evil”). The three monkeys are
-Mizaru (🙈), covering his eyes, who sees no evil;
-Kikazaru (🙉), covering his ears, who hears no evil;
-and Iwazaru (🙊), covering his mouth, who speaks no evil.
+The three wise monkeys […] sometimes called the three mystic
+apes—are a pictorial maxim. Together they embody the proverbial
+principle to (“see no evil, hear no evil, speak no evil”). The
+three monkeys are Mizaru (🙈), covering his eyes, who
+sees no evil; Kikazaru (🙉), covering his ears, who
+hears no evil; and Iwazaru (🙊), covering his mouth,
+who speaks no evil.
 ```
 
 ## API
@@ -102,7 +101,7 @@ Change the way [**retext**](#api) works by using a [plugin](#plugin).
 
 **Returns**
 
-`Object`: an instance of Retext: The returned object functions just like
+`Object` — an instance of Retext: The returned object functions just like
 **retext** (it has the same methods), but caches the `use`d plugins. This
 provides the ability to chain `use` calls to use multiple plugins, but
 ensures the functioning of the **retext** module does not change for other
@@ -132,17 +131,25 @@ The result is `null` if a plugin is asynchronous, in which case the callback
 `done` should’ve been passed (don’t worry: plugin creators make sure you know
 its async).
 
-### plugin
+## Plugin
 
-A plugin is simply a function, with `function(retext[, options])` as its
-signature. The first argument is the **Retext** instance a user attached the
-plugin to. The plugin is invoked when a user `use`s the plugin (not when a
-document is parsed) and enables the plugin to modify retext.
+### function attacher(retext\[, options\])
 
-The plugin can return another function: `function(NLCSTNode, file[, next])`.
-This function is invoked when a document is parsed.
+A plugin is a function, which takes the **Retext** instance a user attached
+the plugin on as a first parameter and optional configuration as a second
+parameter.
 
-## Plugins
+A plugin can return a `transformer`.
+
+### function transformer([node](https://github.com/wooorm/nlcst), [file](https://github.com/wooorm/vfile)\[, next\])
+
+A transformer changes the provided document (represented as a node and a
+virtual file).
+
+Transformers can be asynchronous, in which case `next` must be invoked on
+when done.
+
+## List of Plugins
 
 *   [retext-directionality](https://github.com/wooorm/retext-directionality)
     — (**[demo](http://wooorm.github.io/retext-directionality/)**)
@@ -156,10 +163,19 @@ This function is invoked when a document is parsed.
     — (**[demo](http://wooorm.github.io/retext-double-metaphone/)**)
     — Implementation of the Double Metaphone algorithm;
 
+*   [retext-dutch](https://github.com/wooorm/retext-dutch)
+    — Dutch language support;
+
+*   [retext-english](https://github.com/wooorm/retext-english)
+    — English language support;
+
 *   [retext-emoji](https://github.com/wooorm/retext-emoji)
     — (**[demo](http://wooorm.github.io/retext-emoji/)**)
     — Encode or decode [Gemojis](https://github.com/github/gemoji);
 
+*   [retext-equality](https://github.com/wooorm/retext-equality)
+    — Warn about possible insensitive, inconsiderate language;
+
 *   [retext-keywords](https://github.com/wooorm/retext-keywords)
     — (**[demo](http://wooorm.github.io/retext-keywords/)**)
     — Extract keywords and keyphrases;
@@ -203,14 +219,17 @@ This function is invoked when a document is parsed.
 ## List of Utilities
 
 Although not **retext** plug-ins, the following projects are useful when
-working with the [CST](https://github.com/wooorm/nlcst):
+working with the syntax tree: [NLCST](https://github.com/wooorm/nlcst):
 
 *   [wooorm/nlcst-to-string](https://github.com/wooorm/nlcst-to-string)
     — Stringify a node;
 
 *   [wooorm/nlcst-is-literal](https://github.com/wooorm/nlcst-is-literal)
     — Check whether a node is meant literally;
 
+*   [wooorm/nlcst-test](https://github.com/wooorm/nlcst-test)
+    — Validate a NLCST node;
+
 In addition, see [`wooorm/unist`](https://github.com/wooorm/unist#unist-node-utilties)
 for other utilities which work with **retext** nodes, but also with
 [**mdast**](https://github.com/wooorm/mdast) nodes.