Feature Request - Raw HTML in ddoc comments

[Janice Caron]

On 01/03/2008, Derek Parnell <derek at psych.ward> wrote:
> I feel that you don't quite understand what Ddoc is or does.

That is certainly possible. My understanding is that it is a simple
markup language, whereby (for example)

    $(I whatever)

means "whatever" in italics.


> It is not a
> text to HTML converter.

I certainly do know that.


> It really does not know anything about HTML, or any
>  other brand of markup language.

Of course. Nor should it. Just as HTML knows nothing about RTF, or PDF
knows nothing about XML. That absolutely makes sense.


> The only thing Ddoc does is to transform
>  macros embedded in the text

Now I'm confused. Is ddoc the /format/, or the /tool/? Because I'm
hearing inconsistent things here. I thought ddoc was the name of the
/format/.


> The DMD
>  compiler does two indepenant transformations - it first transforms D
>  Comments and some D language constrcuts into Ddoc text,

I thought ddoc comments /were/ ddoc text. Presumably you mean it
isolates them from non-ddoc comments, removes the asterisks, and so
on?


> then it transforms
> the Ddoc text based on the macros that it knows about.

Ooookaaay.

But when DMD produces HTML output from DDOC comments as a result of
the -D command line options, where are these macros "that it knows
about"?

Regardless, wherever it gets them from, the combination of DMD+MACROS
together constitute a translation tool, and if that translation tool
does not escape what needs to be escaped, then that translation tool
is at fault. So maybe I was blaming the wrong component. Certainly
(DMD+MACROS) does not translate correctly (because it doesn't escape).
I was blaming DMD. Perhaps I should instead have blamed "the macros
that it knows about".

But whichever element is responsible, that element should do the job
properly. If it's going to translate "$(I hello)" into "<i>hello</i>"
then it should also translate "<" into "&lt;".


> By default, Walter
> has defined those macros to expand into HTML,

Aha! Then DMD is not at fault at all. But "those macros" are. They
/attempt/ to expand ddoc text into HTML, but they don't do the job
properly.

That is, if I write "&amp;" in the source code, then "&amp;" should be
displayed in the destination document, whether that be a web page, a
PDF document, or whatever.



> Yes, this is a documentation bug.
>
>  It would have been been written as ...
>
>      this function converts $(AMP)amp$(SC) to $(AMP)$(SC)

OK. That part I could do. I could certainly change the source code to
say that - if we are agreed that is the correct thing to do.


>  AND have a macros 'AMP' and 'SC' defined as ...
>
>  AMP=&
>  SC=;

Defined where? In std.xml.d?

Also, defined how?



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

My feeling is that any charater I include in the source which is /not/
a DDOC macro, should end up in the destination document exactly as it
appears in source. If that means escaping should happen along the way,
then escaping should happen automatically.