From 892cca0ccf7d443d24507ca489d69e859d77c37c Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Fri, 4 May 2012 17:46:01 +0100 Subject: [PATCH] Updated docs --- .../tw5.com/store/CommandLineInterface.tid | 53 ++++--------------- .../tw5.com/store/High Level Architecture.svg | 3 -- .../store/High Level Architecture.svg.meta | 3 -- rabbithole/tw5.com/store/Introduction.tid | 4 +- rabbithole/tw5.com/store/MacroInternals.tid | 40 -------------- rabbithole/tw5.com/store/PluginMechanism.tid | 15 ++++++ rabbithole/tw5.com/store/Testing.tid | 9 ---- .../tw5.com/store/TiddlyWikiInternals.tid | 8 --- 8 files changed, 29 insertions(+), 106 deletions(-) delete mode 100644 rabbithole/tw5.com/store/High Level Architecture.svg delete mode 100644 rabbithole/tw5.com/store/High Level Architecture.svg.meta delete mode 100644 rabbithole/tw5.com/store/MacroInternals.tid create mode 100644 rabbithole/tw5.com/store/PluginMechanism.tid delete mode 100644 rabbithole/tw5.com/store/Testing.tid delete mode 100644 rabbithole/tw5.com/store/TiddlyWikiInternals.tid diff --git a/rabbithole/tw5.com/store/CommandLineInterface.tid b/rabbithole/tw5.com/store/CommandLineInterface.tid index c98746974..5bcf6432c 100644 --- a/rabbithole/tw5.com/store/CommandLineInterface.tid +++ b/rabbithole/tw5.com/store/CommandLineInterface.tid @@ -3,58 +3,27 @@ modifier: JeremyRuston TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles. -The command line interface for TiddlyWiki5 has been designed to support two distinct usages: -* Cooking (or building) old 2.6.x versions of classic TiddlyWiki from the constituent JavaScript components -* Cooking and serving TiddlyWiki5 itself - !!Usage ` -node tiddlywiki.js +node core/boot.js ` -The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a [[recipe file|RecipeFiles]] and all the subrecipes and [[tiddlers|TiddlerFiles]] that it references, and then resumes with the next command line option in sequence. +This boots the TiddlyWiki kernel and loads the core plugins. The wiki store is initially empty. -The state that is carried between options is as follows: -* The set of tiddlers that are currently loaded into memory -* The recipe file last used to load tiddlers (recipe files are used primarily to manage shadow tiddlers) -* The TiddlerFileStore used to store the main content tiddlers. This is independent of the current recipe +The command line options are processed sequentially from left to right. Processing pauses during long operations and then resumes with the next command line option in sequence. +ent recipe The following options are available: -|`--recipe ` |Loads a specfied `.recipe` file | -|`--load ` |Load additional tiddlers from 2.x.x TiddlyWiki files (`.html`), `.tiddler`, `.tid`, `.json` or other files | -|`--store ` |Load a specified TiddlerFileStore | -|`--links none` |Determines how links will be generated by subsequent options. See below for details | -|`--savewiki ` |Saves all the loaded tiddlers as a single file TiddlyWiki called `index.html` and an RSS feed called `index.xml` in a new directory of the specified name | +|`--load ` |Load tiddlers from 2.x.x TiddlyWiki files (`.html`), `.tiddler`, `.tid`, `.json` or other files | |`--savetiddler <filename> [<type>]` |Save an individual tiddler as a specified MIME type, defaults to `text/html` | -|`--savetiddlers <outdir>` |Saves all the loaded tiddlers as `.tid` files in the specified directory | -|`--savehtml <outdir>` |Saves all the loaded tiddlers as static, unstyled `.html` files in the specified directory | -|`--servewiki <port>` |Serve the cooked TiddlyWiki over HTTP at `/` | -|`--servetiddlers <port>` |Serve individual tiddlers over HTTP at `/tiddlertitle` | |`--wikitest <dir> [save]` |Run wikification tests against the tiddlers in the given directory. Include the `save` flag to save the test result files as the new targets | -|`--dumpstore` |Dump the TiddlyWiki store in JSON format | -|`--dumprecipe` |Dump the current recipe in JSON format | -|`--verbose` |verbose output, useful for debugging | +|`--dump tiddlers` |Dump the titles of the tiddlers in the wiki store | +|`--dump shadows` |Dump the titles of the shadow tiddlers in the wiki store | +|`--dump config` |Dump the current core configuration | +|`--verbose` |Triggers verbose output, useful for debugging | !! Examples -This example loads the tiddlers from a TiddlyWiki HTML file and makes them available over HTTP: +This example loads the tiddlers from a TiddlyWiki HTML file and then saves one of them in HTML: ` -node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000 -` -This example cooks a TiddlyWiki from a recipe: -` -node tiddlywiki.js --recipe tiddlywiki.com/index.recipe --savewiki tmp/ -` -This example ginsus a TiddlyWiki into its constituent tiddlers: -` -node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers +node tiddlywiki.js --verbose --load mywiki.html --savertiddler ReadMe ./readme.html ` !! Notes -The HTTP serving functionality built into TiddlyWiki5 is designed to support personal use scenarios. If you want to flexibly and robustly share tiddlers on the web for multiple users, you should use TiddlyWeb or TiddlySpace. - -`--servewiki` and `--servetiddlers` are for different purposes and should not be used together. The former is for TiddlyWiki core developers who want to be able to edit the TiddlyWiki source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the TiddlyWiki JavaScript files each time the page is loaded. The latter is for experimenting with the new wikification engine. - `--wikitest` looks for `*.tid` files in the specified folder. It then wikifies the tiddlers to both "text/plain" and "text/html" format and checks the results against the content of the `*.html` and `*.txt` files in the same directory. - -`--links` controls the way that links are generated. Currently, the only option supported is: - - `none`: Tiddler links are disabled - - diff --git a/rabbithole/tw5.com/store/High Level Architecture.svg b/rabbithole/tw5.com/store/High Level Architecture.svg deleted file mode 100644 index 79b5af370..000000000 --- a/rabbithole/tw5.com/store/High Level Architecture.svg +++ /dev/null @@ -1,3 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="-2 -2 814 684" width="814pt" height="57pc"><metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:date>2012-01-12 18:59Z</dc:date><!-- Produced by OmniGraffle Professional 5.3.6 --></metadata><defs><font-face font-family="Helvetica" font-size="7" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="10" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="7" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="6" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="8" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="9" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="532.22656" cap-height="719.72656" ascent="770.01953" descent="-229.98047" font-weight="bold"><font-face-src><font-face-name name="Helvetica-Bold"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="6" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face><font-face font-family="Helvetica" font-size="21" units-per-em="1000" underline-position="-75.683594" underline-thickness="49.316406" slope="0" x-height="522.94922" cap-height="717.28516" ascent="770.01953" descent="-229.98047" font-weight="500"><font-face-src><font-face-name name="Helvetica"/></font-face-src></font-face></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1Layer 1Manages a collection of tiddlers. Plumbs in representation conversion and cachingWikiStoreInitialisation and bootstrappingAppParses TiddlyWiki-style macro parameters into a JavaScript structureArgParserAbstracts differences between file system and HTTPFileRetrieverParses JavaScript code into a parse treeJavaScriptParserRepresents JavaScript code in a tree structure. Has methods to compile a tree back into textual JavaScriptJavaScriptParseTreeOpen source JavaScript parsing enginePEG.JSParser for the JavaScript language provided as an example by PEG.JSjavascript.pegjsCollection of objects that know how to navigate to a new tiddlerNavigatorsA navigator that implements TiddlyWiki's classic navigation behaviourStoryNavigatorRepresents a TiddlyWiki recipe. Has methods to load a recipe and its tiddlers, and to cook the output of the recipeRecipeRepresents a tiddler as an immutable collection of fieldsTiddlerFunctions know how to write tiddlers to various data formatsTiddlerOutputFunctions that know how to read tiddlers from various data formatsTiddlerInputRagtag of small utility functions for manipulating strings and datesUtilsParses wiki text into a parse treeWikiTextParserRepresents a wiki text parse tree. Has methods to compile the parse tree into a JavaScript functionWikiTextParseTreeIndividual wiki text parsing rulesWikiTextRulesmacrosechoinfolisttiddlerversionviewnode.jsbrowserImplements node.js module loading in the browserBootLoader diff --git a/rabbithole/tw5.com/store/High Level Architecture.svg.meta b/rabbithole/tw5.com/store/High Level Architecture.svg.meta deleted file mode 100644 index 826b3d964..000000000 --- a/rabbithole/tw5.com/store/High Level Architecture.svg.meta +++ /dev/null @@ -1,3 +0,0 @@ -title: High Level Architecture.svg -modifier: JeremyRuston -type: image/svg+xml diff --git a/rabbithole/tw5.com/store/Introduction.tid b/rabbithole/tw5.com/store/Introduction.tid index 9608f964f..f16f38a68 100644 --- a/rabbithole/tw5.com/store/Introduction.tid +++ b/rabbithole/tw5.com/store/Introduction.tid @@ -5,7 +5,9 @@ TiddlyWiki5 gains new capabilities through a [[completely rebuilt architecture|T TiddlyWiki5 also functions as the build system for earlier versions of TiddlyWiki, replacing the elderly Cook and Ginsu tools (see https://github.com/TiddlyWiki/cooker for details). See the CommandLineInterface for details. {{alert alert-error{ -Try out the prototype tiddler chooser by swiping into the left edge of the screen (or hover the mouse over the extreme left edge of the browser window). +Try out the prototype touch features: +* The zooming chooser appears by swiping into the left edge of the screen (or hover the mouse over the extreme left edge of the browser window) +* The zooming navigator appears by swiping in from the right edge of the screen (not accessible by mouse) }}} Learning more about TiddlyWiki5: * WaysToUseTiddlyWiki discusses the various configurations in which TiddlyWiki5 can be used diff --git a/rabbithole/tw5.com/store/MacroInternals.tid b/rabbithole/tw5.com/store/MacroInternals.tid deleted file mode 100644 index a02f7bd33..000000000 --- a/rabbithole/tw5.com/store/MacroInternals.tid +++ /dev/null @@ -1,40 +0,0 @@ -title: MacroInternals - -! Macro Fields - -Macros are implemented as conventional JavaScript modules that export a single variable called `macro` that contains these fields: - -|!Field Name |!Description | -|`name` |The name of the macro | -|`params` |A hashmap of the parameters accepted by the macro (see below) | -|`events` |An optional hashmap of event handling functions (see below) | -|`execute` |The macro rendering function (see below) | -|`refreshInDom` |The optional macro rerendering function (see below) | -|`dependentAll` |True if the macro needs access to all available tiddlers | - -! Macro Parameters -The `params` hashmap provides the following fields about each parameter: - -|!Param Field Name |!Description | -|`byName` |Provided if the parameter should be referenced by name. The value can be `true` or `"default"` to indicate that anonymous parameters are acceptable | -|`byPos` |Provided if the parameter should be referenced by its numerical position (0-based) | -|`type` |The type of the parameter, either `text` or `tiddler` (used for dependency tracking) | -|`skinny` |True if the parameter is only dependent on the skinny fields of the target tiddler. The default is `false` which means that the target tiddler is treated as a fat dependency | - -! Macro Rendering -The `execute` function should prepare the macro output. It is invoked with `this` pointing to the MacroNode object representing this macro invocation. - -!Macro Rerendering -The `refreshInDom` function is called with the following parameters: - -|!Param Name |!Description | -|`changes` |Hashmap of `{title: "created|modified|deleted"}` | - -!Macro Event Handlers -Event handlers are called with the following parameters: - -|!Param Name |!Description | -|`event` |The DOM node containing the existing rendering of the macro | - -Event handlers should return `false` if they handle the event (and generally should also call `event.preventDefault()`), and `true` if they do not. - diff --git a/rabbithole/tw5.com/store/PluginMechanism.tid b/rabbithole/tw5.com/store/PluginMechanism.tid new file mode 100644 index 000000000..44019632f --- /dev/null +++ b/rabbithole/tw5.com/store/PluginMechanism.tid @@ -0,0 +1,15 @@ +title: PluginMechanism + +!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. These modules are executed by the kernel, and the resulting diff --git a/rabbithole/tw5.com/store/Testing.tid b/rabbithole/tw5.com/store/Testing.tid deleted file mode 100644 index b1d391654..000000000 --- a/rabbithole/tw5.com/store/Testing.tid +++ /dev/null @@ -1,9 +0,0 @@ -title: Testing - -!Test Scripts - -Three test scripts are provided, each as a Mac OS X `*.sh` bash script and a Windows `*.bat` batch file. In each case they should be run with the current directory set to the directory in which they reside. - -* `test.sh`/`test.bat` cooks the main tiddlywiki.com recipe for TiddlyWiki 2.6.5 and compares it with the results of the old build process (ie, running cook.rb and then opening the file in a browser and performing a 'save changes' operation). It also runs a series of wikifications tests that work off the data in `test/wikitests/`. -* `tw5.sh`/`tw5.bat` builds TiddlyWiki5 as a static HTML file -* `tw5s.sh`/`tw5s.bat` serves TiddlyWiki5 over HTTP on port 8080 diff --git a/rabbithole/tw5.com/store/TiddlyWikiInternals.tid b/rabbithole/tw5.com/store/TiddlyWikiInternals.tid deleted file mode 100644 index e81969df6..000000000 --- a/rabbithole/tw5.com/store/TiddlyWikiInternals.tid +++ /dev/null @@ -1,8 +0,0 @@ -title: TiddlyWikiInternals - -This diagram gives a birds eye view of the JavaScript files making up TiddlyWiki5: - -<> - -See TiddlyWikiArchitecture for an overview of the architecture of the system. -