[Command Line] Cleanup of the command-line usage output to make things more digestable.

lib/compass/exec.rb

@@ -80,14 +80,24 @@ module Compass
 Usage: compass [options] [project]
 
 Description:
-  When project is given, generates a new project of that name as a subdirectory of
+  The compass command line tool will help you create and manage the stylesheets for your project.
-  the current directory.
   
-  If you change any source files, you can update your project using --update.
+  To get started on a stand-alone project based on blueprint:
 
-Options:
+    compass -f blueprint my_compass_project
+
+  When you change any sass files, you must recompile your project using --update or --watch.
 END
-        opts.on('-u', '--update', :NONE, 'Update the current project') do
+        opts.separator ''
+        opts.separator 'Mode Options(only specify one):'
+
+        opts.on('-i', '--install', :NONE, "Create a new compass project.",
+                                          "  The default mode when a project is provided.") do
+          self.options[:command] = :create_project
+        end
+
+        opts.on('-u', '--update', :NONE, 'Update the current project.',
+                                         '  This is the default when no project is provided.') do
           self.options[:command] = :update_project
         end
 
@@ -96,19 +106,54 @@ END
           self.options[:quiet] = true
         end
 
-        opts.on('-f FRAMEWORK', '--framework FRAMEWORK', 'Use the specified framework.') do |framework|
+        opts.on('-p', '--pattern PATTERN', 'Stamp out a pattern into the current project.',
-          self.options[:framework] = framework
+                                           '  Must be used with -f.') do |pattern|
-        end
-
-        opts.on('-p', '--pattern PATTERN', 'Stamp out a pattern into the current project. Must be used in combination with -f.') do |pattern|
           self.options[:command] = :stamp_pattern
           self.options[:pattern] = pattern
         end
 
-        opts.on('-n', '--pattern-name NAME', 'The name to use when stamping a pattern. Must be used in combination with -p.') do |name|
+        opts.on('--write-configuration', "Write the current configuration to the configuration file.") do
+          self.options[:command] = :write_configuration
+        end
+
+        opts.on('--list-frameworks', "List compass frameworks available to use.") do
+          self.options[:command] = :list_frameworks
+        end
+
+        opts.on('--validate', :NONE, 'Validate your project\'s compiled css. Requires Java.') do
+          self.options[:command] = :validate_project
+        end
+
+        opts.on('--grid-img [DIMENSIONS]', 'Generate a background image to test grid alignment.',
+                                           '  Dimension is given as <column_width>+<gutter_width>.',
+                                           '  Defaults to 30+10.') do |dimensions|
+          self.options[:grid_dimensions] = dimensions || "30+10"
+          unless self.options[:grid_dimensions] =~ /^\d+\+\d+$/
+            puts "Please enter your dimensions as <column_width>+<gutter_width>. E.g. 20+5 or 30+10."
+            exit
+          end
+          self.options[:command] = :generate_grid_background
+        end
+
+        opts.separator ''
+        opts.separator 'Install/Pattern Options:'
+
+        opts.on('-f FRAMEWORK', '--framework FRAMEWORK', 'Use the specified framework. Only one may be specified.') do |framework|
+          self.options[:framework] = framework
+        end
+
+        opts.on('-n', '--pattern-name NAME', 'The name to use when stamping a pattern.',
+                                             '  Must be used in combination with -p.') do |name|
           self.options[:pattern_name] = name
         end
 
+        opts.on('--rails', "Sets the project type to a rails project.") do
+          self.options[:project_type] = :rails
+        end
+
+        opts.separator ''
+        opts.separator 'Configuration Options:'
+
         opts.on('--sass-dir SRC_DIR', "The source directory where you keep your sass stylesheets.") do |sass_dir|
           self.options[:sass_dir] = sass_dir
         end
@@ -121,32 +166,27 @@ END
           self.options[:images_dir] = images_dir
         end
 
-        opts.on('--javascripts-dir JAVASCRIPTS_DIR', "The directory where you keep your javascripts.") do |javascripts_dir|
+        opts.on('--javascripts-dir JS_DIR', "The directory where you keep your javascripts.") do |javascripts_dir|
           self.options[:javascripts_dir] = javascripts_dir
         end
 
-        opts.on('--list-frameworks', "List compass frameworks available to use.") do
+        opts.on('-e ENV', '--environment ENV', [:development, :production], 'Use sensible defaults for your current environment.',
-          self.options[:command] = :list_frameworks
+                '  One of: development, production (default)') do |env|
-        end
-
-        opts.on('-c', '--write-configuration', "Write the current configuration to the configuration file.") do
-          self.options[:command] = :write_configuration
-        end
-
-        opts.on('-e ENV', '--environment ENV', [:development, :production], 'Use sensible defaults for your current environment: development, production (default)') do |env|
           self.options[:environment] = env
         end
 
-        opts.on('-s STYLE', '--output-style STYLE', [:nested, :expanded, :compact, :compressed], 'Select a CSS output mode (nested, expanded, compact, compressed)') do |style|
+        opts.on('-s STYLE', '--output-style STYLE', [:nested, :expanded, :compact, :compressed], 'Select a CSS output mode.',
+                 '  One of: nested, expanded, compact, compressed') do |style|
           self.options[:output_style] = style
         end
 
-        opts.on('-r LIBRARY', '--require LIBRARY', "Require LIBRARY before running commands. This is used to access compass plugins.") do |library|
+        opts.separator ''
-          ::Compass.configuration.require library
+        opts.separator 'General Options:'
-        end
 
-        opts.on('--rails', "Sets the project type to a rails project.") do
+        opts.on('-r LIBRARY', '--require LIBRARY', "Require the given ruby LIBRARY before running commands.",
-          self.options[:project_type] = :rails
+                                                   "  This is used to access compass plugins without having a",
+                                                   "  project configuration file.") do |library|
+          ::Compass.configuration.require library
         end
         
         opts.on('-q', '--quiet', :NONE, 'Quiet mode.') do
@@ -161,11 +201,13 @@ END
           self.options[:trace] = true
         end
         
-        opts.on('--force', :NONE, 'Force. Allows some commands to succeed when they would otherwise fail.') do
+        opts.on('--force', :NONE, 'Force. Allows some failing commands to succeed instead.') do
           self.options[:force] = true
         end
 
-        opts.on('--imports', :NONE, 'Emit an import path suitable for use with the Sass command-line tool.') do
+        opts.on('--imports', :NONE, 'Emit an imports suitable for passing to the sass command-line.',
+                                    '  Example: sass `compass --imports`',
+                                    '  Note: Compass\'s Sass extensions will not be available.') do
           print ::Compass::Frameworks::ALL.map{|f| "-I #{f.stylesheets_directory}"}.join(' ')
           exit
         end
@@ -175,10 +217,6 @@ END
           exit
         end
 
-        opts.on('--validate', :NONE, 'Validate your project\'s compiled css. Requires Java.') do
-          self.options[:command] = :validate_project
-        end
-
         opts.on_tail("-?", "-h", "--help", "Show this message") do
           puts opts
           exit
@@ -188,15 +226,6 @@ END
           self.options[:command] = :print_version
         end
 
-        opts.on('--grid-img [DIMENSIONS]', 'Generate a background image to test grid alignment. Dimension is given as <column_width>+<gutter_width>. Defaults to 30+10.') do |dimensions|
-          self.options[:grid_dimensions] = dimensions || "30+10"
-          unless self.options[:grid_dimensions] =~ /^\d+\+\d+$/
-            puts "Please enter your dimensions as <column_width>+<gutter_width>. E.g. 20+5 or 30+10."
-            exit
-          end
-          self.options[:command] = :generate_grid_background
-        end
-
       end
       
       def do_command(command)