From c4d7401f0297da92437821f9724e4d00a1a6d762 Mon Sep 17 00:00:00 2001
From: Jeremy Ruston <jeremy@osmosoft.com>
Date: Fri, 30 Aug 2013 20:06:23 +0100
Subject: [PATCH] Lots of docs updates

---
 core/docs/fields/bag.tid                      |  3 +
 core/docs/fields/created.tid                  |  3 +
 core/docs/fields/creator.tid                  |  3 +
 core/docs/fields/draftof.tid                  |  3 +
 core/docs/fields/drafttitle.tid               |  3 +
 core/docs/fields/revision.tid                 |  3 +
 core/ui/ToolsPanel.tid                        |  2 +
 core/wiki/WikiInfo.tid                        |  6 ++
 .../tiddlers/concepts/TiddlerFields.tid       | 47 +++++++------
 .../tiddlers/concepts/TiddlerFilters.tid      |  9 +--
 .../tw5.com/tiddlers/concepts/Tiddlers.tid    | 15 +---
 .../tiddlers/concepts/TiddlyWikiFolders.tid   | 69 ++++++++++++++-----
 .../tiddlers/definitions/ListField.tid        | 12 ++++
 .../tiddlers/definitions/TiddlySpace.tid      | 10 +++
 .../tiddlers/definitions/TiddlyWeb.tid        | 14 ++++
 .../tw5.com/tiddlers/widgets/ListWidget.tid   |  4 +-
 readme.md                                     |  6 +-
 17 files changed, 152 insertions(+), 60 deletions(-)
 create mode 100644 core/docs/fields/bag.tid
 create mode 100644 core/docs/fields/created.tid
 create mode 100644 core/docs/fields/creator.tid
 create mode 100644 core/docs/fields/draftof.tid
 create mode 100644 core/docs/fields/drafttitle.tid
 create mode 100644 core/docs/fields/revision.tid
 create mode 100644 core/wiki/WikiInfo.tid
 create mode 100644 editions/tw5.com/tiddlers/definitions/ListField.tid
 create mode 100644 editions/tw5.com/tiddlers/definitions/TiddlySpace.tid
 create mode 100644 editions/tw5.com/tiddlers/definitions/TiddlyWeb.tid

diff --git a/core/docs/fields/bag.tid b/core/docs/fields/bag.tid
new file mode 100644
index 000000000..e2dd686c5
--- /dev/null
+++ b/core/docs/fields/bag.tid
@@ -0,0 +1,3 @@
+title: $:/docs/fields/bag
+
+The name of the bag from which a tiddler came
\ No newline at end of file
diff --git a/core/docs/fields/created.tid b/core/docs/fields/created.tid
new file mode 100644
index 000000000..b78084678
--- /dev/null
+++ b/core/docs/fields/created.tid
@@ -0,0 +1,3 @@
+title: $:/docs/fields/created
+
+The date a tiddler was created
\ No newline at end of file
diff --git a/core/docs/fields/creator.tid b/core/docs/fields/creator.tid
new file mode 100644
index 000000000..7bb243612
--- /dev/null
+++ b/core/docs/fields/creator.tid
@@ -0,0 +1,3 @@
+title: $:/docs/fields/creator
+
+The name of the person who created a tiddler
\ No newline at end of file
diff --git a/core/docs/fields/draftof.tid b/core/docs/fields/draftof.tid
new file mode 100644
index 000000000..11588dd6b
--- /dev/null
+++ b/core/docs/fields/draftof.tid
@@ -0,0 +1,3 @@
+title: $:/docs/fields/draft.of
+
+For draft tiddlers, contains the title of the tiddler of which this is a draft
\ No newline at end of file
diff --git a/core/docs/fields/drafttitle.tid b/core/docs/fields/drafttitle.tid
new file mode 100644
index 000000000..a0f908994
--- /dev/null
+++ b/core/docs/fields/drafttitle.tid
@@ -0,0 +1,3 @@
+title: $:/docs/fields/draft.title
+
+For draft tiddlers, contains the proposed new title of the tiddler
\ No newline at end of file
diff --git a/core/docs/fields/revision.tid b/core/docs/fields/revision.tid
new file mode 100644
index 000000000..bb07d11f0
--- /dev/null
+++ b/core/docs/fields/revision.tid
@@ -0,0 +1,3 @@
+title: $:/docs/fields/revision
+
+The revision of the tiddler held at the server
\ No newline at end of file
diff --git a/core/ui/ToolsPanel.tid b/core/ui/ToolsPanel.tid
index faf982879..f460a9f75 100644
--- a/core/ui/ToolsPanel.tid
+++ b/core/ui/ToolsPanel.tid
@@ -1,5 +1,7 @@
 title: $:/core/ui/ToolsPanel
 
