From be44fb4ad2a43a70a6f167435e5e2d3369083f69 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Sat, 11 Feb 2012 17:11:23 +0000 Subject: [PATCH] Docs Updates --- readme.md | 25 +++++- tiddlywiki5/styles.css | 8 +- tiddlywiki5/tiddlers/HelloThere.tid | 4 + tiddlywiki5/tiddlers/MacroInternals.tid | 2 +- tiddlywiki5/tiddlers/TiddlerFiles.tid | 16 ++-- .../tiddlers/TiddlyWikiArchitecture.tid | 88 +++++++++++++++---- 6 files changed, 114 insertions(+), 29 deletions(-) diff --git a/readme.md b/readme.md index 680fba8dc..7ed9e815a 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -

Welcome to TiddlyWiki5

Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file or as a powerful node.js application.

Some useful tiddlers for feature testing:
  • ImageTests showing different ways of embedding images
  • SampleData showing how JSON tiddlers are handled
  • VideoTests showing how different online video formats can be embedded

Technical documentation includes:

TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can get involved in the development on GitHub and the discussions on Google Groups:

https://github.com/Jermolene/TiddlyWiki5
http://groups.google.com/group/TiddlyWikiDev

Bug: this link doesn't work:


Usage

TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.

Usage:
+

Welcome to TiddlyWiki5

ChrisHelloThere
fiertest1

Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file or as a powerful node.js application.

Some useful tiddlers for feature testing:
  • ClockTiddler showing automatic refreshing of tiddlers
  • ImageTests showing different ways of embedding images
  • SampleData showing how JSON tiddlers are handled
  • VideoTests showing how different online video formats can be embedded

Technical documentation includes:

TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can get involved in the development on GitHub and the discussions on Google Groups:

https://github.com/Jermolene/TiddlyWiki5
http://groups.google.com/group/TiddlyWikiDev

Bug: this link doesn't work:


Usage

TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.

Usage:
node tiddlywiki.js <options>
The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a recipe file and all the subrecipes and tiddlers that it references, and then resumes with the next command line option in sequence. The following options are available:
--recipe <filepath>Loads a specfied .recipe file
--load <filepath>Load additional tiddlers from 2.x.x TiddlyWiki files (.html), .tiddler, .tid, .json or other files
--savewiki <dirpath>Saves all the loaded tiddlers as a single file TiddlyWiki called index.html and an RSS feed called index.xml in a new directory of the specified name
--savetiddler <title> <filename> [<type>]Save an individual tiddler as a specified MIME type, defaults to text/html
--savetiddlers <outdir>Saves all the loaded tiddlers as .tid files in the specified directory
--servewiki <port>Serve the cooked TiddlyWiki over HTTP at /
--servetiddlers <port>Serve individual tiddlers over HTTP at /tiddlertitle
--wikitest <dir>Run wikification tests against the tiddlers in the given directory
--dumpstoreDump the TiddlyWiki store in JSON format
--dumprecipeDump the current recipe in JSON format
--verboseverbose output, useful for debugging

Examples

This example loads the tiddlers from a TiddlyWiki HTML file and makes them available over HTTP:
node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000 @@ -6,7 +6,26 @@ node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000 node tiddlywiki.js --recipe tiddlywiki.com/index.recipe --savewiki tmp/
This example ginsus a TiddlyWiki into its constituent tiddlers:
node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers -

Notes

--servewiki and --servertiddlers are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.

--wikitest looks for *.tid files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the *.html and *.txt files in the same directory.

Testing

test.sh contains a simple test script that cooks the main tiddlywiki.com recipe and compares it with the results of the old build process (ie, running cook.rb and then opening the file in a browser and performing a 'save changes' operation). It also runs a series of wikifications tests that work off the data in test/wikitests/.

Architecture

Overview


The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type.

The most important transformations are from text/x-tiddlywiki wikitext into text/html or text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of JavaScript, and processing CSS.

