Tinderbox User's Manual

Tinderbox v5 Manual
Tinderbox v5 Manual - Table of Contents
Tinderbox v5 Manual - Table of Contents 1

What's New in Tinderbox 5? 11
Tinderbox Basics 12
NOTES 12
HIERARCHY 12
LINKS 12
Notes 13
To create a note 13
To write in a note 14
To delete a note 14
To rename a note 14
The sidebar 15
To find text in a note 15
Common words 16
Listing notes 16
Files 16
Scripts 17
History 17
Writing in Notes 19
Text Appearance 19
Spelling 19
Attributes 20
Key Attributes 20
Key Attribute display differences 21
Key Attribute value pop-up lists 21
Key Attribute value autocomplete 22
To see other attributes in a text window 22
The Attributes Palette 22
To change an attribute’s value 22
To use the quickstamp 22
To change an attribute value using an info window 23
To set an attribute's default value 23
To create a new attribute 24
Attribute types 24
String 24
color 24
File 25
Boolean 25
Date 25
Number 26
List 26
Set 26
URL 27
Action (System use only) 27
Attributes and Agents 27
Exporting Attributes 27
The Attributes Palette: Other Panes 27
Colors 27
Stamps 28
1 of 178
Tinderbox v5 Manual
Link Types 28
Macros 28
Prototypes 29
Prototype Inheritance 30
Any Note Can Be A Prototype 31
Prototypes and Children 31
Built-in Prototypes 32
The Toolbar 33
Importing Notes 34
Drag and Drop 34
Spreadsheets 34
Explode 35
Email 35
Views 37
Moving around 37
Map views 38
The Prototype Tab 39
Links 39
Adornments 39
Image Adornments 40
Locking Adornments 40
To make an adornment "sticky" 40
Smart Adornments 41
Cleanup 41
The Up-Arrow 41
Changing The Appearance of Notes 41
Custom badges 43
Changing the appearance of the Map background 44
Picture Adornments 44
Displaying Text In Maps 44
Subtitle 45
Display Expression 45
Hover Expression 45
Containers 46
Summary Tables 47
Outline views 48
Outline Views 48
The disclosure triangle 48
The Outline Icon 49
Editing a note title 49
Hoisting 50
Separators 50
Changing the View Focus 51
Checkboxes 51
Columns 51
Timeline views 52
Timeline appearance 52
Scope of the Timeline 52
Where settings are stored - containers vs. notes 53
Placing notes in discrete bands 53
Color of the main view 53
2 of 178
Tinderbox v5 Manual
Color of the main view 53
Coloring Timeline bands 53
Timeline band labels 53
Adornments 53
Varying Scale and Label size 54
Customizing the Scale bar 54
Note appearance on the Timeline 54
Moving notes in the Timeline 54
Chart & Treemap views 55
Chart Views 55
The disclosure triangle 55
Treemap Views 55
Changing the View Focus 56
Arranging notes 57
Outline Views 57
Chart Views 57
Treemap Views 57
Aliases 58
To create an alias 58
To find the original note of an alias 58
Properties of Aliases 58
Links 60
Types of Links 60
Basic Links 60
Using a parking space 61
Text Links 61
To create a text link: 61
Internet Links 62
Link Types 63
Browse Links 64
To view links in the Browse Links window 64
Deleting Links 65
To delete a link 65
To delete a text link 66
The Roadmap View 66
To view links with the Roadmap 66
Linking to Text 67
WikiLinks 67
Footnotes 69
To create a footnote 69
Following Links 70
To follow a text link 70
To follow a basic link 70
To choose which link to follow 70
Which Link Will Be Followed? 71
Overlapping Text Links 71
Agents 72
Creating an agent 72
Agent Search Criteria 72
Searching for text patterns 73
Searching attributes 74
3 of 178
Tinderbox v5 Manual
Agents, Dates, and Times 74

Faster Search 75
More Queries 75
Sorting 76
Agent Actions 77
Updating Agents 77
Agent Priority 78
The AgentPriority Attribute 78
Actions 79
Actions In Tinderbox 79
A Spreadsheet for Ideas 79
Expressions 80
Equality vs. Assignment 80
Actions Don’t Need To Do Everything 81
What Actions Mean 81
Container Actions 81
Adornment Actions 81
Agent Actions 81
Rules 81
Contradictions 82
Rules 82
Setting Actions 82
Writing Actions 83
Setting Values 83
Multiple Actions 83
Data Types 83
format(): converting strings 84
Formatting Lists and Sets 84
Formatting Numbers 84
Examining and Acting On Other Notes 84
Using Results from Regular Expressions 85
Conditional Assignment 85
Adding and Deleting Notes 86
Working With Other Processes 86
Shell Actions and runCommand() 86
Template actions 86
One Step At A Time 86
Stamps 88
To create a stamp 88
To apply a stamp 88
Quickstamp 88
Stamps for Storing Data 89
Fetching from the Web 90
Attributes for Working With the Web 90
URL 90
AutoFetch 90
ViewInBrowser 90
ReadOnly 90
LastFetched 91
Email To Tinderbox 92
To Set Up Email To Tinderbox 92
How Tinderbox Handles Email 92
4 of 178
Tinderbox v5 Manual
Passing attribute data 92

Email Limitation 93
Exporting to HTML 94
How Export Works 94
HTML Templates 94
What gets Exported 94
What will transfer to the export 94
What will transfer in part 95
What will not be exported 95
Assembling Web Pages from Many Notes 96
Tinderbox And The Web 96
Text 96
Headings 96
Lists 97
Internal and External Templates 97
Exporting Using Other Than HTML Mark-Up 98
HTML View 99
Export Options 99
Export 99
Export children 99
Markup text 99
Quote HTML 99
File name 99
File extension 99
Template 100
Export folder 100
Previewing your export 100
Update 100
Export 100
Preview 100
Customizing HTML Markup 100
first paragraph 100
subsequent paragraphs 100
indented paragraphs 101
before and after 101
bold 101
italic 101
underline 101
strikethrough 101
HTML Preferences 101
URL ( web server) 101
HTML template file 102
Exported with extension: 102
Open file with: 102
Link images as: 102
Export paragraphs: 102
To export a document to HTML 103
Attributes for HTML Export 103
HTMLDontExport 103
HTMLExportChildren 104
HTMLExportExtension 104
HTMLExportFileName 104
HTMLExportTemplate 104
Exporting Exactly What You Want 104
HTML Templates 106
5 of 178
Tinderbox v5 Manual
Template Essentials 106

Placeholders 106
Paths 107
Referring to other notes 107
Content codes 107
Template codes in text 108
Macros 108
Conditional Export 109
Group Codes 110
An Example Template 110
Complex Pages 113
^children^ 113
înclude^ 113
^randomChildOf^ 114
Dates and Times 114
Format strings 114
Comparing dates 115
Dates and attributes 115
Working with Weblogs 116
Posting to Remote Weblogs 116
To post to remote weblogs 116
To download the most recent posts 116
Pinging 117
Exporting text 118
Text Export Templates 118
Nakakoji View 118
Which template to use 119
Preferences 120
Preference Panes 120
Tips For Experienced Tinderbox Users 122
Tinderbox Resources 123
To Contact Us 124
Publishing Notes 125
Acknowledgements 125
Tinderbox (TM) Software License Agreement 125
Tinderbox™ Software License Agreement 125
Limited Warranty and Disclaimer 126
Limited Warranty and Disclaimer 126
Appendix 1: Attributes 127
Agent 127
Appearance 127
Events 128
General 128
HTML 129
Map 131
Net 132
Outline 132
People 133
Simplenote 133
6 of 178
Tinderbox v5 Manual
Sorting 133
TextFormat 134
Textual 134
Weblog 135
Appendix 2: Regular Expressions 136
Wildcard Characters 136
Character Ranges 136
Anchors 137
The \ [backslash] Character 137
Parentheses 137
Appendix 3: Actions, Expressions and Rules 139
Attribute Types 139
Attribute References 140
Note Designators 140
Group Designators 141
find() 142
Queries 142
true and false 142
Comparisons 142
Text Patterns 143
Other Queries 143
Actions 144
String Functions 145
String Operators 145
String Operations 146
format() 146
string encoding 147
Numeric Functions 148
Mathematical Operators 148
sum(), sum_if, avg and avg_if() 148
Converting Numbers to Strings 149
Color functions 149
Color Operators 149
Converting Colors to Strings 149
Converting Strings to Colors 149
Manipulating Colors 150
Date Functions 150
Date Properties 150
Date Operators 150
Date/time comparison operators 151
List & Set Functions 151
List & Set Operators 151
List Operations 153
Logic functions 153
Logical Operators 154
Logical equality tests 154
Logical Group Operators 154
Link Functions 155
Link Operators 155
Making Links 155
Macros 156
Macro Operator 156
eval() and action() 156
Shell Expressions 156
Shell Operator 156
Template actions 157
Restoring the default value 158
7 of 178
Tinderbox v5 Manual
Conditional Assignment 158

If() 158
Local variables 158
Back References 159
String Operators 159
String Operations 160
format() 160
string encoding 161
Mathematical Operators 162
sum(), sum_if, avg and avg_if() 162
Converting Numbers to Strings 163
Color Functions 163
Color functions 163
Color Operators 163
Converting Colors to Strings 163
Converting Strings to Colors 163
Manipulating Colors 164
Date Functions 164
Date Functions 164
Date Properties 164
Date Operators 164
Date/time comparison operators 165
List & Set Operators 165
List Operations 167
Logic functions 168
Logical equality tests 168
Logical Group Operators 168
Link Operators 169
Link Functions 169
Link Operators 169
Making Links 169
Macros 170
Macros 170
Macro Operator 170
eval() and action() 170
Shell Operator 170
Export codes 171
Template expressions 171
Template actions 171
Appendix 4: HTML Export Codes 173
Common Export Codes 173
Common Export Codes 173
Older Forms 173
Actions and Expressions 173
Actions and Expressions 173
Links 174
Generating Links 174
Conditional Export 174
Conditional Export Codes 174
8 of 178
Tinderbox v5 Manual
Including Other Notes 174

Including Other notes' content 175
Other Export Codes 175
Miscellaneous Codes 175
Appendix 5: Date Formats 177
Addendum: Support for Images 178
9 of 178
Tinderbox v5 Manual
10 of 178
Tinderbox v5 Manual
What's New in Tinderbox 5?
Tinderbox 5 is a universal binary, based on a new compiler, new libraries, and new development
tools. In addition, numerous under-the-hood improvements make Tinderbox 5 faster than ever.
New text engine supports highlighting, strikethrough, super- and subscripts, and indented
paragraphs.
Outlines can have checkboxes and columns
Unicode note names and note text
Inspectors let you change the properties of notes more easily
New note shapes, borders, and translucent notes in maps
In-place Editing in maps
Stationery and oft-used files can be kept indefinitely in the Open Recent menu
URL attributes
Copy items in an outline and paste the outline in any program that accepts text
Improved Chart views
v5.0.2:
Maps - highlighting/animation of currently selected notes' links
v5.1.0:
UTF-8 for export means less character encoding when using HTML, XML, etc.
Improved agent & alias performance
v5.5.0:
Simplenote synch support
Maps - shaped adornments, new shape
Title strikethrough
Colored outline item backgrounds & selections
OPML export improvements
Map - option to let agent contents be moved manually
Features for embedding and exporting images are temporarily suspended (see details for
relaxations in v5.6.0 & v5.9.0).
For a complete run-down on everything new in Tinderbox, see the Release Notes in the
Tinderbox Help Menu.
11 of 178
Tinderbox v5 Manual
Tinderbox Basics
NOTES
Tinderbox is a personal content assistant, a tool for making, analyzing, and sharing notes.
Notes are the basic units of writing and information in Tinderbox. Each note has:
title: the name of the note

text
attributes: other pieces of information about the note.
Notes live in Tinderbox documents. You must create a document before you create notes. You can
create many Tinderbox documents, and individual Tinderbox documents can comfortably contain
thousands of notes.
You can open several different Tinderbox documents at the same time.
HIERARCHY
Notes can contain other notes. This allows you to arrange notes in a hierarchy.
A note that contains other notes is called a container. You could create chapters containing sections
containing divisions; or topics containing subtopics; or any other hierarchy that fits your work.
You don’t need to create a hierarchy in your Tinderbox document; you can leave all the notes at the
same level.
LINKS
A link is a connection between one note and another. Links allow you to make connections between
ideas, and to quickly move between linked notes. A link can lead from a note as a whole, or from
selected text within a note (like linked text on the Web).
You can also create a link to a URL—an external document on the Internet. Following the link will
open that location in your Web browser.
12 of 178
Tinderbox v5 Manual
Notes
Notes are the basic units of writing and information in Tinderbox.
There's no fixed limit to the number of notes Tinderbox can handle. You can easily manage
thousands, even tens of thousands of notes in Tinderbox.
Each note has:
a title: the name of the note

content: the text of the note
attributes: other pieces of information about the note, for instance, the note's color, size,
position in the map, and whether it's private or public.
A note can hold many pages of text, but it's usually best to keep notes short. This makes it easy to
find exactly what you're looking for, and helps agents find specifically what they're seeking.
Almost every aspect of a note—its shape, position, color is associated with an attribute. Tinderbox
makes it easy to add new attributes, and to move information from your notes in attributes. You can
search and sort for any attribute. Tinderbox documents can often be instructed to set attributes
automatically and intelligently.
You don’t need to define your attributes in advance; Tinderbox is designed to let your notes evolve
and adapt as your understanding changes and deepens.
Much more will be said about working with attributes in the chapter on Attributes.
To create a note
Remember that you must create or open a document before you create a note. (Choose New from
the File menu, or press ⌘-N)
In any view window,
select an existing note (by clicking on it)

press Return
or
right-click in the window, then choose Create Note from the contextual menu
or, in a map view window,
double-click
Or, in any view window,
choose Create Note... from the Note menu, or press ⌘-K.
To finish creating the note,
type a name for the new note
13 of 178
Tinderbox v5 Manual
If In-Place Editing is turned on (in the Maps pane of the Preference window), you enter the note
name directly in the view window. Otherwise, Tinderbox displays a dialog where you can enter the
note’s name and adjust other properties.
To write in a note
In any view window,
select any note (by clicking on it)

press spacebar, or choose Text Window from the Note menu (⌥⌘X)
double-click the title (not when edit-in-place of title is active)
This will open a text window for that note. The procedure is the same for editing existing note text.
There is no dialog; just close the window when you want to.
(Whenever you create a new note, you can have a text window automatically open for that note. You
can turn this on in the General pane of Document Preferences... in the Edit menu (⌘8).)
To delete a note
In any view window,
click the note with the arrow tool, to select it

press the delete key, or choose Clear from the Edit menu, or drag it into the trashcan on the
Desktop. If you delete a note that has children, a dialog will ask whether to delete that note
and its children; or delete them and not ask next time; or cancel the delete. (There is a
setting, under Document Preferences, to control what Tinderbox will do when you delete a
note that has children.)
A note’s children are the notes it contains— the notes that are subsidiaries of it in the hierarchy.
To rename a note
In map, chart, or outline views, simply click on a note name and hold the mouse down briefly to edit
the name. Or,
In any view window or list of notes,
click the note with the arrow tool, to select it

press Enter (⌅, not Return ⏎ key)
then
type a new name for the new note

click OK to dismiss the dialog
14 of 178
Tinderbox v5 Manual
In a text window,
choose Rename... from the Note menu, or press Enter

type a new name for the new note
The "Rename" dialog offers other options for the note, such as color, attribute, actions, and rules.
These features will be explained in more detail later.
The sidebar
Each text window has, by default, a sidebar containing menus for popular Tinderbox functions such
as attributes, links, scripts, and prototypes. (These will be discussed later).
To hide the sidebar, choose Hide sidebar from the Views file menu, or use ⌘⌃T. To show it again,
choose Show sidebar or press ⌘⌃T again.
The “gear” menu at the lower left-hand corner of the text window will show or hide the sidebar. The
sidebar is automatically hidden in very narrow text windows.
To hide the sidebar in all windows,
choose Preferences from the Tinderbox file menu

click the Text pane
clear the Show sidebar checkbox
click OK
To find text in a note
select Find text... from the Edit menu or press ⌘F
Type the text you're looking for and, as soon as you've typed the first three or four characters,
Tinderbox will find the matching notes in the open document. Double-click a note name to open its
text window with your search term highlighted.
The find dialog searches for regular expressions — text patterns with wild cards — as well as
performing simple searches. See the Appendix 2: Regular Expressions for details.
15 of 178
Tinderbox v5 Manual
Common words
To display a “word cloud” of frequently-used words in a note or in the entire document
select Common Words from the View menu or press ⌘⌥W
The Common Words window displays a "cloud" of the 100 most common words found in a note, a
section (a note and its descendants), or the entire document. More common words appear larger.
Click on any word to search for the word in a note's text and title.
For note and section, each distinct occurrence of a word is counted. For the document level view,
Tinderbox counts the number of notes that contain a word one or more times. Words of four
characters and fewer are ignored, as are very common English words.
To extend the list of common words for a document
create a note named "stoplist"

open a text window for the newly-created stoplist
type words you wish Tinderbox’s Common Words view to ignore
close the text window
Listing notes
To list all notes in a document
select Locate... from the View menu
All notes in the document will be listed, with each one represented by a tiny icon of the note at the
left, which will be colored as for note's $Color attribute. Click a note and click Open to open that
note's text window.
To list notes that are similar to your current note
select Similar notes from the Window menu
Similarity is based on word usage such as the note's text, title, and text contained in user attributes.
In addition, notes having the same prototype are more similar than notes that have different
prototypes, and notes having roughly similar amounts of text are more similar than notes that have
very different amounts of text.
Files
Each note can be easily associated with a file — an image, a movie, a podcast, an Automator action,
a Tinderbox document, a folder, or even an application — through the note’s File attribute. This lets
you keep the Tinderbox document small and fast, while providing ready access to outside data when
you need it.
You can define additional File attributes as user attributes if needed. But most Tinderbox notes
16 of 178
Tinderbox v5 Manual
should only need to refer to a single file; if you want to have multiple File attributes, your note may
really comprise several different notes.
To associate a file with a note
make sure the text window of the desired note is open

drag a file from the Finder and drop it onto the (drop files and folders) popup menu in the
sidebar
The file association will be stored in the note's File attribute, and may be launched from a menu on
the File button.
To remove a file from a note
choose Clear File from a note's File menu
Files are stored as absolute paths; renaming or moving the file may make it inaccessible from the
Tinderbox note.
Scripts
Tinderbox allows you to execute Applescripts from within a note. Tinderbox will run the script, which
should be saved in uncompiled form (i.e. saved as 'text' , as a '.applescript' file), automatically
whenever the text window for the note is opened, or whenever the note's script button is pressed.
To associate a script with a note
make sure the text window of the desired note is open

drag a compiled script from the Finder
drop the script onto the Script popup menu in the text sidebar
The script will now run automatically whenever the note is opened unless you turn off automatic
running of scripts.
To turn off automatic running of scripts
choose Document Preferences (for this document only) or Tinderbox Preferences (global) from
the Edit menu
in the General tab, uncheck the Run Scripts Automatically box and click OK
To run a script manually
choose Do script from a note's Script menu
To remove a script from a note
choose Clear script from a note's Script menu
History
17 of 178
Tinderbox v5 Manual
The history list is a list of every note you have selected in the current Tinderbox session.
To open the history list
choose History from the View menu or press ⌘⇧Y
To visit a note in the history list
double-click its name in the history list, or select its name and press the space bar. Its text
window will open.
To clear the history list
click Clear
To clear only recent notes in the history list, select a note in the list and click Rewind. All the note
names after the note you selected will be cleared.
18 of 178
Tinderbox v5 Manual
Writing in Notes
The text window for any note is simply a window where you read and write the note's text and
images.
To open a text window
select any note (by clicking on it)

press spacebar, OR double-click the title
To type in a note
Click in the text window, and start typing.
To put the time or date in a note, choose Insert Date from the Edit file menu.
To put an image into a note
copy the desired image from your graphics application or from the Scrapbook (see notes on
temporary suspension of this feature)
paste the image into a text window, wherever in the text it should appear (see notes on
temporary suspension of this feature).
Note that you can’t drag the image directly; you need to select the portion you wish to move to
Tinderbox, copy, and paste.
To copy an image of the current view window,
select Copy view picture from the Edit menu (see notes on temporary suspension of this
feature)
This feature copies the entire view image, not just the visible part.
Text Appearance
The Style menu and the Fonts palette (⌘T) give you control over the appearance of your text,
including size, color, and alignment. Additional formatting options are available in the Text pane of
the Inspector palette (⌘1).
If you are Import text from other programs, the text may include hard line breaks. The Edit menu
command Remove Line Breaks removes unwanted line breaks from the selected text.
Spelling
From the Edit menu’s Spelling submenu, choose Check Spelling to highlight errors in the current
note.
Check Spelling As You Type will highlight spelling errors after every keystroke.
If a word indicated as misspelled really isn't, click it, then select Ignore Word or Learn Word.
19 of 178
Tinderbox v5 Manual
Attributes
In addition to its title and text, each Tinderbox note has a long list of attributes that describe aspects
of the note: its name, color, position, shape, and size. You can define your own attributes as well.
Attributes let you (and Tinderbox) put meaningful information in a known place.
For an informal note, you might simply write information in the note’s text:
Read Gibbon’s Decline and Fall of the Roman Empire
In other contexts — research notes for a dissertation, say — you
might prefer to be a bit more formal:
Author: Edward Gibbon
Title: The Decline and Fall of the Roman Empire
Author and Title are examples of attributes; by putting the name of the author in a specific place, it is
easy for us (and for our Tinderbox agents) to distinguish a book by Gibbon from a book that is about
Gibbon.
You don’t have to define Tinderbox attributes before you begin making and using notes. Tinderbox is
designed to encourage experimentation and evolutionary change in your work. As your needs
change and your understanding grows, you can add, change, and delete attributes whenever you
like.
Each attribute has a value; values can be numbers, character strings, boolean (true/false) values,
dates, colors, files, and so forth. Whenever you rename, edit, or change a note in Tinderbox, you are
actually changing the value of one or more attributes of that note.
There are two types of attributes:
System attributes: information built into all Tinderbox documents such as the color of the note,
or its width and height. Tinderbox keeps this information about every note, and you may view,
use, and change it.
User attributes: you may add your own attributes that every note will have. For instance, you
could add the attribute "Priority," and assign every note a priority level from one to five. Or in a
bibliography, create the attribute "Type" and tag the note for each source as either "primary" or
"secondary."
A few System attributes are
Read-only attributes: information such as the date and time the note was created, or the date
and time it was last modified. Other read-only attributes, such as TextLength and ChildCount,
describe properties derived from the document’s current state and are inherently read-only.
Tinderbox keeps this information about every note, and you may view and use it, but you
cannot change it.
Tip: attribute names are case sensitive—"Height" is not the same as "height."
You can inspect and change the value of any attribute in a note's Get Info... window (choose Get Info
from the Note menu). Inherited values are in gray; values set specifically for this note are in black,
and read-only values are italicized.
Key Attributes
20 of 178
Tinderbox v5 Manual
Tinderbox keeps track of hundreds of attributes for each note, but only few attributes are likely to be
of chief interest to you. If you are making notes about some books, for example, key attributes might
include author, title, and ISBN number.
A note's key attributes are displayed at the top of its text window. You can choose the key attributes
by setting the value of the attribute named KeyAttributes — just enter the names of the
attributes you'd like to make key attributes, separating them with semi-colons.
To add an attribute to the note’s key attributes,
select the key attribute from the Key Attributes menu in the text window sidebar
OR
drag the key attribute from the Attributes palette and drop it into the text window
OR
select the note and press Enter to view the note’s Rename dialog. Choose key attributes
from the Key Attributes popup menu, and press OK.
Drag key attributes to up or down to rearrange them, or drag them out of the key attributes table into
the text area of the note to remove them.
Key Attribute display differences
Attribute data types are discussed in more detail further below, but it is worth noting how attribute
data types are displayed or edited slightly differently when a key attribute:
Action, File and String data types appear as a simple edit box
Boolean data type displays as a tick-box (ticked = true).
Color data types has a color chip to the left of the edit box, which displays the color currently
set. The value in the box may be a named Tinderbox color or hexadecimal color value.
Date type attributes are show as the day, month and year plus hours and minutes, formatted
according to the user's OS' System Preference for the 'short' data format. If a date is entered
manually and the time is omitted, the current system time is appended. Seconds are not used.
Number data types are displayed as exponential numbers if very large or very small (0.000001
as 1e-06). If there are large numbers of decimal places, these may be truncated in the display
(though not the underlying data).
List and Set data types are shown as a single string with semicolons delimiting individual
values.
URL data type shows a globe icon before to the text edit box. If the icon is clicked, the currently
displayed URL is opened in the user's default web browser.
Key Attribute value pop-up lists
For String, List and Set data types, a disclosure triangle at the right end of the attribute edit box
21 of 178
Tinderbox v5 Manual
opens a pop-up list which shows all discrete values for that attribute in the current document; for list
and sets the listing is of all discrete list values across the document. As value lists may grow long,
they are limited to 99 values. For such attributes no pop-up list control if shown - so the absence of a
disclosure triangle indicates many values. Listings are case sensitive ('dog' and 'Dog' will be
separate entries).
Clicking a list item sets a String attribute to that value or with Lists and Sets it is appended to existing
values.
Key Attribute value autocomplete
Where value lists are offered, autocompletion is available. As the user types a value it is completed
with the nearest possible case sensitive match. Up and Down keys can be used whilst editing to
scroll other possible list values for the stored value list.
To see other attributes in a text window

In a text window
reveal the sidebar if it is not already visible.

click the Attributes triangle to reveal the attributes browser.
choose a type of attribute from the popup menu (General, HTML, etc.)
The Attributes Palette

The attribute palette is a convenient way to see what attributes your document has, and to change
the default values for attributes.
Tip: the attributes palette does not allow you to change the value of an attribute for a selected
individual note or notes. (The Quick Stamp is a good way to do that.)
To open the attributes palette
choose Attributes from the Window menu or press ⌘2.

the System tab of the attribute palette shows attributes that are built into Tinderbox. Attributes
you can modify are listed in plain text. Read-only attributes are italicized.
the User tab of the attribute palette shows attributes that you have created and added to this
Tinderbox document.
To change an attribute’s value

There are several ways to change an attribute's value for a selected note or notes:
Using the quick stamp palette allows you to change the value of that attribute for one selected
note or for many selected notes.
In the Info window for a note shows all the note’s attributes and allows you to change the value
of any attribute.
The Value menu contains Stamps that allow you to change the value of that attribute for
selected notes.
To use the quickstamp
22 of 178
Tinderbox v5 Manual
The Quickstamp inspector lets you change any attribute for the currently-selected note(s).
From anywhere,
select the desired note or notes

choose Inspector from the Window menu to open the quick stamp palette
In the Quickstamp palette,
select the desired attribute from the popup menus in the palette
type the desired value into the Value text field
click Apply to apply that value to that attribute in the selected note or notes
To change an attribute value using an info window
select the desired note

choose Get Info from the Note menu, or press ⌘⌥I (the letter i)
or
open the note’s text window

click the blue "i" button in the text window sidebar
From the info window,
double-click the desired attribute in the right-hand column of the list. (The left-hand column
shows the attributes, the right-hand column shows their values.)
in the dialog box, enter a new value for the attribute
Some attributes are read-only and cannot be set. For example, the value of a note’s $WordCount
depends on the number of words in its text. Read-only attributes are italicized in the list.
To set an attribute's default value
The default value of an attribute is the value Tinderbox uses if no specific value has been set for that
note.
The Attributes window lets you change the default value of attributes. If you set the default value of
Color to red, then all newly-created notes will be red, and all notes for which no specific color was
chosen will also become red.
23 of 178
Tinderbox v5 Manual
To open the Attributes palette, choose Attributes from the Window menu (⌘-2).
In the attribute palette,
select the tab of the palette corresponding to the type of attribute you want to modify built
in to Tinderbox
select the desired attribute in the scrolling list of attributes
type the desired default value in the text field on the palette
click Change
To create a new attribute
First, in the attribute palette,
select the User tab

click Create...
Or, from any info window,
click the New button at the bottom of the window
Then,
in the dialog box, choose a name, a type, and a default value for the new attribute
click OK or press Return to dismiss the dialog
All notes will have this new attribute and will use the default value for the new attribute until you set it
in particular notes.
Attribute types
Attributes can be of various types, to contain various kinds of data:
String
Any sequence of text. "Yes," "Marie Hancock-Lowickie, Jr.," and the first paragraph of the Gettysburg
Address would all be valid values for a String attribute. $Name is an example of a string attribute.
color
Color values are accepted in these formats:
24 of 178
Tinderbox v5 Manual
named colors. The name (string) of a color that either comes pre-defined in Tinderbox, or which
you have defined for this Tinderbox document using the Colors pane of the attribute palette.
Names set as text strings are stored as strings. Examples: "blue", "red", "minty-fresh-green",
"subtle yellow".
hexadecimal: six hexadecimal digits, the format used for describing colors in HTML. A
hexadecimal value should be preceded by a number/hash sign sign. Example: #A482BF
hue-saturation-value: hue—a value from 0 to 360 degrees; saturation and value—from 0 to 100
percent. Preceded by HSV, and enclosed in parentheses. Examples: HSV(0,100,50),
HSV(240,80,80). HSV values are stored in the six-digit hexadecimal form (as above).
RGB: Red, green, and blue, with intensity levels represented as integers from 0 to 250.
Examples: rgb(0,0,0) and rgb(68,153,68). RGB values are stored in the six-digit hexadecimal
form (as above).
$BorderColor, which controls the color of a note's main border, is an example of a Color attribute.
You may drag color swatches out of the Colors pane of the Attributes palette, and drop them on
notes in the map, outline or treemap views.
When displayed as a key attribute, Color type attributes show a color swatch next to the text value.
The swatch shows the current color value and if clicked, can be used to set a new color using any of
the OS' color picker panes.
In many respects, Color-type attributes can be considered a special form of String-type attribute
File
The pathname to a file. File-type attributes are used mainly or such System attributes as
$HTMLExportTemplate.
Boolean
A true/false value. May use either 1/0 or true/false. $ShowTitle is an example of a Boolean
attribute. If setting the value via action code, the value is never quoted (as a string would be). The
true/false values are also case-sensitive - i.e. do not use True or False.
When displayed as a key attribute, Boolean type attributes show a tick box; ticked equates to true,
un-ticked to false.
Date
A date and time. When entering a value for a date, you may use your local Macintosh date formats
and a variety of other standard forms. You can also use the terms yesterday, today, and tomorrow,
and add or subtract units of time. Time (in hours/minutes only) is always part of Date data even if not
displayed. For example, these are all acceptable values for a date attribute (on a month/day ordered
Mac):
25 of 178
Tinderbox v5 Manual
10/25/2002
10/25/02
10/25 (assumes the current year)
November 15, 1955
Nov 15 55
today
today - 7 days
yesterday + 4 months (expressing date values relative to the current time is often convenient
when defining agents and actions.)
Wednesday (interpreted as next Wednesday)
11/25/2002 12:43
On non-US Macs, the day/month order might vary as might the allowed delimiters for
day/month/year/time. Tinderbox defers to the current users "international" System Preferences for
allowable formats. Internally, the data is stored in a locale-independent format so a date set on a US-
locale Mac will still be correct is the document is subsequently opened on a French-locale Mac.
If sharing files cross-locale do be aware of where dates represented in code as string literals which
thus fix a locale type. In such cases it is better to store that date in a Date type attribute in a note
somewhere and refer to the attribute, ensuring the date is locale independent.
$Created is an example of a Date type attribute.
Number
Either an integer or a floating point (decimal) number, positive or negative. $ChildCount is an

