EML supports several different types of links.
Link types:
- Hyperlinks
- Datafeed article links
- Datafeed asset links
- Links to assets of other articles
Hyperlinks
Hyperlinks are standard web links.
Example:
http://www.json.org
In EML, they are written like so:
<link>
<type>hyperlink</type>
<reference>http://www.json.org</reference>
<text>http://www.json.org</text>
</link>
<type>hyperlink</type>
<reference>http://www.json.org</reference>
<text>http://www.json.org</text>
</link>
This will be rendered as:
http://www.json.org
The
reference
value is the actual destination of the web link. The
text
value is the text that will be displayed on the web page.Here is an example where the reference and the text have different values.
<link>
<type>hyperlink</type>
<reference>http://www.json.org</reference>
<text>Click here to go to the json.org site.</text>
</link>
<type>hyperlink</type>
<reference>http://www.json.org</reference>
<text>Click here to go to the json.org site.</text>
</link>
This will be rendered as:
Click here to go to the json.org site.
Edgecase has several preferences concerning hyperlinks:
- No trailing slash. This is aesthetically unpleasing. Only preserve it if the destination web address is unable to handle its absence.
- If the reference and text are the same, remove the
http://
prefix from the text. Example: www.json.org- Don't use the
https://
prefix. HTTPS is a soft fork of HTTP, not a completely separate protocol. HTTP is the underlying reality. Most websites that only support HTTPS will reroute HTTP requests to the HTTPS port, so the links will still work.Datafeed article links
Datafeed article links allow the author to link to a datafeed article in a way that is independent of domain names. Domain names can change.
<link>
<type>article</type>
<article_title>Edgecase_Markup_Language_(EML):_Latin-1</article_title>
<datafeed>edgecase</datafeed>
<datafeed_article_id>92</datafeed_article_id>
<text>Edgecase Markup Language (EML): Latin-1</text>
</link>
<type>article</type>
<article_title>Edgecase_Markup_Language_(EML):_Latin-1</article_title>
<datafeed>edgecase</datafeed>
<datafeed_article_id>92</datafeed_article_id>
<text>Edgecase Markup Language (EML): Latin-1</text>
</link>
This will be rendered as:
Edgecase Markup Language (EML): Latin-1
The rendering engine uses the datafeed name (in this case,
edgecase
) to look up the current domain (
http://edgecase.net
) and thereby construct a hyperlink.Datafeed articles are ordered numerically by their IDs, so technically only the datafeed name and the datafeed article ID are required in order to specify the link destination. However, reading the link item itself is easier if the article title is also included.
The
text
value is the text that will be displayed on the web page, the same as for a hyperlink.Datafeed asset links
Datafeed asset links are used within a datafeed article. They allow the author to link to any file by specifying its filename and its hash. Once an asset has been linked from an article, that article is its parent. In a datafeed, an asset has exactly one parent article.
Example from the article Public Key Identity Document: StJohn Piano:
<link>
<type>asset</type>
<filename>stjohn_piano_public_key.txt</filename>
<text>[Click here to download keyfile]</text>
<sha256>73ba4c82ced0198a361cbb693098f5d40c09c2455b8eb5753138c1c74126574f</sha256>
</link>
<type>asset</type>
<filename>stjohn_piano_public_key.txt</filename>
<text>[Click here to download keyfile]</text>
<sha256>73ba4c82ced0198a361cbb693098f5d40c09c2455b8eb5753138c1c74126574f</sha256>
</link>
This will be rendered as:
[Click here to download keyfile]
However, on this page, the link won't work, because it is only meant to be used in the original parent article.
As usual, the
text
value is the text that will be displayed on the web page.Links to assets of other articles
This type of link allows an author to link to an existing asset, one that has already been published in another article.
Example:
<link>
<type>asset_of_another_article</type>
<article_title>Public_Key_Identity_Document:_StJohn_Piano</article_title>
<datafeed>edgecase</datafeed>
<datafeed_article_id>101</datafeed_article_id>
<filename>stjohn_piano_public_key.txt</filename>
<text>[Download public key]</text>
<sha256>73ba4c82ced0198a361cbb693098f5d40c09c2455b8eb5753138c1c74126574f</sha256>
</link>
<type>asset_of_another_article</type>
<article_title>Public_Key_Identity_Document:_StJohn_Piano</article_title>
<datafeed>edgecase</datafeed>
<datafeed_article_id>101</datafeed_article_id>
<filename>stjohn_piano_public_key.txt</filename>
<text>[Download public key]</text>
<sha256>73ba4c82ced0198a361cbb693098f5d40c09c2455b8eb5753138c1c74126574f</sha256>
</link>
Unsurprisingly, this link is a combination of a datafeed article link and a datafeed asset link. It contains the information that will allow a lookup of an existing datafeed asset, in a way that is not domain-name-dependent.
This will be rendered as:
[Download public key]
This link works in any article or page.