<--- Cannot embed stylesheet 'c:/users/edreamleo/vr2-css': Permission denied. --->

# Leo.plugins.bookmarks

Manage bookmarks in a list, and show bookmarks in a pane.

This plugin has two bookmark related functions. It manages nodes that contain bookmarks, and can also display those nodes in a special bookmarks pane / panel / subwindow.

# General bookmark commands

bookmarks-open-bookmark opens the bookmark in the selected node if the
  node has an ancestor which contains `@bookmarks` in its heading.
bookmarks-open-node, like `bookmarks-open-bookmark` but without
  the ancestor requirement.
bookmarks-switch
  move between your working position in the outline, and the current bookmark, in the outline. This is the keyboard friendly no extra pane alternative to the mouse based bookmark pane navigation described below.
bookmarks-bookmark
  Add the current node as a bookmark at the current level in the bookmarks tree. Another keyboard friendly alternative.
bookmarks-bookmark-child
  Add the current node as a child of the current bookmark, if there is a current bookmark. Another keyboard friendly alternative.

# Cross file bookmark commands

These commands let you have personal bookmarks in a .leo file you’re sharing with others. E.g. you can store your personal bookmarks for the shared `LeoPyRef.leo` Leo development outline in `~/.leo/workbook.leo`.

bookmarks-mark-as-target
  Mark a node in outline A as being the container for bookmarks in another outline, outline B.
bookmarks-use-other-outline
  Specify that this outline, outline B, should store its bookmarks in the marked node in outline A. This also adds a bookmark display pane (described below), but you can ignore it, it won’t persist unless you save the layout.

Note: bookmarks treats file urls missing the `file://` part as urls, which deviates from Leo’s behavior elsewhere. It also recognizes local UNLs like `#ToDo-->Critical` as urls.

# Bookmarks pane commands

bookmarks-show
  Add a pane showing the bookmarks in the current subtree with unique colors. You can very quickly jump around between nodes in a file using this.

Nodes can be added and removed from the display with the following mouse actions:

left-click on bookmark
  Jump to that node.
left-click on background
  Add a bookmark at the position clicked, unless already present, in which case the existing link is highlighted.
control-left-click on bookmark
  Remove bookmark.
shift-control-left-click on bookmark
  Rename bookmark.
alt-left-click on bookmark
  Edit clicked bookmark in bookmark list, to change link text.
alt-shift-left-click on bookmark
  Move around bookmark hierarchy without changing nodes, useful for filing
control-alt-left-click on bookmark
  Update clicked bookmark to point to current node.
alt-left-click on background
  Edit bookmark list.
shift-left-click on bookmark
  Add the current node as a child of the clicked bookmark, and display the clicked bookmarks children.

The `@setting` `@int bookmarks-levels = 1` sets the number of levels of hierarchy shown in the bookmarks pane. By default, the @setting @int bookmarks_levels = 1 will limit the bookmarks shown to one level, so given these bookmarks:

    A
    B
       B1
       B2
    C

you’d just see A B C, with B underlined, indicating it has children, and when you click B, one of two things happens.

With bookmarks_levels = 1 (the default) the effect of clicking on B depends on whether or not B is itself a bookmark (contains an URL) or just an organizer node (no body).

If it’s just an organizer node, clicking it immediately shows its children. If it contains an URL itself, the first click makes Leo navigate to that URL, a subsequent click shows the children.

Note that this first click / second click behavior only applies with @int bookmarks_levels = 1.

With @int bookmarks_levels = 2 or more, you’ll initially see:

    A B C

with B underlined, and clicking on B will immediately show its children, so you see:

    A B C
    B1 B2

and, if B contains an URL, navigate to the URL

With @int bookmarks_levels = 0, the original behavior is used, hierarchy is ignored, and you see:

    A B B1 B2 C

all the time.

bookmarks-level-decrease
  Temporarily decrease the value of the the `@int bookmarks-levels` setting.
bookmarks-level-increase
  Temporarily increase the value of the the `@int bookmarks-levels` setting.

# Other notes

The `quickMove.py` plugin also provides actions for adding nodes to a bookmark list.

The free_layout Action button context menu will also allow you to add one of these bookmark panes, and they will be saved and loaded again if the layout is saved and loaded.

## Bookmarks for tabbed body editors

Create a new outline with the following nodes, as simple top level nodes:

    aardvarks
    apples
    autos
    bats
    bison
    bunting
    @bookmarks

(pro-tip, with the paste_as_headlines plugin active, you can just copy the above and use Edit -> Paste as headlines, you’ll need to promote them to top level again though).

Select the `@bookmarks` node and then Alt-X bookmarks-show, which should create a new empty pane above the body pane. Select the `aardvarks` node and click in the new empty pane, repeat for the `bats` node.

Squish the new empty pane up so it’s just high enough to hold the two bookmarks, or “tabs”, and then right click a pane divider and save this layout as “Tabs” or whatever you want to call it.

So now you have two tabs which jump between two nodes. Click the `aardvarks` tab, then select the `apples` node. Now shift-click the `aardvarks` tab. Now you are entering sub tabs of the `aardvarks` tab. You might want to repeat the `aardvarks` tab at this level, just select the node and click in the empty space in the bookmarks pane to repeat it here. You could add `autos` at this level too.

How the ‘tabs’ are displayed (one or more levels at once etc.) and how you edit them are described in the earlier parts of these docs. For example at the top level the first time you click the `aardvarks` tab it just shows you the `aardvarks` node, it requires a second click to see its subtabs (aardvarks, apples, and autos), because the top level `aardvarks` tab is both a bookmark and an organizer node. If you want it to be just and organizer node, alt-click it to edit the bookmark node itself, and delete the body text (UNL) there.