From 19d8216b710a7f5ddf5802ab8946af27ef8b417e Mon Sep 17 00:00:00 2001 From: Jeremy Ruston Date: Mon, 23 Jan 2012 18:31:24 +0000 Subject: [PATCH] Docs updates --- readme.md | 2 +- tiddlywiki5/tiddlers/HelloThere.tid | 2 +- tiddlywiki5/tiddlers/TiddlerFiles.tid | 35 +++++++------ .../tiddlers/TiddlyWikiArchitecture.tid | 49 ++++--------------- tiddlywiki5/tiddlers/TiddlyWikiInternals.tid | 8 +++ 5 files changed, 39 insertions(+), 57 deletions(-) create mode 100644 tiddlywiki5/tiddlers/TiddlyWikiInternals.tid diff --git a/readme.md b/readme.md index 7bd3ef9ea..c586ef590 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -

Welcome to TiddlyWiki5

Welcome to TiddlyWiki5, an interactive wiki written in JavaScript to run in the browser or under node.js. It is a reboot of TiddlyWiki (http://www.tiddlywiki.com/), the now venerable, reusable non-linear personal web notebook first released in 2004.

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 stories (sequences of tiddlers). TiddlyWiki provides a rich, useful and enjoyable interactive interface for manipulating tiddlers.

TiddlyWiki has earned an enduring place as a tool that people love using for its rich, interactive interface to manipulate complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors. Because people can use it without needing any complicated server infrastructure, and because it 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 project with a busy Community of independent developers.

Usage

TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.

Usage:
+

Welcome to TiddlyWiki5

Welcome to TiddlyWiki5, an interactive wiki written in JavaScript to run in the browser or under node.js. It is a reboot of TiddlyWiki (http://www.tiddlywiki.com/), the now venerable, reusable non-linear personal web notebook first released in 2004.

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 stories (sequences of tiddlers). Tiddlers use a wikitext notation that concisely represents a wide range of text formatting and hypertext features.

TiddlyWiki has earned an enduring place as a tool that people love using for its rich, interactive interface to manipulate complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors. Because people can use it without needing any complicated server infrastructure, and because it 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 project with a busy Community of independent developers.

Usage

TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.

Usage:
node tiddlywiki.js <options>
The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a recipe file and all the subrecipes and tiddlers that it references. The following options are available:
--recipe <filepath>Loads a specfied .recipe file
--load <filepath>Load additional tiddlers from 2.x.x TiddlyWiki files (.html), .tiddler, .tid, .json or other files
--savewiki <dirpath>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
--savetiddler <title> <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
--servewiki <port>Serve the cooked TiddlyWiki over HTTP at /
--servetiddlers <port>Serve individual tiddlers over HTTP at /tiddlertitle
--wikitest <dir>Run wikification tests against the tiddlers in the given directory
--dumpstoreDump the TiddlyWiki store in JSON format
--dumprecipeDump the current recipe in JSON format
--verboseverbose output, useful for debugging

Examples

This example loads the tiddlers from a TiddlyWiki HTML file and makes them available over HTTP:
node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000 diff --git a/tiddlywiki5/tiddlers/HelloThere.tid b/tiddlywiki5/tiddlers/HelloThere.tid index 632078744..3862ddc13 100644 --- a/tiddlywiki5/tiddlers/HelloThere.tid +++ b/tiddlywiki5/tiddlers/HelloThere.tid @@ -3,6 +3,6 @@ modifier: JeremyRuston Welcome to TiddlyWiki5, an interactive wiki written in JavaScript to run in the browser or under node.js. It is a reboot of TiddlyWiki (http://www.tiddlywiki.com/), the now venerable, reusable non-linear personal web notebook first released in 2004. -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 stories (sequences of tiddlers). TiddlyWiki provides a rich, useful and enjoyable interactive interface for manipulating tiddlers. +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 stories (sequences of tiddlers). Tiddlers use a wikitext notation that concisely represents a wide range of text formatting and hypertext features. TiddlyWiki has earned an enduring place as a tool that people [[love using|Raves]] for its rich, interactive interface to [[manipulate complex data|TiddlyWikiConcepts]] with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors. Because people can use it without needing any complicated server infrastructure, and because it is [[open source|OpenSourceLicense]], 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|OpenSourceLicense]] project with a busy [[Community]] of independent developers. diff --git a/tiddlywiki5/tiddlers/TiddlerFiles.tid b/tiddlywiki5/tiddlers/TiddlerFiles.tid index b134929cf..ba1d8a478 100644 --- a/tiddlywiki5/tiddlers/TiddlerFiles.tid +++ b/tiddlywiki5/tiddlers/TiddlerFiles.tid @@ -1,41 +1,46 @@ title: TiddlerFiles modifier: JeremyRuston -Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary {{{.meta}}} file formatted as a sequence of name:value pairs: -{{{ +Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary `.meta` file formatted as a sequence of name:value pairs: +` title: TheTitle modifier: someone -}}} +` !! ~TiddlyWeb-style .tid files These files consist of a sequence of lines containing name:value pairs, a blank line and then the text of the tiddler. For example: -{{{ +` title: MyTiddler modifier: Jeremy This is the text of my tiddler. -}}} -!! TiddlyWiki {{{
}}} .tiddler files +` +//The MIME type `application/x-tiddler` is used internally for these files// +!! TiddlyWiki `
` .tiddler files -Modern {{{*.tiddler}}} files look like this: -{{{ +Modern `*.tiddler` files look like this: +` 
Note that there is an embedded 
 tag, and line feeds are not escaped.
 	
 And, weirdly, there is no HTML encoding of the body.