example of the Number type.
When displayed as a key attribute, Number type attributes display very large or small numbers in
exponential form; only 6 decimal places are shown in the key attribute edit box.
List
Lists are strings separated by semicolons, and are useful for lists of topics, categories, and tags.
Status: urgent;delegatedToMartha
Topics: programming;computer languages;courses;news
Tags: tips and techniques; readme; TuesdayMeeting
Lists can be assigned with Stamps, Quickstamp, the Get Info Window, or the Key Attributes table.
They may also be set by agents and other actions.
Lists can be sorted.
In many respects, List-type attributes can be considered a special form of String-type attribute (a
string with semicolon delimited values), meaning that Lists can be coerced to/from Strings.
TimeLineBandLabels is an example of a list attribute.
Set
26 of 178
Tinderbox v5 Manual
Although Set pre-dates List as a Tinderbox attribute data type, Sets are best though of as a special
form of List. The primary difference is that Sets only hold one instance of any given unique list value;
passing a List with duplicate values to a Set will de-dupe it; it can always then be returned back to a
List type so it is a list but now lacking dupes.
A Set, unlike a List, can't be sorted.
In many respects, Set-type attributes can be considered a special form of String-type attribute (a
string with semicolon delimited values), meaning that Sets can be coerced to/from Strings.
$KeyAttributes is an example of a Set attribute.
URL
URL type attributes are used, unsurprisingly to store URL data.

When displayed as a key attribute, URL type attributes show a globe icon to the left of the value edit
box; if a URL value is sert, clicking the icon opens the URL in the users default web browser.
In many respects, URL-type attributes can be considered a special form of String-type attribute.
Action (System use only)
The Action data type is only used internally. $AgentAction, $DisplayExpression, $OnAdd, $Rule and
$TableExpression are all Action type attributes. As may be guessed, these attribute all hold strings of
Tinderbox action code and are evaluated as such when used.
In many respects, Action-type attributes can be considered a special form of String-type attribute.
Attributes and Agents

Agents often use attributes to locate notes accurately. If you define a user attribute Author, agents
will locate books in your notes written by Booker T. Washington and ignore notes on Seattle,
Washington.
Agents can also set the value of attributes. An agent could look for items that are due within a week
and automatically set the priority to "urgent."
Exporting Attributes
The value of any attribute can be exported to HTML using the expression ^value($attribute_name)^.
For example, if we have stored the location of an image in user attribute ImageName, we might
export:
<img src="^value($ImageName)^">
The Attributes Palette: Other Panes
Colors
Tinderbox uses color names to refer to specific colors. In the Colors panel, you can change the color
scheme and add their own. For example, if you prefer a subtler color scheme, you might redefine
"black" to a medium gray, "blue" to a slate blue, and red to a rusty earth tone.
27 of 178
Tinderbox v5 Manual
Each named color has seven variants. For example:

darkest red
darker red
dark red
red
light red
lighter red
lightest red
The Colors panel offers color swatches corresponding to each color variant, and lets you redefine
existing colors.
When setting modified colors via action code the named main color is given first. Thus, to set a note
to 'darker red' use:
$Color = "red darker";
Stamps
Stamps are actions that set attributes. Like a rubber stamp, a Stamp changes the selected note or
notes to which you apply it, providing you a custom tool kit for your needs. See the Stamps chapter of
this manual for details.
Link Types
Links Types presents a list of the types of links possible between notes. Users may change the name
and color of links here, make individual link types (or just their link labels) invisible in map views, or
create their own link types.
Macros
Macros bundle complex export expressions into simpler, more memorable packages. See the Using
Macros section of the HTML Templates chapter for more.
28 of 178
Tinderbox v5 Manual
Prototypes
Often, the easiest way to describe a note is to explain how it differs from another note. We say that
the first note serves as the prototype of the second: it shares all the properties of the prototype,
except where we specify otherwise. For example, Oliver Twist might be prototype for Great
Expectations: Great Expectations inherits all the properties of its prototype, save for Title and
PublicationDate which we specify explicitly.
Prototypes let you specify the default value for an entire class of notes. Whenever Tinderbox checks
an attribute that you haven't specifically set, it will use the value from the prototype. Change an
attribute in a prototype and you change it for the notes that use that prototype.
A few attributes are inherent and are never inherited. For example, moving Oliver Twist
in the map should not move Great Expectations. Inherent attributes include: Created,
Modified, Height, Width, XPos, and YPos.
Prototypes are an advanced feature—you may not need to use them—but they're powerful time-
savers for complex projects.
To create a prototype,
create a new note, however is convenient, or select and existing note to serve as a
prototype
in the dialog box to name the note, check the box can be a prototype
This new note can now be a prototype for other notes.

In outline view the note icon for notes which can serve as prototypes is surrounded by a light green
circle.
To use a prototype,
create a new note, or select a note and press Enter

choose a prototype from the Prototype popup menu in the sidebar. This menu shows the
names of all notes that have been designated "can be a prototype."
or
select the note in the map view. A tab appears beneath the note showing the note's
prototype, if any. Right-click the prototype tab to select a new prototype from the popup
menu
or
select the note in the outline view, and right-click on the rectangular note icon to select a
new prototype from the popup menu.
Your note will now use the selected prototype: it will inherit the values for most of its attributes from
the prototype note. When you change the value of any of those attributes in the prototype, the value
of that attribute in all of the notes that use that prototype will change as well.
29 of 178
Tinderbox v5 Manual
Prototype Inheritance
Tinderbox notes inherit from their prototype; when you give a note a prototype, you’re telling
Tinderbox, "this note is just like its prototype, except for the differences I tell you about."
Whenever Tinderbox looks up the value of an attribute, it reviews the following checklist:
If the note has a value for that attribute, that’s the value.
Otherwise,
If the note has a prototype, and if the prototype has a value, then we inherit the prototype’s
value.
Otherwise,
If the prototype itself has a prototype, we inherit that value.
Otherwise,
We use the default value for that attribute.
A note’s own values always override inheritance. Suppose that note Prototypical Task is gray. We
create a new note called Today's Meeting that inherits from Prototypical Task. Initially, Today's
Meeting inherits everything from its prototype, so it’s gray, too. But if we set the Color of Today's
Meeting to blue, it turns blue. Meanwhile all other tasks remain gray.
Now, we make yet another note, Conference Call, which also inherits from Prototypical Task. It, too, is
gray, because Prototypical Task is gray.
But perhaps we’d like all tasks to be green; we change the Color of Prototypical Task to green. Now,
Conference Call turns green, because it inherits its Color from the prototype. Today's Meeting
remains blue, because you gave it a specific color; a note’s own values always take precedence over
inheritance.
30 of 178
Tinderbox v5 Manual
Any Note Can Be A Prototype

Any note can serve as a prototype for other notes. You don’t need to define prototypes in advance,
and you should feel free to create new prototypes as your needs change.
Prototypes save typing. As you take notes, you may find that you sometimes repeat yourself, setting
up a series of similar notes that describe similar sorts of things — people, or references, or issues
you want to discuss with your staff. Prototypes can help you capture the common elements, making
it easier and more pleasant to create notes.
A note can only have one prototype, but each prototype can be used by many different notes.
Prototype inheritance in Tinderbox is extremely efficient; don’t worry about memory or performance
when using prototypes.
To tell Tinderbox that a note may be used as a prototype, check Can be prototype in the note’s
Rename dialog.
Equivalently, set the note’s attribute IsPrototype to true. This adds the prototype to Tinderbox’s
prototype menus.
Prototypes and Children

If a prototype is a container, then notes that use the prototype will "inherit" copies of the prototype’s
children. For example, if Prototype Article contains separate notes for Author Information and Article
Text, then making a note into an instance of Prototype Article will create new notes inside the article
to hold the author information and the text of the article.
Note that these “inherited” notes are created at the time the prototype is assigned; adding or
removing children to the prototype at some later time will not affect notes that already use the
prototype.
31 of 178
Tinderbox v5 Manual
Inheritance of prototype notes is controlled by the attribute, PrototypeBequeathsChildren. By

setting this attribute to false for a specific prototype, passing of children to new instances of the
prototype may be disabled. By setting the default value of PrototypeBequeathsChildren to
false, the feature may be disabled throughout the document (unless specifically overridden by a
prototype that wants to use it).
Built-in Prototypes
Tinderbox offers a small number of specimen prototypes built into the application that can be added
to any Tinderbox document.
open the File menu.

select Built-In Prototypes sub-menu.
choose a prototype to add.
the selected item is added to a 'Prototypes' container in the current document.
If Tinderbox detects an existing 'Prototypes' note (case-sensitive), the newly added prototypes note
is added to that container. Otherwise a new 'Prototypes' container is created at root level in the
current document.
32 of 178
Tinderbox v5 Manual
The Toolbar
To show or hide the Toolbar, choose Show Toolbar or Hide Toolbar from the Window menu, or press
⌘⇧T.
Top Row
1. Switch to the Marquee cursor—use this to select multiple notes in view windows. Cursor is the
arrow when over a note.
2. Create a Web link from the selected text in a text window
Bottom Row
1. Switch the the Hand cursor to scroll views
2. Create a link from the selected note. Click on the destination to complete the link, or park the link
temporarily in a parking space.
Right side
1. Parking spaces—click one of these, after starting a link, to hold the link temporarily. You can then
adjust views to bring the destination into view; click the parking space to pick up the link once again.
Several parking spaces are provided which allow concurrent parking of up to 3 discrete links.
33 of 178
Tinderbox v5 Manual
Importing Notes
Tinderbox provides many options for importing text from various sources.
To move moderate amounts of text between Tinderbox and another application, it may be easiest to
copy and paste the text. This approach has the added benefit of giving you a chance to review your
notes: arrange them, color-code them, consolidate related notes, and prune out notes that are out-of-
date or irrelevant.
Drag and Drop

Drag and drop can be the quickest way to add an entire text file to your Tinderbox document.
You can drag and drop:
text: drag a text selection into Tinderbox and—

drop it into a text window to insert the dragged text at that point in the text
drop it into a view window to create a new note. To qualify, a text file should be a plain text
file(.txt extension). To create such a file, look at your word processor’s facilities for saving
a file as text only. If you attempt to drag and drop a file that Tinderbox does not recognize
as a text file, the file will zip back to where it came from when you let go, rather than being
dropped into Tinderbox.)
a text file: drag a text file from the Finder. Drop it into a view window to create a new note
containing the dragged text
a folder of text files: drag a folder of text files from the Finder. Drop it into a view window to
create individual notes for each file. If the folder is dragged again onto container of previously-
imported notes, changed files will update their notes and other notes will be left unaltered.
Finder clipping files
drop into a text window to insert the text or image clipping at that point in the text (see
notes on temporary suspension of the image feature)
drop into a view window to create a new note containing the text or image (see notes on
temporary suspension of the image feature)
a Tinderbox clipping that has been dragged to the desktop from Tinderbox
Storyspace files: may be dropped into Tinderbox view windows to import Storyspace writing
spaces into Tinderbox notes
Bookmarks from web browsers, Bookends, or Yojimbo create Tinderbox notes; the URL of the
note reflects the URL of the bookmark
News items and subscriptions from news readers such as NetNewsWire
OPML files and tab-indented outlines
vCards, dropped into Tinderbox from the Address Book or other vCard-enabled programs, will
be imported and key fields mapped to Tinderbox attributes
Spreadsheets
Selecting a table in a spreadsheet and pasting it into Tinderbox will create a useful set of notes.
34 of 178
Tinderbox v5 Manual
The first row is treated as a set of headings, which map to attributes. New user attributes will be
created for attributes that do not already exist.
A new container will be created to for the table's rows.
Each row of the table becomes a note. The table's fields are key attributes, and these attributes
are populated from the table
Explode
You can convert a large text file into several notes by specifying where Tinderbox should make the
divisions.
Drag a text file into a Map view

With the note selected, choose Explode... from the Note menu
Decide whether to end each note after a certain number of characters or after a delimiter such
as a period, then click the radio button next to your choice
Change the number of characters or the delimiter if necessary. To remove the delimiter from
the new exploded notes, check the Delete delimiter box.
Click Explode.
The new notes will appear as children of the original note, in a new container called Exploded Text.
Delimiters you can use to separate the source content include:
\r (new exploded notes will begin with each Return)

\n (new exploded notes will begin with each new line)
\t (new exploded notes will begin with each tab)
, (new exploded notes will begin with each comma - useful for CSV data)
any custom string, e.g. #### or XYXYXY.
Explode can also optionally delete the delimiter character(s), making it easier to use custom string
that would look odd if left in the output.
It is also possible to control what part of the exploded text is used as a new note's title. Options are:
first sentence
first two sentences
first paragraph
remove title from text. This is useful for making title-only notes via explode.
Whatever the option above, note titles are limited to 512 characters and truncated with an ellipisis if
longer.
Email
The user may email data directly to a Tinderbox document. (This feature has particular interest for
iPhone users, who can easily email snippets to key Tinderbox files)
A Tinderbox file may be connected to its own POP3 mailbox, which it will check when opened (and
again when the Fetch Now button of the Network Status pane is pressed). The mailbox should be
35 of 178
Tinderbox v5 Manual
dedicated to this Tinderbox document, as it deletes messages after Tinderbox reads them.
A new Mail Preferences Pane in Document Preferences allows you to turn the current TBX
document's mail checking on or off (default is off), and to specify:
the address of the email (POP3) server..

the user account (usually the full email address).
password for the above email account.
Tinderbox creates a new container /Mail (i.e. at root level in the TBX), and adds new notes for each
message in the mailbox. The notes are then deleted from the server (this is a natural by-product of
using a POP3 server to draw down mail).
The $Email attributes of email notes contain the 'From' address of the email.
You may drag notes from /Mail and place them anywhere in your Tinderbox document - they are now
Tinderbox valid notes.
Limitations:
only plain text email is currently supported but email that contains encoded non-English
characters (RFC 2047) are decoded.
attachments and MIME/HTML email bodies may be ignored.
proxy servers and alternate ports are not currently supported.
You may choose to include an action, in your inbound email, that will set the new (emailed) note's
$Container attribute on arrival. Thus, when Tinderbox receives an email it scans the subject and the
message body for instructions of the form:
Tinderbox: /path-to-(or)-inbox-container
...or...
Tinderbox: /path-to-(or)-inbox container [action code]
The first argument (a path) specifies a container in which the mail is to be stored If the container does
not exist, it will be created. The argument is a TB path string so can be anywhere within the TBX, as
long as correctly specified, and not just as sub-containers of the default 'mail' container. If a TBX's
note names are not unique it will be necessary to cite as much of the path to the target container as
is necessary to give a unique path.
Tinderbox: /longer/unique/path/to/inbox
The optional second argument (action code), specifies an action that will be applied to the newly-
created note.
An example, using both arguments:
Tinderbox: /UrgentMail [$Color="red";]
will save the note in "UrgentMail" instead of "Mail", and will also set its $Color to Tinderbox defined
color "red". Note that in this case the use of the [ ] brackets is explicit, and isn't simply an editorial
device to indicate the argument is optional. Put another way, you must use square brackets around
the second argument otherwise Tinderbox can't parse out the action code and apply it as intended.
36 of 178
Tinderbox v5 Manual
Views
You may keep many view windows open while working in Tinderbox. Often, keeping several view
windows open can be very helpful. A chart window might, for instance, show you the entire structure
of your work, while a map window lets you work with the details of one section. Or, if you are creating
many links between two parts of your document, you could have a view window open on each area.
To open a new view window choose New ... view from the View menu; or use a keyboard shortcut:
⌘⌥M — new map window
⌘⌥C — new chart window
⌘⌥O — new outline window
⌘⌥T — new treemap window
⌘⌥N — new Nakakoji text export window
⌘⌥H — new HTML view window
⌘⌥E — new explorer window
Moving around
Use the hand cursor to move the view in a window. If the marquee tool is active, hold the option key
(⌥) to switch temporarily to the hand tool.
Use the horizontal and vertical scroll bars to move around in a view window.
To scroll directly to a specific note, simply type the first characters of the note’s name.
37 of 178
Tinderbox v5 Manual
Map views
The Tinderbox map view shows all the notes inside a container. You can arrange notes and
containers as you like, perhaps placing related notes close together.
Map views provide great scope for expressing tentative, preliminary, or provisional relationships
among your notes, and for discovering emergent structure. Tinderbox provides a host of visual
dimensions — shape, color, borders, badges, and many more — that you can use to express the
properties of notes.
To place a note inside another note or inside a container, simply drop it inside another note.
To create a note in a map view
double-click where you want to place the note, OR

select a note and press Return (↩) to make a new note,
OR
choose Create Note… (⌘K) from the Note menu,
OR
right-click where to want to place the note and choose Create Note… from the menu
To rename a note in map view using its Rename dialog
select it and press Enter (⌅).
OR
select it and press Function-Return (fn↩), on laptops with no Enter key.
OR
click and hold the note for a moment, and edit the note’s name in the map. (Assumes edit-
in-place option is enabled.)
38 of 178
Tinderbox v5 Manual
The Prototype Tab

When a note is selected in map view, the Prototype Tab appears beneath the note and shows the
name of the note’s prototype, if it has one.
If the document has no prototypes, no prototype tab is displayed.

To change a note’s prototype, right-click the prototype tab for a menu of available prototypes.
Links
A map view shows the links between notes.
If both the source and destination of the link are in the map, the link is drawn as a line between the
boxes. If the source or the destination of the link are outside the map, the link is drawn as a short
arrow departing from or arriving at a note.
In this map, Cicero is linked to Brutus, Antony, and Caesar. Because Caesar is inside the container
"In Gaul", only the start of the link to Caesar appears in the map.
If the Maps Preference "Allow Enactment" is ticked, if one or more notes are selected, the map's
adornments, notes and links are all dimmed except for outbound links from the selected notes and
the targets of those links. The highlighted links' style is changed to a animated dashed line whose
also animation indicates the the direction of the link by cycling towards the link target.
Adornments
Adornments are labels that you can add to the background of a map view to help organize the map.
You can adjust the size, placement, color, and text color of an adornment, and a map view can have
many adornments, or none. Adornments do not show up in any other views. Adornments can serve to
39 of 178
Tinderbox v5 Manual
label neighborhoods in a map view, but they do not affect the hierarchy or the links of any notes.
To create an adornment
choose Create Adornment… from the Note menu.
OR
right-click in the background of a map view and choose Create Adornment….
Image Adornments
You can use adornment to place images in the background of the Tinderbox map.
To create an image adornment
place the image on the clipboard.

right-click the Tinderbox map where you want to place the image
Choose Paste Picture from the contextual menu
OR
drag an image file into the Tinderbox map while holding the ⌘ key.
Locking Adornments
It it often convenient to lock the position of large adornments. The attribute Lock fixes an
adornment's (or note's) position in the map, preventing it from being inadvertently moved. The
attribute works as a toggle for locking.
To lock (or unlock) an adornment
select the adornment

click the Lock icon,
OR
press Enter (⌅) or Function-Return (fn↩) to rename the selected adornment, and click the
checkbox, Locked.
To make an adornment "sticky"
If an adornment is sticky, objects (including other adornments, notes, agents, and containers) lying
on the adornment will stick to the adornment when the adornment is moved. This makes it much
40 of 178
Tinderbox v5 Manual
easier to work with large, complex maps by moving whole sections of notes together. The attribute
works as a toggle for the sticky state.
To toggle 'sticky'
select the adornment

click the pushpin icon to make the adornment sticky,
OR
press Enter (⌅) or Function-Return (fn↩) to rename the adornment, and select the
checkbox, Sticky.
press Delete
Smart Adornments
Tinderbox "smart adornments" have a query, just like agents.
The smart adornment searches within its map—that is, amongst its siblings in the document outline
—for notes that match its query. Matching notes will be moved to the smart adornment, and notes
that do not match the query will be moved off the adornment. (Locked notes and adornments are
never repositioned by a smart adornment.)
Smart Adornments are handy for automatically organizing containers to which you are frequently
adding notes—especially if these notes are added automatically. When you add notes yourself, you
naturally place them appropriately, but when notes are being moved around your Tinderbox
document by agents or inserted from email, smart adornments can help keep things organized.
Cleanup
The Cleanup popup menu, at the bottom of a map window, gives you ways to rearrange all the notes
in the map. You can arrange the notes in a grid, a staggered grid, a row, a column, or a box.
If you select specific notes in the map, Cleanup only moves the selected notes. If only one or no note
is selected the cleanup is applied the whole map.
Like Smart Adornments, automatic cleanup can help organize clutter.
The Up-Arrow
If you press the up-arrow button, in the bottom-left corner of a map view window the view will zoom
out to show a view of one level up in the hierarchy. This will be an entirely different view than the one
you were just seeing: the whole map will be contained within one of the notes shown in the new view.
If the view is already zoomed all the way out—showing the entire document—then the up-arrow will
be inactive.
Changing The Appearance of Notes

Use the Inspector (⌘1) to change a note’s appearance. Many note properties can also be changed
from the note’s contextual menu or by displaying the Rename… dialog.
41 of 178
Tinderbox v5 Manual
To change the color of the selected note
right-click the note, and choose a color from the Color menu
OR
select a color from the Inspector’s Interior pane
OR
change the note’s Color attribute
To change the shape of a note
select a shape from the Shape submenu in the Note menu
OR
right-click the note and choose a shape from the Shape submenu
To fill the face of a note with a pattern
use Pattern menu in the Note menu, or

select a pattern in the Interior pane of the Inspector, or
set the attribute Pattern for the note
Available patterns include:
solid: a solid block of Color

gradient: a gradual gradient from Color at the top of the shape to Color2 at the bottom
diagonal: a gradual gradient from Color at the top left to Color2 at the bottom right
cylinder: a gradual gradient from Color at the top of the shape to Color2 at the center of the
shape and back to Color at the bottom of the shape
bar(nn): a bar of Color2 running from the left edge to nn% of the width of the shape, with the
rest of the shape filled with Color. The argument nn may be a number between 0 and 100, or an
expression that can be evaluated as a number. For example, if you are writing a 2500-word
essay, bar($WordCount/25) would indicate how close you are to the word limit.
vbar(nn): a bar of Color2, running from the bottom of the note to nn% of the height of the
shape, with the rest of the shape filled with Color. The argument nn may be a number between
0 and 100, or an expression that can be evaluated as a number. This is bar(nn) on a vertical as
opposed to a horizontal axis.
Three additional patterns are available only to agents and containers to provide information about
42 of 178
Tinderbox v5 Manual
their contents.
plot(expression[,min,max]): The expression is evaluated in turn for each child of the agent or
container, and a graph of the result is drawn in the body of the agent or container. The graph
color is determined by the attribute PlotColor. If min and max are not specified, the plot is
automatically scaled to the range of the data.
bargraph(expression[,min,max]): The expression is evaluated in turn for each child of the agent
or container, and a bar graph of the result is drawn in the body of the agent or container. The
graph color is determined by the attribute PlotColor. If min and max are not specified, the plot is
automatically scaled to the range of the data.
xyplot(x-expression, y-expression [,ymin,ymax]): The expressions x-expression and y-
expression are evaluated in turn for each child of the agent and container, and a Cartesian
graph of the result is drawn in the body of the agent or container. The graph color is determined
by the attribute PlotColor. If ymin and ymax are not specified, the plot is automatically scaled to
the range of the data
To add a border
the Border Inspector pane is the most convenient way to adjust a note’s border. You may
also use submenus of the Note menu and of the note’s contextual menu to change border
color and styles.
To add a badge to a note

Badges are small icons that are useful for drawing attention to exceptional notes. Frequently,
badges will be set automatically by agents and rules. You can also select a badge manually.
Select a note
In a map view, right-click in the note’s upper right-hand corner
or
In an outline view, right-click in the space to the left of the note title
Choose a badge from the popup menu
Custom badges
A selection of nearly fifty badges is included with Tinderbox, but you can easily add your own badges
or replace built-in badges with new images. User badges may be stored as standard Macintosh .icns
files in:
~/Library/Application Support/Tinderbox/badges/
From v5.5.0, the format for badges has changed from ICNS to PNG, making it easier for users to
create custom badges; pre-existing ICNS will need to be re-saved in PNG format.
43 of 178
Tinderbox v5 Manual
Changing the appearance of the Map background

The color of any individual Map view can be customised via $MapBackgroundColor, which is
inherited from a Maps Preference allowing for app or document-level customization too. It can
sometimes be useful to have a different background color for different views, especially if working
with multiple view windows.
Bear in mind the map background color set in Preferences is also used as a background color for
various minor views such a Find, Locate, etc.
Maps may also use the same basic two-color pattern variants as used by map icons. Again the
defaults are set via Preferences with settings being inherited by individual views in
$MapBackgroundColor, $MapBackgroundColor2 and $MapBackgroundPattern. Fills are not
supported for backgrounds.
Picture Adornments
Pictures may be inserted into the background of a map view as picture adornments. Like text
adornments, picture adornments don't show up in any other views, and don't affect the hierarchy or
the links of any notes. Locked picture adornments are ignored from drag-selections of notes.
For an image to be available to insert as a picture adornment, the file's contents must be copied to
the clipboard. Thus first open the file in Preview (or an image editor), 'select all', 'copy'; the content is
now on the clipboard ready for pasting and image may be closed. Picture adornments can only be
inserted via the Map view pop-up menu. (a Cmd+V paste will not work).
A simpler alternative is to Cmd+drag a suitable image from a Finder window and drop it onto a Map
view.
Images are inserted and displayed at 'actual size' (i.e. for current desktop resolution - normally 72
dpi). Resizing the picture's 'frame' won't zoom the image size but it will crop it if smaller than the
image. If a shape is set for the adornment, the image is cropped by the shape's boundaries. The
image does scale if the whole map is zoomed in or out.
Note that image format must be a bitmap image, not vector-based (i.e. CAD or EPS). The $Opacity
attribute is also supported for image attributes. The image files may have the extensions (formats)
.gif, .jpg, .jpeg, or .png.
Just as adornments aren't exported in HTML Export, neither are picture adornments.
Displaying Text In Maps

Normally, Tinderbox displays the note’s title in the map. If a note is sufficiently large, Tinderbox will
display some or all of the note’s text as well as the title.
44 of 178
Tinderbox v5 Manual
The text is always drawn in the default text font. A suitable size is normally chosen automatically, but
may be overridden by setting the attribute MapBodyTextSize.
If $MapBodyTextSize is 0, Tinderbox chooses a suitable font size.
If $BodyBodyTextSize is 1, no body text is drawn.
Otherwise, $MapBodyTextSize is the font size, in points, for drawing the note's body text.
Subtitle
The value of the attribute $Subtitle is displayed in map view beneath the note’s title, if sufficient
space is available.
The appearance of the subtitle is controlled by the attributes SubtitleColor, SubtitleSize, and
SubtitleOpacity. The built-in template Dashboard provides an example for using subtitles.
The subtitle is most easily added or changed in the Name panbel of the Inspector (⌘-1).
Display Expression
In maps and other views, Tinderbox typically displays the note’s Name attribute to identify each note.
Sometimes, you might want to display additional information: how much text the note contains, who
is responsible for a project, or when a task is due.
The attribute DisplayExpression lets you change the note’s label without changing the value of
its Name.
The DisplayExpression attribute is simply an expression in action code, just as used in Tinderbox
rules, container actions, and agent actions. If DisplayExpression is empty, Tinderbox displays the
note’s name; otherwise, Tinderbox evaluates the expression and displays the result.
For example:
$Name+" ("+$WordCount+" words)"
--> Chapter 3 (7500 words)
$Name+":"+format($DueDate,"l")
--> Return books to library: 12/30/2008
For more information on actions and expressions, see Appendix 3: Actions, Expressions, and Rules .
Hover Expression
You may display additional information about a note when the mouse hovers over the note.
The attribute HoverExpression lets you specify the information that will be shown while hovering.
A note may have its own HoverExpression, but often will inherit HoverExpression from a prototype.
The HoverExpression attribute is simply an expression in action code, just as used in Tinderbox rules,
container actions, and agent actions. If HoverExpression is empty, hovering over that note has no
effect.
For example:
$WordCount+" words"
--> 7500 words)
would display the current word count of the note, and
$WordCount+" words\n\n"+$Text
45 of 178
Tinderbox v5 Manual
would display the word count followed by an empty line, and then display the first lines of the note’s
text.
For more information on actions and expressions, see Appendix 3: Actions, Expressions, and Rules .
Containers
In map view, containers display a miniature view of their contents, including many of the icon
customizations except displaying body text..
Containers are always drawn with a distinctive shape with the title bar at the top and rounded
corners at the bottom. (Compare agents, which have rounded top corners and a title at the bottom).
The relative scale of the interior of a container is set by the attribute InteriorScale.
You can drag notes into the body of a container, or drag them out of the container to move them into
the current map.
Click and drag the interior background of a selected container to scroll the notes inside the
container.
Normally, container titles are a single line, drawn at the top of the container. If you wish to expand the
size of the title bar, simply drag its lower edge (for containers) or upper edge (for agents).
In this container, the title bar has been enlarged to permit Tinderbox to display a second line of the
title.
46 of 178
Tinderbox v5 Manual
Summary Tables
Containers and agents may display a summary table if their title bar is tall enough to accommodate
it.
The contents of the summary table are determined by the attribute TableExpression, which should
evaluate to a string using the vertical bar character "|” to separate columns. For example:
$Name+"|"+$AssignedTo
would display the name and the word count for each note.
The table heading is taken from the attribute TableHeading; for example:
TASK|ASSIGNED TO
Tinderbox displays one line for each child of the agent or container, until it runs out of space or lists
each child.
If the TableExpression for a child note evaluates to the empty string "", that row of the table is
skipped.
If the TableExpression for a child note evaluates to the string "-", a single hyphen, that row of the
table is replaced by a horizontal rule.
47 of 178
Tinderbox v5 Manual
Outline views
Outline Views
An outline view shows the hierarchical structure of the document as an indented outline. It is easy to
restructure the hierarchy of the document in an outline window, by dragging parts of the hierarchy to
other parts of the hierarchy.
The outline view does not show any of the links in the document.
Outlines are best when you understand the structure of your information, and when it’s easy for you
to put everything in its proper place. If you frequently find yourself puzzling over where to put a note,
consider working in Map view for a while. You can always reorganize later.
You can have several outline windows open at once, focusing on different portions of your document.
You may also wish to keep maps and outlines open simultaneously.
The disclosure triangle
A note which has children is displayed in an outline view with a small triangle to its left.
When the triangle points down, the children are shown in the outline. When the triangle points right,
the children are not shown.
click a triangle to alternate between these views.
OR
with a note selected, ⌥→ turns the triangle down, ⌥← turns it up.

choose Expand from the Note window to turn the arrow down and show the note's children.
hold down the ⌘ key while you click a triangle to flip that triangle and the triangles of all its
siblings in the outline.
hold down the ⌥ key while you click a triangle to toggle that triangle, and also expand or
collapse all the siblings of that note.
hold down the ⌘ and ⌥ keys to toggle a note, its siblings, and all their descendants.
select Expand or Collapse from the Note file menu.
48 of 178
Tinderbox v5 Manual
The Outline Icon
The “icon” that appears next to the disclosure triangle in the outline conveys a host of information in
a very small space.
The Color of the icon’s border is the color of the note.

The “title bar” of the icon indicates whether the note is a container (title at the top) or an agent
(title at the bottom). If an agent is turned off, it's title bar is hollow.
The text lines inside the icon indicate whether the note contains any text, and roughly how long
the text is.
The interior color of the icon reflects how recently a note has been edited. newly-created note
is light blue. Over the course of a day, the note “dries” to a neutral white, and then over the
span of a year it gradually yellows.
Right-clicking the icon displays the note’s Prototype menu.
Double-clicking the icon “Hoists” the note, focusing the window on the note and its descendants.
Editing a note title
To edit a note’s title in an outline, simply click and hold the title. After a brief delay, a frame will
appear around the title and you may revise the title at you wish. The click-hold delay is the same
duration as that used to trigger a file rename in Finder
Several key shortcuts are available when using the in-place note editor:
49 of 178
Tinderbox v5 Manual
Escape (⎋)will cancel editing and restore the previous title.

Return (↩) will confirm the new title and terminate editing (and press again to start a new
sibling note).
Enter (⌅) or Function-Return (fn↩) will open the Rename dialog.
Shift+Return (⇧↩) will confirm the new title, terminate editing, and will create a new note and
begin editing the new note’s title.
Tab (⇥) will confirm the new title, terminate editing, and select the next note visible in the
outline.
Shift+Tab (⇧⇥) will confirm the new title, terminate editing, and select the previous note visible
in the outline.
You may also finish editing by:
clicking on the note’s icon,
OR
selecting a different note
The conventional Rename dialog is always available from the Note menu, the note’s contextual
menu, or by pressing Enter (⌅).
Hoisting
Hoisting a note focuses the view on it and its descendants. Unhoist returns the focus to the top-level
note. These commands are available in chart and outline views.
select Hoist from the View file menu
OR
select Unhoist from the View file menu
Identifying prototypes
In outline view, the note icon for notes which can serve as prototypes is now surrounded by a light
green circle. This helps distinguish notes intended to serve as prototypes. See the Prototypes section
of the Notes chapter for more information.
Separators
A separator is a horizontal line in the outline view that may be colored and titled like other notes via
the Note and Colors menus.
To make a separator:
create or rename a note

