Documentation for any* dub package, any version

[Adam D. Ruppe]

On Tuesday, 27 February 2018 at 16:00:26 UTC, David Gileadi wrote:
> Out of curiosity, what prompted [symbol|alt text] instead of 
> going with the Markdown construct of [alt text][symbol]?

Well, markdown is [alt text](url), and adrdox actually DOES 
support that as well:

http://dpldocs.info/experimental-docs/adrdox.syntax.html#markdown-style-links

(I just added that last Friday though for gtkd docs 
compatibility!)

Though it does NOT support a symbol in there, just a URL right 
now. Maybe I can add it, but I always start conservative - allow 
the least syntax with the most restrictions I can, then loosen 
them as I'm sure it isn't annoying.


But anyway, the [symbol|alt text] comes from Wikipedia's markup 
actually, which is the first thing that comes to my mind to 
easily cross-link articles. On wikipedia, you use brackets to 
indicate a word as a link: `director = [[Avery Brooks]]`, for 
example, will link to that article. Similarly, `[[Star Trek: Deep 
Space Nine (season 6)|6]]` will just show the text "6", while 
linking to the page in there.

So I took that and generalized it a bit so it supports other URLs 
too, then simplified it to just one set of [] instead of two.


The big advantage for [] over markdown links is it is lighter 
syntax in the simple case:

/// See also: [intersect]

knows to link to the symbol `intersect`. Whereas:

/// See also: [intersect](intersect)

would be the equivalent markdown style, but it is repeated... so 
you might skip the alt text:

/// See also: (intersect)

but that conflicts with very common parenthetical text like "I 
think that's silly (sorta)..." and I wouldn't want "sorta" to be 
linked there!

So I just went with [].