Update documentation

Author: jonathantneal

README.md

@@ -1,66 +1,70 @@
-# PostCSS :dir() [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]
+# PostCSS :dir() Pseudo [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]
 
 [![CSS Standard Status][css-img]][css-url]
 [![NPM Version][npm-img]][npm-url]
 [![Build Status][cli-img]][cli-url]
 [![Licensing][lic-img]][lic-url]
 [![Gitter Chat][git-img]][git-url]
 
-[PostCSS :dir()] lets you use the `:dir` pseudo-class in CSS, following the
-[Selectors] specification.
+[PostCSS :dir() Pseudo] lets you use the `:dir()` pseudo-class to style by
+directionality in CSS, following the [Selectors] specification.
 
 ```css
-.example:dir(rtl) {
+article h3:dir(rtl) {
   margin-right: 10px;
 }
 
-.example:dir(ltr) {
+article h3:dir(ltr) {
   margin-left: 10px;
 }
 
 /* becomes */
 
-[dir="rtl"] .example {
+[dir="rtl"] article h3 {
   margin-right: 10px;
 }
 
-[dir="ltr"] .example {
+[dir="ltr"] article h3 {
   margin-left: 10px;
 }
 ```
 
-If your [browserslist] already supports the `:dir` pseudo-class, this plugin
-will not change your CSS. You can learn more this by reading about the
-[`browsers` option](#browsers-option).
+### Future-proof your CSS
 
-[PostCSS :dir()] does not change selector weight, but does require at least one
-`[dir]` attribute in your HTML. If you don’t have _any_ `[dir]` attributes,
-consider using the following JavaScript:
+If your [browserslist] already supports the `:dir()` pseudo-class, this plugin
+will not change your CSS. Learn more about this feature in the
+[`browsers`](#browsers-option) section.
+
+### Maintain Specificity
+
+Using [PostCSS :dir() Pseudo] will not impact selector weight, but it will
+require having at least one `[dir]` attribute in your HTML. If you don’t have
+_any_ `[dir]` attributes, consider using the following JavaScript:
 
 ```js
 // force at least one dir attribute (this can run at any time)
 document.documentElement.dir=document.documentElement.dir||'ltr';
 ```
 
-If you absolutely cannot add a `[dir]` attribute in your HTML or force one via
-JavaScript, you can still get around this by presuming a direction in your CSS
-using the [`dir` option](#dir-option), but know that this will increase
-selector weight by one element (`html`).
+If you absolutely cannot add a `[dir]` attribute in your HTML or even force one
+via JavaScript, you can still work around this by presuming a direction in your
+CSS using the [`dir` option](#dir-option), but understand that this will
+sometimes increase selector weight by one element (`html`).
 
 ## Usage
 
-Add [PostCSS :dir()] to your build tool:
+Add [PostCSS :dir() Pseudo] to your build tool:
 
 ```bash
 npm install postcss-dir-pseudo-class --save-dev
 ```
 
 #### Node
 
-Use [PostCSS :dir()] to process your CSS:
+Use [PostCSS :dir() Pseudo] to process your CSS:
 
 ```js
-require('postcss-dir-pseudo-class').process(YOUR_CSS);
+require('postcss-dir-pseudo-class').process(YOUR_CSS /*, processConfig, options */);
 ```
 
 #### PostCSS
@@ -71,11 +75,11 @@ Add [PostCSS] to your build tool:
 npm install postcss --save-dev
 ```
 
-Use [PostCSS :dir()] as a plugin:
+Use [PostCSS :dir() Pseudo] as a plugin:
 
 ```js
 postcss([
-  require('postcss-dir-pseudo-class')()
+  require('postcss-dir-pseudo-class')(/* Options */)
 ]).process(YOUR_CSS);
 ```
 
@@ -87,15 +91,15 @@ Add [Gulp PostCSS] to your build tool:
 npm install gulp-postcss --save-dev
 ```
 
-Use [PostCSS :dir()] in your Gulpfile:
+Use [PostCSS :dir() Pseudo] in your Gulpfile:
 
 ```js
 var postcss = require('gulp-postcss');
 
 gulp.task('css', function () {
   return gulp.src('./src/*.css').pipe(
     postcss([
-      require('postcss-dir-pseudo-class')()
+      require('postcss-dir-pseudo-class')(/* Options */)
     ])
   ).pipe(
     gulp.dest('.')
@@ -111,7 +115,7 @@ Add [Grunt PostCSS] to your build tool:
 npm install grunt-postcss --save-dev
 ```
 
-Use [PostCSS :dir()] in your Gruntfile:
+Use [PostCSS :dir() Pseudo] in your Gruntfile:
 
 ```js
 grunt.loadNpmTasks('grunt-postcss');
@@ -120,7 +124,7 @@ grunt.initConfig({
   postcss: {
     options: {
       use: [
-        require('postcss-dir-pseudo-class')()
+        require('postcss-dir-pseudo-class')(/* Options */)
       ]
     },
     dist: {
@@ -132,7 +136,7 @@ grunt.initConfig({
 
 ---
 
-## browsers option
+## Browsers Option
 
 If your [browserslist] already supports the `:dir` pseudo-class, this plugin
 will not change your CSS. While only Firefox currently supports `:dir`, this
@@ -170,9 +174,9 @@ In both of these examples, the CSS would remain unchanged.
 }
 ```
 
-## dir option
+## Dir Option
 
-By default, this plugin requires you to specify a direction `[dir]` attribute
+By default, this plugin requires you to include a direction `[dir]` attribute
 in your HTML, preferably on the `html` element. If you prefer not to, you
 can presume a direction in your CSS using the `dir` option.
 
@@ -196,7 +200,7 @@ require('postcss-dir-pseudo-class')({
 
 /* becomes */
 
-:not([dir="rtl"]) .example {
+html:not([dir="rtl"]) .example {
   margin-left: 10px;
 }
 
@@ -205,9 +209,6 @@ require('postcss-dir-pseudo-class')({
 }
 ```
 
-*Note: The `:root` pseudo-class is added here to preserve the weight of the
-original selector.*
-
 [cli-url]: https://travis-ci.org/jonathantneal/postcss-dir-pseudo-class
 [cli-img]: https://img.shields.io/travis/jonathantneal/postcss-dir-pseudo-class.svg
 [css-img]: https://jonathantneal.github.io/css-db/badge/selectors-the-dir-pseudo.svg
@@ -223,5 +224,5 @@ original selector.*
 [Gulp PostCSS]: https://github.com/postcss/gulp-postcss
 [Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
 [PostCSS]: https://github.com/postcss/postcss
-[PostCSS :dir()]: https://github.com/jonathantneal/postcss-dir-pseudo-class
+[PostCSS :dir() Pseudo]: https://github.com/jonathantneal/postcss-dir-pseudo-class
 [Selectors]: https://drafts.csswg.org/selectors-4/#the-dir-pseudo