Tinderbox v6+: Exploding a Note's $Text

Tinderbox allows a large text note to be converted into several smaller text notes. The default behaviour is to split each paragraph in the source $Text into a new note. The first sentence of the new note's text is used as the note's title ($Name). All the newly created notes are placed into a child container of the note being exploded (i.e. as the source note's grandchildren). The new notes are stored in the order created, following the flow of the original text. Additional line returns between paragraphs are ignored - i.e. blank paragraphs create no note.

The user is allowed to specify where Tinderbox should make the divisions in the source text, e.g. other that paragraph end, and how these division points are marked. There are further options controlling how new note titles are created from source text, the retention of the title in the new notes text, etc. These options will be described in more detail further below.

Tinderbox will expect that:  Exploded Text

• Only one note is selected.
• The selected note has some text.
• (older versions) The focus is in the View (left) pane of the document window.

Here, a single note with text is selected.  In the text (right) pane it can be seen the note has 2 paragraphs of text.

The Explode feature is called from Tinderbox's Note menu or via a shortcut: Cmd+Opt+E. A dialog is shown. In this example no changes will be made and the 'Explode' button is clicked to start the process.

See how a child container 'exploded notes' has been added to the exploded note.  Inside this container, there are 2 new notes:

• The notes list in the order of the original text.
• The first sentence of the source text forms the note's title (its $Name).
• The title text is retained in the notes text, i.e. the whole paragraph is retained.

In addition, a new built-in prototype 'Exploded Notes' has been added to the document and applied to the 'exploded notes' container (observe the different capitalisation of the prototype as opposed to the container holding the Explode-generated notes. This point of this latter process will be discussed further below.

In versions pre-v5, the container holding the newly generated notes was named 'Exploded Text'. This has been succeeded by the current 'exploded notes' title.

The Explode dialog, from v6, is in the form of a pop-over. It is shown with default settings.

Break delimiter. By default, the source text breaks at paragraph boundaries. A custom delimiter can be supplied instead. The latter is useful if importing data, such as a set of records, which may contain multiple paragraphs but which have a consistent marker between items. The custom delimiter is a string of characters and can include control characters.

Title text. A pop-up controls that amount of the source text used to create each new note's title. The options are:

• First sentence. (default)
• First two sentences.
• First paragraph.

The default choice is the first sentence. The appropriate choice will vary with use. With imported data, 'first paragraph' can often be a better choice. The Remove title from text option, when checked, will omit the text selection used for the note title from that note's text ($Text). The Omit text option, if checked, results in a new note having a tilte but no text at all.

Action. If desired Tinderbox action code can be applied to each new note as it is created.

Explode. Click this button to start the Explode process.

Example output. As settings are chosen, the example panel updates to give an indication of the title and text of the first new exploded note. At the bottom of this preview area is a caption showing the number of notes that will be created and the note currently being previews *default: 1). An up/down control next to this caption allows previewing a different output sample note.

Cancelling Explode. If called in error, the Explode dialog can be closed/cancelled by using the Escape key or simply clicking the Tinderbox document window anywhere outside the pop-over

If the Break at delimiter option is selected, two new controls are shown. An input box allows entry of the custom delimiter string. That string allows use of regular expressions and escape codes for things like a line break (\n) or tab (\t).

A tick-box option Delete delimiter allows the delimiter string to be deleted as part of the Explode process. This is useful in that is allows use of delimiter string that are unlikely to occur in normal text but are not useful if retained after the Explode process

Pretty much every (non-intrinsic) attribute except $Prototype, $OnAdd and $Rule. These are understood to be pragmatic design choices to avoid unintended runaway results after Explode. These limitations are easily circumvented by various methods. Two popular choices are:

• Set the source note to use a prototype whose $OnAdd sets children to use the same prototype. Thus as the 'exploded notes' container is added it receives the parent's prototype and does the same for the children that get added to it.
• Use an agent that looks for items in 'exploded notes' container(s) and apply changes to the child notes via the agent action.

The container created by Explode uses a consistent name so as to make it easy to always easy to find any such container(s) and act on them.

The 'Exploded Notes' prototype is built-in to the app and automatically added the first time Explode is used in a document. It is possible to add it manually (File menu → Built-In Prototypes → Exploded Notes) before first use should you wish to customise it. The prototype has one customisation - $ChildCount is added as a Key Attribute, making it easy to check the (expected) number of new notes has been created. However, the real purpose is to address some of the above issues. thus the prototype can be given custom $OnAdd code. As the prototype is applied to the 'exploded notes' container before the container has the new notes added, it allows rhe prototype to customisae those notes as they are added.

No, if not still needed, simply move the child notes out of it (or at least the ones to be retained) and delete the container.

An easy way to empty the container is to select all its contents and then click Shift+Tab. The selected items are promoted as junior siblings to the parent container (the 'exploded notes' container) which my be deleted. This leaves the new notes as the children of the original source note. However, the user can move these exploded notes anywhere desired in the document - they are still normal notes albeit automatically created.

If unsure on the procedure, read the Tinderbox manual and see aTbRef. The Explode process is described here. If still unsure contact Tinderbox tech support or ask in the Tinderbox User-to-User forums.