RFC: Alternative equivalent syntaxes for hyperlinks
See original GitHub issueIn a separate issue @yume-chan asked:
As a
@link
can link to either a URI or a declaration, will markdown links ([MyClass](Myclass)
) supports this syntax as well?
Let’s discuss this as a separate issue, since it’s unrelated to the declaration references topic.
Issue Analytics
- State:
- Created 5 years ago
- Reactions:1
- Comments:7
Top Results From Across the Web
RFC 1866 Hypertext Markup Language - IETF
Conformance This specification governs the syntax of HTML documents and aspects of the ... permitting) all hyperlinks from <A> elements in an HTML...
Read more >RFC 5988: Web Linking
This document addresses this by re- specifying the Link header as one such serialisation, with updated but backwards-compatible syntax. 2.
Read more >RFC822: Standard for ARPA Internet Text Messages
The syntax of the standard, in RFC #733, was originally specified in the Backus-Naur Form (BNF) meta-language. Ken L. Harrenstien, of SRI International, ......
Read more >Link - HTTP - MDN Web Docs - Mozilla
The HTTP Link entity-header field provides a means for serializing one or more links in HTTP headers. It is semantically equivalent to the ......
Read more >3137-let-else - The Rust RFC Book
Rationale and alternatives. let-else attempts to be as consistent as possible to similar existing syntax. Fundamentally it is treated as a let statement, ......
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
The quick answer is that the TSDoc parser library does not yet support Markdown links at all. Probably it would be counterintuitive not to, however I would hesitate to mix declaration references into this requirement, because the CommonMark link destination is already a pretty complex structure (see below).
<digression>
In general I tend to follow Python’s design philosophy of one obvious way, i.e. I find that multiple equivalent syntaxes make things worse rather than better. Some reasons being: a code base that is inconsistent between different authors, a steeper learning curve since people need to memorize what each syntax does, and a more tricky test surface for any tool that processes the inputs.It’s important to recognize that Markdown takes an exact opposite “everything but the kitchen sink” philosophy: Even strict CommonMark will accept all sorts of obscure notations that rarely occur in the wild. I spent a lot of time thinking about this difference of philosophy, and will probably include a small essay about it in the TSDoc spec document. 😃 But basically I believe Markdown’s design is optimized for fairly different requirements: It doesn’t need to be interoperable (i.e. a Markdown scanner can usually assume that it’s the only tool that needs to process an input, which is why its extensions can get away with having proprietary grammars). It also doesn’t need to be predictable (i.e. we can assume an interactive editor will render the result in realtime). Whereas TSDoc clearly needs to be interoperable and predictable to be successful.
</digression>
So the way TSDoc is framed today, people would expect three different ways of making a link:
JSDoc style
The notation I’m working on supporting in my current PR:
…but not the other redundant JSDoc notations that I’ve been trying to avoid incorporating:
HTML style
Just like CommonMark, TSDoc allows HTML tags and will also support HTML character references as an escaping mechanism.
It would be reasonable to support declaration references, in which case I would suggest a custom tag such as
<tsdoc-link>
:CommonMark style
Okay, strap in folks… Let’s now take a look at the hyperlink notations that a strict CommonMark parser would accept:
The CommonMark spec doesn’t say very much about the link destination itself except that it is a “URI.” The spec makes it clear that all sorts of relative URIs are supported, e.g.
#webhashtag
,/server-relative-path
,file-relative-path
, and//example.com
are all fine.Whereas so far with TSDoc we have been assuming that
{@link}
tags must include absolute URLs.Conclusion
It seems that TSDoc must support some form of
{@link}
in order to remain aligned with JSDoc, but it’s probably reasonable to limit the syntax to eliminate unnecessary variations. We have a very good reason for allowing HTML tags in TSDoc (it’s the most robust representation for people who need nesting custom tags), so it also makes sense to support hyperlinks via the<a>
tag.By contrast, Markdown links bring along a lot of complexity, but without contributing any new capabilities. So I’m somewhat undecided to what extent we want to pursue that. What do people think?
A simple and intuitive way to integrate Markdown links and TSDoc links:
The regular TSDoc equivilent (taken from the README):
Justification:
This is standard Markdown link syntax and semantics.
{@link core-library#Statistics}
is semantically alink destination
, the thing Markdown expects within the parenthesis.It is easier to read because the link text comes first.
Both forms can continue to be supported without conflict.
Easy to implement. Nearly every Markdown parser will parse this without issue, simply passing the
{@link ...}
reference to the renderer. The TSDoc code can hook into the renderer and replace the reference with a resolved link.Users can add a link
title
if desired, again using standard Markdown syntax: