On Wednesday, 31 December 2014 at 23:53:48 UTC, Walter Bright
wrote:
Have fun with LUCKY in markdown.
LUCKY sucks anyway, it would be better to provide a regular link
to something directly useful, even Wikipedia (which is usually
the one I go straight to, and if I want more, I'll Bing it
myself, thank you very much).
Here's a counterpoint: make a Ddoc macro that links to the
documentation of a given symbol.
$(DOC std.array.array)
It needs to somehow get here:
http://dlang.org/phobos/std_array.html#.array
The existing solution in Phobos' macros is something like this:
$(XREF range,chain)
But, how to you convert a name, say in a code example, to that
macro without manual intervention?
One of the things I like most about ddoc is the code example
highlighting. Indeed, I decided to use it last night to start
writing the draft of my DConf 2015 proposal:
http://arsdnet.net/dcode/talk-2015.dd
http://arsdnet.net/dcode/talk-2015.html
Not bad, got some easy syntax highlighting and it wasn't painful
to write at all.
...but when documenting code, it is nice to be able to click on
names and see more information. To compile the ddoc, all imports
need to resolve. Why not go ahead and make "import std.variant;"
available for linking somehow?
We could make it call a macro like $(XREF std.variant) .... but
how do we get that to the link, phobos/std_variant.html? We can't
do a call to replace(".", "_").
Well, I do have a solution for this: my dpldocs.info site.
http://dpldocs.info/std.variant
which for a while redirected to the Phobos site, then I found
that useless since dlang.org couldn't link overloads and I just
displayed the comment myself... but I think I'll go back to
redirecting now that we can link to it.
But the point is translating a module name to a Phobos link
requires transformation code too complex for a ddoc macro...
ironically needing something like LUCKY - an external search
engine - to fix...
