updated README and docs

README.md

@@ -1,36 +1,50 @@
 # Pagy
 
-[![Gem Version](https://badge.fury.io/rb/pagy.svg)](https://badge.fury.io/rb/pagy) [![Build Status](https://travis-ci.org/ddnexus/pagy.svg?branch=master)](https://travis-ci.org/ddnexus/pagy/branches)
+[![Gem Version](https://img.shields.io/gem/v/pagy.svg?label=pagy&colorA=99004d&colorB=cc0066)](https://rubygems.org/gems/pagy)
+![ruby](https://img.shields.io/badge/ruby-v1.9+-ruby.svg?colorA=99004d&colorB=cc0066)
+![jruby](https://img.shields.io/badge/jruby-v1.7+-jruby.svg?colorA=99004d&colorB=cc0066)
+[![Build Status](https://img.shields.io/travis/ddnexus/pagy/master.svg?colorA=1f7a1f&colorB=2aa22a)](https://travis-ci.org/ddnexus/pagy/branches)
+[![MIT license](https://img.shields.io/badge/license-MIT-mit.svg?colorA=1f7a1f&colorB=2aa22a)](http://opensource.org/licenses/MIT)
+![Commits](https://img.shields.io/github/commit-activity/y/ddnexus/pagy.svg?label=commits&colorA=004d99&colorB=0073e6)
+![Downloads](https://img.shields.io/gem/dt/pagy.svg?colorA=004d99&colorB=0073e6)
+[![Chat](http://img.shields.io/badge/gitter-ddnexus/pagy-purple.svg?colorA=800080&colorB=b300b3)](https://gitter.im/ruby-pagy/Lobby)
 
 Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.
 
-## Benchmarks
+## Improvements in v2.0+
+
+- Lower ruby requirements (ruby v1.9+ || jruby v1.7+) make Pagy very convenient also on older systems
+- The i18n internal implementation now includes full dynamic support for multi-language apps, it's ~18x faster and uses ~10x less memory than the i18n gem
+- The `searchkick` and `elasticsearch_rails` extras have been refactored with more and better options
+- Pagy v2.0+ is even faster and lighter than v1.0+ (see charts below)
+
+## Comparison with other gems
 
 The best way to quickly get an idea about Pagy is comparing it to the other well known gems.
 
-The values shown in the charts below have been recorded while each gem was producing the exact same output: same environment conditions, same task, just different gems _(see the [Detailed Gems Comparison](http://ddnexus.github.io/pagination-comparison/gems.html))_
+The values shown in the charts below have been recorded while each gem was producing the exact same output in the exact same environment. _(see the [Detailed Gems Comparison](http://ddnexus.github.io/pagination-comparison/gems.html))_
 
-### Faster
+### ~ 33x Faster!
 
 [![IPS Chart](docs/assets/images/ips-chart.png)](https://ddnexus.github.io/pagination-comparison/gems.html#ips-benchmark)
 
-### Less Memory
+### ~ 26x Lighter!
 
 [![Memory Chart](docs/assets/images/memory-chart.png)](https://ddnexus.github.io/pagination-comparison/gems.html#memory-profile)
 
-### Simpler
+### ~ 25x Simpler!
 
 [![Objects Chart](docs/assets/images/objects-chart.png)](https://ddnexus.github.io/pagination-comparison/gems.html#memory-profile)
 
-### More Efficient
+### ~ 850x More Efficient!
 
 [![Efficiency Table](docs/assets/images/efficiency-table.png)](https://ddnexus.github.io/pagination-comparison/gems.html#efficiency-ratio)
 
 _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#efficiency-ratio) is calculated out of speed (IPS) and Memory (Kb): it shows how well each gem uses any Kb of memory it allocates/consumes._
 
 #### Disclaimer
 
-Please, notice that benchmarking and profiling the pagination gems in a working app environment is quite a tricky task.
+Please, notice that benchmarking and profiling the pagination gems in a working app environment may be a quite a tricky task.
 
 If you compare Pagy in your own app and don't notice much of a difference, your benchmarks are most likely not isolating the pagination code from the rest of your app.
 
@@ -40,26 +54,27 @@ Please check the [Benchmarks and Memory Profiles Source](http://github.com/ddnex
 
 ### Straightforward Code
 
-- Pagy has a very slim core code of just ~100 line of simple ruby, organized in 3 flat modules very easy to understand and use _(see [more...](https://ddnexus.github.io/pagy/api))_
+- Pagy has a very slim core code of just ~100 lines of simple ruby, organized in 3 flat modules, very easy to understand and use _(see [more...](https://ddnexus.github.io/pagy/api))_
 - It has a quite fat set of optional extras that you can explicitly require for very efficient and modular customization _(see [extras](https://ddnexus.github.io/pagy/extras))_
 - It has no dependencies: it produces its own HTML, URLs, i18n with its own specialized and fast code _(see [why...](https://ddnexus.github.io/pagy/index#specialized-code-instead-of-generic-helpers))_
-- 100% of its methods are public API, accessible and overridable **right where you use them** (no need of monkey-patching)
+- 100% of its methods are public API, accessible and overridable **right where you use them** (no pesky monkey-patching neededneed for )
 - 100% test coverage for core code and extras
 
 ### Totally Agnostic
 
 - The `Pagy` class doesn't need to know anything about your models, ORM or storage, so it doesn't add any code to them _(see [why...](https://ddnexus.github.io/pagy/index#stay-away-from-the-models))_
-- It works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just whatever you can count _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-any-collection))_
+- It works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just any list, even if you cannot count it _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-any-collection))_
 - Pagy works with the most popular Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box _(see [more...](https://ddnexus.github.io/pagy/how-to#environment-assumptions))_
 - It works also with any possible non-Rack environment by just overriding one or two two-lines methods _(see [more...](https://ddnexus.github.io/pagy/how-to#environment-assumptions))_
 
 ### Unlike the other gems
 
 - Pagy is very modular and does not load nor execute unnecessary code in your app _(see [why...](https://ddnexus.github.io/pagy/how-to#global-configuration))_
-- It works with collections/scopes that already used `limit` and `offset` _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-a-pre-offsetted-and-pre-limited-collection))_
+- It works even with collections/scopes that already used `limit` and `offset` _(see [how...](https://ddnexus.github.io/pagy/how-to#paginate-a-pre-offsetted-and-pre-limited-collection))_
 - It works with helpers or templates _(see [more...](https://ddnexus.github.io/pagy/how-to#using-templates))_
 - It raises real `Pagy::OverflowError` exceptions that you can rescue from _(see [how...](https://ddnexus.github.io/pagy/how-to#handling-pagyoutofrangeerror-exception))_ or use the [overflow extra](http://ddnexus.github.io/pagy/extras/overflow) for a few ready to use common behaviors
 - It does not impose any difficult-to-override logic or output _(see [why...](https://ddnexus.github.io/pagy/index#really-easy-to-customize))_
+- It also works on legacy systems starting from ruby v1.9+ and jruby v1.7+
 
 ### Easy to use
 
@@ -93,8 +108,8 @@ Use the official extras, or write your own in just a few lines. Extras add speci
 
 - [array](http://ddnexus.github.io/pagy/extras/array): Paginate arrays efficiently, avoiding expensive array-wrapping and without overriding
 - [countless](http://ddnexus.github.io/pagy/extras/countless): Paginate without the need of any count, saving one query per rendering
-- [elasticsearch_rails](http://ddnexus.github.io/pagy/extras/elasticsearch_rails): Paginate `ElasticsearchRails::Results` objects efficiently, avoiding expensive object-wrapping and without overriding
-- [searchkick](http://ddnexus.github.io/pagy/extras/searchkick): Paginate `Searchkick::Results` objects efficiently, avoiding expensive object-wrapping and without overriding
+- [elasticsearch_rails](http://ddnexus.github.io/pagy/extras/elasticsearch_rails): Paginate `ElasticsearchRails` response objects
+- [searchkick](http://ddnexus.github.io/pagy/extras/searchkick): Paginate `Searchkick::Results` objects
 
 ### Frontend Extras
 
@@ -127,7 +142,7 @@ Besides the classic pagination `nav`, Pagy offers a few ready to use alternative
 
 [![Objects Chart](docs/assets/images/gorails-thumbnail-w360.png)](https://gorails.com/episodes/pagination-with-pagy-gem?autoplay=1)
 
-__* Notice__: the `pagy_nav_bootstrap` helper used in the screencast has been renamed to `pagy_bootstrap_nav` in version 2.0
+**Notice**: the `pagy_nav_bootstrap` helper used in the screencast has been renamed to `pagy_bootstrap_nav` in version 2.0
 
 ### Posts and Tutorials
 
@@ -164,13 +179,25 @@ Pagy is a fresh project and your help would be great. If you like it, you have a
 - Submit your translation if your language is missing from the [dictionary files](https://github.com/ddnexus/pagy/blob/master/lib/locales)
 - Write a Tutorial or a "How To" topic
 
-## Versioning, Branches and Pull Requests
+## Repository Info
+
+### Versioning
 
 Pagy follows the [Semantic Versioning 2.0.0](https://semver.org/). Please, check the [Changelog](https://github.com/ddnexus/pagy/blob/master/CHANGELOG.md) for breaking changes introduced by mayor versions.
 
-The `master` branch is the latest rubygem-published release (plus changes that don't affect the actual gem behavior, e.g. doc, tests). You should use it as the base branch for pull requests, because it will not be force-rebased.
+### Branching
+
+Pagy follows the [GitFlow](https://datasift.github.io/gitflow/IntroducingGitFlow.html) branching model with `master` and `dev`.
+
+The `master` branch is the latest rubygem-published release (plus the changes that don't affect the gem behavior, e.g. doc, tests).
+
+The `dev` branch is the development branch with the new code that will be merged in the next release.
+
+Expect any other branch to be experimental, force-rebased and/or deleted even without merging.
+
+### Pull Requests
 
-The `dev` branch is kept rebased on top of `master`, so expect it to be force-rebased (i.e. do not use it as the base for your commits). Use `dev` as a preview for trying the new code that will be merged in the next release, but please, don't use it as the base branch for pull requests.
+Please, use `dev` as the base branch for your Pull Requests.
 
 ## Credits
 

docs/api/frontend.md

@@ -92,7 +92,7 @@ For standard usage you may just need to read [Customizing the link attributes](.
 
 You need this section only if you are going to override a `pagy_nav*` helper or a template AND you need to customize the HTML attributes of the link tags.
 
-**Important**: This method is not intended to be overridden, however you could just replace it in your overridden `pagy_nav*` helpers or templates with some generic helper like the rails `link_to`. If you intend to do so, be sure to have a very good reason, since using `pagy_link_proc` is a lot faster than the rails `link_to` (benchmarked at ~27x faster using ~13x less memory on a 20 links nav).
+**Important**: This method is not intended to be overridden, however you could just replace it in your overridden `pagy_nav*` helpers or templates with some generic helper like the rails `link_to`. If you intend to do so, be sure to have a very good reason, since using `pagy_link_proc` is a lot faster than the rails `link_to` (benchmarked at ~22x faster using ~18x less memory on a 20 links nav).
 
 **Warning**: This is a peculiar way to create page links and it works only for that purpose. It is not intended to be used for any other generic links to any URLs different than a page link.
 
@@ -166,7 +166,7 @@ Pagy is i18n ready. That means that all its strings are stored in the dictionary
 
 ### Pagy I18n implementation
 
-The pagy internal i18n implementation is ~12x faster and uses ~6x less memory than the standard `i18n` gem.
+The pagy internal i18n implementation is ~18x faster and uses ~10x less memory than the standard `i18n` gem.
 
 Since Pagy version 2.0, you can use it for both single-language and multi-language apps, with or without the `i18n` gem.
 

docs/assets/css/style.scss

@@ -57,7 +57,7 @@ h1 span {
   margin: 1.5em 0;
   white-space: nowrap;
   p {
-    margin: .2em 0;
+    margin: .1em 0;
   }
   p.indent1 {
     margin-left: 2rem;

docs/extras/i18n.md

@@ -7,7 +7,7 @@ title: I18n
 
 The `i18n` extra overrides the `pagy_t` method so it uses `I18n.t` implemented by the `i18n` gem.
 
-The `I18n.t` is ~12x slower and uses ~6x more memory than `pagy_t` so use it wisely.
+The `I18n.t` is ~18x slower and uses ~10x more memory than `pagy_t` so use it wisely.
 
 See also [I18n](../api/frontend.md#i18n).
 

lib/config/pagy.rb

@@ -114,7 +114,7 @@
 
 # I18n
 
-# Pagy internal I18n: ~12x faster using ~6x less memory than the i18n gem
+# Pagy internal I18n: ~18x faster using ~10x less memory than the i18n gem
 # See https://ddnexus.github.io/pagy/api/frontend#i18n
 # Notice: No need to use any of the following lines if you use the i18n extra below
 #
@@ -141,7 +141,7 @@
 #                  pluralize: lambda{|count| ... } )
 
 
-# I18n extra: uses the standard i18n gem which is ~12x slower using ~6x more memory
+# I18n extra: uses the standard i18n gem which is ~18x slower using ~10x more memory
 # than the default pagy internal i18n (see above)
 # See https://ddnexus.github.io/pagy/extras/i18n
 # require 'pagy/extras/i18n'

lib/pagy/frontend.rb

@@ -53,7 +53,7 @@ def pagy_get_params(params) params end
     MARKER = "-pagy-#{'pagy'.hash}-"
 
     # Returns a performance optimized proc to generate the HTML links
-    # Benchmarked on a 20 link nav: it is ~27x faster and uses ~13x less memory than rails' link_to
+    # Benchmarked on a 20 link nav: it is ~22x faster and uses ~18x less memory than rails' link_to
     def pagy_link_proc(pagy, link_extra='')
       p_prev, p_next = pagy.prev, pagy.next
       a, b = %(<a href="#{pagy_url_for(MARKER, pagy)}" #{pagy.vars[:link_extra]} #{link_extra}).split(MARKER, 2)
@@ -62,7 +62,7 @@ def pagy_link_proc(pagy, link_extra='')
                                                     else                           '' end } #{extra}>#{text}</a>" }
     end
 
-    # Similar to I18n.t: just ~12x faster using ~6x less memory
+    # Similar to I18n.t: just ~18x faster using ~10x less memory
     def pagy_t(path, vars={}) Pagy::I18n.t(@pagy_locale, path, vars) end
 
   end