sinatra 1.2.0.a → 1.2.0.c

data/README.fr.rdoc

@@ -171,7 +171,7 @@ au lieu de les considérer comme un chemin vers un fichier.
 
 Le gem haml est nécessaire pour utiliser la fonction de rendu Haml:
 
-  ## Chargez la bibliothèque haml dans votre application
+  # Chargez la bibliothèque haml dans votre application
   require 'haml'
 
   get '/' do
@@ -194,7 +194,7 @@ et supportent aussi la réécriture (surcharge) comme dans cet exemple.
 
 === Templates Erb
 
-  ## Chargez la bibliothèque erb dans votre application
+  # Chargez la bibliothèque erb dans votre application
   require 'erb'
 
   get '/' do
@@ -207,7 +207,7 @@ Utilisera le template: <tt>./views/index.erb</tt>
 
 Le gem erubis est nécessaire pour utiliser la fonction de rendu erubis:
 
-  ## Chargez la bibliothèque erubis dans votre application
+  # Chargez la bibliothèque erubis dans votre application
   require 'erubis'
 
   get '/' do
@@ -220,7 +220,7 @@ Utilisera le template: <tt>./views/index.erubis</tt>
 
 Le gem builder est nécessaire pour utiliser la fonction de rendu builder:
 
-  ## Chargez la bibliothèque builder dans votre application
+  # Chargez la bibliothèque builder dans votre application
   require 'builder'
 
   get '/' do
@@ -233,7 +233,7 @@ Utilisera le template: <tt>./views/index.builder</tt>.
 
 Le gem nokogiri est nécessaire pour utiliser la fonction de rendu nokogiri:
 
-  ## Chargez la bibliothèque nokogiri dans votre application
+  # Chargez la bibliothèque nokogiri dans votre application
   require 'nokogiri'
 
   get '/' do
@@ -246,7 +246,7 @@ Utilisera le template: <tt>./views/index.nokogiri</tt>.
 
 Le gem haml est nécessaire pour utiliser la fonction de rendu Sass:
 
-  ## Chargez la bibliothèque haml ou sass dans votre application
+  # Chargez la bibliothèque haml ou sass dans votre application
   require 'sass'
 
   get '/stylesheet.css' do
@@ -270,7 +270,7 @@ et supportent aussi la réécriture (surcharge) comme dans cet exemple.
 
 Le gem haml est nécessaire pour utiliser la fonction de rendu Scss:
 
-  ## Chargez la bibliothèque haml ou sass dans votre application
+  # Chargez la bibliothèque haml ou sass dans votre application
   require 'sass'
 
   get '/stylesheet.css' do
@@ -294,7 +294,7 @@ et supportent aussi la réécriture (surcharge) comme dans cet exemple.
 
 Le gem less est nécessaire pour utiliser la fonction de rendu Less:
 
-  ## Chargez la bibliothèque less dans votre application
+  # Chargez la bibliothèque less dans votre application
   require 'less'
 
   get '/stylesheet.css' do
@@ -307,7 +307,7 @@ Utilisera le template: <tt>./views/stylesheet.less</tt>.
 
 Le gem liquid est nécessaire pour utiliser la fonction de rendu Liquid:
 
-  ## Chargez la bibliothèque liquid dans votre application
+  # Chargez la bibliothèque liquid dans votre application
   require 'liquid'
 
   get '/' do
@@ -325,7 +325,7 @@ template Liquid, il sera toujours nécessaire de lui passer des variables locale
 
 Le gem rdiscount est nécessaire pour utiliser la fonction de rendu Markdown:
 
-  ## Chargez la bibliothèque rdiscount dans votre application
+  # Chargez la bibliothèque rdiscount dans votre application
   require "rdiscount"
 
   get '/' do
@@ -350,7 +350,7 @@ Notez que vous pouvez également appeler la méthode markdown au sein d'autres t
 
 Le gem RedCloth est nécessaire pour utiliser la fonction de rendu Textile:
 
-  ## Chargez la bibliothèqye redcloth dans votre application
+  # Chargez la bibliothèqye redcloth dans votre application
   require "redcloth"
 
   get '/' do
@@ -374,7 +374,7 @@ Notez que vous pouvez également appeler la méthode textile au sein d'autres te
 
 Le gem RDoc est nécessaire pour utiliser la fonction de rendu RDoc:
 
-  ## Chargez la bibliothèque rdoc dans votre application
+  # Chargez la bibliothèque rdoc dans votre application
   require "rdoc"
 
   get '/' do
@@ -398,7 +398,7 @@ Notez que vous pouvez également appeler la méthode rdoc au sein d'autres templ
 
 Le gem radius est nécessaire pour utiliser la fonction de rendu Radius:
 
-  ## Chargez la bibliotèque radius dans votre application
+  # Chargez la bibliotèque radius dans votre application
   require 'radius'
 
   get '/' do
@@ -416,7 +416,7 @@ template Radius, il sera toujours nécessaire de lui passer des variables locale
 
 Le gem markaby est nécessaire pour utiliser la fonction de rendu Markaby:
 
-  ## Chargez la bibliothèque markaby dans votre application
+  # Chargez la bibliothèque markaby dans votre application
   require 'markaby'
 
   get '/' do
@@ -429,7 +429,7 @@ Utilisera <tt>./views/index.mab</tt>.
 
 Le gem slim est nécessaire pour utiliser la fonction de rendu Slim:
 
-  ## Chargez la bibliothèque slim dans votre application
+  # Chargez la bibliothèque slim dans votre application
   require 'slim'
 
   get '/' do
@@ -443,7 +443,7 @@ Utilisera <tt>./views/index.slim</tt>.
 Le gem coffee-script et l'exécutable `coffee` sont nécessaires pour utiliser la
 fonction de rendu CoffeeScript:
 
