Andrei's Google Talk

[Andrei Alexandrescu]

Steven Schveighoffer wrote:
> On Fri, 06 Aug 2010 11:48:00 -0400, Jacob Carlborg <doob at me.com> wrote:
> 
>> On 2010-08-06 17:41, Alexander Malakhov wrote:
>>> Steven Schveighoffer <schveiguy at yahoo.com> писал(а) в своём письме Fri,
>>> 06 Aug 2010 18:28:41 +0700:
>>>
>>>> 2. It seems like the documentation is HTML written as ddoc. I see $(P)
>>>> tags, $(LI) tags, etc. Can't we just write it as HTML?
>>>
>>> I have had exactly same thought when I've first seen DDoc a week ago
>>>
>>>
>>>> I think many would feel much more comfortable that way.
>>>
>>> I have virtually zero exp with HTML/XML, but DDocs syntax seems to be
>>> pretty
>>> straightforward
>>>
>>>> It's also more supported by editors. I forgot a closing parentheses on
>>>> one tag, and it screwed up the entire page. I had to find it by hand,
>>>> whereas an HTML editor could red-flag a tag without a closing tag, or
>>>> you could run it through an XML verifier (if it's xhtml).
>>>
>>> Good points. And XML is not going to disappear anytime soon, so there 
>>> will
>>> always be a lot of people familiar with it, as wall as tool for it.
>>> So I think it would be reasonable to have <tag/> syntax and HTML tags
>>> like <B>, <I> etc.
>>>
>>> Also, for example, what if I want to put extra ')' paren into $(D text)?
>>> I think there is (simple) solution, but that is one more thing to learn.
>>> In the end it's just markup language and I don't see much use in 
>>> learning
>>> more then one of them.
> 
>>>
>>> One reason of it I can think of: parsing speed and ambiguities (same as
>>> with <templates>)
>>>
>>> Anyway, when D will take over the world, they will have to change HTML
>>> syntax to fit what everyone already knows )
>>
>> One reason is why HTML is not used directly is that you could output 
>> the documentation in other formats than HTML, like PDF. A second 
>> reason to use macros (i.e. $(B arg)) instead of HTML is that this 
>> allows you to have the macro expand into something like this <span 
>> class="bold">arg</span> instead of <b>arg<b>. Of course one could 
>> define a language in XML to use instead of the macros.
> 
> Does ddoc output in pdf?

I have an experimental std.ddoc that generates TeX.

I understand your arguments - they're pretty much echoing those of 
myself and of Janice Caron when we first saw the Phobos docs. It didn't 
take me a long time to appreciate ddoc. Right now I'm considering 
converting my entire website to use ddoc. HTML is a pile of dung to 
actually write text in, and somehow I always up editing the raw HTML no 
matter how much editors are trying to hide it from me.

So how about this - give it a while and it's not impossible that your 
view might change.


Andrei