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