From f25299f9f394e306f60a2747101712e5a4b46383 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Sun, 15 Jul 2012 17:34:34 +0100 Subject: [PATCH] Docs update --- readme.md | 2 +- tw5.com/tiddlers/Acknowledgements.tid | 5 +- tw5.com/tiddlers/Docs.tid | 87 +------------------------- tw5.com/tiddlers/HelloThere.tid | 6 +- tw5.com/tiddlers/Internals.tid | 90 +++++++++++++++++++++++++++ 5 files changed, 100 insertions(+), 90 deletions(-) create mode 100644 tw5.com/tiddlers/Internals.tid diff --git a/readme.md b/readme.md index 3ce29a851..c5376bd13 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 in the browser or as a powerful node.js application.

TiddlyWiki offers a radically better way of managing your data compared to traditional documents and emails. The fundamental idea is that information is more useful and reusable if we cut up into the smallest semantically meaningful chunks – tiddlers – and use links, tags and macros to model the structured relationships between them. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.

TiddlyWiki5 has many improvements over the original. It is currently at an early alpha stage, and is not yet ready for general use. But it's the best possible time to get involved and support its future development. You can:

Here are a few features of TiddlyWiki that you can explore:

  • Try editing some tiddlers here on tiddlywiki.com to try out the new WikiText. Your changes will not be visible to other users
  • Use TiddlySpot to host an instance of TiddlyWiki5
  • Save this wiki as a static HTML file:
  • 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)
  • Play with the SubStories example to understand how the StoryMechanism works
  • Browse the list of AllTiddlers or the ShadowTiddlers
  • Examine the example bitmap images and SVG images
  • Explore the RoadMap of TiddlyWiki5's ongoing development

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.

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"});

The power of this mechanism also drives the interactive features of TiddlyWiki. For example, try typing the following into the JavaScript console:

$tw.wiki.addTiddler({title: "ViewDropDownState", text: "(50,50,200,200)"});

You should see the view dropdown appear in the middle of the screen. The underlying mechanism is that the creation of the tiddler with this title triggers the display of the popup at the specified location.

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. +

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 data compared to 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.

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:

Here are a few features of TiddlyWiki that you can explore:

  • Try editing some tiddlers here on tiddlywiki.com to try out the new WikiText. Your changes will not be visible to other users
  • Use TiddlySpot to host an instance of TiddlyWiki5
  • Save this wiki as a static HTML file:
  • 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)
  • Play with the SubStories example to understand how the StoryMechanism works
  • Browse the list of AllTiddlers or the ShadowTiddlers
  • Examine the example bitmap images and SVG images
  • Explore the RoadMap of TiddlyWiki5's ongoing development

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.

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"});

The power of this mechanism also drives the interactive features of TiddlyWiki. For example, try typing the following into the JavaScript console:

$tw.wiki.addTiddler({title: "ViewDropDownState", text: "(50,50,200,200)"});

