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.
