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/
