Add natural-language validation

*   Refactor wording in docs to be simpler;
*   Wrap plug-in, utility, and product names in inline-code;
*   Wrap function signatures in headings in inline-code.

Author: wooorm

.remarkrc

@@ -1,6 +1,7 @@
 {
   "output": true,
   "plugins": [
+    "script/natural-language",
     "comment-config",
     "lint",
     "github",

doc/getting-started.md

@@ -57,6 +57,6 @@ to use asterisks (`*`) or underscores (`_`) for emphasis.
 
 **remark** gets really cool when you combine it with plugins.
 
-*   [View available plug-ins and utilities »](https://github.com/wooorm/remark/blob/master/doc/plugins.md)
+*   [View plug-ins and utilities »](https://github.com/wooorm/remark/blob/master/doc/plugins.md)
 *   [Read how to use plug-ins in  **remarkplugin**(7) »](https://github.com/wooorm/remark/blob/master/doc/remarkplugin.7.md)
 *   [Read how to create plug-ins in **remarkplugin**(3) »](https://github.com/wooorm/remark/blob/master/doc/remarkplugin.3.md)

doc/plugins.md

@@ -19,126 +19,126 @@ See [tools built with remark »](https://github.com/wooorm/remark/blob/master/do
 
 ## List of Plugins
 
-*   [ben-eb/remark-autolink-headings](https://github.com/ben-eb/remark-autolink-headings)
+*   [`ben-eb/remark-autolink-headings`](https://github.com/ben-eb/remark-autolink-headings)
     — Automatically add GitHub style links to headings;
 
-*   [wooorm/remark-comment-config](https://github.com/wooorm/remark-comment-config)
+*   [`wooorm/remark-comment-config`](https://github.com/wooorm/remark-comment-config)
     — Set settings with comments during runtime;
 
-*   [hughsk/remark-contributors](https://github.com/hughsk/remark-contributors)
+*   [`hughsk/remark-contributors`](https://github.com/hughsk/remark-contributors)
     — Inject a given list of contributors into a table in a document;
 
-*   [eush77/remark-defsplit](https://github.com/eush77/remark-defsplit)
-    — Extract inline link/image destinations as separate definitions;
+*   [`eush77/remark-defsplit`](https://github.com/eush77/remark-defsplit)
+    — Extract inline link and image destinations as separate definitions;
 
-*   [wooorm/remark-github](https://github.com/wooorm/remark-github)
+*   [`wooorm/remark-github`](https://github.com/wooorm/remark-github)
     — Auto-link references like in GitHub issues, PRs, and comments;
 
-*   [ben-eb/remark-highlight.js](https://github.com/ben-eb/remark-highlight.js)
+*   [`ben-eb/remark-highlight.js`](https://github.com/ben-eb/remark-highlight.js)
     — Highlight code blocks in Markdown files with
     [highlight.js](https://github.com/isagalaev/highlight.js);
 
-*   [wooorm/remark-html](https://github.com/wooorm/remark-html)
+*   [`wooorm/remark-html`](https://github.com/wooorm/remark-html)
     — Compile Markdown to HTML documents;
 
-*   [wooorm/remark-inline-links](https://github.com/wooorm/remark-inline-links)
+*   [`wooorm/remark-inline-links`](https://github.com/wooorm/remark-inline-links)
     — Transform references and definitions into normal links and images;
 
-*   [wooorm/remark-license](https://github.com/wooorm/remark-license)
+*   [`wooorm/remark-license`](https://github.com/wooorm/remark-license)
     — Add a license section;
 
-*   [wooorm/remark-lint](https://github.com/wooorm/remark-lint)
+*   [`wooorm/remark-lint`](https://github.com/wooorm/remark-lint)
     — Markdown code style linter;
 
-*   [wooorm/remark-man](https://github.com/wooorm/remark-man)
+*   [`wooorm/remark-man`](https://github.com/wooorm/remark-man)
     — Compile Markdown to Man pages (roff);
 
-*   [ben-eb/remark-midas](https://github.com/ben-eb/remark-midas)
+*   [`ben-eb/remark-midas`](https://github.com/ben-eb/remark-midas)
     — Highlight CSS in Markdown files with [midas](https://github.com/ben-eb/midas);
 
-*   [eush77/remark-normalize-headings](https://github.com/eush77/remark-normalize-headings)
+*   [`eush77/remark-normalize-headings`](https://github.com/eush77/remark-normalize-headings)
     — Make sure there is no more than a single top-level heading in the document
 
-*   [wooorm/remark-range](https://github.com/wooorm/remark-range)
+*   [`wooorm/remark-range`](https://github.com/wooorm/remark-range)
     — Add range information;
 
-*   [mapbox/remark-react](https://github.com/mapbox/remark-react)
+*   [`mapbox/remark-react`](https://github.com/mapbox/remark-react)
     — Compile Markdown to [React](https://github.com/facebook/react);
 
-*   [wooorm/remark-reference-links](https://github.com/wooorm/remark-reference-links)
+*   [`wooorm/remark-reference-links`](https://github.com/wooorm/remark-reference-links)
     — Transform links and images into references and definitions;
 
-*   [wooorm/remark-retext](https://github.com/wooorm/remark-retext)
+*   [`wooorm/remark-retext`](https://github.com/wooorm/remark-retext)
     — [retext](https://github.com/wooorm/retext) support;
 
-*   [wooorm/remark-slug](https://github.com/wooorm/remark-slug)
+*   [`wooorm/remark-slug`](https://github.com/wooorm/remark-slug)
     — Add slugs to headings;
 
-*   [wooorm/remark-strip-badges](https://github.com/wooorm/remark-strip-badges)
+*   [`wooorm/remark-strip-badges`](https://github.com/wooorm/remark-strip-badges)
     — Remove badges (such as `shields.io`);
 
-*   [eush77/remark-squeeze-paragraphs](https://github.com/eush77/remark-squeeze-paragraphs)
+*   [`eush77/remark-squeeze-paragraphs`](https://github.com/eush77/remark-squeeze-paragraphs)
     — Remove empty paragraphs;
 
-*   [denysdovhan/remark-textr](https://github.com/denysdovhan/remark-textr)
-    — [Textr](https://github.com/shuvalov-anton/textr), a modular typographic
+*   [`denysdovhan/remark-textr`](https://github.com/denysdovhan/remark-textr)
+    — [`Textr`](https://github.com/shuvalov-anton/textr), a modular typographic
     framework;
 
-*   [wooorm/remark-toc](https://github.com/wooorm/remark-toc)
+*   [`wooorm/remark-toc`](https://github.com/wooorm/remark-toc)
     — Generate a Table of Contents (TOC) for Markdown files;
 
-*   [eush77/remark-unlink](https://github.com/eush77/remark-unlink)
+*   [`eush77/remark-unlink`](https://github.com/eush77/remark-unlink)
     — Remove all links, references and definitions;
 
-*   [wooorm/remark-usage](https://github.com/wooorm/remark-usage)
+*   [`wooorm/remark-usage`](https://github.com/wooorm/remark-usage)
     — Add a usage example to your readme;
 
-*   [wooorm/remark-validate-links](https://github.com/wooorm/remark-validate-links)
+*   [`wooorm/remark-validate-links`](https://github.com/wooorm/remark-validate-links)
     — Validate links point to existing headings and files;
 
-*   [wooorm/remark-vdom](https://github.com/wooorm/remark-vdom)
+*   [`wooorm/remark-vdom`](https://github.com/wooorm/remark-vdom)
     — Compile Markdown to [VDOM](https://github.com/Matt-Esch/virtual-dom/);
 
-*   [wooorm/remark-yaml](https://github.com/wooorm/remark-yaml)
+*   [`wooorm/remark-yaml`](https://github.com/wooorm/remark-yaml)
     — Parse and stringify YAML code blocks;
 
-*   [wooorm/remark-yaml-config](https://github.com/wooorm/remark-yaml-config)
+*   [`wooorm/remark-yaml-config`](https://github.com/wooorm/remark-yaml-config)
     — Set settings with YAML during runtime;
 
 ## List of Utilities
 
 Although not **remark** plug-ins, the following projects are useful when
 working with the AST ([**mdast**](https://github.com/wooorm/mdast)):
 
-*   [wooorm/mdast-util-definitions](https://github.com/wooorm/mdast-util-definitions)
+*   [`wooorm/mdast-util-definitions`](https://github.com/wooorm/mdast-util-definitions)
     — Find definition nodes;
 
-*   [wooorm/mdast-util-escape](https://github.com/wooorm/mdast-util-escape)
+*   [`wooorm/mdast-util-escape`](https://github.com/wooorm/mdast-util-escape)
     — Escape text to be inserted into a node;
 
-*   [wooorm/mdast-util-heading-range](https://github.com/wooorm/mdast-util-heading-range)
+*   [`wooorm/mdast-util-heading-range`](https://github.com/wooorm/mdast-util-heading-range)
     — Markdown heading as ranges;
 
-*   [wooorm/mdast-util-heading-style](https://github.com/wooorm/mdast-util-heading-style)
+*   [`wooorm/mdast-util-heading-style`](https://github.com/wooorm/mdast-util-heading-style)
     — Get the style of a heading (`"atx"`, `"atx-closed"`, or `"setext"`);
 
-*   [anandthakker/mdast-util-inject](https://github.com/anandthakker/mdast-util-inject)
+*   [`anandthakker/mdast-util-inject`](https://github.com/anandthakker/mdast-util-inject)
     — Inject one AST into another at a specified heading, keeping heading
     structure intact;
 
-*   [wooorm/mdast-util-position](https://github.com/wooorm/mdast-util-position)
+*   [`wooorm/mdast-util-position`](https://github.com/wooorm/mdast-util-position)
     — Get the position of nodes;
 
-*   [wooorm/mdast-util-to-string](https://github.com/wooorm/mdast-util-to-string)
+*   [`wooorm/mdast-util-to-string`](https://github.com/wooorm/mdast-util-to-string)
     — Get the plain text content of a node.
 
-*   [eush77/mdast-normalize-headings](https://github.com/eush77/mdast-normalize-headings)
+*   [`eush77/mdast-normalize-headings`](https://github.com/eush77/mdast-normalize-headings)
     — Make sure there is no more than a single top-level heading in the document
 
-*   [eush77/mdast-squeeze-paragraphs](https://github.com/eush77/mdast-squeeze-paragraphs)
+*   [`eush77/mdast-squeeze-paragraphs`](https://github.com/eush77/mdast-squeeze-paragraphs)
     — Remove empty paragraphs;
 
-*   [wooorm/mdast-zone](https://github.com/wooorm/mdast-zone)
+*   [`wooorm/mdast-zone`](https://github.com/wooorm/mdast-zone)
     — HTML comments as ranges or markers.
 
 In addition, see [`unist`](https://github.com/wooorm/unist#unist-node-utilties)
@@ -164,8 +164,8 @@ It is recommended to publish a plugin as an
 [npm module](https://docs.npmjs.com/getting-started/publishing-npm-packages).
 
 You should pick a name prefixed by `"remark-"`, valid examples are
-[**remark-toc**](https://www.npmjs.com/package/remark-toc) or
-[**remark-yaml-config**](https://www.npmjs.com/package/remark-yaml-config).
+[`remark-toc`](https://www.npmjs.com/package/remark-toc) or
+[`remark-yaml-config`](https://www.npmjs.com/package/remark-yaml-config).
 The reasoning here is that they can be used on the CLI without this prefix,
 but can still be meaningful. For example, `lint` was not available, but instead
 of opting for `liiint` or some other weird form, using `remark-lint` ensured a

doc/products.md

@@ -13,35 +13,35 @@ for a list of plugins and utilities.
 
 ### Apps
 
-*   [minodisk/markn](https://github.com/minodisk/markn)
+*   [`minodisk/markn`](https://github.com/minodisk/markn)
     — Lightweight markdown viewer.
 
-*   [rhysd/Shiba](https://github.com/rhysd/Shiba)
+*   [`rhysd/Shiba`](https://github.com/rhysd/Shiba)
     — Live markdown previewer with linter;
 
 ### CLI
 
-*   [wooorm/alex](https://github.com/wooorm/alex)
+*   [`wooorm/alex`](https://github.com/wooorm/alex)
     — Catch insensitive, inconsiderate writing;
 
-*   [hughsk/contributor-table](https://github.com/hughsk/contributor-table)
+*   [`hughsk/contributor-table`](https://github.com/hughsk/contributor-table)
     — Inject a list of git contributors
 
-*   [eush77/github-man](https://github.com/eush77/github-man)
+*   [`eush77/github-man`](https://github.com/eush77/github-man)
     — Open readme from GitHub repository as a man page.
 
-*   [man-n/man-n](https://github.com/man-n/man-n)
+*   [`man-n/man-n`](https://github.com/man-n/man-n)
     — Browse npm with man(1);
 
-*   [eush77/npm-man](https://github.com/eush77/npm-man)
+*   [`eush77/npm-man`](https://github.com/eush77/npm-man)
     — Open any package readme from npm as a man page.
 
-*   [dthree/wat](https://github.com/dthree/wat)
+*   [`dthree/wat`](https://github.com/dthree/wat)
     — Community-controlled cheat sheets for every coder.
 
 ### Atom
 
-*   [AtomLinter/linter-markdown](https://github.com/AtomLinter/linter-markdown)
+*   [`AtomLinter/linter-markdown`](https://github.com/AtomLinter/linter-markdown)
     — Lint markdown files within atom;
 
 *   [ZotPlus/zotero-citations](https://github.com/ZotPlus/zotero-citations)

doc/remark.3.md

@@ -24,13 +24,13 @@ var doc = processor.process([
 
 ## DESCRIPTION
 
-This is the application programming interface documentation for **remark**.
+These are the docs for the application programming interface of **remark**.
 To find documentation for the command line interface, see **remark**(1).
 
-## remark.use(plugin\[, options])
+## `remark.use(plugin[, options])`
 
 Change the way **remark** works by using a plugin.  Plugins are documented
-at <https://github.com/wooorm/remark/blob/master/doc/plugins.md>.
+at on GitHub.
 
 **Signatures**
 
@@ -49,7 +49,7 @@ at <https://github.com/wooorm/remark/blob/master/doc/plugins.md>.
 **remark** object itself (it has the same methods), but caches the `use`d
 plugins.
 
-## remark.parse(file\[, options])
+## `remark.parse(file[, options])`
 
 Parse a markdown document into an **mdast** node.
 
@@ -67,7 +67,7 @@ Parse a markdown document into an **mdast** node.
 
 `Node` — Node.  Nodes are documented at **mdast**.
 
-## remark.run(node\[, file]\[, done])
+## `remark.run(node[, file][, done])`
 
 Transform a node by applying plug-ins to it. Either a node or a file which
 was previously passed to `parse()`, must be given.
@@ -96,7 +96,7 @@ was previously passed to `parse()`, must be given.
 
 When no `node` was given and no node was found on the file.
 
-### function done(err, node, file)
+### `function done(err, node, file)`
 
 Invoked when transformation is complete.
 
@@ -111,7 +111,7 @@ Invoked when transformation is complete.
 *   `node` (`Node`) — Transformed node;
 *   `file` (`File`) — File object representing the input file;
 
-## remark.stringify(node\[, file]\[, options])
+## `remark.stringify(node[, file][, options])`
 
 Compile a node into a document.
 
@@ -135,7 +135,7 @@ Compile a node into a document.
 
 When no `node` was given and no node was found on the file.
 
-## remark.process(file\[, options]\[, done])
+## `remark.process(file[, options][, done])`
 
 Parse, transform, and compile markdown into something else.
 
@@ -156,7 +156,7 @@ Parse, transform, and compile markdown into something else.
 asynchronous generates. When an async transformer is used, `null` is
 returned and `done` must be given to receive the results upon completion.
 
-### function done(err?, doc?, file?)
+### `function done(err[, doc[, file]])`
 
 Invoked when processing is complete.
 
@@ -171,15 +171,15 @@ Invoked when processing is complete.
 *   `doc` (`string`) — Document generated by the process;
 *   `file` (`File`) — File object representing the input file;
 
-## FileSet()
+## `FileSet()`
 
 **remark**(1) compiles multiple files using a `FileSet` instance.  This set
 is exposed to plug-ins as an argument to the attacher. `FileSet`s
 should not be created by plug-ins.
 
-## fileSet.valueOf()
+## `fileSet.valueOf()`
 
-## fileSet.toJSON()
+## `fileSet.toJSON()`
 
 Get access to the file objects in a set.
 
@@ -191,7 +191,7 @@ Get access to the file objects in a set.
 
 `Array.<File>` — List of files being processed by **remark**(1).
 
-## fileSet.use(completer)
+## `fileSet.use(completer)`
 
 Add a completer to the middleware pipeline of a file-set.  When all
 files are transformed, this pipeline is run and `completer` is invoked
@@ -205,7 +205,7 @@ with `fileSet`.
 
 *   `completer` (`Function`).
 
-## fileSet.add(file|filePath)
+## `fileSet.add(file | filePath)`
 
 Add a new file to be processed by **remark**(1). The given file is
 processed just like other files, with a few differences.

doc/remarkconfig.7.md

@@ -17,8 +17,8 @@
 *   **remark**(1) additionally accepts configuration through a `settings`
     key in **remarkrc**(5) configuration files;
 
-*   Plug-ins can configure **remark**, for example, **remark-yaml-config**
-    allows per-file configuration to be set through YAML front-matter.
+*   Plug-ins can configure **remark**. For example, `remark-yaml-config`
+    allows configuration to be set through YAML front-matter.
 
 For a list of available configuration settings, see **remarksetting**(7).
 

doc/remarkignore.5.md

@@ -28,9 +28,8 @@ Each line in a **remarkignore**(5) file provides a pattern which describes to
 *   Lines which start with a interrogation-mark (`!`) negate, thus re-adding
     a previously ignored file path;
 
-For documentation regarding the glob engine itself, such as wild-cards
-(`*`, `?`), brace expressions (`{one,two}`), see
-[isaacs/minimatch](https://github.com/isaacs/minimatch).
+For documentation regarding support of wild-cards (`*`, `?`), brace
+expressions (`{one,two}`), and more, see [`minimatch`](https://github.com/isaacs/minimatch).
 
 You can pass a **gitignore**(5) file to **remark**(1), because it has the same
 format as **remarkignore**(5):