gistfile1.txt

There's a similar problem when using inline doc style: declarative POD cannot be easily nested inside a section, if that is what you want.  For example if you are following manpage conventions, you'd want to start a DESCRIPTION block, then drop out of POD and put declaratives around your module, then end the DESCRIPTION block (explicitly, or implicitly by starting, say, a SEE ALSO block.

There's actually a way to get part of the way (=alias directives) but it is NYI.   Having the ability to =alias before a declarative pod directive and populate the alias with the rendered pod would be nice.   e.g.

=alias DOCSFORFOO
#| does foo things
sub foo {
}

=begin DECRIPTION

A<DOCSFORFOO>

=end

would give:
SYNOPSIS:
sub foo()
    does foo things

...but I'm not sure how that's specced to work.

Nicer would be a way to cut back to ambient code while staying inside pod block nesting.  I thought I remembered there being a tricky, and also NYI, way to do that but can't find it in the spec anymore.