Improve the coverage of the README (#995) (#1000)

* Improve the coverage of the README (#995)

* Revert formatting changes

* revert formatting changes

* revert formatting changes

* Add explanation for -vv flag

* tweaking docs

* more tweaks

Co-authored-by: Andrew Bradley <cspotcode@gmail.com>

README.md

@@ -23,6 +23,8 @@ npm install -g ts-node
 
 ## Usage
 
+### Shell
+
 ```sh
 # Execute a script as `node` + `tsc`.
 ts-node script.ts
@@ -38,10 +40,33 @@ ts-node -p -e '"Hello, world!"'
 
 # Pipe scripts to execute with TypeScript.
 echo 'console.log("Hello, world!")' | ts-node
+
+# Equivalent to ts-node --script-mode
+ts-node-script scripts.ts
+
+# Equivalent to ts-node --transpile-only
+ts-node-transpile-only scripts.ts
 ```
 
 ![TypeScript REPL](https://github.com/TypeStrong/ts-node/raw/master/screenshot.png)
 
+### Shebang
+
+```typescript
+#!/usr/bin/env ts-node-script
+
+console.log("Hello, world!")
+```
+
+`ts-node-script` is recommended because it enables `--script-mode`, discovering `tsconfig.json` relative to the script's location instead of `process.cwd()`.  This makes scripts more portable.
+
+Passing CLI arguments via shebang is allowed on Mac but not Linux.  For example, the following will fail on Linux:
+
+```
+#!/usr/bin/env ts-node --script-mode --transpile-only --files
+// This shebang is not portable.  It only works on Mac
+```
+
 ### Programmatic
 
 You can require `ts-node` and register the loader for future requires by using `require('ts-node').register({ /* options */ })`. You can also use file shortcuts - `node -r ts-node/register` or `node -r ts-node/register/transpile-only` - depending on your preferences.
@@ -122,36 +147,42 @@ Create a new Node.js configuration and add `-r ts-node/register` to "Node parame
 
 **Typescript Node** loads `tsconfig.json` automatically. Use `--skip-project` to skip loading the `tsconfig.json`.
 
+It is resolved relative to `--dir` using [the same search behavior as `tsc`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).  In `--script-mode`, this is the directory containing the script.  Otherwise it is resolved relative to `process.cwd()`, which matches the behavior of `tsc`.
+
+Use `--project` to specify the path to your `tsconfig.json`, ignoring `--dir`.
+
 **Tip**: You can use `ts-node` together with [tsconfig-paths](https://www.npmjs.com/package/tsconfig-paths) to load modules according to the `paths` section in `tsconfig.json`.
 
 ## Configuration Options
 
-You can set options by passing them before the script path, via programmatic usage or via environment variables.
+You can set options by passing them before the script path, via programmatic usage, via `tsconfig.json`, or via environment variables.
 
 ```sh
 ts-node --compiler ntypescript --project src/tsconfig.json hello-world.ts
 ```
 
-**Note:** [`ntypescript`](https://github.com/TypeStrong/ntypescript#readme) is an example of a TypeScript compatible `compiler`.
+**Note:** [`ntypescript`](https://github.com/TypeStrong/ntypescript#readme) is an example of a TypeScript-compatible `compiler`.
 
 ### CLI Options
 
-Supports `--print`, `--eval`, `--require` and `--interactive` similar to the [node.js CLI options](https://nodejs.org/api/cli.html).
+`ts-node` supports `--print` (`-p`), `--eval` (`-e`), `--require` (`-r`) and `--interactive` (`-i`) similar to the [node.js CLI options](https://nodejs.org/api/cli.html).
 
-* `--help` Prints help text
-* `--version` Prints version information
+* `-h, --help` Prints the help text
+* `-v, --version` Prints the version. `-vv` prints node and typescript compiler versions, too
+* `-s, --script-mode` Resolve config relative to the directory of the passed script instead of the current directory. Changes default of `--dir`
 
 ### CLI and Programmatic Options
 
-_Environment variable denoted in parentheses._
+_The name of the environment variable and the option's default value are denoted in parentheses._
 
 * `-T, --transpile-only` Use TypeScript's faster `transpileModule` (`TS_NODE_TRANSPILE_ONLY`, default: `false`)
+* `-H, --compiler-host` Use TypeScript's compiler host API (`TS_NODE_COMPILER_HOST`, default: `false`)
 * `-I, --ignore [pattern]` Override the path patterns to skip compilation (`TS_NODE_IGNORE`, default: `/node_modules/`)
 * `-P, --project [path]` Path to TypeScript JSON project file (`TS_NODE_PROJECT`)
 * `-C, --compiler [name]` Specify a custom TypeScript compiler (`TS_NODE_COMPILER`, default: `typescript`)
 * `-D, --ignore-diagnostics [code]` Ignore TypeScript warnings by diagnostic code (`TS_NODE_IGNORE_DIAGNOSTICS`)
 * `-O, --compiler-options [opts]` JSON object to merge with compiler options (`TS_NODE_COMPILER_OPTIONS`)
-* `--dir` Specify working directory for config resolution (`TS_NODE_CWD`, default: `process.cwd()`)
+* `--dir` Specify working directory for config resolution (`TS_NODE_CWD`, default: `process.cwd()`, or `dirname(scriptPath)` if `--script-mode`)
 * `--scope` Scope compiler to files within `cwd` (`TS_NODE_SCOPE`, default: `false`)
 * `--files` Load `files`, `include` and `exclude` from `tsconfig.json` on startup (`TS_NODE_FILES`, default: `false`)
 * `--pretty` Use pretty diagnostic formatter (`TS_NODE_PRETTY`, default: `false`)
@@ -161,11 +192,27 @@ _Environment variable denoted in parentheses._
 * `--prefer-ts-exts` Re-order file extensions so that TypeScript imports are preferred (`TS_NODE_PREFER_TS_EXTS`, default: `false`)
 * `--log-error` Logs TypeScript errors to stderr instead of throwing exceptions (`TS_NODE_LOG_ERROR`, default: `false`)
 
-### Programmatic Only Options
+### Programmatic-only Options
+
+* `transformers` `_ts.CustomTransformers | ((p: _ts.Program) => _ts.CustomTransformers)`: An object with transformers or a function that accepts a program and returns an transformers object to pass to TypeScript. Function isn't available with `transpileOnly` flag
+* `readFile`: Custom TypeScript-compatible file reading function
+* `fileExists`: Custom TypeScript-compatible file existence function
+
+### Options via tsconfig.json
+
+Most options can be specified by a `"ts-node"` object in `tsconfig.json` using their programmatic, camelCase names. For example, to enable `--transpile-only`:
+
+```json
+// tsconfig.json
+{
+  "ts-node": {
+    "transpileOnly": true
+  },
+  "compilerOptions": {}
+}
+```
 
-* `transformers` `_ts.CustomTransformers | ((p: _ts.Program) => _ts.CustomTransformers)` An object with transformers or a function that accepts a program and returns an transformers object to pass to TypeScript. Function isn't available with `transpileOnly` flag
-* `readFile` Custom TypeScript-compatible file reading function
-* `fileExists` Custom TypeScript-compatible file existence function
+Our bundled [JSON schema](https://unpkg.com/browse/ts-node@8.8.2/tsconfig.schema.json) lists all compatible options.
 
 ## SyntaxError
 
@@ -183,7 +230,7 @@ For global definitions, you can use the `typeRoots` compiler option.  This requi
 
 Example `tsconfig.json`:
 
-```
+```json
 {
   "compilerOptions": {
     "typeRoots" : ["./node_modules/@types", "./typings"]
@@ -193,7 +240,7 @@ Example `tsconfig.json`:
 
 Example project structure:
 
-```
+```text
 <project_root>/
 -- tsconfig.json
 -- typings/
@@ -203,7 +250,7 @@ Example project structure:
 
 Example module declaration file:
 
-```
+```typescript
 declare module '<module_name>' {
     // module definitions go here
 }