Item5308: shout louder, and more slowly, about Foswiki::cfg

git-svn-id: http://svn.foswiki.org/trunk@4866 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

EmptyPlugin/data/System/EmptyPlugin.txt

@@ -1,20 +1,25 @@
 %META:TOPICPARENT{name="Plugins"}%
 ---+ Empty Plugin
 
-This Plugin does nothing.
-
-This is an empty Plugin topic you can use as a template for your own Plugin
-documentation topic.
+%SHORTDESCRIPTION%
 
 Learn how to create your own plugin in %SYSTEMWEB%.DevelopingPlugins.
 
 ---++ Plugin Preferences
 
-You are advised to use the name of the plugin as a prefix to any
-[[%SYSTEMWEB%.PreferenceSettings][preference settings]] you define for the
-extension. This avoids the risk of namespace clashes with other extensions that
-may try to use the same name. For example:
+Plugin preferences should be set using =configure=, as described in
+%SYSTEMWEB%.DevelopingPlugins. You can also use
+[[%SYSTEMWEB%.PreferenceSettings][preference settings]] to define any
+user-controllable configuration. You are strongly advised
+to use the name of the plugin as a prefix, to avoid the risk of namespace
+clashes with other extensions that may try to use the same name.
+
+*BAD*
+   * Set EXAMPLE = Example setting
+   * Set FORMAT  = %d-%m-%y
+*Good*
    * Set EMPTYPLUGIN_EXAMPLE = Example setting
+   * Set EMPTYPLUGIN_FORMAT  = %d-%m-%y
 
 <!--
 One line description, required for extensions repository catalog.
@@ -27,7 +32,7 @@ One line description, required for extensions repository catalog.
 ---++ Plugin Info
 
 |  Author: | Foswiki:Main.PluginAuthor|
-|  Copyright: | &copy; 2008, Foswiki Contributors |
+|  Copyright: | &copy; 2009, Foswiki Contributors |
 |  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
 |  Release: | %$RELEASE% |
 |  Version: | %$VERSION% |

EmptyPlugin/lib/Foswiki/Plugins/EmptyPlugin.pm

@@ -81,10 +81,13 @@ our $SHORTDESCRIPTION = 'Empty Plugin used as a template for new Plugins';
 # preferences set in the plugin topic. This is required for compatibility
 # with older plugins, but imposes a significant performance penalty, and
 # is not recommended. Instead, leave $NO_PREFS_IN_TOPIC at 1 and use
-# =$Foswiki::cfg= entries set in =LocalSite.cfg=, or if you want the users
+# =$Foswiki::cfg= entries, or if you want the users
 # to be able to change settings, then use standard Foswiki preferences that
 # can be defined in your %USERSWEB%.SitePreferences and overridden at the web
 # and topic level.
+#
+# %SYSTEMWEB%.DevelopingPlugins has details of how to define =$Foswiki::cfg=
+# entries so they can be used with =configure=.
 our $NO_PREFS_IN_TOPIC = 1;
 
 =begin TML
@@ -129,7 +132,7 @@ sub initPlugin {
     # Set your per-installation plugin configuration in LocalSite.cfg,
     # like this:
     # $Foswiki::cfg{Plugins}{EmptyPlugin}{ExampleSetting} = 1;
-    # Optional: See %SYSTEMWEB%.DevelopingPlugins#ConfigSpec for information
+    # See %SYSTEMWEB%.DevelopingPlugins#ConfigSpec for information
     # on integrating your plugin configuration with =configure=.
 
     # Always provide a default in case the setting is not defined in