From f9e6a61450d828311257c239dd53f3a891ed9924 Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Fri, 1 Mar 2013 16:25:09 +0000 Subject: [PATCH] Readme updates --- editions/tw5.com/tiddlers/ReadMe.tid | 10 +- readme.md | 133 ++++++++++----------------- 2 files changed, 50 insertions(+), 93 deletions(-) diff --git a/editions/tw5.com/tiddlers/ReadMe.tid b/editions/tw5.com/tiddlers/ReadMe.tid index fe55b8fd0..80721f802 100644 --- a/editions/tw5.com/tiddlers/ReadMe.tid +++ b/editions/tw5.com/tiddlers/ReadMe.tid @@ -7,14 +7,6 @@ tags: introduction ! Usage -{{CommandLineInterface}} - -! Architecture - -{{TiddlyWikiArchitecture}} - -! Boot Mechanism - -{{BootMechanism}} +{{Getting started with TiddlyWiki under node.js}} //This `readme` file was automatically generated by TiddlyWiki5// diff --git a/readme.md b/readme.md index d86d5f45e..c0495cc1d 100644 --- a/readme.md +++ b/readme.md @@ -24,94 +24,59 @@ Join the discussions on @TiddlyWiki on Twitter for the latest news

-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 (like -IntentionallyMissingTiddler) then you'll see any displayed links to it instantly change from italicised to normal:

-$tw.wiki.addTiddler({title: "IntentionallyMissingTiddler", 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

+Usage

+

-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:

    +TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on tiddlers, +TiddlerFiles and +TiddlyWikiFiles. For example, this loads the tiddlers from a +TiddlyWiki HTML file and then saves one of them in HTML:

    +node tiddlywiki.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.html

    +Usage

    +Running +tiddlywiki.js from the command line boots the +TiddlyWiki kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments from left to right. The arguments are separated with spaces.

    +The first argument is the optional path to the wiki directory to be loaded. If not present, then the current directory is used.

    +The commands and their individual arguments follow, each command being identified by the prefix +--.

    +node tiddlywiki.js [<wikipath>] [--<command> [<arg>[,<arg>]]]

    +Batch Files

    +For trying +TiddlyWiki5 out under node.js, several batch files are provided:

    • -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
    • +bld.sh builds the new +TiddlyWiki 5 HTML file
    • -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. -

+2bld.sh builds +TiddlyWiki 2.6.5 from its original source

+Commands

+The following commands are available:

+
+ + + +DumpCommand
+ + + +LoadCommand
+ + + +SaveTiddlerCommand
+ + + +ServerCommand
+ + + +VerboseCommand
+ + + +VersionCommand

This readme file was automatically generated by