This topic started in Support.WhyUsePluginsAndTWikiForPluginTopics.

Please vote on where Plugin docs should go: (moved from within the text by MartinCleaver)

Who	Vote for web	Note
PeterThoeny	TWiki	All docs (TWiki & Plugins) in one web. A (future) TWiki installer can ease the upgrade
GrantBow	TWiki	the TWiki web is the only one that's really gauranteed to exist and I think it makes the most sense to keep the docs there as well. Yet this is maintenance hell.
ColasNahaboo	Plugins	TWiki should be reserved to things coming from out-of-the-box distrib. Mixing distributed info (docs) and local modifications (Plugins) is maintainance hell
LynnwoodBrown	Plugins	Combine Plugins with other upgradable modules a la TWikiToolChest. See note below.
MartinCleaver	TWikiConfig	Keep stuff separate; don't pollute web namespace with names that might want to be used for the site; use and test WebNameAsWikiName (as MS did with 'Program Files')
CrawfordCurrie	Plugins	I agree with Colas; we're creating a real maintenance problem.
AndrewZinck	TWiki	I prefer all system docs to be in one place (even though it currently means more work at upgrade time!)
PeterMasiar	Plugin	Ease of maintenance and upgrade is important (or at least should be). I really do not get it why we cannot add one more standard web - Plugins - in distribution. Or I am so stupid and there is some obvious reason? Can you please tell me?
MichaelSparks	Plugins and TWiki	Have default settings in TWiki. Local Settings in Plugins (see below)
AndreaSterbini	Plugins	I place them in "Plugins" (where they are automatically searched after "TWiki") to keep them all together. You can place them also in TWiki or in the current web if you want a plugin only in a single web. It's useful if the plugin author reminds the admin that they can move the topic after the "unpack" step.
Main.

-- PeterThoeny - 21 Jan 2003

Why are both the TWiki:TWiki and TWiki:Plugins webs used for plugin topics? The majority of plugins use the TWiki web to keep topics in, but there are many that also use the Plugins web.

IMO, all plugin topics should be in the Plugins web, or the Plugins web itself should be disallowed for use by plugin developers. Having 60% of the plugin topics in one web, and 40% in another is just too confusing.

-- MikeMaurer - 20 Jan 2003

I understand the use of the Plugins web at twiki.org, but there are plugins that are packaged with their topics in data/Plugins. Maybe I need to clarify a little more. My question has nothing to do with how twiki.org is layed out, or what individual webs are for. I understand that the TWiki web is for documentation, and have no issue with using it to hold Plugin help topics, as most plugins are pre-packaged this way. However, some are packaged with their help topics in the Plugins web.

It is trivial to just move the data file during installation, but why are some plugins packaged this way? Can topics pacakged in the Plugins directory be moved to the TWiki directory without breaking the associated plugin?

Examples include:

• ActionTrackerPlugin
• CalendarPlugin
• LdapPlugin
• PollPlugin
• TWikiDrawPlugin

-- MikeMaurer - 21 Jan '03

Thanks very much for this list. These plugins have hard coded paths and bugs in the packaging.

-- GrantBow - 21 Jan 2003

Answer

The Plugins Web on the TWiki.org site is for listing and tracking the development of all plugins for the TWiki platform. Plugins that are actually installed for use, either on TWiki.org OR on one's own site, are included in the TWiki web which contains all "help" topics.

-- LynnwoodBrown - 20 Jan 2003

This is actually a good question. Some Plugin authors prefer to pack their Plugin into the TWiki web (all TWiki related stuff in one web; less webs), some prefer to keep it in the Plugins web (separation of TWiki doc/config and Plugins)

TWiki discovers the Plugin in both webs, e.g. the TWiki and Plugin webs are supported. Most Plugins should work in the "other web" then the one it was packaged in, provided the Plugin code does not use hardcoded web names (each Plugin has a $installWeb variable)

For consistency it would be better to recommend to the Plugin authors to use only one web (but TWiki is supporting both for backward compatibility). May be we should start a voting table (moved to top by MartinCleaver)

