mirrors
/
TiddlyWiki5
mirror of https://github.com/Jermolene/TiddlyWiki5
1
0
Fork 0
Code Issues Releases Wiki Activity

Documentation improvements

This commit is contained in:
Jeremy Ruston 2024-05-08 17:50:27 +01:00
parent 8207b80f9f
commit edc6661948
4 changed files with 51 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
editions/tw5.com/tiddlers/concepts/CompoundTiddlers.tid Normal file
View File

@ -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
```

23
editions/tw5.com/tiddlers/concepts/TestCaseTiddlers.tid
View File

@ -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`

19
editions/tw5.com/tiddlers/widgets/DataWidget.tid
View File

@ -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
```

10
editions/tw5.com/tiddlers/widgets/TestCaseWidget.tid
View File

@ -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 |