Merge pull request #669 from burningTyger/master

update German Readme and some small English Readme fixes

README.de.md

@@ -53,6 +53,15 @@ Jeder dieser Routen wird ein Ruby-Block zugeordnet:
 options '/' do
   .. zeige, was wir können ..
 end
+
+link '/' do
+  .. verbinde etwas ..
+end
+
+unlink '/' do
+  .. trenne etwas ..
+end
+
 ```
 
 Die Routen werden in der Reihenfolge durchlaufen, in der sie definiert wurden.
@@ -351,7 +360,8 @@ Einstellungen:
 <dl>
   <dt>locals</dt>
   <dd>Liste von lokalen Variablen, die and das Dokument weitergegeben werden.
-    Praktisch für Partials. Beispiel:
+    Praktisch für Partials:
+
     <tt>erb "<%= foo %>", :locals => {:foo => "bar"}</tt></dd>
       
   <dt>default_encoding</dt>
@@ -364,9 +374,10 @@ Einstellungen:
       
   <dt>layout</dt>
   <dd>Legt fest, ob ein Layouttemplate verwendet werden soll oder nicht
-    (<tt>true</tt> oder<tt>false</tt>). Ist es ein Symbol, dass legt es fest,
+    (<tt>true</tt> oder<tt>false</tt>). Ist es ein Symbol, dann legt es fest,
-    welches Template als Layout verwendet wird. Beispiel:
+    welches Template als Layout verwendet wird:
-    <tt><tt>erb :index, :layout => !request.xhr?</tt></tt></dd>
+
+    <tt>erb :index, :layout => !request.xhr?</tt></dd>
       
   <dt>content_type</dt>
   <dd>Content-Type den das Template ausgibt. Voreinstellung hängt von der
@@ -380,10 +391,14 @@ Einstellungen:
   <dt>layout_engine</dt>
   <dd>Legt fest, welcher Renderer für das Layout verantwortlich ist. Hilfreich
     für Sprachen, die sonst keine Templates unterstützen. Voreingestellt auf
-    den Renderer, der für das Template verwendet wird. Beispiel:
+    den Renderer, der für das Template verwendet wird:
-    <tt>set :rdoc, :layout_engine => :erb</tt></dd>
-</dl>
 
+    <tt>set :rdoc, :layout_engine => :erb</tt></dd>
+  <dt>layout_options</dt>
+  <dd>Besondere Einstellungen, die nur für das Rendering verwendet werden:
+
+    <tt>set :rdoc, :layout_options => { :views => 'views/layouts' }</tt></dd>
+</dl>
 
 Sinatra geht davon aus, dass die Templates sich im `./views` Verzeichnis
 befinden. Es kann jedoch ein anderer Ordner festgelegt werden:
@@ -401,11 +416,21 @@ auch dann, wenn sie sich in einem Unterordner befinden:
 
 Rendering-Methoden rendern jeden String direkt.
 
+#### Direkte Templates
+
+``` ruby
+get '/' do
+  haml '%div.title Hallo Welt'
+end
+```
+
+Hier wird der String direkt gerendert.
+
 ### Verfügbare Templatesprachen
 
 Einige Sprachen haben mehrere Implementierungen. Um festzulegen, welche
 verwendet wird (und dann auch Thread-sicher ist), verwendet man am besten zu
-Beginn ein 'require':
+Beginn ein `'require'`:
 
 ```ruby
 require 'rdiscount' # oder require 'bluecloth'
@@ -809,6 +834,82 @@ verwendet wird.
   </tr>
 </table>
 
+#### Stylus Templates
+
+<table>
+  <tr>
+    <td>Abhängigkeit</td>
+    <td>
+      <a href="https://github.com/lucasmazza/ruby-stylus" title="Ruby Stylus">
+        Stylus
+      </a> und eine Möglichkeit 
+      <a href="https://github.com/sstephenson/execjs/blob/master/README.md#readme" title="ExecJS">
+        JavaScript auszuführen
+      </a>.
+    </td>
+  </tr>
+  <tr>
+    <td>Dateierweiterung</td>
+    <td><tt>.styl</tt></td>
+  </tr>
+  <tr>
+    <td>Beispiel</td>
+    <td><tt>stylus :index</tt></td>
+  </tr>
+</table>
+
+Um Stylus-Templates ausführen zu können, müssen `stylus` und `stylus/tilt`
+zuerst geladen werden:
+
+``` ruby
+require 'sinatra'
+require 'stylus'
+require 'stylus/tilt'
+
+get '/' do
+  stylus :example
+end
+```
+
+#### Yajl Templates
+
+<table>
+  <tr>
+    <td>Abhängigkeit</td>
+    <td><a href="https://github.com/brianmario/yajl-ruby" title="yajl-ruby">yajl-ruby</a></td>
+  </tr>
+  <tr>
+    <td>Dateierweiterung</td>
+    <td><tt>.yajl</tt></td>
+  </tr>
+  <tr>
+    <td>Beispiel</td>
+    <td>
+      <tt>
+        yajl :index,
+             :locals => { :key => 'qux' },
+             :callback => 'present',
+             :variable => 'resource'
+      </tt>
+    </td>
+  </tr>
+</table>
+
+Die Template-Quelle wird als Ruby-String evaluiert. Die daraus resultierende
+json Variable wird mit Hilfe von `#to_json` umgewandelt:
+
+``` ruby
+json = { :foo => 'bar' }
+json[:baz] = key
+```
+
+Die `:callback` und `:variable` Optionen können mit dem gerenderten Objekt
+verwendet werden:
+
+``` ruby
+var resource = {"foo":"bar","baz":"qux"}; present(resource);
+```
+
 ### WLang Templates
 
 <table>
@@ -830,14 +931,6 @@ Ruby-Methoden in wlang aufzurufen entspricht nicht den idiomatischen Vorgaben
 von wlang, es bietet sich deshalb an, `:locals` zu verwenden. Layouts, die
 wlang und `yield` verwenden, werden aber trotzdem unterstützt.
 
-### Eingebettete Templates
-
-```ruby
-    get '/' do
-      haml '%div.title Hallo Welt'
-    end
-```
-
 Rendert den eingebetteten Template-String.
 
 ### Auf Variablen in Templates zugreifen
@@ -864,6 +957,44 @@ Oder durch einen expliziten Hash von lokalen Variablen:
 Dies wird typischerweise bei Verwendung von Subtemplates (partials) in anderen
 Templates eingesetzt.
 
+### Templates mit `yield` und verschachtelte Layouts
+
+Ein Layout ist üblicherweise ein Template, dass ein `yield` aufruft. Ein solches
+Template kann entweder wie oben beschrieben über die `:template` option
+verwendet werden oder mit einem Block gerendert werden:
+
+``` ruby
+erb :post, :layout => false do
+  erb :index
+end
+```
+
+Dieser Code entspricht weitestgehend `erb :index, :layout => :post`.
+
+Blöcke an Render-Methoden weiterzugeben ist besonders bei verschachtelten
+Layouts hilfreich:
+
+``` ruby
+erb :main_layout, :layout => false do
+  erb :admin_layout do
+    erb :user
+  end
+end
+```
+
+Der gleiche Effekt kann auch mit weniger Code erreicht werden:
+
+``` ruby
+erb :admin_layout, :layout => :main_layout do
+  erb :user
+end
+```
+
+Zur Zeit nehmen folgende Renderer Blöcke an: `erb`, `haml`, `liquid`, `slim `
+und `wlang`.
+
+Das gleich gilt auch für die allgemeine `render` Methode.
+
 ### Inline-Templates
 
 Templates können auch am Ende der Datei definiert werden:
@@ -1233,18 +1364,34 @@ Serven wie Thin oder Rainbows möglich, andere Server werden trotzdem den Stream
 beenden:
 
 ```ruby
+# Durchgehende Anfrage (long polling)
+
 set :server, :thin
 connections = []
 
-    get '/' do
+get '/subscribe' do
-      # Den Stream offen halten
+  # Client-Registrierung beim Server, damit Events mitgeteilt werden können
   stream(:keep_open) { |out| connections << out }
+
+  # tote Verbindungen entfernen 
+  connections.reject!(&:closed?)
+
+  # Rückmeldung
+  "Angemeldet"
 end
 
-    post '/' do
+post '/message' do
-      # In alle offenen Streams schreiben
+  connections.each do |out|
-      connections.each { |out| out << params[:message] << "\n" }
+    # Den Client über eine neue Nachricht in Kenntnis setzen
-      "Nachricht verschickt"
+    # notify client that a new message has arrived
+    out << params[:message] << "\n"
+
+    # Den Client zur erneuten Verbindung auffordern
+    out.close
+  end
+
+  # Rückmeldung
+  "Mitteiling erhalten"
 end
 ```
 
@@ -1531,7 +1678,7 @@ zugegriffen werden:
   request.host                # "example.com"
   request.get?                # true (ähnliche Methoden für andere Verben)
   request.form_data?          # false
-      request["IRGENDEIN_HEADER"] # Wert von IRGENDEIN_HEADER header
+  request["irgendein_param"]  # Wert von einem Parameter; [] ist die Kurzform für den params Hash
   request.referrer            # Der Referrer des Clients oder '/'
   request.user_agent          # User-Agent (verwendet in der :agent Bedingung)
   request.cookies             # Hash des Browser-Cookies
