Feature Request - Raw HTML in ddoc comments

Leandro Lucarella llucax at gmail.com
Fri Feb 22 17:17:59 PST 2008


Janice Caron, el 22 de febrero a las 20:56 me escribiste:
> On 22/02/2008, Leandro Lucarella <llucax at gmail.com> wrote:
> > But HTML sucks for writing documentation!
> 
> Opinions differ on that point.
> 
> I can show you a WYSIWYG HTML editor. Can you show me a WYSIWYG ddoc editor?

I don't want to use a WYSISWYG HTML editor when writing code.

> I can show you text editors that auto-complete HTML. Can you show me a
> text editor that auto-completes ddoc?

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

If you just followed my link and saw what is RST about, you have noticed
that...

> For that matter, what I actually /use/ is a text editor which
> syntax-highlights correctly formatted HTML. Can you show me a text
> editor which syntax-highlights correctly formats ddoc?

No, and I'm not interested. But there plainty of tools that highlights
doxygen comments for example...

> Can you even show me a tool which validates well-formed ddoc, and
> takes me to the line containing the error if it doesn't?

Again, no. And not interested. That's all problems related to formats that
sucks for being written by humans :)
I don't want to need any tool for validating anything.

> I don't really want to get into a format war. The point is, I have had
> many years experience of working with HTML, I like it, and I'm very
> comfortable with it.

It's nice to know. I can say the exact opposite though.

> That won't be true for everyone, and it may not
> be true for you, but that doesn't negate my experience of it. I find
> it elegant and beautiful.

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.

> And - just as relevant - I wrote a tool to convert HTML to ddoc and it
> took me half an hour, which is /considerably/ less time than it would
> take me to learn ddoc. The way I see it, that should make everybody
> happy. I'll be writing my larger docs in HTML (I'll still use raw ddoc
> for quickly documenting declarations, of course), but nobody but I
> will have to see that. What will go into the source code will be the
> ddoc which gets produced by my tool. Everybody wins.

Well, for me this is irrelevant, I was talking about HTML sucking for
being written by humans, not about your particular documentation process
:)

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.

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
FINALMENTE EL CABALLITO FABIAN VA A PASAR UNA BUENA NAVIDAD
	-- Crónica TV



More information about the Digitalmars-d mailing list