Literature Review with Tinderbox


This is my workflow about setting up a smoothish transition from getting a PDF into Zotero, annotating it, extracting annotations, and pushing those into Tinderbox for further analysis. The last part is based on Discourse Graph concept, which in turn draws on Toulmin’s Structure of Arguments.
It’s been written for beginner TBX users in mind, in the hope that it will help them take the first few steps in their Tinderbox adventure. I have found projects/examples/workflows shared by other community members to be very helpful. Those Tinderbox recipes helped me not only to ‘have job done’, but also, by experimenting through tweaking parts of pre-set action code to my own preferences, to learn how Tinderbox works. I strongly believe that problem-based learning is the key for understanding complex apps like TBX (‘having the steep learning curve’ kind).
This whole workflow falls into the category of “work in progress”, so I will try to update it based on your feedback and ideas, and/or (hopefully) my future insights into the knowledge synthesis process. I find the concept of Discourse Graph and its usage in literature review intriguing - I’m not an expert by any means, just someone who likes to learn about new things.
I hope someone will find this guide helpful.

1. Useful apps

1.1 Zotero

1.2 Zotero PDF Reader

Zotero 6.0 allow annotating PDF inside their own PDF reader. You can add annotations to notes in various ways + annotations added to notes will automatically include links back to the PDF page as well as citations.

  • Zotero annotations template configuration (we’re going to let Tinderbox know what colour we’ve used in annotations. You can find more info about templates here)
    • Go to Zotero Preferences → Advanced → Config Editor → Click ‘I accept the risk’ → Search for ‘extensions.zotero.annotations.noteTemplates.highlight’ → Double-click on its value → Copy-paste code below and confirm by clicking ‘Ok’ button:

{{if color == '#ff6666'}} 	<p>||RED||&nbsp{{highlight quotes='true'}} {{citation}} {{comment}}</p> 
{{elseif color == '#2ea8e5'}} 	<p>||BLUE||&nbsp {{highlight quotes='true'}} {{citation}} {{comment}}</p>  	
{{elseif color == '#5fb236'}} 	<p>||GREEN||&nbsp{{highlight quotes='true'}} {{citation}} {{comment}}</p>  	
{{elseif color == '#ffd400'}} 	<p>||YELLOW||&nbsp{{highlight quotes='true'}} {{citation}} {{comment}}</p>  
{{elseif color == '#a28ae5'}} 	<p>||PURPLE||&nbsp{{highlight quotes='true'}} {{citation}} {{comment}}</p>  
{{else}} 	<p>{{highlight quotes='true'}} {{citation}} {{comment}}</p>  {{endif}}

1.3 Images in Tinderbox

With version Tinderbox 9.5 comes a much better support for images, so no need for workarounds anymore!

1.4 Pandoc integration

  • Install Pandoc from the official website.
  • Export your Zotero library: click on ‘File’ and select ‘Export library …’ . Select ‘Better BibTex’ as the format. By checking “Keep updated”, BetterBibTex will ensure every change in Zotero will automatically update your file.
  • Download your preferred citation style (CSL file can be found here)
  • Go to ‘TBXConfig’ note and change value inside $HTMLPreviewCommand attribute to:
X -f markdown -t html -C --bibliography=Y  --csl=Z

X - folder location of Pandoc on your machine (usually something like /usr/local/bin/pandoc)
Y - exported Zotero Library location path
Z - CSL file location path

It should look something like this:

/usr/local/bin/pandoc -f markdown -t html -C --bibliography=/Users/sjh/TBXConfig/Library.bib  --csl=/Users/sjh/TBXConfig/apa.csl

2. Literature Synthesis in Tinderbox

Download TBX file (at the bottom of this post).

2.1 Zotero → Tinderbox

2.2 Discourse Graph

  • What’s that:

