Why I'm hesitating to switch to D

[Walter Bright]

On 6/29/2011 11:42 AM, Robert Clipsham wrote:
>> How did it stop you?
>
> DDoc vs Markdown:
> * Pretty much everyone who uses github, stackoverflow, and many other sites
> knows some amount of markdown
> * I've been using D for years and I pride myself on not knowing the hideous DDoc
> beyond "Params: Example:" etc.

It was deliberately designed so you didn't actually have to know it in order to 
generate fairly reasonable documentation for functions.

> * DDoc macros make even the simplest things ugly
>
> Code:
>
> DDoc:
> $(LINK http://my.url/)
> $(LINK2 http://my.url/, My URL)
>
> Markdown:
> http://my.url/

I agree, that's better. That would be a nice improvement to Ddoc.

> [My URL](http://my.url)

I'm familiar with that from reddit, but I confess to always having to look it up 
first as I never can remember which part goes where :-). But what about the 
other kinds of links, such as GLINK, which Ddoc makes easy? For example, I use a 
macro for links that I redefine in order to make them intrapage links for 
generating an ebook and interpage links for the web site. With a non-macro 
system, I'm faced with editting all the links.


> DDoc:
> $(UL
> $(LI $(LINK2 http://a/, A))
> $(LI Nesting
> $(UL
> $(LI I daren't go another layer deeper $(LPAREN)$(LINK2 http://b/,
> honestly)$(RPAREN)
> )
> )
> )
> )

You don't need the $(LPAREN) and $(RPAREN) unless they are not paired. You don't 
need them in your example.


> Markdown:
> * [A](http://a/)
> * Nesting
> - I could go deeper with this without it being hideous
> + (No really http://foo.bar/)
> + I could just keep going
> * [and it's still not ugly](http://b/)

It looks nice, but I think it only works if the items fit on one line.


> Another bonus of markdown: It (or a subset of it) could probably be added to
> ddoc without much effort given its simplicity, without breaking anything. Seems
> like a no-brainer to me.

Not a bad idea.


> PS: I probably missed some parenthesis in the DDoc version. That's not
> intentional, that just comes from DDoc macros being hideous and just generally
> terrible.

You can define your own macros in Ddoc. I do that frequently for repetitive 
custom work on an individual page.