Feature Request - Raw HTML in ddoc comments

[Janice Caron]

On 01/03/2008, Walter Bright <newshound1 at digitalmars.com> wrote:
> There's no way to ban it, because ddoc is a text macro processing
>  program. It does not know what html is.

The docs explicitly state, and I quote: "HTML can be embedded into the
documentation comments, and it will be passed through to the HTML
output unchanged."

This, to my mind, is a bug - both in the documentation, and in the
implementation. DMD is at fault here. DMD should /not/ pass HTML
through unchanged. It should sanitize the input, in order specifically
to prevent it from being interpreted as markup in the output format.
The final HTML document which results from the conversion process
should not contain any HTML markup which was not generated by ddoc.

In general, any tool which converts SRC -> DST needs to escape all
characters which would be considered markup in DST. That's true for
every kind of DST, not just for HTML - but it's particularly important
for HTML because the only way we have to test whether our ddoc source
is correct is to compile it and view the results in a web browser. If
HTML is passed through unfiltered, then we will fail to notice that
our ddoc source will not produce valid PDF, for example.

Here's one case where it matters. In the documentation for std.xml,
the ddoc source says something like

    this function converts &amp;amp; to &amp;

because that was the only way I could get it to render in a web browser as

    this function converts &amp; to &

The question is, will that render correctly when converted to PDF? And
if not, what is the destination-independent way of writing something
that will render as "&amp;"?

I would call failing to sanitize, a bug. Except I can't, because it's
behaving as documented.