Feature Request - Raw HTML in ddoc comments

[Leandro Lucarella]

Janice Caron, el 23 de febrero a las 08:56 me escribiste:
> 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.

Ok, all my other rant was about using HTML for documenting the code. For
higher level documentation I agree a WYSIWYG editor could be desirable (I
still think that RST format makes writing documentation much more easy,
but I don't expect to convince you if you didn't took a look at it yet).

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

But this point remains. *You* don't want to autocomplete anything either.
If you do, it's because you are using a complex tool, and you have to use
another tool lo lower the complexity :)

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

No I said that HTML sucks for being written by humans, and under that
circunstances I will tell you over and over again that yes, RTF and MS
Word suck much more. Fortunately nobody writes those formats by hand, but
many people write HTML by hand, and use tools just to ease that task (as
you said, with auto-completion and such).

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

Of course.

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

But you want to write HTML by hand!!! That's my point :)

I don't write .o by hand either, I let the compiler do it processing some
weird format called D, and that's perfectly fine for me :)

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

No, I'm opposing to that feature because if HTML is allowed (which
apparently is), people will start using it and the documentation comments
will became unreadable for humans. Is not that "I don't use it, I don't
want anyone else to use it". I just think it will hurt D as a language,
encouraging bad practices, and making the posibility to export ddoc to
other formats harder and trickier.

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

We agree on this :)

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
Los sueños de los niños son especialmente importantes en su etapa de
formación; si un niño no sueña es que será un pelotudo toda la vida.
	-- Ricardo Vaporeso