Tiddlers


Tiddlers are a 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


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)
  • JavaScript (text/javascript)
  • CSS (text/css)
  • JSON (application/json)
  • Recipe (text/x-tiddlywiki-recipe)

Compiling and Rendering


When the text of a tiddler is requested in a different format than its native type, TiddlyWiki5 compiles a JavaScript function that generates the new format from the text of the tiddler.

So, a simple tiddler in application/x-tiddlywiki format might read:
Hello World
+
 Notes
--servewiki and --servertiddlers are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine.

--wikitest looks for *.tid files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the *.html and *.txt files in the same directory.

Testing

test.sh contains a simple test script that cooks the main tiddlywiki.com recipe and compares it with the results of the old build process (ie, running cook.rb and then opening the file in a browser and performing a 'save changes' operation). It also runs a series of wikifications tests that work off the data in test/wikitests/.

Architecture

Overview


The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.

The most important transformations are from text/x-tiddlywiki wikitext into text/html or text/plain but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of JavaScript, and processing CSS.

The key feature of wikitext is the ability to include one tiddler within another (usually referred to as transclusion). For example, one could have a tiddler called Disclaimer that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call <<tiddler Disclaimer>>. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the TiddlyWiki5 design.

It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building TiddlyWiki's user interface itself. Consider, for example, the StoryMacro in its simplest form:
<<story story:MyStoryTiddler>>
+
The story macro looks for a list of tiddler titles in the tiddler MyStoryTiddler, and displays them in sequence. The subtle part is that subsequently, if MyStoryTiddler changes, the <<story>> macro is selectively re-rendered. So, to navigate to a new tiddler, code merely needs to add the name of the tiddler and a line break to the top of MyStoryTiddler:
var storyTiddler = store.getTiddler("MyStoryTiddler");
+store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text}));
+
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 Compiling

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. In some cases the constructors require special parameters or options (eg, the JavaScript parser requires the PEG.JS JavaScript parser text).

The parsers are all used the same way:
var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
+
The parse tree object exposes the following fields:
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:
{
+	link: {"tiddlertitle1": 2, "tiddlertitle2": 3},
+	include: {"tiddlertitle3": 5},
+	dependentAll: false
+}
+
The link and include fields are hashmaps of the title of each tiddler that is linked or included in the current one. For the tiddler to be subsequently rendered correctly, the linked tiddlers must be present, at least in skinny form, and the included tiddlers must be fully loaded.

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:
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:
NameDescription
nodeA reference to the DOM node containing the rendering to be rerendered
changesA hashmap of {title: "created|modified|deleted"} indicating which tiddlers have changed since the original rendering
tiddlerThe tiddler providing the rendering context
storeThe store to use for resolving references to other tiddlers
renderStepSee 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.

The remaining text is from an earlier draft, and is in the process of being updated

When the text of a tiddler is requested in a different format than its native type, TiddlyWiki5 compiles a JavaScript function that generates the new format from the text of the tiddler.

So, a simple tiddler in application/x-tiddlywiki format might read:
Hello World
The function to render it to text/html might look like this:
function() {
 	return "<p>Hello World</p>";
 }
@@ -21,7 +40,7 @@ node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers
 		return 2+2;
 	})().toString()].join("");
 }
-

The compilation process has several steps:
  • First, the parse tree is used to generate a JavaScript tree
  • The JavaScript tree is scanned to determine the tiddlers on which this one depends
  • Finally, executable JavaScript text is generated by walking the JavaScript tree

Planned WikiText Features

It is proposed to extend the existing TiddlyWiki wikitext syntax with the following extensions

  1. Addition of **bold** character formatting
  2. Addition of `backtick for code` character formatting
  3. Addition of WikiCreole-style forced line break, e.g. force\\linebreak
  4. Addition of WikiCreole-style headings, e.g. ==Heading
  5. Addition of WikiCreole-style headings in tables, e.g. |=|=table|=header|
  6. Addition of white-listed HTML tags intermixed with wikitext
  7. Addition of WikiCreole-style pretty links, e.g. [[description -> link]]
  8. Addition of multiline macros, e.g.
