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
