Docs update

tw5.com/tiddlers/Docs.tid

@@ -9,11 +9,11 @@ tags: docs
 
 ! Concepts
 
-* [[Tiddler]]
+* [[Tiddlers]]
 * [[Wiki]]
 * TiddlyWiki
 * WikiText
-* [[Filters]]
+* TiddlerFilters
 * TiddlerFields
 * ShadowTiddlers
 * TiddlerModules

tw5.com/tiddlers/ParsingMechanism.tid

@@ -0,0 +1,51 @@
+title: ParsingMechanism
+tags: docs mechanism
+
+TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
+
+* Rendering a tiddler to other formats (e.g. converting wikitext to HTML)
+* Detecting outgoing links from a tiddler, and from them...
+* ...computing incoming links to a tiddler
+* Detecting tiddlers that are orphans with no incoming links
+* Detecting tiddlers that are referred to but missing
+
+The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.
+
+TiddlyWiki5 uses multiple parsers:
+
+* Wikitext ({{{text/x-tiddlywiki}}}) in `js/WikiTextParser.js`
+* JavaScript ({{{text/javascript}}}) in `js/JavaScriptParser.js`
+* Images ({{{image/png}}} and {{{image/jpg}}}) in `js/ImageParser.js`
+* JSON ({{{application/json}}}) in `js/JSONParser.js`
+Additional parsers are planned:
+* CSS ({{{text/css}}})
+* Recipe ({{{text/x-tiddlywiki-recipe}}})
+
+One global instance of each parser is instantiated in `js/App.js` and registered with the main WikiStore object.
+
+The parsers are all used the same way:
+
+$$$.js
+var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
+$$$
+
+The parse tree object exposes the following fields:
+
+$$$.js
+var renderer = parseTree.compile(type); // Compiles the parse tree into a renderer for the specified MIME type
+console.log(parseTree.toString(type)); // Returns a readable string representation of the parse tree (either `text/html` or `text/plain`)
+var dependencies = parseTree.dependencies; // Gets the dependencies of the parse tree (see below)
+$$$
+
+The dependencies are returned as an object like this:
+
+{{{
+{
+	tiddlers: {"tiddlertitle1": true, "tiddlertitle2": false},
+	dependentAll: false
+}
+}}}
+
+The `tiddlers` field is a hashmap of the title of each tiddler that is linked or included in the current one. The value is `true` if the tiddler is a //'fat'// dependency (ie the text is included in some way) or `false` if the tiddler is a //`skinny`// dependency.
+
+The `dependentAll` field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the `<<list>>` macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes.

tw5.com/tiddlers/ReadMe.tid

@@ -1,24 +1,20 @@
 title: ReadMe
 tags: introduction
 
-!Welcome to TiddlyWiki5
+! Welcome to TiddlyWiki5
 
 <<tiddler HelloThere>>
 
-!Usage
+! Usage
 
 <<tiddler CommandLineInterface>>
 
-!Architecture
+! Architecture
 
 <<tiddler TiddlyWikiArchitecture>>
 
-!Plugin Mechanism
+! Plugin Mechanism
 
 <<tiddler PluginMechanism>>
 
-!Planned WikiText Features
-
-<<tiddler NewWikiTextFeatures>>
-
 //This `readme` file was automatically generated by TiddlyWiki5//

tw5.com/tiddlers/RenderingMechanism.tid

@@ -0,0 +1,38 @@
+title: RenderingMechanism
+tags: docs mechanism
+
+The `parseTree.compile(type)` method returns a renderer object that contains a JavaScript function that generates the new representation of the original parsed text.
+
+The renderer is invoked as follows:
+
+$$$.js
+var renderer = parseTree.compile("text/html");
+var html = renderer.render(tiddler,store);
+$$$
+
+The `tiddler` parameter to the `render` method identifies the tiddler that is acting as the context for this rendering -- for example, it provides the fields displayed by the `<<view>>` macro. The `store` parameter is used to resolve any references to other tiddlers.
+
+!! Rerendering
+
+When rendering to the HTML/SVG DOM in the browser, TiddlyWiki5 also allows a previous rendering to be selectively updated in response to changes in dependent tiddlers. At the moment, only the WikiTextRenderer supports rerendering.
+
+The rerender method on the renderer is called as follows:
+
+{{{
+var node = document.getElementById("myNode");
+var renderer = parseTree.compile("text/html");
+myNode.innerHTML = renderer.render(tiddler,store);
+// And then, later:
+renderer.rerender(node,changes,tiddler,store,renderStep);
+}}}
+
+The parameters to `rerender()` are:
+
+|!Name |!Description |
+|node |A reference to the DOM node containing the rendering to be rerendered |
+|changes |A hashmap of `{title: "created|modified|deleted"}` indicating which tiddlers have changed since the original rendering |
+|tiddler |The tiddler providing the rendering context |
+|store |The store to use for resolving references to other tiddlers |
+|renderStep |See below |
+
+Currently, the only macro that supports rerendering is the `<<story>>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<<story>>` macro goes to the trouble of having a `rerender()` method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.

tw5.com/tiddlers/Tiddlers.tid

@@ -0,0 +1,12 @@
+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}}}.
+
+Hardcoded in the system is the knowledge that the `tags` field is a string array, and that the `modified` and `created` fields are JavaScript `Date` objects. All other fields are strings.
+
+The {{{type}}} field identifies the representation of the tiddler text with a MIME type.

tw5.com/tiddlers/TiddlyWiki.tid

@@ -1,7 +1,7 @@
 title: TiddlyWiki
 modifier: JeremyRuston
 modified: 20120211110622
-tag: introduction
+tag: docs concepts
 
 TiddlyWiki is a rich, interactive interface for manipulating complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors.
 

tw5.com/tiddlers/TiddlyWikiArchitecture.tid

@@ -1,6 +1,6 @@
 title: TiddlyWikiArchitecture
 modifier: JeremyRuston
-tags: internals
+tags: docs internals
 
 !! Overview
 
@@ -25,115 +25,4 @@ store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddle
 
 The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of TiddlyWiki5 in a way that should provide a good basis for exploring the code directly.
 
