diff --git a/README.md b/README.md
index 57468a4f..9cbec4c7 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
[![Tailor](https://cloud.githubusercontent.com/assets/1350704/9867389/18ae2e06-5b3b-11e5-9b37-72a3e9621b9c.png)](https://tailor.sh)
+
@@ -25,43 +26,57 @@
[Tailor][] is a cross-platform [static analysis][] and [lint][] tool for source code written in Apple's [Swift][] programming language. It analyzes your code to ensure consistent styling and help avoid bugs.
-# [Tailor][]. Cross-platform static analyzer and linter for [Swift][].
+[static analysis]: https://en.wikipedia.org/wiki/Static_program_analysis
+[lint]: https://en.wikipedia.org/wiki/Lint_(software)
+
+## [Tailor][]. Cross-platform static analyzer and linter for [Swift][].
+
+[Tailor]: https://tailor.sh
+[Swift]: https://swift.org
+
Tailor supports Swift 2 out of the box and helps enforce style guidelines outlined in the [The Swift Programming Language][], [GitHub][], [Ray Wenderlich][], and [Coursera][] style guides. It supports cross-platform usage and can be run on Mac OS X via your shell or integrated with Xcode, as well as on Linux and Windows.
+[The Swift Programming Language]: https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/
+[GitHub]: https://github.com/github/swift-style-guide
+[Ray Wenderlich]: https://github.com/raywenderlich/swift-style-guide
+[Coursera]: https://github.com/coursera/swift-style-guide
+
Tailor parses Swift source code using the primary Java target of [ANTLR](http://www.antlr.org):
> ANTLR is a powerful parser generator [ . . . ] widely used in academia and industry to build all sorts of languages, tools, and frameworks.
--- [About the ANTLR Parser Generator](http://www.antlr.org/about.html)
+— [About the ANTLR Parser Generator](http://www.antlr.org/about.html)
**See the [wiki](https://github.com/sleekbyte/tailor/wiki) for the full documentation.**
# Getting Started
+
## Installation
-Requires Java (JRE or JDK) Version 8 or above: [Java SE Downloads](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
-### [Homebrew](http://brew.sh), [Linuxbrew](http://brew.sh/linuxbrew/)
+Requires Java (JRE or JDK) Version 8 or above: [Java SE Downloads](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
+#### [Homebrew](http://brew.sh), [Linuxbrew](http://brew.sh/linuxbrew/)
```bash
brew install tailor
```
-### Mac OS X (10.10+), Linux
+#### Mac OS X (10.10+), Linux
```bash
curl -fsSL https://tailor.sh/install.sh | sh
```
-### Windows (10+)
+#### Windows (10+)
```powershell
iex (new-object net.webclient).downloadstring('https://tailor.sh/install.ps1')
```
-### Manually
+#### Manually
You may also download Tailor via [GitHub Releases](https://github.com/sleekbyte/tailor/releases), extract the archive, and symlink the `tailor/bin/tailor` shell script to a location in your `$PATH`.
-### Continuous Integration
+#### Continuous Integration
+
If your continuous integration server supports [Homebrew](http://brew.sh) installation, you may use the following snippet:
```yaml
@@ -82,6 +97,7 @@ before_script:
```
## Usage
+
Run Tailor with a list of files and directories to analyze, or via Xcode.
```bash
@@ -126,88 +142,88 @@ Options:
```
# Features
-- [Enabling and Disabling Rules](#enabling-and-disabling-rules)
-- [Cross-Platform](#cross-platform)
-- [Automatic Xcode Integration](#automatic-xcode-integration)
-- [Colorized Output](#colorized-output)
-- [Warnings, Errors, and Failing the Build](#warnings-errors-and-failing-the-build)
-- [Disable Violations within Source Code](#disable-violations-within-source-code)
-- [Configuration](#configuration)
-- [Formatters](#formatters)
-
-## Enabling and Disabling Rules
+* [Enabling and Disabling Rules](#enabling-and-disabling-rules)
+* [Cross-Platform](#cross-platform)
+* [Automatic Xcode Integration](#automatic-xcode-integration)
+* [Colorized Output](#colorized-output)
+* [Warnings, Errors, and Failing the Build](#warnings-errors-and-failing-the-build)
+* [Disable Violations within Source Code](#disable-violations-within-source-code)
+* [Configuration](#configuration)
+* [Formatters](#formatters)
+
+### Enabling and Disabling Rules
+
**Rule identifiers and "preferred/not preferred" code samples may be found on the [Rules](https://github.com/sleekbyte/tailor/wiki/Rules) page.**
Rules may be individually disabled (blacklist) or enabled (whitelist) via the `--except` and `--only` command-line flags.
-### Except
-
+#### Except
```bash
tailor --except=brace-style,trailing-whitespace main.swift
```
-### Only
-
+#### Only
```bash
tailor --only=redundant-parentheses,terminating-semicolon main.swift
```
-## Cross-Platform
+### Cross-Platform
Tailor may be used on Mac OS X via your shell or integrated with Xcode, as well as on Linux and Windows.
-### Linux
+#### Linux
![Tailor on Ubuntu](https://cloud.githubusercontent.com/assets/1350704/9894130/2b959794-5bee-11e5-9ed2-84d035895239.png)
-### Windows
+#### Windows
![Tailor on Windows](https://cloud.githubusercontent.com/assets/1791760/9913016/2ff0e9a8-5cc8-11e5-8722-d5a6f9d84027.PNG)
-## Automatic Xcode Integration
+### Automatic Xcode Integration
Tailor can be integrated with Xcode projects using the `--xcode` option.
-
```bash
tailor --xcode /path/to/demo.xcodeproj/
```
+This adds the following Build Phase Run Script to your project's default target.
+![Run Script](https://cloud.githubusercontent.com/assets/1350704/11074861/5bae6b24-87f2-11e5-8167-4328b9b01174.png)
-This adds the following Build Phase Run Script to your project's default target. ![Run Script](https://cloud.githubusercontent.com/assets/1350704/11074861/5bae6b24-87f2-11e5-8167-4328b9b01174.png)
+Tailor's output will be displayed inline within the Xcode Editor Area and as a list in the Log Navigator.
+![Xcode messages](https://cloud.githubusercontent.com/assets/1350704/11017260/b79cb162-8599-11e5-94fa-e7cf77fdc657.png)
-Tailor's output will be displayed inline within the Xcode Editor Area and as a list in the Log Navigator. ![Xcode messages](https://cloud.githubusercontent.com/assets/1350704/11017260/b79cb162-8599-11e5-94fa-e7cf77fdc657.png)
-## Colorized Output
+### Colorized Output
Tailor uses the following color schemes to format CLI output:
-- **Dark theme** (enabled by default)
-- ![Dark theme](https://cloud.githubusercontent.com/assets/1791760/9807444/fde82de6-5870-11e5-9e20-05a9d736e136.png)
-- **Light theme** (enabled via `--invert-color` option)
-- ![Light theme](https://cloud.githubusercontent.com/assets/1791760/9807312/129ce45e-586f-11e5-8e26-fe818af0ec09.png)
-- **No color theme** (enabled via `--no-color` option)
-- ![No color](https://cloud.githubusercontent.com/assets/1791760/9807318/261811d4-586f-11e5-9010-0e627431bbb9.png)
-
-## Warnings, Errors, and Failing the Build
+
+* **Dark theme** (enabled by default)
+![Dark theme](https://cloud.githubusercontent.com/assets/1791760/9807444/fde82de6-5870-11e5-9e20-05a9d736e136.png)
+* **Light theme** (enabled via `--invert-color` option)
+![Light theme](https://cloud.githubusercontent.com/assets/1791760/9807312/129ce45e-586f-11e5-8e26-fe818af0ec09.png)
+* **No color theme** (enabled via `--no-color` option)
+![No color](https://cloud.githubusercontent.com/assets/1791760/9807318/261811d4-586f-11e5-9010-0e627431bbb9.png)
+
+### Warnings, Errors, and Failing the Build
`--max-severity` can be used to control the maximum severity of violation messages. It can be set to `error` or `warning` (by default, it is set to `warning`). Setting it to `error` allows you to distinguish between lower and higher priority messages. It also fails the build in Xcode, if any errors are reported (similar to how a compiler error fails the build in Xcode). With `max-severity` set to `warning`, all violation messages are warnings and the Xcode build will never fail.
This setting also affects Tailor's exit code on the command-line, a failing build will `exit 1` whereas having warnings only will `exit 0`, allowing Tailor to be easily integrated into pre-commit hooks.
-## Disable Violations within Source Code
+### Disable Violations within Source Code
Violations on a specific line may be disabled with a **trailing** single-line comment.
-
```swift
import Foundation; // tailor:disable
```
-## Configuration
+### Configuration
The behavior of Tailor can be customized via the `.tailor.yml` configuration file. It enables you to
-- include/exclude certain files and directories from analysis
-- enable and disable specific analysis rules
-- specify output format
+* include/exclude certain files and directories from analysis
+* enable and disable specific analysis rules
+* specify output format
+* specify CLI output color scheme
You can tell Tailor which configuration file to use by specifying its file path via the `--config` CLI option. By default, Tailor will look for the configuration file in the directory where you will run Tailor from.
The file follows the [YAML 1.1](http://www.yaml.org/spec/1.1/) format.
-### Including/Excluding files
+#### Including/Excluding files
Tailor checks all files found by a recursive search starting from the directories given as command line arguments. However, it only analyzes Swift files that end in `.swift`. If you would like Tailor to analyze specific files and directories, you will have to add entries for them under `include`. Files and directories can also be ignored through `exclude`.
Here is an example that might be used for an iOS project:
-
```YAML
include:
- Source # Inspect all Swift files under "Source/"
@@ -217,17 +233,16 @@ exclude:
- Source/Pods # Ignore Swift files under "Source/Pods/"
```
-#### Notes
-- Files and directories are specified relative to where `tailor` is run from
-- Paths to directories or Swift files provided explicitly via CLI will cause the `include`/`exclude` rules specified in `.tailor.yml` to be ignored
-- _Exclude_ is given higher precedence than _Include_
-- Tailor recognizes the [Java Glob](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob) syntax
+##### Notes
+* Files and directories are specified relative to where `tailor` is run from
+* Paths to directories or Swift files provided explicitly via CLI will cause the `include`/`exclude` rules specified in `.tailor.yml` to be ignored
+* *Exclude* is given higher precedence than *Include*
+* Tailor recognizes the [Java Glob](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob) syntax
-### Enabling/Disabling rules
+#### Enabling/Disabling rules
Tailor allows you to individually disable (blacklist) or enable (whitelist) rules via the `except` and `only` labels.
Here is an example showcasing how to enable certain rules:
-
```YAML
# Tailor will solely check for violations to the following rules
only:
@@ -238,7 +253,6 @@ only:
```
Here is an example showcasing how to disable certain rules:
-
```YAML
# Tailor will check for violations to all rules except for the following ones
except:
@@ -246,11 +260,11 @@ except:
- lower-camel-case
```
-#### Notes
-- _only_ is given precedence over _except_
-- Rules that are explicitly included/excluded via CLI will cause the `only`/`except` rules specified in `.tailor.yml` to be ignored
+##### Notes
+* *only* is given precedence over *except*
+* Rules that are explicitly included/excluded via CLI will cause the `only`/`except` rules specified in `.tailor.yml` to be ignored
-### Specifying output format
+#### Specifying output format
Tailor allows you to specify the output format (`xcode`/`json`) via the `format` label.
Here is an example showcasing how to specify the output format:
@@ -260,13 +274,27 @@ Here is an example showcasing how to specify the output format:
format: json
```
-#### Notes
+##### Note
- The output format explicitly specified via CLI will cause the output format defined in `.tailor.yml` to be ignored
-## Formatters
+#### Specifying CLI output color scheme
+Tailor allows you to specify the CLI output color schemes via the `color` label. To disable colored output, set `color` to `disable`. To invert the color scheme, set `color` to `invert`.
+
+Here is an example showcasing how to specify the CLI output color scheme:
+
+```YAML
+# The CLI output will not be colored
+format: disable
+```
+
+##### Note
+- The CLI output color scheme explicitly specified via CLI will cause the output color scheme defined in `.tailor.yml` to be ignored
+
+### Formatters
Tailor's output format may be customized via the `-f`/`--format` option. The Xcode formatter is selected by default.
-### Xcode Formatter (default)
+#### Xcode Formatter (default)
+
The default `xcode` formatter outputs violation messages according to the format expected by Xcode to be displayed inline within the Xcode Editor Area and as a list in the Log Navigator. This format is also as human-friendly as possible on the console.
```
@@ -282,7 +310,8 @@ $ tailor main.swift
Analyzed 1 file, skipped 0 files, and detected 5 violations (0 errors, 5 warnings).
```
-### [JSON](http://www.json.org) Formatter
+#### [JSON](http://www.json.org) Formatter
+
The `json` formatter outputs an array of violation messages for each file, and a `summary` object indicating the parsing results and the violation counts.
```