sinatra 2.0.0.beta2 → 2.0.0.rc1

data/README.es.md

@@ -1654,7 +1654,7 @@ get '/foo' do
   request.ip                  # dirección IP del cliente
   request.secure?             # false (sería true sobre ssl)
   request.forwarded?          # true (si se está corriendo atrás de un proxy reverso)
-  requuest.env                # hash de entorno directamente entregado por Rack
+  request.env                 # hash de entorno directamente entregado por Rack
 end
 ```
 

data/README.hu.md

@@ -649,6 +649,40 @@ Az alábbi kapcsolókat ismeri fel a rendszer:
   -s # a rack szerver/handler beállítása (alapértelmezetten ez a thin)
   -x # a mutex lock bekapcsolása (alapértelmezetten ki van kapcsolva)
 
+## Több szálon futtatás
+
+_Parafrázis [Konstantin StackOverflow válasza][so-answer] alapján_
+
+A Sinatra nem szabja meg az konkurenciakezelés módját, hanem az alatta működő
+Rack kezelőre (szerverre) hagyja ezt a feladatot, ami például a Thin, a Puma,
+vagy a WEBrick. A Sinatra önmagában szálbiztos, tehát semmilyen probléma sem
+adódik, ha a Rack kezelő többszálú konkurenciamodellt használ. Ezek szerint
+szerverindításkor meg kell adni a Rack szervernek megfelelő indítási módot.
+A következő példa egy többszálú Thin szerver indítását mutatja be.
+
+```ruby
+# app.rb
+
+require 'sinatra/base'
+
+class App < Sinatra::Base
+  get '/' do
+    "Hello, World"
+  end
+end
+
+App.run!
+
+```
+
+A szerverindítás parancsa a következő lenne:
+
+``` shell
+thin --threaded start
+```
+
+[so-answer]: http://stackoverflow.com/a/6282999/1725341
+
 ## Fejlesztői változat
 
 Ha a Sinatra legfrissebb, fejlesztői változatát szeretnéd használni,

data/README.ja.md

@@ -1,7 +1,7 @@
 # Sinatra
 
 *注）
-本文書は英語から翻訳したものであり、その内容が最新でない場合もあります。最新の情報はオリジナルの英語版を参照して下さい。*
+本文書は英語から翻訳したものであり、その内容が最新でない場合もあります。最新の情報はオリジナルの英語版を参照してください。*
 
 Sinatraは最小の労力でRubyによるWebアプリケーションを手早く作るための[DSL](https://ja.wikipedia.org/wiki/メインページドメイン固有言語)です。
 
@@ -70,9 +70,11 @@ ThinがあればSinatraはこれを利用するので、`gem install thin`する
         * [名前付きテンプレート(Named Templates)](#名前付きテンプレートnamed-templates)
         * [ファイル拡張子の関連付け](#ファイル拡張子の関連付け)
         * [オリジナルテンプレートエンジンの追加](#オリジナルテンプレートエンジンの追加)
+        * [カスタムロジックを使用したテンプレートの探索](#カスタムロジックを使用したテンプレートの探索)
     * [フィルタ(Filters)](#フィルタfilters)
     * [ヘルパー(Helpers)](#ヘルパーhelpers)
         * [セッションの使用](#セッションの使用)
+        * [セッションミドルウェアの選択](#セッションミドルウェアの選択)
         * [停止(Halting)](#停止halting)
         * [パッシング(Passing)](#パッシングpassing)
         * [別ルーティングの誘発](#別ルーティングの誘発)
@@ -168,7 +170,6 @@ end
     end
 ```
 
-
 ルーティングのパターンは名前付きパラメータを含むことができ、
 `params`ハッシュで取得できます。
 
@@ -379,7 +380,6 @@ get %r{(?!/index)} do
 end
 ```
 
-
 ## 静的ファイル(Static Files)
 
 静的ファイルは`./public`ディレクトリから配信されます。
@@ -427,7 +427,6 @@ end
 
 Sinatraが理解できないオプションは、テンプレートエンジンに渡されることになります。
 
-
 ```ruby
 get '/' do
   haml :index, :format => :html5
@@ -457,7 +456,7 @@ end
 
   <dt>default_encoding</dt>
   <dd>
-    文字エンコーディング（不確かな場合に使用される）。デフォルトは、<tt>settings.default_encoding</tt>。
+    文字エンコーディングが確実でない場合に指定。デフォルトは、<tt>settings.default_encoding</tt>。
   </dd>
 
   <dt>views</dt>
@@ -499,9 +498,9 @@ end
 set :views, settings.root + '/templates'
 ```
 
-テンプレートはシンボルを使用して参照させることを覚えておいて下さい。
-サブディレクトリでもこの場合は`:'subdir/template'`のようにします。
-レンダリングメソッドは文字列が渡されると、それをそのまま文字列として出力するので、シンボルを使ってください。
+テンプレートの参照は、テンプレートがサブディレクトリ内にある場合でも常にシンボルで指定することを覚えておいてください。
+（これは`:'subdir/template'`または`'subdir/template'.to_sym`のように指定することを意味します。）
+レンダリングメソッドにシンボルではなく文字列を渡してしまうと、そのまま文字列として出力してしまいます。
 
 ### リテラルテンプレート(Literal Templates)
 
@@ -511,13 +510,19 @@ get '/' do
 end
 ```
 
-これはそのテンプレート文字列をレンダリングします。
+これはテンプレート文字列をレンダリングしています。
+テンプレート文字列に関連するファイルパスや行数を`:path`や`:line`オプションで指定することで、バックトレースを明確にすることができます。
+
+```ruby
+get '/' do
+  haml '%div.title Hello World', :path => 'examples/file.haml', :line => 3
+end
+```
 
 ### 利用可能なテンプレート言語
 
 いくつかの言語には複数の実装があります。使用する（そしてスレッドセーフにする）実装を指定するには、それを最初にrequireしてください。
 
-
 ```ruby
 require 'rdiscount' # または require 'bluecloth'
 get('/') { markdown :index }
@@ -540,7 +545,6 @@ get('/') { markdown :index }
   </tr>
 </table>
 
-
 #### Erb テンプレート
 
 <table>
@@ -601,7 +605,6 @@ get('/') { markdown :index }
 
 インラインテンプレート用にブロックを取ることもできます（例を参照）。
 
-
 #### Sass テンプレート
 
 <table>
@@ -619,7 +622,6 @@ get('/') { markdown :index }
   </tr>
 </table>
 
-
 #### Scss テンプレート
 
 <table>
@@ -713,7 +715,6 @@ erb :overview, :locals => { :text => markdown(:introduction) }
 
 MarkdownからはRubyを呼ぶことができないので、Markdownで書かれたレイアウトを使うことはできません。しかしながら、`:layout_engine`オプションを渡すことでテンプレートのものとは異なるレンダリングエンジンをレイアウトのために使うことができます。
 
-
 #### Textile テンプレート
 
 <table>
@@ -773,7 +774,6 @@ erb :overview, :locals => { :text => rdoc(:introduction) }
 
 ノート: 他のテンプレート内で`rdoc`メソッドを呼び出せます。
 
-
 ```ruby
 %h1 Hello From Haml!
 %p= rdoc(:greetings)
@@ -819,7 +819,6 @@ AsciiDocテンプレートからRubyのメソッドを直接呼び出すこと
 
 RadiusテンプレートからRubyのメソッドを直接呼び出すことができないため、ほぼ全ての場合にlocalsを指定する必要があるでしょう。
 
