Documentation improvements

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

@@ -0,0 +1,31 @@
+title: CompoundTiddlers
+modified: 20240507221902644
+created: 20240507221902644
+tags: Concepts
+
+Compound tiddlers are a special type of tiddler that can store one or more payload tiddlers. The tiddlers within a compound tiddler are only accessible via special operations, typically with the TestCaseWidget.
+
+The compound tiddler format is extremely simple, and includes the notable flaw that it does not permit tiddlers that contain a plus sign (`+`) on a line by itself. It is not intended as a general purpose way of storing tiddler data.
+
+Compound tiddlers are identified by having their type field set to `text/vnd.tiddlywiki-multiple`.
+
+The content of a compound tiddler consists of a sequence of tiddlers separated by a plus sign (`+`) on a line by itself. Each tiddler uses the same format as [[.tid files|TiddlerFiles]].
+
+For example:
+
+```
+title: First
+tags: one two
+
+This is the first tiddler
++
+title: Second
+tags: three four
+
+This is the second tiddler
++
+title: third
+tags: five six
+
+This is the third tiddler
+```

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

@@ -1,13 +1,24 @@
 title: TestCaseTiddlers
+modified: 20240507221902644
+created: 20240507221902644
+tags: Concepts
 
+Testcase tiddlers encapsulate one or more tiddlers that can be displayed as a [[testcase|TestCaseWidget]]: an independent embedded wiki that can be used for testing or learning purposes.
 
+Testcase tiddlers are formatted as CompoundTiddlers, allowing them to contain multiple tiddlers packed into one.
 
-Behind the scenes, the templates used to view TestCaseTiddlers use the <<.wlink TestCaseWidget>> widget.
+Testcase tiddlers have the following fields:
 
-! Testcase Conventions
+|!Field |!Description |
+|<<.field type>> | Should be set to `text/vnd.tiddlywiki-multiple` |
+|<<.field tags>> | Testcases are tagged [[$:/tags/wiki-test-spec]]. Test cases that intentionally fail are tagged [[$:/tags/wiki-test-spec-failing]] |
+|<<.field description>> |Descriptive heading for the test, intended to make it easy to identify the test |
+|<<.field display-format>> |Optional, defaults to `wikitext`. Set to `plaintext` to cause the output to be rended as plain text |
 
-The following conventions are used for testcase tiddlers:
+Some payload tiddlers are set aside for special purposes:
+
+|!Tiddler |!Description |
+|''Narrative'' |Narrative description of the test, intended to explain the purpose and operation of the test |
+|''Output'' |The tiddler that produces the test output |
+|''~ExpectedResult'' |HTML of expected result of rendering the ''Output'' tiddler |
 
-* `Description` contains a brief description of the test (rendered in inline mode)
-* `Output` contains the tiddler text to be rendered. It can also reference other tiddlers
-* `ExpectedResult` contains the HTML that should match the rendering of the tiddler `Output`

editions/tw5.com/tiddlers/widgets/DataWidget.tid

@@ -40,22 +40,3 @@ The attribute <<.attr $filter>> is used to ingest multiple tiddlers from the wik
 [[Compound tiddlers|CompoundTiddlers]] provide a way to easily create multiple tiddlers from within a single tiddler. They are contained in tiddlers of type `text/vnd.tiddlywiki-multiple`. The text field consists of a series of tiddlers in the same format as `.tid` files, each separated by a line containing a single `+` character.
 
 <<testcase "TestCases/DataWidget/ImportCompound">>
-
-Here is a more complex example of the content of a compound tiddler:
-
-```
-title: First
-tags: one two
-
-This is the first tiddler
-+
-title: Second
-tags: three four
-
-This is the second tiddler
-+
-title: third
-tags: five six
-
-This is the third tiddler
-```

editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid

@@ -11,6 +11,8 @@ The <<.wid testcase>> widget is designed to present interactive example test cas
 
 This makes it possible to run independent tests that also serve as documentation examples.
 
+The <<.wid testcase>> widget can be used directly as documented below, but it is generally easier to create [[TestCaseTiddlers]]. These are special CompoundTiddlers that can contain multiple payload tiddlers making up a testcase.
+
 !! Features
 
 Here is an example of a testcase showing the default split view with the source tiddlers on the left and the tiddler titled `Output` rendered on the right.
@@ -27,12 +29,6 @@ If the test fails, a red cross is shown, and there is a display of the differenc
 
 <<testcase "TestCases/TestCaseWidget/FailingTest">>
 
-!! Usage
-
-The <<.wid testcase>> widget can be used directly as documented below, but it is generally easier to create [[TestCaseTiddlers]]. These are special CompoundTiddlers that can contain multiple payload tiddlers making up a testcase.
-
-Note that the rendering of the testcase wiki will inherit variables that are visible to the <<.wid testcase>> widget itself.
-
 ! Limitations
 
 The <<.wid testcase>> widget creates a lightweight TiddlyWiki environment that is a parasite of the main wiki. Because it is not a full, independent TiddlyWiki environment, there are some important limitations:
@@ -71,7 +67,7 @@ The default testcase template assigns special meanings to a number of payload ti
 |''Output'' |The tiddler that produces the test output |
 |''~ExpectedResult'' |HTML of expected result of rendering the ''Output'' tiddler |
 
-The default template uses several variables that can be set by the user:
+The testcase wiki will inherit variables that are visible to the <<.wid testcase>> widget itself. The default template uses several variables that can be set by the user:
 
 |!Variable |!Description |
 |<<.var linkTarget>> |Causes the testcase description to be rendered as a link to the current tiddler |