-}}} -These {{{*.tiddler}}} files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way. +` +These `*.tiddler` files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way. -Older {{{*.tiddler}}} files more closely matched the store format used by TiddlyWiki at the time: -{{{ +Older `*.tiddler` files more closely matched the store format used by TiddlyWiki at the time: +`
This is an old-school .tiddler file, without an embedded <pre> tag.\nNote how the body is "HTML encoded" and new lines are escaped to \\n
-}}} +` +//The MIME type `application/x-tiddler-html-div` is used internally for these files// !! ~TiddlyWeb-style JSON files -These files are a straightforward array of hashmaps of name:value fields. Currently only these known fields are processed: {{{title}}}, {{{text}}}, {{{created}}}, {{{creator}}}, {{{modified}}}, {{{modifier}}}, {{{type}}} and {{{tags}}}. +These files are a straightforward array of hashmaps of name:value fields. Currently only these known fields are processed: `title`, `text`, `created`, `creator`, `modified`, `modifier`, `type` and `tags`. + +//The MIME type `application/json` is used internally for these files// !! TiddlyWiki HTML files -TiddlyWiki HTML files contain a collection of tiddlers encoded in {{{
}}} format. +TiddlyWiki HTML files contain a collection of tiddlers encoded in `
` format. +//The MIME type `application/x-tiddlywiki` is used internally for these files// diff --git a/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid b/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid index e07a0bac1..5ae320452 100644 --- a/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid +++ b/tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid @@ -3,26 +3,10 @@ modifier: JeremyRuston !! Overview +The heart of TiddlyWiki can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated MIME type, the engine can produce a rendering of the tiddler in a new MIME type. +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. -Tiddlers use a special wikitext notation that concisely represents text formatting and hypertext features. - - - -<> - -!! Content Types - -TiddlyWiki uses MIME types to indicate how the text of tiddlers should be interpreted. It uses standard MIME types such as {{{text/plain}}} and {{{text/html}}}, as well as these non-standard types for TiddlyWiki-specific formats: - -* {{{text/x-tiddlywiki}}}: TiddlyWiki-format wiki text -* {{{application/x-tiddlywiki}}}: A TiddlyWiki HTML file containing tiddlers -* {{{application/x-tiddler}}}: A tiddler in TiddlyWeb-style tiddler file format -* {{{application/x-tiddler-html-div}}}: A tiddler in TiddlyWiki {{{
}}} format -In some situations //parameterised MIME types// are used to allow parameters to be specified for the conversion. For example, a tiddler can be rendered to an image of a particular size: -{{{ -image/png({width:500}) -}}} !! Tiddlers Tiddlers are a dictionary of name:value pairs called fields. @@ -31,9 +15,9 @@ The only field that is required is the {{{title}}} field, but useful tiddlers al Values can be a string, an array of strings, or a JavaScript {{{Date}}} object. Hardcoded in the system is the knowledge that the `tags` field is a string array, and that the `modified` and `created` fields are dates. All other fields are strings. -The {{{type}}} field identifies the representation of the tiddler text with a raw, unparameterised, MIME type. +The {{{type}}} field identifies the representation of the tiddler text with a MIME type. -!! WikiStore +!! ~WikiStore Groups of uniquely titled tiddlers are contained in WikiStore objects. @@ -41,11 +25,11 @@ The WikiStore also manages the plugin modules used for macros, and operations li Each WikiStore is connected to another shadow store that is used to provide default content. Under usual circumstances, when an attempt is made to retrieve a tiddler that doesn't exist in the store, the search continues into its shadow store (and so on, if the shadow store itself has a shadow store). -!! WikiStore Events +!! ~WikiStore Events Clients can register event handlers with the WikiStore object. Event handlers can be registered to be triggered for modifications to any tiddler in the store, or with a filter to only be invoked when a particular tiddler or set of tiddlers changes. -Whenever a change is made to a tiddler, the wikistore registers a nexttick handler (if it hasn't already done so). The nexttick handler looks back at all the tiddler changes, and dispatches matching event handlers. +Whenever a change is made to a tiddler, the wikistore registers a `nexttick` handler (if it hasn't already done so). The `nexttick handler` looks back at all the tiddler changes, and dispatches matching event handlers. !! Parsing @@ -56,7 +40,7 @@ TiddlyWiki parses the content of tiddlers to build an internal tree representati * Detecting tiddlers that are orphans with no incoming links * Detecting tiddlers that are referred to but missing -The parse tree is built when needed, and then cached by the WikiStore until the text changes. +The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes. TiddlyWiki5 uses multiple parsers: * Wikitext ({{{text/x-tiddlywiki}}}) @@ -65,16 +49,6 @@ TiddlyWiki5 uses multiple parsers: * JSON ({{{application/json}}}) * Recipe ({{{text/x-tiddlywiki-recipe}}}) -The parsers support several useful conversions: -* Converting wikitext to HTML -* Converting Less-style CSS to real CSS, using tiddler references for variable names -* Whitelisting JavaScript for safe execution of untrusted code - -In the future the architecture might also support: -* Converting JavaScript procedural images to PNGs, using a synthetic graphics context mocking the canvas -* Converting images from one size or format to another -* Minifying JavaScript - !! Compiling and Rendering When the text of a tiddler is requested in a different format than its native type, TiddlyWiki5 compiles a JavaScript function that generates the new format from the text of the tiddler. @@ -107,14 +81,9 @@ function() { Now, the return value of this function can be cached until a tiddler in the dependency chain changes. The function itself can be cached until the tiddler itself changes, or a macro that it uses changes. -The dependency chain is calculated when a tiddler is compiled. Every tiddler that is directly referenced is accumulated (until the point at which it is concluded that it is simpler to mark the tiddler as being dependent on any other tiddler changing). +The dependency chain is calculated when a tiddler is parsed. Every tiddler that is directly referenced is accumulated (until the point at which it is concluded that it is simpler to mark the tiddler as being dependent on any other tiddler changing). -The render function is invoked with `this` pointing to a tiddler object. Parameters to the render function include: -* ''getTiddler(title)'' - a function to retrieve a specified tiddler -* ''renderTiddler(title,type,params)'' - a function to render a tiddler to a specified type -* ''forEachTiddler(sortField,excludeTag,callback)'' - a function to enumerate all tiddlers - -Evaluated macro parameters would be parsed and checked for safeness, and then included in the compiled code. For example, +Evaluated macro parameters are parsed and can bechecked for safeness, and then included in the compiled code. For example, {{{ Hello <> }}} diff --git a/tiddlywiki5/tiddlers/TiddlyWikiInternals.tid b/tiddlywiki5/tiddlers/TiddlyWikiInternals.tid new file mode 100644 index 000000000..e81969df6 --- /dev/null +++ b/tiddlywiki5/tiddlers/TiddlyWikiInternals.tid @@ -0,0 +1,8 @@ +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. +