ControlWikiWordPlugin

Plugin to stop linking of WikiWords or force linking of non-standard WikiWords

Usage

This plugin provides 4 functions:

• Rules-based blocking of WikiWord linking backwards compatible to the StopWikiWordPlugin
• Limit linking of Acronyms to the first instance in a topic.
• Singleton WikiWord linking backwards compatible to the SingletonWikiWordPlugin
• Regular Expression rules-based Singleton WikiWord linking (Configurable only by system administrator)

All functions are disabled by default unless explicitly enabled.

Note: The linking rules provided by this extension are not evalutated during topic rename actions. Links that are forced by this plugin will not be renamed. Linking words that are blocked by this plugin will still be renamed.

---

Rules-based blocking of WikiWord linking

Originally implemented in the StopWikiWordPlugin

In this mode, the Plugin prevents automatic linking of selected WikiWords such as LinuxWorld or MacDonald. These are an exact match. A Stop word contained as a prefix to a longer WikiWord should still be linked.

Configuration

WikiWords that should not be automatically linked are listed in a STOPWIKIWORDLINK preferences setting. This is typically done in the SitePreferences, but can be done also in any web (in WebPreferences), in the User topic for personal preferences, or in a single topic. See sample entry in the Plugin settings.

Note: Global settings are not read from this topic.

• Add a STOPWIKIWORDLINK setting to the SitePreferences topic, listing all WikiWords to exclude from auto-linking. Example:

  
   * Set STOPWIKIWORDLINK = LinuxWorld, MacDonald

Examples

• Test if the installation was successful. The following words will not be linked in this topic. (The above setting needs to be copied to one of the preferences locations to activate for other webs or topics.):
  • LinuxWorld, MacDonald and MacDonald/Farm
  • But MacDonalds and MacDonalds/Farm should still be WikiWords.

---

Acronym Linking Control

Adapted from the Acronym limits provided by the FindElsewherePlugin

In addition to WikiWords, Foswiki will auto-link Acronyms - any string consisting of 3 or more upper-case letters and numbers. WikiWords are always linked - displaying a question mark if the topic does not exist. Acronyms however only link when the topic exists.

In some technical topics, this can result in excessive linking. This feature will limit acronym links to only the first occurrence of an acronym in a topic. Forced [[link]] however will always be honored.

Configuration

To limit Acronym linking, add the CONTROLWIKIWORDPLUGIN_LIMITACRONYMS setting to the SitePreferences topic or in any web in WebPreferences, or in user or individual topics. This mode of operation is not enabled by default. (This setting can be abbreviated as simply LIMITACRONYMS.)

  
   * Set CONTROLWIKIWORDPLUGIN_LIMITACRONYMS = 1

Examples

HTML is an example of an ACRONYM, as is RSS. If an ACRONYM occurs twice, only the first instance will be linked.

SingletonWikiWordPlugin compatible operation

Originally implemented in the SingletonWikiWordPlugin

In this mode, the plugin will interpret that a single word is a reference to a Foswiki Topic of that name. To create a Singleton link, write a dot before the topic name. For example, if you have a topic named Ontology you can link to it as .Ontology This adds a simpler way to force a single word link. You can already accomplish the same thing by enclosing the word in double square brackets, like this: [[Ontology]]

The syntax was chosen to be an extension of the Web.Topic syntax. The syntax does not support topic names qualified with the web name. So to link to Ontology in a different web than the current web, you need to use the square-bracket mode of forcing the links, [[Support.Ontology][Support.Ontology]]

Configuration

To enable backwards compatible operation with the TWiki SingletonWikiWordPlugin, Add the CONTROLWIKIWORDPLUGIN_DOTSINGLETONENABLE setting to the SitePreferences topic or in any web in WebPreferences, or in user or individual topics. This mode of operation is not enabled by default.

  
   * Set CONTROLWIKIWORDPLUGIN_DOTSINGLETONENABLE = 1

Examples

As Written	Should appear as	If installed
.Singleword	Singleword	Singleword

---

Regular Expression rules-based WikiWords

This feature has no WikiUser configurable features. The System Administrator can set regular expression rules in the Foswiki Configuration that will match topic names useful for your configuration. Examples might include bug tracking link on http://foswiki.org/Support, where question topics are the word Question followed by a 3-5 digit number.

• The sample configuration will provide a link for Question123 FAQ22, Item123 and Item1244, but not ATask123.
  • But Task123A is matched as a normal WikiWord and not by this plugin.
• Forced links containing a Singleton link in the link text are not broken: Forced link to Question123 in System Web
• Neither are HTML Link to Question123 in Foswiki.org
• <noautolink> blocks are honored Question123 </noautolink>

Configuration

The system administrator uses the bin/configure interface to set one or more Regular Expressions to find Singleton WikiWords that should be converted to links. The configuration is a hash of a Regular Expression, and the web that should be linked. {qr/Regular Expression/,'Webname'} If the webname is not provided, the link will be for the web of the topic containing the matching word. The plugin performs case-sensitive matching.

Caution: Syntax errors in LocalSite.cfg can render the site non-operational. This is an Expert level perl language configuration and should be approached with caution! Each entry in the list of regular expressions must be followed by a comma.

Sample Configuration:

 {Plugins}{ControlWikiWordPlugin}{SingletonWords} = {
     '(?:Item[[:digit:]]{3,6})' => 'Tasks',
     '(?:Question[[:digit:]]{3,5}|FAQ[[:digit:]]{1,3})' => 'Support',
     '(?:Plugins)' => '',
     }; 

Will perform the following links: $ '(?:Item[[:digit:]]{3,6}) => 'Tasks': Match the word Item followed by a 3-6 digit number. If found, create a link to the topic of that name in the Tasks web. $ '(?:Question[[:digit:]]{3,5}|FAQ[[:digit:]]{1,3}) => 'Support': Match either Question, followed by a 3-5 digit number, or FAQ followed by a 1-3 digit number. If found create a link to the topic of that name in the Support web. $ '(?:Plugins)' => '': Link any instance of the word Plugins to a topic of that name in the current web. (If the Web portion of the rule is empty, the link will point to the current web where the Singleton WikiWord was found.)

Examples

The following examples will function only if the sample configuration above has been set using the bin/configure interface by the systems administrator. Note that all links except for the last example will typically result in "missing topic" links with the "?".

As Written	Should appear as	If Installed	Notes
Item123	Item123	Item123	Link points to Tasks Web
Question234	Question234	Question234	Link points to Support Web
FAQ23	FAQ23	FAQ23	Link points to Support Web
Plugins	Plugins	Plugins	Links to Plugins topic in System Web

---

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Info

Change History:
10 Feb 2016 (1.5)	Foswikitask:Item13953 - Inconsistent operation with persistent perl
22 Jul 2011 (1.4)	Foswikitask:Item10997 - Fix issue with ending delimiter for STOPWIKIWORDLINK
6 Nov 2010	Foswikitask:Item9964 - Fix issue with Attachment table on 1.1, Foswikitask:Item9968 - Improve regular expressions
24 Aug 2010	Foswikitask:Item9473 - Restructure for performance, clarify documentation
16 Mar 2010	Foswikitask:Item8720 - STOPWIKIWORDLINK should be an exact match.
15 Mar 2010	Foswikitask:Item8714 - Update author and copyright attributions. Bump version - no code changes.
22 Feb 2010	Foswikitask:Item8433 - Restructured internals. Added feature to control Acronym linking to first instance in a topic.
Dependencies:	None
Home page:	http://foswiki.org/bin/view/Extensions/ControlWikiWordPlugin