check the Separator checkbox in the dialog
OR
50 of 178
Tinderbox v5 Manual
choose Create Separator… from the Note menu
Changing the View Focus

The bottom-left corner of every view window contains an arrow button: an up-arrow in map and
treemap views, a left-arrow in chart and outline views.
If you press the arrow button, the view will “zoom out” to show a view of one level up in the hierarchy.
In chart, outline, and treemap view windows this will make more of the document visible, including
what you were seeing before.
If the view is already zoomed all the way out—showing the entire document—then the arrow button
will be inactive.
Checkboxes
If this View menu item is ticked, the status of $Checked is displayed as a check-box to the left of an
outline item's icon, i.e. at the left-most end of the line entry.
This can be useful for tasks like to-do lists, etc., as the box value can be toggled by clicking on it.
Columns
If this option in the view menu is ticked, it is possible to enhance the view by adding one or more
columns of system or user attribute data to the right of the existing title ($Name) data. This can be
very useful for visual data review, spreadsheet-style.
By default, $ChildCount data is added as the first new column A right-click menu at column head
allows the column contents to be changed, deletion of the column or addition of a new column.
Horizontal order of the column (except the normal $Name data, icons, etc.) is possible via drag-drap
of the column titles.
Boolean attributes are displayed as tickboxes which can be toggled in situ (though only if the the
parent item is first selected). All other column view displayed data is view-only.
51 of 178
Tinderbox v5 Manual
Timeline views
The Tinderbox Timeline shows all the descendants of a selected note. The notes are displayed in a
horizontal timeline, using their $StartDate and $EndDate attributes to determine horizontal position
and automatically arranging notes vertically for legibility.
If none of the notes have a $StartDate, Tinderbox uses their $Modified attribute instead.
Timeline views let you explore complicated events and plan complex processes. They can be
invaluable for determining what happened in events that are incompletely understood, and for
ensuring that plans can be performed as expected and can adapt to unexpected problems.
Tinderbox provides a host of visual dimensions — colors, typography, badges, and many more — to
help distinguish key events and clarify their relationships.
To view the timeline for a container, select an agent or container and choose New Timeline from the
View menu ( ⌘-option-T )
Timelines do not show separators or agents.
To create a new note in a timeline
double-click where you want to place the note, OR
The newly-created note will automatically receive the $StartDate for the point at which you clicked.
To move a note in the timeline, drag it horizontally. The note’s vertical position will adjust
automatically as you drag the note to avoid overlaps.
To change the $StartDate of a note in the timeline, select the note and drag the left resize handle. To
change the $EndDate of a note in the timeline, select the note and drag the right resize handle.
Timeline appearance
Scope of the Timeline
By default, all descendant notes (N.B. not just children) are plotted in a container's Timeline view.
Any note in scope without a $StartDate set is listed in a sidebar to the left titled "NO DATE".
52 of 178
Tinderbox v5 Manual
If $TimelineStart and $TimelineEnd are set for the container, the timeline is constrained to these
dates. Descendant notes with date information but which lie outside the defined Timeline start/end
are placed in a left sidebar titled "OUT OF RANGE".
Where both "NO DATE" and "OUT OF RANGE" data exist both sidebars are drawn separately at the
left of the Timeline with "OUT OF RANGE" closest to the actual timeline.
Where settings are stored - containers vs. notes
Values for the look and feel of the overall view, as opposed to per-note data is stored in the attributes
of the parent container of the notes in the view - i.e. the container selected when Timeline view was
opened.
When no note is selected in the view focus is on the view itself which is useful if opening the
Inspector or Info View to edit atributes.
Placing notes in discrete bands
By default all notes are drawn in a single horizontal band, stored as $TimelineBand. Bands are
numbered upwards from Zero. Descendant notes from different outline depth or parent containers
will all plot in the band is their $TimelineBand is the same.
Notes can placed on discrete timeline bands by setting a different $TimelineBand value or dragging
notes to a new band in the view. Dragging downwards below the bottom existing timeline will cause
a new band to be added (and the dropped note to be set to that $TimelineBand value).
Bands without data below the highest-used band in the view are drawn at a fixed height.
Color of the main view
The color of the timeline part of the view is the parent container's $MapBackgroundColor. Vertical
grid lines indicating major scale increments (depending on current scale) are drawn in the parent's
$TimelineGridColor.
Coloring Timeline bands
Timeline bands are drawn in alternating colors. All even-numbered bands, with numbers starting
from zero, are drawn in a tint of $TimelineColor; all odd-numbered bands are drawn in
$MapBackgroundColor. For a given Timeline view these colors are those of the view's source
container.
Timeline band labels
Bands may optionally be given labels, via a List-type attribute $TimelineBandLabels and further
modified via $TimelineBandLabelColor and $TimelineBandLabelOpacity. All three attribute values
are those of the source container of the Timeline.
Adornments
Map adornments with a $StartDate (and $EndDate) are drawn on the Timeline across (and behind) all
53 of 178
Tinderbox v5 Manual
bands. Adornments can overlap. If $EndDate isn't specified the adornment is drawn with an arbitrary
width (which will vary according to the Timeline scale when the adornment is first drawn). Dragging
the left/right drag handles of a selected adornment will update its $StartDate/$EndDate. A Smart
adornment's query is ignored within a Timeline (unless its OnAdd alters a matched note's
$StartDate/$EndDate).
Varying Scale and Label size
Two scrubber controls at the top of the view allow the horizontal scale to be expanded/compressed
and for on screen labels to be made bigger/smaller.
Customizing the Scale bar
The view container's $TimelineScaleColor and $TimelineScaleColor2 can be used to alter the look of
the bottom scale bar.
Note appearance on the Timeline

Any note in scope for the Timeline is plotted, in its Timeline Band with its left edge at its $StartDate
as on the lower scale bar. To avoid overlapping labels, Tinderbox will plot such notes at different
heights in the band - generally the later of any such pair of notes will plot lower in the band.
If the note has an $EndDate a duration bar will be drawn beneath the note label in the note's $Color2.
When selected, a note has a marker line dropped from the left edge to the scale bar (in $Color2).
When deselected the line disappears unless $TimelineMarker has been set for the note.
The note label is drawn with a background tint of the note's $Color. A badge, if set is shows to the left
of the title but to the right of the marker. The note's $Opacity setting is also respected.
Links between notes on the Timeline are displayed.
Moving notes in the Timeline

Dragging the left drag-handle of a selected note will alter its $StartDate, the right drag-handle its
$EndDate.
Clicking and dragging horizontally moves the note updating both $StartDate and $EndDate without
affecting duration.
Dragging vertically will move a note to a new Timeline band (dragging vertically within a band has no
effect). Dragging all the way below the lowest band will add the note to a new band. A note can be
dragged to the "NO DATE" sidebar, which will set both its $StartDate and $EndDate to "never".
Shift+vertical drag ensures dates aren't altered when dragging between Timeline bands.
To edit a note, simply select it in the main view or sidebar and use normal edit controls. A read-only
note cannot be selected and thus not dragged/altered within the Timeline.
54 of 178
Tinderbox v5 Manual
Chart & Treemap views
Chart Views
A chart view shows the hierarchical structure of the document very clearly, as a tree chart. A chart is
also handy for seeing many notes in one window. It is easy to re-structure the hierarchy of the
document in a chart window, by dragging parts of the hierarchy to other parts of the hierarchy. The
view shows badges (if applied) and log titles will wrap to aid best use of layout space.
A chart view does not show any of the links in the document.
Chart view should be used for smaller (parts of large hierarchies) owing to OS limitations in the
overall virtual canvas on which the chart gets drawn.
The disclosure triangle
A note which has children is displayed in a chart view as a pointy-ended block (rather than a plain
rectangular block).
click a triangle point to alternate between showing or hiding that note’s children in the chart
view.
OR
with a note selected, ⌥→ shows the children, ⌥← hides them.
Treemap Views
A Treemap view shows the hierarchical structure of the document as boxes within boxes, taking up
the entire window. You can re-structure the hierarchy of the document in a treemap window by
dragging the box representing a note (and the boxes it contains) into another box in the window. A
treemap view does not show any of the links in the document, but can visualize complex hierarchies
that are difficult to explore in more conventional views.
55 of 178
Tinderbox v5 Manual
Changing the View Focus

The bottom-left corner of every view window contains an arrow button: an up-arrow in map and
treemap views, a left-arrow in chart and outline views.
If you press the arrow button, the view will “zoom out” to show a view of one level up in the hierarchy.
In chart, outline, and treemap view windows this will make more of the document visible, including
what you were seeing before.
If the view is already zoomed all the way out—showing the entire document—then the arrow button
will be inactive.
56 of 178
Tinderbox v5 Manual
Arranging notes
Outline Views
You can drag notes in an outline window to rearrange the document’s hierarchy.
Drag-postioning a note:
Drop the note while it is over the right third of another note—while the cursor is a right-pointing
triangle—to make the note you are dragging a child of the note you drop it on.
Drop the note while it is over the middle of another note—while the cursor is an up- or down-
pointing triangle—to make the note you are dragging a sibling of the note you drop it on.
(If you drop the note elsewhere in the outline window, it will snap back to its starting location.)
Indenting notes in the outline:
Press Tab (⇥) on the keyboard to indent the selected note one more level in the outline.
Hold down the Shift key while you press Tab (⇧⇥)on the keyboard to unindent the selected
note out one level in the outline.
Chart Views
You can drag notes in a chart window to rearrange the document’s hierarchy. With the arrow tool,
drag a note:
Drop the note while it is over the right third of another note—while the cursor is a right-pointing
triangle — to make the note you are dragging a child of the note you drop it on.
Drop the note while it is over the middle of another note—while the cursor is an up- or down-
pointing triangle—to make the note you are dragging a sibling of the note you drop it on.
(If you drop the note elsewhere in the chart window, it will snap back to its starting location.)
This is effectively the same behaviour as used in Outline view.
Treemap Views
In a treemap window, drag a note inside another note to make it a child of that note in the hierarchy.
If the note you are dragging into is mostly covered up (because it has children), you can drop the note
you are dragging onto the target note’s title bar.
You can drag notes into and out of each other in a treemap window, to completely re-arrange the
hierarchy.
57 of 178
Tinderbox v5 Manual
Aliases
An alias of a note is a new note that is permanently tied to its original. The alias can has its own place
in the outline and the map, but in almost all respects the properties of an alias are the properties of
the original.
An alias allows a note to be in two places at once. The original note can be in one place in the
hierarchy; the alias can be somewhere else entirely. But both the original note and the alias have the
same contents: the same text window, the same attributes, and so on. When you change an alias,
you change the original.
When you delete an original note, Tinderbox deletes all its aliases. Deleting an alias, however, does
not delete the original.
Aliases are one of the most powerful tools in Tinderbox, and one of the most flexible ways for
organizing your notes in ways that a hierarchy doesn’t permit. Aliases are also useful for building
Web sites, where the same content may be required in several different parts of the exported Web
site.
A note can have many aliases, or none.
To create an alias
From anywhere,
select a note
choose Make Alias (⌘L) from the Edit menu
The alias will be created as a sibling of the original note. You can then move it anywhere in the
document that you want.
To find the original note of an alias
From anywhere,
Select the alias

choose Show Original (⌘R) from the Edit menu
Properties of Aliases
An alias has the same name as its original. Change the name of either the alias or the original, and
both will change.
The name of an alias is always drawn in italics.
An alias cannot contain children.
When you open a text window on an alias, you are opening a text window on the original. When you
edit the attributes of an alias, you are editing the attributes of the original.
A few attributes are inherent, and belong to the alias and not its original. For example,
58 of 178
Tinderbox v5 Manual
an alias has its own position in the map, so Xpos and Ypos are inherent. Other
inherent attributes include Height, Width, Parent, Created, and Modified.
If you delete an alias, the original will remain. If you delete the original note, all aliases to it will be
deleted.
59 of 178
Tinderbox v5 Manual
Links
A link is a connection between one note and another. Links allow you to make connections between
ideas, and to move quickly between linked notes.
Types of Links
Tinderbox has three types of links:
basic links — links that connect an entire note to another note (or a section of text within that
note). When you create a link by using the link tool to click between notes in a view, you are
creating a basic link.
text links — links that connect a section of text within a note to another note (or a section of
text within that note) or to an external URL (see below).
Internet links. A link out of the document from a selection of note text to a web URL. Following
such a link will open that location in your Web browser.
Basic Links
To create a basic link

select the source note

click the link tool on the toolbar, or
choose Create Link... from the Note menu, or
choose Make a Link from the Links popup menu in the text window sidebar, or
press ⌘⌃L, or
drag from the link widget on the note
then
click the destination note

choose a type for the link, if desired
Or, in any view window,
right-click, ctrl-click or click-and-hold on the source note with the arrow tool
choose Create Link... from the contextual menu
If you start to make a link and then you change your mind, just click the link tool again to cancel
linking, or press the Escape (⎋) key.
If a web link is created and a URL is found on the clipboard, that URL is auto-inserted as a candidate
URL for the new web link.
60 of 178
Tinderbox v5 Manual
Using a parking space
A parking space allows you to link two notes that are not visible at the same time and create links to
and from text. When you click a parking space in the middle of making a link, it holds on to the link
for you until you're ready to complete the link.
You don't need to clear old parking spaces, just put a new link in the parking space to replace the old
one. When you close Tinderbox all existing parked spaces are cleared (you won't see them next time
you open the app).
The Find view (⌘F or Edit menu) and Locate view (⌘⌥L or View menu) are often useful for rapidly
locating link destinations.
In any view window,
select the source note with the arrow tool

click the link tool on the toolbar (or press ⌘⌃L or otherwise start the link) click a parking
space on the toolbar
while the parking space is holding on to the link for you, do whatever you need to make the
destination note visible.
click the parking space again, to "pick up" the link
Deletion of links is described in 'Deleting Links' further below.
Text Links
To create a text link:
61 of 178
Tinderbox v5 Manual
In a text window,
select the text that should be the source of the link

click the start link button at the bottom of the text window
or
click the link tool on the toolbar (or press ⌘⌃L or otherwise start the link)
if
the destination of the link is visible, click the destination note
if not
click a parking space on the toolbar

do whatever you need to make the destination note visible.
click the parking space again
then,

If you change the text that is the source of a text link, add more text to the source of the link, or
remove some text from the source of the link, the link remains anchored to the modified text.
If you delete all of the text that is the source of a link, but no other text, the link remains: it is linked to
no text, but is at the place in the text where the linked text used to be. If you start typing at that point
in the text, the new text will become part of the text link.
If you add more text to the end of a text link, the added text also becomes part of the text link.
Remember that you can type the special character option-space so that the text you type after the
option-space is not part of the preceding text link.
In a text window, press and hold command+option (⌘⌥) to highlight all text links.
Internet Links
A text link can link to an external Internet resource. When an Internet link is followed, the destination
will be opened in a Web browser (if it is a Web page), in an email program (if it is an email address)
and so on.
62 of 178
Tinderbox v5 Manual
In a text window,
Select the text that should be the source of the link

Choose Create web link button from the Note menu
In the URL field of the dialog box, enter the URL for the link. (For example:
http://www.eastgate.com or mailto:info@eastgate.com) There will also be fields where you
can enter a Title, Target, or CSS Class for the link.
Click OK to dismiss the dialog
Link Types
You can assign each link a type, to express the purpose or category of the link. For instance, if your
Tinderbox document is mapping a logical argument, you might want links of types thesis, support,
conclusion, exception, and so on, to indicate the types of connections between parts of the
argument.
A link does not need to have a type. If you do not assign it a type to a link, it will not have one.
To assign a type to a new link:
create the link

in the create link dialog box, enter a link type: either choose a type from the pull-down
menu of all the link types you have created so far in the document, or create a new link type
by typing in the text field.
to dismiss a Links window, use its close box, or press ⌘W
To assign a type to an existing link:
locate the link, for instance, by choosing Browse Links from the Note menu and clicking the
link
enter a value in the Type field or choose one from the drop-down menu next to the field
click the Apply button
To modify a link type's attributes:
select Attributes from the Window menu or press ⌘2.

click the Link Types tab.
click the link type you wish to modify.
63 of 178
Tinderbox v5 Manual
From there, you can type a new value in the Name or Color field. (Click Change to save your
changes.)
To delete the selected link type for the current document, click the Delete button.
You can also make a link type invisible in the map view:
select a link type, such as prototype, by clicking it

uncheck the checkbox labelled visible
click the Change button
Browse Links
To view links in the Browse Links window
The Links window lets you see all the links originating from the selected note, and edit them if you
want.
For every link originating from the selected note, the Links window shows:
type — the type of the link (if it has one)

destination — the name of the note the link connects.
In the far right of the list, a T indicates that the link is a text link.
From anywhere,
choose Browse Links... from the Note menu, or press ⌘\ (if you are in a view window, first
select the correct note with the mouse or arrow tool.)
From any view window
Control-click (or right-click or click-and-hold) on the note

choose Browse links... from the contextual menu
To dismiss a Links window, use its close box, or press ⌘W.

Note that you can have many Browse Links windows open at once—each showing the links leading
from a different note.
64 of 178
Tinderbox v5 Manual
To change a link's type

From anywhere,
In a view window, first select the source note with the arrow tool (unnecessary from a text
window);
Choose Browse Links from the Note menu; or use another method of opening the Links
window for that note
In the Links window, select the desired link in the scrolling list
Type or choose a new type in the type field (near the lower left of the window), then click the
Apply button
Or, in a map window,
Control-click (or right-click or click-and-hold on the arrowhead of the links arriving at or

departing from one of the notes on the link
Choose the desired link from the contextual menu of links
Change the link type in the dialog
Or, from a note's text window
Choose Browse Links from the Links menu in the sidebar of the text window
Choose the desired link from the list
Change the link type in the dialog
Deleting Links
To delete a link
65 of 178
Tinderbox v5 Manual
In a map window,
Control-click (or right-click or click-and-hold on the arrowhead of the links arriving at or

departing from one of the notes on the link
Choose the desired link from the contextual menu of links
Click Delete in the dialog
From anywhere,
choose Browse Links… from the Note menu, or press ⌘\ (if you are in a view window, first
select the correct note with the arrow tool.)
in the Links window, select the desired link in the scrolling list
press the Delete key to delete the selected link
use its close box to dismiss that Links window
From a note's text window
choose Browse Links from the Links menu in the sidebar

click the note of your choice and select Delete
To delete a text link
A text link can be deleted like any other link, as described above. Or,
In a text window,
select text containing the desired text link

choose Cut from the Edit menu, or press ⌘X
The Roadmap View
To view links with the Roadmap
The Roadmap lets you see all of the links leading to or from a selected space—the local area of a
complex hypertext.
66 of 178
Tinderbox v5 Manual
To open a roadmap,
select a note
choose Roadmap from the Note window
OR
right-click on the note and choose Roadmap from the contextual menu
OR
press ⌘⌥R
The selected note will be shown at the top center of the view, with a thumbnail view of its text below
it. The left column lists all notes that are linked to this note. The right column lists all notes that this
note links to.
You can have many roadmap windows open at once—each showing the links leading to and from a
different note.
To change the focus of a roadmap
Double-click any note in either column. The roadmap will change to show it as the central note, with
links leading in and out of it in the two columns. Any open view windows will also change to make
that note the selected note.
Linking to Text
A link to text will take you to that particular text, in that note, when it is followed; both basic-to-text
and text-to-text links are possible. If the target text is not visibly when the note window opens, it will
be scrolled into view. Rarely needs with short notes, linking to text can be useful if notes contain
large amounts of text and it might otherwise be hard to quickly find the referred-to text when
following a link.
A link to text may originate from anything.
From anywhere,
begin the link as described previously, and click a parking space to hold the link for you
open the text window of the destination
with the cursor, select the text that is the link’s destination
click the parking space, to pick up the link
click the selected text
WikiLinks
Tinderbox has built-in wiki support.
67 of 178
Tinderbox v5 Manual
⌘-⌥-click on any WikiWord (in Tinderbox, a capitalized word with both internal capital and lower-
case letters, i.e. 'CamelCase') to open the note whose title is that WikiWord. If no such note exists,
Tinderbox offers to create one for you. The new note is always created as a child of the current note,
and you can drag the new note anywhere in your document.
Be cautious when mixing Basic links and WikiWord links in the same note. In such a
scenario, ⌘-⌥-clicking anywhere inside a note's text area (though obviously, not on
an embedded basic link), including on WikiWords, will open the first basic link listed in
the Links drop down for the note. Basic links have a higher priority than WikiLinks,
which are dynamic by nature.
WikiLinks do not appear in Tinderbox's tools for examining and finding links, such as the Browse
Links dialog, Roadmap, various query and template calls, nor will a WikiLink be highlighted when
holding down ⌘-⌥ in the text window or drawn on the Map view. When a WikiLink is ⌘-⌥-clicked,
Tinderbox always looks for a matching named note, whether or not such a note has already been
created. In this sense, it should not be thought of as a proper link, but a pointer to a potential location;
a link that does not exist until clicked on, which then ceases to exist after activation.
WikiLinks are not exported to HTML.
68 of 178
Tinderbox v5 Manual
Footnotes
The Footnote submenu of the Note menu provides a fast and easy way to create a new note from a
selected word or phrase.
In one click, it:
creates a new note;

creates a text link from the selected text to the new note;
creates a link from the new note back to the selected text.
The selected text becomes the name of the new note.
To create a footnote
In a text window,
choose Note:Footnote:As Sibling from the Footnote submenu of the Note menu.
OR
choose Note:Footnote:As Child from the Footnote submenu of the Note menu.
Tinderbox will create a new note named after the selected text, and open a text window for you to
write in that new note.
Tinderbox will also create a new text link from the selected text to the new note (of link type of 'note'),
and a new link from the new note back to the selected text (of link type of 'note+').
Depending on the menu option chosen, the footnote note is created either next to the note it
annotates—a sibling of the source note—or as its child.
This new note is like any other note. You can write in it, add images, and add more links as you
choose (see notes on temporary suspension of the image feature). You can close its text window, and
the text window you came from will still be open.
Creating notes and links with the note tool can be handy for adding definitions, explanations,
footnotes, or other quick annotations. You can easily follow the text link from the annotated text to
the note, and easily follow the link from the note back to the annotated text.
The different link type naming of the links to/from the footnote make it easier to identify notes with
footnotes or footnotes themselves.
69 of 178
Tinderbox v5 Manual
Following Links
To see text links, even if Colored Text Links are disabled in Document Preferences, press and hold
the Command (⌘) and Option (⌥) keys.
To follow a text link
In a text window,
while holding down the Command and Option keys(⌘⌥), click within the text of the link.
or
click to place the insertion point within the text of the link.
choose Navigate (⌘]) from the Note menu.
To follow a basic link
In a text window,
while holding down the Command and Option keys(⌘⌥), click any text that is not part of a
text link.
or
with the insertion point within any text that is not part of a text link,choose Navigate (⌘])
from the Note menu.
In any view window,
choose Navigate (⌘]) from the Note menu

The note at the end of the link will become selected; and the view will change (if necessary)
to put that note in view.
To choose which link to follow
A note may have many links departing from it: several basic links, several text links. You can see
what these links are and choose which one to follow:
70 of 178
Tinderbox v5 Manual
First, open the Links window. From anywhere,
choose Browse Links from the View menu (⌘\).
Then, in the Browse Links window,
double-click the desired link.

A text window will open on the link’s destination.
Which Link Will Be Followed?
When you follow a link from a note—by clicking on text, or by clicking the forward button, for
instance—Tinderbox goes through this procedure:
Was the click within a single text link?
If so, then follow that link. If not...
Was the click within overlapping links?
If so, then display a dialog allowing the choice of which link to follow. If not...
Follow the first (uppermost) link in the list of links that is not a text link
Inspecting the list of links in the Links window can tell you which link from a note will be followed.
Re-arranging the order (priority) of links in the Links window can control which link from that note will
be followed, under which circumstances.
Overlapping Text Links
When you try to follow a link from a section of text that is the source of more than one text link,
Tinderbox will display a dialog listing all the outbound links.
In that dialog,
select the desired link in the scrolling list.

click Follow. The dialog box will close, and a text window will open on the link’s destination.
71 of 178
Tinderbox v5 Manual
Agents
Agents are persistent searches.
Agents constantly scour your Tinderbox document, looking for notes of interest—that is, for notes
that match the agent’s criteria. As you add notes to the document, or change existing notes, your
agents automatically update themselves. Agents are active assistants, helping to keep your work
organized and to draw your attention to issues you might perhaps overlook.
Agents can match notes—including container notes, separator notes, aliases, other agents but not
map adornments.
Agents seldom move, and never delete your notes. Instead, agents contain aliases of notes that
match their criteria. You can open, inspect, and edit these aliases.
Your agents can also sort their results, and agents can perform actions on the notes they find.
For example, an agent might locate all books in your research notes that have been
borrowed from a library and are now overdue. It might sort them by the library from
which they were borrowed, and then by author. And it might give these notes a
prominent red border to make them stand out, and also tag them with the topic
"Overdue" to remind you to return them.
Actions are discussed in their own chapter.
Creating an agent
In any view window,
Choose Create Agent... from the Note menu
OR
Right-click, or the background of the view , and choose Create Agent... from the contextual
menu
Tinderbox displays a dialog that lets you name the agent and tell it what to look for. To finish
creating the agent,
Type a name for the new agent

Enter search criteria for the agent
Click OK. (If an action or rule cannot be parsed, Tinderbox will select the troubled item but
will not dismiss the dialog until the error is corrected.)
Agent Search Criteria

The agent’s search criteria or query describes which notes the agent is searching for.
The simplest and most common agents search for notes in which attributes taken on specific values
$Status=="important"
or
$DueDate<"tomorrow"
72 of 178
Tinderbox v5 Manual
Other agents search for combinations of criteria, or for complex patterns of text.
Tinderbox makes it easy to add new agents when you need them, and to improve agents gradually as
your needs change.
Tinderbox provides two ways for building agent queries. You can build simple agents by using the
pulldown expression menus in the middle of the agent dialog; these will help you get started.
Alternatively, you can simply type more advanced queries into the agent dialog.
The pulldown menus in the middle of the agent dialog allow you to create a search expression.
Choose an system attribute—such as $Text, or a user-defined attribute.

Choose a comparison—such as == (equals), or Contains, or linked from
Enter a value:
If you are using Contains, ==, >, <, or ≠, this is the value that you are comparing to.
If you are using inside, descended from, linked to, linked from, or first inside, this is the
name of a note.
Use the … popup menu to add another clause to your criteria, with 'and' or 'or' join. An
'and' generally acts to restrict the number of matches for the previous criteria, an 'or' to
increase them.
Alternatively, you can simply type the agent’s query into the agent query text field. The text field at
the middle of the agent dialog shows the search expression you have built using the expression
menus in the dialog. Modify this by typing in the text field, or create a search entirely from scratch by
typing in the text field.
Searching for text patterns

Perhaps the most common use of agents is to search notes for names and terms of special interest.
For example, the query
$Text.contains("Abyssinia")
locates notes which mention “Abyssinia” in the text, while
$Name.contains("Taipei")
locates notes in which “Taipei” appears anywhere in the note’s title.
The pattern may be a regular expression with wildcards and subexpressions:
73 of 178
Tinderbox v5 Manual
$Text.cintains("Email: \w+@.+$")
will look for notes that contain lines like the following:
Email: info@eastgate.com
That is, the agent looks for the letters “Email: “, followed by one or more letters (\w+), followed by an
‘@’, followed by one or more characters leading up to the end of a line ($).
Appendix 2 discusses regular expressions in more detail. Some
common and useful special characters include:
. matches any character
* matches zero or more occurrences of the previous character.
+ matches one or more occurrences of the previous character.
\s matches any white space character
\S matches anything EXCEPT a white space character
\w matches a word character, such as a letter
\W matches any non-word character, such as punctuation
Searching attributes
Another common pattern for agents is to examine each note’s attributes and look for particularly
interesting notes. For example, we might want to locate notes new notes:
$Created>"yesterday"
or we might seek notes that are colored red:
$Color=="red"
The left-hand side of the comparison is always the name of an attribute. The comparison operators
include
== > >= < <= ≠ !=
The right-hand side of the comparison may be a constant value, as in the examples above, or it may
be a reference to another attribute. For example,
$Color==$BorderColor
will find notes where the border color matches the color, and
$Height==$Width
will find square notes.
The ‘$’ sign tells Tinderbox, “this is the name of an attribute”; since the left-hand side of the
comparison is always an attribute, the $ is optional on the left.
$Name=="TrueName" notes named "TrueName"
$Name==$TrueName notes whose name matches the value of the attribute TrueName
More complex queries may be constructed using logical operators & (and), | (or), and ! (not).
Parentheses may be used to group expressions:
$DueDate<tomorrow & ($Topic=="Iraq" | $Status == "Urgent")
Agents, Dates, and Times

The == equality operator regards two dates as being equal if they share the same year, month, and
74 of 178
Tinderbox v5 Manual
day – regardless of the time of day.

The comparison operators >, >=, < and <= always compare both date and time, so the same note
could be found by two agents: one that locates $Date < "today" and another that searches for
$Date == today.
Faster Search
Searching for text patterns is powerful and flexible, and Tinderbox works hard to ensure that
searching is blindingly fast.
Nonetheless, searching very large documents for complex patterns will eventually become slow. If
your agents need to search numerous lengthy notes for complex textual patterns, they will require
more time. To accommodate them without slowing down your work, Tinderbox will update the agents
less frequently.
You can give your agents a hand by avoiding unnecessary work. For example:
Constrain your queries: If all the notes of interest lie within on container, it is often faster to write
inside(/archives)&$Text.contains(...complex pattern)
than
$Text.contains(...complex pattern)&inside(/archives)
In the first example, Tinderbox knows it can skip notes outside the archives and so can do less work.
Let agents use other agents: Often, several agents may want to limit their search to the same group
of notes — tasks that have not yet been completed, say, or articles that have been published. If each
agent repeats each part of the query, each needs to do work that has already been performed.
Instead, create an agent specifically to look for Open Tasks
$Prototype=="Task"&$Complete==false
and let other agents limit their search to notes inside(/Open Tasks).
Simpler patterns. The query word ( a word ) — is true for all notes that contain the given word
in the title, text, or any string attribute. Because word() need not consider wildcard characters or
other regular expression issues, it is much faster than conventional search.
More Queries
Any expression may serve as an agent query. Some of the most common queries include:
inside( name of note ) — finds notes that are the children of the note named in the parentheses
descendedFrom( name of note ) — finds notes that are descended from the note named in the
parentheses. A note’s descendants are its children, its children’s children and so on.
linkedTo( name of note ) — finds notes that have links leading to the note named in the parentheses
linkedFrom( name of note ) — finds notes that have links coming to them from the note named in
the parentheses
first( name of note[,count] ) — finds the first child of the note named in the parentheses. Optionally,
finds the first count children.
last( name of note[,count] ) —finds the last child of the note named in the parentheses. Optionally,
finds count children.
contains( name of note ) — finds the note which acts as the container of the named note.
word(a word) — for a given single word value, finds all notes containing that word in their title, text
75 of 178
Tinderbox v5 Manual
or any string attribute.