@@ -1754,7 +1901,7 @@ Schutzmechanismen zu deaktivieren:
 ```ruby
 set :protection, :except => [:path_traversal, :session_hijacking]
 ```
-## Möglichee Einstellungen
+## Mögliche Einstellungen
 
 <dl>
   <dt>absolute_redirects</dt>
@@ -1767,10 +1914,9 @@ Schutzmechanismen zu deaktivieren:
   Standardmäßig nicht aktiviert.</dd>
 
   <dt>add_charsets</dt>
-  <dd>
+  <dd>Mime-Types werden hier automatisch der Helfer-Methode
-    Mime-Types werden hier automatisch der Helfer-Methode <tt>content_type</tt>
+  <tt>content_type</tt> zugeordnet. Es empfielt sich, Werte hinzuzufügen statt
-    zugeordnet. Es empfielt sich, Werte hinzuzufügen statt sie zu
+  sie zu überschreiben: <tt>settings.add_charsets << "application/foobar"</tt>
-    überschreiben: <tt>settings.add_charsets << "application/foobar"</tt>
   </dd>
 
   <dt>app_file</dt>
@@ -1778,8 +1924,8 @@ Schutzmechanismen zu deaktivieren:
   Inline-, View- und öffentliche Verzeichnis des Projekts festzustellen.</dd>
 
   <dt>bind</dt>
-  <dd>IP-Address, an die gebunden wird (Standardwert: 0.0.0.0). Wird nur für
+  <dd>IP-Address, an die gebunden wird (Standardwert: <tt>0.0.0.0</tt>). Wird
-  den eingebauten Server verwendet.</dd>
+  nur für den eingebauten Server verwendet.</dd>
 
   <dt>default_encoding</dt>
   <dd>Das Encoding, falls keines angegeben wurde. Standardwert ist
@@ -1848,9 +1994,8 @@ Schutzmechanismen zu deaktivieren:
 
   <dt>server</dt>
   <dd>Server oder Liste von Servern, die als eingebaute Server zur Verfügung
-  stehen. Standardmäßig auf [‘thin’, ‘mongrel’, ‘webrick’] voreingestellt. Die
+  stehen. Standardmäßig auf <tt>[‘thin’, ‘mongrel’, ‘webrick’]</tt>
-  Anordnung gibt die Priorität
+  voreingestellt. Die Anordnung gibt die Priorität vor.</dd>
-  vor.</dd>
 
   <dt>sessions</dt>
   <dd>Sessions auf Cookiebasis mittels
@@ -1878,9 +2023,17 @@ Schutzmechanismen zu deaktivieren:
   mehrere Werte gleichzeitig zu übergeben: <tt>set :static_cache_control,
   [:public, :max_age => 300]</tt></dd>
 
+  <dt>threaded</dt>
+  <dd>Wird es auf <tt>true</tt> gesetzt, wird Thin aufgefordert
+  <tt>EventMachine.defer</tt> zur Verarbeitung des Requests einzusetzen.</dd>
+  
   <dt>views</dt>
   <dd>Verzeichnis der Views. Leitet sich von der <tt>app_file</tt> Einstellung
   ab, wenn nicht gesetzt.</dd>
+
+  <dt>x_cascade</dt>
+  <dd>Einstellung, ob der X-Cascade Header bei fehlender Route gesetzt wird oder
+  nicht. Standardeinstellung ist <tt>true</tt>.</dd>
 </dl>
 
 ## Umgebungen
@@ -1973,7 +2126,8 @@ Oder ein Status-Code-Bereich:
 ```
 
 Sinatra setzt verschiedene `not_found`- und `error`-Handler in der
-Development-Umgebung.
+Development-Umgebung ein, um hilfreiche Debugging Informationen und Stack Traces
+anzuzeigen.
 
 ## Rack-Middleware
 
@@ -2055,7 +2209,10 @@ wird empfohlen:
 end
 ```
 
