On Tuesday, 26 February 2013 at 23:44:32 UTC, Walter Bright wrote:
As Andrei has demonstrated, Ddoc can generate html, pdf, and
ebooks without changing the Ddoc comments.
This is not true in general because ddoc doesn't properly encode
its output for different formats (it doesn't even get html right!)
http://dlang.org/ddoc.html
===
Embedded HTML
HTML can be embedded into the documentation comments, and it will
be passed through to the HTML output unchanged. However, since it
is not necessarily true that HTML will be the desired output
format of the embedded documentation comment extractor, it is
best to avoid using it where practical.
===
This "feature" is why I haven't bothered documenting my html
library: the html examples are incorrectly displayed in the
output!
BTW, using $(LT) and $(GT) is both hideously ugly and still wrong
because other output formats need different characters
escaped/encoded. It obviously isn't practical to macroize every
character just in case.
The easiest way to fix this would be to use the ESCAPES
capability ddoc already has over ALL the comment data (except
Macros: sections) before doing anything else.
This will ensure all data is properly encoded while still keeping
all the macro functionality.
Of course, it will kill the embedded html misfeature, which even
the documentation, as seen above, admits is a bad idea to use
anyway!
