Merge branch 'stable'

* stable:
  Print out the new style help with -h and --help instead of the old-style help.
  clean up the docs on the fancy-type module in blueprint.
  update some comments and formatting
  make the docs on extensions a bit more clear for rubygems extensions.
  official gradients still need image declared
  fix typo in docs
  Print a better error message if the extension isn't found.
  versions change.
  prepare for release
  Update docs
  Update docs
  A command to unpack an extension from the system location.

Conflicts:
	VERSION.yml
	doc-src/content/CHANGELOG.markdown

VERSION.yml

@@ -3,4 +3,3 @@
 :minor: 11
 :state: alpha
 :build: 0
-

doc-src/Gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: /Users/chris/Projects/compass
   specs:
-    compass (0.10.5.pre.0)
+    compass (0.10.5)
       haml (>= 3.0.4)
 
 GEM

doc-src/content/CHANGELOG.markdown

@@ -7,9 +7,8 @@ layout: article
 COMPASS CHANGELOG
 =================
 
-<<<<<<< HEAD:doc-src/content/CHANGELOG.markdown
+0.11.alpha.1 (UNRELEASED)
-0.11.alpha.1
+-------------------------
-------------
 
 * Deprecated imports and APIs from v0.10 have been removed.
 
@@ -21,27 +20,8 @@ COMPASS CHANGELOG
 * Some color defaults now use color functions instead of color arithmetic.
   This may result in different output for those who have color customizations.
 
-0.10.3
-------
 
