diff options
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/XML/LibXML/DOM.pod')
-rwxr-xr-x | Master/tlpkg/tlperl.straw/lib/XML/LibXML/DOM.pod | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/XML/LibXML/DOM.pod b/Master/tlpkg/tlperl.straw/lib/XML/LibXML/DOM.pod new file mode 100755 index 00000000000..27fd92c6d59 --- /dev/null +++ b/Master/tlpkg/tlperl.straw/lib/XML/LibXML/DOM.pod @@ -0,0 +1,142 @@ +=head1 NAME + +XML::LibXML::DOM - XML::LibXML DOM Implementation + +=head1 DESCRIPTION + +XML::LibXML provides an light-wight interface to I<<<<<< modify >>>>>> a node of the document tree generated by the XML::LibXML parser. This interface +follows as far as possible the DOM Level 3 specification. Additionally to the +specified functions the XML::LibXML supports some functions that are more handy +to use in the perl environment. + +One also has to remember, that XML::LibXML is an interface to libxml2 nodes +which actually reside on the C-Level of XML::LibXML. This means each node is a +reference to a structure different than a perl hash or array. The only way to +access these structure's values is through the DOM interface provided by +XML::LibXML. This also means, that one I<<<<<< can't >>>>>> simply inherit a XML::LibXML node and add new member variables as they were +hash keys. + +The DOM interface of XML::LibXML does not intend to implement a full DOM +interface as it is done by XML::GDOME and used for full featured application. +Moreover, it offers an simple way to build or modify documents that are created +by XML::LibXML's parser. + +Another target of the XML::LibXML interface is to make the interfaces of +libxml2 available to the perl community. This includes also some workarounds to +some features where libxml2 assumes more control over the C-Level that most +perl users don't have. + +One of the most important parts of the XML::LibXML DOM interface is, that the +interfaces try do follow the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>) rather strictly. This means the interface functions are named as the DOM +specification says and not what widespread Java interfaces claim to be +standard. Although there are several functions that have only a singular +interface that conforms to the DOM spec XML::LibXML provides an additional Java +style alias interface. + +Also there are some function interfaces left over from early stages of +XML::LibXML for compatibility reasons. These interfaces are for compatibility +reasons I<<<<<< only >>>>>>. They might disappear in one of the future versions of XML::LibXML, so a user +is requested to switch over to the official functions. + + +=head2 Encodings and XML::LibXML's DOM implementation + +See the section on Encodings in the I<<<<<< XML::LibXML >>>>>> manual page. + + +=head2 Namespaces and XML::LibXML's DOM implementation + +XML::LibXML's DOM implementation is limited by the DOM implementation of +libxml2 which treats namespaces slightly differently than required by the DOM +Level 2 specification. + +According to the DOM Level 2 specification, namespaces of elements and +attributes should be persistent, and nodes should be permanently bound to +namespace URIs as they get created; it should be possible to manipulate the +special attributes used for declaring XML namespaces just as other attributes +without affecting the namespaces of other nodes. In DOM Level 2, the +application is responsible for creating the special attributes consistently +and/or for correct serialization of the document. + +This is both inconvenient, causes problems in serialization of DOM to XML, and +most importantly, seems almost impossible to implement over libxml2. + +In libxml2, namespace URI and prefix of a node is provided by a pointer to a +namespace declaration (appearing as a special xmlns attribute in the XML +document). If the prefix or namespace URI of the declaration changes, the +prefix and namespace URI of all nodes that point to it changes as well. +Moreover, in contrast to DOM, a node (element or attribute) can only be bound +to a namespace URI if there is some namespace declaration in the document to +point to. + +Therefore current DOM implementation in XML::LibXML tries to treat namespace +declarations in a compromise between reason, common sense, limitations of +libxml2, and the DOM Level 2 specification. + +In XML::LibXML, special attributes declaring XML namespaces are often created +automatically, usually when a namespaced node is attached to a document and no +existing declaration of the namespace and prefix is in the scope to be reused. +In this respect, XML::LibXML DOM implementation differs from the DOM Level 2 +specification according to which special attributes for declaring the +apropriate XML namespaces should not be added when a node with a namespace +prefix and namespace URI is created. + +Namespace declarations are also created when L<<<<<< XML::LibXML::Document >>>>>>'s createElementNS() or createAttributeNS() function are used. If the a +namespace is not declared on the documentElement, the namespace will be locally +declared for the newly created node. In case of Attributes this may look a bit +confusing, since these nodes cannot have namespace declarations itself. In this +case the namespace is internally applied to the attribute and later declared on +the node the attribute is appended to (if required). + +The following example may explain this a bit: + + + + my $doc = XML::LibXML->createDocument; + my $root = $doc->createElementNS( "", "foo" ); + $doc->setDocumentElement( $root ); + + my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" ); + $root->setAttributeNodeNS( $attr ); + +This piece of code will result in the following document: + + + + <?xml version="1.0"?> + <foo xmlns:bar="bar" bar:foo="test"/> + +The namespace is declared on the document element during the +setAttributeNodeNS() call. + +Namespaces can be also declared explicitly by the use of XML::LibXML:Element's +setNamespace() function. Since 1.61, they can also be manipulated with +functions setNamespaceDeclPrefix() and setNamespaceDeclURI() (not available in +DOM). Changing an URI or prefix of an existing namespace declaration affects +the namespace URI and prefix of all nodes which point to it (that is the nodes +in its scope). + +It is also important to repeat the specification: While working with namespaces +you should use the namespace aware functions instead of the simplified +versions. For example you should I<<<<<< never >>>>>> use setAttribute() but setAttributeNS(). + +=head1 AUTHORS + +Matt Sergeant, +Christian Glahn, +Petr Pajas + + +=head1 VERSION + +1.70 + +=head1 COPYRIGHT + +2001-2007, AxKit.com Ltd. + +2002-2006, Christian Glahn. + +2006-2009, Petr Pajas. + +=cut |