-  ## Chargez la bibliothèque coffee-script dans votre application
+  # Chargez la bibliothèque coffee-script dans votre application
   require 'coffee-script'
 
   get '/application.js' do

data/README.hu.rdoc

@@ -123,7 +123,7 @@ metódusok minden, nekik közvetlenül átadott karakterláncot megjelenítenek.
 
 HAML sablonok rendereléséhez szükségünk lesz a haml gem-re vagy könyvtárra:
 
-  ## Importáljuk be a haml-t az alkalmazásba
+  # Importáljuk be a haml-t az alkalmazásba
   require 'haml'
 
   get '/' do
@@ -146,7 +146,7 @@ A globális beállításokat lehetőségünk van felülírni metódus szinten is
 
 === Erb sablonok
 
-  ## Importáljuk be az erb-t az alkalmazásba
+  # Importáljuk be az erb-t az alkalmazásba
   require 'erb'
 
   get '/' do
@@ -160,7 +160,7 @@ Ez a <tt>./views/index.erb</tt> sablont fogja lerenderelni.
 Szükségünk lesz a builder gem-re vagy könyvtárra a builder sablonok
 rendereléséhez:
 
-  ## Importáljuk be a builder-t az alkalmazásba
+  # Importáljuk be a builder-t az alkalmazásba
   require 'builder'
 
   get '/' do
@@ -173,7 +173,7 @@ Ez pedig a <tt>./views/index.builder</tt> állományt fogja renderelni.
 
 Sass sablonok használatához szükség lesz a haml gem-re vagy könyvtárra:
 
-  ## Be kell importálni a haml, vagy a sass könyvtárat
+  # Be kell importálni a haml, vagy a sass könyvtárat
   require 'sass'
 
   get '/stylesheet.css' do

data/README.jp.rdoc

@@ -169,7 +169,7 @@ Rackレスポンス、Rackボディオブジェクト、HTTPステータスコ
 
 hamlを使うにはhamlライブラリが必要です:
 
-  ## hamlを読み込みます
+  # hamlを読み込みます
   require 'haml'
 
   get '/' do
@@ -192,7 +192,7 @@ hamlを使うにはhamlライブラリが必要です:
 
 === Erb テンプレート
 
-  ## erbを読み込みます
+  # erbを読み込みます
   require 'erb'
 
   get '/' do
@@ -205,7 +205,7 @@ hamlを使うにはhamlライブラリが必要です:
 
 erubisテンプレートを表示するには、erubisライブラリが必要です:
 
-  ## erubisを読み込みます
+  # erubisを読み込みます
   require 'erubis'
 
   get '/' do
@@ -218,7 +218,7 @@ erubisテンプレートを表示するには、erubisライブラリが必要
 
 builderを使うにはbuilderライブラリが必要です:
 
-  ## builderを読み込みます
+  # builderを読み込みます
   require 'builder'
 
   get '/' do
@@ -231,7 +231,7 @@ builderを使うにはbuilderライブラリが必要です:
 
 鋸を使うには鋸ライブラリが必要です:
 
-  ## 鋸を読み込みます
+  # 鋸を読み込みます
   require 'nokogiri'
 
   get '/' do
@@ -244,7 +244,7 @@ builderを使うにはbuilderライブラリが必要です:
 
 Sassテンプレートを使うにはsassライブラリが必要です:
 
-  ## hamlかsassを読み込みます
+  # hamlかsassを読み込みます
   require 'sass'
 
   get '/stylesheet.css' do
@@ -268,7 +268,7 @@ see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
 
 Scssテンプレートを使うにはsassライブラリが必要です:
 
-  ## hamlかsassを読み込みます
+  # hamlかsassを読み込みます
   require 'sass'
 
   get '/stylesheet.css' do
@@ -292,7 +292,7 @@ see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
 
 Lessテンプレートを使うにはlessライブラリが必要です:
 
-  ## lessを読み込みます
+  # lessを読み込みます
   require 'less'
 
   get '/stylesheet.css' do
@@ -305,7 +305,7 @@ Lessテンプレートを使うにはlessライブラリが必要です:
 
 Liquidテンプレートを使うにはliquidライブラリが必要です:
 
-  ## liquidを読み込みます
+  # liquidを読み込みます
   require 'liquid'
 
   get '/' do
@@ -323,7 +323,7 @@ LiquidテンプレートからRubyのメソッド(+yield+を除く)を呼び出
 
 Markdownテンプレートを使うにはrdiscountライブラリが必要です:
 
-  ## rdiscountを読み込みます
+  # rdiscountを読み込みます
   require "rdiscount"
   
   get '/' do
@@ -346,7 +346,7 @@ markdownからメソッドを呼び出すことも、localsに変数を渡すこ
 
 Textileテンプレートを使うにはRedClothライブラリが必要です:
 
-  ## redclothを読み込みます
+  # redclothを読み込みます
   require "redcloth"
 
   get '/' do
@@ -369,7 +369,7 @@ textileからメソッドを呼び出すことも、localsに変数を渡すこ
 
 RDocテンプレートを使うにはRDocライブラリが必要です:
 
-  ## rdocを読み込みます
+  # rdocを読み込みます
   require "rdoc"
 
   get '/' do
@@ -392,7 +392,7 @@ rdocからメソッドを呼び出すことも、localsに変数を渡すこと
 
 Radiusテンプレートを使うにはradiusライブラリが必要です:
 
-  ## radiusを読み込みます
+  # radiusを読み込みます
   require 'radius'
 
   get '/' do
@@ -410,7 +410,7 @@ RadiusテンプレートからRubyのメソッド(+yield+を除く)を呼び出
 
 Markabyテンプレートを使うにはmarkabyライブラリが必要です:
 
