Tinderbox Forum

Ok, here goes....i'm new here. and i need a litttttle help

ok - i am deeply interested yet deeply confused by tinderbox. i can tell it will be great for me once i can make some general steps forward. so i have some questions that may be really basic. please forgive me.

  1. do notes and attributes overlap? e.g. let’s say i have 2 user attributes, person and theme. i make a note about a doc, z, that is about theme x and deals with person y. so but theme x and person y also have their own dedicated notes. can, for example, the note for theme x automatically contain an alias of the note for doc z, simply because i assigned note for doc z the attribute theme x? am i describing an agent? can an agent also have attributes? i’m sorry if this is confusing.

  2. i have documents in devonthink that have tags representing the date, all in this format - YYYY-MM-DD. is there a way for tbx to process those tags as a date attribute? (subquestion to this question: in general, is there a document that explains how dt tags work in tinderbox? like, some of the tags in the doc i could drag in might be a person, another might be a theme, another might be a place. i just am too overwhelmed to even begin, even though i’m just starting with a few.)

  3. this goes back to question 1. so i guess i’m not really sure what should be an attribute and what should be a note, because frankly everything in this book feels like both. theme would be a good example. i definitely want it to be an attribute, and i also want it to be a container. i’m writing a book that features like 300 people, 10 main ideas (chapters), 10 secondary ideas (featured throughout the chapters) and then another 25 or so recurring policies that also feature throughout the chapter. Note: I am NOT trying to do all this at once on tinderbox. but is there anyone who has written a book like this who can guide me somewhat on how they structure things?

Everything is a note.

(Attributes are just properties of notes).

yes but i am asking if an attribute is also a note, i think

Attributes are not notes. Attributes are properties of notes. For example, the name of a note is an attribute of that note, but the name itself is not a note.

This might help


A note can contain other notes. (An outline structure)

An attribute is a simple value like a number, color, string;

Notes have attributes.
Attributes do not have or contain other attributes.
Attributes do not have or contain notes.
As @PaulWalters says, attributes are not notes.

More on using DEVONthink with Tinderbox.

You might also find these articles of use. It is certainly worth taking a few moments to understand Tinderbox inheritance and prototypes. Your project would certainly benefit form using prototypes - but don’t worry about the how of that until are comfortable with the basic mechanics of the app.

DEVONThink tags import to Tinderbox’s $Tags attribute. Each tag value is a string, but that does not stop you processing the tags and detecting the dates therein.

As you’re starting down the common path of using new app B with data from app A, don’t fall into the trap of assuming B’s import is totally organised around A default export. You will guess what A and B are here, but the app names aren’t the point but the false assumptions that creep in in this scenario. I’d suggest trying to import a few DEVONThink items and see what turns up as expected and what doesn’t. That gives you some idea of what will need massaging at one or both ends of the data migration process.

I am nowhere near the level of others who have already posted replies, but here was my progress with Tinderbox:

  1. This thing feels impossible to understand.
  2. I think I might have wasted my money.
  3. Hang on… I’m starting to get it.
  4. Yes, it’s coalescing!
  5. This thing IS possible to understand.
  6. This thing is very powerful.
  7. This thing is invaluable.

I categorically promise you it will take a bit of time, but working through the Getting Started and Actions and Dashboards docs found in the Help menu really helped a lot. Be advised that Tinderbox is a dynamic application and has had updates since those were written (as mentioned in them), but the broad concepts remain sound.

Also, @mwra’s http://www.acrobatfaq.com/atbref8/index.html will be your constant friend along your learning journey. So will this forum.

Allow your competency to grow at a reasonable pace and you’ll be amply rewarded. You won’t be up to speed this time tomorrow, but it won’t take as long as you think it will right now.


@doublem’s generous comments are spot on, in my opinion.

One thing I would add is that this forum (and its predecessor) are known for helping readers at all levels of experience dig into problems and challenges with doing projects with Tinderbox. Working with real-world questions on the minds of readers is sure to engage others and advance everyone’s expertise.

So, @jd5, if at some time you are inclined to post “I’m looking to do … with Tinderbox … any thoughts on how to do that”?, you’ll probably get lots of questions to help frame the problem, and helpful suggestions for how to solution it. Browse this forum and you’ll see numerous examples.


