mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-11-27 03:57:21 +00:00
Code Issues Releases Wiki Activity

Docs updates

Browse Source
This commit is contained in:
Jeremy Ruston 2012-03-03 18:06:24 +00:00
parent d6397e9d84
commit 5124de8d25
6 changed files with 58 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
readme.md
View File

File diff suppressed because one or more lines are too long

1
tiddlywiki5/tiddlers/CommandLineInterface.tid
View File

@ -13,6 +13,7 @@ The command line options are processed sequentially from left to right. Processi
|`--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 |
|`--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>` |Run wikification tests against the tiddlers in the given directory |

29
tiddlywiki5/tiddlers/ImageTests.tid
View File

@ -1,9 +1,38 @@
title: ImageTests
This tiddler demonstrates different ways of displaying images
{{{
<<tiddler [[Motovun Jack.jpg]]>>
}}}
Appears as:
<<tiddler [[Motovun Jack.jpg]]>>
{{{
<<image [[Motovun Jack.jpg]] text:"A kitten">>
}}}
Appears as:
<<image [[Motovun Jack.jpg]] text:"A kitten">>
{{{
[img[Motovun Jack.jpg]]
}}}
Appears as:
[img[Motovun Jack.jpg]]
{{{
[img[tooltip|Motovun Jack.jpg]]
}}}
Appears as:
[img[tooltip|Motovun Jack.jpg]]
{{{
[img[tooltip|Motovun Jack.jpg][http://google.com/]]
}}}
Appears as:
[img[tooltip|Motovun Jack.jpg][http://google.com/]]
{{{
<<tiddler [[Tiddler Fishes.svg]]>>
}}}
Appears as:
<<tiddler [[Tiddler Fishes.svg]]>>
{{{
[img[Tiddler Fishes.svg]]
}}}
Appears as:
[img[Tiddler Fishes.svg]]

29
tiddlywiki5/tiddlers/MacroInternals.tid
View File

@ -9,8 +9,8 @@ Macros are implemented as conventional JavaScript modules that export a single v
|`types` |An array of the MIME types that the macro can render |
|`params` |A hashmap of the parameters accepted by the macro (see below) |
|`events` |An optional hashmap of event handling functions (see below) |
|`render` |The macro rendering function (see below) |
|`rerender` |The optional macro rerendering function (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
@ -18,41 +18,24 @@ 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) |
|`rel` |The relationship for parameters of type tiddler - either "link" or "include" |
|`optional` |`true` if the parameter is optional |
|`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 `render` function should return the new text representation of the macro output. It is called with the following parameters:
|!Param Name |!Description |
|`type` |The target MIME type for rendering the macro |
|`tiddler` |The tiddler in whose context the macro is being rendered |
|`store` |The `WikiStore` object to be used |
|`params` |The macro parameters as a hashmap |
|`content` |The rendered text of the children of the macro |
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 `rerender` function is called with the following parameters:
The `refreshInDom` function is called with the following parameters:
|!Param Name |!Description |
|`node` |The DOM node containing the existing rendering of the macro |
|`changes` |Hashmap of `{title: "created|modified|deleted"}` |
|`type` |The target MIME type for rendering the macro |
|`tiddler` |The tiddler in whose context the macro is being rendered |
|`store` |The `WikiStore` object to be used |
|`params` |The macro parameters as a hashmap |
|`content` |The rendered text of the children of the macro |
!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 |
|`node` |Hashmap of `{title: "created|modified|deleted"}` |
|`tiddler` |The tiddler in whose context the macro is being rendered |
|`store` |The `WikiStore` object to be used |
|`params` |The macro parameters as a hashmap |
Event handlers should return `false` if they handle the event (and generally should also call `event.preventDefault()`), and `true` if they do not.

8
tiddlywiki5/tiddlers/NewWikiTextFeatures.tid
View File

@ -1,7 +1,7 @@
title: NewWikiTextFeatures
modifier: JeremyRuston
It is proposed to extend the existing TiddlyWiki wikitext syntax with the following extensions
It is proposed to extend the existing TiddlyWiki WikiText syntax with the following extensions
# Addition of {{{**bold**}}} character formatting
# Addition of {{{`backtick for code`}}} character formatting
@ -22,3 +22,9 @@ and contain linebreaks.
))
>>
}}}
# Addition of typed text blocks, e.g.
{{{
$$$.js
return "This will have syntax highlighting applied"
$$$
}}}