+[[Wiki Info|$:/WikiInfo]]
+
 ---
 
 {{$:/snippets/viewswitcher}}
diff --git a/core/wiki/WikiInfo.tid b/core/wiki/WikiInfo.tid
new file mode 100644
index 000000000..8c0087adc
--- /dev/null
+++ b/core/wiki/WikiInfo.tid
@@ -0,0 +1,6 @@
+title: $:/WikiInfo
+
+* Tiddlers: <$count filter="[!is[system]]"/>
+* System tiddlers: <$count filter="[is[system]]"/>
+* Shadow tiddlers: <$count filter="[is[shadow]]"/>
+** Over-ridden shadow tiddlers: <$count filter="[!is[system]is[shadow]]"/>
diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerFields.tid b/editions/tw5.com/tiddlers/concepts/TiddlerFields.tid
index bbffdc439..82f3f8a7b 100644
--- a/editions/tw5.com/tiddlers/concepts/TiddlerFields.tid
+++ b/editions/tw5.com/tiddlers/concepts/TiddlerFields.tid
@@ -1,38 +1,41 @@
 created: 201308252133
 creator: JeremyRuston
-modified: 201308252133
+modified: 201308300902
 modifier: JeremyRuston
 tags: concepts
 title: TiddlerFields
 
 TiddlerFields are name:value pairs that make up a [[tiddler|Tiddlers]]. The standard fields are:
 
-* `title` - The unique title of the tiddler
-* `modified` - The date of the last modification to the tiddler
-* `modifier` - The name of the last person to modify the tiddler
-* `created` - The date the tiddler was created
-* `creator` - The name of the person who created the tiddler
-* `tags` - A list of tags applied to the tiddler
-* `type` - The ContentType that should used to interpret the content of the tiddler
-* `list` - A list of tiddler titles
+|!Field Name |!Reference |!Description |
+|`title` |TitleField |{{$:/docs/fields/title}} |
+|`modified` |ModifiedField |{{$:/docs/fields/modified}} |
+|`modifier` |ModifierField |{{$:/docs/fields/modifier}} |
+|`created` |CreatedField |{{$:/docs/fields/created}} |
+|`creator` |CreatorField |{{$:/docs/fields/creator}} |
+|`tags` |TagsField |{{$:/docs/fields/tags}} |
+|`type` |TypeField |{{$:/docs/fields/type}} |
+|`list` |ListField |{{$:/docs/fields/list}} |
 
 Other fields used by the core are:
 
-* `color` - The colour associated with a tiddler (expressed as a valid CSS value like `#fea` or `rgb(100,100,100)`)
-* `description` - The description of a plugin
-* `draft.of` - For draft tiddlers, contains the title of the tiddler of which this is a draft
-* `draft.title` - For draft tiddlers, contains the proposed new title of the tiddler
-* `footer` - The footer for a modal dialogue (interpreted as WikiText)
-* `library` - Set to `yes` if the tiddler should be loaded in the browser as a `<script>` tag
-* `name` - Human-readable name of a plugin
-* `plugin-priority` - An integer giving the priority for loading plugin tiddlers
-* `plugin-type` - The type of a plugin (currently can be `plugin` or `theme`)
-* `source` - The original URL associated with a tiddler
-* `subtitle` - The subtitle for a modal dialogue (interpreted as WikiText)
+|!Field Name |!Reference |!Description |
+|`color` |ColorField |{{$:/docs/fields/color}} |
+|`description` |DescriptionField |{{$:/docs/fields/description}} |
+|`draft.of` |DraftOfField |{{$:/docs/fields/draft.of}} |
+|`draft.title` |DraftTitleField |{{$:/docs/fields/draft.title}} |
+|`footer` |FooterField |{{$:/docs/fields/footer}} |
+|`library` |LibraryField |{{$:/docs/fields/library}} |
+|`name` |NameField |{{$:/docs/fields/name}} |
+|`plugin-priority` |PluginPriorityField |{{$:/docs/fields/plugin-priority}} |
+|`plugin-type` |PluginTypeField |{{$:/docs/fields/plugin-type}} |
+|`source` |SourceField |{{$:/docs/fields/source}} |
+|`subtitle` |SubtitleField |{{$:/docs/fields/subtitle}} |
 
 The TiddlyWebAdaptor uses a few more fields:
 