Discourse graphs are an information model for bodies of knowledge that emphasize discourse moves (such as questions, claims, and evidence), and relations (such as support or opposition), rather than papers or sources as the main units.
To give an intuition for what it is, here is a figure of a visual representation of a simple discourse graph for a body of literature on bans and antisocial behaviour in online forums. You may recognize similarities to things like argument maps.

This information model (theoretically!) has high potential for augmenting individual and collective “research-grade” synthesis (e.g., lit reviews for a dissertation or grant proposal). Source

  • How does it work:
    When doing literature review, a researcher is looking for literature in some way connected to his Research Question. What he will find are theories, models, perspectives, frameworks etc. of various authors, written in the forms of Claims. Such claims are often supported by other Claims, which in turn are supported by Evidences. Authors of competing theories, trying to prove the correctness of their own theory (or ‘trying to get closer to the truth’), will present counterarguments. Mapping the relationships between competing Claims may be helpful for finding “points of disagreement” and new meaningful relationships between ideas, which can be later turned into a new article.

2.3 Literature Review process with Discourse Graph

  • Create a new note under ‘Synthesis Page’ container, name it with your Research Question, and change its prototype to pQuestion. You can add some context inside note’s $Text. We will come back to Synthesis Page later.

  • In the ‘Excerpts from Zotero’ you can find few kinds of notes: having Red square as a badge are Claims, Blue square are Evidences, Green square are Questions. There are also notes having Quote badge and the rest, common notes. Notes with the square badges have them assigned depending on the colour of highlight used in Zotero PDF Reader. Notes with Quote badge are quotes. Notes without assigned prototype are those highlighted in Zotero using yellow or purple colour. You can change their prototype if you like. As you can see, part of those have funny names like ‘Annotation of a linked quote ID …’, rename them to be more understandable.
    Important: You don’t need to import annotations from Zotero to make Claim, Evidence or Question notes, simply create a new note under Reference note and change its prototype.

  • It’s time to link! Evidence/Claim can support/oppose (Link type: ‘Supports’,‘Opposes’) Claims, and Claims can inform(Link type: ‘Informs’) Research Question. You should link not only inside the reference container, but even more importantly, between other sources’ notes. Claim note’s badge change from red square to red dot when linked to Question note with ‘Informs’ link type.

    • If you feel a need to give your link some more context, rather than merely link it with above-mentioned link types, you can do it through ‘Browse Links’ option in right-click menu list. Choose the link you want to describe, and you should see a blank space at the bottom of the box where you can write your thoughts.
  • Synthesis Map gives you an overview of your Discourse Graph. Choose a Research Question under investigation in the $ResearchQuestion. $NeighborsBetween is a number of links between the designated note (Research Question) and last node of your graph. You can start with 10 and experiment later with other values. $AgentOn turns on and off agent. To summarize: Choose Research Question from the list, enter the number, and insert a tick mark next to AgentOn. Update agents twice (hit [Cmd]+[Ctrl]+[=] twice), and turn off AgentOn. Synthesis Map agent should find all notes linked to your Research Question.

  • In the third tab, you can see your notes in the hyperbolic view. Compared to Synthesis Map view, hyperbolic view shows also Link Types other than “Supports”,“Opposes” and “Informs”. Usage of too many Link Types may affect this view and make it difficult to see (discourse graph) connections between notes. You also can’t move your notes the way you can in the Map View. There is an advantage of using this view over Synthesis Map view - you can freely link notes.

  • ‘Outline: Synthesis Map’ tab shows us number of overall Inbound links, as well as ‘Supports’ and ‘Opposes’ inbound link types.

  • Last four tabs i.e. ‘Outline: Claims’, ‘Outline: Evidences’, ‘Outline: Questions’ and ‘Outline: References’ help to track all Claims, Evidences, Questions and References we have in our document.

2.4 Synthesis Page

2.5 Other things worth mentioning

  • Prototypes pClaim, pEvidence and pQuestion use Markdown (CommonMark) in their $Text.
  • Questions inside Reference notes are there to guide reading and critical engagement with the material.
  • Notes used in this TBX file come from here.

