Docs updates

Trying to get the plugin documentation into shape

tw5.com/tiddlers/Docs.tid

@@ -29,7 +29,8 @@ The machinery tying those concepts together includes:
 * TiddlerTemplates
 * ContentType
 * ShadowTiddlers
-* TiddlerModules
+* [[Plugins]]
+* [[Modules]] and [[ModuleType]]
 
 ! Wiki Text Rules
 

tw5.com/tiddlers/concepts/ModuleType.tid

@@ -0,0 +1,25 @@
+title: ModuleType
+tags: docs concepts
+
+The `module-type` field of a [[JavaScript module|Modules]] is set to a string that identifies the type of the module. TiddlyWiki5 uses the following types:
+
+* `command` - individual commands for the `$tw.Commander` class 
+* `config` - values to be merged over the `$tw.config` global
+* `editor` - interactive editors for different types of content
+* `global` - members of the `$tw` global
+* `library` - external global JavaScript library, such as Esprima or jQuery
+* `macro` - macro definitions
+* `module` - generic type for modules `require`d by other modules
+* `parser` - parsers for different types of content
+* `saver` - functions for saving TiddlyWiki content on different platforms
+* `startup` - functions to be called by the kernel after booting
+* `storyview` - visualisations for the `story` macro
+* `tiddlerdeserializer` - methods to extract tiddlers from text representations or the DOM
+* `tiddlerfield` - defines the characteristics of tiddler fields of a particular name
+* `tiddlermethod` - additional methods for the `$tw.Tiddler` class
+* `tiddlerserializer` - methods to serialise tiddlers to text representations
+* `treenode` - classes of parser tree nodes
+* `treeutils` - static utility methods for parser tree nodes 
+* `utils` - general purpose utility functions residing in `$tw.utils`
+* `wikimethod` - additional methods for the `$tw.Wiki` class
+* `wikitextrule` - individual rules for the wikitext parser

tw5.com/tiddlers/concepts/Modules.tid

@@ -0,0 +1,4 @@
+title: Modules
+tags: docs concepts
+
+A //module// in TiddlyWiki5 is a tiddler containing executable JavaScript, of the type `application/javascript` and with the field `module-type` set to the ModuleType of the module.

tw5.com/tiddlers/concepts/Plugins.tid

@@ -0,0 +1,8 @@
+title: Plugins
+tags: docs concepts
+
+A plugin in TiddlyWiki5 is a bundle of tiddlers packaged together as a single tiddler. Plugins are used to distribute optional, custom components for TiddlyWiki. Plugins can be updated from their source as a unit.
+
+Plugins can contain JavaScript modules, style sheets, and templates to extend the functionality of TiddlyWiki itself. Plugins can also be used to distribute ordinary text, image or other content.
+
+See the PluginMechanism discussion for more details about how plugins are implemented internally.

tw5.com/tiddlers/mechanisms/BootMechanism.tid

@@ -7,23 +7,22 @@ TiddlyWiki5 is based on a 600-line boot kernel that runs on node.js or in the br
 
 The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers and execute JavaScript modules. Plugin modules are written like `node.js` modules.
 
-There are many different types of module: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module that knows how to handle the `tags` field, and another that knows how to handle the special behaviour of
-the `modified` and `created` fields.
+There are many [[different types of module|ModuleType]]: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module that knows how to handle the `tags` field, and another that knows how to handle the special behaviour of the `modified` and `created` fields.
 
 Some plugin modules have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugin modules.
 
 !Plugins and Modules
 
-In TiddlyWiki5, "plugins" are bundles of tiddlers that are distributed and managed as one; "modules" are JavaScript tiddlers with a module type identifying when and how they should be executed.
+In TiddlyWiki5, [[Plugins]] are bundles of tiddlers that are distributed and managed as one; [[Modules]] are JavaScript tiddlers with a module type identifying when and how they should be executed.
 
-The tiddler [[$:/core/boot.js]] is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup plugin module to load up the rest of the application.
+The tiddler [[$:/core/boot.js]] is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup module to load up the rest of the application.
 
 The kernel includes:
 
-* Eight short shared utility functions
-* Three methods implementing the plugin module mechanism
-* The `$tw.Tiddler` class (and three field definition plugins)
-* The `$tw.Wiki` class (and three tiddler deserialization methods)
+* Several short shared utility functions
+* A handful of methods implementing the plugin module mechanism
+* The `$tw.Tiddler` class (and field definition plugins)
+* The `$tw.Wiki` class (and tiddler deserialization methods)
 * Code for the browser to load tiddlers from the HTML DOM
 * Code for the server to load tiddlers from the file system
 
@@ -33,35 +32,9 @@ In the browser, `core/boot.js` is packed into a template HTML file that contains
 
 * Ordinary and shadow tiddlers, packed as HTML `<DIV>` elements
 * `core/bootprefix.js`, containing a few lines to set up the plugin environment
-* Plugin JavaScript modules, packed as HTML `<SCRIPT>` blocks
+* JavaScript modules, packed as HTML `<SCRIPT>` blocks
 * `core/boot.js`, containing the boot kernel
 
 On the server, `core/boot.js` is executed directly. It uses the `node.js` local file API to load plugins directly from the file system in the `core/modules` directory. The code loading is performed synchronously for brevity (and because the system is in any case inherently blocked until plugins are loaded).
 
 The boot kernel sets up the `$tw` global variable that is used to store all the state data of the system.
-
-!Core 
-
-The 'core' is the boot kernel plus the set of plugin modules that it loads. It contains plugins of the following types:
-
-* `tiddlerfield` - defines the characteristics of tiddler fields of a particular name
-* `tiddlerdeserializer` - methods to extract tiddlers from text representations or the DOM
-* `startup` - functions to be called by the kernel after booting
-* `global` - members of the `$tw` global
-* `config` - values to be merged over the `$tw.config` global
-* `utils` - general purpose utility functions residing in `$tw.utils`
-* `tiddlermethod` - additional methods for the `$tw.Tiddler` class
-* `wikimethod` - additional methods for the `$tw.Wiki` class
-* `treeutils` - static utility methods for parser tree nodes 
-* `treenode` - classes of parser tree nodes
-* `macro` - macro definitions
-* `editor` - interactive editors for different types of content
-* `parser` - parsers for different types of content
-* `wikitextrule` - individual rules for the wikitext parser
-* `command` - individual commands for the `$tw.Commander` class
-
-TiddlyWiki5 makes extensive use of JavaScript inheritance:
-
-* Tree nodes defined in `$:/core/treenodes/` all inherit from `$:/core/treenodes/node.js`
-* Macros defined in `$:/core/macros/` all inherit from `$:/core/treenodes/macro.js`
-

tw5.com/tiddlers/mechanisms/PluginMechanism.tid

@@ -1,51 +1,42 @@
 title: PluginMechanism
 tags: docs mechanism
 
-Plugins are bundles of tiddlers that are distributed and managed as a single unit.
+[[Plugins]] are bundles of tiddlers that are distributed and managed as a single unit by being packed into a single JSON tiddler. If a tiddler isn't found in the main store, then the loaded plugins are searched for it instead.
 
-Plugins usually have a title of the form `$:/plugins/publisher/name`. Plugins that are part of the core TiddlyWiki distribution have titles of the form `$:/core/plugins/name`.
+Tiddlers within plugins behave something like shadow tiddlers in classic TiddlyWiki: they can be freely overwritten by creating a tiddler with the same title, but deleting that tiddler restores the underlying tiddler value from the plugin.
 
-Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example: "tiddlytools.slider".
+Plugins conventionally have a title of the form `$:/plugins/publisher/name`. Plugins that are part of the core TiddlyWiki distribution have titles of the form `$:/plugins/tiddlywiki/name`.
 
-Plugins can contain tiddlers with arbitrary titles but are expected to sandbox their tiddlers into the shadow tiddler namespace, for example "$:/plugins/tiddlytools/superslider/handle.js".
-
-On both the server and in the browser, the constituent tiddlers of a plugin are created with the `tiddler.fromPlugin` member containing the title of the plugin. They can be filtered out with `[is[fromPlugin]]` and `[plugin[$:/plugins/name]]` (the latter selects all the tiddlers that are constituents of the plugin, regardless of whether they still hold the value specified in the plugin).
-
-Note that plugins can contain any tiddler content, and so can be used to distribute documentation, templates, or clip art.
+Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example: `tiddlytools.slider`.
 
 ! Plugin format
 