between(attribName,minimum,maximum ) — true if the the value of attribName lies between the
minimum and maximum values.
indented( count ) — finds notes that have exactly count ancestors
similarTo( name of note ) — finds notes whose text is most similar to the text of the named notes.
Similarity is based on the number of words that appear in both texts, weighted to give more weight to
words that are less common in the rest of the document.
The expressions above are listed in the operator pop-up list of the Find view and agents'
Create/Rename dialogs. The listings use slightly different labels, shown here in the same order as
above:
inside
descended from
linked to
linked from
first inside
last inside
is container of
contains word
is between
has indentation
is similar to
Sorting
Popup menus in the Agent properties dialog allows you to sort the contents of agents (and
containers). For example, an agent might gather all notes that are red, and sort them alphabetically
by title. You may sort by any attribute.
76 of 178
Tinderbox v5 Manual
A second popup menu lets you choose to sort capital and lower-case characters separately (case-
sensitive), to ignore differences of capitalization when sorting (case-insensitive), or to sort by the last
word (as when sorting a list of names).
The popup menus next to "Sort by" are the agent’s primary sort order; the menus next to "and by" are
an optional secondary sort order.
Agent Actions
An agent may perform an action (or actions) on the notes it finds. For instance, an agent could find all
the notes that contain the text Connie and turn them blue.
For information on using agent actions, see the chapter on Actions.
Updating Agents
Tinderbox agents search your document for all the notes that match your queries. If your document is
large and your queries complicated, your agents need to do a great deal of computational work.
Tinderbox agents do their work every few seconds, and typically are nearly invisible to you. If you
have many agents, Tinderbox updates only a few agents at a time. But if your agents require so
much time that you find it interrupts your work, you can choose to update agents only on request.
77 of 178
Tinderbox v5 Manual
To update agents manually:
choose Update Now from the File menu or press ⌘-option-=
Normally, agents update automatically and the File menu item Update Agents Automatically is
checked. Select this item to turn off automatic agent updates.
Agent Priority
In some cases, you may find it useful to update certain agents infrequently. For example, if an agent
is comparing $DueDate to "today", the result is unlikely to change in the next few seconds.
The AgentPriority attribute and the Priority popup menu let you reduce the update frequency of
individual agents, or even turn them off entirely.
An agent that has been turned off is sometimes called a frozen agent. It retains whatever aliases it
had created when you turned it off, and will behave as a normal container until you turn the agent on
once more.
The AgentPriority Attribute
In rare cases, you might want to adjust AgentPriority in a rule or action.

The default value of $AgentPriority is 1, which will usually update the agent at approximately
ten-second intervals. Higher values of AgentPriority cause the agent to be checked less frequently.
Setting AgentPriority to 0 asks Tinderbox to check the agent as frequently as possible, and setting it
to -1 turns off the agent entirely.
78 of 178
Tinderbox v5 Manual
Actions
Actions can make your Tinderbox document smarter and more helpful by automatically doing things
that you might forget, or things that you might not have time to do yourself. For example, an agent
might search for especially interesting and urgent notes that might interest you, and perform the
action $Color="red" to call them to your attention.
Several different kinds of notes can perform actions.
Agents can perform actions on notes that meet their criteria.

Containers can perform actions on each note added to the container.
Adornments can perform actions on notes placed on the adornment.
Rules are actions that are performed continuously. Any note, container, agent, or adornment
may have a rule.
Actions In Tinderbox
A Tinderbox action sets the value of an note’s attribute. Because almost every facet of your
Tinderbox document is, in fact, the value of an attribute, actions are flexible and powerful.
Tinderbox is a personal content assistant; actions let you arrange for Tinderbox to perform chores
on your behalf, helping to organize and tag information and bringing especially interesting or urgent
items to your attention.
Actions and inheritance work together to help keep your metadata in good shape. Many people begin
projects with ambitious plans for metadata: topic categories, tag lists, timestamps and statuses of all
sorts. But each additional tag and category takes thought and time; eventually, you skip the
metadata because you’re in a hurry. And each bit of metadata opens opportunities for mistakes; you
look back and realize that some items that you classified under Category 1 actually belongs another
category. Then, some marginal cases confuse matters; soon, you aren’t using categories at all and
vowing eventually to go back and categorize everything. The ambitious category system gathers
dust.
Tinderbox actions can help reduce the bother of metadata by automatically filling out the correct
information and by making sensible initial guesses. It is often preferable to have a few things slightly
miscategorized or mistagged, than to have everything tossed into a single endless list.
At the same time, it is important for assistants to accept some limitations. Tinderbox actions never
create or delete notes. The assistant can suggest delete a note that seems out of place or obsolete,
but the final decision is always yours.
This chapter from the Tinderbox User’s Manual describes the most common and useful Tinderbox
actions. See Appendix 3 of the manual for details on all Tinderbox actions. The Tinderbox Cookbook
is a valuable resource, demonstrating each Tinderbox action, and aTbRef – Mark Anderson’s
Tinderbox Reference in Tinderbox – discussed each action as well.
A Spreadsheet for Ideas

Actions make Tinderbox a more effective tool, shouldering a greater share of routine chores and
letting you concentrate on the more interesting and demanding aspects of your work.
For example, it is often convenient to tag notes with an indication of topic. Sometimes, you don’t
have time to assign notes to topics, and sometimes you might overlook an obvious topic assignment.
79 of 178
Tinderbox v5 Manual
As time passes, you may well discover new topics you’d like to have, but you may not be eager to
review all your old notes.
Tinderbox agents can help. Agents can search for unfiled notes that contain significant words and
phrases; these can be gathered for your attention or even automatically classified.
Containers can help too, because the container may provide valuable context. Suppose your
container holds notes you’re making during a symposium on the naval history of the Second World
War. The container might automatically propose keywords or tags “WW2” and “Navy”. Rules can
enforce workflow requirements or business logic; for example, if you expand a Task into a container
holding several subtasks, a Rule could automatically change the Task into a Project.
if($ChildCount>1) {$Prototype="Project";}
Actions are themselves stored at attributes of notes. They can be inherited from prototypes, so
related notes can share the same actions. Actions can even create and modify other actions.
Expressions
Tinderbox actions can perform interesting and useful computations as they pass information within
and between notes.
Common binary operators include
adds two numbers, concatenates two strings, or computes the

+
union of two sets
subtracts two numbers, or removes an item or a set from a larger

-
set
* multiplies two numbers
/ divides two numbers
& logical and of two boolean values
| logical or of two boolean values
Unary operators include:
! logical not
- numeric negation
The conventional order of operations and operator precedence are used, and expressions with equal
precedence are evaluated from left to right. Parenthesis may be used to group expressions as
desired.
Equality vs. Assignment
assignment: sets left side to value of right side expression.

=
$Color="red" sets the value of $Color.
equality: true if the values of left and right side expressions are
== equal. $Price=="100" checks whether $Price is equal to
80 of 178
Tinderbox v5 Manual
"100."
inequality: true if the values of left and right side expressions are
!=
not equal.
In contexts where Tinderbox is anticipating an expression – in agent

queries, display expressions, and if() statements, Tinderbox treats
= as a synonym for ==. This avoids a common mistake, but we
recommend you use == when testing for equality.
Actions Don’t Need To Do Everything

An assistant’s purpose is to help you to accomplish your work more quickly and pleasantly. It is not
essential to arrange for the assistant to do everything! Instead, let your agents and containers do
what seems easiest and most helpful.
Tinderbox is designed for organic growth, and it is usually best to start with a simple Tinderbox
document. Gradually add assistance as you need it. Little is gained by making a large initial
investment in complex infrastructure which may prove unnecessary.
It is not essential or desirable to use every Tinderbox feature and facility in every project. Assistants
render assistance when their help is useful; sometimes, it is best to do a task yourself.
What Actions Mean

Tinderbox provides different kinds of actions — agent actions, container actions, adornment actions,
and rules. Each kind of action has a subtly different meaning.
Container Actions
Container actions set a note’s values when a note is moved to the container, or when a note is
created inside that container. A container action suggests a sensible or typical value, which you can
then change later if you like. For example, a weblog’s archives might set
$PublicationDate=today when a new note is moved into the Public container, but you remain
free to backdate the post if you wish.
Adornment Actions
Adornment actions set a note’s values when the note is moved onto the adornment. An adornment
with an action is often a special tool that let’s you do something conveniently.
Agent Actions
Agents gather aliases of notes to bring them to your attention, and agent actions change attribute
values of the notes that meet the agent’s criteria. Agents often perform routine tasks that you might
forget; for example, they can automatically assign general topics to notes.
Rules
Rules enforce constraints and business rules. If a container says that $PublicationDate =
"today", that’s a suggestion. When a rule says it, it’s the law: If you change the value, the rule will
81 of 178
Tinderbox v5 Manual
simply change it back. For example, if a rule says that

if(!$FinalReportDate) {$Status="incomplete"}
then, if this note has no $FinalReportDate, its status will remain incomplete.
In summary, Agent actions act on the notes that the agent gathers. Container actions act on notes
added to the container, or notes created inside the container. Adornment actions act on notes that
are placed on top of the adornment. Rules act constantly, but apply to the note itself.
Rules and Actions can be inherited from prototypes just like other attributes.
Contradictions
Contradictory actions may lead to constant document changes and should be avoided.
For example, two different agents might each be trying to change the color of the same note. The first
agent looks for HighPriority notes, and sets their color to be red. A second agent looks for Invalid
notes, and sets their color to orange. What will happen if a note is both high-priority and invalid? One
agent will turn it Orange, then the other agent will turn it Red, and then the first agent will make it
Orange again.
Try to avoid contradictory actions. For example, you might decide that the agent that flags invalid
notes might simply add a badge instead of changing the color
Action: $Badge="flag yellow"
Alternatively, we might decide that a high-priority note should never be flagged as invalid:
Query: $Valid==true | $HighPriority==true
This agent would collect all valid notes ($Valid==true) and also all high priority notes, even if those
notes are invalid. Expressions like these lets agents work together instead of constantly
contradicting each other.
Rules
A rule is an action attached to a note (or container). Rules typically acts only on that note.
For example, the rule
$Urgent = any(children,$Urgent)
will make a note Urgent if any of its children are urgent.
Rules run continuously. If a note’s rule turns it red
$Color = "red"
and you manually set the $Color to green, the rule will change the color to "red" the next time it runs.
Setting Actions
82 of 178
Tinderbox v5 Manual
Select the desired note, adornment, or agent. To assign an action;
Select a note
Choose Rename from the Note menu, or press Enter (fn-Return)
In the Rename dialog , type the desired action(s) into the Action or Rule field (for Agents), or
into the OnAdd or Rule field (for notes and adornments).
Click OK to dismiss the dialog box.
If an action or rule cannot be parsed, Tinderbox will select the troubled item but will not dismiss
the dialog until the error is corrected.
Writing Actions
Setting Values
Actions typically set the value of an attribute"

attribute= value
For instance, the action $Color="red" turns the note red.
To remove a value from a note’s attribute, leave the right-hand side of the assignment empty.
$Color=;
This removes any special value assigned to note’s $Color. After this action is performed, the note’s
$Color will be whatever color it inherits from its prototype, or the default value of $Color if the note
has no prototype.
Text strings should be enclosed in single or double quotes. If you need to include a quotation mark in
a quoted string, precede it with the backslash character.
$Name="She said, \"Hello\" "
Boolean values true and false do not need to be quoted.
Lists and sets are represented as quoted strings, with elements separated by semicolons. For
example:
$ExpenseList="1.50; 2.75"; $Names="Albert; Alex; Alice; "'
Multiple Actions
Multiple actions may be separated by semicolons.

$Color="red"; $BorderColor="blue";
Data Types
Each attribute has a type, which determines what kind of information that attribute contains. Some
attributes are dates, some numbers, some are strings. Details about types are discussed in Appendix
3: Actions, Expressions, and Rules.
Tinderbox automatically converts types as needed.
83 of 178
Tinderbox v5 Manual
$Color="red" OK: Tinderbox converts the string "red" to a color.

$Name="red" OK: Tinderbox treats "red" as a string
$Name=$Color OK: Tinderbox converts the color to a string
$Name=3+4 OK: Tinderbox sets the name to "7"
$Name="3+4" OK: Tinderbox sets the name to "3+4"
format(): converting strings
The format() operator converts various types of attributes to text strings, giving you control of exactly
how the string will be formatted.
format(value,format_string)
For example:
format($Created,"L")
takes the note’s creation date and formats it as a "long local date", such as "Sunday, March 23, 2007
1:26pm".
For more information about formatting dates, see Appendix 5: Date Formats.
Formatting Lists and Sets
If value is a list or a set, the format string is the delimiter used to separate items in the set.
$Text = format($PriceList,"\r")
replaces the note’s text with a list of prices, each separated by a carriage return.
Alternatively, you may supply five arguments to format the set as an HTML, XML, or xoxo list:
format(value,list-prefix,item-prefix,item-suffix,list-suffix)
For example, to format a set $Topics as an unordered HTML list:
format($Topics,"<ul>","<li>","</li>","</ul>")
Formatting Numbers
If a value is a number, format() lets you specify the precision and width of the decimal number:
format(value,precision, width)
For example, if $MyNum is 3.1415927, then
format($MyNum,2,7) is " 3.14"
format($MyNum,2) is "3.14"
format($MyNum,0) is "3"
An alternative with numbers is to use the Number.precision() operator (see Appendix 3).
$MyNum.precision(2) is "3.14"
Examining and Acting On Other Notes

Actions usually refer to the attributes of the this note – the note an agent is examining, the note that
is being added to a container, or the note whose rule is running.
84 of 178
Tinderbox v5 Manual
Attribute references may refer to other notes through keywords such as "parent", "child", "next" and
"previous". A full list of keywords is found in Appendix 3. For example:
$Status=$Status(parent)
makes the status of this note the same as the status of the parent, while
$Status(parent)=$Status
sets that status of this note’s parent to match its own.
Attribute references may also refer to a note through its unique name, or through a path expression:
$ChildCount(/London/monuments)
refers to the note named “monuments” inside the top-level container named "London".
Using Results from Regular Expressions

Agent actions can refer to the results of a regular expression search in a query. For example, an
agent might search for email addresses using the query
Query:$Text.contains("(\w+)@(\w+)")
which matches a series of characters preceding the "@" character and followed by a series of
additional characters.
When a regular expression contains sub-expressions in parenthesis, like (\w+) above, Tinderbox
remembers the actual text that each sub-expression matched. The first matching subexpression is
called $1, the second is $2, and so forth.
In an action, we can then write $1 to refer to the result of the first sub-expression – the part of the
email address preceding the @ sign, and $2 to refer to the second sub-expression.
If the agent query looked for notes that have a line of the form
Color: red;
using the query
$Text.contains("Color: (.+)\r")
then the action
$Color=$1
sets the Color attribute of the note from the color specified in the text.
Conditional Assignment
Actions may be conditional:
if (query) {action} if (query) {action} else {action}
The query may be any expression that could appear in an agent. See the chapter on Agents and
Appendix 3 for a full discussion.
A very common conditional action is a suggestion, assigning a value only if no value has yet been
assigned. For example,
if(!$Status) {$Status="waiting for action"}
A more compact way to write this in Tinderbox is the conditional assignment |=:
$Status |= "waiting for action"
The |= operator assigns a new value to an attribute only if the attribute does not already have a value.
85 of 178
Tinderbox v5 Manual
Many additional actions are discussed in Appendix 3.
Adding and Deleting Notes

Tinderbox actions can neither create new notes nor delete existing notes.
Working With Other Processes
Shell Actions and runCommand()
The runCommand() function lets you run any command-line process or script. For examples,
$Text = runCommand(command_line, input)
runs the specified command line, passing it the result of evaluating input. The value of runCommand
is the standard output of the command. For example:
$Status=runCommand(“sendmail -f address@example.com”,$Text)
will send the note’s text as an email message, or
$Text=runCommand(“ls ~/Documents”)
will replace the note’s text with a list of the files on the user’s Documents folder.
Template actions
Export template markup is primarily used for exporting Tinderbox information to HTML or XML, but it
may also be used in actions. This feature was formerly popular, but is now seldom useful. Use of
export codes in actions is now deprecated.
Export codes are introduced by a caret (^) following the = sign. The remainder of the expression, up
to the next semicolon or the end of the action, is interpreted as an export template. The following
example works but is deprecated:
$MyString=^ Note ^value($Name)^: ^linkTo(/someNote)^;
If you wish to use the template mechanism to construct a complex string, a cleaner approach is the
exportedString function.
exportedString(note,templateFile)
exportedString(note,templateString)
The first form of exportedString takes a reference to a note and the name of a template note or
template file, and returns the result of applying the template to the note. The second form requires no
template; instead, its second argument is itself the template's code string.
exportedString(this,"^value($Name(parent))^")
or
exportedString(this,$MyTemplate)
In the second example, the $MyTemplate attribute would hold export code.
For more information about HTML Export and markup Tinderbox uses for this process, see the HTML
Templates chapter of this manual and Appendix 4.
One Step At A Time
86 of 178
Tinderbox v5 Manual
Tinderbox actions are powerful, and the extensive list of possibilities in Appendix 3 of the User’s
Manual might seem daunting at first.
You don’t need to know every action to use Tinderbox superbly. Tinderbox is intended to help you
extend and revise your documents as your needs change, so you can gradually add richer actions to
streamline your work later, when you more completely understand what you need.
When you see an opportunity to let Tinderbox perform dull chores for you, simply refer to the built-in
manual to find the actions you need.
87 of 178
Tinderbox v5 Manual
Stamps
Stamps make it easy to set the values of attributes quickly and consistently.
Stamps appear in the Stamps menu; choosing a stamp applies that stamp to the selected notes.
Stamps are especially useful for repetitive actions, such as marking tasks as Completed.
The Quickstamp Inspector pane also provides a convenient tool for inspecting a Tinderbox
document, letting you compare the values of any attribute as you select different notes.
To create a stamp
From anywhere,
Choose Edit Stamp… from the Stamps menu, OR

Open the Stamps pane of the Attributes window (⌘-2)
Then,
Enter a Name for the stamp

Enter the Action the stamp performs. For example, $Color="red";$BorderColor="orange";
Click Change to create the new stamp
To apply a stamp
From anywhere,
Select the desired note or notes. To select multiple notes, use the marquee tool or shift-
select, cmd-select, or Select All (⌘-A)
Select the desired stamp from the Stamps menu
Quickstamp
The Quickstamp Inspector lets you create a temporary stamp, providing a quick way to change the
attributes of any selected note.
To open the Quickstamp Inspector, choose Inspector from the Window menu (⌘-1).
88 of 178
Tinderbox v5 Manual
The Quickstamp Inspector assigns new values to all the currently-selected notes. If the selected
notes share the same current value, that value is also displayed in the inspector:
In addition, the QuickStamp Inspector also lets you restore the note’s value to whatever value it
would normally inherit. Simply press the use default button.
With large selections of notes, the Quickstamp Inspector shows a busy indicator whilst the process
is still running.
Stamps for Storing Data

Stamps can do more than just be used to change simple attribute values. They may also be used
simply to hold code snippets - like a form of clipboard. For instance a note might have a complex
Rule that needs to be temporarily be removed. A complex bit of code is hard to remember and re-key
and if it will be re-added at a later time it makes sense to cut and save the code rather than simply
delete it.
A stamp may thus be used to hold such code rather than needing to store it in a note's text or outside
the Tinderbox document. Bear in mind that to use this type of stamp you don't apply it but rather
open the Stamp palette, select the stamp and copy the code back to the appropriate location.
89 of 178
Tinderbox v5 Manual
Fetching from the Web

Tinderbox has several ways to fetch information from a Web page and place it in a note, or integrate
the operation of Tinderbox with your Web browser:
You can create a note whose text is the contents of a Web page you designate. Tinderbox can
automatically fetch the contents of that Web page, so that the note is always updated with the
current contents of that Web location.
You can have notes that open automatically in a Web browser.
Attributes for Working With the Web

You obtain all these special behaviors for notes by setting various System attributes for those notes.
URL
$URL lets you associate a URL with a note. Other attributes use this URL to fetch data.
Examples:
http://www.eastgate.com
mailto:info@eastgate.com
AutoFetch
If $AutoFetch is true, the note will attempt to download text from the URL specified in $URL. If no
URL is specified, or if the URL cannot be reached, or if Tinderbox cannot open an internet
connection, AutoFetch has no effect.
The attribute $AutoFetchCommand extends AutoFetch’s capabilities. AutoFetchCommand is an
action, using the same syntax as agent actions and rules. It runs when the file is loaded, exported,
and possibly during idle moments. Typically, AutoFetchCommand will invoke an outside program,
perhaps fetching some information from the user's hard disk or network. For example:
$Text=runCommand("ls ~Documents")
will replace the text of the note with a list of all the files currently in the user's Documents folder.
$Delivered=runCommand ("myDatabaseQuery "+$TrackingID)
will run the shell script myDatabaseQuery, passing it the value of the note's TrackingID attribute as
an argument.
Remember, you can use stamps, Quick Stamps, and prototypes to help you organize and set
attributes easily.
ViewInBrowser
If $ViewInBrowser is true, opening a text window on this note will also open the Web page
indicated by the URL attribute, using in your Web browser
ReadOnly
90 of 178
Tinderbox v5 Manual
If $ReadOnly is true, you cannot modify the text in this note—you can only view it. It makes sense
to set this true for notes that fetch their contents from the Web.
LastFetched
$LastFetched records the date and time when a note was post recently updated from the Web.
91 of 178
Tinderbox v5 Manual
Email To Tinderbox
Though Tinderbox is the tool for notes, you may sometimes need to gather information when
Tinderbox isn’t ready to hand. In some cases, the most convenient solution may be to set up a
special mailbox for key Tinderbox documents. For example, myProjects@example.com could be the
mailbox for your Projects Tinderbox document.
To Set Up Email To Tinderbox
Open the Tinderbox document you wish to receive email.

Open Document Preferences (⌘-8) and select the Mail pane
Check the checkbox to Check email
Enter the address of your POP mail server, and the account name and password that Tinderbox
should use when logging in
Press OK
Note that the email account should be dedicated to this Tinderbox document. Do not use your main
email account, as Tinderbox will download messages and remove them from the server.
How Tinderbox Handles Email
If email checking is turned on, a Tinderbox will attempt to check its email when it is first opened, and
also whenever the Fetch Now button in the Network palette (⌘-3) is pressed. If no internet
connection is available or if the email server cannot be reached, Tinderbox will await a future
opportunity to check mail.
If Tinderbox finds mail on its server, it will download and delete each message in turn. Each message
becomes a note inside the container named Mail at the top level of the document hierarchy.
If the container does not yet exist, Tinderbox will create a new 'Mail' container at root level. Once
created, do not move or rename this container as Tinderbox will re-create the original one; the
container name is case sensitive and it must be at root level.
The Subject of the email becomes the name of the note. The text body of the email becomes the text
of the note. Only plain text email bodies are currently supported; MIME email and attachments are
discarded.
Note that the Mail container may have OnAdd actions. These actions are applied to the newly-
received email notes as soon as they are created. For example, the Mail container could scan the
note and choose a suitable Prototype automatically.
Passing attribute data
Incoming email's body text is scanned for a discrete single line starting "Tinderbox: ". If found the
first (only the first) is scanned for two parameters:
92 of 178
Tinderbox v5 Manual
The target container (mandatory). Use "/Mail" fro the default container otherwise give a
quoted full path or partial path or note name of another container. For partial paths or note
names the first match in outline order will be used if not unique. If the specified container
doesn't exist, Tinderbox will create it before adding the new note.
Action code (optional, mandatory enclosing [ ] if used). A set of [ ] enclosing one or more
complete action code expressions, e.g. $IsUrgent=true. Targeted attributes must already
exist - they won't be created for you. The expression code, including [ ] should not exceed 59
characters, assuming you sue the default container. This limit is the standard (under-the-hood)
per-line length of 80, minus return character and the path 'Tinderbox: ' mark-up , etc. The limit
means this method should not be regarded as a mass data import mechanism.
Email Limitation
Email to Tinderbox requires a standard POP email service that can be reached on the standard POP
port (port 110). IMAP mail servers are not currently supported, but free or inexpensive POP mailboxes
are readily available from a variety of hosting services.
93 of 178
Tinderbox v5 Manual
Exporting to HTML
Tinderbox provides exceptionally powerful and flexible export to HTML and XML. Every Web site and
application has unique needs and requirements; Tinderbox makes it easy to pour information from
your Tinderbox notes into HTML and XML files that meet your exact needs.
Indeed, Tinderbox templates can export data to all sorts of other programs and formats. Since HTML
and XML are likely the most common formats in use today, our discussion will focus on these.
How Export Works

Tinderbox uses HTML templates to understand how your notes should be formatted as Web pages.
The template is simply a HTML or XML text file that looks like the information you want to export,
marking with 'placeholders': the location of information Tinderbox is to take from your document. The
export template is thus a form the Tinderbox fills out, with placeholders to represent blanks and
boxes that into which Tinderbox inserts information from your notes.
For each note that you export, Tinderbox looks at what you have in that note. This tells it, for
instance, “The title goes here, formatted like this. Then the text goes here. Over in this column, put
links to this note’s children, if it has any.”
Many different notes can use the same template. Exporting them will create many Web pages, with
different content—different titles, text, links, and so on—but in the same format on each Web page.
Other notes may use a different format, and so may require a different template.
HTML Templates
An HTML template is simply an HTML file in which special codes, or "placeholders", indicate where
Tinderbox should insert information from each note; see the section further on about Placeholders for
more detail. For example, ^title^ is replaced by the title of the note, and ^text^ is replaced by
the text of the note.
Tinderbox defines a host of placeholders for various purposes, but the majority of these are required
very rarely. The principal placeholders are ^title^, ^text^, ^format^, ^value^, înclude^, and
^children^; understanding these will suffice for many users.
When you export a document, Tinderbox takes each note, puts information in the appropriate places
in the appropriate template, and thus creates a new HTML file for that note.
What gets Exported
What will transfer to the export
Text. The text in your notes translates to text on Web pages. Special characters, such as © and
“curly quotes” that are not part of the standard ASCII 128-character set, will also be translated
appropriately for the Web.
Images. Images will be placed in the translated Web pages where they appear in the Tinderbox
notes. Tinderbox will automatically translate the image files into formats suitable for the Web (either
JPEG or PNG files); see notes on temporary suspension of this feature.
Text links. Tinderbox links from portions of text will translate into links from that text on the web page
to other exported notes or external web links.
94 of 178
Tinderbox v5 Manual
What will transfer in part
Text appearance
Tinderbox’s translation attempts to translate text styles, such as italics, boldface, and relative size, to
similar text styles on most Web browsers.
The translation also attempts to recognize such meaningful items as headings and lists, and create
appropriate HTML to display those items. Tinderbox has a simple lists feature that treats a paragraph
beginning with an asterisk as an unordered list; use two or more asterisks to embed lists within lists.
Or, you can instruct Tinderbox to leave your text exactly as written—you will want to do this if you
have incorporated Web formatting codes into your text already; do this using ^text(plain)^.
Lists
Tinderbox has a simple lists feature that treats a paragraph beginning with an asterisk as an
unordered list. Use two or more asterisks to embed lists within lists.
Ordered lists may be created by beginning new paragraphs with the '#' symbol.
Ordered lists are exported using <ol> and </ol>

The ordered list markup may be customized by setting the attributes HTMLOrderedListStart
and HTMLOrderedListEnd
Ordered and simple (unordered) quick lists should not be mixed
Basic links
If you choose, Tinderbox can add links to each Web page corresponding to the basic links from that
note.
Hierarchy
If you choose, by adding appropriate export codes Tinderbox can create additional links from text on
each Web page to provide access to the notes that are nearby in the Tinderbox hierarchy (ancestors,
siblings, children, etc.).
Overlapping text links
Text on a Web page cannot be the source of more than one link. Text in a note that is the source of
more than one link is linked on the Web to a special Web page listing the links that can be followed.
What will not be exported
Views
View windows—map views, chart views, outline views, and treemap views—are not available on the
Web.
Multi-paragraph text links
On the Web, the text that is the origin of a link cannot span a paragraph boundary. The source of a
Tinderbox text link can span a paragraph boundary. Tinderbox does not check for this violation when
it exports text links; if you are creating for the World Wide Web, you will want to avoid creating such
text links. (If you do export such a text link, various Web browsers interpret this incorrect link markup
with varying degrees of forgiveness. Your link may work on some Web browsers and not on others.)
Links to included notes
Basic and text links to notes included within other notes aren't exported. This is because a note may
95 of 178
Tinderbox v5 Manual
be included in many places and Tinderbox can't guess to which exported page to source page
should link.
Other interface items
Other items of the Tinderbox interface are also unavailable on Web pages, including:
Find text, to search for text throughout the document

Locate, to find a note by name
The Common Words and Similar To views have special export codes to allow their data to be
exported as lists.
Assembling Web Pages from Many Notes

So far we have envision creating one Web page out of the information in one Tinderbox note.
Tinderbox also has very powerful facilities for building Web pages built out of many notes. For
instance, you could have many notes containing news briefs, and Tinderbox could create a Web
page showing all of the news briefs on one page, in the format you choose.
This feature, particularly when combined with the power of agents, is a very powerful way to create
dynamic Web content. Blog-like journal entries, or project updates, gathered into categories, are two
such possible uses.
Complex Pages are described in depth in its own chapter.
Tinderbox And The Web
Text
The ^text^ placeholder is replaced by an HTML rendition of the note’s text.

Tinderbox converts text styles to stylistic markup tags, such as <b> and <i> and <strike>. If you
prefer to use different tags, such as <em> and <strong>, change attributes HTMLBoldStart/End
and HTMLItalicStart/End, and HTMLStrikeStart/End.
Tinderbox converts many non-ASCII characters to their corresponding HTML entities. For example,
the character "&" is converted to "&". If your Web site uses a non-Western character set, such as
Japanese or Chinese, this process will have undesirable effects; turn off HTMLEntities.
Tinderbox recognizes paragraph boundaries and inserts paragraph markup, typically <p> and </p>.
You may easily customize paragraph markup for individual notes or for the entire document by
setting HTMLParagraphStart/End and HTMLFirstParagraphStart/End.
Tinderbox recognizes paragraphs that start with a tab character and emits special markup tags. To
modify these tags, see HTMLIndentedParagraphStart/End.
You may insert HTML tags directly into your text, and Tinderbox will export them in place. If a
paragraph begins and ends with tags, Tinderbox does not add additional paragraph markup.
You may insert export template elements directly into the text, and Tinderbox will evaluate these
exactly as if they had appeared in the template.
Headings
96 of 178
Tinderbox v5 Manual
Tinderbox recognizes paragraphs as headings when the paragraph uses a font size larger than the
default text font size.
If the font is 2-3 points larger than the default font size, the paragraph is treated as an <h3> heading.
If the font is 4-5 points larger, it is treated as <h2>.
If the font is at least six points larger, it is treated as <h1>.
Lists
Tinderbox recognizes lists in your notes, using a simple convention. A series of paragraphs that begin
with an asterisk ‘*” or a bullet ‘•’ character is interpreted as an unordered list.
Ordered lists may be created by beginning new paragraphs with the '#' symbol.
List markup may be customized through markup attributes:
HTMLOrderedListStart/End
HTMLListStart/End
HTMLListItemStart/End
Lists are automatically indented in the text window. Automatic indentation of lists may be turned off
by default in the Text pane of Document Preferences (⌘-8), or for individual notes by setting
$AutomaticIndent to false.
Internal and External Templates

Templates are usually stored as Tinderbox notes. To use a note as a template, check the Is Template
checkbox when creating or renaming the note, or set $IsTemplate to true.
Tinderbox also provides some built-in templates that are available to all documents.
Tinderbox also lets you store export templates in external files, and older Tinderbox documents often
use external templates. All export templates for a particular document must be stored in the same
folder. We will refer to this folder as the HTML templates folder, but it may have any name you
choose, and may be a different folder for each of your documents.
To specify which is the HTML templates folder for a Tinderbox document, choose a default HTML
template for the document. Tinderbox then looks for all other templates as well within the folder that
contains the default HTML template.
97 of 178
Tinderbox v5 Manual
To choose a default template
select Document Preferences (⌘8) from the Edit menu.

select the HTML pane.
press the HTML template file button.
use the standard file dialog to locate and select a template file.
To choose a template for one note

From anywhere,
select the desired note.

choose New HTML View from the View menu.
press ⌘⌥H to open an HTML view window on the note.
In the HTML view window,
choose a template from the template popup menu, near the top right of the controls in the
window. This menu will list all the HTML template files in the HTML templates folder.
Exporting Using Other Than HTML Mark-Up

