libxml-ruby 2.8.0 → 3.2.1

data/LICENSE

@@ -1,21 +1,21 @@
-  Copyright (c) 2008-2013 Charlie Savage and contributors
-  Copyright (c) 2002-2007 Sean Chittenden and contributors
-  Copyright (c) 2001 Wai-Sun "Squidster" Chia
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in 
-the Software without restriction, including without limitation the rights to 
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  Copyright (c) 2008-2013 Charlie Savage and contributors
+  Copyright (c) 2002-2007 Sean Chittenden and contributors
+  Copyright (c) 2001 Wai-Sun "Squidster" Chia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies 
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

data/MANIFEST

@@ -1,166 +1,166 @@
-#!mast -x doc/libxml-ruby/rdoc -i .gitignore ext doc lib script test [A-Z]*
-ext/libxml/extconf.rb
-ext/libxml/libxml.c
-ext/libxml/ruby_libxml.h
-ext/libxml/ruby_xml.c
-ext/libxml/ruby_xml.h
-ext/libxml/ruby_xml_attr.c
-ext/libxml/ruby_xml_attr.h
-ext/libxml/ruby_xml_attr_decl.c
-ext/libxml/ruby_xml_attr_decl.h
-ext/libxml/ruby_xml_attributes.c
-ext/libxml/ruby_xml_attributes.h
-ext/libxml/ruby_xml_cbg.c
-ext/libxml/ruby_xml_document.c
-ext/libxml/ruby_xml_document.h
-ext/libxml/ruby_xml_dtd.c
-ext/libxml/ruby_xml_dtd.h
-ext/libxml/ruby_xml_encoding.c
-ext/libxml/ruby_xml_encoding.h
-ext/libxml/ruby_xml_error.c
-ext/libxml/ruby_xml_error.h
-ext/libxml/ruby_xml_html_parser.c
-ext/libxml/ruby_xml_html_parser.h
-ext/libxml/ruby_xml_html_parser_context.c
-ext/libxml/ruby_xml_html_parser_context.h
-ext/libxml/ruby_xml_html_parser_options.c
-ext/libxml/ruby_xml_html_parser_options.h
-ext/libxml/ruby_xml_input_cbg.c
-ext/libxml/ruby_xml_input_cbg.h
-ext/libxml/ruby_xml_io.c
-ext/libxml/ruby_xml_io.h
-ext/libxml/ruby_xml_namespace.c
-ext/libxml/ruby_xml_namespace.h
-ext/libxml/ruby_xml_namespaces.c
-ext/libxml/ruby_xml_namespaces.h
-ext/libxml/ruby_xml_node.c
-ext/libxml/ruby_xml_node.h
-ext/libxml/ruby_xml_parser.c
-ext/libxml/ruby_xml_parser.h
-ext/libxml/ruby_xml_parser_context.c
-ext/libxml/ruby_xml_parser_context.h
-ext/libxml/ruby_xml_parser_options.c
-ext/libxml/ruby_xml_parser_options.h
-ext/libxml/ruby_xml_reader.c
-ext/libxml/ruby_xml_reader.h
-ext/libxml/ruby_xml_relaxng.c
-ext/libxml/ruby_xml_relaxng.h
-ext/libxml/ruby_xml_sax2_handler.c
-ext/libxml/ruby_xml_sax2_handler.h
-ext/libxml/ruby_xml_sax_parser.c
-ext/libxml/ruby_xml_sax_parser.h
-ext/libxml/ruby_xml_schema.c
-ext/libxml/ruby_xml_schema.h
-ext/libxml/ruby_xml_version.h
-ext/libxml/ruby_xml_xinclude.c
-ext/libxml/ruby_xml_xinclude.h
-ext/libxml/ruby_xml_xpath.c
-ext/libxml/ruby_xml_xpath.h
-ext/libxml/ruby_xml_xpath_context.c
-ext/libxml/ruby_xml_xpath_context.h
-ext/libxml/ruby_xml_xpath_expression.c
-ext/libxml/ruby_xml_xpath_expression.h
-ext/libxml/ruby_xml_xpath_object.c
-ext/libxml/ruby_xml_xpath_object.h
-ext/libxml/ruby_xml_xpointer.c
-ext/libxml/ruby_xml_xpointer.h
-ext/mingw/Rakefile
-ext/mingw/build.rake
-ext/mingw/libiconv-2.dll
-ext/mingw/libxml2-2.dll
-ext/mingw/libxml_ruby.dll.a
-ext/mingw/libxml_ruby.so
-ext/vc/libxml_ruby.sln
-ext/vc/libxml_ruby_18/libxml_ruby.vcproj
-ext/vc/libxml_ruby_19/libxml_ruby_19.vcproj
-doc/.htaccess
-doc/.rsync-filter
-lib/libxml/attr.rb
-lib/libxml/attr_decl.rb
-lib/libxml/attributes.rb
-lib/libxml/document.rb
-lib/libxml/error.rb
-lib/libxml/hpricot.rb
-lib/libxml/html_parser.rb
-lib/libxml/namespace.rb
-lib/libxml/namespaces.rb
-lib/libxml/node.rb
-lib/libxml/ns.rb
-lib/libxml/parser.rb
-lib/libxml/properties.rb
-lib/libxml/reader.rb
-lib/libxml/sax_callbacks.rb
-lib/libxml/sax_parser.rb
-lib/libxml/tree.rb
-lib/libxml/xpath_object.rb
-lib/libxml.rb
-lib/xml/libxml.rb
-lib/xml.rb
-script/benchmark/depixelate
-script/benchmark/hamlet.xml
-script/benchmark/parsecount
-script/benchmark/sock_entries.xml
-script/benchmark/throughput
-script/test
-test/etc_doc_to_s.rb
-test/ets_doc_file.rb
-test/ets_doc_to_s.rb
-test/ets_gpx.rb
-test/ets_node_gc.rb
-test/ets_test.xml
-test/ets_tsr.rb
-test/model/atom.xml
-test/model/bands.xml
-test/model/books.xml
-test/model/merge_bug_data.xml
-test/model/ruby-lang.html
-test/model/rubynet.xml
-test/model/rubynet_project
-test/model/shiporder.rnc
-test/model/shiporder.rng
-test/model/shiporder.xml
-test/model/shiporder.xsd
-test/model/soap.xml
-test/model/xinclude.xml
-test/tc_attr.rb
-test/tc_attr_decl.rb
-test/tc_attributes.rb
-test/tc_deprecated_require.rb
-test/tc_document.rb
-test/tc_document_write.rb
-test/tc_dtd.rb
-test/tc_error.rb
-test/tc_html_parser.rb
-test/tc_namespace.rb
-test/tc_namespaces.rb
-test/tc_node.rb
-test/tc_node_cdata.rb
-test/tc_node_comment.rb
-test/tc_node_copy.rb
-test/tc_node_edit.rb
-test/tc_node_pi.rb
-test/tc_node_text.rb
-test/tc_node_write.rb
-test/tc_node_xlink.rb
-test/tc_parser.rb
-test/tc_parser_context.rb
-test/tc_properties.rb
-test/tc_reader.rb
-test/tc_relaxng.rb
-test/tc_sax_parser.rb
-test/tc_schema.rb
-test/tc_traversal.rb
-test/tc_xinclude.rb
-test/tc_xml.rb
-test/tc_xpath.rb
-test/tc_xpath_context.rb
-test/tc_xpath_expression.rb
-test/tc_xpointer.rb
-test/test_suite.rb
-Rakefile
-HISTORY.rdoc
-PROFILE
-TODO
-LICENSE
-README.rdoc
-VERSION
+#!mast -x doc/libxml-ruby/rdoc -i .gitignore ext doc lib script test [A-Z]*
+ext/libxml/extconf.rb
+ext/libxml/libxml.c
+ext/libxml/ruby_libxml.h
+ext/libxml/ruby_xml.c
+ext/libxml/ruby_xml.h
+ext/libxml/ruby_xml_attr.c
+ext/libxml/ruby_xml_attr.h
+ext/libxml/ruby_xml_attr_decl.c
+ext/libxml/ruby_xml_attr_decl.h
+ext/libxml/ruby_xml_attributes.c
+ext/libxml/ruby_xml_attributes.h
+ext/libxml/ruby_xml_cbg.c
+ext/libxml/ruby_xml_document.c
+ext/libxml/ruby_xml_document.h
+ext/libxml/ruby_xml_dtd.c
+ext/libxml/ruby_xml_dtd.h
+ext/libxml/ruby_xml_encoding.c
+ext/libxml/ruby_xml_encoding.h
+ext/libxml/ruby_xml_error.c
+ext/libxml/ruby_xml_error.h
+ext/libxml/ruby_xml_html_parser.c
+ext/libxml/ruby_xml_html_parser.h
+ext/libxml/ruby_xml_html_parser_context.c
+ext/libxml/ruby_xml_html_parser_context.h
+ext/libxml/ruby_xml_html_parser_options.c
+ext/libxml/ruby_xml_html_parser_options.h
+ext/libxml/ruby_xml_input_cbg.c
+ext/libxml/ruby_xml_input_cbg.h
+ext/libxml/ruby_xml_io.c
+ext/libxml/ruby_xml_io.h
+ext/libxml/ruby_xml_namespace.c
+ext/libxml/ruby_xml_namespace.h
+ext/libxml/ruby_xml_namespaces.c
+ext/libxml/ruby_xml_namespaces.h
+ext/libxml/ruby_xml_node.c
+ext/libxml/ruby_xml_node.h
+ext/libxml/ruby_xml_parser.c
+ext/libxml/ruby_xml_parser.h
+ext/libxml/ruby_xml_parser_context.c
+ext/libxml/ruby_xml_parser_context.h
+ext/libxml/ruby_xml_parser_options.c
+ext/libxml/ruby_xml_parser_options.h
+ext/libxml/ruby_xml_reader.c
+ext/libxml/ruby_xml_reader.h
+ext/libxml/ruby_xml_relaxng.c
+ext/libxml/ruby_xml_relaxng.h
+ext/libxml/ruby_xml_sax2_handler.c
+ext/libxml/ruby_xml_sax2_handler.h
+ext/libxml/ruby_xml_sax_parser.c
+ext/libxml/ruby_xml_sax_parser.h
+ext/libxml/ruby_xml_schema.c
+ext/libxml/ruby_xml_schema.h
+ext/libxml/ruby_xml_version.h
+ext/libxml/ruby_xml_xinclude.c
+ext/libxml/ruby_xml_xinclude.h
+ext/libxml/ruby_xml_xpath.c
+ext/libxml/ruby_xml_xpath.h
+ext/libxml/ruby_xml_xpath_context.c
+ext/libxml/ruby_xml_xpath_context.h
+ext/libxml/ruby_xml_xpath_expression.c
+ext/libxml/ruby_xml_xpath_expression.h
+ext/libxml/ruby_xml_xpath_object.c
+ext/libxml/ruby_xml_xpath_object.h
+ext/libxml/ruby_xml_xpointer.c
+ext/libxml/ruby_xml_xpointer.h
+ext/mingw/Rakefile
+ext/mingw/build.rake
+ext/mingw/libiconv-2.dll
+ext/mingw/libxml2-2.dll
+ext/mingw/libxml_ruby.dll.a
+ext/mingw/libxml_ruby.so
+ext/vc/libxml_ruby.sln
+ext/vc/libxml_ruby_18/libxml_ruby.vcproj
+ext/vc/libxml_ruby_19/libxml_ruby_19.vcproj
+doc/.htaccess
+doc/.rsync-filter
+lib/libxml/attr.rb
+lib/libxml/attr_decl.rb
+lib/libxml/attributes.rb
+lib/libxml/document.rb
+lib/libxml/error.rb
+lib/libxml/hpricot.rb
+lib/libxml/html_parser.rb
+lib/libxml/namespace.rb
+lib/libxml/namespaces.rb
+lib/libxml/node.rb
+lib/libxml/ns.rb
+lib/libxml/parser.rb
+lib/libxml/properties.rb
+lib/libxml/reader.rb
+lib/libxml/sax_callbacks.rb
+lib/libxml/sax_parser.rb
+lib/libxml/tree.rb
+lib/libxml/xpath_object.rb
+lib/libxml.rb
+lib/xml/libxml.rb
+lib/xml.rb
+script/benchmark/depixelate
+script/benchmark/hamlet.xml
+script/benchmark/parsecount
+script/benchmark/sock_entries.xml
+script/benchmark/throughput
+script/test
+test/etc_doc_to_s.rb
+test/ets_doc_file.rb
+test/ets_doc_to_s.rb
+test/ets_gpx.rb
+test/ets_node_gc.rb
+test/ets_test.xml
+test/ets_tsr.rb
+test/model/atom.xml
+test/model/bands.xml
+test/model/books.xml
+test/model/merge_bug_data.xml
+test/model/ruby-lang.html
+test/model/rubynet.xml
+test/model/rubynet_project
+test/model/shiporder.rnc
+test/model/shiporder.rng
+test/model/shiporder.xml
+test/model/shiporder.xsd
+test/model/soap.xml
+test/model/xinclude.xml
+test/test_attr.rb
+test/test_attr_decl.rb
+test/test_attributes.rb
+test/test_deprecated_require.rb
+test/test_document.rb
+test/test_document_write.rb
+test/test_dtd.rb
+test/test_error.rb
+test/test_html_parser.rb
+test/test_namespace.rb
+test/test_namespaces.rb
+test/test_node.rb
+test/test_node_cdata.rb
+test/test_node_comment.rb
+test/test_node_copy.rb
+test/test_node_edit.rb
+test/test_node_pi.rb
+test/test_node_text.rb
+test/test_node_write.rb
+test/test_node_xlink.rb
+test/test_parser.rb
+test/test_parser_context.rb
+test/test_properties.rb
+test/test_reader.rb
+test/test_relaxng.rb
+test/test_sax_parser.rb
+test/test_schema.rb
+test/test_traversal.rb
+test/test_xinclude.rb
+test/test_xml.rb
+test/test_xpath.rb
+test/test_xpath_context.rb
+test/test_xpath_expression.rb
+test/test_xpointer.rb
+test/test_suite.rb
+Rakefile
+HISTORY.rdoc
+PROFILE
+TODO
+LICENSE
+README.rdoc
+VERSION

