README.md in fcrepo_admin-0.5.3 vs README.md in fcrepo_admin-0.5.4

@@ -63,14 +63,16 @@
 
 ```ruby
 module BlacklightHelper
   include Blacklight::BlacklightHelperBehavior  # Default Blacklight behaviors
   include FcrepoAdmin::Helpers::BlacklightHelperBehavior # fcrepo_admin overrides
-  # additional customizations here, if any
 end
 ```
 
+If you have an existing custom blacklight helper module, simply include `FcrepoAdmin::Helpers::BlacklightHelperBehavior`
+*after* `Blacklight::BlacklightHelperBehavior`.
+
 **Add audit trail support** (optional)
 
 To enable access to the Fedora audit trail data through the fcrepo_admin UI, include the 
 `ActiveFedora::Auditable` mixin in your ActiveFedora models:
 
@@ -176,10 +178,26 @@
     alias_action :my_method, :to => :read
   end
 end
 ```  
 
+#### Associations
+
+Due to issues with Rails partials and relative paths, in order to use Blacklight's default document index view behavior
+on the associations show page and avoid missing template errors, fcrepo_admin provides a custom document partial at 
+`fcrepo_admin/catalog/document` that renders the partial at `catalog/document`, for which Blacklight provides a default.
+If you have a custom document partial at a different path that you want to use for the document list on the associations 
+show page, you *may* be able to simply copy it to `app/views/fcrepo_admin/catalog/document`, or you might try putting 
+this content in that file:
+
+```
+<%= render :partial => 'path/to/my/document', :locals => { :document => document, :document_counter => document_counter } %>
+```
+
+replacing the partial path as appropriate.  If anyone has a better solution or knows of a way to avoid providing the 
+document partial in fcrepo_admin admin, please submit a pull request.
+
 #### Read-only mode
 
 To suppress mutating behaviors (i.e, routes, nav items, etc.) regardless of user permissions, 
 add this configuration setting:
 
@@ -189,9 +207,37 @@
 
 ### Internationalization (i18n)
 
 An effort has been made to support i18n on headings, menus, etc.  See https://github.com/projecthydra/fcrepo-admin/blob/master/config/locales/fcrepo_admin.en.yml
 for the keys and consult the Rails documentation on how to provide your own translations or alternate text values.
+
+### Known Issues
+
+#### Pagination
+
+Kaminari as of version 0.14.1 does not support namespace-prefixed routes, which causes a routing error in Blacklight's 
+`paginate_rsolr_response` helper when called from within fcrepo_admin.  In place of `paginate_rsolr_response` fcrepo_admin
+use its own helper `safe_paginate_rsolr_response` which provides a basic set of pagination links without using Kaminari.  
+
+There is (as of 2013-05-24) an outstanding Kaminari pull request which resolves the routing issue (https://github.com/amatsuda/kaminari/pull/322).
+You can implement this solution by adding to your application's Gemfile:
+
+```
+gem 'kaminari', github: 'harai/kaminari', branch: 'route_prefix_prototype'
+```
+
+and then override the `safe_paginate_rsolr_response` helper with something like:
+
+```ruby
+def safe_paginate_rsolr_response(response)
+  paginate_rsolr_response response, :outer_window => 2, :theme => 'blacklight', :route_set => fcrepo_admin
+end
+```
+
+the key part being the `:route_set` option -- note that the value is not a string -- with gets passed through to Kaminari.
+
+If Kaminari is suitably patched in the future, we will likely remove `safe_paginate_rsolr_response` in favor of
+`paginate_rsolr_response`.
 
 ### Contributing
 
 * Consider first posting to [e-mail] with a question or bug report, or submit an issue
   to the Github issue tracker at https://github.com/projecthydra/fcrepo-admin/issues.