mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2025-02-05 05:30:02 +00:00
Code Issues Releases Wiki Activity

Readme updates

Browse Source
This commit is contained in:
Jeremy Ruston 2013-03-01 16:25:09 +00:00
parent f6faa156a5
commit f9e6a61450
2 changed files with 50 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
editions/tw5.com/tiddlers/ReadMe.tid
View File

@ -7,14 +7,6 @@ tags: introduction
! Usage ! Usage
{{CommandLineInterface}} {{Getting started with TiddlyWiki under node.js}}
! Architecture
{{TiddlyWikiArchitecture}}
! Boot Mechanism
{{BootMechanism}}
//This `readme` file was automatically generated by TiddlyWiki5// //This `readme` file was automatically generated by TiddlyWiki5//

133
readme.md
View File

@ -24,94 +24,59 @@ Join the discussions on <a class='tw-tiddlylink tw-tiddlylink-external' href='ht
the TiddlyWikiDev Google Group</a></li><li> the TiddlyWikiDev Google Group</a></li><li>
Follow <a class='tw-tiddlylink tw-tiddlylink-external' href='http://twitter.com/#!/TiddlyWiki'> Follow <a class='tw-tiddlylink tw-tiddlylink-external' href='http://twitter.com/#!/TiddlyWiki'>
@TiddlyWiki on Twitter</a> for the latest news</li></ul></div><h1 class=''> @TiddlyWiki on Twitter</a> for the latest news</li></ul></div><h1 class=''>
Usage</h1><div class='tw-transclude tw-tiddler-missing'> Usage</h1><div class='tw-transclude'>
</div><h1 class=''> <p>
Architecture</h1><div class='tw-transclude'>
<h1 class=''>
Overview</h1><p>
The heart of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
TiddlyWiki</a> can be seen as an extensible representation transformation engine. Given the text of a tiddler and its associated <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='ContentType'>
ContentType</a>, the engine can produce a rendering of the tiddler in a new <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='ContentType'>
ContentType</a>. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.</p><p>
The primary use of the engine is to convert raw <code>
text/vnd.tiddlywiki</code> <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='WikiText'>
WikiText</a> into a <code>
text/html</code> or <code>
text/plain</code> representation for display. The transclusion and templating features of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='WikiText'>
WikiText</a> allow the engine to also be used to generate <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
TiddlyWiki</a> HTML files from raw tiddlers.</p><p>
You can explore this mechanism by opening the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>
JavaScript</a> console in your browser. Typing this command will replace the text of the tiddler <code>
HelloThere</code> with new content:</p><pre>
$tw.wiki.addTiddler({title: &quot;HelloThere&quot;, text: &quot;This is some new content&quot;});</pre><p>
If the tiddler <code>
HelloThere</code> is visible then you'll see it instantly change to reflect the new content. If you create a tiddler that doesn't currently exist (like <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='IntentionallyMissingTiddler'>
IntentionallyMissingTiddler</a>) then you'll see any displayed links to it instantly change from italicised to normal:</p><pre>
$tw.wiki.addTiddler({title: &quot;IntentionallyMissingTiddler&quot;, text: &quot;This tiddler now exists&quot;});</pre><p>
If you're interested in understanding more about the internal operation of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
TiddlyWiki</a>, it is recommended that you review the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='Docs'>
Docs</a> and read the code &ndash; start with the boot kernel <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='%24%3A%2Fcore%2Fboot.js'>
$:/core/boot.js</a>.
</p></div><h1 class=''>
Boot Mechanism</h1><div class='tw-transclude'>
<h1 class=''>
Introduction</h1><p>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki5'> <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki5'>
TiddlyWiki5</a> is based on a 1,000 line boot kernel that runs on node.js or in the browser, with all other functionality added via dynamically loaded modules.</p><p> TiddlyWiki5</a> can be used on the command line to perform an extensive set of operations based on tiddlers, <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlerFiles'>
The kernel boots just enough of the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'> TiddlerFiles</a> and <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWikiFiles'>
TiddlyWiki</a> environment to allow it to load tiddlers and execute <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'> TiddlyWikiFiles</a>. For example, this loads the tiddlers from a <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
JavaScript</a> modules. Plugin modules are written like <code> TiddlyWiki</a> HTML file and then saves one of them in HTML:</p><pre>
node.js</code> modules.</p><p> node tiddlywiki.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.html</pre><h2 class=''>
There are many <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='ModuleType'> Usage</h2><p>
different types of module</a>: parsers, serializers, deserializers, macros etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module that knows how to handle the <code> Running <code>
tags</code> field, and another that knows how to handle the special behaviour of the <code> tiddlywiki.js</code> from the command line boots the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
modified</code> and <code> TiddlyWiki</a> kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments from left to right. The arguments are separated with spaces.</p><p>
created</code> fields.</p><p> The first argument is the optional path to the wiki directory to be loaded. If not present, then the current directory is used.</p><p>
Some plugin modules have further sub-plugins: the wikitext parser, for instance, accepts rules as individual plugin modules.</p><h1 class=''> The commands and their individual arguments follow, each command being identified by the prefix <code>
Plugins and Modules</h1><p> --</code>.</p><pre>
In <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki5'> node tiddlywiki.js [&lt;wikipath&gt;] [--&lt;command&gt; [&lt;arg&gt;[,&lt;arg&gt;]]]</pre><h2 class=''>
TiddlyWiki5</a>, <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='Plugins'> Batch Files</h2><p>
Plugins</a> are bundles of tiddlers that are distributed and managed as one; <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='Modules'> For trying <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki5'>
Modules</a> are <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'> TiddlyWiki5</a> out under node.js, several batch files are provided:</p><ul>
JavaScript</a> tiddlers with a module type identifying when and how they should be executed.</p><p>
The tiddler <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='%24%3A%2Fcore%2Fboot.js'>
$:/core/boot.js</a> is a barebones <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
TiddlyWiki</a> kernel that is just sufficient to load the core plugin modules and trigger a startup module to load up the rest of the application.</p><p>
The kernel includes:</p><ul>
<li> <li>
Several short shared utility functions</li><li>
A handful of methods implementing the plugin module mechanism</li><li>
The <code>
$tw.Tiddler</code> class (and field definition plugins)</li><li>
The <code>
$tw.Wiki</code> class (and tiddler deserialization methods)</li><li>
Code for the browser to load tiddlers from the HTML DOM</li><li>
Code for the server to load tiddlers from the file system</li></ul><p>
Each module is an ordinary <code>
node.js</code>-style module, using the <code>
require()</code> function to access other modules and the <code>
exports</code> global to return <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>
JavaScript</a> values. The boot kernel smooths over the differences between <code>
node.js</code> and the browser, allowing the same plugin modules to execute in both environments.</p><p>
In the browser, <code>
core/boot.js</code> is packed into a template HTML file that contains the following elements in order:</p><ul>
<li>
Ordinary and shadow tiddlers, packed as HTML <code>
&lt;DIV&gt;</code> elements</li><li>
<code> <code>
core/bootprefix.js</code>, containing a few lines to set up the plugin environment</li><li> bld.sh</code> builds the new <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'> TiddlyWiki</a> 5 HTML file</li><li>
JavaScript</a> modules, packed as HTML <code>
&lt;SCRIPT&gt;</code> blocks</li><li>
<code> <code>
core/boot.js</code>, containing the boot kernel</li></ul><p> 2bld.sh</code> builds <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>
On the server, <code> TiddlyWiki</a> 2.6.5 from its original source</li></ul><h2 class=''>
core/boot.js</code> is executed directly. It uses the <code> Commands</h2><p>
node.js</code> local file API to load plugins directly from the file system in the <code> The following commands are available:</p><div class='tw-list-frame'>
core/modules</code> directory. The code loading is performed synchronously for brevity (and because the system is in any case inherently blocked until plugins are loaded).</p><p> <div class='tw-list-element'>
The boot kernel sets up the <code> <span class='tw-transclude'>
$tw</code> global variable that is used to store all the state data of the system. <span class='tw-view-link'>
</p></div><p> <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='DumpCommand'>
DumpCommand</a></span></span></div><div class='tw-list-element'>
<span class='tw-transclude'>
<span class='tw-view-link'>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='LoadCommand'>
LoadCommand</a></span></span></div><div class='tw-list-element'>
<span class='tw-transclude'>
<span class='tw-view-link'>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='SaveTiddlerCommand'>
SaveTiddlerCommand</a></span></span></div><div class='tw-list-element'>
<span class='tw-transclude'>
<span class='tw-view-link'>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='ServerCommand'>
ServerCommand</a></span></span></div><div class='tw-list-element'>
<span class='tw-transclude'>
<span class='tw-view-link'>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='VerboseCommand'>
VerboseCommand</a></span></span></div><div class='tw-list-element'>
<span class='tw-transclude'>
<span class='tw-view-link'>
<a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='VersionCommand'>
VersionCommand</a></span></span></div></div></div><p>
<em> <em>
This <code> This <code>
readme</code> file was automatically generated by <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki5'> readme</code> file was automatically generated by <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki5'>