Skip to content

Commit

Permalink
Item14433: modernise the plugin for Foswiki 2
Browse files Browse the repository at this point in the history
  • Loading branch information
cdot committed Jul 12, 2017
1 parent e097ac5 commit 8bb0582
Show file tree
Hide file tree
Showing 2 changed files with 142 additions and 222 deletions.
141 changes: 64 additions & 77 deletions data/System/SpacedWikiWordPlugin.txt
View file
@@ -1,15 +1,23 @@
%META:TOPICINFO{author="ProjectContributor" date="1081752098" format="1.0" version="1.1"}%
---+!! Spaced Wiki Word Plugin
---+!! %TOPIC%
<!--
* Set SHORTDESCRIPTION = %$SHORTDESCRIPTION%
-->

Display topic links spaced out: [[%TOPIC%][WebHome]] is displayed as [[%TOPIC%][Web Home]]. %BR%
Or use this plugin to display "underscore topic names" like [[%TOPIC%][Topic_name]] as [[%TOPIC%][Topic name]].
Automatically display topic links spaced out: [[[%TOPIC%]] is displayed as %SPACEOUT{"%TOPIC%"}%.

*AND/OR*

Display "underscore topic names" like [[%TOPIC%][Topic_name]] as [[%TOPIC%][Topic name]].

This plugin also overrides the core =SPACEOUT= macro to improve the presentation
of spaced out words, and allow for a =DONTSPACE= list.

%TOC%

---++ Space Out Options
You can choose to switch on or off either display option.
---++ Options

Spaced out !WikiWords will definitely make links more readable, but they can also produce "Odd Looking Sentence Case" links.
Spaced out !WikiWords definitely make links more readable, but they can also produce "Odd Looking Sentence Case" links.

Use underscore topic names if you want total control over links:
1 (Optionally) disable automatic linking of !WikiWords. Do this if you are in the position to teach your users to only write links in bracket notation like =[<nop>[WebHome]]=. This is also how Wikipedia links are written. Bracket notation is necessary to create links for underscore topic names, but you can also mix both link notations.
Expand All @@ -21,28 +29,17 @@ Use underscore topic names if you want total control over links:
* A topic name such as =[<nop>[Human_evolution]]= will be rendered as [[%TOPIC%][Human evolution]]
* Plain topic names like =Human_evolution= are not expanded; always use bracket notation



---++ Syntax Rules
---+++ !WikiWord links
You don't have to write any syntax. If this plugin is enabled, wiki words are automatically spaced out. Automatically spaced out are: =TopicName=, =Web.TopicName=, =[<nop>[TopicName]]=.
wiki words are automatically spaced out. Automatically spaced out are: =TopicName=, =Web.TopicName=, =[<nop>[TopicName]]=.

Explicitly written link labels are *not* spaced out. Examples: =[<nop>[TopicName][TopicName]]= or =[<nop>[TopicName][SomeOtherName]]=.

---+++ Underscore links
=SPACE_OUT_UNDERSCORE_LINKS= needs to be set to =1=. Automatically spaced out are: =[<nop>[Underscore_topic]]=, but not =Underscore_topic= (without brackets).
=[<nop>[Underscore_topic]]= is automaticlly spaced out (but not =Underscore_topic=).


#SearchResults
---+++ Spacing out search results
Link labels in search results are also considered 'explicit':

<verbatim>
[[$web.$topic][$topic]]
</verbatim>
... is not spaced out automatically.

Instead write:
Use the =[[VarSPACEOUT][SPACEOUT]]= macro. For example, write:

<verbatim>
[[$web.$topic][$percntSPACEOUT{$topic}$percnt]]
Expand All @@ -56,83 +53,73 @@ More info on search syntax in [[FormattedSearch]].
---+++ Preventing spacing out of some words
Some words (often brand names and medical terms) are written in [[Wikipedia:CamelCase][CamelCase]] notation and should not be spaced out. For example: !CamelCase, !DaimlerChrysler, !MasterCard.

Define a list of words that should not get spaced out with =DONTSPACE= at the [[#PluginSettings][Plugin Settings]] below.


Define a list of words that should not get spaced out with =DONTSPACE= in your prefereces.

---++ Troubleshooting
---+++ My links do not display spaced out
---+++ My links are not spaced out
* At [[#PluginTest][Plugin test]] below, check if this plugin is enabled and if the correct spacing settings are applied.
* You have used an explicit link label: with =[<nop>[WebHome][WebHome]]=, "WebHome" is not spaced out. Use =[<nop>[WebHome]]= or =[<nop>[WebHome][%<nop>SPACEOUT{"WebHome"}%]]=
* You have used underscore topic names without bracket notation. Always write =[<nop>[Human_evolution]]=
* You are showing links from a search result. See [[#SearchResults]] above.

---+++ I try to write anchors with underscores
Anchors written as =#Some_anchor= are not supported. Use !WikiWord syntax instead: =#SomeAnchor=

---+++ Some word are spaced out but shouldn't
---+++ Some words are spaced out, but shouldn't be
See [[#PreventingSpaceOut]].



#PluginSettings
---++ Plugin Settings

Plugin settings are stored as preferences variables.

* One line description, shown in the %SYSTEMWEB%.TextFormattingRules topic:
* Set SHORTDESCRIPTION = Display topic links spaced out

* List of words that should not be spaced out (separated by commas or spaces):
* Set DONTSPACE =

* Where spacing is applied. %BR%
* =SPACE_OUT_WIKI_WORD_LINKS= will space out =WikiWord= links to =Wiki Word= links
* Set SPACE_OUT_WIKI_WORD_LINKS = 1
* =SPACE_OUT_UNDERSCORE_LINKS= will space out =Topic_name= links to =Topic name= links
* Set SPACE_OUT_UNDERSCORE_LINKS = 1
* Remove anchor dashes when writing =[<nop>[#SomeAnchor]]=
* Set REMOVE_ANCHOR_DASHES = 1
* Debug plugin: (See output in =data/debug.txt=)
* Set DEBUG = 0



#PluginTest
---++ Plugin Tests
* This plugin is %IF{"context SpacedWikiWordPluginEnabled" then='%GREEN%enabled%ENDCOLOR%' else ='%RED%not enabled%ENDCOLOR%'}%.
* !WikiWord links will %IF{"$ SPACE_OUT_WIKI_WORD_LINKS='1'" then='%GREEN%be spaced out%ENDCOLOR%' else='%RED%not be spaced out%ENDCOLOR%'}%.
* !Underscore_topic links will %IF{"$ SPACE_OUT_UNDERSCORE_LINKS='1'" then='%GREEN%be spaced out%ENDCOLOR%' else='%RED%not be spaced out%ENDCOLOR%'}%.
* =NOAUTOLINK= is %IF{"$ NOAUTOLINK='on'" then='%GREEN%on%ENDCOLOR%' else='not set'}%. !WikiWords will %IF{"$ NOAUTOLINK='on'" then=' *not* '}% automatically create links. Test: SpacedWikiWordPlugin
* Anchor dashes will %IF{"$ REMOVE_ANCHOR_DASHES='1'" then='%GREEN%be removed%ENDCOLOR%' else='%RED%not be removed%ENDCOLOR%'}%. Test: [[#PluginSettings]]

---++ Settings
You can control the behaviour of the plugin using the following PreferenceSettings:
* =DONTSPACE= can be set to a commaa-separated list of words that should not be spaced out
* =SPACE_OUT_WIKI_WORD_LINKS= can be set to 1/0 to enable/disable spacing out =WikiWord= links to =Wiki Word= links
* =SPACE_OUT_UNDERSCORE_LINKS= can be set to 1/0 to enable/disable spacing out =Topic_name= links to =Topic name= links
* =REMOVE_ANCHOR_DASHES= can be set to 1/0 to enable/disable removing anchor dashes when writing =[<nop>[#SomeAnchor]]=
All these settings are on by default.

---++ Tests
#TestHere
If the plugin is installed and enabled:
<!--
* Set SPACE_OUT_WIKI_WORD_LINKS = %URLPARAM{"SPACE_OUT_WIKI_WORD_LINKS" default="0"}%
* Set SPACE_OUT_UNDERSCORE_LINKS = %URLPARAM{"SPACE_OUT_UNDERSCORE_LINKS" default="0"}%
* Set REMOVE_ANCHOR_DASHES = %URLPARAM{"REMOVE_ANCHOR_DASHES" default="0"}%
* Set DONTSPACE = %URLPARAM{"DONTSPACE"}%
-->
<form method="post" action="%SCRIPTURL{"view" web="%WEB%" topic="%TOPIC%" #="Tests"}%">
* SPACE_OUT_WIKI_WORD_LINKS <input type="checkbox" name="SPACE_OUT_WIKI_WORD_LINKS" value="1" %IF{"$SPACE_OUT_WIKI_WORD_LINKS" then="checked"}%>
* SPACE_OUT_UNDERSCORE_LINKS <input type="checkbox" name="SPACE_OUT_UNDERSCORE_LINKS" value="1" %IF{"$SPACE_OUT_UNDERSCORE_LINKS" then="checked"}%>
* REMOVE_ANCHOR_DASHES <input type="checkbox" name="REMOVE_ANCHOR_DASHES" value="1" %IF{"$REMOVE_ANCHOR_DASHES" then="checked"}%>
* DONTSPACE (comma-separated list of things not to space) <input name="DONTSPACE" value="%DONTSPACE%" size="50"}%>

<input type="submit" value="Refresh">
</form>
* Plain Wikiword: %TOPIC%, ODDsAndEnds, AsYouLikeIt, JustAMinute
* Wikiword in brackets: [[%TOPIC%]]
* !Underscore_topic link: [[Spaced_Wiki_Word_Plugin]]
* Anchor dashes: [[#TestHere]]
* Pluralised ACRONYMs like [[JETs]] should not be spaced
* =%<nop>SPACEOUT{"WishUponAStar"}%=: %SPACEOUT{"WishUponAStar"}%


---++ Plugin Installation Instructions

To install plugin:
* Unzip the archive to the top of your directory
* Visit =configure= in your installation, and enable the plugin in the {Plugins} section.
---++ Installation Instructions

%X% WARNING: this plugin is designed for Foswiki 2.0 and later. It may work on some earlier Foswiki versions, but has not been tested with them.

---++ Plugin Info
%$INSTALL_INSTRUCTIONS%

| Copyright: | &copy; Foswiki:Main.MartinCleaver (2002, 2004), Foswiki:Main.ArthurClemens (2007, 2008) |
| Release: | %$RELEASE% |
| Version: | %$VERSION% |
| History: | <!-- specify latest version first -->&nbsp; |
---++ History
| 12 July 2017 | Crawford Currie: rewrote for Foswiki 2 |
| 10 Nov 2010 | Padraig Lennon: Foswikitask:Item9994 - Fix Release Version |
| 23 Nov 2007 | Arthur Clemens: made compatible to Foswiki; allow =DONTSPACE= to separated words by spaces. |
| 05 May 2007 | Arthur Clemens: fixed a wrong function call, thanks TWiki:Main.JohnFitzpatrick. |
| 04 May 2007 | Arthur Clemens: spacing out uses a Core function (from Plugins version 1.13; fallback for older versions); added support for spacing out of "underscore topic names"; added optional removal of anchor dashes. |
| 20 Apr 2007 | Arthur Clemens: updated with regexes from TWiki Core =spaceOutWikiWord=; added =DONTSPACE= option. |
| 12 Apr 2004 | Updated for TWiki 3 |
| 14 Apr 2002 | First release |
| CPAN Dependencies: | none |
| Other Dependencies: | none |
| Perl Version: | 5.0 |
| Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
| Support: | http://foswiki.org/Support/%TOPIC% |

__Related Topics:__ %USERSWEB%.SitePreferences, [[%SYSTEMWEB%.Plugins][Plugins]]
%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="Foswiki:Main.MartinCleaver (2002, 2004), Foswiki:Main.ArthurClemens (2007, 2008), Foswiki:Main.CrawfordCurrie (2017)"}%
%META:FIELD{name="Version" title="Version" value="%$VERSION%"}%
%META:FIELD{name="Release" title="Release" value="%$RELEASE%"}%
%META:FIELD{name="Repository" attributes="" title="Repository" value="https://github.com/foswiki/WorkFlowPlugin"}%
%META:FIELD{name="Support" attributes="" title="Support" value="http://foswiki.org/Support/SpacedWikiWordPlugin"}%
%META:FIELD{name="Home" attributes="" title="Home" value="http://foswiki.org/Extensions/SpacedWikiWordPlugin"}%

0 comments on commit 8bb0582

Please sign in to comment.