On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote:
> Also, the lack of flexibility in number of macro arguments means you end
> up with LINK, LINK2, LINK3, etc., with no obvious indication what the
> difference is and where you should use which macro.

(Well the obvious indication is the number innit :o).)

A _simple_ way to handle arity might be worth adding to ddoc. Any ideas?


Andrei

On 12/16/2015 04:17 PM, deadalnix wrote:
> In that regard, I think it is fair to asses that people that know webdev
> don't know ddoc an vice versa. So using ddoc is probably not the best
> bet here.

Yah, agreed (though I have to say it's not that fair to my tushy :o)). -- Andrei

On 12/16/2015 05:32 PM, H. S. Teoh via Digitalmars-d wrote:
> While I'm on the fence about the value of ddoc as a website programming
> language (not as a documentation generator, where it is excellent IMO),
> I'm doubtful of the value of converting wholesale to a different format
> at this present time.  That's a lot of effort and drain of our scant
> resources, with only unverifiable claims of increased participation from
> nebulous crowds who so far haven't showed any signs of interest in
> participating yet.  It's something we could perhaps consider in the long
> term, but right now there are far more important things we need to work
> on. Like actually improving what docs are currently there.

Very very very wise words. Thanks! -- Andrei

On Wed, Dec 16, 2015 at 06:18:22PM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote:
> >Also, the lack of flexibility in number of macro arguments means you end up with LINK, LINK2, LINK3, etc., with no obvious indication what the difference is and where you should use which macro.
> 
> (Well the obvious indication is the number innit :o).)

But does the number mean the number of arguments, or the number of arguments past the mandatory arguments, or an incremental poor man's macro version number, or ...?

I think some agreed-on common naming conventions for ddoc macros (perhaps just restricted to dlang.org / phobos / etc.) would go a long way in alleviating this issue. Right now it's just a random grab-bag where it's every man for himself and anything goes.


> A _simple_ way to handle arity might be worth adding to ddoc. Any ideas?
[...]

Allow overloading by number of arguments, maybe? (This sounds suspiciously like a slippery slope, though...)

Or allow argument list slicing, D-style?  Not sure if this would solve all the necessary cases.


T

-- 
Answer: Because it breaks the logical sequence of discussion. / Question: Why is top posting bad?

On Wednesday, 16 December 2015 at 23:01:47 UTC, Walter Bright wrote:
> Exactly.
>
> We'll never get anywhere chasing people who say "I'll help only if you convert to my way of doing things." I've done enough of that in the past, and concluded they're just seeing how long you'll dance to their tune and have no real intention of ever helping - there will just be another excuse.

It's funny how much "better" one's own ideas seem until one realizes that implementing them usually takes just as much effort as with someone else's idea, and work is almost always the limiting factor.

On the subject of "one's own ideas", here's mine, FWIW:

First, my background thoughts. We seem to have four main "sections" of the site: the forums (built on DFeed), the wiki (built on MediaWiki), the language docs (DDoc), and the "main" site (in DDoc/HTML). The first three are using technologies which were explicitly designed for what they do, and they work quite nicely. The only thing left is the "main" site (the download page, articles, etc.), which doesn't fit into the models of the first two technologies and is somewhat clumsy for some people to edit because it's built on more than just "common" Web standards.

I can think of a couple of ideas for making the main page more palatable to Web developers. One is to make as much of it as possible in plain old static HTML. Stuff like the articles rarely changes, after all. Another idea is to use a Web application framework. There's a significant advantage there: we can have one master "layout" template, and almost any content we want (forums, DDoc-generated HTML, static HTML, and so on) can be rendered in that template with relatively minimal code. There are lots of frameworks that shouldn't be hard to use. I'm sure that someone has already suggested doing it in vibe.d, and that probably got shot down due to a technical issue or something, but it would be interesting from a PR standpoint.

On 12/16/2015 06:29 PM, H. S. Teoh via Digitalmars-d wrote:
> Allow overloading by number of arguments, maybe? (This sounds
> suspiciously like a slippery slope, though...)

That'll have trouble with $0 and $+.

> Or allow argument list slicing, D-style?  Not sure if this would solve
> all the necessary cases.

Overall I think a few additions to the macro engine could be very beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to expand b if a is nonempty and c otherwise.


Andrei

On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote:
> [snip]

...and as I read some older posts, I see that mine is completely redundant. ;)

Seriously, though, I'm willing to help prototype something. I've got time before the next semester starts.

On 12/16/2015 06:43 PM, BLM768 wrote:
> One is to make as much of it as possible in plain old static HTML. Stuff
> like the articles rarely changes, after all.

But I dislike typing HTML. DDoc improves on that significantly.

> Another idea is to use a
> Web application framework. There's a significant advantage there: we can
> have one master "layout" template, and almost any content we want
> (forums, DDoc-generated HTML, static HTML, and so on) can be rendered in
> that template with relatively minimal code.

Ironically Ddoc does exactly that, and quite nicely.


Andrei

On 12/16/2015 3:43 PM, BLM768 wrote:
> One is to make as much of it as possible in plain old static HTML.

I've done that before, a lot. Ddoc cut the work involved in that in half, and I mean in half. It also made it easy to change the look of a whole site, rather than being a mess of tedium.

No way I'm going back to that.

On Wed, Dec 16, 2015 at 06:46:46PM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> On 12/16/2015 06:29 PM, H. S. Teoh via Digitalmars-d wrote:
> >Allow overloading by number of arguments, maybe? (This sounds suspiciously like a slippery slope, though...)
> 
> That'll have trouble with $0 and $+.

Not if we adopt the rule that if there are more arguments than the overload with the most number of arguments, then that overload is invoked.

OTOH, I just realized that macro definitions don't indicate the number of parameters. Perhaps overloads should be defined with different syntax? E.g.:

	// old syntax:
	NON_OVERLOADABLE = blah $0 blah $1 blah $+

	// new (additional) syntax:
	OVERLOADABLE(a) = blah $a blah
	OVERLOADABLE(a,b) = blah $a blah $b blah
	OVERLOADABLE(a,b,c) = blah $a blah $b blah $c blah

Having parameter names will also help readability; currently, with $1, $2, $3 it's non-obvious what each parameter is supposed to be without reading the macro definition.

The old parameterless syntax then can be reserved for truly variadic macros.


> >Or allow argument list slicing, D-style?  Not sure if this would solve all the necessary cases.
> 
> Overall I think a few additions to the macro engine could be very beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to expand b if a is nonempty and c otherwise.
[...]

This will make ddoc Turing-complete, which may or may not be what you want. :-D

(Although IIRC ddoc does impose a limit on recursion depth, so perhaps it won't *quite* be Turing complete just yet...)


T

-- 
I think the conspiracy theorists are out to get us...