-  ## markabyを読み込みます
+  # markabyを読み込みます
   require 'markaby'
 
   get '/' do
@@ -423,7 +423,7 @@ Markabyテンプレートを使うにはmarkabyライブラリが必要です:
 
 Slimテンプレートを使うにはslimライブラリが必要です:
 
-  ## slimを読み込みます
+  # slimを読み込みます
   require 'slim'
 
   get '/' do
@@ -436,7 +436,7 @@ Slimテンプレートを使うにはslimライブラリが必要です:
 
 CoffeeScriptテンプレートを表示するにはcoffee-scriptライブラリと`coffee`バイナリが必要です:
 
-  ## coffee-scriptを読み込みます
+  # coffee-scriptを読み込みます
   require 'coffee-script'
 
   get '/application.js' do

data/README.pt-br.rdoc

@@ -119,7 +119,7 @@ qualquer string passada diretamente para elas.
 
 A gem/biblioteca haml é necessária para renderizar templates HAML:
 
-  ## Você precisa do 'require haml' em sua aplicação.
+  # Você precisa do 'require haml' em sua aplicação.
   require 'haml'
 
   get '/' do
@@ -142,7 +142,7 @@ e substitua em uma requisição individual.
 
 === Erb Templates
 
-  ## Você precisa do 'require erb' em sua aplicação
+  # Você precisa do 'require erb' em sua aplicação
   require 'erb'
 
   get '/' do
@@ -155,7 +155,7 @@ Renderiza <tt>./views/index.erb</tt>
 
 A gem/biblioteca erubis é necessária para renderizar templates erubis:
 
-  ## Você precisa do 'require erubis' em sua aplicação.
+  # Você precisa do 'require erubis' em sua aplicação.
   require 'erubis'
 
   get '/' do
@@ -168,7 +168,7 @@ Renderiza <tt>./views/index.erubis</tt>
 
 A gem/biblioteca builder é necessária para renderizar templates builder:
 
-  ## Você precisa do 'require builder' em sua aplicação.
+  # Você precisa do 'require builder' em sua aplicação.
   require 'builder'
 
   get '/' do
@@ -182,7 +182,7 @@ Renderiza <tt>./views/index.builder</tt>.
 
 A gem/biblioteca sass é necessária para renderizar templates sass:
 
-  ## Você precisa do 'require haml' ou 'require sass' em sua aplicação.
+  # Você precisa do 'require haml' ou 'require sass' em sua aplicação.
   require 'sass'
 
   get '/stylesheet.css' do
@@ -208,7 +208,7 @@ e substitua em uma requisição individual.
 
 A gem/biblioteca less é necessária para renderizar templates Less:
 
-  ## Você precisa do 'require less' em sua aplicação.
+  # Você precisa do 'require less' em sua aplicação.
   require 'less'
 
   get '/stylesheet.css' do

data/README.rdoc

@@ -123,7 +123,7 @@ You can easily define your own conditions:
     "Sorry, you lost."
   end
 
-=== Return values
+=== Return Values
 
 The return value of a route block determines at least the response body passed
 on to the HTTP client, or at least the next middleware in the Rack stack.
@@ -174,9 +174,9 @@ directly.
 
 === Haml Templates
 
-The haml gem/library is required to render HAML templates:
+The <tt>haml</tt> gem/library is required to render HAML templates:
 
-  ## You'll need to require haml in your app
+  # You'll need to require haml in your app
   require 'haml'
 
   get '/' do
@@ -199,33 +199,44 @@ and overridden on an individual basis.
 
 === Erb Templates
 
-  ## You'll need to require erb in your app
+  # You'll need to require erb in your app
   require 'erb'
 
   get '/' do
     erb :index
   end
 
-Renders <tt>./views/index.erb</tt>
+Renders <tt>./views/index.erb</tt>.
 
-=== Erubis
+=== Erubis Templates
 
-The erubis gem/library is required to render erubis templates:
+The <tt>erubis</tt> gem/library is required to render Erubis templates:
 
-  ## You'll need to require erubis in your app
+  # You'll need to require erubis in your app
   require 'erubis'
 
   get '/' do
     erubis :index
   end
 
-Renders <tt>./views/index.erubis</tt>
+Renders <tt>./views/index.erubis</tt>.
+
+It is also possible to replace Erb with Erubis:
+
+  require 'erubis'
+  Tilt.register :erb, Tilt[:erubis]
+  
+  get '/' do
+    erb :index
+  end
+
+Renders <tt>./views/index.erb</tt> with Erubis.
 
 === Builder Templates
 
-The builder gem/library is required to render builder templates:
+The <tt>builder</tt> gem/library is required to render builder templates:
 
-  ## You'll need to require builder in your app
+  # You'll need to require builder in your app
   require 'builder'
 
   get '/' do
@@ -236,9 +247,9 @@ Renders <tt>./views/index.builder</tt>.
 
 === Nokogiri Templates
 
-The nokogiri gem/library is required to render nokogiri templates:
+The <tt>nokogiri</tt> gem/library is required to render nokogiri templates:
 
-  ## You'll need to require nokogiri in your app
+  # You'll need to require nokogiri in your app
   require 'nokogiri'
 
   get '/' do
@@ -249,9 +260,9 @@ Renders <tt>./views/index.nokogiri</tt>.
 
 === Sass Templates
 
-The haml gem/library is required to render Sass templates:
+The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Sass templates:
 
-  ## You'll need to require haml or sass in your app
+  # You'll need to require haml or sass in your app
   require 'sass'
 
   get '/stylesheet.css' do
@@ -273,9 +284,9 @@ and overridden on an individual basis.
 
 === Scss Templates
 
