References

The third type of a location is the reference location. It creates a reference bookmark.

If you have more than one bookmark that share a common path, you can choose to use one bookmark’s name as the target of the other bookmark.

So a reference location is a location whose target is another bookmark in the database.

Unlike the linking locations, this is the only type of bookmark that`hlg` checks for validity:

  • hlg cannot check whether a link is resolving to a valid target, and

  • Can also not check whether a command is syntactically or semantically correct;

  • but it will not run if the target of a reference is invalid: this is because it simply checks to see whether the linked bookmark exists or not.

To refer to another bookmark, you enclose the name of that other bookmark in curly braces and prepend an at symbol like this: @{bookmark-name}

Using references

You can only use references to target a bookmark name whose location field is a link and not a command.

The purpose of a reference is to:

  • Set at least one other location that takes advantage of another bookmark''s location;

  • This location could be a base path which other references can use to create their own unique targets;

  • This is only possible if the referenced bookmark is a link and not a command.

With references, it is possible to do the following:

Linking to other bookmark References

Hlg supports creating bookmarks that link to other bookmarks whose locations are also resolving to other bookmarks. This feature makes it possible to create a base path from which other bookmarks are resolved from.

For example:

music <~/Music>
classics <@{music}/international/Classics>
beethoven <@{classics}/yesteryears/Beethoven>

The advantage with this arrangement is that, even though hlg cannot run deactivated bookmarks, it lets you build other active bookmarks from a deactivated bookmark.

This means we can do something like this:

docs- <~/Documents>
projects <@{docs}/work/Projects>
transcripts <@{docs}/fieldwork/transcripts/>

So even though the “docs” bookmark is deactivated, and hence cannot be started on its own, yet the other two bookmarks, “projects” and “transcripts” that are referring to it still work and can be activated.

Working with subdomains

In visiting some sites, you will find that they provide convenient subdomains that you can get to after typing: “https://subdomain.mainsite.com”;

One example of this is the the hlg subdomain on the access-computing.com site.

Thus, while the main host can be reached after typing the https:, you can enter the subdomain before the host name.

As this is a common scenario, hlg supports references that link to bookmarks that provide links to the main domain.

So for this to work, the linked bookmark must have an address to the main site that has the full protocol which other reference locations can use.

To tell hlg that this reference is a subdomain to some other bookmark, just prepend a ~ symbol to the referenced bookmark.

For example, the following reference bookmark, “wiki”, relies on the Archlinux site:

arch <https://archlinux.org>
wiki <wiki.@{~arch}> :chromium
download <@{arch}/downloads/> :firefox

  • The first bookmark is what is referred to by others, which is the “arch” bookmark in this case.

  • the “wiki” bookmark takes advantage of the protocol provided by the “arch” bookmark and only provides the “wiki.” subdomain.

  • The last bookmark uses every path details of the arch so it just appends the /downloads folder to it. In fact, in the last bookmark, you do not need to add a subdomain symbol as this is just a directory and works like other bookmarks on the filesystem.

Of interest is the second bookmark that goes to the Arch Wiki.

Don’t forget the ~ character if you want to leave out the protocol in your reference bookmark. The ~ is put just before the target bookmark.

On the same note, if you add a tilde symbol to request a protocol of the main site, you must not provide a protocol to the linking bookmark. So do not do this:

<https://wiki.@{~arch}>

The tilde symbol is only used with subdomains: you only use it if you are not providing a protocol on the reference as the reference will use the protocol of the target bookmark.

Limitation of references

Though references offer convenience, they have the following limitations:

Only one target per Reference

A reference cannot have more than one target. Where it is placed depends on the nature of the path to be constructed after the reference is resolved.

In any case, it is not possible to have a valid path if we have got two targets in one reference.

The linked target is meant to stand on its own, and be called independently and not rely on other references.

For example:

multimedia <$HOME/Multimedia>
music <@{multimedia}/Audio/Music>

The multimedia bookmark can only expand to the $HOME/Multimedia once in that location.

So you cannot have a reference like this: @{multimedia}/@{music}

You cannot build a new complete path out of different targets , as each bookmark by default is meant to stand on its own.

References only work with links and not commands

Also references can only be used with links and cannot work with command bookmarks.

In other words, we can not use a reference to:

  • Refer to a bookmark with a script or command in its location field; or

  • Use command variables to refer to names of bookmarks.

Be careful not to create recursive links in references!

Although it is possible to link to some other bookmark which is also linking to another bookmark, beware of creating links that recurse to themselves.

If you do that, hlg will crash.

An example of a recursive link is this:

downloads <~/Downloads/@{multimedia}>
iso_files <@{downloads}/iso/>
multimedia <@{downloads}/Multimedia/>

The “downloads” bookmark is linking to the “multimedia” bookmark, while the “multimedia” bookmark is linking to the “downloads” bookmark.

This results in a crash.

References only work within one category

A reference cannot work across categories. Always make sure that the linked bookmark is in the same category as the linking bookmark.