www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Ddoc macro syntax

reply Walter Bright <newshound2 digitalmars.com> writes:
On 9/15/2016 4:06 AM, Andrei Alexandrescu wrote:

 I was thinking more about it and figured we could introduce a special macro at
 the very beginning of a .ddoc file or "Macros:" section called
 DDOC_MACRO_CALL_SYNTAX. It may be defined one of the following:

 DDOC_MACRO_CALL_SYNTAX = DDOC

 That's today's syntax.

 DDOC_MACRO_CALL_SYNTAX = CPP

 A macro will be invoked as MACRO(a1, a2).


That will break every usage of function calling examples. (It works in CPP 
because if MACRO is not a macro, the text is left unchanged. In Ddoc, a 
non-existent macro is replaced by the empty string.)



 DDOC_MACRO_CALL_SYNTAX = $CPP

 A macro will be invoked as $MACRO(a1, a2)

 DDOC_MACRO_CALL_SYNTAX = LaTeX

 Macro invocation is \MACRO{a1}{a2}.

 This definition is modular, i.e. it doesn't carry beyond the current document
 (otherwise the semantics of a .dd file depends on the .ddoc file(s) it's used
 with).

 Macro definitions stay the same using $1, $2 etc. but macros invoked by them
 would need to obey the DDOC_MACRO_CALL_SYNTAX defined at the top.



Alternatives:
1. accept more than one syntax
2. have the first encountered usage set the mode
Sep 15 2016
parent reply Jacob Carlborg <doob me.com> writes:
On 2016-09-16 01:53, Walter Bright wrote:

 On 9/15/2016 4:06 AM, Andrei Alexandrescu wrote:

 I was thinking more about it and figured we could introduce a special


 macro at

 the very beginning of a .ddoc file or "Macros:" section called
 DDOC_MACRO_CALL_SYNTAX. It may be defined one of the following:

 DDOC_MACRO_CALL_SYNTAX = DDOC

 That's today's syntax.

 DDOC_MACRO_CALL_SYNTAX = CPP

 A macro will be invoked as MACRO(a1, a2).


 That will break every usage of function calling examples. (It works in
 CPP because if MACRO is not a macro, the text is left unchanged. In
 Ddoc, a non-existent macro is replaced by the empty string.)



 DDOC_MACRO_CALL_SYNTAX = $CPP

 A macro will be invoked as $MACRO(a1, a2)

 DDOC_MACRO_CALL_SYNTAX = LaTeX

 Macro invocation is \MACRO{a1}{a2}.

 This definition is modular, i.e. it doesn't carry beyond the current


 document

 (otherwise the semantics of a .dd file depends on the .ddoc file(s)


 it's used

 with).

 Macro definitions stay the same using $1, $2 etc. but macros invoked


 by them

 would need to obey the DDOC_MACRO_CALL_SYNTAX defined at the top.



 Alternatives:
 1. accept more than one syntax
 2. have the first encountered usage set the mode


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.

-- 
/Jacob Carlborg
Sep 16 2016
parent reply Marco Leise <Marco.Leise gmx.de> writes:
Am Fri, 16 Sep 2016 13:16:35 +0200
schrieb Jacob Carlborg <doob 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.

-- 
Marco
Sep 16 2016
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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 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
Sep 16 2016
parent rikki cattermole <rikki cattermole.co.nz> writes:
On 17/09/2016 1:42 AM, H. S. Teoh via Digitalmars-d wrote:

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


We wouldn't even have to use headings like markdowns because of ddocs! 
(I quite like that part).
Sep 16 2016
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/16/16 9:10 AM, Marco Leise wrote:

 Am Fri, 16 Sep 2016 13:16:35 +0200
 schrieb Jacob Carlborg <doob 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.


Very nice point. Now, who is kiith-sa and what do we need to do to 
integrate that ddoc+markdown project within our toolchain? -- Andrei
Sep 16 2016