Extend CLI documentation

Author: jugglinmike

pages/cli.md

@@ -1,8 +1,123 @@
 { "title": "JSHint CLI flags", "url": "/docs/cli", "template": "docs" }
 
-# CLI flags
+# Command-line Interface
 
-The JSHint CLI program accepts the following flags:
+The JSHint CLI can be installed via npm (see [the Installation page](/install)
+for instructions).
+
+Contents: [Specifying Input](#specifying-input) · [Specifying Linting
+Options](#specifying-linting-options) · [Special Options](#special-options) ·
+[Ignoring Files](#ignoring-files) · [Flags](#flags)
+
+<a name="specifying-input"></a>
+
+### Specifying Input
+
+The `jshint` executable accepts paths to files, which it will read and lint:
+
+    $ jshint myfile.js
+    myfile.js: line 10, col 39, Octal literals are not allowed in strict mode.
+
+    1 error
+
+If a file path is a dash (`-`) then JSHint will read from standard input.
+
+<a name="specifying-linting-options"></a>
+
+### Specifying Linting Options
+
+The `jshint` executable is capable of applying [linting options](/docs/options)
+specified in an external [JSON](http://json.org/)-formatted file. Such a file
+might look like this:
+
+    {
+      "curly": true,
+      "eqeqeq": true,
+      "nocomma": true
+    }
+
+`jshint` will look for this configuration in a number of locations, stopping at
+the first positive match:
+
+1. The location specified with the `--config` [flag](#flags)
+2. A file named `package.json` located in the current directory or any parent
+   of the current directory (the configuration should be declared as the
+   `jshintConfig` attribute of that file's JSON value)
+3. A file named `.jshintrc` located in the current directory or any parent of
+   the current directory
+4. A file named `.jshintrc` located in the current user's "home" directory
+   (where defined)
+
+If this search yields no results, `jshint` will lint the input code as if no
+linting rules had been enabled.
+
+The command-line interface offers some [special options](#special-options) in
+addition to [the ones available in other contexts](/docs/options)
+
+<a name="special-options"></a>
+
+### Special Options
+
+The following options concern the file system and are only available from
+within configuration files (i.e. not from inline directives or the API):
+
+#### `extends`
+
+Use another configuration file as a "base". The value of this option should be
+a file path to another configuration file, and the path should be relative to
+the current file.
+
+For example, you might define a `.jshintrc` file in the top-level directory of
+your project (say, `./.jshintrc') to specify the [linting
+options](/docs/options) you would like to use in your entire project:
+
+    {
+      "undef": true,
+      "unused": true
+    }
+
+You may want to re-use this configuration for your project's automated tests,
+but also [allow for global
+variables](http://localhost:4000/docs/options#globals) that are specific to the
+test environment.  In this case, you could create a a new file in their test
+directory, (`./test/.jshintrc` for example), and include the following
+configuration:
+
+    {
+      "extends": "../.jshintrc",
+      "globals": {
+        "test": false,
+        "assert": false
+      }
+    }
+
+#### `overrides`
+
+Specify options that should only be applied to files matching a given path
+pattern.
+
+The following configuration file [disallows variable
+shadowing](/docs/options#shadow) for *all* files and [allows expressions as
+statements](/docs/options#expr) for only those files ending in `-test.js`:
+
+    {
+      "shadow": false,
+      "overrides": {
+        "lib/*-test.js": {
+          "expr": true
+        }
+      }
+    }
+
+<a name="ignoring-files"></a>
+
+### Ignoring Files
+
+TODO
+
+<a name="flags"></a>
+
+### Flags
 
 #### `--config`
 

pages/docs.md

@@ -6,8 +6,9 @@ JSHint is a program that flags suspicious usage in programs written in JavaScrip
 The core project consists of a library itself as well as a CLI program distributed
 as a Node module.
 
-More docs: [List of all JSHint options](/docs/options/) · [CLI flags](/docs/cli/) · 
-[Writing your own reporter](/docs/reporters/) · [FAQ](/docs/faq/)
+More docs: [List of all JSHint options](/docs/options/) · [Command-line
+Interface](/docs/cli/) · [Writing your own reporter](/docs/reporters/) ·
+[FAQ](/docs/faq/)
 
 ### Basic usage
 
@@ -18,16 +19,7 @@ working directory):
 
     $ npm install jshint -g
 
-After you've done that you should be able to use the `jshint` program. The
-simplest use case would be linting a single file or all JavaScript files in
-a directory:
-
-    $ jshint myfile.js
-    myfile.js: line 10, col 39, Octal literals are not allowed in strict mode.
-
-    1 error
-
-If a file path is a dash (`-`) then JSHint will read from standard input.
+After you've done that you should be able to use the `jshint` program.
 
 ### Configuration