+=head1 STRUCTURE OF PAGES
+
+The returned hashref will have the following structure:
+
+ { per_page => 20, # how many entries per page
+ max => 5, # number of the last page
+ page => 2, # number of the current page
+ common => [ # an array of hashes for each page
+ ...,
+ { active => 1, # set if this is the active page
+ page => 2, # the string to display for this page
+ visible => 1, # should this be displayed in the paginating controls
+ },
+ ...
+ ]
+ }
+
+You may assume that C<page> is sanitized to be within 1..C<max>.
+
+The common list is kept arbitrary by design, so that the algorithm to display
+the paginating controls can be changed by solely changing the
+C<make_common_pages> algorithm. If you need different glyphs for the pages or
+different boundaries, translate the C<page> entry for the page.
+
+The initial algorithm will show the following pages:
+
+=over 4
+
+=item *
+
+1, 2, 3
+
+=item *
+
+Last page
+
+=item *
+
+Current page +/- 5 pages
+
+=item *
+
+Current page +/- 10, 50, 100, 500, 1000, 5000
+
+=back
+