From 9a19ed67d4ff5ab9bc90496a4b3629980fc56f1e Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Fri, 22 Jun 2012 13:51:47 +0100 Subject: [PATCH] Docs updates --- readme.md | 2 +- tw5.com/tiddlers/Acknowledgements.tid | 10 ++++++++ tw5.com/tiddlers/HelloThere.tid | 5 ++-- tw5.com/tiddlers/History.tid | 23 +++++++++++++++++++ tw5.com/tiddlers/Improvements.tid | 3 ++- tw5.com/tiddlers/concepts/TiddlyWiki.tid | 2 +- .../definitions/FederatialLimited.tid | 6 +++++ tw5.com/tiddlers/definitions/JeremyRuston.tid | 18 +++++++++++++++ tw5.com/tiddlers/definitions/OpenSource.tid | 17 ++++++++++++++ 9 files changed, 80 insertions(+), 6 deletions(-) create mode 100644 tw5.com/tiddlers/Acknowledgements.tid create mode 100644 tw5.com/tiddlers/History.tid create mode 100644 tw5.com/tiddlers/definitions/FederatialLimited.tid create mode 100644 tw5.com/tiddlers/definitions/JeremyRuston.tid create mode 100644 tw5.com/tiddlers/definitions/OpenSource.tid diff --git a/readme.md b/readme.md index 6494ea617..365fd7d55 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 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");
+
 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 improved 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 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 is at an incomplete 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:
 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/Acknowledgements.tid b/tw5.com/tiddlers/Acknowledgements.tid
new file mode 100644
index 000000000..3f8d8615c
--- /dev/null
+++ b/tw5.com/tiddlers/Acknowledgements.tid
@@ -0,0 +1,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.
+
+Working in OpenSource has enabled me to stand on the shoulders of giants, by reusing these projects:
+
+* [[Twitter Bootstrap|http://twitter.github.com/bootstrap/]]'s CSS
+* [[Esprima|http://esprima.org]], a JavaScript parsing infrastructure for multipurpose analysis
diff --git a/tw5.com/tiddlers/HelloThere.tid b/tw5.com/tiddlers/HelloThere.tid
index 97842a8d9..99c961712 100644
--- a/tw5.com/tiddlers/HelloThere.tid
+++ b/tw5.com/tiddlers/HelloThere.tid
@@ -5,12 +5,11 @@ 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|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.
+TiddlyWiki offers a radically improved 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 is at an incomplete early alpha stage, and is not yet ready for general use. You can:
+TiddlyWiki5 is at an incomplete 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:
 
 * 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
-
diff --git a/tw5.com/tiddlers/History.tid b/tw5.com/tiddlers/History.tid
new file mode 100644
index 000000000..77a6d897b
--- /dev/null
+++ b/tw5.com/tiddlers/History.tid
@@ -0,0 +1,23 @@
+title: History
+
+! Origins of TiddlyWiki
+
+Back in 1997 a colleague introduced me to [[Ward Cunningham's original wiki|http://c2.com/cgi/wiki]]. I was stunned that something so powerful could fit into just 700 lines of Perl, and fascinated by the radical reimagining of security and permissions. Like many other developers, I took every opportunity I could to try out various wikis, and to explore their use at work.
+
+After watching people use wikis for a few years, I noticed that power users made extensive use of the ability to open multiple wiki pages at once in several browser tabs, making it easier for them to compare and review pages, to copy text between them and to act as a sort of queue of pages yet to be read.
+
+I could see that this ability to manipulate multiple pages at once was central to the ability to refactor a wiki, and I've found that a wiki that is lovingly refactored tends to be more useful. And yet, standard wiki user interfaces have always been designed exclusively for the presentation and manipulation of single pages at once.
+
+All of these thoughts came together when I saw GMail in April 2004, which used Ajax cleverly to blend individual emails into threaded conversations.
+
+I started experimenting with HTML and JavaScript to explore the idea further. I'd had virtually no experience of either, just having put together some static pages and simple ASP sites in previous lives. Getting my head around these client-side technologies was painful; like everyone else, I was horrified to discover how appalling were the incompatibilities and inconsistencies of web programming.
+
+Then I could show the idea with a static HTML file. So, I didn't need a serverside to demonstrate how this simple user interface idea worked. Or indeed a proper grown-up server with the ability to run cgi scripts.
+
+! Launch of TiddlyWiki
+
+So, in September 2004 I released a primitive [[first version of TiddlyWiki|http://tiddlywiki.com/firstversion.html]]. It was the smallest possible thing that demonstrated the idea that I had: it was a simple, self-contained static 48KB HTML file sitting on a dusty old Sun server in my friend Steph's attic.
+
+The downside of writing the first version of TiddlyWiki in this way was that it made it completely impractical to use for editing - when you click 'save changes' it just pops up a window showing the data that would be saved if it were possible for an HTML page to write to the file system.
+
+//To be continued.../
\ No newline at end of file
diff --git a/tw5.com/tiddlers/Improvements.tid b/tw5.com/tiddlers/Improvements.tid
index d8d81de4e..ccaa0664e 100644
--- a/tw5.com/tiddlers/Improvements.tid
+++ b/tw5.com/tiddlers/Improvements.tid
@@ -2,11 +2,12 @@ title: Improvements
 modifier: JeremyRuston
 tags: docs introduction
 
-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.
+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. The new code is much easier to work with, and will hopefully prove an even more fertile ground for the community of open source developers around TiddlyWiki.
 
 For end users, the important improvements include:
 
 * Improved WikiText, with much better generation of HTML, including proper `
` tags
+* Flexible TiddlerFilters that make it easier to work with several tiddlers in a single operation
 * 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)
diff --git a/tw5.com/tiddlers/concepts/TiddlyWiki.tid b/tw5.com/tiddlers/concepts/TiddlyWiki.tid
index f96539d1a..023142b21 100644
--- a/tw5.com/tiddlers/concepts/TiddlyWiki.tid
+++ b/tw5.com/tiddlers/concepts/TiddlyWiki.tid
@@ -7,6 +7,6 @@ TiddlyWiki is a rich, interactive interface for manipulating complex data with s
 
 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 sequences of tiddlers called stories. Tiddlers use a WikiText notation that concisely represents a wide range of text formatting and hypertext features.
 
-People [[love using|Raves]] TiddlyWiki. Because it can be used without any complicated server infrastructure, and because it is [[open source|What 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|What is open source?]] project with a busy [[Community]] of independent developers.
+People [[love using|Raves]] TiddlyWiki. Because it can be used without any complicated server infrastructure, and because it is [[open source|What 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|OpenSource]] project with a busy [[Community]] of independent developers.
 
 See TiddlyWikiArchitecture and [[Introduction]].
diff --git a/tw5.com/tiddlers/definitions/FederatialLimited.tid b/tw5.com/tiddlers/definitions/FederatialLimited.tid
new file mode 100644
index 000000000..93f54f9cc
--- /dev/null
+++ b/tw5.com/tiddlers/definitions/FederatialLimited.tid
@@ -0,0 +1,6 @@
+title: FederatialLimited
+tags: definitions
+
+Federatial Limited is a software consultancy founded by JeremyRuston specializing in understanding the impact of the web on the way that we work together.
+
+Through human history we've used hierarchies to organize ourselves to undertake the big challenges of raising an army, organizing a church, or building an enterprise. Now we see the rise of small, loosely federated groups that use the web to establish agreement and organize action, such as the creation of open source software. Federatial is exploring a new wave of collaboration tools that eschew the old, crude hierarchical models of organization.
diff --git a/tw5.com/tiddlers/definitions/JeremyRuston.tid b/tw5.com/tiddlers/definitions/JeremyRuston.tid
new file mode 100644
index 000000000..b89cbc4a2
--- /dev/null
+++ b/tw5.com/tiddlers/definitions/JeremyRuston.tid
@@ -0,0 +1,18 @@
+title: JeremyRuston
+modifier: JeremyRuston
+tags: definitions
+
+I've spent my life inventing software products with great user experiences, and building the teams to develop them. I'm the inventor of TiddlyWiki, a popular open source personal organiser that's grown to be the platform for a whole new class of web applications. I lead the community around TiddlyWiki, and am dedicated to building a great product for users all over the world.
+
+I am available through my company FederatialLimited for consultancy and speaking engagements.
+
+You can find me on these services:
+
+* [[@Jermolene on Twitter|http://twitter.com/#!/jermolene]]
+* [[LinkedIn|http://www.linkedin.com/in/jermy]]
+* [[Flickr|http://www.flickr.com/photos/jermy/]]
+
+Further information:
+
+* An [[interview with me in The Inquirer|http://www.theinquirer.net/inquirer/feature/2105529/bt-software-engineer-tells-telco-source]] by Wendy Grossman
+* A [[hilarious interview with me|http://www.youtube.com/watch?v=auyIhw8MTmQ]] from British television in 1983
diff --git a/tw5.com/tiddlers/definitions/OpenSource.tid b/tw5.com/tiddlers/definitions/OpenSource.tid
new file mode 100644
index 000000000..c342b1843
--- /dev/null
+++ b/tw5.com/tiddlers/definitions/OpenSource.tid
@@ -0,0 +1,17 @@
+title: OpenSource
+modifier: JeremyRuston
+tags: definitions
+
+OpenSource is [[defined by Wikipedia|http://en.wikipedia.org/wiki/Open_source]] as //a philosophy, or pragmatic methodology that promotes free redistribution and access to an end product's design and implementation details//.
+
+For me, OpenSource speaks to a fundamental truth about software: software is unlike anything else we produce in our post-industrial revolution era. Initially, we thought that programming would evolve to be a branch of engineering: a process that was amenable to conventional techniques of mass production, and the traditional business models we have wrapped around the things we make and the things we dig out of the ground.
+
+As it has turned out, programming isn't like engineering at all. In a field like bridge building, engineers can reliably build bridges to any required specification, with a full understanding of the practical limitations under which it has to operate. In software, we struggle to manage large scale development. We can't even reliably estimate the complexity of non-trivial programming tasks. Smart people think of software as being mostly a liability, and not the asset that it first appears.
+
+OpenSource doesn't change the  nature of software, but instead incorporates it into the philosophy. The most fundamental insight is that programming is hard, and that the best way to mitigate the problem is to have lots and lots of smart brains working on it. But open source doesn't seek to do that by prescribing a reductionist, hierarchical breakdown of the required tasks that can be allocated to an army of programmers. Instead, OpenSource suggests that our code should be accessible to everyone, to create the widest possible surface area for potential collaborators.
+
+This leads to an intense, organic, chaotic way of working, but the results are undeniably impressive.
+
+TiddlyWiki is part of a small band of OpenSource projects like Firefox that don't just target software developers, but provide something that end users can use themselves, without any special programming ability.
+
+Here's a video of a presentation I did in 2007 called [["How to Start an Open Source Project"|http://vimeo.com/856110]].