On 2/26/2013 4:08 PM, Adam D. Ruppe wrote:
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
ddoc relies on using the macros to encode for different formats. Setting up the
macros right is something for the user, although the default is for html.
(it doesn't even get html right!)
The default setup should generate standard html. If the html is wrong, that
should be a bug report in bugzilla, not an indictment of the approach.
===
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!
Yes, if you write incorrect html in the ddoc comments, they'll just get passed
through to the output. I don't think that is a fault with ddoc, though.
Of course, it will kill the embedded html misfeature, which even the
documentation, as seen above, admits is a bad idea to use anyway!
It's not actually a feature of ddoc at all. Ddoc just transmits its input to its
output, expanding macros along the way.
