om 1.2.5 → 1.3.0

data/COMMON_OM_PATTERNS.textile

@@ -2,6 +2,133 @@ h1. Common Patterns You'll Use with OM
 
 h2. Common Terminology Patterns
 
+h4. element value
+
+We want an OM term to be assigned so its value is the value of an element.
+
+Given this xml:
+
+<pre>
+<outer>
+  <element>my value</element>
+</outer> 
+</pre>
+
+we want to have an OM term named "element" with "my value" as the value.
+
+In the Datastream Model:
+
+<pre>  
+# defines the expected OM terminology for example xml
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
+  # OM (Opinionated Metadata) terminology mapping 
+  set_terminology do |t|
+    t.root(:path => "outer", :xmlns => '')
+    t.element
+  end  
+end # class
+</pre>
+
+Q: What if we don't want the OM term to be named "element," but "giraffe"?
+
+A: 
+
+<pre>  
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
+  set_terminology do |t|
+    t.root(:path => "outer", :xmlns => '')
+    t.giraffe(:path => "element")
+  end  
+end # class
+</pre>
+
+h4. element value given a specific attribute value
+
+We want an OM term to be assigned to an element's value, but only when the element has a specific attribute value.
+
+Given this xml:
+
+<pre>
+</outer> 
+  <element my_attr="attr value">element value</element>
+</outer> 
+</pre>
+
+we want to have an OM term named "element" with "element value" as the value.
+
+In the Datastream Model:
+
+<pre>  
+# defines the expected OM terminology for example xml
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
+  # OM (Opinionated Metadata) terminology mapping 
+  set_terminology do |t|
+    t.root(:path => "outer", :xmlns => '')
+    t.element(:attributes=>{:my_attr=>"attr value"})
+  end  
+end # class
+</pre>
+
+Q: What if we don't want the OM term to be named "element," but "gazelle"?
+
+A: 
+
+<pre>  
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
+  set_terminology do |t|
+    t.root(:path => "outer", :xmlns => '')
+    t.gazelle(:path => "element", :attributes=>{:my_attr=>"attr value"})
+  end  
+end
+</pre>
+
+h4. attribute value
+
+We want an OM term to be assigned to an element's attribute value.
+
+Given this xml:
+
+<pre>
+</outer> 
+  <element my_attr="attr value">element value</element>
+</outer> 
+</pre>
+
+we want to have an OM term named "my_attr" with "attr value" as the value.
+
+In the Datastream Model:
+
+FIXME:  is this correct?  (Naomi wonders 2011-06-22)
+
+<pre>  
+# defines the expected OM terminology for example xml
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
+  # OM (Opinionated Metadata) terminology mapping 
+  set_terminology do |t|
+    t.root(:path => "outer", :xmlns => '')
+    t.element {
+      t.my_attr(:path => {:attribute=>"my_attr"})
+    }
+  end  
+end # class
+</pre>
+
+Q: What if we don't want the OM term to be named "my_attr," but "hippo"?
+
+A: 
+
+<pre>  
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
+  set_terminology do |t|
+    t.root(:path => "outer", :xmlns => '')
+    t.element {
+      t.hippo(:path => {:attribute=>"my_attr"})
+    }
+  end  
+end
+</pre>
+
+
 h3. Reserved method names (ie. id_, root_)
 
 Like Nokogiri ...

data/GETTING_FANCY.textile

@@ -4,9 +4,11 @@ h1. Getting Fancy
 
 h2. Alternative ways to Manipulate Terms, Terminologies and their Builders
 
-h3. The Example
+There is more than one way to build a terminology. 
 
-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.  
+h3. OM::XML::Terminology::Builder":OM/XML/Terminology/Builder.html Block Syntax
+
+The simplest way to create an OM Terminology is to use the "OM::XML::Terminology::Builder":OM/XML/Terminology/Builder.html" block syntax. 
 
 In the following examples, we will show different ways of building this Terminology:
 
@@ -24,21 +26,21 @@ In the following examples, we will show different ways of building this Terminol
 </pre>
 
 
-h3. Using Term::Builders
+h3. Using "OM::XML::Term":OM/XML/Term.html ::Builders
 
-First, create the Terminology Builder object.
+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
+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.
+This sets the namespaces for you and created the "grants" root term:
 
 <pre>
   terminology_builder.namespaces
@@ -46,7 +48,7 @@ As you can see, this sets the namespaces for you and created the "grants" root t
   terminology_builder.term_builders
 </pre>
 
-Create Term Builders for each of the Terms
+Create Term Builders for each of the Terms:
 
 <pre>
   term1_builder = OM::XML::Term::Builder.new("grant", terminology_builder).path("grant")
@@ -55,7 +57,7 @@ Create Term Builders for each of the Terms
   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.
+Assemble the tree of Term builders by adding child builders to their parents; then add the top level terms to the root term in the Terminology builder:
 
 <pre>
   subterm1_builder.add_child(subsubterm_builder)
@@ -64,7 +66,7 @@ Assemble the tree of Term builders by adding child builders to their parents, th
   terminology_builder.term_builders["grant"] = term1_builder
 </pre>
 
-Now build the Terminology, which will also call .build on each of the Term Builders
+Now build the Terminology, which will also call .build on each of the Term Builders in the tree:
 
 <pre>
   built_terminology = terminology_builder.build
@@ -86,8 +88,8 @@ If you want to manipulate Terms and Terminologies directly rather than using the
 
 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.
+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
@@ -96,7 +98,7 @@ Note that you have to set the :oxns namespaces to match :xmlns.  This is usually
   handcrafted_terminology.schema = "http://example.org/schemas/grants-v1.xsd"
 </pre>
 
-Create the Terms
+Create the Terms:
 
 <pre>
   # Create term1 (the root) and set it as the root term
@@ -126,7 +128,7 @@ Assemble the tree of terms by adding child terms to their parents, then add thos
   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
+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!}

data/GETTING_STARTED.textile

@@ -1,3 +1,25 @@
+h2. OM (Opinionated Metadata) - Getting Started
+
+OM allows you to define a "terminology" to ease translation between XML and ruby objects - you can query the xml for Nodes _or_ node values without ever writing a line of XPath.
+
+OM "terms" are ruby symbols you define (in the terminology) that map specific XML content into ruby object attributes.
+
+The API documentation at "http://hudson.projecthydra.org/job/om/Documentation/OM.html":http://hudson.projecthydra.org/job/om/Documentation/OM.html provides additional, more targeted information.  We will provide links to the API as appropriate.
+
+h4. What you will learn from this document
+
+# Install OM and run it in IRB
+# Build an OM Terminology
+# Use OM XML Document class 
+# Create XML from the OM XML Document 
+# Load existing XML into an OM XML Document
+# Query OM XML Document to get term values
+# Access the Terminology of an OM XML Document
+# Retrieve XPath from the terminology
+
+
+h2. Install OM
+
 To get started, you will create a new folder, set up a Gemfile to install OM, and then run bundler.
 
 <pre>
@@ -5,20 +27,24 @@ mkdir omtest
 cd omtest
 </pre>
 
-Using whichever editor you prefer, create a file called Gemfile with the following contents
+Using whichever editor you prefer, create a file (in omtest directory) called Gemfile with the following contents:
 
 <pre>
 source 'http://rubygems.org'
 gem 'om'
 </pre>
 
-Now run bundler to install the gem:
+Now run bundler to install the gem:  (you will need the bundler Gem)
 
 <pre>
 bundle install
 </pre>
 
-You should now be set to use irb to run the following examples.
+You should now be set to use irb to run the following example.
+
+h2. Build a simple OM terminology (in irb)
+
+To experiment with abbreviated terminology examples, irb is your friend.  If you are working on a persistent terminology and have to experiment to make sure you declare your terminology correctly, we recommend writing test code (e.g. with rspec).  You can see examples of this "here":https://github.com/projecthydra/hydra-tutorial-application/blob/master/spec/models/journal_article_mods_datastream_spec.rb 
 
 <pre>
 irb
@@ -28,7 +54,7 @@ require "om"
 => true
 </pre>
 
-Builder for a simple Terminology based on a couple of elements from the MODS schema.
+Create a simple (simplish?) Terminology Builder ("OM::XML::Terminology::Builder":OM/XML/Terminology/Builder.html") based on a couple of elements from the MODS schema.
 
 <pre>
 terminology_builder = OM::XML::Terminology::Builder.new do |t|
@@ -54,28 +80,15 @@ terminology_builder = OM::XML::Terminology::Builder.new do |t|
 end
 </pre>
 
-Now tell the Builder to build your Terminology for you.
+Now tell the Terminology Builder to build your Terminology ("OM::XML::Terminology":OM/XML/Terminology.html"):
 
 <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.
+Generally you will use an "OM::XML::Document":OM/XML/Document.html to work with your xml.  Here's how to define a Document class that uses the same Terminology as above.  
+
+In a separate window (so you can keep irb running), create the file my_mods_document.rb in the omtest directory, with this content:
 
 <pre>
   class MyModsDocument &lt; ActiveFedora::NokogiriDatastream 
@@ -101,7 +114,10 @@ In action, you will usually use "OM::XML::Document":OM/XML/Document.html to deal
       }
     end
     
+    # Generates an empty Mods Article (used when you call ModsArticle.new without passing in existing xml)
+    #  (overrides default behavior of creating a plain xml document)
     def self.xml_template
+      # use Nokogiri to build the XML
       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",
@@ -122,15 +138,24 @@ In action, you will usually use "OM::XML::Document":OM/XML/Document.html to deal
              }
            }
       end
+      # return a Nokogiri::XML::Document, not an OM::XML::Document
       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.
+(Note that we are now also using the ActiveFedora gem.)
+
+"OM::XML::Document":OM/XML/Document.html 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
+h3. Creating XML Documents from Scratch using OM
+
+By default, new OM Document instances will create an empty xml document, but if you override self.xml_template to return a different object (e.g. "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html), that will be created instead.  
+
+In the example above, we have overridden xml_template to build an empty, relatively simple MODS document as a "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html.  We use "Nokogiri::XML::Builder":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Builder.html and call its .doc method at the end of xml_template in order to return the "Nokogiri::XML::Document":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Document.html object.  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.
+
+to use "Nokogiri::XML::Builder":http://nokogiri.rubyforge.org/nokogiri/Nokogiri/XML/Builder.html
 
 <pre>
 require "my_mods_document"
@@ -139,44 +164,27 @@ 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 with OM
 
-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"
 
-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:
+For an example, download "hydrangea_article1.xml":https://github.com/mediashelf/om/blob/master/spec/fixtures/mods_articles/hydrangea_article1.xml into your working directory (omtest), then run this in irb:
 
 <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.
+Take a look at the document object's xml that you've just populated.  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.
+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.
+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)
@@ -184,14 +192,16 @@ 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
+You might prefer to use nodes as a way of getting multiple values pertaining to a node, rather than doing more expensive lookups for each desired value.
+
+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.
+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)
@@ -205,12 +215,40 @@ For more examples of Updating OM Documents, see "Updating Documents":https://git
 
 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.
+If you have an XML 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.__
+__*Note:* this method requires an internet connection, as it will download the XML schema from the URL you have specified in the Terminology's root term.__
+
+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 OM 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 Document's _class_.
+
+<pre>
+MyModsDocument.terminology
+doc.class.terminology
+</pre>
+
+h2. Using a Terminology to generate XPath Queries based on Term Pointers 
+
+Because the Terminology is essentially a mapping from XPath queries to ruby object attributes, in most cases you won't need to know the actual XPath queries.  Nevertheless, when you <i>do</i> want to know the Xpath (e.g. for ensuring your terminology is correct) for a term, the Terminology can generate xpath queries based on the structures you've defined ("OM::XML::TermXPathGenerator":OM/XML/TermXpathGenerator.html).
+
+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>
 
-h3. Solrizing Documents
+h2. 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/QUERYING_DOCUMENTS.textile

@@ -1,6 +1,6 @@
 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
+This document will help you understand how to access the information associated with an "OM::XML::Document":OM/XML/Document.html object.  We will explain some of 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._
 
@@ -8,7 +8,7 @@ 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:
+Download "hydrangea_article1.xml":https://github.com/mediashelf/om/blob/master/spec/fixtures/mods_articles/hydrangea_article1.xml (sample xml) into your working directory, then run this in irb:
 
 <pre>
   require "om/samples"
@@ -16,11 +16,15 @@ Download "hydrangea_article1.xml":https://github.com/mediashelf/om/blob/master/s
   doc = OM::Samples::ModsArticle.from_xml(sample_xml)
 </pre>
 
-h3. Query the Document
+h2. Querying the "OM::XML::Document":OM/XML/Document.html
 
-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.
+The "OM::XML::Terminology":OM/XML/Terminology.html" declared by "OM::Samples::ModsArticle":https://github.com/mediashelf/om/blob/master/lib/om/samples/mods_article.rb maps the defined Terminology structure to xpath queries.  It will also run the queries for you in most cases.  
 
-Here are the xpaths for :name and two variants of :name that were created using the :ref argument in the Terminology builder.
+h4. xpath_for method of "OM::XML::Terminology":OM/XML/Terminology.html" retrieves xpath expressions for OM terms
+
+The xpath_for method retrieves the xpath used by the "OM::XML::Terminology":OM/XML/Terminology.html"
+
+Examples of 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)
@@ -31,20 +35,24 @@ OM::Samples::ModsArticle.terminology.xpath_for(:organization)
 => "//oxns:name[@type=\"corporate\"]"
 </pre>
 
-To retrieve the values of xml nodes, use the term_values method
+h4. Working with Terms
+
+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.
+The term_values method is defined in the "OM::XML::TermValueOperators":OM/XML/TermValueOperators.html module, which is included in "OM::XML::Document":OM/XML/Document.html
+
+Not that if a term's xpath mapping points to XML nodes that contain other nodes, the response to term_values will be Nokogiri::XML::Node objects instead of text values:
 
 <pre>
   doc.term_values(:name)
 </pre>
 
-More examples of using term_values and find_by_terms:
+More examples of using term_values and find_by_terms (defined in "OM::XML::Document":OM/XML/Document.html):
 
 <pre>
 doc.find_by_terms(:organization).to_xml
@@ -54,7 +62,7 @@ doc.term_values(:organization, :namePart)
 => ["NSF"]
 </pre>
 
-You will often string together a series of term names to point to what you want
+To retrieve the values of nested terms, create a sequence of terms, from outermost to innermost:
 
 <pre>
 OM::Samples::ModsArticle.terminology.xpath_for(:journal, :issue, :pages, :start)
@@ -63,30 +71,23 @@ 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.
+If you get one of the term names wrong in the sequence, 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]
+h2. When XML Elements are Reused in a Document
 
-<pre>
-OM::Samples::ModsArticle.terminology.xpath_for(:peer_reviewed)
-=> "//oxns:relatedItem[@type=\"host\"]/oxns:originInfo/oxns:issuance"
-</pre>
+(Another way to put this: the xpath statement for a term can be ambiguous.)
 
-h2. What to do when elements are reused throughout an XML document
+In our MODS document, we have two distinct uses of the title XML element:
+# the title of the published article 
+# the title of the journal it was published in.  
 
-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? 
+How can we distinguish between these two uses?
 
 <pre>
 doc.term_values(:title_info, :main_title)
@@ -115,7 +116,9 @@ doc.term_values(:journal, :title_info, :main_title)
 
 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.
+If you use a nested term often, you may want to avoid typing the whole sequence of term names by defining a _proxy_ term.  
+
+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])
@@ -124,9 +127,11 @@ 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.
+You can use proxy terms just like any other term when querying the document.
 
 <pre>
+OM::Samples::ModsArticle.terminology.xpath_for(:peer_reviewed)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:originInfo/oxns:issuance"
 OM::Samples::ModsArticle.terminology.xpath_for(:title)
 => "//oxns:mods/oxns:titleInfo/oxns:title" 
 OM::Samples::ModsArticle.terminology.xpath_for(:journal_title)

data/README.rdoc

@@ -1,6 +1,10 @@
 = opinionated-xml
 
-A library to help you tame sprawling XML schemas like MODS.
+A library to help you tame sprawling XML schemas like MODS.  
+
+OM allows you to define a “terminology” to ease translation between XML and ruby objects – you can query the xml for Nodes or node values without ever writing a line of XPath.
+
+OM “terms” are ruby symbols you define (in the terminology) that map specific XML content into ruby object attributes.
 
 == Note on Patches/Pull Requests
  

data/README.textile

@@ -2,6 +2,10 @@ h1. om (Optinionated Metadata)
 
 A library to help you tame sprawling XML schemas like MODS.
 
+OM allows you to define a “terminology” to ease translation between XML and ruby objects – you can query the xml for Nodes or node values without ever writing a line of XPath.
+
+OM “terms” are ruby symbols you define (in the terminology) that map specific XML content into ruby object attributes.
+
 h2. Tutorials
 
 * "Getting Started":http://hudson.projecthydra.org/job/om/Documentation/file.GETTING_STARTED.html