mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-06-18 11:29:55 +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
parent
ef9878802a
commit
376b447570
|
|
@ -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]].
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
21
editions/tw5.com/tiddlers/concepts/Transclusion.tid
Normal file
21
editions/tw5.com/tiddlers/concepts/Transclusion.tid
Normal 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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
17
editions/tw5.com/tiddlers/system/style-guide-macros.tid
Normal file
17
editions/tw5.com/tiddlers/system/style-guide-macros.tid
Normal 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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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]]
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue
Block a user