diff --git a/readme.md b/readme.md index 2e2fca304..6494ea617 100644 --- a/readme.md +++ b/readme.md @@ -1,5 +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 in the browser or as a powerful node.js application.

TiddlyWiki5 is currently at version 5.0.0.a3 and is under active development, which is to say that it is useful but incomplete. You can try out the online prototype at http://alpha.tiddlywiki.com/, try out the command line incarnation, get involved in the development on GitHub or join the discussions on the TiddlyWikiDev Google Group. -

Usage

Architecture

Overview

The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated ContentType, the engine can produce a rendering of the tiddler in a new ContentType. 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");
+
 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 in the browser or as a powerful node.js application.
TiddlyWiki offers a radically new way of managing your data compared to traditional documents. The fundamental idea is that information is more useful and reusable if we cut up into the smallest semantically meaningful chunks. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.
TiddlyWiki5 is at an incomplete early alpha stage, and is not yet ready for general use. You can:
 Usage
 Architecture
 Overview
The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated ContentType, the engine can produce a rendering of the tiddler in a new ContentType. 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.
 Plugin Mechanism
Introduction
TiddlyWiki5 is based on a 500 line boot kernel that runs on node.js or in the browser, and everything else is plugins.
The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers as plugins and execute them (a barebones tiddler class, a barebones wiki store class, some utilities etc.). Plugin modules are written like node.js modules; you can use require() to invoke sub components and to control load order.
There are several different types of plugins: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are plugins, too: there's a plugin 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 plugins have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugins.
Plugins and Modules
In TiddlyWiki5, a plugin is a bundle of related tiddlers that are distributed together as a single unit. Plugins can include tiddlers which are JavaScript modules. 
The file 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 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)
  •  Code for the browser to load tiddlers from the HTML DOM
  •  Code for the server to load tiddlers from the file system
Each module is an ordinary node.js-style module, using the require() function to access other modules and the exports global to return JavaScript values. The boot kernel smooths over the differences between node.js and the browser, allowing the same plugin modules to execute in both environments.
In the browser, core/boot.js is packed into a template HTML file that contains the following elements in order:
  •  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
  •  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
tiddlywiki.plugin files
 
This readme file was automatically generated by TiddlyWiki5
diff --git a/tw5.com/tiddlers/AllTiddlers.tid b/tw5.com/tiddlers/AllTiddlers.tid
new file mode 100644
index 000000000..8cf670f71
--- /dev/null
+++ b/tw5.com/tiddlers/AllTiddlers.tid
@@ -0,0 +1,6 @@
+title: AllTiddlers
+tags: navigation
+
+Current tiddlers:
+
+<>
diff --git a/tw5.com/tiddlers/HelloThere.tid b/tw5.com/tiddlers/HelloThere.tid
index 6e8c7c0e0..97842a8d9 100644
--- a/tw5.com/tiddlers/HelloThere.tid
+++ b/tw5.com/tiddlers/HelloThere.tid
@@ -3,6 +3,14 @@ modifier: JeremyRuston
 tags: introduction greetings
 type: text/x-tiddlywiki
 
-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 in the browser or as a powerful [[node.js application|What is node.js?]].
+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 in the browser or as a powerful [[node.js application|node.js]].
+
+TiddlyWiki offers a radically new way of managing your data compared to traditional documents. The fundamental idea is that information is more useful and reusable if we cut up into the [[smallest semantically meaningful chunks|Tiddlers]]. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.
+
+TiddlyWiki5 is at an incomplete early alpha stage, and is not yet ready for general use. You can:
+
+* Explore its features online at http://alpha.tiddlywiki.com/
+* Get involved in the [[development on GitHub|https://github.com/Jermolene/TiddlyWiki5]]
+* Join the discussions on [[the TiddlyWikiDev Google Group|http://groups.google.com/group/TiddlyWikiDev]]
+* Follow [[@TiddlyWiki on Twitter|http://twitter.com/#!/TiddlyWiki]] for the latest news
 
-TiddlyWiki5 is currently at version <> and is under active development, which is to say that it is useful but incomplete. You can try out the online prototype at http://alpha.tiddlywiki.com/, [[try out the command line incarnation|TryingOutTiddlyWiki]], get involved in the [[development on GitHub|https://github.com/Jermolene/TiddlyWiki5]] or join the discussions on [[the TiddlyWikiDev Google Group|http://groups.google.com/group/TiddlyWikiDev]].
diff --git a/tw5.com/tiddlers/Improvements.tid b/tw5.com/tiddlers/Improvements.tid
index a249a9941..d8d81de4e 100644
--- a/tw5.com/tiddlers/Improvements.tid
+++ b/tw5.com/tiddlers/Improvements.tid
@@ -1,12 +1,16 @@
 title: Improvements
+modifier: JeremyRuston
 tags: docs introduction
 
-Some of the features that have been improved in TiddlyWiki5:
+TiddlyWiki5 is a complete rewrite of the original TiddlyWiki, incorporating many of the improvements that I've wanted to make over the years. It is now based on an elegant [[microkernel architecture|PluginMechanism]], that allows infinite customisation by replacing and augmenting the core modules.
+
+For end users, the important improvements include:
 
-* TiddlyWiki can now be run under [[node.js|http://nodejs.org]] as well as in the browser
-* TiddlyWiki is structured as a 600-line boot kernel, with everything else implemented as plugins
 * Improved WikiText, with much better generation of HTML, including proper `
` tags
+* TiddlyWiki can now be run under [[node.js]] as well as in the browser, allowing it to be used as a personal web server
 * Tiddlers containing images are now supported just like WikiText tiddlers, including integrated editing of bitmap and SVG images
 * Uses standard Twitter Bootstrap CSS (thus enabling the use of Boostrap themes such as http://bootswatch.com)
 * Syntax highlighting for JavaScript and JSON tiddlers
 * TiddlyWiki5 can directly build both itself and previous (2.6.x) versions of TiddlyWiki from their constituent separate files, without needing external tools
+
+The internal changes mean that TiddlyWiki5 is not compatible with previous versions, using different plugins, themes and so on. The changes to the WikiText have been carefully developed to try to maximise backwards compatibility but content prepared for previous versions of TiddlyWiki will need massaging to work properly in TiddlyWiki5.
diff --git a/tw5.com/tiddlers/Introduction.tid b/tw5.com/tiddlers/Introduction.tid
index 1479bf186..eb2352345 100644
--- a/tw5.com/tiddlers/Introduction.tid
+++ b/tw5.com/tiddlers/Introduction.tid
@@ -1,45 +1,13 @@
 title: Introduction
 tags: introduction
 
-TiddlyWiki5 gains new capabilities through a [[completely rebuilt architecture|TiddlyWikiArchitecture]] using the latest features of HTML5 and node.js. It runs natively under node.js, and can also use its own components to construct a version of itself that works entirely within the browser, just as TiddlyWiki has always done.
+Here are a few features of TiddlyWiki that you can explore:
 
-If you're running Google Chrome Canary you can modify this wiki, and then download a copy by clicking this button:
-<>
-
-You can download a static copy of the tiddlers that are currently displayed in this wiki by clicking this button: <>
-
-

-Try out the prototype touch features:
-
-* The zooming chooser appears by swiping into the left edge of the screen (or hover the mouse over the extreme left edge of the browser window)
-* The zooming navigator appears by swiping in from the right edge of the screen (not accessible by mouse)
-

-
-Learning more about TiddlyWiki5:
-
-* WaysToUseTiddlyWiki discusses the various configurations in which TiddlyWiki5 can be used
-* Some very rough UserInterfaceSketches showing where it is heading
-
-Some useful tiddlers for feature testing:
-
-* HelloThere
-* TestingNewWikiText shows off the embryonic new wiki text engine
-* SampleJsonTiddler showing how JSON tiddlers are handled
-* SampleJavaScriptTiddler and SampleJavaScriptTiddlerWithError showing how JavaScript code is displayed
-* VideoTests showing how different online video formats can be embedded
-* SliderTests showing how sliders work
-* TypedBlockTests showing how embedded typed text blocks work
-* ShadowTiddlers, including ViewTemplate, EditTemplate and PageTemplate
-
-Technical documentation includes:
-
-* [[Testing]] regimen
-* Details of the CommandLineInterface
-* Overview of TiddlyWikiArchitecture
-** MacroInternals
-* Information about TiddlerFiles and RecipeFiles
-* A discussion of potential NewWikiTextFeatures
-
-All tiddlers:
-
-<>
+* Try editting some tiddlers and trying out the new WikiText. Your changes will not be visible to other users
+* If you're running [[Google Chrome Canary|https://tools.google.com/dlpage/chromesxs]] you can:
+** Modify this wiki, and then download a copy by clicking this button: <>
+** Download a static copy of the tiddlers that are currently displayed in this wiki by clicking this button: <>
+* If you're running on a touch browser like Mobile Safari on the iPad or iPhone:
+** The zooming chooser appears by swiping into the left edge of the screen. (It's currently broken but you get the idea)
+** The zooming navigator appears by swiping in from the right edge of the screen. (It currently only works in the 'Classic' storyview)
+* Browse the list of AllTiddlers or the ShadowTiddlers
diff --git a/tw5.com/tiddlers/definitions/Quine.tid b/tw5.com/tiddlers/definitions/Quine.tid
new file mode 100644
index 000000000..3fbae79a2
--- /dev/null
+++ b/tw5.com/tiddlers/definitions/Quine.tid
@@ -0,0 +1,6 @@
+title: Quine
+tags: definitions
+
+Wikipedia [[defines a Quine|http://en.wikipedia.org/wiki/Quine_(computing)]] as //a computer program which takes no input and produces a copy of its own source code as its only output//.
+
+TiddlyWiki is an unusual example of a practical quine: it is this ability to produce a copy of its own source code that lies at the heart of TiddlyWiki's ability to independently save changes to itself.
diff --git a/tw5.com/tiddlers/definitions/node.js.tid b/tw5.com/tiddlers/definitions/node.js.tid
new file mode 100644
index 000000000..a0fe89531
--- /dev/null
+++ b/tw5.com/tiddlers/definitions/node.js.tid
@@ -0,0 +1,8 @@
+title: node.js
+tags: definitions
+
+[[node.js]] is a downloadable application for your PC, Mac or Linux computer that lets it run JavaScript applications. Unlike JavaScript applications running in a web browser, [[node.js]] code has full access to the file system and other resources of the computer, enabling it to perform the roles that have traditionally been the preserve of languages like Java, PHP and Python. See http://nodejs.org/ for more details.
+
+For TiddlyWiki, [[node.js]] means that we can have a single code base that can run in the browser or on the server, giving great flexibility in how it is used.
+
+For end users, [[node.js]] is no more complicated to install than a web browser, but unlocks powerful capabilities such as the ability to run TiddlyWiki as a web server that you can connect to from other devices.