-The haml gem/library is required to render Scss templates:
+The <tt>haml</tt> or <tt>sass</tt> gem/library is required to render Scss templates:
 
-  ## You'll need to require haml or sass in your app
+  # You'll need to require haml or sass in your app
   require 'sass'
 
   get '/stylesheet.css' do
@@ -297,9 +308,9 @@ and overridden on an individual basis.
 
 === Less Templates
 
-The less gem/library is required to render Less templates:
+The <tt>less</tt> gem/library is required to render Less templates:
 
-  ## You'll need to require less in your app
+  # You'll need to require less in your app
   require 'less'
 
   get '/stylesheet.css' do
@@ -310,9 +321,9 @@ Renders <tt>./views/stylesheet.less</tt>.
 
 === Liquid Templates
 
-The liquid gem/library is required to render Liquid templates:
+The <tt>liquid</tt> gem/library is required to render Liquid templates:
 
-  ## You'll need to require liquid in your app
+  # You'll need to require liquid in your app
   require 'liquid'
 
   get '/' do
@@ -328,9 +339,9 @@ template, you almost always want to pass locals to it:
 
 === Markdown Templates
 
-The rdiscount gem/library is required to render Markdown templates:
+The <tt>rdiscount</tt> gem/library is required to render Markdown templates:
 
-  ## You'll need to require rdiscount in your app
+  # You'll need to require rdiscount in your app
   require "rdiscount"
   
   get '/' do
@@ -340,20 +351,58 @@ The rdiscount gem/library is required to render Markdown templates:
 Renders <tt>./views/index.markdown</tt> (+md+ and +mkd+ are also valid file
 extensions).
 
-It is not possible to call methods from markdown, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
+It is not possible to call methods from markdown, nor to pass locals to it.
+You therefore will usually use it in combination with another rendering
+engine:
 
   erb :overview, :locals => { :text => markdown(:introduction) }
 
-Note that you may also call the markdown method from within other templates:
+Note that you may also call the +markdown+ method from within other templates:
 
   %h1 Hello From Haml!
   %p= markdown(:greetings)
 
+Since you cannot call Ruby from Markdown, you cannot use layouts written in
+Markdown. However, it is possible to use another rendering engine for the
+template than for the layout by passing the <tt>:layout_engine</tt> option:
+
+  get '/' do
+    markdown :index, :layout_engine => :erb
+  end
+
+This will render <tt>./views/index.md</tt> with <tt>./views/layout.erb</tt> as
+layout.
+
+Remember that you can set such rendering options globally:
+
+  set :markdown, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    markdown :index
+  end
+
+This will render <tt>./views/index.md</tt> (and any other Markdown template)
+with <tt>./views/post.haml</tt> as layout.
+
+It is also possible to parse Markdown with BlueCloth rather than RDiscount:
+
+  require 'bluecloth'
+  
+  Tilt.register 'markdown', BlueClothTemplate
+  Tilt.register 'mkd',      BlueClothTemplate
+  Tilt.register 'md',       BlueClothTemplate
+  
+  get '/' do
+    markdown :index
+  end
+
+Renders <tt>./views/index.md</tt> with BlueCloth.
+
 === Textile Templates
 
-The RedCloth gem/library is required to render Textile templates:
+The <tt>RedCloth</tt> gem/library is required to render Textile templates:
 
-  ## You'll need to require redcloth in your app
+  # You'll need to require redcloth in your app
   require "redcloth"
 
   get '/' do
@@ -362,20 +411,43 @@ The RedCloth gem/library is required to render Textile templates:
 
 Renders <tt>./views/index.textile</tt>.
 
-It is not possible to call methods from textile, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
+It is not possible to call methods from textile, nor to pass locals to it. You
+therefore will usually use it in combination with another rendering engine:
 
   erb :overview, :locals => { :text => textile(:introduction) }
 
-Note that you may also call the textile method from within other templates:
+Note that you may also call the +textile+ method from within other templates:
 
   %h1 Hello From Haml!
   %p= textile(:greetings)
 
+Since you cannot call Ruby from Textile, you cannot use layouts written in
+Textile. However, it is possible to use another rendering engine for the
+template than for the layout by passing the <tt>:layout_engine</tt> option:
+
+  get '/' do
+    textile :index, :layout_engine => :erb
+  end
+
+This will render <tt>./views/index.textile</tt> with
+<tt>./views/layout.erb</tt> as layout.
+
+Remember that you can set such rendering options globally:
+
+  set :textile, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    textile :index
+  end
+
+This will render <tt>./views/index.textile</tt> (and any other Textile
+template) with <tt>./views/post.haml</tt> as layout.
+
 === RDoc Templates
 
-The RDoc gem/library is required to render RDoc templates:
+The <tt>rdoc</tt> gem/library is required to render RDoc templates:
 
-  ## You'll need to require rdoc in your app
+  # You'll need to require rdoc in your app
   require "rdoc"
 
   get '/' do
@@ -384,20 +456,43 @@ The RDoc gem/library is required to render RDoc templates:
 
 Renders <tt>./views/index.rdoc</tt>.
 
-It is not possible to call methods from rdoc, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
+It is not possible to call methods from rdoc, nor to pass locals to it. You
+therefore will usually use it in combination with another rendering engine:
 
   erb :overview, :locals => { :text => rdoc(:introduction) }
 
-Note that you may also call the rdoc method from within other templates:
+Note that you may also call the +rdoc+ method from within other templates:
 
   %h1 Hello From Haml!
   %p= rdoc(:greetings)
 
