Skip to content

Commit

Permalink
Refactor wording
Browse files Browse the repository at this point in the history
  • Loading branch information
wooorm committed Sep 16, 2015
1 parent b6d6c76 commit 6f85072
Showing 1 changed file with 52 additions and 33 deletions.
85 changes: 52 additions & 33 deletions readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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/)**)
Expand All @@ -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;
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 6f85072

Please sign in to comment.