Features with OS limit higher than app base specification

The following features require an OS later than the current baseline of macOS 10.13. See the individual notes for details of the OS-based limitations:

• macOS Dark or Light modes
• Exploding Notes
• Built-in Hints container
• Sentiment Analysis
• Taggers
• Find results stand-alone dialog
• Find results pop-over
• Find toolbar (view pane)
• Window menu
• Colors
• String.paragraphList()
• String.wordList()
• String.nounList()
• wordsRelatedTo(dataStr[, wordsNum])
• favorites folder

The Tinderbox Licence

The licence (EULA) can also be view in the Tinderbox Help file.

---

License, Copyright and Colophon

© Copyright 2014 by Eastgate Systems, Inc. All Rights Reserved.

Tinderbox is © Copyright 2002-2014 by Eastgate Systems, Inc. All Rights Reserved.

Tinderbox™ is a trademark of Eastgate Systems, Inc. Storyspace™ and CIVILIZED SOFTWARE™ are also trademarks of Eastgate Systems, Inc. All other trademarks are the property of their respective owners and are used for informational and illustrative purposes only.

This help document was created and edited with Tinderbox Six. Other especially helpful tools included BBEdit, Acorn, Skitch, Xcode, AppCode, DropDMG, Transmit, and CSSEdit.

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.

II) allow anyone else to use the program, so long as there is never more than one user per licensed program at any time;

III) 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 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

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: https://www.eastgate.com/

Registering Tinderbox for the first time

Licence renewal and upgrade requirements

One year from first registering, the right to use new major and minor versions Tinderbox ceases unless you purchase an upgrade licence. An 'upgrade' licence renews free use of new releases for a further year, i.e. for 12 months from the issue date of upgrade licence. If your current cover has not quite expired the new period is added to the end of the existing one.

Therefore, those wanting continued full access to all new releases should purchase upgrade licences on a yearly basis, but this is not a requirement for continued use.

An upgrade licence allows the user to move from any past Tinderbox version to the latest release. As the licence code controls access to all releases, the terms upgrade and update can be regarded as interchangeable.

If a user is outside the free update cover period, new releases may still be downloaded and tried, though use a separate install location and note the the newer version will run in demo mode.

The user is not prompted for upgrades, but it is possible to check the number of remaining months access to new versions and the current licence code via the Register tab of Preferences.

It is not a requirement that upgrades be purchased before expiry of the current free update period. This offers flexibility, especially for those with limited budget for upgrades. Thus it is allowable for the original or a renewal upgrade licence's free upgrade period to elapse and then purchase a new upgrade at some later date. Simply register the upgrade, download the current version and carry on installing new versions for a further year.

Put another way, an existing user can run any version of Tinderbox. If the release date of that version post-dates the end of their free upgrade access, the app will run in demo mode. If within the current access period, the app will run normally; the upgrade licence ensures continued unlocking of new releases.

Registering an upgrade

The process is the same as with initially registering Tinderbox. When purchasing an upgrade licence, a new registration code will be emailed. The code is applied via the Register tab of Preferences, accessed via the Tinderbox 8 menu.

Once registered, the Preferences Register tab will show how many months' entitlement of free updates is left.

Possible problems applying a licence

See Registering Tinderbox for the first time.

Installing a licence on more than one computer

Note licence conditions about installing the same licence on more than one computer (see manual for complete licence), in that you may only:

• Install the program on a second computer you use provided all copies of the program are used directly and exclusively by yourself.
• Allow anyone else to use the program, so long as there is never more than one user per licensed program at any time;

Put in simple terms, you can install it as many times as you like on different computers as long as you are the only user. For those who work on multiple computers at once, the licence does not check concurrent use so you can, for example, use your Tinderbox on you desktop and laptop at the same time.

If your licence for free upgrades has expired, install your current version on the new computer.

Separately, the 'Household' version of the licence allows:

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

In essence, the latter is a 5-seat concurrent access licence.

Installing Tinderbox

To install Tinderbox, download the disk image (DMG) and double-click it to mount the image. Drag the application icon onto the shortcut to your Applications folder to install the app. If installing over an existing version you will be asked if you wish to replace it or to keep both versions. For normal use, replace any existing version.

If the mounted image contains no shortcut to Applications (e.g. with beta builds), simply open a Finder window showing the Applications folder and drag the drag the new app icon onto it.

Once installed, open the Applications folder, find the Tinderbox icon and double-click it to open Tinderbox. On very first use you will be asked for permission to open the app, as part of standard Mac security procedures.

Installing on macOS 10.8+ with default permissions

From v10.8, Apple has changed the defaults for installing applications as part of improving security for the general user. As a result, after installation, on a default 10.8.x system the user may receive a warning dialog along the lines of "Tinderbox" can not be opened because it is from an unidentified developer. The error is slightly misleading, as Eastgate is a long-standing Mac developer. The warning relates to the lack of macOS 10.8-specific code signing. However, including such causes problems on older supported OS.

Solution (required once only):

• When/if given the above warning, locate the Tinderbox program in Finder (in the /Applications/ folder).
• Right-click the program and select "open".
• A warning dialog will now state: Tinderbox" it is from an unidentified developer. Are you sure you want to open it? The dialog will offer 'Open' and 'Cancel' buttons.
• Click 'Open' and the app will run.
• Subsequently, the app will run as normal with no warning dialog.
• If you over-install with a newer release of Tinderbox, you may need to repeat the process (again, once only until the app is changed).

Multiple versions

For users with more specialist needs or those just wishing to test a new version before over-writing their existing version, Tinderbox can be installed pretty much anywhere (for which your account has permissions). Note that if several versions are installed, they will share the same application support folder.

Versions 6.x or later and v5.x can be co-installed but it is not recommended to open both versions at the same time.

Installing a new version

The process is as simple as:

• Close Tinderbox (if open)
• Download the DMG of the latest version from the Eastgate website: https://www.eastgate.com/Tinderbox/download.html 
• Double-click the DMG to mount it. Depending on system settings this may happen automatically on download. A new Finder window opens.
• Select the 'Tinderbox.app' icon and drag it:
  • onto the the alias icon next to it to install to the default location (in /Applications). Accept the prompt to overwrite the existing version.
  • into any other location, e.g. the Desktop if installing a second version to test.
• Unmount the DMG.
• Use the new version.

It can also be useful to review the Document Settings and change any defaults that do not suit. It is certainly worth setting the user name value that is stored as the name of the creator of the note. The latter is very useful if sharing a file with other users who may edit it.

Updating an existing installation

To replace an existing version, first ensure you have closed the existing version. If required, back up the current app (or ensure you still have its installer). Then:

• mount the new version's disk image by double-clicking it
  • default install: drag the application icon onto the Applications folder alias in the disk image
  • custom location: drag the application icon onto the folder holding the current version
• Finder will ask if you wish to replace the current application; click the 'replace' button
• Tinderbox is now installed

If you wish to run more than one version, install the new version to a different folder from your existing one. However, do note that both versions will use the same preferences. If the later version has changed significantly, i.e. has differing preferences, this may cause the older version to behave unexpectedly. Versions 6 and 5 can co-exist but it is not recommended to attempt to work in both concurrently as this scenario is not tested.

Updating the application will inherit existing app preferences so if a preference or attribute default changes in a new version this may not be reflected as the app assumes the existing preference is the users choice. A change to preferences on new version install generally only occurs when completely new preferences are introduced or when the new default choice(s) no longer fit with the pre-existing ones. The user can always manually apply changes to bring preferences back in line with current defaults (assuming these are known!). For those using custom configuration files, also bear these in mind when reviewing changes to preferences.

Although you may have more than one version installed, and whilst they may both open if started you should not open more than one version/copy of the app at a time or you may get unexpected results. In other words, unless you are a beta tester and/or are specifically instructed to do so, only run one version at a time.

Installing more than one version

NOTE: Nearly all users should only ever need to have one version installed—either the current one or the last one available when their free upgrades expired.

However, occasionally it can be necessary to want to have two versions installed at once. A good example is assessing a new version to decide on purchasing an upgrade after having let cover lapse. This approach is also needed for beta testers.

So, it is possible, but do so with care. It is not a supported form of general use. Both versions will share the same app settings.

Do not try to open both versions at the same time—you will not get a warning (or a crash) but you may get unexpected results, so do not do it!

It is suggested to leave the current version of the application installed in Applications. This user then places secondary versions on the Desktop, or whatever location is chosen. If wishing to keep multiple version in the same folder, one will need renaming before being added to the folder.

As all installed versions share settings file, if using a much newer version for test, there is a chance the settings may not then work in the older version. This has not been seen, but if it does old app setting may be lost. Plan accordingly.

As aTbRef's author is also a beta tester, this document has been used editing on multiple versions of Tinderbox (albeit one version at a time) including most betas and without harm.

Note: it is worth repeating that very few users will ever need to use this configuration, but it is worth documenting for those who do.

Migrating Tinderbox to a new computer

With a current original or upgrade licence, simply download the latest version of Tinderbox onto your new compute and register as normally.

If your licence for free updates has expired the process is the same except you should install the last version that your licence allows. If you no longer have the installer for that version, email Tinderbox support and ask for the download URL for your version.

Note the limitations on using the same licence on multiple computers.

Other aspects to consider:

• Preferences file. This is in ~/Library/Preferences. That folder will contain a preferences file and (if used) a Tinderbox user dictionary.
• Configuration files. If you have customised badges, colour menus, etc., or have a set of favourite files, check your configuration files which are at ~/Library/Application Support/Tinderbox/. The latter folder can also be opened from the Tinderbox Help menu.

TBX Documents

A Tinderbox document is a saved as a single file, with a '.tbx' extension, and thus are often referred to as 'TBX' documents.

Tinderbox can create and save multiple TBX documents, limited only by storage space available. It can open multiple TBX documents at once, limited only by the host computer's resources. When Tinderbox is started, it will open any documents open when the app was last closed; this behaviour follows the host OS's System Preference/General 'Close windows when quitting an app', so may vary if that preference is changed.

Tinderbox also tracks recently opened documents on a sub-menu of the File menu. If multiple documents are open, the application's Window menu list all open windows from all documents. The latter listing does not indicate the document to which each document belongs.

Any non-default Document Settings and other customisations (link types, custom colours, user attributes, etc.) are stored in the TBX.

A Tinderbox TBX document stores its data in XML format; for some users with XML skills this can provide another way to interface with, or view, the data. Users altering TBX documents by editing the XML source should note that such work is not formally supported as an editing method, i.e. do not expect that Tech Support will be able to fix user mistakes editing source XML.

An open document can display one or more windows and tabs.

See more on the XML structure of TBX documents.

What does a Tinderbox document contain?

A Tinderbox document is a self-contained storage of your notes and information about them including:

• every note (including any embedded images)
• every agent
• every adornment (including picture adornments)
• any non-default Document Settings
• user attributes
• any user added/customised link types, defined colours, stamps and macros
• information about open document windows and tabs

Note that embedding images inside a document—whether as map adornments or in notes—will likely add noticeably to the overall file size of the document.

The document data is stored as XML. Those whose understand XML can (at their own risk). Use XML tools and techniques to read, extract or even modify data. Do not attempt to edit XML data for Tinderbox files that are also currently open in Tinderbox but rather close them first. Users altering TBX documents by editing the XML source should not this is not formally supported as an editing method; i.e. do not expect Tech Support to clear up after user mistakes. See more on the XML structure of TBX documents.