Please keep in mind that Plugins are supposed to work in both webs, so admins can choose where to put them. The vote is just to decide where to package Plugins for consistency.

-- PeterThoeny - 21 Jan 2003

Yes. BTW my use if to have a "Wiki" web listing the infos on the local install of the (T)wiki engine. This webs describes local infos, as it is the most important info for a new user (status of twiki in the company, who maintains it, intended use, local modifications), and points to TWiki for reference documentation, and Plugins for installed plugins.

-- ColasNahaboo - 21 Jan 2003

Colas, this sounds like a very interesting and useful arrangement. I didn't even realize that a Plugins web could be used insted of the TWiki web.

The choice of webs seems to me to be very customized for each site. Also given the history of no TWiki web at all and only a Main (I was surprised to recently read about this), the waters seem muddy compared to allowing TWiki developers to set unmovable standards for web configurations for all sites. Right now I don't think any conventions can be assumed and I don't think that's too bad a situation. It sounds like with some modification and use of variables in the packaging of Plugins that they can be installed in just about any web without too much difficulty. I need to dig in to find out for myself how difficult this really is, but I am attracted to this approach.

Aside: I feel that all Webs (except TWiki) should be created dynamically from the new web creation pages instead of shipping them installed by default, but that's another discussion entirely I think.

-- GrantBow - 21 Jan 2003

I did not wish to immediately vote for either. Here is the way I feel:

• The Plugins web is my preference organizationally, but
• The TWiki web should be used unless we begin shipping TWiki with the Plugins Web in the base package. Otherwise one would have to ensure the creation of the Plugins web before installing the first plugin.

-- WalterMundt - 21 Jan 2003

