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 slash must be escaped with a back-slash: 'Large\/Medium' otherwise the backslash is treated as part of a path.

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 ../. A path not starting with either of these will result in Tinderbox treating the string as a single note name.

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. 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 it's own:

$Created(Child B)

$Created(Child A)

$Created(Child C\/D)

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 forward slashes in the path must be 'escaped' by preceding them 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.
• any forward slashes in the path must be 'escaped' by preceding them with a backslash (\) character.

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 (N.B 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)

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.
• the path doesn't end in a slash character.
• the path may contain spaces but doesn't needed to be enclosed in single quotes.
• any forward slashes in the path must be 'escaped' by preceding them with a backslash (\) character.

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.

Licensed under Creative Commons Attribution-Noncommercial-Share Alike 3.0 License
[See aTbRef CC licence Attribution/Waiver info info]