You can convert a large text note into several smaller text notes by specifying where Tinderbox should make the divisions. There are options for where splits should occur and what text should be used to title the resulting notes.
This process can be used to help with the import of data as well as for existing notes. For imports, drag, a plain text format file into an Outline or Map view, so as to create a new note. Now with that, or with a large existing note selected, choose Explode… from the Note menu. This presents the Explode dialog.
Next, decide whether to create each new note after a certain number of characters or after a delimiter such as a period, then click the radio button next to your choice. The choices are:
- Break at paragraphs. Breaks each paragraph into a new note (default option).
- Break at tabs. Breaks on every tab or tab sequence.
- Break every. Change the number of characters after which to break the existing text.
- Delimiter. Break on a delimiter. The delimiter is a string of character(s) that immediately precede the break point. Delimiters you can use include:
- \n (new exploded notes will begin with new line feed character). [More on line end character codes.]
- \r (new exploded notes will begin with each carriage return or hard line break).
- \t (new exploded notes will begin with each tab, e.g. for tab-delimited content pasted into a note).
- \, (new exploded notes will begin with each comma, e.g. use for CSV content pasted into a note).
- Otherwise use a custom string of your choice, e.g. a sequence of characters unlikely to occur in normal copy, e.g. '####' or 'XYXYXY', etc. The text is case-sensitive. Use of regular expressions is not supported for this option.
- Delete delimiter. Only available if the 'Delimiter' option is set (default = not ticked). Tick this to remove the specified delimiter from the new exploded notes. When the delimiter is a complete line/paragraph, ensure the string used includes the line return character at the end or some output notes will have text starting with a blank line.
The Explode button starts the Explode process using the choices set above. Focus remains on the exploded note.
The newly created notes contain an appropriate segment of the original note. There will (should!) be no empty notes, such as those that might arise where two hard line returns are used as faux paragraph breaks, as these unwanted outputs are automatically deleted as part of the Explode process. Empty notes will not be emitted for sequences of multiple paragraph breaks, i.e. sequences of greater than two breaks.
The Title settings give control of what part of each newly split note is used to form the note's title, doing so by a measure of sentence or paragraph. A 'sentence' is delimited by a terminating period, exclamation mark or question mark. A 'paragraph' is delimited by a line break.
- first sentence. Only the first sentence forms the new title.
- first two sentences. Only the two sentences form the new title.
- first paragraph. Only the first paragraph is used for the new title.
- Remove title from text. If selected the text used for the above choice is deleted from the new note's body text.
- Omit text. This results in only a $Name being set for new notes and no $Text.
When Explode constructs a note title, the title may now extend up to 512 characters, and will include either the first line or the first sentence of the target note - whichever is the best fit. If still over 512 characters the title is truncated at that point with an ellipsis. In some earlier versions pre-v5, truncation occurred at about 64 characters.
What results from an Explode?
The exploded (source) note itself remains unchanged and a new child container of the selected note is created, called 'Exploded Text', and which contains the resulting new notes (i.e. the individual exploded notes are grandchildren of the source note). Each note contains as its text a section of the original text with the notes being titled according to the choices made before exploding. Using a secondary container for the notes might seem odd until you realise this allows for the fact - more so for exploding existing notes than for new import - that the note being exploded might already have children; thus the new notes are separated from existing children of the exploded note.
Also notice that the 'Exploded Text' container is added to the outline order after any pre-existing child notes for the exploded note, i.e. is is the last child (and thus easily accessible via the lastChild designator, amongst others).
The 'Exploded Text' container inherits all of the source note's attributes except $Rule and $OnAdd. Prior to v5, the 'Exploded Text' received the source's $Rule and $OnAdd but this proved not to scale well with more complex tasks like running command lines on the exploded notes. However, accessing the source note's actions is still possible, for instance this $Rule in an exploded note:
$OnAdd=$OnAdd(../..);
Of course, the constant name of the container holding the new notes ('Exploded Text') makes it easy for agents to fine and work on the new notes' actions. Be aware that unless the 'Exploded Text' is cleaned up or renamed after an explode, there may be more than one container of that name. A benison of this is that it is possible to write a generic agent to act on the contents of all explode results using an $AgentQuery:
$Name(parent)=="Exploded Text"
By adding a preceding descendedFrom() query argument to the above query, the scope of action can be reduced to items descended from a given container.
descendedFrom(To Do) & ($Name(parent)=="Exploded Text")
This might be done because of the nature of the resulting agent action to be applied or simply to reduce agent update cycle time.
In summary:
- 'Exploded Text' receives all the source note's attribute values except $Rule and $OnAdd.
- Individual exploded notes do not inherit attribute values.
- Agents or manual editing of 'Exploded Text' actions should be used to apply attribute values to exploded text.
From v6.3.0, the explode action is applied after the text of the newly-created note is set, allowing the action to modify or depend on the exploded text. Explode also remembers the most recently-used delimiter, which can be convenient when using complicated regular expression delimiters.
Exploded Notes prototype. From v6.3.1, when a note is exploded the 'exploded notes' container has a prototype added and applied from '/Prototypes/exploded notes' (The /Prototypes container is created if needed). By default, the only customisation of this prototype is to add $ChildCount as a key attribute. The prototype make it easy to set up things like counts and such if doing repeat explodes in the same document. The prototype can't be added manually - if necessary do a test explode to add the attribute and customise it before doing the intended explode.