radiant 0.9.1 → 1.0.0.rc1

data/vendor/plugins/haml/doc-src/HAML_REFERENCE.md

@@ -39,9 +39,14 @@ Use `haml --help` for full documentation.
 
 ### Rails/Merb Plugin {#plugin}
 
-To enable Haml as a Rails plugin, run
+To enable Haml in Rails versions before Rails 3,
+add the following line to `environment.rb`:
 
-    haml --rails path/to/rails/app
+    config.gem "haml"
+
+For Rails 3, instead add the following line to the Gemfile:
+
+    gem "haml"
 
 Once it's installed, all view files with the `".html.haml"` extension
 will be compiled using Haml.
@@ -123,7 +128,8 @@ in `environment.rb` in Rails...
 Available options are:
 
 {#format-option} `:format`
-: Determines the output format. The default is `:xhtml`.
+: Determines the output format. Normally the default is `:xhtml`,
+  although under Rails 3 it's `:html5`, since that's the Rails 3's default format.
   Other options are `:html4` and `:html5`, which are
   identical to `:xhtml` except there are no self-closing tags,
   the XML prolog is ignored and correct DOCTYPEs are generated.
@@ -173,6 +179,8 @@ Available options are:
 {#autoclose-option} `:autoclose`
 : A list of tag names that should be automatically self-closed
   if they have no content.
+  This can also contain regular expressions that match tag names
+  (or any object which responds to `#===`).
   Defaults to `['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']`.
 
 {#preserve-option} `:preserve`
@@ -190,7 +198,9 @@ Available options are:
   Note that Haml **does not** automatically re-encode Ruby values;
   any strings coming from outside the application should be converted
   before being passed into the Haml template.
-  Defaults to `Encoding.default_internal` or, if that's not set, `"utf-8"`.
+  Defaults to `Encoding.default_internal`; if that's not set,
+  defaults to the encoding of the Haml template;
+  if that's `us-ascii`, defaults to `"utf-8"`.
   <br/><br/> <!-- There's no better way to do a paragraph break in a dl in Maruku -->
   Many Ruby database drivers are not yet Ruby 1.9 compatible;
   in particular, they return strings marked as ASCII-encoded
@@ -200,6 +210,25 @@ Available options are:
   set `:encoding` to `"ascii-8bit"`, or try to get the authors of the database drivers
   to make them Ruby 1.9 compatible.
 
+### Encodings
+
+When using Ruby 1.9 or later,
+Haml supports the same sorts of encoding-declaration comments that Ruby does.
+Although both Ruby and Haml support several different styles,
+the easiest it just to add `-# coding: encoding-name`
+at the beginning of the Haml template
+(it must come before all other lines).
+This will tell Haml that the template is encoded using the named encoding.
+
+By default, the HTML generated by Haml has the same encoding as the Haml template.
+However, if `Encoding.default_internal` is set, Haml will attempt to use that instead.
+In addition, the [`:encoding` option](#encoding-option) can be used
+to specify an output encoding manually.
+
+Note that, like Ruby, Haml does not support templates encoded in UTF-16 or UTF-32,
+since these encodings are not compatible with ASCII.
+It is possible to use these as the output encoding, though.
+
 ## Plain Text
 
 A substantial portion of any HTML document is its content,
@@ -308,6 +337,50 @@ is compiled to:
 
     <script src='javascripts/script_9' type='text/javascript'></script>
 
+#### `:class` and `:id` Attributes
+{#class-and-id-attributes}
+
+The `:class` and `:id` attributes can also be specified as a Ruby array
+whose elements will be joined together.
+A `:class` array is joined with `" "`
+and an `:id` array is joined with `"_"`.
+For example:
+
+    %div{:id => [@item.type, @item.number], :class => [@item.type, @item.urgency]}
+
+is equivalent to:
+
+    %div{:id => "#{@item.type}_#{@item.number}", :class => "#{@item.type} #{@item.urgency}"}
+
+The array will first be flattened
+and any elements that do not test as true will be removed.
+The remaining elements will be converted to strings.
+For example:
+
+    %div{:class => [@item.type, @item == @sortcol && [:sort, @sortdir]] } Contents
+
+could render as any of:
+
+    <div class="numeric sort ascending">Contents</div>
+    <div class="numeric">Contents</div>
+    <div class="sort descending">Contents</div>
+    <div>Contents</div>
+
+depending on whether `@item.type` is `"numeric"` or `nil`,
+whether `@item == @sortcol`,
+and whether `@sortdir` is `"ascending"` or `"descending"`.
+
+If a single value is specified and it evaluates to false it is ignored;
+otherwise it gets converted to a string.
+For example:
+
+    .item{:class => @item.is_empty? && "empty"}
+
+could render as either of:
+
+    class="item"
+    class="item empty"
+
 #### HTML-style Attributes: `()`
 
 Haml also supports a terser, less Ruby-specific attribute syntax
@@ -426,6 +499,21 @@ or using `true` and `false`:
 
     %input(selected=true)
 
+#### HTML5 Custom Data Attributes
+
+HTML5 allows for adding [custom non-visible data attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data)
+to elements using attribute names beginning with `data-`.
+Custom data attributes can be used in Haml by using the key `:data` with a Hash value
+in an attribute hash.
+Each of the key/value pairs in the Hash will be transformed into a custom data attribute.
+For example:
+
+    %a{:href=>"/posts", :data => {:author_id => 123}} Posts By Author
+
+will render as:
+
+    <a data-author_id='123' href='/posts'>Posts By Author</a>
+
 ### Class and ID: `.` and `#`
 
 The period and pound sign are borrowed from CSS.
@@ -451,11 +539,11 @@ is compiled to:
 
 And,
 
-    #content
-      .articles
-        .article.title Doogie Howser Comes Out
-        .article.date 2006-11-05
-        .article.entry
+    %div#content
+      %div.articles
+        %div.article.title Doogie Howser Comes Out
+        %div.article.date 2006-11-05
+        %div.article.entry
           Neil Patrick Harris would like to dispel any rumors that he is straight
 
 is compiled to:
@@ -470,6 +558,22 @@ is compiled to:
       </div>
     </div>
 
+These shortcuts can be combined with long-hand attributes;
+the two values will be merged together
+as though they were all placed in an array
+(see [the documentation on `:class` and `:id` attributes](#class-and-id-attributes)).
+For example:
+
+    %div#Article.article.entry{:id => @article.number, :class => @article.visibility}
+
+is equivalent to
+
+    %div{:id => ['Article', @article.number], :class => ['article', 'entry', @article.visibility]} Gabba Hey
+
+and could compile to:
+
+    <div class="article entry visible" id="Article_27">Gabba Hey</div>
+
 #### Implicit Div Elements
 
 Because divs are used so often, they're the default elements.
@@ -609,6 +713,29 @@ is compiled to:
       Hello!
     </div>
 
+If you require that the class be something other than the underscored
+object's class, you can implement the `haml_object_ref` method on the object.
+
+    # file: app/models/crazy_user.rb
+
+    class CrazyUser < ActiveRecord::Base
+      def haml_object_ref
+        "a_crazy_user"
+      end
+    end
+
+    -# file: app/views/users/show.haml
+
+    %div[@user]
+      Hello!
+
+is compiled to:
+
+    <div class='a_crazy_user' id='a_crazy_user_15'>
+      Hello!
+    </div>
+
+
 ## Doctype: `!!!`
 
 When describing HTML documents with Haml,
@@ -640,7 +767,7 @@ is compiled to:
     </html>
 
 You can also specify the specific doctype after the `!!!`
-When the [`:format`](#format) is set to `:xhtml` (the default),
+When the [`:format`](#format-option) is set to `:xhtml` (the default except in Rails 3),
 the following doctypes are supported:
 
 `!!!`
@@ -671,7 +798,11 @@ the following doctypes are supported:
 : XHTML Mobile 1.2<br/>
  `<!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd">`
 
-When the [`:format`](#format) option is set to `:html4`,
+`!!! RDFa`
+: XHTML+RDFa 1.0<br/>
+ `<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">`
+
+When the [`:format`](#format-option) option is set to `:html4`,
 the following doctypes are supported:
 
 `!!!`
@@ -686,7 +817,7 @@ the following doctypes are supported:
 : HTML 4.01 Frameset<br/>
  `<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">`
 
-When the [`:format`](#format) option is set to `:html5`,
+When the [`:format`](#format-option) option is set to `:html5`,
 `!!!` is always `<!DOCTYPE html>`.
 
 If you're not using the UTF-8 character set for your document,
@@ -827,6 +958,14 @@ would be compiled to
 
     <p>hello</p>
 
+A line of Ruby code can be stretched over multiple lines
+as long as each line but the last ends with a comma.
+For example:
+
+    = link_to_remote "Add to cart",
+        :url => { :action => "add", :id => product.id },
+        :update => { :success => "cart", :failure => "error" }
+
 Note that it's illegal to nest code within a tag that ends with `=`.
 
 ### Running Ruby: `-`
@@ -851,6 +990,14 @@ is compiled to:
       hello there you!
     </p>
 
+A line of Ruby code can be stretched over multiple lines
+as long as each line but the last ends with a comma.
+For example:
+
+    - links = {:home => "/",
+        :docs => "/docs",
+        :about => "/about"}
+
 #### Ruby Blocks
 
 Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
@@ -1064,6 +1211,11 @@ when you don't want lines starting with `.` or `-` to be parsed.
 Surrounds the filtered text with `<script>` and CDATA tags.
 Useful for including inline Javascript.
 
+{#css-filter}
+### `:css`
+Surrounds the filtered text with `<style>` and CDATA tags.
+Useful for including inline CSS.
+
 {#cdata-filter}
 ### `:cdata`
 Surrounds the filtered text with CDATA tags.
@@ -1091,7 +1243,7 @@ See also [Whitespace Preservation](#whitespace_preservation).
 
 {#erb-filter}
 ### `:erb`
-Parses the filtered text with ERB, like an RHTML template.
+Parses the filtered text with ERb, like an RHTML template.
 Not available if the [`:suppress_eval`](#suppress_eval-option) option is set to true.
 Embedded Ruby code is evaluated in the same context as the Haml template.
 
@@ -1128,7 +1280,7 @@ It's placed at the end of a line (after some whitespace)
 and means that all following lines that end with `|`
 will be evaluated as though they were on the same line.
 **Note that even the last line in the multiline block
-should end wit `|`.**
+should end with `|`.**
 For example:
 
     %whoo
@@ -1153,11 +1305,19 @@ in their Haml templates.
 If you find yourself using multiline declarations, stop and think:
 could I do this better with a helper?
 
-Note that there is one case where it's useful to allow
-something to flow over onto multiple lines in a non-awkward manner: attributes.
+Note that there are a few cases where it's useful to allow
+something to flow over onto multiple lines in a non-awkward manner.
+One of these is HTML attributes.
 Some elements just have lots of attributes,
 so you can wrap attributes without using `|` (see [Attributes](#attributes)).
 
+In addition, sometimes you need to call Ruby methods or declare data structures
+that just need a lot of template information.
+So data structures and  functions that require lots of arguments
+can be wrapped over multiple lines,
+as long as each line but the last ends in a comma
+(see [Inserting Ruby](#inserting_ruby_)).
+
 ## Whitespace Preservation
 
 Sometimes you don't want Haml to indent all your text.

data/vendor/plugins/haml/doc-src/INDENTED_SYNTAX.md

@@ -0,0 +1,210 @@
+# Sass Indented Syntax
+
+* Table of contents
+{:toc}
+
+Sass's indented syntax (also known simply as "Sass")
+is designed to provide a more concise
+and, for some, more aesthetically appealing alternative
+to the CSS-based SCSS syntax.
+It's not compatible with CSS;
+instead of using `{` and `}` to delimit blocks of styles,
+it uses indentation,
+and instead of using semicolons to separate statements it uses newlines.
+This usually leads to substantially less text
+when saying the same thing.
+
+Each statement in Sass, such as property declarations and selectors,
+must be placed on its own line.
+In addition, everything that would be within `{` and `}` after a statement
+must be on a new line and indented one level deeper than that statement.
+For example, this CSS:
+
+    #main {
+      color: blue;
+      font-size: 0.3em;
+    }
+
+would be this Sass:
+
+    #main
+      color: blue
+      font-size: 0.3em
+
+Similarly, this SCSS:
+
+    #main {
+      color: blue;
+      font-size: 0.3em;
+
+      a {
+        font: {
+          weight: bold;
+          family: serif;
+        }
+        &:hover {
+          background-color: #eee;
+        }
+      }
+    }
+
+would be this Sass:
+
+    #main
+      color: blue
+      font-size: 0.3em
+
+      a
+        font:
+          weight: bold
+          family: serif
+        &:hover
+          background-color: #eee
+
+## Sass Syntax Differences
+
+In general, most CSS and SCSS syntax
+works straightforwardly in Sass
+by using newlines instead of semicolons
+and indentation instead of braces.
+However, there are some cases where there are differences or subtleties,
+which are detailed below.
+
+## Property Synax
+
+The indented syntax supports two ways of declaring CSS properties.
+The first is just like CSS, except without the semicolon.
+The second, however, places the colon *before* the property name.
+For example:
+
+    #main
+      :color blue
+      :font-size 0.3em
+
+By default, both ways may be used.
+However, the {file:SASS_REFERENCE.md#property_syntax-option `:property_syntax` option}
+may be used to specify that only one property syntax is allowed.
+
+### Multiline Selectors
+
+Normally in the indented syntax, a single selector must take up a single line.
+There is one exception, however:
+selectors can contain newlines as long as they only appear after commas.
+For example:
+
+    .users #userTab,
+    .posts #postTab
+      width: 100px
+      height: 30px
+
+### Comments
+
+Like everything else in the indented syntax,
+comments are line-based.
+This means that they don't work the same way as in SCSS.
+They must take up an entire line,
+and they also encompass all text nested beneath them.
+
+Like SCSS, the indented syntax supports two kinds of comments.
+Comments beginning with `/*` are preserved in the CSS output,
+although unlike SCSS they don't require a closing `*/`.
+Comments beginning with `//` are removed entirely.
+For example:
+
+    /* This comment will appear in the CSS output.
+      This is nested beneath the comment,
+      so it's part of it
+    body
+      color: black
+
+    // This comment will not appear in the CSS output.
+      This is nested beneath the comment as well,
+      so it also won't appear
+    a
+      color: green
+
+is compiled to:
+
+    /* This comment will appear in the CSS output.
+     * This is nested beneath the comment,
+     * so it's part of it */
+    body {
+      color: black; }
+
+    a {
+      color: green; }
+
+### `@import`
+
+The `@import` directive in Sass does not require quotes, although they may be used.
+For example, this SCSS:
+
+    @import "themes/dark";
+    @import "font.sass";
+
+would be this Sass:
+
+    @import themes/dark
+    @import font.sass
+
+### Mixin Directives
+
+Sass supports shorthands for the `@mixin` and `@include` directives.
+Instead of writing `@mixin`, you can use the character `=`;
+instead of writing `@include`, you can use the character `+`.
+For example:
+
+    =large-text
+      font:
+        family: Arial
+        size: 20px
+        weight: bold
+      color: #ff0000
+
+    h1
+      +large-text
+
+is the same as:
+
+    @mixin large-text
+      font:
+        family: Arial
+        size: 20px
+        weight: bold
+      color: #ff0000
+
+    h1
+      @include large-text
+
+## Deprecated Syntax
+
+Since the indented syntax has been around for a while,
+previous versions have made some syntactic decisions
+that have since been changed.
+Some of the old syntax still works, though,
+so it's documented here.
+
+**Note that this syntax is not recommended
+for use in new Sass files**.
+It will print a warning if it's used,
+and it will be removed in a future version.
+
+### `=` for Properties and Variables
+
+`=` used to be used instead of `:` when setting variables
+and when setting properties to SassScript values.
+It has slightly different semantics than `:`;
+see {file:SASS_CHANGELOG.md#3-0-0-sass-script-context this changelog entry} for details.
+
+### `||=` for Default Variables
+
+`||=` used to be used instead of `:` when setting the default value of a variable.
+The `!default` flag was not used.
+The variable value has the same semantics as `=`;
+see {file:SASS_CHANGELOG.md#3-0-0-sass-script-context this changelog entry} for details.
+
+### `!` Prefix for Variables
+
+`!` used to be used as the variable prefix instead of `$`.
+This had no difference in functionality;
+it was a purely aesthetic change.