Ddoc WEB function

[Jonathan M Davis]

On Wednesday, October 02, 2013 13:46:23 Joseph Rushton Wakeling wrote:
> Hello all,
> 
> I've noticed that various places in Phobos docs use the WEB function, as in
> e.g.:
> 
> Authors: $(WEB erdani.org, Andrei Alexandrescu)
> 
> However, this seems to be some custom function that only works with the
> dlang.org website build process -- if you just run regular dmd -o- -D on the
> file in question, the parts in the $(WEB ...) function are just not
> included in the resulting HTML.
> 
> This seems a bit undesirable ... is it a bug, or is there a good reason for
> it

It's not a bug at all. It's in

https://github.com/D-Programming-Language/dlang.org/blob/master/std.ddoc

ddoc is a macro language and does not at all restrict you to what comes with 
it, and the standard library uses quite a few macros that are specific to it 
(e.g. XREF for a link to another module in std). When you run dmd with -D, you 
can give it a .ddoc file which contains macros that you define (or redefine), and 
std.ddoc is the one that the standard library uses.

If you to restrict yourself to the built-in ones in your code, then use the 
ones at

http://dlang.org/ddoc.html

And if you want to define more, then create your own .ddoc file with them in it. 
But Phobos uses std.ddoc, and we add new macros to it when we feel that it's 
appropriate.

> , and is there any particular reason to favour WEB over, say, LINK2 ?

It's less verbose.

- Jonathan M Davis