The bookmark name

The bookmark name field is the first field in the bookmark entry. This is the name of your bookmark as you would look it up in your database.

  • A bookmark name must not have embedded spaces nor periods in it.

  • If you wish to have a bookmark name with more than one words, consider using underscores (_), or a dash (-). For example, "the-great-trek"

  • Your bookmarks must start and end with alphanumeric characters.

  • You can, however, flag a bookmark using some other special symbols to be described below.

A bookmark name is case-sensitive. hlg will look it up based on the case you use to call it when it is passed as an argument.

Flagging a bookmark

Though hlg looks up your bookmark as you save it in the bookmarks file, it ignores any flag attached to the bookmark name.

A flag is a symbol that sets special properties on a bookmark. These properties are read by hlg but do not form part of the bookmark name. For example, this entry:

heavenly_voice+ <~/Music/Christian/bands/heaven_onwards/praise.ogg> :mpv

As far as hlg is concerned:

  • The bookmark is simply called, "heavenly-voice"

  • Typing it as an argument including a plus sign will result in an error because no bookmark can begin or end with a non-alphanumeric character (of which the plus sign is one of them!)

  • Still, this bookmark, "heavenly-voice" has a special property set on it, the + which means it is a favorite or "starred" or "flagged" bookmark in the category.

  • Because of this property, this bookmark is now classified as "special" (See this page on how special bookmarks are used.)

  • It acquires a special status and will be treated as such.

There are a few symbols used this way, such as having the underscore as the first character of a bookmark name causing the first letter of the bookmark name to be its shortcut key.

The following are the flags used by hlg and their meaning:

_

Indicates that the first character of a bookmark name is a shortcut key at category level. This is the only flag that is used as a prefix. For example:

_hi <https://hlg.access-computing.com/> :opera

tells hlg that the bookmark "hi" uses h as its shortcut key.

()

The key assignment brackets. This is used when you want flexibility: whereas the underscore character limits you to assigning the first character of a bookmark name as its key, with the key assignment brackets, you can use any key whether it is part of the bookmark name or not. The only requirement is that the key you assign has to be an alphanumeric key. For example:

hi(g)

uses the character g as its shortcut key. To find out more on using shortcut keys, see this page.

+

Marks a bookmark as a favorite. When we talk of a "flagged bookmark", we mean a bookmark that has the plus flag as its suffix. For example,

heavenly_voice+

tells hlg that the “heavenly_voice” bookmark is a starred or favorite bookmark.

*

Sets a bookmark as a category home bookmark. This bookmark can be launched with hlg . as opposed to the main home bookmark which is set in the configuration file.[1]

-

Marks a bookmark as deactivated. This means that it cannot be launched. You reactivate a bookmark by removing a - at the end of its name. You deactivate a bookmark for a number of reasons, for example when you want to update some of its fields, but not wishing to first delete the bookmark and re-enter it. You may also deactivate a bookmark because you don’t want to activate the bookmark itself, but use it as a target for reference links.

Restrictions on flags

A bookmark must not have more than one flag attached to it. Only one flag will be read and the rest will be ignored. This in turn will lead to the bookmark being rejected as having invalid characters.

So make sure to only flag a bookmark with only one flag at a time. The reasoning behind this is commonsense:

  • A bookmark marked as a category home bookmark with a * need not be assigned a shortcut key. Already you can launch it with the . special symbol.

  • A bookmark marked as a favorite with the + sign needs no other shortcut key. Already you can launch it with hlg +, hence another shortcut key will be a waste.

  • A bookmark whose first character is indicated to be a shortcut key with the _ symbol needs no key assignment brackets. This will in effect cause a double-assignment of keys on one bookmark which does not make sense. For example, this bookmark entry is nonsensical and will cause hlg to not start:

    _itsfoss(s) <https://itsfoss.com/> :firefox

    will have hlg complain that the "itsfoss" bookmark is assigned shortcut keys in two different places. So you have to either remove the _ symbol at the beginning, or the key assignment brackets.

  • A bookmark marked as deactivated needs no shortcut key anyway to launch it. As a deactivated bookmark,

    • It cannot be directly launched from the terminal;

    • It needs not be marked as a favorite or a home bookmark.

A bookmark name is a required field in a bookmark entry. If you leave it out, hlg will generate an error and not start.
1. Note, however, that when you have no "home" entry in the configuration file, this bookmark will be used as the main home bookmark if the bookmark file is the default category.