On Wed, Oct 02, 2013 at 01:46:23PM +0200, 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, and is there any particular reason to favour WEB over, say, LINK2 ?
[...]

It's probably a macro defined somewhere in the phobos .ddoc file maybe?

Or is it post-processed by some script?


T

-- 
Старый друг лучше новых двух.

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

On 02/10/13 21:34, Jonathan M Davis wrote:
> 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.

Ahh, OK, thanks.

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

Fair enough, but ...

>> , and is there any particular reason to favour WEB over, say, LINK2 ?
>
> It's less verbose.

... is there any difference between WEB and LINK2 apart from the length?  And if so, why not just include WEB among the built-in macros?

On Thursday, 3 October 2013 at 10:46:00 UTC, Joseph Rushton
Wakeling wrote:
> On 02/10/13 21:34, Jonathan M Davis wrote:
>> 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.
>
> Ahh, OK, thanks.
>
>> 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.
>
> Fair enough, but ...
>
>>> , and is there any particular reason to favour WEB over, say, LINK2 ?
>>
>> It's less verbose.
>
> ... is there any difference between WEB and LINK2 apart from the length?  And if so, why not just include WEB among the built-in macros?

Doesn't WEB just add "http://" before the first parameter?
LINK2 = <a href="$1">$+</a>
WEB   = <a href="http://$1">$+</a>

I don't think there should be too many predefined macros. At
least not all related to HTML. But it's possible to override
them, right?

There are probably plenty of nice-to-have macros that would be
convenient to have always available, but it's pretty trivial to
add them yourself - or just use the phobos ddoc.

On Thursday, October 03, 2013 12:45:55 Joseph Rushton Wakeling wrote:
> > 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.
> 
> Fair enough, but ...

I don't see the problem. If you want the standard set of macros, then look at the docs. If you want more, then add your own. We need more in the Phobos docs, so we define more - many of which wouldn't even make sense as standard macros. I see no reason to restrict Phobos to the standard set of macros.

> >> , and is there any particular reason to favour WEB over, say, LINK2 ?
> > 
> > It's less verbose.
> 
> ... is there any difference between WEB and LINK2 apart from the length? And if so, why not just include WEB among the built-in macros?

I don't know how Walter arrived at the standard ones. I don't think that we ever mess with those at this point. If we need new ones, we add them to std.ddoc. WEB saves a bit of typing, so someone among the Phobos devs decided to add it, and we've ended up using it. But all it saves you is the http://, so for the common case at least, it's kind of redundant to have both (though you do need LINK2 for when it's not http). If someone wants WEB, they can just copy it from std.ddoc. There's a good chance that anyone doing a lot with ddoc will be copying and tweaking std.ddoc anyway. I don't see a lot of benefit in adding anything to the standard ones, particularly when there's a good chance that you're just going to end up overriding them all anyway in order to tweak them (std.ddoc does that with at least some of them - like the colors).

- Jonathan M Davis

On 03/10/13 20:06, Jonathan M Davis wrote:
> I don't see the problem. If you want the standard set of macros, then look at
> the docs. If you want more, then add your own. We need more in the Phobos
> docs, so we define more - many of which wouldn't even make sense as standard
> macros. I see no reason to restrict Phobos to the standard set of macros.

I wouldn't dream of restricting Phobos just to the standard macros, but I did find it a little odd to define a new macro that does essentially much the same as a built-in one.  I suppose the logic would be that if you use WEB for internal dlang.org links, and LINK2 for externals, then you can control the protocol used for dlang.org -- e.g. switch everything from http to https if that ever becomes desirable.

> I don't know how Walter arrived at the standard ones. I don't think that we
> ever mess with those at this point. If we need new ones, we add them to
> std.ddoc.

The main problem was that I didn't know about std.ddoc (it's in the dlang.org repo and not the Phobos one).  Now that I know, it's trivial to build a single Phobos doc file with

    dmd -o -D std/whatever.d ../dlang.org/std.ddoc

I'd had some hassles building the docs en masse previously, and it was annoying to have to rebuild the lot when the goal was to check the tweaked docs of a single file.

So, thanks for the insight, and apologies if it seems like I'm over-complaining about a minor issue :-)

Best wishes,

    -- Joe