-
 #### Markaby テンプレート
 
 <table>
@@ -1015,7 +1014,6 @@ end
   </tr>
 </table>
 
-
 テンプレートのソースはRubyの文字列として評価され、その結果のJSON変数は`#to_json`を使って変換されます。
 
 ```ruby
@@ -1068,7 +1066,7 @@ get '/:id' do
 end
 ```
 
-このやり方は他のテンプレート内で部分テンプレートとして表示する時に典型的に使用されます。
+これは他のテンプレート内で部分テンプレートとして表示する典型的な手法です。
 
 ### `yield`を伴うテンプレートとネストしたレイアウト
 
@@ -1105,7 +1103,6 @@ end
 `liquid`, `slim `, `wlang`。
 また汎用の`render`メソッドもブロックを取れます。
 
-
 ### インラインテンプレート(Inline Templates)
 
 テンプレートはソースファイルの最後で定義することもできます。
@@ -1147,7 +1144,7 @@ get '/' do
 end
 ```
 
-「layout」というテンプレートが存在する場合、そのテンプレートファイルは他のテンプレートがレンダリングされる度に使用されます。`:layout => false`で個別に、または`set :haml, :layout => false`でデフォルトとして、レイアウトを無効にすることができます。
+「layout」という名前のテンプレートが存在する場合は、そのテンプレートファイルは他のテンプレートがレンダリングされる度に使用されます。`:layout => false`で個別に、または`set :haml, :layout => false`でデフォルトとして、レイアウトを無効にすることができます。
 
 ```ruby
 get '/' do
@@ -1181,6 +1178,22 @@ end
 
 これは、`./views/index.myat`をレンダリングします。Tiltについての詳細は、https://github.com/rtomayko/tilt を参照してください。
 
+### カスタムロジックを使用したテンプレートの探索
+
+オリジナルテンプレートの検索メカニズムを実装するためには、`#find_template`メソッドを実装します。
+
+```ruby
+configure do
+  set :views [ './views/a', './views/b' ]
+end
+
+def find_template(views, name, engine, &block)
+  Array(views).each do |v|
+    super(v, name, engine, &block)
+  end
+end
+```
+
 ## フィルタ(Filters)
 
 beforeフィルタは、リクエストのルーティングと同じコンテキストで各リクエストの前に評価され、それによってリクエストとレスポンスを変更可能にします。フィルタ内でセットされたインスタンス変数はルーティングとテンプレートからアクセスすることができます。
@@ -1263,10 +1276,9 @@ helpers FooUtils, BarUtils
 
 その効果は、アプリケーションクラスにモジュールをインクルードするのと同じです。
 
-
 ### セッションの使用
 
-セッションはリクエスト間での状態維持のために使用されます。その起動により、ユーザセッションごとに一つのセッションハッシュが与えられます。
+セッションはリクエスト間での状態維持のために使用されます。セッションを有効化すると、ユーザセッションごとに一つのセッションハッシュが与えられます。
 
 ```ruby
 enable :sessions
@@ -1312,6 +1324,38 @@ foo.comのサブドメイン上のアプリ間でセッションを共有化し
 set :sessions, :domain => '.foo.com'
 ```
 
+#### セッションミドルウェアの選択
+
+`enable :sessions`とすることで、クッキー内の全てのデータを実際に保存してしまうことに注意してください。
+これは、あなたが望む挙動ではない（例えば、大量のデータを保存することでトラフィックが増大してしまう）かもしれません。
+あなたは、次のいずれかの方法によって、任意のRackセッションミドルウェアを使用することができます。
+
+```ruby
+enable :sessions
+set :session_store, Rack::Session::Pool
+```
+
+オプションのハッシュを設定するためには、次のようにします。
+
+```ruby
+set :sessions, :expire_after => 2592000
+set :session_store, Rack::Session::Pool
+```
+
+他の方法は`enable :sessions`を**しない**で、他のミドルウェアの選択と同様にあなた自身でミドルウェアを選択することです。
+
+この方法を選択する場合は、セッションベースの保護は**デフォルトで有効にならない**ということに注意することが重要です。
+
+これを満たすためのRackミドルウェアを追加することが必要になります。
+
+```ruby
+use Rack::Session::Pool, :expire_after => 2592000
+use Rack::Protection::RemoteToken
+use Rack::Protection::SessionHijacking
+```
+
+より詳しい情報は、「攻撃防御に対する設定」の項を参照してください。
+
 ### 停止(Halting)
 
 フィルタまたはルーティング内で直ちにリクエストを止める場合
@@ -1369,7 +1413,8 @@ end
 
 ### 別ルーティングの誘発
 
-`pass`を使ってルーティングを飛ばすのではなく、他のルーティングを呼んだ結果を得たいというときがあります。これを実現するには`call`を使えばいいです。
+`pass`を使ってルーティングを飛ばすのではなく、他のルーティングを呼んだ結果を得たいという場合があります。
+これは`call`を使用することで実現できます。
 
 ```ruby
 get '/foo' do
@@ -1382,12 +1427,11 @@ get '/bar' do
 end
 ```
 
-ノート: 先の例において、テストを楽にしパフォーマンスを改善するには、`"bar"`を単にヘルパーに移し、`/foo`および`/bar`から使えるようにするのがいいです。
+ノート: 先の例において、テストを楽にしパフォーマンスを改善するには、`"bar"`を単にヘルパーに移し、`/foo`および`/bar`から使えるようにしたほうが良いです。
 
 リクエストが、その複製物でない同じアプリケーションのインスタンスに送られるようにしたいときは、`call`に代えて`call!`を使ってください。
 
-`call`についての詳細はRackの仕様書を参照してください。
-
+`call`についての詳細はRackの仕様を参照してください。
 
 ### ボディ、ステータスコードおよびヘッダの設定
 
@@ -1476,7 +1520,6 @@ end
 
 リクエストスコープにおいて、`logger`ヘルパーは`Logger`インスタンスを作り出します。
 
-
 ```ruby
 get '/' do
   logger.info "loading data"
@@ -1500,7 +1543,7 @@ end
 
 ### MIMEタイプ(Mime Types)
 
-`send_file`か静的ファイルを使う時、SinatraがMIMEタイプを理解できない場合があります。その時は `mime_type` を使ってファイル拡張子毎に登録して下さい。
+`send_file`か静的ファイルを使う時、SinatraがMIMEタイプを理解できない場合があります。その時は `mime_type` を使ってファイル拡張子毎に登録してください。
 
 ```ruby
 configure do
@@ -1561,7 +1604,6 @@ end
 
 redirectに引数を渡すには、それをクエリーに追加するか、
 
-
 ```ruby
 redirect to('/bar?sum=42')
 ```