+Since you cannot call Ruby from RDoc, you cannot use layouts written in
+RDoc. However, it is possible to use another rendering engine for the
+template than for the layout by passing the <tt>:layout_engine</tt> option:
+
+  get '/' do
+    rdoc :index, :layout_engine => :erb
+  end
+
+This will render <tt>./views/index.rdoc</tt> with <tt>./views/layout.erb</tt> as
+layout.
+
+Remember that you can set such rendering options globally:
+
+  set :rdoc, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    rdoc :index
+  end
+
+This will render <tt>./views/index.rdoc</tt> (and any other RDoc template)
+with <tt>./views/post.haml</tt> as layout.
+
 === Radius Templates
 
-The radius gem/library is required to render Radius templates:
+The <tt>radius</tt> gem/library is required to render Radius templates:
 
-  ## You'll need to require radius in your app
+  # You'll need to require radius in your app
   require 'radius'
 
   get '/' do
@@ -413,9 +508,9 @@ template, you almost always want to pass locals to it:
 
 === Markaby Templates
 
-The markaby gem/library is required to render Markaby templates:
+The <tt>markaby</tt> gem/library is required to render Markaby templates:
 
-  ## You'll need to require markaby in your app
+  # You'll need to require markaby in your app
   require 'markaby'
 
   get '/' do
@@ -424,7 +519,7 @@ The markaby gem/library is required to render Markaby templates:
 
 Renders <tt>./views/index.mab</tt>.
 
-If you have Tilt 1.2 or later, you may also use inline markaby:
+You may also use inline Markaby:
 
   get '/' do
     markaby { h1 "Welcome!" }
@@ -432,9 +527,9 @@ If you have Tilt 1.2 or later, you may also use inline markaby:
 
 === Slim Templates
 
-The slim gem/library is required to render Slim templates:
+The <tt>slim</tt> gem/library is required to render Slim templates:
 
-  ## You'll need to require slim in your app
+  # You'll need to require slim in your app
   require 'slim'
 
   get '/' do
@@ -445,10 +540,18 @@ Renders <tt>./views/index.slim</tt>.
 
 === CoffeeScript Templates
 
-The coffee-script gem/library and the `coffee` binary are required to render
-CoffeeScript templates:
+The <tt>coffee-script</tt> gem/library and at least <b>one</b> of the
+following options to execute JavaScript:
+
+* +node+ (from Node.js) in your path
+* you must be running on OSX
+* +therubyracer+ gem/library
+
+See http://github.com/josh/ruby-coffee-script for an updated list of options.
+
+Now you can render CoffeeScript templates:
 
-  ## You'll need to require coffee-script in your app
+  # You'll need to require coffee-script in your app
   require 'coffee-script'
 
   get '/application.js' do
@@ -457,13 +560,13 @@ CoffeeScript templates:
 
 Renders <tt>./views/application.coffee</tt>.
 
-=== Inline Templates
+=== Embedded Templates
 
   get '/' do
     haml '%div.title Hello World'
   end
 
-Renders the inlined template string.
+Renders the embedded template string.
 
 === Accessing Variables in Templates
 
@@ -525,27 +628,38 @@ Templates may also be defined using the top-level <tt>template</tt> method:
   end
 
 If a template named "layout" exists, it will be used each time a template
-is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
+is rendered. You can individually disable layouts by passing <tt>:layout => false</tt>
+or disable them by default via <tt>set :haml, :layout => false</tt>.
 
   get '/' do
     haml :index, :layout => !request.xhr?
   end
 
-== Helpers
+=== Associating File Extensions
 
-Use the top-level <tt>helpers</tt> method to define helper methods for use in
-route handlers and templates:
+To associate a file extension with a template engine, use
+<tt>Tilt.register</tt>. For instance, if you like to use the file extension
++tt+ for Textile templates, you can do the following:
+
+  Tilt.register :tt, Tilt[:textile]
+
+=== Adding You Own Template Engine
+
+First, register your engine with Tilt, then create a rendering method:
+
+  Tilt.register :myat, MyAwesomeTemplateEngine
 
   helpers do
-    def bar(name)
-      "#{name}bar"
-    end
+    def myat(*args) render(:myat, *args) end
   end
 
-  get '/:name' do
-    bar(params[:name])
+  get '/' do
+    myat :index
   end
 
+Renders <tt>./views/index.myat</tt>. See https://github.com/rtomayko/tilt to
+learn more about Tilt.
+
 == Filters
 
 Before filters are evaluated before each request within the same context as
@@ -570,6 +684,10 @@ and routes are accessible by after filters:
     puts response.status
   end
 
+Note: Unless you use the +body+ method rather than just returning a String from
+the routes, the body will not yet be available in the after filter, since it is
+generated later on.
+
 Filters optionally taking a pattern, causing them to be evaluated only if the
 request path matches that pattern:
 
@@ -591,7 +709,22 @@ Like routes, filters also take conditions:
     # ...
   end
 
-== Halting
+== Helpers
+
+Use the top-level <tt>helpers</tt> method to define helper methods for use in
+route handlers and templates:
+
+  helpers do
+    def bar(name)
+      "#{name}bar"
+    end
+  end
+
+  get '/:name' do
+    bar(params[:name])
+  end
+
+=== Halting
 
 To immediately stop a request within a filter or route use:
 
@@ -613,7 +746,7 @@ With headers:
 
   halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
 
-== Passing
+=== Passing
 
 A route can punt processing to the next matching route using <tt>pass</tt>:
 
@@ -629,9 +762,148 @@ A route can punt processing to the next matching route using <tt>pass</tt>:
 The route block is immediately exited and control continues with the next
 matching route. If no matching route is found, a 404 is returned.
 
