<divdata-tw-render-tiddler='ReadMe'><h1>Welcome to <spandata-tw-macro='link'data-tw-render-step='1'><ahref='TiddlyWiki5'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span></h1><divdata-tw-macro='tiddler'data-tw-render-step='2'><divdata-tw-render-tiddler='HelloThere'><divdata-tw-macro='view'data-tw-render-step='1'><ahref='HelloThere'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>HelloThere</a></div><br><br>Welcome to <spandata-tw-macro='link'data-tw-render-step='2'><ahref='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><spandata-tw-macro='link'data-tw-render-step='3'><ahref='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 "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.<br><br><spandata-tw-macro='link'data-tw-render-step='4'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> has earned an enduring place as a tool that people <spandata-tw-macro='link'data-tw-render-step='5'><ahref='Raves'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>love using</a></span> for its rich, interactive interface to <spandata-tw-macro='link'data-tw-render-step='6'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='7'><ahref='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. <spandata-tw-macro='link'data-tw-render-step='8'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> was originally created by <spandata-tw-macro='link'data-tw-render-step='9'><ahref='JeremyRuston'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JeremyRuston</a></span> and is now a thriving <spandata-tw-macro='link'data-tw-render-step='10'><ahref='OpenSourceLicense'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>open source</a></span> project with a busy <spandata-tw-macro='link'data-tw-render-step='11'><ahref='Community'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>Community</a></span> of independent developers.<br></div></div><br><h1>Usage</h1><divdata-tw-macro='tiddler'data-tw-render-step='3'><divdata-tw-render-tiddler='CommandLineInterface'><spandata-tw-macro='link'data-tw-render-step='1'><ahref='TiddlyWiki5'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span> can be used on the command line to perform an extensive set of operations based on <spandata-tw-macro='link'data-tw-render-step='2'><ahref='RecipeFiles'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>RecipeFiles</a></span>, <spandata-tw-macro='link'data-tw-render-step='3'><ahref='TiddlerFiles'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>TiddlerFiles</a></span> and <spandata-tw-macro='link'data-tw-render-step='4'><ahref='TiddlyWikiFiles'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWikiFiles</a></span>.<br><br>
</code><br>The command line options are processed sequentially from left to right. Processing pauses during long operations, like loading a <spandata-tw-macro='link'data-tw-render-step='5'><ahref='RecipeFiles'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>recipe file</a></span> and all the subrecipes and <spandata-tw-macro='link'data-tw-render-step='6'><ahref='TiddlerFiles'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves'>tiddlers</a></span> that it references. The following options are available:<br><tableclass='twtable'><tbody><trclass='evenRow'><tdalign='left'><code>--recipe <filepath></code></td><tdalign='left'>Loads a specfied <code>.recipe</code> file</td></tr><trclass='oddRow'><tdalign='left'><code>--load <filepath></code></td><tdalign='left'>Load additional tiddlers from 2.x.x <spandata-tw-macro='link'data-tw-render-step='7'><ahref='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><trclass='evenRow'><tdalign='left'><code>--savewiki <dirpath></code></td><tdalign='left'>Saves all the loaded tiddlers as a single file <spandata-tw-macro='link'data-tw-render-step='8'><ahref='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><trclass='oddRow'><tdalign='left'><code>--savetiddler <title><filename> [<type>]</code></td><tdalign='left'>Save an individual tiddler as a specified MIME type, defaults to <code>text/html</code></td></tr><trclass='evenRow'><tdalign='left'><code>--savetiddlers <outdir></code></td><tdalign='left'>Saves all the loaded tiddlers as <code>.tid</code> files in the specified directory</td></tr><trclass='oddRow'><tdalign='left'><code>--servewiki <port></code></td><tdalign='left'>Serve the cooked <spandata-tw-macro='link'data-tw-render-step='9'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> over HTTP at <code>/</code></td></tr><trclass='evenRow'><tdalign='left'><code>--servetiddlers <port></code></td><tdalign='left'>Serve individual tiddlers over HTTP at <code>/tiddlertitle</code></td></tr><trclass='oddRow'><tdalign='left'><code>--wikitest <dir></code></td><tdalign='left'>Run wikification tests against the tiddlers in the given directory</td></tr><trclass='evenRow'><tdalign='left'><code>--dumpstore</code></td><tdalign='left'>Dump the <spandata-tw-macro='link'data-tw-render-step='10'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> store in JSON format</td></tr><trclass='oddRow'><tdalign='left'><code>--dumprecipe</code></td><tdalign='left'>Dump the current recipe in JSON format</td></tr><trclass='evenRow'><tdalign='left'><code>--verbose</code></td><tdalign='left'>verbose output, useful for debugging</td></tr></tbody></table><h2> Examples</h2>This example loads the tiddlers from a <spandata-tw-macro='link'data-tw-render-step='11'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> HTML file and makes them available over HTTP:<br><code>
</code><br>This example cooks a <spandata-tw-macro='link'data-tw-render-step='12'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> from a recipe:<br><code>
</code><br>This example ginsus a <spandata-tw-macro='link'data-tw-render-step='13'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> into its constituent tiddlers:<br><code>
</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 <spandata-tw-macro='link'data-tw-render-step='14'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span> core developers who want to be able to edit the <spandata-tw-macro='link'data-tw-render-step='15'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='16'><ahref='TiddlyWiki'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki</a></span><spandata-tw-macro='link'data-tw-render-step='17'><ahref='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 "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.</div></div><br><h1>Testing</h1><divdata-tw-macro='tiddler'data-tw-render-step='4'><divdata-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><divdata-tw-macro='tiddler'data-tw-render-step='5'><divdata-tw-render-tiddler='TiddlyWikiArchitecture'><h2> Overview</h2><br>The heart of <spandata-tw-macro='link'data-tw-render-step='1'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='2'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='3'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='4'><ahref='WikiStore'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiStore</a></span> objects.<br><br>The <spandata-tw-macro='link'data-tw-render-step='5'><ahref='WikiStore'class='
</pre>The function to render it to <code>text/html</code> might look like this:<br><pre>function() {
</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 <<tiddler Who>>
</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() {
</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 <<echo {{2+2}}>>
</pre>Compiles to:<br><pre>function() {
return ["Hello ",(function(){
return 2+2;
})().toString()].join("");
}
</pre><br>The compilation process has several steps:<br><ul><li> First, the parse tree is used to generate a <spandata-tw-macro='link'data-tw-render-step='14'><ahref='JavaScript'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> tree</li><li> The <spandata-tw-macro='link'data-tw-render-step='15'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='16'><ahref='JavaScript'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> text is generated by walking the <spandata-tw-macro='link'data-tw-render-step='17'><ahref='JavaScript'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>JavaScript</a></span> tree</li></ul></div></div><br><h1>Planned <spandata-tw-macro='link'data-tw-render-step='6'><ahref='WikiText'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiText</a></span> Features</h1><divdata-tw-macro='tiddler'data-tw-render-step='7'><divdata-tw-render-tiddler='NewWikiTextFeatures'>It is proposed to extend the existing <spandata-tw-macro='link'data-tw-render-step='1'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='2'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='3'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='4'><ahref='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 <spandata-tw-macro='link'data-tw-render-step='5'><ahref='WikiCreole-style'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>WikiCreole-style</a></span> pretty links, e.g. <code>[[description -> link]]</code></li><li> Addition of multiline macros, e.g.</li></ol><pre><<myMacro
</pre></div></div><br><br><em>This <code>readme</code> file was automatically generated by <spandata-tw-macro='link'data-tw-render-step='8'><ahref='TiddlyWiki5'class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing'>TiddlyWiki5</a></span></em><br></div>