.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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 "DOM 3pm"
.TH DOM 3pm "2004-03-23" "perl v5.12.4" "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::Generator::DOM \- XML::Generator subclass for producing DOM trees instead of strings.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use XML::Generator::DOM;
\&
\&        my $dg  = XML::Generator::DOM\->new();
\&        my $doc = $dg\->xml($dg\->xmlcmnt("Test document."),
\&                           $dg\->foo({\*(Aqbaz\*(Aq => \*(Aqbam\*(Aq}, 42));
\&        print $doc\->toString;
.Ve
.PP
yields:
.PP
.Vb 3
\&        <?xml version="1.0" standalone="yes"?>
\&        <!\-\-Test document\-\->
\&        <foo baz="bam">42</foo>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::Generator::DOM subclasses XML::Generator in order to produce \s-1DOM\s0
trees instead of strings (see XML::Generator and \s-1XML::DOM\s0).  This
module is still experimental and its semantics might change.
.PP
Essentially, tag methods return XML::DOM::DocumentFragment objects,
constructed either from a \s-1DOM\s0 document passed into the constructor or
a default document that XML::Generator::DOM will automatically construct.
.PP
Calling the \fIxml()\fR method will return this automatically constructed
document and cause a fresh one to be constructed for future tag method
calls.  If you passed in your own document, you may not call the \fIxml()\fR
method.
.PP
Below, we just note the remaining differences in semantics between
XML::Generator methods and XML::Generator::DOM methods.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
These configuration options are accepted but have no effect on the
semantics of the returned object: escape, pretty, conformance and
empty.
.SH "TAG METHODS"
.IX Header "TAG METHODS"
Subsequently, tag method semantics are somewhat different for
this module compared to XML::Generator.  The primary difference is
that tag method return XML::DOM::DocumentFragment objects.  Namespace
and attribute processing remains the same, but remaining arguments to
tag methods must either be text or other XML::DOM::DocumentFragment
objects.  No escape processing, syntax checking, or output control is
done; this is all left up to \s-1XML::DOM\s0.
.SH "SPECIAL TAGS"
.IX Header "SPECIAL TAGS"
All special tags are available by default with XML::Generator::DOM; you don't
need to use 'conformance' => 'strict'.
.SS "xmlpi(@args)"
.IX Subsection "xmlpi(@args)"
Arguments will simply be concatenated and passed as the data to
the XML::DOM::ProcessingInstruction object that is returned.
.SS "xmlcmnt"
.IX Subsection "xmlcmnt"
Escaping of '\-\-' is done by XML::DOM::Comment, which replaces both
hyphens with '&#45;'.  An XML::DOM::Comment object is returned.
.SS "xmldecl"
.IX Subsection "xmldecl"
Returns an XML::DOM::XMLDecl object.  Respects 'version', 'encoding'
and 'dtd' settings in the object.
.SS "xmldecl"
.IX Subsection "xmldecl"
Returns an XML::DOM::DocumentType object.
.SS "xmlcdata"
.IX Subsection "xmlcdata"
Returns an XML::DOM::CDATASection object.
.SS "xml"
.IX Subsection "xml"
As described above, \fIxml()\fR can only be used when dom_document was not
set in the object.  The automatically created document will have its \s-1XML\s0
Declaration set and the arguments to \fIxml()\fR will be appended to it.  Then
a new \s-1DOM\s0 document is automatically generated and the old one is
returned.  This is the only way to get a \s-1DOM\s0 document from this module.