-== Accessing the Request Object
+=== Triggering Another Route
+
+Sometimes +pass+ is not what you want, instead you would like to get the result
+of calling another route. Simply use +call+ to achieve this:
+
+  get '/foo' do
+    status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
+    [status, body.upcase]
+  end
+
+  get '/bar' do
+    "bar"
+  end
+
+Note that in the example above, you would ease testing and increase performance
+by simply moving <tt>"bar"</tt> into a helper used by both <tt>/foo</tt> and
+<tt>/bar</tt>.
 
-The incoming request object can be accessed from request level (filter, routes, error handlers) through the `request` method:
+If you want the request to be sent to the same application instance rather than
+a duplicate, use <tt>call!</tt> instead of <tt>call</tt>.
+
+Check out the Rack specification if you want to learn more about <tt>call</tt>.
+
+=== Setting Body and Status Code
+
+It is possible and recommended to set the status code and response body with the
+return value of the route block. However, in some scenarios you might want to
+set the body at an arbritary point in the execution flow. You can do so with the
++body+ helper method. If you do so, you can use that method from there on to
+access the body:
+
+  get '/foo' do
+    body "bar"
+  end
+  
+  after do
+    puts body
+  end
+
+It is also possible to pass a block to body, that will be executed by the rack
+handler (this can be used to implement streaming, see
+"Return Values").
+
+Similar to the body, you can also set the status code:
+
+  get '/foo' do
+    status 418
+    halt "I'm a tea pot!"
+  end
+
+=== Generating URLs
+
+For generating URLs you should use the +url+ helper method, for instance, in
+Haml:
+
+  %a{:href => url('/foo')} foo
+
+It takes reverse proxies and Rack routers into account, if present.
+
+This method is also aliased to +to+ (see below) for an
+example).
+
+=== Browser Redirect
+
+You can trigger a browser redirect with the +redirect+ helper method:
+
+  get '/foo' do
+    redirect to('/bar')
+  end
+
+Any additional parameters are handled like arguments passed to +halt+:
+
+  redirect to('/bar'), 303
+  redirect 'http://google.com', 'wrong place, buddy'
+
+You can also easily redirect back to the page the user came from with
+<tt>redirect back</tt>:
+
+  get '/foo' do
+    "<a href='/bar'>do something</a>"
+  end
+
+  get '/bar' do
+    do_something
+    redirect back
+  end
+
+To pass arguments with a redirect, either add them to the query:
+
+  redirect to('/bar?sum=42')
+
+Or use a session:
+
+  enable :session
+  
+  get '/foo' do
+    session[:secret] = 'foo'
+    redirect to('/bar')
+  end
+  
+  get '/bar' do
+    session[:secret]
+  end
+
+=== Sending Files
+
+For sending files, you can use the <tt>send_file</tt> helper method:
+
+  get '/' do
+    send_file 'foo.png'
+  end
+
+It also take a couple of options:
+
+  send_file 'foo.png', :type => :jpg
+
+The options are:
+
+[filename]
+  file name in response, defaults to the real file name.
+
+[last_modified]
+  value for Last-Modified header, defaults to the file's mtime.
+
+[type]
+  content type to use, guessed from the file extension if missing.
+
+[disposition]
+  used for Content-Disposition, possible values: +nil+ (default),
+  <tt>:attachement</tt> and <tt>:inline</tt>
+
+[length]
+  Content-Length header, defaults to file size.
+
+If supported by the Rack handler, other means than streaming from the Ruby
+process will be used. If you use this helper method, Sinatra will automatically
+handle range requests.
+
+=== Accessing the Request Object
+
+The incoming request object can be accessed from request level (filter, routes,
+error handlers) through the <tt>request</tt> method:
 
   # app running on http://example.com/example
   get '/foo' do
@@ -676,12 +948,66 @@ The <tt>request.body</tt> is an IO or StringIO object:
     "Hello #{data['name']}!"
   end
 
+=== Looking Up Template Files
+
+The <tt>find_template</tt> helper is used to find template files for rendering:
+
+  find_template settings.views, 'foo', Tilt[:haml] do |file|
+    puts "could be #{file}"
+  end
+
+This is not really useful. But it is useful that you can actually override this
+method to hook in your own lookup mechanism. For instance, if you want to be
+able to use more than one view directory:
+
+  set :views, ['views', 'templates']
+
+  helpers do
+    def find_template(views, name, engine, &block)
+      Array(views).each { |v| super(v, name, engine, &block) }
+    end
+  end
+
+Another example would be using different directories for different engines:
+
+  set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
+
+  helpers do
+    def find_template(views, name, engine, &block)
+      _, folder = views.detect { |k,v| engine == Tilt[k] }
+      folder ||= views[:default]
+      super(folder, name, engine, &block)
+    end
+  end
+
+You can also easily wrap this up in an extension and share with others!
+
+Note that <tt>find_template</tt> does not check if the file really exists but
+rather calls the given block for all possible paths. This is not a performance
+issue, since +render+ will use +break+ as soon as a file is found. Also,
+template locations (and content) will be cached if you are not running in
+development mode. You should keep that in mind if you write a really crazy
+method.
+
 == Configuration
 
 Run once, at startup, in any environment:
 
   configure do
-    ...
+    # setting one option
+    set :option, 'value'
+    
+    # setting multiple options
+    set :a => 1, :b => 2
+    
+    # same as `set :option, true`
+    enable :option
+    
+    # same as `set :option, false`
+    disable :option
+    
+    # you can also have dynamic settings with blocks
+    set(:css_dir) { File.join(views, 'css') }
   end
 
 Run only when the environment (RACK_ENV environment variable) is set to
@@ -698,7 +1024,102 @@ Run when the environment is set to either <tt>:production</tt> or
     ...
   end
 
