From 85d7bb6d8b6d4220b69415cb5e7f61c6578fc549 Mon Sep 17 00:00:00 2001
From: Jeremy Ruston <jeremy@osmosoft.com>
Date: Sun, 10 Jun 2012 22:53:51 +0100
Subject: [PATCH] Docs updates

---
 tw5.com/tiddlers/Docs.tid              | 74 +++++++++++++++++---------
 tw5.com/tiddlers/concepts/Tiddlers.tid |  2 -
 tw5.com/tiddlers/concepts/Wiki.tid     |  2 -
 3 files changed, 48 insertions(+), 30 deletions(-)

diff --git a/tw5.com/tiddlers/Docs.tid b/tw5.com/tiddlers/Docs.tid
index 5308562db..364903ffe 100644
--- a/tw5.com/tiddlers/Docs.tid
+++ b/tw5.com/tiddlers/Docs.tid
@@ -3,16 +3,23 @@ tags: docs
 
 ! Guides
 
+How to get things done with TiddlyWiki:
+
 * [[Getting started with TiddlyWiki in the browser]]
 * [[Getting started with TiddlyWiki under node.js]]
 * [[Getting involved in TiddlyWiki development]]
 
 ! Concepts
 
+The core concepts underlying TiddlyWiki are:
+
 * [[Tiddlers]]
 * [[Wiki]]
 * TiddlyWiki
 * WikiText
+
+The machinery tying those concepts together includes:
+
 * TiddlerFilters
 * TiddlerFields
 * ContentType
@@ -21,6 +28,8 @@ tags: docs
 
 ! Wiki Text Rules
 
+These are the individual rules that make up WikiText:
+
 * ClassBlockWikiText
 * CodeBlockWikiText
 * CodeRunWikiText
@@ -40,6 +49,8 @@ tags: docs
 
 ! Macros
 
+Macros give WikiText dynamic functionality:
+
 * ViewMacro
 * EditMacro
 * StoryMacro
@@ -61,6 +72,8 @@ tags: docs
 
 ! Commands
 
+When run under node.js, TiddlyWiki supports a [[command line interface|Getting started with TiddlyWiki under node.js]] with the following built-in commands:
+
 * DumpCommand
 * LoadCommand
 * SaveTiddlerCommand
@@ -69,8 +82,12 @@ tags: docs
 * VersionCommand
 * WikiTestCommand
 
-! Internal Mechanisms
+! Internal Objects and Mechanisms
 
+Internally, TiddlyWiki is built on a number of key objects and mechanisms:
+
+* TiddlerObject
+* WikiObject
 * BootMechanism
 * PluginMechanism
 * ParsingMechanism
@@ -85,35 +102,34 @@ tags: docs
 * CommandMechanism
 * ConfigMechanism
 
-! Data Model
-
-* TiddlerObject
-* WikiObject
-
 ! Plugin Module Types
 
-* CommandPlugins
-* ConfigPlugins
-* EditorPlugins
-* GlobalPlugins
-* LibraryPlugins
-* MacroPlugins
-* ModulePlugins
-* ParserPlugins
-* StartupPlugins
-* StoryViewPlugins
-* TiddlerDeserializerPlugins
-* TiddlerFieldPlugins
-* TiddlerMethodPlugins
-* TiddlerSerializerPlugins
-* TreeNodePlugins
-* TreeUtilsPlugins
-* UtilsPlugins
-* WikiMethodPlugins
-* WikiTextRulePlugins
+TiddlyWiki is built on a [[tiny microkernel|BootMechanism]] with all functionality provided as various types of plugin module:
+
+* CommandModules
+* ConfigModules
+* EditorModules
+* GlobalModules
+* LibraryModules
+* MacroModules
+* ModuleModules
+* ParserModules
+* StartupModules
+* StoryViewModules
+* TiddlerDeserializerModules
+* TiddlerFieldModules
+* TiddlerMethodModules
+* TiddlerSerializerModules
+* TreeNodeModules
+* TreeUtilsModules
+* UtilsModules
+* WikiMethodModules
+* WikiTextRuleModules
 
 ! Tree Nodes
 
+The ParsingMechanism and the RenderingMechanism use a simple tree structure to represent both parsed WikiText and the HTML DOM structure of rendered content.
+
 * TreeNode
 * ElementNode
 * EntityNode
@@ -123,6 +139,8 @@ tags: docs
 
 ! Other Parsers
 
+TiddlyWiki processes other [[ContentTypes|ContentType]] than WikiText using these parsers:
+
 * OldWikiTextParser
 * JsonParser
 * ImageParser
@@ -132,14 +150,18 @@ tags: docs
 
 ! Deserializers
 
+Deserializers are modules that read tiddlers from different text formats:
+
 * RecipeFiles
 * TiddlerFiles
+* TiddlyWikiFiles
 
 ! Serializers
 
-* TiddlyWikiFiles
+Serializers are modules that convert tiddlers to different text formats:
 
 ! Miscellaneous
 
+* [[History]]
 * [[Acknowledgements]]
 
diff --git a/tw5.com/tiddlers/concepts/Tiddlers.tid b/tw5.com/tiddlers/concepts/Tiddlers.tid
index 34d29dac0..caab70560 100644
--- a/tw5.com/tiddlers/concepts/Tiddlers.tid
+++ b/tw5.com/tiddlers/concepts/Tiddlers.tid
@@ -1,8 +1,6 @@
 title: Tiddlers
 tags: docs concepts
 
-!! Tiddlers
-
 Tiddlers are an immutable dictionary of name:value pairs called fields.
 
 The only field that is required is the {{{title}}} field, but useful tiddlers also have a {{{text}}} field, and some or all of the standard fields {{{modified}}}, {{{modifier}}}, {{{created}}}, {{{creator}}}, {{{tags}}} and {{{type}}}.
diff --git a/tw5.com/tiddlers/concepts/Wiki.tid b/tw5.com/tiddlers/concepts/Wiki.tid
index 00b740079..4cd81c910 100644
--- a/tw5.com/tiddlers/concepts/Wiki.tid
+++ b/tw5.com/tiddlers/concepts/Wiki.tid
@@ -1,8 +1,6 @@
 title: Wiki
 tags: docs concepts
 
-!! ~WikiStore
-
 Groups of uniquely titled tiddlers are contained in WikiStore objects.
 
 The WikiStore also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.