moxml 0.1.7 → 0.1.9

data/README.adoc

@@ -41,6 +41,10 @@ https://github.com/opal/opal[Opal].
 
 Ox:: https://github.com/ohler55/ox[Ox], a fast XML parser.
 
+LibXML:: https://github.com/xml4r/libxml-ruby[libxml-ruby], Ruby bindings
+for the performant https://github.com/GNOME/libxml2[libxml2] C library.
+Alternative to Nokogiri with similar performance characteristics.
+
 === Feature table
 
 Moxml exercises its best effort to provide a consistent interface across basic
@@ -51,41 +55,408 @@ The following table summarizes the features supported by each library.
 NOTE: The checkmarks indicate support for the feature, while the footnotes
 provide additional context for specific features.
 
-[cols="1,1,1,1,3"]
+[cols="1,1,1,1,1,3"]
 |===
-|Feature |Nokogiri |Oga |REXML |Ox
+|Feature |Nokogiri |Oga |REXML |LibXML |Ox |HeadedOx
 
 |Parsing, serializing
 | ✅
 | ✅
 | ✅
 | ✅
+| ✅
+| ✅
+
+|SAX parsing
+| ✅ Full (10/10 events)
+| ✅ Full (10/10 events)
+| ✅ Full (10/10 events)
+| ✅ Full (10/10 events)
+| ⚠️ Core (4/10 events) See NOTE 7.
+| ⚠️ Core (4/10 events) See NOTE 7.
 
 |Node manipulation
 | ✅
 | ✅
 | ✅
+| ✅
+| ✅ See NOTE 1.
 | ✅ See NOTE 1.
 
 |Basic XPath
 | ✅
 | ✅
 | ✅
-a|
-Uses `locate`. See NOTE 2.
+| ✅
+| Uses Ox-specific API `locate`. See NOTE 2.
+| ✅ Full XPath 1.0. See NOTE 3.
 
 |XPath with namespaces
 | ✅
 | ✅
 | ❌
-a|
-Uses `locate`. See NOTE 2.
+| ✅
+| Uses Ox-specific API `locate`. See NOTE 2.
+| ⚠️ Basic. See NOTE 3.
+
+|===
 
+NOTE: Ox/HeadedOx: Text node replacement may fail in some cases due to internal
+node structure.
+
+NOTE: Limited XPath support via `locate()` method. See adapter limitations
+section.
+
+NOTE: HeadedOx provides full XPath 1.0 support via a pure Ruby XPath engine
+layered on top of Ox's C parser. See HeadedOx documentation for details.
+
+NOTE: Ox/HeadedOx SAX: Only core events supported (start_element, end_element, characters, errors). No separate CDATA, comment, or processing instruction events.
+
+== Adapter comparison
+
+=== Feature compatibility matrix
+
+[cols="3,1,1,1,1,1,1", options="header"]
+|===
+| Feature/Operation | Nokogiri | Oga | REXML | LibXML | Ox | HeadedOx
+
+| *Core Operations*
+|
+|
+|
+|
+|
+|
+
+| Parse XML string
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Parse XML file/IO
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Serialize to XML
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| *Element Operations*
+|
+|
+|
+|
+|
+|
+
+| Create elements
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Get/set attributes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Add/remove children
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Replace nodes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Limited^1^
+| ⚠️ Limited^1^
+
+| *Namespace Operations*
+|
+|
+|
+|
+|
+|
+
+| Add namespaces
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Default namespaces
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Basic
+| ⚠️ Basic
+
+| Namespace inheritance
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ❌ None^5^
+
+| Namespaced attributes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Limited
+| ⚠️ Limited^5^
+
+| *XPath Queries*
+|
+|
+|
+|
+|
+|
+
+| Basic paths (`//element`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Attribute predicates (`[@id]`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Existence only^2^
+| ✅ Full
+
+| Attribute values (`[@id='123']`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None^3^
+| ✅ Full
+
+| Logical operators (`[@a and @b]`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ✅ Full
+
+| Position predicates (`[1]`, `[last()]`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ✅ Full
+
+| Text predicates (`[text()='x']`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ✅ Full
+
+| Namespace-aware queries
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ⚠️ Basic^5^
+
+| Parent axis (`..`)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ✅ Full
+
+| Sibling axes
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ❌ None^5^
+
+| XPath functions (`count()`, etc.)
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ❌ None
+| ✅ All 27
+
+| *Special Content*
+|
+|
+|
+|
+|
+|
+
+| CDATA sections
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Comments
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| Processing instructions
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ✅ Full
+
+| DOCTYPE declarations
+| ✅ Full
+| ✅ Full
+| ✅ Full
+| ⚠️ Limited^4^
+| ✅ Full
+| ✅ Full
+
+| *Performance*
+|
+|
+|
+|
+|
+|
+
+| Parse speed
+| Fast
+| Fast
+| Medium
+| Fast
+| Very Fast
+| Very Fast
+
+| Serialize speed
+| Fast
+| Fast
+| Medium
+| Medium
+| Very Fast
+| Very Fast
+
+| Memory usage
+| Good
+| Medium
+| Medium
+| Good
+| Excellent
+| Excellent
+
+| Thread safety
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
+| ✅ Yes
 |===
 
-NOTE 1: Ox's node manipulation may have issues, especially when manipulating Text nodes.
+^1^ Ox/HeadedOx: Text node replacement may fail in some cases due to internal node structure +
+^2^ Ox: `//book[@id]` works (returns all book elements), but doesn't filter by attribute existence +
+^3^ HeadedOx: Full XPath 1.0 with all 27 functions and 6 axes. Pure Ruby XPath engine on Ox's C parser. 99.20% pass rate. See link:docs/headed-ox.adoc[] +
+^4^ Ox: Use `.find { |el| el["id"] == "123" }` instead of XPath attribute value predicates +
+^5^ LibXML: DOCTYPE parsing works, serialization is limited (no round-trip preservation) +
+^6^ HeadedOx limitations: Namespace introspection and 7 axes not implemented. See link:docs/HEADED_OX_LIMITATIONS.md[]
+
+=== Adapter selection guide
+
+*Choose Nokogiri when:*
+
+* You need industry-standard compatibility
+* Large community support is important
+* C extension performance is acceptable
+* Cross-platform deployment is required
+
+*Choose Oga when:*
+
+* Pure Ruby environment is required (JRuby, TruffleRuby)
+* Best test coverage is needed (98%)
+* No C extensions are allowed
+* Memory usage is not the primary concern
+
+*Choose REXML when:*
+
+* Standard library only (no external gems)
+* Maximum portability is required
+* Small to medium documents
+* Deployment simplicity is critical
+
+*Choose LibXML when:*
+
+* Alternative to Nokogiri is desired
+* Full namespace support is required
+* Good performance with correctness
+* Native C extension is acceptable
+
+*Choose Ox when:*
+
+* Maximum parsing speed is critical
+* Simple document structures (limited nesting)
+* XPath usage is minimal or absent
+* Memory efficiency is paramount
+
+*Choose HeadedOx when:*
+
+* Need Ox's fast parsing with full XPath support
+* Want comprehensive XPath 1.0 features (functions, predicates)
+* Prefer pure Ruby XPath implementation for debugging
+* Need more XPath capabilities than standard Ox provides
+* Memory efficiency is important but XPath features are required
+
+CAUTION: Ox's custom XPath engine supports common patterns but may not handle
+complex XPath expressions. Test thoroughly if your use case requires advanced
+XPath.
 
-NOTE 2: The native Ox method `locate` is similar to XPath but has a different syntax.
 
 == Getting started
 
@@ -97,16 +468,13 @@ Install the gem and at least one supported XML library:
 ----
 # In your Gemfile
 gem 'moxml'
-gem 'nokogiri'  # Or 'oga', 'rexml', or 'ox'
+gem 'nokogiri'  # Or 'oga', 'rexml', 'ox', or 'libxml-ruby'
 ----
 
 === Basic document creation
 
 [source,ruby]
 ----
-require 'moxml'
-
-# Create a new XML document
 doc = Moxml.new.create_document
 
 # Add XML declaration
@@ -126,6 +494,42 @@ root.add_child(title)
 puts doc.to_xml(indent: 2)
 ----
 
+== Real-world examples
+
+Practical, runnable examples demonstrating Moxml usage in common scenarios are
+available in the link:examples/[examples directory].
+
+These examples include:
+
+link:examples/rss_parser/[**RSS Parser**]::
+Parse RSS/Atom feeds with XPath queries and namespace handling
+
+link:examples/web_scraper/[**Web Scraper**]::
+Extract data from HTML/XML using DOM navigation and table parsing
+
+link:examples/api_client/[**API Client**]::
+Build and parse XML API requests/responses with SOAP
+
+Each example is:
+
+* Fully documented with detailed README
+* Self-contained and runnable
+* Demonstrates best practices
+* Includes sample data files
+* Shows comprehensive error handling
+
+Run any example directly:
+
+[source,shell]
+----
+ruby examples/rss_parser/rss_parser.rb
+ruby examples/web_scraper/web_scraper.rb
+ruby examples/api_client/api_client.rb
+----
+
+See the link:examples/README.md[examples README] for complete documentation and
+learning paths.
+
 == Working with documents
 
 === Using the builder pattern
@@ -174,6 +578,7 @@ doc.add_child(root)
 # Add elements with attributes
 book = doc.create_element('book')
 book['id'] = 'b1'
+book['type'] = 'technical'
 root.add_child(book)
 
 # Add mixed content
@@ -183,286 +588,80 @@ title.text = 'Ruby Programming'
 book.add_child(title)
 ----
 
-== XML objects and their methods
-
-=== Document object
-
-The Document object represents an XML document and serves as the root container
-for all XML nodes.
-
-[source,ruby]
-----
-# Creating a document
-doc = Moxml.new.create_document
-doc = Moxml.new.parse(xml_string)
-
-# Document properties and methods
-doc.encoding               # Get document encoding
-doc.encoding = "UTF-8"     # Set document encoding
-doc.version                # Get XML version
-doc.version = "1.1"        # Set XML version
-doc.standalone             # Get standalone declaration
-doc.standalone = "yes"     # Set standalone declaration
-
-# Document structure
-doc.root                  # Get root element
-doc.children              # Get all top-level nodes
-doc.add_child(node)       # Add a child node
-doc.remove_child(node)    # Remove a child node
-
-# Node creation methods
-doc.create_element(name)    # Create new element
-doc.create_text(content)    # Create text node
-doc.create_cdata(content)   # Create CDATA section
-doc.create_comment(content) # Create comment
-doc.create_processing_instruction(target, content) # Create PI
-
-# Document querying
-doc.xpath(expression)      # Find nodes by XPath
-doc.at_xpath(expression)   # Find first node by XPath
-
-# Serialization
-doc.to_xml(options)        # Convert to XML string
-----
-
-=== Element object
+=== Fluent interface API
 
-Elements are the primary structural components of an XML document, representing
-tags with attributes and content.
+Moxml provides a fluent, chainable API for improved developer experience:
 
 [source,ruby]
 ----
-# Element properties
-element.name               # Get element name
-element.name = "new_name"  # Set element name
-element.text              # Get text content
-element.text = "content"   # Set text content
-element.inner_text        # Get text content for current node only
-element.inner_xml         # Get inner XML content
-element.inner_xml = xml   # Set inner XML content
-
-# Attributes
-element[name]             # Get attribute value
-element[name] = value     # Set attribute value
-element.attributes        # Get all attributes
-element.remove_attribute(name) # Remove attribute
-
-# Namespace handling
-element.namespace         # Get element's namespace
-element.namespace = ns     # Set element's namespace
-element.add_namespace(prefix, uri) # Add new namespace
-element.namespaces        # Get all namespace definitions
-
-# Node structure
-element.parent            # Get parent node
-element.children          # Get child nodes
-element.add_child(node)   # Add child node
-element.remove_child(node) # Remove child node
-element.add_previous_sibling(node) # Add sibling before
-element.add_next_sibling(node)    # Add sibling after
-element.replace(node)     # Replace with another node
-element.remove           # Remove from document
-
-# Node type checking
-element.element?         # Returns true
-element.text?           # Returns false
-element.cdata?          # Returns false
-element.comment?        # Returns false
-element.processing_instruction? # Returns false
-
-# Node querying
-element.xpath(expression)  # Find nodes by XPath
-element.at_xpath(expression) # Find first node by XPath
-----
-
-=== Text object
-
-Text nodes represent character data in the XML document.
-
-[source,ruby]
+element = doc.create_element('book')
+  .set_attributes(id: "123", type: "technical")
+  .with_namespace("dc", "http://purl.org/dc/elements/1.1/")
+  .with_child(doc.create_element("title"))
 ----
-# Creating text nodes
-text = doc.create_text("content")
-
-# Text properties
-text.content             # Get text content
-text.content = "new"     # Set text content
-
-# Node type checking
-text.text?              # Returns true
-
-# Structure
-text.parent             # Get parent node
-text.remove             # Remove from document
-text.replace(node)      # Replace with another node
-----
-
-=== CDATA object
-
-CDATA sections contain text that should not be parsed as markup.
-
-[source,ruby]
-----
-# Creating CDATA sections
-cdata = doc.create_cdata("<raw>content</raw>")
-
-# CDATA properties
-cdata.content           # Get CDATA content
-cdata.content = "new"   # Set CDATA content
-
-# Node type checking
-cdata.cdata?           # Returns true
-
-# Structure
-cdata.parent           # Get parent node
-cdata.remove           # Remove from document
-cdata.replace(node)    # Replace with another node
-----
-
-=== Comment object
-
-Comments contain human-readable notes in the XML document.
-
-[source,ruby]
-----
-# Creating comments
-comment = doc.create_comment("Note")
-
-# Comment properties
-comment.content         # Get comment content
-comment.content = "new" # Set comment content
 
-# Node type checking
-comment.comment?        # Returns true
+For complete fluent API documentation including all chainable methods, convenience methods, and practical examples, see link:docs/_guides/working-with-documents.adoc[Working with Documents Guide].
 
-# Structure
-comment.parent          # Get parent node
-comment.remove         # Remove from document
-comment.replace(node)   # Replace with another node
-----
 
-=== Processing instruction object
+=== SAX (Event-Driven) Parsing
 
-Processing instructions provide instructions to applications processing the XML.
+SAX (Simple API for XML) provides memory-efficient, event-driven XML parsing for large documents.
 
-[source,ruby]
-----
-# Creating processing instructions
-pi = doc.create_processing_instruction("xml-stylesheet",
-  'type="text/xsl" href="style.xsl"')
-
-# PI properties
-pi.target              # Get PI target
-pi.target = "new"      # Set PI target
-pi.content             # Get PI content
-pi.content = "new"     # Set PI content
-
-# Node type checking
-pi.processing_instruction? # Returns true
-
-# Structure
-pi.parent             # Get parent node
-pi.remove             # Remove from document
-pi.replace(node)      # Replace with another node
-----
+**When to use SAX:**
 
-=== Attribute object
+* Processing very large XML files (>100MB)
+* Memory-constrained environments
+* Streaming data extraction
+* Need to process data as it arrives
 
-Attributes represent name-value pairs on elements.
+**Quick example:**
 
 [source,ruby]
 ----
-# Attribute properties
-attr.name              # Get attribute name
-attr.name = "new"      # Set attribute name
-attr.value            # Get attribute value
-attr.value = "new"     # Set attribute value
-
-# Namespace handling
-attr.namespace         # Get attribute's namespace
-attr.namespace = ns    # Set attribute's namespace
-
-# Node type checking
-attr.attribute?        # Returns true
-----
+class BookExtractor < Moxml::SAX::ElementHandler
+  attr_reader :books
 
-=== Namespace object
+  def initialize
+    super
+    @books = []
+  end
 
-Namespaces define XML namespaces used in the document.
+  def on_start_element(name, attributes = {}, namespaces = {})
+    super
+    @books << { id: attributes["id"] } if name == "book"
+  end
+end
 
-[source,ruby]
+handler = BookExtractor.new
+Moxml.new.sax_parse(xml_string, handler)
+puts handler.books.inspect
 ----
-# Namespace properties
-ns.prefix             # Get namespace prefix
-ns.uri               # Get namespace URI
 
-# Formatting
-ns.to_s              # Format as xmlns declaration
+For complete SAX documentation including all handler types, event methods, adapter support, and best practices, see link:docs/_guides/sax-parsing.adoc[SAX Parsing Guide].
 
-# Node type checking
-ns.namespace?        # Returns true
-----
-
-=== Node traversal and inspection
+== XML objects and their methods
 
-Each node type provides methods for traversing the document structure:
+For complete node API reference including traversal methods, manipulation, queries, type checking, and node information, see link:docs/_pages/node-api-reference.adoc[Node API Reference].
 
-[source,ruby]
-----
-node.parent              # Get parent node
-node.children            # Get child nodes
-node.next_sibling        # Get next sibling
-node.previous_sibling    # Get previous sibling
-
-# Type checking
-node.element?          # Is it an element?
-node.text?             # Is it a text node?
-node.cdata?            # Is it a CDATA section?
-node.comment?          # Is it a comment?
-node.processing_instruction? # Is it a PI?
-node.attribute?        # Is it an attribute?
-node.namespace?        # Is it a namespace?
-
-# Node information
-node.document          # Get owning document
-----
 
 == Advanced features
 
-=== XPath querying and node mapping
-
-==== Nokogiri, Oga, REXML
+=== XPath querying
 
-Moxml provides efficient XPath querying by leveraging the native XML library's
-implementation while maintaining consistent node mapping:
+Moxml provides efficient XPath querying with consistent node mapping:
 
 [source,ruby]
 ----
 # Find all book elements
 books = doc.xpath('//book')
-# Returns Moxml::Element objects mapped to native nodes
 
 # Find with namespaces
-titles = doc.xpath('//dc:title',
-  'dc' => 'http://purl.org/dc/elements/1.1/')
+titles = doc.xpath('//dc:title', 'dc' => 'http://purl.org/dc/elements/1.1/')
 
 # Find first matching node
 first_book = doc.at_xpath('//book')
-
-# Chain queries
-doc.xpath('//book').each do |book|
-  # Each book is a mapped Moxml::Element
-  title = book.at_xpath('.//title')
-  puts "#{book['id']}: #{title.text}"
-end
 ----
 
-==== Ox
-
-The native Ox's query method
-https://www.ohler.com/ox/Ox/Element.html#method-i-locate[`locate`] resembles
-XPath but has a different syntax.
-
 === Namespace handling
 
 [source,ruby]
@@ -472,62 +671,35 @@ element.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
 
 # Create element in namespace
 title = doc.create_element('dc:title')
-title.text = 'Document Title'
-
-# Query with namespaces
-doc.xpath('//dc:title',
-  'dc' => 'http://purl.org/dc/elements/1.1/')
-----
-
-=== Accessing native implementation
-
-While not typically needed, you can access the underlying XML library's nodes:
-
-[source,ruby]
 ----
-# Get native node
-native_node = element.native
 
-# Get adapter being used
-adapter = element.context.config.adapter
+For complete documentation on XPath querying, namespace handling, and accessing native implementations, see link:docs/_guides/advanced-features.adoc[Advanced Features Guide].
 
-# Create from native node
-element = Moxml::Element.new(native_node, context)
-----
 
 == Error handling
 
-Moxml provides specific error classes for different types of errors that may
-occur during XML processing:
+Moxml provides comprehensive error classes with enhanced context for debugging:
 
 [source,ruby]
 ----
 begin
-  doc = context.parse(xml_string)
+  doc = Moxml.new.parse(xml_string, strict: true)
+  results = doc.xpath("//book[@id='123']")
 rescue Moxml::ParseError => e
-  # Handles XML parsing errors
-  puts "Parse error at line #{e.line}, column #{e.column}"
-  puts "Message: #{e.message}"
-rescue Moxml::ValidationError => e
-  # Handles XML validation errors
-  puts "Validation error: #{e.message}"
+  puts "Parse failed at line #{e.line}: #{e.message}"
 rescue Moxml::XPathError => e
-  # Handles XPath expression errors
-  puts "XPath error: #{e.message}"
-rescue Moxml::NamespaceError => e
-  # Handles namespace errors
-  puts "Namespace error: #{e.message}"
+  puts "XPath error: #{e.expression}"
 rescue Moxml::Error => e
-  # Handles other Moxml-specific errors
-  puts "Error: #{e.message}"
+  puts "XML processing error: #{e.message}"
 end
 ----
 
-== Configuration
+For complete error class hierarchy, error types, best practices, and debugging techniques, see link:docs/_pages/error-handling.adoc[Error Handling Guide].
 
-=== General
 
-Moxml can be configured globally or per instance.
+== Configuration
+
+Moxml can be configured globally or per instance:
 
 [source,ruby]
 ----
@@ -539,124 +711,115 @@ Moxml.configure do |config|
 end
 
 # Instance configuration
-moxml = Moxml.new do |config|
+context = Moxml.new do |config|
   config.adapter = :oga
   config.strict = false
 end
 ----
 
-=== Default adapter selection
+For all configuration options, adapter selection, serialization options, and environment-based configuration, see link:docs/_pages/configuration.adoc[Configuration Guide].
 
-To select a non-default adapter, set it before processing any input using the
-following syntax.
 
-[source,ruby]
-----
-Moxml::Config.default_adapter = <adapter-symbol>
-----
 
-Where, `<adapter-symbol>` is one of the following:
+== Thread safety
 
-`:rexml`:: REXML
+For complete information on thread-safe patterns, context management, and concurrent processing, see the link:docs/_pages/thread-safety.adoc[Thread Safety Guide].
 
-`:nokogiri`:: Nokogiri (default)
 
-`:oga`:: Oga
+== Performance considerations
 
-`:ox`:: Ox
+For detailed performance optimization strategies, memory management best practices, and efficient querying patterns, see the link:docs/_pages/performance.adoc[Performance Considerations Guide].
 
+== Best practices
 
-== Thread safety
+For comprehensive best practices covering XPath queries, adapter selection, error handling, namespace handling, memory management, thread safety, performance optimization, and testing strategies, see link:docs/_pages/best-practices.adoc[Best Practices Guide].
 
-Moxml is thread-safe when used properly. Each instance maintains its own state
-and can be used safely in concurrent operations:
 
-[source,ruby]
-----
-class XmlProcessor
-  def initialize
-    @mutex = Mutex.new
-    @context = Moxml.new
-  end
+== Specific adapter limitations
 
-  def process(xml)
-    @mutex.synchronize do
-      doc = @context.parse(xml)
-      # Modify document
-      doc.to_xml
-    end
-  end
-end
-----
+=== Ox adapter
 
-== Performance considerations
+The Ox adapter provides maximum parsing speed but has XPath limitations.
 
-=== Memory management
+**XPath limitations:**
 
-Moxml maintains a node registry to ensure consistent object mapping:
+* No attribute value predicates: `//book[@id='123']` ❌
+* No logical operators, position predicates, text predicates ❌
+* No namespace queries, parent axis, sibling axes ❌
+* No XPath functions ❌
+
+**Workaround:** Use Ruby enumerable methods:
 
 [source,ruby]
 ----
-doc = context.parse(large_xml)
-# Process document
-doc = nil  # Allow garbage collection of document and registry
-GC.start   # Force garbage collection if needed
+# Instead of: doc.xpath("//book[@id='123']")
+doc.xpath("//book").find { |book| book["id"] == "123" }
 ----
 
-=== Efficient querying
+For complete Ox adapter documentation including all limitations and workarounds, see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
 
-Use specific XPath expressions for better performance:
+=== HeadedOx adapter
 
-[source,ruby]
-----
-# More efficient - specific path
-doc.xpath('//book/title')
+The HeadedOx adapter combines Ox's fast C-based XML parsing with Moxml's comprehensive pure Ruby XPath 1.0 engine.
 
-# Less efficient - requires full document scan
-doc.xpath('//title')
+**Status:** Production-ready v1.2 (99.20% pass rate, 1,992/2,008 tests)
 
-# Most efficient - direct child access
-root.xpath('./*/title')
-----
+**Key features:**
 
-== Best practices
+* Fast XML parsing (Ox C extension)
+* All 27 XPath 1.0 functions
+* 6 XPath axes (child, descendant, parent, attribute, self, descendant-or-self)
+* Expression caching for performance
+* Pure Ruby XPath engine (debuggable)
 
-=== Document creation
+**When to use:**
+
+* Need Ox's fast parsing with comprehensive XPath
+* Want XPath functions (count, sum, contains, etc.)
+* Prefer pure Ruby XPath for debugging
+* Basic namespace queries are sufficient
 
 [source,ruby]
 ----
-# Preferred - using builder pattern
-doc = Moxml::Builder.new(Moxml.new).build do
-  declaration version: "1.0", encoding: "UTF-8"
-  element 'root' do
-    element 'child' do
-      text 'content'
-    end
-  end
-end
+# Use HeadedOx adapter
+context = Moxml.new(:headed_ox)
+doc = context.parse(xml_string)
 
-# Alternative - direct manipulation
-doc = Moxml.new.create_document
-doc.add_child(doc.create_declaration("1.0", "UTF-8"))
-root = doc.create_element('root')
-doc.add_child(root)
+# Full XPath 1.0 support
+books = doc.xpath('//book[@price < 20]')
+count = doc.xpath('count(//book)')
+titles = doc.xpath('//book/title[contains(., "Ruby")]')
 ----
 
-=== Node manipulation
+For complete HeadedOx documentation including architecture, XPath capabilities, known limitations, and usage examples, see link:docs/_pages/adapters/headed-ox.adoc[HeadedOx Adapter Guide] and link:docs/HEADED_OX_LIMITATIONS.md[Limitations Documentation].
 
-[source,ruby]
-----
-# Preferred - chainable operations
-element
-  .add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
-  .add_child(doc.create_text('content'))
-
-# Preferred - clear node type checking
-if node.element?
-  node.add_namespace('dc', 'http://purl.org/dc/elements/1.1/')
-  node.add_child(doc.create_text('content'))
-end
-----
+
+==== LibXML adapter
+
+*DOCTYPE Limitations:*
+
+* DOCTYPE parsing works
+* DOCTYPE round-trip preservation is limited
+* DOCTYPE cannot be reliably re-serialized after parsing
+
+*Performance:*
+
+* Serialization speed: ~120 ips (slower than target)
+* Parsing speed: Good
+* For high-throughput serialization, consider Ox or Nokogiri
+
+=== Other adapters
+
+*Nokogiri, Oga, REXML:*
+
+All three adapters have near-complete feature support with only minor edge case
+limitations. Use these adapters when you need full XPath and namespace support.
+
+
+
+== Development and testing
+
+For complete information on development setup, testing strategies, benchmarking, and coverage reporting, see the link:docs/_guides/development-testing.adoc[Development and Testing Guide].
 
 == Contributing
 
@@ -670,6 +833,5 @@ end
 
 Copyright Ribose.
 
-This project is licensed under the BSD-2-Clause License. See the
+This project is licensed under the Ribose 3-Clause BSD License. See the
 link:LICENSE.md[] file for details.
-