TBX file:
Discourse_Graph_v.0.1.tbx (6.8 MB)
Discourse_Graph_v.0.2.tbx (7.0 MB)
Discourse_Graph_v.0.2.5.tbx (7.1 MB)
Discourse_Graph_v.0.3.tbx (7.0 MB)
Discourse_Graph_v.0.3.1.tbx (7.1 MB)
Discourse_Graph_v.0.3.2.tbx (522.3 KB)
Discourse_Graph_v.0.3.3.tbx (503.5 KB)
Discourse_Graph_v.0.4.tbx (525.4 KB)

That’s all. I hope this guide will be of use for someone. English is not my mother tongue, so excuse me for errors I’ve made in the text. If you have any questions, or problems with understanding because something is not written clear enough, please ask!


05/05/2022 Update:

  • Most of action code has been moved to functions for clarity and better code editing experience.
  • Bugfixes:
    • $ResearchQuestion has been changed from string to list type.
    • Fixed a logic gap in fClaimEdict. Now badge go back to red square if not linked with ‘Informs’ link type.

05/05/2022 23:35 Update:

  • With @mwra help even more and better written action code has been moved to functions.
  • Bugfixes:
    • $ResearchQuestion has been changed from list to string type back again.
  • Known issues:
    • Synthesis Map not working as intended.

06/05/2022 Update:

  • Bugfixes:
    • Synthesis Map works as intended.
  • Known issues:
    • Synthesis Map $ResearchQuestion dropdown not cleaning out old Questions.

07/05/2022 Update:

  • Added:
    • Added ^value($CitationKey)^ in ‘Synthesis Outline item’ template to show $CitationKey between square brackets, just after relationship description.
    • fSynthesisMapAction now also change container notes’ $TitleHeight and $Width to make $Name more readable.
  • Known issues:
    • Synthesis Map $ResearchQuestion dropdown not cleaning out old Questions.

09/05/2022 Update - v. 0.3.2

  • Fixes:
    • The file size has been reduced. ‘Readme’ note inside TBX document instead of having text with images, now contains a link to this thread.
    • Small query action code fixes.

10/05/2022 Update - v. 0.3.3

  • Fixes:
    • $ResearchQuestion has been changed from string to list type to help with cleaning old Questions in $ResearchQuestion attribute value dropdown.

27/05/2022 Update- v. 0.4

  • Added:
    • Instruction how to use Pandoc inside Tinderbox for showing bibliographic references in the Preview pane.

15/12/2022 Update- v.
Deleted paragraph 1.3 about working with images in Tinderbox.

I’ve lately changed my workflow substantially. I’m planning to update this topic as soon as I can.


Thanks for the shoutout.

Great references.

Note, if you’re on Chrome you won’t get the shortcut. Copy and paste this link into Safari to download the shortcut or rt. mouse click and download the file.

Is this step using. my RIS splcing action code? if so, that is not clear here. If not, how are you doing this?

@Arek this is really great stuff! Did you provide the TBX file as an example? If so, I don’t see it.

A few more things I’d like to add. I have a few videos on working with media that might be helpful: Mastering Tinderbox: Training Videos (Complete List).

Also, to enhance this flow I think the next step would be to discuss template building and the use of CSS for export. If you’re in academic work, then you might want you files in APA format. This can be done with export templates.

Also, if you use Pandoc, with the Markdown, you can have your citations automatically converted in your TBX file. See my video on this.

Again, great work!


I forgot the most important part…already updated, thanks!

Yes, it’s based on your action code you’ve shared some time ago:

  $CitationKey="@"+ $ReferenceDictionary[LB];
if($ReferenceDictionary[TY]!="BOOK" & !$IsPrototype){$Badge="📄"};

That’s a good idea, thank you!

1 Like

@ShiJianhui, this is a wonderful gift to the community. I’m setting aside a few hours to work through your advice – your post is 20 printed pages, far more effort went into it than many journal articles. It is deeply appreciated.

I hope this thread doesn’t scroll away eventually – unfortunately, though we have nice community-contributed tools like aTbRef that delve into the mechanics of Tinderbox, there is no easily referenced library of community-contributed user case and concrete advice for putting Tinderbox to deep work, other than the hit-or-miss use of this forum’s search box. (There was once; but, that’s all gone now.)


Trying to understand the code and flow: How did you make this happen?

Nice work Arek!


1 Like

See the $Edict for pClaim, in this section:

//check only original notes
if(!$IsPrototype & !$IsAlias){
  //re-initialise $MySetC, $MySetD
  // set $MySetC to IDs of targets of outbound links of type 'informs'
  // set $MySetD to current $ClaimInformsQuestionID - why, is not clear as...
  // is immediately reset to intersect of MySetC and MySetD (i.e. any values found in both sets)
// if $ClaimInformsQuestionID has any values claim has informing factors
  // set a different badge
  $Badge="🔴" ;
// interestingly the code fails to re-set $Badge were the informing claim
//   claim subsequently to be removed, e.g. disproved by further research.

The latter logic gap could be fixed bay adding an ‘else’ branch:

// if $ClaimInformsQuestionID has any values claim has informing factors
  // set a red dot badge
  $Badge="🔴" ;
  // or reset to an inherited prototype default (here, a red square)

So a claim changes from a red square badge to a red dot badge if it has one or more inbound links of link type ‘Informs’. Should the informing note’s links be removed the badge will not be reset unless the fix I mention above is added.

Now we have functions, it occurs to me that it might be easier to make the current edict into the code of a function fClaimEdict() and make the edict:


No left side is needed. All function code runs in the context of the note calling the function and this function would return no value.

This suggestion doesn’t change how the code runs but it makes it easier to edit the large amount of code and functions can be read in an open window without needing to open/re-size the Inspector. A further boon, for those of use who’ve ever edited an edict/rule in an inheriting note rather than the preview, you can only edit the function code in the note where it is stored, so less chance of editing in the wrong place.

You can have the best of both. Do initial development with the long code in the rule or edict. Then, once stable, move the code into the ‘safety’ of a function.


Yes, you are right, I will fix it asap. Thank you! @TomD I hope you this answers your question :slight_smile:

It makes sense, thank you!

Thank you very much for your kind words, I hope it will be worth your time!

No worries and no disrespect to a such a lovely document you’ve so kindly shared with us. The function aspect only occurred to whilst asweriing @TomD 's question. Being new, functions aren’t yet a familiar sight or obvious choice. Certainly, there’s no requirement to use them. :slight_smile:

Thanks again for sharing a really interesting file with the community and for all the descriptive info.

1 Like

Yes, they are pretty new, I haven’t got used to them. But you’re right about the pros of using them, so I updated the file. :wink:
Thanks for the time you spent looking into it!

Hummm… I think there might be a bug in the new code…
Ex: when I link the Claim: antisocial behaviors spread from bad actors to other users via norm-setting ->Informs → Question: Are bans an effective way to mitigate antisocial behavior online forums?

…the badge does not change.

Here is my file:

Discourse_Graph_v.0.2 copy.tbx (6.8 MB)

It could be I am missing something… perhaps I do not fully understand the way it works. This could be.


Well that was a head scratcher. I went back and forth on the code, but it appears to be an (unintentional!) error in the source doc,

when I paste the code of ‘fClaimEdict’ into BBEdit, the line breaks disappear:

Thanks to BBEdit’s character palette, the odd ‘invisible’ character symbol that look like a pipe (|) is actually Unicode #2028 the ‘line separator’. Clearly this is making Tinderbox hang. If I change these mystery characters to proper line breaks and paste back the code, the Tinderbox works OK.

I guess @ShiJianhui used some external code editor to lay out the code and it uses #2028.

I found few code code errors in checking things in file version #2 that I’ll try and post later when I get a spare moment. I suspect most result in the desired/expected outcome, but only by accident. More later.

Yes, I will have a look at the code again.

That’s truly something I would never guess could happen… The only one external code editor I have been using while writing code for this TBX project was BBedit’s CLM for Tinderbox, and maybe Apple Notes… hard to say because it have taken me some time to code it before posting here.

I would be enormously grateful! I have next to nothing (action) coding experience, so every suggestion is very much appreciated!

1 Like

Another issue I am noting… if you change your Research question in the Display Attribute dropdown for the Synthesis Map, nothing changes. Even if you change tabs, the expectation, I think is that the new question would be visible. My expectation could be wrong…

You might want to test the Synthesis map under a new question.


I’d agree! I’ve never seen this before. :open_mouth:

FWIW, what made me suspicious of invisible characters was that the comments in your function were the wrong colour, in Tinderbox, but comments I added were grey. Thus the test with BBEdit.

Here is a version of the TBX with strange line breaks fixed. I’ve also supplied alternate version of some edict functions using variables avoiding the needs for $MySetA, etc. The calling edicts use the original function, the alternate is there as an example (these functions use a ‘2’ appended to the name e.g. fClaimEdict2().

I’ve also made functions for the link actions. If you want to use the functions replace the current link action code with a call to the appropriate function. An added benefit of the function is you get syntax checking/colouring unlike in the Link Inspector’s action code box.

For some reason the Library container in you file’s ‘Hints’ wasn’t setting the ‘Action’ prototype for new children so I fixed that action too.

In fClaimEdict, you have this test:


IOW, this query which doesn’t make sense:


Queries don’t use semi-colons, so I assume you are trying to set is the set attribute ClaimInformsQuestionID has any content. You could check either of:

// or better

I’ve used the latter in the uploaded file: Discourse_Graph_v.0.2-ed.tbx (7.0 MB)

Thanks for all your feedback and help with fixing broken code!
I feel a bit embarrassed of not making sure everything works 100 % fine before sharing with the rest of the community, but on the other hand, maybe I could never be sure of that, and so never share anything…never mind, thanks again for help! :wink:

Thanks for the feedback! I will look into it


No sir, never feel embarrassed for trying. This was much better than I could have ever done!

I am proud of you and glad you shared it at this stage. It completely opened my eyes in this new direction. Job well done… Onwards!



Thanks for your kind words!

It seems to be a bigger issue than I thought. I will have a look at it tomorrow morning :wink:


No need for embarrassment. Your code wasn’t ‘broken’ but rather hit by one of the more obscure line-break glitches I’ve come across and ironically only because you generously picked up on the idea of migrating code into functions. My input was really only some polish for edge cases.

You should take heart from the genuine notes of thanks for the community here. It’s always a joy when someone takes the time to share such a built-out example and to give notes on use. Really nice to see hyperbolic mode being given a role, too.


I will, thank you!

I think I’m onto something, but can’t figure out one thing (that I’m aware of). ‘Synthesis Map’ agent seems to work as intended, with one exception - some notes are somehow resistant to agent’s $OnAdd action, i.e. they don’t get linked as I want them to. In the screenshot below, there are 5 notes in red frames that should, but are not, connected to notes pointed by arrows.

I don’t see what makes them so special. Any help will be very appreciated!
TBX file:
Discourse_Graph_v.0.2.6.tbx (7.0 MB)

$OnAdd action:

      linkTo(find($Name(parent)=="Synthesis Map" & $Name==$Name(listValue)),"Informs");
      linkTo(find($Name(parent)=="Synthesis Map" & $Name==$Name(listValue)),"Opposes");
      linkTo(find($Name(parent)=="Synthesis Map" & $Name==$Name(listValue)),"Supports");
      linkTo(find($Name(parent)=="Synthesis Map" & $Name==$Name(listValue)),"Opposes");
      linkTo(find($Name(parent)=="Synthesis Map" & $Name==$Name(listValue)),"Supports");

}; // end function