mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-27 03:57:21 +00:00
Added link to prototype to top of readme
This commit is contained in:
Jeremy Ruston
parent
ced1ed1d01
commit
269e03caad
@ -1,12 +1,12 @@
|
||||
<div data-tiddler-target='ReadMe' data-tiddler-template='ReadMe' class='tw-tiddler-frame'><h1>Welcome to TiddlyWiki5</h1><div data-tiddler-target='HelloThere' data-tiddler-template='HelloThere' class='tw-tiddler-frame'>Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file in the browser or as a powerful node.js application.<br><br>TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can get involved in the <a href='https://github.com/Jermolene/TiddlyWiki5' classes='tw-tiddlylink tw-tiddlylink-external'>development on GitHub</a> and the discussions on <a href='http://groups.google.com/group/TiddlyWikiDev' classes='tw-tiddlylink tw-tiddlylink-external'>the TiddlyWikiDev Google Group</a>.<br></div><br><h1>Usage</h1><div data-tiddler-target='CommandLineInterface' data-tiddler-template='CommandLineInterface' class='tw-tiddler-frame'>TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.<br><br>The command line interface for TiddlyWiki5 has been designed to support two distinct usages:<br><ul><li> Cooking (or building) old 2.6.x versions of classic TiddlyWiki from the constituent JavaScript components</li><li> Cooking and serving TiddlyWiki5 itself</li></ul><br><h2>Usage</h2><code>
|
||||
<div data-tiddler-target='ReadMe' data-tiddler-template='ReadMe' class='tw-tiddler-frame'><h1>Welcome to TiddlyWiki5</h1><div data-tiddler-target='HelloThere' data-tiddler-template='HelloThere' class='tw-tiddler-frame'>Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file in the browser or as a powerful node.js application.<br><br>TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can try out the prototype at <a href='http://tiddlywiki.com/tiddlywiki5' classes='tw-tiddlylink tw-tiddlylink-external'>http://tiddlywiki.com/tiddlywiki5</a>, get involved in the <a href='https://github.com/Jermolene/TiddlyWiki5' classes='tw-tiddlylink tw-tiddlylink-external'>development on GitHub</a> or the discussions on <a href='http://groups.google.com/group/TiddlyWikiDev' classes='tw-tiddlylink tw-tiddlylink-external'>the TiddlyWikiDev Google Group</a>.<br></div><br><h1>Usage</h1><div data-tiddler-target='CommandLineInterface' data-tiddler-template='CommandLineInterface' class='tw-tiddler-frame'>TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.<br><br>The command line interface for TiddlyWiki5 has been designed to support two distinct usages:<br><ul><li> Cooking (or building) old 2.6.x versions of classic TiddlyWiki from the constituent JavaScript components</li><li> Cooking and serving TiddlyWiki5 itself</li></ul><br><h2>Usage</h2><code>
|
||||
node tiddlywiki.js <options>
|
||||
</code><br>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, and then resumes with the next command line option in sequence.<br><br>The state that is carried between options is as follows:<br><ul><li> The set of tiddlers that are currently loaded into memory</li><li> The recipe file last used to load tiddlers (recipe files are used primarily to manage shadow tiddlers)</li><li> The TiddlerFileStore used to store the main content tiddlers. This is independent of the current recipe</li></ul><br>The following options are available:<br><table class='table'><tbody><tr class='evenRow'><td align='left'><code>--recipe <filepath></code></td><td align='left'>Loads a specfied <code>.recipe</code> file</td></tr><tr class='oddRow'><td align='left'><code>--load <filepath></code></td><td align='left'>Load additional tiddlers from 2.x.x TiddlyWiki files (<code>.html</code>), <code>.tiddler</code>, <code>.tid</code>, <code>.json</code> or other files</td></tr><tr class='evenRow'><td align='left'><code>--store <dirpath></code></td><td align='left'>Load a specified TiddlerFileStore</td></tr><tr class='oddRow'><td align='left'><code>--savewiki <dirpath></code></td><td align='left'>Saves all the loaded tiddlers as a single file TiddlyWiki called <code>index.html</code> and an RSS feed called <code>index.xml</code> in a new directory of the specified name</td></tr><tr class='evenRow'><td align='left'><code>--savetiddler <title> <filename> [<type>]</code></td><td align='left'>Save an individual tiddler as a specified MIME type, defaults to <code>text/html</code></td></tr><tr class='oddRow'><td align='left'><code>--savetiddlers <outdir></code></td><td align='left'>Saves all the loaded tiddlers as <code>.tid</code> files in the specified directory</td></tr><tr class='evenRow'><td align='left'><code>--savehtml <outdir></code></td><td align='left'>Saves all the loaded tiddlers as static, unstyled <code>.html</code> files in the specified directory</td></tr><tr class='oddRow'><td align='left'><code>--servewiki <port></code></td><td align='left'>Serve the cooked TiddlyWiki over HTTP at <code>/</code></td></tr><tr class='evenRow'><td align='left'><code>--servetiddlers <port></code></td><td align='left'>Serve individual tiddlers over HTTP at <code>/tiddlertitle</code></td></tr><tr class='oddRow'><td align='left'><code>--wikitest <dir> [save]</code></td><td align='left'>Run wikification tests against the tiddlers in the given directory. Include the <code>save</code> flag to save the test result files as the new targets</td></tr><tr class='evenRow'><td align='left'><code>--dumpstore</code></td><td align='left'>Dump the TiddlyWiki store in JSON format</td></tr><tr class='oddRow'><td align='left'><code>--dumprecipe</code></td><td align='left'>Dump the current recipe in JSON format</td></tr><tr class='evenRow'><td align='left'><code>--verbose</code></td><td align='left'>verbose output, useful for debugging</td></tr></tbody></table><h2> Examples</h2>This example loads the tiddlers from a TiddlyWiki HTML file and makes them available over HTTP:<br><code>
|
||||
</code><br>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, and then resumes with the next command line option in sequence.<br><br>The state that is carried between options is as follows:<br><ul><li> The set of tiddlers that are currently loaded into memory</li><li> The recipe file last used to load tiddlers (recipe files are used primarily to manage shadow tiddlers)</li><li> The TiddlerFileStore used to store the main content tiddlers. This is independent of the current recipe</li></ul><br>The following options are available:<br><table class='table'><tbody><tr class='evenRow'><td align='left'><code>--recipe <filepath></code></td><td align='left'>Loads a specfied <code>.recipe</code> file</td></tr><tr class='oddRow'><td align='left'><code>--load <filepath></code></td><td align='left'>Load additional tiddlers from 2.x.x TiddlyWiki files (<code>.html</code>), <code>.tiddler</code>, <code>.tid</code>, <code>.json</code> or other files</td></tr><tr class='evenRow'><td align='left'><code>--store <dirpath></code></td><td align='left'>Load a specified TiddlerFileStore</td></tr><tr class='oddRow'><td align='left'><code>--links none</code></td><td align='left'>Determines how links will be generated by subsequent options. See below for details</td></tr><tr class='evenRow'><td align='left'><code>--savewiki <dirpath></code></td><td align='left'>Saves all the loaded tiddlers as a single file TiddlyWiki called <code>index.html</code> and an RSS feed called <code>index.xml</code> in a new directory of the specified name</td></tr><tr class='oddRow'><td align='left'><code>--savetiddler <title> <filename> [<type>]</code></td><td align='left'>Save an individual tiddler as a specified MIME type, defaults to <code>text/html</code></td></tr><tr class='evenRow'><td align='left'><code>--savetiddlers <outdir></code></td><td align='left'>Saves all the loaded tiddlers as <code>.tid</code> files in the specified directory</td></tr><tr class='oddRow'><td align='left'><code>--savehtml <outdir></code></td><td align='left'>Saves all the loaded tiddlers as static, unstyled <code>.html</code> files in the specified directory</td></tr><tr class='evenRow'><td align='left'><code>--servewiki <port></code></td><td align='left'>Serve the cooked TiddlyWiki over HTTP at <code>/</code></td></tr><tr class='oddRow'><td align='left'><code>--servetiddlers <port></code></td><td align='left'>Serve individual tiddlers over HTTP at <code>/tiddlertitle</code></td></tr><tr class='evenRow'><td align='left'><code>--wikitest <dir> [save]</code></td><td align='left'>Run wikification tests against the tiddlers in the given directory. Include the <code>save</code> flag to save the test result files as the new targets</td></tr><tr class='oddRow'><td align='left'><code>--dumpstore</code></td><td align='left'>Dump the TiddlyWiki store in JSON format</td></tr><tr class='evenRow'><td align='left'><code>--dumprecipe</code></td><td align='left'>Dump the current recipe in JSON format</td></tr><tr class='oddRow'><td align='left'><code>--verbose</code></td><td align='left'>verbose output, useful for debugging</td></tr></tbody></table><h2> Examples</h2>This example loads the tiddlers from a TiddlyWiki HTML file and makes them available over HTTP:<br><code>
|
||||
node tiddlywiki.js --load mywiki.html --servewiki 127.0.0.1:8000
|
||||
</code><br>This example cooks a TiddlyWiki from a recipe:<br><code>
|
||||
node tiddlywiki.js --recipe tiddlywiki.com/index.recipe --savewiki tmp/
|
||||
</code><br>This example ginsus a TiddlyWiki into its constituent tiddlers:<br><code>
|
||||
node tiddlywiki.js --load mywiki.html --savetiddlers tmp/tiddlers
|
||||
</code><br><h2> Notes</h2><code>--servewiki</code> and <code>--servetiddlers</code> 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.<br><br><code>--wikitest</code> looks for <code>*.tid</code> 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 <code>*.html</code> and <code>*.txt</code> files in the same directory.<br></div><br><h1>Testing</h1><div data-tiddler-target='Testing' data-tiddler-template='Testing' class='tw-tiddler-frame'><h1>Test Scripts</h1><br>Three test scripts are provided, each as a Mac OS X <code>*.sh</code> bash script and a Windows <code>*.bat</code> batch file. In each case they should be run with the current directory set to the directory in which they reside.<br><br><ul><li> <code>test.sh</code>/<code>test.bat</code> 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 <code>test/wikitests/</code>.</li><li> <code>tw5.sh</code>/<code>tw5.bat</code> builds TiddlyWiki5 as a static HTML file</li><li> <code>tw5s.sh</code>/<code>tw5s.bat</code> serves TiddlyWiki5 over HTTP on port 8080</li></ul></div><br><h1>Architecture</h1><div data-tiddler-target='TiddlyWikiArchitecture' data-tiddler-template='TiddlyWikiArchitecture' class='tw-tiddler-frame'><h2> Overview</h2><br>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. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.<br><br>The most important transformations are from <code>text/x-tiddlywiki</code> wikitext into <code>text/html</code> or <code>text/plain</code> 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.<br><br>The key feature of wikitext is the ability to include one tiddler within another (usually referred to as <em>transclusion</em>). For example, one could have a tiddler called <em>Disclaimer</em> that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call <code><<tiddler Disclaimer>></code>. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the TiddlyWiki5 design.<br><br>It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building TiddlyWiki's user interface itself. Consider, for example, the StoryMacro in its simplest form:<br><pre><<story story:MyStoryTiddler>>
|
||||
</code><br><h2> Notes</h2><code>--servewiki</code> and <code>--servetiddlers</code> 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.<br><br><code>--wikitest</code> looks for <code>*.tid</code> 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 <code>*.html</code> and <code>*.txt</code> files in the same directory.<br><br><code>--links</code> controls the way that links are generated. Currently, the only option supported is:<br><br> <code>none</code>: Tiddler links are disabled<br><br><br></div><br><h1>Testing</h1><div data-tiddler-target='Testing' data-tiddler-template='Testing' class='tw-tiddler-frame'><h1>Test Scripts</h1><br>Three test scripts are provided, each as a Mac OS X <code>*.sh</code> bash script and a Windows <code>*.bat</code> batch file. In each case they should be run with the current directory set to the directory in which they reside.<br><br><ul><li> <code>test.sh</code>/<code>test.bat</code> 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 <code>test/wikitests/</code>.</li><li> <code>tw5.sh</code>/<code>tw5.bat</code> builds TiddlyWiki5 as a static HTML file</li><li> <code>tw5s.sh</code>/<code>tw5s.bat</code> serves TiddlyWiki5 over HTTP on port 8080</li></ul></div><br><h1>Architecture</h1><div data-tiddler-target='TiddlyWikiArchitecture' data-tiddler-template='TiddlyWikiArchitecture' class='tw-tiddler-frame'><h2> Overview</h2><br>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. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.<br><br>The most important transformations are from <code>text/x-tiddlywiki</code> wikitext into <code>text/html</code> or <code>text/plain</code> 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.<br><br>The key feature of wikitext is the ability to include one tiddler within another (usually referred to as <em>transclusion</em>). For example, one could have a tiddler called <em>Disclaimer</em> that contains the boilerplate of a legal disclaimer, and then include it within lots of different tiddlers with the macro call <code><<tiddler Disclaimer>></code>. This simple feature brings great power in terms of encapsulating and reusing content, and evolving a clean, usable implementation architecture to support it efficiently is a key objective of the TiddlyWiki5 design.<br><br>It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building TiddlyWiki's user interface itself. Consider, for example, the StoryMacro in its simplest form:<br><pre><<story story:MyStoryTiddler>>
|
||||
</pre>The story macro looks for a list of tiddler titles in the tiddler <code>MyStoryTiddler</code>, and displays them in sequence. The subtle part is that subsequently, if <code>MyStoryTiddler</code> changes, the <code><<story>></code> macro is selectively re-rendered. So, to navigate to a new tiddler, code merely needs to add the name of the tiddler and a line break to the top of <code>MyStoryTiddler</code>:<br><pre>var storyTiddler = store.getTiddler("MyStoryTiddler");
|
||||
store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + "\n" + storyTiddler.text}));
|
||||
</pre>The mechanisms that allow all of this to work are fairly intricate. The sections below progressively build the key architectural concepts of TiddlyWiki5 in a way that should provide a good basis for exploring the code directly.<br><h2> Tiddlers</h2>Tiddlers are an immutable dictionary of name:value pairs called fields.<br><br>The only field that is required is the <code>title</code> field, but useful tiddlers also have a <code>text</code> field, and some or all of the standard fields <code>modified</code>, <code>modifier</code>, <code>created</code>, <code>creator</code>, <code>tags</code> and <code>type</code>.<br><br>Hardcoded in the system is the knowledge that the <code>tags</code> field is a string array, and that the <code>modified</code> and <code>created</code> fields are JavaScript <code>Date</code> objects. All other fields are strings.<br><br>The <code>type</code> field identifies the representation of the tiddler text with a MIME type.<br><h2> WikiStore</h2>Groups of uniquely titled tiddlers are contained in WikiStore objects.<br><br>The WikiStore also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.<br><br>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).<br><h2> WikiStore Events</h2>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.<br><br>Whenever a change is made to a tiddler, the wikistore registers a <code>nexttick</code> handler (if it hasn't already done so). The <code>nexttick</code> handler looks back at all the tiddler changes, and dispatches any matching event handlers. <br><h2> Parsing and Rendering</h2>TiddlyWiki parses the content of tiddlers to build an internal tree representation that is used for several purposes:<br><ul><li> Rendering a tiddler to other formats (e.g. converting wikitext to HTML)</li><li> Detecting outgoing links from a tiddler, and from them...</li><li> ...computing incoming links to a tiddler</li><li> Detecting tiddlers that are orphans with no incoming links</li><li> Detecting tiddlers that are referred to but missing</li></ul>The parse tree is built when needed, and then cached by the WikiStore until the tiddler changes.<br><br>TiddlyWiki5 uses multiple parsers:<br><ul><li> Wikitext (<code>text/x-tiddlywiki</code>) in <code>js/WikiTextParser.js</code></li><li> JavaScript (<code>text/javascript</code>) in <code>js/JavaScriptParser.js</code></li><li> Images (<code>image/png</code> and <code>image/jpg</code>) in <code>js/ImageParser.js</code></li><li> JSON (<code>application/json</code>) in <code>js/JSONParser.js</code></li></ul>Additional parsers are planned:<br><ul><li> CSS (<code>text/css</code>)</li><li> Recipe (<code>text/x-tiddlywiki-recipe</code>)</li></ul>One global instance of each parser is instantiated in <code>js/App.js</code> and registered with the main WikiStore object.<br><br>The parsers are all used the same way:<br><pre class='javascript-source'><span class='javascript-keyword'>var</span> <span class='javascript-identifier'>parseTree</span> <span class='javascript-punctuator'>=</span> <span class='javascript-identifier'>parser</span><span class='javascript-punctuator'>.</span><span class='javascript-identifier'>parse</span><span class='javascript-punctuator'>(</span><span class='javascript-identifier'>type</span><span class='javascript-punctuator'>,</span><span class='javascript-identifier'>text</span><span class='javascript-punctuator'>)</span> <span class='javascript-comment javascript-line-comment'>// Parses the text and returns a parse tree object
|
||||
|
||||
@ -3,4 +3,4 @@ modifier: JeremyRuston
|
||||
|
||||
Welcome to TiddlyWiki5, a reboot of TiddlyWiki, the venerable, reusable non-linear personal web notebook first released in 2004. It is a complete interactive wiki that can run from a single HTML file in the browser or as a powerful [[node.js application|What is node.js?]].
|
||||
|
||||
TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can get involved in the [[development on GitHub|https://github.com/Jermolene/TiddlyWiki5]] and the discussions on [[the TiddlyWikiDev Google Group|http://groups.google.com/group/TiddlyWikiDev]].
|
||||
TiddlyWiki5 is currently in early beta, which is to say that it is useful but incomplete. You can try out the prototype at http://tiddlywiki.com/tiddlywiki5, get involved in the [[development on GitHub|https://github.com/Jermolene/TiddlyWiki5]] or the discussions on [[the TiddlyWikiDev Google Group|http://groups.google.com/group/TiddlyWikiDev]].
|
||||
|
||||
Loading…
Reference in New Issue
Block a user