Why I'm hesitating to switch to D

[Robert Clipsham]

On 29/06/2011 19:57, Walter Bright wrote:
> 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.

I'm just glad it ditched the horrible @params: etc nonsense that every 
other documentation system seems to have its heart set on.

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

GLINK?

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

I didn't know this. Nor do I intend to!

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

Whenever I've done it it's been fine with items spreading lines, 
providing the whitespace is roughly right. Though I know you don't like 
whitespace aware languages.

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

Should I open an enhancement request in bugzilla?

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

That wouldn't particularly help the above example though. And 
regardless, macros are ugly :D

-- 
Robert
http://octarineparrot.com/