From bab43fe6c2422ae8c8be8f3eb5874debb67d83b3 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Thu, 3 Jan 2013 16:28:07 +0000 Subject: [PATCH] Docs update --- editions/tw5.com/tiddlers/AllTiddlers.tid | 2 +- .../tiddlers/concepts/ContextTiddler.tid | 2 +- .../tiddlers/concepts/ShadowTiddlers.tid | 2 +- .../tw5.com/tiddlers/concepts/WikiText.tid | 4 +- .../tiddlers/mechanisms/ParsingMechanism.tid | 47 ------------------- .../tw5.com/tiddlers/widgets/VideoWidget.tid | 6 +-- readme.md | 4 +- 7 files changed, 10 insertions(+), 57 deletions(-) diff --git a/editions/tw5.com/tiddlers/AllTiddlers.tid b/editions/tw5.com/tiddlers/AllTiddlers.tid index 967a43b5a..ac83659bb 100644 --- a/editions/tw5.com/tiddlers/AllTiddlers.tid +++ b/editions/tw5.com/tiddlers/AllTiddlers.tid @@ -3,4 +3,4 @@ tags: navigation Current tiddlers: -<_list type="all" /> +<$list type="all" /> diff --git a/editions/tw5.com/tiddlers/concepts/ContextTiddler.tid b/editions/tw5.com/tiddlers/concepts/ContextTiddler.tid index 69a12a8e6..905d411d7 100644 --- a/editions/tw5.com/tiddlers/concepts/ContextTiddler.tid +++ b/editions/tw5.com/tiddlers/concepts/ContextTiddler.tid @@ -1,4 +1,4 @@ title: ContextTiddler tags: docs concepts -The ContextTiddler is the current tiddler during WikiText processing. It allows you to write a widget like `<_view field="title" format="link"/>` in TiddlerTemplates without explicitly specifying the tiddler that it applies to. +The ContextTiddler is the current tiddler during WikiText processing. It allows you to write a widget like `<$view field="title" format="link"/>` in TiddlerTemplates without explicitly specifying the tiddler that it applies to. diff --git a/editions/tw5.com/tiddlers/concepts/ShadowTiddlers.tid b/editions/tw5.com/tiddlers/concepts/ShadowTiddlers.tid index 08c1b8465..da596c5e6 100644 --- a/editions/tw5.com/tiddlers/concepts/ShadowTiddlers.tid +++ b/editions/tw5.com/tiddlers/concepts/ShadowTiddlers.tid @@ -7,4 +7,4 @@ Thus, even an apparently empty TiddlyWiki actually contains dozens of tiddlers t The current shadow tiddlers are: -<_list type="shadows" /> +<$list type="shadows" /> diff --git a/editions/tw5.com/tiddlers/concepts/WikiText.tid b/editions/tw5.com/tiddlers/concepts/WikiText.tid index 27a539024..d2c3a65b8 100644 --- a/editions/tw5.com/tiddlers/concepts/WikiText.tid +++ b/editions/tw5.com/tiddlers/concepts/WikiText.tid @@ -200,10 +200,10 @@ This is my nice and simple block of text. HelloThere ! Widgets -Widgets provide rich functionality within WikiText. For example, the `<_video>` widget can be used to embed videos from YouTube, Vimeo or the Internet Archive: +Widgets provide rich functionality within WikiText. For example, the `<$video>` widget can be used to embed videos from YouTube, Vimeo or the Internet Archive: ``` -<_video src="32001208" type="vimeo" /> +<$video src="32001208" type="vimeo" /> ``` For full details of the available widgets, see the [[Docs]]. diff --git a/editions/tw5.com/tiddlers/mechanisms/ParsingMechanism.tid b/editions/tw5.com/tiddlers/mechanisms/ParsingMechanism.tid index eb06b4ef6..793e051a7 100644 --- a/editions/tw5.com/tiddlers/mechanisms/ParsingMechanism.tid +++ b/editions/tw5.com/tiddlers/mechanisms/ParsingMechanism.tid @@ -1,51 +1,4 @@ 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/vnd.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/vnd.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 `<>` macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes. diff --git a/editions/tw5.com/tiddlers/widgets/VideoWidget.tid b/editions/tw5.com/tiddlers/widgets/VideoWidget.tid index 9e270e0e3..2ad239cdf 100644 --- a/editions/tw5.com/tiddlers/widgets/VideoWidget.tid +++ b/editions/tw5.com/tiddlers/widgets/VideoWidget.tid @@ -3,8 +3,8 @@ tags: docs widget Here is a collection of embedded videos. Try opening and closing tiddlers while the videos are playing; they should not be affected. -<_video src="32001208" type="vimeo" /> +<$video src="32001208" type="vimeo" /> -<_video src="wvWHnK2FiCk" type="youtube" /> +<$video src="wvWHnK2FiCk" type="youtube" /> -<_video src="santa_claus_conquers_the_martians_ipod" type="archiveorg" /> +<$video src="santa_claus_conquers_the_martians_ipod" type="archiveorg" /> diff --git a/readme.md b/readme.md index ee6b766d5..11f50f015 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -

Welcome to TiddlyWiki5

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

TiddlyWiki is designed to fit around your brain, giving you a better way of managing information than traditional documents and emails. The fundamental idea is that information is more useful and reusable if we cut it up into the smallest semantically meaningful chunks – tiddlers – and give them titles so that they can be structured with links, tags and macros. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.

28th December 2012 - the TiddlyWiki5 core code is in the midst of some major refactoring upheavals, and there have been several regressions that will be fixed over the next few days, along with bringing the documentation back up to date

TiddlyWiki5 has many improvements over the original. It is currently labelled alpha, meaning it is working but incomplete. It is the best possible time to get involved and support its future development. 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 primary use of the engine is to convert raw text/vnd.tiddlywiki WikiText into a text/html or text/plain representation for display. The transclusion and templating features of WikiText allow the engine to also be used to generate TiddlyWiki HTML files from raw tiddlers.

You can explore this mechanism by opening the JavaScript console in your browser. Typing this command will replace the text of the tiddler HelloThere with new content:

$tw.wiki.addTiddler({title: "HelloThere", text: "This is some new content"});

If the tiddler HelloThere is visible then you'll see it instantly change to reflect the new content. If you create a tiddler that doesn't currently exist then you'll see any displayed links to it instantly change from italicised to normal:

$tw.wiki.addTiddler({title: "TiddlyWiki5", text: "This tiddler now exists"});

If you're interested in understanding more about the internal operation of TiddlyWiki, it is recommended that you review the Docs and read the code – start with the boot kernel $:/core/boot.js. -

Boot Mechanism

Introduction

TiddlyWiki5 is based on a 1,000 line boot kernel that runs on node.js or in the browser, with all other functionality added via dynamically loaded modules.

The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers and execute JavaScript modules. Plugin modules are written like node.js modules.

There are many different types of module: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module 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 plugin modules have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugin modules.

Plugins and Modules

In TiddlyWiki5, Plugins are bundles of tiddlers that are distributed and managed as one; Modules are JavaScript tiddlers with a module type identifying when and how they should be executed.

The tiddler $:/core/boot.js is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup module to load up the rest of the application.

The kernel includes:

  • Several short shared utility functions
  • A handful of methods implementing the plugin module mechanism
  • The $tw.Tiddler class (and field definition plugins)
  • The $tw.Wiki class (and 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
  • 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. +

Welcome to TiddlyWiki5

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

TiddlyWiki is designed to fit around your brain, giving you a better way of managing information than traditional documents and emails. The fundamental idea is that information is more useful and reusable if we cut it up into the smallest semantically meaningful chunks – tiddlers – and give them titles so that they can be structured with links, tags and macros. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.

28th December 2012 - the TiddlyWiki5 core code is in the midst of some major refactoring upheavals, and there have been several regressions that will be fixed over the next few days, along with bringing the documentation back up to date

TiddlyWiki5 has many improvements over the original. It is currently labelled alpha, meaning it is working but incomplete. It is the best possible time to get involved and support its future development. 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 primary use of the engine is to convert raw text/vnd.tiddlywiki WikiText into a text/html or text/plain representation for display. The transclusion and templating features of WikiText allow the engine to also be used to generate TiddlyWiki HTML files from raw tiddlers.

You can explore this mechanism by opening the JavaScript console in your browser. Typing this command will replace the text of the tiddler HelloThere with new content:

$tw.wiki.addTiddler({title: "HelloThere", text: "This is some new content"});

If the tiddler HelloThere is visible then you'll see it instantly change to reflect the new content. If you create a tiddler that doesn't currently exist then you'll see any displayed links to it instantly change from italicised to normal:

$tw.wiki.addTiddler({title: "TiddlyWiki5", text: "This tiddler now exists"});

If you're interested in understanding more about the internal operation of TiddlyWiki, it is recommended that you review the Docs and read the code – start with the boot kernel $:/core/boot.js. +

Boot Mechanism

Introduction

TiddlyWiki5 is based on a 1,000 line boot kernel that runs on node.js or in the browser, with all other functionality added via dynamically loaded modules.

The kernel boots just enough of the TiddlyWiki environment to allow it to load tiddlers and execute JavaScript modules. Plugin modules are written like node.js modules.

There are many different types of module: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module 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 plugin modules have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugin modules.

Plugins and Modules

In TiddlyWiki5, Plugins are bundles of tiddlers that are distributed and managed as one; Modules are JavaScript tiddlers with a module type identifying when and how they should be executed.

The tiddler $:/core/boot.js is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup module to load up the rest of the application.

The kernel includes:

  • Several short shared utility functions
  • A handful of methods implementing the plugin module mechanism
  • The $tw.Tiddler class (and field definition plugins)
  • The $tw.Wiki class (and 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
  • 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.

This readme file was automatically generated by TiddlyWiki5

\ No newline at end of file