Updated the changelog to be easier to read

package.xml

@@ -26,53 +26,72 @@ http://pear.php.net/dtd/package-2.0.xsd">
  </stability>
  <license uri="https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt">BSD 3-Clause License</license>
  <notes>
-  - Caching between runs (--cache, --no-cache and "cache" config var) (request #530)
-    -- Use --cache=/path/to/cacheFile to use a specific file
-  - Check files in parallel (--parallel=1 for off, --parallel=100 etc) (request #421)
-  - Default encoding changed from iso-8859-1 to utf-8 (request #760)
-    -- encoding config option still works, but no longer have to set it to get utf-8 strings
-    -- if you are already setting encoding to utf-8 in a ruleset or on CLI, you can remove it
-    -- still need to have the iconv extension installed for utf-8 strings to be processed correctly
+  - Added optional caching of results between runs (request #530)
+    -- Enable the cache by using the --cache command line argument
+    -- If you want the cache file written somewhere specific, use --cache=/path/to/cacheFile
+    -- Use the command "phpcs --config-set cache true" to turn caching on by default
+    -- Use the --no-cache command line argument to disable caching if it is being turned on automatically
+  - Add support for checking file in parallel (request #421)
+    -- Tell PHPCS how many files to check at once using the --parallel command line argument
+    -- To check 100 files at once, using --parallel=100
+    -- To disable parallel checking if it is being turned on automatically, use --parallel=1
+    -- Requires PHP to be compiled with the PCNTL package
+  - The default encoding has been changed from iso-8859-1 to utf-8 (request #760)
+    -- The --encoding command line argument still works, but you no longer have to set it to process files as utf-8
+    -- If encoding is being set to utf-8 in a ruleset or on the CLI, it can be safely removed
+    -- If the iconv PHP extension is not installed, standard non-multibyte aware functions will be used
   - Added a new "code" report type to show a code snippet for each error (request #419)
-    -- The line containing the error is printed, with 2 lines above and below
-    -- The location of the errors is underlined in the code
-    -- Use --report=code to try it out
+    -- The line containing the error is printed, along with 2 lines above and below it to show context
+    -- The location of the errors is underlined in the code snippet if you also use --colors
+    -- Use --report=code to generate this report
   - Added support for custom filtering of the file list
-    -- use --filter=/path/to/filter.php to filter the list
-    -- extend \PHP_CodeSniffer\Filters\Filter to also get the basic PHPCS ext/path filtering
-    -- extend \PHP_CodeSniffer\Filters\ExactMatch to get the basic filtering + ability to use blacklists and whitelists
-    -- included filter \PHP_CodeSniffer\Filters\GitModified is a good example of an ExactMatch filter
-    -- use --filter=gitmodified to only check modified and added files in a git repo
-  - Automatic discovery of executable paths (request #571)
+    -- Developers can write their own filter classes to perform custom filtering of the list before the run starts
+    -- Use the command line arg --filter=/path/to/filter.php to specify a filter to use
+    -- Extend \PHP_CodeSniffer\Filters\Filter to also support the core PHPCS extension and path filtering
+    -- Extend \PHP_CodeSniffer\Filters\ExactMatch to get the core filtering and the ability to use blacklists and whitelists
+    -- The included \PHP_CodeSniffer\Filters\GitModified filter is a good example of an ExactMatch filter
+  - Added support for only checking files that have been locally modified or added in a git repo
+    -- Use --filter=gitmodified to check these files
+    -- You still need to give PHPCS a list of files or directories in which to check
+  - Added automatic discovery of executable paths (request #571)
     -- Thanks to Sergey Morozov for the patch
-  - Must pass '-' on the cli to have PHPCS wait for STDIN
-    -- Can still pass content on STDIN as normal
-  - All sniff errors are now exceptions and caught to stop infinite loops
-  - Sniff codes are no longer optional - use them with addError/Warning/Fixable
-  - installed_paths config setting can now point directly to a standard instead of the dir above
-  - --report=full,summary,info instead of --report=full --report=summary --report=info
-  - Can now set severity, message type and exclude patterns for entire sniff, category or standard
-  - Can include a single sniff code, which will exclude all other codes from that sniff
-    -- if the sniff is already included by an imported standard, set sniff severity to 0 and include the specific message you want
-  - phpcbf no longer uses patch - files are always overwritten (--no-patch option has been removed)
-  - Added --basepath option to strip a directory from the front of file paths in output (request #470)
-    -- the basepath is absolute or relative to the current directory
-    -- to make paths relative to current dir, use --basepath=.
+  - You must now pass "-" on the command line to have PHPCS wait for STDIN
+    -- E.g., phpcs --standard=PSR2 -
+    -- You can still pipe content via STDIN as normal as PHPCS will see this and process it
+    -- But without the "-", PHPCS will throw an error if no content or files are passed to it
+  - All PHP errors generated by sniffs are caught, re-thrown as expections, and reported in the standard error reports
+    -- This should stop bugs inside sniffs causing infinite loops
+    -- Also stops invalid reports being produced as errors don't print to the screen directly
+  - Sniff codes are no longer optional
+    -- If a sniff throws and error or a warning, it must specify an internal code for that message
+  - The installed_paths config setting can now point directly to a standard
+    -- Previously, it had to always point to the directory in which the standard lives
+  - Multiple reports can now be specified using the --report command line argument
+    -- Report types are separated by commas
+    -- E.g., --report=full,summary,info
+    -- Previously, you had to use one argument for each report such as --report=full --report=summary --report=info
+  - You can now set the severity, message type, and exclude patterns for and entire sniff, category, or standard
+    -- Previously, this was only available for a single message
+  - You can now include a single sniff code in a ruleset instead of having to include an entire sniff
+    -- Including a sniff code will automatically exclude all other messages from that sniff
+    -- If the sniff is already included by an imported standard, set the sniff severity to 0 and include the specific message you want
+  - PHPCBF no longer uses patch
+    -- Files are now always overwritten
+    -- The --no-patch option has been removed
+  - Added a --basepath option to strip a directory from the front of file paths in output (request #470)
+    -- The basepath is absolute or relative to the current directory
+    -- E.g., to output paths relative to current dir in reports, use --basepath=.
   - Ignore rules are now checked when using STDIN (request #733)
-  - Added include-pattern tag to include a sniff for specific files and folders only (request #656)
-    -- exact opposite of the exclude-pattern tag
-    -- only useable within sniffs, not globally like exclude-patterns are
-  - Added -m option to stop error messages from being recorded, which saves a lot of memory
-    -- PHPCBF always uses this setting to reduce memory
-    -- Setting $recordErrors in custom reports no longer supported
-  - Exit code 2 now used to indicate fixable errors were found (request #930)
-    -- Exit code 3 now used for general script execution errors
-    -- Exit code 1 used to indicate that coding standard errors were found, but none are fixable
+  - Added an include-pattern tag to rulesets to include a sniff for specific files and folders only (request #656)
+    -- This is the exact opposite of the exclude-pattern tag
+    -- This options is only useable within sniffs, not globally like exclude-patterns are
+  - Added a new -m option to stop error messages from being recorded, which saves a lot of memory
+    -- PHPCBF always uses this setting to reduce memory as it never outputs error messages
+    -- Setting the $recordErrors member var inside custom report classes is no longer supported (use -m instead)
+  - Exit code 2 is now used to indicate fixable errors were found (request #930)
+    -- Exit code 3 is now used for general script execution errors
+    -- Exit code 1 is used to indicate that coding standard errors were found, but none are fixable
     -- Exit code 0 is unchanged and continues to mean no coding standard errors found
-
-  - Squiz.WhiteSpace.LanguageConstructSpacing no longer checks for spaces if parenthesis are being used (request #1062)
-    -- Makes this sniff more compatibile with those that check parenthesis spacing of function calls
-  - Fixed bug #1066 : Undefined index: quiet in CLI.php during unit test run with -v command line arg
  </notes>
  <contents>
   <dir name="/">