-## Sinatra::Base - Middleware, Bibliotheken und modulare Anwendungen
+Hinweis: Wird Sinatra modular verwendet, muss <tt>Sinatra::Application</tt> mit
+dem Namen der Applikations-Klasse ersetzt werden.
+
+[[##]] Sinatra::Base - Middleware, Bibliotheken und modulare Anwendungen
 
 Das Definieren einer Top-Level-Anwendung funktioniert gut für
 Mikro-Anwendungen, hat aber Nachteile, wenn wiederverwendbare Komponenten wie
@@ -2120,16 +2277,49 @@ miteinander zu vermischen.
 Bei einem Umstieg, sollten einige Unterschiede in den Einstellungen beachtet
 werden:
 
-```
+<table>
-    Szenario            Classic                 Modular
+  <tr>
-    ---------------------------------------------------
+    <th>Szenario</th>
+    <th>Classic</th>
+    <th>Modular</th>
+  </tr>
 
-    app_file            sinatra ladende Datei   Sinatra::Base subklassierende Datei
+  <tr>
-    run                 $0 == app_file          false
+    <td>app_file</td>
-    logging             true                    false
+    <td>Sinatra ladende Datei</td>
-    method_override     true                    false
+    <td>Sinatra::Base subklassierende Datei</td>
-    inline_templates    true                    false
+  </tr>
-```
+
+  <tr>
+    <td>run</td>
+    <td>$0 == app_file</td>
+    <td>false</td>
+  </tr>
+
+  <tr>
+    <td>logging</td>
+    <td>true</td>
+    <td>false</td>
+  </tr>
+
+  <tr>
+    <td>method_override</td>
+    <td>true</td>
+    <td>false</td>
+  </tr>
+
+  <tr>
+    <td>inline_templates</td>
+    <td>true</td>
+    <td>false</td>
+  </tr>
+
+  <tr>
+    <td>static</td>
+    <td>true</td>
+    <td>false</td>
+  </tr>
+</table>
 
 ### Eine modulare Applikation bereitstellen
 
@@ -2158,7 +2348,7 @@ Oder über eine `config.ru`-Datei, die es erlaubt, einen beliebigen
 Rack-Handler zu verwenden:
 
 ```ruby
-    # config.ru
+# config.ru (mit rackup starten)
 require './mein_app'
 run MeineApp
 ```
@@ -2445,7 +2635,7 @@ Die folgenden Versionen werden offiziell unterstützt:
   Einsatz kommt – die Thin und Mongrel Web-Server werden bisher nicht
   unterstütz. JRubys Unterstützung für C-Erweiterungen sind zur Zeit ebenfalls
   experimenteller Natur, betrifft im Moment aber nur die RDiscount, Redcarpet,
-  RedCloth und Yajl Templates.</dd>
+  RedCloth und [[Yajl]] Templates.</dd>
 </dl>
 
 Weiterhin werden wir die kommende Ruby-Versionen im Auge behalten.

README.md

@@ -484,22 +484,17 @@ Available Options:
     Special options only used for rendering the layout. Example:
     <tt>set :rdoc, :layout_options => { :views => 'views/layouts' }</tt>
   </dd>
-
-  <dd>
-    Templates are assumed to be located directly under the `./views`
-    directory. To use a different views directory:
-  <tt>set :views, settings.root + '/templates'</tt>
-  </dd>
-
-  <dd>
-    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: <tt>'subdir/template'</tt>). You must use a symbol because
-    otherwise rendering methods will render any strings passed to them
-    directly.
-  </dd>
 </dl>
     
+Templates are assumed to be located directly under the `./views` directory. To 
+use a different views directory: 
+<tt>set :views, settings.root + '/templates'</tt>
+
+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:
+<tt>'subdir/template'</tt>). You must use a symbol because otherwise rendering
+methods will render any strings passed to them directly.
+
 #### Literal Templates
 
 ``` ruby
@@ -977,14 +972,15 @@ end
 
 
 The template source is evaluated as a Ruby string, and the
-resulting json variable is converted using `#to_json`.
+resulting json variable is converted using `#to_json`:
 
 ``` ruby
 json = { :foo => 'bar' }
 json[:baz] = key
 ```
 
-The `:callback` and `:variable` options can be used to decorate the rendered object.
+The `:callback` and `:variable` options can be used to decorate the rendered
+object:
 
 ``` ruby
 var resource = {"foo":"bar","baz":"qux"}; present(resource);
@@ -2013,7 +2009,7 @@ set :protection, :session => true
   </dd>
 
   <dt>bind</dt>
-  <dd>IP address to bind to (default: 0.0.0.0). Only used for built-in server.</dd>
+  <dd>IP address to bind to (default: <tt>0.0.0.0</tt>). Only used for built-in server.</dd>
 
   <dt>default_encoding</dt>
   <dd>encoding to assume if unknown (defaults to <tt>"utf-8"</tt>).</dd>
@@ -2094,7 +2090,7 @@ set :protection, :session => true
   <dt>server</dt>
   <dd>
     server or list of servers to use for built-in server. defaults to
-    ['thin', 'mongrel', 'webrick'], order indicates priority.
+    <tt>['thin', 'mongrel', 'webrick']</tt>, order indicates priority.
   </dd>
 
   <dt>sessions</dt>
@@ -2150,7 +2146,7 @@ set :protection, :session => true
   <dt>x_cascade</dt>
   <dd>
     Whether or not to set the X-Cascade header if no route matches.
-    Defaults to `true`.
+    Defaults to <tt>true</tt>.
   </dd>
 </dl>