From 5cee932833624da18e2456a916beae0015df6739 Mon Sep 17 00:00:00 2001 From: roma0104 Date: Tue, 18 Nov 2014 18:02:51 -0600 Subject: [PATCH 01/33] Update GSD5/Briefcase site address and naming. --- .../tiddlers/community/resources/Briefcase mGSD.tid | 12 ------------ .../tw5.com/tiddlers/community/resources/GSD5.tid | 10 ++++++++++ 2 files changed, 10 insertions(+), 12 deletions(-) delete mode 100644 editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid create mode 100644 editions/tw5.com/tiddlers/community/resources/GSD5.tid diff --git a/editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid b/editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid deleted file mode 100644 index 50b545583..000000000 --- a/editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid +++ /dev/null @@ -1,12 +0,0 @@ -created: 20140916203526273 -modified: 20140916203526273 -tags: Resources -title: "Briefcase" by Roma Hicks -type: text/vnd.tiddlywiki -url: https://drive.google.com/open?id=0Bydfk9tNRJHBc3FvclFBMzRreTQ&authuser=0 - -An adaptation of the [[TiddlyWiki powered GTD® system formerly known as MonkeyGTD|http://mgsd.tiddlyspot.com/]] for TiddlyWiki version 5. - -<<< -Briefcase is a Getting-Thing-Done tool for TiddlyWiki5 based off the mGSD classic TiddlyWiki. -<<< diff --git a/editions/tw5.com/tiddlers/community/resources/GSD5.tid b/editions/tw5.com/tiddlers/community/resources/GSD5.tid new file mode 100644 index 000000000..081ff010c --- /dev/null +++ b/editions/tw5.com/tiddlers/community/resources/GSD5.tid @@ -0,0 +1,10 @@ +tags: Resources +title: "Briefcase" by Roma Hicks +type: text/vnd.tiddlywiki +url: http://gsd5.tiddlyspot.com/ + +An adaptation of the [[TiddlyWiki powered GTD® system formerly known as MonkeyGTD|http://mgsd.tiddlyspot.com/]] for TiddlyWiki version 5. + +<<< +GSD5 is a Getting-Thing-Done tool for TiddlyWiki5 based off the mGSD classic TiddlyWiki. +<<< From 438db4d868670b38e46f94a91c692abbae09cd88 Mon Sep 17 00:00:00 2001 From: roma0104 Date: Tue, 18 Nov 2014 18:11:59 -0600 Subject: [PATCH 02/33] Signed the CLA. --- licenses/cla-individual.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/licenses/cla-individual.md b/licenses/cla-individual.md index 99d3491ad..123e7ca9b 100644 --- a/licenses/cla-individual.md +++ b/licenses/cla-individual.md @@ -182,3 +182,5 @@ Mark S., @marxsal, 2014/10/18 Erwan Moreau, @erwanm, 2014/10/27 Felix Küppers, @felixhayashi, 2014/11/02 + +Roma Hicks, @roma0104, 2014/11/18 \ No newline at end of file From 8e47a200694eed495e96fb07184af01c3df9850c Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 14:59:16 +0000 Subject: [PATCH 03/33] Improvements to wording --- editions/tw5.com/tiddlers/howtos/Tagging.tid | 45 ++++++++++++-------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/editions/tw5.com/tiddlers/howtos/Tagging.tid b/editions/tw5.com/tiddlers/howtos/Tagging.tid index 139112035..32e3812ca 100644 --- a/editions/tw5.com/tiddlers/howtos/Tagging.tid +++ b/editions/tw5.com/tiddlers/howtos/Tagging.tid @@ -4,33 +4,42 @@ tags: [[Working with TiddlyWiki]] Concepts title: Tagging type: text/vnd.tiddlywiki -Tagging a tiddler assigns a tiddler to a category of your choosing (see [[Creating and editing tiddlers]] for instructions on how to tag). For example, tiddlers representing individuals might be tagged ''friend'', ''family'', ''colleague'' etc to indicate the relationship to the author. Multiple tags can be applied to the same tiddler. +Tagging is a way of organising tiddlers into categories. For example, if you had tiddlers representing various individuals, you could tag them as ''friend'', ''family'', ''colleague'' etc to indicate these people's relationships to you. -Tagging tiddlers gives you numerous additional ways to view, navigate and organise your information: +A tag is in fact just a tiddler (or a potential tiddler), and it can have tags of its own. You can add any number of tags to the same tiddler. -* The coloured tag pills on a tagged tiddler give you links to all the other tiddlers with the same tag, as well as to the tiddler representing the tag itself. -* The ''Tagging'' tab in the tiddler info panel (accessed by clicking the {{$:/core/images/info-button}} button) gives you links to all the tiddlers tagged with the title of the current tiddler. +See [[Creating and editing tiddlers]] for instructions on how to tag. -* You can use the tags tab in the ''More'' sidebar tab to view all your tags and access your tagged tiddlers. +By tagging your tiddlers, you can view, navigate and organise your information in numerous additional ways: -* You can use [[filters|Filters]] to create lists of tiddlers based on tags, then display whichever combination of tiddler fields you wish. For example, you can create a list that shows both the title and the text of all tiddlers tagged ''Glossary''. Such lists can be formatted however you wish: for example: bulleted, numbered, or comma-separated. +* The coloured tag pills on a tiddler give you quick access to all the other tiddlers with the same tag, as well as to the tiddler that represents the tag itself. -* System tags can be used to customise the layout of tiddlers and the entire ~TiddlyWiki page. See [[Page and tiddler layout customisation]] for instructions. +* If a tiddler is serving as a tag, then the ''Tagging'' tab in its InfoPanel will show you which tiddlers are currently tagged with it. + +* The ''More'' tab of the sidebar has a ''Tags'' tab that presents an overview of all your tags and lets you access all your tagged tiddlers. + +* You can use [[filters|Filters]] to create lists of tiddlers based on their tags. You can then display any combination of the [[fields|TiddlerFields]] of those tiddlers. For example, you could build a glossary by listing the title and text of all tiddlers tagged ''Glossary''. Such lists can be formatted in any way you wish: e.g. bulleted, numbered or comma-separated. + +* There are a number of special ''system tags'' that control the layout of tiddlers and the entire ~TiddlyWiki page. See [[Page and tiddler layout customisation]] for instructions. There are two more things you can do with tags: -! Assign colours and icons to a tag +! Set a tag's colour and icon -You can use the [[tag manager|$:/TagManager]], found in the ''Tags'' tab of the ''More'' sidebar tab, to assign background colours and/or icons to a tag. +You can use the [[tag manager|$:/TagManager]], found in the sidebar under ''More'' → ''Tags'', to change the colour of a tag's pill or add an icon to the pill. -* Colours can be assigned to a tag either by specifying the CSS colour value in the upper window in the colour column, or choosing a colour from the dropdown colour picker provided. -* Icons can be assigned to a tag by clicking the {{$:/core/images/down-arrow}} button in the icon column and choosing one of the icons listed. +* To change the colour, click the button in the ''Colour'' column to select from a colour picker. Alternatively, click the icon in the ''Info'' column, then type a [[CSS]] colour value in the ''Colour'' field +* To change the icon, click the {{$:/core/images/down-arrow}} button in the ''Icon'' column and choose from the list of available icons -! Use list fields to adjust the ordering of tag lists +! Change the order in which tags are listed -* If you want to create a list of tagged tiddlers with a [[filter|Filters]], but want the tiddlers to be listed in a special order rather than the default alphabetical order, you can create a field called ''list'' in the tag tiddler, and add the titles of the tiddlers to the field in the order you wish. ~TiddlyWiki will order lists of tagged tiddlers in the following order of priority: -** First, any tiddlers that are listed in the ListField of the tag tiddler are placed into a new list in the same order -** Second, any unplaced tiddlers that have the field ''list-before'' are placed before the tiddler specified in the field -*** (if the ''list-before'' field is empty then the unplaced tiddler is placed at the start of the list) -** Third, if any unplaced tiddlers have the field ''list-after'' then they are placed immediately after the tiddler specified in the field -** Finally, any remaining unplaced tiddlers are placed at the end of the list +By default, tagged tiddlers are listed in the order they were added to the wiki. The [[sort operator|Filter operator: sort]] can change the order to alphabetical. + +If you want any other order, add a [[field called ''list''|ListField]] to the tag tiddler, and set its value to be a [[TiddlerChain]] of the tiddlers in that order. + +The ''list'' field doesn't have to mention all of the tiddlers. Here are the precise rules ~TiddlyWiki uses to order tagged tiddlers: + +# Start with the tiddlers in the ''list'' field, in the sequence given there. +# In each remaining tiddler, look for a ''list-before'' field. If this has a tiddler title as its value, insert the tiddler into the sequence just before that one. As a special case, if the field's value is blank, add the tiddler at the very start of the sequence. +# In each remaining tiddler, look for a ''list-after'' field. If this has a tiddler title as its value, insert the tiddler into the sequence just after that one. +# If any tiddlers still remain, add them to the very end of the sequence. From 39c786b042e641d24940b00ec7ae727bb10503f4 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 15:05:17 +0000 Subject: [PATCH 04/33] Link to the TiddlerChain tiddler --- .../tiddlers/workingwithtw/Creating journal tiddlers.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid b/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid index d0ebce43d..ce69f29c6 100644 --- a/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid +++ b/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid @@ -29,7 +29,7 @@ For example, you might be reviewing a tiddler called ''Oxford Street'' and reali To configure how new journal entries are created, visit the ''Basics'' tab under ''Info'' in the [[control panel|$:/ControlPanel]]: * "Title of new journal tiddlers" specifies how these tiddlers should be named, as a [[date format string|DateFormat]]. The default setting of `DDth MMM YYYY` causes new entries to have titles of the form "10th October 2014" -* "Tags for new journal tiddlers" specifies tags that will automatically appear on new journal entries. Type a space between each tag and the next. If any of the tags //contains// a space, place double square brackets around it. For example: `Journal [[Summer vacation]]` +* "Tags for new journal tiddlers" [specifies|TiddlerChain] tags that will automatically appear on new journal entries. For example: `Journal [[Summer vacation]]` Hint: if you want to create a separate journal tiddler whenever you click ''new journal'' (even if you do this several times in the same day), you can include the clock time in the title format. Specify something like `YYYY-0MM-0DD at 0hhh0mm'0ss''` as the date format. From 304848f2586f72c4e6021da0db3e0043988a356d Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 15:06:18 +0000 Subject: [PATCH 05/33] Add a TiddlerChain tiddler For the common but unnamed concept of a "string [[of tiddler]] titles" like that. --- editions/tw5.com/tiddlers/concepts/TiddlerChain.tid | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/TiddlerChain.tid diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerChain.tid b/editions/tw5.com/tiddlers/concepts/TiddlerChain.tid new file mode 100644 index 000000000..c9d46427f --- /dev/null +++ b/editions/tw5.com/tiddlers/concepts/TiddlerChain.tid @@ -0,0 +1,12 @@ +tags: Concepts +title: TiddlerChain + +A tiddler chain is a line of text that presents one or more tiddler titles, strung together with a space between each one and the next. + +If a title //contains// a space, it needs double square brackets around it. + +Example: + +`GettingStarted [[Discover TiddlyWiki]] Upgrading` + +Tiddler chains are used in various places, including PermaLinks and the ListField. From 7ca37739aadb72906cfcd984b1969b5a7bc3fb6d Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 17:32:45 +0000 Subject: [PATCH 06/33] Simplify style of arrow in tab hierarchy This is something that --- editions/tw5.com/tiddlers/howtos/Tagging.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/howtos/Tagging.tid b/editions/tw5.com/tiddlers/howtos/Tagging.tid index 32e3812ca..8d9cdb44c 100644 --- a/editions/tw5.com/tiddlers/howtos/Tagging.tid +++ b/editions/tw5.com/tiddlers/howtos/Tagging.tid @@ -26,7 +26,7 @@ There are two more things you can do with tags: ! Set a tag's colour and icon -You can use the [[tag manager|$:/TagManager]], found in the sidebar under ''More'' → ''Tags'', to change the colour of a tag's pill or add an icon to the pill. +You can use the [[tag manager|$:/TagManager]], found in the sidebar under ''More'' > ''Tags'', to change the colour of a tag's pill or add an icon to the pill. * To change the colour, click the button in the ''Colour'' column to select from a colour picker. Alternatively, click the icon in the ''Info'' column, then type a [[CSS]] colour value in the ''Colour'' field * To change the icon, click the {{$:/core/images/down-arrow}} button in the ''Icon'' column and choose from the list of available icons From 25e447f69ed176017722aa151d8282343fc779b2 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 21:46:20 +0000 Subject: [PATCH 07/33] Rephrase route through tabs Provisionally, rather than using any sort of arrow symbol. We need to standardise a notation for referring to hierarchical UI, but that will come with the documentation style guide. --- editions/tw5.com/tiddlers/howtos/Tagging.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/howtos/Tagging.tid b/editions/tw5.com/tiddlers/howtos/Tagging.tid index 8d9cdb44c..245fb9cc4 100644 --- a/editions/tw5.com/tiddlers/howtos/Tagging.tid +++ b/editions/tw5.com/tiddlers/howtos/Tagging.tid @@ -26,7 +26,7 @@ There are two more things you can do with tags: ! Set a tag's colour and icon -You can use the [[tag manager|$:/TagManager]], found in the sidebar under ''More'' > ''Tags'', to change the colour of a tag's pill or add an icon to the pill. +You can use the [[tag manager|$:/TagManager]], found on the ''Tags'' tab under ''More'' in the sidebar, to change the colour of a tag's pill or add an icon to the pill. * To change the colour, click the button in the ''Colour'' column to select from a colour picker. Alternatively, click the icon in the ''Info'' column, then type a [[CSS]] colour value in the ''Colour'' field * To change the icon, click the {{$:/core/images/down-arrow}} button in the ''Icon'' column and choose from the list of available icons From cc2688bf44746a4675227669aadbcab21e7cbda6 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 21:55:04 +0000 Subject: [PATCH 08/33] Update and rename TiddlerChain.tid to TitleList.tid --- editions/tw5.com/tiddlers/concepts/TiddlerChain.tid | 12 ------------ editions/tw5.com/tiddlers/concepts/TitleList.tid | 12 ++++++++++++ 2 files changed, 12 insertions(+), 12 deletions(-) delete mode 100644 editions/tw5.com/tiddlers/concepts/TiddlerChain.tid create mode 100644 editions/tw5.com/tiddlers/concepts/TitleList.tid diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerChain.tid b/editions/tw5.com/tiddlers/concepts/TiddlerChain.tid deleted file mode 100644 index c9d46427f..000000000 --- a/editions/tw5.com/tiddlers/concepts/TiddlerChain.tid +++ /dev/null @@ -1,12 +0,0 @@ -tags: Concepts -title: TiddlerChain - -A tiddler chain is a line of text that presents one or more tiddler titles, strung together with a space between each one and the next. - -If a title //contains// a space, it needs double square brackets around it. - -Example: - -`GettingStarted [[Discover TiddlyWiki]] Upgrading` - -Tiddler chains are used in various places, including PermaLinks and the ListField. diff --git a/editions/tw5.com/tiddlers/concepts/TitleList.tid b/editions/tw5.com/tiddlers/concepts/TitleList.tid new file mode 100644 index 000000000..72d06900d --- /dev/null +++ b/editions/tw5.com/tiddlers/concepts/TitleList.tid @@ -0,0 +1,12 @@ +tags: Concepts +title: TitleList + +A title list is a line of text that presents one or more tiddler titles, strung together with a space between each one and the next. + +If a title //contains// a space, it needs double square brackets around it. + +Example: + +`GettingStarted [[Discover TiddlyWiki]] Upgrading` + +Title lists are used in various places, including PermaLinks and the ListField. From 5f3de6ec17b0f1ab3f330ed3713febc815cce66c Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 21:56:00 +0000 Subject: [PATCH 09/33] Change TiddlerChain to TitleList --- .../tiddlers/workingwithtw/Creating journal tiddlers.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid b/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid index ce69f29c6..47f87b23d 100644 --- a/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid +++ b/editions/tw5.com/tiddlers/workingwithtw/Creating journal tiddlers.tid @@ -29,7 +29,7 @@ For example, you might be reviewing a tiddler called ''Oxford Street'' and reali To configure how new journal entries are created, visit the ''Basics'' tab under ''Info'' in the [[control panel|$:/ControlPanel]]: * "Title of new journal tiddlers" specifies how these tiddlers should be named, as a [[date format string|DateFormat]]. The default setting of `DDth MMM YYYY` causes new entries to have titles of the form "10th October 2014" -* "Tags for new journal tiddlers" [specifies|TiddlerChain] tags that will automatically appear on new journal entries. For example: `Journal [[Summer vacation]]` +* "Tags for new journal tiddlers" [specifies|TitleList] tags that will automatically appear on new journal entries. For example: `Journal [[Summer vacation]]` Hint: if you want to create a separate journal tiddler whenever you click ''new journal'' (even if you do this several times in the same day), you can include the clock time in the title format. Specify something like `YYYY-0MM-0DD at 0hhh0mm'0ss''` as the date format. From 19050934118888e3f8416476ac00f4d971505b7a Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Tue, 23 Dec 2014 21:57:18 +0000 Subject: [PATCH 10/33] Change TiddlerChain to TitleList --- editions/tw5.com/tiddlers/howtos/Tagging.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/howtos/Tagging.tid b/editions/tw5.com/tiddlers/howtos/Tagging.tid index 245fb9cc4..5b6cf411d 100644 --- a/editions/tw5.com/tiddlers/howtos/Tagging.tid +++ b/editions/tw5.com/tiddlers/howtos/Tagging.tid @@ -35,7 +35,7 @@ You can use the [[tag manager|$:/TagManager]], found on the ''Tags'' tab under ' By default, tagged tiddlers are listed in the order they were added to the wiki. The [[sort operator|Filter operator: sort]] can change the order to alphabetical. -If you want any other order, add a [[field called ''list''|ListField]] to the tag tiddler, and set its value to be a [[TiddlerChain]] of the tiddlers in that order. +If you want any other order, add a [[field called ''list''|ListField]] to the tag tiddler, and set its value to be a [[TitleList]] of the tiddlers in that order. The ''list'' field doesn't have to mention all of the tiddlers. Here are the precise rules ~TiddlyWiki uses to order tagged tiddlers: From 421d75a207864b0cd6ec9ba28ed1373699e1467d Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:24:47 +0000 Subject: [PATCH 11/33] Initial expansion of the Documentation Style Guide --- .../about/Documentation Style Guide.tid | 71 +++---------------- 1 file changed, 10 insertions(+), 61 deletions(-) diff --git a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid b/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid index c61584675..5da2174a9 100644 --- a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid +++ b/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid @@ -1,69 +1,18 @@ created: 20140904164608166 modified: 20140904164935351 title: Documentation Style Guide -tags: Improving TiddlyWiki Documentation +tags: documenting type: text/vnd.tiddlywiki -The documentation for ~TiddlyWiki tries to follow a consistent style. The aim is to ensure that documentation from different authors reads consistently. +The documentation for ~TiddlyWiki tries to follow a consistent editorial style. It has two main areas, each with its own tone and audience: -! Tone +* [[Instruction Tiddlers]] +* [[Reference Tiddlers]] -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 for ordinary words, 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. - -Technical abbreviations should be in upper case and omit periods: - -* ''HTML'', not ''html'' or ''H.T.M.L.'' -* ''CSS'', not ''css'' - -! 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. ''Open'', ''Appearance'' - -!! 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. - -<> +Keep the two areas distinct, otherwise beginners will be overwhelmed and experts will be denied quick access to information. +* [[Tiddler Titles]] +* [[Tiddler Structure]] +* [[Spelling]] +* [[Typography]] +* [[Technical Prose Style]] From f952b8f1df1b673aa78652216fcffa0caa7b23ee Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:27:38 +0000 Subject: [PATCH 12/33] Create Instruction Tiddlers.tid --- .../tiddlers/about/Instruction Tiddlers.tid | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid diff --git a/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid b/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid new file mode 100644 index 000000000..1c9716482 --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid @@ -0,0 +1,39 @@ +created: 20141226192500000 +created: 20141226192500000 +title: Instruction Tiddlers +tags: documenting + +Instruction tiddlers talk directly to the reader and guide them through a process. The reader is likely to be a beginner or an intermediate user. + +Such tiddlers can be subcategorised as: + +* ''Welcome'' +** What is ~TiddlyWiki and why should I care? +** Demonstrations of key features and benefits +** Frequently asked questions +** Examples of ~TiddlyWiki in the field +** Information about the project itself + +* ''Tutorial'' +** An ordered presentation of material for beginners +** Each tiddler introduces one new point or concept +** Its main content contains very few links +** A revealable "Further reading" section at the end can offer related links + +* ''Exercise'' +** Accompanying a tutorial tiddler +** Solution revealed on demand + +* ''How-to'' +** A list of numbered steps for performing a small specific task +** Concise, with links to reference tiddlers where appropriate +** Often has a preamble to clarify the nature of the task + +* ''Example'' +** Accompanying a [[Reference Tiddler|Reference Tiddlers]] +** Can contain explanations and similar commentary +** Kept separate to keep the reference tiddler pure + +Instruction tiddlers talk directly to the reader as "you". They can be reasonably chatty. + +But they avoid excessively colloquial language, cultural or topical references and attempts at humour, as these can baffle or even offend the international readership. They also avoid potentially frustrating the reader with descriptions of features as "convenient" or "easy". From dfd4c480d2d9308341178aa0d5dd1c97c62cc8b6 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:28:24 +0000 Subject: [PATCH 13/33] Create Reference Tiddlers.tid --- .../tiddlers/about/Reference Tiddlers.tid | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Reference Tiddlers.tid diff --git a/editions/tw5.com/tiddlers/about/Reference Tiddlers.tid b/editions/tw5.com/tiddlers/about/Reference Tiddlers.tid new file mode 100644 index 000000000..d7380e442 --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Reference Tiddlers.tid @@ -0,0 +1,25 @@ +created: 20141226192500000 +title: Reference Tiddlers +tags: documenting + +Reference tiddlers offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user. + +There are several subcategories: + +* ''Concepts'' +** With definitions, together forming a glossary +* ''User manual'' +** Presenting technical details of ~WikiText features +** Subcategorised: messages, operators, widgets, etc +* ''Developer manual'' +** Presenting technical details of ~TiddlyWiki's internal architecture + +Reference material is written in a terse, formal style that avoids referring to the reader, and instead focuses on how ~TiddlyWiki itself behaves. The passive voice is often suitable: + +* "the template can be specified as a tiddler" rather than "specify the template as a tiddler" +* "the widget can be used for various purposes" rather than "you can use the widget for various purposes" +* But "this widget has several possible uses" is better, because it is more succinct + +Contracted verb forms are normally avoided in reference tiddlers. + +To reduce the risk that the reader will overlook the word "not", it can be italicised. From 1366ef3e1c82408ab2ad98269b9a68ebceec78ed Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:29:03 +0000 Subject: [PATCH 14/33] Create Tiddler Titles.tid --- editions/tw5.com/tiddlers/about/Tiddler Titles.tid | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Tiddler Titles.tid diff --git a/editions/tw5.com/tiddlers/about/Tiddler Titles.tid b/editions/tw5.com/tiddlers/about/Tiddler Titles.tid new file mode 100644 index 000000000..9d381b0ad --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Tiddler Titles.tid @@ -0,0 +1,13 @@ +created: 20141226192500000 +title: Tiddler Titles +tags: documenting + +Each of the main words of a tiddler title begins with a capital letter, but minor words such as "and", "or", "the", "to" and "with" do not. Avoid starting a tiddler with the word "the". + +[[Reference Tiddlers]] have ~CamelCase nouns as their titles, e.g. ''~RevealWidget'', ''~CamelCase'', ''CSS''. The title is plural if it denotes a category, e.g. ''~KeyboardShorcuts'', ''~TiddlerFields''. Such categories are used to tag more specific tiddlers within the category. + +Other tags usually consist of a single lowercase word. Avoid spaces in tags. + +[[Instruction Tiddlers]] have spaces between the words of their titles. Each word that contributes significantly to the meaning of the title starts with a capital letter. Words that are little more than structural signposts ("the", "and", "of", etc) are entirely lowercase. + +How-to tiddlers have titles that begin with ''How to''. From e415edb4405003413b40820c7c4556b33b278204 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:29:41 +0000 Subject: [PATCH 15/33] Create Tiddler Structure.tid --- .../tw5.com/tiddlers/about/Tiddler Structure.tid | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Tiddler Structure.tid diff --git a/editions/tw5.com/tiddlers/about/Tiddler Structure.tid b/editions/tw5.com/tiddlers/about/Tiddler Structure.tid new file mode 100644 index 000000000..26ef86882 --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Tiddler Structure.tid @@ -0,0 +1,15 @@ +created: 20141226192500000 +title: Tiddler Structure +tags: documenting + +In accordance with the [[Philosophy of Tiddlers]], documentation tiddlers are typically short and interlinked. + +When a tiddler seems as if it needs to contain subheadings, this is often a sign that it should in fact be split into several tiddlers. But it is reasonable for a [[Reference Tiddler|Reference Tiddlers]] to consist of an untitled introductory section followed by a titled section of details. + +Consistency of terminology is essential if the reader is not to become confused. Consistent typography and punctuation lend a professional quality to the documentation. Macros can improve the consistency and maintainability of the text. + +Use numbered lists for step-by-step instructions, and bullet points for lists whose order is arbitrary. Use a definition list in preference to a bulleted list if each bulleted item would begin with a term and a colon. If at all possible, avoid burdening the reader with a nested list. + +Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[Reference Tiddlers]]. + +The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations. From 439154c0eab7cc2418079a7930f5f25282e5e7a6 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:30:11 +0000 Subject: [PATCH 16/33] Create Spelling.tid --- editions/tw5.com/tiddlers/about/Spelling.tid | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Spelling.tid diff --git a/editions/tw5.com/tiddlers/about/Spelling.tid b/editions/tw5.com/tiddlers/about/Spelling.tid new file mode 100644 index 000000000..7049d85f5 --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Spelling.tid @@ -0,0 +1,16 @@ +created: 20141226192500000 +title: Spelling +tags: documenting + +Because ~TiddlyWiki is of British origin, its English documentation uses [[British spelling in preference to US spelling|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]]. + +Words like "customise" are spelled "-ise", not "-ize". + +Standard technical acronyms are written in upper case, without dots: `HTML`, not `html` or `H.T.M.L.` + +Avoid arbitrarily abbreviating words and sentences. But the following abbreviations are acceptable: + +|!Abbreviation |!Meaning |!Notes | +|e.g. |for example |with a dot after each letter | +|i.e. |that is to say |with a dot after each letter | +|etc |and so on |without a dot | From bcee212195f7956d8e1607e84c609f6ef5b0b28b Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:31:18 +0000 Subject: [PATCH 17/33] Create Typography.tid --- .../tw5.com/tiddlers/about/Typography.tid | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Typography.tid diff --git a/editions/tw5.com/tiddlers/about/Typography.tid b/editions/tw5.com/tiddlers/about/Typography.tid new file mode 100644 index 000000000..dabce5a9b --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Typography.tid @@ -0,0 +1,26 @@ +created: 20141226192500000 +title: Typography +tags: documenting + +Use ''bold'' when referring to: + +* Captions in ~TiddlyWiki's user interface: +** "the ''Recent'' tab", "the ''Hide sidebar'' button" +* Tiddler fields: +** "the ''list'' field" +* Example tiddlers and tags: +** "create a tiddler called ''Super Soup Recipe'' with the tag ''cookery''" + +''Bold'' is also used to make part or all of a sentence stand out from the rest of the tiddler. + +Use //italics// to give more subtle emphasis to a word or phrase. + +Use `monospaced` text when a sentence contains a fragment of ~WikiText or a string that the user could type. + +Use the double quotation mark `"` as the basic one. It is easier to read on screen, and it avoids confusion with the apostrophe. To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…` + +Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side. + +Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise. + +It is very rarely necessary to use an exclamation mark in professional documentation. From c5650708a7f35c59a096e1c03ec6989fbfedffce Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:32:01 +0000 Subject: [PATCH 18/33] Create Technical Prose Style.tid --- .../tiddlers/about/Technical Prose Style.tid | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 editions/tw5.com/tiddlers/about/Technical Prose Style.tid diff --git a/editions/tw5.com/tiddlers/about/Technical Prose Style.tid b/editions/tw5.com/tiddlers/about/Technical Prose Style.tid new file mode 100644 index 000000000..0f8f7465b --- /dev/null +++ b/editions/tw5.com/tiddlers/about/Technical Prose Style.tid @@ -0,0 +1,15 @@ +created: 20141226192500000 +title: Technical Prose Style +tags: documenting + +When writing an [[Instruction Tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown. + +Keep sentences short and simple. A clear technical sentence seldom contains more than one idea. It therefore avoids parenthetical information. Similarly, keep paragraph structure simple. A flat presentation is often easier to understand than a hierarchical one. + +It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. "Execution of the macro is performed" just means "The macro runs". "Your expectation might be..." just means "You might expect..." + +Prefer the active voice by default: "Jane creates a tiddler" rather than "a tiddler is created by Jane". The passive voice can be useful if you want the reader to focus on the action itself or its result: "a tiddler is created". But it may be clearer to proceed from cause to effect and say "this creates a tiddler" in the active voice. + +Documentation often presents two items that are parallel either by similarity or by difference. The reader will more easily detect such a pattern if you use the same sentence or phrase structure for both. But this must be balanced with the need to avoid monotony. + +Prefer precise instructions over woolly descriptions. If something has a name, use it. If something lacks a name, give it a tiddler. From 42050e1b038efc30d185d1c8aa536bd3e221f97b Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Fri, 26 Dec 2014 19:33:37 +0000 Subject: [PATCH 19/33] Remove duplicate field line --- editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid | 1 - 1 file changed, 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid b/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid index 1c9716482..0270800ea 100644 --- a/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid +++ b/editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid @@ -1,5 +1,4 @@ created: 20141226192500000 -created: 20141226192500000 title: Instruction Tiddlers tags: documenting From bbcca4c784ab72ab661c13e28a16fb211ca200ad Mon Sep 17 00:00:00 2001 From: Andrew J Harrison Date: Sat, 27 Dec 2014 12:49:32 -0700 Subject: [PATCH 20/33] Update cla-individual.md Please correct my previous pull request. I guess my twitter name was already taken. --- licenses/cla-individual.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/licenses/cla-individual.md b/licenses/cla-individual.md index 926c4672b..1f763b3d4 100644 --- a/licenses/cla-individual.md +++ b/licenses/cla-individual.md @@ -198,3 +198,5 @@ Andreas Hahn, @Drakor, 2014/12/21 Jean-Charles Longuet, @Jc-L, 2014/12/22 Evgeniy Gryaznov, @evgeniy-gryaznov, 2014/12/23 + +Andrew Harrison, @infurnoape, 2014/12/27 From 7290be9e47c1fa64e0b4d052736b10d4355ac5aa Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 09:50:19 +0000 Subject: [PATCH 21/33] Improvements to wording --- .../tiddlers/concepts/ColourPalettes.tid | 41 +++++++------------ 1 file changed, 15 insertions(+), 26 deletions(-) diff --git a/editions/tw5.com/tiddlers/concepts/ColourPalettes.tid b/editions/tw5.com/tiddlers/concepts/ColourPalettes.tid index 5b6890ca6..4e08b2d21 100644 --- a/editions/tw5.com/tiddlers/concepts/ColourPalettes.tid +++ b/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]]: ``` <> ``` -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 | -|title |Any title can be used, typically a system title starting with "$:/" | -|type |`application/x-tiddler-dictionary` to identify this tiddler as a [[data tiddler|DataTiddlers]] | -|tags |`$:/tags/Palette` to identify this tiddler as a palette | -|description |Description to be displayed in palette browser | -|text |Colour definitions (see below) | +|!Name |!Value | +|title |Typically starting with `$:/` | +|type |`application/x-tiddler-dictionary` | +|tags |`$:/tags/Palette` | +|description |Displayed in the palette browser | +|text |`name: value` colour definitions | -The text of a palette tiddler consists of name value pairs like this: - -``` -foreground: #000 -background: #fff -``` +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). From e9c6610d745ddd881760f6047771105b283954b9 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 09:51:13 +0000 Subject: [PATCH 22/33] Improvements to wording --- editions/tw5.com/tiddlers/concepts/CurrentTiddler.tid | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/editions/tw5.com/tiddlers/concepts/CurrentTiddler.tid b/editions/tw5.com/tiddlers/concepts/CurrentTiddler.tid index bc673c507..9bbf6979d 100644 --- a/editions/tw5.com/tiddlers/concepts/CurrentTiddler.tid +++ b/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. From 117d10275f3df3150211f63b938e77a5dbb59185 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 09:51:53 +0000 Subject: [PATCH 23/33] Improvements to wording --- .../tiddlers/concepts/DataTiddlers.tid | 45 ++++++------------- 1 file changed, 14 insertions(+), 31 deletions(-) diff --git a/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid b/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid index 4a54872f0..d03be08aa 100644 --- a/editions/tw5.com/tiddlers/concepts/DataTiddlers.tid +++ b/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` -* 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 `:` - -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: +Use a TextReference to look up a value by its name. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains: ``` -{"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 -b:two -c:three +{"oct":31,"nov":30,"dec":31} ``` -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.// From 9aafed511bf5173be18a9d96f695838347f685be Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 09:53:58 +0000 Subject: [PATCH 24/33] Add concept of Dictionary Tiddlers --- .../tw5.com/tiddlers/concepts/DictionaryTiddlers.tid | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid diff --git a/editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid b/editions/tw5.com/tiddlers/concepts/DictionaryTiddlers.tid new file mode 100644 index 000000000..f9d9afe8d --- /dev/null +++ b/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 //name//: //value//. + +[[ColourPalettes]], such as the [[default Vanilla palette|$:/palettes/Vanilla]], are dictionary tiddlers. From 4f1d6f71fcb899c99705e8b3664625141b96af07 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 09:54:44 +0000 Subject: [PATCH 25/33] Add concept of JSON Tiddlers --- editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid diff --git a/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid b/editions/tw5.com/tiddlers/concepts/JSONTiddlers.tid new file mode 100644 index 000000000..776c77940 --- /dev/null +++ b/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. From 79a3beeaa605d3245808751b184653aa41bac47f Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 09:55:36 +0000 Subject: [PATCH 26/33] Add concept of Tag Tiddlers --- editions/tw5.com/tiddlers/concepts/TagTiddlers.tid | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 editions/tw5.com/tiddlers/concepts/TagTiddlers.tid diff --git a/editions/tw5.com/tiddlers/concepts/TagTiddlers.tid b/editions/tw5.com/tiddlers/concepts/TagTiddlers.tid new file mode 100644 index 000000000..1f6d45ecb --- /dev/null +++ b/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. From 597a5fb2f2e7d05aee37ccda685ee44e07f2abec Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 10:07:30 +0000 Subject: [PATCH 27/33] Update and make easier to understand --- .../nodejs/TiddlerFilter Formal Grammar.tid | 95 +++++++++---------- 1 file changed, 44 insertions(+), 51 deletions(-) diff --git a/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid b/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid index 7f352f8ff..dd8eb1c5a 100644 --- a/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid +++ b/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid @@ -4,68 +4,61 @@ tags: Filters title: Filter Formal Grammar type: text/vnd.tiddlywiki -[[Filters]] follow a formal grammar that is presented here for users who are familiar with the notation. It isn't necessary to understand this grammar in order to write your own filter expressions. +[[Filter expressions|Filters]] follow a grammar that is presented here for those who find formal syntax descriptions helpful. However, you can write your own filter expressions without needing to understand this tiddler. -''<filter-string>'' ::= ''<opt-whitespaces>'' ''<filter-operand>'' | ''<opt-whitespaces>'' ''<filter-operand>'' ''<filter-string>'' +* [//x//] denotes an optional //x// +* (//x//)... denotes 1 or more instances of //x// +* Literal characters are `monospaced` +* Bullets indicate alternative possibilities -Whitespace is matched with javascript "\s+", which matches space, tab, carriage return, new line, vertical tab, and form feed. +;filter +* ( [//whitespace//] [`+`|`-`] //run// )... -''<opt-whitespaces>'' ::= ''<opt-whitespace>'' | ''<opt-whitespace>'' ''<opt-whitespaces>'' +;run +* `[` (//operation//)... `]` +* `"` //text// `"` +** The text can contain anything but `"` +* `'` //text// `'` +** The text can contain anything but `'` +* //text// +** The text can contain anything but whitespace and `[` and `]` +** These last three alternatives are short for `[title[text]]` -''<opt-whitespace>'' ::= " " | "\t" | "0xD" | "0xA" | "0xB" | "0xC" +;operation +* [`!`] //operator// //operand// -''<filter-operand>'' ::= ''<opt-operation-prefix>'' ''<string-or-operator-list>'' +;operator +* [//keyword//] [//suffix//] +** Terminated by the `[` or `{` or `<` of the operand +** Keywords are drawn from a reserved list +** A suffix on its own implies the keyword `field` +** An entirely omitted operator defaults to `title` -''<opt-operation-prefix>'' ::= "+" | "-" | "" +;suffix +* `:` [//text//] -''<string-or-operator-list>'' ::= ''<operation>'' | "\"" ''<string>'' "\"" | "'" ''<string>'' "'" | ''<string>'' +;operand +* `[` //text// `]` +** literal -- the text can contain anything but `]` +* `{` //text// `}` +** text reference -- the text can contain anything but `}` +* `<` //text// `>` +** variable -- the text can contain anything but `>` -''<operation>'' ::= "[" ''<operator-list>'' "]" +;whitespace +* One or more spaces, tabs or linefeeds, i.e. a match for the JavaScript regular expression `\s+` -''<operator-list>'' ::= ''<operator>'' | ''<operator>'' ''<operator-list>'' +!Evaluation -''<operator>'' ::= ''<opt-operator-prefix>''''<operator>''''<operand>'' +Each operation returns a set of tiddlers, in the form of a TitleList. -''<opt-operator-prefix>'' ::= "!" | "" +A run evaluates each of the operations it contains, and returns the intersection of the resulting sets. -''<operator>'' ::= ''<operator-name>'' | ''<operator-name>'' ":" ''<opt-operator-suffix>'' +A sequence of runs is evaluated from left to right, as follows: -''<operator-name>'' ::= "" | "is" | "has" | "each" | "field" ... +|!Sequence |!Interpretation | +|run1 run2 |union of the sets, i.e. the tiddlers in //either// run1 //or// run2 | +|run1 -run2 |difference of the sets, i.e. run1 but excluding any tiddlers in run2 | +|run1 +run2 |run2 takes run1 as its input | -''<opt-operator-suffix>'' ::= ''<string>'' | "" - -''<operand>'' ::= "[" ''<search-string>'' "]" | "{" ''<indirect-search-string>'' "}" | "<" ''<variable-name-string>'' ">" - -''<string>'' ::= ''<string-type-1>'' | ''<string-type-2>'' | ... - -At the end of parsing you end up with some or all of: - -* ''<opt-operation-prefix>'' -* ''<opt-operator-prefix>'' -* ''<operator-name>'' -* ''<opt-operator-suffix>'', and -* ''<operand>'' - -These are used differently by the different operators. For example, the field filter operator supports: - -* ''<opt-operator-prefix>'' to negate the result -* ''<regex>'' or ''<string>'' operand (note that this must be explicitly supported by each filter operator) -* ''<opt-operator-suffix>'' to specify a fieldname against which to filter - -NOTES: - -* The ''<string>'' is a terminal that generally supports single- or double- quoted strings which match, respectively, strings of non-single and non-double quotes. Unquoted strings include the extra exclusion of whitespace and square bracket characters. - -* In the case where the ''<string-or-operator-list>'' is NOT an ''<operation>'' it is treated as the operand passed to the default operator (see next bullet). It is not parsed as a full ''<operation>''. - -* If ''<operator-name>'' is the empty string then it will be set to "title" (i.e. the title filter operator is the default operator) - -* Results are collected and each operation is applied in turn. The ''<opt-operation-prefix>'' can be used to specify how the corresponding operation is used. Suppose T is the set of all tiddlers, R0 is the current set of results, and Fx is the xth operation. Then: - -** No prefix (""): R0 = R0 U Fx(T) (set union) -** "-": R0 = R0 - Fx(T) (set difference) -** "+": R0 = Fx(R0) - -Note that ''<filter-operand>''s are not commutative! - -* The parser was simplified by treating regex "/" as a "bracket" of sorts, meaning there could only be a start and end bracket. Thus the regex arguments, like i, are included in parenthesis immediately following the trailing "/". +The first run of a sequence takes `[all[tiddlers]]` as its input, i.e. the set of all non-missing tiddlers. From e6ede67282c53c78ec1f321e48a7efff0605bfc1 Mon Sep 17 00:00:00 2001 From: Astrid Elocson Date: Sun, 28 Dec 2014 16:16:24 +0000 Subject: [PATCH 28/33] Further improvements suggested by felixhayashi --- .../nodejs/TiddlerFilter Formal Grammar.tid | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid b/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid index dd8eb1c5a..24b7501f5 100644 --- a/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid +++ b/editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid @@ -9,7 +9,8 @@ type: text/vnd.tiddlywiki * [//x//] denotes an optional //x// * (//x//)... denotes 1 or more instances of //x// * Literal characters are `monospaced` -* Bullets indicate alternative possibilities +* Top-level bullets indicate alternative possibilities +* Second-level bullets are comments and clarifications ;filter * ( [//whitespace//] [`+`|`-`] //run// )... @@ -28,15 +29,11 @@ type: text/vnd.tiddlywiki * [`!`] //operator// //operand// ;operator -* [//keyword//] [//suffix//] -** Terminated by the `[` or `{` or `<` of the operand -** Keywords are drawn from a reserved list -** A suffix on its own implies the keyword `field` +* [//keyword//] [`:` //fieldname//] +** Keywords (`is`, `has`, `tag`, etc) are reserved names that identify filter functions +** A fieldname on its own implies the keyword `field` ** An entirely omitted operator defaults to `title` -;suffix -* `:` [//text//] - ;operand * `[` //text// `]` ** literal -- the text can contain anything but `]` From 21df296c2fe98243b556e01703bbce1c818b7ad1 Mon Sep 17 00:00:00 2001 From: Jermolene Date: Tue, 30 Dec 2014 09:09:40 +0000 Subject: [PATCH 29/33] Docs: Clarify widgets generated by wikitext transclusion --- .../wikitext/Transclusion in WikiText.tid | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid b/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid index 651a02ba6..8cf4acd7a 100644 --- a/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid +++ b/editions/tw5.com/tiddlers/wikitext/Transclusion in WikiText.tid @@ -1,9 +1,11 @@ +caption: Transclusion created: 20131205160146648 -modified: 20140317214256948 +modified: 20141230090901681 tags: WikiText title: Transclusion in WikiText type: text/vnd.tiddlywiki -caption: Transclusion + +! Introduction You can incorporate the content of one tiddler within another using the [[Transclusion]] notation: @@ -11,6 +13,8 @@ You can incorporate the content of one tiddler within another using the [[Transc * `{{MyTiddler||TemplateTitle}}` displays the tiddler through a specified [[TemplateTiddler|TemplateTiddlers]] * `{{||TemplateTitle}}` displays the specified template tiddler without altering the CurrentTiddler +!! Transcluding Text References + You can also use a TextReference instead of a tiddler title: * `{{MyTiddler!!field}}` transcludes a specified field of a tiddler @@ -18,6 +22,8 @@ You can also use a TextReference instead of a tiddler title: * `{{MyTiddler##index}}` transcludes a specified indexed property of a [[DataTiddler|DataTiddlers]] * `{{##index}}` transcludes a specified indexed property of the current [[DataTiddler|DataTiddlers]] +!! Filtered Transclusion + A similar syntax can be used to transclude a list of tiddlers matching a specified [[filter|Filters]]: ``` @@ -25,6 +31,16 @@ A similar syntax can be used to transclude a list of tiddlers matching a specifi {{{ [tag[mechanism]] ||TemplateTitle}}} ``` +! Generated Widgets + +The WikiText transclusion syntax generates a TiddlerWidget wrapped around a TranscludeWidget. For example, `{{MyTiddler||MyTemplate!!myField}}` generates the following pair of widgets: + +``` +<$tiddler tiddler="MyTiddler"> +<$transclude tiddler="MyTemplate" field="myField"/> + +``` + See also: * [[Transclusion Basic Usage]] From b83d311951087e4678a69c2e20e68f7e08306c7d Mon Sep 17 00:00:00 2001 From: Arlen22 Date: Tue, 30 Dec 2014 09:28:27 -0500 Subject: [PATCH 30/33] Sign the CLA --- licenses/cla-individual.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/licenses/cla-individual.md b/licenses/cla-individual.md index 926c4672b..1929e09c4 100644 --- a/licenses/cla-individual.md +++ b/licenses/cla-individual.md @@ -198,3 +198,5 @@ Andreas Hahn, @Drakor, 2014/12/21 Jean-Charles Longuet, @Jc-L, 2014/12/22 Evgeniy Gryaznov, @evgeniy-gryaznov, 2014/12/23 + +Arlen Beiler, @arlen22, 2014/12/30 From b8f090e0c637b9bf20acc36b683ff206c3377a51 Mon Sep 17 00:00:00 2001 From: Jermolene Date: Tue, 30 Dec 2014 18:30:49 +0000 Subject: [PATCH 31/33] Clean up from merging @roma0104's changes --- .../community/resources/Briefcase mGSD.tid | 14 -------------- .../tw5.com/tiddlers/community/resources/GSD5.tid | 6 +++++- 2 files changed, 5 insertions(+), 15 deletions(-) delete mode 100644 editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid diff --git a/editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid b/editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid deleted file mode 100644 index 5e8d2cd95..000000000 --- a/editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid +++ /dev/null @@ -1,14 +0,0 @@ -created: 20140916203526273 -modified: 20140916203526273 -tags: Resources -title: "Briefcase" by Roma Hicks -type: text/vnd.tiddlywiki -url: https://drive.google.com/open?id=0Bydfk9tNRJHBc3FvclFBMzRreTQ&authuser=0 - -An adaptation of the [[TiddlyWiki powered GTD® system formerly known as MonkeyGTD|http://mgsd.tiddlyspot.com/]] for TiddlyWiki version 5. - -{{!!url}} - -<<< -Briefcase is a Getting-Thing-Done tool for TiddlyWiki5 based off the mGSD classic TiddlyWiki. -<<< diff --git a/editions/tw5.com/tiddlers/community/resources/GSD5.tid b/editions/tw5.com/tiddlers/community/resources/GSD5.tid index 081ff010c..c114e4e61 100644 --- a/editions/tw5.com/tiddlers/community/resources/GSD5.tid +++ b/editions/tw5.com/tiddlers/community/resources/GSD5.tid @@ -1,10 +1,14 @@ tags: Resources -title: "Briefcase" by Roma Hicks +title: "GSD5" by Roma Hicks type: text/vnd.tiddlywiki url: http://gsd5.tiddlyspot.com/ +created: 20141230182901899 +modified: 20141230182901899 An adaptation of the [[TiddlyWiki powered GTD® system formerly known as MonkeyGTD|http://mgsd.tiddlyspot.com/]] for TiddlyWiki version 5. +{{!!url}} + <<< GSD5 is a Getting-Thing-Done tool for TiddlyWiki5 based off the mGSD classic TiddlyWiki. <<< From a8854662e49aa90536bc0a66ae21c39c76a285e7 Mon Sep 17 00:00:00 2001 From: Jermolene Date: Tue, 30 Dec 2014 18:38:22 +0000 Subject: [PATCH 32/33] Keep documentation style guide in the TOC --- editions/tw5.com/tiddlers/about/Documentation Style Guide.tid | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid b/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid index 5da2174a9..99ca0ef04 100644 --- a/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid +++ b/editions/tw5.com/tiddlers/about/Documentation Style Guide.tid @@ -1,7 +1,7 @@ created: 20140904164608166 modified: 20140904164935351 title: Documentation Style Guide -tags: documenting +tags: documenting [[Improving TiddlyWiki Documentation]] type: text/vnd.tiddlywiki The documentation for ~TiddlyWiki tries to follow a consistent editorial style. It has two main areas, each with its own tone and audience: From 544ee4668e85abbf6acc59f13754559249ff2708 Mon Sep 17 00:00:00 2001 From: Jermolene Date: Wed, 31 Dec 2014 09:34:32 +0000 Subject: [PATCH 33/33] Typo correction --- editions/tw5.com/tiddlers/concepts/TiddlerLinks.tid | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/editions/tw5.com/tiddlers/concepts/TiddlerLinks.tid b/editions/tw5.com/tiddlers/concepts/TiddlerLinks.tid index aa5e8090d..b5eb221da 100644 --- a/editions/tw5.com/tiddlers/concepts/TiddlerLinks.tid +++ b/editions/tw5.com/tiddlers/concepts/TiddlerLinks.tid @@ -1,5 +1,5 @@ created: 20130825202900000 -modified: 20140410103200281 +modified: 20141231093344090 tags: Concepts title: TiddlerLinks type: text/vnd.tiddlywiki @@ -10,7 +10,7 @@ Holding the ''control'' or ''command'' key while clicking on a tiddler link open Links are useful for modelling organic relationships between tiddlers, and particularly for expressing the navigational paths between tiddlers. -The TiddlerInfoPanel lists incoming links to a tiddler in the tab ''References''. +The InfoPanel lists incoming links to a tiddler in the tab ''References''. [[Filters]] can include the following filter operators that work with links: