tilt 1.2 → 1.3.1

data/README.md

@@ -21,22 +21,29 @@ template engines included in the distribution.
 
 Support for these template engines is included with the package:
 
-    ENGINE                     FILE EXTENSIONS   REQUIRED LIBRARIES
-    -------------------------- ----------------- ----------------------------
-    ERB                        .erb              none (included ruby stdlib)
-    Interpolated String        .str              none (included ruby core)
-    Haml                       .haml             haml
-    Sass                       .sass             haml
-    Less CSS                   .less             less
-    Builder                    .builder          builder
-    Liquid                     .liquid           liquid
-    RDiscount                  .markdown         rdiscount
-    RedCloth                   .textile          redcloth
-    RDoc                       .rdoc             rdoc
-    Radius                     .radius           radius
-    Markaby                    .mab              markaby
-    Nokogiri                   .nokogiri         nokogiri
-    CoffeeScript               .coffee           coffee-script (+node coffee)
+    ENGINE                     FILE EXTENSIONS        REQUIRED LIBRARIES
+    -------------------------- ---------------------- ----------------------------
+    ERB                        .erb, .rhtml           none (included ruby stdlib)
+    Interpolated String        .str                   none (included ruby core)
+    Erubis                     .erb, .rhtml, .erubis  erubis
+    Haml                       .haml                  haml
+    Sass                       .sass                  haml (< 3.1) or sass (>= 3.1)
+    Scss                       .scss                  haml (< 3.1) or sass (>= 3.1)
+    Less CSS                   .less                  less
+    Builder                    .builder               builder
+    Liquid                     .liquid                liquid
+    RDiscount                  .markdown, .mkd, .md   rdiscount
+    Redcarpet                  .markdown, .mkd, .md   redcarpet
+    BlueCloth                  .markdown, .mkd, .md   bluecloth
+    Kramdown                   .markdown, .mkd, .md   kramdown
+    Maruku                     .markdown, .mkd, .md   maruku
+    RedCloth                   .textile               redcloth
+    RDoc                       .rdoc                  rdoc
+    Radius                     .radius                radius
+    Markaby                    .mab                   markaby
+    Nokogiri                   .nokogiri              nokogiri
+    CoffeeScript               .coffee                coffee-script (+ javascript)
+    Creole (Wiki markup)       .creole                creole
 
 These template engines ship with their own Tilt integration:
 
@@ -116,7 +123,7 @@ classes based on those associations.
 The `Tilt::register` method associates a filename pattern with a specific
 template implementation. To use ERB for files ending in a `.bar` extension:
 
-     >> Tilt.register 'bar', Tilt::ERBTemplate
+     >> Tilt.register Tilt::ERBTemplate, 'bar'
      >> Tilt.new('views/foo.bar')
      => #<Tilt::ERBTemplate @file="views/foo.bar" ...>
 
@@ -131,7 +138,7 @@ It's also possible to register template file mappings that are more specific
 than a file extension. To use Erubis for `bar.erb` but ERB for all other `.erb`
 files:
 
-     >> Tilt.register 'bar.erb', Tilt::ErubisTemplate
+     >> Tilt.register Tilt::ErubisTemplate, 'bar.erb'
      >> Tilt.new('views/foo.erb')
      => Tilt::ERBTemplate
      >> Tilt.new('views/bar.erb')
@@ -147,14 +154,37 @@ mappings:
   3. `html.erb`
   4. `erb`
 
-`Tilt::register` can also be used to select between alternative template
-engines. To use Erubis instead of ERB for `.erb` files:
+### Fallback mode
+
+If there are more than one template class registered for a file extension, Tilt
+will automatically try to load the version that works on your machine:
+
+  1. If any of the template engines has been loaded already: Use that one.
+  2. If not, it will try to initialize each of the classes with an empty template.
+  3. Tilt will use the first that doesn't raise an exception.
+  4. If however *all* of them failed, Tilt will raise the exception of the first
+     template engine, since that was the most preferred one.
+
+Template classes that were registered *last* would be tried first. Because the
+Markdown extensions are registered like this:
+
+    Tilt.register Tilt::BlueClothTemplate, 'md'
+    Tilt.register Tilt::RDiscountTemplate, 'md'
+
+Tilt will first try RDiscount and then BlueCloth. You could say that RDiscount
+has a *higher priority* than BlueCloth.
 
-    Tilt.register 'erb', Tilt::ErubisTemplate
+The fallback mode works nicely when you just need to render an ERB or Markdown
+template, but if you depend on a specific implementation, you should use #prefer:
 
-Or, use BlueCloth for markdown instead of RDiscount:
+    # Prefer BlueCloth for all its registered extensions (markdown, mkd, md)
+    Tilt.prefer Tilt::BlueClothTemplate
+    
+    # Prefer Erubis for .erb only:
+    Tilt.prefer Tilt::ErubisTemplate, 'erb'
 
-    Tilt.register 'markdown', Tilt::BlueClothTemplate
+When a file extension has a preferred template class, Tilt will *always* use
+that class, even if it raises an exception.
 
 Template Compilation
 --------------------
@@ -164,7 +194,7 @@ it on subsequent template invocations. Benchmarks show this yields a 5x-10x
 performance increase over evaluating the Ruby source on each invocation.
 
 Template compilation is currently supported for these template engines:
-StringTemplate, ERB, Erubis, Haml, and Builder.
+StringTemplate, ERB, Erubis, Haml, Nokogiri and Builder.
 
 LICENSE
 -------