Either to save space for long term storage or for safe transmission (e.g. as email attachments), Tinderbox files compress quite well. To make a ZIP format archive of one or more documents, select the Tinderbox file(s) in a Finder window, right-click the selection and choose the 'Compress' option. A Zip file will be created alongside the selection. The name of the file is either the filename plus a '.zip' extension or 'archive.zip' if multiple files are compressed. The name of the compressed file can be altered without affecting the contents (though leave the .zip' extension!).

TBX file sizes

Generally most TBX files are pretty small—a few MB or less. There is no hard limit to size to a practical limit will be resources getting maxed out either in the app or the host OS.

Some of the ideas behind Tinderbox do have limitations at large scale. Spatial hypertext works well with dozens or hundreds of notes. If you have millions of notes, it’s harder to make any sense of the map, and it’s hard to know where a new note ought to go. Hyperbolic view can likewise become very busy with large numbers of notes.

Adding images to notes (i.e. to their $Text) or as image adornments on maps will have far greater effect on document size than ordinary textual content (in $Text or as attribute values). Occasionally, users will discover hard limits by building documents larger than anyone had tried to build before but there is no fixed limit.

As a general guideline, Tinderbox is comfortable with hundreds or a few thousand notes. If needing millions of notes, a database application is really the correct. In between those sizes is a grey area. If TBXs are operating smoothly, size should not be a cause for concern.

Reporting Problems

In the event you have problems with the application or with particular TBX(s), formal tech support is offered via email at info@eastgate.com.

Bear in mind that the online forums are user-to-user (i.e. not formal Eastgate support), so people helping there are fellow users who do not have access to the internals of the app. They can however be a useful source of advice on the how and why of using Tinderbox and specific techniques.

Tinderbox files have no '.tbx' extension

Showing or hiding filename extensions via Finder

Tinderbox files do not have a Tinderbox icon

Tinderbox documents should show the file icon illustrated here and open in Tinderbox if double-clicked. If the icon is for some other application or just a plain white page, Finder believes the file is not associated with Tinderbox. In such instances double-clicking the file will cause the other app to try and open the file or finder will ask the user to choose and application to use. This can be fixed.

In such a case, first check that the file has a '.tbx' file extension.

If there is an extension but still the wrong icon it is likely that, due to some unintended error, you have told Finder to open this document in some other application and/or the later has now assumed 'ownership' of the document. Such and error can happen for a single file or all files of a given file extension.

To fix, locate your file in Finder:

• Use Finder's Get Info on the file (Cmd+i).
• Click the 'Open With' disclosure triangle to expand an application list.
• Choose Tinderbox as the application you want all files of this type to open with. If Tinderbox is not already listed as suggested choice, use the "Choose…" option and find Tinderbox in your /Applications folder.
• Click "Change All" and then "Continue" when the confirmation dialog appears. This last step tells Finder to open not just this file, but every file of this type with Tinderbox.

The icons for your Tinderbox file(s) should now regain the expected icon type and open correctly in Tinderbox when double-clicked.

Tinderbox files don't open on double-click

If you definitely know the file is a Tinderbox document and are in a hurry:

• Open Tinderbox
• In Finder, drag the document's file icon onto the Tinderbox application icon in the Dock.
• The file should open

If this does not work, or when you have more time to fix things properly, follow this procedure to (re-)inform Finder how to handle files with a '.tbx' extension.

Read what to do if you get a "Tinderbox was unable to parse this file" message.

Checking or resetting old System attribute defaults

Over time, in successive Tinderbox releases, some System attributes' defaults have changed. These changes will not show up for existing users if their Tinderbox Preference file already defines the values, i.e. some but not all values are masked by existing Preferences.

If it is desired to reset/review attribute defaults:

• Create a new Preferences file (see how).
• Create and save a new Tinderbox document.
• Save the new Preferences file to a new location.
• Close the Tinderbox and restore the old Preferences file.

The old and new Preferences file can now be compared for differences. Attribute defaults set directly via the app can be viewed by opening the saved new TBX in a text editor (the source is XML code).

For long-term users with TBXs originally created in older versions, the issue is the latter are set and fixed at doc creation. New app defaults are not applied. Comparing the attributes section of the new TBX with one or more existing files may show up changes that can then be applied, if required, to the existing document(s) by resetting the document attribute defaults. Note that some attributes, being set via Document Settings, should be altered by that mechanism.

Message: Tinderbox was unable to parse this file

Very occasionally, on opening a file you may get a dialog with a message like:

Tinderbox was unable to parse this file. It may be damaged, or you may need a newer version of Tinderbox. The XML parser said : not-well formed (invalid token) (line 1232).

Whilst the exact line number stated at then end will vary, Tinderbox is telling you that the TBX file's data includes something it can not understand at the line (as referred to) in the source XML of the document. When Tinderbox opens a file, it has to read in all the XML data stored in the TBX document file. If this data has been corrupted in some way such that it is no longer in valid XML format, Tinderbox cannot read past that point and gives this error message.

How might such a thing occur? The error is unusual but causes include copying/pasting text from web pages that mis-declare their encoding, such as with web pages where quote marks show as question marks (e.g. character) or less common accented characters as pairs of random characters. It is not always possible for the Tinderbox to detect that the data it is passed is not what it declares itself to be. This can cause the data to be stored inappropriately in Tinderbox, although the effect does not tend to surface until the document is next opened—which for some users can be hours or days after the triggering event. More technically, data is saved in a form that's not intelligible to the XML parser used to read the data when opening a TBX file. Similarly, AutoFetch of data from badly-encoded pages/feeds/sources can ingest data that has the same effect as above.

The solution is to send the file (or better, a zip of it) to Tinderbox support (info@eastgate.com) and they should be able to fix it and return the document. At times the fix may result in the loss of all or part of $Text (or the affect attribute(s) of the affected note(s), but generally just the offending characters can be excised.

If you are doing some task where this happens more than once (perhaps you have very 'dirty' source material) then ensure you have reviewed your settings for back-ups and autosave. You can always change back to your defaults once the problem is resolved.

For the more technically minded…

If you are confident using a text editor and looking at XML source code you can have a go at fixing this yourself. If you do not have a text (code) editor—do not use TextEdit—a good free option is BBEdit. Now:

• Make a copy of your broken TBX and give it a new name indicating it is (will be) the 'fixed' version.
• In your text editor turn on line numbering (see your editor's manual if unsure how). It is also a good idea to turn on 'invisibles' so you see an on screen character for spaces, tabs, control characters, etc. Turn line wrap 'off', at least until you have located the problem.
• Open the TBX in the text editor app
• Scroll to the line mentioned in the original Tinderbox error message.
• Examine that line in the code for anything untoward (use the window's line numbering to find the right place). If your editor has syntax colouring it should stop working around where the error occurs.
• If it is not self evident as to the exact error, try removing the whole attribute value containing the bad line. Most commonly these errors occur in $Text. In such a case you might delete the value of that $Text, i.e. all code from the last tag preceding the error position and the first tag following it. You can always cut/paste the excised data to a text file for temporary safe keeping.
• Save the file close and re-open in Tinderbox. You may get another error (likely caused by the same thing in a different note). Rinse and repeat the previous steps until the file opens. You can then review what's been lost and the likely probable cause. If you think you know the latter, it is probably worth letting Tinderbox support know in case it is a cause they can predict and guard against in the future.
• If you have no joy at all delete your edited file and sent a copy of the original TBX to support.

For TextWrangler and BBEdit users a slightly more hands-off approach is offered via those apps' "zap gremlins" option. It should prune non-XML-safe characters from the file though you will not know exactly what that is. You will just have to look at the resulting TBX file and guess.

Where are crash and hang logs found?

Tinderbox is generally very stable but that does not mean you may not find some data from the app can not ingest from drag/drop or find some configuration next really designed for.

Should the unfortunate occur, and the app crashes, macOS will create a crash log which it can be helpful to Tech Support in resolving the cause. Such logs are found inside your home folder at:

~/Library/Logs/CrashReporter/ 

or

~/Library/Logs/DiagnosticReports/ 

Within that folder look for files with names in the format "Tinderbox_yyyy-mm-dd-hhmmss_macbookpro.crash". Basically, the filename retains the date/time of the crash.

If reporting a crash, attach a copy of the log file(s) to your email. It is also very helpful to support is you can describe the events lading to the crash and/or a step-by-step method to trigger the crash.

Occasionally an app may not crash but become very busy and have to be stopped (by the user or the system). In such cases a hang report may be created. These are stored in in the main, system-wide Library:

/Library/Logs/DiagnosticReports 

The logs use a similar naming method to the crash logs but use a '.spin' or '.hang' extension.

A more detailed tutorial on crash/hang logs for Tinderbox is available elsewhere.

Resetting Preferences

It is most unusual to get a problem with Tinderbox's preferences. The file contains the app-installed preference defaults, as subsequently modified. However, if a problem is suspected, a number of things may be tried.

For the non-tech user…

…who does not like looking at under-the-hood stuff:

• Locate the Preferences file (for location see below).
• Ensure you have your Tinderbox licence code to hand. NB: the licence is needed only if you cannot roll back to existing Preferences after testing.
• Close Tinderbox, if open.
• Drag the "Tinderbox™ Preferences" file to another place such as the Desktop.
• Restart Tinderbox, which causes a new Preferences file to be created. If demo mode does not enable you to test as needed, you will need to re-apply your licence info via the.
• Test Tinderbox and if no change:
  • Close the app, and copy the old Preferences back over the new set.
  • Contact technical support.
• Or, if the problem goes away:
  • Continue using the new preferences.
  • Re-apply your licence key if you have not already.
  • Check the Tinderbox Preferences dialog in the app and make any customisations to restore your preferred settings.
  • Archive or delete the old preferences file.

For the more technical user…

…the Preferences are a text file so you can open it in a proper text editing (not a word processor!) and look for any obvious corruption. The file includes the Recently Used Files list and in earlier v5 versions some more exotic filenames/paths caused problems. Deleting the corrupt path listing could normally fix Preferences (assuming no other errors). The latter problem seems to have been resolved in later v5 releases.

If confident using a text editor and if forced to use a new Preferences file, the old file can be viewed/compared and used as a reference to re-apply any desired non-default settings via the Tinderbox Preferences dialog.

Locating the Tinderbox Preferences file

Tinderbox's Preferences files normally normal located at:

~/Library/Preferences/Tinderbox™ Preferences 

Users wanting to share Preferences between several users of the same Mac may elect to copy/move their Preferences file to:

/Library/Preferences/Tinderbox™ Preferences 

Tinderbox checks the latter folder for a Preferences file and if found, uses it in preference to any local version.

Register

General

Text

Maps

Outlines

Colors

Note Text

Each note (including agents and adornments) has:

• a title, i.e. the name of the note. This is stored as the $Name attribute of the note.
• body text: stored as $Text. It is not necessary for a note to have any body text.
• attributes: other pieces of information about the note. For instance the note's colour, size, position in the map, and whether it is exported or not.

The equivalent of many pages of styled text and images can be fitted in a note's $Text, but notes are best kept short. Using less text per note also makes it easy to find exactly the desired content, and helps agents find specifically what they are seeking.

A note is primarily text: it can contain many paragraphs, with colour, bold, italic and underline mark-ups, a choice of font as well. This content can also contain links to other notes or link out to web URLs. Embedded graphics in the text are also supported.

Under the hood, Tinderbox files are XML allowing a good range of options when it comes to exporting text. HTML is especially easy as an output format, but the HTML export method can be used for pretty much any mark-up format (XML, PHP, OPML, etc.) as well as plain text and including web support text formats such as CSS.

Note Attributes

An Attribute has a name, a data type, a value (which may be preset to an optional default value). Some attributes are read-only, meaning they cannot be modified by the user; this is normally because such attributes are calculated on the fly (like the current number of child notes ). If no default value is set the attribute is empty/zero/false/etc., according to data type. There are two primary types of attributes:

• System attributes: information built into all Tinderbox documents, such as the colour 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 are then available to every note. For instance, you could add a user attribute "Priority" and give 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".

Additionally, system attributes may be:

• Read-only attributes: information such as the date and time the note was created, or the date and time it was last modified, or its position within the overall document outline structure. Tinderbox keeps this information about every note, and you may view and use it, but you cannot change it.

In Tinderbox all attributes are global in the sense that they exist and can be given a value for any note or agent, even if it might not be useful in a particular case. Just ignore attributes when they do not make sense. Put in database terms, Tinderbox implements one big table (flat file style), rather than a set of related tables.

Note that whilst the document itself does not have an (accessible) $Text property, it does have attributes. Thus you can set some document level preferences. For instance, you can set the Map view's background colour through out the document by opening the Document Inspector's System tab and changing the $MapBackgroundColor attribute's default value.

See here for a deeper discussion of the concept of note attributes.

Special types of notes

Although essentially notes, there are a few objects in a document that by design behave differently from normal notes.

• Adornments for Maps and Timelines
• Separators
• Prototype notes
• Export Template notes

Containers

Any notes containing other notes, i.e. in outline terms having child notes, is considered a 'container.' At the most trivial level this allows notes to be nested inside other notes. For instance, a 'Section' container might contain a series of 'Chapter' notes.

Containers are most useful for structured projects that will mostly be viewed in outline or chart view. In map view, only sibling notes within a a single container are visible on the map. Containers on the current map draw a 'viewport' showing a part of its child map.

Agents are a special class of container, as their children consist of an an alias to every note matching the query stored in their $AgentQuery attribute.

Adornments (map view only) are not strictly containers but act like containers in that they have OnAdd and OnRemove actions and support the inside() action query.

Creating via keystroke

Only normal notes or agents can be created via a keystroke (shortcut):

Note:

• Return key (↩). In most view pane view types except report type views (Attribute Browser, Crosstabs, etc.), pressing Return will add a new note to the document as the next item in sibling/outline order.
• Shift+Return (⇧+↩). In Outline and Chart views, this will result in the new note being created as a child of the currently selected note. If the selected note already has children, it is added as the last child of the container.
• Option+Shift+Return (⇧+↩). In Outline and Chart views, this will result in the new note being created as a child of the currently selected note. If the selected note already has children, it is added as the first child of the container.

Agent:

• Command+Shift+A (⌘+⇧+A). This adds a new agent to the document as the next item in sibling/outline order.

Creating via menus

Various menus can be used to make a variety of note types and agents.

Note menu:

• Create Note. (keyboard alternative)
• Create Agent. (keyboard alternative)
• Create Agent As Child. The agent is generated as a child of the current note/container. Note: agents cannot be nested.
• Create Separator (Outline view only) / Create Adornment (Map view only)
• Add Composite (Map view only). Adds a new composite from those available in the current document.

View context menu (i.e. right-click), when no note is selected:

• Create Note. (keyboard alternative)
• Create Agent. (keyboard alternative)
• Create Agent As Child. The agent is generated as a child of the current note/container. Note: agents cannot be nested.
• Create Separator (Outline view only) / Create Adornment (Map view only)
• Create Composite (Map view only). Adds a new composite from those available in the current document.

Other creation methods

Notes and agents can be generated in a number of other ways.

Drag-drop or Paste image adornments (Map view only). See more.

Attributes (via Displayed Attributes, Inspector, Get Info or an action)

• Separators. $IsSeparator toggles a note between normal and separator. Separators appear in outline view only and are hidden in all other views.
• Smart Adornments. Setting a query in an adornment's $AgentQuery makes it into a smart adornment; removing the query switches back to normal adornment behaviour.
• Timeline adornments. Setting $StartDate (and $EndDate) will make an adornment show in a relevantly-scoped Timeline view as well as in a Map.

Action code:

• create() will create a note.
• createAgent() will create an agent.

AppleScript. See more on Tinderbox AppleScript methods

Windows, Tabs & Views

A Tinderbox (TBX) document has a single two-paned document window by default, with two tabs. Your work in Tinderbox takes place in one of the two main panes of a document window, the View pane and the Text pane:

• The View pane (left-hand pane) depicts some, or all, of the document's notes using one of a variety of view (visualisations) types. The View pane represents what were stand-alone 'main view' pre-v6. There are a number of types of view used by the view pane:
• Map.
• Outline.
• Chart.
• Timeline.
• Treemap.
• Attribute Browser.
• Hyperbolic.

The Text pane (right-hand) represents the note's pre-v6 text window. It holds the note title, optional Displayed Attributes, and the note's text ($Text). Alternate sub-tabs of this pane show the raw mark-up of the note as exported via HTML (marked-up) Export and the same in web browser preview form.

Some View pane views show only a narrow context, e.g. Map view, whilst others (by default) show the document's hierarchical structure such as Outline, Chart or Treemap views.

All new document windows always have a Map view (tab #1, selected by default) and Outline (tab #2). However, users are free to use as many or as few view types as their work or particular projects demand. Not all users will need to use every view type.

A small number of secondary view and windows from earlier Tinderbox designs have become pop-over dialogs (and thus essentially modal), although a few such pop-overs 'torn off' text windows can be created, by dragging them to become stand-alone windows. Pop-over offering this affordance do so with a double rectangle icon in their top right corner. Stand alone text windows show the contents of a note's Displayed Attributes and $Text, but lack some text pane affordances such as the link well, title bar and Preview/HTML tabs.

Multiple document windows may be open while working in Tinderbox as well as torn-off windows and the Inspector. They can show the same or different parts of your document. It is also possible have multiple windows open for more than one TBX document. Thus, if more than one document is open at a time, the windows from each/every document are be open at the same time. This can be useful when trying out new code techniques, to avoid doing potentially disruptive tests on a primary work document.

Hierarchy of Content

Paths

Tinderbox allows you to identify notes by relative or absolute paths, not just name. If a tag's request matches neither a keyword nor a note, Tinderbox tries to interpret it as a path. For example:

/news …is the top-level note named "news"

/news/Iraq …is the note named "Iraq", inside the top-level note "news"

../Chicago …is the note named "Chicago" that is a sibling of this note

../.. …is the grandparent of this note.

Using paths implies:

• knowledge of the Tinderbox document's outline structure
• where in the outline that named notes are used
• that the outline will not change.

If a note name contains a forward slash, as in 'Large/Medium', then the path must be enclosed with quotes, e.g. Large/Medium should be cited as "Large/Medium". A deprecated legacy alternate is to escape the slash by a preceding backslash, e.g. Large\/Medium. Doing otherwise, the backslash is treated as part of a path, i.e. is a container delimiter.

A path beginning with a / is always a (complete) absolute path down from a top-level note (though it need not be the cover if there is more than one top level note). Relative paths start with ../ (i.e. period+period+slash). A path not starting with either of these will result in Tinderbox treating the proffered string as a single note name.

Quoting of Paths

Historically paths were not quoted where used in Tinderbox code, and thus may be omitted in many older code examples you find. However, users should switch to quoting paths as they are string literals. Past convention in code examples is to quote paths in action code but not in export code, but this largely reflects past usage and should not prompt current users to omit quotes.

An exception to quoting paths occurs, where a path argument is actually an expression or an attribute name. A simpler way to view this is that quote enclosing a string of text is to say to Tinderbox, "This is just text. Do not try interpreting any control/code characters found within it", i.e. string literal.

Using Path arguments in Tinderbox

Many operators and codes in Tinderbox that allow a note name as an argument also allow a 'path' to be used. All attributes can also take a path argument, allowing code to refer to an attribute from some other note.

For new users, figuring out paths can be a bit confusing. But firstly, why might a path argument needed? If a note name is not unique across the whole TBX document, then when Tinderbox finds a code mentioning that name, it will use the first matching note as found by $OutlineOrder. So, using a path rather than a note name can help identify exactly to which note you wish to refer. Consider using paths explicitly if:

• Your document deliberately does not use unique note names
• It may be that names may not remain unique over the life of the document.

That's the 'why', but how do you refer to a note using a path? To investigate this consider the following TBX outline:

  First Root
    Child A
      Sibling A1
      Sibling A2
    Child Z
  Second Root
    Child A
      Sibling A1
    Child B
      Sibling B1
      Sibling B2
    Child C/D
      Child of D

In this demo, you will note that there are some duplicate note names. For the examples below, to help give starters code such as they might use for real, the examples are written as if referring to a value of the system attribute 'Created'.

Note name (i.e. no path)

Just use the note name on its own:

$Created(Child B) 

$Created(Child A) 

$Created("Child C/D") 

$Created("/Second Root") N.B. need for root slash

Notes:

• note name will not suffice if you want to reach the 'Child A' in 'Second Root'. The note of the same name within 'First Root' will always get called.
• any paths (or just note names) with forward slashes must be 'escaped' by quoting the whole string.
• citing root-level note names must include a slash prefix, i.e. when the $Name is the $Path—or rather the $Path is "/"+$Name . See also notes on partial paths further below.
• there is still legacy support for the now deprecated old usage of preceding (/) slashes in paths with a backslash (\) character.

Ways to view a note's path

The clearest way is to view $Path data but various views offer ways to see all or part of the path:

• hoisted views show a 'breadcrumb' trail indicating ancestor container, and thus the path to notes in the current view.
• Outline, Chart and (albeit less obviously) Treemap views allow the (ancestor) path to be viewed. In the case of Outline and Chart it may involve expanding the outline branch holding the current note. In the case of the treemap it is a case of spotting the nested containers.
• Text pane. Holding the cursor over the note name results in a tooltip showing the full path of the note. This is useful when a $Name is not unique within the document.

Paths from Attribute Values

A path may be supplied as an attribute to address an attribute of another note than the current one.

$Text($MyPath) 

…where $MyPath is a user attribute holding a path.

Paths from Expressions

Path may also be supplied in the form of an expression such a string concatenation or simple arithmetic:

$Text(' "../"+(1+2) ') 

…would collect the $Text of a note named "3".

Paths with Designators

Most Tinderbox designators can use a path to refer to a different context. For example:

min(child("/some/other map note",$Xpos) 

^min(child("/some/other map note",Xpos)^ 

Paths with nested designators: it is possible to cite an offset combining designators.

  ancestor
    Examples
      A
        1
        2
      Aliases
        A
  another
    More
      B
        3

For the alias A

$Container(this) is "Aliases"

$Container(original) is "Examples"

The designator parent(original) will give the parent of the original -- the parent of Examples, So $Container(parent(original)) is "ancestor".

The designator original(parent) will give the original of the parent -- "Aliases". So $Container(original(parent)) is "another".

Thus nested designators like this tend to be written as spoken: the 'parent of the original' being parent(original).

Other ways to identify a note other than via its path

The $Path attribute holds the note's path. For unique note titles the title alone ($Name) can be used as a proxy for the path in many cases. A robust but less human-readable path alternate (but accurate) is to use $ID or the newer v9.5.0 $IDString. The latter can be useful if the $Path data contains problematic characters like a forward slash in any note title in the path.

Further notes on Paths

See here:

• Absolute Paths
• Relative Paths
• Partial Paths

Uniqueness, duplicates and matching notes

Does a note (agent, etc.) need to have a unique title ($Name)?

No, though usually unique, an object's title ($Name) is not required to be unique. Same-titled objects will have different a $Path path, unless they are in the same container. Even then, all objects (including aliases) have a discrete $ID enabling duplicate objects to be addressed discretely.

Be aware that generally, that when using code with attributes using an offset address argument, most users only employ an object's $Name and this is apparent in most code examples found in the forums and in this resource.

Is is possible to test for duplicated titles?

Yes, by using isDuplicateName(). For instance a stamp with code:

$MyBoolean = isDuplicateName($Name); 

… when applied to one or more objects will set $MyBoolean to true for any object whose $Name is not unique. The scope of the test is always the whole document.

Are there any $Name values to avoid duplicating?

Yes. A number of build-in features—when used—generate root-level containers: prototypes, (export) templates, composites, and hints. It is a good idea to avoid duplicating these features' default containers, indeed all sub-containers within '/Hints'. If it is necessary to duplicate any of these containers (and at root level) ensure the built-in feature generated one is first by outline order ($OutlineOrder).

How do duplicate titles affect queries and finds?

Duplicate-titled notes have no effect on queries which will generate an alias (agent) or path (find()) for each discrete note, even if the duplicate-titled notes are in the same container. It is not documented but it may be because the duplicates are resolved using $ID or $IDString (from v9.5.0) which will be unique for each note. Note that whilst a find() uses a query, like an agent, the difference is that a find() does not weed out matches aliases whereas an agent does so..

How do duplicate titles affect queries and finds?

When referring to another note via its $Name as an attribute argument, e.g. $MyString("Some note"), if there is more than one match the resulting action(s) will be carried out only on the first match by outline order ($OutlineOrder). Thus if the $Name matches 3 discrete notes, the action will occur three times on the first matched not and not once each on each matched note. This issue can be countered in part by using $Path rather than $Name for the argument. If the matches are duplicates within a single container, only $ID can be used to ensure every match note is acted on by the action.

Summary

It can be seen that actions—including agent actions—rather than queries that are affected badly by notes with a common name. If document's subject requires the existence of duplicate note titles, extra care should be taken in how actions are addressed to the corrected note(s).

Attributes

Many aspects of Tinderbox are set and stored by using attributes, such as a note's name, the colour of its icon in a Map view, etc. Attributes apply to every note (including special notes like separators and adornments) and agents.

An Attribute has a case-sensitive name, a value type, a value and an optional default value. Some attributes are read-only, meaning they cannot be modified by the user. If no default value is set the attribute is empty/zero/false/etc., according to data type. There are two primary types of attributes:

• System attributes: information built into all Tinderbox documents, such as the colour 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 give 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". More on naming attributes.

Additionally, system attributes may be:

• Read-only attributes: information such as the date and time the note was created, or the date and time it was last modified. Tinderbox keeps this information about every note, and you may view and use it, but you cannot change it.

The two primary attribute listings, General and User, and their data types, etc., are covered in more detail in the Attributes section and all General attributes are described system attribute list. Values used by attributes are often inherited. There are also naming rules for attributes.

System attributes will generally have a default value which may be set via Preferences or, at document level, by editing the default value.

In Tinderbox all attributes are global in the sense that they exist and can be given a value for any note or agent, even if it might not be useful in a particular case. Just ignore attributes when they do not make sense. Put in database terms, Tinderbox implements one big table (flat file style), rather than a set of related tables.

The attributes of TBX document are set at document creation by Tinderbox and may be altered via the Document Inspector's System tab, though some can also be set via Document Settings. Thus you can set the Map view's background colour by opening the document's Info view and changing the $MapBackgroundColor attribute; be aware changing this attribute only affects the document if the current 'item' is the document and not a note, i.e. no note is currently selected.

In Action code, attribute values are referred to in Tinderbox attribute coding by using a '$' prefix, e.g. $Color returns the _value_ for the attribute 'Color' (i.e. the note's colour in the view pane). By general informal usage, the Tinderbox community will also use (misuse!) the $-prefix in general writing to make explicit they are talking about a the name of an attribute. Thus "See the $Name of…" or "You can use the $Height…" where in both cases the context implies that "$X" means the "the attribute named X". This latter convention is used in aTbRef.

There are a variety of methods for editing attribute values.

Give consideration to naming attributes in a manner that matches Tinderbox's assumptions. If attribute names are wrong, either due to import or because they were created before reading the notes on naming styles, attributes can be renamed.

Attributes all have one of a number of data types.

Attribute use in the context of automation ('coding') in Tinderbox is discussed in detail under Use of Attributes.

Prototypes

Prototypes are a method to let a single note specify the default value for an entire class of notes. This is achieved by specifying an existing note as the prototype, via the $IsPrototype attribute; this tells Tinderbox to use the prototype's values for the all the notes set to use that prototype. The easiest way to make a note a prototype is via the Properties Inspector's Prototype tab.

Attribute inheritance

See also: Inheritance of attribute values.

Whenever Tinderbox uses a prototype it will re-use an attribute value from the prototype for its own attributes unless the attribute is specifically set for that note (by action or manual edit). Such manual edits break inheritance (for that attribute only) but inheritance can be reset. There are some special mechanisms for disabling action inheritance.

When you change an attribute in a prototype, you change it for the notes that use that prototype. A note inherits all attributes from its prototype except for intrinsic attributes. Prototypes are not a necessary feature for everyday use but they can powerful time-savers for complex projects. Indeed, any large or long term Tinderbox project is likely to benefit for judicious use of prototypes.

As well as normal notes, an agent or adornment may be a prototype, but setting a normal note to use either of those will note change the nature of the note; it will simply use the customisations it can so, for example an agent query would be ignored. Nonetheless if making large use of agents or adornments, prototypes can speed their configuration.With agents, ideally the prototype should not have a query set though Tinderbox will cope with such a configuration. The Rule and Display Expression disabling attributes can help by ensuring things like self-resetting rules only run in non-prototype notes.

If a note or agent is copied and pasted to a different document, the new item does not inherit its source's $Prototype value. This is a defensive assumption by Tinderbox as it cannot be sure pasted notes are from the current TBX and thus that all source prototypes exist. When creating 'template' type notes/containers bear this in mind. Think about using an agent to help set prototype values directly or indirectly via rules and actions. The |= operator can be used to ensure actions occur once only.

Inheritance of Text

When a note’s prototype is set or changed, the note copies the prototype’s text ($Text) if the note has none, or if the text it inherited from its former prototype has not been changed.

Inheritance of Text links

From v9.5.2, if the prototype's $Text contains any text links, these are inherited when $Text is inherited (as described above)

Prototypes bequeathing child notes

Prototypes can have children that are created/added to a note if that prototype is applied, described in Tinderbox as 'bequeathing' notes—see more.

Built-in Prototypes

Tinderbox makes it easy to experiment with prototypes as a number of simple generic ones are predefined and built-in, noting that a few of these—such as for notes in DEVONthink watch folders—are added as-needed by the app and are not available for manual insertion via the File menu.

See more:

• Setting prototypes
• Disabling action inheritance
• Prototypes 'Bequeathing' Child Notes
• Duplication and prototype assignment
• Shared prototypes
• Chaining prototypes

Inheritance of attribute values

The series of notes in this section of aTbRef describe how inheritance of attribute values works in Tinderbox as this can be be confusing for those beginning to use Tinderbox.

Gaining a working understanding of the process is a solid step towards deeper use of the program.

• Attribute value inheritance flows downwards
• Inheritance for Intrinsic or Read-only attributes
• Inheritance is not based on the actual outline of your data
• The Inheritance Cascade
• Inheritance and prototypes

Data export

Tinderbox offers extremely flexible export, both in format and scope.

The is all covered in the section on Export.

Data import

Tinderbox can both import data via a variety of means though there is no primary 'Import' command or mechanism. Broadly, Tinderbox accepts drag drop of plain text data including tab-delimited text. There is also support for data interchange with some specific applications.

Data import is explored in detail in the section on Import.

Unicode

Since Tinderbox version 5.x, Unicode is supported in note text ($Text) and all system/user attributes. From version 6.x, all UI elements support Unicode display and input.

Data exported from Tinderbox will use Unix-style line ends, i.e. line feed character. In Action code this is inserted as the string "\n".

Inline images

Tinderbox can embed and show bitmap images in two places:

• In note body text. Such images are exported via HTML export.
• Map image adornments. These cannot be exported but the overall View pane can be exported using the 'Copy View as Image' Edit menu option.

These images are embedded into the Tinderbox document and form part of the data (and stored size) to the TBX file. Depending on the nature of a TBX document, it may make sense to store large images externally and link to them.

If the TBX is primarily intended for export, such as this document, it may make more sense to store the images outside the TBX and link the exported pages to the external assets. Given that embedded images do not export (at least not currently) then it is possible for a note to have both an embedded image for viewing within Tinderbox and separately alongside it export code that links to an externally stored copy of the image for use with HTML output.

Tinderbox compresses images; this substantially decreases the size of Tinderbox files with embedded images. Tinderbox currently uses JPEG compression, and compresses fairly aggressively; this significantly diminishes the size and loading time of Tinderbox files at the cost of some image degradation.

Another way images may be used as fills for Map view notes and adornments and the view background (see $Fill and $MapBackgroundFill).

Fonts: italics and bold

Using current Apple frameworks, italics and bold are generated by using the italic or bold font variants of the normal version of the specified typeface. Thus if $TextFont is Helvetica, italic text is rendered in Helvetica Italic and not a false italic of Helvetica; similar for bold text.

Some fonts well used in the past as Tinderbox defaults may lack these font variants. For instance, macOS currently has no italic variant of Lucida Grande, as was used for $TextFont in earlier versions of Tinderbox. This can be problematic when opening TBX documents created using the latter as italic text and titles are rendered as normal text. In particular this makes it difficult to tell aliases apart from original notes.

As $Text is saved as Rich Text (i.e. with embedded style information) it is not possible to recover 'lost' style caused by the above issue and it will need to be re-applied manually. For title contexts (e.g. aliases styled in italics), there are two possible solutions.

• If a permanent change of font is acceptable, change to one that has both italic and bold variants. If in doubt, use the v7 defaults for the relevant attribute.
• If the existing font is still desired, there is a document setting that allows for aliases to be rendered in underlined normal fonts in addition to the italic styling; i.e. if italics are available the title is underlined and in italics, otherwise it is only underlined).

Use of Attributes

Aside from what an attribute is as a concept within Tinderbox, it is useful to understand how code interacts with attributes and how choices about attribute type and name can affect their use. See:

• Attribute Naming
• Attribute Data Types
• Determining the data type of an attribute
• Default values for attribute Data Types
• Document versus Application: system attributes and defaults
• Renaming an attribute
• Keywords for Date-Type Attributes
• What are Displayed Attributes?
• Pre-populating Displayed Attributes pop-up lists
• Attribute inheritance of preferences and settings
• Intrinsic attributes
• Attribute Listings
• Editing attribute values
• Setting or resetting an attribute's default
• Attributes - $ prefix notation
• Change to Number-based opacity attributes