Merge remote-tracking branch 'upstream/master'

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 [[Improving TiddlyWiki Documentation]]
 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.
-
-<<style-guide
-"""!! How to Configure Default Tiddlers"""
-"""!! How to configure default tiddlers"""
->>
+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]]

editions/tw5.com/tiddlers/about/Instruction Tiddlers.tid

@@ -0,0 +1,38 @@
+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".

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.

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 |

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.

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.

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''.

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.

editions/tw5.com/tiddlers/community/resources/Briefcase mGSD.tid

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

editions/tw5.com/tiddlers/community/resources/GSD5.tid

@@ -0,0 +1,14 @@
+tags: Resources
+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.
+<<<

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]]:
 
 ```
 <<colour page-background>>
 ```
 
-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).

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.

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 `<name>:<value>`
-
-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.//

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 <code>//name//: //value//</code>.
+
+[[ColourPalettes]], such as the [[default Vanilla palette|$:/palettes/Vanilla]], are dictionary tiddlers.

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.

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.

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:
 

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.

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 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.
 
-* 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 [[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:
+
+# 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.

editions/tw5.com/tiddlers/nodejs/TiddlerFilter Formal Grammar.tid

@@ -4,68 +4,58 @@ 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`
+* Top-level bullets indicate alternative possibilities
+* Second-level bullets are comments and clarifications
 
-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//] [`:` //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`
 
-''<opt-operation-prefix>'' ::= "+" | "-" | ""
+;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 `>`
 
-''&lt;string-or-operator-list&gt;'' ::= ''&lt;operation&gt;'' | "\"" ''&lt;string&gt;'' "\"" | "'" ''&lt;string&gt;'' "'" | ''&lt;string&gt;''
+;whitespace
+* One or more spaces, tabs or linefeeds, i.e. a match for the JavaScript regular expression `\s+`
 
-''&lt;operation&gt;'' ::= "[" ''&lt;operator-list&gt;'' "]"
+!Evaluation
 
-''&lt;operator-list&gt;'' ::= ''&lt;operator&gt;'' | ''&lt;operator&gt;'' ''&lt;operator-list&gt;''
+Each operation returns a set of tiddlers, in the form of a TitleList.
 
-''&lt;operator&gt;'' ::= ''&lt;opt-operator-prefix&gt;''''&lt;operator&gt;''''&lt;operand&gt;''
+A run evaluates each of the operations it contains, and returns the intersection of the resulting sets.
 
-''&lt;opt-operator-prefix&gt;'' ::= "!" | ""
+A sequence of runs is evaluated from left to right, as follows:
 
-''&lt;operator&gt;'' ::= ''&lt;operator-name&gt;'' | ''&lt;operator-name&gt;'' ":" ''&lt;opt-operator-suffix&gt;''
+|!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 |
 
-''&lt;operator-name&gt;'' ::= "" | "is" | "has" | "each" | "field" ...
-
-''&lt;opt-operator-suffix&gt;'' ::= ''&lt;string&gt;'' | ""
-
-''&lt;operand&gt;'' ::= "[" ''&lt;search-string&gt;'' "]" | "{" ''&lt;indirect-search-string&gt;'' "}" | "<" ''&lt;variable-name-string&gt;'' ">"
-
-''&lt;string&gt;'' ::= ''&lt;string-type-1&gt;'' | ''&lt;string-type-2&gt;'' | ...
-
-At the end of parsing you end up with some or all of: 
-
-* ''&lt;opt-operation-prefix&gt;''
-* ''&lt;opt-operator-prefix&gt;''
-* ''&lt;operator-name&gt;''
-* ''&lt;opt-operator-suffix&gt;'', and 
-* ''&lt;operand&gt;''
-
-These are used differently by the different operators. For example, the field filter operator supports:
-
-* ''&lt;opt-operator-prefix&gt;'' to negate the result
-* ''&lt;regex&gt;'' or ''&lt;string&gt;'' operand (note that this must be explicitly supported by each filter operator)
-* ''&lt;opt-operator-suffix&gt;'' to specify a fieldname against which to filter
-
-NOTES:
-
-* The ''&lt;string&gt;'' 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 ''&lt;string-or-operator-list&gt;'' is NOT an ''&lt;operation&gt;'' it is treated as the operand passed to the default operator (see next bullet). It is not parsed as a full ''&lt;operation&gt;''.
-
-* If ''&lt;operator-name&gt;'' 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 ''&lt;opt-operation-prefix&gt;'' 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 ''&lt;filter-operand&gt;''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.

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"/>
+</$tiddler>
+```
+
 See also:
 
 * [[Transclusion Basic Usage]]

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

licenses/cla-individual.md

@@ -183,6 +183,8 @@ Erwan Moreau, @erwanm, 2014/10/27
 
 Felix Küppers, @felixhayashi, 2014/11/02
 
+Roma Hicks, @roma0104, 2014/11/18
+
 Jedediah Carty, @inmysocks, 2014/11/21
 
 Erwan Dano, @Braincoke, 2014/11/24
@@ -198,3 +200,7 @@ 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
+
+Arlen Beiler, @arlen22, 2014/12/30