Exploding Notes

A single note's text ($Text) can be 'exploded' (split) into a container holding a number of discrete smaller notes by specifying where Tinderbox should divide the current text. The newly created notes contain an appropriate segment of the original note, using part of the same text as the note title. The basic default behaviour is to split the source by paragraph, using the paragraph of text as the note's text and the first sentence of the paragraph as the note's title. However, there are a number of option, described below that control the title and content of the new notes. 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 'empty' 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.

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. Note with that, or with a large existing note, selected in the view pane, choose Explode… from the Note menu. The option is available regardless of which pane has focus (prior to this, be aware that the Explode menu option is disabled if the input cursor is in the text pane).

Calling Note ▸ Explode presents the Explode pop-over. There are essentially three discrete sets of options to set before committing the explode:

• Defining how/where the source is split. This is defined by the top two radio buttons:
  • Break at paragraphs. Breaks each paragraph into a new note (default option).
  • Break at delimiter. Break on a (custom) delimiter. The input box for the delimiter is hidden when this option is not selected. The delimiter is a string of character(s) that is a regular expression that immediately precedes the break point. Tinderbox assumes each section of the source note that will form a new note starts with the delimiter. If there is source text before the first occurrence of the delimiter, Tinderbox behaves as if there were a starting delimiter and makes a new note use the content between source start and the first occurrence of the delimiter. Tinderbox remembers the last-used custom delimiter until the end of the current session. Use of delimiter regular expressions is described in more detail further below.
    • Delete Delimiter. If the custom option is chosen, there is a further option to delete the delimiter string, otherwise it is retained as the end of each new note's text (as the end of the delimiter string is the per-note break). When importing date for explode and using a deliberate string for delimiter purposes it is usually best to use this sub-option to avoid importing unnecessary data.
• Selecting source of new note $Name and $Text. The Title panel settings give control of what part of each newly split note's $Text is used to form the note's title ($Name). This is done at sentence or paragraph scope. A 'sentence' is delimited by a terminating period, exclamation mark or question mark. A 'paragraph' is delimited by a line break. By default, an explode-generated note uses the whole exploded section of the source note as its own $Text and that text's first sentence as the note title. Explode removes any leading or trailing whitespace from titles of exploded notes.
  • The scope of a new note's title can be altered:
    • First Sentence. Only the first sentence of the note text forms the new title (default). When running under macOS 10.14.x or later, Explode is substantially smarter about recognising sentences. It understands, for example, that "Dr. Perkins paid $10.00 to the U.S. Treasury." is one sentence, not five. However, if the user's current language locale does not support the new sentence-detection neural net, Tinderbox falls back to use the older sentence-end detection logic.
    • First Two Sentences. The first two sentences form the new title.
    • First Paragraph. Only the first paragraph is used for the new title. When importing custom data, such as lists of papers that often contain punctuation marks, this is usually the best option to choose.
  • When Explode constructs a note title, the title may extend up to 512 characters, and will include either the first line or the first $Text sentence of the new note—whichever is the best fit. If still over 512 characters the title is truncated at that point with an ellipsis.
  • Two tick boxes give additional control the $Text of the newly created notes. By default, both are un-ticked:
    • Remove title from text. If ticked, the text used for the above choice is deleted from the new note's body text.
    • Omit text. If ticked, this results in only a $Name being set for new notes and no $Text. If importing a list of data consisting only of data to form the title of new notes, this box should be ticked.
• Actions to apply to newly created notes. The Action box allows action code to be inserted that is applied to each newly exploded note by setting an $OnAdd for the 'exploded notes' container created by the process. If it is desired to apply a prototype other than the default (see below the section 'Exploded Notes' prototype for more detail), simply set the action to set the desired prototype's name. Essentially, the default OnAdd action of the 'exploded notes' container is the OnAdd action (if any is set) for the 'Exploded Notes' prototype unless the user adds code to the Action box; depending on the inputs, this may result code from Action and from the prototype being applied to newly-exploded notes.
• Example preview. This panel Gives a preview of the $Name and $Text of the first exploded note. A control below the preview allows cycling through a preview of successive exploded notes.

Finally, the Explode button closes the pop-over and starts the Explode process using the choices set above. Focus remains on the exploded note. The Return keypress will act like a button press and start the Explode.

Custom delimiters

This is a regular expression ('regex') but may be a literal string (i.e. the actual characters to match). Any regex-based text matching is case-sensitive. For single character matches, the matched character forms the end of the first/preceding note. For instance:

