Documentation for any* dub package, any version

[David Gileadi]

On 2/27/18 9:21 AM, Adam D. Ruppe wrote:
> 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 [].

Markdown actually supports two kinds of links: inline links (which you 
describe above and I'm very happy you support) and reference links [1].

A reference link can be like [alt text][reference] or you can do the 
shortcut version if your alt text is the same as the reference name: 
[reference]. I currently support both forms in my upcoming Markdown PR, 
but they only link to references that are defined elsewhere in the 
document, like my [1] at the bottom of this message. What I want to do 
is automatically include references for symbols in the current scope, to 
support links to symbols via [symbol] and [alt text][symbol].


[1]: http://spec.commonmark.org/0.28/#reference-link