Feature Request - Raw HTML in ddoc comments

[Derek Parnell]

On Sat, 1 Mar 2008 18:51:22 +0000, Janice Caron wrote:

> 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.


I feel that you don't quite understand what Ddoc is or does. It is not a
text to HTML converter. It really does not know anything about HTML, or any
other brand of markup language. The only thing Ddoc does is to transform
macros embedded in the text into *whatever* the macro has been defined to
expand to and to pass all other text *as written*. That's it! The DMD
compiler does two indepenant transformations - it first transforms D
Comments and some D language constrcuts into Ddoc text, then it transforms
the Ddoc text based on the macros that it knows about. By default, Walter
has defined those macros to expand into HTML, but the macro definitions can
be modified by the developer to expand into anything at all.

> 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;

Yes, this is a documentation bug. 

It would have been been written as ...

     this function converts $(AMP)amp$(SC) to $(AMP)$(SC)

AND have a macros 'AMP' and 'SC' defined as ...


AMP=&
SC=;

Because punctuation characters are frequently special to the various markup
languages. However, writing like this can be tedious so maybe Ddoc can be
improved to help automate this.

-- 
Derek Parnell
Melbourne, Australia
skype: derek.j.parnell