TiddlyWiki5/readme.md

<div data-tw-render-tiddler='ReadMe'><h1>Welcome to <span data-tw-macro='link' data-tw-render-step='1'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span></h1><div data-tw-macro='tiddler' data-tw-render-step='2'><div data-tw-render-tiddler='HelloThere'><div data-tw-macro='view' data-tw-render-step='1'><a href='HelloThere' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>HelloThere</a></div><br><br>Welcome to <span data-tw-macro='link' data-tw-render-step='2'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span>, a reboot of 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 or as a powerful <code>node.js</code> application.<br><br><span data-tw-macro='link' data-tw-render-step='3'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> is based on the idea of making information more useful by modelling it in the smallest meaningful semantic units, referred to as &quot;tiddlers&quot;.  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.<br><br><span data-tw-macro='link' data-tw-render-step='4'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> has earned an enduring role as a tool that people <span data-tw-macro='link' data-tw-render-step='5'><a href='Raves' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>love using</a></span> for its rich, interactive interface to <span data-tw-macro='link' data-tw-render-step='6'><a href='TiddlyWikiConcepts' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>manipulate complex data</a></span> 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 <span data-tw-macro='link' data-tw-render-step='7'><a href='OpenSourceLicense' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span>, it has bought unprecedented freedom to people to keep their precious information under their own control. <span data-tw-macro='link' data-tw-render-step='8'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> was originally created by <span data-tw-macro='link' data-tw-render-step='9'><a href='JeremyRuston' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JeremyRuston</a></span> and is now a thriving <span data-tw-macro='link' data-tw-render-step='10'><a href='OpenSourceLicense' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span> project with a busy <span data-tw-macro='link' data-tw-render-step='11'><a href='Community' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>Community</a></span> of independent developers.<br><br><span data-tw-macro='link' data-tw-render-step='12'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span> is currently in early beta, which is to say that it is useful but incomplete. You can get involved in the development on <span data-tw-macro='link' data-tw-render-step='13'><a href='GitHub' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>GitHub</a></span> and the discussions on Google Groups:<br><br><span data-tw-macro='link' data-tw-render-step='14'><a href='https://github.com/Jermolene/TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-external'>https://github.com/Jermolene/TiddlyWiki5</a></span><br><span data-tw-macro='link' data-tw-render-step='15'><a href='http://groups.google.com/group/TiddlyWikiDev' class='tw-tiddlylink tw-tiddlylink-external'>http://groups.google.com/group/TiddlyWikiDev</a></sp
node tiddlywiki.js &lt;options&gt;
</code><br>The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a <span data-tw-macro='link' data-tw-render-step='5'><a href='RecipeFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>recipe file</a></span> and all the subrecipes and <span data-tw-macro='link' data-tw-render-step='6'><a href='TiddlerFiles' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>tiddlers</a></span> that it references. The following options are available:<br><table class='twtable'><tbody><tr class='evenRow'><td align='left'><code>--recipe &lt;filepath&gt;</code></td><td align='left'>Loads a specfied <code>.recipe</code> file</td></tr><tr class='oddRow'><td align='left'><code>--load &lt;filepath&gt;</code></td><td align='left'>Load additional tiddlers from 2.x.x <span data-tw-macro='link' data-tw-render-step='7'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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>--savewiki &lt;dirpath&gt;</code></td><td align='left'>Saves all the loaded tiddlers as a single file <span data-tw-macro='link' data-tw-render-step='8'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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 &lt;title&gt; &lt;filename&gt; [&lt;type&gt;]</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 &lt;outdir&gt;</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>--servewiki &lt;port&gt;</code></td><td align='left'>Serve the cooked <span data-tw-macro='link' data-tw-render-step='9'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> over HTTP at <code>/</code></td></tr><tr class='evenRow'><td align='left'><code>--servetiddlers &lt;port&gt;</code></td><td align='left'>Serve individual tiddlers over HTTP at <code>/tiddlertitle</code></td></tr><tr class='oddRow'><td align='left'><code>--wikitest &lt;dir&gt;</code></td><td align='left'>Run wikification tests against the tiddlers in the given directory</td></tr><tr class='evenRow'><td align='left'><code>--dumpstore</code></td><td align='left'>Dump the <span data-tw-macro='link' data-tw-render-step='10'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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 <span data-tw-macro='link' data-tw-render-step='11'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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 <span data-tw-macro='link' data-tw-render-step='12'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> from a recipe:<br><code>
node tiddlywiki.js --recipe tiddlywiki.com/index.recipe --savewiki tmp/
</code><br>This example ginsus a <span data-tw-macro='link' data-tw-render-step='13'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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>--servertiddlers</code> are for different purposes and should not be used together. The former is for <span data-tw-macro='link' data-tw-render-step='14'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> core developers who want to be able to edit the <span data-tw-macro='link' data-tw-render-step='15'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> source files in a text editor and view the results in the browser by clicking refresh; it is slow because it reloads all the <span data-tw-macro='link' data-tw-render-step='16'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> <span data-tw-macro='link' data-tw-render-step='17'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> 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 &quot;text/plain&quot; and &quot;text/html&quot; format and checks the results against the content of the <code>*.html</code> and <code>*.txt</code> files in the same directory.</div></div><br><h1>Testing</h1><div data-tw-macro='tiddler' data-tw-render-step='4'><div data-tw-render-tiddler='Testing'><code>test.sh</code> contains a simple test script that cooks the main tiddlywiki.com recipe 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>.</div></div><br><h1>Architecture</h1><div data-tw-macro='tiddler' data-tw-render-step='5'><div data-tw-render-tiddler='TiddlyWikiArchitecture'><h2> Overview</h2><br>The heart of <span data-tw-macro='link' data-tw-render-step='1'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> 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.<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 <span data-tw-macro='link' data-tw-render-step='2'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span>, and processing CSS.<br><br><h2> Tiddlers</h2><br>Tiddlers are a 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 <span data-tw-macro='link' data-tw-render-step='3'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> <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><br><h2> WikiStore</h2><br>Groups of uniquely titled tiddlers are contained in <span data-tw-macro='link' data-tw-render-step='4'><a href='WikiStore' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiStore</a></span> objects.<br><br>The <span data-tw-macro='link' data-tw-render-step='5'><a href='WikiStore' class='
</pre>The function to render it to <code>text/html</code> might look like this:<br><pre>function() {
	return &quot;&lt;p&gt;Hello World&lt;/p&gt;&quot;;
}
</pre><br>The function can also include calls to the store to incorporate the values of other tiddlers. Consider this tiddler, called <code>HelloThere</code>:<br><pre>Hello &lt;&lt;tiddler Who&gt;&gt;
</pre>And this one called <code>Who</code>:<br><pre>World
</pre>The function to generate <code>HelloThere</code> in <code>text/html</code> might be:<br><pre>function() {
	return [&quot;&lt;p&gt;&quot;,&quot;Hello &quot;, getTiddlerText(&quot;Who&quot;,&quot;text/html&quot;), &quot;&lt;/p&gt;&quot;].join(&quot;&quot;); 
}
</pre><br>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.<br><br>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).<br><br>Evaluated macro parameters are parsed and can be checked for safeness, and then included in the compiled code. For example,<br><pre>Hello &lt;&lt;echo {{2+2}}&gt;&gt;
</pre>Compiles to:<br><pre>function() {
	return [&quot;Hello &quot;,(function(){
		return 2+2;
	})().toString()].join(&quot;&quot;);
}
</pre><br>The compilation process has several steps:<br><ul><li> First, the parse tree is used to generate a <span data-tw-macro='link' data-tw-render-step='14'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> tree</li><li> The <span data-tw-macro='link' data-tw-render-step='15'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> tree is scanned to determine the tiddlers on which this one depends</li><li> Finally, executable <span data-tw-macro='link' data-tw-render-step='16'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> text is generated by walking the <span data-tw-macro='link' data-tw-render-step='17'><a href='JavaScript' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> tree</li></ul></div></div><br><h1>Planned <span data-tw-macro='link' data-tw-render-step='6'><a href='WikiText' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiText</a></span> Features</h1><div data-tw-macro='tiddler' data-tw-render-step='7'><div data-tw-render-tiddler='NewWikiTextFeatures'>It is proposed to extend the existing <span data-tw-macro='link' data-tw-render-step='1'><a href='TiddlyWiki' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> wikitext syntax with the following extensions<br><br><ol><li> Addition of <code>**bold**</code> character formatting</li><li> Addition of <code>`backtick for code`</code> character formatting</li><li> Addition of <span data-tw-macro='link' data-tw-render-step='2'><a href='WikiCreole-style' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiCreole-style</a></span> forced line break, e.g. <code>force\\linebreak</code></li><li> Addition of <span data-tw-macro='link' data-tw-render-step='3'><a href='WikiCreole-style' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiCreole-style</a></span> headings, e.g. <code>==Heading</code></li><li> Addition of <span data-tw-macro='link' data-tw-render-step='4'><a href='WikiCreole-style' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiCreole-style</a></span> headings in tables, e.g. <code>|=|=table|=header|</code></li><li> Addition of white-listed HTML tags intermixed with wikitext</li><li> Addition of <span data-tw-macro='link' data-tw-render-step='5'><a href='WikiCreole-style' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiCreole-style</a></span> pretty links, e.g. <code>[[description -&gt; link]]</code></li><li> Addition of multiline macros, e.g.</li></ol><pre>&lt;&lt;myMacro
param1: Parameter value
param2: value
&quot;unnamed parameter&quot;
param4: ((
A multiline parameter that can go on for as long as it likes
and contain linebreaks.
))
&gt;&gt;
</pre></div></div><br><br><em>This <code>readme</code> file was automatically generated by <span data-tw-macro='link' data-tw-render-step='8'><a href='TiddlyWiki5' class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span></em><br></div>