diff --git a/data/System/SpacedWikiWordPlugin.txt b/data/System/SpacedWikiWordPlugin.txt index b90dd61..cc1948a 100644 --- a/data/System/SpacedWikiWordPlugin.txt +++ b/data/System/SpacedWikiWordPlugin.txt @@ -1,15 +1,23 @@ %META:TOPICINFO{author="ProjectContributor" date="1081752098" format="1.0" version="1.1"}% ----+!! Spaced Wiki Word Plugin +---+!! %TOPIC% + -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 =[[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. @@ -21,28 +29,17 @@ Use underscore topic names if you want total control over links: * A topic name such as =[[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=, =[[TopicName]]=. + wiki words are automatically spaced out. Automatically spaced out are: =TopicName=, =Web.TopicName=, =[[TopicName]]=. Explicitly written link labels are *not* spaced out. Examples: =[[TopicName][TopicName]]= or =[[TopicName][SomeOtherName]]=. ---+++ Underscore links -=SPACE_OUT_UNDERSCORE_LINKS= needs to be set to =1=. Automatically spaced out are: =[[Underscore_topic]]=, but not =Underscore_topic= (without brackets). +=[[Underscore_topic]]= is automaticlly spaced out (but not =Underscore_topic=). #SearchResults ---+++ Spacing out search results -Link labels in search results are also considered 'explicit': - - -[[$web.$topic][$topic]] - -... is not spaced out automatically. - -Instead write: +Use the =[[VarSPACEOUT][SPACEOUT]]= macro. For example, write: [[$web.$topic][$percntSPACEOUT{$topic}$percnt]] @@ -56,72 +53,60 @@ 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 =[[WebHome][WebHome]]=, "WebHome" is not spaced out. Use =[[WebHome]]= or =[[WebHome][%SPACEOUT{"WebHome"}%]]= * You have used underscore topic names without bracket notation. Always write =[[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 =[[#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 =[[#SomeAnchor]]= +All these settings are on by default. + +---++ Tests +#TestHere +If the plugin is installed and enabled: + +
+ * SPACE_OUT_WIKI_WORD_LINKS + * SPACE_OUT_UNDERSCORE_LINKS + * REMOVE_ANCHOR_DASHES + * DONTSPACE (comma-separated list of things not to space) + + +
+ * 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 + * =%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: | © Foswiki:Main.MartinCleaver (2002, 2004), Foswiki:Main.ArthurClemens (2007, 2008) | -| Release: | %$RELEASE% | -| Version: | %$VERSION% | -| History: |   | +---++ 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. | @@ -129,10 +114,12 @@ To install plugin: | 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"}% + diff --git a/lib/Foswiki/Plugins/SpacedWikiWordPlugin.pm b/lib/Foswiki/Plugins/SpacedWikiWordPlugin.pm index 1360f8f..cc6d596 100644 --- a/lib/Foswiki/Plugins/SpacedWikiWordPlugin.pm +++ b/lib/Foswiki/Plugins/SpacedWikiWordPlugin.pm @@ -1,184 +1,117 @@ -# Plugin for Foswiki - The Free and Open Source Wiki, http://foswiki.org/ -# -# Copyright (c) by Foswiki Contributors. All Rights Reserved. Foswiki Contributors -# are listed in the AUTHORS file in the root of this distribution. -# NOTE: Please extend that file, not this notice. -# -# This program is free software; you can redistribute it and/or -# modify it under the terms of the GNU General Public License -# as published by the Free Software Foundation; either version 2 -# of the License, or (at your option) any later version. For -# more details read LICENSE in the root of this distribution. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -# -# For licensing info read LICENSE file in the Foswiki root. - -# ========================= +# See bottom of file for license and copyright information package Foswiki::Plugins::SpacedWikiWordPlugin; -# ========================= -use vars qw( - $web $topic $user $installWeb $VERSION $RELEASE $debug %dontSpaceSet $spaceOutWikiWordLinks $spaceOutUnderscoreLinks $removeAnchorDashes -); - -# This should always be $Rev$ so that Foswiki can determine the checked-in -# status of the plugin. It is used by the build automation tools, so -# you should leave it alone. -$VERSION = '$Rev$'; - -# This is a free-form string you can use to "name" your own plugin version. -# It is *not* used by the build automation tools, but is reported as part -# of the version number in PLUGINDESCRIPTIONS. -$RELEASE = '1.0.1'; +use strict; +use warnings; + +our $VERSION = '1.1'; +our $RELEASE = '12 July 2017'; +our $SHORTDESCRIPTION = "Space out Wiki Word links automatically"; +our $NO_PREFS_IN_TOPIC = 1; + +our $spaceOutWikiWordLinks; +our $spaceOutUnderscoreLinks; +our $removeAnchorDashes; +our %dontSpaceSet = (); +our $default_spaceOutWikiWord; + +sub _get_bool_pref { + my ($n, $default) = @_; + my $v = Foswiki::Func::getPreferencesValue($n); + return $default unless defined $v; + $v = Foswiki::Func::expandCommonVariables( $v ); + return $v; +} -# ========================= sub initPlugin { - ( $topic, $web, $user, $installWeb ) = @_; - - # check for Plugins.pm versions - if ( $Foswiki::Plugins::VERSION < 1 ) { - &Foswiki::Func::writeWarning( - "Version mismatch between SpacedWikiWordPlugin and Plugins.pm"); - return 0; + my ( $topic, $web, $user, $installWeb ) = @_; + + $spaceOutWikiWordLinks = _get_bool_pref("SPACE_OUT_WIKI_WORD_LINKS", 1); + $spaceOutUnderscoreLinks = _get_bool_pref("SPACE_OUT_UNDERSCORE_LINKS", 1); + $removeAnchorDashes = _get_bool_pref("REMOVE_ANCHOR_DASHES", 0); + my $dontSpaceWords = _get_bool_pref("DONTSPACE", ''); + $dontSpaceWords =~ s/^\s*(.*?)\s*$/$1/; + %dontSpaceSet = map { $_ => 1 } split( /[,\s]+/, $dontSpaceWords ); + + # Monkey patch! + unless (defined $default_spaceOutWikiWord) { + $default_spaceOutWikiWord = \&Foswiki::spaceOutWikiWord; + no warnings; + *Foswiki::spaceOutWikiWord = \&_spaceOutWikiWord; + use warnings; } - - # Get plugin debug flag - $debug = &Foswiki::Func::getPreferencesFlag("SPACEDWIKIWORDPLUGIN_DEBUG"); - - $spaceOutWikiWordLinks = - &Foswiki::Func::getPreferencesValue("SPACE_OUT_WIKI_WORD_LINKS") - || &Foswiki::Func::getPreferencesValue( - "SPACEDWIKIWORDPLUGIN_SPACE_OUT_WIKI_WORD_LINKS"); - - $spaceOutUnderscoreLinks = - &Foswiki::Func::getPreferencesValue("SPACE_OUT_UNDERSCORE_LINKS") - || &Foswiki::Func::getPreferencesValue( - "SPACEDWIKIWORDPLUGIN_SPACE_OUT_UNDERSCORE_LINKS"); - - $removeAnchorDashes = - &Foswiki::Func::getPreferencesValue("REMOVE_ANCHOR_DASHES") - || &Foswiki::Func::getPreferencesValue( - "SPACEDWIKIWORDPLUGIN_REMOVE_ANCHOR_DASHES"); - - my $dontSpaceWords = &Foswiki::Func::getPreferencesValue("DONTSPACE") - || &Foswiki::Func::getPreferencesValue("SPACEDWIKIWORDPLUGIN_DONTSPACE"); - $dontSpaceWords =~ s/^\s*(\w+)\s*$/$1/go; - $dontSpaceWords =~ s/\s+/ /go; - %dontSpaceSet = map { $_ => 1 } split( /[,\s]/, $dontSpaceWords ) - if $dontSpaceWords; - - Foswiki::Func::registerTagHandler( 'SPACEOUT', \&_SPACEOUT ); - - # Plugin correctly initialized - &Foswiki::Func::writeDebug( - "- Foswiki::Plugins::SpacedWikiWord::initPlugin( $web.$topic ) is OK") - if $debug; + return 1; } =pod ---++ renderWikiWordHandler( $linkLabel, $hasExplicitLinkLabel ) -> $text - +Handler invoked by the core rendering engine to render a wikiword. * =$linkLabel= - the link label to be spaced out * =$hasExplicitLinkLabel= - in case of bracket notation: the link label is written as [[TopicName][link label]] -We use the following rules: - - Space out in case of TopicName, Web.TopicName, [[TopicName]] - - Do not space out [[TopicName][TopicName]] or [[TopicName][SomeOtherName]]; in these cases the topic author has used an explicit link label - - Search results written as [[$web.$topic][$topic]] are not spaced -out. Use [[$web.$topic][$percntSPACEOUT{$topic}$percnt]] instead. - =cut sub renderWikiWordHandler { my ( $linkLabel, $hasExplicitLinkLabel ) = @_; # do nothing if this label is defined in the do-not-link list - return $linkLabel if $dontSpaceSet{$linkLabel}; - - if ( $spaceOutUnderscoreLinks && !$hasExplicitLinkLabel ) { - $linkLabel = _spaceOutUnderscoreTopicLinks($linkLabel); - } - - if ( $spaceOutWikiWordLinks && !$hasExplicitLinkLabel ) { - if ( $Foswiki::Plugins::VERSION < 1.13 ) { - $linkLabel = _spaceOutWikiWordLinks($linkLabel); - } - else { - $linkLabel = Foswiki::Func::spaceOutWikiWord($linkLabel); - } - - # eat anchor dash - $linkLabel =~ s/^#(.*?)$/$1/go if $removeAnchorDashes; + $linkLabel =~ s/^(#)//; + my $dashed = $1 // ''; + + unless ( $hasExplicitLinkLabel || $dontSpaceSet{$linkLabel}) { + $linkLabel =~ s/_/ /g if $spaceOutUnderscoreLinks; + $linkLabel = Foswiki::Func::spaceOutWikiWord($linkLabel) + if ( $spaceOutWikiWordLinks ); } + + # eat anchor dash + $dashed = '' if $removeAnchorDashes; - return $linkLabel; + return ($dashed ? '#' : '') . $linkLabel; } =pod ---++ _spaceOutWikiWordLinks( $linkLabel ) -> $text -Fallback for older Plugins version. Regexes are copied from Foswiki::spaceOutWikiWord. +Monkey-patch replacing Foswiki::spaceOutWikiWord. * =$linkLabel= - the link label to be spaced out =cut -sub _spaceOutWikiWordLinks { - my ( $linkLabel, $sep ) = @_; - - my $separator = $sep || ' '; - my $lowerAlphaRegex = Foswiki::Func::getRegularExpression('lowerAlpha'); - my $upperAlphaRegex = Foswiki::Func::getRegularExpression('upperAlpha'); - my $numericRegex = Foswiki::Func::getRegularExpression('numeric'); - - $linkLabel =~ -s/([$lowerAlphaRegex])([$upperAlphaRegex$numericRegex]+)/$1$separator$2/go; - $linkLabel =~ s/([$numericRegex])([$upperAlphaRegex])/$1$separator$2/go; - - return $linkLabel; +sub _spaceOutWikiWord { + my ( $word, $sep ) = @_; + + $word //= ''; + $sep //= ' '; + my $mark = "\001"; + $word =~ s/([[:upper:]])([[:digit:]])/$1$mark$2/g; + $word =~ s/([[:digit:]])([[:upper:]])/$1$mark$2/g; + $word =~ s/([[:lower:]])([[:upper:][:digit:]]+)/$1$mark$2/g; + $word =~ s/(^|[^[:upper:]])([[:upper:]])([[:upper:]])([[:lower:]])/$1$2$mark$3$4/g; + $word =~ s/$mark/$sep/g; + return $word; } -=pod - -Space out underscore topic links: "Human_revolution" becomes "Human revolution" - - * =$linkLabel= - the link label to be spaced out - -=cut - -sub _spaceOutUnderscoreTopicLinks { - my ($linkLabel) = @_; - - $linkLabel =~ s/_/ /go; - - return $linkLabel; -} - -=pod - -Override Foswiki _SPACEOUT function to enable spacing out of underscore topic links. +1; +__END__ +Copyright (C) 2008-2017 Foswiki Contributors. All Rights Reserved. Foswiki Contributors +are listed in the AUTHORS file in the root of this distribution. +NOTE: Please extend that file, not this notice. - * =$this= - not used - * =$params= - - (default) - the string to space out - - separator - the separator string, default a space - -=cut +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. For +more details read LICENSE in the root of this distribution. -sub _SPACEOUT { - my ( $this, $params ) = @_; +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - my $spaceOutTopic = $params->{_DEFAULT}; - my $sep = $params->{'separator'}; - $spaceOutTopic = _spaceOutWikiWordLinks( $spaceOutTopic, $sep ); - $spaceOutTopic = _spaceOutUnderscoreTopicLinks($spaceOutTopic); - return $spaceOutTopic; -} +For licensing info read LICENSE file in the Foswiki root. -1; +As per the GPL, removal of this notice is prohibited.