update documentation explaining insert method rules, and clarify PDOM explanation

[wchristian]

@adamkennedy :

Why are there restrictions on what type of Element can be inserted before or after another Element? It does not seem to help the document remain viable Perl code, since it's entirely possible to insert a block or arbitrary token in front of a subscript structure. At the same time it causes people to have to make weird contortions for seemingly simple acts like adding a simple statement after a block.

I tried to look at the git history, but that only leads back to the import from CSV in 2006. Looking at http://parseperl.cvs.sourceforge.net/viewvc/parseperl/ seems to imply that those functions were introduced inbetween the end of sourceforge history and git import.

There does not seem to be a justification in the documentation or comments.

Unless there's a reason for this that i can document, i'd like to simply remove these restrictions.

[wchristian]

As some of the heavier users, you two could probably provide insight here as well, @thaljef and @rjbs.

[wchristian]

As per #79 (comment) and following, there exists documentation explaining this, but it still needs to be cross-linked, and the PDOM explanation could use some straightening up to make it a little less ambiguous.