-== Error handling
+You can access those options via <tt>settings</tt>:
+
+  configure do
+    set :foo, 'bar'
+  end
+
+  get '/' do
+    settings.foo? # => true
+    settings.foo  # => 'bar'
+    ...
+  end
+
+=== Available Settings
+
+[absolute_redirects]  If disabled, Sinatra will allow relative redirects,
+                      however, Sinatra will no longer conform with RFC 2616
+                      (HTTP 1.1), which only allows absolute redirects.
+                      
+                      Enable if your app is running behind a reverse proxy that
+                      has not been set up properly. Note that the +url+ helper
+                      will still produce absolute URLs, unless you pass in
+                      +false+ as second parameter.
+                      
+                      Disabled per default.
+
+[add_charsets]        mime types the <tt>content_type</tt> helper will
+                      automatically add the charset info to.
+                      
+                      You should add to it rather than overriding this option:
+                      
+                        settings.add_charsets << "application/foobar"
+
+[app_file]            main application file, used to detect project root,
+                      views and public folder and inline templates
+
+[bind]                IP address to bind to (default: 0.0.0.0).
+                      Only used for built-in server.
+
+[default_encoding]    encoding to assume if unknown
+                      (defaults to <tt>"utf-8"</tt>)
+
+[dump_errors]         display errors in the log
+
+[environment]         current environment, defaults to <tt>ENV['RACK_ENV']</tt>,
+                      or <tt>"development"</tt> if not available
+
+[logging]             use the logger
+
+[lock]                Places a lock around every request, only running
+                      processing on request per Ruby process concurrently.
+                      
+                      Enabled if your app is not thread-safe.
+                      Disabled per default.
+
+[method_override]     use <tt>_method</tt> magic to allow put/delete forms in
+                      browsers that don't support it
+
+[port]                Port to listen on. Only used for built-in server.
+
+[prefixed_redirects]  Whether or not to insert <tt>request.script_name</tt> into
+                      redirects if no absolute path is given. That way
+                      <tt>redirect '/foo'</tt> would behave like
+                      <tt>redirect to('/foo')</tt>. Disabled per default.
+
+[public]              folder public files are server from
+
+[reload_templates]    whether or not to reload templates between requests.
+                      enabled in development mode and on Ruby 1.8.6 (to
+                      compensate a bug in Ruby causing a memory leak)
+
+[root]                project root folder
+
+[raise_errors]        raise exceptions (will stop application)
+
+[run]                 if enabled, Sinatra will handle starting the webserver,
+                      do not enable if using rackup or other means.
+
+[running]             is the built-in server running now?
+                      do not change this setting!
+
+[server]              server or list of servers to use for built-in server.
+                      defaults to ['thin', 'mongrel', 'webrick'], order indicates
+                      priority.
+
+[sessions]            enable cookie based sessions
+
+[show_exceptions]     show a stacktrace in the browser
+
+[static]              Whether Sinatra should handle serving static files.
+                      Disable when using a Server able to do this on its own.
+                      Disabling will boost performance.
+                      Enabled per default.
+
+[views]               views folder
+
+== Error Handling
 
 Error handlers run within the same context as routes and before filters, which
 means you get all the goodies it has to offer, like <tt>haml</tt>,
@@ -758,7 +1179,7 @@ Or a range:
 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
 running under the development environment.
 
-== Mime types
+== Mime Types
 
 When using <tt>send_file</tt> or static files you may have mime types Sinatra
 doesn't understand. Use +mime_type+ to register them by file extension:
@@ -861,13 +1282,6 @@ etc.). That's where Sinatra::Base comes into play:
     end
   end
 
-The MyApp class is an independent Rack component that can act as
-Rack middleware, a Rack application, or Rails metal. You can +use+ or
-+run+ this class from a rackup +config.ru+ file; or, control a server
-component shipped as a library:
-
-   MyApp.run! :host => 'localhost', :port => 9090
-
 The methods available to Sinatra::Base subclasses are exactly as those
 available via the top-level DSL. Most top-level apps can be converted to
 Sinatra::Base components with two modifications:
@@ -882,6 +1296,91 @@ Sinatra::Base components with two modifications:
 including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
 for details on available options and their behavior.
 
+=== Modular vs. Classic Style
+
+Contrary to common believes, there is nothing wrong with classic style. If it
+suits your application, you do not have to switch to a modular application.
+
+There are only two downsides compared to modulare style:
+
+* You may only have one Sinatra application per Ruby process - if you plan to
+  use more, switch to modular style.
+
+* Classic style pollutes Object with delegator methods - if you plan to ship
+  your application in a library/gem, switch to modular style.
+
+There is no reason you cannot mix modular and classic style.
+
+If switching from one style to the other, you should be aware of slight
+differences in the setting:
+
+  Setting             Classic                 Modular
+
+  app_file            file loading sinatra    nil
+  run                 $0 == app_file          false
+  logging             true                    false
+  method_override     true                    false
+  inline_templates    true                    false
+
+
+=== Serving a Modular Application
+
+There are two common options for starting a modular app, activly starting with
+<tt>run!</tt>:
+
+  # my_app.rb
+  require 'sinatra/base'
+  
+  class MyApp < Sinatra::Base
+    # ... app code here ...
+    
+    # start the server if ruby file executed directly
+    run! if app_file == $0
+  end
+
+Start with:
+
+  ruby my_app.rb
+
+Or with a <tt>config.ru</tt>, which allows using any Rack handler:
+
+  # config.ru
+  require 'my_app'
+  run MyApp
+
+Run:
+
+  rackup -p 4567
+
+=== Using a Classic Style Application with a config.ru
+
+Write your app file:
+
+  # app.rb
+  require 'sinatra'
+  
+  get '/' do
+    'Hello world!'
+  end
+
+And a corresponding <tt>config.ru</tt>:
+
+  require 'app'
+  run Sinatra::Application
+
+=== When to use a config.ru?
+
+Good signs you probably want to use a <tt>config.ru</tt>:
+
+* You want to deploy with a different Rack handler (Passenger, Unicorn,
+  Heroku, ...).
+* You want to use more than one subclass of <tt>Sinatra::Base</tt>.
+* You want to use Sinatra only for middleware, but not as endpoint.
+
+<b>There is no need to switch to a <tt>config.ru</tt> only because you
+switched to modular style, and you don't have to use modular style for running
+with a <tt>config.ru</tt>.</b>
+
 === Using Sinatra as Middleware
 
 Not only is Sinatra able to use other Rack middleware, any Sinatra application