-!! 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}}}.
-
-Hardcoded in the system is the knowledge that the `tags` field is a string array, and that the `modified` and `created` fields are JavaScript `Date` objects. All other fields are strings.
-
-The {{{type}}} field identifies the representation of the tiddler text with a MIME type.
-
-!! ~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.
-
-Each WikiStore is connected to another shadow store that is used to provide default content. Under usual circumstances, when an attempt is made to retrieve a tiddler that doesn't exist in the store, the search continues into its shadow store (and so on, if the shadow store itself has a shadow store).
-
-!! ~WikiStore Events
-
-Clients can register event handlers with the WikiStore object. Event handlers can be registered to be triggered for modifications to any tiddler in the store, or with a filter to only be invoked when a particular tiddler or set of tiddlers changes.
-
-Whenever a change is made to a tiddler, the wikistore registers a `nexttick` handler (if it hasn't already done so). The `nexttick` handler looks back at all the tiddler changes, and dispatches any matching event handlers. 
-
-!! Parsing and Rendering
-
-TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
-
-* Rendering a tiddler to other formats (e.g. converting wikitext to HTML)
-* Detecting outgoing links from a tiddler, and from them...
-* ...computing incoming links to a tiddler
-* Detecting tiddlers that are orphans with no incoming links
-* Detecting tiddlers that are referred to but missing
-
-The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.
-
-TiddlyWiki5 uses multiple parsers:
-
-* Wikitext ({{{text/x-tiddlywiki}}}) in `js/WikiTextParser.js`
-* JavaScript ({{{text/javascript}}}) in `js/JavaScriptParser.js`
-* Images ({{{image/png}}} and {{{image/jpg}}}) in `js/ImageParser.js`
-* JSON ({{{application/json}}}) in `js/JSONParser.js`
-Additional parsers are planned:
-* CSS ({{{text/css}}})
-* Recipe ({{{text/x-tiddlywiki-recipe}}})
-
-One global instance of each parser is instantiated in `js/App.js` and registered with the main WikiStore object.
-
-The parsers are all used the same way:
-
-$$$.js
-var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
-$$$
-
-The parse tree object exposes the following fields:
-
-$$$.js
-var renderer = parseTree.compile(type); // Compiles the parse tree into a renderer for the specified MIME type
-console.log(parseTree.toString(type)); // Returns a readable string representation of the parse tree (either `text/html` or `text/plain`)
-var dependencies = parseTree.dependencies; // Gets the dependencies of the parse tree (see below)
-$$$
-
-The dependencies are returned as an object like this:
-
-{{{
-{
-	tiddlers: {"tiddlertitle1": true, "tiddlertitle2": false},
-	dependentAll: false
-}
-}}}
-
-The `tiddlers` field is a hashmap of the title of each tiddler that is linked or included in the current one. The value is `true` if the tiddler is a //'fat'// dependency (ie the text is included in some way) or `false` if the tiddler is a //`skinny`// dependency.
-
-The `dependentAll` field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the `<<list>>` macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes.
-
-!! Rendering
-
-The `parseTree.compile(type)` method returns a renderer object that contains a JavaScript function that generates the new representation of the original parsed text.
-
-The renderer is invoked as follows:
-
-$$$.js
-var renderer = parseTree.compile("text/html");
-var html = renderer.render(tiddler,store);
-$$$
-
-The `tiddler` parameter to the `render` method identifies the tiddler that is acting as the context for this rendering -- for example, it provides the fields displayed by the `<<view>>` macro. The `store` parameter is used to resolve any references to other tiddlers.
-
-!! Rerendering
-
-When rendering to the HTML/SVG DOM in the browser, TiddlyWiki5 also allows a previous rendering to be selectively updated in response to changes in dependent tiddlers. At the moment, only the WikiTextRenderer supports rerendering.
-
-The rerender method on the renderer is called as follows:
-
-{{{
-var node = document.getElementById("myNode");
-var renderer = parseTree.compile("text/html");
-myNode.innerHTML = renderer.render(tiddler,store);
-// And then, later:
-renderer.rerender(node,changes,tiddler,store,renderStep);
-}}}
-
-The parameters to `rerender()` are:
-
-|!Name |!Description |
-|node |A reference to the DOM node containing the rendering to be rerendered |
-|changes |A hashmap of `{title: "created|modified|deleted"}` indicating which tiddlers have changed since the original rendering |
-|tiddler |The tiddler providing the rendering context |
-|store |The store to use for resolving references to other tiddlers |
-|renderStep |See below |
-
-Currently, the only macro that supports rerendering is the `<<story>>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<<story>>` macro goes to the trouble of having a `rerender()` method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.

tw5.com/tiddlers/Wiki.tid

@@ -0,0 +1,16 @@
+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.
+
+Each WikiStore is connected to another shadow store that is used to provide default content. Under usual circumstances, when an attempt is made to retrieve a tiddler that doesn't exist in the store, the search continues into its shadow store (and so on, if the shadow store itself has a shadow store).
+
+!! ~WikiStore Events
+
+Clients can register event handlers with the WikiStore object. Event handlers can be registered to be triggered for modifications to any tiddler in the store, or with a filter to only be invoked when a particular tiddler or set of tiddlers changes.
+
+Whenever a change is made to a tiddler, the wikistore registers a `nexttick` handler (if it hasn't already done so). The `nexttick` handler looks back at all the tiddler changes, and dispatches any matching event handlers.