-### CSS3 Module
+0.10.5 (08/29/2010)
-
-* Deprecations: 
-  - `+font-face` mixin no longer uses `$postscript` name or
-  `$stle` type variables, in favor of the Paul Irish [smiley bulletproof
-  technique](http://paulirish.com/2009/bulletproof-font-face-implementation-syntax/).
-  Older declarations will still work, but will not apply the varaibles and
-  will throw a deprecation warning. 
-* `+box-shadow` now supports `$spread` length and `$inset` declarations.
-* The gradient mixins output official w3c declarations along with the
-  `-webkit` and `-moz` prefixed versions. The official code is based on the
-  w3c spec and is nearly ideantical to the mozilla version, although it is
-  currently not supported by any browser.
-* `+opacity` no longer uses any prefixed variations, as IE uses `filter` and
-  all other modern browsers support the official spec or nothing at all.
-
-=======
-0.10.5 (UNRELEASED)
 -------------------
 
 * The [HTML5 Reset mixin][html5-reset] now resets the following new elements:
@@ -55,6 +35,8 @@ COMPASS CHANGELOG
   treated as paths instead of relative directories so
   `--css-dir /var/www/docroot/css` will set `css_path`. Should both a directory
   and a path be specified, the path will override the corresponding directory.
+* A new command is available that will unpack an extension from the system location into
+  your extensions folder. Run `compass help unpack` for more information.
 
 0.10.4 (8/08/2010)
 ------------------
@@ -112,7 +94,6 @@ This will fix a bug in the rails initializer that caused compass extensions to n
 * [Milo Winningham](http://github.com/quadule)
 * [jonathanpberger](http://github.com/jonathanpberger)
 * [Stephan Kaag](http://github.com/stephankaag)
->>>>>>> stable:doc-src/content/CHANGELOG.markdown
 
 0.10.2 (May 31, 2010)
 ---------------------
@@ -120,6 +101,7 @@ This will fix a bug in the rails initializer that caused compass extensions to n
 This is a bug fix release. [Details on Github.](http://github.com/chriseppstein/compass/compare/v0.10.1...v0.10.2)
 
 0.10.1 (May 15, 2010)
+---------------------
 
 * Fixed a regression in the Blueprint module, the blueprint reset
   was no longer automatically applying the reset styles. This behavior

doc-src/content/examples/compass/css3/border_radius/markup.haml

@@ -18,7 +18,7 @@
   %p
     Box with only bottom right corner rounded
 
-#border-radiusTop.border-radius-example
+#border-radius-top.border-radius-example
   %p
     Box with top corners rounded
 

doc-src/content/tutorials/command-line.markdown

@@ -88,6 +88,10 @@ Misc commands
 
     compass version
 
+### Unpack a framework or extension into your project
+
+    compass unpack <extension>
+
 Get Help on the Command Line
 ----------------------------
 

doc-src/content/tutorials/extensions.markdown

@@ -80,7 +80,7 @@ The extension library file referenced above as `my_extension/lib/my_extension.rb
 can actually be stored at any of the following three locations:
 
 1. `my_extension/compass_init.rb`
-2. `my_extension/lib/my_extension.rb`
+2. `my_extension/lib/my_extension.rb` (NOTE: You must use this one if you're distributing as a rubygem.)
 3. `my_extension/my_extension.rb`
 
 The first of those locations found (in the above order) will be loaded.

frameworks/blueprint/stylesheets/blueprint/_fancy-type.scss

@@ -1,12 +1,12 @@
 @import "typography";
 
 $alternate-text-font : "Warnock Pro", "Goudy Old Style", "Palatino", "Book Antiqua", Georgia, serif !default;
-// To install the fancy type plugin:
-//   1. import the fancy_type module: @import blueprint/fancy_type
-//   2. mixin +fancy-type to your project's body or at the top level of your stylesheet:
-//     body
-//       +fancy-type
 
+// To install the fancy type plugin:
+//
+// 1. Import the fancy_type module: `@import "blueprint/fancy_type"`
+// 2. Mix in `fancy-type` to your project's body or at the top level of your stylesheet:<br>
+//    `body { @include fancy-type; }`
 @mixin fancy-type {
   @include fancy-paragraphs;
   .caps { @include caps; }
@@ -14,16 +14,8 @@ $alternate-text-font : "Warnock Pro", "Goudy Old Style", "Palatino", "Book Antiq
   .alt  { @include alt;  }
 }
 
-// Indentation instead of line shifts for sibling paragraphs. Mixin to a style like p + p
-@mixin sibling-indentation {
-  text-indent: 2em;
-  margin-top: -1.5em;
-  /* Don't want this in forms. */
-  form & { text-indent: 0; }
-}
-
 // For great looking type, use this code instead of asdf: 
-// <span class="alt">asdf</span>  
+// `<span class="alt">asdf</span>`
 // Best used on prepositions and ampersands.
 
 @mixin alt {
@@ -34,16 +26,15 @@ $alternate-text-font : "Warnock Pro", "Goudy Old Style", "Palatino", "Book Antiq
 }
 
 // For great looking quote marks in titles, replace "asdf" with:
-// <span class="dquo">&#8220;</span>asdf&#8221;
+// `<span class="dquo">&#8220;</span>asdf&#8221;`
 // (That is, when the title starts with a quote mark). 
-// (You may have to change this value depending on your font size).
+// Note: you may have to change this value depending on your font size.
 
 @mixin dquo($offset: 0.5em) {
   margin-left: -$offset;
 }
 
-// Reduced size type with incremental leading
+// Reduced size type with [incremental leading](http://www.markboulton.co.uk/journal/comments/incremental_leading/)
-// (http://www.markboulton.co.uk/journal/comments/incremental_leading/)
 //
 // This could be used for side notes. For smaller type, you don't necessarily want to 
 // follow the 1.5x vertical rhythm -- the line-height is too much. 
@@ -52,9 +43,9 @@ $alternate-text-font : "Warnock Pro", "Goudy Old Style", "Palatino", "Book Antiq
 // every four lines of normal sized type, there is five lines of the sidenote. eg:
 //
 // Arguments:
-//   `$font-size` - The desired font size in pixels. This will be converted to ems for you. Defaults to 10px.
+// * `$font-size` - The desired font size in pixels. This will be converted to ems for you. Defaults to 10px.
-//   `$base-font-size` - The base font size in pixels. Defaults to 12px
+// * `$base-font-size` - The base font size in pixels. Defaults to 12px
-//   `$old-line-height` - The old line height. Defaults to 1.5 times the base-font-size
+// * `$old-line-height` - The old line height. Defaults to 1.5 times the base-font-size
 
 @mixin incr(
   $font-size: 10px,
@@ -67,7 +58,7 @@ $alternate-text-font : "Warnock Pro", "Goudy Old Style", "Palatino", "Book Antiq
 }
 
 // Surround uppercase words and abbreviations with this class.
-// Based on work by Jørgen Arnor Gårdsø Lom [http://twistedintellect.com/]
+// Based on work by [Jørgen Arnor Gårdsø Lom](http://twistedintellect.com/)
 
 @mixin caps {
   font-variant: small-caps;
@@ -79,8 +70,18 @@ $alternate-text-font : "Warnock Pro", "Goudy Old Style", "Palatino", "Book Antiq
   padding: 0 2px;
 }
 
+// This mixin is automatically included when you include `fancy-type`
 @mixin fancy-paragraphs {
   p + p   { @include sibling-indentation; }
   p.incr,
   .incr p { @include incr; }
 }
+
+// Indentation instead of line shifts for sibling paragraphs. Mixin to a selector like `p + p`
+@mixin sibling-indentation {
+  text-indent: 2em;
+  margin-top: -1.5em;
+  /* Don't want this in forms. */
+  form & { text-indent: 0; }
+}
+

frameworks/blueprint/templates/project/partials/_base.sass

@@ -6,6 +6,6 @@ $blueprint-container-size : 950px
 $blueprint-grid-margin    : 10px
 
 // Use this to calculate the width based on the total width.
-// Or you can set !blueprint_grid_width to a fixed value and unset !blueprint_container_size -- it will be calculated for you.
+// Or you can set $blueprint-grid-width to a fixed value and unset $blueprint-container-size -- it will be calculated for you.
 $blueprint-grid-width: ($blueprint-container-size + $blueprint-grid-margin) / $blueprint-grid-columns - $blueprint-grid-margin
 

frameworks/blueprint/templates/semantic/partials/_base.sass

@@ -1,10 +1,10 @@
 // Here is where you can define your constants for your application and to configure the blueprint framework.
 // Feel free to delete these if you want keep the defaults:
 
-$blueprint-grid-columns: 24
+$blueprint-grid-columns   : 24
-$blueprint-container-size: 950px
+$blueprint-container-size : 950px
-$blueprint-grid-margin: 10px
+$blueprint-grid-margin    : 10px
 
 // Use this to calculate the width based on the total width.
-// Or you can set !blueprint_grid_width to a fixed value and unset !blueprint_container_size -- it will be calculated for you.
+// Or you can set $blueprint-grid-width to a fixed value and unset $blueprint-container-size -- it will be calculated for you.
 $blueprint-grid-width: ($blueprint-container-size + $blueprint-grid-margin) / $blueprint-grid-columns - $blueprint-grid-margin

frameworks/compass/stylesheets/compass/css3/_gradient.scss

@@ -44,7 +44,7 @@
   @if $experimental-support-for-mozilla {
     background-image: #{$background}-moz-linear-gradient($start, $color-stops);
   }
-  background-image: linear-gradient($start, $color-stops);
+  background-image: #{$background}linear-gradient($start, $color-stops);
 }
 
 // Due to limitation's of webkit, the radial gradient mixin works best if you use
@@ -78,5 +78,5 @@
   @if $experimental-support-for-mozilla {
     background-image: #{$background}-moz-radial-gradient($center-position, circle, $color-stops);
   }
-  background-image: radial-gradient($center-position, circle, $color-stops);
+  background-image: #{$background}radial-gradient($center-position, circle, $color-stops);
 }

lib/compass/commands.rb

@@ -6,6 +6,6 @@ require 'compass/commands/registry'
 %w(base generate_grid_background help list_frameworks project_base
    update_project watch_project create_project imports installer_command
    print_version project_stats stamp_pattern validate_project
-   write_configuration interactive).each do |lib|
+   write_configuration interactive unpack_extension).each do |lib|
   require "compass/commands/#{lib}"
 end

lib/compass/commands/project_base.rb

@@ -24,7 +24,7 @@ module Compass
       def configure!
         add_project_configuration
         Compass.add_configuration(options, "command_line")
-        Compass.discover_extensions!
+        Compass.discover_extensions! unless skip_extension_discovery?
       end
 
       def add_project_configuration
@@ -88,6 +88,10 @@ module Compass
         path.index(File::SEPARATOR) == 0
       end
 
+      def skip_extension_discovery?
+        false
+      end
+
     end
   end
 end

lib/compass/commands/unpack_extension.rb

@@ -0,0 +1,120 @@
+require 'compass/commands/project_base'
+require 'fileutils'
+
+module Compass
+  module Commands
+    module ExtensionOptionsParser
+      def set_options(opts)
+        opts.banner = %Q{
+          Usage: compass unpack EXTENSION
+
+          Description:
+            Copy an extension into your extensions folder for easy access to the source code.
+            This makes it easier to peruse the source in unfamiliar projects. It is not recommended
+            that you change other extensions' source -- this makes it hard to take updates from
+            the original author. The following extensions are available:
+            
+          FRAMEWORKS
+            
+          Options:
+        }.strip.split("\n").map{|l| l.gsub(/^ {0,10}/,'')}.join("\n")
+        opts.banner.gsub!(/FRAMEWORKS/,Compass::Frameworks.pretty_print(true))
+        super
+      end
+    end
+
+    class UnpackExtension < ProjectBase
+
+      register :unpack
+
+      def initialize(working_path, options)
+        super
+        assert_project_directory_exists!
+      end
+
+      def perform
+        framework = Compass::Frameworks[options[:framework]]
+        unless framework
+          raise Compass::Error, "No extension named \"#{options[:framework]}\" was found."
+        end
+        files = Dir["#{framework.path}/**/*"]
+        extension_dir = File.join(Compass.configuration.extensions_path, framework.name)
+        FileUtils.rm_rf extension_dir
+        FileUtils.mkdir_p extension_dir
+        write_file File.join(extension_dir, "DO_NOT_MODIFY"), readme(framework)
+        files.each do |f|
+          next if File.directory?(f)
+          ending = f[(framework.path.size+1)..-1]
+          destination = File.join(extension_dir, ending)
+          FileUtils.mkdir_p(File.dirname(destination))
+          copy f, destination
+        end
+        puts "\nYou have unpacked \"#{framework.name}\""
+        puts
+        puts readme(framework)
+      end
+
+      def readme(framework)
+        %Q{| This is a copy of the "#{framework.name}" extension.
+           |
+           | It now overrides the original which was found here:
+           |
+           | #{framework.path}
+           |
+           | Unpacking an extension is useful when you need to easily peruse the
+           | extension's source. You might find yourself tempted to change the
+           | stylesheets here. If you do this, you'll find it harder to take
+           | updates from the original author. Sometimes this seems like a good
+           | idea at the time, but in a few months, you'll probably regret it.
+           |
+           | In the future, if you take an update of this framework, you'll need to run
+           |
+           |     compass unpack #{framework.name}
+           |
+           | again or remove this unpacked extension.
+           |}.gsub(/^\s*\| ?/,"")
+      end
+
+      def skip_extension_discovery?
+        true
+      end
+
+      class << self
+
+        def option_parser(arguments)
+          parser = Compass::Exec::CommandOptionParser.new(arguments)
+          parser.extend(Compass::Exec::GlobalOptionsParser)
+          parser.extend(Compass::Exec::ProjectOptionsParser)
+          parser.extend(ExtensionOptionsParser)
+        end
+
+        def usage
+          option_parser([]).to_s
+        end
+
+        def description(command)
+          "Copy an extension into your extensions folder."
+        end
+
+        def parse!(arguments)
+          parser = option_parser(arguments)
+          parser.parse!
+          parse_arguments!(parser, arguments)
+          parser.options
+        end
+
+        def parse_arguments!(parser, arguments)
+          if arguments.size == 1
+            parser.options[:framework] = arguments.shift
+          elsif arguments.size == 0
+            raise Compass::Error, "Please specify an extension to unpack."
+          else
+            raise Compass::Error, "Too many arguments were specified."
+          end
+        end
+
+      end
+
+    end
+  end
+end

lib/compass/exec/helpers.rb

@@ -5,8 +5,10 @@ module Compass::Exec
       if Compass::Commands.command_exists? arguments.first
         SubCommandUI
       else
-        Compass::Logger.new.red do
+        unless arguments.include?("-h") || arguments.include?("--help")
-          Haml::Util.haml_warn "WARNING: This interface is deprecated. Please use the new subcommand interface.\nSee `compass help` for more information.\n"
+          Compass::Logger.new.red do
+            Haml::Util.haml_warn "WARNING: This interface is deprecated. Please use the new subcommand interface.\nSee `compass help` for more information.\n"
+          end
         end
         SwitchUI
       end

lib/compass/exec/switch_ui.rb

@@ -89,6 +89,11 @@ END
         self.options[:pattern] = pattern
       end
 
+      opts.on('-h', '--help') do
+        self.options[:command] = :help
+        self.options[:help_command] = :help
+      end
+
       opts.on('--write-configuration', "Write the current configuration to the configuration file.") do
         self.options[:command] = :write_configuration
       end

lib/compass/frameworks.rb

@@ -7,10 +7,11 @@ module Compass
 
     class Framework
       attr_accessor :name
+      attr_accessor :path
       attr_accessor :templates_directory, :stylesheets_directory
       def initialize(name, *arguments)
         options = arguments.last.is_a?(Hash) ? arguments.pop : {}
-        path = options[:path] || arguments.shift
+        self.path = path = options[:path] || arguments.shift
         @name = name
         @templates_directory = options[:templates_directory] || File.join(path, 'templates')
         @stylesheets_directory = options[:stylesheets_directory] || File.join(path, 'stylesheets')
@@ -97,7 +98,7 @@ module Compass
       end
     end
 
-    def pretty_print
+    def pretty_print(skip_patterns = false)
       result = ""
       max = Compass::Frameworks::ALL.inject(0) do |gm, framework|
         fm = framework.template_directories.inject(0) do |lm,pattern|
@@ -108,12 +109,14 @@ module Compass
       Compass::Frameworks::ALL.each do |framework|
         next if framework.name =~ /^_/
         result << "  * #{framework.name}\n"
-        framework.template_directories.each do |pattern|
+        unless skip_patterns
-          result << "    - #{framework.name}/#{pattern}".ljust(max)
+          framework.template_directories.each do |pattern|
-          if description = framework.manifest(pattern).description
+            result << "    - #{framework.name}/#{pattern}".ljust(max)
-            result << " - #{description}"
+            if description = framework.manifest(pattern).description
+              result << " - #{description}"
+            end
+            result << "\n"
           end
-          result << "\n"
         end
       end
       result