Cross referencing in Ddoc

[Sönke Ludwig]

Am 02.01.2014 22:38, schrieb H. S. Teoh:
> For example,
> using `backticks` to write code snippets is definitely more readable
> than writing $(D backticks), among many other things. But that does
> introduce more syntax, which makes parsing more involved and also
> requires learning more syntax. So, it's a trade-off.

I don't want to argue for as much syntax as Markdown has - even if I'd 
actually find that great, Markdown has become a kind of de-facto 
standard in the programming area - but, overall, at least the aspect of 
learning new syntax is not really worse than learning new macros. There 
may be cases where a form of syntax is more difficult to remember, but 
there are also many cases where the macros are actually harder to learn 
and remember.

Having said that, Markdown, if not implemented using a series of 
regexes, is a crazy format to parse. There is an existing parser in 
vibe.d, though.


>> Case in point: markdown lists will be styled one way. With DDoc
>> macros one can define any style of lists needed. (We've defined
>> BOOKTABLE in addition to a couple of other TABLEs, which works
>> beautifully in HTML and LaTeX; not sure how can be done in Markdown.
>
> Styling is an orthogonal issue. Markdown was designed to translate to
> HTML, so you'd just write CSS stylesheets to customize the output. Ddoc,
> OTOH, was designed to be a generic macro system, so obviously it's
> better at doing macro-based stuff.

Also, an important point is that markdown defines *semantic* primitives. 
They can be translated to whatever is required by the output format. In 
DDOC's case that could simply be some standard macros ($(UL), $(LI)).

BTW to Markdown HTML basically is what macros are to DDOC (just that it 
also has defined semantics). Inline HTML explicitly supported to handle 
advanced cases and, if restricted to semantic tags, provides a pretty 
good basis for translating into other output formats.