64
tiddlywiki5/tiddlers/TiddlyWikiArchitecture.tid
View File

@ -37,7 +37,7 @@ Each WikiStore is connected to another shadow store that is used to provide defa
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 any matching event handlers.
!! Parsing and Compiling
!! Parsing and Rendering
TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:
* Rendering a tiddler to other formats (e.g. converting wikitext to HTML)
* Detecting outgoing links from a tiddler, and from them...
@ -54,12 +54,12 @@ TiddlyWiki5 uses multiple parsers:
Additional parsers are planned:
* CSS ({{{text/css}}})
* Recipe ({{{text/x-tiddlywiki-recipe}}})
One global instance of each parser is instantiated in `js/App.js` and registered with the main WikiStore object. In some cases the constructors require special parameters or options (eg, the JavaScript parser requires the [[PEG.JS]] JavaScript parser text).
One global instance of each parser is instantiated in `js/App.js` and registered with the main WikiStore object.
The parsers are all used the same way:
{{{
$$$.js
var parseTree = parser.parse(type,text) // Parses the text and returns a parse tree object
}}}
$$$
The parse tree object exposes the following fields:
$$$.js
var renderer = parseTree.compile(type); // Compiles the parse tree into a renderer for the specified MIME type
@ -69,12 +69,11 @@ $$$
The dependencies are returned as an object like this:
{{{
{
link: {"tiddlertitle1": 2, "tiddlertitle2": 3},
include: {"tiddlertitle3": 5},
tiddlers: {"tiddlertitle1": true, "tiddlertitle2": false},
dependentAll: false
}
}}}
The `link` and `include` fields are hashmaps of the title of each tiddler that is linked or included in the current one. For the tiddler to be subsequently rendered correctly, the linked tiddlers must be present, at least in skinny form, and the included tiddlers must be fully loaded.
The `tiddlers` field is a hashmap of the title of each tiddler that is linked or included in the current one. The value is `true` if the tiddler is a //'fat'// dependency (ie the text is included in some way) or `false` if the tiddler is a //`skinny`// dependency.
The `dependentAll` field is used to indicate that the tiddler contains a macro that scans the entire pool of tiddlers (for example the `<<list>>` macro), and is potentially dependent on any of them. The effect is that the tiddler should be rerendered whenever any other tiddler changes.
!! Rendering
@ -106,55 +105,4 @@ The parameters to `rerender()` are:
|renderStep |See below |
Currently, the only macro that supports rerendering is the `<<story>>` macro; all other macros are rerendered by calling the ordinary `render()` method again. The reason that the `<<story>>` macro goes to the trouble of having a `rerender()` method is so that it can be carefully selective about not disturbing tiddlers in the DOM that aren't affected by the change. If there were, for instance, a video playing in one of the open tiddlers it would be reset to the beginning if the tiddler were rerendered.
----
//The remaining text is from an earlier draft, and is in the process of being updated//
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.
So, a simple tiddler in {{{application/x-tiddlywiki}}} format might read:
{{{
Hello World
}}}
The function to render it to {{{text/html}}} might look like this:
{{{
function() {
return "<p>Hello World</p>";
}
}}}
The function can also include calls to the store to incorporate the values of other tiddlers. Consider this tiddler, called {{{HelloThere}}}:
{{{
Hello <<tiddler Who>>
}}}
And this one called {{{Who}}}:
{{{
World
}}}
The function to generate {{{HelloThere}}} in {{{text/html}}} might be:
{{{
function() {
return ["<p>","Hello ", getTiddlerText("Who","text/html"), "</p>"].join("");
}
}}}
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 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).
Evaluated macro parameters are parsed and can be checked for safeness, and then included in the compiled code. For example,
{{{
Hello <<echo {{2+2}}>>
}}}
Compiles to:
{{{
function() {
return ["Hello ",(function(){
return 2+2;
})().toString()].join("");
}
}}}
The compilation process has several steps:
* First, the parse tree is used to generate a JavaScript tree
* The JavaScript tree is scanned to determine the tiddlers on which this one depends
* Finally, executable JavaScript text is generated by walking the JavaScript tree