Merge pull request #1293 from aelocson/patch-3

Improvements to wording

editions/tw5.com/tiddlers/concepts/ColourPalettes.tid

@@ -4,40 +4,29 @@ tags: Concepts
 title: ColourPalettes
 type: text/vnd.tiddlywiki
 
-Colour palettes bind logical colour names (such as ''page-background'') to actual CSS colours (such as ''#fe0'').
+A colour palette is a [[data tiddler|DataTiddlers]] that supplies a [[CSS]] colour value, such as ''yellow'' or ''#fe0'', for each of several colour names, like this:
 
-Entire colour palettes are stored in a single [[data tiddler|DataTiddlers]].
+```
+page-background: #fe0
+table-border: #ccc
+...
+```
 
-The title of the tiddler containing the current colour palette is identified by the tiddler [[$:/palette]].
+Several palettes form part of the core. The system tiddler [[$:/palette]] always contains the title of the currently selected palette tiddler.
 
-To retrieve a named colour from the current palette you can use the ''colour'' macro:
+To retrieve the value of a named colour from the current palette, e.g. for use in a stylesheet tiddler, use the [[colour macro|$:/core/macros/CSS]]:
 
 ```
 <<colour page-background>>
 ```
 
-The ''colour'' macro is defined like this:
-
-```
-\define colour(name)
-<$transclude tiddler={{$:/palette}} index="$name$"/>
-\end
-```
-
-By convention, each theme provides a default colour palette in the tiddler [[$:/config/DefaultPalette]] tiddler. Thus, setting the tiddler [[$:/theme]] to the string `$:/config/DefaultPalette` will revert to the palette packaged with the current theme (as long as it hasn't been redefined, since it is a shadow tiddler).
-
 Palette tiddlers should have the following fields:
 
-|!Field |!Description |
+|!Name |!Value |
-|title |Any title can be used, typically a system title starting with "$:/" |
+|title |Typically starting with `$:/` |
-|type |`application/x-tiddler-dictionary` to identify this tiddler as a [[data tiddler|DataTiddlers]] |
+|type |`application/x-tiddler-dictionary` |
-|tags |`$:/tags/Palette` to identify this tiddler as a palette |
+|tags |`$:/tags/Palette` |
-|description |Description to be displayed in palette browser |
+|description |Displayed in the palette browser |
-|text |Colour definitions (see below) |
+|text |`name: value` colour definitions |
 
-The text of a palette tiddler consists of name value pairs like this:
+By convention, each [[theme|Themes]] provides a default colour palette in the tiddler [[$:/config/DefaultPalette]]. Thus, setting the tiddler [[$:/theme]] to the string `$:/config/DefaultPalette` will revert to the palette packaged with the current theme (as long as it hasn't been redefined, since it is a shadow tiddler).
-
-```
-foreground: #000
-background: #fff
-```

editions/tw5.com/tiddlers/concepts/CurrentTiddler.tid

@@ -4,6 +4,10 @@ tags: Concepts
 title: CurrentTiddler
 type: text/vnd.tiddlywiki
 
-The CurrentTiddler is the current tiddler during WikiText rendering. It is usually set by the TiddlerWidget. It allows you to write references like `<$view field="title"/>` in TemplateTiddlers without explicitly specifying the tiddler that it applies to.
+The current tiddler provides an ever-changing context or background against which several features of WikiText are interpreted.
 
-The title of the current tiddler is contained in the [[WidgetVariable: currentTiddler]].
+For example, `{{!!title}}` denotes the value of the ''title'' field of whatever the current tiddler happens to be. This technique can be used in a [[TemplateTiddler|TemplateTiddlers]] to keep the template generic.
+
+The title of the current tiddler can always be found in the [[currentTiddler variable|WidgetVariable: currentTiddler]].
+
+The current tiddler is set in several ways, including by the ListWidget and the TiddlerWidget.

editions/tw5.com/tiddlers/concepts/DataTiddlers.tid

@@ -3,46 +3,29 @@ modified: 201308291647
 tags: Concepts
 title: DataTiddlers
 
-Data tiddlers provide a way to access blocks of [[JSON]] data within the `text` field of a tiddler.
+A data tiddler is a miniature database contained within a tiddler.
 
-//The implementation of data tiddlers is preliminary, with some intentional limitations.//
+There are two standard formats:
 
-! Data tiddler format
+* DictionaryTiddlers
+* [[JSONTiddlers]]
 
-A native data tiddler must have:
+Other formats of tiddler can also be parsed to yield blocks of data that behave like data tiddlers.
 
-* The ContentType field `type` set to `application/json`
+Use a TextReference to look up a value by its name. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains:
-* Valid JSON data in the `text` field 
-
-For example, the [[history list|$:/HistoryList]] tiddler is a data tiddler.
-
-Other tiddler types with alternative formats can also be parsed to yield a block of data that behaves like a data tiddler.
-
-!! Tiddler dictionary format
-
-The tiddler dictionary format is an alternative syntax for data tiddlers:
-
-* The ContentType field `type` is set to `application/x-tiddler-dictionary`
-* The `text` field consists of one or more lines of the form `<name>:<value>`
-
-For example, palettes such as the [[default Vanilla palette|$:/palettes/Vanilla]] are tiddler dictionaries.
-
-! Accessing data within data tiddlers
-
-Currently, it is only possible to access the top level properties of the data using TextReference syntax.
-
-For example, given a `application/json` tiddler containing:
 
 ```
-{"a":"one","b":"two","c":"three"}
+oct:31
+nov:30
+dec:31
 ```
 
-Or the equivalent tiddler dictionary of type `application/x-tiddler-dictionary`:
+... then `{{MonthDays##nov}}` will resolve to the value `30`.
+
+The same is true if `MonthDays` is a [[JSONTiddler|JSONTiddlers]] with the following content:
 
 ```
-a:one
+{"oct":31,"nov":30,"dec":31}
-b:two
-c:three
 ```
 
-With either of those definitions `{{TiddlerTitle##b}}` would have the value `two`.
+Note: //It is currently only possible to retrieve data from the immediate properties of the root object of a JSONTiddler.//

editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid

@@ -0,0 +1,12 @@
+created: 20141228094500000
+modified: 20141228094500000
+tags: Concepts
+title: DictionaryTiddlers
+
+A dictionary tiddler is a [[data tiddler|DataTiddlers]] containing a simple list of name/value pairs.
+
+Its [[ContentType]] is `application/x-tiddler-dictionary`.
+
+The `text` field consists of one or more lines of the form <code>//name//: //value//</code>.
+
+[[ColourPalettes]], such as the [[default Vanilla palette|$:/palettes/Vanilla]], are dictionary tiddlers.

editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid

@@ -0,0 +1,10 @@
+created: 20141228094500000
+modified: 20141228094500000
+tags: Concepts
+title: JSONTiddlers
+
+A JSON tiddler is a [[data tiddler|DataTiddlers]] containing a [[JSON]] structure in its `text` field.
+
+Its [[ContentType]] is `application/json`.
+
+The [[history list|$:/HistoryList]] is a good example of a JSON tiddler.

editions/tw5.com/tiddlers/concepts/TagTiddlers.tid

@@ -0,0 +1,10 @@
+created: 20141228094500000
+modified: 20141228094500000
+tags: Concepts
+title: TagTiddlers
+
+A tag tiddler is any tiddler that is in use as a tag.
+
+The ''Tagging'' tab on the InfoPanel of a tag tiddler shows which tiddlers are tagged with the tag tiddler.
+
+A tag can be used without a corresponding tag tiddler.