blacklight 4.6.3 → 4.7.0.pre1

data/doc/Internationalization.md

@@ -0,0 +1,32 @@
+Blacklight uses the [Rails i18n framework|http://guides.rubyonrails.org/i18n.html] to provide a translatable (or, application customized) version of most text in the Blacklight default templates. Blacklight ships with a set of English translations (other languages welcome!) in [blacklight.en.yml|https://github.com/projectblacklight/blacklight/blob/master/config/locales/blacklight.en.yml].
+
+You can also customize the English strings in your local application, which will override the Blacklight-distributed strings.
+
+## A quick i18n example
+A locale entry that looks like this:
+
+```yaml
+en:
+  blacklight:
+    application_name: 'Blacklight'
+```
+
+Is referenced in the Blacklight code as:
+
+```ruby
+I18n.t 'blacklight.application_name'
+# OR
+t('blacklight.application_name')
+```
+
+You could override this in your application's ```config/locales/en.yml```:
+
+```yaml
+en:
+  blacklight:
+    application_name: 'My Blacklight Application'
+```
+
+And then everywhere Blacklight views show the application name, it will use your label ("My Blacklight Application") instead of ours ("Blacklight").
+
+There are other i18n tricks (that we use) covered in the [Rails i18n Rails guide|http://guides.rubyonrails.org/i18n.html], including pluralization, interpolation, etc.

data/doc/JSON-API.md

@@ -0,0 +1,17 @@
+Feature added in v4.5
+
+By default the search page, the show page, and the facet list page can return JSON responses provided you set the format suffix:
+
+Search results
+`/catalog.json?search_field=all_fields&q=auckland`
+
+Facet list
+`/catalog/facet/subject_topic_facet.json`
+
+Single record
+`/catalog/2009002600.json`
+
+
+If you wish to alter the format of the returned JSON, you can override `render_search_results_as_json` and `render_facet_list_as_json` methods in CatalogController.
+
+See: https://github.com/projectblacklight/blacklight/blob/master/lib/blacklight/catalog.rb#L175-L191

data/doc/Pagination.md

@@ -0,0 +1,51 @@
+Blacklight uses [kaminari](https://github.com/amatsuda/kaminari) for providing pagination of Solr responses. 
+
+One motivation for this is so a pagination view theme can be provided that you can use for your custom code with ordinary ActiveRecord or anything else kaminari can handle, to have consistency between the rest of your app's pagination and Blacklight's Solr response pagination. 
+
+## How it works
+
+The Blacklight #paginate_params helper method takes an RSolr::Response, and converts it to something Kaminari #paginate can handle. (Basically just by translating some attribute names). So you could call:
+
+    paginate( paginate_params(@response) )  # where @response is an RSolr::Response
+
+But there's a shortcut Blacklight helper method which compacts this, #paginate_rsolr_response:
+
+    paginate_rsolr_response @response, :theme => 'blacklight'
+
+The `theme => 'blacklight'` part will be passed through kaminari, and tell kaminari to use the theme that the Blacklight plugin supplies at [app/views/kaminari/blacklight](https://github.com/projectblacklight/blacklight/tree/master/app/views/kaminari/blacklight)
+
+Any other arguments of ordinary kaminari paginate can also be passed in there. If all client code uses #paginate_solr_response, it also provides a 'hook' for local apps to completely over-ride pagination rendering, perhaps not even using kaminari. 
+
+Additionally, we sometimes want to output a "Showing X through Y of N" message, which kaminari doesnt' have a way to do by default, so we just provide our own way in a Blacklight view helper method, which takes a RSolr::Response too:
+
+    render_pagination_info(@response)
+
+## Changing the kaminari theme
+
+If you want to change how pagination links are rendered, the easiest/cleanest thing to do is to over-ride the 'blacklight' theme that the Blacklight plugin defines. Copy the view templates in Blacklight source at app/views/kaminari/blacklight to your own local app/views/kaminari/blacklight.  You actually only need to copy files you'll want to modify, templates not overridden with a local copy will still be found by kaminari from the Blacklight gem.  You can use any techniques available for creating a kaminari theme when editing these files, including over-riding more kaminari view templates if available. See the kaminari documentation. 
+
+There are other ways you could change how Blacklight pagination renders, but by doing it this way, any code (in core Blacklight or additional plugins you install) that tries to render pagination using kaminari with 'blacklight' theme will get your locally defined theme. 
+
+The "pagination info" (showing X through Y of N) is not part of the kaminari theme, but just a blacklight view helper method, #render_pagination_info.  To change this, just over-ride this method [[over-ride locally|CUSTOMIZING]] like any other Blacklight view helper method. 
+
+## Using kaminari theme for your own pagination
+
+Your local app may show pagination of ActiveRecord objects, that you'd like to appear consistent with other Blacklight pagination. Just use kaminari to show the pagination HTML, with the theme :blacklight.  This technique can be used for anything kaminari can paginate, such as Mongoid et al, in addition to ActiveRecord. Fetch the ActiveRecords using ordinary kaminari techniques (see kaminari docs) and then:
+
+    paginate @my_active_records, :theme => 'blacklight'
+
+That's it. There's currently no great way to display the #render_pagination_info for anything but RSolr::Response. 
+
+## Changing the default kaminari pagination options
+
+Sometimes you you just want to tweak a few things with pagination and it doesn't require crawling into the RSolr response or creating a kaminari theme. Here's how you do that.
+
+First, generate the kaminari config initializer:
+
+    rails g kaminari:config
+
+You will get a file in config/initializers/kaminari_config.rb that is mostly commented out.  The config options are mostly self-explanatory, but let's say that you don't like that Blacklight gives you 4 pages of links on either side of the current page.  Uncomment: 
+
+    # config.window = 4
+
+and change 4 to whatever number is preferable. More information on the kaminari general configuration options is available here: https://github.com/amatsuda/kaminari#general-configuration-options

data/doc/Providing-your-own-view-templates.md

@@ -0,0 +1,109 @@
+> TODO: Validate this page for Blacklight 4.x!
+
+# Customizing the User Interface
+## Layouts 
+
+The built-in Blacklight controllers all by default use a Rails view layout called "blacklight", that lives in the Blacklight source. This ends up being a bit confusing, but is the best way we have at present to have out of the box default using a layout with full functionality, without stepping on a possibly existing local 'application' layout. 
+
+To change what layout the Blacklight controllers use, simply implement a method #layout_name in your local application_controller.rb that returns the name of the layout you'd like them to use. 
+
+```ruby
+# [from app/controllers/application_controller.rb]
+class ApplicationController < ActionController::Base
+  ...
+    def layout_name
+       "application"
+    end
+  ...
+end
+```
+
+When implementing your own layout instead of using the stock one, you may want to look at the Blacklight app/views/layouts/blacklight.html.erb file to see what helper methods are called there, to maintain full Blacklight functionality you may want to call these same helper methods. 
+
+* `render_head_content` renders content within the
+  html `<head>` tag, which includes document-specific alternative
+formats as well as tags generated by plugins, etc.
+* `sidebar_items` renders features including sidebar content, e.g. facet
+  lists.
+* flash messages
+* user util links
+
+## Overriding Views (templates and partials)
+As a Rails Engine, you can easily override views in your app. You can see what views and partials are provided by looking in `[[./app/views|https://github.com/projectblacklight/blacklight/tree/master/app/views]]` inside the Blacklight source.
+
+Once you find the view you'd like to change, you should create a file with the same name and relative path in your own application (e.g. if you wanted to override [[./app/views/catalog/_show_partials/_default.html.erb|https://github.com/projectblacklight/blacklight/blob/master/app/views/catalog/_show_partials/_default.html.erb]] you would create ./app/views/catalog/_show_partials/_default.html.erb in your local application. Frequently, you will start by copying the existing Blacklight view and modifying it from there.
+
+It is generally recommended that you override as little as possible, in order to maximize your forward compatibility. Look to override either a small, focused partial template, or a helper method of partial template called from a larger template, so your application's version can call out to those same helpers or partial templates within blacklight core code. 
+
+## Overriding the CatalogController
+Overriding the Blacklight `CatalogController` implementation is easy, and the skeleton of the `CatalogController` is generated into your application for you when you install Blacklight. 
+
+See the [[Extending or Modifying Blacklight Search Behavior]] for tips and approaches to customizing the catalog.
+
+## Overriding Other Controllers
+
+1. Find the controller you're interested in blacklight's app/controllers/  . 
+2. Create a file with the same name in your local app/controllers. 
+3. This file requires the original class, and then re-opens it to add more methods.
+ 
+```ruby
+require "#{Blacklight.controllers_dir}/some_controller"
+
+class SomeController < ApplicationController
+   # custom code goes here
+end
+```
+
+In that "custom code goes here", you can redefine certain methods (action methods or otherwise) to do something different.  You can also add new methods (again action methods or otherwise), etc. 
+
+It's kind of hard to call 'super' to call original functionality: 
+
+* the ruby language features here make 'super' unavailable, although you can work around that confusingly with the rails #alias_method_chain method. 
+* but more importantly, action methods in particular don't really suit themselves to being over-ridden and called by super, because the original implementation often does something you'd want to change but there's no easy way to 'undo' -- calling 'render', which can only be called once. 
+
+So basically, if you find yourself wanting to access some functionaltiy in the original implementation of a method that you also want to over-ride -- the best solution is probably to refactor Blacklight core code to put that functionality in a subsidiary method, so you can over-ride the action method entirely but call that logic from core.  Action methods should be short and sweet anyway. 
+
+
+## Custom View Helpers
+
+(This is accurate for Blacklight 3.1.1 and subsequent. Before that, things were messier). 
+
+One of the most common things you might need to do is create a view helper -- especially to override some Blacklight behavior implemented in it's own view helpers. The first step is looking at Blacklight source to determine what view helper method you want to override. 
+
+Blacklight comes packaged with several view helper modules. There is a BlacklightHelper in (blacklight source) app/helpers/blacklight_helper.rb , and several others that correspond to specific controller. (Note, depending on version of Rails and configuration, all helpers may get loaded for every request, even ones that are named to correspond only to a particular other controller). 
+
+If you simply created a local helper with the same name as a helper in Blacklight, that will end up preventing the Blacklight helper from being loaded at all though, which is not what you want to do to override. 
+
+We've structured each Blacklight view helper module into two parts to make it easy to selectively over-ride methods. For instance, here's Blacklight's app/helpers/blacklight_helper.rb:
+
+```ruby
+module BlacklightHelper
+  include Blacklight::BlacklightHelperBehavior
+end
+```
+
+Now, the actual methods will be found in app/helpers/blacklight/blacklight_helper_behavior.rb instead. 
+
+If you want to over-ride a helper method, copy the wrapper blacklight_helper into your local app, with the 'include' line, and now you can individually over-ride methods from BlacklightHelperBehavior, and the other methods you don't over-ride will still have their default implementation. 
+
+YOUR `app/helpers/blacklight_helper.rb`
+
+```ruby
+module BlacklightHelper
+  include Blacklight::BlacklightHelperBehavior
+
+  def application_name
+    "Bestest University Search"
+  end
+end
+```
+
+One helper you might want to over-ride for customization is #render_document_partial (currently defined in [[blacklight_helper|https://github.com/projectblacklight/blacklight/blob/master/app/helpers/blacklight_helper.rb]]), which you can over-ride to choose differnet local partial views to display a document on search results or detail page, possibly varying depending on type of document according to your own local logic. 
+
+## Adding in your own CSS or Javascript
+
+Within your local application, you can use the [[Rails Asset Pipeline|http://guides.rubyonrails.org/asset_pipeline.html]] to manipulate javascript and css documents.
+
+**todo??** better instructions for over-riding BL's built in CSS using SASS? (jrochkind thought jamesws wrote such already, but can't find them now)
+
+The Blacklight generator added a file to your app at `./app/assets/stylesheets/blacklight_themes/standard.css.scss`, elements of the BL default theme can be customized or over-ridden there. If there's something you want to do but aren't sur e the best way, feel free to ask on the listserv. 

data/doc/Quickstart.md

@@ -0,0 +1,115 @@
+Blacklight is a Ruby on Rails Engine plugin, meaning it provides a small application that runs inside an existing Ruby on Rails project.  For notes on upgrading Blacklight, check out our [[Release Notes And Upgrade Guides]] index.
+
+This Quickstart will walk you through installing Blacklight and Solr, and indexing a sample set of records. If you want information about configuring Blacklight to use an existing Solr index with your data in it, see the [[Blacklight configuration]] document.
+
+## Pre-requisites
+ * Ruby 1.9 or higher (consider using [[RVM|https://rvm.beginrescueend.com/rvm/install/]] or [[RBEnv|http://rbenv.org/]] to manage your Ruby version). 
+ * Java 1.5 or higher (in order to run solr under a java servlet container)
+ * **For Windows users**: You may want to use [RailsInstaller](http://railsinstaller.org/) to get a Ruby on Rails environment.
+
+> NOTE: We run our continuous integration tests against Ruby 1.9.3, Ruby 2.0 and JRuby (running in 1.9 mode) using the latest release of Rails on a Redhat Linux machine. While Blacklight may work with older versions of Ruby, we can't commit ourselves to supporting them.
+
+In addition, you should have the Bundler and Rails ruby gems installed:
+
+```bash
+$ gem install bundler
+$ gem install rails
+```
+
+## Install and Use
+
+1. Create a new rails 3 application
+
+    ```bash
+    $ rails new my_app      
+    #      create  
+    #      create  README
+    #      create  Rakefile
+    #      create  config.ru
+    #      create  .gitignore
+    #      create  Gemfile
+    #      [...]
+
+    $ cd my_app
+    ```
+
+    Rails automatically created an `public/index.html` file. However, Blacklight will provide a default `root` route for your application, so you probably want to remove it:
+
+    ```bash
+    $ rm public/index.html
+    ```
+
+2. Append this line to your application's `Gemfile`
+
+    ```ruby
+    gem 'blacklight'
+    ```
+
+    Especially if you are running on Linux, you may have to add `gem 'therubyracer'` to your gemfile, to get a Javascript runtime needed by the asset pipeline. 
+
+    then, update the bundle
+
+    ```bash
+    $ bundle install
+    ```
+
+3. Install blacklight using Devise for user authentication: 
+
+    ```bash
+    $ rails generate blacklight --devise
+    ```
+    If you would prefer to integrate with an alternative user authentication provider, see the [[User Authentication]] documentation. You can also install with no support for logged in users simply by omitting the devise install, and generating blacklight with `rails generate blacklight` (no --devise argument).
+
+4. Run your database migrations to create Blacklight's database tables:
+
+    ```bash
+    $ rake db:migrate
+    ```
+
+5. You will need to install and configure Solr. You can install
+Blacklight's example Solr configuration (using the jetty servlet container) that is configured to work with
+the Blacklight defaults:
+
+    ```bash
+    $ rails generate blacklight:jetty
+    ```
+
+    **For Windows Users: ** This step will only work on *nix platforms. You can manually download and extract a tagged version of [blacklight-jetty](https://github.com/projectblacklight/blacklight-jetty/tags). After extracting the file, you need to update the `config/jetty.yml` file to add the `jetty_home` key to your test environment, e.g.:
+
+    ```yaml
+test:
+  jetty_port: <%= ENV['TEST_JETTY_PORT'] || 8888 %> 
+  jetty_home: <%= ENV['TEST_JETTY_PATH'] || File.join(Rails.root, 'test_jetty') %>
+  startup_wait: 15
+    ```
+
+
+6.  Make sure your Solr server is running. If you installed the Blacklight demo Solr/Jetty package, you can start the Jetty/Solr server using:
+
+    ```bash
+    $ cd jetty; java -jar start.jar &
+    ```
+
+6. Index some data. You can index test MARC records provided Blacklight running:
+
+    ```bash
+    $ rake solr:marc:index_test_data
+    ```
+
+7. Start up your application
+
+    ```bash
+    $ rails server
+    ```
+
+Visit the catalog at [[http://localhost:3000/catalog]]. 
+
+[[https://github.com/projectblacklight/projectblacklight.github.com/raw/master/images/home.png|frame|alt=Blacklight home page]]
+
+You should see the Blacklight interface with 30 MARC records for testing. Additional MARC records are available from the [[blacklight-data|https://github.com/projectblacklight/blacklight-data]] repository. These can be ingested into Solr using SolrMarc, 
+
+```bash
+$ rake solr:marc:index MARC_FILE=(path to file)
+```
+
+See [[Configuring and Customizing Blacklight]] for information about how to customize the Blacklight user interface, search experience, and more.

data/doc/README_SOLR.md

@@ -0,0 +1,245 @@
+#Solr in Blacklight
+
+##Setting up Solr
+
+Blacklight uses Solr as its "search engine". 
+More information about Solr is available at the Solr web site ( http://lucene.apache.org/solr/)
+
+There are three sections to this document:
+* Getting Solr
+* Configuring Solr
+  * schema.xml
+  * solrconfig.xml
+* SolrMARC
+
+### Getting Solr
+Blacklight distributes a pre-configured version of Solr (with the Jetty
+container) as [[blacklight-jetty|https://github.com/projectblacklight/blacklight-jetty/tags]].
+
+You can also use an existing Solr index (with some minor modifications).
+If you want to start from a new version of Solr, follow the directions from the [[Solr tutorial|http://lucene.apache.org/solr/tutorial.html]]
+
+You should now have a usable copy of Solr.
+
+### Configuring Solr
+####Solr Schema.xml
+
+Between the `schema.xml` and `solrconfig.xml` you can change and tune the search behavior following directions from the [[Solr wiki|http://wiki.apache.org/solr/]]. Solr comes with example schema and solrconfig files, which you can use as a starting point for configuring your local Solr application.
+
+Blacklight expects a uniqueKey field within your Solr index,
+traditionally called `id`. The name of the unique key field can be
+configured in your application's `SolrDocument`.
+
+##### Blacklight community "best practices"
+
+Solr uses a schema.xml file to define document fields (among other things). These fields store data for searching and for result display. You can find the example/solr/conf/schema.xml file in the Solr distribution you just downloaded and uncompressed.
+
+Documentation about the Solr schema.xml file is available at (http://wiki.apache.org/solr/SchemaXml).
+
+  The default schema.xml file comes with some preset fields made to work with
+  the example data. If you don't already have a schema.xml setup, we 
+  recommend using a simplified "fields" section like this:
+```xml  
+	<fields>
+		<field name="id" type="string" indexed="true" stored="true" required="true" />
+		<field name="text" type="text" indexed="true" stored="false" multiValued="true"/>
+		<field name="timestamp" type="date" indexed="true" stored="true" default="NOW" multiValued="false"/>
+		<field name="spell" type="textSpell" indexed="true" stored="true" multiValued="true"/>
+		<dynamicField name="*_i"  type="sint"    indexed="true"  stored="true"/>
+		<dynamicField name="*_s"  type="string"  indexed="true"  stored="true" multiValued="true"/>
+		<dynamicField name="*_l"  type="slong"   indexed="true"  stored="true"/>
+		<dynamicField name="*_t"  type="text"    indexed="true"  stored="true" multiValued="true"/>
+		<dynamicField name="*_b"  type="boolean" indexed="true"  stored="true"/>
+		<dynamicField name="*_f"  type="sfloat"  indexed="true"  stored="true"/>
+		<dynamicField name="*_d"  type="sdouble" indexed="true"  stored="true"/>
+		<dynamicField name="*_dt" type="date"    indexed="true"  stored="true"/>
+		<dynamicField name="random*" type="random" />
+		<dynamicField name="*_facet" type="string" indexed="true" stored="true" multiValued="true" />
+		<dynamicField name="*_display" type="string" indexed="false" stored="true" />
+	</fields>
+```
+
+  Additionally, replace all of the tags after the "fields" section, and before 
+  the `</schema>` tag with this:
+
+```xml  
+	<uniqueKey>id</uniqueKey>
+	<defaultSearchField>text</defaultSearchField>
+	<solrQueryParser defaultOperator="OR"/>
+	<copyField source="*_facet" dest="text"/>
+```
+
+  Now you have a basic schema.xml file ready. Other fields can be specified, including a primary document title (`title_display`) and format (`format`), but these are easily configured in your application's `CatalogController`.
+
+  Fields that are "indexed" are searchable.
+
+  Fields that are "stored" are can be viewed/displayed from the Solr search 
+  results. 
+
+  The fields with asterisks ('*') in their names are "dynamic" fields. These 
+  allow you to create arbitrary tags at index time. 
+
+  The *_facet field can be used for creating your facets. When you index, 
+  simply define a field with _facet on the end:
+    category_facet
+
+  The *_display field can be used for storing text that doesn't need to be 
+  indexed. An example would be the raw MARC for a record's detail view:
+    raw_marc_display
+
+  For text that will be queried (and possibly displayed), use the *_t type 
+  field for tokenized text (text broken into pieces/words) or the *_s type 
+  for queries that should exactly match the field contents:
+    description_t
+    url_s
+
+  The Blacklight application is generic enough to work with any Solr schema, but to
+  manipulate the search results and single record displays, you'll need to know the 
+  stored fields in your indexed documents.
+
+  For more information, refer to the Solr documentation: 
+    http://wiki.apache.org/solr/SchemaXml
+
+
+#####solrconfig.xml
+
+Solr uses the solrconfig.xml file to define searching configurations, set cache options, etc. 
+You can find the examples/solr/conf/solrconfig.xml in the distribution directory you just uncompressed.
+
+Documentation about the solrconfig.xml file is available at (http://wiki.apache.org/solr/SolrConfigXml).
+
+Blacklight expects two request handlers to be defined -- one to handle
+general search requests and one to handle single-document lookup. The
+names of these request handlers are configurable, but are called
+"search" and "document" respectively, out of the box.
+
+
+#####Solr Search Request Handlers
+
+  When Blacklight does a collection search, it sends a request to a Solr 
+  request handler named "search". The most important settings in this handler 
+  definition are the "fl" param (field list) and the facet params.
+
+  The "fl" param specifies which fields are returned in a Solr response.
+  The facet related params set up the faceting mechanism.
+
+  Find out more about the basic params: 
+     http://wiki.apache.org/solr/DisMaxRequestHandler
+  
+  Find out more about the faceting params: 
+    http://wiki.apache.org/solr/SimpleFacetParameters
+
+
+######How the "fl" param works in Blacklight's request handlers
+
+  Blacklight comes with a set of "default" views for rendering each document 
+  in a search results page. This view simply loops through all of the fields 
+  returned in each document in the Solr response. The "fl" (field list) param
+  tells Solr which fields to include in the documents in the response ... 
+  and these are the fields rendered in the Blacklight default views.  
+  Thus, the fields you want rendered must be specified in "fl".  Note that 
+  only "stored" fields will be available;  if you want a field to be rendered 
+  in the result, it must be "stored" per the field definition in schema.xml.
+
+  The "fl" parameter definition in the "search" handler looks like this:
+  ```xml
+    <str name="fl">id,score,author_display,(....lots of other fields)</str>
+  ```  
+  You may also use an asterisk plus "score":
+  ```xml
+    <str name="fl">*,score</str>
+  ```  
+
+######How the facet params work in Blacklight's request handlers
+
+  In the search results view, Blacklight will look into the Solr response for 
+  facets. If you specify any facet.field params in your "search" handler, 
+  they will automatically get displayed in the facets list:
+  ```xml
+    <str name="facet.field">format</str>
+    <str name="facet.field">language_facet</str>
+  ```  
+
+
+#####Blacklight's "search" request handler: for search results
+
+  When Blacklight displays a list of search results, it uses a Solr request 
+  handler named "search." Thus, the field list (fl param) for the "search"
+  request handler should be tailored to what will be displayed in a search
+  results page.  Generally, this will not include fields containing a large
+  quantity of text.  The facet param should contain the facets to be 
+  displayed with the search results.
+  ```xml
+
+	<requestHandler name="search" class="solr.SearchHandler" >
+		<lst name="defaults">
+			<str name="defType">dismax</str>
+			<str name="echoParams">explicit</str>
+			<!-- list fields to be returned in the "fl" param -->
+			<str name="fl">*,score</str>
+			
+			<str name="facet">on</str>
+			<str name="facet.mincount">1</str>
+			<str name="facet.limit">10</str>
+			
+			<!-- list fields to be displayed as facets here. -->
+		    <str name="facet.field">format</str>
+		    <str name="facet.field">language_facet</str>
+			
+			<str name="q.alt">*:*</str>
+		</lst>
+	</requestHandler>
+   ```
+
+#####Blacklight's "document" request handler:  for a single record
+
+  When Blacklight displays a single record it uses a Solr request handler 
+  named "document".  The "document" handler doesn't necessarily need to be 
+  different than the "search" handler, but it can be used to control which 
+  fields are available to display a single document. In the example below, 
+  there is no faceting set (facets are not displayed with a single record) 
+  and the "rows" param is set to 1 (since there will only be a single record).
+  Also, the field list ("fl" param) could include fields containing large
+  text values if they are desired for record display. Is is acceptable to
+  include large amounts of data, because this handler should only be used 
+  to query for one document:
+
+	<requestHandler name="document" class="solr.SearchHandler">
+		<lst name="defaults">
+			<str name="echoParams">explicit</str>
+			<str name="fl">*</str>
+			<str name="rows">1</str>
+			<str name="q">{!raw f=id v=$id}</str>
+			<!-- use id=blah instead of q=id:blah -->
+		</lst>
+	</requestHandler>
+	
+  A Solr query for a single record might look like this:
+   http://(yourSolrBaseUrl)/solr/select?id=my_doc_id&qt=document
+
+
+####Blacklight Solr Schema and Solrconfig File Templates
+
+Blacklight provides schema.xml and solrconfig.xml files as starting points:
+
+  https://github.com/projectblacklight/blacklight-jetty/blob/master/solr/blacklight-core/conf/schema.xml
+
+  https://github.com/projectblacklight/blacklight-jetty/blob/master/solr/blacklight-core/conf/solrconfig.xml
+
+#SolrMARC:  from Marc data to Solr documents
+
+The SolrMARC project is designed to create a Solr index from raw MARC data.  
+It can be configured easily and used with the basic parsing and indexing 
+supplied.  It is also readily customized for a site's unique requirements.
+
+The project software and documentation is available at [[http://code.google.com/p/solrmarc]]
+
+Blacklight comes with an embedded SolrMarc, with some default config that matches the default Blacklight setup, and provides some rake tasks to easily index docs with SolrMarc according to your app's environment.  There is no need to manually install/configure SolrMarc yourself.  From your application's home directory simply run:
+```bash
+  rake solr:marc:index:info
+```
+to see options.  Run `rake solr:marc:index` to actually do indexing. Like all rake tasks, by default this will use your 'development' environment; add "RAILS_ENV=production" to instead index to the solr you've labelled production in your config/solr.yml file. 
+
+The solrmarc config files are in your app's config/SolrMarc directory, you can edit them there for local config. 
+
+If you'd like to use a different or more recent version of SolrMarc.jar, you can put it in your app at ./solr_marc/SolrMarc.jar, and the built-in rake tasks will use your local SolrMarc.jar instead of the one bundled with Blacklight.