data/README.rdoc

@@ -1,184 +1,217 @@
-= LibXML Ruby
-
-== Overview
-The libxml gem provides Ruby language bindings for GNOME's Libxml2
-XML toolkit. It is free software, released under the MIT License.
-
-We think libxml-ruby is the best XML library for Ruby because:
-
-* Speed - Its much faster than REXML and Hpricot
-* Features - It provides an amazing number of featues
-* Conformance - It passes all 1800+ tests from the OASIS XML Tests Suite
-
-== Requirements
-libxml-ruby requires Ruby 1.8.4 or higher.  It is dependent on 
-the following libraries to function properly:
-
-* libm      (math routines: very standard)
-* libz      (zlib)
-* libiconv
-* libxml2
-
-If you are running Linux or Unix you'll need a C compiler so the
-extension can be compiled when it is installed.  If you are running
-Windows, then install the Windows specific RubyGem which
-includes an already built extension.
-
-== INSTALLATION
-The easiest way to install libxml-ruby is via Ruby Gems.  To install:
-
-<tt>gem install libxml-ruby</tt>
-
-If you are running Windows, make sure to install the Win32 RubyGem
-which includes prebuilt extensions for Ruby 1.8, 1.9 and 2.0 preview.  These
-extensions are built with MinGW32 against libxml2 version 2.9.0,
-iconv version 1.13 and zlib version 1.2.5.  Note these binaries
-are available in the lib\libs directory.  To use them, put them
-someplace on your path.
-
-The gem also includes a Microsoft VC++ 2012 solution (useful for debugging).
-
-libxml-ruby's source codes lives on Github at https://github.com/xml4r/libxml-ruby.
-
-== Getting Started
-Using libxml is easy. First decide what parser you want to use:
-
-* Generally you'll want to use the LibXML::XML::Parser which provides a tree based API.
-* For larger documents that don't fit into memory, or if you prefer an input based API, use the LibXML::XML::Reader.
-* To parse HTML files use LibXML::XML::HTMLParser.
-* If you are masochistic, then use the LibXML::XML::SaxParser, which provides a callback API.
-
-Once you have chosen a parser, choose a datasource.  Libxml can parse files, strings, URIs
-and IO streams.  For each data source you can specify an LibXML::XML::Encoding, a base uri and
-various parser options.  For more information, refer the LibXML::XML::Parser.document,
-LibXML::XML::Parser.file, LibXML::XML::Parser.io or LibXML:::XML::Parser.string methods (the
-same methods are defined on all four parser classes).
-
-== Advanced Functionality
-Beyond the basics of parsing and processing XML and HTML documents,
-libxml provides a wealth of additional functionality.
-
-Most commonly, you'll want to use its LibXML::XML::XPath support, which makes
-it easy to find data inside a XML document.  Although not as popular,
-LibXML::XML::XPointer provides another API for finding data inside an XML document.
-
-Often times you'll need to validate data before processing it. For example,
-if you accept user generated content submitted over the Web, you'll
-want to verify that it does not contain malicious code such as embedded scripts.
-This can be done using libxml's powerful set of validators:
-
-* DTDs (LibXML::XML::Dtd)
-* Relax Schemas (LibXML::XML::RelaxNG)
-* XML Schema (LibXML::XML::Schema)
-
-Finally, if you'd like to use XSL Transformations to process data,
-then install the libxslt gem which is available at
-https://github.com/xml4r/libxslt-ruby.
-
-== Usage
-For information about using libxml-ruby please refer to its documentation at
-http://xml4r.github.com/libxml-ruby/rdoc/index.html. Some tutorials are also
-available at https://github.com/xml4r/libxml-ruby/wiki.
-
-All libxml classes are in the LibXML::XML module. The easiest
-way to use libxml is to require 'xml'.  This will mixin
-the LibXML module into the global namespace, allowing you to
-write code like this:
-
-  require 'xml'
-  document = XML::Document.new
-
-However, when creating an application or library you plan to
-redistribute, it is best to not add the LibXML module to the global
-namespace, in which case you can either write your code like this:
-
-  require 'libxml'
-  document = LibXML::XML::Document.new
-
-Or you can utilize a namespace for your own work and include LibXML into it.
-For example:
-
-  require 'libxml'
-
-  module MyApplication
-    include LibXML
-
-    class MyClass
-      def some_method
-        document = XML::Document.new
-      end
-    end
-  end
-
-For simplicity's sake, the documentation uses the xml module in its examples.
-
-== Memory Management
-libxml-ruby automatically manages memory associated with the
-underlying libxml2 library.  There is however one corner case that
-your code must handle.  If a node is imported into a document, but not
-added to the document, a segmentation fault may occur on program termination.
-
-  # Do NOT do this
-  require 'xml'
-  doc1 = XML::Document.string("test1")
-  doc2 = XML::Document.string("test2")
-  node = doc2.import(doc1.root)
-
-If doc2 is freed before node2 a segmentatin fault will occur since
-node2 references the document.  To avoid this, simply make sure to add the
-node to the document:
-
-  # DO this instead
-  doc1 = XML::Document.string("test1")
-  doc2 = XML::Document.string("test2")
-  doc2.root << doc2.import(doc1.root)
-
-Alternatively, you can call node2.remove! to disassociate node2 from doc2.
-
-== Threading
-libxml-ruby fully supports native, background Ruby threads.  This of course
-only applies to Ruby 1.9.x and higher since earlier versions of Ruby do not
-support native threads.
-
-== Performance
-In addition to being feature rich and conformation, the main reason
-people use libxml-ruby is for performance.  Here are the results 
-of a couple simple benchmarks recently blogged about on the
-Web (you can find them in the benchmark directory of the 
-libxml distribution).
-
-From http://depixelate.com/2008/4/23/ruby-xml-parsing-benchmarks
-
-               user     system      total        real
- libxml    0.032000   0.000000   0.032000 (  0.031000)
- Hpricot   0.640000   0.031000   0.671000 (  0.890000)
- REXML     1.813000   0.047000   1.860000 (  2.031000)
-
-From https://svn.concord.org/svn/projects/trunk/common/ruby/xml_benchmarks/
-
-               user     system      total        real
- libxml    0.641000   0.031000   0.672000 (  0.672000)
- hpricot   5.359000   0.062000   5.421000 (  5.516000)
- rexml    22.859000   0.047000  22.906000 ( 23.203000) 
-
-
-== Documentation
-Documentation is available via rdoc, and is installed automatically with the
-gem.
-
-libxml-ruby's online documentation is generated using Hanna, which is a
-development gem dependency.
-
-Note that older versions of Rdoc, which ship with Ruby 1.8.x, will report
-a number of errors.  To avoid them, install Rdoc 2.1 or higher.  Once you have
-installed the gem, you'll have to disable the version of Rdoc that Ruby 1.8.x
-includes.  An easy way to do that is rename the directory ruby/lib/ruby/1.8/rdoc to
-ruby/lib/ruby/1.8/rdoc_old.
-
-== Support
-
-If you have any questions about using libxml-ruby, please report them to
-Git Hub at https://github.com/xml4r/libxml-ruby/issues
-
-== License
-See LICENSE for license information.
+= LibXML Ruby
+
+== Overview
+The libxml gem provides Ruby language bindings for GNOME's Libxml2
+XML toolkit. It is free software, released under the MIT License.
+
+We think libxml-ruby is the best XML library for Ruby because:
+
+* Speed - Its much faster than REXML and Hpricot
+* Features - It provides an amazing number of featues
+* Conformance - It passes all 1800+ tests from the OASIS XML Tests Suite
+
+== Requirements
+libxml-ruby requires Ruby 1.8.7 or higher.  It depends on libxml2 to
+function properly.  libxml2, in turn, depends on:
+
+* libm      (math routines: very standard)
+* libz      (zlib)
+* libiconv
+
+If you are running Linux or Unix you'll need a C compiler so the
+extension can be compiled when it is installed.  If you are running
+Windows, then install the x64-mingw32 gem or build it yourself using
+Devkit[http://rubyinstaller.org/add-ons/devkit/] or
+msys2[https://msys2.github.io/].
+
+== Installation
+The easiest way to install libxml-ruby is via RubyGems.  To install:
+
+<tt>gem install libxml-ruby</tt>
+
+If the extension compile process cannot find libxml2, you may need to indicate
+the location of the libxml2 configuration utility as it is used to find the
+required header and include files.  (If you need to indicate a location for the
+libxml2 library or header files different than reported by <tt>xml2-config</tt>,
+see the additional configuration options.)
+
+This may be done with RubyGems:
+
+<tt>gem install libxml-ruby -- --with-xml2-dir=/path/to/xml2-config</tt>
+
+Or bundler:
+
+<tt>bundle config build.libxml-ruby --with-xml2-config=/path/to/xml2-config</tt>
+
+<tt>bundle install libxml-ruby</tt>
+
+If you are running Windows, then install the libxml-ruby-x64-mingw32 gem.
+The gem includes prebuilt extensions for Ruby 2.3.  These
+extensions are built using MinGW64 and libxml2 version 2.9.3,
+iconv version 1.14 and zlib version 1.2.8. Note these binaries
+are available in the <tt>lib\\libs</tt> directory.  To use them, put them
+on your <tt>PATH</tt>.
+
+The gem also includes a Microsoft VC++ 2012 solution and XCode 5 project - these
+are very useful for debugging.
+
+libxml-ruby's source codes lives on GitHub[https://github.com/xml4r/libxml-ruby].
+
+== Getting Started
+Using libxml is easy. First decide what parser you want to use:
+
+* Generally you'll want to use the LibXML::XML::Parser which provides a tree based API.
+* For larger documents that don't fit into memory, or if you prefer an input based API, use the LibXML::XML::Reader.
+* To parse HTML files use LibXML::XML::HTMLParser.
+* If you are masochistic, then use the LibXML::XML::SaxParser, which provides a callback API.
+
+Once you have chosen a parser, choose a datasource.  Libxml can parse files, strings, URIs
+and IO streams.  For each data source you can specify an LibXML::XML::Encoding, a base uri and
+various parser options.  For more information, refer the LibXML::XML::Parser.document,
+LibXML::XML::Parser.file, LibXML::XML::Parser.io or LibXML:::XML::Parser.string methods (the
+same methods are defined on all four parser classes).
+
+== Advanced Functionality
+Beyond the basics of parsing and processing XML and HTML documents,
+libxml provides a wealth of additional functionality.
+
+Most commonly, you'll want to use its LibXML::XML::XPath support, which makes
+it easy to find data inside an XML document.  Although not as popular,
+LibXML::XML::XPointer provides another API for finding data inside an XML document.
+
+Often times you'll need to validate data before processing it. For example,
+if you accept user generated content submitted over the Web, you'll
+want to verify that it does not contain malicious code such as embedded scripts.
+This can be done using libxml's powerful set of validators:
+
+* DTDs (LibXML::XML::Dtd)
+* Relax Schemas (LibXML::XML::RelaxNG)
+* XML Schema (LibXML::XML::Schema)
+
+Finally, if you'd like to use XSL Transformations to process data, then install
+the {libxslt gem}[https://github.com/xml4r/libxslt-rubygem].
+
+== Usage
+For information about using libxml-ruby please refer to its
+documentation[http://xml4r.github.io/libxml-ruby]. Some tutorials are also
+available[https://github.com/xml4r/libxml-ruby/wiki].
+
+All libxml classes are in the LibXML::XML module. The easiest
+way to use libxml is to <tt>require 'xml'</tt>.  This will mixin
+the LibXML module into the global namespace, allowing you to
+write code like this:
+
+  require 'xml'
+  document = XML::Document.new
+
+However, when creating an application or library you plan to
+redistribute, it is best to not add the LibXML module to the global
+namespace, in which case you can either write your code like this:
+
+  require 'libxml'
+  document = LibXML::XML::Document.new
+
+Or you can utilize a namespace for your own work and include LibXML into it.
+For example:
+
+  require 'libxml'
+
+  module MyApplication
+    include LibXML
+
+    class MyClass
+      def some_method
+        document = XML::Document.new
+      end
+    end
+  end
+
+For simplicity's sake, the documentation uses the xml module in its examples.
+
+== Threading
+libxml-ruby fully supports native, background Ruby threads.  This of course
+only applies to Ruby 1.9.x and higher since earlier versions of Ruby do not
+support native threads.
+
+== Tests
+
+To run tests you first need to build the shared libary:
+
+  rake compile
+
+Once you have build the shared libary, you can then run tests using rake:
+
+  rake test
+
++Travis build status: {<img src="https://travis-ci.org/xml4r/libxml-ruby.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/xml4r/libxml-ruby]
+
+== Performance
+
+In addition to being feature rich and conformation, the main reason
+people use libxml-ruby is for performance.  Here are the results
+of a couple simple benchmarks recently blogged about on the
+Web (you can find them in the benchmark directory of the
+libxml distribution).
+
+From http://depixelate.com/2008/4/23/ruby-xml-parsing-benchmarks
+
+               user     system      total        real
+ libxml    0.032000   0.000000   0.032000 (  0.031000)
+ Hpricot   0.640000   0.031000   0.671000 (  0.890000)
+ REXML     1.813000   0.047000   1.860000 (  2.031000)
+
+From https://svn.concord.org/svn/projects/trunk/common/ruby/xml_benchmarks/
+
+               user     system      total        real
+ libxml    0.641000   0.031000   0.672000 (  0.672000)
+ hpricot   5.359000   0.062000   5.421000 (  5.516000)
+ rexml    22.859000   0.047000  22.906000 ( 23.203000) 
+
+
+== Documentation
+Documentation is available via rdoc, and is installed automatically with the
+gem.
+
+libxml-ruby's {online
+documentation}[https://xml4r.github.io/libxml-ruby/rdoc/index.html] is generated
+using Hanna, which is a development gem dependency.
+
+Note that older versions of Rdoc, which ship with Ruby 1.8.x, will report
+a number of errors.  To avoid them, install Rdoc 2.1 or higher.  Once you have
+installed the gem, you'll have to disable the version of Rdoc that Ruby 1.8.x
+includes.  An easy way to do that is rename the directory
+<tt>ruby/lib/ruby/1.8/rdoc</tt> to
+<tt>ruby/lib/ruby/1.8/rdoc_old</tt>.
+
+== Support
+If you have any questions about using libxml-ruby, please report an issue
+on GitHub[https://github.com/xml4r/libxml-ruby/issues].
+
+== Memory Management
+libxml-ruby automatically manages memory associated with the
+underlying libxml2 library.  The bindings create a one-to-one mapping between
+Ruby objects and libxml documents and libxml parent nodes (ie, nodes that do not
+have a parent and do not belong to a document).  In these cases,
+the bindings manage the memory.  They do this by installing a free
+function and storing a back pointer to the Ruby object from the xmlnode
+using the _private member on libxml structures.  When the Ruby object
+goes out of scope, the underlying libxml structure is freed.  Libxml
+itself then frees all child nodes (recursively).
+
+For all other nodes (the vast majority), the bindings create temporary
+Ruby objects that get freed once they go out of scope. Thus there can be
+more than one Ruby object pointing to the same xml node. To mostly hide
+this from a programmer on the Ruby side, the <tt>#eql?</tt> and <tt>#==</tt> methods are
+overriden to check if two Ruby objects wrap the same xmlnode.  If they do,
+then the methods return true.  During the mark phase, each of these temporary
+objects marks its owning document, thereby keeping the Ruby document object
+alive and thus the xmldoc tree.
+
+In the sweep phase of the garbage collector, or when a program ends,
+there is no order to how Ruby objects are freed.  In fact, the Ruby document
+object is almost always freed before any Ruby objects that wrap child nodes.
+However, this is ok because those Ruby objects do not have a free function
+and are no longer in scope (since if they were the document would not be freed).
+
+== License
+See LICENSE for license information.