From 9bce14474cb1df5e5c70b75db327bcd7fee8c34b Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Sat, 9 Feb 2013 17:08:28 +0000 Subject: [PATCH] Update docs --- editions/tw2/readme.md | 32 +- .../tw5.com/tiddlers/definitions/node.js.tid | 2 + ..._started_with_TiddlyWiki_under_node.js.tid | 14 +- readme.md | 278 ++++++------------ 4 files changed, 125 insertions(+), 201 deletions(-) diff --git a/editions/tw2/readme.md b/editions/tw2/readme.md index 0191aba925..79534f1757 100644 --- a/editions/tw2/readme.md +++ b/editions/tw2/readme.md @@ -1,4 +1,34 @@ -

Using TiddlyWiki5 to build TiddlyWikiClassic

TiddlyWiki5 can be used to build older 2.x.x versions of TiddlyWiki from their constituent components. Doing so involves these additional features over and above those used for building TiddlyWiki5:

Usage

TiddlyWikiClassic is built from the command line by running TiddlyWiki5 under node.js. A typical usage would be:

node ../../tiddlywiki.js \
+

+Using 
+TiddlyWiki5 to build 
+TiddlyWikiClassic

+
+TiddlyWiki5 can be used to build older 2.x.x versions of 
+TiddlyWiki from their constituent components. Doing so involves these additional features over and above those used for building 
+TiddlyWiki5:

+Usage

+
+TiddlyWikiClassic is built from the command line by running 
+TiddlyWiki5 under node.js. A typical usage would be:
+node ../../tiddlywiki.js \
 	--verbose \
 	--load <path_to_recipe_file> \
 	--savetiddler $:/core/templates/tiddlywiki2.template.html <path_to_write_index_file> text/plain \
diff --git a/editions/tw5.com/tiddlers/definitions/node.js.tid b/editions/tw5.com/tiddlers/definitions/node.js.tid
index a0fe895316..392354a92c 100644
--- a/editions/tw5.com/tiddlers/definitions/node.js.tid
+++ b/editions/tw5.com/tiddlers/definitions/node.js.tid
@@ -6,3 +6,5 @@ tags: definitions
 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.
+
+See [[Getting started with TiddlyWiki under node.js]] for more details.
diff --git a/editions/tw5.com/tiddlers/guides/Getting_started_with_TiddlyWiki_under_node.js.tid b/editions/tw5.com/tiddlers/guides/Getting_started_with_TiddlyWiki_under_node.js.tid
index 7dedff826b..71ca7a93cf 100644
--- a/editions/tw5.com/tiddlers/guides/Getting_started_with_TiddlyWiki_under_node.js.tid
+++ b/editions/tw5.com/tiddlers/guides/Getting_started_with_TiddlyWiki_under_node.js.tid
@@ -9,19 +9,25 @@ node tiddlywiki.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.ht
 ```
 !!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 commands are identified by the prefix `--`.
+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 [-- [[,]]]
+node tiddlywiki.js [] [-- [[,]]]
 ```
 
 !! Batch Files
 
-For trying TiddlyWiki5 out under node.js, two batch files are provided:
+For trying TiddlyWiki5 out under node.js, several batch files are provided:
 
-* `bld.sh` builds the new TiddlyWiki 5 HTML file (placed in the `tmp/tw5/` directory by default)
+* `bld.sh` builds the new TiddlyWiki 5 HTML file
+* `2bld.sh` builds TiddlyWiki 2.6.5 from its original source
 
 !!Commands
 
 The following commands are available:
 
+{{{ [tag[command]sort[title]] }}}
diff --git a/readme.md b/readme.md
index fc26e4f846..d86d5f45e3 100644
--- a/readme.md
+++ b/readme.md
@@ -1,233 +1,119 @@
 

 Welcome to 
-TiddlyWiki5
-

-

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

-

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

-

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

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

-

+@TiddlyWiki on Twitter for the latest news

+Usage

+

+Architecture

 

-Usage

-

-

-

-Architecture

-

-

-Overview

-

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

-

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

-

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

-

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

-

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

-

+TiddlyWiki, it is recommended that you review the 
+Docs and read the code – start with the boot kernel 
+$:/core/boot.js.
+

+Boot Mechanism

 

-Boot Mechanism

-

-

-Introduction

-

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

-

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

-

+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

-

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

-

+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
    • 
+$:/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)
      • 
-
    • 
+$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
      • 
-
    
-
    
+$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.

-

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

-
    
+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
      • 
-
    • 
+<DIV> elements
    • 
 
-core/bootprefix.js
-, containing a few lines to set up the plugin environment
      • 
-
    • 
+core/bootprefix.js, containing a few lines to set up the plugin environment
    • 
 
-JavaScript
- modules, packed as HTML 
-<SCRIPT>
- blocks
      • 
-
    • 
+JavaScript modules, packed as HTML 
+<SCRIPT> blocks
    • 
 
-core/boot.js
-, containing the boot kernel
      • 
-
    
-
    
+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).

-

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

-

-

+$tw global variable that is used to store all the state data of the system.
+

 
 This 
-readme
- file was automatically generated by 
-TiddlyWiki5
-
-
-

+readme file was automatically generated by 
+TiddlyWiki5
+

\ No newline at end of file