DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:interwikiformatting

Interwiki Formatting Plugin

Compatible with DokuWiki

  • 2017-02-19 "Frusterick Manners" yes
  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" unknown
  • 2014-09-29 "Hrun" unknown

plugin The Interwiki Formatting Plugin automatically produces formatted titles for interwiki links.

Last updated on
2016-11-19
Provides
Syntax
Repository
Source

Tagged with formatting, interwiki, links

By jeckel

Installation

Install the plugin using the Extension Manager with the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

Description

Interwiki links are a powerful and time saving tool in the belt of any Dokuwiki editor, especially on wikis that provide various custom shortcuts to often used sites. However, they do have one drawback, namely that you either have to accept the displaying of the URL part in whatever form is required for the related site or you have to constantly add titles that more often than not only differ from the URL part by their formatting.

This plugin attempts to solve that issue by automating the formatting of interwiki links that don't have a title manually defined. For sites like Tv Tropes where page ids are composed of multiple words run together without spaces the plugin will reinsert them and on sites like Wikipedia where page ids are made of words separated by underscores or other delimiters the plugin will replace them with spaces. The displayed title will then have the capitalization of words standardized into common title case where all words except articles, conjunctions, prepositions, and uppercase acronyms start with a capital letter.

This automation of formatting and the configurability provided by the plugin's settings should simplify the use of interwiki links, standardize their displayed appearance, and save time for any editor using them.

Usage

This plugin requires no special syntax, simply use interwiki links, [[shortcut>Some_Page#OptionalAnchor]], as normal and the automatic formatting will be applied unless the interwiki link already has a title defined, [[shortcut>Some_Page#OptionalAnchor|No Formatting Applied Here Because I Already Have A Title]].

See examples of the plugin in action.

Configuration Settings

The Interwiki Formatting Plugin has eight settings that can be set in the Dokuwiki Configuration Manager:

  1. Ignored Shortcut List (ignored_shortcuts) - A space separated list of interwiki shortcuts that should not receive any automatic formatting. The default list includes the user and skype shortcuts.
  2. Strip Query Toggle (strip_query) - Whether or not the query part of the interwiki link should be stripped from the displayed title. This setting is enabled by default.
  3. Strippable Extension List (strippable_extensions) - A space separated list of extensions that should be removed from the end of interwiki link titles. The default list includes asp, htm, html, and php.
  4. Word Separator List (word_separators) - A space separated list of characters that should be replaced by a space when the title is formatted. The default list includes _, :, ., and -.
  5. Anchor Replacement Text (anchor_replacement) - The text that the anchor symbol (#) will be replaced by unless it is the first or last character of the string, in which case it will be remove entirely. The default value is a dash with a space on both sides ( - ).
  6. Slash Replacement Text (slash_replacement) - The text that the common path separator symbol (/) will be replaced by unless it is the first or last character of the string, in which case it will be remove entirely. The default value is a dash with a space on both sides ( - ).
  7. Capitalize Words Toggle (capitalize_words) - Whether or not all words in the display interwiki link title should be capitalized. This setting is enabled by default.
  8. Capitalize Exceptions List (capitalize_exceptions) - A space separated list of words that should not be capitalized. This setting is ignored if capitalizing of words is disabled. The words in this list will still be capitalized if they are the first or last word of the title, the first word after the anchor or slash replacement text, or the last word before the anchor of slash replacement text. The default word list includes the, of, a, an, and, but, or, for, nor, are, in, and at.

Future Plans

  • Fix any bugs that are reported.
  • Update as necessary for future Dokuwiki versions.
  • There are currently no plans for new features.

Security

There are currently no know vulnerabilities related to normal use of the mod. The mod takes advantage of the built-in methods for creating interwiki links and simply provides them with a generated title in lieu of a user-defined one. This should be no more or less secure than any normal interwiki link. No extra measures have been implemented to secure or validate the values of the plugin's configuration settings, but these should only be available to the wiki's admin and those user's who have been trusted with access to the configuration manager, so they are no more or less secure than any other setting.

Bugs

Bugs should be reported through the Gitlab Issue Tracker.

  • There are currently no know bugs.

Formatting Issues

It should be made clear that anyone using this plugin will come across interwiki links that will not look good when automatically formatted and instead will have to be given a manually defined title. This is something that will always be the case and it can not be avoided completely. No matter how much the code is improved, urls and page ids are simply to varied and, with such a low bar of entry, web development is an atmosphere that tends to foster bad practices, like requiring query strings and not hiding file extensions.

Thankfully, some of these issues can very easily be solved by those using the plugin. Take the phpfn interwiki link below. The main issue is immediately obvious, it is suppose to be a shortcut to a php function page (hence the fn in phpfn), but it isn't; it is a shortcut to the php website and the entire manual/en/function.count.php has to be given to it which leads to Manual - En - Function and .php being included in the title.

[[phpfn>manual/en/function.count.php]] Manual - En - Function Count Php

The plugin can be (and by default is) configured to remove the php and any other common extensions when formatting titles. However, the former problem can not be solved in any real way by the plugin, but it can be fixed by redefining the shortcut itself to what it should have been in the first place. Simply add manual/en/function. before the {NAME} and add .php after it. This will make the shortcut more intuitive, easier to use, and it will allow the plugin's automatic formatting to work more as intended.

Before After
phpfn     https://secure.php.net/{NAME}
phpfn     https://secure.php.net/manual/en/function.{NAME}.php
Manual - En - Function Count Php Count

On the other hand, take the mess that is the following amazon links. The first example has a bunch of gunk at the end, dp/B00DBYBNEE, and there is no way to create rules to automatically remove such clutter. The second link is both better and worse; the plugin (with default settings) will strip the question mark and everything after it, but there is still a trailing b there. While, theoretically, that b could be removed with a rule about single characters that aren't a or i, that is far too prone to cause unwanted removals, making it an addition that is as much or more costly to include than to leave out. Perhaps, again theoretically, the plugin could extend interwiki links to include some kind of substring arguments that could strip x number of characters from the end or beginning, but changing interlink syntax is outside the scope of this plugin.

[[amazon>Amazon-Prime-One-Year-Membership/dp/B00DBYBNEE]] Amazon Prime One Year Membership - Dp - B00 DBYBNEE
[[amazon>Black-Friday/b?ie=UTF8&node=384082011]] Black Friday - B?ie=UT F8&node=384082011

In conclusion, this plugin does have its short comings, but some of those issues can be solved by redefining interwiki shortcuts in a more appropriate way, others are solved with configuration settings, and the rest can always fall back on giving the link a manually defined title, leaving the plugin to automatically format the majority of commonly used links which tend to be well behaved.

Discussion

Discussion should be kept on the Plugin's Discussion Page.

plugin/interwikiformatting.txt · Last modified: 2017-03-14 09:56 by jeckel