First serious Tinderbox project

I’ve gone from playing to dabbling to some more significant work with Tinderbox and I’m now about to start what will hopefully be a long term process.

The background is that I have studied and worked with someone over the course of several decades. My objective is to consolidate what I know, learn new things and think through / develop my own thinking based on all this. It seems like a great fit with tinderbox.

The resources that I will draw upon are:

  1. My own existing experience and knowledge
  2. Word documents of 1-3 pages ( a few hundred)
  3. Word manuals of 60-200 pages (about 35)
  4. Audio recordings of 1-7 day courses with one audio file per day (about 300)

I also have access to Devonthink and my first thought is to use Devonthink as a repository for items 2-4.

I aim to start capturing item 1 as tinderbox notes but I would like to get links into specific parts of items 2-4 from a tinderbox note so that e.g. I record a thought / idea / concept and then link out to a relevant audio section (maybe start playing a file from 3mins 30 secs in until 5mins 10secs. or maybe link to a section in a manual or to a specific word doc.

Currently I have no plans to export / create any substantial material myself but I think it prudent not to rule it out.

so my initial questions are:

  1. is devonthink a good fit with tinderbox for this approach? could I just use a finder based approach maybe?

  2. how do I do the linking to specifc segments of word and audio files? (maybe also pdf’s)?

  3. are there any considerations to be careful of up front to allow for export at a later date?

Q1. Yes, there are those with deeper DEVONthink expertise here, but at the general level. The upside it you don’t need import loads of docs/text that you don’t regularly read in Tinderbox. Both DEVONthink and Tinderbox(and some other apps) support ‘pseudo-protocols’. These look like https:// URLs but start with something like the name of the app, e.g. for DEVONthink the DEVONthink URL pseudo-protocol. Very easy to use. Leave the detail for when you start implementing.

Q2. Audio: there are a number of possible methods but if not and obscure format, the URL-style approach works well and you just state the offset (usually in seconds) from the start of the audio (and/or video). Word is harder. I think Micro$oft really would prefer you only use M$ products (ker-ching $$$$): think ‘embrace and extend’. There are some hints around (e.g. here) but interestingly, they are mostly for old formats of Word suggesting that loss-of-revenue hole has been plugged with new limitations. You might do better to ‘print’ the Word DOC/DOCX to PDF and put those in DEVONthink in which case the URL-based method can be used with bookmarks.

I’m very happy to be wrong about deep-linking into a Word Doc. But everything I’ve found suggests no—at lerast anything a mere mortal might try.

Q3. Actually, yes. The simplest is to thing ‘addressability’ can you describe desired content, and easily access that. For instance, a really good source or quote might be paragraph #15 of a doc. If it’s all of para 15 and you’ve recorded that fact. it’s exportable later and you can relax for now. If it’s just somewhere in a 10,000 word essay, you want to mark where. It Tinderbox, note text ($Text) is easily addressable (for action/code code) are paragraph level. Below that you might want to cache a smaller slug of text (e.g. a quote) as a note, note attribute, or a note stored in DEVONthink. If you don’t know if you’ll ever need to export you planning to the above level will avoid lots of extra make-work when/if you come to export.

For other readers here, who know form outset that they will export, then yes do embrace any possible constraints from the outset even if the export phase comes later.

A last point re ‘local’ URLs/pseudoURLs. I’m assuming you’re working on one Mac. Tinderbox os not a multi-user app. You can open the same file from different Macs but:

  • Only open it on one Mac at a time. Tinderbox doesn’t file-lock on open, so you the user need to be diligent at closing the doc in Mac A before opening in in Mac B.
  • ‘local’ really means assets on this Mac. Some apps like DEVONthink may (licence level dependent) allow links across your local network (e.g. within your house/office), but check if unsure and planning to use multiple Macs for work.

Best to check your assumptions re those bullets before you get going. It can save some hassle early on by starting down a path of assumed process that can’t be made to work.

So, unless you need to work on the data on your phone on long-haul flights, I think your covered. Hopefully the DEVONthink veterans here can backfill some detail of use of Tinderbox+DEVONthink.

I hope that helps. :slight_smile:

†. As I write, I’m going through a 12k+, >400k words TBX doing re-structure. Back in 2016 [sic] I’d planned for CSV/Tab-delim table export but now I’m being asked for JSON instead (and for good reasons). This means a degree of re-stating how some detail is ‘linked’ (cross-referenced) so as to make sense in JSON. Still, it’s no big deal—the joy of Tinderbox is it’s a little unexpected work but not a complete do-over as it might be in many other apps.

You’re thinking of a pretty complex, though interesting project. So, rather than diving into the details from the outset, I suggest roughing out in Tinderbox an concept for how the structure of the overall project might look when it is complete, from the 10,000 foot level. A roadmap, perhaps. What are the main themes in your mind, how might they fit together. This isn’t an outline, but an initial concept. As you then work through the details the whole concept will of course change. But, it’s always helpful to periodically step back and go up to the 10,000 foot level to once again sketch out how the work is going, and if it needs simplification or redirection.

I second the suggestion to put the big data dump into DEVONthink and then link to it as necessary. You can even create notes and annotations in DEVONthink for your documents, and import those into Tinderbox to work with. That is probably my most common working method.

Links to specific text in PDFs in DEVONthink are possible, then use that link in Tinderbox text, or as the URL attribute for a Tinderbox note. (DEVONthink calls these “Selection Links”, created via the contextual menu when working with a document.)

You can also import .mp3 (or a few other formats) into DEVONthink and grab a link to specific time of the file (a “Frame Link”, which is a bit of a misleading description, but it works):

All links mentioned by @mwra and me are in the form x-devonthink-item://….

1 Like

Thanks Mark and Paul

I’ll experiment with Devonthink links then.

The word docs are all pretty much fixed so I think I’ll just run a big batch conversion to PDF’s to save any headaches. Most of them are versioned anyway so if one does change it will be good discipline to up the version and freeze to PDF.

with the audio do I have to use devonthink links or can I do that directly with tinderbox?

Personally, I wouldn’t bother with a mass conversion of .docx files. If you add them to DEVONthink, then DEVONthink’s search can find their content, and DEVONthink will display the Quick Look content of the document. If you need a .pdf from one of them (or a selection of them), then DEVONthink has a command to convert the .docx to OCR’d PDF or to other formats, on the fly.

Will DEVONthink allow an inbound devonthink:// link to a location within such a record, e.g. to a particular page? Cool if it can.

(Sorry my question isn’t by way of countering the well-made suggestion above—lest it appear so. I’m just wondering about the finer point of linkage as I’m no DEVONthink expert. :slight_smile: )

yes - DT can link to a specific page:


Links are available to a document, to a page (in a PDF), and to a specific string – all from the same document, all created via the command menus in DEVONthink – no need for the user to figure out what codes to use:

Document: x-devonthink-item://2F595F61-6C96-47D5-A965-8E1CDA649886

Page: x-devonthink-item://2F595F61-6C96-47D5-A965-8E1CDA649886?page=1

Selection: x-devonthink-item://2F595F61-6C96-47D5-A965-8E1CDA649886?page=1&start=1&length=27&search=I%20am%20a%20string%20in%20a%20document

To be clear, I’m asking specifically about linking to MS Word-format documents, e.g. Doc/DOCX, and only because it is pertinent to the OPs question. References to “in a PDF” suggest the above might work only for PDFs.

I was a fairly sophisticated word user in the past and have just looked into the current situation. Using word bookmarks you can link to a bookmark from another word document (so probably other office 365 apps too). It doesn’t work outside the MS Office apps though.

Essentially create a hyperlink in the source word document to the pathname of the target word document and add #bookmarkName to the end of the link path.

There is an official MS apps published uri scheme here but having tried it the #bookmark syntax doesn’t work.

1 Like

Generally, one can have an x-devonthink-item://… document-level link to anything: to any document type, in a DEVONthink database. These are called Item Links. Everything in any database has an Item Link, and the Item Link, once clicked, will open the linked document regardless of whether the database is currently open, or the DEVONthink application is currently running.

PDFs are the only document type that can have more granular x-devonthink-item://… links to “pages”. PDFs can also have x-devonthink-item://… links to selected text (including annotations) within the PDF.

As @Chris_N points out, links to .docx pages or other Microsoft-type documents are not possible in DEVONthink.

DEVONthink is a very feature-rich application, and rather than cherry-pick this or that feature, the new user is advised to have a copy of the manual which is very well written and searchable. I keep all my manuals for all the software that have them (including DEVONthink) in a database for easy reference and annotation.

1 Like

Many thanks. this is really useful fine detail. I’m not entirely surprised at the limitation Word places on inbound links. Still, the app predates the Web and also has commercial constraint issues to navigate.

For me, none of this goes against your useful advice upthread to leverage DEVONthink (if a user has it) to help mine into the initial trove. I see there is an ePub version of the manual. As that is essentially a packed HTML website, it offers some interesting opportunities for exploration of the corpus.

Thanks again.

Thanks for the advice Paul here and below. I’ve been doing the 10,00 ft exploration (using Tinderbox!!) over the last few days and it has already revealed a lot more to consider.

I’ve been exploring and playing some more and am now reconsidering the use of Devonthink as a repository for the word docs and the audio.

I’ve written my first ever applescript and it works to open a word doc and take me to a bookmark. I suspect I can even not change the documents at by adding bookmarks and go instead to a page then find text but haven’t written that yet.

VLC player which was my preferred player when I used PC’s does support url pseudo protocol with start and stop times for audio.

So I’m thinking of having attributes with the word, audio and other file references that I can then use in a runCommand to execute applescript that will take me direct from Tinderbox to the source in question. I have played with a stamp for this but would welcome suggestions about how best to run the script on demand as I’m learning all this from scratch.

I may still use Devonthink but index rather than import the files. Tinderbox then becomes the place for all my own notes and thinking and Devonthink as pure repository and search mechanism.

In case it helps someone I’ve added my little applescript script below

============= AppleScript below here =======================

use AppleScript version “2.4” – Yosemite (10.10) or later

use scripting additions

script to open ms word if required and go to a specific bookmark

set PosixPath to “/Users/username/Downloads/Tinderbox/tbx Testing DBM Summary of Models 2014 v2.docx”

– Convert POSIX path into colon path

set theDOCX to (POSIX file PosixPath) as string

tell application “Microsoft Word”


open file theDOCX

set bkMark to bookmarks of active document whose name is “tbxTest”


select (item 1 of bkMark)

end try

–close active document saving yes

end tell

–tell application “Microsoft Word” to if it is running then quit


I wouldn’t go through runCommand as that way you’ll likely run into headaches “escaping” for the shell.

AppleScript can retrieve the attribute values directly from Tinderbox.

Thanks Sumner - not too sure I understand completely but I really am only just starting.

So, I would be reading a Word document and decide to make a Tinderbox note which references the place or a text segment in the document. So as a first approximation of the process I would

  1. create a named bookmark, grab the path and name of the document. (I would have at a more global level the starting root where all the assets are stored).

  2. make my note in Tinderbox and store name, path, bookmark as attributes

Probably keyboard maestro for that.

outside of that I would have a stamp that I can apply to the note at a later point that essentially runs whatever script I end up with that picks up the attributes from the note. I think I just need to get the stamp code correct just once.

One issue with this route is that I’m limited to one reference per note

Instead of a stamp (which would require runCommand and struggling with shell quoting) I’d think in terms of using an AppleScript that “directly” retrieves the attributes from the note and uses them to find the bookmark in Word. For easy access that AppleScript can be placed in a Shortcut (in the built-in Shortcuts app) and pinned to the Menu Bar, or placed in the Script Menu, or Services menu, and/or assigned a keyboard shortcut, etc.

Though not often advertised, Tinderbox has robust AppleScript support (check out its AppleScript Dictionary in Script Editor and look in aTbRef). Some of the examples in AppleScript in Help > Tinderbox Help are a bit awkward so I wouldn’t really on them too much, though they give an idea of what can be done.

@Chris_N Sounds like an awesome project. It mirrors my effort to complete my doctoral dissertation with Tinderbox. Over the years, I’ve developed a ton of methods/processes/approaches and tips and tricks for tackling this type of work. In fact, I call the method the 5Cs (collection, curation, creation, collaboration, contribution) knowledge management process. Works great.

For me, one of the biggest breakthroughs was to work backward from the type of contribution I wanted to make, i.e., I focussed on the outputs and thinking through through the inputs that I needed to get there. This then led me to develop all the requisite mental models and skills to pull all the pieces together.

I’ve evaluated a TON of tools for this kind of work. Tinderbox is central to what I do now. There is nothing like it in the world.

As you venture into a big project like this, I’d encourage you to consider several important structural considerations:

  • Map view vs. outline view thinking
  • A container for your project/writing
  • A container for your “resources,” i.e., those items (terms, references, places, entities, etc.) that will be reusable and referencable across all your writing
  • A config file to store reusable values (dates, pats, etc.)
  • Judicious use of attributes and prototypes
  • No one tool can do it all, not even Tinderbox (see below).
  • Start with “What is it that I want to get done?” and then figure out the how. I’ve learned with Tinderbox that there are several ways to get something done, the answer you land on often depends on time and where your head is at.
  • When building out new action code in Tinderbox, bound the effort by using test files
  • Just get started, Tinderbox is very forgiving, you can always refind and incremental modify your work
  • Get active with the community, share your challenges/desires and your solutions (you’ll get so much more out of it when you actively engage us all)
  • …oh, so many more ideas to share (welcome to the journey)

I’d like to suggest a list of other software/tools that you might want to roll into your process eventually. Here is my near-complete list of tools that I use daily:

  • Tinderbox
  • DEVONThink
  • Zotero
  • Pandoc
  • TextSniper*
  • Text Expander
  • Snagit
  • BBEdit
  • Grammarly
  • Drafts
  • Cavas
  • Houda Spot*
  • Foxtrot*
  • Bartender*
  • Arq
  • MS Office: Word, Excel, PPT
  • Google Docs
  • ChatGPT 4
  • Languages: HTML, CSS, RegEx, Command Line, BitT4x, Markdown
  • Concepts: Atomization, metacognition, incremental formalization

* available on SetApp

I’m hosting an open Tinderbox session for my Patrons on Friday the 19th 6:00 PST. DM at @satikusala if you’d like to join. This will be the first of many sessions I’ll be hosting (eventually, it will be a course-- “Contributing Your Knowledge: Some Assembly Required”) on how to use and produce large-scale research within the Tinderbox ecosystem.

1 Like

Thanks Sumner

with that further detail I now get it a lot more. I’ve already invested in script debugger as I think applescript might become more important to me so I’ll look at the tinderbox dictionary. Inspecting the word dictionary was helpful to get me going.

I use shortcuts on my phone but will have to investigate more on my mac and the other ways of accessing were unknow to me before you pointed them out.

thanks for your help

aTbRef’s notes on AppleScript are here: Applescript.

I commend AppleScript Debugger (AD). It’s not cheap (edu discounts are available), but I find it makes AppleScript far more accessible. Apple’s own AppleScript tools have long remained unchanged as part of deliberate neglect and lack some of AD depth. For most us, I suspect, AD had more depth than we need. But we don’t have to use every menu in an app to get value from it. :slight_smile:. I keep my AD updated, even though my use is now occasional.

1 Like