TiddlyWiki5/readme.md

Welcome to TiddlyWiki5

HelloThere

Welcome to TiddlyWiki5, a reboot of 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.

TiddlyWiki is based on the idea of making information more useful by modelling it in the smallest meaningful semantic units, referred to as "tiddlers". Structure comes from links, tags, and stories (sequences of tiddlers). Tiddlers use a wikitext notation that concisely represents a wide range of text formatting and hypertext features.

TiddlyWiki has earned an enduring role as a tool that people love using for its rich, interactive interface to manipulate complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors. Because people can use it without needing any complicated server infrastructure, and because it is open source, it has bought unprecedented freedom to people to keep their precious information under their own control. TiddlyWiki was originally created by JeremyRuston and is now a thriving open source project with a busy Community of independent developers.

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

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. 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
--dumpstore	Dump the TiddlyWiki store in JSON format
--dumprecipe	Dump the current recipe in JSON format
--verbose	verbose 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
This example cooks a TiddlyWiki from a recipe:
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

The function to render it to text/html might look like this:

function() {
	return "<p>Hello World</p>";
}

The function can also include calls to the store to incorporate the values of other tiddlers. Consider this tiddler, called HelloThere:

Hello <<tiddler Who>>

And this one called Who:

World

The function to generate HelloThere in text/html might be:

function() {
	return ["<p>","Hello ", getTiddlerText("Who","text/html"), "</p>"].join(""); 
}

Now, the return value of this function can be cached until a tiddler in the dependency chain changes. The function itself can be cached until the tiddler itself changes, or a macro that it uses changes.

The dependency chain is calculated when a tiddler is parsed. Every tiddler that is directly referenced is accumulated (until the point at which it is concluded that it is simpler to mark the tiddler as being dependent on any other tiddler changing).

Evaluated macro parameters are parsed and can be checked for safeness, and then included in the compiled code. For example,

Hello <<echo {{2+2}}>>

Compiles to:

function() {
	return ["Hello ",(function(){
		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
param1: Parameter value
param2: value
"unnamed parameter"
param4: ((
A multiline parameter that can go on for as long as it likes
and contain linebreaks.
))
>>

This readme file was automatically generated by TiddlyWiki5