small docs improvements

docs/api/backend.md

@@ -8,9 +8,10 @@ This module provides a _generic_ pagination method (`pagy`) that works out of th
 
 If you use also the `pagy-extras` gem, this module will get extended by a few _specific_ pagination methods, very convenient to use with _specific_ types of collections like Array, elasticsearch results, etc.
 
- __Notice__: Currently, the only available backend extra is the [array extra](../pagy-extras/array.md), but stay tuned, because there will be more in the near future.
+__Notice__: Currently, the only available backend extra is the [array extra](../pagy-extras/array.md), but stay tuned, because there will be more in the near future.
+
+_(see the [pagy-extras](../pagy-extras.md) doc for more details)_
 
-  _(see the [pagy-extras](../pagy-extras.md) doc for more details)_
 
 ## Synopsys
 
@@ -42,12 +43,21 @@ This is the main method of this module. It takes a collection object (e.g. a sco
 ```ruby
 @pagy, @records = pagy(Product.my_scope, some_option: 'get merged in the pagy object')
 ```
-Internally it calls the following sub-methods, in order to get the arguments needed to initialize the `Pagy` instance and to paginate the collection.
+The built-in `pagy` method is designed to be easy to customize by overriding any of the two sub-methods that it calls internally. You can independently change the default variables (`pagy_get_variables`) and/or the default page of items from the collection `pagy_get_items`).
+
+If you need to use multiple different types of collections in the same app or action, you may want to define some alternative and self contained custom `pagy` method.
 
+For example: here is a `pagy` method that doesn't call any sub-method, that may be enough for your app:
+```ruby
+def pagy_custom(collection, vars={})
+  pagy = Pagy.new(count: collection.count, page: params[:page], **vars)
+  return pagy, collection.offset(pagy.offset).limit(pagy.items)
+end
+```
 
 ### pagy_get_vars(collection)
 
-Sub-method called by the `pagy` method, it returns the hash of variables used to initialize the pagy object.
+Sub-method called only by the `pagy` method, it returns the hash of variables used to initialize the pagy object.
 
 Here is its source:
 
@@ -65,7 +75,7 @@ See also the [How To](../how-to.md) wiki page for some usage example.
 
 ### pagy_get_items(collection, pagy)
 
-Sub-method called by the `pagy` method, it returns the page items (i.e. the records belonging to the current page).
+Sub-method called only by the `pagy` method, it returns the page items (i.e. the records belonging to the current page).
 
  Here is its source (it works with most ORMs like `ActiveRecord`, `Sequel`, `Mongoid`, ...):
 
@@ -81,3 +91,4 @@ def pagy_get_items(array, pagy)
   array[pagy.offset, pagy.items]
 end
 ```
+__Notice__: in order to paginate arrays, you may want to use the `array` extra.

docs/how-to.md

@@ -54,6 +54,30 @@ You can also pass it as an instance variable to the `Pagy.new` method or to the
 @pagy, @records = pagy(Product.some_scope, items: 30)
 ```
 
+## Controlling the page links
+
+You can control the number and position of page links in the navigation through the `:size` variable. It is an array of 4 integers that specify which and how many page link to show.
+
+The default is `[1,4,4,1]`, which means that you will get `1` initial page, `4` pages before the current page, `4` pages after the current page, and `1` final page
+
+As usual you can set the `:size` variable as a global default by using the `Pagy::VARS` hash or pass it directly to the `pagy` method.
+
+The navigation links will contain the number of pages set in the variables:
+
+`size[0]`...`size[1]` current page `size[2]`...`size[3]`
+
+For example:
+
+```ruby
+pagy = Pagy.new count:1000, page: 10, size: [3,4,4,3] # etc
+pagy.series
+#=> [1, 2, 3, :gap, 6, 7, 8, 9, "10", 11, 12, 13, 14, :gap, 48, 49, 50]
+```
+
+As you can see by the result of the `series` method, you get 3 initial pages, 1 `:gap` (series interupted), 4 pages before the current page, the current `:page` (which is a string), 4 pages after the current page, another `:gap` and 3 final pages.
+
+You can easily try different options (also asymmetrical) in a console by changing the `:size`: just check the `series` array to see what it contains when used in combination with different core variables.
+
 ## Paginate Any Collection
 
 Pagy doesn't need to know anything about the kind of collection you paginate, it doesn't need to "teach" it how to paginate itself by adding code to it: pagy just needs to know its count.
@@ -120,32 +144,6 @@ That will explicitly set the `:page` variable, overriding the `params[:page]` de
 
 __Notice__: If you need to get the page number from another param or in some different way, just override the `pagy_get_vars` method right in your controller.
 
-
-## Controlling the page links
-
-You can control the number and position of page links in the navigation through the `:size` variable. It is an array of 4 integers that specify which and how many page link to show.
-
-The default is `[1,4,4,1]`, which means that you will get `1` initial page, `4` pages before the current page, `4` pages after the current page, and `1` final page
-
-As usual you can set the `:size` variable as a global default by using the `Pagy::VARS` hash or pass it directly to the `pagy` method.
-
-The navigation links will contain the number of pages set in the variables:
-
-`size[0]`...`size[1]` current page `size[2]`...`size[3]`
-
-For example:
-
-```ruby
-pagy = Pagy.new count:1000, page: 10, size: [3,4,4,3] # etc
-pagy.series
-#=> [1, 2, 3, :gap, 6, 7, 8, 9, "10", 11, 12, 13, 14, :gap, 48, 49, 50]
-```
-
-As you can see by the result of the `series` method, you get 3 initial pages, 1 `:gap` (series interupted), 4 pages before the current page, the current `:page` (which is a string), 4 pages after the current page, another `:gap` and 3 final pages.
-
-You can easily try different options (also asymmetrical) in a console by changing the `:size`: just check the `series` array to see what it contains when used in combination with different core variables.
-
-
 ## Using the pagy_nav* helpers
 
 These helpers take the pagy object and returns the HTML string with the pagination links, which are wrapped in a `nav` tag and are ready to use in your view. For example: