haml-edge 2.1.21 → 2.1.22

data/EDGE_GEM_VERSION

@@ -1 +1 @@
-2.1.21
+2.1.22

data/FAQ.md

@@ -0,0 +1,142 @@
+# Frequently Asked Questions
+
+## Haml
+
+### How do I put a punctuation mark after an element, like "`I like <strong>cake</strong>!`"?
+{#q-punctuation}
+
+Expressing the structure of a document
+and expressing inline formatting are two very different problems.
+Haml is mostly designed for structure,
+so the best way to deal with formatting is to leave it to other languages
+that are designed for it.
+You could use Textile:
+
+    %p
+      :textile
+        I like *cake*!
+
+or Markdown:
+
+    %p
+      :markdown
+        I like **cake**!
+
+or plain old XHTML:
+
+    %p I like <strong>cake</strong>!
+
+If you're inserting something that's generated by a helper, like a link,
+then it's even easier:
+
+    %p== I like #{link_to 'chocolate', 'http://franschocolates.com'}!
+
+### How do I stop Haml from indenting the contents of my `pre` and `textarea` tags?
+{#q-preserve}
+
+Because Haml automatically indents the HTML source code,
+the contents of whitespace-sensitive tags like `pre` and `textarea`
+can get screwed up.
+The solution is to replace the newlines inside these tags
+with HTML newline entities (`&#x000A;`),
+which Haml does using the {Haml::Helpers#preserve} and {Haml::Helpers#find_and_preserve} helpers.
+
+Normally, Haml will do this for you automatically
+when you're using a tag that needs it
+(this can be customized using the [`:preserve`](Haml.html#preserve-option) option.
+For example,
+
+    %p
+      %textarea= "Foo\nBar"
+
+will be compiled to
+
+    <p>
+      <textarea>Foo&#x000A;Bar</textarea>
+    </p>
+
+However, if a helper is generating the tag,
+Haml can't detect that and so you'll have to call {Haml::Helpers#find_and_preserve} yourself.
+You can also use `~`, which is the same as `=`
+except that it automatically runs `find_and_preserve` on its input.
+For example:
+
+    %p= find_and_preserve "<textarea>Foo\nBar</textarea>"
+
+is the same as
+
+    %p~ "<textarea>Foo\nBar</textarea>"
+
+and renders
+
+    <p><textarea>Foo&#x000A;Bar</textarea></p>
+
+### How do I make my long lines of Ruby code look nicer in my Haml document?
+{#q-multiline}
+
+Put them in a helper or your model.
+
+Haml purposefully makes it annoying to put lots of Ruby code into your templates,
+because lots of code doesn't belong in the view.
+If you take that huge `link_to_remote` call
+and move it to a `update_sidebar_link` helper,
+it'll make your view both easier to read and more semantic.
+
+If you absolutely must put lots of code in your template,
+Haml offers a somewhat awkward multiline-continuation tool.
+Put a `|` (pipe character) at the end of each line you want to be merged into one
+(including the last line!).
+For example:
+
+    %p= @this.is(way.too.much). |
+        code("and I should").   |
+        really_move.it.into(    |
+          :a => @helper)        |
+
+### I have Haml installed. Why is Rails (only looking for `.html.erb` files | rendering Haml files as plain text | rendering Haml files as blank pages)?
+{#q-blank-page}
+
+There are several reasons these things might be happening.
+First of all, make sure `vendor/plugins/haml` really exists
+and has an `init.rb` file in there.
+Then try restarting Mongrel or WEBrick or whatever you might be using.
+
+Finally, if none of these work,
+chances are you've got some localization plugin like Globalize installed.
+Such plugins often don't play nicely with Haml.
+Luckily, there's usually an easy fix.
+For Globalize, just edit `globalize/lib/globalize/rails/action_view.rb`
+and change
+
+    @@re_extension = /\.(rjs|rhtml|rxml)$/
+
+to
+
+    @@re_extension = /\.(rjs|rhtml|rxml|erb|builder|haml)$/
+
+For other plugins, a little searching will probably turn up a way to fix them as well.
+
+## Sass
+
+### Can I use a variable from my controller in my Sass file?
+{#q-ruby-code}
+
+No. Sass files aren't views.
+They're compiled once into static CSS files,
+then left along until they're changed and need to be compiled again.
+Not only don't you want to be running a full request cycle
+every time someone requests a stylesheet,
+but it's not a great idea to put much logic in there anyway
+due to how browsers handle them.
+
+If you really need some sort of dynamic CSS,
+the best thing to do is put only the snippet you need to dynamically set
+in the `head` of your HTML document.
+
+## You still haven't answered my question!
+
+Sorry! Try looking at the Haml or Sass references,
+in the doucmentation for the haml and Sass modules, respectively.
+If you can't find an answer there,
+feel free to ask in `#haml` on irc.freenode.net
+or send an email to the [mailing list](http://groups.google.com/group/haml?hl=en).

data/{README.rdoc → README.md}

@@ -1,4 +1,4 @@
-= Haml and Sass
+# Haml and Sass
 
 Haml and Sass are templating engines
 for the two most common types of documents on the web:
@@ -9,32 +9,32 @@ by eliminating redundancy,
 reflecting the underlying structure that the document represents,
 and providing elegant, easily understandable, and powerful syntax.
 
-== Using
+## Using
 
 There are several ways to use Haml and Sass.
 They can be used as a plugin for Rails or Merb,
 or embedded on their own in other applications.
 The first step of all of these is to install the Haml gem:
 
-  gem install haml
+    gem install haml
 
 To install Haml and Sass as a Rails plugin,
-just run <tt>haml --rails path/to/rails/app</tt>
+just run `haml --rails path/to/rails/app`
 and both Haml and Sass will be installed.
-Views with the <tt>.haml</tt> (or <tt>.html.haml</tt> for edge)
+Views with the `.haml` (or `.html.haml` for edge)
 extension will automatically use Haml.
 Sass is a little more complicated;
-<tt>.sass</tt> files should be placed in public/stylesheets/sass,
+`.sass` files should be placed in public/stylesheets/sass,
 where they'll be automatically compiled
 to corresponding CSS files in public/stylesheets when needed
 (the Sass template directory is customizable...
 see the Sass module docs for details).
 
-For Merb, <tt>.html.haml</tt> views will work without any further modification.
+For Merb, `.html.haml` views will work without any further modification.
 To enable Sass, you also need to add a dependency.
 To do so, just add
 
-  dependency "merb-haml"
+    dependency "merb-haml"
 
 to config/dependencies.rb (or config/init.rb in a flat/very flat Merb application).
 Then it'll work just like it does in Rails.
@@ -42,31 +42,31 @@ Then it'll work just like it does in Rails.
 To use Haml and Sass programatically,
 check out the RDocs for the Haml and Sass modules.
 
-== Formatting
+## Formatting
 
-=== Haml
+### Haml
 
 The most basic element of Haml
-is a shorthand for creating HTML tags:
+is a shorthand for creating HTML
 
-  %tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents
+    %tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents
 
 No end-tag is needed; Haml handles that automatically.
-Adding <tt>class</tt> and <tt>id</tt> attributes is even easier.
+Adding `class` and `id` attributes is even easier.
 Haml uses the same syntax as the CSS that styles the document:
 
-  %tagname#id.class
+    %tagname#id.class
 
-In fact, when you're using the <tt><div></tt> tag,
-it becomes <em>even easier</em>.
-Because <tt><div></tt> is such a common element,
+In fact, when you're using the `<div>` tag,
+it becomes _even easier_.
+Because `<div>` is such a common element,
 a tag without a name defaults to a div. So
 
-  #foo Hello!
+    #foo Hello!
 
 becomes
 
-  <div id='foo'>Hello!</div>
+    <div id='foo'>Hello!</div>
 
 Haml uses indentation
 to bring the individual elements to represent the HTML structure.
@@ -74,40 +74,40 @@ A tag's children are indented beneath than the parent tag.
 Again, a closing tag is automatically added.
 For example:
 
-  %ul
-    %li Salt
-    %li Pepper
+    %ul
+      %li Salt
+      %li Pepper
 
 becomes:
 
-  <ul>
-    <li>Salt</li>
-    <li>Pepper</li>
-  </ul>
+    <ul>
+      <li>Salt</li>
+      <li>Pepper</li>
+    </ul>
 
 You can also put plain text as a child of an element:
 
-  %p
-    Hello,
-    World!
+    %p
+      Hello,
+      World!
 
 It's also possible to embed Ruby code into Haml documents.
-An equals sign, <tt>=</tt>, will output the result of the code.
-A hyphen, <tt>-</tt>, will run the code but not output the result.
+An equals sign, `=`, will output the result of the code.
+A hyphen, `-`, will run the code but not output the result.
 You can even use control statements
-like <tt>if</tt> and <tt>while</tt>:
+like `if` and `while`:
 
-  %p
-    Date/Time:
-    - now = DateTime.now
-    %strong= now
-    - if now > DateTime.parse("December 31, 2006")
-      = "Happy new " + "year!"
+    %p
+      Date/Time:
+      - now = DateTime.now
+      %strong= now
+      - if now > DateTime.parse("December 31, 2006")
+        = "Happy new " + "year!"
 
 Haml provides far more tools than those presented here.
 Check out the reference documentation in the Haml module.
 
-=== Sass
+### Sass
 
 At its most basic,
 Sass is just another way of writing CSS.
@@ -119,15 +119,15 @@ and newlines indicate the end of an attribute,
 rather than a semicolon.
 For example:
 
-  #main
-    :background-color #f00
-    :width 98%
+    #main
+      :background-color #f00
+      :width 98%
 
 becomes:
 
-  #main {
-    background-color: #f00;
-    width: 98% }
+    #main {
+      background-color: #f00;
+      width: 98% }
 
 However, Sass provides much more than a way to make CSS look nice.
 In CSS, it's important to have accurate selectors,
@@ -144,35 +144,35 @@ Well, Sass gets rid of that.
 Like Haml, it uses indentation to indicate the structure of the document.
 So, what was:
 
-  #main {
-    width: 90%;
-  }
-  #main p {
-    border-style: solid;
-    border-width: 1px;
-    border-color: #00f;
-  }
-  #main p a {
-    text-decoration: none;
-    font-weight: bold;
-  }
-  #main p a:hover {
-    text-decoration: underline;
-  }
+    #main {
+      width: 90%;
+    }
+    #main p {
+      border-style: solid;
+      border-width: 1px;
+      border-color: #00f;
+    }
+    #main p a {
+      text-decoration: none;
+      font-weight: bold;
+    }
+    #main p a:hover {
+      text-decoration: underline;
+    }
 
 becomes:
 
-  #main
-    :width 90%
-    p
-      :border-style solid
-      :border-width 1px
-      :border-color #00f
-      a
-        :text-decoration none
-        :font-weight bold
-      a:hover
-        :text-decoration underline
+    #main
+      :width 90%
+      p
+        :border-style solid
+        :border-width 1px
+        :border-color #00f
+        a
+          :text-decoration none
+          :font-weight bold
+        a:hover
+          :text-decoration underline
 
 Pretty nice, no? Well, it gets better.
 One of the main complaints against CSS is that it doesn't allow variables.
@@ -180,127 +180,127 @@ What if have a color or a width you re-use all the time?
 In CSS, you just have to re-type it each time,
 which is a nightmare when you decide to change it later.
 Not so for Sass!
-You can use the "!" character to set variables.
-Then, if you put "=" after your attribute name,
+You can use the `!` character to set variables.
+Then, if you put `=` after your attribute name,
 you can set it to a variable.
 For example:
 
-  !note_bg= #55aaff
+    !note_bg= #55aaff
 
-  #main
-    :width 70%
-    .note
-      :background-color= !note_bg
-    p
-      :width 5em
-      :background-color= !note_bg
+    #main
+      :width 70%
+      .note
+        :background-color= !note_bg
+      p
+        :width 5em
+        :background-color= !note_bg
 
 becomes:
 
-  #main {
-    width: 70%; }
-    #main .note {
-      background-color: #55aaff; }
-    #main p {
-      width: 5em;
-      background-color: #55aaff; }
+    #main {
+      width: 70%; }
+      #main .note {
+        background-color: #55aaff; }
+      #main p {
+        width: 5em;
+        background-color: #55aaff; }
 
 You can even do simple arithmetic operations with variables,
 adding numbers and even colors together:
 
-  !main_bg= #46ar12
-  !main_width= 40em
+    !main_bg= #46ar12
+    !main_width= 40em
 
-  #main
-    :background-color= !main_bg
-    :width= !main_width
-    .sidebar
-      :background-color= !main_bg + #333333
-      :width= !main_width - 25em
+    #main
+      :background-color= !main_bg
+      :width= !main_width
+      .sidebar
+        :background-color= !main_bg + #333333
+        :width= !main_width - 25em
 
 becomes:
 
-  #main {
-    background-color: #46a312;
-    width: 40em; }
-    #main .sidebar {
-      background-color: #79d645;
-      width: 15em; }
+    #main {
+      background-color: #46a312;
+      width: 40em; }
+      #main .sidebar {
+        background-color: #79d645;
+        width: 15em; }
 
 Taking the idea of variables a bit further are mixins.
 These let you group whole swathes of CSS attributes into a single
 directive and then include those anywhere you want:
 
-  =blue-border
-    :border
-      :color blue
-      :width 2px
-      :style dotted
+    =blue-border
+      :border
+        :color blue
+        :width 2px
+        :style dotted
 
-  .comment
-    +blue-border
-    :padding 2px
-    :margin 10px 0
+    .comment
+      +blue-border
+      :padding 2px
+      :margin 10px 0
 
-  .reply
-    +blue-border
+    .reply
+      +blue-border
 
 becomes:
 
-  .comment {
-    border-color: blue;
-    border-width: 2px;
-    border-style: dotted;
-    padding: 2px;
-    margin: 10px 0;
-  }
+    .comment {
+      border-color: blue;
+      border-width: 2px;
+      border-style: dotted;
+      padding: 2px;
+      margin: 10px 0;
+    }
 
-  .reply {
-    border-color: blue;
-    border-width: 2px;
-    border-style: dotted;
-  }
+    .reply {
+      border-color: blue;
+      border-width: 2px;
+      border-style: dotted;
+    }
 
 A comprehensive list of features is in
 the documentation for the Sass module.
 
-== Indentation
+## Indentation
 
 Indentation can be made up of one or more tabs or spaces.
 However, indentation must be consistent within a given document.
 Hard tabs and spaces can't be mixed,
 and the same number of tabs or spaces must be used throughout.
 
-== Executables
+## Executables
 
 The Haml gem includes several executables that are useful
 for dealing with Haml and Sass from the command line.
 
-=== +haml+
+### `haml`
 
-The +haml+ executable transforms a source Haml file into HTML.
-See <tt>haml --help</tt> for further information and options.
+The `haml` executable transforms a source Haml file into HTML.
+See `haml --help` for further information and options.
 
-=== +sass+
+### `sass`
 
-The +sass+ executable transforms a source Sass file into CSS.
-See <tt>sass --help</tt> for further information and options.
+The `sass` executable transforms a source Sass file into CSS.
+See `sass --help` for further information and options.
 
-=== <tt>html2haml</tt>
+### `html2haml`
 
-The <tt>html2haml</tt> executable attempts to transform HTML,
+The `html2haml` executable attempts to transform HTML,
 optionally with ERB markup, into Haml code.
 Since HTML is so variable, this transformation is not always perfect;
 it's a good idea to have a human check the output of this tool.
-See <tt>html2haml --help</tt> for further information and options.
+See `html2haml --help` for further information and options.
 
-=== <tt>css2sass</tt>
+### `css2sass`
 
-The <tt>css2sass</tt> executable attempts to transform CSS into Sass code.
+The `css2sass` executable attempts to transform CSS into Sass code.
 This transformation attempts to use Sass nesting where possible.
-See <tt>css2sass --help</tt> for further information and options.
+See `css2sass --help` for further information and options.
 
-== Authors
+## Authors
 
 Haml and Sass are designed by Hampton Catlin (hcatlin) and he is the author
 of the original implementation. However, Hampton doesn't even know his way
@@ -329,4 +329,4 @@ buy Nathan some jelly beans. Maybe pet a kitten. Yeah. Pet that kitty.
 Some of the work on Haml was supported by Unspace Interactive.
 
 Beyond that, the implementation is licensed under the MIT License.
-Ok, fine, I guess that means compliments aren't *required*.
+Okay, fine, I guess that means compliments aren't __required__.

data/Rakefile

@@ -122,25 +122,37 @@ end
 
 # ----- Documentation -----
 
-begin
-  require 'hanna/rdoctask'
-rescue LoadError
-  require 'rake/rdoctask'
+task :rdoc do
+  puts '=' * 100, <<END, '=' * 100
+Haml uses the YARD documentation system (http://github.com/lsegal/yard).
+Install the yard gem and then run "rake doc".
+END
 end
 
-Rake::RDocTask.new do |rdoc|
-  rdoc.title    = 'Haml/Sass'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include(*FileList.new('*') do |list|
-                            list.exclude(/(^|[^.a-z])[a-z]+/)
-                            list.exclude('TODO')
-                          end.to_a)
-  rdoc.rdoc_files.include('lib/**/*.rb')
-  rdoc.rdoc_files.exclude('TODO')
-  rdoc.rdoc_files.exclude('lib/haml/buffer.rb')
-  rdoc.rdoc_files.exclude('lib/sass/tree/*')
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.main = 'README.rdoc'
+begin
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files = FileList.new('lib/**/*.rb') do |list|
+      list.exclude('lib/haml/template/*.rb')
+      list.exclude('lib/haml/helpers/action_view_mods.rb')
+    end.to_a
+    t.options += FileList.new('yard/*.rb').to_a.map {|f| ['-e', f]}.flatten
+    t.options << '--files' << FileList.new('*') do |list|
+      list.exclude(/(^|[^.a-z])[a-z]+/)
+      list.exclude('README.md')
+      list.exclude('REVISION')
+      list.exclude('TODO')
+    end.to_a.join(',')
+  end
+  Rake::Task['yardoc'].instance_variable_set('@comment', nil)
+
+  desc "Generate Documentation"
+  task :doc => :yardoc
+rescue LoadError
+  desc "Generate Documentation"
+  task :doc => :rdoc
+  task :yardoc => :rdoc
 end
 
 # ----- Coverage -----

data/VERSION

@@ -1 +1 @@
-2.1.21
+2.1.22