I also second @doublem 's comments. As another new user – in early stages of @doublem 's phase 3. – I’d note two things:

  1. Choose a project, or a discrete part of a project, that you are just taking off the back burner, adding to the line-up or warming up to in the same way that you are just taking off the back burner, adding to the line-up or warming up to Tinderbox itself. That way, the project or subproject can grow in tandem with your skill with the program. I’m finding this quite enjoyable

  2. At the most general level, in just getting an initial grasp, I’ve found it useful to think of Tinderbox as a database program that has a note-centric front end – or rather 7 interchangeable note-centric front ends (map, outline, chart, etc… ). This has helped me orient myself in thinking of ways I may be able to use it.

Onwards — JM

1 Like

Thanks. All of this is really helpful. I think whats currently perplexing is what to start with. Ideas? People? Chapters?

Maybe the answer is one of each. Maybe it’s all. Or the opposite - just one thing in one category! You all are helping me find my way through to what I’m confident is a system for me. But as I navigate this, for clarity, my question about attributes is this: can a character, for example, be both a note/container and an attribute that I assign to other notes? I imagine this is an agent question - can, eg, @ejspark have his own dedicated note that includes references to other notes that identify him as one of the attributes. Let’s say I have a note about sailing that includes ejspark as the attributed fullname, because i went sailing with him. But I also have a later note about just @ejspark himself - his likes, dislikes, place in the book, etc. can I autoinclude the text from the sailing note as part of the text of the latter note?

There are classically 4 modes of documentation:

  • Introduction to core concepts
  • Tutorial
  • Cookbook
  • Reference

For reference we have the excellent atTbRef site map.

The Tinderbox Help menu takes us to some tutorial material.

The main obstacle to sales and adoption (even by those who have actually purchased) is, I think, the lack of a quick route to overall conceptual clarity about the structure and nature of the thing.

(The Tinderbox Way does aim at conceptual presentation, but in a long form, and at a pace which, while unrushed, doesn’t quite provide a quick guide to the perplexed, or a short route up the mountain).

My guess is that investment in developing a clear and tight single summary sheet, with some conceptual diagrams, might well help sales and aspirant users alike.

1 Like