-Plugins are stored as tiddlers of type `application/x-tiddlywiki-plugin` containing a JSON structure encoding the plugin metadata and the list of tiddlers within it. After tiddlers have been loaded, plugins are exploded by iterating through the plugin tiddlers and creating the individual constituent tiddlers that they contain. Any tiddlers that already exist are preserved, and not overwritten.
+Plugins are stored as tiddlers of type `application/json` with the field `plugin` present and the text containing a JSON structure encoding the plugin metadata and the list of tiddlers within it.
 
 The JSON structure for plugin tiddlers is as follows:
 
 {{{
 {
 	"metadata": {
-		"title": "MyPlugin",
-		"pluginType": "plugin"
+		"title": "$:/plugins/publisher/name",
 		"description": "An exemplary plugin for demonstration purposes",
 		"author": "JeremyRuston",
 		"version": "1.2.3-alpha3",
 		"coreVersion": ">=5.0.0",
-		"source": "http://tiddlywiki.com/MyPlugin",
-		"dependencies": [
-			"dependent-plugin-1",
-			"dependent-plugin-2"
-		]
+		"source": "http://tiddlywiki.com/MyPlugin"
 	},
-	"tiddlers": [
-		{"title": "MyTitle", "type": "image/png", "text": "<base64>"},
-		{"title": "MyTitle2", "text": "Text"}
-	]
+	"tiddlers": {
+		"title1": {"type": "image/png", "text": "<base64>"},
+		"title2": {"text": "Text"}
+	}
 }
 }}}
 
-The title specified in the metadata block of the plugin must match the actual title of the tiddler in which the plugin is stored.
+The titles of the individual tiddlers within a plugin are automatically prefixed with the title of the plugin itself and a slash `/`. Thus, in the example above the two tiddlers within the plugin will have the titles `$:/plugins/publisher/name/title1` and `$:/plugins/publisher/name/title2`.
 
 ! Plugin folders
 
-On the server, plugins can be stored in folders containing a `plugin.tiddlywiki` file that contains the metadata for the plugin and specifies the files comprising it. It can also optionally override any metadata provided by the files themselves. Loading a plugin creates the JSON tiddler containing the plugin. It only creates the constituent tiddlers if they do not already exist.
+On the server, plugins can be stored as ordinary JSON tiddlers but it is often more convenient to store them as separate tiddler files within folders. Plugin folders must contain a `plugin.tiddlywiki` file that contains the metadata for the plugin. It can also optionally identify files external to the plugin folder that should be loaded as tiddlers.
 
 The `plugin.tiddlywiki` file should contain the following JSON structure:
 
@@ -61,33 +52,40 @@ The `plugin.tiddlywiki` file should contain the following JSON structure:
 }
 }}}
 
-! Plugin types
+The titles of the external tiddlers are again relative to the title of the plugin. Constituent tiddler files must specify the full title of the tiddler, including the name of the plugin.
 
-Plugins can have an optional plugin type:
+! Plugin library
 
-* ''plugin'' - an ordinary plugin loaded at boot time
-* ''pagetheme'' - a dynamically loaded page theme
-* ''tiddlertheme'' - a dynamically loaded tiddler theme
-* ''translation'' - a dynamically loaded translation
+The standard distribution of TiddlyWiki includes a number of standard plugins in the `plugins` directory.
 
-In the browser, any constituent tiddlers that are static styles (ie shadow tiddlers of content type `text/css`) or javascript library modules (ie shadow tiddlers of content type `application/javascript` and possessing the field `library`) are added to the DOM during processing.
+! Including plugins in a wiki
 
-! Loading plugins
+To be usable in the browser, plugins just need to be included in the wiki. This is done when the wiki is generated on the server.
 
-A folder containing an exploded TiddlyWiki can contain a `wiki.tiddlywiki` file that identifies the plugins to be included in this wiki, and specifies the load order:
+A folder containing an exploded TiddlyWiki can contain a `wiki.tiddlywiki` file that identifies the plugins to be included in this wiki:
 
 {{{
 {
 	"plugins": [
 		"slider",
 		"chooser",
-		"tiddlytools.superslider"
+		"tiddlytools/superslider",
+		"../../myplugins/specialone",
+		"/mylib/another",
 	]
 }
 }}}
 
+Plugins can be identified in several ways:
+
+* Names that do not contain a slash are interpreted as the name of a TiddlyWiki core plugin (ie, `$:/plugins/tiddlywiki/<name>`)
+* Names that start with a slash or dot are interpreted as pathnames to a plugin file or folder
+* Names that contain a single slash that is not at the start or end are interpreted as names of plugins from the core plugin library (ie, `$:/plugins/<publisher/name>`)
+
 Plugins can also be included manually by copying them into the `plugins` subfolder of the wiki.
 
-! Plugin implementation
+! Plugin processing
 
 The wiki object keeps track of all of the currently loaded plugins. If a request for a tiddler isn't in the store then the wiki looks through the cascade of plugins to find the requested tiddler. It is a similar idea to the way that shadow tiddlers are implemented in classic TiddlyWiki.
+
+In the browser, any constituent tiddlers that are static styles (ie shadow tiddlers of content type `text/css`) or JavaScript modules (ie shadow tiddlers of content type `application/javascript` and possessing the field `module-type`) are added to the DOM during startup processing.