om 1.2.4 → 1.2.5

data/.gitignore

@@ -0,0 +1,25 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+/.bundle
+doc
+.yardoc
+
+## PROJECT::SPECIFIC
+

data/.rvmrc

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+ruby_string="ree-1.8.7"
+gemset_name="om"
+
+# Install rubies when used instead of only displaying a warning and exiting
+rvm_install_on_use_flag=1
+
+# Specify our desired <ruby>[@<gemset>], the @gemset name is optional.
+environment_id="${ruby_string}@${gemset_name}"
+
+# First, attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+#
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]] ; then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create "$environment_id"
+fi
+
+# Ensure that Bundler is installed, install it if it is not.
+if ! (command -v bundle > /dev/null) ; then
+  printf "The rubygem 'bundler' is not installed, installing it now.\n"
+  gem install bundler
+fi
+

data/COMMON_OM_PATTERNS.textile

@@ -0,0 +1,14 @@
+h1. Common Patterns You'll Use with OM
+
+h2. Common Terminology Patterns
+
+h3. Reserved method names (ie. id_, root_)
+
+Like Nokogiri ...
+
+h3. Namespaces
+oxns
+document namespaces & node namespaces
+_no namespace_ (suppressing oxns in xpath queries)
+
+h3. :ref and :proxy Terms

data/GETTING_FANCY.textile

@@ -0,0 +1,143 @@
+h1. Getting Fancy
+
+
+
+h2. Alternative ways to Manipulate Terms, Terminologies and their Builders
+
+h3. The Example
+
+There are a few ways to build a terminology.  The simplest way is to use the Terminology Builder block syntax.  This is what most of the tutorials use.  
+
+In the following examples, we will show different ways of building this Terminology:
+
+<pre>
+  builder = OM::XML::Terminology::Builder.new do |t|
+    t.root(:path=>"grants", :xmlns=>"http://yourmediashelf.com/schemas/hydra-dataset/v0", :schema=>"http://example.org/schemas/grants-v1.xsd")
+    t.grant {
+      t.org(:path=>"organization", :attributes=>{:type=>"funder"}) {
+        t.name(:index_as=>:searchable)
+      }
+      t.number
+    }
+  end
+  another_terminology = builder.build
+</pre>
+
+
+h3. Using Term::Builders
+
+First, create the Terminology Builder object.
+
+<pre>
+  terminology_builder = OM::XML::Terminology::Builder.new
+</pre>
+
+The .root method handles creating the root term and setting namespaces, schema, etc on the Terminology
+
+<pre>
+  terminology_builder.root(:path=>"grants", :xmlns=>"http://yourmediashelf.com/schemas/hydra-dataset/v0", :schema=>"http://example.org/schemas/grants-v1.xsd")
+</pre>
+
+As you can see, this sets the namespaces for you and created the "grants" root term.
+
+<pre>
+  terminology_builder.namespaces
+   => {"oxns"=>"http://yourmediashelf.com/schemas/hydra-dataset/v0", "xmlns"=>"http://yourmediashelf.com/schemas/hydra-dataset/v0"}
+  terminology_builder.term_builders
+</pre>
+
+Create Term Builders for each of the Terms
+
+<pre>
+  term1_builder = OM::XML::Term::Builder.new("grant", terminology_builder).path("grant")
+  subterm1_builder = OM::XML::Term::Builder.new("org", terminology_builder).attributes(:type=>"funder")
+  subsubterm_builder = OM::XML::Term::Builder.new("name", terminology_builder).index_as(:searchable)
+  subterm2_builder = OM::XML::Term::Builder.new("number", terminology_builder)
+</pre>
+
+Assemble the tree of Term builders by adding child builders to their parents, then add those to the Terminology builder.
+
+<pre>
+  subterm1_builder.add_child(subsubterm_builder)
+  term1_builder.add_child(subterm1_builder)
+  term1_builder.add_child(subterm2_builder)
+  terminology_builder.term_builders["grant"] = term1_builder
+</pre>
+
+Now build the Terminology, which will also call .build on each of the Term Builders
+
+<pre>
+  built_terminology = terminology_builder.build
+</pre>
+
+Test it out:
+
+<pre>
+  built_terminology.retrieve_term(:grant, :org, :name)
+  built_terminology.xpath_for(:grant, :org, :name)
+  built_terminology.root_terms
+  built_terminology.terms.keys  # This will only return the Terms at the root of the terminology hierarchy
+  built_terminology.retrieve_term(:grant).children.keys
+</pre>
+
+h3. Creating Terms & Terminologies without any Builders
+
+If you want to manipulate Terms and Terminologies directly rather than using the Builder classes, you can consume their APIs at any time.
+
+People don't often do this, but the option is there if you need it.
+
+Create the Terminology, set its namespaces & (optional) schema 
+Note that you have to set the :oxns namespaces to match :xmlns.  This is usually done for you by the Terminology::Builder.root method.
+
+<pre>
+  handcrafted_terminology = OM::XML::Terminology.new
+  handcrafted_terminology.namespaces[:xmlns] = "http://yourmediashelf.com/schemas/hydra-dataset/v0"
+  handcrafted_terminology.namespaces[:oxns] = "http://yourmediashelf.com/schemas/hydra-dataset/v0"
+  handcrafted_terminology.schema = "http://example.org/schemas/grants-v1.xsd"
+</pre>
+
+Create the Terms
+
+<pre>
+  # Create term1 (the root) and set it as the root term
+  root_term = OM::XML::Term.new("grants")
+  root_term.is_root_term = true
+
+  # Create term1 (grant) and its subterms
+  term1 = OM::XML::Term.new("grant")
+
+  subterm1 = OM::XML::Term.new("org")
+  subterm1.path = "organization"
+  subterm1.attributes = {:type=>"funder"}
+
+  subsubterm = OM::XML::Term.new("name")
+  subsubterm.index_as = :searchable
+
+  subterm2 = OM::XML::Term.new("number")
+</pre>
+
+Assemble the tree of terms by adding child terms to their parents, then add those to the Terminology.
+
+<pre>
+  subterm1.add_child(subsubterm)
+  term1.add_child(subterm1)
+  term1.add_child(subterm2)
+  handcrafted_terminology.add_term(root_term)
+  handcrafted_terminology.add_term(term1)
+</pre>
+
+Generate the xpath queries for each term.  This is usually done for you by the Term Builder.build method
+
+<pre>
+  [root_term, term1, subterm1, subsubterm, subterm2].each {|t| t.generate_xpath_queries!}
+</pre>
+
+Test it out:
+
+<pre>
+  handcrafted_terminology.retrieve_term(:grant, :org, :name)
+  handcrafted_terminology.xpath_for(:grant, :org, :name)
+  handcrafted_terminology.root_terms
+  handcrafted_terminology.terms.keys  # This will only return the Terms at the root of the terminology hierarchy
+  handcrafted_terminology.retrieve_term(:grant).children.keys
+</pre>

