7  Configuring hande

Besides the bookmark files themselves, hande has one other file: its configuration file, in TOML format.

To open it:

hlg> :config

or, from the command line:

$ hande --edit-configuration

:config is also available as :cfg.

7.1 The general settings

default-category = "default"
create-missing-category = false
autoselect = true
save-with-shortcuts = true
script-dir = "scripts"
history-size = 1000
search = "google"
  • default-category — the category hande uses when a bookmark name is typed with no category attached (see Chapter 2).
  • create-missing-category — if true, hande creates a category file on the fly the first time it’s asked to use one that doesn’t exist yet, rather than treating that as an error.
  • autoselect — if true, an alias/tag lookup (the / trigger from Chapter 1) that matches exactly one bookmark opens it directly, instead of showing a one-item menu to confirm.
  • save-with-shortcuts — if true, saving a category file after editing it (:edit) automatically rewrites any fully spelled-out http:///file:// locations into hande’s own shortcut form (see Chapter 4), tidying the file up for you.
  • script-dir — where hande looks for a script named in a command location that isn’t given as a full path (see Chapter 3).
  • history-size — how many lines of shell command history are kept between sessions.
  • search — the exact name of your default search bookmark (see Chapter 5), used whenever you type more than one word, or a single word prefixed with ?. Write it exactly as it’s stored — search bookmarks are always resolved in the global scope, so no category qualification is needed or supported here, regardless of the bookmark’s own case. Leave it out entirely and hande falls back to its own built-in search bookmark.

7.2 [protocols]

[protocols]
browser = "firefox"
file-manager = "nautilus"
command = "bash"

The default handlers hande falls back to when a bookmark doesn’t specify one of its own: browser for a web address, file-manager for a local file or directory, and command for running a script or one-liner.

The file manager hande ships with by default is nautilus — GNOME Files’ own binary name. If you’re on a different desktop, change it to match: caja for MATE, nemo for Cinnamon, dolphin for KDE Plasma, pcmanfm for LXDE/LXQt, and so on — whatever your own desktop’s file manager is actually called on your $PATH (see Appendix B).

Here’s how hande decides which of these three a location without its own handler actually gets, in order:

  1. It’s a web address. Anything resolving to http://, https://, ftp://, ftps://, file://, or a bare www. address goes to browser — always, regardless of what the domain’s TLD happens to be. @sci-hub.africa opens in your browser exactly as readily as @example.com does; an unusual top-level domain is never a reason for hande to balk.
  2. It’s a local file with a recognized extension. If the location looks like a filesystem path (it has a / in it, or starts with ~) and its last segment ends in an extension listed under [[formats]] below, that entry’s program is used.
  3. Everything else falls back to file-manager. A plain directory, a path with no extension, or a bare word that isn’t a web address at all (say, a domain typed without a @ link shortcut, so it never picked up a https:// in the first place) is handed to the file manager rather than guessed at as a file type it isn’t.

7.3 [[domain-codes]]

[[domain-codes]]
code = "b"
value = "blog"

A domain code is a single-character shorthand for a subdomain, for use in a subdomain reference (see Chapter 4) — @b{name} here means the same as @blog{name}. hande ships with two: b for “blog” and w for “wiki”. Add as many more of your own as you like, each with its own code letter and value, or redefine either of the two that ship by default.

7.4 [[formats]]

[[formats]]
name = "vim"
extensions = ["txt", "c", "conf"]

[[formats]]
name = "libreoffice"
extensions = ["odf", "odt", "docx", "doc", "xls", "xlsx", "ppt", "pptx"]

A format entry maps a set of file extensions to the program that should open them by default, when a bookmark’s location is a local file with no handler of its own. Add or edit these entries to match what’s actually installed on your own system — hande ships with a reasonable starting set (an editor for plain text and code, an office suite for documents, a media player for audio and video), but there’s nothing special about any of the program names themselves; they’re just what’s run.

This table is only ever consulted for a location that already looks like a filesystem path (see the ordering above) and has a recognizable extension on it. If that extension has no matching [[formats]] entry and the bookmark has no handler of its own, hande refuses to guess and asks you to set one, either on the bookmark itself or by adding a [[formats]] entry here. A path with no extension at all, or anything that isn’t a filesystem path or a web address in the first place, never reaches this table — it falls back to file-manager instead (see above).