@@ -1629,7 +1671,6 @@ etag @article.sha1, :weak
 
 これらのヘルパーは、キャッシングをしてくれませんが、必要な情報をキャッシュに与えてくれます。もし手早いリバースプロキシキャッシングの解決策をお探しなら、 [rack-cache](https://github.com/rtomayko/rack-cache)を試してください。
 
-
 ```ruby
 require "rack/cache"
 require "sinatra"
@@ -1706,7 +1747,6 @@ send_file 'foo.png', :type => :jpg
     </dd>
 </dl>
 
-
 ### リクエストオブジェクトへのアクセス
 
 受信するリクエストオブジェクトは、`request`メソッドを通じてリクエストレベル(フィルタ、ルーティング、エラーハンドラ)からアクセスすることができます。
@@ -1911,18 +1951,19 @@ end
 
 ### 攻撃防御に対する設定
 
-Sinatraは、[Rack::Protection](https://github.com/sinatra/rack-protection#readme)を使って、アプリケーションを多発する日和見的攻撃から守っています。この挙動は簡単に無効化できます(これはアプリケーションを大量の脆弱性攻撃に晒すことになります)。
+Sinatraは[Rack::Protection](https://github.com/sinatra/rack-protection#readme)を使用することで、アプリケーションを一般的な日和見的攻撃から守っています。これは簡単に無効化できます（が、アプリケーションに大量の一般的な脆弱性を埋め込むことになってしまいます）。
 
 ```ruby
 disable :protection
 ```
 
-単一の防御層を外すためには、`protection`をオプションハッシュにセットします。
+ある1つの防御を無効にするには、`protection`にハッシュでオプションを指定します。
 
 ```ruby
 set :protection, :except => :path_traversal
 ```
-また配列を渡して、複数の防御を無効にすることもできます。
+
+配列を渡すことで、複数の防御を無効にすることもできます。
 
 ```ruby
 set :protection, :except => [:path_traversal, :session_hijacking]
@@ -2081,7 +2122,7 @@ set :protection, :session => true
 
 ## 環境設定(Environments)
 
-３種類の既定環境、`"development"`、`"production"`および`"test"`があります。環境は、`APP_ENV`環境変数を通して設定できます。デフォルト値は、`"development"`です。`"development"`環境において、すべてのテンプレートは、各リクエスト間で再ロードされ、そして、特別の`not_found`および`error`ハンドラがブラウザにスタックトレースを表示します。`"production"`および`"test"`環境においては、テンプレートはデフォルトでキャッシュされます。
+3種類の既定環境、`"development"`、`"production"`および`"test"`があります。環境は、`APP_ENV`環境変数を通して設定できます。デフォルト値は、`"development"`です。`"development"`環境において、すべてのテンプレートは、各リクエスト間で再ロードされ、そして、特別の`not_found`および`error`ハンドラがブラウザにスタックトレースを表示します。`"production"`および`"test"`環境においては、テンプレートはデフォルトでキャッシュされます。
 
 異なる環境を走らせるには、`APP_ENV`環境変数を設定します。
 
@@ -2117,7 +2158,14 @@ end
 
 ### エラー(Error)
 
-`error`ハンドラはルーティングブロックまたはフィルタ内で例外が発生したときはいつでも発動します。例外オブジェクトはRack変数`sinatra.error`から取得できます。
+`error`ハンドラはルーティングブロックまたはフィルタ内で例外が発生したときはいつでも発動します。
+しかし、環境設定がdevelopmentの場合は`:after_handler`を設定している場合のみ発動するようになります。
+
+```ruby
+set :show_exceptions, :after_handler
+```
+
+例外オブジェクトはRack変数`sinatra.error`から取得できます。
 
 ```ruby
 error do
@@ -2169,7 +2217,6 @@ end
 
 Sinatraを開発環境の下で実行している場合は、特別な`not_found`および`error`ハンドラが導入され、これは親切なスタックトレースと追加のデバッギング情報をブラウザに表示します。
 
-
 ## Rackミドルウェア(Rack Middleware)
 
 SinatraはRuby製Webフレームワークのミニマルな標準的インタフェースである[Rack](http://rack.github.io/)上に構築されています。アプリケーションデベロッパーにとってRackにおける最も興味深い機能は、「ミドルウェア(middleware)」をサポートしていることであり、これは、サーバとアプリケーションとの間に置かれ、HTTPリクエスト/レスポンスを監視および/または操作することで、各種の汎用的機能を提供するコンポーネントです。
@@ -2256,13 +2303,13 @@ class MyApp < Sinatra::Base
 end
 ```
 
-`Sinatra::Base`のサブクラスで利用できるメソッドは、トップレベルDSLで利用できるものと全く同じです。ほとんどのトップレベルで記述されたアプリは、以下の２点を修正することで`Sinatra::Base`コンポーネントに変えることができます。
+`Sinatra::Base`のサブクラスで利用できるメソッドは、トップレベルDSLで利用できるものと全く同じです。ほとんどのトップレベルで記述されたアプリは、以下の2点を修正することで`Sinatra::Base`コンポーネントに変えることができます。
 
 * `sinatra`の代わりに`sinatra/base`を読み込む
   (そうしない場合、SinatraのDSLメソッドの全てがmainの名前空間にインポートされます)
 * ルーティング、エラーハンドラ、フィルタ、オプションを`Sinatra::Base`のサブクラスに書く
 
-`Sinatra::Base`はまっさらです。ビルトインサーバを含む、ほとんどのオプションがデフォルトで無効になっています。利用可能なオプションとその挙動の詳細については[Configuring Settings](http://www.sinatrarb.com/configuration.html)(英語)をご覧下さい。
+`Sinatra::Base`はまっさらです。ビルトインサーバを含む、ほとんどのオプションがデフォルトで無効になっています。利用可能なオプションとその挙動の詳細については[Configuring Settings](http://www.sinatrarb.com/configuration.html)(英語)をご覧ください。
 
 もしもクラシックスタイルと同じような挙動のアプリケーションをトップレベルで定義させる必要があれば、`Sinatra::Application`をサブクラス化させてください。
 

data/README.md

@@ -1,6 +1,6 @@
 # Sinatra
 
-[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.png)](http://travis-ci.org/sinatra/sinatra)
+[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](http://travis-ci.org/sinatra/sinatra)
 
 Sinatra is a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for
 quickly creating web applications in Ruby with minimal effort:
@@ -75,7 +75,9 @@ pick up if available.
     * [Filters](#filters)
     * [Helpers](#helpers)
         * [Using Sessions](#using-sessions)
-        	* [Choosing Your Own Session Middleware](#choosing-your-own-session-middleware)
+          * [Session Secret Security](#session-secret-security)
+          * [Session Config](#session-config)
+          * [Choosing Your Own Session Middleware](#choosing-your-own-session-middleware)
         * [Halting](#halting)
         * [Passing](#passing)
         * [Triggering Another Route](#triggering-another-route)
@@ -116,8 +118,6 @@ pick up if available.
     * [Requirement](#requirement)
     * [The Bleeding Edge](#the-bleeding-edge)
         * [With Bundler](#with-bundler)
-        * [Roll Your Own](#roll-your-own)
-        * [Install Globally](#install-globally)
     * [Versioning](#versioning)
     * [Further Reading](#further-reading)
 
@@ -166,9 +166,9 @@ matches the request is invoked.
 Routes with trailing slashes are different from the ones without:
 
 ```ruby
-    get '/foo' do
-      # Does not match "GET /foo/"
-    end
+get '/foo' do
+  # Does not match "GET /foo/"
+end
 ```
 
 Route patterns may include named parameters, accessible via the
@@ -252,8 +252,23 @@ get '/posts' do
 end
 ```
 
-By the way, unless you disable the path traversal attack protection (see below),
-the request path might be modified before matching against your routes.
+By the way, unless you disable the path traversal attack protection (see
+below), the request path might be modified before matching against your
+routes.
+
+You may customize the Mustermann options used for a given route by passing in a
+`:mustermann_opts` hash:
+
+```ruby
+get '\A/posts\z', :mustermann_opts => { :type => :regexp, :check_anchors => false } do
+  # matches /posts exactly, with explicit anchoring
+  "If you match an anchored pattern clap your hands!"
+end
+```
+
+It looks like a [condition](#conditions), but it isn't one! These options will
+be merged into the global `:mustermann_opts` hash described
+[below](#available-settings).
 
 ## Conditions
 
@@ -322,10 +337,10 @@ end
 
 ## 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.
-Most commonly, this is a string, as in the above examples. But other values are
-also accepted.
+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. Most commonly, this is a string, as in the above examples.
+But other values are also accepted.
 
 You can return any object that would either be a valid Rack response, Rack
 body object or HTTP status code:
@@ -350,14 +365,14 @@ end
 get('/') { Stream.new }
 ```
 
-You can also use the `stream` helper method (described below) to reduce boiler
-plate and embed the streaming logic in the route.
+You can also use the `stream` helper method (described below) to reduce
+boiler plate and embed the streaming logic in the route.
 
 ## Custom Route Matchers
 
-As shown above, Sinatra ships with built-in support for using String patterns
-and regular expressions as route matches. However, it does not stop there. You
-can easily define your own matchers:
+As shown above, Sinatra ships with built-in support for using String
+patterns and regular expressions as route matches. However, it does not
+stop there. You can easily define your own matchers:
 
 ```ruby
 class AllButPattern
@@ -505,15 +520,17 @@ Available Options:
 
   <dt>scope</dt>
   <dd>
-    Scope to render template under. Defaults to the application instance. If you
-    change this, instance variables and helper methods will not be available.
+    Scope to render template under. Defaults to the application
+    instance. If you change this, instance variables and helper methods
+    will not be available.
   </dd>
 
   <dt>layout_engine</dt>
   <dd>
-    Template engine to use for rendering the layout. Useful for languages that
-    do not support layouts otherwise. Defaults to the engine used for the
-    template. Example: <tt>set :rdoc, :layout_engine => :erb</tt>
+    Template engine to use for rendering the layout. Useful for
+    languages that do not support layouts otherwise. Defaults to the
+    engine used for the template. Example: <tt>set :rdoc, :layout_engine
+    => :erb</tt>
   </dd>
 
   <dt>layout_options</dt>
@@ -523,19 +540,19 @@ Available Options:
   </dd>
 </dl>
 
-Templates are assumed to be located directly under the `./views` directory. To
-use a different views directory:
+Templates are assumed to be located directly under the `./views`
+directory. To use a different views directory:
 
 ```ruby
 set :views, settings.root + '/templates'
 ```
 
 
-One important thing to remember is that you always have to reference templates
-with symbols, even if they're in a subdirectory (in this case, use:
-`:'subdir/template'` or `'subdir/template'.to_sym`). You must use a symbol
-because otherwise rendering methods will render any strings passed to them
-directly.
+One important thing to remember is that you always have to reference
+templates with symbols, even if they're in a subdirectory (in this case,
+use: `:'subdir/template'` or `'subdir/template'.to_sym`). You must use a
+symbol because otherwise rendering methods will render any strings
+passed to them directly.
 
 ### Literal Templates
 
@@ -545,9 +562,9 @@ get '/' do
 end
 ```
 
-Renders the template string.
-You can optionally specify `:path` and `:line` for a clearer backtrace if there is
-a filesystem path or line associated with that string:
+Renders the template string. You can optionally specify `:path` and
+`:line` for a clearer backtrace if there is a filesystem path or line
+associated with that string:
 
 ```ruby
 get '/' do
@@ -745,7 +762,8 @@ 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:
 
 ```ruby
 %h1 Hello From Haml!
@@ -773,8 +791,9 @@ template than for the layout by passing the `:layout_engine` option.
   </tr>
 </table>
 
-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:
 
 ```ruby
 erb :overview, :locals => { :text => textile(:introduction) }
@@ -863,8 +882,8 @@ almost always want to pass locals to it.
   </tr>
 </table>
 
-Since you cannot call Ruby methods directly from a Radius template, you almost
-always want to pass locals to it.
+Since you cannot call Ruby methods directly from a Radius template, you
+almost always want to pass locals to it.
 
 #### Markaby Templates
 
@@ -971,15 +990,16 @@ template than for the layout by passing the `:layout_engine` option.
   </tr>
 </table>
 
-It is not possible to call methods from MediaWiki markup, 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 MediaWiki markup, nor to pass
+locals to it. You therefore will usually use it in combination with
+another rendering engine:
 
 ```ruby
 erb :overview, :locals => { :text => mediawiki(:introduction) }
 ```
 
-Note that you may also call the `mediawiki` method from within other templates:
+Note that you may also call the `mediawiki` method from within other
+templates:
 
 ```ruby
 %h1 Hello From Haml!
@@ -1109,8 +1129,9 @@ present(resource);
   </tr>
 </table>
 
-Since calling ruby methods is not idiomatic in WLang, you almost always want to
-pass locals to it. Layouts written in WLang and `yield` are supported, though.
+Since calling ruby methods is not idiomatic in WLang, you almost always
+want to pass locals to it. Layouts written in WLang and `yield` are
+supported, though.
 
 ### Accessing Variables in Templates
 
@@ -1150,7 +1171,8 @@ end
 
 This code is mostly equivalent to `erb :index, :layout => :post`.
 
-Passing blocks to rendering methods is most useful for creating nested layouts:
+Passing blocks to rendering methods is most useful for creating nested
+layouts:
 
 ```ruby
 erb :main_layout, :layout => false do
@@ -1273,8 +1295,8 @@ end
 
 ## Filters
 
-Before filters are evaluated before each request within the same
-context as the routes will be and can modify the request and response. Instance
+Before filters are evaluated before each request within the same context
+as the routes will be and can modify the request and response. Instance
 variables set in filters are accessible by routes and templates:
 
 ```ruby
@@ -1289,9 +1311,10 @@ get '/foo/*' do
 end
 ```
 
-After filters are evaluated after each request within the same context as the
-routes will be and can also modify the request and response. Instance variables
-set in before filters and routes are accessible by after filters:
+After filters are evaluated after each request within the same context
+as the routes will be and can also modify the request and response.
+Instance variables set in before filters and routes are accessible by
+after filters:
 
 ```ruby
 after do
@@ -1299,9 +1322,9 @@ after do
 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.
+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 take a pattern, causing them to be evaluated only if the
 request path matches that pattern:
@@ -1378,17 +1401,83 @@ get '/:value' do
 end
 ```
 
+#### Session Secret Security
+
 To improve security, the session data in the cookie is signed with a session
-secret. A random secret is generated for you by Sinatra. However, since this
-secret will change with every start of your application, you might want to
-set the secret yourself, so all your application instances share it:
+secret using `HMAC-SHA1`. This session secret should optimally be a
+cryptographically secure random value of an appropriate length which for
+`HMAC-SHA1` is greater than or equal to 64 bytes (512 bits, 128 hex
+characters). You would be advised not to use a secret that is less than 32
+bytes of randomness (256 bits, 64 hex characters). It is therefore **very
+important** that you don't just make the secret up, but instead use a secure
+random number generator to create it. Humans are extremely bad at generating
+random values.
+
+By default, a 32 byte secure random session secret is generated for you by
+Sinatra, but it will change with every restart of your application. If you
+have multiple instances of your application, and you let Sinatra generate the
+key, each instance would then have a different session key which is probably
+not what you want.
+
+For better security and usability it's
+[recommended](https://12factor.net/config) that you generate a secure random
+secret and store it in an environment variable on each host running your
+application so that all of your application instances will share the same
+secret. You should periodically rotate this session secret to a new value.
+Here are some examples of how you might create a 64 byte secret and set it:
+
+**Session Secret Generation**
+
+```text
+$ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
+99ae8af...snip...ec0f262ac
+```
+
+**Session Secret Generation (Bonus Points)**
+
+Use the [sysrandom gem](https://github.com/cryptosphere/sysrandom) to prefer
+use of system RNG facilities to generate random values instead of
+userspace `OpenSSL` which MRI Ruby currently defaults to:
+
+```text
+$ gem install sysrandom
+Building native extensions.  This could take a while...
+Successfully installed sysrandom-1.x
+1 gem installed
+
+$ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)"
+99ae8af...snip...ec0f262ac
+```
+
+**Session Secret Environment Variable**
+
+Set a `SESSION_SECRET` environment variable for Sinatra to the value you
+generated. Make this value persistent across reboots of your host. Since the
+method for doing this will vary across systems this is for illustrative
+purposes only:
+
+```bash
+# echo "export SESSION_SECRET=99ae8af...snip...ec0f262ac" >> ~/.bashrc
+```
+
+**Session Secret App Config**
+
+Setup your app config to fail-safe to a secure random secret
+if the `SESSION_SECRET` environment variable is not available.
+
+For bonus points use the [sysrandom
+gem](https://github.com/cryptosphere/sysrandom) here as well:
 
 ```ruby
-set :session_secret, 'super secret'
+require 'securerandom'
+# -or- require 'sysrandom/securerandom'
+set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }
 ```
 
-If you want to configure it further, you may also store a hash with options in
-the `sessions` setting:
+#### Session Config
+
+If you want to configure it further, you may also store a hash with options
+in the `sessions` setting:
 
 ```ruby
 set :sessions, :domain => 'foo.com'
@@ -1405,7 +1494,7 @@ set :sessions, :domain => '.foo.com'
 
 Note that `enable :sessions` actually stores all data in a cookie. This
 might not always be what you want (storing lots of data will increase your
-traffic, for instance). You can use any Rack session middleware: in order to
+traffic, for instance). You can use any Rack session middleware in order to
 do so, one of the following methods can be used:
 
 ```ruby
@@ -1420,10 +1509,11 @@ set :sessions, :expire_after => 2592000
 set :session_store, Rack::Session::Pool
 ```
 
-Another option is to **not** call `enable :sessions`, but instead pull in your
-middleware of choice as you would any other middleware.
+Another option is to **not** call `enable :sessions`, but instead pull in
+your middleware of choice as you would any other middleware.
 
-It is important to note that when using this method, session based protection **will not be enabled by default**.
+It is important to note that when using this method, session based
+protection **will not be enabled by default**.
 
 The Rack middleware to do that will also need to be added:
 
@@ -1493,8 +1583,8 @@ matching route. If no matching route is found, a 404 is returned.
 
 ### 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:
+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:
 
 ```ruby
 get '/foo' do
@@ -1507,21 +1597,22 @@ get '/bar' do
 end
 ```
 
-Note that in the example above, you would ease testing and increase performance
-by simply moving `"bar"` into a helper used by both `/foo` and `/bar`.
+Note that in the example above, you would ease testing and increase
+performance by simply moving `"bar"` into a helper used by both `/foo` and
+`/bar`.
 
-If you want the request to be sent to the same application instance rather than
-a duplicate, use `call!` instead of `call`.
+If you want the request to be sent to the same application instance rather
+than a duplicate, use `call!` instead of `call`.
 
 Check out the Rack specification if you want to learn more about `call`.
 
 ### Setting Body, Status Code and Headers
 
-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 arbitrary 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:
+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 arbitrary 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:
 
 ```ruby
 get '/foo' do
@@ -1572,15 +1663,15 @@ end
 
 This allows you to implement streaming APIs,
 [Server Sent Events](https://w3c.github.io/eventsource/), and can be used as
-the basis for [WebSockets](https://en.wikipedia.org/wiki/WebSocket). It can also be
-used to increase throughput if some but not all content depends on a slow
-resource.
+the basis for [WebSockets](https://en.wikipedia.org/wiki/WebSocket). It can
+also be used to increase throughput if some but not all content depends on a
+slow resource.
 
-Note that the streaming behavior, especially the number of concurrent requests,
-highly depends on the web server used to serve the application. Some servers
-might not even support streaming at all. If the server does not support
-streaming, the body will be sent all at once after the block passed to `stream`
-finishes executing. Streaming does not work at all with Shotgun.
+Note that the streaming behavior, especially the number of concurrent
+requests, highly depends on the web server used to serve the application.
+Some servers might not even support streaming at all. If the server does not
+support streaming, the body will be sent all at once after the block passed
+to `stream` finishes executing. Streaming does not work at all with Shotgun.
 
 If the optional parameter is set to `keep_open`, it will not call `close` on
 the stream object, allowing you to close it at any later point in the
@@ -1616,9 +1707,9 @@ post '/:message' do
 end
 ```
 
-It's also possible for the client to close the connection when trying to write
-to the socket. Because of this, it's recommended to check `out.closed?` before
-trying to write.
+It's also possible for the client to close the connection when trying to
+write to the socket. Because of this, it's recommended to check
+`out.closed?` before trying to write.
 
 ### Logging
 
@@ -1635,8 +1726,8 @@ This logger will automatically take your Rack handler's logging settings into
 account. If logging is disabled, this method will return a dummy object, so
 you do not have to worry about it in your routes and filters.
 
-Note that logging is only enabled for `Sinatra::Application` by default, so if
-you inherit from `Sinatra::Base`, you probably want to enable it yourself:
+Note that logging is only enabled for `Sinatra::Application` by default, so
+if you inherit from `Sinatra::Base`, you probably want to enable it yourself:
 
 ```ruby
 class MyApp < Sinatra::Base
@@ -1788,8 +1879,9 @@ etag @article.sha1, :weak
 ```
 
 These helpers will not do any caching for you, but rather feed the necessary
-information to your cache. If you are looking for a quick reverse-proxy caching
-solution, try [rack-cache](https://github.com/rtomayko/rack-cache):
+information to your cache. If you are looking for a quick
+reverse-proxy caching solution, try
+[rack-cache](https://github.com/rtomayko/rack-cache):
 
 ```ruby
 require "rack/cache"
@@ -1807,12 +1899,13 @@ end
 Use the `:static_cache_control` setting (see below) to add
 `Cache-Control` header info to static files.
 
-According to RFC 2616, your application should behave differently if the If-Match
-or If-None-Match header is set to `*`, depending on whether the resource
-requested is already in existence. Sinatra assumes resources for safe (like get)
-and idempotent (like put) requests are already in existence, whereas other
-resources (for instance post requests) are treated as new resources. You
-can change this behavior by passing in a `:new_resource` option:
+According to RFC 2616, your application should behave differently if the
+If-Match or If-None-Match header is set to `*`, depending on whether the
+resource requested is already in existence. Sinatra assumes resources for
+safe (like get) and idempotent (like put) requests are already in existence,
+whereas other resources (for instance post requests) are treated as new
+resources. You can change this behavior by passing in a `:new_resource`
+option:
 
 ```ruby
 get '/create' do
@@ -1849,8 +1942,8 @@ The options are:
 
 <dl>
   <dt>filename</dt>
-    <dd>File name to be used in the response, defaults to the real file name.</dd>
-
+    <dd>File name to be used in the response,
+    defaults to the real file name.</dd>
   <dt>last_modified</dt>
     <dd>Value for Last-Modified header, defaults to the file's mtime.</dd>
 
@@ -1869,18 +1962,17 @@ The options are:
 
   <dt>status</dt>
     <dd>
-      Status code to be sent. Useful when sending a static file as an error page.
-
-      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.
+      Status code to be sent. Useful when sending a static file as an error
+      page. 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.
     </dd>
 </dl>
 
 ### Accessing the Request Object
 
-The incoming request object can be accessed from request level (filter, routes,
-error handlers) through the `request` method:
+The incoming request object can be accessed from request level (filter,
+routes, error handlers) through the `request` method:
 
 ```ruby
 # app running on http://example.com/example
@@ -1937,8 +2029,8 @@ end
 
 ### Attachments
 
-You can use the `attachment` helper to tell the browser the response should be
-stored on disk rather than displayed in the browser:
+You can use the `attachment` helper to tell the browser the response should
+be stored on disk rather than displayed in the browser:
 
 ```ruby
 get '/' do
@@ -1958,19 +2050,20 @@ end
 
 ### Dealing with Date and Time
 
-Sinatra offers a `time_for` helper method that generates a Time object from the
-given value. It is also able to convert `DateTime`, `Date` and similar classes:
+Sinatra offers a `time_for` helper method that generates a Time object from
+the given value. It is also able to convert `DateTime`, `Date` and similar
+classes:
 
 ```ruby
 get '/' do
-  pass if Time.now > time_for('Dec 23, 2012')
+  pass if Time.now > time_for('Dec 23, 2016')
   "still time"
 end
 ```
 
-This method is used internally by `expires`, `last_modified` and akin. You can
-therefore easily extend the behavior of those methods by overriding `time_for`
-in your application:
+This method is used internally by `expires`, `last_modified` and akin. You
+can therefore easily extend the behavior of those methods by overriding
+`time_for` in your application:
 
 ```ruby
 helpers do
@@ -2000,9 +2093,9 @@ find_template settings.views, 'foo', Tilt[:haml] do |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:
+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:
 
 ```ruby
 set :views, ['views', 'templates']
@@ -2031,11 +2124,11 @@ end
 You can also easily wrap this up in an extension and share with others!
 
 Note that `find_template` 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.
+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
 
@@ -2094,10 +2187,10 @@ end
 ### Configuring attack protection
 
 Sinatra is using
-[Rack::Protection](https://github.com/sinatra/rack-protection#readme) to defend
-your application against common, opportunistic attacks. You can easily disable
-this behavior (which will open up your application to tons of common
-vulnerabilities):
+[Rack::Protection](https://github.com/sinatra/rack-protection#readme) to
+defend your application against common, opportunistic attacks. You can
+easily disable this behavior (which will open up your application to tons
+of common vulnerabilities):
 
 ```ruby
 disable :protection
@@ -2117,7 +2210,7 @@ set :protection, :except => [:path_traversal, :session_hijacking]
 By default, Sinatra will only set up session based protection if `:sessions`
 have been enabled. See 'Using Sessions'. Sometimes you may want to set up
 sessions "outside" of the Sinatra app, such as in the config.ru or with a
-separate Rack::Builder instance. In that case you can still set up session
+separate `Rack::Builder` instance. In that case you can still set up session
 based protection by passing the `:session` option:
 
 ```ruby
@@ -2128,194 +2221,213 @@ set :protection, :session => true
 
 <dl>
   <dt>absolute_redirects</dt>
-  <dd>
-    If disabled, Sinatra will allow relative redirects, however, Sinatra will no
-    longer conform with RFC 2616 (HTTP 1.1), which only allows absolute redirects.
-  </dd>
-  <dd>
-    Enable if your app is running behind a reverse proxy that has not been set up
-    properly. Note that the <tt>url</tt> helper will still produce absolute URLs, unless you
-    pass in <tt>false</tt> as the second parameter.
-  </dd>
-  <dd>Disabled by default.</dd>
+    <dd>
+      If disabled, Sinatra will allow relative redirects, however, Sinatra
+      will no longer conform with RFC 2616 (HTTP 1.1), which only allows
+      absolute redirects.
+    </dd>
+    <dd>
+      Enable if your app is running behind a reverse proxy that has not been
+      set up properly. Note that the <tt>url</tt> helper will still produce
+      absolute URLs, unless you pass in <tt>false</tt> as the second
+      parameter.
+    </dd>
+    <dd>Disabled by default.</dd>
 
   <dt>add_charset</dt>
-  <dd>
-    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:
-    <tt>settings.add_charset << "application/foobar"</tt>
-  </dd>
+    <dd>
+      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: <tt>settings.add_charset << "application/foobar"</tt>
+    </dd>
 
   <dt>app_file</dt>
-  <dd>
-    Path to the main application file, used to detect project root, views and public
-    folder and inline templates.
-  </dd>
+    <dd>
+      Path to the main application file, used to detect project root, views
+      and public folder and inline templates.
+    </dd>
 
   <dt>bind</dt>
-  <dd>IP address to bind to (default: <tt>0.0.0.0</tt> <em>or</em>
-  <tt>localhost</tt> if your `environment` is set to development). Only used
-  for built-in server.</dd>
+    <dd>
+      IP address to bind to (default: <tt>0.0.0.0</tt> <em>or</em>
+      <tt>localhost</tt> if your `environment` is set to development). Only
+      used for built-in server.
+    </dd>
 
   <dt>default_encoding</dt>
-  <dd>Encoding to assume if unknown (defaults to <tt>"utf-8"</tt>).</dd>
+    <dd>Encoding to assume if unknown (defaults to <tt>"utf-8"</tt>).</dd>
 
   <dt>dump_errors</dt>
-  <dd>Display errors in the log.</dd>
+    <dd>Display errors in the log.</dd>
 
   <dt>environment</dt>
-  <dd>
-    Current environment. Defaults to <tt>ENV['APP_ENV']</tt>, or
-    <tt>"development"</tt> if not available.
-  </dd>
+    <dd>
+      Current environment. Defaults to <tt>ENV['APP_ENV']</tt>, or
+      <tt>"development"</tt> if not available.
+    </dd>
 
   <dt>logging</dt>
-  <dd>Use the logger.</dd>
+    <dd>Use the logger.</dd>
 
   <dt>lock</dt>
-  <dd>
-    Places a lock around every request, only running processing on request
-    per Ruby process concurrently.
-  </dd>
-  <dd>Enabled if your app is not thread-safe. Disabled by default.</dd>
+    <dd>
+      Places a lock around every request, only running processing on request
+      per Ruby process concurrently.
+    </dd>
+    <dd>Enabled if your app is not thread-safe. Disabled by default.</dd>
 
   <dt>method_override</dt>
+    <dd>
+      Use <tt>_method</tt> magic to allow put/delete forms in browsers that
+      don't support it.
+    </dd>
+
+  <dt>mustermann_opts</dt>
   <dd>
-    Use <tt>_method</tt> magic to allow put/delete forms in browsers that
-    don't support it.
+    A default hash of options to pass to Mustermann.new when compiling routing
+    paths.
   </dd>
 
   <dt>port</dt>
-  <dd>Port to listen on. Only used for built-in server.</dd>
+    <dd>Port to listen on. Only used for built-in server.</dd>
 
   <dt>prefixed_redirects</dt>
-  <dd>
-    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 by default.
-  </dd>
+    <dd>
+      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 by default.
+    </dd>
 
   <dt>protection</dt>
-  <dd>Whether or not to enable web attack protections. See protection section
-  above.</dd>
+    <dd>
+      Whether or not to enable web attack protections. See protection section
+      above.
+    </dd>
 
   <dt>public_dir</dt>
-  <dd>Alias for <tt>public_folder</tt>. See below.</dd>
+    <dd>Alias for <tt>public_folder</tt>. See below.</dd>
 
   <dt>public_folder</dt>
-  <dd>
-    Path to the folder public files are served from. Only used if static
-    file serving is enabled (see <tt>static</tt> setting below). Inferred from
-    <tt>app_file</tt> setting if not set.
-  </dd>
+    <dd>
+      Path to the folder public files are served from. Only used if static
+      file serving is enabled (see <tt>static</tt> setting below). Inferred
+      from <tt>app_file</tt> setting if not set.
+    </dd>
 
   <dt>quiet</dt>
-  <dd>
-    Disables logs generated by Sinatra's start and stop commands. `false` by default.
-  </dd>
+    <dd>
+      Disables logs generated by Sinatra's start and stop commands.
+      <tt>false</tt> by default.
+    </dd>
 
   <dt>reload_templates</dt>
-  <dd>
-    Whether or not to reload templates between requests. Enabled in development
-    mode.
-  </dd>
+    <dd>
+      Whether or not to reload templates between requests. Enabled in
+      development mode.
+    </dd>
 
   <dt>root</dt>
-  <dd>
-    Path to project root folder. Inferred from <tt>app_file</tt> setting if not
-    set.
-  </dd>
+    <dd>
+      Path to project root folder. Inferred from <tt>app_file</tt> setting
+      if not set.
+    </dd>
 
   <dt>raise_errors</dt>
-  <dd>
-    Raise exceptions (will stop application). Enabled by default when
-    <tt>environment</tt> is set to <tt>"test"</tt>, disabled otherwise.
-  </dd>
+    <dd>
+      Raise exceptions (will stop application). Enabled by default when
+      <tt>environment</tt> is set to <tt>"test"</tt>, disabled otherwise.
+    </dd>
 
   <dt>run</dt>
-  <dd>
-    If enabled, Sinatra will handle starting the web server. Do not
-    enable if using rackup or other means.
-  </dd>
+    <dd>
+      If enabled, Sinatra will handle starting the web server. Do not
+      enable if using rackup or other means.
+    </dd>
 
   <dt>running</dt>
-  <dd>Is the built-in server running now? Do not change this setting!</dd>
+    <dd>Is the built-in server running now? Do not change this setting!</dd>
 
   <dt>server</dt>
-  <dd>
-    Server or list of servers to use for built-in server. Order indicates
-    priority, default depends on Ruby implementation.
-  </dd>
+    <dd>
+      Server or list of servers to use for built-in server. Order indicates
+      priority, default depends on Ruby implementation.
+    </dd>
 
   <dt>sessions</dt>
-  <dd>
-    Enable cookie-based sessions support using <tt>Rack::Session::Cookie</tt>.
-    See 'Using Sessions' section for more information.
-  </dd>
+    <dd>
+      Enable cookie-based sessions support using
+      <tt>Rack::Session::Cookie</tt>. See 'Using Sessions' section for more
+      information.
+    </dd>
 
   <dt>session_store</dt>
-  <dd>The Rack session middleware used. Defaults to <tt>Rack::Session::Cookie</tt>. See 'Using Sessions' section for more information.</dd>
+    <dd>
+      The Rack session middleware used. Defaults to
+      <tt>Rack::Session::Cookie</tt>. See 'Using Sessions' section for more
+      information.
+    </dd>
 
   <dt>show_exceptions</dt>
-  <dd>
-    Show a stack trace in the browser when an exception happens. Enabled by
-    default when <tt>environment</tt> is set to <tt>"development"</tt>,
-    disabled otherwise.
-  </dd>
-  <dd>
-    Can also be set to <tt>:after_handler</tt> to trigger app-specified error
-    handling before showing a stack trace in the browser.
-  </dd>
+    <dd>
+      Show a stack trace in the browser when an exception happens. Enabled by
+      default when <tt>environment</tt> is set to <tt>"development"</tt>,
+      disabled otherwise.
+    </dd>
+    <dd>
+      Can also be set to <tt>:after_handler</tt> to trigger app-specified
+      error handling before showing a stack trace in the browser.
+    </dd>
 
   <dt>static</dt>
-  <dd>Whether Sinatra should handle serving static files.</dd>
-  <dd>Disable when using a server able to do this on its own.</dd>
-  <dd>Disabling will boost performance.</dd>
-  <dd>
-    Enabled by default in classic style, disabled for modular apps.
-  </dd>
+    <dd>Whether Sinatra should handle serving static files.</dd>
+    <dd>Disable when using a server able to do this on its own.</dd>
+    <dd>Disabling will boost performance.</dd>
+    <dd>
+      Enabled by default in classic style, disabled for modular apps.
+    </dd>
 
   <dt>static_cache_control</dt>
-  <dd>
-    When Sinatra is serving static files, set this to add <tt>Cache-Control</tt>
-    headers to the responses. Uses the <tt>cache_control</tt> helper. Disabled
-    by default.
-  </dd>
-  <dd>
-    Use an explicit array when setting multiple values:
-    <tt>set :static_cache_control, [:public, :max_age => 300]</tt>
-  </dd>
+    <dd>
+      When Sinatra is serving static files, set this to add
+      <tt>Cache-Control</tt> headers to the responses. Uses the
+      <tt>cache_control</tt> helper. Disabled by default.
+    </dd>
+    <dd>
+      Use an explicit array when setting multiple values:
+      <tt>set :static_cache_control, [:public, :max_age => 300]</tt>
+    </dd>
 
   <dt>threaded</dt>
-  <dd>
-    If set to <tt>true</tt>, will tell Thin to use <tt>EventMachine.defer</tt>
-    for processing the request.
-  </dd>
+    <dd>
+      If set to <tt>true</tt>, will tell Thin to use
+      <tt>EventMachine.defer</tt> for processing the request.
+    </dd>
 
   <dt>traps</dt>
-  <dd>Whether Sinatra should handle system signals.</dd>
+    <dd>Whether Sinatra should handle system signals.</dd>
 
   <dt>views</dt>
-  <dd>
-    Path to the views folder. Inferred from <tt>app_file</tt> setting if
-    not set.
-  </dd>
+    <dd>
+      Path to the views folder. Inferred from <tt>app_file</tt> setting if
+      not set.
+    </dd>
 
   <dt>x_cascade</dt>
-  <dd>
-    Whether or not to set the X-Cascade header if no route matches.
-    Defaults to <tt>true</tt>.
-  </dd>
+    <dd>
+      Whether or not to set the X-Cascade header if no route matches.
+      Defaults to <tt>true</tt>.
+    </dd>
 </dl>
 
 ## Environments
 
-There are three predefined `environments`: `"development"`, `"production"` and
-`"test"`. Environments can be set through the `APP_ENV` environment variable.
-The default value is `"development"`. In the `"development"` environment all
-templates are reloaded between requests, and special `not_found` and `error`
-handlers display stack traces in your browser. In the `"production"` and
-`"test"` environments, templates are cached by default.
+There are three predefined `environments`: `"development"`,
+`"production"` and `"test"`. Environments can be set through the
+`APP_ENV` environment variable. The default value is `"development"`.
+In the `"development"` environment all templates are reloaded between
+requests, and special `not_found` and `error` handlers display stack
+traces in your browser. In the `"production"` and `"test"` environments,
+templates are cached by default.
 
 To run different environments, set the `APP_ENV` environment variable:
 
@@ -2338,9 +2450,9 @@ end
 
 ## 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 `haml`,
-`erb`, `halt`, etc.
+Error handlers run within the same context as routes and before filters,
+which means you get all the goodies it has to offer, like `haml`, `erb`,
+`halt`, etc.
 
 ### Not Found
 
@@ -2420,10 +2532,11 @@ and additional debugging information in your browser.
 ## Rack Middleware
 
 Sinatra rides on [Rack](http://rack.github.io/), a minimal standard
-interface for Ruby web frameworks. One of Rack's most interesting capabilities
-for application developers is support for "middleware" -- components that sit
-between the server and your application monitoring and/or manipulating the
-HTTP request/response to provide various types of common functionality.
+interface for Ruby web frameworks. One of Rack's most interesting
+capabilities for application developers is support for "middleware" --
+components that sit between the server and your application monitoring
+and/or manipulating the HTTP request/response to provide various types
+of common functionality.
 
 Sinatra makes building Rack middleware pipelines a cinch via a top-level
 `use` method:
@@ -2463,7 +2576,8 @@ or in the [Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
 
 ## Testing
 
-Sinatra tests can be written using any Rack-based testing library or framework.
+Sinatra tests can be written using any Rack-based testing library or
+framework.
 [Rack::Test](http://www.rubydoc.info/github/brynary/rack-test/master/frames)
 is recommended:
 
@@ -2522,9 +2636,9 @@ class MyApp < Sinatra::Base
 end
 ```
 
-The methods available to `Sinatra::Base` subclasses are exactly the same as
-those available via the top-level DSL. Most top-level apps can be converted to
-`Sinatra::Base` components with two modifications:
+The methods available to `Sinatra::Base` subclasses are exactly the same
+as those available via the top-level DSL. Most top-level apps can be
+converted to `Sinatra::Base` components with two modifications:
 
 * Your file should require `sinatra/base` instead of `sinatra`;
   otherwise, all of Sinatra's DSL methods are imported into the main
@@ -2533,12 +2647,11 @@ those available via the top-level DSL. Most top-level apps can be converted to
   of `Sinatra::Base`.
 
 `Sinatra::Base` is a blank slate. Most options are disabled by default,
-including the built-in server. See
-[Configuring Settings](http://www.sinatrarb.com/configuration.html)
-for details on available options and their behavior. If you want
-behavior more similar to when you define your app at the top level (also
-known as Classic style), you
-can subclass `Sinatra::Application`.
+including the built-in server. See [Configuring
+Settings](http://www.sinatrarb.com/configuration.html) for details on
+available options and their behavior. If you want behavior more similar
+to when you define your app at the top level (also known as Classic
+style), you can subclass `Sinatra::Application`:
 
 ```ruby
 require 'sinatra/base'
@@ -2552,16 +2665,17 @@ end
 
 ### Modular vs. Classic Style
 
-Contrary to common belief, there is nothing wrong with the classic style. If it
-suits your application, you do not have to switch to a modular application.
+Contrary to common belief, there is nothing wrong with the classic
+style. If it suits your application, you do not have to switch to a
+modular application.
 
-The main disadvantage of using the classic style rather than the modular style
-is that you will only have one Sinatra application per Ruby process. If you
-plan to use more than one, switch to the modular style. There is no reason you
-cannot mix the modular and the classic styles.
+The main disadvantage of using the classic style rather than the modular
+style is that you will only have one Sinatra application per Ruby
+process. If you plan to use more than one, switch to the modular style.
+There is no reason you cannot mix the modular and the classic styles.
 
-If switching from one style to the other, you should be aware of slightly
-different default settings:
+If switching from one style to the other, you should be aware of
+slightly different default settings:
 
 <table>
   <tr>
@@ -2616,8 +2730,8 @@ different default settings:
 
 ### Serving a Modular Application
 
-There are two common options for starting a modular app, actively starting with
-`run!`:
+There are two common options for starting a modular app, actively
+starting with `run!`:
 
 ```ruby
 # my_app.rb
@@ -2680,16 +2794,16 @@ A `config.ru` file is recommended if:
 * You want to use more than one subclass of `Sinatra::Base`.
 * You want to use Sinatra only for middleware, and not as an endpoint.
 
-**There is no need to switch to a `config.ru` simply because you switched to
-the modular style, and you don't have to use the modular style for running with
-a `config.ru`.**
+**There is no need to switch to a `config.ru` simply because you
+switched to the modular style, and you don't have to use the modular
+style for running with a `config.ru`.**
 
 ### Using Sinatra as Middleware
 
-Not only is Sinatra able to use other Rack middleware, any Sinatra application
-can in turn be added in front of any Rack endpoint as middleware itself. This
-endpoint could be another Sinatra application, or any other Rack-based
-application (Rails/Ramaze/Camping/...):
+Not only is Sinatra able to use other Rack middleware, any Sinatra
+application can in turn be added in front of any Rack endpoint as
+middleware itself. This endpoint could be another Sinatra application,
+or any other Rack-based application (Rails/Hanami/Roda/...):
 
 ```ruby
 require 'sinatra/base'
@@ -2778,9 +2892,9 @@ available.
 Every Sinatra application corresponds to a subclass of `Sinatra::Base`.
 If you are using the top-level DSL (`require 'sinatra'`), 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` or `session` objects, as there is only a
-single application class for all requests.
+created explicitly. At class level you have methods like `get` or
+`before`, but you cannot access the `request` or `session` objects, as
+there is only a single application class for all requests.
 
 Options created via `set` are methods at class level:
 
@@ -2954,9 +3068,9 @@ known to run Sinatra:
 Not being officially supported means if things only break there and not on a
 supported platform, we assume it's not our issue but theirs.
 
-We also run our CI against ruby-head (future releases of MRI), but we can't
-guarantee anything, since it is constantly moving. Expect upcoming 2.x releases
-to be fully supported.
+We also run our CI against ruby-head (future releases of MRI), but we
+can't guarantee anything, since it is constantly moving. Expect upcoming
+2.x releases to be fully supported.
 
 Sinatra should work on any operating system supported by the chosen Ruby
 implementation.
@@ -2968,8 +3082,9 @@ Ruby version prior to 2.2.
 
 ## The Bleeding Edge
 
-If you would like to use Sinatra's latest bleeding-edge code, feel free to run your
-application against the master branch, it should be rather stable.
+If you would like to use Sinatra's latest bleeding-edge 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
 
@@ -2998,12 +3113,11 @@ gem 'sinatra', :github => 'sinatra/sinatra'
 
 # 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 application's dependencies in the `Gemfile`.
-Sinatra's direct dependencies (Rack and Tilt) will, however, be automatically
-fetched and added by Bundler.
+Note that you will have to list all your application's dependencies in
+the `Gemfile`. Sinatra's direct dependencies (Rack and Tilt) will,
+however, be automatically fetched and added by Bundler.
 
 Now you can run your app like this:
 
@@ -3011,41 +3125,6 @@ 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 `sinatra/lib` directory
-on the `$LOAD_PATH`:
-
-```shell
-cd myapp
-git clone git://github.com/sinatra/sinatra.git
-ruby -I sinatra/lib myapp.rb
-```
-
-To update the Sinatra sources in the future:
-
-```shell
-cd myapp/sinatra
-git pull
-```
-
-### Install Globally
-
-You can build the gem on your own:
-
-```shell
-git clone git://github.com/sinatra/sinatra.git
-cd sinatra
-rake sinatra.gemspec
-rake install
-```
-
-If you install gems as root, the last step should be:
-
-```shell
-sudo rake install
-```
-
 ## Versioning
 
 Sinatra follows [Semantic Versioning](http://semver.org/), both SemVer and