• \n A newly exploded note will begin after new line feed character. This is also the default for this option, it is essentially the same as 'break at paragraphs' overall explode default. [More on line-end character codes.]
• \r A newly exploded note will begin after each carriage return or hard line break.
• \t A newly exploded note will begin after each tab, e.g. for tab-delimited content pasted into a note.
• \, A newly exploded note will begin after each comma, e.g. use for CSV content pasted into a note. In this case it might make sense to delete the demiyied as a trailing comm might suggest missing content.

For multi-character matches, the new note starts at the beginning of the matched string, and is thus included in the new note. Therefore in this case it is usual to use the Delete delimiter option (see below), so the detected delimiter string is removed from the start of each new note's text. For example:

• ^\d{1,4}\ ?. A newly exploded note will begin at the beginning of line starting with a sequence of between 1 and 4 numerical characters followed by zero or 1 space characters.
• #### (delimiter deleted). A newly exploded note will begin after the end of each occurrence of the string '####'. After, because the delimiter has been deleted.
  • Often text is generated/edited elsewhere, adding characters as a deliberate explode delimiter for Tinderbox use. In the above case a better approach might be to add the '####' on a discrete line as this is easy to spot when visually scanning text. If so, the custom delimiter to find/remove becomes ####\n. Of course the '####' part of the delimiter can be whatever the user chooses, the key point here is to include the trailing '\n' if the delimiter is on its own line in the source text.
• action: (delimiter deleted). with match 'action: ' but not 'Action: ' as the regex test is case-sensitive.

Delete delimiter option. This is only visible/available if the 'Break at delimiter' option is selected (default = not ticked). Tick ing this option removes the specified delimiter character(s) 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.

Escaping characters for regex use

If struggling with understanding regex, assume that any space or non-alphanumeric character in a custom delimiter needs escaping by preceding it with a backslash \, e.g. a\+b rather than a+b. Without the escape '+' is interpreted as 'a+', i.e. a sequence one or more 'a' characters and thus the literal '+' in the demiter would not be matched.

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 notes', 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 (described above) made before exploding. Using a secondary container for the notes might seem odd until realising 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 notes' container is added to the outline order after any pre-existing child notes for the exploded note, i.e. it is the last child (and thus easily accessible via the lastChild designator, amongst others).

The 'exploded notes' container does not inherit anything from the source note. However, the Action box allows the $OnAdd for the 'exploded notes' container to be set afresh for each explode. However, the 'Exploded Notes' prototype (see below) is added to the 'exploded notes' child container of the exploded source note.

If there is code in the Action box and the Exploded Notes prototype's $OnAdd, both actions are run with the Action code running last. So if the prototype set $Color and $Badge, and Action set $Color (to a different colour), after the explode, the new notes would have the $Badge set via the prototype but its $Color setting would be overridden by the $Color value set by the Action code.

'Exploded Notes' prototype

When a note is exploded the 'exploded notes' container has a built-in prototype 'Exploded Notes' applied. Note the different letter case from the 'exploded notes' container; this is deliberate to stop name collision in queries. If the prototype of the /Prototypes container does not yet exist, Tinderbox automatically created the container and adds the prototype to the document before applying it.

Note the case sensitive spelling of the post explode container's title vs. that of the prototype; this is deliberate to avoid name collisions, e.g. he prototype does not want to be matched by a query looking for 'exploded notes' container(s).

By default, the only customisation of this prototype is to add $ChildCount as a Displayed Attribute. The prototype makes it easy to set up things like counts or a specific set of OnAdd actions (rather than set an action in the dialog: this can be useful if there are a number of actions to be set. The ability to customise this prototype becomes useful if doing regular/repeated Explodes.

For the reason explained above, do not use Action box code as well an $OnAdd in this prototype. At least do not do so if both pieces of code set the same attribute to different values. Carefully considered use of both input does, however, allow for document-wide consistent settings via the prototype alongside per-Explode settings using the Action box.

This prototype can be added manually, via the File ▸ Built-in Prototypes menu, for instance to customise it before using an explode. To 're-install' the default version, simply delete the any existing version of the prototype and re-add it via the Built-in Prototypes menu.

Working with exploded notes

Of course, the constant name of the container holding the new notes ('exploded notes') makes it easy for agents to find and work on the new notes' actions. Be aware that unless the 'exploded notes' 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 notes" 

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 notes") 

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 notes' receives all the source note's attribute values except $Rule and $OnAdd. If the 'Exploded Notes' prototype has been altered to locally set attribute values these will be used in preference.
• 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.

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.