Every time I upgrade a Twiki (i've done 4-5 upgrades) I run into the probelm of whether or not to upgrade the TWiki web. doing so involves searching out the customisation that have been done to run the web, settings and Plugins etc. This is no fun, and I have no idea how to automate it (like for the debian package install) For this reason I would like to suggest the idea of a ConfigurationWeb, this way the Webs that come with a Release should be able to be replace the previous release's Webs without makeing the upgrade hell.

For this reason I also think that we should ship all Plugins in the release, but disabled in the ConfigurationWeb. That way each new release updates the Plugins.

-- SvenDowideit - 21 Jan 2003

What would really help is if the ConfigurationWeb could initially be empty, and its topics 'override' those in the TWiki web - i.e. it has its own TWikiPreferences, which if present overrides the TWiki.TWikiPreferences. The idea is that the ConfigurationWeb is the 'local site config', very much like SpamAssassin and many other tools that let the user have a 'user config' overriding the standard site config.

Another idea is to have a FreeBSD style 'merge' tool that lets you merge the new standard TWikiPreferences with the locally modified TWikiPreferences. This could be done with Unix/Linux/CygWin shell scripts and GNU diff3, which is part of the GNU diffutils package that is already in TWikiSystemRequirements. If someone is feeling like real coding, they could write a CGI script to wrap around diff3, but that could be a lot of work.

On balance, I prefer the merge solution, as this could be used for many upgrade issues and doesn't add (even more) run-time overhead - it also avoids the confusion of possible duplication of TWikiPreferences settings. I'm sure other OpenSource projects have solved the merge/upgrade issue already, so it would be good to hear how they've done this.

Of course, what's really needed is a TWikiUnixInstaller with upgrade features, but simple tools that involve more user involvement are a good first step.

-- RichardDonkin - 22 Jan 2003

Having just completed the upgrade to TWikiRelease01Feb2003, I'm all for having a TWikiUnixInstaller or at least a SimplerUpgradePath! I had to go through several folders (TWiki, Know, Main) to parse out my topics from the installed base topics. One thought on creating a new ConfigurationWeb: why not just go annoint TWiki as the official "system" and documentation web and consolidate upgradeable elements there as much as possible? TWiki is basically serving that role already so let's just carry it further.

While we were at it, let's also include a sampling of the "lastest and greatest" TwikiApplications along the lines of ItemToDo (and as was discussed in EZUsabilityUpgradePlan, and TWikiToolChest). This would dispense with the need for upgrading Know.Webhome since it is basically a demonstration web anyway (one which we tend to populate with our own topics creating yet another upgrade hassle).

I also like the idea of including the lastest batch of stable plugins that can be easily "switched on" as needed. So what if it creates a larger download? That's far easier time spent than sorting through files or individually re-installing a bunch of plugins!

In response to some of the comments above about mixing docs and plugins making maintenance difficult, you must be speaking from a developer's perspective rather than endusers. I make very few changes to the TWiki web other than to install plugins so I wouldn't mind simply replacing the TWiki web as a whole in an upgrade. One lesson I've learned from this last upgrade is that, in the future, I'm going to keep my modifications to the TWiki help files (such as GoodStyle & TextFormattingRules) in separate topics (and even another web) and then %INCLUDE% them into the standard topics so that I don't have to re-edit in the changes after upgrading.

-- LynnwoodBrown - 10 Feb 2003

I like the idea of just being able to unpack/install a twiki distribution without having to worry about about my local preferences being clobbered. Installing Plugins should work exactly the same. Whether this is accomplished by the ConfigurationWeb (I think I would called it etc, local or prefs ) proposal or an intelligent merge, I don't care so long as it works and is standardised.

I second the motion for the plugins to installed by default, but turned off. There could be a classification system to let new twiki-admins know which plugins are production use worthy and which are unstable or abandoned.

-- MattWilkie - 10 Feb 2003

I disagree that there should be an option as to where to locate the Plugins, it should be standardised everywhere - what do we gain by this not being the case?

Put all Config together and separate from out of the box stuff. I've said above to include TWikiExtensions in a TWikiConfig web; some might even prefer a separate TWikiExtensions web to a TWikiConfig web.

-- MartinCleaver - 24 Apr 2003

I recently moved my plugins into the TWiki web to conform to the 'standard' but I dislike having to do so. This is purely because of the problems I've had in the past doing upgrades. The TWiki, Main and Know webs are areas I prefer to treat as untouchable. The less people who can dabble with the components of the standard install the better, I say, to the extent that I would like to be able to restrict write access to these three webs to the Admin group only.

-- CrawfordCurrie - 25 Apr 2003

Like, CrawfordCurrie, I too recently migrated all my plugin topics into the TWiki web. I wanted to consolidate the help files in one place and anyway Plugins was looking more and more like a graveyard ("Why maintain an entire web for just a couple of topics?" I asked myself). I did find the latest update to TWikiRelease01Feb2003 a challenge because I had edited a number of key topics in the TWiki web, but I like having all the info in one place. I am also a firm believer in customizing the "out-of-the-box" materials to better suit my own needs (that's one of the things I like about TWiki), so perhaps I have only my masochistic self to blame for the extra time it took. However, I am happy with the simplified structure (and so are those who are using my site).

I'm not sure about the whole TWikiConfig web thing. Perhaps it's just my own lack of ability to understand it clearly. It seems like another layer of complexity, although I'd welcome an explanation of TWikiConfigWebForDummies!

I have often thought that it would be nice to include a large base of plugins with the distribution and then simply "activate" them as necessary, but a practical problem appears since some of the plugins require additional perl modules to be installed. This could cause problems for some people setting up a new installation of TWiki, particularly if they don't realize that the modules are necessary. I can see more than one frustrated person blaming TWiki for certain plugins not working right away. That's the last thing we need. One might have to restrict distributed plugins to only those that have no additional perl module requirements. At least including those would give a taste of what is possible and simplify the setup slightly.

-- AndrewZinck - 25 Apr 2003

There is some difficulty in installing plugins, or packaging for distribution. There should be a Makefile or script file in the root dir to do this, along the lines of the example solution below.

I have found plugins a pain to install (but skins are worse) because one of the first customizations I do is to rename the webs. (I've installed twiki again this week as a small corporate intranet.)

The install for skins is even more problematic because not only do they need to put things in templates/ (which is often in a far-off location relative to pub/ and lib/) but the .tmpl files themselves often have hard-coded Web names in them for no good reason. I usually end up using grep TWiki *tmpl and editting out all the occurances, for example.

I believe an installation Makefile (or script) would solve install and 3rd party distribution problems for both plugins and skins:

• use directory settings from TWiki.cfg
• use web names from TWiki.cfg
• for installs, the .zip files have a known subdirectory format which is unpacked elsewhere and copied into the user-customized directories
  • make PLUGIN=TWikiDraw install
• for packing into a distribution,
  • the file list would be part of a variable included makefile
    • TWikiDraw.mk could contain
      • PLUGINNAME=TWikiDrawPlugin
      • PUBFILES=pub/Plugins/${PLUGINNAME}/example.gif ${PLUGINNAME}/example.draw ...
      • LIBFILES=${PLUGINNAME}/source.zip
      • DATAFILES=${PLUGINNAME}/TWikiDrawPlugin.txt
  • make SKIN=VoidSkin distrib would
    • copy files to temp, put in a predefined (i.e. the default) dir structure
    • zip the structure, put in root dir

There could also be a make uninstall option which would use the distribution's .mk file (or etc) to remove the whole thing. So I guess I consider the above discussion a symptom; the real problem is poor install/uninstall/packaging management.

-- JonathanCline - 05 Jun 2003

I added my vote for adding Plugin as standard web in distro. I really do not get it. Everybody here is proud about Plugins as best feature of the Twiki. There are bunch of nice stable mature plugins available. Other plugins are getting there. For me is obvious they should go somewhere where it's easy to deal with them. Also, there should be some curator or project manager who will read plugins code and give advice how to make it more portable. Write some guidelines. I cannot write them, I need them myself. But more advanced plugin authors - can you please agree on something and guide us? To make our life less miserable and more productive?

I know hacking the code is more fun. But lack of guidance is apparent on Twiki for a long while. How I can help moving the mountain if I do not know which way to go?

-- PeterMasiar - 06 Jun 2003

I've actually shifted my view on this subject. I had been for including all upgradable components within one web (TWiki) but I see now that the different frequency or rhythm of upgrades between the core system and the plugins makes intermixing them problamatic. It would simplify upgrades if one could upgrade the core system by replaceing the entire TWiki web. Plugins and other upgradeable modules would carry over in their own web and be upgraded piecemeal. However, as JonathanCline points out, better install/uninstall/packaging management via improved TWikiUnixInstaller,InstallationScripts, AutomatedBuildAndInstallOfPlugins or similar tools might make this whole discussion moot.

If Plugins by themselves are too meager in content to fill their own web, then perhaps this web could house other upgradable "modules" along the lines of TWikiToolChest. We're beginning to gather some more TWikiApplication in the Sandbox. I propose that these would be more appropriately grouped with plugins, even if they don't involve code. Afterall, the Plugins web doesn't actually contain the code but only their documentation and demonstrations of their application. Doesn't this blur the line between plugin and TWikiApplication? Looking back over the Plugins web, I see the precedent has already been set with AddOnPackages

-- LynnwoodBrown - 06 Jun 2003

Plugins are not meager, IMHO. We already have stable usable skins. They should go to Plugin and into distro, so new admin can pick one of half a dozen skins and use it. Slide show plugin is nice, cool and stable. What might be reasoen not to include it in the distro?

-- PeterMasiar - 06 Jun 2003

Personally I see the TWiki web as having 2 main pieces of functionality:

• Documentation
• Site wide configuration

I also see the Plugins has similar functionality:

• Documentation
• Site wide configuration

ie same basic functionality!

Let's exclude the documentation aspect - in this case they both become configuration webs. Given that the TWiki web is by default shipped with new releases, if you upgrade simply by unzipping over your old distribution ... you break everything. Your TWiki-, Web- and any plugins shipped- Preferences all get wiped. What would be better?

• Treat the TWiki web as essentially read only
• If someone wants to change a config variable, they copy the config file into the Plugins (or probably better Config?) web.
• Likewise, plugins by default put their NamePlugin page into the TWiki web. To configure the plugin the user has to have a copy of the page in their Plugins/Config web.

Whilst this Plugins/Config web would then be a default web - it would be shipped empty. (Think of it this way, the TWiki web acts as a base class which people don't modify, the Config web inherits from the TWiki web and is modifiable)

A script should then be run after unpacking a distribution that performs the following logic:

foreach file in TWiki/data:
   if [ not -x Config/data/file ] :
      cp TWiki/data/file Config/data/file

(This would avoid the user having to do this themselves)

Then when a plugin or part of twiki wants a variable's value it checks the following:

• The current Topic
• The current Web's WebPreferences
• The Plugins or Config web
• The TWiki or System web

That way you get separation of code/tar ball things (they all go in TWiki/System) and local/config things (Plugins/Config).

This would ease the burden of sysadmins performing upgrades, make life simpler for Plugin writers ("Which web? The TWiki web of course!") and overall bring about world peace. (OK, maybe going to far there )

Given I've been going through cleaning up the TWikiUnixInstaller in recent days I see no reason I couldn't add support for this sort of thing as well.

-- MichaelSparks - 06 Jun 2003

I agree with practically everything you've just said, Michael.

Just one point: about the web called 'Config'.

Because people keep supporting that they don't need HierarchicallyNestedTwikiWebs, I think it is particularly important that the web names we choose do not conflict with anything the user might want to use. (Remember the 'Test' web and the continual hoo-har to get it renamed to Sandbox? 'Config' and 'System' (and for that matter, 'Plugins') could all provoke the same objections).

I therefore think that we either support HierarchicallyNestedTwikiWebs (my preference) and call the webs:

• TWiki.Config &
• TWiki.System

Or we keep the TWiki related webnames out of the user's namespace. One way do this is by calling the webs:

• TWikiConfig &
• TWikiSystem

If you wanted to not force people to test the WebNameAsWikiName feature (yet I suggest we need as much testing of it as possible), one way to do this would be by calling the webs:

• TWiki_Config &
• TWiki_System

-- MartinCleaver - 07 Jun 2003

I also agree. It makes eminent sense to me. As for the configuration web's name, I would call it Etc. This would be immediately familiar to unix users, strange to windows users but not too strange, and is unlikely to be used for another purpose. Another possiblity which makes semantic sense regardless of operating system is Local. -- Not that I think Martin's suggestion of Twiki_Config is a bad one, I just wanted to fill out the choices.

-- MattWilkie - 08 Jun 2003

PeterKlausner - 21 Oct 2004: Factored out to SeparateTWikiSystemAndSitePreferences

-- PeterKlausner - 09 Jun 2003

PeterKlausner, what you say makes sense. I think the idea should be explored further. I do wonder if maybe I want to keep my user registrations seperate from site administrivia though. I'm not sure.

ColasNahaboo requested skin templates be put in templates/thisskin/, =templates/thatskin. I seconded the idea as it would make developing and upgrading/retrograding/uninstalling skins so much easier. I can't find the topic either, not even with google.

-- MattWilkie - 10 Jun 2003

Using Main web for users is relist from times where Twiki was everything in one web as other wikis do. Many installation RenameTheMainWeb. KoalaSkin does the Right Thing: groups related webs. So we should have System groupweb where Twiki, User, Plugins, Config And Sandbox webs are, they always exist, and users should go only to Sandbox to play. All mistuderstanding comes from wrong naming. Name it "Main" and yyou are tempted to put pages there which belong to Config. How is newbie admin going to find them? Spending weeks reading docs? No, they will switch to other wikis, whih are simpler to install, and add missing features there. Try to install KwikiWiki and you will see the difference.

Why not do it intuitive way? And if plugins is the best feature of Twiki, why not to place it more promimently and make it easy to use and upgrade?

-- PeterMasiar - 10 Jun 2003