@jd5, here is a sample Tinderbox file I created that can illustrate one way** to answer some of your questions.

  1. I used the built-in “Reference” and “Person” prototypes. The “Moby Dick” note uses the “Reference” prototype, and the “Herman Melville” note uses the “Person” prototype.
  2. The $Text of each note came from Wikipedia. When I pasted the data from Wikipedia’s page on Herman Melville into his note, Tinderbox add the URL for that reference and used its natural language features to find proper names in the text I pasted and populate the built-in $NLNames attribute that belongs to the Person prototype.
  3. In the Herman Melville note, I added a link to the Moby Dick note, at the end of the text, by typing “[[Moby” and Tinderbox suggested the full “Moby Dick” name of that note to autocomplete the note name and, when I pressed Return, Tinderbox added a link from the person back to the reference (“Moby Dick”). I did similarly to add a link from the “Moby Dick” note back to the “Herman Melville” note. This is only one of many ways that Tinderbox allows linking notes together. On the map, I created an “Author” link between the two notes by dragging a link from “Herman Melville” to “Moby Dick”.
  4. At the bottom of the text of the “Moby Dick” note I added a line of “export code” which looks like this:
^text(Herman Melville)^
  1. That line causes Tinderbox to include the text of the “Herman Melville” note into the “Moby Dick” note. I see the included text when I activate Window > Show Text Pane Selector and, in that selector, click the “Preview Button”. How did this happen? I added a “text” Template and assigned that template to the “Person” prototype, so that the preview pane “knows” how to display the note.

There is a lot going on here, in this seemingly simple file. I composed the document in about 5 minutes just to show a quick example of Tinderbox’s power when, for example, taking reading notes or making a database of books and their authors. I don’t suggest all of the features used in the sample document will be immediately obvious, but I offer it as an example of doing what you asked about. And something to experiment and play around with.

Moby Dick.tbx (1.0 MB)

**A strength and a challenge with learning Tinderbox is that there are numerous ways to do the same or similar thing. Each of us, more than once, has to take a breath and scratch our heads, as we learn. This is part of transitioning from stages 3 to 5 in @doublem’s progression.


I think the difficulties getting started relate to (in no particular order, and based on experience helping the Tinderbox user community since c.2004):

  • trying to both define their process and its implementation, in one document and at the same time.
  • assuming, without testing, the Tinderbox happens to work in the same manner as a tool they are more familiar with and thus further assuming certain features/functions therefore must exist of all is lost.
  • unwillingness to experiment.

Some recommendations, again in no particular order:

  • Keep a ‘clean’ master file. House rule: no experiments in this file. Either test in a copy, if a complex issue, or in a small test file. Only implement the concept once done.
  • Others style/experience/task is not your own. You won’t have to look far to find post here that essentially assert the notion “doesn’t everybody…?”. Actually, no. Aspects may be in common but, and there’s the rub, not totally the same. Much angst is seen by people wanting to believe there is an easy answer being hidden from them.
  • Tinderbox is not a utility program, IOW, it doesn’t do just one—or a few—things well. In the utitly example the tradeoff is lack of flexibility: it works so well because there is one—or a few—well thought-out ways to do the task. Tinderbox, by contrast, is a Toolbox for your notes. Instead of enforcing a ‘right’ way, it lets you build what you need but with ‘some assembly required’ and this is to be expected. If the presumed latter effort makes you roll your eyes at the ‘extra’ work, I’d remind that this isn’t a one-trick utility, but a configurable toolset that is very resilient to incremental formalisation and being able to roll back design errors in a way very few apps do.
  • Do tests in small file. Don’t do your first test of inheritance in a file with 00s of notes and the litter of failed experiments. Make a new file with sufficient info to meet the desired test and offer potential false negatives/positives you’ll want to code around these). Once that works you can up the code into a larger file. If it fails there, you’ve a new edge case to diagnose/test.
  • Do not fall into the trap of thinking using more than one TBX is ‘extra’ work. IME, in aggregate it is faster in time terms. You get to throw away the experiments and build up less cruft in your main file(s).
  • Don’t assume that the export of [app you know well] is the best most appropriate format. Tinderbox has specific customisations for a number of apps, not necessarily your favourite. For instance an import bugbear at present is MarginNote - really great for annotation, really not-so-good for nuanced export. If working cross-app be prepared to to some work in interim tools to resolve the issue that many small (good!) utilities have sub-par export features.
  • In aTbRef I have tried to provide working code examples for action and export code. But, don’t assume an input parameter is evaluated if it doesn’t expressly say so. IOW, if you use an attribute reference or a bit of action code instead of a literal value it may well be that operator doesn’t (yet!) support that degree of evaluation. There is no simple way, other than by black-box test (or documentation) to tell which parameters are evaluated.
  • Since v8 Tinderbox supports AppleScript. For import problems (see above) this may be a useful approach is drag-drop approaches don’t work. AppleScript can be daunting to dive into but a few members are quite practised in it. But, to help them help you give decent detail - don’t assume they have the same apps as you: e.g. provide the problematic ‘input’ file (i.e. output from some other doc) and show the desired outcome. For instance, in that scenario, upload the ‘input’ file and a TBX showing what you want/expect the result to be. Do, in the post or the TBX include instructions as to the process. People here are helping in their own free time and may not have time to read a long thread to guess your intent. Plus, writing things down tends to reveal hitherto overlooked assumptions and edge cases in the process.

† I’m not picking on MarginNote per se, it is just a current example. It illustrates another good point of Tinderbox - your information is all exportable and (bar rich-text $Text & embedded images) is all in plain text in the stored XML of the TBX file. Even if you can’t export from inside the app in the desired fashion (export is very flexible) you can still use AppleScript support (v8+) or read directly from the XML and RTFD in the TBX.

‡ disclaimer - I’m the author/maintainer of aTbRef: it is not a formal vendor’s doc but my own outboard manual. (I do however get a lot of useful input from the vendor in the background). I only note this as sometimes people mis-presume as to the provenance of aTbRef.

I’m sure there’s more, but that’s plenty of reading for now.


I couldn’t have said it better and it expresses precisely what I’ve been experiencing for years. On the market, what other tool can offer its users an experience that can only be found in arts, philosophy or engineering? I mean: adjusting, step by step, one’s own tool?

Somewhere on these forums James Fallows made a comment roughly to the effect that he used Tinderbox more for associations than for hierarchies. I found this a valuable idea. Organising things by putting them into containers and sub-containers several layers deep (as one might with some other programs) is, for me, not a good way to work with material. I find there is more flexibility and power in making associations via links, metadata, tags, keywords, or whatever you want to call them.


Indeed. Which reminds me to add another tip, re a map-based approach:

  • Don’t make your main document map at the root, add a container to the root. By the time you understand why, you’ll thank yourself. At its most basic, you aren’t cluttering up your maps with containers to prototypes, templates, etc.

If going a map based route for a task, do consider scale. Maps with 00s of notes aren’t going to be fun to work with, even if only because of screen size.

The joy of Tinderbox is you don’t get just one view nor are you forced to use one view. Different views can help provide different cross cuts on the overall project.

If an end point is to export some kind of (sections of a) long-form document then you’ll probably want to end up in an outline. But again, view & doc structure aren’t fixed. If you are given to using links, the hyperbolic view (still very now) offers some interesting ideas.

1 Like

Hi JD and welcome to the Tinderbox tribe!

Here are my some suggestions which worked for me…

  1. IMO, one of the best discussions I remember reading regarding getting started with Tinderbox came about in 2015 from a newbie (at the time). Here is how the discussion began and evolved. http://www.eastgate.com/Tinderbox/forum//YaBB.cgi?num=1421254289

  2. The problem all of us (speaking for myself of course) have fallen into with tinderbox is that when we are getting started, we all try to make tinderbox work like other software. That assumption and prior history does not work well here mainly because there is nothing else like it. Its a note taking software at its core but it also a wiki (kind of, except without the CamelCase) a pseudo graph database, an advanced outliner and a very advanced mind mapping software. Take your pick. Build and use the tool you want or need…but…always start simple, until, at least, you have some “wind under your sail”.
    When I first began, all I did, was focus on creating a bunch notes and arrange them in map view to organize them. I would then, switch to outline view then create new notes. The focus here was to find relationships between them. A funny thing happened for me, soon I realized the relationships became just as important as the note itself. In some cases, even more important. My advice, pick a task: take notes on your journey with tinderbox, take reading notes, type some daily journal thoughts…anything. Just start writing in tinderbox and begin very simply. That is it. Build a foundation with the basics: create notes, organize them, view them in different ways. Attributes and other topics will come later…when you need it.

  3. Take time each day using tinderbox. Keep track of things, just write in tinderbox! You will make mistakes, get confused and finally figure things out. Things will always take more time at first. Later on: explore structure and attributes. Maybe try export (don’t forget simple copy and paste is all used at the beginning with composites and using the attribute browser…search for it… JFallows helped me here)

  4. Look for examples at this stage: I found the actions and dashboards help file really helpful here. The trick: read along while you have the associated tinderbox file open. It is included within the section but here it is: http://www.eastgate.com/download/ActionsAndDashboards.dmg. Look for other examples by using the forum.

  5. Read The Tinderbox Way (by Mark B…twice) and atbref (by Mark A…I still use it all the time as a reference)

  6. Stay with it. Read the forum every day. Ask questions as you did and search the forum for a similar question using key words. This worked well for me.

MarkB, MarkA, PaulW, BCrane, JFallows, MartinBoycott-Brown, dominiquerenauld and many, many others (way too many to type here) have poured their hearts and years of Tinderbox Expertise into this forum and have made Tinderbox a truly, one of kind mac app. It honestly has become, my most favorite and gratifying app to use. I look forward to using it every day.

It is the single reason, I have remained on the mac platform for so many years…Tinderbox for me has become irreplaceable.

Hope this helps…



If going a map based route for a task, do consider scale. Maps with 00s of notes aren’t going to be fun to work with, even if only because of screen size.

Big maps have gotten a lot nicer to work with in recent releases. Of course, at some point your screen isn’t big enough, and you have to do too much zooming and scrolling.

I move back and forth between map, outline, and hyperbolic views all the time.

1 Like

this is phenomenally helpful, all. thank you so much for your generosity and spending time working through this with me. i’m quite grateful.

1 Like

@jd5, we want to know what happens next … please stay in touch on your way. :wave::wave:

1 Like