On Thursday, 15 September 2016 at 03:49:55 UTC, Andrei Alexandrescu wrote:
> 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.

doxygen is mostly javadoc compatible and that one is the standard.
(in fact the \ can be replaced by @ every where) and it allows direct html tags. The good thing about doxygen is that it supports also markdown.
There are also some niceties like auto brief and autoreferencing (when a symbol is written in a text will be clickable if its body was reachable during generation of the doc).

>
> 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.)
>
Probably. But be reminded of your remark in the SDLang vs. JSON thread from last year:
"...this is a strategic error. Please throw s/SDL/DDOC/ away and use a standardized file format. -- Andrei

On 15 September 2016 at 19:23, Jacob Carlborg via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 2016-09-15 09:11, Manu via Digitalmars-d wrote:
>>
>> Do we mind moving this discussion to the other topic I started actually on this topic?
>>
>> It's slightly upsetting that this discussion about ddoc is more popular than the colour lib I spent months workinng on :(
>
>
> Sorry.
>
> Is it the "ddoc latex/formulas?" topic? That's the only recent topic by you related to ddoc. But I have no interest in either latex or formulas.

Yeah, sorry I forgot that detail. That thread meandered in the same direction though.

On 9/15/16 2:11 AM, Walter Bright wrote:
> 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.

In the words of Seinfeld, "And that doesn't help either!"

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

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.

Thoughts?


Andrei

On Thursday, 15 September 2016 at 09:45:26 UTC, Marco Leise wrote:
> Am Wed, 14 Sep 2016 23:44:16 -0700
> schrieb Walter Bright <newshound2@digitalmars.com>:
>
> I suspect that adding Markdown would help a lot (yes, I changed my mind about that).
>


https://github.com/kiith-sa/harbored-mod provides support for mixing ddoc and markdown. That's what we're using, and it's nice (especially because docs in source files look very close to generated ones), but it would be nicer if we could just use dmd for that, of course.

On 09/15/2016 02:55 AM, Jacob Carlborg wrote:
> On 2016-09-14 22:14, Andrei Alexandrescu wrote:
>
>> Why? -- Andrei
>
> I've recently worked on a theme for Ddoc that will be used in TextMate.
> For convince I started by adding the CSS inline in the head tag. Turns
> out if you have CSS looking like this:
>
> .foo {
>   font-weight: bold;
>   background-color: white;
> }
>
> Everything works perfectly fine. Then I added text color as well:
>
> color: black;
>
> Guess what happens? It cuts, it cuts everything after "color". The
> solution is to use a colon macro:
>
> Macros:
>   COLON = :
>
> color$(COLON) black;
>
> It took me quite a while and a lot of frustration until I figured that
> out. But I guess that's an inherit problem with a macro system.

Yah, this is terrible (it happens with http: all the time). We need to suppress the special meaning of ":" to only the cases when it's preceded by only one word and followed by a newline, e,g, "\ncolor:\n".

> That is what I'm missing from Ddoc:
>
> * Inline source code for each symbol [1]. The [1] example both has a
> button to show the source code inline and a direct link to GitHub

Can this be done by defining the expansion macros appropriately?

> * Link to GitHub for each symbol [1] and for the whole module. The way
> it's done now with $(PHOBOSSRC std/net/_isemail.d) is not standardized
> and feels like a hack. Why slashes and why the underscore?

Slashes are tolerable. The underscore I agree it's a quirk.

> If anything
> it should be the fully qualified name.

That'd be nice.

> Ideally it should be automatic,
> or a compiler recognized macro that inserts the link

Ironically the underscore is necessary because ddoc does too much automatically.

> * Ddoc should organize symbols by visibility [2]
> * Ddoc should generate index table [3]
> * Ddoc should organize a module by symbol category [4]
> * Add a way to inherit documentation from the parent class [5]
>
> * Ddoc should give a list of inherited members [6]. JavaDoc does this by
> default [7]
>
> * Consistent way of cross-referencing. Ideally one would just pass the
> fully qualified name (or local name for symbols in the same module) to a
> compiler recognized macro and it would generate the appropriate links
>
> * An index page with all symbols, including a filter [8]. This is super
> convenient when you know the symbol to use but you need to double check
> how it's used or the behavior. I use it almost every day with Ruby
>
> All this should be done within Ddoc without the need for any post
> processing.

I think we should start with a postprocessing-based approach and see what capabilities need to be added to obviate the need for postprocessing.

> In general I feel that Ddoc is too much focused on a generic macro
> system instead of focusing on being a good tool for writing
> documentation for code.

That's a fair assessment, and an actionable one.


Andrei

On 2016-09-15 08:44, Walter Bright wrote:

> The original idea was to be able to write documentation without needing
> many macros, if any. Such as this I wrote recently:
>
> /**
>  * Provides a safe interface to the Posix stat() function.
>  *
>  * Detailed description that I didn't write for this function,
>  * but this is where it goes.
>  *
>  * Another paragraph.
>  *
>  * Params:
>  *    path = file name
>  *    buf = stat instance to be filled in
>  * Returns:
>  *    0 for success, system errno for error
>  */
>
> I suspect that adding Markdown would help a lot (yes, I changed my mind
> about that). Also auto-detecting email addresses and urls and turning
> them into clickable links would help.

Yeah, if you already have defined all the standard ddoc macros because the default styling is not useful at all.

This is an example of the documentation generator for Ruby called Yard [1]. The default output view/style might not be the best in the world but I think it's pretty good. Here's an example of how to write the documentation [2].

[1] http://www.rubydoc.info/gems/httparty/0.14.0/HTTParty/ClassMethods
[2] http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md

-- 
/Jacob Carlborg

On 09/15/2016 10:37 AM, Jacob Carlborg wrote:
> Yeah, if you already have defined all the standard ddoc macros because
> the default styling is not useful at all.

Glad to hear that. It becomes a matter of improving the default-provided macros and/or distribute some .ddoc batteries.

Jacob, I'd also like to thank for the great constructive ideas for improving things and for formulating them as enhancement requests on bugsilla. This is the kind of communication that pushes things forward.


Andrei

On Thursday, 15 September 2016 at 00:42:57 UTC, Andrei Alexandrescu wrote:

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

Yes. Unfortunately I cannot find any mention of it on this page:
http://dlang.org/spec/ddoc.html

On 09/15/2016 11:25 AM, bachmeier wrote:
> On Thursday, 15 September 2016 at 00:42:57 UTC, Andrei Alexandrescu wrote:
>
>> Do you mean like a macro $(VERBATIM ... text with balanced parens
>> ...)? -- Andrei
>
> Yes. Unfortunately I cannot find any mention of it on this page:
> http://dlang.org/spec/ddoc.html

It doesn't exist :o). I agree it's needed, I've hit the matter a few times. See https://issues.dlang.org/show_bug.cgi?id=16498. -- Andrei

On Wednesday, 14 September 2016 at 20:14:48 UTC, Andrei Alexandrescu wrote:
> 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

The syntax is clunky and it's poorly documented. I've been lurking this mailing list since late 2012 and sporadically contributing since late 2013, and I had no idea you could do something like your example for Manu using DDOC. It seems like a real case of NiH syndrome; there are plenty of more widely used systems that would probably fit D just fine, but instead we have our own special macro documentation language. Really the only thing DDOC has going for it in comparison to something like Doxygen, IMO, is momentum. It's just too much of a pain to switch now.