-* `bag` - The name of the bag from which a tiddler came
-* `revision` - The revision of the tiddler held at the server
+|!Field Name |!Reference |!Description |
+|`bag` |BagField |{{$:/docs/fields/bag}} |
+|`revision` |RevisionField |{{$:/docs/fields/revision}} |
 
 See [[$:/ConfigInfo]] for details of the fields used in this wiki.
diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid b/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid
index bf60a12bb..3ef68102c 100644
--- a/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid
+++ b/editions/tw5.com/tiddlers/concepts/TiddlerFilters.tid
@@ -1,6 +1,6 @@
 created: 201308270800
 creator: JeremyRuston
-modified: 201308270800
+modified: 201308300906
 modifier: JeremyRuston
 tags: concepts
 title: TiddlerFilters
@@ -60,10 +60,11 @@ The operator defaults to `title` if omitted, so `[[HelloThere]]` is equivalent t
 
 The operands available with the `is` operator are:
 
-* ''system'': selects all system tiddlers
+* ''system'': selects all SystemTiddlers
+* ''shadow'': selects all ShadowTiddlers
 * ''current'': selects the current ContextTiddler
-* ''missing'': selects all missing tiddlers
-* ''orphan'': selects all orphan tiddlers
+* ''missing'': selects all MissingTiddlers
+* ''orphan'': selects all OrphanTiddlers
 
 ! Indirect Operands
 
diff --git a/editions/tw5.com/tiddlers/concepts/Tiddlers.tid b/editions/tw5.com/tiddlers/concepts/Tiddlers.tid
index 38cde1cbd..79533dad4 100644
--- a/editions/tw5.com/tiddlers/concepts/Tiddlers.tid
+++ b/editions/tw5.com/tiddlers/concepts/Tiddlers.tid
@@ -1,21 +1,10 @@
 created: 201308252135
 creator: JeremyRuston
-modified: 201308252135
+modified: 201308300907
 modifier: JeremyRuston
 tags: concepts
 title: Tiddlers
 
 Tiddlers are the smallest unit of information in TiddlyWiki. They can be structured with [[links|TiddlerLinks]] and tags.
 
-Internally, tiddlers are an immutable dictionary of name:value pairs called fields. The only field that is required is the `title` field, but useful tiddlers also have a `text` field, and some or all of the standard fields listed below:
-
-* `title` - The unique title of the tiddler
-* `modified` - The date of the last modification to the tiddler
-* `modifier` - The name of the last person to modify the tiddler
-* `created` - The date the tiddler was created
-* `creator` - The name of the person who created the tiddler
-* `tags` - A list of tags applied to the tiddler
-* `type` - The ContentType that should used to interpret the content of the tiddler
-
-See TiddlerFields for a complete list of fields used in TiddlyWiki5.
-
+Internally, tiddlers are an immutable dictionary of name:value pairs called fields. The only field that is required is the `title` field, but useful tiddlers also have a `text` field, and some or all of the standard fields listed in TiddlerFields.
diff --git a/editions/tw5.com/tiddlers/concepts/TiddlyWikiFolders.tid b/editions/tw5.com/tiddlers/concepts/TiddlyWikiFolders.tid
index e75831474..41c55f814 100644
--- a/editions/tw5.com/tiddlers/concepts/TiddlyWikiFolders.tid
+++ b/editions/tw5.com/tiddlers/concepts/TiddlyWikiFolders.tid
@@ -1,6 +1,6 @@
 created: 201308252142
 creator: JeremyRuston
-modified: 201308281907
+modified: 201308300920
 modifier: JeremyRuston
 tags: dev
 title: TiddlyWikiFolders
