I have a pull request up to remove the big misfeature of embedded html in ddoc, and it is pending action, from me, to answer some of Walter's concerns.
But, I was updating the documentation for some of my code (using std.ddoc and my improveddoc post-processor to make it prettier and remove Javascript), and I hit pain. http://arsdnet.net/web.d/std_dom.html#Form.addValueArray It is extremely difficult to document a HTML library when your HTML examples are mis-interpreted as markup! Also, ddoc should outdent the code examples: http://arsdnet.net/web.d/std_cgi.html#Cgi.request The examples are indented in my source to line up with the declarations, but this indentation doesn't make sense in the output!