Feature Request - Raw HTML in ddoc comments

[Janice Caron]

On 23/02/2008, Leandro Lucarella <llucax at gmail.com> wrote:
>  I don't want to use a WYSISWYG HTML editor when writing code.

Nor do I. Perhaps you misunderstood. I was talking about
/documentation/, not code.
Raw ddoc is absolutely perfect for inline doc comments, and Walter has
done a /fantastic/ job in getting a system like that going.

What I'm talking is real documentation, like, actual instruction
manuals - tutorials, fifty or a hundred pages long, or more when
printed. Think "std.whatever For Dummies". A whole book. There is no
way I want to write a whole book in ddoc, and /for that purpose/, a
wysiwyg editor wouldn't be a bad thing.

Using ddoc as the final output remains a good thing, however, because
ddoc format can turn into everything else, including auto-generated
Digital Mars web pages.


> I don't want to auto-complete anything, that's the point :)

It's /a/ point, but it's not /the/ point. When I request something,
it's usually because /I/ want it, so whether or not /you/ want it is
really kind of incidental.

Besides which, *I made the tool*. The deed is done, so I'm not
requesting anything any more. I already have it. I made it myself. If
that tells you anything, it tells you that D is a brilliant language,
if only because that was possible.


> But there plainty of tools that highlights
>  doxygen comments for example...

ddoc! It's perfect for that! No complaints there.

As I said, I was thinking a few orders of magnitude higher than that.


> I'm glad for you, but your experience don't make HTML suck less for
>  humans. All the tools you mention are needed because it *sucks*. If it
>  doesn't suck, you don't need tools to make it suck less.

That's only true if you look at it from the point of view that you're
supposed to interact directly with the source, and that's not
necessarily so. You could argue in exactly the same way that Microsoft
Word format, or RTF, both suck, because you need special tools (i.e.
Microsoft Word or some other word processor) to manipulate them. If
you were to try editing an RTF document by editing the raw text file
with a plain text editor, I'm sure you would quickly come to the
conclusion that RTF sucks. However, that's just not what you do. But
HTML is really just another document format, like Word document or
RTF, and so, from that point of view, the underlying representation
matters less. What matters more is its portability, how easy it is to
convert it to other formats, and the availability of tools to edit it.


> I was talking about HTML sucking for
>  being written by humans, not about your particular documentation process
>  :)

I get that, but you leapt into a thread that I started, basically
telling me that /I/ shouldn't be doing something, or requesting
something, because /you/ don't need it. No disrespect intended, but
... huh?


>  PS: What we do agree is that I don't want to start a war on formats
>     either, just because is too naive to think that Walter will change
>     DDoc for something else.

And nor do I. It's a solved problem.

However, it still remains the case that ddoc documentation /may
contain raw HTML, but its use is strongly discouraged/. That, I think,
is bad. Either don't allow it all, or fully support it.