README.rdoc in tailor-0.1.5 vs README.rdoc in tailor-1.0.0.alpha

@@ -3,64 +3,197 @@
 * http://github.com/turboladen/tailor
 
 == DESCRIPTION:
 
 tailor recursively parses Ruby files in a directory and checks them for bad 
-style.  Rules for judging style are based on a number of style guides that are popular in the Ruby community.  More on this
-here http://wiki.github.com/turboladen/tailor.
+style.  Rules for judging style are based on a number of style guides that are
+popular in the Ruby community.  More on this here
+http://wiki.github.com/turboladen/tailor.
 
 == FEATURES/PROBLEMS:
 
-* Checks for bad style in .rb and .erb files
+* Checks for bad style in Ruby files
   * Recursively in a directory, or...
-  * A given file
+  * A given file, or...
+  * A glob ('lib/**/*.rb')
 * Checks for:
-  * Indentation
-    * Hard-tabs in indentation
+  * Horizontal spacing
+    * Indentation
+    * Use of hard-tabs
+    * Line length
+    * Trailing spaces at the end of lines
+    * Spacing after commas
+    * Spacing before commas
+    * Spacing around { and before }
+    * Spacing after [ and before ]
+    * Spacing after ( and before )
+  * Vertical spacing
+    * Trailing newlines (at the end of the file)
+    * Max code lines in a class/module
+    * Max code lines in a method
   * Name cases
     * Snake case class & module names
     * Camel case method names
-  * Extra whitespace
-    * At the end of lines
-    * On empty lines
-    * Around commas
-    * Around open/closed parentheses
-    * Around open/closed square brackets
-    * Around open/closed curly braces
-    * Around colons in ternary statements
-  * Line length
-    * Should be <= 80 characters
+* Configurable
+  * Specify style in
+    * ~./tailorrc
+    * PROJECT_ROOT + .tailor
+    * as CLI options
+  * "File sets" allow for applying different styles to different sets of files
+* CI/Build Integration
+  * (Well, this may be stretching things a bit, but...) Exit 1 on failures
 
 == SYNOPSIS:
 
+=== Why style check?
+
+If you're reading this, there's a good chance you already have your own reasons
+for doing so.  If you're not familiar with static analysis, give tailor a go
+for a few days and see if you think it improves your code's readability.
+
+=== What's it do?
+
+At tailor's inception, there were some other static analysis tools for Ruby,
+but none which checked style stuff; tailor started off as a means to fill this
+gap.  Since then, a number of those tools have dropped by the wayside due to
+various Ruby 1.9 incompatibilities, and left a bigger tool gap for Rubyists.
+Right now it's mostly a style-checker, but might also have a future role in
+analyzing other aspects of your Ruby code.
+
+=== Since 0.x...
+
+tailor 1.x is a marked improvment over 0.x.  While 0.x provided a few (pretty
+inconsistent) style checks, its design made the code get all spaghetti-like,
+with lots of really gnarly regular expression matching, making it a realy bear
+to add new features and fix bugs.  tailor 1.x is completely redesigned to make
+that whole process much easier.
+
+=== Measure Stuff
+
 Run tailor like:
 
   $ tailor path/to/check/
+
 ...or...
-  $ tail file_to_check.rb
 
-There are a number of false-positives and false-negatives in detection of the
-above rules, so please don't expect perfection in this detection.  :)  I'm
-working on solving this.
+  $ tailor file_to_check.rb
 
+...or...
+
+  $ tailor test/**/*.rb
+
+...or... (defaults to lib/**/*.rb):
+
+  $ tailor
+
+There are still a number of false-positives and false-negatives in detection of
+the above rules, so please don't expect perfection in this detection.  :)
+
+=== Configurable:
+
+Not everyone prefers the same style of, well, anything really.  tailor is
+configurable to allow you to check your code against the style measurements
+that you want.
+
+It has default values for each of the "rulers" it uses, but if you want to
+customize these, there are a number of ways you can do so.
+
+==== CLI
+
+At any time, you can tell tailor to show you the configuration that it's going
+to use by doing:
+
+  $ tailor --show-config
+
+To see, amongst other options, the style options that you can pass in, do
+
+  $ tailor --help
+
+If, for example, you want to tell tailor to warn you if any of your code lines
+are > 100 chars (instead of the default of 80):
+
+  $ tailor --max-line-length 100 lib/
+
+If you want to simply disable a ruler, just pass +false+ to the option:
+
+  $ tailor --max-line-length false lib/
+
+==== Configuration File
+
+Configuration files allow for some more flexibility with style rulers, file
+lists, and (eventually) report formatters.  To create one with default
+settings, do:
+
+  $ tailor --create-config
+
+With the documentation that's provided in the file, the settings should be
+straightforward (if they're not, please let me know!).  You don't have to specify
+all of those settings in your config file--those are just rendered so you have
+a starting ground to tweak with.  If you only want to override a single value,
+you can delete the rest of the code from your config.  This would accomplish
+the same as the --max-line-length example above:
+
+  # .tailor
+  Tailor.config do |config|
+    config.file_set :default do
+      max_line_length 100
+    end
+  end
+
+This brings us to the concept of "file sets"...
+
+===== File Sets
+
+File sets allow you to use different style rulers against different groups of
+files.  You may, for example, want your Rails app code to allow for longer
+lines, or fewer code lines in methods... You may want your RSpec code to be
+more lenient with curly-brace usage... You may just want to specify a few file
+globs to use the default set of rulers...  File sets allow for those sorts of
+things.
+
+In the default config file, you see a single parameter being passed to
+<tt>config.file_set</tt>--this is the _label_ for that file set.  The label is
+simply just a name to refer to that file set by; it will show in your report
+(in the case that problems were found, of course) so you know what set of
+rulers caused the problem to be found.  <tt>config.file_set</tt> also takes
+a second paramter: the file/directory/glob to apply the style to.
+
+  # .tailor
+  Tailor.config do |config|
+    config.file_set :rails_app, 'app/**/*.rb' do
+      max_line_length 100
+      # All other rulers will use default values
+    end
+
+    config.file_set :features, 'features/**/*.rb'     # Uses default style
+
+    config.file_set :rspec, 'spec/**/*.rb' do
+      spaces_after_lbrace false
+      spaces_before_lbrace false
+      spaces_before_rbrace false
+      # All other rulers will use default values
+    end
+  end
+
 == REQUIREMENTS:
 
 * Rubies (tested)
- * 1.8.7
- * 1.9.2
- * 1.9.3-preview1
+  * 1.9.2
+  * 1.9.3
 * Gems
+  * log_switch
   * term-ansicolor
+  * text-table
 
 == INSTALL:
 
   $ (sudo) gem install tailor
 
 == LICENSE:
 
 (The MIT License)
 
-Copyright (c) 2010-2011 Steve Loveless
+Copyright (c) 2010-2012 Steve Loveless
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
 'Software'), to deal in the Software without restriction, including
 without limitation the rights to use, copy, modify, merge, publish,