Paths

Tinderbox allows you to identify notes by relative or absolute paths, not just name. If a tag's request matches neither a keyword nor a note, Tinderbox tries to interpret it as a path. For example:

/news …is the top-level note named "news"

/news/Iraq …is the note named "Iraq", inside the top-level note "news"

../Chicago …is the note named "Chicago" that is a sibling of this note

../.. …is the grandparent of this note.

Using paths implies:

• knowledge of the Tinderbox files' outline structure
• where named notes are used
• that the outline will not change.

If a note name contains a forward slash, as in 'Large/Medium', then the path must be enclosed with quotes, e.g. Large/Medium should be cited as "Large/Medium". A deprecated legacy alternate is to escape the slash by a preceding backslash, e.g. Large\/Medium. Doing otherwise, the backslash is treated as part of a path, i.e. as a container delimiter.

A path beginning with a / is always an absolute path down from a top-level note (though it needn't be the cover if there is more than one top level note). Relative paths start with ../ (i.e. period+period+slash). A path not starting with either of these will result in Tinderbox treating the string as a single note name.

Quoting of Paths

Historically paths weren't quoted where used in Tinderbox code - and thus may be omitted in many older code examples you find. However, post version 4.0, in general did no harm to quote paths where used. From v5.7, users should switch to quoting paths - as they are string literals. Past convention in code examples is to quote paths in action code but not in export code, but this largely reflects past usage and should not prompt current users to omit quotes.

An exception to quoting paths occurs, where a path argument is actually an expression or an attribute name. A simpler way to view this is that quote enclosing a string of text is to say to Tinderbox, "this is just text - don't try interpreting any control/code characters found within it", i.e. a string literal.

Using Path arguments in Tinderbox

Many operators and codes in Tinderbox that allow a note name as an argument also allow a 'path' to be used; from v4.6 all attributes can also take a path argument allowing an attribute from some other note to be referenced.

For new users, figuring out paths can be a bit confusing. But firstly, why might a path argument needed? If a note name is not unique across the whole TBX document, then when Tinderbox finds a reference to that name, it will use the first one found (using $OutlineOrder). So, using a path rather than a note name can help identify exactly to which note you wish to refer. Consider using paths if:

• Your document deliberately doesn't use unique note names
• It may be that names may not remain unique over the life of the document.

That's the 'why', but how do you refer to a note using a path? To investigate this consider the following TBX outline:

  First Root
    Child A
      Sibling A1
      Sibling A2
    Child Z
  Second Root
    Child A
      Sibling A1
    Child B
      Sibling B1
      Sibling B2
    Child C/D
      Child of D

In this demo, you'll note that there are some duplicate note names. For the examples below, to help give starters code such as they might use for real, the examples are written as if making an attribute reference to the value of the system attribute 'Created'.

Note name (i.e. no path)

Just use the note name on its own:

$Created(Child B) 

$Created(Child A) 

$Created("Child C/D") 

$Created("/Second Root") N.B. need for root slash

Notes:

• note name will not suffice if you want to reach the 'Child A' in 'Second Root'. The note of the same name within 'First Root' will always get called.
• any paths (or just note names) with forward slashes must be 'escaped' by quoting the whole string.
• root-level note names must include a slash prefix as here $Name = $Path. See also notes on partial paths further below.
• there is still legacy support for the deprecated old usage of preceding (/) slashes in paths with a backslash (\) character.

Absolute Paths

With an absolute path you are stating the full and exact path. These are absolute paths, as:

$Created(/First Root/Child A/Sibling A1) 

$Created("/Second Root/Child C/D/Child of D") 

Points to note:

• there can be more than one root (top level note) but regardless the path always begins with a slash (/) and the name of a root note.
• every note from the root to the target note is included in the path, divided with a forward slash.
• the path doesn't end in a slash character.
• the path may contain spaces but doesn't needed to be enclosed in single quotes, although for consistency it may be a good idea to quote. Since v4.6, syntax has been moving towards explicit quoting of all strings.
• any path containing forward slashes must be enclosed in quotes.

Although any note's Text window lists its ancestors in the sidebar, only the last 3 are shown - i.e. father, grandfather and great-grandfather (in reverse order). If you need to work out the full list you'll need to open an outline view (or possibly a chart view), or look at $Path in the Info view (General section).

Absolute paths aren't a big deal in a small document like the example, but if it is a big TBX with deep nesting, you will want to consider using relative paths.

Relative Paths

The basic rules are roughly the same:

• the relative path always begins with a dot-dot-slash (../)
• navigating upwards, a dot-dot-slash is used for every level of outline traversed.
• navigating downward use the name of the notes working down from that point divided with a forward slash between each nested container's name.
• the path doesn't end in a slash character.
• the path may contain spaces but doesn't needed to be enclosed in single quotes, although for consistency it may be a good idea to quote. Since v4.6, syntax has been moving towards explicit quoting of all strings.
• any path containing forward slashes must be enclosed in quotes.

For the following example assume the currently selected note is 'Child B' within 'Second Root'.

$Created(../Child A) 

$Created(../../First Root/Child A) 

$Created("../Child C/D/Child of D") 

A relative call from Sibling B2 to its grandparent (Second Root) would be:

$Created(../../Second Root) 

The above examples show two subtle points to note about relative paths:

• to access a sibling (or its children) you must go 'up and back' to the current note's parent. You can't call a sibling by using its name with no slash prefix.
• when accessing notes under a different root, you must navigate to a level above the root note (effectively the document itself) before you navigate downwards.

If you're used to UNIX file navigation, note the absence of the dot '.' method. Also, if used to HTML relative links, note the 'up and back' method of navigation - you can't cite a sub-folder or sibling simply by using its name (without a preceding slash). So some slight variance form what some more expert users may intuit but the usage is consistent within Tinderbox and not difficult to learn.

Partial Paths

An easy mistake to make, especially when trying to disambiguate between two same-named notes, is to use a 'partial' path, such as in citing container name/note name. Although not illegal usage, this doesn't necessarily get parsed as the user assumes. The logic runs like this:

• If the path is an attribute reference, that reference is evaluated. If the path is quoted, the quoted expression is evaluated. Else…
• If the path is a keyword (e.g. parent). Else…
• If the path starts with a '/', it is evaluated relative to the root of the document. If not, it is evaluated relative to the current note. If the absolute or relative path locates a note that exists. Else…
• If the path designates a note that is an immediate child of this note. Else…
• If the path designates any note in the document whose name exactly matches the note.

Bottom line - don't use use partial paths as shorthand. Use a full path or a relative paths as described above.

Paths from Attribute Values

Another enhancement is that a path may be supplied as an attribute.

$Text($MyPath) 

…where $MyPath is a user attribute holding a path.

Paths from Expressions

Path may also be supplied in the form of an expression such a string concatenation or simple arithmetic:

$Text(' "../"+(1+2) ') 

…would collect the Text of a note named "3".

Paths with Designators

Most Tinderbox designators can use a path to refer to a different context. For example:

min(child("/some/other map note",$Xpos) 

^min(child("/some/other map note",Xpos)^ 

Paths with nested references

It is possible to cite an offset combining designators.

  ancestor
    Examples
      A
        1
        2
      Aliases
        A
  another
    More
      B
        3

For the alias A

$Container(this): Aliases

$Container(original): Examples

The designator parent(original) will give the parent of the original -- the parent of Examples, So $Container(parent(original)) is "ancestor".

The designator original(parent) will give the original of the parent -- "Aliases". So $Container(original(parent)) is "another".

Thus nested references like this tend to be written as spoken: the 'parent of the original' being parent(original).

Paths containing Parentheses

From v5.8.0, paths containing $Names including parentheses, e.g. "Fred Smith (Jr.)", will handle correctly during concatenation. Previously, parentheses caused the new string to terminate at the first parenthesis. For a note with $Name "Fred Smith (Jr.)":

"/Some/Path/"+ $Name 

…giving "/Some/Path/Fred Smith (Jr.)" unlike the old - incorrect - "/Some/Path/Fred Smith ".