Although (X)HTML is the presumed mark-up used for 'HTML Export', the process can be used to
export data in all sorts of other forms: XML, OPML, tab-delimited text, CSV, markdown, LaTeX.
Export codes and functions can be used in the same way as with HTML using mark-up tags/codes
for the export language. With export codes take care if using codes that normally auto-generate
HTML code - e.g. link creation codes - as you may wish to create your data using a different output
method. Both the export codes and action operators include a number of special codes designed to
facilitate non-HTML format export.
98 of 178
Tinderbox v5 Manual
HTML View
An HTML View shows you the HTML that would be created by exporting the selected note with the
current HTML export settings. The window also provides convenient controls for changing many of
these settings. Export and Preview buttons allow you to export the note to as a file or to view it in your
Web browser.
You can have many HTML Views windows open at once, showing different notes.
Opening the HTML view for an alias, opens the HTML view for the alias' original.
Tip: To select text in an HTML view window: hold down option while you select the text. This lets you
copy the text, in case you want to inspect or test its HTML elsewhere.
Export Options
The Export pane of a note's HTML View lets you control which notes are exported, choose a file
name, and preview individual notes.
Export
If this box is checked, this note will be exported to HTML when you export the document. (Equivalent
to setting $HTMLDontExport to false.)
Export children
If this box is checked, this note’s children will be exported to HTML when you export the document.
(Equivalent to setting $HTMLExportChildren to true.)
Markup text
If this box is checked, Tinderbox’s export to HTML translate text styles, such as italic, bold, headings,
and lists, using HTML markup.
If this box is unchecked, Tinderbox exports the text of the note without adding HTML markup codes.
Quote HTML
Check this if you want to include examples of HTML in your text as HTML -- i.e., <p> will appear as
<p>, not be translated into a paragraph break. (Equivalent to setting the $HTMLQuoteHTML attribute
to true)
File name
When Tinderbox exports a note to HTML, it automatically generates a name for the HTML file base
on the note’s title. If you want a note’s file to have a specific name—so that you can know what name
to link to from another Web site, for instance—enter a name here. (Equivalent to setting the
$HTMLExportFilename attribute.)
File extension
99 of 178
Tinderbox v5 Manual
The extension—usually ".html"—that should be added to the filename for the HTML file. (Equivalent
to setting the $HTMLExportExtension attribute.)
Template
The template used when exporting this note to HTML. Choose a template from the popup menu,
which lists in turn all the template notes, all the built-in templates, and each external HTML template
file in the HTML Templates folder. (Equivalent to setting the $HTMLExportTemplate attribute.)
Export folder
The folder, usually on your local hard disk, where the HTML files created for this document should be
saved. Press this button to select a new export location.
Previewing your export

Several buttons in the Export pane of a note's HTML View let you inspect and test the exported
information.
Update
Click this button to update the HTML shown in the window to reflect any changes you have made to
the options in this window.
Export
Click this button to export this note to HTML. Exporting will overwrite any older HTML files of the
same name(s). Only the current file is exported, aliases are not exported (use a full HTML export for
this.
Preview
Click this button to export the note to HTML and open the resulting HTML in your Web browser. Note
that the preview feature will result in an HTML file being created on your hard drive.
Customizing HTML Markup

You can customize the tags that Tinderbox applies to mark paragraphs and styles in order to
accommodate your own coding styles and standards.
first paragraph
These fields specify what HTML markup should surround the first paragraph of text when the text of
this note is exported to HTML. They default to <p> and </p>. (Equivalent to setting the
HTMLFirstParagraphStart and HTMLFirstParagraphEnd attributes.)
subsequent paragraphs
100 of 178
Tinderbox v5 Manual
As above, but for all other paragraphs of text in the text of the note. (Equivalent to setting the
HTMLParagraphStart and HTMLParagraphEnd attributes.)
indented paragraphs
Tinderbox recognizes paragraphs that begin with a tab character as special. These are exported with
HTMLIndentedParagraphStart and HTMLIndentedParagraphEnd tags. Starting a paragraph with a tab
character is often used to indicate an indented or block-quote paragraph.
before and after
Empty by default, this is what is exported immediately before a note's opening paragraph markup
and after a note's final paragraph market, respectively. Can be useful in connection with CSS
stylesheets, such as setting before and after to <div> and </div>. (Equivalent to setting the
HTMLExportBefore and HTMLExportAfter attributes.)
The Style tab of HTML View lets you customize the markup applied to bold, italic, and other styled
runs of text.
bold
The before and after fields hold the opening and closing tags for bold passages and default to <b>
and </b>. (Equivalent to setting HTMLBoldStart and HTMLBoldEnd attributes.)
italic
The before and after fields hold the opening and closing tags for an italic passage, <i> and </i> by
default. (Equivalent to setting the HTMLItalicStart and HTMLItalicEnd attributes.)
underline
The before and after fields hold the opening and closing tags for an underlined passage, <u> and
</u> by default. (Equivalent to setting the HTMLUnderlineStart and HTMLIUnderlineEnd attributes.)
strikethrough
The before and after fields hold the opening and closing tags for an strikethrough passage, <strike>
and </strike> by default. (Equivalent to setting the HTMLStrikeStart and HTMLStrikeEnd attributes.)
HTML Preferences
The HTML pane of the Preferences dialog controls how your document will be exported into HTML.
You will want to set these options before you export to HTML.
To open the Preferences dialog, choose Document Preferences... from the Edit menu (⌘-8).
URL ( web server)
The text in this field should describe where the HTML files will be stored when your document is
101 of 178
Tinderbox v5 Manual
available for Web reading (no matter where they are originally saved). Some examples:
If you are creating HTML files to read locally on your computer (to test your export, perhaps) you
can leave this field blank.
Tinderbox exports hrefs with relative addresses, so for most Web-serving applications you can
also leave this field blank (rather than filling it in as described next).
If your HTML page files will eventually be made available in a directory named web_texts within
a directory named public, and that directory is on a machine whose Internet address is
carthage.utara.edu, then this field should contain
http://carthage.utara.edu/public/web_texts/
The catalogue section of the Eastgate Systems Web site is located at

www.eastgate.com/catalog/. To create files that will go on that portion of the site, I can enter
catalog/ in this field. (The links between pages created this way will all be relative to the
catalogue section of the Web site. These links will not work for testing the files locally, but will
link properly after the files are uploaded to Eastgate’s Web server.)
Tip: changing the URL (Web server) information will not change where Tinderbox stores the HTML
files—you choose that when you export, using the usual Macintosh file dialog. This information only
describes where those files should be for the links to work.
HTML template file
You should choose which template Tinderbox should use by default when you export to HTML. This
will be the template used for notes that do not specify a different template.
You may choose an external file, a template note, or a built-in template.
Exported with extension:
Choose whether the names for the HTML files Tinderbox creates should end with the .html extension
or .htm.
Open file with:
For convenience while testing your exported files on your Macintosh, select which application should
open when you double-click one of these HTML files.
Link images as:
Tinderbox must translate the images in your document from the Macintosh image format (PICT) to a
format suitable for use on the Web. You may choose to have images translated into JPEG images, or
into PNG images. (At this writing, PNG images are only understood by newer Web browsers.)
Tinderbox creates the image files, and the references to them in the HTML files (see notes on
temporary suspension of this feature).
Export paragraphs:
102 of 178
Tinderbox v5 Manual
as prose: if this option is selected, paragraph breaks (carriage returns) in text are exported as
paragraph markers <p> in HTML. This is standard HTML for most applications. On most Web
browsers, this separates paragraphs of text with a bit of extra white space. This option is selected by
default.
as poetry: if this option is selected, paragraph breaks (carriage returns) in text are exported as break
markers <br> in HTML. This can be useful if you are using line breaks to separate lines—as in poetry,
or lists of data—that should not be separated by extra white space when converted to Web format.
To export a document to HTML
From anywhere,
Save the document. This is a good idea before any major change, or before using any
powerful tool.
Choose Document Preferences... from the Edit menu (⌘-8)
In the Preferences dialog,
Select the HTML tab

Set the HTML export preferences, as described in the previous section
Click OK to dismiss the preferences dialog
Then, from anywhere,
Choose Export as HTML... from the File menu

In the standard file dialog, choose which folder should hold all the new HTML files and the
new folders holding them. (You may want to create a new, empty, folder to hold the files.)
Press Choose
Recall that when you export your document into HTML, Tinderbox creates many HTML files and also
many new folders to put them in. For instance, if the note “Big Cats” contains the notes “Lions”,
“Tigers”, and “Jaguars”, Tinderbox will create the HTML file BigCats, as well as the new folder
BigCats. The folder BigCats will contain the HTML files Lions.html, Tigers.html, and Jaguars.html.
Attributes for HTML Export

The section on Export Options and earlier in this chapter describe setting these attributes via the
controls on the HTML view window. These attributes may also be set by actions and rules, Stamps,
Quickstamp, etc.
HTMLDontExport
Boolean attribute. If true, the note won't be exported when other notes in the same document are
exported to HTML. No aliases of this note will be exported. If other notes înclude this note, nothing
will be added.
103 of 178
Tinderbox v5 Manual
HTMLExportChildren
Boolean attribute. If false, the children of the note will not be exported upon export to HTML.
Remember that if this attribute is false, Tinderbox never even examines the child notes when
exporting to HTML. So individual child notes may have HTMLDontExport set either true or false, and
will not be exported in either case.
The easiest way to set this attribute is with the Export children as pages checkbox on the HTML view
window for the note.
HTMLExportExtension
Text attribute. The extension added to the end of the HTML file created for this note. Defaults to .html.
The easiest way to set this attribute is with the File extension text field on the HTML view window for
the note.
HTMLExportFileName
Text attribute. The name of the HTML file created for this note.
In most cases this field is blank, and Tinderbox automatically creates a name for the HTML file from
the note name. For a particular note this may not be what you want: perhaps you’d rather have a
more legible name, or perhaps other sites refer to a particular file. In that case you can use this
attribute to tell Tinderbox what file name to use instead.
The easiest way to set this attribute is with the File name text field on the HTML view window for the
note.
HTMLExportTemplate
Filename attribute. The template that should be used to export this note to HTML. If left blank, the
note is exported with the default HTML template, as set in Preferences.
The easiest way to set this attribute is with the Template popup menu on the HTML view window for
the note.
Exporting Exactly What You Want

Let’s say you’ve exported a note to HTML, and the Web page isn't exactly what you want. What do
you fix?
If there’s a mistake in the content—you see that you wrote "Thoreua" where you want
"Thoreau".
You could edit the Web page in a text editor or Web page editor and fix the mistake—change
"Thoreua" to "Thoreau". But the original Tinderbox note will still have the mistake, and if you export it
again, the mistake will reappear in the Web page.
Or, you could fix the mistake in the Tinderbox note, and then export it again to HTML. This gets you a
new Web page, with the mistake fixed, and eliminates it once and for all.
104 of 178
Tinderbox v5 Manual
If it doesn’t look the way you want—you look at the Web page, and decide that you want more
cellpadding in the table, or a different background color.
Remember that you can select text in an HTML view window: press and hold the option key while
you select the text. This lets you copy the text, in case you want to inspect or test it elsewhere.
Again, you could edit the Web page in a text editor or Web page editor and make the change. But if
you use the template you used here for more than one Tinderbox note, you will have to make this
change many times—once for each Web page created using this template.
A better idea is to use that text editor or Web page editor to edit the template that was used to create
this Web page. In the template, change the cellpadding or background color or make whatever
change you’ve decided on.
Then, export the note (or notes) again, using the modified HTML template. The change you made to
the template will be reflected in all the new HTML files created with it.
105 of 178
Tinderbox v5 Manual
HTML Templates
Export templates are a simple but enormously flexible way to export your data in exactly the form you
want. The template supplies the structure of the exported file, with placeholders marking where
Tinderbox is to add information from your document.
An HTML export template need not be complicated. Here is a very simple template for an HTML Web
page:
<html>

<head><title>^title^</title></head>

<body>

^text^
</body>
</html>
Template Essentials
Tinderbox offers a great variety of export template codes, giving you immense flexibility. You can
export Tinderbox notes as HTML, XML, or in many other formats. You can easily control nearly every
aspect of the process, making Tinderbox a convenient front end to a host of systems and services.
The full array of export codes are described in Appendix 4. But most of these codes are seldom used.
In this chapter, we will discuss the much smaller number of export codes that you are likely to use
frequently.
Placeholders
Tinderbox placeholders begin with a caret (^), entered by typing Shift+6.
^title^
^value($Color)^
The placeholder continues from the opening caret and ends with white space, an optional closing
caret, or a closing parenthesis. Although the closing caret is optional, it is best to include one unless
familiar with exporting - the closing caret saves Tinderbox having to make assumptions about where
a particular code ends.
A placeholder ends with a closing parenthesis, white space, or a caret; the closing
caret is only required if the placeholder directly abuts a printing character.
Most placeholders refer to the note that is currently being exported, but some placeholders can
extract information from different notes.
^title^ : the name of this note
^title(this)^ : equivalent to ^title
^title(parent)^ : the title of this note's container
106 of 178
Tinderbox v5 Manual
^title(/tasks/132)^ : the title of the note "132" inside the container "tasks"
Placeholders that refer to other notes can refer to them in several ways:
The name of the note

The path to the note — especially useful if several notes might share the same name— such as
/Configuration/PriceList
A designator, such as "parent" or "nextSibling"
Paths
Export templates allow you to identify notes by relative or absolute paths. For example:
/news is the top-level note named "news"
/news/local is the note named "local", inside the top-level note "news"
The file name "." stands for this note, and ".." stands for the parent of this. Thus,
../Chicago is the note named "Chicago" that is a sibling of this note
../.. is the grandparent of this note
If a path begins with "/", the path begins at the top level of the document. If it does not begin with "/",
it begins inside this.
Referring to other notes

A variety of designator keywords designate notes by their relationship to this note rather than by their
name or path. The full set of keywords is listed in Appendix 4.
The most common and useful designators include:
this - the note being exported immediately
current - the note Tinderbox is currently exporting. If a note includes other notes, this is the most
immediate note, and current is the note that ultimately includes it.
next - the note that follows this note in outline order
previous - the note that precedes this note in outline order
prevSibling - the next older sibling of the this note
nextSibling - the next younger sibling of the this note
parent - the parent of this note
child - the first child of this note
lastChild - the last child of this note
Content codes
To export the title of a note, we simply include the placeholder
^title^
^title(object)^
For example, we might want to show the title and the parent's title:
<h2> ^title(parent)^ : ^title(this)^ </h2>
Similarly, we can use ^text^ to convert a note’s text into HTML and insert it into our page.
107 of 178
Tinderbox v5 Manual
Similarly, we can use ^text^ to convert a note’s text into HTML and insert it into our page.
^text^
^text(note)^
^text(note,max_words)^
While the note’s text and title are most likely to be of interest, we can export any attribute.
^value($attribute)^
gets the value of any attribute you specify, for this note.
^value($attribute(parent))^
gets the value of any attribute of this note’s parent.
Older templates used ^get(attribute)^ and ^getFor(parent,attribute)^, and these
obsolete forms continue to work. Note that in ^value^ attribute names take a $-prefix, whereas this is
not used in most other export codes.
^title^
^get(Name)^
^value($Name)^
But ^value^ also evaluates expressions, permitting more complex forms:
Total Price: ^value($Price*$Quantity)^
Template codes in text

While export template codes are most often found in export templates, you may also type them
directly into your note’s text. For example, if the text reads
This note, ^value($Name)^, contains ^value($WordCount)^ words
the exported HTML for a particular note might read:
<p>This note, Objections To Operation TORCH, contains 731
words.</p>
We can also include information from other notes within the text.
înclude(object)^
will format another note, using its own export template, and insert the results into our page.
Alternatively, we might specify a special template
înclude(object,summaryTemplate)^
Or, we can simply include some other note’s text:
Please keep in mind the following warnings:
^text(/warnings/fragile)^
^text(/warnings/inflammable)^
^text(warnings/heady)^
înclude^ and the related code ^children^ can help you to assemble complex pages and
weblogs, pulling information from dozens or hundreds of notes into a single layout. These techniques
are discussed in a chapter on Complex Pages.
Macros
108 of 178
Tinderbox v5 Manual
Macros provide a convenient shorthand, helping you save typing and making your work easier to
keep up-to-date.
^do(disclaimer, show, contact, phone)^
might expand into a lengthy, customized passage that might need to appear in many notes, and that
would be tedious to retype.
<h3>DISCLAIMER</h3>
<p>These notes regard production plans for show, a projected
production of Imaginary Studios, Inc. All plans are preliminary and
strictly confidential. Writers are cautioned that all details are
subject to change, and that final budgets are not approved until signed
by contact. If you have questions, please call contact at phone. </p>
Note that, if the legal department wants to change the wording of the disclaimer, we need only
change the macro. If we had typed the disclaimer in several places, we would need to search and
correct each occurrence. A macro is a text pattern that, when invoked, expands into a larger
element.
^do(...)^
To define a macro, use the Macros pane of the Attributes window (⌘-2). For example:
Name: dot
Value: <img src="anImage.gif" height="16" width="16">.
Defines a macro that will replace ^do(dot)^ with the specified 16-pixel image.
The ^do^ command may take additional arguments that are passed to the macro. Wherever the
macro contains the substring $1, that substring will be replaced by the first additional argument. The
substring $2 will be replaced by the second additional argument.
If a paragraph consists entirely of a macro, paragraph markup is not applied. This is useful, for
instance, as it makes it easy to use a macro to insert an element like an image (<img>) which
requires no enclosing paragraph.
Conditional Export
Occasionally, you may want to export some information for some notes, but not for others. Of course,
you could use two different templates. But if the changes are small, you can use îf to vary the
behavior of the template depending on the contents of the note.
îf( condition )^ ...... êndif^
îf (condition)^ ... êlse^ ..... êndif^
Here, condition may be any expression. For example
îf( $Created>"today-1 week" )^NEW!êndif^
will export the phrase “NEW!” in notes less than a week old.
if condition is true, Tinderbox exports everything from the îf()^ statement to the êlse^ or the
êndif^.
Be careful to ensure that every îf()^ is balanced by a corresponding êndif^.
Conditional logic can greatly reduce the number of templates you need, at the cost of increasing
their complexity. Conversely, if your templates are becoming a tangle of îfs, consider breaking them
into several separate templates.
109 of 178
Tinderbox v5 Manual
Group Codes
Most HTML markup elements concern an individual note, either this or a designated note. Some
element consolidate information from a group of notes.
For example
êvery(children,$Urgent)^
is true if each child of this note is has a true value for its Urgent attribute.
The group designators include
children - all immediate children of this note

descendants - all notes descended from this note
sibling - all siblings of this note
ancestor - all notes from which this note is descended
all - all notes in the document
êvery(group,attribute)^
êvery(group,attribute,value)^
true if every member of the group (such as every child) is true (if two arguments are supplied) or if
every member of the group has a specific value for that argument (if three arguments are supplied).
Always true if there are no examples of that group
âny(group,attribute)^
âny(group,attribute,value)^
true if any member of the group is true (two arguments) or if any member of the group has an attribute
with the specific value (three arguments). Always false if there are no members of the group.
^count(group)^
counts the number of elements in the group
^min(group,attribute[,precision])^
the smallest value in the group.
^max(group,attribute[,precision])^
the largest element in the group
^sum(group,attribute[,precision])^
computes the sum of all elements in the group.
^mean(group,attribute[,precision])^
computes the arithmetic average of the group
Several group codes allow an optional argument, precision; if supplied, it indicates the number of
decimal places desired in the result.
Note that most group codes can also be expressed using ^value^. For instance:
^value(any(children,$IsOverdue))^
An Example Template
110 of 178
Tinderbox v5 Manual
<html>

<head><title>^title^</title></head>
<body bgcolor="#FFFFFF">

^text^


îf(ûrl(this)^ != ûrl(cover)^)^

<hr height="3" width="75%" align="center">

<a href="ûrl(cover)^">
<img src="^root^homebut.gif" alt="Home" vspace="2"></a>

êndif


îf(êxists(childLinks)^)^


<h5>Children:</h5> ^childLinks("<ol>", "<li>", "</li>", "</ol>")^
êndif

îf(êxists(basicLinks)^)^

^basicLinks(
<table border="2" cellspacing="0" cellpadding="3" width="100%">
<caption><strong>Related pages:</strong></caption>
<tr>,
<td>,
</td>,
</tr></table>)^
êndif^


<cite>This page was last modified on ^value(format($Modified,"*"))^,
by ^value($Creator)^,
and was exported to HTML on ^value(format(date("today"),"*")^
using ^version^</cite>
</body>
111 of 178
Tinderbox v5 Manual
</html>
112 of 178
Tinderbox v5 Manual
Complex Pages
Tinderbox has a very powerful facility for building Web pages built out of many notes. This is useful
because even a simple personal page might have links to archives on the left edge, recent articles
on the right, a headline at the top, and daily updates in the center.
Tinderbox could build such a page by gathering each article (each one a separate note) and sorting
them by date. If you decide that sorting by title would be more useful, it's an easy change. If you need
to revise the entry for one article, just open that note. By keeping notes separate from layout,
Tinderbox helps focus your attention and keeps things simple.
This feature, particularly when combined with the power of agents, is a very powerful way to create
dynamic Web content. Tinderbox agents can build lists automatically, scanning your document
continuously for notes that fit criteria of interest. One agent might look for new notes, another might
look for anything marked Urgent, a third agent might search for old notes that have not yet been
acted upon. All these lists could then appear in separate sections of a project page or dashboard.
To build a web page from many notes, you'll create or use HTML export templates which pull lots of
notes together into a page Web page, and control exactly how the pieces fit together.
^children^
This ^children^ code tells Tinderbox to include the children of the current note or agent in the
current Web page. A template is applied to each child before it is added to the page. If a template is
specified in the markup
^children(myTemplate)^
that template is used for every child. If no template is specified
^children^
each child note's $HTMLExportTemplate is used.
Using ^children^ in an agent’s export template is a very powerful way to create dynamic Web
content. An agent’s children are aliases of all the notes that satisfy its criteria. An agent could gather
all the notes that have been added since a certain date, or that belong to a certain category, and use
^children to export all of them as a list .
^children^ ^children(template)^ ^children(template, count)^
The argument template should designate a template note, a built-in template, or an external export
template file. This this will be applied to each child in turn, regardless of the child's own template.
If supplied, a second argument, count, specifies the maximum number of children to be exported.
Tip:the template file used by ^children^ will be very different from a template file
intended to export a single note. Since the children are being included in a single Web
page, the children’s template file should not include opening and closing codes such
as <html>, <head>, and <body>. The children’s template is often very
brief, containing only the code to make the desired elements from each child appear
correctly in the context of the overall Web page.
In older versions of Tinderbox, ^children^ was called ^justChildren^. Whilst the old name continues
to function, the new name is clearer and the old form is deprecated. A new code ^descendants^,
replaces the previous function of ^children^.
înclude^
113 of 178
Tinderbox v5 Manual
The înclude^ template code includes a specified note in the Web page for the current note.
înclude^ adds a single note, but that note's export template may include other notes as well. It's
common to înclude^ several different notes in the same template.
Be careful not to înclude^ a note in itself!
înclude( note_name [, template])^
From v5.9.2, înclude^ offers the alternative of including the output of a group of notes rather than a
single note. For this, pass in a list of Paths, or do this dynamically via find(), collect() or collect_if() or
such operators.
The argument note_name designates which note is to be included. The optional argument template
should be the name of an HTML template file.
If you do not specify a template, the note is formatted using the HTML export template assigned to
the note in its $HTMLExportTemplate attribute.
^randomChildOf^
This template code allows you to include a randomly selected child of a specified note. The syntax is
very similar to the syntax for înclude^ and ^children^:
^randomChildOf( note[, template])^
The argument note designates the note whose random child is to be exported. The optional
argument template should be the name of an HTML template file; if no template is specified, the
note’s own template is used.
Dates and Times

Tinderbox offers great flexibility in date formatting.
To export a date attribute for a note:
^format( attribute, format)^ ^format( attribute(which), format)^
For example, ^format( $Created, "L")^ exports the time this note was created in the
system’s local date format.
Format strings let you present dates and times in exactly the way you wish. They can appear in any
language or style. The complete repertoire of format strings is described in Appendix 5: some
common formats include the following:
Format strings
L: local time, in long format, using the system format settings (example: Tuesday, April 29, 2003.)
l: local time, in short format, using the system format settings (example: 4-29-03)
d: day of the month (example: 29)
D: formats date 01-31, with leading zero
m: number of month (example: 4)
M: abbreviation of month (example: Apr)
MM: name of month (example:April) w: abbreviation of weekday (example: Tue)
M0: formats month numerically 01-12, with leading 0
W: name of weekday (example: Tuesday)
114 of 178
Tinderbox v5 Manual
y: year (example: 2003)

t: time, in local format (example: 2:32 pm)
h: hour of the day on a 24-hour clock (example: 13:39)
H: hour of the day on a 12-hour clock (example: 1:39)
mm: minute of the hour (example:05 for five minutes after the hour)
s: second
p: AM or PM
*: date/time in RFC 822 format (example: Thu, 18 Feb 2004 19:12:00 0500)
=: date in ISO 8601 format (example: 2004-02-18)
Tinderbox also accepts expressions such as today, yesterday, tomorrow, yesterday + 1 week,
tomorrow + 1 year, and never (later than any other date).
Comparing dates
Tinderbox date attributes always record both date and time.

Because agents often want to locate notes pertaining to a specific day, two dates are considered
equal if they occur on the same calendar day. The other comparison operators, such as > and <,
consider both date and time.
Dates and attributes
Tinderbox automatically records two dates as read-only attributes: $Created (the date and time when
a note was first made), and $Modified (the date and time when the note was most recently changed).
Notes that use AutoFetch notes also record $LastFetched. You can create your own date attributes,
too; for example, $Published might be the date when a note was first added to the public version of
your Web site.
115 of 178
Tinderbox v5 Manual
Working with Weblogs
Posting to Remote Weblogs

Tinderbox supports posting to Blogger, MovableType, and Radio Userland weblogs. This will be easy
after the initial setup, which you will only have to do once:
To set up remote blogging
Select Document Preferences from the Edit menu

Select the Weblogs pane
In the Server field, enter the address with which Tinderbox communicates with the remote
weblog:
Blogger: http://api.blogger.com/api/RPC2
Radio Userland: http://127.0.0.1:5335/RPC2
Movable Type:the same address as your weblog editing url, substituting 'mt-
xmlrpc.cgi' for the usual 'mt.cgi'
In the User and Password fields, enter the username and password associated with your
blog
In the Weblog ID field, enter:
Blogger: the weblog ID number of your weblog, found by entering your weblog and
looking in the Address bar for the number at the end of the URL.
Movable Type, typically: 1
Radio Userland: home
Select your remote weblog from the Weblog Type menu
Click OK
Tip: Radio Userland users must enable remote Internet access in Radio Userland
Preferences, and must enable the Blogger API. These may be off in default
installations.
To post to remote weblogs
Select a note to post to your weblog

Choose Post to Weblog from the Note menu
To download the most recent posts
Select Get Recent Weblog Posts from the Note menu
116 of 178
Tinderbox v5 Manual
If notes for these posts already exist, their contents will be updated to match the weblog.
Warning: you will lose any changes you have made to these notes. New notes will be
made for any weblog posts for which corresponding notes do not currently exist. (If
the document already contains notes posted to the weblog, the newly created notes
will appear in the same container. Otherwise, the newly-created notes will appear at the
top level of the document.)
Pinging
Tinderbox can "ping" Web services such as and weblogs.com from Tinderbox to announce that your
site has been updated., This helps notify other systems of the change. If you upload your site by FTP,
you should ping after uploading revised files.
To enable pinging
Select Document Preferences from the Edit menu

Click the Ping pane
You may also enter information in the Server and Method text boxes under custom ping
Enter the title and URL of your weblog in the Title and URL fields
Click OK
To ping after updating your weblog
Choose Ping Now from the Edit menu or press ^-⌘-P
117 of 178
Tinderbox v5 Manual
Exporting text
To export the text of all or some of the notes in your Tinderbox document,
Select a note
Choose New Nakakoji View from the View menu (⌘⌥N)
Select a text export template, to describe how the text should be exported
Choose how much of the document should be exported—which note or notes, or the entire
document
Export the text.
Text Export Templates
Text export templates are much like HTML templates; they describe the framework for exporting a
note and provide placeholders for information each note supplies. Most text export templates are
very simple.
For each exported note, Tinderbox copies the text export template to the output file. Placeholders are
replaced with information from the note. For example:
^title^
is replaced by the note’s title,
^text^
by the note’s text, and
^value($theAttribute)^
by the value of theAttribute. Most of the placeholders described in HTML Export may also be used in
text export, but these are less often necessary—or inappropriate.
There is seldom need to use înclude^ or ^children^ in text export, since text export provides
implicitly exports all the descendants of a note or the entire document.
Nakakoji View
Nakakoji views are named for Prof. Kumiyo Nakakoji, who, with Yasushiro Yamamoto, was the first to
implement a continuous text view of all the text in a hypertext.
A Nakakoji view window shows you how the text in the selected note (or document, or portion of the
document) would be exported with the chosen text export template.
In this window you can:
Choose which text export template to use;

Select how much of the document to export;
Export the text
You can have many Nakakoji view windows open at once.
118 of 178
Tinderbox v5 Manual
The radio buttons at the left of a Nakakoji view window choose how much of the document to export
(and show in the window):
Entire document:
[Name of note] and contents: export the text in the selected note and its descendants—the
notes it contains, the notes they contain, and so on.
Selected notes: export the text in the currently-selected note or notes.
Path: export the text in the selected note, and all notes linked to it by a chain of links of the link
type you choose. The popup menu lists all the link types used in the document.
Which template to use
The popup menu at the top center of the window lets you choose which template should be used
when exporting to text. Choose a file name from the popup menu, which lists all the export template
notes, the built-in templates, and the files in the document’s text export templates folder.
The same text export template is applied to all exported notes.
To Export: press the Export button to export the text of the note (or notes or entire document).
119 of 178
Tinderbox v5 Manual
Preferences
Preferences control aspects of how documents appear and Tinderbox behaves on your computer.
Document Preferences apply only to the document that is open. Choose Document
Preferences... from the Edit menu or press ⌘-8
Tinderbox Preferences apply to newly-created documents. Choose Tinderbox Preferences...
from the Edit menu.
Tinderbox Preferences also controls Tinderbox’s behavior when no documents are open — for
example, whether Tinderbox shows the introductory screen or creates a new document at startup.
Preference Panes
General: Enter your username and choose whether to open new notes immediately, have the toolbar
be initially visible, enable auto-save and auto-backup of documents, re-open the last used
document, show dialog at startup.
Text: Alter margins, paragraph spacing, fonts, text size and alignment, text color, background color,
width, and height. Choose whether to magnify fonts, remember window positions, keep windows
open, magnify pictures, frame text links, or have colored text links (and if so, choose the color of text
links, visited links, and active links).
Title: Choose whether to show titles in text and explorer views. Select background and text color for
the titles, font, size, and alignment.
Maps: These preferences control maps, outlines, and other views. Choose whether to show links,
used curved links, and allow enactment (a short "zoom" animation that shows you what's happening
when you move down into, or up out of, a container). Select the background color and/or apply a
background pattern, and the font and size of note labels; darken the colors used for drawing outline
text; control whether edit-in-place of new notes in major views is enabled.
HTML: Enter your URL (web server) and select your HTML template. Choose whether to export text
links, basic links, hierarchical links, and link types. Choose a format for link images and which
application to open/edit files with. Export paragraphs as prose (paragraph breaks) or poetry (line
breaks). Choose whether exported names end with .html, .htm, or neither. Select the font and font
size used for the HTML View window.
Text Export: Choose your text export template and preferred editor; sets the font preference for text
export display.
Warnings: Choose whether to show warnings about duplicate names and before changing default
values. run linked AppleScripts automatically. Get a warning before deleting notes either always,
never, or only if the note has children.
Ping: (Document Preferences only): Enter the title and URL of your weblog to enable the pinging of
weblogs.com or another server. You may change the default Server and Method, which are set up for
the most popular server as of this writing, or click the Restore Factory Defaults button to return to the
original values.
Weblogs: (Document Preferences only): Set up Tinderbox to post to remote weblogs. User and
Password are those associated with your blog. Other settings (server, WeblogID, Weblog type) will
depend on your remote weblog; see the Web Pages Built of Many Notes chapter for more detail on
remote weblogs.
120 of 178
Tinderbox v5 Manual
Email: If you wish this Tinderbox document to receive email from its own mailbox, enter the login
information for the mail account here.
121 of 178
Tinderbox v5 Manual
Tips For Experienced Tinderbox Users

Tinderbox has changed a lot over the years. So has your computer. If you’ve been using Tinderbox for
a long time, some of your preference settings might be worth revisiting.
To set preferences for an existing document, open the document and choose Document
Preferences from the Edit menu. To set preferences for new documents you’ll create in the future,
choose Tinderbox Preferences from the File menu.
Some preferences you’ll want to think about include:
Text Pane
Font (especially if your preference is still set to Geneva)
Font size (try 14 or 16pt)
Width and Height (modern screens are bigger)
Maps Pane
Turn on In-Place Editing
Turn on Charts and Outlines Have Darker Colors
HTML Export Pane
Text Export Pane
122 of 178
Tinderbox v5 Manual
Tinderbox Resources
The Tinderbox User’s Manual will be found in the Help menu.

The Tinderbox Way, by Mark Bernstein, takes a close look at Tinderbox and its underlying
ideas, exploring not just the program's mechanics but also its design and its spirit.
The Tinderbox Forum is an active community for discussing Tinderbox ideas and applications.
The Tinderbox Cookbook provides dozens of examples of Tinderbox agent queries and actions.
The Tinderbox wiki also provides lots of terrific information.
aTbRef — A Tinderbox Reference — is a user-supported reference guide to Tinderbox,
available both on the Web and as a Tinderbox file.
123 of 178
Tinderbox v5 Manual
To Contact Us
Eastgate Systems, Inc.
134 Main Street
Watertown, MA 02472 USA
phone:800-562-1638 +1 617-924-9044
fax:+1 617-924-9051
Tinderbox Forum: http://www.eastgate.com/Tinderbox/forum/
Tinderbox wiki: http://www.eastgate.com/wiki2/
e-mail: info@eastgate.com
Web: www.eastgate.com
124 of 178
Tinderbox v5 Manual
Publishing Notes
Acknowledgements
Tinderbox™ software copyright © 2002-2009 by Eastgate Systems, Inc. All Rights Reserved.
Documentation copyright © 2009 by Eastgate Systems, Inc. All Rights Reserved.
The information in this document is subject to change without notice. Eastgate Systems, Inc., makes
no warranty of any kind regarding this material and assumes no responsibility for errors that may
appear in this document.
Tinderbox™ is a trademark of Eastgate Systems, Inc. Civilized Software is a service mark of
Eastgate Systems, Inc.
Special Thanks for documentation help to: Eric A. Cohen, Jen Muehlbauer, Mark Anderson, and Barry
Webster
Microsoft®, Windows®, Windows NT®, and Internet Explorer® are registered trademarks of
Microsoft Corporation. IBM® is a registered trademark of International Business Machines
Corporation. Apple is a registered service mark, MacintoshTM and AppleScriptTM are trademarks,
and QuickTime® is a registered trademark of Apple Computer, Inc. UNIX® is a registered trademark
of The Open Group.
Other product names mentioned in this document may be trademarks or registered trademarks of
their respective owners. Product names are used for identification only, with no intent to infringe.
Mention of third-party products is for informational purposes only and constitutes neither an
endorsement nor a recommendation. Eastgate Systems, Inc., assumes no responsibility with respect
to the performance or use of these products.
Tinderbox (TM) Software License Agreement
Tinderbox™ Software License Agreement

Eastgate Systems, Inc., grants you a non-exclusive license to use this copy of the program on the
following terms:
YOU MAY:
I) Use the program on any one computer;
II) Install the program on a second computer you use provided all copies of the program are used
directly and exclusively by yourself.
III) allow anyone else to use the program, so long as there is never more than one user per licensed
program at any time;
IV) make copies of the program in machine-readable form, but only for archival purposes, and only so
long as all proprietary notices are reproduced on each copy.
YOU MAY NOT:
I) Modify, translate, reverse engineer, decompile, disassemble, create derivative works based upon,
or copy (save for archival purposes) the program or the accompanying documentation;
II) rent, transfer or grant any rights in the program or accompanying documentation in any form to
anyone else without the prior written consent of Eastgate Systems, Inc.;
III) remove any proprietary notices, labels, or marks on the program and accompanying
125 of 178
Tinderbox v5 Manual
documentation;
IV) use this program, or permit this program to be used, on more than one computer at any one time.
Non-compliance with any of the above restrictions will terminate this license.
This license is not a sale. Title and copyrights to the program and accompanying documentation and
any copy remain with Eastgate Systems, Inc.
Household License:
You and up to four (4) other persons who occupy the same household may use the program on their
respective computers. "Household" means a person or persons who share the same home,
apartment, condominium or dormitory suite, but shall also extend to student household members
who are primary residents of the household but who reside at a separate on-campus location.
Limited Warranty and Disclaimer
Limited Warranty and Disclaimer

This product and associated files are provided without warranty of any kind, express or implied,
including without limitation the warranties that it is free of defects, virus free, able to operate on an
uninterrupted basis, merchantable, fit for a particular purpose, or non-infringing. The entire risk as to
the quality and performance of the product is borne by licensee. Should the product prove defective
in any respect, licensee and not licensor assumes the entire cost of any service and repair.
This disclaimer of warranty constitutes an essential part of this agreement. No use of the product is
authorized except under this disclaimer.
The liability of Eastgate Systems, Inc.,shall be limited to the replacement of the product or the refund
of the purchase price. This is the entire liability of Eastgate Systems, Inc., and your exclusive remedy.
Save for the above express limited warranty, Eastgate Systems, Inc., makes no warranties or
conditions express, implied, statutory or in any communication with you.
This agreement is the entire agreement. If any provision of this agreement is held invalid, the
remainder of this agreement shall continue in full force and effect.
Eastgate Systems Inc.
134 Main Street
WatertownMA 02472 USA
Tel: (800) 562-1638 (617) 924-9051
Fax: (617) 924-9051
Email: info@eastgate.com
Web: http://www.eastgate.com/
126 of 178
Tinderbox v5 Manual
Appendix 1: Attributes
This appendix lists Tinderbox’s built-in System attributes and describes their program semantics —
that is, their meaning and use within Tinderbox.
Attribute names are case-sensitive. This 'Agentaction' will not be interpreted by Tinderbox as a
reference to the AgentAction attribute. By convention, system attributes start with capitals, are
intercapitalized and capitialize acronyms: 'Border', 'ShadowBlur', 'URL', 'HTMLDontExport'.
In Tinderbox code, an attribute' value is referenced by placing a '$' before the filename. $Name gives
the value of attributed 'Name'. When making offset references to attributes via designators or paths,
there must be no space between the attribute name and the parentheses, $Name("parent") - this is
discussed further in Appendix 3 'Attribute References'.
Agent
AgentAction (action) - describes the action the agent performs, for instance, Color=red
AgentCaseSensitive (boolean) - if true, agent searches are case-sensitive
AgentPriority (number) - the more often the agent runs
AgentQuery (string) - the criterion for which the agent searches
Appearance
Badge (string) - the name of the badge displayed for this note.
Border (number) - the size of a border around adornments and notes. If Border is zero, no border is
drawn.
BorderBevel (string) - if "raised" the border is bevelled; if "normal" the border is a simple outline
(adornments) or bevelled (notes). If "plain" it is a simple outline; if "none" the border is not drawn.
BorderColor (color) - specifies the color of the adornment’s border. The special keyword
"automatic", draws an opaque border in the adornment's natural color. Adornments are otherwise
translucent.
BorderDash (number) - The length of a dashes for dashed borders; a value of 0, the default, gives a
solid line border.
Color (color) - color of notes view.
Color2 (color) - a second color used by the Pattern attribute (see below). In the Inspector, this is
called the “Accent Color”
Opacity (number) - the opacity of the note. Normal opacity is 100; translucent notes have an opacity
of 50.
Pattern (string) - Map view only, fills the face of the note or adornment. Values include "lines",
"gradient", "radial", "diagonal", "cylinder", "bar()", "vbar()"; also - for containers only - values "plot",
"xyplot", and "bargraph".
PlotColor (color) - color used for drawing the plot(), xyplot() and bargraph() patterns for containers
and agents.
Shadow (boolean) – turns drop shadows on or off
ShadowBlur (number) – in pixels, controls the blurriness of drop shadows.
ShadowColor (color) - controls the color of drop shadows
127 of 178
Tinderbox v5 Manual
ShadowDistance (number) – in pixels, the offset distance between the note and its shadow.
Shape (string) – the name of the note's shape. The default shape is a rectangle; other shapes include
"oval", lozenge", "diamond", "left tag". "right tag", "bubble", "cloud", "banner" and "leaf".
Events
Attributes in this category are not presently used by Tinderbox, but are provided for convenience and
to facilitate exchange among Tinderbox users.
DueDate (date) - a date, provided for the user’s convenience
EndDate (date) - a date, provided for the user’s convenience
DateDate (date) - a date, provided for the user’s convenience
TimelineBand (number) - the band number of a timeline view to which an event belongs (numbers
from zero)
TimelineBandLabelColor (color) - color used for drawing band labels
TimelineBandLabelOpacity (number) - opacity value for drawing band labels
TimelineBandLabels (list) - text labels to use for bands in the Timeline view of that container.
TimelineColor (color) - the color used to color every other band of a Timeline view
TimelineEnd (date) -events after this date are listed as "out of range"
TimeLineGridColor (color) - the color used for guidelines in a Timeline view
TimelineMarker (boolean) - controls whether lines from events to the scale are drawn for the
selected event or all events
TimelineScaleColor (color) - the primary color for the Timeline's time scale bar
TimelineScaleColor2 (color) - the secondary color for the Timeline's time scale bar
TimelineStart (date) -events before this date are listed as "out of range"
General
Checked (boolean) - checkmark status from Outline view

ChildCount (number, read-only) - how many children the note has.
CleanupAction (string) - the type of cleanup to be applied to agent maps
Container (string) - the path to the note that contains this note. Setting the value of Container will
move the note to a new container.
Created (date, read-only) - time and date the note was created.
Creator (string, read-only) - user who created the note.
DescendantCount (number, read-only) - returns the number of descendants of a container.
DisplayExpression (action) - an expression used to compute the label of the note in Tinderbox
views. If DisplayExpression is empty, the value of Name is used as the label of the note.
DisplayExpressionDisabled (boolean) - if true, the current note's DisplayExpression is not used
DisplayName (string, read-only) the displayed name computed by evaluating $DisplayExpression.
File (file) - identifies a file associated with this note, typically by having been dragged onto the File
button.
128 of 178
Tinderbox v5 Manual
ID (number, read-only) - the unique ID of a note or other object

InboundLinkCount (number, read-only) - returns the number of inbound basic links and text links.
Includes prototype links.
IsAdornment (boolean, read-only) - true if the object is an adornment
IsAlias (boolean, read-only) - true f the object is an alias
IsPrototype (boolean) - whether this note is a prototype for other notes.
Modified (date, read-only) - time and date the note was last modified.
Name (string) - name of the note.
OnAdd (action) - an action (or list of actions, separated by semicolons) to be applied to notes when
they are added to this container.
OutboundLinkCount (number, read-only) - returns the number of outbound basic links and text links,
excluding Web links. Includes prototype links.
OutlineDepth (number, read-only) - the number of steps between a note and the document root ( top-
level notes have OutlineDepth=1; notes inside a container have OutlineDepth=2, etc.).
OutlineOrder (number, read-only) - lets agents compare the position of this note to the overall
document hierarchy.
Path (string, read-only) - the Tinderbox path to the note.
Private (boolean) - if true, omitted from Map and Outline view prototype popup lists.
Prototype (string) - the note used as a prototype for this note.
PrototypeBequeathsChildren (boolean) - if true, children of this prototype will be cloned in notes
that used it as their prototype.
ReadCount (number, read-only) – the number of times that this note’s text window has been opened
Rule (action) - describes the action the rule performs.
RuleDisabled (boolean) - if true the note's rule is not used.
SelectionCount (number, read-only) – the number of times that this note has been selected
SiblingOrder ( number, read-only) - the SiblingOrder of the first child in a container is 1, the next child
is 2, etc.
Subtitle ( string ) - Optional subtitle drawn on map icons (beneath the title).
WebLinkCount (number, read-only) - counts the number of web links.
HTML
HTMLBoldEnd (string) - the closing tag for bold passages.

HTMLBoldStart (string) - the opening tag for bold passages.
HTMLCloud1End (string) - the closing tag for a list of the most common words in a note, section, or
document.
HTMLCloud1Start (string) - the opening tag for a list of the most common words in a note, section,
or document
HTMLCloud2End, HTMLCloud2Start, HTMLCloud3End, HTMLCloud3Start, HTMLCloud4End,
HTMLCloud4Start, HTMLCloud5End, HTMLCloud5Start, operate as HTMLCloud1End and
HTMLCloud1Start above.
HTMLDontExport (boolean) - if true, doesn't export the note to HTML when you export the
129 of 178
Tinderbox v5 Manual
document.
HTMLEntities (boolean) - if true, translates non-ASCII characters like '&' and '¢' into HTML entities.
HTMLExportAfter (string) - what's exported immediately after everything else in the note's text.
HTMLExportBefore (string) - what's exported immediately before a note's opening paragraph
markup.
HTMLExportChildren (boolean) - if true, exports this note's children to HTML when you export the
document.
HTMLExportCommand (string) - Allows you to apply a program or script to each exported HTML file.
The exported file is piped to the standard input of the command line in HTMLExportCommand, and
the file is replaced by command line's standard output.
HTMLExportExtension (string) - the suffix that should be added to the filename for exported HTML
files.
HTMLExportFileName (string) - sets a specific name for a note's HTML file upon export to HTML. If
empty, Tinderbox automatically generates a file name based on the note's title.
HTMLExportFileNameSpace (string) - sets optional replacement character for characters deleted
from $Name when creating $HTMLExportFileName
HTMLExportTemplate (file) - the template that should be used when exporting this note to HTML.
HTMLFileNameLowerCase (boolean) - if true, HTML file names must be in lowercase.
HTMLFileNameMaxLength (number) - maximum length for HTML file names.
HTMLFirstParagraphEnd (string) - the closing tag for a paragraph.
HTMLFirstParagraphStart (string) - the opening tag for a paragraph.
HTMLImageEnd (string) - the end of an image tag.
HTMLImageStart (string) - the start of an image tag.
HTMLIndentedParagraphEnd (string): the closing tag for a paragraph that begins, in Tinderbox, with
a tab character.
HTMLIndentedParagraphStart (string): the opening tag for a paragraph that begins, in Tinderbox,
with a tab character.
HTMLItalicEnd (string) - the closing tag for an italic passage.
HTMLItalicStart (string) - the opening tag for an italic passage.
HTMLListEnd (string) - the closing tag of an unordered list.
HTMLListItemEnd (string) - the closing tag of a list item.
HTMLListItemStart (string) - the opening tag of a list item.
HTMLListStart (string) - the opening tag of an unordered list.
HTMLMarkupText (boolean) - if true, Tinderbox uses HTML markup when exporting text to HTML.
HTMLOrderedListEnd (string) - the closing tag of an ordered list.
HTMLOrderedListStart (string) - the opening tag of an ordered list.
HTMLOverwriteImages (boolean) - can instruct Tinderbox not to overwrite existing images when
exporting.
HTMLParagraphEnd (string) - the closing tag for a paragraph, other than the first paragraph.
HTMLParagraphStart (string) - the opening tag for a paragraph, other than the first paragraph.
HTMLQuoteHTML - (boolean) if true, Tinderbox includes examples of HTML in your text as HTML --
130 of 178
Tinderbox v5 Manual
i.e.,
will appear as
, not be translated into a paragraph break.
HTMLStrikeEnd (string) - the ending tag for an strike-through passage.
HTMLStrikeStart (string) - the opening tag for an strike-through passage.
HTMLUnderlineEnd (string) - the closing tag of underline formatting.
HTMLUnderlineStart (string) - the opening tag of underline formatting.
IsTemplate (boolean) - indicates that the note is intended for use as an HTML or Text Export
template.
Map
Fill (string) - a texture that is applied to the interior of the note. Values include wood, linen, steel, and
sandstone.
FillOpacity (number) - the percentage opacity of the object's Fill or Color/Color2 patterns or solid
color fills
Height (number) - with Width, relative size of notes in the Map view.
HoverExpression (action) - action code for the note's map icon Hover Expression
InteriorScale (number) - the factor by which notes inside a container are smaller than the notes
elsewhere in a map.
LeafBase (number) - the Leaf attributes control the geometry of the experimental Leaf note shape
LeafBend (number) - the Leaf attributes control the geometry of the experimental Leaf note shape
LeafDirection (boolean) - the Leaf attributes control the geometry of the experimental Leaf note
shape
LeafTip (number) - the Leaf attributes control the geometry of the experimental Leaf note shape
Lock (boolean) - if true, the item (adornment or note) can be selected but not repositioned.
MapBackgroundColor (color) - color of the background of the Map view.
MapBackgroundColor2 (color) - accent color of the background of the Map view.
MapBackgroundPattern (string) - pattern for the background of the Map view. Values include
"lines", "gradient", "radial", "diagonal", "cylinder".
MapBodyTextColor (color) - color of the note's body text when displayed in a map view's note icon.
MapBodyTextSize (number) –the font size of the text in which the body text is displayed in map view,
if the note is large enough for body text to be displayed. If MapBodyTextSize is zero, Tinderbox will
choose a suitable size.
MapScrollX, MapScrollY - the relative offset of the interior of the container, when viewed in the
parent’s map view
MapTextSize (number) - the relative size of names in the Map view. Mainly useful for adornments.
Expressed as an order of magnification, so changing this value from 100 to 200 would double the
size (make it 200% of the original).
NameAlignment (string) - whether the title of notes and adornments should be left-justified,
centered, or right-justified. Legal values include "left," "center," and "right".
NameBold (boolean) - if true, uses bold type for note names in maps, charts, and outlines.
131 of 178
Tinderbox v5 Manual
NameColor (color) - the color of the name of the note. If unchanged, a color will be chosen
automatically to contrast with the note color.
NameFont (string) - font of the name of a note in the Map view.
NameLeading (number) - amount of leading between the lines of a wrapped title.
NameStrike (boolean) - if true the object title is struck through.
Sticky (boolean) - if true, objects that overlap the adornment will move when the adornment is
moved.
SubtitleColor ( color ) - Sets the color of map subtitle text.
SubtitleOpacity ( number ) - Sets the opacity of map subtitle text.
SubtitleSize ( number ) - Sets the size of map subtitle text.
TableExpression (action) - an expression used to generate summary tables for containers and
agents. Columns are separated by the vertical bar character, "|".
TableHeading (string) – the column headings for the container or agent summary table. Columns are
separated by the vertical bar character, "|".
TitleHeight (number) - the height of the note’s title bar, if the note is an agent or container.
TitleHeight is expressed in map units, like Xpos and Height. If TitleHeight is zero, the height of the
title bar is calculated automatically.
TitleOpacity (number) - Sets the opacity of the $Name label.
Width (number) - with Height, relative size of notes in the Map and other views.
Xpos (number) - with Ypos, coordinates of the note in the Map view (in the same units as Width and
Height).
Ypos (number) - with Xpos, coordinates of the note in the Map view (in the same units as Width and
Height).
Net
AutoFetch (boolean) - if true, automatically fetches content from the web into this note.
AutoFetchCommand (string) - typically invokes an outside program, perhaps fetching some
information from the user's hard disk or network.
LastFetched (date, read-only) - when a note was last updated from the Web.
RawData (string) - contains a copy of AutoFetched information without ant further processing.
RSSChannelTemplate (file) - the template used for RSS channels when importing (AutoFetching) an
RSS feed.
RSSItemLimit (number) - how many items to import from other people's RSS feeds. The default
value, 0, means "import all items".
RSSItemTemplate (file) - the template used for RSS items when importing (AutoFetching) an RSS
feed.
URL (URL) - the URL used if this note fetches its content from the web.
ViewInBrowser (boolean) - if true, opening a text window indicated by the URL attribute on this note
will also open the Web page in your browser.
Outline
132 of 178
Tinderbox v5 Manual
MapPrototypeColor (color) - the color used to highlight prototypes in outline view.

OutlineBackgroundColor (color) - the color used for the background of that container's outline view
OutlineColorSwatch (boolean) - if true, outline views will display a small block reflecting the note's
color and border.
OutlineTextSize (string) - adjust the relative size of items, such as individual notes, in outline view.
Expressed as an order of magnification: changing the value from 100 to 200 doubles the size (makes
it 200% of the original).
Separator (boolean) - designates a note in an outline as a separator, a horizontal line in the outline
view that may be colored and titled like other notes. Separators appear normal in other views.
People
The attributes for People are string attributes provided for convenience and consistency. Some of
these attributes are automatically populated when importing vCards and address book pages.
AIM (string)
Address (string)
Email (string)
FullName (string)
Latitude (number)
Longitude (number)
Organization (string)
Telephone (string)
Twitter (string)
Simplenote
SimplenoteKey (number) - the simplenote UID for that item

SimplenoteModified (date) - simplenote's modification date for the object.
SimplenoteSync (number)
SimplenoteTags (set) - a list of that note's simplenote tag values
SimplenoteVersion (number)
Sorting
Sort (string) - the primary sort order for notes, such as alphabetically by title.
SortAlso (string) - if two notes have equal Sort values (like the same title), Tinderbox uses SortAlso as
a secondary sort key such as date of creation.
SortAlsoTransform (string) - sorts string attributes’ secondary sort order as “normal” (case-
sensitive), case-insensitive, or “last word” (sorts on the last word of the element).
SortBackward (boolean) if true, the notes will be sorted backwards, for example, Z before A.
SortBackwardAlso (boolean) if true, the notes' secondary sort order will also go in reverse, for
example, oldest notes first.
133 of 178
Tinderbox v5 Manual
SortTransform (string) - sorts string attributes as “normal” (case-sensitive), case-insensitive, or “last

word” (sorts on the last word of the element).
TextFormat
AutomaticIndent (boolean) - if true, text lists beginning with *, •, and # are automatically indented.
KeyAttributes (set) - separated by semicolons, the names of especially significant attribute-value
pairs that are displayed at the top of the text window.
KeyAttributeFont (string) - if supplied this font is used instead of $NameFont (from the Map group) to
draw the titles and values of the key attributes table in note text windows.
LeftMargin (number) - the size, in multiples of nine pixels, of the left margin.
LineSpacing (number) - adjusts the space between lines within a paragraph. Expressed as a
percentage; 100 is "standard" line space while 200 would be "double-spaced".
NoSpelling (boolean) - if true the note is excluded from continuous spellcheck.
ParagraphSpacing (number) - the amount of space (4, 6, 10, 12, 14, or 16 pt, or none) before and
after paragraphs.
RightMargin (number) - the size, in multiples of nine pixels, of the left margin.
ShowTitle (boolean) - if true, the title of the note is drawn prominently at the top of the text window.
Tabs (string) - a semi-colon delimited list of intervals between tab stops, measured in inches.
TextAlign (string) - the alignment of rext within a text windwo or Map icon
TextBackgroundColor (color) - the color of the background of a note's main text section.
TextColor (color) - the normal color for body text.
TextFont (string) –the default or “plain” font for this note. The default value of TextFont is set in the
text pane of Document Preferences. It is often useful to allow a class of related notes to inherit a
specific TextFont from their prototype, in order to give a PhoneMessage or GroceryList a distinctive
appearance.
TextFontSize (number) –the default text size for this note. The default value of TextFontSize is set in
the text pane of Document Preferences.
TextSidebar (boolean) - true if a note’s sidebar should be visible, and false if it should be hidden.
TitleBackgroundColor (color) - controls the background color of the title pane in text spaces;
defaults to Text settings in the Preferences dialog.
TitleFont (string) - the font for the title displayed if the ShowTitle attribute is set to true.
TitleForegroundColor (color) - controls the foreground color of the title pane in text spaces; defaults
to Text settings in the Preferences dialog.
Textual
ReadOnly (boolean) - if true, you can't modify the text in this note. It makes sense to set this to true
for notes that fetch their contents from the web.
Text (string) - the body text of the note.
TextExportTemplate (file) - which text export template the note uses.
TextLength (number) - the character length of the note's text WordCount (number, read-only) - the
number of words in the note's text.
134 of 178
Tinderbox v5 Manual
WordCount (number, read-only) - the number of words in the note's text.
Weblog
mt_allow_comments (boolean) - if true, MovableType weblogs will allow comments.

mt_allow_pings (boolean) - if true, MovableType weblogs allow pings to weblogs.com.
mt_convert_breaks (boolean) - if true, MovableType adds its own markup to discover paragraph
breaks.
mt_keywords (string) - lets users specify one or more categories for MovableType and related
weblogs.
WeblogPostID (string) - ID for weblog APIs such as MovableType, and Blogger.
135 of 178
Tinderbox v5 Manual
Appendix 2: Regular Expressions

When analyzing a large number of notes, you will likely find many occasions to search for notes, or to
have your assistant search on your behalf. While simple searches often suffice, Tinderbox can also
search for complex textual patterns called regular expressions.
Regular expression search is available in Agent queries, in the Find dialog, and in selected template
codes and actions. The agent query:
Text(pattern)
is true of the attribute Text contains a string that matches the pattern. Regular expression search
may be applied to any attribute:
Name(pattern)
searches only the note titles for a textual pattern.
Sometimes, you may want to avoid regular expressions and to search for an exact match to a
specific string. To search for an exact match, use
$Name=="this string"
Note the doubled equals sign used for an equality test (the legacy code using a single equals sign is
supported but deprecated).
A number of special characters represent “wild cards” and other classes of text patterns. Complete
information on Tinderbox’s regular expression engine may be found at:
http://www.boost.org/libs/regex/doc/
The most common and useful examples are described here.
Wildcard Characters
The period character, “.”, matches any single character.

The plus sign, “+”, matches one or more occurrences of the expression that precedes it. The pattern
!+
will match one or more exclamation points, and the pattern
....+
will match any string with at least four characters.
An asterisk matches zero or more occurrences of whatever precedes it;
10*
matches 1, 10, or 1000.
The question mark “?” matches zero or one occurrence of whatever precedes it.
You can also specify the minimum and maximum number of repetitions:
Xa{2,4}Y
will match XaaY, XaaaY, or XaaaaY, but won’t match XaaaaaaY.
Character Ranges
A set of characters to be matched may be enclosed in square brackets. For example,

[0123456789]
136 of 178
Tinderbox v5 Manual
will match any digit. Ranges of consecutive characters can be written more concisely:
[0-9]
will match any digit, and
[A-Z][a-z]*
will match any capitalized word. Beginning a set with the character “^” matches everything except
the set;
[A-Z][^0-9]
will match any capital letter provided it’s not followed by a digit.
Several special sequences represent common sets of characters:
\w - any word character (including underscore)
\W - any non-word character
\< - the start of a word
\> - the end of a word
\s - any white space character
\d - any digit
\l - any lowercase letter
\u - any uppercase letter
Anchors
The special character "^" matches the beginning of the text or attribute being searched. When
searching the text of a note, ^ matches the beginning of any paragraph in the note.
The special character “$” matches the end of the text or attribute being searched. When searching
the text of a note, $ matches the end of the paragraph in the note.
The \ [backslash] Character
The backslash character "\" removes the special meaning from the character that follows it. Use "\\"
to search for the backslash character itself.
Parentheses
Grouping expressions in parenthesis determines the scope of wildcards. For example,

Name=(\u\l+)+
Would match “Rochester” and “SmallTalk”.
In addition, when Tinderbox sees a parenthetical expression, it remembers the substring(s) that
matched it and can use those substrings in actions. For example, the agent
Query: Text(^ color: (\w+)\b$)
Action: $Color=$1
scans the document for any notes that contain paragraphs like this:
Color: red
137 of 178
Tinderbox v5 Manual
If it finds any matching notes, the agent extracts the word that follows the string “Color: ” and
changes the note’s color to match. Here, $1 stands for “whatever matched the first set of
parenthesis”, $2 for the second set, and so forth. $0 stands for the entire matched string.
138 of 178
Tinderbox v5 Manual
Appendix 3: Actions, Expressions and Rules

Tinderbox agents, containers, and adornments can have actions which modify notes when they are
found by the agent, added to a container, or move onto an adornment. All such code is generically
termed 'action code'. A Tinderbox note's Rule is simply some action code continually applied to that
note. Action code is held in these attributes (if a value is set) of notes, containers, agents,
adornments:
OnAdd
Rule
DisplayExperession
HoverExpression
TableExpression - containers and agents only
AgentAction - agents only
AgentQuery - agents only
Text - for more complex use (for more expert users!), it is possible to store larger sections of
action code in the Text to then be applied in the context of one of the above.
Action code is case-sensitive; “Red” and “red” are distinct, 'Descendendfrom()' can not be
substituted for the correctly cased 'descendedFrom()'. Action code functions are generally lowercase
and inter-capitalized.
Action code functions are normally followed by parentheses. There must be no whitespace between
the end of the function and the parentheses:
RIGHT any(children,$overdue)
WRONG any (children,$overdue)
If so noted, some action code functions allow the parentheses to be omitted. If in doubt, simply
include a pair of empty parentheses on the end of the function.
Strings in actions and rules may be enclosed in either single or double quotes. By general convention
- i.e. as seen in most examples - double quotes are used as first preference, but that is not a
requirement.
Attribute Types
Each attribute has a type, which determines what kind of information it contains.
boolean
color
date
file
number
list
set
string
url
139 of 178
Tinderbox v5 Manual
Lists and sets are collections of string values, such as tags or topics. Each item in a set is unique,
while a list might contain the same element several times.
When Tinderbox assigns a value to an attribute, that value is coerced to the appropriate type. If you
assign a string to a color attribute, for example, Tinderbox will try to interpret the string as a color.
$BorderColor="rgb(200,150,120)"
Some operators hav different meanings when acting on different types of data. For example, "+"
adds numbers but concatenates strings:
$Total=$BasePrice+$Tax; (result: 17.95)
$Name=$Topic(parent)+":"+$Topic; (result: Waterfowl:Loons)
In an assignment, the governing type is the type of the left-hand side.
In an expression or a query, the governing type is the type of the left-hand operand (for binary
operators like +) or the sole operand (for unary operators).
Attribute References
Attribute references retrieve the value of an attribute. The attribute name is preceded by a '$', and
followed by an optional argument to designate which note is to be referred to.
$Height
$Color(parent)
Attribute references normally refer to this note, but may refer to another note by its unique name
$Price(My Wonderful Red Widget)
or a path to the note
$Text(/catalog/widgets/red/wonderful/price)
Note Designators
Attribute references usually refer to this note, but you may instead specify a different note. For
example, $Width is the width of this note, but $Width(parent) is the width of this note's
container, and $Width(/data/example) is the width of the note named "example" inside the
top-level container named "data."
Agent queries the note being tested
OnAdd actions the note being added to the agent or container
Rules the note whose rule is being performed
A number of keywords, called designators, let you designate a note by its relationship to this.
The note being examined by an agent, the note being added to

this
an adornment, or the note whose rule is being run
next The note that follows this note in outline order
previous The note that precedes this note in outline order
prevSibling The next older sibling of this note
140 of 178
Tinderbox v5 Manual
nextSibling The next younger sibling of this note
firstSibling The first sibling of this note
lastSibling The last sibling of this note
parent The parent of this note
grandparent The parent of the parent of this note
child The first child of this note
lastChild The last child of this note
randomChild A randomly selected child of this note
The note Tinderbox is currently exporting. When not used in an

export template, current is equivalent to this. Where a note is
current exported to its own page, current is the same as this. If the note
is included in another note's page, however, current refers to the
page being exported.
cover The first note in the document.
source The link source (used only in link expressions)
destination The link destination (used only in link expressions)
Available only in agent queries and agent actions; refers to the

agent
agent that is currently examining the note.
Available only in adornment queries and adornment actions;

adornment refers to the smart adornment that is currently examining or
performing an action on the note.
In aliases, refers to the original note associated with the alias and
useful for addressing properties of the original such as $Xpos
original
and $Ypos that are not inherent to the alias. Otherwise
synonymous with this.
Designators may be combined. For example, $Name(nextSibling(parent)) is the name of the