data/GETTING_STARTED.textile

@@ -0,0 +1,216 @@
+To get started, you will create a new folder, set up a Gemfile to install OM, and then run bundler.
+
+<pre>
+mkdir omtest
+cd omtest
+</pre>
+
+Using whichever editor you prefer, create a file called Gemfile with the following contents
+
+<pre>
+source 'http://rubygems.org'
+gem 'om'
+</pre>
+
+Now run bundler to install the gem:
+
+<pre>
+bundle install
+</pre>
+
+You should now be set to use irb to run the following examples.
+
+<pre>
+irb
+require "rubygems"
+=> true 
+require "om"
+=> true
+</pre>
+
+Builder for a simple Terminology based on a couple of elements from the MODS schema.
+
+<pre>
+terminology_builder = OM::XML::Terminology::Builder.new do |t|
+  t.root(:path=>"mods", :xmlns=>"http://www.loc.gov/mods/v3", :schema=>"http://www.loc.gov/standards/mods/v3/mods-3-2.xsd")
+  # This is a mods:name.  The underscore is purely to avoid namespace conflicts.
+  t.name_ {
+    t.namePart
+    t.role(:ref=>[:role])
+    t.family_name(:path=>"namePart", :attributes=>{:type=>"family"})
+    t.given_name(:path=>"namePart", :attributes=>{:type=>"given"}, :label=>"first name")
+    t.terms_of_address(:path=>"namePart", :attributes=>{:type=>"termsOfAddress"})
+  }
+  
+  # Re-use the structure of a :name Term with a different @type attribute
+  t.person(:ref=>:name, :attributes=>{:type=>"personal"})
+  t.organization(:ref=>:name, :attributes=>{:type=>"corporate"})
+  
+  # This is a mods:role, which is used within mods:namePart elements
+  t.role {
+    t.text(:path=>"roleTerm",:attributes=>{:type=>"text"})
+    t.code(:path=>"roleTerm",:attributes=>{:type=>"code"})
+  }
+end
+</pre>
+
+Now tell the Builder to build your Terminology for you.
+
+<pre>terminology = terminology_builder.build</pre>
+
+h2. Using a Terminology to generate XPath Queries based on Term Pointers ("OM::XML::TermXPathGenerator":OM/XML/TermXpathGenerator.html)
+
+The Terminology handles generating xpath queries based on the structures you've defined.  It will also run the queries for you, so in most cases you won't even have to look at the XPath.  If you're ever curious what the xpath queries are, or if you want to use them in some other way, they are a few keystrokes away.
+
+Here are the xpaths for :name and two variants of :name that were created using the :ref argument in the Terminology builder.
+
+<pre>
+terminology.xpath_for(:name)
+=> "//oxns:name"
+terminology.xpath_for(:person)
+=> "//oxns:name[@type=\"personal\"]" 
+terminology.xpath_for(:organization)
+=> "//oxns:name[@type=\"corporate\"]"
+</pre>
+
+h2. OM Documents
+
+In action, you will usually use "OM::XML::Document":OM/XML/Document.html to deal with your xml.  Here's how to define a Document class that uses the same Terminology as above.  In a separate window, create the file my_mods_document.rb in the directory you created at the beginning of this document.
+
+<pre>
+  class MyModsDocument &lt; ActiveFedora::NokogiriDatastream 
+    include OM::XML::Document
+    
+    set_terminology do |t|
+      t.root(:path=>"mods", :xmlns=>"http://www.loc.gov/mods/v3", :schema=>"http://www.loc.gov/standards/mods/v3/mods-3-2.xsd")
+      # This is a mods:name.  The underscore is purely to avoid namespace conflicts.
+      t.name_ {
+        t.namePart
+        t.role(:ref=>[:role])
+        t.family_name(:path=>"namePart", :attributes=>{:type=>"family"})
+        t.given_name(:path=>"namePart", :attributes=>{:type=>"given"}, :label=>"first name")
+        t.terms_of_address(:path=>"namePart", :attributes=>{:type=>"termsOfAddress"})
+      }
+      t.person(:ref=>:name, :attributes=>{:type=>"personal"})
+      t.organization(:ref=>:name, :attributes=>{:type=>"corporate"})
+
+      # This is a mods:role, which is used within mods:namePart elements
+      t.role {
+        t.text(:path=>"roleTerm",:attributes=>{:type=>"text"})
+        t.code(:path=>"roleTerm",:attributes=>{:type=>"code"})
+      }
+    end
+    
+    def self.xml_template
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.mods(:version=>"3.3", "xmlns:xlink"=>"http://www.w3.org/1999/xlink",
+           "xmlns:xsi"=>"http://www.w3.org/2001/XMLSchema-instance",
+           "xmlns"=>"http://www.loc.gov/mods/v3",
+           "xsi:schemaLocation"=>"http://www.loc.gov/mods/v3 http://www.loc.gov/standards/mods/v3/mods-3-3.xsd") {
+             xml.titleInfo(:lang=>"") {
+               xml.title
+             }
+             xml.name(:type=>"personal") {
+               xml.namePart(:type=>"given")
+               xml.namePart(:type=>"family")
+               xml.affiliation
+               xml.computing_id
+               xml.description
+               xml.role {
+                 xml.roleTerm("Author", :authority=>"marcrelator", :type=>"text")
+               }
+             }
+           }
+      end
+      return builder.doc
+    end
+    
+  end
+</pre>
+
+OM::XML::Document provides the set_terminology method to handle the details of creating a TerminologyBuilder and building the terminology for you.  This allows you to focus on defining the structures of the Terminology itself.
+
+h3. Creating XML Documents from Scratch
+
+<pre>
+require "my_mods_document"
+newdoc = MyModsDocument.new
+newdoc.to_xml
+=> NoMethodError: undefined method `to_xml' for nil:NilClass
+</pre>
+
+By default, new OM Document instances will create an empty xml document.  However, if you set self.xml_template to return a different "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html, that will be used instead.  
+
+In the example above, we have overridden xml_template to use "Nokogiri::XML::Builder":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Builder.html to build an empty, relatively simple MODS document.  Note that at the end of the definition for xml_template, we call .doc on that XML Builder to return the "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html object.  This is important because you need xml_template to return a "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html.  Instead of using "Nokogiri::XML::Builder":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Builder.html, you could put your template into an actual xml file and have xml_template use "Nokogiri::XML::Document.parse":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html#M000225 to load it.  That's up to you.  Create the documents however you want, just return a "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html.
+
+
+h3. Loading an existing XML document
+
+To load existing XML into your OM Document, use "#from_xml":OM/XML/Container/ClassMethods.html#from_xml-instance_method" }
+
+Download "hydrangea_article1.xml":https://github.com/mediashelf/om/blob/master/spec/fixtures/mods_articles/hydrangea_article1.xml into your working directory, then run this:
+
+<pre>
+sample_xml = File.new("hydrangea_article1.xml")
+doc = MyModsDocument.from_xml(sample_xml)
+</pre>
+
+Now take a look at the document you've loaded.  We will use this document for the next few examples.
+
+<pre>doc.to_xml</pre>
+
+h3. Directly accessing the "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html and the "OM::XML::Terminology":https://github.com/mediashelf/om/blob/master/lib/om/xml/terminology.rb
+
+"OM::XML::Document":https://github.com/mediashelf/om/blob/master/lib/om/xml/document.rb is implemented as a container for a "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html.  It uses the associated Terminology to provide a bunch of convenience methods that wrap calls to Nokogiri.  If you ever need to operate directly on the Nokogiri Document, simply call ng_xml and do what you need to do.  OM will not get in your way.
+
+<pre>ng_document = doc.ng_xml</pre>
+
+If you need to look at the Terminology associated with your Document, call "#terminology":OM/XML/Document/ClassMethods.html#terminology-instance_method on the _class_.
+
+<pre>
+MyModsDocument.terminology
+doc.class.terminology
+</pre>
+
+h3. Querying OM Documents 
+
+Using the Terminology associated with your Document, you can query the xml for Nodes _or_ node values without ever writing a line of XPath.
+
+You can use OM::XML::Document.find_by_terms to retrieve xml nodes from the datastream.  It returns Nokogiri::XML::Node objects.
+
+<pre>
+doc.find_by_terms(:person)
+doc.find_by_terms(:person).length
+doc.find_by_terms(:person).each {|n| puts n.to_xml}
+</pre>
+
+If you want to get directly to the _values_ within those nodes, use OM::XML::Document.term_values
+
+<pre>
+doc.term_values(:person, :given_name)
+doc.term_values(:person, :family_name)
+</pre>
+
+If the xpath points to XML nodes that contain other nodes, the response to term_values will contain Nokogiri::XML::Node objects instead of text values.
+
+<pre>
+doc.term_values(:name)
+</pre>
+
+For more examples of Querying OM Documents, see "Querying Documents":https://github.com/mediashelf/om/blob/master/QUERYING_DOCUMENTS.textile
+
+h3. Updating, Inserting & Deleting Elements (TermValueOperators)
+
+For more examples of Updating OM Documents, see "Updating Documents":https://github.com/mediashelf/om/blob/master/UPDATING_DOCUMENTS.textile
+
+h3. Validating Documents
+
+If you have a schema defined in your Terminology's root Term, you can validate any xml document by calling ".validate" on any instance of your Document classes.
+
+<pre>doc.validate</pre>
+
+__*Note:* this method requires an internet connection, as it will download the schema from the URL you have specified in the Terminology's root term.__
+
+h3. Solrizing Documents
+
+The solrizer gem provides support for indexing XML documents into Solr based on OM Terminologies.  That process is documented in the "solrizer documentation":http://hudson.projecthydra.org/job/solrizer/Documentation/file.SOLRIZING_OM_DOCUMENTS.html

data/Gemfile

@@ -1,3 +1,10 @@
 source "http://rubygems.org"
 
 gemspec
+
+
+group :development, :test do
+  gem "rcov"
+  gem "yard"
+  gem "RedCloth"
+end

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    om (1.2.1)
+    om (1.2.4)
       nokogiri (>= 1.4.2)
       om
 
 GEM
   remote: http://rubygems.org/
   specs:
+    RedCloth (4.2.7)
     columnize (0.3.2)
     equivalent-xml (0.2.6)
       nokogiri (>= 1.4.3)
@@ -20,20 +21,25 @@ GEM
     mocha (0.9.12)
     nokogiri (1.4.4)
     rake (0.8.7)
+    rcov (0.9.9)
     rspec (1.3.1)
     ruby-debug (0.10.4)
       columnize (>= 0.1)
       ruby-debug-base (~> 0.10.4.0)
     ruby-debug-base (0.10.4)
       linecache (>= 0.3)
+    yard (0.6.8)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  RedCloth
   equivalent-xml (>= 0.2.4)
   jeweler
   mocha (>= 0.9.8)
   om!
+  rcov
   rspec (< 2.0.0)
   ruby-debug
+  yard

data/History.textile

@@ -1,3 +1,7 @@
+h3. 1.3.0
+
+  Document automatically includes Validation module, meaning that you can now call .validate on any document
+
 h3. 1.2.4
 
   TerminologyBuilder.root now passes on its options to the root term builder that it creates.

data/QUERYING_DOCUMENTS.textile

@@ -0,0 +1,134 @@
+h2. Querying OM Documents
+
+This document gives you some exposure to the methods provided by the "OM::XML::Document":OM/XML/Document.html module and its related modules "OM::XML::TermXPathGenerator":OM/XML/TermXPathGenerator.html & "OM::XML::TermValueOperators":OM/XML/TermValueOperators.html
+
+_Note: In your code, don't worry about including OM::XML::TermXPathGenerator and OM::XML::TermValueOperators into your classes.  OM::XML::Document handles that for you._
+
+h3. Load the Sample XML and Sample Terminology
+
+These examples use the Document class defined in "OM::Samples::ModsArticle":https://github.com/mediashelf/om/blob/master/lib/om/samples/mods_article.rb
+
+Download "hydrangea_article1.xml":https://github.com/mediashelf/om/blob/master/spec/fixtures/mods_articles/hydrangea_article1.xml into your working directory, then run this:
+
+<pre>
+  require "om/samples"
+  sample_xml = File.new("hydrangea_article1.xml")
+  doc = OM::Samples::ModsArticle.from_xml(sample_xml)
+</pre>
+
+h3. Query the Document
+
+The OM Terminology declared by OM::Samples::ModsArticle handles generating xpath queries based on the structures you've defined.  It will also run the queries for you in most cases.  If you're ever curious what the xpath queries are, or if you want to use them in some other way, they are a few keystrokes away.
+
+Here are the xpaths for :name and two variants of :name that were created using the :ref argument in the Terminology builder.
+
+<pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:name)
+=> "//oxns:name"
+OM::Samples::ModsArticle.terminology.xpath_for(:person)
+=> "//oxns:name[@type=\"personal\"]" 
+OM::Samples::ModsArticle.terminology.xpath_for(:organization)
+=> "//oxns:name[@type=\"corporate\"]"
+</pre>
+
+To retrieve the values of xml nodes, use the term_values method
+
+<pre>
+doc.term_values(:person, :first_name) 
+doc.term_values(:person, :last_name) 
+</pre>
+
+If the xpath points to XML nodes that contain other nodes, the response to term_values will contain Nokogiri::XML::Node objects instead of text values.
+
+<pre>
+  doc.term_values(:name)
+</pre>
+
+More examples of using term_values and find_by_terms:
+
+<pre>
+doc.find_by_terms(:organization).to_xml
+doc.term_values(:organization, :role)
+=> ["\n      Funder\n    "] 
+doc.term_values(:organization, :namePart)
+=> ["NSF"]
+</pre>
+
+You will often string together a series of term names to point to what you want
+
+<pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:journal, :issue, :pages, :start)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:part/oxns:extent[@unit=\"pages\"]/oxns:start" 
+doc.term_values(:journal, :issue, :pages, :start)
+=> ["195"] 
+</pre>
+  
+If you get one of the names wrong in the list, OM will tell you which one is causing problems.  See what happens when you put :page instead of :pages in your argument to term_values.
+
+<pre>
+doc.term_values(:journal, :issue, :page, :start)
+OM::XML::Terminology::BadPointerError: You attempted to retrieve a Term using this pointer: [:journal, :issue, :page] but no Term exists at that location. Everything is fine until ":page", which doesn't exist.
+</pre>
+
+If you use a term often and you're sick of typing all of those term names, you can define a proxy term.  Here we have a proxy term called :start_page that saves you from having to remember the details of how MODS is structured.  
+
+<pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:journal, :issue, :start_page)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:part/oxns:extent[@unit=\"pages\"]/oxns:start"
+</pre>
+  
+Here is another proxy term.  It proxies to [:journal,:origin_info,:issuance]
+
+<pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:peer_reviewed)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:originInfo/oxns:issuance"
+</pre>
+
+h2. What to do when elements are reused throughout an XML document
+
+In our MODS document, we have two types of title: 1) the title of the published article and 2) the title of the journal it was published in.  They both use the same xml node.  How can we deal with that? 
+
+<pre>
+doc.term_values(:title_info, :main_title)
+=> ["ARTICLE TITLE", "VARYING FORM OF TITLE", "TITLE OF HOST JOURNAL"] 
+doc.term_values(:mods, :title_info, :main_title)
+=> ["ARTICLE TITLE", "VARYING FORM OF TITLE"]
+OM::Samples::ModsArticle.terminology.xpath_for(:title_info, :main_title)
+=> "//oxns:titleInfo/oxns:title" 
+</pre>
+
+The solution: include the root node in your term pointer.
+
+<pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:mods, :title_info, :main_title)
+=> "//oxns:mods/oxns:titleInfo/oxns:title"
+doc.term_values(:mods, :title_info, :main_title)
+=> ["ARTICLE TITLE", "VARYING FORM OF TITLE"] 
+</pre>
+
+We can still access the Journal title by its own pointers:
+
+<pre>
+doc.term_values(:journal, :title_info, :main_title)
+ => ["TITLE OF HOST JOURNAL"] 
+</pre>
+
+h2. Making life easier with Proxy Terms
+
+Sometimes all of these terms become tedious.  That's where proxy terms come in. You can use them to access frequently used Terms more easily.  As you can see in "OM::Samples::ModsArticle":https://github.com/mediashelf/om/blob/master/lib/om/samples/mods_article.rb, we have defined a few proxy terms for convenience.
+
+<pre>
+t.publication_url(:proxy=>[:location,:url])
+t.peer_reviewed(:proxy=>[:journal,:origin_info,:issuance], :index_as=>[:facetable])
+t.title(:proxy=>[:mods,:title_info, :main_title])
+t.journal_title(:proxy=>[:journal, :title_info, :main_title])
+</pre>
+
+You can use them just like any other Term when querying the document.
+
+<pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:title)
+=> "//oxns:mods/oxns:titleInfo/oxns:title" 
+OM::Samples::ModsArticle.terminology.xpath_for(:journal_title)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:titleInfo/oxns:title"
+</pre>

data/README.textile

@@ -1,16 +1,25 @@
-h1. opinionated-xml
+h1. om (Optinionated Metadata)
 
 A library to help you tame sprawling XML schemas like MODS.
 
-h2. Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+h2. Tutorials
+
+* "Getting Started":http://hudson.projecthydra.org/job/om/Documentation/file.GETTING_STARTED.html
+* "Querying Documents":http://hudson.projecthydra.org/job/om/Documentation/file.QUERYING_DOCUMENTS.html
+* "Updating Documents":http://hudson.projecthydra.org/job/om/Documentation/file.UPDATING_DOCUMENTS.html
+* "Getting Fancy":http://hudson.projecthydra.org/job/om/Documentation/file.GETTING_FANCY.html
+
+h2. Common OM Patterns
+
+"Common OM Patterns":http://hudson.projecthydra.org/job/om/Documentation/file.COMMON_OM_PATTERNS.html
+
+h3. Solrizing Documents
+
+The solrizer gem provides support for indexing XML documents into Solr based on OM Terminologies.  That process is documented in the "solrizer documentation":http://hudson.projecthydra.org/job/solrizer/Documentation/file.SOLRIZING_OM_DOCUMENTS.html
+
+h2. OM in the Wild
+
+We have a page on the Hydra wiki with a list of OM Terminologies in active use: "OM Terminologies in the Wild":https://wiki.duraspace.org/display/hydra/OM+Terminologies+in+the+Wild
 
 h2. Acknowledgements