Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

A quick sweep for missing or inaccurate code comments

  • Loading branch information...
commit 34edb487842e8f57358a3cb9f2506839b9baf582 1 parent 6a7a5a2
@Jermolene authored
Showing with 105 additions and 51 deletions.
  1. +1 −1  core/modules/commands/dump.js
  2. +1 −1  core/modules/commands/load.js
  3. +1 −1  core/modules/commands/savetiddler.js
  4. +1 −14 core/modules/commands/server.js
  5. +2 −0  core/modules/macros/button.js
  6. +2 −0  core/modules/macros/chooser.js
  7. +2 −0  core/modules/macros/download.js
  8. +2 −0  core/modules/macros/echo.js
  9. +2 −0  core/modules/macros/edit/edit.js
  10. +2 −0  core/modules/macros/edit/editors/bitmapeditor.js
  11. +2 −0  core/modules/macros/edit/editors/texteditor.js
  12. +2 −0  core/modules/macros/image.js
  13. +2 −0  core/modules/macros/include.js
  14. +2 −0  core/modules/macros/list.js
  15. +1 −1  core/modules/macros/story/views/scroller.js
  16. +2 −0  core/modules/macros/version.js
  17. +2 −0  core/modules/macros/video.js
  18. +2 −0  core/modules/macros/view.js
  19. +2 −0  core/modules/macros/zoomer.js
  20. +1 −1  core/modules/parsers/javascriptparser/javascriptparser.js
  21. +1 −1  core/modules/parsers/plaintextparser.js
  22. +2 −0  core/modules/parsers/wikitextparser/rules/wikitextrules.js
  23. +0 −2  core/modules/utils.js
  24. +0 −3  core/static.template.html.tid
  25. +6 −4 readme.md
  26. +62 −22 tw5.com/tiddlers/CommandLineInterface.tid
