Feature Request - Raw HTML in ddoc comments

[Bruno Medeiros]

Janice Caron wrote:
> On 01/03/2008, Walter Bright <newshound1 at digitalmars.com> wrote:

For what it matters I think Janice is right in the sense that we have a 
problem with DDoc here. But let me put it in my terms:

I think that there are two issues under discussion here:

What DDoc can be.
What DDoc currently is (this one might not seem an issue, but it is).

== What DDoc can be?:
Option 1: DDoc is simply a macro expansion system. Nothing is said about 
what the output format means, so it can be HTML, PDF, whatever. This is 
actually pretty bad, since because there are is no standard to what the 
output means, tools cannot make assumptions about it, and thus work with 
in a standard way. For example, an IDE could macro-process the DDoc but 
then it wouldn't know how to render it.

Option 2: DDoc is a macro expansion system, but specifies how the output 
text should be interpreted. It can say it should be interpreted as HTML 
for example (or a subset of it). Now tools can interpret it, but you 
can't write output for other targets (or at least shouldn't).

Option 3: DDoc is a markup language, besides a macro expansion system. 
This allows conversion for different targets, such as HTML, PDF, but in 
my opinion seems overkill. Why invent another markup language, if we 
already have HTML and others (like Wiki formatting, etc.). To me option 
2 seems the ideal.

== What DDoc currrently is?:
Well, the problem here is that this is ambiguous:
Walter stated that: "ddoc is a text macro processing program. It does 
not know what html is.". That would be option 1.

However, not only does this suck, but dmd has functionality that 
generates HTML output from DDoc, which will makes assuming HTML output 
somewhat a de-facto standard. For example the Eclipse IDEs (Descent and 
Mmrnhrmm) assume HTML output when they render DDoc in popups. If you try 
to put something else there, it will look garbled. So I would argue that 
DDoc is more like Option 2 than 1.


Janice Caron wrote:
 > 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.

Following on what I said above, you could only have a 
destination-independent of writing things if DDoc was option 3 - a 
proper markup language. Which it isn't. Should it be? Well, that's 
another discussion.


-- 
Bruno Medeiros - MSc in CS/E student
http://www.prowiki.org/wiki4d/wiki.cgi?BrunoMedeiros#D