@@ -928,11 +1427,11 @@ available.
 Every Sinatra application corresponds to a subclass of Sinatra::Base. If you
 are using the top level DSL (<tt>require 'sinatra'</tt>), then this class is
 Sinatra::Application, otherwise it is the subclass you created explicitly. At
-class level you have methods like `get` or `before`, but you cannot access the
-`request` object or the `session`, as there only is a single application class
+class level you have methods like +get+ or +before+, but you cannot access the
++request+ object or the +session+, as there only is a single application class
 for all requests.
 
-Options created via `set` are methods at class level:
+Options created via +set+ are methods at class level:
 
     class MyApp < Sinatra::Base
       # Hey, I'm in the application scope!
@@ -948,21 +1447,21 @@ You have the application scope binding inside:
 
 * Your application class body
 * Methods defined by extensions
-* The block passed to `helpers`
-* Procs/blocks used as value for `set`
+* The block passed to +helpers+
+* Procs/blocks used as value for +set+
 
 You can reach the scope object (the class) like this:
 
 * Via the object passed to configure blocks (<tt>configure { |c| ... }</tt>)
-* `settings` from within request scope
+* +settings+ from within request scope
 
 === Request/Instance Scope
 
 For every incoming request, a new instance of your application class is
 created and all handler blocks run in that scope. From within this scope you
-can access the `request` and `session` object or call rendering methods like
-`erb` or `haml`. You can access the application scope from within the request
-scope via the `settings` helper:
+can access the +request+ and +session+ object or call rendering methods like
++erb+ or +haml+. You can access the application scope from within the request
+scope via the +settings+ helper:
 
   class MyApp < Sinatra::Base
     # Hey, I'm in the application scope!
@@ -992,19 +1491,19 @@ The delegation scope just forwards methods to the class scope. However, it
 does not behave 100% like the class scope, as you do not have the class'
 binding: Only methods explicitly marked for delegation are available and you
 do not share variables/state with the class scope (read: you have a different
-`self`). You can explicitly add method delegations by calling
++self+). You can explicitly add method delegations by calling
 <tt>Sinatra::Delegator.delegate :method_name</tt>.
 
 You have the delegate scope binding inside:
 
 * The top level binding, if you did <tt>require "sinatra"</tt>
-* An object extended with the `Sinatra::Delegator` mixin
+* An object extended with the <tt>Sinatra::Delegator</tt> mixin
 
 Have a look at the code for yourself: here's the
 {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
 being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28].
 
-== Command line
+== Command Line
 
 Sinatra applications can be run directly:
 
@@ -1020,32 +1519,67 @@ Options are:
   -x # turn on the mutex lock (default is off)
 
 == The Bleeding Edge
+If you would like to use Sinatra's latest bleeding code, feel free to run your
+application against the master branch, it should be rather stable.
+
+We also push out prerelease gems from time to time, so you can do a
+
+  gem install sinatra --pre
+
+To get some of the latest features.
+
+=== With Bundler
+If you want to run your application with the latest Sinatra, using
+{Bundler}[http://gembundler.com/] is the recommend way.
+
+First, install bundler, if you haven't:
 
-If you would like to use Sinatra's latest bleeding code, create a local
-clone and run your app with the <tt>sinatra/lib</tt> directory on the
-<tt>LOAD_PATH</tt>:
+  gem install bundler
+
+Then, in you project directory, create a +Gemfile+:
+
+  source :rubygems
+  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
+  
+  # other dependencies
+  gem 'haml'                    # for instance, if you use haml
+  gem 'activerecord', '~> 3.0'  # maybe you also need ActiveRecord 3.x
+
+Note that you will have to list all your applications dependencies in there.
+Sinatra's direct dependencies (Rack and Tilt) will however be automatically
+fetched and added by Bundler.
+
+Now you can run your app like this:
+
+  bundle exec ruby myapp.rb
+
+=== Roll Your Own
+Create a local clone and run your app with the <tt>sinatra/lib</tt> directory
+on the <tt>LOAD_PATH</tt>:
 
   cd myapp
   git clone git://github.com/sinatra/sinatra.git
   ruby -Isinatra/lib myapp.rb
 
-Alternatively, you can add the <tt>sinatra/lib</tt> directory to the
-<tt>LOAD_PATH</tt> in your application:
+To update the Sinatra sources in the future:
+
+  cd myapp/sinatra
+  git pull
 
-  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
-  require 'rubygems'
-  require 'sinatra'
+=== Install Globally
 
-  get '/about' do
-    "I'm running version " + Sinatra::VERSION
-  end
+You can build the gem on your own:
 
-To update the Sinatra sources in the future:
+  git clone git://github.com/sinatra/sinatra.git
+  cd sinatra
+  rake sinatra.gemspec
+  rake install
 
-  cd myproject/sinatra
-  git pull
+If you install gems as root, the last step should be
+
+  sudo rake install
 
-== More
+== Further Reading
 
 * {Project Website}[http://www.sinatrarb.com/] - Additional documentation,
   news, and links to other resources.