Andrei's Google Talk

[Steven Schveighoffer]

On Fri, 06 Aug 2010 15:02:26 -0400, Andrei Alexandrescu  
<SeeWebsiteForEmail at erdani.org> wrote:

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

Heh. by editor I meant vim :)   I meant syntax highlighting, and matching  
tags, not something like frontpage.

I wouldn't mind the current docs, but I'd like to have some document to  
know what tags are defined and what they mean (like a ddocdoc), and how to  
define new tags.  Maybe this already exists?

The one issue I had is that closing tags are hard to spot.  When I edited  
the arrays.dd file, first vim refused to do any syntax highlighting, so  
everything was black and white (horror!).  Second, while adding anchors to  
all the headers (which by the way are still in html), I missed one closing  
parentheses.  So ddoc decided to match the global closing $(D_SPEC tag  
with the opening $(LNAME2 tag I forgot to close.  The result was no menu  
appeared on the left.  A proper html editor (not wysiwyg) would have  
highlighted tags, and flagged the missing <a> closing tag if I had done  
the anchors that way.

I'm not saying html is the end-all of the docs, I think we need some sort  
of macro system.  But perhaps we can use an already-existing one instead  
of ddoc.

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

I don't plan on writing tons of standalone ddoc documentation :)  I  
generally just comment my functions and let ddoc take care of the  
generation.  For documenting code, I think ddoc is great.  But the spec is  
not code.  It contains code snipits, and I think ddoc is great for those,  
but simply spitting out a bullet list is handled just fine by html or some  
other standard markup language.

-Steve