<<myMacro
+

The compilation process has several steps:
  • First, the parse tree is used to generate a JavaScript tree
  • The JavaScript tree is scanned to determine the tiddlers on which this one depends
  • Finally, executable JavaScript text is generated by walking the JavaScript tree

Planned WikiText Features

It is proposed to extend the existing TiddlyWiki wikitext syntax with the following extensions

  1. Addition of **bold** character formatting
  2. Addition of `backtick for code` character formatting
  3. Addition of WikiCreole-style forced line break, e.g. force\\linebreak
  4. Addition of WikiCreole-style headings, e.g. ==Heading
  5. Addition of WikiCreole-style headings in tables, e.g. |=|=table|=header|
  6. Addition of white-listed HTML tags intermixed with wikitext
  7. Addition of WikiCreole-style pretty links, e.g. [[description -> link]]
  8. Addition of multiline macros, e.g.
<<myMacro
 param1: Parameter value
 param2: value
 "unnamed parameter"
diff --git a/tiddlywiki5/styles.css b/tiddlywiki5/styles.css
index a0bcc2572..1a5fdd27e 100644
--- a/tiddlywiki5/styles.css
+++ b/tiddlywiki5/styles.css
@@ -6,10 +6,14 @@ body {
 
 body {
     font-size: 15px;
-    line-height: 22px;
-    max-width: 644px;
+    line-height: 20px;
+    max-width: 944px;
     margin: auto;
 }
+th, td {
+    background: #f6f6f6;
+    padding: 3px 3px 3px 3px;
+}
 code, pre {
     font-size: 13px;
     line-height: 18px;
diff --git a/tiddlywiki5/tiddlers/HelloThere.tid b/tiddlywiki5/tiddlers/HelloThere.tid
index 88d67728f..4b4f17905 100644
--- a/tiddlywiki5/tiddlers/HelloThere.tid
+++ b/tiddlywiki5/tiddlers/HelloThere.tid
@@ -1,9 +1,13 @@
 title: HelloThere
 modifier: JeremyRuston
 
+ChrisHelloThere
+[[fiertest1]]
+
 Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file or as a powerful [[node.js application|What is node.js?]].
 
 Some useful tiddlers for feature testing:
+* ClockTiddler showing automatic refreshing of tiddlers
 * ImageTests showing different ways of embedding images
 * SampleData showing how JSON tiddlers are handled
 * VideoTests showing how different online video formats can be embedded
diff --git a/tiddlywiki5/tiddlers/MacroInternals.tid b/tiddlywiki5/tiddlers/MacroInternals.tid
index 8b90ccb3a..8350279a6 100644
--- a/tiddlywiki5/tiddlers/MacroInternals.tid
+++ b/tiddlywiki5/tiddlers/MacroInternals.tid
@@ -2,7 +2,7 @@ title: MacroInternals
 
 ! Macro Fields
 
-Macros are conventional JavaScript modules that export a single variable called `macro` that contains:
+Macros are implemented as conventional JavaScript modules that export a single variable called `macro` that contains these fields:
 
 |!Field Name |!Description |
 |`name` |The name of the macro |
diff --git a/tiddlywiki5/tiddlers/TiddlerFiles.tid b/tiddlywiki5/tiddlers/TiddlerFiles.tid
index ba1d8a478..cc2a6eefe 100644
--- a/tiddlywiki5/tiddlers/TiddlerFiles.tid
+++ b/tiddlywiki5/tiddlers/TiddlerFiles.tid
@@ -2,36 +2,36 @@ title: TiddlerFiles
 modifier: JeremyRuston
 
 Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary `.meta` file formatted as a sequence of name:value pairs:
-`
+{{{
 title: TheTitle
 modifier: someone
-`
+}}}
 !! ~TiddlyWeb-style .tid files
 
 These files consist of a sequence of lines containing name:value pairs, a blank line and then the text of the tiddler. For example:
-`
+{{{
 title: MyTiddler
 modifier: Jeremy
 
 This is the text of my tiddler.
-`
+}}}
 //The MIME type `application/x-tiddler` is used internally for these files//
 !! TiddlyWiki `
` .tiddler files
 
 Modern `*.tiddler` files look like this:
-`
+{{{
 

 
Note that there is an embedded 
 tag, and line feeds are not escaped.
 	
 And, weirdly, there is no HTML encoding of the body.

 

-`
+}}}
 These `*.tiddler` files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way.
 
 Older `*.tiddler` files more closely matched the store format used by TiddlyWiki at the time:
-`
+{{{
 
This is an old-school .tiddler file, without an embedded <pre> tag.\nNote how the body is "HTML encoded" and new lines are escaped to \\n

-`
+}}}
 //The MIME type `application/x-tiddler-html-div` is used internally for these files//
 !! ~TiddlyWeb-style JSON files
 
diff --git a/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid b/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid
index 5cd69d978..be601699b 100644
--- a/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid
+++ b/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid
@@ -3,53 +3,111 @@ modifier: JeremyRuston
 
 !! Overview
 
-The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type.
+The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.
 
 The most important transformations are from `text/x-tiddlywiki` wikitext into `text/html` or `text/plain` but the engine is used throughout the system for other transformations, such as converting images for display in HTML, sanitising fragments of JavaScript, and processing CSS.
 
-!! Tiddlers
+The key feature of wikitext is the ability to include one tiddler within another (usually referred to as //transclusion//). For example, one could have a tiddler called //Disclaimer// that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call `<>`. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the TiddlyWiki5 design.
 
-Tiddlers are a dictionary of name:value pairs called fields.
+It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building TiddlyWiki's user interface itself. Consider, for example, the StoryMacro in its simplest form:
+{{{
+<>
+}}}
+The story macro looks for a list of tiddler titles in the tiddler `MyStoryTiddler`, and displays them in sequence. The subtle part is that subsequently, if `MyStoryTiddler` changes, the `<>` macro is selectively re-rendered. So, to navigate to a new tiddler, code merely needs to add the name of the tiddler and a line break to the top of `MyStoryTiddler`:
+{{{
+var storyTiddler = store.getTiddler("MyStoryTiddler");
+store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text}));
+}}}
+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
-
+!! Parsing and Compiling
 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}}})
-* JavaScript ({{{text/javascript}}})
+* 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}}})
-* JSON ({{{application/json}}})
 * Recipe ({{{text/x-tiddlywiki-recipe}}})
+One global instance of each parser is instantiated in `js/App.js` and registered with the main WikiStore object. In some cases the constructors require special parameters or options (eg, the JavaScript parser requires the [[PEG.JS]] JavaScript parser text).
 
-!! Compiling and Rendering
+The parsers are all used the same way:
+{{{
+var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
+}}}
+The parse tree object exposes the following fields:
+{{{
+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:
+{{{
+{
+	link: {"tiddlertitle1": 2, "tiddlertitle2": 3},
+	include: {"tiddlertitle3": 5},
+	dependentAll: false
+}
+}}}
+The `link` and `include` fields are hashmaps of the title of each tiddler that is linked or included in the current one. For the tiddler to be subsequently rendered correctly, the linked tiddlers must be present, at least in skinny form, and the included tiddlers must be fully loaded.
+
+The `dependentAll` field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the `<>` 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:
+{{{
+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 `<>` 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 `<>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<>` 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.
+
+----
+//The remaining text is from an earlier draft, and is in the process of being updated//
 
 When the text of a tiddler is requested in a different format than its native type, TiddlyWiki5 compiles a JavaScript function that generates the new format from the text of the tiddler.