Ddoc macro syntax

[H. S. Teoh via Digitalmars-d]

On Fri, Sep 16, 2016 at 03:10:11PM +0200, Marco Leise via Digitalmars-d wrote:
> Am Fri, 16 Sep 2016 13:16:35 +0200
> schrieb Jacob Carlborg <doob at me.com>:
> 
> > My biggest issue with the macros is not the syntax (I don't like
> > that either) but it's that one needs to use them too much.
> 
> Same for me. I feel like this discussion is probably
> picking out the wrong enemy. Sure macros need some way of
> escaping, but I'm happy with anything that replaces macros in
> common use case scenarios with more readable syntax, just like
> the design goals stated back in the day:
> 
> 1. It looks good as embedded documentation, not just after it
>    is extracted and processed.
> 2. It's easy and natural to write, i.e. minimal reliance on
>    <tags> and other clumsy forms one would never see in a
>    finished document.
> 
> The abundance of macros for common formatting tasks like
> emphasis, (un)ordered lists and - a while ago - inline code,
> contradicts point 2 when compared to a bottom up approach,
> where you take a look at some plain text documents and ask
> yourself: If there is only ASCII, how do people use it
> creatively to convey the idea of formatting in a natural way
> and can we deduce rules from that to automatically transform
> text into PDF/HTML/CHM/...
> I want to think that markdown came into existence like this.
> Someone sat down and formalized a list of things people
> already do and slapped a name on it.
[...]

We have already added `...` last year for code snippets, which made
things much more readable than writing $(D ...) everywhere. Now we're
asking for emphasis and other things like that, that eventually,
basically leads to reinventing markdown.

So why not just implement markdown in the first place?!

We can still have macros for the more complicated things, but having
markdown as a baseline syntax means that you can almost get away without
using any macros for 90% of documentation, which is a big plus.


T

-- 
Talk is cheap. Whining is actually free. -- Lars Wirzenius