Perhaps i don't understand XML then. All that I want is this:

<?xml version="1.0" encoding="UTF-8">
[download]

Without adding a doctype. The example that I am modeling has neither. I am merely trying to produce exactly what the specs i have in front of me specify. At this point i am very inclined to simply prepend this to my XML:

qq|<?xml version="1.0" encoding="UTF-8" ?>\n|
[download]

Because it works. *shrug* :/

UPDATE: OK ... I finally see what I am doing wrong now. But, in my defense -- these docs are crappy. The solution for me is to not "wrap" the xml() method around the XML tags, but to instead concat the output of xmldecl() to my XML tags:

$gen->xmldecl( standalone => undef ) . $gen->foo( $gen->bar() );
[download]

RANT: why can't people understand that examples are worth a thousand words? I make a strict point to clearly show how to use my code in my documentation because the last thing i want is for people to become frustrated and confused and when using my code.

But it works -- thanks for all your help ikegami!