Features with OS limit higher than app base specification

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

• mcp()
• Technical Requirements
• AI container
• AI Additions to the Hints container
• Claude Integration
• Claude-Tinderbox MCP tools
• MCP for AI
• Natural Language Processing
• Full Screen Tile sub-menu
• Move and Resize sub-menu
• Edit menu
• Writing Tools sub-menu
• Apple Intelligence
• 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-2024 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, DropDMG, and Transmit.

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.

---

Markdown Copyright (c) 2004 by John Gruber. All rights reserved.

CommonMark Copyright (c) 2014, John MacFarlane. All rights reserved.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

Eastgate Systems Inc.

134 Main Street

Watertown MA 02472 USA

Tel: (800) 562-1638 (617) 924-9051

Email: info@eastgate.com

Web: https://www.eastgate.com/

Registering Tinderbox for the first time

When first purchasing Tinderbox, a registration code will be emailed. The code is applied via the Register tab of Preferences, accessed from the Tinderbox menu.

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

Until a registration code is applied, the application runs in demo mode.

If Tinderbox cannot run on the macOS version of the current host Mac, Tinderbox will not launch.

If the host macOS is older but supported, Tinderbox may skip some facilities, or use older or slower versions of those facilities. This is not generally a big concern.

If the licence is valid, a green tick is shown at bottom right of the dialog, otherwise a grey X is shown.

Possible problems applying a licence

The most common registration problems are:

• The registration code is mistyped.
• The registration code is too old, e.g. when meaning to apply an upgrade licence but using a previous code
• Using a different name (or middle initial) in the registration window from the name on the order. To Tinderbox, J. Doe, john doe, and J. Q. Doe are all different names.
• omitting the optional organisation name (only if one was given during purchase).
• mistaking the letter "l" (lowercase L) and the numeral "1" in the registration code.
• Tinderbox thinks (usually incorrectly) that the user's name cannot be a name.

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

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.

Note that if using multiple versions in different locations and using AI with an MCP bridge, the AI settings will hold the version/location of the app as at the time AI was last enabled.

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

First check you have not set Finder's preferences to hide file extensions: see how. If you have, you will not see any file extensions!

If a Tinderbox file has no '.tbx' extension, even when extensions are shown, then there are some possible causes:

• If you used Tinderbox before July 2005 (v2.5), the application did not add extensions and relied on old-style Mac OS resource fork info. All such legacy Tinderbox files should now be given a '.tbx' extension.
• You somehow deleted the extension. If you are certain the file is a Tinderbox document, then give it a '.tbx' extension and try opening it
• The file is not really a Tinderbox file. Either—if confident to look at XML—look at the source code in a text editor. A Tinderbox file will mention the app name on line #2 of the code. Or, send a copy of the file to support (info@eastgate.com).

Now your files have the correct extension they should show a Tinderbox file icon and you should be able to open then simply by double-clicking their file icon. If not, see here.

Showing or hiding filename extensions via Finder

The setting is normally on the Advanced tab of Finder Preference. To do this:

• Select Finder
• Open the Finder menu from the main menubar (top of screen)
• Click the 'Preferences…' menu option
• The Finder Preferences dialog will open (illustrated here)
• If not already selected, click the 'Advanced' button in the dialog's toolbar.
• Ensure the top tick-box 'Show all filename extensions' is ticked (as shown)
• Close the Finder Preferences dialog.

Your Tinderbox documents now show a '.tbx' extension.

If desired, you can toggle this option back off but all extensions will be hidden. It is certainly advisable to have file extensions visible whilst troubleshooting issues with Tinderbox files being opened correctly on double-click.

Note that Finder itself can still 'see' any file extensions even if you have told it to hide the file extensions.

Beyond the scope of this article is that depending on how much fiddling you have done in this area, some extensions may not be hidden, even when Finder has been told to hide extensions. This is because unwittingly you will have told Finder that this particular file's extension or this extension in general must always be shown. That is fixable; look in Finder's Help for how.

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.

If interested, the XML format of a TBX is described in aTbRef.

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 cannot 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 if you can describe the events leading up to the crash and/or a step-by-step method to consistently 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

The Register tab holds the following information:

• Name. The user's name as per the registration details (user's details greyed out in screen-grab).
• Organization. Optional organisation information as per the registration details (user's details greyed out in screen-grab).
• Registration Code. The licence code as supplied by Eastgate (user's details greyed out in screen-grab).
• (Remaining months of free updates.) The number of months remaining of access to free updates or a reminder. Or, if expired there is a click-able link to an Eastgate webpage for obtaining upgrades.
• Anonymized Data Sharing. Tinderbox anonymously reports some simple usage statistics to Eastgate make features easier to discover (see longer discussion). The default is to allow sharing. Un-tick the box to prevent sharingTbRef's author recommends accepting the default, of sharing.

This is Version. The version of Tinderbox currently being used.

Latest Version. The latest public release of Tinderbox.

Tick/Cross. The tick symbol indicates the supplied registration code has been successfully applied.

A text prompt indicates where to find Document Settings.

General

The General tab has the following controls:

• User Name
• Check spelling as you type
• Show toolbar in new document
• Recognize #Prototypes and @Places in Note Names
• Enter key
• Enable Al Integration in this document

Text

The Text tab controls various defaults relating to note text ($Text):

• Paragraph Spacing
• Text color
• Background color
• Text link color
• Smart quotes
• Underline on ⌘⌥
• Colored text links
• Update after renaming
• Text Font
• Alignment
• Displayed Attributes date format

Maps

The Maps tab controls various defaults relating to Map view (although some may be used in other views too):

• Map Font
• Map interior scale
• Background Main Color
• Background Accent Color
• Background Pattern
• If note name is too long
• After linking
• Opaque Adornments
• Adjacent Notes Form Composites
• Texture
• ^⌥⌘ zooms out

Outlines

The Outlines tab controls various defaults relating to Outline view (although some may be used in other views such as Chart):

• Charts and outlines have:
• Underline alias titles
• Prototype highlight color
• Outline Spacing

Accounts

This tab holds account criteria for various tools with which Tinderbox can communicate.

Readwise

This is for Readwise data import, and the box should hold the users Readwise Authorisation Token.

Zotero

This is for reference management using the Zotero app. There are three inputs, the first two can be obtained from the Zotero user account Settings page as https://www.zotero.org/settings/security. As user wishing to use this feature will need a (free) online account even if using the macOS native desktop Zotero app as he latter does not generate these codes. The three controls are:

• ID. The users' Zotero ID, a seven figure number.
• Key. The key from account settings.
• Style. The desired publishing format. The default is "apa". You can use any format installed in your Zotero app/account (i.e. you can add other formats besides the default installed formats).

Colors

The Colors tab controls selection of the current colour scheme in use in the document. The default is 'Modern'. The list shows both built-in scheme and any stored in the Tinderbox support folders. Read more on colour scheme files.

The left list box lists available scheme. When selected, a sample bitmap (if supplied) illustrating the scheme is displayed on the right.

Note that from v8.0.0, Tinderbox's colour schemes have been given an overhaul. In support of these improvements, several old colour schemes have been dropped. This means new documents will have a different set of pre-defined colour schemes. Note that for new documents created in v8+ on OS versions (10.14+) with dark/light modes the document is given a different default colour scheme. The current built-in schemes (and defaults)

• Coral
• Dark Coral (default for new TBX files in OS dark mode)
• Franchi
• Green
• London
• Modern (default for new TBX files in OS light mode)
• Postmodern (added in v11.5.0)
• Solarized
• Sorolla
• Standard
• Storyspace
• Sunny
• Sunny Dark
• Tinderbox 7 (default v6-v7 and closest to colours matching colour names)
• [user colour schemes in the user's 'color schemes' app support folder, if any, list at the end]

The colour scheme format has been extended to accommodate a wider range of appearances. Experimental support has been added for colour schemes that use dark background colours, in part to determine how difficult this may prove. Tinderbox has always assumed that map and text panes had fairly light backgrounds, but there has clearly some interest in dark colour schemes, especially since the macOS 10.14 introduced a dark mode.

'Modern' is the light mode default, replacing 'Standard' in older versions; in this scheme, the map background colour, and the colours 0-9, are slightly bluer. "Dark Coral' is the dark mode default. For those who do not primarily work in map view, the colours in 'Modern' may be hard to tell apart when only used for text or icons. In such circumstances

For those with TBXs pre-dating v8 and who work in dark mode, applying 'Tinderbox 7' should give a better result. The issue this solves is that older colour schemes were not aware of the colours changed when toggling OS dark/light modes and so did not (re-)set some colours accordingly. All the schemes above have been updated to allow for this issue.

When applying a new colour scheme, if the scheme changes $TextFont, notes that use the old (scheme's) text font will be changed to use the new scheme's text font.

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 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 windows termed a 'main view' pre-v6; these are now simply the view pane's content visualisation options. There are a number of types of view used by the view pane, as listed here.
• 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 full 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 the 'secondary' views and windows from earlier Tinderbox designs have become pop-over dialogs (and thus essentially modal); a few such pop-overs 'torn off' text windows can be created, by dragging them to become stand-alone windows. Pop-overs 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

A Tinderbox document has two basic kinds of structure: one is the structure formed by links between notes. The other is the hierarchical structure of the document. A Tinderbox note can contain other notes, which can contain other notes, and so on. The notes can thought of this as chapters containing sections containing divisions; or topics containing sub-topics; or in any way that fits the user's workflow.

In the image for this article, the 'MyString' column shows the relevant designator (in correct case-sensitive form). Note that designators are case-sensitive when used in export/action code; by convention designators are normally not quoted in action code, although they are strings. The OutlineDepth column shows the $OutlineDepth for each note (1 being root level).

IMPORTANT: inheritance of attribute values (e.g. via prototypes) is not a feature of hierarchy. Put another way, a child note does not automatically inherit all its parent's customisation: that may be made to happen but will require the user to add some action code.

Several terms are used to describe relationships within a hierarchy:

• parent: the item one level up. A parent note contains one or more child notes (children), and thus contains one or more levels of sub-notes. A parent note may also be referred to as a 'container' as it contains other notes. ('parent' designator)
• sibling: an item that has the same parent. ('firstSibling', 'prevSibling', 'nextSibling', 'lastSibling' designators). The group designator siblings means all items with the same parent as the current item.
• child: an item one level down. In Tinderbox, when a note contains other notes, those notes are its children. A child note is thus any note that has a parent note, i.e. it is not a top level note. ('child', 'lastChild', 'randomChild', 'previous' (child), 'next' (child), Nth child (zero-based) 'child[N]' designators).
• descendant: a child, or a child of a child, and so on, of the current note.
• ancestor: a parent, or a parent of a parent, and so on, of the current note.
• grandparent: specifically the parent of a note's parent. ('grandparent' designator)
• root: an item that has no parent. In a Tinderbox document, the document as a whole is the root: it contains the top-level notes, and nothing contains it. Root level notes have $OutlineDepth of 1. Root is not used as a designator but does have a role in export code: see ^root^.
• cover: the first root level sibling. Thus, if there is more than one root-level note, the cover is the oldest sibling. ('cover' designator). This is little used in Tinderbox and has more purpose in its sibling program Storyspace.
• original. The note upon which an alias is based. ('original' designator)
• this and current. These generally mean the same thing. 'this' applies to the currently selected item; where transclusion is used (e.g. during export, see ^include^) current applies to the note in current scope of evaluation.
• agent. This is a method for agent queries to refer to the agent's attribute values and for aliases to refer to their parent agent in agent actions. ('agent' designator)
• adornment. Not illustrated, as only used in map view. It fulfils the same role as 'agent' in adornments and smart adornments ('adornment' designator)
• ID. Not a hierarchical element, but an item's $ID value (a 10-digit number) can be used as a designator.

Not illustrated: item-scope designators: 'that' and 'find()'.

There are several group terms to describe Tinderbox notes:

• all: all notes in the current TBX file. ('all' designator)
• ancestors: all ancestors. ('ancestors' designator)
• children: all children. ('children' designator)
• descendants: all descendants, i.e. all children and their children. ('descendants' designator)
• siblings: all siblings. ('siblings' designator)

Any note containing other notes is a 'container'; put another way, a container is any note that has children/descendants. Agents are a special class of container, holding an alias to every note matching the query stored in their $AgentQuery attribute. Map adornments are not containers. Though not originally intended as such, outline separators can be used as containers.

Paths

) evaluated resultTinderbox 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 action code 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 Action Code

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

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

…would collect the $Text of a note named "3" at path /Tasks/3.

Paths with Designators

Most Tinderbox designators can use a path to refer to a different context. For example in action or export code use:

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 $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, not recommended

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 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. Some system attribute properties can be altered via the Document Inspector System tab.
• 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. Some user attribute properties can be altered via the Document Inspector User tab.

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.
• Added to by new Tinderbox versions. At creation of a new TBX document, Tinderbox adds all the currently defined system system attributes with their existing properties, default values, etc.

**Opening the document in later releases will add any 'missing' system attributes added to the roster since the originating (or last-used version). These new attributes use current defaults.

• NOTE: pre-existing attribute defaults are not updated. Even if the newer Tinderbox version has different defaults to those in a pre-existing document, these are not updated. It is down to the user to update these if required. Changes to system attributes (if documented) are reflected in aTbRef's listing of system attributes where the current default is given.
• reference derived values. Some System attributes will have a default value which is set via preferences in Document Settings and inherited from there (unless inheritance is broken by manually setting a default in the System Attributes Inspector)

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.

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.

See also:

• Offset addressing or referencing 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

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

Action Code Expressions

Using in the context of Tinderbox Action code, an expression is a combination of values, variables, and operators that Tinderbox computes. This computation results in a new value. Commonly, that new value is then stored in a system or user attribute.

Used widely, in programming and data manipulation, 'expression' is a common concept. For example, an 'expression' can be a repeatable recipe use to calculate or derive information based on existing data.

In the context of Tinderbox, expressions are used to define values, set conditions, or perform computations to automate tasks and customise data handling.

A Tinderbox expression is normally a part of a complete Action code action (though in some edge cases the two are functionally the same).

See more at:

• Expressions vs. Actions in Action code.
• Action-based attributes.

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
• Creating a new user attribute
• Renaming an attribute
• Correct setting of Font names as attribute values
• Attribute Data Types
• Determining the data type of an attribute
• Default values for attribute Data Types
• Document versus Application: system attributes and defaults
• Keywords for Date-Type Attributes
• What are Displayed Attributes?
• Pre-populating Displayed Attributes pop-up lists
• Attribute inheritance of preferences and settings
• Intrinsic attributes
• Action-based attributes
• Attribute Listings
• Editing attribute values
• Setting or resetting an attribute's document-level default value
• Attributes - $ prefix notation
• Change to Number-based opacity attributes
• Testing for local attribute values