View
2  core/modules/commands/dump.js
@@ -3,7 +3,7 @@ title: $:/core/modules/commands/dump.js
type: application/javascript
module-type: command
-Dump command
+Dump command for inspecting TiddlyWiki internals
\*/
(function(){
View
2  core/modules/commands/load.js
@@ -3,7 +3,7 @@ title: $:/core/modules/commands/load.js
type: application/javascript
module-type: command
-Load tiddlers command
+Command to load tiddlers from a file
\*/
(function(){
View
2  core/modules/commands/savetiddler.js
@@ -3,7 +3,7 @@ title: $:/core/modules/commands/savetiddler.js
type: application/javascript
module-type: command
-Save tiddlers command
+Command to save a tiddler to a file
\*/
(function(){
View
15 core/modules/commands/server.js
@@ -3,20 +3,7 @@ title: $:/core/modules/commands/server.js
type: application/javascript
module-type: command
-Serve tiddlers over http. The server is very simple. At the root, it serves a rendering of a specified tiddler. Otherwise, it serves individual tiddlers encoded in JSON, and supports the basic HTTP operations for GET, PUT and DELETE.
-
-For example:
-
- --server 8080 $:/core/tiddlywiki5.template.html text/plain text/html
-
-The parameters are:
-
- --server <port> <roottiddler> <rendertype> <servetype>
-
-* ''port'' - port number to serve from (defaults to "8080")
-* ''roottiddler'' - the tiddler to serve at the root (defaults to "$:/core/tiddlywiki5.template.html")
-* ''rendertype'' - the content type to which the root tiddler should be rendered (defaults to "text/plain")
-* ''servetype'' - the content type with which the root tiddler should be served (defaults to "text/html")
+Serve tiddlers over http
\*/
(function(){
View
2  core/modules/macros/button.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/button.js
type: application/javascript
module-type: macro
+Button macro
+
\*/
(function(){
View
2  core/modules/macros/chooser.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/chooser.js
type: application/javascript
module-type: macro
+Zooming chooser macro
+
\*/
(function(){
View
2  core/modules/macros/download.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/download.js
type: application/javascript
module-type: macro
+Download macro
+
\*/
(function(){
View
2  core/modules/macros/echo.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/echo.js
type: application/javascript
module-type: macro
+Echo macro
+
\*/
(function(){
View
2  core/modules/macros/edit/edit.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/edit/edit.js
type: application/javascript
module-type: macro
+Edit macro for editting fields and tiddlers
+
\*/
(function(){
View
2  core/modules/macros/edit/editors/bitmapeditor.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/edit/editors/bitmapeditor.js
type: application/javascript
module-type: editor
+An editor plugin for editting bitmaps
+
\*/
(function(){
View
2  core/modules/macros/edit/editors/texteditor.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/edit/editors/texteditor.js
type: application/javascript
module-type: editor
+An editor plugin for editting text
+
\*/
(function(){
View
2  core/modules/macros/image.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/image.js
type: application/javascript
module-type: macro
+Image macro for displaying images
+
\*/
(function(){
View
2  core/modules/macros/include.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/include.js
type: application/javascript
module-type: macro
+Include macro
+
\*/
(function(){
View
2  core/modules/macros/list.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/list.js
type: application/javascript
module-type: macro
+List macro
+
\*/
(function(){
View
2  core/modules/macros/story/views/scroller.js
@@ -3,7 +3,7 @@ title: $:/core/modules/macros/story/views/scroller.js
type: application/javascript
module-type: storyview
-A storyview that shows a sequence of tiddlers and navigates by scrolling
+A storyview that shows a sequence of tiddlers and navigates by smoothly scrolling
\*/
(function(){
View
2  core/modules/macros/version.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/version.js
type: application/javascript
module-type: macro
+Version macro
+
\*/
(function(){
View
2  core/modules/macros/video.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/video.js
type: application/javascript
module-type: macro
+Video macro
+
\*/
(function(){
View
2  core/modules/macros/view.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/view.js
type: application/javascript
module-type: macro
+View macro
+
\*/
(function(){
View
2  core/modules/macros/zoomer.js
@@ -3,6 +3,8 @@ title: $:/core/modules/macros/zoomer.js
type: application/javascript
module-type: macro
+Zooming navigator macro
+
\*/
(function(){
View
2  core/modules/parsers/javascriptparser/javascriptparser.js
@@ -3,7 +3,7 @@ title: $:/core/modules/parsers/javascriptparser/javascriptparser.js
type: application/javascript
module-type: parser
-Parses a JSON object into a parse tree
+Parses a JavaScript program into a parse tree
\*/
(function(){
View
2  core/modules/parsers/plaintextparser.js
@@ -3,7 +3,7 @@ title: $:/core/modules/parsers/plaintextparser.js
type: application/javascript
module-type: parser
-Renders plain text tiddlers
+Parses plain text tiddlers
\*/
(function(){
View
2  core/modules/parsers/wikitextparser/rules/wikitextrules.js
@@ -3,6 +3,8 @@ title: $:/core/modules/parsers/wikitextparser/rules/wikitextrules.js
type: application/javascript
module-type: wikitextrule
+Rule modules for the wikitext parser
+
\*/
(function(){
View
2  core/modules/utils.js
@@ -5,8 +5,6 @@ module-type: utils
Various static utility functions.
-This file is a bit of a dumping ground; the expectation is that most of these functions will be refactored.
-
\*/
(function(){
View
3  core/static.template.html.tid
@@ -7,9 +7,6 @@ type: text/x-tiddlywiki-html
<meta name="application-name" content="TiddlyWiki" />
<meta name="generator" content="TiddlyWiki" />
<meta name="tiddlywiki-version" content="<<include "$:/core/version.txt" text/plain shadow:yes>>" />
-<meta name="viewport" content="width=device-width, initial-scale=1.0" />
-<meta name="apple-mobile-web-app-capable" content="yes" />
-<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
<meta name="format-detection" content="telephone=no">
<meta name="copyright" content="
<<include "$:/core/copyright.txt" text/plain shadow:yes>>
View
10 readme.md
@@ -1,8 +1,10 @@
-<h1>Welcome to <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a></h1><div class='tw-tiddler-frame' data-tiddler-target='HelloThere' data-tiddler-template='HelloThere'>Welcome to <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a>, a reboot of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a>, 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='What%20is%20node.js%3F'>node.js application</a>.<br><br><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> is currently at version 5.0.0.a2 and is under active development, which is to say that it is useful but incomplete. You can try out the prototype at <a class='tw-tiddlylink tw-tiddlylink-external' href='http://tiddlywiki.com/tiddlywiki5'>http://tiddlywiki.com/tiddlywiki5</a>, get involved in the <a class='tw-tiddlylink tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5'>development on GitHub</a> or the discussions on <a class='tw-tiddlylink tw-tiddlylink-external' href='http://groups.google.com/group/TiddlyWikiDev'>the TiddlyWikiDev Google Group</a>.<br><br><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='Introduction'>Introduction</a></div><br><h1>Usage</h1><div class='tw-tiddler-frame' data-tiddler-target='CommandLineInterface' data-tiddler-template='CommandLineInterface'><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> can be used on the command line to perform an extensive set of operations based on <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='RecipeFiles'>RecipeFiles</a>, <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlerFiles'>TiddlerFiles</a> and <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWikiFiles'>TiddlyWikiFiles</a>.<br><br><h2>Usage</h2><code>
-node core/boot.js &lt;options&gt;
-</code><br>This boots the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> kernel and loads the core plugins. The wiki store is initially empty.<br><br>The command line options are processed sequentially from left to right. Processing pauses during long operations and then resumes with the next command line option in sequence.<br><br>The following options are available:<br><table class='table'><tbody><tr class='evenRow'><td align='left'><code>--load &lt;filepath&gt;</code></td><td align='left'>Load tiddlers from 2.x.x <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> files (<code>.html</code>), <code>.tiddler</code>, <code>.tid</code>, <code>.json</code> or other files</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>--wikitest &lt;dir&gt; [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>--dump tiddlers</code></td><td align='left'>Dump the titles of the tiddlers in the wiki store</td></tr><tr class='evenRow'><td align='left'><code>--dump tiddler &lt;title&gt;</code></td><td align='left'>Dump the fields of an individual tiddler</td></tr><tr class='oddRow'><td align='left'><code>--dump shadows</code></td><td align='left'>Dump the titles of the shadow tiddlers in the wiki store</td></tr><tr class='evenRow'><td align='left'><code>--dump config</code></td><td align='left'>Dump the current core configuration</td></tr><tr class='oddRow'><td align='left'><code>--verbose</code></td><td align='left'>Triggers verbose output, useful for debugging</td></tr></tbody></table><h2> Examples</h2>This example loads the tiddlers from a <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> HTML file and then saves one of them in HTML:<br><code>
+<h1>Welcome to <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a></h1><div class='tw-tiddler-frame' data-tiddler-target='HelloThere' data-tiddler-template='HelloThere'>Welcome to <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a>, a reboot of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a>, 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='What%20is%20node.js%3F'>node.js application</a>.<br><br><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> is currently at version 5.0.0.a2 and is under active development, which is to say that it is useful but incomplete. You can try out the prototype at <a class='tw-tiddlylink tw-tiddlylink-external' href='http://tiddlywiki.com/tiddlywiki5'>http://tiddlywiki.com/tiddlywiki5</a>, get involved in the <a class='tw-tiddlylink tw-tiddlylink-external' href='https://github.com/Jermolene/TiddlyWiki5'>development on GitHub</a> or the discussions on <a class='tw-tiddlylink tw-tiddlylink-external' href='http://groups.google.com/group/TiddlyWikiDev'>the TiddlyWikiDev Google Group</a>.<br><br><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='Introduction'>Introduction</a></div><br><h1>Usage</h1><div class='tw-tiddler-frame' data-tiddler-target='CommandLineInterface' data-tiddler-template='CommandLineInterface'><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> can be used on the command line to perform an extensive set of operations based on <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='RecipeFiles'>RecipeFiles</a>, <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlerFiles'>TiddlerFiles</a> and <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWikiFiles'>TiddlyWikiFiles</a>.<br><h2> Examples</h2>This example loads the tiddlers from a <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> HTML file and then saves one of them in HTML:<br><code>
node tiddlywiki.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.html
-</code><br><h2> Notes</h2><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.<br><h2>Try it out</h2>The easiest way to try out the code is to visit <a class='tw-tiddlylink tw-tiddlylink-external' href='http://tiddlywiki.com/tiddlywiki5/'>http://tiddlywiki.com/tiddlywiki5/</a><br><br>For trying it out under <code>node.js</code>, two batch files are provided:<br><br><ul><li> <code>run.sh</code> boots the kernel and loads the core modules and then outputs the <code>$tw</code> global for inspection</li><li> <code>bld.sh</code> builds the new <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> 5 HTML file (placed in the <code>tmp/tw5/</code> directory by default)</li></ul></div><br><h1>Architecture</h1><div class='tw-tiddler-frame' data-tiddler-target='TiddlyWikiArchitecture' data-tiddler-template='TiddlyWikiArchitecture'><h2> Overview</h2><br>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 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>JavaScript</a>, 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>&lt;&lt;tiddler Disclaimer&gt;&gt;</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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> design.<br><br>It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a>'s user interface itself. Consider, for example, the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='StoryMacro'>StoryMacro</a> in its simplest form:<br><pre>&lt;&lt;story story:MyStoryTiddler&gt;&gt;
+</code><br><h2>Usage</h2><code>
+node core/boot.js [--&lt;option&gt; [&lt;arg&gt;[,&lt;arg&gt;]]]
+</code><br>Running <code>boot.js</code> from the command line boots the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments. The arguments are separated with spaces. The commands are identified by the prefix <code>--</code>.<br><br>The commands are processed sequentially from left to right. Processing pauses during long operations and then resumes with the next command in sequence <br><h2>Commands</h2>The following commands are available.<br><br><h3> load</h3><code>--load &lt;filepath&gt;</code><br>Load tiddlers from 2.x.x <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> files (<code>.html</code>), <code>.tiddler</code>, <code>.tid</code>, <code>.json</code> or other files <br><br><h3> savetiddler</h3><code>--savetiddler &lt;title&gt; &lt;filename&gt; [&lt;type&gt;]</code> <br>Save an individual tiddler as a specified MIME type, defaults to <code>text/html</code> <br><br><h3> wikitest</h3><code>--wikitest &lt;dir&gt; [save]</code> <br>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.<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.<br><br><h3> server</h3><code>--server &lt;port&gt; &lt;roottiddler&gt; &lt;rendertype&gt; &lt;servetype&gt;</code> <br><br>The server is very simple. At the root, it serves a rendering of a specified tiddler. Away from the root, it serves individual tiddlers encoded in JSON, and supports the basic HTTP operations for GET, PUT and DELETE.<br><br>For example:<br><pre>--server 8080 $:/core/tiddlywiki5.template.html text/plain text/html
+</pre>The parameters are:<br><pre>--server &lt;port&gt; &lt;roottiddler&gt; &lt;rendertype&gt; &lt;servetype&gt;
+</pre><ul><li> <strong>port</strong> - port number to serve from (defaults to &quot;8080&quot;)</li><li> <strong>roottiddler</strong> - the tiddler to serve at the root (defaults to &quot;$:/core/tiddlywiki5.template.html&quot;) </li><li> <strong>rendertype</strong> - the content type to which the root tiddler should be rendered (defaults to &quot;text/plain&quot;)</li><li> <strong>servetype</strong> - the content type with which the root tiddler should be served (defaults to &quot;text/html&quot;)</li></ul><br><h3> dump</h3><code>--dump tiddlers</code> <br>Dump the titles of the tiddlers in the wiki store <br><br><h3> dump</h3><code>--dump tiddler &lt;title&gt;</code> <br>Dump the fields of an individual tiddler <br><br><h3> dump</h3><code>--dump shadows</code> <br>Dump the titles of the shadow tiddlers in the wiki store <br><br><h3> dump</h3><code>--dump config</code> <br>Dump the current core configuration <br><br><h3> verbose</h3><code>--verbose</code> <br>Triggers verbose output, useful for debugging <br><br><h2>Trying it out</h2>For trying <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> out under <code>node.js</code>, two batch files are provided:<br><br><ul><li> <code>run.sh</code> boots the kernel and loads the core modules and then outputs the <code>$tw</code> global for inspection</li><li> <code>bld.sh</code> builds the new <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> 5 HTML file (placed in the <code>tmp/tw5/</code> directory by default)</li></ul></div><br><h1>Architecture</h1><div class='tw-tiddler-frame' data-tiddler-target='TiddlyWikiArchitecture' data-tiddler-template='TiddlyWikiArchitecture'><h2> Overview</h2><br>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 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>JavaScript</a>, 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>&lt;&lt;tiddler Disclaimer&gt;&gt;</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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> design.<br><br>It turns out that the transclusion capability combined with the selective refreshing mechanism provides a good foundation for building <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a>'s user interface itself. Consider, for example, the <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='StoryMacro'>StoryMacro</a> in its simplest form:<br><pre>&lt;&lt;story story:MyStoryTiddler&gt;&gt;
</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>&lt;&lt;story&gt;&gt;</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(&quot;MyStoryTiddler&quot;);
store.addTiddler(new Tiddler(storyTiddler,{text: navigateTo + &quot;\n&quot; + 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>JavaScript</a> <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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> objects.<br><br>The <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> also manages the plugin modules used for macros, and operations like serializing, deserializing, parsing and rendering tiddlers.<br><br>Each <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> 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><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='TiddlyWiki'>TiddlyWiki</a> 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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> until the tiddler changes.<br><br><a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='TiddlyWiki5'>TiddlyWiki5</a> uses multiple parsers:<br><ul><li> Wikitext (<code>text/x-tiddlywiki</code>) in <code>js/WikiTextParser.js</code></li><li> <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='JavaScript'>JavaScript</a> (<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 <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='WikiStore'>WikiStore</a> 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<br>
View
84 tw5.com/tiddlers/CommandLineInterface.tid
@@ -2,35 +2,75 @@ title: CommandLineInterface
modifier: JeremyRuston
TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on RecipeFiles, TiddlerFiles and TiddlyWikiFiles.
-
-!!Usage
-`
-node core/boot.js <options>
-`
-This boots the TiddlyWiki kernel and loads the core plugins. The wiki store is initially empty.
-
-The command line options are processed sequentially from left to right. Processing pauses during long operations and then resumes with the next command line option in sequence.
-
-The following options are available:
-|`--load <filepath>` |Load tiddlers from 2.x.x TiddlyWiki files (`.html`), `.tiddler`, `.tid`, `.json` or other files |
-|`--savetiddler <title> <filename> [<type>]` |Save an individual tiddler as a specified MIME type, defaults to `text/html` |
-|`--wikitest <dir> [save]` |Run wikification tests against the tiddlers in the given directory. Include the `save` flag to save the test result files as the new targets |
-|`--dump tiddlers` |Dump the titles of the tiddlers in the wiki store |
-|`--dump tiddler <title>` |Dump the fields of an individual tiddler |
-|`--dump shadows` |Dump the titles of the shadow tiddlers in the wiki store |
-|`--dump config` |Dump the current core configuration |
-|`--verbose` |Triggers verbose output, useful for debugging |
!! Examples
This example loads the tiddlers from a TiddlyWiki HTML file and then saves one of them in HTML:
`
node tiddlywiki.js --verbose --load mywiki.html --savetiddler ReadMe ./readme.html
`
-!! Notes
+!!Usage
+`
+node core/boot.js [--<option> [<arg>[,<arg>]]]
+`
+Running `boot.js` from the command line boots the TiddlyWiki kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments. The arguments are separated with spaces. The commands are identified by the prefix `--`.
+
+The commands are processed sequentially from left to right. Processing pauses during long operations and then resumes with the next command in sequence
+!!Commands
+The following commands are available.
+
+!!! load
+`--load <filepath>`
+Load tiddlers from 2.x.x TiddlyWiki files (`.html`), `.tiddler`, `.tid`, `.json` or other files
+
+!!! savetiddler
+`--savetiddler <title> <filename> [<type>]`
+Save an individual tiddler as a specified MIME type, defaults to `text/html`
+
+!!! wikitest
+`--wikitest <dir> [save]`
+Run wikification tests against the tiddlers in the given directory. Include the `save` flag to save the test result files as the new targets.
+
`--wikitest` looks for `*.tid` 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 `*.html` and `*.txt` files in the same directory.
-!!Try it out
-The easiest way to try out the code is to visit http://tiddlywiki.com/tiddlywiki5/
-For trying it out under `node.js`, two batch files are provided:
+!!! server
+`--server <port> <roottiddler> <rendertype> <servetype>`
+
+The server is very simple. At the root, it serves a rendering of a specified tiddler. Away from the root, it serves individual tiddlers encoded in JSON, and supports the basic HTTP operations for GET, PUT and DELETE.
+
+For example:
+{{{
+--server 8080 $:/core/tiddlywiki5.template.html text/plain text/html
+}}}
+The parameters are:
+{{{
+--server <port> <roottiddler> <rendertype> <servetype>
+}}}
+* ''port'' - port number to serve from (defaults to "8080")
+* ''roottiddler'' - the tiddler to serve at the root (defaults to "$:/core/tiddlywiki5.template.html")
+* ''rendertype'' - the content type to which the root tiddler should be rendered (defaults to "text/plain")
+* ''servetype'' - the content type with which the root tiddler should be served (defaults to "text/html")
+
+!!! dump
+`--dump tiddlers`
+Dump the titles of the tiddlers in the wiki store
+
+!!! dump
+`--dump tiddler <title>`
+Dump the fields of an individual tiddler
+
+!!! dump
+`--dump shadows`
+Dump the titles of the shadow tiddlers in the wiki store
+
+!!! dump
+`--dump config`
+Dump the current core configuration
+
+!!! verbose
+`--verbose`
+Triggers verbose output, useful for debugging
+
+!!Trying it out
+For trying TiddlyWiki5 out under `node.js`, two batch files are provided:
* `run.sh` boots the kernel and loads the core modules and then outputs the `$tw` global for inspection
* `bld.sh` builds the new TiddlyWiki 5 HTML file (placed in the `tmp/tw5/` directory by default)
Please sign in to comment.
Something went wrong with that request. Please try again.