<NME> README.textile
<BEF> h1. Installation via RubyGems

* Daily builds: @gem install rango --pre@ and @gem install simple-templater@. RubyGems don't work with prerelease gems properly, so you can't just run @gem install simple-templater rango --pre@. The trouble is when you are installing with @--pre@, RubyGems are looking just for prerelease gems, but Erubis, which is dependency of simple-templater, doesn't have any prerelease gem.
* Stable version: @gem install simple-templater rango@
* JRuby: @jruby --1.9 -S gem install simple-templater rango@ is how you should install Rango for JRuby. Unfortunately I'm getting strange errors here. Don't forget the @--1.9@ argument, because Rango can be installed just on Ruby 1.9.

_Rango itself doesn't define any runtime dependencies, since you may want to use just a subset of Rango, i. e. just template layer. If you are using stack generator, you get @Gemfile@ with usual dependencies, so @gem bundle@ will take care about it._

h1. Installation via "Rip":http://hellorip.com

* Install edge version: @rip install git://github.com/botanicus/rango.git@
* Install tagged version: @rip install git://github.com/botanicus/rango.git 0.2@

h1. How to Contribute To Rango

Contributions to Rango is easy, you don't have to create a ticket or something, the only thing you really have to do is write good code. Before you send a pull request, please ensure that you:
* Have no trailing whitespace in your code (if you run @rake hooks@, you get git pre-commit hook which take care about it)
* Wrote YARD documentation
* Wrote specs and run them under at least under Ruby 1.9.1, ideally under all the supported Ruby platforms:

<pre>
# run all the specs under Ruby 1.9.1 and Ruby 1.9.2
rvm specs 1.9.1,1.9.2

# run given spec under all installed Ruby implementations
rvm ruby ./script/spec spec/rango/mixins/message_spec.rb

# run given spec under Ruby 1.9.1
rvm 1.9.1 ruby ./script/spec spec/rango/mixins/message_spec.rb

Run @thor yardoc:generate@ in the sources directory and open doc/index.html in your browser. You will need to have "Yard":http://github.com/lsegal/yard installed.

You can also check the "Example Rango project":http://github.com/botanicus/rango-example

h1. Usage

* "RDoc.info API Docs":http://rdoc.info/projects/botanicus/rango
* "Yardoc.org API Docs":http://yardoc.org/docs/botanicus-rango
* "Examples":http://github.com/botanicus/rango-examples
* "Bug reporting":http://github.com/botanicus/rango/issues
* "Caliper Code Metrics":http://devver.net/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fbotanicus%2Frango.git

h1. Community

* "Google Group":http://groups.google.com/group/rango-project
* "Rango Blog":http://botanicus.github.com/rango
* "Twitter":https://twitter.com/RangoProject
* IRC: #rango at irc://irc.freenode.net
rango -i
</pre>

h1. Boot

Rango.boot

h1. Flat applications

<pre>
Rango.boot(:flat => true)
</pre>

@rackup config.ru@

h1. Init file @init.rb@

h1. Configuration

Main configuration is in file @settings.rb@

h1. Router

h2. Matching URL

You can match *regexp or string*. String will be matched as be matched as @/^url/@. When you use regexp you also can match parts of URL which will be available in request params hash. These arguments can be *positional or named*. Positional arguments are simply groups in regexp as @%r[/post/(\w+)]@. "Named regexps groups":http://pragdave.blogs.pragprog.com/pragdave/2008/10/fun-with-ruby-19-regular-expressions.html are new feature of Ruby 1.9 and it's syntax is @(?<name>pattern)@, for example @%r[/post/(?<slug>.+)$/]@

<pre>
"post/foo-bar".match(%r[^post/(?<slug>.+)$])
# => #<MatchData "post/foo-bar" slug:"foo-bar">
</pre>

h2. Strategies

h3. ControllerStrategy

<pre>
match(%r[^/(?<slug>.+)$]).to("Post#show", "blog/views")
will require or load (depends on Project.settings.debug) "blog/views"
and then creates new instance of Post and call show method this way:
controller = Post.new(request, params)
controller.show(slug)
</pre>

h3. CallableStrategy

<pre>
match(/.*/).to do |request|
  Rango.logger.debug(request)
  "Logged" # will be returned as response
end
</pre>

h2. Returned value

Returned value must be ....

<pre>
# coding=utf-8

Rango::Router.register do
  match("admin/").include('admin/urls.rb')
  # match regexp, positional argument
  match(%r[post/(.+)/$]).to('Posts#show', 'blog/views')
  # match regexp, named argument
  match(%r[^/post/(?<slug>.+)$]).to('blog/views', 'Posts#show')
  match("/kontakt").to(method(:foo))
  match("/kontakt").to do |request|
    Project.logger.debug("Huraaa!")
    "Huraaa!"
  end
  match(%r[^/(?<slug>.+)$]).to(method(:foo))
  match("block/").to do |request|
    "<h1>hello from block!</h1>"
  end
end
</pre>

h1. Pupu

"Pupu":http://github.com/botanicus/pupu is framework for writing assets plugins and there are already bundled many of useful javascript libraries and frameworks. It can handle dependencies.

h2. CLI usage

<pre>
# install autocompleter and its dependencies from my github repo
thor pupu:install botanicus/mootools

# or uninstall, it's the same
thor pupu:remove mootools

# list all installed pupus
thor pupu:list
</pre>

h2. Usage in templates

<pre>
= pupu :mootools, :more => true
= pupu :autocompleter, :type => "request"
= pupu :blueprint
</pre>

If you like to write your own pupu, please read "Pupu README":http://github.com/botanicus/pupu

