Andrei's Google Talk

[Steven Schveighoffer]

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?  And besides, most of the tags *are* html tags,  
they're even the same tag name.  I can't imagine there's no htmltopdf  
program that would do exactly that.

Regarding the <span class="bold"> thing, can't you just do this in css:

b {
    whatever;
}

and override what <b> does?  There are probably macros which do other  
things that xhtml/css cannot do, but I don't think we should use macros  
for every html element.  For example, the $(V1) and $(V2) tags.  We need a  
good solution for that, and I think having dmd work those out is fine.  I  
also don't mind using the macros for more dynamic stuff.  I just think the  
formatting stuff can remain html, and all the macros should be  
defined/documented somewhere.

I like this explanation from Alexander:

In the end it's just markup language and I don't see much use in learning  
more then one of them.

It's just a thought, it might be blowing out of proportion a bit.  Granted  
I think I would have felt more comfortable using html directly, but it  
wasn't that hard to learn, and I was able to work through the issues.  I  
just wish I had some editor help...

-Steve