1
0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-06-14 17:39:56 +00:00

Documentation tweaks

@erwanm I ended up making some fairly extensive tweaks.

One issue is that the (excellent) material you’ve provided on
transclusion with templates covers very much the same ground as the
existing TemplateTiddlers tiddler. The existing text was focused on
transclusion with widgets; I think your material using transclusion
notation is much easier to understand.

I’ve also removed the exercises section. We don’t have exercises
elsewhere in the documentation, so I think we need to make a conscious
decision about whether we’re going to try to add them, and then do so
consistently across the material.

I also made some changes to bring the text into house style for
consistency (which I’ve also tried to start documenting).
This commit is contained in:
Jermolene 2014-12-10 17:08:59 +00:00
parent ef9878802a
commit 376b447570
10 changed files with 167 additions and 150 deletions

View File

@ -4,10 +4,61 @@ title: Documentation Style Guide
tags: Improving TiddlyWiki Documentation
type: text/vnd.tiddlywiki
The documentation for ~TiddlyWiki tries to follow the following guidelines. The aim is to ensure that documentation from different authors reads consistently.
The documentation for ~TiddlyWiki tries to follow a consistent style. The aim is to ensure that documentation from different authors reads consistently.
# Do address the reader directly as "you"
# Avoid the [[passive voice|http://grammar.ccc.commnet.edu/grammar/passive.htm]] in tutorial and introductory material
# Do use [[British spellings in preference to US spellings|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]]
! Tone
Tutorial documentation may address the user as "you" for clarity and immediacy. Reference documentation should use a more formal [[passive voice|http://grammar.ccc.commnet.edu/grammar/passive.htm]].
For example, this would be reasonable for tutorial documentation:
> You can add a new sidebar tab by creating a specially tagged tiddler
But for reference documentation this would be better:
> Tiddlers with a special tag are displayed as sidebar tabs
! Tiddler Title Policy
The following conventions govern how tiddler titles are composed:
* Use lowercase single words for tags
** e.g. [[task]], [[demo]]
* Use CamelCase for definitions and concepts
** e.g. TiddlerFields, DeveloperDocs
* Use separate words for titles that are full phrases or sentences, such as FAQ, howtos or tasks
** e.g. [[How to build a TiddlyWiki5 from individual tiddlers]]
* Where TiddlyWiki or TiddlyWiki5 is used as a qualifier at the start of the title, always use separate words
** e.g. [[TiddlyWiki on Node.js]]
! Spelling
Use [[British spellings in preference to US spellings|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]].
! Abbreviations
We try to avoid abbreviations, but the following are acceptable:
* `e.g.` for ''for example''
* `i.e.` for ''that is to say''
Note that the periods should not be omitted from these abbreviations.
! Typographic Standards
!! Referring to Titles, Fields, Tags
* ''Titles'' of tiddlers should usually be typed as links
* ''Tag names'' should usually be typed as links
* ''Field names'' should be typed in bold: e.g. ''title'', ''tags'', ''caption''
* ''Tab names'' should be typed in bold: e.g.
!! Headings
Initial capitalisation is preferred, where the initial letter of most words is capitalised. The exceptions are small conjunctions and prepositions like "and", "or", "the", "to", etc.
<<style-guide
"""!! How to Configure Default Tiddlers"""
"""!! How to configure default tiddlers"""
>>
See also the guidelines for [[tiddler titles|Adopt a Titles Policy]].

View File

@ -4,37 +4,15 @@ tags: Concepts
title: TemplateTiddlers
type: text/vnd.tiddlywiki
A template tiddler is not in fact a type of tiddler, it is a role in which a tiddler can be used.
A template tiddler is not actually a type of tiddler, it is a role in which a tiddler can be used.
When text is wikified there is the concept of the CurrentTiddler. Certain widgets (like the ViewWidget) can use the current tiddler implicitly. For example:
Templates are a way to re-use chunks of WikiText.
```
<$view tiddler="HelloThere" field="myfield"/> - displays the field "myfield" of the tiddler HelloThere
<$view field="myfield"/> - displays the field "myfield" of the current tiddler
```
Transcluding through a template extends the basic functionality of [[Transclusion]] by combining two tiddlers:
When the TranscludeWidget pulls in the content from another tiddler, by default it does not change the current tiddler, so the transcluded content behaves as if it were in the context of the transcluding tiddler.
* A template tiddler that contains the WikiText to be displayed. It can contain transclusions that reference fields in the CurrentTiddler
* A target tiddler that identifies the CurrentTiddler to be used when resolving references to fields
So, if we have a tiddler "A" that contains:
The best example of templating is the main story river in TiddlyWiki. Each tiddler in the story river is rendered through a ViewTemplate that specifies how each field is to be rendered.
```
<$view field="myfield"/>
```
And then transclude it from a tiddler "B" like so:
```
My field value is: <$transclude tiddler="A"/>
```
The result will be that the field from the tiddler "B" is displayed; in other words, tiddler "A" is acting as a template for displaying information from tiddler "B".
The TiddlerWidget is used to change the current tiddler. Consider a tiddler "C" containing:
```
<$tiddler tiddler="A"><$transclude tiddler="A"/></$tiddler>
```
It is still transcluding tiddler "A", but now it is also setting the current tiddler to "A". The result is therefore that the field "myfield" for tiddler "A" is displayed.
The shorthand syntax for [[Transclusion in WikiText]] actually generates both a TiddlerWidget and a TranscludeWidget.
See [[Transclusion with Templates]] for details.

View File

@ -0,0 +1,21 @@
created: 20141129194651420
modified: 20141130195444237
tags: Concepts
title: Transclusion
<a href="http://en.wikipedia.org/wiki/Transclusion">Transclusion</a> is the process of referencing one tiddler "A" from another tiddler "B" such that the content of "A" appears to be a part of "B".
Copying and pasting content creates multiple copies of the same content in several different places. With transclusion, there can be a single copy and a special instruction in "B" which indicates the point at which content should be inserted from tiddler "A".
Note that if the content of "A" is modified then the modification automatically appears in "B". This makes it easier to maintain repetitive content, by allowing every piece to be written in a single place, but viewed from many.
The concept of transclusion plays an important role in the [[Philosophy of Tiddlers]] because it is the primary way in which small items of content are combined.
To learn more:
* [[Transclusion in WikiText]]
* [[Transclusion Basic Usage]]
* [[Transclusion with Templates]]
* TextReference
* TemplateTiddlers
* TranscludeWidget

View File

@ -1,44 +0,0 @@
created: 20141129201509859
creator: Erwan
modified: 20141130194810119
modifier: Erwan
tags: Transclusion
title: TransclusionBasicUsage
! Simple transclusion
To include some content from ~TiddlerA into ~TiddlerB, edit the latter and write:
```
This is the content of TiddlerA: {{TiddlerA}}
```
As a result, the content of the field ``text`` (i.e. the main content) of ~TiddlerA is rendered in ~TiddlerB.
! Usage
The notation ``{{TiddlerA}}`` is actually a shortcut for ``{{TiddlerA!!text}}``. This is because by default the transcluded field is ``text``, but any other [[field|TiddlerFields]] can be used explicitly. For example, you can print the last time ~TiddlerA was modified using:
```
TiddlerA was modified on {{TiddlerA!!modified}}
```
The ``{{...!!...}}`` notation is also used to display the content of a field from the current tiddler, for example:
```
The current tiddler was modified on {{!!modified}}
```
This is because displaying a field is also a form of transclusion. In this case, the notation ``{{!!modified}}`` used in ~TiddlerB is equivalent to ``{{TiddlerB!!modified}}``. In other words, the default value for the part before ``!!`` is the title of the current tiddler.
! Recursion errors
Notice that using ``{{!!text}}`` or ``{{}}`` causes an error (//Recursive transclusion error in transclude widget//), because it does not make sense to include the content of the current tiddler into the content of the current tiddler (that is, into itself). Whenever you encouter this error message, it means that you are trying to include something into itself, directly or not (for example if tiddler A transcludes tiddler B which transcludes tiddler C which, in turn, transcludes tiddler A).
! Going further
In TiddlyWiki, transclusions are not limited to including raw content like the above. To learn about a more advanced kind of transclusion, see TransclusionAsTemplateUsage.
See also: TransclusionAsTemplateUsage, [[Transclusion in WikiText]], TextReference, and TiddlerFields.

View File

@ -1,14 +0,0 @@
created: 20141129194651420
creator: Erwan
modified: 20141130195444237
modifier: Erwan
tags: Transclusion
title: TransclusionPrinciple
A <a href="http://en.wikipedia.org/wiki/Transclusion">transclusion</a> consists in including some content from a tiddler A into another tiddler B //by reference//.
This means that, instead of having the same content in two different places (as what happens if the content is "copy-pasted" from A to B), there is a special instruction in B which indicates that this part should be taken from tiddler A. The first advantage is that if something is modified in A, the modification appears automatically in B as well. Thus it is easier to maintain inter-dependent content, since every piece of content is written in a single place, but can be viewed from many.
In TiddlyWiki the concept of transclusion plays a very important role because the [[Philosophy of Tiddlers]] is to connect small pieces of information together. But the concept is extended even further to allow for various kinds of useful features. To learn how to use it, see TransclusionBasicUsage and TransclusionAsTemplateUsage.
See also: TransclusionBasicUsage, TransclusionAsTemplateUsage, [[Transclusion in WikiText]], TextReference, TemplateTiddlers and TranscludeWidget.

View File

@ -6,17 +6,8 @@ type: text/vnd.tiddlywiki
As the structures within your TiddlyWiki documents get more complex it can be hard to keep the titles of tiddlers consistent. For example, should terms be defined in the plural or the singular? Camel case or separate words?
Recording a formal titling policy can help to reduce confusion. For example, the titling policies for this wiki are:
Recording a formal titling policy can help to reduce confusion. For example, the titling policies for this wiki are recorded in the [[Documentation Style Guide]].
* Use lowercase single words for tags
** e.g. [[task]], [[demo]]
* Use CamelCase for definitions and concepts
** e.g. TiddlerFields, DeveloperDocs
* Use separate words for titles that are full phrases or sentences, such as FAQ, howtos or tasks
** e.g. [[How to build a TiddlyWiki5 from individual tiddlers]]
* Where TiddlyWiki or TiddlyWiki5 is used as a qualifier at the start of the title, always use separate words
** e.g. [[Saving with TiddlyFox]]
! SystemTiddler Titles
Policies that may make sense for your own wikis include:
* Use the prefix `$:/_` for any system tiddlers that you create to ensure that they are near the top of the system tiddler listing in the sidebar
A useful convention is to use the prefix `$:/_` for any system tiddlers that you create to ensure that they are near the top of the system tiddler listing in the sidebar

View File

@ -0,0 +1,17 @@
title: $:/editions/tw5.com/style-guide-macros
tags: $:/tags/Macro
\define style-guide(good,bad)
<table>
<tbody>
<tr>
<th>Good</th>
<td>``$good$``</td>
</tr>
<tr>
<th>Bad</th>
<td>``$bad$``</td>
</tr>
</tbody>
</table>
\end

View File

@ -0,0 +1,45 @@
created: 20141129201509859
modified: 20141130194810119
tags: [[Transclusion in WikiText]]
title: Transclusion Basic Usage
caption: Basic Usage
! Simple Transclusion
To include some content from [[TiddlerA]] into [[TiddlerB]], edit the latter to include the following text:
```
This is the content of TiddlerA: {{TiddlerA}}
```
The result is that the content of the ''text'' field (i.e. the main content) of [[TiddlerA]] is rendered within [[TiddlerB]].
! Usage
The notation ``{{TiddlerA}}`` is a shortcut for ``{{TiddlerA!!text}}``. This is because the default field for transclusion is ''text'', but any other [[field|TiddlerFields]] can be used explicitly. For example, you can print the last time TiddlerA was modified using:
```
TiddlerA was modified on {{TiddlerA!!modified}}
```
By omitting the tiddler title, the transclusion notation can also be used to display the content of a field from the current tiddler, for example:
```
The current tiddler was modified on {{!!modified}}
```
! Recursion Errors
Notice that using ``{{!!text}}`` or ``{{}}`` causes an error (//Recursive transclusion error in transclude widget//), because it does not make sense to include the content of the current tiddler into the content of the current tiddler (that is, into itself). Whenever you encouter this error message, it means that you are trying to include something into itself, directly or indirectly (for example if tiddler A transcludes tiddler B which transcludes tiddler C which, in turn, transcludes tiddler A).
! Learning More
In TiddlyWiki, transclusions are not limited to including raw content like the above. To learn about more advanced uses of transclusion, see [[Transclusion with Templates]].
See also:
* [[Transclusion]]
* [[Transclusion with Templates]]
* [[Transclusion in WikiText]]
* TextReference
* TiddlerFields.

View File

@ -5,7 +5,7 @@ title: Transclusion in WikiText
type: text/vnd.tiddlywiki
caption: Transclusion
You can incorporate the content of one tiddler within another using the transclusion notation:
You can incorporate the content of one tiddler within another using the [[Transclusion]] notation:
* `{{MyTiddler}}` transcludes a single tiddler
* `{{MyTiddler||TemplateTitle}}` displays the tiddler through a specified [[TemplateTiddler|TemplateTiddlers]]
@ -27,4 +27,8 @@ A similar syntax can be used to transclude a list of tiddlers matching a specifi
See also:
* [[Transclusion Basic Usage]]
* [[Transclusion with Templates]]
* TemplateTiddlers
* TranscludeWidget
* [[Confusion between Transclusion and Substitution]]

View File

@ -1,14 +1,12 @@
created: 20141129210304238
creator: Erwan
modified: 20141209142028738
modifier: Erwan
tags: Transclusion
title: TransclusionAsTemplateUsage
tags: [[Transclusion in WikiText]]
title: Transclusion with Templates
caption: With Templates
! Problem
! Introduction
In TransclusionBasicUsage we have seen how to include the content of a tiddler A into a tiddler B. Now suppose that tiddler A contains:
In [[Transclusion Basic Usage]] we have seen how to include the content of a tiddler A into a tiddler B. Now suppose that tiddler A contains:
```
@@background-color:yellow;
@ -26,9 +24,7 @@ Hello, my title is A
The style is applied as expected, but the title is wrong: we want ``{{!!title}}`` to refer to the target tiddler B, and not the source tiddler A.
! Solution
Thankfully TiddlyWiki provides a way to do exactly that, using ''templates''. In this case, the source tiddler A is called the [[TemplateTiddler|TemplateTiddlers]], and it is //applied// to tiddler B using the notation ``{{||A}}``. The difference is that any TextReference which does not refer explicitly to a specific tiddler is applied to the [[current tiddler|CurrentTiddler]], that is, the target tiddler. As a result, tiddler B now looks as expected:
The solution is to use a \\template\\. In this case, the source tiddler A is called the [[TemplateTiddler|TemplateTiddlers]], and it is //applied// to tiddler B using the notation ``{{||A}}``. The difference is that any TextReference which does not refer explicitly to a specific tiddler is applied to the [[current tiddler|CurrentTiddler]], that is, the target tiddler. As a result, tiddler B now looks as expected:
<<<
@@background-color:yellow;
@ -54,39 +50,11 @@ You can apply the system template ``$:/core/ui/TagTemplate`` to a tag in order t
is rendered as {{Transclusion||$:/core/ui/TagTemplate}}
!! An exercise
See also:
Create three tiddlers A, B and C with the following content:
!!! in A:
```
Hello, my name is {{!!title}} and the last time I was modified is {{!!modified}}
```
!!! in B:
```
{{||A}}
```
!!! in C:
```
{{B}}
```
# Can you make C print //"Hello, my name is C ..."// without referring to A directly?
# Can you make C print //"Hello, my name is A ..."// without modifying C?
<$button set="$:/TransclusionAsTemplateUsageExerciseState1" setTo="show">Show the answers</$button>
<$reveal type="match" state="$:/TransclusionAsTemplateUsageExerciseState1" text="show">
# In tiddler C, replace ``{{B}}`` with ``{{||B}}``
# In tiddler B, replace ``{{||A}}`` with ``{{A}}``
<$button set="$:/TransclusionAsTemplateUsageExerciseState1" setTo="hide">Hide the answers</$button>
</$reveal>
See also [[Transclusion in WikiText]], TextReference, CurrentTiddler and TemplateTiddlers.
* [[Transclusion in WikiText]]
* [[Transclusion Basic Usage]]
* TextReference
* TemplateTiddlers
* TranscludeWidget
* CurrentTiddler