Am Wed, 14 Sep 2016 13:47:43 +0000
schrieb Meta <jared771@gmail.com>:

> On Wednesday, 14 September 2016 at 13:28:23 UTC, Manu wrote:
> > Cheers.
> > Yeah, I need to do better with ddoc.
> >
> > ... I'm just gonna go on the record and say that I am really, really not enjoying ddoc ;)
> 
> I can't say I'm a fan either.

You can replace $(D …) with `…` nowadays. It made me a bit more
of a fan. :)

-- 
Marco

On 09/14/2016 09:47 AM, Meta wrote:
> On Wednesday, 14 September 2016 at 13:28:23 UTC, Manu wrote:
>> Cheers.
>> Yeah, I need to do better with ddoc.
>>
>> ... I'm just gonna go on the record and say that I am really, really
>> not enjoying ddoc ;)
>
> I can't say I'm a fan either.

Why? -- Andrei

On 9/14/2016 5:47 AM, Meta wrote:
> DDOC sections such as Returns, Args, etc.

s/Args/Params/

On 09/14/2016 09:28 AM, Manu via Digitalmars-d wrote:
> ... I'm just gonna go on the record and say that I am really, really
> not enjoying ddoc ;)

I was using ddoc today for the Greeks in DIP1000 and was musing about what makes it annoying. I think a major part is the macro invocation syntax: $(MACRO a1, a2, a3). After writing it for a few dozen times today, I figured it's objectively awkward to type (at least on the US keyboard): the dollar sign followed by the left paren is just unpleasant for mechanical reasons.

The resulting look is alien too, as opposed to the more familiar $MACRO(a1, a2, a3) or the CPP-style MACRO(a1, a2, a3).

There are a couple of un(der)documented tricks without which life is very difficult. For example, people commonly believe that in order to embed a literal comma they need to go like this:

COMMA = ,

and then $(MACRO Hello$(COMMA) world, a2). That scales poorly with the size of the argument. In fact, there's a much better solution:

ARGS = $0

and then $(MACRO $(ARGS Hello, world), a2) allows any amount of text with commas. Sadly no similar solution for unpaired parens.

Also, the fact that the doc opens with the text and then has an obscure "Macros:" line at a point is unpleasant. The macro definitions should come first, followed by a separator and then the content. That would make for a much nicer flow.

There are a few other macros I never leave home without:

ARGS = $0
COMMA = ,
DOLLAR = $
LPAREN = (
RPAREN = )
TAIL = $+
COLON = :
LF = $(LF)
$(LF)
COMMENT =
SP = $(COMMENT space coming) $(COMMENT that was a space)

TAIL sadly doesn't work properly.

Overall: I'm trying to build a list of ddoc grievances that can be fixed. It's the de jure and de facto standard for D documentation (with the ddoc processor or ddox), so we'd do good to improve it.

Please add your own ideas.


Andrei

On 09/14/2016 05:31 PM, Andrei Alexandrescu wrote:
> After writing it for a few dozen times today, I figured it's objectively
> awkward to type (at least on the US keyboard): the dollar sign followed
> by the left paren is just unpleasant for mechanical reasons.
>
> The resulting look is alien too, as opposed to the more familiar
> $MACRO(a1, a2, a3) or the CPP-style MACRO(a1, a2, a3).

I meant to add here: we can improve this in a backward-compatible way by allowing users to choose syntax by means of some notation, e.g. this thing as the first macro:

DD0C_SYNTAX = $(X)

for the existing syntax, vs.

DD0C_SYNTAX = $X()

for the $MACRO(a1, a2) syntax. We may also allow users to define the argument separator, also on a per-document basis. By default:

DDOC_ARGUMENT_SEPARATOR = ,

We may also allow custom parens and so on.


Andrei

On Wednesday, 14 September 2016 at 21:31:51 UTC, Andrei Alexandrescu wrote:

> Please add your own ideas.
>
>
> Andrei

One thing that I didn't like when I used DDOC was that I couldn't find a way to add a block of text directly to the output file. I know that can be done with html, but it's not the same. When I am programming I want to make notes (the way I make comments) but not get bogged down with all the macros/html stuff. Unformatted text is way better than unwritten text. Blocks of markdown would be better, but blocks of text would have helped.

[Maybe this is possible but I was a new D user at that time and haven't had a reason to look into it.]

On 9/14/16 7:04 PM, bachmeier wrote:
> On Wednesday, 14 September 2016 at 21:31:51 UTC, Andrei Alexandrescu wrote:
>
>> Please add your own ideas.
>>
>>
>> Andrei
>
> One thing that I didn't like when I used DDOC was that I couldn't find a
> way to add a block of text directly to the output file. I know that can
> be done with html, but it's not the same. When I am programming I want
> to make notes (the way I make comments) but not get bogged down with all
> the macros/html stuff. Unformatted text is way better than unwritten
> text. Blocks of markdown would be better, but blocks of text would have
> helped.
>
> [Maybe this is possible but I was a new D user at that time and haven't
> had a reason to look into it.]

Do you mean like a macro $(VERBATIM ... text with balanced parens ...)? -- Andrei

On 15 September 2016 at 07:31, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 09/14/2016 09:28 AM, Manu via Digitalmars-d wrote:
>>
>> ... I'm just gonna go on the record and say that I am really, really not enjoying ddoc ;)
>
>
> I was using ddoc today for the Greeks in DIP1000 and was musing about what makes it annoying. I think a major part is the macro invocation syntax: $(MACRO a1, a2, a3). After writing it for a few dozen times today, I figured it's objectively awkward to type (at least on the US keyboard): the dollar sign followed by the left paren is just unpleasant for mechanical reasons.
>
> The resulting look is alien too, as opposed to the more familiar $MACRO(a1,
> a2, a3) or the CPP-style MACRO(a1, a2, a3).
>
> There are a couple of un(der)documented tricks without which life is very difficult. For example, people commonly believe that in order to embed a literal comma they need to go like this:
>
> COMMA = ,
>
> and then $(MACRO Hello$(COMMA) world, a2). That scales poorly with the size
> of the argument. In fact, there's a much better solution:
>
> ARGS = $0
>
> and then $(MACRO $(ARGS Hello, world), a2) allows any amount of text with
> commas. Sadly no similar solution for unpaired parens.
>
> Also, the fact that the doc opens with the text and then has an obscure "Macros:" line at a point is unpleasant. The macro definitions should come first, followed by a separator and then the content. That would make for a much nicer flow.
>
> There are a few other macros I never leave home without:
>
> ARGS = $0
> COMMA = ,
> DOLLAR = $
> LPAREN = (
> RPAREN = )
> TAIL = $+
> COLON = :
> LF = $(LF)
> $(LF)
> COMMENT =
> SP = $(COMMENT space coming) $(COMMENT that was a space)
>
> TAIL sadly doesn't work properly.
>
> Overall: I'm trying to build a list of ddoc grievances that can be fixed. It's the de jure and de facto standard for D documentation (with the ddoc processor or ddox), so we'd do good to improve it.
>
> Please add your own ideas.

I haven't had enough experience for meaningful input. I have
experienced the comma and parens things myself, and I generally just
hate that everything is a macro, like you said yourself above.
It didn't occur to me to attempt the sort of workarounds you
illustrated here, I rather just factored the commas and parens out of
my docs and moved on ;)

Like, I really just don't care enough to try and understand ddoc
sufficiently to have a bag of tricks like those you demonstrated above
to workaround these issues. It's not a skill I *want* to possess,
rather, in this case, it's a skill I'm being forced into.
You're welcome to call me lazy, I'd suggest I'm being realistic.
Perhaps a phobos contributor will be required to work it out (as seems
to be a requirement for me right now), but normal programmers
wouldn't. In 7 years, I've never been motivated to find workarounds to
ddoc shortcomings before now, and now, it's only because people are
hassling me. There's no intrinsic motivation here... one reason I use
D is because I hate the C preprocessor ;)

If I had to suggest, I'd introduce doxygen style \tags alongside the macros, then when people try and type docs in the way they've been doing for decades, it'll just work, and they can get on with their code. Nobody likes writing documentation, it needs to have the minimum possible friction or people just won't.

Added bonus; when you cut&paste C code to adapt bindings, the existing
docs on the C code would remain valid documentation without additional
amendment.
I bind C code regularly, and my goto 'solution' is to just remove the
doxygen doco comments from the translated code and point them to the
C/C++ docs instead.
Again, call me what you like, I think my behaviour is probably typical
though. I'm just being honest.

On 9/14/16 9:28 PM, Manu via Digitalmars-d wrote:
> Like, I really just don't care enough to try and understand ddoc
> sufficiently to have a bag of tricks like those you demonstrated above
> to workaround these issues. It's not a skill I *want* to possess,
> rather, in this case, it's a skill I'm being forced into.
> You're welcome to call me lazy, I'd suggest I'm being realistic.
> Perhaps a phobos contributor will be required to work it out (as seems
> to be a requirement for me right now), but normal programmers
> wouldn't. In 7 years, I've never been motivated to find workarounds to
> ddoc shortcomings before now, and now, it's only because people are
> hassling me. There's no intrinsic motivation here... one reason I use
> D is because I hate the C preprocessor ;)

I don't see those workarounds to ddoc shortcomings. m4 and all macro systems I know of have similar idioms. It's the nature of macro processing. Are you simply saying you're familiar with other documentation tools and are not motivated to get into another one? That's entirely fair.

> If I had to suggest, I'd introduce doxygen style \tags alongside the
> macros, then when people try and type docs in the way they've been
> doing for decades, it'll just work, and they can get on with their
> code. Nobody likes writing documentation, it needs to have the minimum
> possible friction or people just won't.

I have difficulty understanding this. I haven't looked at Doxygen in a long time and never really used it, but from what I see at https://www.stack.nl/~dimitri/doxygen/manual/commands.html it seems the \tags you refer to are just a form of macros. The syntax is different, i.e. you'd write \a hello whereas in html you'd write <i>hello</i>, in latex \textit{hello}, in ddoc $(I hello). It's a matter of syntax and though I agree syntax matters (and it would be nice to make ddoc's more configurable), is it right to assume you simply want a syntax you're more familiar with?

How do you mean people "type docs in the way they've been doing for decades"? Are you implying doxygen not only has been around for decades, but it's been some sort of ubiquitous standard? Honest question, I'm definitely not getting that.

Does this boil down to - if we replace the macro syntax with one closer to doxygen things will just click? (That may as well be the case.)


Andrei

On 9/14/2016 2:31 PM, Andrei Alexandrescu wrote:
> The resulting look is alien too, as opposed to the more familiar $MACRO(a1, a2,
> a3) or the CPP-style MACRO(a1, a2, a3).

The $(MACRO a1, a2, a3) syntax comes from makefiles.