h1. Generators

Rango is simple so we don't need to generate much code, so there are just two generators: project generator and application generator. The only thing they do is that they copy @lib/stubs/project@, resp. @lib/stubs/app@ to current directory. If you like to use your own stubs, just create @~/.rango/stubs@ with @project@ and/or @app@ directories and fill them with your files.

h1. Controllers

class Posts < Rango::Controller
  before :authenticate
  
  def authenticate
    raise SkipFilter if session.user.authorized?
    # ...
  end
  
  def show(slug)
    @post = Post.get(slug)
    display @post
  end
end

h1. Writing plugins

<pre>
class Rango::Plugin::MyPlugin
  include Rango::Settings
end
</pre>

h1. Contributing

Please follow Rango documentation standard.

h1. Deployment

Rango application is classic rack application, so it can be deployed to all of the rack-compatible server. I recommend Apache with Passenger.

<MSG> Most of the text from README was moved to doc/rango

<DFF> @@ -30,7 +30,7 @@ h1. Documentation
 
 Run @thor yardoc:generate@ in the sources directory and open doc/index.html in your browser. You will need to have "Yard":http://github.com/lsegal/yard installed.
 
-You can also check the "Example Rango project":http://github.com/botanicus/rango-example
+You can also check the "Rango examples project":http://github.com/botanicus/rango-examples
 
 h1. Usage
 
@@ -50,140 +50,4 @@ rackup config.ru
 rango -i
 </pre>
 
-h1. Boot
-
-Rango.boot
-
-h1. Flat applications
-
-<pre>
-Rango.boot(:flat => true)
-</pre>
-
-@rackup config.ru@
-
 h1. Init file @init.rb@
-
-h1. Configuration
-
-Main configuration is in file @settings.rb@
-
-h1. Router
-
-h2. Matching URL
-
-You can match *regexp or string*. String will be matched as be matched as @/^url/@. When you use regexp you also can match parts of URL which will be available in request params hash. These arguments can be *positional or named*. Positional arguments are simply groups in regexp as @%r[/post/(\w+)]@. "Named regexps groups":http://pragdave.blogs.pragprog.com/pragdave/2008/10/fun-with-ruby-19-regular-expressions.html are new feature of Ruby 1.9 and it's syntax is @(?<name>pattern)@, for example @%r[/post/(?<slug>.+)$/]@
-
-<pre>
-"post/foo-bar".match(%r[^post/(?<slug>.+)$])
-# => #<MatchData "post/foo-bar" slug:"foo-bar">
-</pre>
-
-h2. Strategies
-
-h3. ControllerStrategy
-
-<pre>
-match(%r[^/(?<slug>.+)$]).to("Post#show", "blog/views")
-will require or load (depends on Project.settings.debug) "blog/views"
-and then creates new instance of Post and call show method this way:
-controller = Post.new(request, params)
-controller.show(slug)
-</pre>
-
-h3. CallableStrategy
-
-<pre>
-match(/.*/).to do |request|
-  Rango.logger.debug(request)
-  "Logged" # will be returned as response
-end
-</pre>
-
-h2. Returned value
-
-Returned value must be ....
-
-<pre>
-# coding=utf-8
-
-Rango::Router.register do
-  match("admin/").include('admin/urls.rb')
-  # match regexp, positional argument
-  match(%r[post/(.+)/$]).to('Posts#show', 'blog/views')
-  # match regexp, named argument
-  match(%r[^/post/(?<slug>.+)$]).to('blog/views', 'Posts#show')
-  match("/kontakt").to(method(:foo))
-  match("/kontakt").to do |request|
-    Project.logger.debug("Huraaa!")
-    "Huraaa!"
-  end
-  match(%r[^/(?<slug>.+)$]).to(method(:foo))
-  match("block/").to do |request|
-    "<h1>hello from block!</h1>"
-  end
-end
-</pre>
-
-h1. Pupu
-
-"Pupu":http://github.com/botanicus/pupu is framework for writing assets plugins and there are already bundled many of useful javascript libraries and frameworks. It can handle dependencies.
-
-h2. CLI usage
-
-<pre>
-# install autocompleter and its dependencies from my github repo
-thor pupu:install botanicus/mootools
-
-# or uninstall, it's the same
-thor pupu:remove mootools
-
-# list all installed pupus
-thor pupu:list
-</pre>
-
-h2. Usage in templates
-
-<pre>
-= pupu :mootools, :more => true
-= pupu :autocompleter, :type => "request"
-= pupu :blueprint
-</pre>
-
-If you like to write your own pupu, please read "Pupu README":http://github.com/botanicus/pupu
-
-h1. Generators
-
-Rango is simple so we don't need to generate much code, so there are just two generators: project generator and application generator. The only thing they do is that they copy @lib/stubs/project@, resp. @lib/stubs/app@ to current directory. If you like to use your own stubs, just create @~/.rango/stubs@ with @project@ and/or @app@ directories and fill them with your files.
-
-h1. Controllers
-
-class Posts < Rango::Controller
-  before :authenticate
-  
-  def authenticate
-    raise SkipFilter if session.user.authorized?
-    # ...
-  end
-  
-  def show(slug)
-    @post = Post.get(slug)
-    display @post
-  end
-end
-
-h1. Writing plugins
-
-<pre>
-class Rango::Plugin::MyPlugin
-  include Rango::Settings
-end
-</pre>
-
-h1. Contributing
-
-Please follow Rango documentation standard.
-
-h1. Deployment
-
-Rango application is classic rack application, so it can be deployed to all of the rack-compatible server. I recommend Apache with Passenger.

Most of the text from README was moved to doc/rango