next sibling of this note's container.
Group Designators
Some operators accept a group designator that designates multiple notes. For example,
any(child,$Checked) is true if the $Checked attribute of any of this note's children is set to true.
Group designators include:
children the immediate children of a note
descendants all descendants of a note
141 of 178
Tinderbox v5 Manual
siblings all siblings of a note
ancestors all ancestors of a note
all all notes in the document
A list or set of pathnames may be used anywhere a group designator is required.
find()
The special designator find() searches through the entire Tinderbox document to locate notes that
satisfy an expression. For example:
$Color( find($Status="Urgent"))="red"
will locate every note whose $Status is "Urgent" and turn is red.
The find() designator acts in many ways like an agent. In general, prefer agents to using find(),
because the agent’s results can be reused by other agents.
Queries
true and false
Agents use a query expression to locate notes they should list, and smart adornments use a query
expression to identify notes they should gather. The conditional expression
if(expression){...} uses an expression to conditionally execute an action.
The following values are treated as "false":
the empty string ""
the number 0
the date "never"
the constant "false"
the color black (rgb(0,0,0) or #000000)
All other values are considered "true".
An attribute reference may stand alone as a query. For example, if Urgent is a boolean user attribute,
the query
$Urgent
finds all urgent notes.
If the attribute is a string, the query is true if the string is not empty and not the string "false".
If the attribute is a number, the query is true if the value is not zero.
If the attribute is a date, the query is true if the value is not "never".
If the attribute is a list or a set, the query is true if the attribute is empty
Comparisons
Comparison operators include:
142 of 178
Tinderbox v5 Manual
== < <= > >= !=

The left-hand side of a comparison is always an attribute name; it may be preceded by a '$'
character. If the left-hand side has an argument, is must be preceded by a '$'.
$Color=red; deprecated (strings should be enclosed in quotes)
$Color=="red"; OK
$Color(this)=="red"; OK
$Color(parent)=="red"; OK
Color(parent)=="red"; Obsolete! No '$' left-side $-prefix
The right-hand side of a comparison may be a number, a string (which should normally be enclosed
in quotation marks), or an attribute reference.
An attribute reference is an attribute name, optionally followed by an argument that designates a
specific note. If the argument is absent, this is assumed.
$Color=="red"
$Color==$BorderColor
$Color==$Color(parent)
Parenthesis may be used to group multiple queries together, using logical operators &(and), | (or), and
! (not).
Text Patterns
Regular expressions can be used to search for text patterns in any attribute. Regular expressions are
most frequently used to search for strings or patterns in the note’s $Text and $Name. A regular
expression query begins with the name of an attribute, followed by a parenthesis containing the
pattern:
Text(pattern)
Note that the '$' prefix is not used in regular expressions. $Text(parent) is the text of the note's parent,
whilst Text(parent) is a regular expression.
Regular expression queries may also be written using the .contains() operator:
$Text.contains(pattern)
The query is true if the attribute contains the text pattern. A variety of wildcards and other special
characters let you search for complex textual patterns; see Appendix 2 (Regular Expressions) for
details.
Other Queries
Any expression can be a query, common queries include the following:
143 of 178
Tinderbox v5 Manual
contains( name of note )

descendedFrom( name of note )
inside( name of note )
first( name of note[,count] )
last( name of note[,count] )
between( attribName,minimum,maximum )
linkedFrom( name of note )
linkedTo( name of note )
indented( count )
similarTo( name of note ) — finds notes whose text is most similar to the text of the named
notes. Similarity is based on the number of words that appear in both texts, weighted to give
more weight to words that are less common in the rest of the document.
word( pattern ) — finds notes that contain the pattern string. No regular expressions are
allowed, but word() is much faster than searching for a regular expression.
Actions
An action changes the value of an attribute. For example,
$Color="red"
sets the color of this note to "red".
Actions may be combined, setting them apart with semicolons.
$Color="red";$BorderColor="bright red"
If the right-hand side of the action is empty, the attribute will be restored to the value it inherits from
its prototype, or to the default value.
$Width=;
The assignment operator |= assigns a new value to an attribute only if the attribute does not currently
have a value. For example, the action
$Project |= $Project(parent)
will set a note's project to be the same as its parent's project, provided the note doesn't already have
a project.
For boolean attributes, |= performs the assignment if the current value is false. For string attributes
and set attributes, |= performs the assignment if the current value is empty. For numbers, |= performs
the assignment if the current value is zero. For dates, |= performs the assignment if the current value
is "never".
The assignment operator &= assigns a new value to an attribute only if the attribute already has a
value.
Conditional actions can perform any query before proceeding, and make their action contingent
upon that query.
if(query){ action }
if(query) { action } else { action }
Normally, actions save results in the note’s attributes. On occasion, it might be useful to save an
intermediate result temporarily. The var statement
144 of 178
Tinderbox v5 Manual
var x;
var area($Width*$Height)
declares a local variable which may be used for the duration of the current action.
For example:
var area($Width*$Height);if(area>25){$Color="red"}
would make the note red if its area exceeded 25.
When agents search for regular expressions, the agent saves substrings that match parenthesized
sub-expressions. These substrings or back references can be used in actions, and are especially
useful for automatically extracting information from notes.
For example, an agent might search for notes that contain fields like this:
From: Henry Higgins
by searching for the pattern
From: (.+)$
An action can then refer to the name extracted following "From: " as $1
$Author=$1;
The author will now be set to Henry Higgins. Subsequent subexpressions may be referred to as $2,
$3, and so on.
String Functions
String Operators
Plus-sign + operator concatenates strings:

"We "+"few" (result: "We few")
Asterisk * operator repeats strings:
5*"!" (result: "!!!!!")
String.capitalize() - returns a copy of the string, capitalizing the initial letter of each word but leaving
all other characters unchanged.
String.contains("pattern") - true if the string contains the quote-enclosed regular expression
"pattern", which may be a regular expression or a string literal. Matches are case-sensitive. The
pattern should always be enclosed in quotes. For example:
$Text.contains("Asia")
is true of the text contains the string, "Asia", and
$Text.contains("s..c")
is true of the text contains an "s" followed by any two characters and then followed by a "c".
String.empty - true if the string is has no characters. Boolean read-only property.
String.icontains(pattern) - true if the string contains the quote-enclosed regular expression
"pattern", which may be a regular expression or a string literal. Matches are case-insensitive. The
pattern should always be enclosed in quotes.
String.json(string) - returns the string in JSON-encoded form; characters that have special meaning
in JSON are escaped with backslashes.
145 of 178
Tinderbox v5 Manual
String.lowercase() - returns a copy of the string, transforming all capital letters to lower case.
String.paragraphs(N) - returns first N paragraphs of the string.
String.replace("pattern","replace"[,"replace"]) - If the regular expression "pattern" is found in the
string, the matching portion of the string is replaced by the replacement string. Additional arguments
allow replacement of multiple sub-expressions assuming extra back-references are created by
"pattern".
String.reverse() - reverses the order of the values in the string.
string.size() - the number of characters in the the string.
String.split("pattern") -splits a string into a list, dividing the string at designated "pattern"; the
matched "pattern" characters are discarded.
String.substr(start,length) - extracts substrings form the string, starting at character number start
(zero-based) and including up to length characters.
"Hello, world".substr(0,5): Hello
If the second argument is absent, the result runs from start through the end of the string.
"Hello, world".substr(7): world
If start is negative, the substring begins -start characters from the end of the string.
"Hello, world".substr(-5): world
String.toNumber() – converts a string of digits to the corresponding number. If the string is empty,
toNumber() returns zero. If the string cannot be parsed as a number, the result is undefined.
String.tr("character","replacement") - replaces every occurrence of a "character" with a
"replacement" character.
"Hello, world".tr(w,W) : Hello, World
Multiple characters may be replaced at once:
"Hello, world".tr("aeiou","AEIOU"): HEllO, wOrld
If no corresponding character appears in the replacement string, the matched character is deleted.
"Hello, world".tr(aeiou): Hll, wrld
String.uppercase() - returns a copy of the string, transforming all lowercase letters to upper case.
String Operations
format()
format(value,format_string) converts attributes to strings and lets you choose exactly how you
prefer the data to appear. format() is useful for export and for preparing data for other programs and
Web services through runCommand.
The argument value is usually an attribute reference or expression. For example:
gets the note's creation date and formats it as a "long local date" such as "Sunday, March 23, 2007
1:26pm".
The meaning of format_string depends on the type of object represented by value.
If value is a date, the format string is the same as the format used by Tinderbox's date export codes.
146 of 178
Tinderbox v5 Manual
If value is a list or set, the format string is the delimiter used to separate discrete list elements
format($KeyAttributes,",")
converts key attributes to a comma-separated list. Optionally, you may supply four quoted string
arguments besides value to format the set as an HTML list:
format(value,list-prefix,item-prefix,item-suffix,list-suffix)
For example
format($MyList,"<ul>","<li>","</li>","</ul>")
If value is a number, then the arguments are numeric and interpreted as follows:
format($MyNum,2) is 3.14
format($MyNum,0) is 3
In quoted string arguments here (as elsewhere), \" is converted to a quotation mark, \n to a carriage
return, and \t to a tab.
string encoding
Four functions encode strings for use in different contexts.

urlEncode("the string")
utf8("the string")
escapeHTML("the string")
idEncode("the string")
urlEncode converts a string to urlEncoded form, for use in HTML links. Characters that are illegal in
URLs are encoded as '%' followed by the corresponding hexadecimal character code.
utf8 was formerly used to convert a string to unicode. Tinderbox strings now use Unicode throughout,
and this function has no effect - do not use it any more!
escapeHTML converts HTML and XML special characters to XML entities. For example, '<' is
replaced by '<' and '&' is replaced by '&'.
idEncode converts a string to form suitable for use as an HTML identifier. Punctuation and other
characters that art neither letters or digits are replaced by underscores.
The first form of exportedString takes a reference to a note and the name of a file in the HTML Export
Template folder, and returns the result of applying the template to the note. The second form requires
no external file; instead, its second argument is the template string itself.
or
147 of 178
Tinderbox v5 Manual
Numeric Functions
The familiar mathematical operators + - * / operate on numeric expressions in the expected way.
Note that + and - have different meanings when applied to sets, and that + has yet another meaning
(concatenation) when applied to strings.
Mathematical Operators
In all the following, the N argument is a number value.

log(N) computes the natural logarithm of its argument, which should be a number, a numeric
attribute, or an expression that can be interpreted as a number.
sqrt(N) computes the square root of its argument.
abs(N) computes the absolute value of is argument.
exp(N) returns the exponential of N, exp(N).
round(N) rounds the value of its argument to the nearest integer.
sin(N), cos(N), and tan(N) are the familiar trigonometric functions, taking arguments in radians.
atan(N) computes arctangent, and returns its result in radians.
mod(N,dividend) computes the remainder of A divided by B.
pow(N,K) raises N to the power of K.
radians(degrees) converts its argument, in degrees, to radians.
rand() returns a pseudo-random number between 0 and 1.
sum(), sum_if, avg and avg_if()
In the following operators, the expression parameter may be an attribute reference, a literal number
value or a code expression.
sum(group,expression) computes the sum of a series of expressions. For example,
sum(child,$WordCount)
computes the total word count of all the children of a note. 'group' may be any group designator
{children,descendants,sibling,ancestor,all}. In addition, 'group' may take a single argument that
designates a particular note other than this; for example
sum(children(/agents/books),$TextLength)
sum_if(group,condition,expression) computes the sum of the values for expression for each item in
the group, ignoring any notes for which if condition is not true. For example:
sum_if(children, $Checked, $Price)
totals the prices of all the note's children which have been checked.
avg(group,expression) computes the mean of a value computed separately for each note in the
specified a group.
avg_if(group,condition,expression)
computes the sum or the mean of a value computed in each note for a group that meets the
designated condition. For example:
148 of 178
Tinderbox v5 Manual
sum_if(child,$Checked,$Qty*$Price)
avg_if(child,$Checked,$Qty*$Price)
compute the total price and the average price of checked items that are children of this note.
Converting Numbers to Strings
String.format(decimal_places[, width]) - converts a number to a string. decimal_places specified

the number of digits to be displayed after the decimal point, and may be zero to display an integer. If
the optional width is specified, additional spaces will be added to the left of the number to pad the
result to a minimum width.
Color functions
Color Operators
Color.red
Color.green
Color.blue
Three read/write properties allow the individual RGB color channel values to be read or set. The read
value is always a number (0-255). Values may set using a number 0-255 or a hex number string "#00"
- "#ff".
$MyNumber=$Color.red
$Color.red = 255
Color.brightness - Read/write property allows a color's brightness level to be read or set using a
value in the 0-100 range representing a percentage. Replaces brightness() action.
Color.saturation - Read/write property allows a color's saturation level to be read or set using a
value in the 0-100 range representing a percentage. Replaces saturation() action.
Color.hue - Read/write property allow a color's hue to be read or set using a value in the 0-360 range
representing a a circular degree. Replaces hue() action.
Converting Colors to Strings
Color.format() - converts a color attribute to a string representation.
Converting Strings to Colors
Tinderbox provides several flexible notations for interpreting colors.

Named colors are always the preferred way to set and change colors in Tinderbox. Named colors
may be redefined, and new named colors added or deleted, in the Colors pane of the Attributes
window (⌘-2)
Hex colors, customarily used on the Web, begin with a # sign followed by six hexadecimal digits:
#rrggbb, corresponding to the proportion of red, green, and blue in the color. #FFFFFF is white,
#800000 is dark red, and #000000 is black.
149 of 178
Tinderbox v5 Manual
RGB colors of the form RGB(red,green,blue) use decimal colors from 0 to 255 to describe the
proportion of red, green, and blue in the color.
HSV colors of the form HSV(hue,saturation,value) describe the hue, saturation, and value of the color.
Hue is a color wheel angle, in degrees, running from 0 to 360. 0 corresponds to red, 120 to blue, and
240 to green. Saturation and value run from 0 to 100. THe value is the equivalent to brightness in
HSB(hue, saturation, brightness)
Manipulating Colors
rgb(red,green,blue) -creates a color. Its arguments are integers ranging from 0 to 255. Arguments
may also be expressions or attribute references.
$Color=rgb($MyRed,255,255)
brightness(color,value) - returns a modified color that has the same hue and saturation as the
original color, but that has reduced brightness. The range of value is 0 to 100.
brightness(color) - returns the brightness of a color, as a numeric value from 0 to 100.
saturation(color,saturation) - returns a modified color that has the same high and brightness as the
original color, but has a reduced saturation as a numeric value from 0 to 100.
saturation(color) - returns the saturation of a color, as a numeric value from 0 to 100.
hue(color,value) - returns a modified color that has the same brightness and saturation as the
original color, but has a different hue. The range of value is 0 to 360.
hue(color) - returns the hue of a color, as a numeric value from 0 to 360.
Date Functions
Date Properties
Seven read/write properties are provided allowing various aspects of data/time data to be read or set.
Date.day (1-31)
Date.month (1-12)
Date.year (value of year)
Date.hour (0-23)
Date.minute (0-59)
Date.weekday (1-7) Monday = 1, Sunday = 7. Read-only
If the Date is never, all functions return 0 (zero).
Date Operators
Date.format("format-string") converts a date to a string, using the quoted date format string
described in Appendix 5: Date Formats. For example, $DueDate.format("l") will format the
value of $DueDate using the system’s short date format.
date(year,month,day,hour,min) constructs a date from individual numeric elements — useful, for
example, if you need to assemble a date from separate attributes. year is the 4-digit year, month is a
number from 1-12. The time arguments are optional, and are specified in a 24-hour clock.
150 of 178
Tinderbox v5 Manual
date(2004,7,23,16,45) is 23 July 2004 4:45pm

date("string") constructs a date from string which is a string literal or string expression. Usually, this
is not necessary as Tinderbox will coerce the string to a date type automatically. In some contexts,
though, it may be more convenient or more clear to make the conversion explicit. (See format() to
convert dates into strings)
day(theDate) returns the day of the month from theDate date expression or Date attribute value. If
$Date is July 4, 2009 then day($Date) is 4. Use Date.day (above) instead.
day(theDate,val) creates a new date based on theDate, but in which the day of the month is val.
theDate itself is not changed. If $Date is July 4,2009, then
$NewDate=day($Date,5) will set $NewDate to July 5, 2009
month(theDate) returns the month from theDate date expression. If $Date is July 4, 2009 then
month($Date) is 7. Use Date.month (above) instead.
month(theDate,val) creates a new date based on theDate, but in which the month is val. theDate
itself is not changed. If $Date is July 4,2009, then
$NewDate=month($Date,5) will set $NewDate to May 4, 2009.
time(theDate) returns the time from theDate expression. Use Date.hour and Date.minute (above)
instead.
time(theDate,hours,minutes) creates a new date based on theDate, but in which the time is set by
hours and minutes. theDate itself is not changed.
year(theDate) returns the month from theDate date expression as a string. If $Date is July 4, 2009
then year($Date) is 2009. Use Date.year (above) instead.
year(theDate,val) creates a new date based on theDate, but in which the year is val. theDate itself is
not changed. If $Date is July 4,2009, then
$NewDate=month($Date,2010) will set $NewDate to July 4, 2010.
Date/time comparison operators
days(date1,date2) returns the number of days that elapsed between date1 and date2, as a number.
If date2 is the earlier date, the result is negative. The internal comparison includes the time portion
of the date. thus if 2 dates are 1 day apart but the times are less than 24 hours aport, the result is 0
and not 1 as might be expected.
minutes(date1,date2) returns the number of minutes that elapsed between date1 and date2, as a
number. If date2 is the earlier date, the result is negative.
List & Set Functions
List & Set Operators
A List is a list of strings or tags separated by semicolons. A Set is a special type of List where
duplicate values are not allowed. A given tag can appear in a set at most once; duplicates are
automatically removed, whereas a List allows duplicates. The order of elements in a set is not
significant. A List can be sorted, a set cannot.
Two Lists or Sets are equal if they contain the same tags (unique values) - regardless of the presence
151 of 178
Tinderbox v5 Manual
of differing numbers of duplicates.

List/Set.contains("item") - true if any element of the List or Set matches the quoted string "item"
exactly. Regular expressions are not supported (unlike with pure string operations). Matches are
case-sensitive. Match values must be enclosed in quotes.
List/Set.each(n){...actions... } – performs an action for each element of the list or set. The local
variable "n" is bound to each element in turn. For example:
$Result=0; $MyList.each(x){ $Result=$Result+x;}
adds each element to $Result
List/Set.empty - true if the List or Set has no data
List/Set.format("delimiter") - converts a List or Set to String-type data, concatenating each value
with the specified "delimiter" characters. thus if "delimiter" is ", " the source data becomes as
comma+space delimited list as a single String.
List/Set.format("list-prefix", "item-prefix", "item-suffix", "list-suffix") - converts a List or Set to a
String. The list begins with the "list-prefix" and ends with "list-suffix"; each item is preceded by
"item-prefix" and followed by"item-suffix".
List/Set.icontains("item") - true if any element of the List or Set matches the quoted string "item"
exactly; differences between upper and lower-case letters are ignored. Regular expressions are not
supported (unlike with pure string operations). Matches are case-insensitive. Match values must be
enclosed in quotes.
List/Set.replace("item","replace") - replaces the designated item with a replacement value.
Matches are only the whole list values; partial value matches are not supported. Match values must
be enclosed in quotes.
List/Set.size - the number of values in the the list. Read-only property.
Lists (but not sets) may be sorted. The following sort operations apply only to lists:
List.sort - case-sensitive sort
List.isort - case-insensitive version of sort().
List.nsort([expression]) - an nsort() behaves exactly like sort(), but assumes that the list elements,
are numbers. Thus an nsort() always sorts numerically.
List.sort([expression]) - if List is a list of note names or $Paths, returns a list sorted by the
corresponding expression (or attribute value). If expression is a Number-type, a numeric sort is
used; if Date-type, a date sort is used. Otherwise, the list is sorted lexically.
List.isort([expression]) - as above but case-insensitive.
List.nsort([expression]) - numeric sort. An nsort() behaves exactly like sort(), but assumes that the
list elements, or the result of the optional expression, are numbers. Thus an nsort() always sorts
numerically.
List.reverse - reverses the sequence of items in the list.
For example, suppose $Favorites is a list of favorite notes.
$Favorites.sort($Price)
returns a list of notes sorted by price with the lowest price first, and
$Favorites.sort($Price).reverse
is sorted by price with the highest price first.
List.unique() - returns a new list that contains each unique item found in the source list. Duplicate
152 of 178
Tinderbox v5 Manual
entries are not copied. Note that all items in a Set are, by definition, unique.
List Operations
Several functions are useful for extracting notable elements from sets and lists. In the following, the
list argument implies set or list data.
count(list) returns the number of tags in list
max(list) returns the largest tag in list
min(list) returns the smallest tag in list
If max(list) or min(list) is evaluated in a numerical context, numerical comparison is used. Otherwise,
Tinderbox uses lexical comparison.
The mathematical functions sum(), sum_if() and avg_if() take a group scope (i.e a list of $Paths) so
can be used with lists - see Numeric Functions further above.
Several functions construct lists from a group of notes.
collect(group,expression) builds a list by visiting each note described by group and adding the
value of the designated attribute to the list. For example,
collect(children,$Name)
constructs a list with the name of each child of the note.
group may be any of {children,descendants,sibling,ancestor,all}. In addition, group may take a path
modifier; for example
collect(children(/agents/books),$Name)
expression can be any expression, but is typically an attribute.For example,
collect(children,$Width*$Height)
collect_if(group,condition,expression) constructs a list by collecting all the notes corresponding to
group, testing each note to see if it meets condition, and adding the expression to the set for each
such note. For example
collect_if(children,$Status="Important",$Name)
will construct a set of the names of all of this note's important children.
Should a unique list of values be required, pass the output to a Set-type as this will de-dupe the
results.
find(query) is equivalent to
collect_if( all, query, $Path)
Note that collect_if is related to agents; many tasks you might perform with collect_if can be done as
well, or better, with an agent. The results of an agent can be reused by other agents, while find() and
collect_if() need to start from scratch each time they are run.
values("attribute_name") returns a set of unique values stored in that attribute throughout the
document. If the attribute is a set or a list, values() returns a set of unique elements used throughout
the document; if the attribute is a any other type, values() returns each of the distinct values in use.
Logic functions
153 of 178
Tinderbox v5 Manual
Logical Operators
Boolean operators & (and), | (or), and ! (not) operate as expected. Boolean assignment (and queries)
coerce non-boolean attributes to either to or false.
number zero is false and any non-zero is true.
string "" and "false" are false, other values are true
set empty sets are false, all others are true
date "never" is false, all others are true
color "black" (or RGB(0,0,0) or "#000" or "‹000000") is false, others are true
Logical equality tests
Use == to equality and != to test inequality. The older form of using a single equals sign (=) for an
equality test is now deprecated (and may cease to function as expected).
A direct reference to an attribute of any data type can be be used as Boolean test for a (non-zero
value):
$MyString is the same as testing $MyString!=""
!$MyString is the same as testing $MyString==""
$MyNumber is the same as testing $MyNumber!=0
!$MyNumber is the same as testing $MyNumber==0
$MyDate is the same as testing $MyDate!=never
!$MyDate is the same as testing $MyDate==never
Action, File, List, Set and URL data types conform to the String type test above as their data is just a
particular form of string.
Logical Group Operators
Logical group operators examine a group of notes and determine whether every note in the group
meets a criterion, or if any note does.
every(group,expression)
any(group,expression)
The designator group describes the notes to be examined. group may be any of
{child,descendant,sibling,ancestor,all}. In addition, group may take a single argument that
designates a particular group other than this; for example
The expression may be any valid expression, but is most often a reference to an attribute.
any(children,$overdue)
every(children,$status="important")
154 of 178
Tinderbox v5 Manual
Link Functions
Link Operators
links[(item)].direction.linkType.attribute operator builds a list from a collection of links.

item selects which note's links should be collected. It may be a single item, a list of items, or a
group.If item is omitted, "this" is implied; it item is omitted the enclosing parentheses may be
omitted as well. item may be a keyword (e.g. "parent") or a note path (/config/details).
The argument direction is either "inbound" or "outbound".
linkType collects only links of a specified link type. linkType is a regular expression: wild-card
characters are permitted and have special meanings. If linkType contains white space or periods,
enclose it in quotes:
links.outbound."responds to".$Name
If 'linkType' is left empty, links of all types are collected with the exception of prototype links.
Prototype links are always omitted. As a regular expression, linkType may match more than one link
type:
links.outbound."agree|clarify".$Name
attribute is the name of the attribute whose values are to be collected in the result.
For example
$MySet=links(/config).outbound.supports.$Name
constructs a list of all the Names of notes that are linked to the top-level note named config via links
of type "supports".
$MySet=links.inbound..$Name
collects a set of all the names of notes that are linked to this note.
links[(note)].kind.linkType.attribute
Making Links
Four actions create or remove links between notes.

linkTo(target [,linkType])
unlinkTo(target [,linkType])
linkFrom(target [,linkType])
unlinkFrom(target [,linkType])
The first argument to each of these actions, is the name or path of a note, or a list of paths. The
optional second argument is the link’s type; if no argument is supplied, untitled links are used. Unlike
links(), above, the linkType argument is not a regex and is a string literal.
linkTo and linkFrom will not create a new link if the link already exists. unlinkTo and unlinkFrom will do
nothing if the described link does not exist. Thus, these actions may be used in agents:
Query: Status(urgent) Action: linkFrom(/agenda/today/tasks,"urgent!")
This action will insure that an "urgent!" link runs from the note "tasks" in today's agenda; if the link
already exists, the action has no effect.
If linkType is not supplied, unlink actions will remove links of all link types.
155 of 178
Tinderbox v5 Manual
Macros
Macro Operator
Rules and actions may use macros through the do() function:
do(macro[,arg1,arg2,arg3])
macro is the name of the macro. Subsequent arguments are optional and are passed to the macro,
which can refer to them as $1, $2, $3, and so forth.
After the macro is evaluated, its result is returned and is parsed again as a rule, action, or expression.
For example:
$Name=do(computeName,$Name,$Name(parent))
sets name to the result of a macro.
do(Instructions);
simply executes whatever actions are returned by Instructions.
eval() and action()
The eval() function evaluates an string and returns the result. For example,
eval("$Price*1.05")
returns the value of price augmented by 5%. Similarly, action() performs an action stored in a string.
action("$Total=$Price*1.05")
changes the value of $Total. action() and eval() are occasionally useful when a note must assemble a
rule on the fly.
Shell Expressions
Shell Operator
The runCommand() function asks the operating system to start a new process and results the result
of that process.
runCommand() executes the specified command line in your default, passing it the the value input as
its standard input. The standard output of the command, if any, is the value of the completed action.
For example:
$Text = runCommand(ls ~/Documents)
replaces the note’s text with a list of the files and folders in the user’s Documents folder, and
$Text |= runCommand("curl "+$URL)
will – if the note has no text – ask curl to fetch whatever text is found at the url stored in the note’s
$URL.
It is not necessary to use an attribute to hold the output from runCommand, allowing the operator to
be used 'bare' in action code. If $CommandValue holds a valid command line string, this can be
used in a rule or action:
156 of 178
Tinderbox v5 Manual
runCommand($CommandValue)
Backtick. If the right-hand side of an action begins with the character `, the rest of the action is
treated as a command that is passed to the Mac OS X command line.
This Tinderbox feature is deprecated, and we believe there are now
better ways to accomplish its purpose. It is discussed here to
assist those working with older document. If your Tinderbox work
uses this feature, we recommend updating it.
For example,
$Text=`perl -v
would replace the note's text with the a string describing the version of perl installed on this
computer. More usefully,
$Text=`curl http://example.com
would set the text to whatever information is available at the stated URL.
Template actions

Template expressions in actions are now deprecated. If you wish to use a template expression to
construct a complex string, exportedString() would be a better approach.
If the right hand side of an action begins with the character ^, the rest of the action is interpreted as a
template expression. For example,
$Msg=^ See ^value($Name(parent))^’s son ^value($Name)^;
The use of template expressions in actions was formerly common but is now seldom if ever
necessary.
$MyString=^ Note ^get(Name)^: ^linkTo(/someNote)^;
157 of 178
Tinderbox v5 Manual
or
Restoring the default value
If the right-hand side of the action is empty, the attribute will be restored to the value it inherits from
its prototype, or to the default value.
$Width=;
Conditional Assignment
The assignment operator |= assigns a new value to an attribute only if the attribute does not currently
have a value. For example, the action
$Project |= $Project(parent)
will set a note's project to be the same as its parent's project, provided the note doesn't already have
a project.
For boolean attributes, |= performs the assignment if the current value is false. For string attributes
and set attributes, |= performs the assignment if the current value is empty. For numbers, |= performs
the assignment if the current value is zero. For dates, |= performs the assignment if the current value
is "never".
The assignment operator &= assigns a new value to an attribute only if the attribute already has a
value.
If()
Conditional actions can perform any query before proceeding, and make their action contingent
upon that query.
if(query){ action }
if(query) { action } else { action }
Local variables
Normally, actions save results in the note’s attributes. On occasion, it might be useful to save an
intermediate result temporarily. The var statement
var x;
var area($Width*$Height)
declares a local variable which may be used for the duration of the current action.
For example:
var area($Width*$Height);if(area>25){$Color="red"}
would make the note red if its area exceeded 25.
158 of 178
Tinderbox v5 Manual
Back References
When agents search for regular expressions, the agent saves substrings that match parenthesized
sub-expressions. These substrings or back references can be used in actions, and are especially
useful for automatically extracting information from notes.
For example, an agent might search for notes that contain fields like this:
From: Henry Higgins
by searching for the pattern
From: (.+)$
An action can then refer to the name extracted following "From: " as $1
$Author=$1;
The author will now be set to Henry Higgins. Subsequent subexpressions may be referred to as $2,
$3, and so on.
String Functions
String Functions
String Operators
Plus-sign + operator concatenates strings:

"We "+"few" (result: "We few")
Asterisk * operator repeats strings:
5*"!" (result: "!!!!!")
String.capitalize() - returns a copy of the string, capitalizing the initial letter of each word but leaving
all other characters unchanged.
String.contains("pattern") - true if the string contains the quote-enclosed regular expression
"pattern", which may be a regular expression or a string literal. Matches are case-sensitive. The
pattern should always be enclosed in quotes. For example:
$Text.contains("Asia")
is true of the text contains the string, "Asia", and
$Text.contains("s..c")
is true of the text contains an "s" followed by any two characters and then followed by a "c".
String.empty - true if the string is has no characters. Boolean read-only property.
String.icontains(pattern) - true if the string contains the quote-enclosed regular expression
"pattern", which may be a regular expression or a string literal. Matches are case-insensitive. The
pattern should always be enclosed in quotes.
String.json(string) - returns the string in JSON-encoded form; characters that have special meaning
in JSON are escaped with backslashes.
String.lowercase() - returns a copy of the string, transforming all capital letters to lower case.
String.paragraphs(N) - returns first N paragraphs of the string.
159 of 178
Tinderbox v5 Manual
String.replace("pattern","replace"[,"replace"]) - If the regular expression "pattern" is found in the

string, the matching portion of the string is replaced by the replacement string. Additional arguments
allow replacement of multiple sub-expressions assuming extra back-references are created by
"pattern".
String.reverse() - reverses the order of the values in the string.
string.size() - the number of characters in the the string.
String.split("pattern") -splits a string into a list, dividing the string at designated "pattern"; the
matched "pattern" characters are discarded.
String.substr(start,length) - extracts substrings form the string, starting at character number start
(zero-based) and including up to length characters.
"Hello, world".substr(0,5): Hello
If the second argument is absent, the result runs from start through the end of the string.
"Hello, world".substr(7): world
If start is negative, the substring begins -start characters from the end of the string.
"Hello, world".substr(-5): world
String.toNumber() – converts a string of digits to the corresponding number. If the string is empty,
toNumber() returns zero. If the string cannot be parsed as a number, the result is undefined.
String.tr("character","replacement") - replaces every occurrence of a "character" with a
"replacement" character.
"Hello, world".tr(w,W) : Hello, World
Multiple characters may be replaced at once:
"Hello, world".tr("aeiou","AEIOU"): HEllO, wOrld
If no corresponding character appears in the replacement string, the matched character is deleted.
"Hello, world".tr(aeiou): Hll, wrld
String.uppercase() - returns a copy of the string, transforming all lowercase letters to upper case.
String Operations
format()
format(value,format_string) converts attributes to strings and lets you choose exactly how you
prefer the data to appear. format() is useful for export and for preparing data for other programs and
Web services through runCommand.
The argument value is usually an attribute reference or expression. For example:
gets the note's creation date and formats it as a "long local date" such as "Sunday, March 23, 2007
1:26pm".
The meaning of format_string depends on the type of object represented by value.
If value is a date, the format string is the same as the format used by Tinderbox's date export codes.
If value is a list or set, the format string is the delimiter used to separate discrete list elements
format($KeyAttributes,",")
160 of 178
Tinderbox v5 Manual
converts key attributes to a comma-separated list. Optionally, you may supply four quoted string
arguments besides value to format the set as an HTML list:
format(value,list-prefix,item-prefix,item-suffix,list-suffix)
For example
format($MyList,"<ul>","<li>","</li>","</ul>")
If value is a number, then the arguments are numeric and interpreted as follows:
format($MyNum,2) is 3.14
format($MyNum,0) is 3
In quoted string arguments here (as elsewhere), \" is converted to a quotation mark, \n to a carriage
return, and \t to a tab.
string encoding
Four functions encode strings for use in different contexts.

urlEncode("the string")
utf8("the string")
escapeHTML("the string")
idEncode("the string")
urlEncode converts a string to urlEncoded form, for use in HTML links. Characters that are illegal in
URLs are encoded as '%' followed by the corresponding hexadecimal character code.
utf8 was formerly used to convert a string to unicode. Tinderbox strings now use Unicode throughout,
and this function has no effect - do not use it any more!
escapeHTML converts HTML and XML special characters to XML entities. For example, '<' is
replaced by '<' and '&' is replaced by '&'.
idEncode converts a string to form suitable for use as an HTML identifier. Punctuation and other
characters that art neither letters or digits are replaced by underscores.
The first form of exportedString takes a reference to a note and the name of a file in the HTML Export
Template folder, and returns the result of applying the template to the note. The second form requires
no external file; instead, its second argument is the template string itself.
or
Numeric Functions
161 of 178
Tinderbox v5 Manual
Numeric Functions
The familiar mathematical operators + - * / operate on numeric expressions in the expected way.
Note that + and - have different meanings when applied to sets, and that + has yet another meaning
(concatenation) when applied to strings.
Mathematical Operators
In all the following, the N argument is a number value.

log(N) computes the natural logarithm of its argument, which should be a number, a numeric
attribute, or an expression that can be interpreted as a number.
sqrt(N) computes the square root of its argument.
abs(N) computes the absolute value of is argument.
exp(N) returns the exponential of N, exp(N).
round(N) rounds the value of its argument to the nearest integer.
sin(N), cos(N), and tan(N) are the familiar trigonometric functions, taking arguments in radians.
atan(N) computes arctangent, and returns its result in radians.
mod(N,dividend) computes the remainder of A divided by B.
pow(N,K) raises N to the power of K.
radians(degrees) converts its argument, in degrees, to radians.
rand() returns a pseudo-random number between 0 and 1.
sum(), sum_if, avg and avg_if()
In the following operators, the expression parameter may be an attribute reference, a literal number
value or a code expression.
sum(group,expression) computes the sum of a series of expressions. For example,
sum(child,$WordCount)
computes the total word count of all the children of a note. 'group' may be any group designator
{children,descendants,sibling,ancestor,all}. In addition, 'group' may take a single argument that
designates a particular note other than this; for example
sum(children(/agents/books),$TextLength)
sum_if(group,condition,expression) computes the sum of the values for expression for each item in
the group, ignoring any notes for which if condition is not true. For example:
sum_if(children, $Checked, $Price)
totals the prices of all the note's children which have been checked.
avg(group,expression) computes the mean of a value computed separately for each note in the
specified a group.
avg_if(group,condition,expression)
computes the sum or the mean of a value computed in each note for a group that meets the
designated condition. For example:
sum_if(child,$Checked,$Qty*$Price)
162 of 178
Tinderbox v5 Manual
avg_if(child,$Checked,$Qty*$Price)
compute the total price and the average price of checked items that are children of this note.
Converting Numbers to Strings
String.format(decimal_places[, width]) - converts a number to a string. decimal_places specified

the number of digits to be displayed after the decimal point, and may be zero to display an integer. If
the optional width is specified, additional spaces will be added to the left of the number to pad the
result to a minimum width.
Color Functions
Color functions
Color Operators
Color.red
Color.green
Color.blue
Three read/write properties allow the individual RGB color channel values to be read or set. The read
value is always a number (0-255). Values may set using a number 0-255 or a hex number string "#00"
- "#ff".
$MyNumber=$Color.red
$Color.red = 255
Color.brightness - Read/write property allows a color's brightness level to be read or set using a
value in the 0-100 range representing a percentage. Replaces brightness() action.
Color.saturation - Read/write property allows a color's saturation level to be read or set using a
value in the 0-100 range representing a percentage. Replaces saturation() action.
Color.hue - Read/write property allow a color's hue to be read or set using a value in the 0-360 range
representing a a circular degree. Replaces hue() action.
Converting Colors to Strings
Color.format() - converts a color attribute to a string representation.
Converting Strings to Colors
Tinderbox provides several flexible notations for interpreting colors.

Named colors are always the preferred way to set and change colors in Tinderbox. Named colors
may be redefined, and new named colors added or deleted, in the Colors pane of the Attributes
window (⌘-2)
Hex colors, customarily used on the Web, begin with a # sign followed by six hexadecimal digits:
#rrggbb, corresponding to the proportion of red, green, and blue in the color. #FFFFFF is white,
163 of 178
Tinderbox v5 Manual
#800000 is dark red, and #000000 is black.

RGB colors of the form RGB(red,green,blue) use decimal colors from 0 to 255 to describe the
proportion of red, green, and blue in the color.
HSV colors of the form HSV(hue,saturation,value) describe the hue, saturation, and value of the color.
Hue is a color wheel angle, in degrees, running from 0 to 360. 0 corresponds to red, 120 to blue, and
240 to green. Saturation and value run from 0 to 100. THe value is the equivalent to brightness in
HSB(hue, saturation, brightness)
Manipulating Colors
rgb(red,green,blue) -creates a color. Its arguments are integers ranging from 0 to 255. Arguments
may also be expressions or attribute references.
$Color=rgb($MyRed,255,255)
brightness(color,value) - returns a modified color that has the same hue and saturation as the
original color, but that has reduced brightness. The range of value is 0 to 100.
brightness(color) - returns the brightness of a color, as a numeric value from 0 to 100.
saturation(color,saturation) - returns a modified color that has the same high and brightness as the
original color, but has a reduced saturation as a numeric value from 0 to 100.
saturation(color) - returns the saturation of a color, as a numeric value from 0 to 100.
hue(color,value) - returns a modified color that has the same brightness and saturation as the
original color, but has a different hue. The range of value is 0 to 360.
hue(color) - returns the hue of a color, as a numeric value from 0 to 360.
Date Functions
Date Functions
Date Properties
Seven read/write properties are provided allowing various aspects of data/time data to be read or set.
Date.day (1-31)
Date.month (1-12)
Date.year (value of year)
Date.hour (0-23)
Date.minute (0-59)
Date.weekday (1-7) Monday = 1, Sunday = 7. Read-only
If the Date is never, all functions return 0 (zero).
Date Operators
Date.format("format-string") converts a date to a string, using the quoted date format string
described in Appendix 5: Date Formats. For example, $DueDate.format("l") will format the
value of $DueDate using the system’s short date format.
164 of 178
Tinderbox v5 Manual
date(year,month,day,hour,min) constructs a date from individual numeric elements — useful, for

example, if you need to assemble a date from separate attributes. year is the 4-digit year, month is a
number from 1-12. The time arguments are optional, and are specified in a 24-hour clock.
date(2004,7,23,16,45) is 23 July 2004 4:45pm
date("string") constructs a date from string which is a string literal or string expression. Usually, this
is not necessary as Tinderbox will coerce the string to a date type automatically. In some contexts,
though, it may be more convenient or more clear to make the conversion explicit. (See format() to
convert dates into strings)
day(theDate) returns the day of the month from theDate date expression or Date attribute value. If
$Date is July 4, 2009 then day($Date) is 4. Use Date.day (above) instead.
day(theDate,val) creates a new date based on theDate, but in which the day of the month is val.
theDate itself is not changed. If $Date is July 4,2009, then
$NewDate=day($Date,5) will set $NewDate to July 5, 2009
month(theDate) returns the month from theDate date expression. If $Date is July 4, 2009 then
month($Date) is 7. Use Date.month (above) instead.
month(theDate,val) creates a new date based on theDate, but in which the month is val. theDate
itself is not changed. If $Date is July 4,2009, then
$NewDate=month($Date,5) will set $NewDate to May 4, 2009.
time(theDate) returns the time from theDate expression. Use Date.hour and Date.minute (above)
instead.
time(theDate,hours,minutes) creates a new date based on theDate, but in which the time is set by
hours and minutes. theDate itself is not changed.
year(theDate) returns the month from theDate date expression as a string. If $Date is July 4, 2009
then year($Date) is 2009. Use Date.year (above) instead.
year(theDate,val) creates a new date based on theDate, but in which the year is val. theDate itself is
not changed. If $Date is July 4,2009, then
$NewDate=month($Date,2010) will set $NewDate to July 4, 2010.
Date/time comparison operators
days(date1,date2) returns the number of days that elapsed between date1 and date2, as a number.
If date2 is the earlier date, the result is negative. The internal comparison includes the time portion
of the date. thus if 2 dates are 1 day apart but the times are less than 24 hours aport, the result is 0
and not 1 as might be expected.
minutes(date1,date2) returns the number of minutes that elapsed between date1 and date2, as a
number. If date2 is the earlier date, the result is negative.
List & Set Operators
165 of 178
Tinderbox v5 Manual
A List is a list of strings or tags separated by semicolons. A Set is a special type of List where
duplicate values are not allowed. A given tag can appear in a set at most once; duplicates are
automatically removed, whereas a List allows duplicates. The order of elements in a set is not
significant. A List can be sorted, a set cannot.
Two Lists or Sets are equal if they contain the same tags (unique values) - regardless of the presence
of differing numbers of duplicates.
List/Set.contains("item") - true if any element of the List or Set matches the quoted string "item"
exactly. Regular expressions are not supported (unlike with pure string operations). Matches are
case-sensitive. Match values must be enclosed in quotes.
List/Set.each(n){...actions... } – performs an action for each element of the list or set. The local
variable "n" is bound to each element in turn. For example:
$Result=0; $MyList.each(x){ $Result=$Result+x;}
adds each element to $Result
List/Set.empty - true if the List or Set has no data
List/Set.format("delimiter") - converts a List or Set to String-type data, concatenating each value
with the specified "delimiter" characters. thus if "delimiter" is ", " the source data becomes as
comma+space delimited list as a single String.
List/Set.format("list-prefix", "item-prefix", "item-suffix", "list-suffix") - converts a List or Set to a
String. The list begins with the "list-prefix" and ends with "list-suffix"; each item is preceded by
"item-prefix" and followed by"item-suffix".
List/Set.icontains("item") - true if any element of the List or Set matches the quoted string "item"
exactly; differences between upper and lower-case letters are ignored. Regular expressions are not
supported (unlike with pure string operations). Matches are case-insensitive. Match values must be
enclosed in quotes.
List/Set.replace("item","replace") - replaces the designated item with a replacement value.
Matches are only the whole list values; partial value matches are not supported. Match values must
be enclosed in quotes.
List/Set.size - the number of values in the the list. Read-only property.
Lists (but not sets) may be sorted. The following sort operations apply only to lists:
List.sort - case-sensitive sort
List.isort - case-insensitive version of sort().
List.nsort([expression]) - an nsort() behaves exactly like sort(), but assumes that the list elements,
are numbers. Thus an nsort() always sorts numerically.
List.sort([expression]) - if List is a list of note names or $Paths, returns a list sorted by the
corresponding expression (or attribute value). If expression is a Number-type, a numeric sort is
used; if Date-type, a date sort is used. Otherwise, the list is sorted lexically.
List.isort([expression]) - as above but case-insensitive.
List.nsort([expression]) - numeric sort. An nsort() behaves exactly like sort(), but assumes that the
list elements, or the result of the optional expression, are numbers. Thus an nsort() always sorts
numerically.
List.reverse - reverses the sequence of items in the list.
For example, suppose $Favorites is a list of favorite notes.
166 of 178
Tinderbox v5 Manual
$Favorites.sort($Price)
returns a list of notes sorted by price with the lowest price first, and
$Favorites.sort($Price).reverse
is sorted by price with the highest price first.
List.unique() - returns a new list that contains each unique item found in the source list. Duplicate
entries are not copied. Note that all items in a Set are, by definition, unique.
List Operations
Several functions are useful for extracting notable elements from sets and lists. In the following, the
list argument implies set or list data.
count(list) returns the number of tags in list
max(list) returns the largest tag in list
min(list) returns the smallest tag in list
If max(list) or min(list) is evaluated in a numerical context, numerical comparison is used. Otherwise,
Tinderbox uses lexical comparison.
The mathematical functions sum(), sum_if() and avg_if() take a group scope (i.e a list of $Paths) so
can be used with lists - see Numeric Functions further above.
Several functions construct lists from a group of notes.
collect(group,expression) builds a list by visiting each note described by group and adding the
value of the designated attribute to the list. For example,
constructs a list with the name of each child of the note.
group may be any of {children,descendants,sibling,ancestor,all}. In addition, group may take a path
modifier; for example
expression can be any expression, but is typically an attribute.For example,
collect(children,$Width*$Height)
collect_if(group,condition,expression) constructs a list by collecting all the notes corresponding to
group, testing each note to see if it meets condition, and adding the expression to the set for each
such note. For example
collect_if(children,$Status="Important",$Name)
will construct a set of the names of all of this note's important children.
Should a unique list of values be required, pass the output to a Set-type as this will de-dupe the
results.
find(query) is equivalent to
collect_if( all, query, $Path)
Note that collect_if is related to agents; many tasks you might perform with collect_if can be done as
well, or better, with an agent. The results of an agent can be reused by other agents, while find() and
collect_if() need to start from scratch each time they are run.
167 of 178
Tinderbox v5 Manual
values("attribute_name") returns a set of unique values stored in that attribute throughout the
document. If the attribute is a set or a list, values() returns a set of unique elements used throughout
the document; if the attribute is a any other type, values() returns each of the distinct values in use.
Logical Operators
Logic functions
Logical Operators
Boolean operators & (and), | (or), and ! (not) operate as expected. Boolean assignment (and queries)
coerce non-boolean attributes to either to or false.
number zero is false and any non-zero is true.
string "" and "false" are false, other values are true
set empty sets are false, all others are true
date "never" is false, all others are true
color "black" (or RGB(0,0,0) or "#000" or "‹000000") is false, others are true
Logical equality tests
Use == to equality and != to test inequality. The older form of using a single equals sign (=) for an
equality test is now deprecated (and may cease to function as expected).
A direct reference to an attribute of any data type can be be used as Boolean test for a (non-zero
value):
$MyString is the same as testing $MyString!=""
!$MyString is the same as testing $MyString==""
$MyNumber is the same as testing $MyNumber!=0
!$MyNumber is the same as testing $MyNumber==0
$MyDate is the same as testing $MyDate!=never
!$MyDate is the same as testing $MyDate==never
Action, File, List, Set and URL data types conform to the String type test above as their data is just a
particular form of string.
Logical Group Operators
Logical group operators examine a group of notes and determine whether every note in the group
meets a criterion, or if any note does.
every(group,expression)
any(group,expression)
The designator group describes the notes to be examined. group may be any of
168 of 178
Tinderbox v5 Manual
{child,descendant,sibling,ancestor,all}. In addition, group may take a single argument that

designates a particular group other than this; for example
The expression may be any valid expression, but is most often a reference to an attribute.
any(children,$overdue)
every(children,$status="important")
Link Operators
Link Functions
Link Operators
links[(item)].direction.linkType.attribute operator builds a list from a collection of links.

item selects which note's links should be collected. It may be a single item, a list of items, or a
group.If item is omitted, "this" is implied; it item is omitted the enclosing parentheses may be
omitted as well. item may be a keyword (e.g. "parent") or a note path (/config/details).
The argument direction is either "inbound" or "outbound".
linkType collects only links of a specified link type. linkType is a regular expression: wild-card
characters are permitted and have special meanings. If linkType contains white space or periods,
enclose it in quotes:
links.outbound."responds to".$Name
If 'linkType' is left empty, links of all types are collected with the exception of prototype links.
Prototype links are always omitted. As a regular expression, linkType may match more than one link
type:
links.outbound."agree|clarify".$Name
attribute is the name of the attribute whose values are to be collected in the result.
For example
$MySet=links(/config).outbound.supports.$Name
constructs a list of all the Names of notes that are linked to the top-level note named config via links
of type "supports".
$MySet=links.inbound..$Name
collects a set of all the names of notes that are linked to this note.
links[(note)].kind.linkType.attribute
Making Links
Four actions create or remove links between notes.

linkTo(target [,linkType])
unlinkTo(target [,linkType])
linkFrom(target [,linkType])
unlinkFrom(target [,linkType])
169 of 178
Tinderbox v5 Manual
The first argument to each of these actions, is the name or path of a note, or a list of paths. The
optional second argument is the link’s type; if no argument is supplied, untitled links are used. Unlike
links(), above, the linkType argument is not a regex and is a string literal.
linkTo and linkFrom will not create a new link if the link already exists. unlinkTo and unlinkFrom will do
nothing if the described link does not exist. Thus, these actions may be used in agents:
Query: Status(urgent) Action: linkFrom(/agenda/today/tasks,"urgent!")
This action will insure that an "urgent!" link runs from the note "tasks" in today's agenda; if the link
already exists, the action has no effect.
If linkType is not supplied, unlink actions will remove links of all link types.
Macros
Macros
Macro Operator
Rules and actions may use macros through the do() function:
do(macro[,arg1,arg2,arg3])
macro is the name of the macro. Subsequent arguments are optional and are passed to the macro,
which can refer to them as $1, $2, $3, and so forth.
After the macro is evaluated, its result is returned and is parsed again as a rule, action, or expression.
For example:
$Name=do(computeName,$Name,$Name(parent))
sets name to the result of a macro.
do(Instructions);
simply executes whatever actions are returned by Instructions.
eval() and action()
The eval() function evaluates an string and returns the result. For example,
eval("$Price*1.05")
returns the value of price augmented by 5%. Similarly, action() performs an action stored in a string.
action("$Total=$Price*1.05")
changes the value of $Total. action() and eval() are occasionally useful when a note must assemble a
rule on the fly.
Shell Expressions
Shell Expressions
Shell Operator
170 of 178
Tinderbox v5 Manual
The runCommand() function asks the operating system to start a new process and results the result
of that process.
runCommand() executes the specified command line in your default, passing it the the value input as
its standard input. The standard output of the command, if any, is the value of the completed action.
For example:
$Text = runCommand(ls ~/Documents)
replaces the note’s text with a list of the files and folders in the user’s Documents folder, and
$Text |= runCommand("curl "+$URL)
will – if the note has no text – ask curl to fetch whatever text is found at the url stored in the note’s
$URL.
It is not necessary to use an attribute to hold the output from runCommand, allowing the operator to
be used 'bare' in action code. If $CommandValue holds a valid command line string, this can be
runCommand($CommandValue)
Backtick. If the right-hand side of an action begins with the character `, the rest of the action is
treated as a command that is passed to the Mac OS X command line.
For example,
$Text=`perl -v
would replace the note's text with the a string describing the version of perl installed on this
computer. More usefully,
$Text=`curl http://example.com
would set the text to whatever information is available at the stated URL.
Export codes
Template expressions
Template actions

Template expressions in actions are now deprecated. If you wish to use a template expression to
construct a complex string, exportedString() would be a better approach.
If the right hand side of an action begins with the character ^, the rest of the action is interpreted as a
template expression. For example,
171 of 178
Tinderbox v5 Manual
$Msg=^ See ^value($Name(parent))^’s son ^value($Name)^;

The use of template expressions in actions was formerly common but is now seldom if ever
necessary.
$MyString=^ Note ^get(Name)^: ^linkTo(/someNote)^;
or
172 of 178
Tinderbox v5 Manual
Appendix 4: HTML Export Codes

Export codes is case-insensitive; ^childLinks^ and ^childLinks will both work. However, in
documentation, the form used generally follows that for action code functions where names are
lowercase and inter-capitalized.
Export code functions generally include trailing parentheses. There must be no whitespace between
the end of the function and the parentheses:
RIGHT ^value($Name("parent"))^
WRONG ^value ($Name("parent"))^
Historically, strings in export code weren't required to be quoted and this usage is still supported for
legacy code. However, strings in export code should now be enclosed in either double quotes (and
single quotes if quote nesting is required.
Common Export Codes
Common Export Codes
^title( object )^ the title of the note

^text^ the body (text and graphics) of the note
^text( object )^ the body (text and graphics) of the note object
^text( plain )^ the body without added HTML markup
^text(this, N )^ the first N words of the body of this note
^paragraphs( N )^ exports the first N paragraphs of the text.
^value( $attribute )^ the value if the cited attribute (q.v. ^get^)
^value( $attribute(object) )^ the value of the cited attribute for a different note (q.v. ^)
^value( ..expression .. )^ Evaluates an an expression, exporting the result as a string.
Older Forms
Two additional export elements were formerly very common. Though both have been replaced by
^value(), they continue to operate and might be encountered in older documents.
^get( attribute_name )^ the value of that attribute for the note
^getFor( object,attribute_name )^ gets the value of an attribute for the note
Actions and Expressions
Actions and Expressions
^value( expression )^ evaluates an expression and exports the resulting string value. For example,
^value($Name)^ exports the note’s name, and ^value(log($TextLength(parent))^
exports the logarithm of the text length of the note’s parent.
âction( action )^ performs an action, with immediate effect. For example,
âction($Color="red")^ will change the color of the note as soon as it is exported. âction()^
173 of 178
Tinderbox v5 Manual
does not export anything, but merely performs the stated action. Its effect is permanent.
Links
Generating Links
ûrl( object)^ the URL of the Web page for the note
^linkTo( object)^ a link to the Web page for that note.
^basicLinks^ or ^basicLinks( "start", "item-prefix", "item-suffix", "end"[, "linkType"] )^
^childLinks^ or ^childLinks( "start", "item-prefix", "item-suffix", "end"[, "linkType"] )^
âncestors^ or âncestors( "start", "item-prefix", "item-suffix", "end"[, "linkType"] )^
^siblings^ or ^siblings( "start", "item-prefix", "item-suffix", "end"[, "linkType"] )^
înboundBasicLinks^ or înboundBasicLinks( "start", "item-prefix", "item-suffix", "end"[,
"linkType"] )^
înboundTextLinks^ or înboundTextLinks( "start", "item-prefix", "item-suffix", "end"[,
"linkType"] )^
înboundLinks^ or înboundLinks( "start", "item-prefix", "item-suffix", "end" )^
ôutboundBasicLinks^ or ôutboundBasicLinks( "start", "item-prefix", "item-suffix", "end"[,
"linkType"] )^
ôutboundTextLinks^ or ôutboundTextLinks( "start", "item-prefix", "item-suffix", "end"[,
"linkType"] )^
ôutboundWebLinks^ or ^ outboundWebLinks(item, count[, "start", "item-prefix", "item-suffix",
"end"] )^
The Similar Notes view listing can be exported by ^simliarTo^ or ^similarTo(item, count[, "start",
"item-prefix", "item-suffix", "end"] )^
^root^ the relative path from the current file to the directory that contains the cover page. This is
valuable for creating relative URLs from templates that may appear anywhere in the document. For
example, ^root^stylesheets/screen.css will always refer to the file “screen.css” in the stylesheets
directory at the top level of the site.
Conditional Export
Conditional Export Codes
îf( condition )^ if the condition is true, then include everything from the îf()^ statement to the
êlse^ or the êndif^
êlse^
êndif^
êxists( object )^ is true if the designated object (for example: parent, nextSibling) exists
^contains( object, pattern )^ is true if the regular expression pattern is found within the object's
text.
Including Other Notes
174 of 178
Tinderbox v5 Manual
Including Other notes' content
^children^ place the children of this note, exported using their own export template, at this point in
the current Web page. (Replaces previous ^justChildren^).
^children( template-file)^ place the children of this note, exported with the HTML template named
template-file, at this point in the current web page. (Replaces previous ^justChildren^).
^children( template-file, N )^ place the first N children of this note (where N is a number) into the
current Web page using the template template-file specified.
^descendants^ place all descendants of this note, exported using their own export template, at this
point in the current Web page. (Replaces previous ^children^).
^descendants( template-file )^ place all descendants of this note, exported with the HTML
template named template-file, at this point in the current web page. (Replaces previous ^children^).
^descendants( template-file, N )^ (deprecated) place the first N descendants of this note (where N
is a number) into the current Web page using the template template-file specified. (Replaces
previous ^children^).
înclude( note_name )^ place the note named note_name, exported with its default HTML template,
at this point in the current Web page
înclude( note_name, template_file )^ place the note named note_name, exported with the HTML
template named template-file, at this point in the current Web page
^randomChildOf( note_name)^ places the whole text of a randomly selected child of the note
named note_name, exported with its default HTML template, at this point in the current Web page
^randomLine( note_name, template_file)^ place a randomly selected line of the note named
note_name, exported with the HTML template named template-file, at this point in the current Web
page
^paragraphs( note_name, N)^ place N paragraphs of the text from note named note_name at this
point in the current Web page
Other Export Codes
Miscellaneous Codes
^comment( string )^ emits string enclosed in an HTML comment

^^ use two carets to put a caret into the text
^host^ the host of the site of this Web page
^file( object )^ the filename of the file for the Web page of the note object (if object is omitted, 'this'
is assumed)
^path( object)^ relative path from the top-level export directory to the file for this Web page (if
object is omitted, 'this' is assumed)
^version^ version of Tinderbox used to create this Web page
^doctitle^ the name of the Tinderbox document
^randomLine( object )^ exports a random paragraph selected from the text of note object (if object
is omitted, 'this' is assumed)
175 of 178
Tinderbox v5 Manual
îndent^ emits a tab character for each ancestor the currently exported node has.
îndent( object)^ emits an object character/string for each ancestor the currently exported node
has. (if object is omitted, 'this' is assumed)
êncode ( what )^ translates special characters such as "<" and "> in what into HTML entities
before exporting them
ûrlencode(what)^ translates characters in what that may not appear in URLs into encoded
equivalents. For example, the space character becomes "%20"
ôpmlencode(what)^ translates paragraph breaks in what to the entity
, as required for some
OPML importers that use the _note attribute."
ûppercase ( what )^ transforms what into all UPPERCASE LETTERS
^lowercase ( what )^ transforms what into all lowercase letters
^capitalize ( what )^ transforms what into Initial Capitals
^firstWord ( what )^ returns the first word of what
^lastWord ( what )^ returns the last word of what
^cloud^ provides an HTML interface to the information displayed in the Common Words view (the
100 most common words in a note)
^sectionCloud^ builds a cloud based on a note and its descendants
^documentCloud^ builds a cloud based on the number of different notes that contain a word in the
entire document.
^cloud (note_name, number)^ for all ^cloud codes, optional arguments allow you to specify a note
note_name and the number of common words displayed
^similarTo (note_name)^ exports a list of notes that are similar to a note note_name
^sectionNumber( object )^ the hierarchical number of the note object (if object is omitted, 'this' is
assumed)
^today( object )^ the date the note object was exported to HTML (if object is omitted, 'this' is
assumed)
^created( object )^ the date the note object was created in Tinderbox (if object is omitted, 'this' is
assumed)
^lastModified( object )^ the date the note object was last modified in Tinderbox (if object is
omitted, 'this' is assumed)
^creator( object )^ the creator of the note object (if object is omitted, 'this' is assumed)
176 of 178
Tinderbox v5 Manual
Appendix 5: Date Formats

L: local time, in long format, using the system format settings (example: Tuesday, April 29, 2003.)
l: local time, in short format, using the system format settings (example: 4-29-03)
d: day of the month (example:29)
D: formats date 01-31, with leading zero
m: number of month (example: 4)
M: abbreviation of month (example: Apr)
MM: name of month (example:April) w: abbreviation of weekday (example: Tue)
M0: formats month numerically 01-12, with leading 0
W: name of weekday (example: Tuesday)
y: year (example:2003)
t: time, in local format (example:2:32 pm)
h: hour of the day on a 24-hour clock (example:13:39)
H: hour of the day on a 12-hour clock (example:1:39)
mm: minute of the hour (example: 05 for five minutes after the hour)
s: second
p: AM or PM
*: date/time in RFC 822 format (example: Thu, 18 Feb 2004 19:12:00 0500)
=: date in ISO 8601 format (example: 2004-02-18)
Within a double-quote-enclosed format strings all other characters are themselves. To use any of the
above literally, prefix the character with a backslash. Thus:
"yM0D" gives "20040218"

y M0 D" gives "2004 02 18"
"Y: y, \M: M, \D: D" gives "Y: 2004, M: 02, D: 18"
Tinderbox date attributes also accept expressions using date designators such as:
now
today
yesterday
tomorrow
day / days
week / weeks
month / months
year / years
Date designators should always be quoted strings, e.g. "today", "week - 2", "week + 1", "tomorrow +
1 year" and "never". 'never' is the 'no date' value and is always later than any other date.
177 of 178
Tinderbox v5 Manual
Addendum: Support for Images

Due to ongoing incompatibilities between image storage in Tinderbox files and the new (v5.0.0)
Unicode text engine, various features related to pictures are temporarily suspended:
Insertion of images into note body text

Saving pictures of Map views
Exporting of images embedded in notes
Help notes on the above features also have annotations linking back to this notes to help clarify that
the features are not currently available.
Users with existing TBXs with images should continue to use v4.7.x. It is possible, though not
generally advised practice to run -from different folders - different copies of Tinderbox, so it may be
possible to have a copy of v4.7.x for image bearing files and v5.x for all other TBXs.
Update:
v5.6.0+. Picture Adornments. Copy the contents of am image (e.g in open in Preview, Select All,
Copy) and past to a Map view/
v5.9.0+. Picture Adornments. Map, Cmd+drag/drop a suitable image from Finder.
v5.9.0+. Image in notes. Drag/drop a suitable image from Finder into a major view contains a
note containing the image. Either add $Text and use the note or copy/paste the image data to
another note's $Text.
178 of 178

Tinderbox User's Manual

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Tinderbox User's Manual

Caricato da

Copyright:

Formati disponibili

Tinderbox v5 Manual

Tinderbox v5 Manual - Table of Contents

Tinderbox v5 Manual - Table of Contents 1

Agents, Dates, and Times 74

Passing attribute data 92

Template Essentials 106

Conditional Assignment 158

Including Other Notes 174

What's New in Tinderbox 5?

title: the name of the note

a title: the name of the note

In any view window,

select an existing note (by clicking on it)

or, in a map view window,

Or, in any view window,

choose Create Note... from the Note menu, or press ⌘-K.

To ﬁnish creating the note,

type a name for the new note

In any view window,

select any note (by clicking on it)

In any view window,

click the note with the arrow tool, to select it

In any view window or list of notes,

click the note with the arrow tool, to select it

type a new name for the new note

choose Rename... from the Note menu, or press Enter

To hide the sidebar in all windows,

choose Preferences from the Tinderbox ﬁle menu

To ﬁnd text in a note

select Find text... from the Edit menu or press ⌘F

To display a “word cloud” of frequently-used words in a note or in the entire document

select Common Words from the View menu or press ⌘⌥W

create a note named "stoplist"

To list all notes in a document

select Locate... from the View menu

To list notes that are similar to your current note

select Similar notes from the Window menu

To associate a ﬁle with a note

make sure the text window of the desired note is open

choose Clear File from a note's File menu

To associate a script with a note

make sure the text window of the desired note is open

To run a script manually

choose Do script from a note's Script menu

To remove a script from a note

choose Clear script from a note's Script menu

To open the history list

choose History from the View menu or press ⌘⇧Y

To visit a note in the history list

To clear the history list

select any note (by clicking on it)

Click in the text window, and start typing.

A few System attributes are

To add an attribute to the note’s key attributes,

Key Attribute display differences

Key Attribute value pop-up lists

Key Attribute value autocomplete

To see other attributes in a text window

reveal the sidebar if it is not already visible.

The Attributes Palette

choose Attributes from the Window menu or press ⌘2.

To change an attribute’s value

To use the quickstamp