You should see the view dropdown appear in the middle of the screen. The underlying mechanism is that the creation of the tiddler with this title triggers the display of the popup at the specified location.

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.

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/Acknowledgements.tid b/tw5.com/tiddlers/Acknowledgements.tid index 3f8d8615c..f7314d0ce 100644 --- a/tw5.com/tiddlers/Acknowledgements.tid +++ b/tw5.com/tiddlers/Acknowledgements.tid @@ -2,9 +2,10 @@ title: Acknowledgements modifier: JeremyRuston tags: introduction -TiddlyWiki5 wouldn't be possible without the ongoing support of the TiddlyWiki user and developer community. Their attention and feedback has made it possible for me to get a good understanding of what people want from the product, and their passion for the product has taught me that the project is worth the investment of effort that I am making. +TiddlyWiki5 wouldn't be possible without the ongoing support of the TiddlyWiki user and developer community. Their attention and feedback has made it possible for get a good understanding of what people want from the product, and their passion for the product has taught me that the project is worth the investment of effort that I am making. -Working in OpenSource has enabled me to stand on the shoulders of giants, by reusing these projects: +TiddlyWiki5 stands on the shoulders of giants, by reusing these projects: * [[Twitter Bootstrap|http://twitter.github.com/bootstrap/]]'s CSS +* [[LESS dynamic stylesheet language|http://lesscss.org/]], used by Bootstrap * [[Esprima|http://esprima.org]], a JavaScript parsing infrastructure for multipurpose analysis diff --git a/tw5.com/tiddlers/Docs.tid b/tw5.com/tiddlers/Docs.tid index 065110970..e11685dcd 100644 --- a/tw5.com/tiddlers/Docs.tid +++ b/tw5.com/tiddlers/Docs.tid @@ -1,7 +1,9 @@ title: Docs tags: docs introduction -This is the main documentation hub for TiddlyWiki. +This is the main documentation hub for TiddlyWiki. See also: + +* [[Internals]] for developer documentation ! Guides @@ -89,89 +91,6 @@ When run under node.js, TiddlyWiki supports a [[command line interface|Getting s * VersionCommand * WikiTestCommand -! Internal Objects and Mechanisms - -Internally, TiddlyWiki is built on a number of key objects and mechanisms: - -* TiddlerObject -* WikiObject -* BootMechanism -* PluginMechanism -* ParsingMechanism -* RenderingMechanism -* DependencyMechanism -* RefreshMechanism -* MacroMechanism -* StoryMechanism -* EditingMechanism -* SavingMechanism -* SyncMechanism -* CommandMechanism -* ConfigMechanism - -! Plugin Module Types - -TiddlyWiki is built on a [[tiny microkernel|BootMechanism]] with all functionality provided as various types of plugin module: - -* CommandModules -* ConfigModules -* EditorModules -* GlobalModules -* LibraryModules -* MacroModules -* ModuleModules -* ParserModules -* StartupModules -* StoryViewModules -* TiddlerDeserializerModules -* TiddlerFieldModules -* TiddlerMethodModules -* TiddlerSerializerModules -* TreeNodeModules -* TreeUtilsModules -* UtilsModules -* WikiMethodModules -* WikiTextRuleModules - -! Tree Nodes - -The ParsingMechanism and the RenderingMechanism use a simple tree structure to represent both parsed WikiText and the HTML DOM structure of rendered content. - -* TreeNode -* ElementNode -* EntityNode -* MacroNode -* RawNode -* TextNode - -! Other Parsers - -TiddlyWiki processes other [[ContentTypes|ContentType]] than WikiText using these parsers: - -* OldWikiTextParser -* JsonParser -* ImageParser -* PlainTextParser -* TiddlyTextParser -* JavaScriptParser - -! Deserializers - -Deserializers are modules that read tiddlers from different text formats: - -* RecipeFiles -* TiddlerFiles -* TiddlyWikiFiles - -! Serializers - -Serializers are modules that convert tiddlers to different text formats: - -! Developer Cookbooks - -* [[Using TiddlyWiki for GitHub Pages project documentation]] -* [[Using TiddlyWiki as a component in node.js applications]] - ! Miscellaneous * ReportingBugs diff --git a/tw5.com/tiddlers/HelloThere.tid b/tw5.com/tiddlers/HelloThere.tid index 3a7a669a8..c21a5725a 100644 --- a/tw5.com/tiddlers/HelloThere.tid +++ b/tw5.com/tiddlers/HelloThere.tid @@ -3,11 +3,11 @@ 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|History]]. 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]]. +Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the reusable non-linear personal web notebook [[first released in 2004|History]]. 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|node.js]]. -TiddlyWiki offers a radically better way of managing your data compared to traditional documents and emails. The fundamental idea is that information is more useful and reusable if we cut up into the smallest semantically meaningful chunks -- [[tiddlers|Tiddlers]] -- and use links, tags and macros to model the structured relationships between them. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives. +TiddlyWiki is designed to fit around your brain, giving you a better way of managing data compared to 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|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. -TiddlyWiki5 has many [[improvements|Improvements]] over the original. It is currently at an early alpha stage, and is not yet ready for general use. But it's the best possible time to get involved and support its future development. You can: +TiddlyWiki5 has many [[improvements|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: * Explore its features online at http://alpha.tiddlywiki.com/ * Get involved in the [[development on GitHub|https://github.com/Jermolene/TiddlyWiki5]] diff --git a/tw5.com/tiddlers/Internals.tid b/tw5.com/tiddlers/Internals.tid new file mode 100644 index 000000000..932f10da1 --- /dev/null +++ b/tw5.com/tiddlers/Internals.tid @@ -0,0 +1,90 @@ +title: Internals +tags: docs introduction dev + +This is the developer documentation hub for TiddlyWiki. + +! Developer Cookbooks + +* [[Using TiddlyWiki for GitHub Pages project documentation]] +* [[Using TiddlyWiki as a component in node.js applications]] +* [[Constructing TiddlyWiki documents in other applications]] + +! Internal Objects and Mechanisms + +Internally, TiddlyWiki is built on a number of key objects and mechanisms: + +* TiddlerObject +* WikiObject +* BootMechanism +* PluginMechanism +* ParsingMechanism +* RenderingMechanism +* DependencyMechanism +* RefreshMechanism +* MacroMechanism +* StoryMechanism +* EditingMechanism +* SavingMechanism +* SyncMechanism +* CommandMechanism +* ConfigMechanism + +! Plugin Module Types + +TiddlyWiki is built on a [[tiny microkernel|BootMechanism]] with all functionality provided as various types of plugin module: + +* CommandModules +* ConfigModules +* EditorModules +* GlobalModules +* LibraryModules +* MacroModules +* ModuleModules +* ParserModules +* SaverModules +* StartupModules +* StoryViewModules +* SyncerModules +* TiddlerDeserializerModules +* TiddlerFieldModules +* TiddlerMethodModules +* TiddlerSerializerModules +* TreeNodeModules +* TreeUtilsModules +* UtilsModules +* WikiMethodModules +* WikiTextRuleModules + +! Tree Nodes + +The ParsingMechanism and the RenderingMechanism use a simple tree structure to represent both parsed WikiText and the HTML DOM structure of rendered content. + +* TreeNode +* ElementNode +* EntityNode +* MacroNode +* RawNode +* TextNode + +! Other Parsers + +TiddlyWiki processes other [[ContentTypes|ContentType]] than WikiText using these parsers: + +* OldWikiTextParser +* JsonParser +* ImageParser +* PlainTextParser +* TiddlyTextParser +* JavaScriptParser + +! Deserializers + +Deserializers are modules that read tiddlers from different text formats: + +* RecipeFiles +* TiddlerFiles +* TiddlyWikiFiles + +! Serializers + +Serializers are modules that convert tiddlers to different text formats: