--- /dev/null
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "XML::LibXML::Document 3"
+.TH XML::LibXML::Document 3 "2009-10-07" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+XML::LibXML::Document \- XML::LibXML DOM Document Class
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 3
+\& use XML::LibXML;
+\& # Only methods specific to Document nodes are listed here,
+\& # see XML::LibXML::Node manpage for other methods
+\&
+\& $dom = XML::LibXML::Document\->new( $version, $encoding );
+\& $dom = XML::LibXML::Document\->createDocument( $version, $encoding );
+\& $strURI = $doc\->URI();
+\& $doc\->setURI($strURI);
+\& $strEncoding = $doc\->encoding();
+\& $strEncoding = $doc\->actualEncoding();
+\& $doc\->setEncoding($new_encoding);
+\& $strVersion = $doc\->version();
+\& $doc\->standalone
+\& $doc\->setStandalone($numvalue);
+\& my $compression = $doc\->compression;
+\& $doc\->setCompression($ziplevel);
+\& $docstring = $dom\->toString($format);
+\& $c14nstr = $doc\->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
+\& $ec14nstr = $doc\->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
+\& $str = $doc\->serialize($format);
+\& $state = $doc\->toFile($filename, $format);
+\& $state = $doc\->toFH($fh, $format);
+\& $str = $document\->toStringHTML();
+\& $str = $document\->serialize_html();
+\& $bool = $dom\->is_valid();
+\& $dom\->validate();
+\& $root = $dom\->documentElement();
+\& $dom\->setDocumentElement( $root );
+\& $element = $dom\->createElement( $nodename );
+\& $element = $dom\->createElementNS( $namespaceURI, $qname );
+\& $text = $dom\->createTextNode( $content_text );
+\& $comment = $dom\->createComment( $comment_text );
+\& $attrnode = $doc\->createAttribute($name [,$value]);
+\& $attrnode = $doc\->createAttributeNS( namespaceURI, $name [,$value] );
+\& $fragment = $doc\->createDocumentFragment();
+\& $cdata = $dom\->create( $cdata_content );
+\& my $pi = $doc\->createProcessingInstruction( $target, $data );
+\& my $entref = $doc\->createEntityReference($refname);
+\& $dtd = $document\->createInternalSubset( $rootnode, $public, $system);
+\& $dtd = $document\->createExternalSubset( $rootnode_name, $publicId, $systemId);
+\& $document\->importNode( $node );
+\& $document\->adoptNode( $node );
+\& my $dtd = $doc\->externalSubset;
+\& my $dtd = $doc\->internalSubset;
+\& $doc\->setExternalSubset($dtd);
+\& $doc\->setInternalSubset($dtd);
+\& my $dtd = $doc\->removeExternalSubset();
+\& my $dtd = $doc\->removeInternalSubset();
+\& my @nodelist = $doc\->getElementsByTagName($tagname);
+\& my @nodelist = $doc\->getElementsByTagNameNS($nsURI,$tagname);
+\& my @nodelist = $doc\->getElementsByLocalName($localname);
+\& my $node = $doc\->getElementById($id);
+\& $dom\->indexElements();
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The Document Class is in most cases the result of a parsing process. But
+sometimes it is necessary to create a Document from scratch. The \s-1DOM\s0 Document
+Class provides functions that conform to the \s-1DOM\s0 Core naming style.
+.PP
+It inherits all functions from XML::LibXML::Node as specified in the \s-1DOM\s0 specification. This enables access to the nodes besides
+the root element on document level \- a \f(CW\*(C`DTD\*(C'\fR for example. The support for these nodes is limited at the moment.
+.PP
+While generally nodes are bound to a document in the \s-1DOM\s0 concept it is
+suggested that one should always create a node not bound to any document. There
+is no need of really including the node to the document, but once the node is
+bound to a document, it is quite safe that all strings have the correct
+encoding. If an unbound text node with an \s-1ISO\s0 encoded string is created (e.g.
+with \f(CW$CLASS\fR\->\fInew()\fR), the \f(CW\*(C`toString\*(C'\fR function may not return the expected result.
+.PP
+To prevent such problems, it is recommended to pass all data to XML::LibXML
+methods as character strings (i.e. \s-1UTF\-8\s0 encoded, with the \s-1UTF8\s0 flag on).
+.SH "METHODS"
+.IX Header "METHODS"
+Many functions listed here are extensively documented in the \s-1DOM\s0 Level 3 specification (<http://www.w3.org/TR/DOM\-Level\-3\-Core/>). Please refer to the specification for extensive documentation.
+.IP "new" 4
+.IX Item "new"
+.Vb 1
+\& $dom = XML::LibXML::Document\->new( $version, $encoding );
+.Ve
+.Sp
+alias for \fIcreateDocument()\fR
+.IP "createDocument" 4
+.IX Item "createDocument"
+.Vb 1
+\& $dom = XML::LibXML::Document\->createDocument( $version, $encoding );
+.Ve
+.Sp
+The constructor for the document class. As Parameter it takes the version
+string and (optionally) the encoding string. Simply calling \fIcreateDocument\fR() will create the document:
+.Sp
+.Vb 1
+\& <?xml version="your version" encoding="your encoding"?>
+.Ve
+.Sp
+Both parameter are optional. The default value for \fI\f(CI$version\fI\fR is \f(CW1.0\fR, of course. If the \fI\f(CI$encoding\fI\fR parameter is not set, the encoding will be left unset, which means \s-1UTF\-8\s0 is
+implied.
+.Sp
+The call of \fIcreateDocument\fR() without any parameter will result the following code:
+.Sp
+.Vb 1
+\& <?xml version="1.0"?>
+.Ve
+.Sp
+Alternatively one can call this constructor directly from the XML::LibXML class
+level, to avoid some typing. This will not have any effect on the class
+instance, which is always XML::LibXML::Document.
+.Sp
+.Vb 1
+\& my $document = XML::LibXML\->createDocument( "1.0", "UTF\-8" );
+.Ve
+.Sp
+is therefore a shortcut for
+.Sp
+.Vb 1
+\& my $document = XML::LibXML::Document\->createDocument( "1.0", "UTF\-8" );
+.Ve
+.IP "\s-1URI\s0" 4
+.IX Item "URI"
+.Vb 1
+\& $strURI = $doc\->URI();
+.Ve
+.Sp
+Returns the \s-1URI\s0 (or filename) of the original document. For documents obtained
+by parsing a string of a \s-1FH\s0 without using the \s-1URI\s0 parsing argument of the
+corresponding \f(CW\*(C`parse_*\*(C'\fR function, the result is a generated string unknown-XYZ where \s-1XYZ\s0 is some
+number; for documents created with the constructor \f(CW\*(C`new\*(C'\fR, the \s-1URI\s0 is undefined.
+.Sp
+The value can be modified by calling \f(CW\*(C`setURI\*(C'\fR method on the document node.
+.IP "setURI" 4
+.IX Item "setURI"
+.Vb 1
+\& $doc\->setURI($strURI);
+.Ve
+.Sp
+Sets the \s-1URI\s0 of the document reported by the method \s-1URI\s0 (see also the \s-1URI\s0
+argument to the various \f(CW\*(C`parse_*\*(C'\fR functions).
+.IP "encoding" 4
+.IX Item "encoding"
+.Vb 1
+\& $strEncoding = $doc\->encoding();
+.Ve
+.Sp
+returns the encoding string of the document.
+.Sp
+.Vb 2
+\& my $doc = XML::LibXML\->createDocument( "1.0", "ISO\-8859\-15" );
+\& print $doc\->encoding; # prints ISO\-8859\-15
+.Ve
+.IP "actualEncoding" 4
+.IX Item "actualEncoding"
+.Vb 1
+\& $strEncoding = $doc\->actualEncoding();
+.Ve
+.Sp
+returns the encoding in which the \s-1XML\s0 will be returned by \f(CW$doc\fR\->\fItoString()\fR.
+This is usually the original encoding of the document as declared in the \s-1XML\s0
+declaration and returned by \f(CW$doc\fR\->encoding. If the original encoding is not
+known (e.g. if created in memory or parsed from a \s-1XML\s0 without a declared
+encoding), '\s-1UTF\-8\s0' is returned.
+.Sp
+.Vb 2
+\& my $doc = XML::LibXML\->createDocument( "1.0", "ISO\-8859\-15" );
+\& print $doc\->encoding; # prints ISO\-8859\-15
+.Ve
+.IP "setEncoding" 4
+.IX Item "setEncoding"
+.Vb 1
+\& $doc\->setEncoding($new_encoding);
+.Ve
+.Sp
+This method allows to change the declaration of encoding in the \s-1XML\s0 declaration
+of the document. The value also affects the encoding in which the document is
+serialized to \s-1XML\s0 by \f(CW$doc\fR\->\fItoString()\fR. Use \fIsetEncoding()\fR to remove the encoding
+declaration.
+.IP "version" 4
+.IX Item "version"
+.Vb 1
+\& $strVersion = $doc\->version();
+.Ve
+.Sp
+returns the version string of the document
+.Sp
+\&\fI\fIgetVersion()\fI\fR is an alternative form of this function.
+.IP "standalone" 4
+.IX Item "standalone"
+.Vb 1
+\& $doc\->standalone
+.Ve
+.Sp
+This function returns the Numerical value of a documents \s-1XML\s0 declarations
+standalone attribute. It returns \fI1\fR if standalone=\*(L"yes\*(R" was found, \fI0\fR if standalone=\*(L"no\*(R" was found and \fI\-1\fR if standalone was not specified (default on creation).
+.IP "setStandalone" 4
+.IX Item "setStandalone"
+.Vb 1
+\& $doc\->setStandalone($numvalue);
+.Ve
+.Sp
+Through this method it is possible to alter the value of a documents standalone
+attribute. Set it to \fI1\fR to set standalone=\*(L"yes\*(R", to \fI0\fR to set standalone=\*(L"no\*(R" or set it to \fI\-1\fR to remove the standalone attribute from the \s-1XML\s0 declaration.
+.IP "compression" 4
+.IX Item "compression"
+.Vb 1
+\& my $compression = $doc\->compression;
+.Ve
+.Sp
+libxml2 allows reading of documents directly from gzipped files. In this case
+the compression variable is set to the compression level of that file (0\-8). If
+XML::LibXML parsed a different source or the file wasn't compressed, the
+returned value will be \fI\-1\fR.
+.IP "setCompression" 4
+.IX Item "setCompression"
+.Vb 1
+\& $doc\->setCompression($ziplevel);
+.Ve
+.Sp
+If one intends to write the document directly to a file, it is possible to set
+the compression level for a given document. This level can be in the range from
+0 to 8. If XML::LibXML should not try to compress use \fI\-1\fR (default).
+.Sp
+Note that this feature will \fIonly\fR work if libxml2 is compiled with zlib support and \fItoFile()\fR is used for output.
+.IP "toString" 4
+.IX Item "toString"
+.Vb 1
+\& $docstring = $dom\->toString($format);
+.Ve
+.Sp
+\&\fItoString\fR is a \s-1DOM\s0 serializing function, so the \s-1DOM\s0 Tree is serialized into a \s-1XML\s0 string,
+ready for output.
+.Sp
+\&\s-1IMPORTANT:\s0 unlike toString for other nodes, on document nodes this function
+returns the \s-1XML\s0 as a byte string in the original encoding of the document (see
+the \fIactualEncoding()\fR method)! This means you can simply do:
+.Sp
+.Vb 2
+\& open OUT, $file;
+\& print OUT $doc\->toString;
+.Ve
+.Sp
+regardless of the actual encoding of the document. See the section on encodings
+in XML::LibXML for more details.
+.Sp
+The optional \fI\f(CI$format\fI\fR parameter sets the indenting of the output. This parameter is expected to be an \f(CW\*(C`integer\*(C'\fR value, that specifies that indentation should be used. The format parameter can
+have three different values if it is used:
+.Sp
+If \f(CW$format\fR is 0, than the document is dumped as it was originally parsed
+.Sp
+If \f(CW$format\fR is 1, libxml2 will add ignorable white spaces, so the nodes content
+is easier to read. Existing text nodes will not be altered
+.Sp
+If \f(CW$format\fR is 2 (or higher), libxml2 will act as \f(CW$format\fR == 1 but it add a
+leading and a trailing line break to each text node.
+.Sp
+libxml2 uses a hard-coded indentation of 2 space characters per indentation
+level. This value can not be altered on run-time.
+.IP "toStringC14N" 4
+.IX Item "toStringC14N"
+.Vb 1
+\& $c14nstr = $doc\->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
+.Ve
+.Sp
+See the documentation in XML::LibXML::Node.
+.IP "toStringEC14N" 4
+.IX Item "toStringEC14N"
+.Vb 1
+\& $ec14nstr = $doc\->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
+.Ve
+.Sp
+See the documentation in XML::LibXML::Node.
+.IP "serialize" 4
+.IX Item "serialize"
+.Vb 1
+\& $str = $doc\->serialize($format);
+.Ve
+.Sp
+An alias for \fItoString()\fR. This function was name added to be more consistent
+with libxml2.
+.IP "serialize_c14n" 4
+.IX Item "serialize_c14n"
+An alias for \fItoStringC14N()\fR.
+.IP "serialize_exc_c14n" 4
+.IX Item "serialize_exc_c14n"
+An alias for \fItoStringEC14N()\fR.
+.IP "toFile" 4
+.IX Item "toFile"
+.Vb 1
+\& $state = $doc\->toFile($filename, $format);
+.Ve
+.Sp
+This function is similar to \fItoString()\fR, but it writes the document directly
+into a filesystem. This function is very useful, if one needs to store large
+documents.
+.Sp
+The format parameter has the same behaviour as in \fItoString()\fR.
+.IP "toFH" 4
+.IX Item "toFH"
+.Vb 1
+\& $state = $doc\->toFH($fh, $format);
+.Ve
+.Sp
+This function is similar to \fItoString()\fR, but it writes the document directly to
+a filehandle or a stream. A byte stream in the document encoding is passed to
+the file handle. Do \s-1NOT\s0 apply any \f(CW\*(C`:encoding(...)\*(C'\fR or \f(CW\*(C`:utf8\*(C'\fR PerlIO layer to the filehandle! See the section on encodings in XML::LibXML for more details.
+.Sp
+The format parameter has the same behaviour as in \fItoString()\fR.
+.IP "toStringHTML" 4
+.IX Item "toStringHTML"
+.Vb 1
+\& $str = $document\->toStringHTML();
+.Ve
+.Sp
+\&\fItoStringHTML\fR serialize the tree to a byte string in the document encoding as \s-1HTML\s0. With this
+method indenting is automatic and managed by libxml2 internally.
+.IP "serialize_html" 4
+.IX Item "serialize_html"
+.Vb 1
+\& $str = $document\->serialize_html();
+.Ve
+.Sp
+An alias for \fItoStringHTML()\fR.
+.IP "is_valid" 4
+.IX Item "is_valid"
+.Vb 1
+\& $bool = $dom\->is_valid();
+.Ve
+.Sp
+Returns either \s-1TRUE\s0 or \s-1FALSE\s0 depending on whether the \s-1DOM\s0 Tree is a valid
+Document or not.
+.Sp
+You may also pass in a XML::LibXML::Dtd object, to validate against an external \s-1DTD:\s0
+.Sp
+.Vb 3
+\& if (!$dom\->is_valid($dtd)) {
+\& warn("document is not valid!");
+\& }
+.Ve
+.IP "validate" 4
+.IX Item "validate"
+.Vb 1
+\& $dom\->validate();
+.Ve
+.Sp
+This is an exception throwing equivalent of is_valid. If the document is not
+valid it will throw an exception containing the error. This allows you much
+better error reporting than simply is_valid or not.
+.Sp
+Again, you may pass in a \s-1DTD\s0 object
+.IP "documentElement" 4
+.IX Item "documentElement"
+.Vb 1
+\& $root = $dom\->documentElement();
+.Ve
+.Sp
+Returns the root element of the Document. A document can have just one root
+element to contain the documents data.
+.Sp
+Optionally one can use \fIgetDocumentElement\fR.
+.IP "setDocumentElement" 4
+.IX Item "setDocumentElement"
+.Vb 1
+\& $dom\->setDocumentElement( $root );
+.Ve
+.Sp
+This function enables you to set the root element for a document. The function
+supports the import of a node from a different document tree, but does not
+support a document fragment as \f(CW$root\fR.
+.IP "createElement" 4
+.IX Item "createElement"
+.Vb 1
+\& $element = $dom\->createElement( $nodename );
+.Ve
+.Sp
+This function creates a new Element Node bound to the \s-1DOM\s0 with the name \f(CW$nodename\fR.
+.IP "createElementNS" 4
+.IX Item "createElementNS"
+.Vb 1
+\& $element = $dom\->createElementNS( $namespaceURI, $qname );
+.Ve
+.Sp
+This function creates a new Element Node bound to the \s-1DOM\s0 with the name \f(CW$nodename\fR and placed in the given namespace.
+.IP "createTextNode" 4
+.IX Item "createTextNode"
+.Vb 1
+\& $text = $dom\->createTextNode( $content_text );
+.Ve
+.Sp
+As an equivalent of \fIcreateElement\fR, but it creates a \fIText Node\fR bound to the \s-1DOM\s0.
+.IP "createComment" 4
+.IX Item "createComment"
+.Vb 1
+\& $comment = $dom\->createComment( $comment_text );
+.Ve
+.Sp
+As an equivalent of \fIcreateElement\fR, but it creates a \fIComment Node\fR bound to the \s-1DOM\s0.
+.IP "createAttribute" 4
+.IX Item "createAttribute"
+.Vb 1
+\& $attrnode = $doc\->createAttribute($name [,$value]);
+.Ve
+.Sp
+Creates a new Attribute node.
+.IP "createAttributeNS" 4
+.IX Item "createAttributeNS"
+.Vb 1
+\& $attrnode = $doc\->createAttributeNS( namespaceURI, $name [,$value] );
+.Ve
+.Sp
+Creates an Attribute bound to a namespace.
+.IP "createDocumentFragment" 4
+.IX Item "createDocumentFragment"
+.Vb 1
+\& $fragment = $doc\->createDocumentFragment();
+.Ve
+.Sp
+This function creates a DocumentFragment.
+.IP "createCDATASection" 4
+.IX Item "createCDATASection"
+.Vb 1
+\& $cdata = $dom\->create( $cdata_content );
+.Ve
+.Sp
+Similar to createTextNode and createComment, this function creates a
+CDataSection bound to the current \s-1DOM\s0.
+.IP "createProcessingInstruction" 4
+.IX Item "createProcessingInstruction"
+.Vb 1
+\& my $pi = $doc\->createProcessingInstruction( $target, $data );
+.Ve
+.Sp
+create a processing instruction node.
+.Sp
+Since this method is quite long one may use its short form \fI\fIcreatePI()\fI\fR.
+.IP "createEntityReference" 4
+.IX Item "createEntityReference"
+.Vb 1
+\& my $entref = $doc\->createEntityReference($refname);
+.Ve
+.Sp
+If a document has a \s-1DTD\s0 specified, one can create entity references by using
+this function. If one wants to add a entity reference to the document, this
+reference has to be created by this function.
+.Sp
+An entity reference is unique to a document and cannot be passed to other
+documents as other nodes can be passed.
+.Sp
+\&\fI\s-1NOTE:\s0\fR A text content containing something that looks like an entity reference, will
+not be expanded to a real entity reference unless it is a predefined entity
+.Sp
+.Vb 3
+\& my $string = "&foo;";
+\& $some_element\->appendText( $string );
+\& print $some_element\->textContent; # prints "&foo;"
+.Ve
+.IP "createInternalSubset" 4
+.IX Item "createInternalSubset"
+.Vb 1
+\& $dtd = $document\->createInternalSubset( $rootnode, $public, $system);
+.Ve
+.Sp
+This function creates and adds an internal subset to the given document.
+Because the function automatically adds the \s-1DTD\s0 to the document there is no
+need to add the created node explicitly to the document.
+.Sp
+.Vb 2
+\& my $document = XML::LibXML::Document\->new();
+\& my $dtd = $document\->createInternalSubset( "foo", undef, "foo.dtd" );
+.Ve
+.Sp
+will result in the following \s-1XML\s0 document:
+.Sp
+.Vb 2
+\& <?xml version="1.0"?>
+\& <!DOCTYPE foo SYSTEM "foo.dtd">
+.Ve
+.Sp
+By setting the public parameter it is possible to set \s-1PUBLIC\s0 DTDs to a given
+document. So
+.Sp
+.Vb 2
+\& my $document = XML::LibXML::Document\->new();
+\& my $dtd = $document\->createInternalSubset( "foo", "\-//FOO//DTD FOO 0.1//EN", undef );
+.Ve
+.Sp
+will cause the following declaration to be created on the document:
+.Sp
+.Vb 2
+\& <?xml version="1.0"?>
+\& <!DOCTYPE foo PUBLIC "\-//FOO//DTD FOO 0.1//EN">
+.Ve
+.IP "createExternalSubset" 4
+.IX Item "createExternalSubset"
+.Vb 1
+\& $dtd = $document\->createExternalSubset( $rootnode_name, $publicId, $systemId);
+.Ve
+.Sp
+This function is similar to \f(CW\*(C`createInternalSubset()\*(C'\fR but this \s-1DTD\s0 is considered to be external and is therefore not added to the
+document itself. Nevertheless it can be used for validation purposes.
+.IP "importNode" 4
+.IX Item "importNode"
+.Vb 1
+\& $document\->importNode( $node );
+.Ve
+.Sp
+If a node is not part of a document, it can be imported to another document. As
+specified in \s-1DOM\s0 Level 2 Specification the Node will not be altered or removed
+from its original document (\f(CW\*(C`$node\->cloneNode(1)\*(C'\fR will get called implicitly).
+.Sp
+\&\fI\s-1NOTE:\s0\fR Don't try to use \fIimportNode()\fR to import sub-trees that contain an entity
+reference \- even if the entity reference is the root node of the sub-tree. This
+will cause serious problems to your program. This is a limitation of libxml2
+and not of XML::LibXML itself.
+.IP "adoptNode" 4
+.IX Item "adoptNode"
+.Vb 1
+\& $document\->adoptNode( $node );
+.Ve
+.Sp
+If a node is not part of a document, it can be imported to another document. As
+specified in \s-1DOM\s0 Level 3 Specification the Node will not be altered but it will
+removed from its original document.
+.Sp
+After a document adopted a node, the node, its attributes and all its
+descendants belong to the new document. Because the node does not belong to the
+old document, it will be unlinked from its old location first.
+.Sp
+\&\fI\s-1NOTE:\s0\fR Don't try to \fIadoptNode()\fR to import sub-trees that contain entity references \-
+even if the entity reference is the root node of the sub-tree. This will cause
+serious problems to your program. This is a limitation of libxml2 and not of
+XML::LibXML itself.
+.IP "externalSubset" 4
+.IX Item "externalSubset"
+.Vb 1
+\& my $dtd = $doc\->externalSubset;
+.Ve
+.Sp
+If a document has an external subset defined it will be returned by this
+function.
+.Sp
+\&\fI\s-1NOTE\s0\fR Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
+XML::LibXML is still limited. In particular one may not want use common node
+function on doctype declaration nodes!
+.IP "internalSubset" 4
+.IX Item "internalSubset"
+.Vb 1
+\& my $dtd = $doc\->internalSubset;
+.Ve
+.Sp
+If a document has an internal subset defined it will be returned by this
+function.
+.Sp
+\&\fI\s-1NOTE\s0\fR Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
+XML::LibXML is still limited. In particular one may not want use common node
+function on doctype declaration nodes!
+.IP "setExternalSubset" 4
+.IX Item "setExternalSubset"
+.Vb 1
+\& $doc\->setExternalSubset($dtd);
+.Ve
+.Sp
+\&\fI\s-1EXPERIMENTAL\s0!\fR
+.Sp
+This method sets a \s-1DTD\s0 node as an external subset of the given document.
+.IP "setInternalSubset" 4
+.IX Item "setInternalSubset"
+.Vb 1
+\& $doc\->setInternalSubset($dtd);
+.Ve
+.Sp
+\&\fI\s-1EXPERIMENTAL\s0!\fR
+.Sp
+This method sets a \s-1DTD\s0 node as an internal subset of the given document.
+.IP "removeExternalSubset" 4
+.IX Item "removeExternalSubset"
+.Vb 1
+\& my $dtd = $doc\->removeExternalSubset();
+.Ve
+.Sp
+\&\fI\s-1EXPERIMENTAL\s0!\fR
+.Sp
+If a document has an external subset defined it can be removed from the
+document by using this function. The removed dtd node will be returned.
+.IP "removeInternalSubset" 4
+.IX Item "removeInternalSubset"
+.Vb 1
+\& my $dtd = $doc\->removeInternalSubset();
+.Ve
+.Sp
+\&\fI\s-1EXPERIMENTAL\s0!\fR
+.Sp
+If a document has an internal subset defined it can be removed from the
+document by using this function. The removed dtd node will be returned.
+.IP "getElementsByTagName" 4
+.IX Item "getElementsByTagName"
+.Vb 1
+\& my @nodelist = $doc\->getElementsByTagName($tagname);
+.Ve
+.Sp
+Implements the \s-1DOM\s0 Level 2 function
+.Sp
+In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
+.IP "getElementsByTagNameNS" 4
+.IX Item "getElementsByTagNameNS"
+.Vb 1
+\& my @nodelist = $doc\->getElementsByTagNameNS($nsURI,$tagname);
+.Ve
+.Sp
+Implements the \s-1DOM\s0 Level 2 function
+.Sp
+In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
+.IP "getElementsByLocalName" 4
+.IX Item "getElementsByLocalName"
+.Vb 1
+\& my @nodelist = $doc\->getElementsByLocalName($localname);
+.Ve
+.Sp
+This allows the fetching of all nodes from a given document with the given
+Localname.
+.Sp
+In \s-1SCALAR\s0 context this function returns a XML::LibXML::NodeList object.
+.IP "getElementById" 4
+.IX Item "getElementById"
+.Vb 1
+\& my $node = $doc\->getElementById($id);
+.Ve
+.Sp
+Returns the element that has an \s-1ID\s0 attribute with the given value. If no such
+element exists, this returns undef.
+.Sp
+Note: the \s-1ID\s0 of an element may change while manipulating the document. For
+documents with a \s-1DTD\s0, the information about \s-1ID\s0 attributes is only available if
+\&\s-1DTD\s0 loading/validation has been requested. For \s-1HTML\s0 documents parsed with the
+\&\s-1HTML\s0 parser \s-1ID\s0 detection is done automatically. In \s-1XML\s0 documents, all \*(L"xml:id\*(R"
+attributes are considered to be of type \s-1ID\s0. You can test ID-ness of an
+attribute node with \f(CW$attr\fR\->\fIisId()\fR.
+.Sp
+In versions 1.59 and earlier this method was called \fIgetElementsById()\fR (plural)
+by mistake. Starting from 1.60 this name is maintained as an alias only for
+backward compatibility.
+.IP "indexElements" 4
+.IX Item "indexElements"
+.Vb 1
+\& $dom\->indexElements();
+.Ve
+.Sp
+This function causes libxml2 to stamp all elements in a document with their
+document position index which considerably speeds up XPath queries for large
+documents. It should only be used with static documents that won't be further
+changed by any \s-1DOM\s0 methods, because once a document is indexed, XPath will
+always prefer the index to other methods of determining the document order of
+nodes. XPath could therefore return improperly ordered node-lists when applied
+on a document that has been changed after being indexed. It is of course
+possible to use this method to re-index a modified document before using it
+with XPath again. This function is not a part of the \s-1DOM\s0 specification.
+.Sp
+This function returns number of elements indexed, \-1 if error occurred, or \-2
+if this feature is not available in the running libxml2.
+.SH "AUTHORS"
+.IX Header "AUTHORS"
+Matt Sergeant,
+Christian Glahn,
+Petr Pajas
+.SH "VERSION"
+.IX Header "VERSION"
+1.70
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+2001\-2007, AxKit.com Ltd.
+.PP
+2002\-2006, Christian Glahn.
+.PP
+2006\-2009, Petr Pajas.
projects / catagits/Gitalist.git / blobdiff