Refactor docs

Author: wooorm

readme.md

@@ -42,19 +42,22 @@ This specification is written in a [Web IDL][webidl]-like grammar.
 
 ### Where this specification fits
 
-esast extends [unist][], a format for syntax trees, to benefit from its
-[ecosystem of utilities][utilities].
+esast extends [unist][],
+a format for syntax trees,
+to benefit from its [ecosystem of utilities][utilities].
 There is one important difference with other implementations of unist: children
 are added at fields other than the `children` array and the `children` field is
 not used.
 
 esast relates to [ESTree][] in that the first is a superset of the latter.
 Any tool that accepts an ESTree also supports esast.
 
-esast relates to [JavaScript][], other than that it represents it, in that it
-has an [ecosystem of utilities][list-of-utilities] for working with compliant
-syntax trees in JavaScript.
-However, esast is not limited to JavaScript and can be used in other programming
+esast relates to [JavaScript][],
+other than that it represents it,
+in that it has an [ecosystem of utilities][list-of-utilities] for working with
+compliantsyntax trees in JavaScript.
+However,
+esast is not limited to JavaScript and can be used in other programming
 languages.
 
 esast relates to the [unified][] project in that esast syntax trees are used
@@ -64,17 +67,21 @@ throughout its ecosystem.
 
 ESTree is great but it is missing some things:
 
-* Trees can’t be roundtripped through `JSON.parse(JSON.stringify(s))`,
+* trees can’t be roundtripped through `JSON.parse(JSON.stringify(s))`,
   leading to cache troubles
-* Columns are 0-indexed, whereas most text editors display 1-indexed
-  columns, leading to a tiny discrepancy or some math to display warnings
-* There is no recommendation for range-based positional info,
+* columns are 0-indexed,
+  whereas most text editors display 1-indexed columns,
+  leading to a tiny discrepancy or some math to display warnings
+* there is no recommendation for range-based positional info,
   leading implementations to scatter them in different places
-* There is no safe space for metadata,
+* there is no safe space for metadata,
   leading implementations to scatter them in different places
-* There are no recommendations for how to handle JSX, comments, or raw values
+* there are no recommendations for how to handle JSX,
+  comments,
+  or raw values
 
-These are minor nits, which is why esast is a superset.
+These are minor nits,
+which is why esast is a superset.
 
 ## Nodes
 
@@ -85,8 +92,8 @@ extend interface Node <: UnistNode {}
 ```
 
 All esast nodes inherit from unist’s [Node][unist-node] and are otherwise the
-same as their ESTree counterparts, with the exception of `RegExpLiteral` and
-`BigIntLiteral`.
+same as their ESTree counterparts,
+with the exception of `RegExpLiteral` and `BigIntLiteral`.
 
 ### `RegExpLiteral`
 
@@ -104,22 +111,27 @@ must be ignored.
 
 ## Recommendations
 
-For JSX, follow the
+For JSX,
+follow the
 [JSX extension](https://github.com/facebook/jsx/blob/master/AST.md)
 maintained in `facebook/jsx`.
 
-For type annotations, follow the
+For type annotations,
+follow the
 [Type annotations extension](https://github.com/estree/estree/blob/master/extensions/type-annotations.md)
 maintained in `estree/estree`.
 
 `raw` fields (added by most parsers) should not be used: they create an extra
-source of truth, which is often not maintained.
+source of truth,
+which is often not maintained.
 
-`start`, `end`, and `range` fields should not be used.
+`start`,
+`end`,
+and `range` fields should not be used.
 
 `comments` should not be added on nodes other that `Program`.
-When adding comments, use the `'Block'` (for `/**/`) or `'Line'` (for `//`)
-types.
+When adding comments,
+use the `'Block'` (for `/**/`) or `'Line'` (for `//`) types.
 Do not use `leading` or `trailing` fields on comment nodes.
 
 `tokens` should not be used.
@@ -130,13 +142,15 @@ See the [unist glossary][glossary] but note of the following deviating terms.
 
 ###### Child
 
-Node X is **child** of node Y, if X is either referenced directly or referenced
-in an array at a field on node Y.
+Node X is **child** of node Y,
+if X is either referenced directly or referenced in an array at a field on
+node Y.
 
 ###### Sibling
 
-Node X is a **sibling** of node Y, if X and Y have the same parent (if any) and
-X and Y are both referenced in an array at a field on node Y.
+Node X is a **sibling** of node Y,
+if X and Y have the same parent (if any) and X and Y are both referenced in an
+array at a field on node Y.
 
 ## List of utilities
 
@@ -159,7 +173,8 @@ See the [unist list of utilities][utilities] for more utilities.
 * [`esast-util-from-js`](https://github.com/syntax-tree/esast-util-from-js)
   — parse from JavaScript
 
-Please use either `estree-util-` (if it works with all ESTrees, preferred)
+Please use either `estree-util-` (if it works with all ESTrees,
+preferred)
 or `esast-util-` (if it uses on esast specific features) as a prefix.
 
 See also the [`estree`](https://github.com/search?q=topic%3Aestree\&s=stars\&o=desc)
@@ -184,8 +199,9 @@ topic on GitHub.
 
 ## Security
 
-As esast represents JS, and JS can open you up to a bunch of problems, esast is
-also unsafe.
+As esast represents JS,
+and JS can open you up to a bunch of problems,
+esast is also unsafe.
 Always be careful with user input.
 
 ## Related
@@ -202,12 +218,17 @@ ways to get started.
 See [`support.md`][support] for ways to get help.
 Ideas for new utilities and tools can be posted in [`syntax-tree/ideas`][ideas].
 
-A curated list of awesome syntax-tree, unist, mdast, esast, xast, and nlcst
-resources can be found in [awesome syntax-tree][awesome].
+A curated list of awesome `syntax-tree`,
+unist,
+mdast,
+esast,
+xast,
+and nlcst resources can be found in [awesome syntax-tree][awesome].
 
 This project has a [code of conduct][coc].
-By interacting with this repository, organization, or community you agree to
-abide by its terms.
+By interacting with this repository,
+organization,
+or community you agree to abide by its terms.
 
 ## Acknowledgments