@@ -11,13 +11,13 @@ As well as traditional single file wikis, TiddlyWiki5 [[under node.js|TiddlyWiki
 
 Wiki folders can contain the following files and folders:
 
+* ''tiddlywiki.info'' - JSON file containing metadata for the wiki
 * ''\tiddlers'' - folder containing tiddler files comprising the wiki
 * ''\plugins'' - folder containing [[plugin folders|PluginMechanism]] to be included in the wiki
-* ''tiddlywiki.info'' - JSON file containing metadata for the wiki. See below
 
 Only the ''tiddlywiki.info'' file is required, the ''tiddlers'' and ''plugins'' folders are optional. Any files and folders not listed above are ignored.
 
-! Content of `tiddlywiki.info`
+!! Content of `tiddlywiki.info` file
 
 The `tiddlywiki.info` file in a wiki folder contains a JSON object comprising the following fields:
 
@@ -29,18 +29,55 @@ For example:
 
 ```
 {
-	"plugins": [
-		"tiddlywiki/tiddlyweb",
-		"tiddlywiki/filesystem"
-	],
-	"doNotSave": [
-		"$:/StoryList",
-		"$:/HistoryList",
-		"$:/status/IsLoggedIn",
-		"$:/status/UserName"
-	],
-	"includeWikis": [
-		"../tw5.com"
-	]
+  "plugins": [
+    "tiddlywiki/tiddlyweb",
+    "tiddlywiki/filesystem"
+  ],
+  "doNotSave": [
+    "$:/StoryList",
+    "$:/HistoryList",
+    "$:/status/IsLoggedIn",
+    "$:/status/UserName"
+  ],
+  "includeWikis": [
+    "../tw5.com"
+  ]
 }
 ```
+
+!! Content of `tiddlers` folder
+
+All the TiddlerFiles in the `tiddlers` folder are read into the wiki at startup. Sub-folders are scanned recursively for TiddlerFiles.
+
+Sub-folders within the `tiddlers` folder can also be given a `tiddlywiki.files` JSON file that overrides the default processing for that folder. The file format is illustrated with this example from the D3 plugin:
+
+```
+{
+  "tiddlers": [
+    {
+      "file": "d3.min.js",
+      "fields": {
+        "type": "application/javascript",
+        "title": "$:/plugins/tiddlywiki/d3/d3.js",
+        "module-type": "library"
+      },
+      "prefix": "var d3;if($tw.browser){\n",
+      "suffix": "}\nexports.d3 = d3;\n"
+    },
+    {
+      "file": "cloud/d3.layout.cloud.js",
+      "fields": {
+        "type": "application/javascript",
+        "title": "$:/plugins/tiddlywiki/d3/d3.layout.cloud.js",
+        "module-type": "library"
+      }
+    }
+  ]
+}
+```
+
+The JSON data consists of an object with a `tiddlers` property that contains an array of information about each tiddler to be loaded into the wiki. That information consists of:
+
+* `file`: the relative or absolute path to the file to include
+* `fields`: an object containing fields that override any provided in the tiddler file
+* `prefix` & `suffix`: (optional) specify strings to be prefixed and suffixed to the tiddler file text content
diff --git a/editions/tw5.com/tiddlers/definitions/ListField.tid b/editions/tw5.com/tiddlers/definitions/ListField.tid
new file mode 100644
index 000000000..d93381d04
--- /dev/null
+++ b/editions/tw5.com/tiddlers/definitions/ListField.tid
@@ -0,0 +1,12 @@
+created: 201308300925
+creator: JeremyRuston
+modified: 201308300927
+modifier: JeremyRuston
+tags: fields
+title: ListField
+
+The `list` [[field of a tiddler|TiddlerFields]] is an optional feature that can be used to help structure your content. It is defined as an ordered sequence of tiddler titles, and it can be used in several ways:
+
+* The `list` [[filter|TiddlerFilters]] selects the entries from a list
+* The `listed` [[filter|TiddlerFilters]] selects the tiddlers that list the selected tiddler(s)
+* The NavigatorWidget manipulates a StoryList tiddler containing a `list` field of the tiddlers that are displayed in the main story column
diff --git a/editions/tw5.com/tiddlers/definitions/TiddlySpace.tid b/editions/tw5.com/tiddlers/definitions/TiddlySpace.tid
new file mode 100644
index 000000000..9c6f77e02
--- /dev/null
+++ b/editions/tw5.com/tiddlers/definitions/TiddlySpace.tid
@@ -0,0 +1,10 @@
+created: 201308300842
+creator: JeremyRuston
+modified: 201308300842
+modifier: JeremyRuston
+tags: definitions
+title: TiddlySpace
+
+TiddlySpace is an environment for discourse on the web, built from TiddlyWeb.
+
+TiddlySpace was originally sponsored by [[Osmosoft]] at [[BT]].
diff --git a/editions/tw5.com/tiddlers/definitions/TiddlyWeb.tid b/editions/tw5.com/tiddlers/definitions/TiddlyWeb.tid
new file mode 100644
index 000000000..e3b2e34ae
--- /dev/null
+++ b/editions/tw5.com/tiddlers/definitions/TiddlyWeb.tid
@@ -0,0 +1,14 @@
+created: 201308300841
+creator: JeremyRuston
+modified: 201308300843
+modifier: JeremyRuston
+tags: definitions
+title: TiddlyWeb
+
+TiddlyWeb is a server application that puts [[Tiddlers]] on the web:
+
+http://tiddlyweb.com/
+
+TiddlyWeb can be used to host TiddlyWiki and TiddlyWiki5 wikis, making the individual tiddlers available over a flexible HTTP API.
+
+TiddlyWeb was originally sponsored by [[Osmosoft]] at [[BT]] (along with TiddlySpace).
diff --git a/editions/tw5.com/tiddlers/widgets/ListWidget.tid b/editions/tw5.com/tiddlers/widgets/ListWidget.tid
index f4049a8da..f7cb45c77 100644
--- a/editions/tw5.com/tiddlers/widgets/ListWidget.tid
+++ b/editions/tw5.com/tiddlers/widgets/ListWidget.tid
@@ -1,6 +1,6 @@
 created: 201308241419
 creator: JeremyRuston
-modified: 201308241419
+modified: 201308300837
 modifier: JeremyRuston
 tags: widget
 title: ListWidget
@@ -10,7 +10,7 @@ This is the tiddler called [[Blah-$title$]]
 \end
 ! Introduction
 
-The list widget displays a sequence of tiddlers that match a TiddlerFilter. It can be used for many purposes:
+The list widget displays a sequence of tiddlers that match a [[tiddler filter|TiddlerFilters]]. It can be used for many purposes:
 
 * Displaying custom lists of links, like in TiddlyWiki5's sidebar
 * Custom lists, such as "all tiddlers tagged 'task' that are not tagged 'done'"
diff --git a/readme.md b/readme.md
index b440d9c2b..eeff45223 100644
--- a/readme.md
+++ b/readme.md
@@ -109,11 +109,11 @@ http://0.0.0.0:8080</code> in a browser.</p><p>
 Changes made in the browser propagate to the server over HTTP (use the browser developer console to see these requests). The server then syncs changes to the file system (and logs each change to the screen).</p><h3 class=''>
 <code>
 wbld.sh</code> builds <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWiki5.html'>
-TiddlyWiki5</a> for <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='http://five.tiddlywiki.com/static/TiddlyWeb.html'>
+TiddlyWiki5</a> for <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWeb.html'>
 TiddlyWeb</a></h3><p>
 This batch file builds and deploys the code for <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWiki5%20in%20the%20Sky%20for%20TiddlyWeb.html'>
 TiddlyWiki5 in the Sky for TiddlyWeb</a>. If you want to experiment with your own builds of <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWiki5.html'>
-TiddlyWiki5</a> for <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='http://five.tiddlywiki.com/static/TiddlyWeb.html'>
+TiddlyWiki5</a> for <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWeb.html'>
 TiddlyWeb</a> you could use this batch file as a base.</p><h3 class=''>
 <code>
 2bld.sh</code> builds <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWiki.html'>
@@ -201,7 +201,7 @@ ServerCommand</a></span></h3><div>
 <div class='tw-transclude'>
 <p>
 The server built in to <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWiki5.html'>
-TiddlyWiki5</a> is very simple. Although compatible with <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-missing' href='http://five.tiddlywiki.com/static/TiddlyWeb.html'>
+TiddlyWiki5</a> is very simple. Although compatible with <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWeb.html'>
 TiddlyWeb</a> it doesn't support many of the features needed for robust Internet-facing usage - in particular, <a class='tw-tiddlylink tw-tiddlylink-internal tw-tiddlylink-resolves' href='http://five.tiddlywiki.com/static/TiddlyWiki5.html'>
 TiddlyWiki5</a> is an old-school wiki in the sense that it offers no authentication.</p><p>
 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 <code>