2  Organizing Bookmarks

2.1 Bookmark scope

Every bookmark is either local or global, and the difference is decided entirely by its name’s first letter:

  • Starting with an uppercase letter makes a bookmark global — visible and addressable from anywhere in your whole database, regardless of which category file it happens to live in.
  • Starting with a lowercase letter (or a digit) makes it local — visible only within its own category.
News <@bbc.com>       # global: reachable from anywhere as "News"
news <@bbc.com>       # local: reachable only from within its own category

There’s no separate setting for this anywhere — the case of the name is the scope. A shortcut key follows the same rule: a global bookmark’s key must be uppercase, a local bookmark’s key must be lowercase or a digit. hande checks this when the bookmark file is loaded and refuses to launch anything that doesn’t match.

2.2 The category file

A category is simply a file. Whatever name you give a bookmark file stored in the bookmarks directory under hande’s own data directory becomes the name of that category. If you have files called default, books, and work, you have three categories, each holding whichever bookmarks you’ve put in it.

To edit a category’s own file directly:

hlg> :edit

or, from the command line:

$ hande --edit-bookmarks --category books

:edit (or :e) always opens the working category’s file — see “The active category” below.

2.3 The category header

The first line of a category file is special. It’s a header line, marked with a leading *, and it declares up to three things about the category itself: a shortcut key, a home location, and a short description — all independently optional:

*l <@kernel.org> These bookmarks are about Linux

The key, if you want one, is stuck directly onto the * with no space (*l); the location, if you want one, goes in angle brackets exactly like an ordinary bookmark’s own location; the description, if you want one, is whatever’s left on the line. Leave out whichever you don’t need:

*l <@kernel.org>          # just a key and a location, no description
* <@kernel.org>            # just a location
*l                          # just a key
* These bookmarks are about Linux

A header line needs at least one of the three — a bare * with nothing after it is an error. If you don’t want a header at all, just leave the line out of the file entirely.

The header’s home location always opens through whatever handler hande would infer for it (see Chapter 7) — a category header can’t set its own handler the way an ordinary bookmark can.

Once a category has a header with a location in it, typing a bare . opens that category’s home bookmark.

2.4 Subcategories

A category file can hold subcategories — groups nested inside it, opened with a colon and a brace:

education : {
    bookshare <@bookshare.org>
}

Braces can nest as deeply as you like. A subcategory reaches a bookmark inside “education”, inside a category “web”, as web.education.bookshare.

2.4.1 Giving a subcategory its own header

A subcategory can carry its own key, home location, and description too — on its own header line, in exactly the same *key <location> description shape as a category’s own header, placed right after the subcategory’s opening line:

education : {
*e <@bookshare.org> reading and literacy
    bookshare <@bookshare.org>
}

All three are independently optional here too, exactly like a category header — a subcategory can have a key with no location, a location with no key, a description alone, or none of these at all (in which case it simply has no header line). This is what makes the @-chain shortcuts from Chapter 1 possible — @web walks category key w, then subcategory key e, then bookmark key b.

A subcategory’s home location is restricted the same way everything else inside a subcategory is (see below) — an ordinary web link only, never a local file or command. If a subcategory has no home of its own, opening it (with a trailing period — see below) falls back to using the whole category’s own header instead of failing outright.

Because a subcategory’s header is just an ordinary line inside its braces, editing a subcategory (:e, from within it — see Chapter 3) shows you that header line right along with its bookmarks, so you can change its key, location, or description the same way you’d retype any other line.

2.4.3 What subcategories are for

Subcategories exist mainly to preserve the folder structure of bookmarks imported from a real browser (see Chapter 6) without flattening it away. Because of that, anything living inside a subcategory has to stay something a browser could represent too:

  • No search-flagged bookmarks (see Chapter 5).
  • No command bookmarks — scripts and one-liners only make sense to hande itself, not to a browser.
  • No global (uppercase) bookmarks — everything inside a subcategory is local.
  • Locations are limited to ordinary web links: the plain @ shortcut (for https://), @= (for https://www.), @! (for plain http://), or an explicit http:///https:// address. The other location shortcuts covered in Appendix B don’t apply here.

A category’s own top level has none of these restrictions — they apply only inside a subcategory block.

2.4.4 Listing what’s there

:category-list (or :c) always shows only what’s directly in front of you — the working category’s own top-level bookmarks, or a subcategory’s own direct contents if that’s where you are — never descending into anything nested further down. :list (:l) additionally shows the global bookmarks reachable from wherever you are; :global-list (:g) shows every global bookmark in the whole database.

2.5 The default category

When you type a lowercase bookmark name with no category attached, hande looks for it in the default category — the one named in the configuration file under default-category (see Chapter 7).

2.6 The active category

When you’re in the shell, the category you’re currently working in — set by :to, and shown right in the prompt — is the active category (also called the working category throughout this manual). Every bookmark name you type without qualifying it, :edit, :add-bookmark, and every other category-implicit command in this manual, all act on the active category, not necessarily the default one. :to with no argument at all resets the active category back to the default.

Outside the shell, there’s no notion of an “active” category carried between calls — every direct command-line call either names its own category explicitly or falls back to the default.

2.7 Working with other categories

To open, or edit, a bookmark that isn’t in your default or active category, name its category explicitly, separated by a period:

hlg> books.recipes

or, equivalently, pass the category as its own option:

$ hande --category books recipes