diff options
Diffstat (limited to 'www/interwiki.md')
| -rw-r--r-- | www/interwiki.md | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/www/interwiki.md b/www/interwiki.md new file mode 100644 index 0000000..fd9a33f --- /dev/null +++ b/www/interwiki.md @@ -0,0 +1,117 @@ +# Interwiki Links + +Interwiki links are a short-hand notation for links that target +external wikis or websites. For example, the following two +hyperlinks mean the same thing (assuming an appropriate [intermap](#intermap) +configuration): + + * [](wikipedia:MediaWiki#Interwiki_links) + * [](https://en.wikipedia.org/wiki/MediaWiki#Interwiki_links) + +Another example: The Fossil Forum is hosted in a separate repository +from the Fossil source code. This page is part of the +source code repository. Interwiki links can be used to more easily +refer to the forum repository: + + * [](forum:d5508c3bf44c6393df09c) + * [](https://fossil-scm.org/forum/info/d5508c3bf44c6393df09c) + +## Advantages Over Full URL Targets + + * Interwiki links are easier to write. There is less typing, + and fewer opportunities to make mistakes. + + * Interwiki links are easier to read. With well-chosen + intermap tags, the links are easier to understand. + + * Interwiki links continue to work after a domain change on the + target. If the target of a link moves to a different domain, + an interwiki link will continue to work, if the intermap is adjusted, + but a hard-coded link will be permanently broken. + + * Interwiki links allow clones to use a different target domain from the + original repository. + +## Details + +Fossil supports interwiki links in both the +[Fossil Wiki](/wiki_rules) and [Markdown](/md_rules) markup +styles. An interwiki link consists of a tag followed by a colon +and the link target: + +> <i>Tag</i><b>:</b><i>PageName</i> + +The Tag must consist of ASCII alphanumeric characters only - no +punctuation or whitespace or characters greater than U+007A. +The PageName is the link notation on the target wiki. +Three different classes of PageNames are recognized by Fossil: + + 1. <b>Path Links</b> → the PageName begins with the "/" character + or is an empty string. + + 2. <b>Hash Links</b> → the PageName is a hexadecimal number with + at least four digits. + + 3. <b>Wiki Links</b> → A PageName that is not a Path or Hash. + +The Intermap defines a base URL for each Tag. Path links are appended +directly to the URL contained in the Intermap. The Intermap can define +additional text to put in between the base URL and the PageName for +Hash and Wiki links, respectively. + +<a id="intermap"></a> +## Intermap + +The intermap defines a mapping from interwiki Tags to full URLs. The +Intermap can be viewed and managed using the [fossil interwiki][iwiki] +command or the [/intermap][imap] webpage. + +[iwiki]: /help/interwiki +[imap]: /intermap + +The current intermap for a server is seen on the [/intermap][imap] page +(which is read-only for non-Setup users) and at the bottom of the built-in +[Fossil Wiki rules](/wiki_rules) and [Markdown rules](/md_rules) +documentation pages. + +Each intermap entry stores, at a minimum, the base URL for the remote +wiki. The intermap entry might also store additional path text that +is used for Hash and Wiki links. If only the base URL is provided, +then the intermap will only allow Path style interwiki links. The +Hash and Wiki style interwiki links are only allowed if the necessary +extensions are provided in the intermap. + + +## Disadvantages and Limitations + + * Configuration is required. The intermap must be set up correctly + before interwiki links will work. This contrasts with ordinary + links that just work without any configuration. Cloning a repository + copies the intermap, but normal syncs do not keep the intermap in + sync. Use the "[fossil config pull interwiki][fcfg]" command to + synchronize the intermap. + + * The is no backlink tracking. For ordinary intrawiki links, Fossil keeps + track of both the source and target, and when displaying targets it + commonly shows links to that target. For example, if you mention a + check-in as part of a comment of another check-in, that new check-in + shows up in the "References" section of the target check-in. + ([example](31af805348690958). In other words, Fossil tracks not just + "_source→target_", but it also tracks "_target→source_". + But backtracking does not work for interwiki links, since the Fossil + running on the target has no way of scanning the source text and + hence has no way of knowing that it is a target of a link from the source. + +[fcfg]: /help/config + +## Intermap Storage Details + +The intermap is stored in the CONFIG table of the repository database, +in entries with names of the form "<tt>interwiki:</tt><i>Tag</i>". The +value for each such entry is a JSON string that defines the base URL +and extensions for Hash and Wiki links. + +## See Also + + 1. [](https://www.mediawiki.org/wiki/Manual:Interwiki) + 2. [](https://duckduckgo.com/?q=interwiki+links&ia=web) |