slim 1.3.0 → 1.3.2

data/.travis.yml

@@ -6,10 +6,13 @@ rvm:
   - rbx-18mode
   - rbx-19mode
 env:
-  - "TASK=test"
+  - "TASK=test:core_and_plugins"
   - "TASK=test:rails RAILS=master"
-  - "TASK=test:rails RAILS=3.0.11"
-  - "TASK=test:rails RAILS=3.1.3"
+  - "TASK=test:rails RAILS=3.0.17"
+  - "TASK=test:rails RAILS=3.1.8"
+  - "TASK=test:rails RAILS=3.2.8"
+  - "TASK=test:sinatra SINATRA=master"
+  - "TASK=test:sinatra SINATRA=1.3.3"
 matrix:
   exclude:
     # Test Rails master only on 1.9.3+ Rubies
@@ -20,9 +23,10 @@ matrix:
     - rvm: rbx-18mode
       env: "TASK=test:rails RAILS=master"
   allow_failures:
-    - rvm: ruby-head
     - env: "TASK=test:rails RAILS=master"
-script: "bundle exec rake test:ci"
+    - env: "TASK=test:sinatra SINATRA=master"
+    - rvm: ruby-head
+script: "bundle exec rake $TASK"
 notifications:
   email: false
   irc:

data/CHANGES

@@ -1,3 +1,26 @@
+1.3.2
+
+  * Fix boolean attributes #299
+
+1.3.1
+
+  * Support inline html at the beginning of a line (New line indicator <). No pipe symbol is | necessary.
+    It is even possible to wrap other Slim syntax in such a html block.
+  * Code restructured - Handling of boolean and splat attributes improved and PERFORMANCE improved.
+  * BACKWARD INCOMPATIBLE CHANGE -  Dynamic attributes which return empty value "" are not removed anymore
+    (this means "" is now interpreted as true), whereas false and nil are still removed.
+    This corresponds to the definition of boolean attributes in XHTML and HTML5.
+  * Deprecated option :remove_empty_attrs (TODO: Remove in 1.4.0)
+  * Add option :escape_quoted_attrs to escape quoted attributes, use == if you don't want that.
+    The default is false to stay backward compatible.
+  * Use Temple::FilterError exception
+  * Use Temple::Parser
+  * / is not escaped anymore to &#47;
+  * Parser: check for missing closing quote in quoted attributes
+  * Use new temple option validation to make Slim configuration more user friendly.
+  * Support thread options Slim::Engine.with_options which especially useful for Rails
+  * Add explicit column number to SyntaxError.to_s
+
 1.3.0
 
   * Parser wraps text blocks in [:slim, :text, ...] (Used by Translator/I18n plugin)

data/Gemfile

@@ -3,12 +3,14 @@ source :rubygems
 gemspec
 
 if ENV['TRAVIS'] || ENV['TEMPLE'] == 'master'
-   gem 'temple', :git => 'git://github.com/judofyr/temple.git'
+  gem 'temple', :github => 'judofyr/temple'
+elsif ENV['TEMPLE_PATH']
+  gem 'temple', :path => ENV['TEMPLE_PATH']
 end
 
 if ENV['RAILS']
   if ENV['RAILS'] == 'master'
-    gem 'rails', :git => 'git://github.com/rails/rails.git'
+    gem 'rails', :github => 'rails/rails'
   else
     gem 'rails', "= #{ENV['RAILS']}"
   end
@@ -21,3 +23,12 @@ if ENV['RAILS']
     gem 'sqlite3-ruby'
   end
 end
+
+if ENV['SINATRA']
+  gem 'rack-test'
+  if ENV['SINATRA'] == 'master'
+    gem 'sinatra', :github => 'sinatra/sinatra'
+  else
+    gem 'sinatra', "= #{ENV['SINATRA']}"
+  end
+end

data/README.md

@@ -1,9 +1,22 @@
 # Slim
 
-
 [![Build Status](https://secure.travis-ci.org/stonean/slim.png?branch=master)](http://travis-ci.org/stonean/slim) [![Dependency Status](https://gemnasium.com/stonean/slim.png?travis)](https://gemnasium.com/stonean/slim) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/stonean/slim)
 
-Slim is a template language whose goal is to reduce the view syntax to the essential parts without becoming cryptic.
+Slim is a template language whose goal is to reduce the view syntax to the essential parts without becoming cryptic. It started as an exercise to see how much could be removed from a standard html template (<, >, closing tags, etc...). As more people took an interest in Slim, the functionality grew and so did the flexibility of the syntax.
+
+A short list of the features...
+
+* Short syntax without closing tags (Using indentation instead)
+* Embedded engines like Markdown and Textile
+* Configurable shortcut tags (`#` for `div id` and `.` for `div class` in the default configuration)
+* Automatic HTML escaping and support for Rails' `html_safe?`
+* HTML style mode with closing tags
+* Logic less mode similar to Mustache, realized as plugin
+* Translator/I18n, realized as plugin
+* Highly configurable and extendable
+* High performance (Comparable to ERB)
+* Supported by all major frameworks (Rails, Sinatra, ...)
+* Streaming support in Rails
 
 ## Introduction
 
@@ -14,12 +27,12 @@ continous integration (travis-ci).
 
 Slim's core syntax is guided by one thought: "What's the minimum required to make this work".
 
-As more people have contributed to Slim, there have been syntax additions influenced from their use of [Haml](https://github.com/nex3/haml) and [Jade](https://github.com/visionmedia/jade).  The Slim team is open to these additions because we know beauty is in the eye of the beholder.
+As more people have contributed to Slim, there have been syntax additions influenced from their use of [Haml](https://github.com/haml/haml) and [Jade](https://github.com/visionmedia/jade).  The Slim team is open to these additions because we know beauty is in the eye of the beholder.
 
 Slim uses [Temple](https://github.com/judofyr/temple) for parsing/compilation and is also integrated into [Tilt](https://github.com/rtomayko/tilt), so it can be used together with [Sinatra](https://github.com/sinatra/sinatra) or plain [Rack](https://github.com/rack/rack).
 
 The architecture of Temple is very flexible and allows the extension of the parsing and compilation process without monkey-patching. This is used
-by the logic-less plugin and the translator plugin which provides I18n.
+by the logic less plugin and the translator plugin which provides I18n.
 
 ### Why use Slim?
 
@@ -66,9 +79,10 @@ Here's a quick example to demonstrate what a Slim template looks like:
                 td.name = item.name
                 td.price = item.price
         - else
-          p No items found
+          p No items found Please add some inventory.
+            Thank you!
 
-        #footer
+        div id="footer"
           = render 'footer'
           | Copyright &copy; #{year} #{author}
 
@@ -100,18 +114,43 @@ Each following line that is indented greater than the backtick is copied over.
               This line will have two spaces in front of it.
                 And so on...
 
+You can also embed html in the text line
+
+    - articles.each do |a|
+      | <tr><td>#{a.name}</td><td>#{a.description}</td></tr>
+
 ### Text with trailing space `'`
 
-The single quote tells Slim to copy the line (similar to |), but makes sure that a single trailing space is appended.
+The single quote tells Slim to copy the line (similar to `|`), but makes sure that a single trailing space is appended.
+
+### Inline html `<` (HTML style)
+
+You can write html tags directly in Slim which allows you to write your templates in a more html like style with closing tags or mix html and Slim style.
+
+    <html>
+      head
+        title Example
+      <body>
+        - if articles.empty?
+        - else
+          table
+            - articles.each do |a|
+              <tr><td>#{a.name}</td><td>#{a.description}</td></tr>
+      </body>
+    </html>
 
 ### Control code `-`
 
 The dash denotes control code.  Examples of control code are loops and conditionals. `end` is forbidden behind `-`. Blocks are defined only by indentation.
-If your ruby code needs to use multiple lines, append a `\` at the end of the lines.
+If your ruby code needs to use multiple lines, append a backslash `\` at the end of the lines.
+
+    body
+      - if articles.empty?
+        | No inventory
 
 ### Dynamic output `=`
 
-The equal sign tells Slim it's a Ruby call that produces output to add to the buffer. If your ruby code needs to use multiple lines, append a `\` at the end of the lines, for example:
+The equal sign tells Slim it's a Ruby call that produces output to add to the buffer. If your ruby code needs to use multiple lines, append a backslash `\` at the end of the lines, for example:
 
     = javascript_include_tag \
        "jquery", \
@@ -145,13 +184,15 @@ Use the forward slash for code comments - anything after it won't get displayed
 
 ### HTML comment `/!`
 
-Use the forward slash immediately followed by an exclamation mark for html comments (` <!-- --> `).
+Use the forward slash immediately followed by an exclamation mark for html comments (`<!-- ... -->`).
 
-### IE conditional comment `/![IE]`
+### IE conditional comment `/[...]`
 
-    /[ if IE ]
+    /[if IE]
         p Get a better browser.
 
+renders as
+
     <!--[if IE]><p>Get a better browser.</p><![endif]-->
 
 ## HTML tags
@@ -296,6 +337,10 @@ You can use text interpolation in the quoted attributes:
 
     a href="http://#{url}" Goto the #{url}
 
+The attribute value will be escaped by default. Use == if you want to disable escaping in the attribute.
+
+    a href=="&amp;"
+
 #### Ruby attributes
 
 Write the ruby code directly after the `=`. If the code contains spaces you have to wrap
@@ -308,7 +353,9 @@ the code into parentheses `(...)`, `{...}` or `[...]`. The code in the parenthes
             a href=user_action(user, :edit) Edit #{user.name}
             a href={path_to_user user} = user.name
 
-Use == if you want to disable escaping in the attribute.
+The attribute value will be escaped by default. Use == if you want to disable escaping in the attribute.
+
+    a href==action_path(:start)
 
 #### Boolean attributes
 
@@ -329,6 +376,9 @@ The splat shortcut allows you turn a hash in to attribute/value pairs
 
     .card*{'data-url'=>place_path(place), 'data-id'=>place.id} = place.name
     .card *method_which_returns_hash = place.name
+    .card *@hash_instance_variable = place.name
+
+renders as
 
     <div class="card" data-id="1234" data-url="/place/1234">Slim's house</div>
 
@@ -385,7 +435,7 @@ To escape the interpolation (i.e. render as is)
 
 ## Embedded engines (Markdown, ...)
 
-Thanks to Tilt, Slim has impressive support for embedding other template engines.
+Thanks to [Tilt](https://github.com/rtomayko/tilt), Slim has impressive support for embedding other template engines.
 
 Examples:
 
@@ -400,27 +450,24 @@ Examples:
 Supported engines:
 
 <table>
-<thead style="font-weight:bold"><tr><td>Engine</td><td>Filter</td><td>Required libraries</td><td>Type</td><td>Description</td></tr></thead>
+<thead style="font-weight:bold"><tr><td>Filter</td><td>Required gems</td><td>Type</td><td>Description</td></tr></thead>
 <tbody>
-<tr><td>Ruby</td><td>ruby:</td><td>none</td><td>Shortcut</td><td>Shortcut to embed ruby code</td></tr>
-<tr><td>Javascript</td><td>javascript:</td><td>none</td><td>Shortcut</td><td>Shortcut to embed javascript code and wrap in script tag</td></tr>
-<tr><td>CSS</td><td>css:</td><td>none</td><td>Shortcut</td><td>Shortcut to embed css code and wrap in style tag</td></tr>
-<tr><td>Sass</td><td>sass:</td><td>sass</td><td>Compile time</td><td>Embed sass code and wrap in style tag</td></tr>
-<tr><td>Scss</td><td>scss:</td><td>sass</td><td>Compile time</td><td>Embedd scss code and wrap in style tag</td></tr>
-<tr><td>LessCSS</td><td>less:</td><td>less</td><td>Compile time</td><td>Embed less css code and wrap in style tag</td></tr>
-<tr><td>Stylus</td><td>styl:</td><td>styl</td><td>Compile time</td><td>Embed stylus css code and wrap in style tag</td></tr>
-<tr><td>CoffeeScript</td><td>coffee:</td><td>coffee-script (+node coffee)</td><td>Compile time</td><td>Compile coffee script code and wrap in script tag</td></tr>
-<tr><td>RDiscount</td><td>markdown:</td><td>rdiscount/kramdown</td><td>Compile time + Interpolation</td><td>Compile markdown code and interpolate #\{variables} in text</td></tr>
-<tr><td>RedCloth</td><td>textile:</td><td>redcloth</td><td>Compile time + Interpolation</td><td>Compile textile code and interpolate #\{variables} in text</td></tr>
-<tr><td>Creole</td><td>creole:</td><td>creole</td><td>Compile time + Interpolation</td><td>Compile creole code and interpolate #\{variables} in text</td></tr>
-<tr><td>Wikicloth</td><td>wiki:, mediawiki:</td><td>wikicloth</td><td>Compile time + Interpolation</td><td>Compile wiki code and interpolate #\{variables} in text</td></tr>
-<tr><td>RDoc</td><td>rdoc:</td><td>rdoc</td><td>Compile time + Interpolation</td><td>Compile rdoc code and interpolate #\{variables} in text</td></tr>
-<tr><td>Builder</td><td>builder:</td><td>builder</td><td>Precompiled</td><td>Embed builder code</td></tr>
-<tr><td>Nokogiri</td><td>nokogiri:</td><td>nokogiri</td><td>Precompiled</td><td>Embed nokogiri builder code</td></tr>
-<tr><td>ERB</td><td>erb:</td><td>none</td><td>Precompiled</td><td>Embed erb code</td></tr>
-<tr><td>Liquid</td><td>liquid:</td><td>liquid</td><td>Runtime</td><td>Embed liquid code (Not recommended, no caching)</td></tr>
-<tr><td>Radius</td><td>radius:</td><td>radius</td><td>Runtime</td><td>Embed radius code (Not recommended, no caching)</td></tr>
-<tr><td>Markaby</td><td>markaby:</td><td>markaby</td><td>Runtime</td><td>Embed markaby code (Not recommended, no caching)</td></tr>
+<tr><td>ruby:</td><td>none</td><td>Shortcut</td><td>Shortcut to embed ruby code</td></tr>
+<tr><td>javascript:</td><td>none</td><td>Shortcut</td><td>Shortcut to embed javascript code and wrap in script tag</td></tr>
+<tr><td>css:</td><td>none</td><td>Shortcut</td><td>Shortcut to embed css code and wrap in style tag</td></tr>
+<tr><td>sass:</td><td>sass</td><td>Compile time</td><td>Embed sass code and wrap in style tag</td></tr>
+<tr><td>scss:</td><td>sass</td><td>Compile time</td><td>Embedd scss code and wrap in style tag</td></tr>
+<tr><td>less:</td><td>less</td><td>Compile time</td><td>Embed less css code and wrap in style tag</td></tr>
+<tr><td>styl:</td><td>styl</td><td>Compile time</td><td>Embed stylus css code and wrap in style tag</td></tr>
+<tr><td>coffee:</td><td>coffee-script</td><td>Compile time</td><td>Compile coffee script code and wrap in script tag</td></tr>
+<tr><td>markdown:</td><td>redcarpet/rdiscount/kramdown</td><td>Compile time + Interpolation</td><td>Compile markdown code and interpolate #\{variables} in text</td></tr>
+<tr><td>textile:</td><td>redcloth</td><td>Compile time + Interpolation</td><td>Compile textile code and interpolate #\{variables} in text</td></tr>
+<tr><td>creole:</td><td>creole</td><td>Compile time + Interpolation</td><td>Compile creole code and interpolate #\{variables} in text</td></tr>
+<tr><td>wiki:, mediawiki:</td><td>wikicloth</td><td>Compile time + Interpolation</td><td>Compile wiki code and interpolate #\{variables} in text</td></tr>
+<tr><td>rdoc:</td><td>rdoc</td><td>Compile time + Interpolation</td><td>Compile rdoc code and interpolate #\{variables} in text</td></tr>
+<tr><td>builder:</td><td>builder</td><td>Precompiled</td><td>Embed builder code</td></tr>
+<tr><td>nokogiri:</td><td>nokogiri</td><td>Precompiled</td><td>Embed nokogiri builder code</td></tr>
+<tr><td>erb:</td><td>none</td><td>Precompiled</td><td>Embed erb code</td></tr>
 </tbody>
 </table>
 
@@ -430,8 +477,10 @@ The embedded engines can be configured in Slim by setting the options directly o
 
 ## Configuring Slim
 
-Slim and the underlying Temple framework are highly configurable. Unfortunately the way how you configure Slim depends on the compilation mechanism (Rails or Tilt).
-It is always possible to set default options. This can be done in Rails' environment files. For instance, in config/environments/development.rb you probably want:
+Slim and the underlying [Temple](https://github.com/judofyr/temple) framework are highly configurable.
+The way how you configure Slim depends a bit on the compilation mechanism (Rails or [Tilt](https://github.com/rtomayko/tilt)). It is always possible to set default options per `Slim::Engine` class. This can be done in Rails' environment files. For instance, in config/environments/development.rb you probably want:
+
+### Default options
 
     # Indent html for pretty debugging and do not sort attributes (Ruby 1.8)
     Slim::Engine.set_default_options :pretty => true, :sort_attrs => false
@@ -443,18 +492,37 @@ You can also access the option hash directly:
 
     Slim::Engine.default_options[:pretty] = true
 
-For developers who know more about Slim and Temple architecture it is possible to override default
-options at different positions. Temple uses an inheritance mechanism to allow subclasses to override
-options of the superclass. The option priorities are as follows:
+### Setting options at runtime
+
+There are two ways to set options at runtime. For Tilt templates (`Slim::Template`) you can set
+the options when you instatiate the template:
+
+    Slim::Template.new('template.slim', optional_option_hash).render(scope)
+
+The other possibility is to set the options per thread which is interesting mostly for Rails:
+
+    Slim::Engine.with_options(option_hash) do
+       # Any Slim engines which are created here use the option_hash
+       # For example in Rails:
+       render :page, :layout => true
+    end
+
+You have to be aware that the compiled engine code and the options are cached per template in Rails and you cannot change the option afterwards.
 
-    Options passed at engine instantination > Slim::Template > Slim::Engine > Parser/Filter/Generator (e.g Slim::Parser, Slim::Compiler)
+    # First render call
+    Slim::Engine.with_options(:pretty => true) do
+       render :page, :layout => true
+    end
 
-It is also possible to set options for superclasses like Temple::Engine. But this will affect all temple template engines then.
+    # Second render call
+    Slim::Engine.with_options(:pretty => false) do
+       render :page, :layout => true # :pretty is still true because it is cached
+    end
 
-    Slim::Engine > Temple::Engine
-    Slim::Compiler > Temple::Filter
+### Available options
 
 The following options are exposed by the `Slim::Engine` and can be set with `Slim::Engine.set_default_options`.
+There are a lot of them but the good thing is, that Slim checks the configuration keys and reports an error if you try to use an invalid configuration key.
 
 <table>
 <thead style="font-weight:bold"><tr><td>Type</td><td>Name</td><td>Default</td><td>Purpose</td></tr></thead>
@@ -464,35 +532,132 @@ The following options are exposed by the `Slim::Engine` and can be set with `Sli
 <tr><td>String</td><td>:encoding</td><td>"utf-8"</td><td>Set encoding of template</td></tr>
 <tr><td>String</td><td>:default_tag</td><td>"div"</td><td>Default tag to be used if tag name is omitted</td></tr>
 <tr><td>Hash</td><td>:shortcut</td><td>\{'.' => 'class', '#' => 'id'}</td><td>Attribute shortcuts</td></tr>
-<tr><td>String list</td><td>:enable_engines</td><td>nil <i>(All enabled)</i></td><td>List of enabled embedded engines (whitelist)</td></tr>
-<tr><td>String list</td><td>:disable_engines</td><td>nil <i>(None disabled)</i></td><td>List of disabled embedded engines (blacklist)</td></tr>
+<tr><td>Symbol/String list</td><td>:enable_engines</td><td>nil <i>(All enabled)</i></td><td>List of enabled embedded engines (whitelist)</td></tr>
+<tr><td>Symbol/String list</td><td>:disable_engines</td><td>nil <i>(None disabled)</i></td><td>List of disabled embedded engines (blacklist)</td></tr>
 <tr><td>Boolean</td><td>:disable_capture</td><td>false (true in Rails)</td><td>Disable capturing in blocks (blocks write to the default buffer </td></tr>
 <tr><td>Boolean</td><td>:disable_escape</td><td>false</td><td>Disable automatic escaping of strings</td></tr>
+<tr><td>Boolean</td><td>:escape_quoted_attrs</td><td>false</td><td>Escape quoted attributes</td></tr>
 <tr><td>Boolean</td><td>:use_html_safe</td><td>false (true in Rails)</td><td>Use String#html_safe? from ActiveSupport (Works together with :disable_escape)</td></tr>
 <tr><td>Symbol</td><td>:format</td><td>:xhtml</td><td>HTML output format (Possible formats :xhtml, :html4, :html5, :html)</td></tr>
 <tr><td>String</td><td>:attr_wrapper</td><td>'"'</td><td>Character to wrap attributes in html (can be ' or ")</td></tr>
 <tr><td>Hash</td><td>:attr_delimiter</td><td>\{'class' => ' '}</td><td>Joining character used if multiple html attributes are supplied (e.g. class="class1 class2")</td></tr>
 <tr><td>Boolean</td><td>:sort_attrs</td><td>true</td><td>Sort attributes by name</td></tr>
-<tr><td>Boolean</td><td>:remove_empty_attrs</td><td>true</td><td>Remove attributes with empty value</td></tr>
 <tr><td>Boolean</td><td>:pretty</td><td>false</td><td>Pretty html indenting <b>(This is slower!)</b></td></tr>
 <tr><td>String</td><td>:indent</td><td>'  '</td><td>Indentation string</td></tr>
 <tr><td>Boolean</td><td>:streaming</td><td>false (true in Rails > 3.1)</td><td>Enable output streaming</td></tr>
 <tr><td>Class</td><td>:generator</td><td>Temple::Generators::ArrayBuffer/RailsOutputBuffer</td><td>Temple code generator (default generator generates array buffer)</td></tr>
+<tr><td>String</td><td>:buffer</td><td>'_buf' ('@output_buffer' in Rails)</td><td>Variable used for buffer</td></tr>
 </tbody>
 </table>
 
-Additionally the code generator options can be set (used by the :generator class). The standard generators support the options :buffer and :capture_generator.
-There are more options which are supported by the filters which are used by `Slim::Engine` but which are not exposed and are not officially supported. You
+There are more options which are supported by the Temple filters but which are not exposed and are not officially supported. You
 have to take a look at the Slim and Temple code for that.
 
+### Option priority and inheritance
+
+For developers who know more about Slim and Temple architecture it is possible to override default
+options at different positions. Temple uses an inheritance mechanism to allow subclasses to override
+options of the superclass. The option priorities are as follows:
+
+1. `Slim::Template` options passed at engine instatination
+2. `Slim::Template.default_options`
+3. `Slim::Engine.thread_options`, `Slim::Engine.default_options`
+5. Parser/Filter/Generator `thread_options`, `default_options` (e.g `Slim::Parser`, `Slim::Compiler`)
+
+It is also possible to set options for superclasses like `Temple::Engine`. But this will affect all temple template engines then.
+
+    Slim::Engine < Temple::Engine
+    Slim::Compiler < Temple::Filter
+
 ## Plugins
 
-### Logic-less mode
+### Logic less mode
+
+<a name="logicless">Logic less mode</a> is inspired by [Mustache](https://github.com/defunkt/mustache). Logic less mode uses a dictionary object
+e.g. a recursive hash tree which contains the dynamic content.
+
+#### Conditional
+
+If the object is not false or empty?, the content will show
+
+    - article
+      h1 = title
+
+#### Inverted conditional
+
+If the object is false or empty?, the content will show
+
+    -! article
+      p Sorry, article not found
+
+#### Iteration
+
+If the object is an array, the section will iterate
+
+    - articles
+      tr: td = title
+
+#### Wrapped dictionary - Resolution order
+
+Example code:
+
+    - article
+      h1 = title
+
+In wrapped dictionary acccess mode (the default, see the options), the dictionary object is accessed in the following order.
+
+1. If `article.respond_to?(:title)`, Slim will execute `article.send(:title)`
+2. If `article.respond_to?(:has_key?)` and `article.has_key?(:title)`, Slim will execute `article[:title]`
+3. If `article.instance_variable_defined?(@title)`, Slim will execute `article.instance_variable_get @title`
+
+If all the above fails, Slim will try to resolve the title reference in the same order against the parent object. In this example, the parent would be the dictionary object you are rendering the template against.
+
+As you might have guessed, the article reference goes through the same steps against the dictionary. Instance variables are not allowed in the view code, but Slim will find and use them. Essentially, you're just using dropping the @ prefix in your template. Parameterized method calls are not allowed.
+
+#### Logic less in Rails
 
-Enable the logic-less plugin with
+Install:
+
+    $ gem install slim
+
+Require:
+
+    gem 'slim', :require => 'slim/logic_less'
+
+You might want to activate logic less mode only for a few actions, you should disable logic-less mode globally at first in the configuration
+
+    Slim::Engine.set_default_options :logic_less => false
+
+and activate logic less mode per render call in your action
+
+    class Controller
+      def action
+        Slim::Engine.with_options(:logic_less => true) do
+          render
+        end
+      end
+    end
+
+#### Logic less in Sinatra
+
+Sinata has built-in support for Slim. All you have to do is require the logic less Slim plugin. This can be done in your config.ru:
 
     require 'slim/logic_less'
 
+You are then ready to rock!
+
+You might want to activate logic less mode only for a few actions, you should disable logic-less mode globally at first in the configuration
+
+    Slim::Engine.set_default_options :logic_less => false
+
+and activate logic less mode per render call in your application
+
+    get '/page'
+      slim :page, :logic_less => true
+    end
+
+#### Options
+
 <table>
 <thead style="font-weight:bold"><tr><td>Type</td><td>Name</td><td>Default</td><td>Purpose</td></tr></thead>
 <tbody>
@@ -502,18 +667,29 @@ Enable the logic-less plugin with
 </tbody>
 </table>
 
-#### Variable output
+### Translator/I18n
+
+The translator plugin provides automatic translation of the templates using Gettext, Fast-Gettext or Rails I18n. Static text
+in the template is replaced by the translated version.
+
+Example:
 
-#### Section
+    h1 Welcome to #{url}!
 
-#### Inverted section
+Gettext translates the string from english to german where interpolations are replaced by %1, %2, ...
 
-### Translator
+    "Welcome to %1!" -> "Willkommen auf %1!"
+
+and renders as
+
+    <h1>Willkommen auf slim-lang.com!</h1>
 
 Enable the translator plugin with
 
     require 'slim/translator'
 
+#### Options
+
 <table>
 <thead style="font-weight:bold"><tr><td>Type</td><td>Name</td><td>Default</td><td>Purpose</td></tr></thead>
 <tbody>
@@ -527,7 +703,7 @@ Enable the translator plugin with
 
 ### Tilt
 
-Slim uses Tilt to compile the generated code. If you want to use the Slim template directly, you can use the Tilt interface.
+Slim uses [Tilt](https://github.com/rtomayko/tilt) to compile the generated code. If you want to use the Slim template directly, you can use the Tilt interface.
 
     Tilt.new['template.slim'].render(scope)
     Slim::Template.new('template.slim', optional_option_hash).render(scope)
@@ -537,20 +713,19 @@ The optional option hash can have to options which were documented in the sectio
 
 ### Sinatra
 
-<pre>
-    require 'sinatra'
-    require 'slim'
-    
-    get('/') { slim :index }
-    
-    __END__
-    @@ index
-    doctype html
-    html
-      head
-        title Sinatra With Slim
-      body
-        h1 Slim Is Fun!
+<pre>require 'sinatra'
+require 'slim'
+
+get('/') { slim :index }
+
+ __END__
+@@ index
+doctype html
+html
+  head
+    title Sinatra With Slim
+  body
+    h1 Slim Is Fun!
 </pre>
 
 ### Rails
@@ -559,8 +734,56 @@ Rails generators are provided by [slim-rails](https://github.com/leogalmeida/sli
 is not necessary to use Slim in Rails though. Just install Slim and add it to your Gemfile with `gem 'slim'`.
 Then just use the .slim extension and you're good to go.
 
+#### Streaming
+
+HTTP streaming is enabled enabled by default if you use a Rails version which supports it.
+
 ## Tools
 
+### Slim Command 'slimrb'
+
+The gem 'slim' comes with the small tool 'slimrb' to test Slim from the command line.
+
+<pre>
+$ slimrb --help
+Usage: slimrb [options]
+    -s, --stdin                      Read input from standard input instead of an input file
+        --trace                      Show a full traceback on error
+    -c, --compile                    Compile only but do not run
+    -r, --rails                      Generate rails compatible code (Implies --compile)
+    -t, --translator                 Enable translator plugin
+    -l, --logic-less                 Enable logic less plugin
+    -p, --pretty                     Produce pretty html
+    -o, --option [NAME=CODE]         Set slim option
+    -h, --help                       Show this message
+    -v, --version                    Print version
+</pre>
+
+Start 'slimrb', type your code and press Ctrl-d to send EOF. Example usage:
+
+<pre>
+$ slimrb
+markdown:
+  First paragraph.
+
+  Second paragraph.
+
+  * one
+  * two
+  * three
+
+//Enter Ctrl-d
+&lt;p&gt;First paragraph &lt;/p&gt;
+
+&lt;p&gt;Second paragraph &lt;/p&gt;
+
+&lt;ul&gt;
+&lt;li&gt;one&lt;/li&gt;
+&lt;li&gt;two&lt;/li&gt;
+&lt;li&gt;three&lt;/li&gt;
+&lt;/ul&gt;
+</pre>
+
 ### Syntax Highlighters
 
 There are plugins for various text editors (including the most important ones - Vim, Emacs and Textmate):
@@ -581,8 +804,8 @@ There are plugins for various text editors (including the most important ones -
 ### Benchmarks
 
   *The benchmarks demonstrate that Slim in production mode
-   is nearly as fast as ERB. So if you choose not to use Slim it
-   is not due to its speed.*
+   is nearly as fast as Erubis (which is the fastest template engine).
+   So if you choose not to use Slim it is not due to its speed.*
 
 Run the benchmarks with `rake bench`. You can add the option `slow` to
 run the slow parsing benchmark which needs more time. You can also increase the number of iterations.
@@ -591,38 +814,39 @@ run the slow parsing benchmark which needs more time. You can also increase the
 
 <pre>
 Linux + Ruby 1.9.3, 1000 iterations
+
                       user     system      total        real
-(1) erb           0.020000   0.000000   0.020000 (  0.016618)
-(1) erubis        0.010000   0.000000   0.010000 (  0.013974)
-(1) fast erubis   0.010000   0.000000   0.010000 (  0.014625)
-(1) temple erb    0.030000   0.000000   0.030000 (  0.024930)
-(1) slim pretty   0.030000   0.000000   0.030000 (  0.030838)
-(1) slim ugly     0.020000   0.000000   0.020000 (  0.021263)
-(1) haml pretty   0.120000   0.000000   0.120000 (  0.121439)
-(1) haml ugly     0.110000   0.000000   0.110000 (  0.105082)
-(2) erb           0.030000   0.000000   0.030000 (  0.034145)
-(2) erubis        0.020000   0.000000   0.020000 (  0.022493)
-(2) temple erb    0.040000   0.000000   0.040000 (  0.034921)
-(2) slim pretty   0.040000   0.000000   0.040000 (  0.041750)
-(2) slim ugly     0.030000   0.000000   0.030000 (  0.030792)
-(2) haml pretty   0.140000   0.000000   0.140000 (  0.144159)
-(2) haml ugly     0.130000   0.000000   0.130000 (  0.129690)
-(3) erb           0.140000   0.000000   0.140000 (  0.140154)
-(3) erubis        0.110000   0.000000   0.110000 (  0.110870)
-(3) fast erubis   0.100000   0.000000   0.100000 (  0.098940)
-(3) temple erb    0.040000   0.000000   0.040000 (  0.036024)
-(3) slim pretty   0.040000   0.000000   0.040000 (  0.043326)
-(3) slim ugly     0.040000   0.000000   0.040000 (  0.031623)
-(3) haml pretty   0.310000   0.000000   0.310000 (  0.317270)
-(3) haml ugly     0.250000   0.000000   0.250000 (  0.256257)
-(4) erb           0.350000   0.000000   0.350000 (  0.352818)
-(4) erubis        0.310000   0.000000   0.310000 (  0.308558)
-(4) fast erubis   0.310000   0.000000   0.310000 (  0.308920)
-(4) temple erb    0.920000   0.000000   0.920000 (  0.920607)
-(4) slim pretty   3.510000   0.000000   3.510000 (  3.513418)
-(4) slim ugly     2.940000   0.000000   2.940000 (  2.944823)
-(4) haml pretty   2.320000   0.000000   2.320000 (  2.321830)
-(4) haml ugly     2.180000   0.000000   2.180000 (  2.179788)
+(1) erb           0.020000   0.000000   0.020000 (  0.017383)
+(1) erubis        0.020000   0.000000   0.020000 (  0.015048)
+(1) fast erubis   0.020000   0.000000   0.020000 (  0.015372) &lt;===
+(1) temple erb    0.030000   0.000000   0.030000 (  0.026239)
+(1) slim pretty   0.030000   0.000000   0.030000 (  0.031463)
+(1) slim ugly     0.020000   0.000000   0.020000 (  0.018868) &lt;===
+(1) haml pretty   0.130000   0.000000   0.130000 (  0.122521)
+(1) haml ugly     0.110000   0.000000   0.110000 (  0.106640)
+(2) erb           0.030000   0.000000   0.030000 (  0.035520)
+(2) erubis        0.020000   0.000000   0.020000 (  0.023070)
+(2) temple erb    0.040000   0.000000   0.040000 (  0.036514)
+(2) slim pretty   0.040000   0.000000   0.040000 (  0.040086)
+(2) slim ugly     0.030000   0.000000   0.030000 (  0.028461)
+(2) haml pretty   0.150000   0.000000   0.150000 (  0.145618)
+(2) haml ugly     0.130000   0.000000   0.130000 (  0.129492)
+(3) erb           0.140000   0.000000   0.140000 (  0.134953)
+(3) erubis        0.120000   0.000000   0.120000 (  0.119723)
+(3) fast erubis   0.100000   0.000000   0.100000 (  0.097456)
+(3) temple erb    0.040000   0.000000   0.040000 (  0.035916)
+(3) slim pretty   0.040000   0.000000   0.040000 (  0.039626)
+(3) slim ugly     0.030000   0.000000   0.030000 (  0.027827)
+(3) haml pretty   0.310000   0.000000   0.310000 (  0.306664)
+(3) haml ugly     0.250000   0.000000   0.250000 (  0.248742)
+(4) erb           0.350000   0.000000   0.350000 (  0.350719)
+(4) erubis        0.310000   0.000000   0.310000 (  0.304832)
+(4) fast erubis   0.300000   0.000000   0.300000 (  0.303070)
+(4) temple erb    0.910000   0.000000   0.910000 (  0.911745)
+(4) slim pretty   3.410000   0.000000   3.410000 (  3.413267)
+(4) slim ugly     2.880000   0.000000   2.880000 (  2.885265)
+(4) haml pretty   2.280000   0.000000   2.280000 (  2.292623)
+(4) haml ugly     2.170000   0.000000   2.170000 (  2.169292)
 
 (1) Compiled benchmark. Template is parsed before the benchmark and
     generated ruby code is compiled into a method.
@@ -662,9 +886,26 @@ Slim is working well on all major Ruby implementations:
 * JRuby
 * Rubinius 2.0
 
+## Contributing
+
+If you'd like to help improve Slim, clone the project with Git by running:
+
+    $ git clone git://github.com/stonean/slim
+
+Work your magic and then submit a pull request. We love pull requests!
+
+Please remember to test against Ruby versions 1.9.2 and 1.8.7.
+
+If you find the documentation lacking (and you probably will), help us out
+The docs are located in the gh-pages branch:
+
+    $ git checkout gh-pages
+
+If you don't have the time to work on Slim, but found something we should know about, please submit an issue.
+
 ## License
 
-This project is released under the MIT license.
+Slim is released under the [MIT license](http://www.opensource.org/licenses/MIT).
 
 ## Authors
 
@@ -707,5 +948,5 @@ Language ports/Similar languages:
 * [Hamlet.rb (Similar template language)](https://github.com/gregwebs/hamlet.rb)
 * [Plim (Python port of Slim)](https://github.com/2nd/plim)
 * [Skim (Slim for Javascript)](https://github.com/jfirebaugh/skim)
-* [Haml (Older engine which inspired Slim)](https://github.com/nex3/haml)
-* [Jade (Similar engine for javascript)](https://github.com/visionmedia/jade)
+* [Haml (Older engine which inspired Slim)](https://github.com/haml/haml)
+* [Jade (Similar engine for javascript)](https://github.com/visionmedia/jade)