Tinderbox Forum

Easiest way to concatenate notes (transclusion)

Really basic question but a new concept for me in Tbx.
What I the easiest way to produce a single note containing the text of several other notes in a particular order?
Do all of these notes have to reside in a single Tinderbox document?

There are other ways that readers will suggest, one of these is a stamp such as


This can be applied to a parent note that is the destination of the transclusion, and the children are the transcluded notes.

Your example would require all notes to be transcluded to be children of that note, correct? If so, they’d be referenced by their position relative to the parent note. Could they also be referenced by the title of the note or some other attribute?
Would this only work in a single Tbx document?

Not sure exactly what this means, but this method will sort the children (for Collection purposes only) by an attribute – e.g., by a user attribute called $Rank.


Yes. It’s not possible as far as I know to access the content of other Tinderbox documents this way.

BTW, you don’t need to limit the method to collect the Children. You can use other Group Note Designators including find(). And you can collect other attributes. And the destination does not have to be $Text. The flexibility is somewhat overwhelming at times.

I am not expressing myself very well, I am afraid. What I am looking for is a way to designate which the notes that will be concatenated are going to be, the individual transclusion nuggets if you will. Imagine a largish Tinderbox file containing some notes scattered all over the place that would make sense put together.

Your example presumes the all the notes that will be concatenated live in a single place in the hierarchy (I am assuming that an agent looking for a certain properties might do that job as well)
My last question was whether attributes other than position in the outline hierarchy could be used as well to designate a particular note anywhere in the file to be part of the concatenation. I hope this is a little clearer now.

As I said, you can use other Group Note Designators including find()

aTbRef explains all this and more. I’ll drop off here – I’m sure someone else knows this stuff better.

Your last answer arrived whilst I was trying to explain myself better but it looks like you had anticipated what I had difficulties stating already.
Tinderbox is a little overwhelming at times but I now know where to dig, thanks a lot.

As @PaulWalters says, there is a huge range of expertise among people on this forum. I’m not an expert, but here’s another specific illustration of how you might get what you want:

  • Yes, it’s true that any search or operation needs to be within a single data file. The files can be huge, but all TB operations I’m aware of occur within one specific file.

  • If it happens that the notes you’re wanting to combine are all already within a single container, then (as noted) you could just do an exercise like the one mentioned above, as a Rule for the parent note, eg: $Text=collect(children,$Text).format("\n") The final dot-format command will separate them with line breaks, but you could add any other separator you want.

  • If it doesn’t happen that the notes are already in one container, then you can create a virtual container that includes them, by selecting them with an agent. For instance, you could look for ones that contained a certain word in the text, or that had a certain flag set ($Overdue==true), or that had any other characteristic you wanted to identify (eg $Context=="ResearchNotes"), and so on. Then you could have this same rule $Text=collect(children,$Text).format("\n") for the agent note itself, since all of the notes matching the search criteria would be its children.

  • Also a mentioned, as part of the agent (or any container) you can have notes sorted by any criterion that the program can recognize – alphabetic sequence, creation time, or any other attribute. (If it’s a normal container, not one created by an agent, you could also sort them manually).

In short, there is almost certainly one way for the program to do what you want, and there likely are three or four ways. The easiest way to develop some comfort with the procedures is to start with a very small and simple test sample, and go from there. I think that is how everyone using the program has gotten going with it. Good luck!


An additional method that support the Preview view and exports is to include in the $Text of a note:


This will grab the text of the three notes and put a line break after each note’s text.

(In my opinion, this is truly a case of transclusion, whereas most of our other examples are not.)

Sorry for the prolonged silence but this time I wanted to do my homework and not ask questions that I could answer myself (although I managed to do it anyway)

With your last example you guessed precisely what I wanted to do, Paul.
After I started over in a fresh document your code worked flawlessly, thank you!

Of course, renaming the original note will break the transclusion. An alternative solution that would allow this would be to substitute the name of the note with their ID, like so:

In which case the renaming of the note entitled “pawpaw” has no effect on the result. The broken transclusion attempt can be seen one line above).

Incidentally, why would the attempt to transclude a target that does not exist result in “text trying to include itself”?

Anyway, many thanks, I learned a whole lot, this forum is a goldmine of information.

1 Like

I noticed that when I was testing. Obviously it’s a good thing to get an error message. I think that if Tinderbox cannot resolve “raspberry” in ^text("raspberry")^ then it interprets the request as ^text(this)^, which is self-referrent – hence the error message – and therefore the request abends rather than attempt the recursion.

A error such as cannot locate "raspberry" might be friendlier.