xml-mapping 0.9.1 → 0.10.0

data/test/multiple_mappings_test.rb

@@ -15,7 +15,9 @@ class MultipleMappingsTest < Test::Unit::TestCase
       Classes_by_rootelt_names.clear
     EOS
     Object.send(:remove_const, "Triangle")
-    $".delete "triangle_mm.rb"
+    unless ($".delete "triangle_mm.rb")
+      $".delete_if{|name| name =~ %r!test/triangle_mm.rb$!}
+    end
     $:.unshift File.dirname(__FILE__)  # test/unit may have undone this (see test/unit/collector/dir.rb)
     require 'triangle_mm'
   end

data/test/xml_mapping_adv_test.rb

@@ -3,7 +3,6 @@ require File.dirname(__FILE__)+"/tests_init"
 require 'test/unit'
 require 'documents_folders'
 require 'bookmarks'
-require 'yaml'
 
 class XmlMappingAdvancedTest < Test::Unit::TestCase
   def setup
@@ -13,8 +12,12 @@ class XmlMappingAdvancedTest < Test::Unit::TestCase
     Object.send(:remove_const, "Document")
     Object.send(:remove_const, "Folder")
 
-    $".delete "documents_folders.rb"
-    $".delete "bookmarks.rb"
+    unless ($".delete "documents_folders.rb")  # works in 1.8 only. In 1.9, $" contains absolute paths.
+      $".delete_if{|name| name =~ %r!test/documents_folders.rb$!}
+    end
+    unless ($".delete "bookmarks.rb")
+      $".delete_if{|name| name =~ %r!test/bookmarks.rb$!}
+    end
     require 'documents_folders'
     require 'bookmarks'
 
@@ -26,23 +29,20 @@ class XmlMappingAdvancedTest < Test::Unit::TestCase
   end
 
   def test_read_polymorphic_object
-    assert_equal YAML::load(<<-EOS), @f
-      --- !ruby/object:Folder 
-      entries: 
-        - !ruby/object:Document 
-          contents: " inhale, exhale"
-          name: plan
-        - !ruby/object:Folder 
-          entries: 
-            - !ruby/object:Folder 
-              entries: 
-                - !ruby/object:Document 
-                  contents: foo bar baz
-                  name: README
-              name: xml-mapping
-          name: work
-      name: home
-    EOS
+    expected = Folder.new \
+      :name => "home",
+      :entries => [
+                   Document.new(:name => "plan", :contents => " inhale, exhale"),
+                   Folder.new(:name => "work",
+                              :entries => [
+                                           Folder.new(:name => "xml-mapping",
+                                                      :entries => [Document.new(:name => "README",
+                                                                                :contents => "foo bar baz")]
+                                                      )
+                                          ])
+                  ]
+
+    assert_equal expected, @f
   end
 
   def test_write_polymorphic_object

data/test/xml_mapping_test.rb

@@ -27,7 +27,10 @@ class XmlMappingTest < Test::Unit::TestCase
     Object.send(:remove_const, "Names1")
     Object.send(:remove_const, "ReaderTest")
     Object.send(:remove_const, "WriterTest")
-    $".delete "company.rb"
+    Object.send(:remove_const, "ReaderWriterProcVsLambdaTest")
+    unless ($".delete "company.rb") # works in 1.8 only. In 1.9, $" contains absolute paths.
+      $".delete_if{|name| name =~ %r!test/company.rb$!}
+    end
     $:.unshift File.dirname(__FILE__)  # test/unit may have undone this (see test/unit/collector/dir.rb)
     require 'company'
 
@@ -155,7 +158,33 @@ class XmlMappingTest < Test::Unit::TestCase
     assert_equal %w{dingdong2 dingdong3}, xml2.all_xpath("quux").map{|elt|elt.text}
   end
 
-  
+  def test_reader_writer_proc_vs_lambda
+    xml = REXML::Document.new("<test>
+                                 <proc_2args>proc_2args_text</proc_2args>
+                                 <lambda_2args>lambda_2args_text</lambda_2args>
+                                 <proc_3args>proc_3args_text</proc_3args>
+                                 <lambda_3args>lambda_3args_text</lambda_3args>
+                              </test>").root
+    r = ReaderWriterProcVsLambdaTest.load_from_xml xml
+    assert_equal [:proc_2args, :proc_3args, :lambda_2args, :lambda_3args], r.read
+    assert_nil r.written
+    assert_nil r.proc_2args
+    assert_nil r.lambda_2args
+    assert_equal 'proc_3args_text', r.proc_3args
+    assert_equal 'lambda_3args_text', r.lambda_3args
+
+    r.proc_2args = "proc_2args_text_new"
+    r.lambda_2args = "lambda_2args_text_new"
+    r.proc_3args = "proc_3args_text_new"
+    r.lambda_3args = "lambda_3args_text_new"
+    xml2 = r.save_to_xml
+    assert_equal [:proc_2args, :proc_3args, :lambda_2args, :lambda_3args], r.written
+    assert_nil xml2.first_xpath("proc_2args", :allow_nil=>true)
+    assert_nil xml2.first_xpath("lambda_2args", :allow_nil=>true)
+    assert_equal 'proc_3args_text_new', xml2.first_xpath("proc_3args").text
+    assert_equal 'lambda_3args_text_new', xml2.first_xpath("lambda_3args").text
+  end
+
   def test_setter_text_node
     @c.ent2 = "lalala"
     assert_equal "lalala", REXML::XPath.first(@c.save_to_xml, "arrtest/entry[2]").text

data/{README → user_manual.md}

@@ -1,44 +1,377 @@
-= XML-MAPPING: XML-to-object (and back) Mapper for Ruby, including XPath Interpreter
+# XML-MAPPING: XML-to-object (and back) Mapper for Ruby, including XPath Interpreter
 
 Xml-mapping is an easy to use, extensible library that allows you to
 semi-automatically map Ruby objects to XML trees and vice versa.
 
-== Download
+## Download
 
-For downloading the latest version, CVS repository access etc. go to:
+For downloading the latest version, git repository access etc. go to:
 
-http://rubyforge.org/projects/xml-mapping/
+https://github.com/multi-io/xml-mapping
 
-== Contents of this Document
+## Contents of this Document
 
-- {Example}[aref:example]
-- {Single-attribute Nodes}[aref:sanodes]
-  - {Default Values}[aref:defaultvalues]
-  - {Single-attribute Nodes with Sub-objects}[aref:subobjnodes]
-  - {Attribute Handling Details, Augmenting Existing Classes}[aref:attrdefns]
-- {Other Nodes}[aref:onodes]
-  - {choice_node}[aref:choice_node]
-  - {Readers/Writers}[aref:readerswriters]
-- {Multiple Mappings per Class}[aref:mappings]
-- {Defining your own Node Types}[aref:definingnodes]
-- {XPath Interpreter}[aref:xpath]
+- {Example}[rdoc-label:label-Example]
+- {Single-attribute Nodes}[rdoc-label:label-Single-attribute+Nodes]
+    - {Default Values}[rdoc-label:label-Default+Values]
+    - {Single-attribute Nodes with Sub-objects}[rdoc-label:label-Single-attribute+Nodes+with+Sub-objects]
+    - {Attribute Handling Details, Augmenting Existing Classes}[rdoc-label:label-Attribute+Handling+Details%2C+Augmenting+Existing+Classes]
+- {Other Nodes}[rdoc-label:label-Other+Nodes]
+    - {choice_node}[rdoc-label:label-choice_node]
+    - {Readers/Writers}[rdoc-label:label-Readers%2FWriters]
+- {Multiple Mappings per Class}[rdoc-label:label-Multiple+Mappings+per+Class]
+- {Defining your own Node Types}[rdoc-label:label-Defining+your+own+Node+Types]
+- {XPath Interpreter}[rdoc-label:label-XPath+Interpreter]
 
-== {Example}[a:example]
+## Example
 
 (example document stolen + extended from
 http://www.castor.org/xml-mapping.html)
 
-=== Input Document:
-
-  :include: order.xml
-
-=== Mapping Class Declaration:
-
-  :include: order.rb
-
-=== Usage:
-
-  :include: order_usage.intout
+### Input Document:
+
+    <?xml version="1.0" encoding="ISO-8859-1"?>
+    
+    <Order reference="12343-AHSHE-314159">
+      <Client>
+        <Name>Jean Smith</Name>
+        <Address where="home">
+          <City>San Mateo</City>
+          <State>CA</State>
+          <ZIP>94403</ZIP>
+          <Street>2000, Alameda de las Pulgas</Street>
+        </Address>
+        <Address where="work">
+          <City>San Francisco</City>
+          <State>CA</State>
+          <ZIP>94102</ZIP>
+          <Street>98765, Fulton Street</Street>
+        </Address>
+      </Client>
+    
+      <Item reference="RF-0001">
+        <Description>Stuffed Penguin</Description>
+        <Quantity>10</Quantity>
+        <UnitPrice>8.95</UnitPrice>
+      </Item>
+    
+      <Item reference="RF-0034">
+        <Description>Chocolate</Description>
+        <Quantity>5</Quantity>
+        <UnitPrice>28.50</UnitPrice>
+      </Item>
+    
+      <Item reference="RF-3341">
+        <Description>Cookie</Description>
+        <Quantity>30</Quantity>
+        <UnitPrice>0.85</UnitPrice>
+      </Item>
+    
+      <Signed-By>
+        <Signature>
+          <Name>John Doe</Name>
+          <Position>product manager</Position>
+        </Signature>
+        
+        <Signature>
+          <Name>Jill Smith</Name>
+          <Position>clerk</Position>
+        </Signature>
+    
+        <Signature>
+          <Name>Miles O'Brien</Name>
+        </Signature>
+      </Signed-By>
+    
+    </Order>
+
+### Mapping Class Declaration:
+
+    require 'xml/mapping'
+    
+    ## forward declarations
+    class Client; end
+    class Address; end
+    class Item; end
+    class Signature; end
+    
+    
+    class Order
+      include XML::Mapping
+    
+      text_node :reference, "@reference"
+      object_node :client, "Client", :class=>Client
+      hash_node :items, "Item", "@reference", :class=>Item
+      array_node :signatures, "Signed-By", "Signature", :class=>Signature, :default_value=>[]
+    
+      def total_price
+        items.values.map{|i| i.total_price}.inject(0){|x,y|x+y}
+      end
+    end
+    
+    
+    class Client
+      include XML::Mapping
+    
+      text_node :name, "Name"
+      object_node :home_address, "Address[@where='home']", :class=>Address
+      object_node :work_address, "Address[@where='work']", :class=>Address, :default_value=>nil
+    end
+    
+    
+    class Address
+      include XML::Mapping
+    
+      text_node :city, "City"
+      text_node :state, "State"
+      numeric_node :zip, "ZIP"
+      text_node :street, "Street"
+    end
+    
+    
+    class Item
+      include XML::Mapping
+    
+      text_node :descr, "Description"
+      numeric_node :quantity, "Quantity"
+      numeric_node :unit_price, "UnitPrice"
+    
+      def total_price
+        quantity*unit_price
+      end
+    end
+    
+    
+    class Signature
+      include XML::Mapping
+    
+      text_node :name, "Name"
+      text_node :position, "Position", :default_value=>"Some Employee"
+    end
+
+### Usage:
+
+    ####read access
+    o=Order.load_from_file("order.xml") 
+    => #<Order:0x007fb01549d438 @signatures=[#<Signature:0x007fb015493b68 @position="product manager", @name="John Doe">, #<Signature:0x007fb015492c68 @position="clerk", @name="Jill Smith">, #<Signature:0x007fb015491a20 @position="Some Employee", @name="Miles O'Brien">], @reference="12343-AHSHE-314159", @client=#<Client:0x007fb01549c998 @work_address=#<Address:0x007fb01549a238 @city="San Francisco", @state="CA", @zip=94102, @street="98765, Fulton Street">, @name="Jean Smith", @home_address=#<Address:0x007fb01549bbb0 @city="San Mateo", @state="CA", @zip=94403, @street="2000, Alameda de las Pulgas">>, @items={"RF-0001"=>#<Item:0x007fb0154989b0 @descr="Stuffed Penguin", @quantity=10, @unit_price=8.95>, "RF-0034"=>#<Item:0x007fb015496638 @descr="Chocolate", @quantity=5, @unit_price=28.5>, "RF-3341"=>#<Item:0x007fb015495300 @descr="Cookie", @quantity=30, @unit_price=0.85>}>
+    o.reference 
+    => "12343-AHSHE-314159"
+    o.client 
+    => #<Client:0x007fb01549c998 @work_address=#<Address:0x007fb01549a238 @city="San Francisco", @state="CA", @zip=94102, @street="98765, Fulton Street">, @name="Jean Smith", @home_address=#<Address:0x007fb01549bbb0 @city="San Mateo", @state="CA", @zip=94403, @street="2000, Alameda de las Pulgas">>
+    o.items.keys 
+    => ["RF-0001", "RF-0034", "RF-3341"]
+    o.items["RF-0034"].descr 
+    => "Chocolate"
+    o.items["RF-0034"].total_price 
+    => 142.5
+    o.signatures 
+    => [#<Signature:0x007fb015493b68 @position="product manager", @name="John Doe">, #<Signature:0x007fb015492c68 @position="clerk", @name="Jill Smith">, #<Signature:0x007fb015491a20 @position="Some Employee", @name="Miles O'Brien">]
+    o.signatures[2].name 
+    => "Miles O'Brien"
+    o.signatures[2].position 
+    => "Some Employee"
+    ## default value was set
+    
+    o.total_price 
+    => 257.5
+    
+    ####write access
+    o.client.name="James T. Kirk"
+    o.items['RF-4711'] = Item.new
+    o.items['RF-4711'].descr = 'power transfer grid'
+    o.items['RF-4711'].quantity = 2
+    o.items['RF-4711'].unit_price = 29.95
+    
+    s=Signature.new
+    s.name='Harry Smith'
+    s.position='general manager'
+    o.signatures << s
+    xml=o.save_to_xml #convert to REXML node; there's also o.save_to_file(name) 
+    => <order reference='12343-AHSHE-314159'> ... </>
+    xml.write($stdout,2) 
+    <order reference='12343-AHSHE-314159'>
+      <Client>
+        <Name>
+          James T. Kirk
+        </Name>
+        <Address where='home'>
+          <City>
+            San Mateo
+          </City>
+          <State>
+            CA
+          </State>
+          <ZIP>
+            94403
+          </ZIP>
+          <Street>
+            2000, Alameda de las Pulgas
+          </Street>
+        </Address>
+        <Address where='work'>
+          <City>
+            San Francisco
+          </City>
+          <State>
+            CA
+          </State>
+          <ZIP>
+            94102
+          </ZIP>
+          <Street>
+            98765, Fulton Street
+          </Street>
+        </Address>
+      </Client>
+      <Item reference='RF-0001'>
+        <Description>
+          Stuffed Penguin
+        </Description>
+        <Quantity>
+          10
+        </Quantity>
+        <UnitPrice>
+          8.95
+        </UnitPrice>
+      </Item>
+      <Item reference='RF-0034'>
+        <Description>
+          Chocolate
+        </Description>
+        <Quantity>
+          5
+        </Quantity>
+        <UnitPrice>
+          28.5
+        </UnitPrice>
+      </Item>
+      <Item reference='RF-3341'>
+        <Description>
+          Cookie
+        </Description>
+        <Quantity>
+          30
+        </Quantity>
+        <UnitPrice>
+          0.85
+        </UnitPrice>
+      </Item>
+      <Item reference='RF-4711'>
+        <Description>
+          power transfer grid
+        </Description>
+        <Quantity>
+          2
+        </Quantity>
+        <UnitPrice>
+          29.95
+        </UnitPrice>
+      </Item>
+      <Signed-By>
+        <Signature>
+          <Name>
+            John Doe
+          </Name>
+          <Position>
+            product manager
+          </Position>
+        </Signature>
+        <Signature>
+          <Name>
+            Jill Smith
+          </Name>
+          <Position>
+            clerk
+          </Position>
+        </Signature>
+        <Signature>
+          <Name>
+            Miles O&apos;Brien
+          </Name>
+        </Signature>
+        <Signature>
+          <Name>
+            Harry Smith
+          </Name>
+          <Position>
+            general manager
+          </Position>
+        </Signature>
+      </Signed-By>
+    </order>
+    
+    
+    ####Starting a new order from scratch
+    o = Order.new 
+    => #<Order:0x007fb0153bfef8 @signatures=[]>
+    ## attributes with default values (here: signatures) are set
+    ## automatically
+    
+    xml=o.save_to_xml 
+    XML::MappingError: no value, and no default value, for attribute: reference
+    	from /home/olaf/xml-mapping/lib/xml/mapping/base.rb:712:in `obj_to_xml'
+    	from /home/olaf/xml-mapping/lib/xml/mapping/base.rb:218:in `block in fill_into_xml'
+    	from /home/olaf/xml-mapping/lib/xml/mapping/base.rb:217:in `each'
+    	from /home/olaf/xml-mapping/lib/xml/mapping/base.rb:217:in `fill_into_xml'
+    	from /home/olaf/xml-mapping/lib/xml/mapping/base.rb:229:in `save_to_xml'
+    ## can't save as long as there are still unset attributes without
+    ## default values
+    
+    o.reference = "FOOBAR-1234"
+    
+    o.client = Client.new
+    o.client.name = 'Ford Prefect'
+    o.client.home_address = Address.new
+    o.client.home_address.street = '42 Park Av.'
+    o.client.home_address.city = 'small planet'
+    o.client.home_address.zip = 17263
+    o.client.home_address.state = 'Betelgeuse system'
+    
+    o.items={'XY-42' => Item.new}
+    o.items['XY-42'].descr = 'improbability drive'
+    o.items['XY-42'].quantity = 3
+    o.items['XY-42'].unit_price = 299.95
+    
+    xml=o.save_to_xml
+    xml.write($stdout,2)
+    
+    <order reference='FOOBAR-1234'>
+      <Client>
+        <Name>
+          Ford Prefect
+        </Name>
+        <Address where='home'>
+          <City>
+            small planet
+          </City>
+          <State>
+            Betelgeuse system
+          </State>
+          <ZIP>
+            17263
+          </ZIP>
+          <Street>
+            42 Park Av.
+          </Street>
+        </Address>
+      </Client>
+      <Item reference='XY-42'>
+        <Description>
+          improbability drive
+        </Description>
+        <Quantity>
+          3
+        </Quantity>
+        <UnitPrice>
+          299.95
+        </UnitPrice>
+      </Item>
+    </order>
+    ## the root element name when saving an object to XML will by default
+    ## be derived from the class name (in this example, "Order" became
+    ## "order"). This can be overridden on a per-class basis; see
+    ## XML::Mapping::ClassMethods#root_element_name for details.
+    
 
 As shown in the example, you have to include XML::Mapping into a class
 to turn it into a "mapping class". There are no other restrictions
@@ -55,18 +388,18 @@ from the body of the class definition to define instance attributes
 that are automatically and bidirectionally mapped to subtrees of the
 XML element an instance of the class is mapped to.
 
-== {Single-attribute Nodes}[a:sanodes]
+## Single-attribute Nodes
 
 For example, in the definition
 
-  class Address
-    include XML::Mapping
+    class Address
+      include XML::Mapping
 
-    text_node :city, "City"
-    text_node :state, "State"
-    numeric_node :zip, "ZIP"
-    text_node :street, "Street"
-  end
+      text_node :city, "City"
+      text_node :state, "State"
+      numeric_node :zip, "ZIP"
+      text_node :street, "Street"
+    end
 
 the first call to #text_node creates an attribute named "city" which
 is mapped to the text of the XML child element defined by the XPath
@@ -90,7 +423,7 @@ node". All node types that come with xml-mapping except one
 nodes.
 
 
-=== {Default Values}[a:defaultvalues]
+### Default Values
 
 For each single-attribute node you may define a <i>default value</i>
 which will be set if there was no value defined for the attribute in
@@ -98,43 +431,43 @@ the XML source.
 
 From the example:
 
-  class Signature
-    include XML::Mapping
+    class Signature
+      include XML::Mapping
 
-    text_node :position, "Position", :default_value=>"Some Employee"
-  end
+      text_node :position, "Position", :default_value=>"Some Employee"
+    end
 
 The semantics of default values are as follows:
 
 - when creating a new instance from scratch:
 
-  - attributes with default values are set to their default values
+    - attributes with default values are set to their default values
 
-  - attributes without default values are left unset
+    - attributes without default values are left unset
 
   (when defining your own initializer, you'll have to call the
   inherited _initialize_ method in order to get this behaviour)
 
 - when loading an instance from an XML document:
 
-  - attributes without default values that are not represented in the
-    XML raise an error
+    - attributes without default values that are not represented in
+      the XML raise an error
 
-  - attributes with default values that are not represented in the XML
-    are set to their default values
+    - attributes with default values that are not represented in the
+      XML are set to their default values
 
-  - all other attributes are set to their respective values as present
-    in the XML
+    - all other attributes are set to their respective values as
+      present in the XML
 
 
 - when saving an instance to an XML document:
 
-  - unset attributes without default values raise an error
+    - unset attributes without default values raise an error
 
-  - attributes with default values that are set to their default
-    values are not saved
+    - attributes with default values that are set to their default
+      values are not saved
 
-  - all other attributes are saved
+    - all other attributes are saved
 
 
 This implies that:
@@ -147,14 +480,14 @@ This implies that:
 
 
 
-=== {Single-attribute Nodes with Sub-objects}[a:subobjnodes]
+### Single-attribute Nodes with Sub-objects
 
 Single-attribute nodes of type +array_node+, +hash_node+, and
 +object_node+ recursively map one or more subtrees of their XML to
 sub-objects (e.g. array elements or hash values) of their
 attribute. For example, with the line
 
-  array_node :signatures, "Signed-By", "Signature", :class=>Signature, :default_value=>[]
+    array_node :signatures, "Signed-By", "Signature", :class=>Signature, :default_value=>[]
 
 , an attribute named "signatures" is added to the surrounding class
 (here: +Order+); the attribute will be an array whose elements
@@ -174,17 +507,17 @@ attribute contains an array with 3 +Signature+ instances (let's call
 them <tt>sig1</tt>, <tt>sig2</tt>, and <tt>sig3</tt>) in it, it will
 be marshalled to an XML tree that looks like this:
 
-  <Signed-By>
-    <Signature>
-      [marshalled object sig1]
-    </Signature>
-    <Signature>
-      [marshalled object sig2]
-    </Signature>
-    <Signature>
-      [marshalled object sig3]
-    </Signature>
-  </Signed-By>
+    <Signed-By>
+      <Signature>
+        [marshalled object sig1]
+      </Signature>
+      <Signature>
+        [marshalled object sig2]
+      </Signature>
+      <Signature>
+        [marshalled object sig3]
+      </Signature>
+    </Signed-By>
 
 Internally, each +Signature+ instance is stored into its
 <tt><Signature></tt> sub-element by calling
@@ -212,16 +545,59 @@ strings or numbers as sub-objects of attributes of +array_node+,
 +hash_node+, or +object_node+ nodes. For example, say you have an XML
 document like this one:
 
-  :include: stringarray.xml
+    <?xml version="1.0" encoding="ISO-8859-1"?>
+    
+    <people>
+      <names>
+        <name>Jim</name>
+        <name>Susan</name>
+        <name>Herbie</name>
+        <name>Nancy</name>
+      </names>
+    </people>
 
 , and you want to map all the names to a string array attribute
 +names+, you could do it like this:
 
-  :include: stringarray.rb
+    require 'xml/mapping'
+    class People
+      include XML::Mapping
+      array_node :names, "names", "name", :class=>String
+    end
 
 usage:
 
-  :include: stringarray_usage.intout
+    ppl=People.load_from_file("stringarray.xml") 
+    => #<People:0x007fb015431a58 @names=["Jim", "Susan", "Herbie", "Nancy"]>
+    ppl.names 
+    => ["Jim", "Susan", "Herbie", "Nancy"]
+    
+    ppl.names.concat ["Mary","Arnold"] 
+    => ["Jim", "Susan", "Herbie", "Nancy", "Mary", "Arnold"]
+    ppl.save_to_xml.write $stdout,2
+    
+    <people>
+      <names>
+        <name>
+          Jim
+        </name>
+        <name>
+          Susan
+        </name>
+        <name>
+          Herbie
+        </name>
+        <name>
+          Nancy
+        </name>
+        <name>
+          Mary
+        </name>
+        <name>
+          Arnold
+        </name>
+      </names>
+    </people>
 
 As a side node, this feature actually makes +text_node+ and
 +numeric_node+ special cases of +object_node+. For example,
@@ -229,7 +605,7 @@ As a side node, this feature actually makes +text_node+ and
 "path", :class=>String</tt>.
 
 
-==== Polymorphic Sub-objects, Marshallers/Unmarshallers
+#### Polymorphic Sub-objects, Marshallers/Unmarshallers
 
 Besides the <tt>:class</tt> keyword argument, there are alternative
 ways for a single-attribute node with sub-objects to specify the way
@@ -244,15 +620,105 @@ recursive set of named "documents" and "folders", where folders hold a
 set of entries, each of which may again be either a document or a
 folder:
 
-  :include: documents_folders.xml
+    <?xml version="1.0" encoding="ISO-8859-1"?>
+    
+    <folder name="home">
+      <document name="plan">
+        <contents> inhale, exhale</contents>
+      </document>
+    
+      <folder name="work">
+        <folder name="xml-mapping">
+          <document name="README">
+            <contents>foo bar baz</contents>
+          </document>
+        </folder>
+      </folder>
+    
+    </folder>
 
 This can be mapped to Ruby like this:
 
-  :include: documents_folders.rb
+    require 'xml/mapping'
+    
+    class Entry
+      include XML::Mapping
+    
+      text_node :name, "@name"
+    end
+    
+    
+    class Document <Entry
+      include XML::Mapping
+    
+      text_node :contents, "contents"
+    end
+    
+    
+    class Folder <Entry
+      include XML::Mapping
+    
+      array_node :entries, "document|folder", :default_value=>[]
+    
+      def [](name)
+        entries.select{|e|e.name==name}[0]
+      end
+    
+      def append(name,entry)
+        entries << entry
+        entry.name = name
+        entry
+      end
+    end
 
 Usage:
 
-  :include: documents_folders_usage.intout
+    
+    root = XML::Mapping.load_object_from_file "documents_folders.xml" 
+    => #<Folder:0x007fb015437098 @entries=[#<Document:0x007fb015436148 @name="plan", @contents=" inhale, exhale">, #<Folder:0x007fb0154352c0 @entries=[#<Folder:0x007fb015434550 @entries=[#<Document:0x007fb015432e30 @name="README", @contents="foo bar baz">], @name="xml-mapping">], @name="work">], @name="home">
+    root.name 
+    => "home"
+    root.entries 
+    => [#<Document:0x007fb015436148 @name="plan", @contents=" inhale, exhale">, #<Folder:0x007fb0154352c0 @entries=[#<Folder:0x007fb015434550 @entries=[#<Document:0x007fb015432e30 @name="README", @contents="foo bar baz">], @name="xml-mapping">], @name="work">]
+    
+    root.append "etc", Folder.new
+    root["etc"].append "passwd", Document.new
+    root["etc"]["passwd"].contents = "foo:x:2:2:/bin/sh"
+    root["etc"].append "hosts", Document.new
+    root["etc"]["hosts"].contents = "127.0.0.1 localhost"
+    
+    xml = root.save_to_xml 
+    => <folder name='home'> ... </>
+    xml.write $stdout,2
+    
+    <folder name='home'>
+      <document name='plan'>
+        <contents>
+           inhale, exhale
+        </contents>
+      </document>
+      <folder name='work'>
+        <folder name='xml-mapping'>
+          <document name='README'>
+            <contents>
+              foo bar baz
+            </contents>
+          </document>
+        </folder>
+      </folder>
+      <folder name='etc'>
+        <document name='passwd'>
+          <contents>
+            foo:x:2:2:/bin/sh
+          </contents>
+        </document>
+        <document name='hosts'>
+          <contents>
+            127.0.0.1 localhost
+          </contents>
+        </document>
+      </folder>
+    </folder>
 
 As you see, the <tt>Folder#entries</tt> attribute is mapped via an
 array_node that does not specify a <tt>:class</tt> or anything else to
@@ -297,7 +763,15 @@ extend the +Signature+ class from the initial example to include the
 date on which the signature was created. We want the new XML
 representation of such a signature to look like this:
 
-  :include: time_node_w_marshallers.xml
+    <Signature>
+      <Name>John Doe</Name>
+      <Position>product manager</Position>
+      <signed-on>
+        <day>13</day>
+        <month>2</month>
+        <year>2005</year>
+      </signed-on>
+    </Signature>
 
 So, a new "signed-on" element was added that holds the day, month, and
 year. In the +Signature+ instance in Ruby, we want the date to be
@@ -313,7 +787,31 @@ here[aref:definingnodes]). The fastest, most ad-hoc way to achieve
 what we want are :marshaller and :unmarshaller keyword arguments, like
 this:
 
-  :include: time_node_w_marshallers.intout
+    require 'xml/mapping'
+    require 'xml/xxpath_methods'
+    
+    class Signature
+      include XML::Mapping
+    
+      text_node :name, "Name"
+      text_node :position, "Position", :default_value=>"Some Employee"
+      object_node :signed_on, "signed-on",
+                  :unmarshaller=>proc{|xml|
+                                   y,m,d = [xml.first_xpath("year").text.to_i,
+                                            xml.first_xpath("month").text.to_i,
+                                            xml.first_xpath("day").text.to_i]
+                                   Time.local(y,m,d)
+                                 },
+                  :marshaller=>proc{|xml,value|
+                                 e = xml.elements.add; e.name = "year"; e.text = value.year
+                                 e = xml.elements.add; e.name = "month"; e.text = value.month
+                                 e = xml.elements.add; e.name = "day"; e.text = value.day
+    
+                                 # xml.first("year",:ensure_created=>true).text = value.year
+                                 # xml.first("month",:ensure_created=>true).text = value.month
+                                 # xml.first("day",:ensure_created=>true).text = value.day
+                               }
+    end 
 
 The <tt>:unmarshaller</tt> proc will be called whenever a +Signature+
 instance is being read in from an XML source. The +xml+ argument
@@ -353,9 +851,9 @@ possible with all single-attribute nodes with sub-objects, i.e. with
 a whole array of date values, you could use +array_node+ with the same
 :marshaller/:unmarshaller procs as above, for example:
 
-  array_node :birthdays, "birthdays", "birthday",
-             :unmarshaller=> <as above>,
-             :marshaller=> <as above>
+    array_node :birthdays, "birthdays", "birthday",
+               :unmarshaller=> <as above>,
+               :marshaller=> <as above>
 
 You can see that :marshaller/:unmarshaller procs give you more
 flexibility, but they also impose more work because you essentially
@@ -383,12 +881,12 @@ functionality of a node type while retaining another part.
 
 
 
-=== {Attribute Handling Details, Augmenting Existing Classes}[a:attrdefns]
+### Attribute Handling Details, Augmenting Existing Classes
 
 I'll shed some more light on how single-attribute nodes add mapped
 attributes to Ruby classes. An attribute declaration like
 
-  text_node :city, "City"
+    text_node :city, "City"
 
 maps some portion of the XML tree (here: the "City" sub-element) to an
 attribute (here: "city") of the class whose body the declaration
@@ -418,7 +916,41 @@ scratch, you can also take existing classes that contain some
 a simple example, let's augment Ruby's "Time" class with node
 declarations that declare XML mappings for the day, month etc. fields:
 
-  :include: time_augm.intout
+    class Time
+      include XML::Mapping
+    
+      numeric_node :year, "year"
+      numeric_node :month, "month"
+      numeric_node :day, "mday"
+      numeric_node :hour, "hours"
+      numeric_node :min, "minutes"
+      numeric_node :sec, "seconds"
+    end
+    
+    
+    nowxml=Time.now.save_to_xml 
+    => <time> ... </>
+    nowxml.write($stdout,2)
+    <time>
+      <year>
+        2014
+      </year>
+      <month>
+        9
+      </month>
+      <mday>
+        19
+      </mday>
+      <hours>
+        14
+      </hours>
+      <minutes>
+        1
+      </minutes>
+      <seconds>
+        43
+      </seconds>
+    </time>
 
 Here XML mappings are defined for the existing fields +year+, +month+
 etc. Xml-mapping noticed that the getter methods for those attributes
@@ -445,10 +977,21 @@ variables, so the setter methods don't really change the time of the
 +Time+ object. So we have to redefine +load_from_xml+ for the +Time+
 class:
 
-  :include: time_augm_loading.intout
+    
+    def Time.load_from_xml(xml, options={:mapping=>:_default})
+      year,month,day,hour,min,sec =
+        [xml.first_xpath("year").text.to_i,
+         xml.first_xpath("month").text.to_i,
+         xml.first_xpath("mday").text.to_i,
+         xml.first_xpath("hours").text.to_i,
+         xml.first_xpath("minutes").text.to_i,
+         xml.first_xpath("seconds").text.to_i]
+      Time.local(year,month,day,hour,min,sec)
+    end
+    
 
 
-== {Other Nodes}[a:onodes]
+## Other Nodes
 
 All nodes I've shown so far (node types text_node, numeric_node,
 boolean_node, object_node, array_node, and hash_node) were
@@ -457,7 +1000,7 @@ of such a node is an attribute name, and the attribute of that name is
 the only piece of the state of instances of the node's mapping class
 that gets read/written by the node.
 
-=== {choice_node}[a:choice_node]
+### choice_node
 
 There is one node type distributed with xml-mapping that is not a
 single-attribute node: +choice_node+. A +choice_node+ allows you to
@@ -477,7 +1020,26 @@ objects that have either a single author (contained in an "author" XML
 attribute) or several "contributors" (contained in a sequence of
 "contr" XML elements):
 
-  :include: publication.intout
+    
+    class Publication
+      include XML::Mapping
+    
+      choice_node :if,    '@author', :then, (text_node :author, '@author'),
+                  :elsif, 'contr',   :then, (array_node :contributors, 'contr', :class=>String)
+    end
+    
+    ### usage
+    
+    p1 = Publication.load_from_xml(REXML::Document.new('<publication author="Jim"/>').root)
+    => #<Publication:0x007fb01548e668 @author="Jim">
+    
+    p2 = Publication.load_from_xml(REXML::Document.new('
+    <publication>
+      <contr>Chris</contr>
+      <contr>Mel</contr>
+      <contr>Toby</contr>
+    </publication>').root)
+    => #<Publication:0x007fb01547ef38 @contributors=["Chris", "Mel", "Toby"]>
 
 The symbols :if, :then, and :elsif (but not :else -- see below) in the
 +choice_node+'s node factory method call are ignored; they may be
@@ -519,7 +1081,33 @@ person should be stored alternatively in a sub-element named +name+,
 or an attribute named +name+, or in the text of the +person+ element
 itself. You can achieve this with +choice_node+ like this:
 
-  :include: person.intout
+    
+    class Person
+      include XML::Mapping
+    
+      choice_node :if,    'name',  :then, (text_node :name, 'name'),
+                  :elsif, '@name', :then, (text_node :name, '@name'),
+                  :else,  (text_node :name, '.')
+    end
+    
+    ### usage
+    
+    p1 = Person.load_from_xml(REXML::Document.new('<person name="Jim"/>').root)
+    => #<Person:0x007fb014e95298 @name="Jim">
+    
+    p2 = Person.load_from_xml(REXML::Document.new('<person><name>James</name></person>').root)
+    => #<Person:0x007fb014e847b8 @name="James">
+    
+    p3 = Person.load_from_xml(REXML::Document.new('<person>Suzy</person>').root)
+    => #<Person:0x007fb014e6c550 @name="Suzy">
+    
+    
+    p1.save_to_xml.write($stdout)
+    <person><name>Jim</name></person>
+    p2.save_to_xml.write($stdout)
+    <person><name>James</name></person>
+    p3.save_to_xml.write($stdout)
+    <person><name>Suzy</name></person>
 
 Here all sub-nodes of the choice_nodes are single-attribute nodes
 (text_nodes) with the same attribute (+name+). As you see, when
@@ -528,7 +1116,7 @@ sub-element. Of course, this is because that alternative appears first
 in the choice_node.
 
 
-=== {Readers/Writers}[a:readerswriters]
+### Readers/Writers
 
 Finally, _all_ nodes support keyword arguments :reader and :writer
 which allow you to extend or completely override the reading and/or
@@ -545,7 +1133,25 @@ The :reader proc is for reading (from the XML into the object), the
 
 Here's a (really contrived) example:
 
-  :include: reader.intout
+    
+    class Foo
+      include XML::Mapping
+    
+      text_node :name, "@name", :reader=>proc{|obj,xml,default_reader|
+                                           default_reader.call(obj,xml)
+                                           obj.name += xml.attributes['more']
+                                         },
+                                :writer=>proc{|obj,xml|
+                                           xml.attributes['bar'] = "hi #{obj.name} ho"
+                                         }
+    end
+    
+    f = Foo.load_from_xml(REXML::Document.new('<foo name="Jim" more="XYZ"/>').root)
+    => #<Foo:0x007fb015460c40 @name="JimXYZ">
+    
+    xml = f.save_to_xml 
+    xml.write $stdout,2 
+    <foo bar='hi JimXYZ ho'/>
 
 So there's a "Foo" class with a text_node that would by default
 (without the :reader and :writer proc) map the Ruby attribute "name"
@@ -573,14 +1179,14 @@ As a special convention, if you specify both a :reader and a :writer
 for a node, and in both cases you do /not/ call the default behaviour,
 then you should use the generic node type +node+, e.g.:
 
-  class SomeClass
-    include XML::Mapping
+    class SomeClass
+      include XML::Mapping
 
-    ....
+      ....
 
-    node :reader=>proc{|obj,xml| ...},
-         :writer=>proc{|obj,xml| ...}
-  end
+      node :reader=>proc{|obj,xml| ...},
+           :writer=>proc{|obj,xml| ...}
+    end
 
 (since you're completely replacing both the reading and the writing
 functionality, you're effectively replacing all the functionality of
@@ -608,7 +1214,7 @@ the (sensibly parameterized) code from your readers/writers to your
 node types.
 
 
-== {Multiple Mappings per Class}[a:mappings]
+## Multiple Mappings per Class
 
 Sometimes you might want to represent the same Ruby object in multiple
 alternative ways in XML. For example, the name of a "Person" object
@@ -635,7 +1241,120 @@ In the following example, we define two mappings (the default one and
 a mapping named <tt>:other</tt>) for +Person+ objects with a name, an
 age and an address:
 
-  :include: examples/person_mm.intout
+    require 'xml/mapping'
+    
+    class Address; end
+    
+    class Person
+      include XML::Mapping
+    
+      # the default mapping. Stores the name and age in XML attributes,
+      # and the address in a sub-element "address".
+    
+      text_node :name, "@name"
+      numeric_node :age, "@age"
+      object_node :address, "address", :class=>Address
+    
+      use_mapping :other
+    
+      # the ":other" mapping. Non-default root element name; name and age
+      # stored in XML elements; address stored in the person's element
+      # itself
+    
+      root_element_name "individual"
+      text_node :name, "name"
+      numeric_node :age, "age"
+      object_node :address, ".", :class=>Address
+    
+      # you could also specify the mapping on a per-node basis with the
+      # :mapping option, e.g.:
+      #
+      # numeric_node :age, "age", :mapping=>:other
+    end
+    
+    
+    class Address
+      include XML::Mapping
+    
+      # the default mapping.
+    
+      text_node :street, "street"
+      numeric_node :number, "number"
+      text_node :city, "city"
+      numeric_node :zip, "zip"
+    
+      use_mapping :other
+    
+      # the ":other" mapping.
+    
+      text_node :street, "street-name"
+      numeric_node :number, "street-name/@number"
+      text_node :city, "city-name"
+      numeric_node :zip, "city-name/@zip-code"
+    end
+    
+    
+    ### usage
+    
+    ## XML representation of a person in the default mapping
+    xml = REXML::Document.new('
+    <person name="Suzy" age="28">
+      <address>
+        <street>Abbey Road</street>
+        <number>72</number>
+        <city>London</city>
+        <zip>18827</zip>
+      </address>
+    </person>').root
+    
+    ## load using the default mapping
+    p = Person.load_from_xml xml 
+    => #<Person:0x007fb015506640 @name="Suzy", @age=28, @address=#<Address:0x007fb015505a38 @street="Abbey Road", @number=72, @city="London", @zip=18827>>
+    
+    ## save using the default mapping
+    xml2 = p.save_to_xml
+    xml2.write $stdout,2 
+    <person name='Suzy' age='28'>
+      <address>
+        <street>
+          Abbey Road
+        </street>
+        <number>
+          72
+        </number>
+        <city>
+          London
+        </city>
+        <zip>
+          18827
+        </zip>
+      </address>
+    </person>
+    ## xml2 identical to xml
+    
+    
+    ## now, save the same person to XML using the :other mapping...
+    other_xml = p.save_to_xml :mapping=>:other
+    other_xml.write $stdout,2 
+    <individual>
+      <name>
+        Suzy
+      </name>
+      <age>
+        28
+      </age>
+      <street-name number='72'>
+        Abbey Road
+      </street-name>
+      <city-name zip-code='18827'>
+        London
+      </city-name>
+    </individual>
+    ## load it again using the :other mapping
+    p2 = Person.load_from_xml other_xml, :mapping=>:other 
+    => #<Person:0x007fb0154bad30 @name="Suzy", @age=28, @address=#<Address:0x007fb0154b98e0 @street="Abbey Road", @number=72, @city="London", @zip=18827>>
+    
+    ## p2 identical to p 
 
 In this example, each of the two mappings contains nodes that map the
 same set of Ruby attributes (name, age and address). This is probably
@@ -652,11 +1371,11 @@ sub-ordinated class (+Address+). This is the case for all
 specify a different mapping for the sub-object(s) using the option
 :sub_mapping, e.g.
 
-  object_node :address, "address", :class=>Address, :sub_mapping=>:other
+    object_node :address, "address", :class=>Address, :sub_mapping=>:other
 
 
 
-== {Defining your own Node Types}[a:definingnodes]
+## Defining your own Node Types
 
 It's easy to write additional node types and register them with the
 xml-mapping library (the following node types come with xml-mapping:
@@ -665,18 +1384,32 @@ xml-mapping library (the following node types come with xml-mapping:
 
 I'll first show an example, then some more theoretical insight.
 
-=== Example
+### Example
 
 Let's say we want to extend the +Signature+ class from the example to
 include the time at which the signature was created. We want the new
 XML representation of such a signature to look like this:
 
-  :include: order_signature_enhanced.xml
+    <Signature>
+      <Name>John Doe</Name>
+      <Position>product manager</Position>
+      <signed-on>
+        <day>13</day>
+        <month>2</month>
+        <year>2005</year>
+      </signed-on>
+    </Signature>
 
 (we only save year, month and day to make this example shorter), and
 the mapping class declaration to look like this:
 
-  :include: order_signature_enhanced.rb
+    class Signature
+      include XML::Mapping
+    
+      text_node :name, "Name"
+      text_node :position, "Position", :default_value=>"Some Employee"
+      time_node :signed_on, "signed-on", :default_value=>Time.now
+    end
 
 (i.e. a new "time_node" declaration was added).
 
@@ -686,7 +1419,34 @@ class +Time+.
 
 This node type can be defined with this piece of code:
 
-  :include: time_node.rb
+    require 'xml/mapping/base'
+    
+    class TimeNode < XML::Mapping::SingleAttributeNode
+      def initialize(*args)
+        path,*args = super(*args)
+        @y_path = XML::XXPath.new(path+"/year")
+        @m_path = XML::XXPath.new(path+"/month")
+        @d_path = XML::XXPath.new(path+"/day")
+        args
+      end
+    
+      def extract_attr_value(xml)
+        y,m,d = default_when_xpath_err{ [@y_path.first(xml).text.to_i,
+                                         @m_path.first(xml).text.to_i,
+                                         @d_path.first(xml).text.to_i]
+                                      }
+        Time.local(y,m,d)
+      end
+    
+      def set_attr_value(xml, value)
+        @y_path.first(xml,:ensure_created=>true).text = value.year
+        @m_path.first(xml,:ensure_created=>true).text = value.month
+        @d_path.first(xml,:ensure_created=>true).text = value.day
+      end
+    end
+    
+    
+    XML::Mapping.add_node_class TimeNode
 
 The last line registers the new node type with the xml-mapping
 library. The name of the node factory method ("time_node") is
@@ -798,7 +1558,7 @@ _xml_. If it was not, it is created (preferably at the end of _xml_'s
 list of sub-nodes), and returned. See below[aref:xpath] for a more
 detailed documentation of the XPath interpreter.
 
-=== Element order in created XML documents
+### Element order in created XML documents
 
 As just said, XML::XXPath, when used to create new XML nodes,
 generally appends those nodes to the end of the list of subnodes of
@@ -821,7 +1581,7 @@ The following is a more systematic overview of the basic node
 types. The description is self-contained, so some information from the
 previous section will be repeated.
 
-=== Node Types Are Ruby Classes
+### Node Types Are Ruby Classes
 
 A node type is implemented as a Ruby class derived from
 XML::Mapping::Node or one of its subclasses.
@@ -830,16 +1590,16 @@ The following node types (node classes) come with xml-mapping (they
 all live in the XML::Mapping namespace, which I've left out here for
 brevity):
 
-  Node
-   +-SingleAttributeNode
-   |  +-SubObjectBaseNode
-   |  |  +-ObjectNode
-   |  |  +-ArrayNode
-   |  |  +-HashNode
-   |  +-TextNode
-   |  +-NumericNode
-   |  +-BooleanNode
-   +-ChoiceNode
+    Node
+     +-SingleAttributeNode
+     |  +-SubObjectBaseNode
+     |  |  +-ObjectNode
+     |  |  +-ArrayNode
+     |  |  +-HashNode
+     |  +-TextNode
+     |  +-NumericNode
+     |  +-BooleanNode
+     +-ChoiceNode
 
 XML::Mapping::Node is the base class for all nodes,
 XML::Mapping::SingleAttributeNode is the base class for
@@ -863,12 +1623,12 @@ built-in nodes is not very long or complicated; you may consider
 reading it in addition to this text to gain a better understanding.
 
 
-=== How Node Types Work
+### How Node Types Work
 
 The xml-mapping core "operates" node types as follows:
 
 
-==== Node Initialization
+#### Node Initialization
 
 As said above, when a node class is registered with xml-mapping by
 calling <tt>XML::Mapping.add_node_class TheNodeClass</tt>, xml-mapping
@@ -881,11 +1641,11 @@ the node class. The list of parameters to _new_ will consist of <i>the
 mapping class, followed by all arguments that were passed to the node
 factory method</i>. For example, when you have this node declaration:
 
-  class MyMappingClass
-    include XML::Mapping
+    class MyMappingClass
+      include XML::Mapping
 
-    my_node :foo, "bar", 42, :hi=>"ho"
-  end
+      my_node :foo, "bar", 42, :hi=>"ho"
+    end
 
 , then the node factory method (+my_node+) calls
 <tt>MyNode.new(MyMappingClass, :foo, "bar", 42, :hi=>"ho")</tt>.
@@ -898,14 +1658,14 @@ processes itself, process them, and return an array containing the
 remaining (still unprocessed) parameters. Thus, an implementation of
 _initialize_ follows this pattern:
 
-  def initialize(*args)
-    myparam1,myparam2,...,myparamx,*args = super(*args)
+    def initialize(*args)
+      myparam1,myparam2,...,myparamx,*args = super(*args)
 
-    .... process the myparam1,myparam2,...,myparamx ....
+      .... process the myparam1,myparam2,...,myparamx ....
 
-    # return still unprocessed args
-    args
-  end
+      # return still unprocessed args
+      args
+    end
 
 (since the called superclass initializer is written the same way, the
 parameter array returned by it will already be stripped of all
@@ -928,7 +1688,7 @@ per node definition, and that instance lives in the mapping class the
 node was defined in.
 
 
-==== Node Operation during Marshalling and Unmarshalling
+#### Node Operation during Marshalling and Unmarshalling
 
 When an instance of a mapping class is created or filled from an XML
 tree, xml-mapping will call +xml_to_obj+ on all nodes defined in that
@@ -951,7 +1711,7 @@ the instance and put it into the appropriate XML elements/XML attr
 etc. of the XML tree.
 
 
-=== Basic Node Types Overview
+### Basic Node Types Overview
 
 The following is an overview of how initialization and
 marshalling/unmarshalling is implemented in the node base classes
@@ -959,7 +1719,7 @@ marshalling/unmarshalling is implemented in the node base classes
 
 TODO: summary table: member var name; introduced in class; meaning
 
-==== Node
+#### Node
 
 In _initialize_, the mapping class and the option arguments are
 stripped from the argument list. The mapping class is stored in
@@ -990,7 +1750,7 @@ The marshalling/unmarshalling methods
 +Node+ (they just raise an exception).
 
 
-==== SingleAttributeNode
+#### SingleAttributeNode
 
 In _initialize_, the attribute name is stripped from the argument list
 and stored in @attrname, and an attribute of that name is added to the
@@ -1003,9 +1763,9 @@ this, the <tt>obj_to_xml</tt>/<tt>xml_to_obj</tt> implementations in
 SingleAttributeNode call two new methods introduced by
 SingleAttributeNode, which must be overwritten by subclasses:
 
-  extract_attr_value(xml)
+    extract_attr_value(xml)
 
-  set_attr_value(xml, value)
+    set_attr_value(xml, value)
 
 <tt>extract_attr_value(xml)</tt> is called by <tt>xml_to_obj</tt>
 during unmarshalling. _xml_ is the XML tree being read. The method
@@ -1028,7 +1788,7 @@ XML. SingleAttributeNode will catch this exception and put the default
 value, if it was defined, into the attribute.
 
 
-==== SubObjectBaseNode
+#### SubObjectBaseNode
 
 The initializer will set up additional member variables @sub_mapping,
 @marshaller, and @unmarshaller.
@@ -1045,7 +1805,7 @@ procs are there to be called from <tt>extract_attr_value</tt> or
 <tt>set_attr_value</tt> whenever the need arises.
 
 
-== {XPath Interpreter}[a:xpath]
+## XPath Interpreter
 
 XML::XXPath is an XPath parser. It is used in xml-mapping node type
 definitions, but can just as well be utilized stand-alone (it does not
@@ -1053,32 +1813,34 @@ depend on xml-mapping). XML::XXPath is very incomplete and probably
 will always be, but it should be reasonably efficient (XPath
 expressions are precompiled), and, most importantly, it supports write
 access, which is needed for writing objects to XML. For example, if
-you create the path "/foo/bar[3]/baz[@key='hiho']" in the XML document
+you create the path <tt>/foo/bar[3]/baz[@key='hiho']</tt> in the XML
+document
 
-  <foo>
-    <bar>
-      <baz key="ab">hello</baz>
-      <baz key="xy">goodbye</baz>
-    </bar>
-  </foo>
+    <foo>
+      <bar>
+        <baz key="ab">hello</baz>
+        <baz key="xy">goodbye</baz>
+      </bar>
+    </foo>
 
 , you'll get:
 
-  <foo>
-    <bar>
-      <baz key='ab'>hello</baz>
-      <baz key='xy'>goodbye</baz>
-    </bar>
-    <bar/>
-    <bar>
-      <baz key='hiho'/>
-    </bar>
-  </foo>
+    <foo>
+      <bar>
+        <baz key='ab'>hello</baz>
+        <baz key='xy'>goodbye</baz>
+      </bar>
+      <bar/>
+      <bar>
+        <baz key='hiho'/>
+      </bar>
+    </foo>
 
 XML::XXPath is explained in more detail in the reference documentation
-and the README_XPATH file.
+and the user_manual_xxpath file.
 
 
-== License
+## License
 
-Ruby's.
+xml-mapping is licensed under the Apache License, version 2.0. See the
+LICENSE file for details.