search

alphapapa / dogears.el

Never lose your place in Emacs again
GNU General Public License v3.0
190 stars 7 forks source link
emacs

readme

+TITLE: dogears.el

+PROPERTY: LOGGING nil

Note: This readme works with the org-make-toc https://github.com/alphapapa/org-make-toc package, which automatically updates the table of contents.

+HTML:

[[https://melpa.org/#/package-name][file:https://melpa.org/packages/dogears-badge.svg]] [[https://stable.melpa.org/#/package-name][file:https://stable.melpa.org/packages/dogears-badge.svg]]

/Never lose your place in Emacs again!/

This library automatically and smartly remembers where you've been, in and across buffers, and helps you quickly return to any of those places. It works similarly to a Web browser's history list and back/forward commands, but with more contextual information and customization. As well, for most modes, it can return to a place even if its buffer no longer exists.

It's configurable to suit each user, with regard to how often places are remembered, which ones, and for how long. It uses standard Emacs completion, so it works with Helm, Ivy, Selectrum, Vertico, etc. For Helm users, a ~helm-dogears-source~ is also provided in =helm-dogears.el= that can be used with any Helm command.

This shows the ~dogears-list~ buffer, in which you can browse entries, sort them, etc.

[[images/screenshot.png]]

This screenshot shows it while using the theme =doom-solarized-dark=, and the =Line= column shows some source code snippets with highlighting by [[https://github.com/alphapapa/prism.el][prism.el]].

[[images/screenshot2.png]]

** MELPA

If you installed from MELPA, you're done. Just run one of the commands below.

** Quelpa

The recommended way to install is with [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]], like this:

+BEGIN_SRC elisp

;; Install and load `quelpa-use-package'. (package-install 'quelpa-use-package) (require 'quelpa-use-package)

(use-package dogears :quelpa (dogears :fetcher github :repo "alphapapa/dogears.el" :files (:defaults (:exclude "helm-dogears.el")))

;; These bindings are optional, of course:
:bind (:map global-map
            ("M-g d" . dogears-go)
            ("M-g M-b" . dogears-back)
            ("M-g M-f" . dogears-forward)
            ("M-g M-d" . dogears-list)
            ("M-g M-D" . dogears-sidebar)))

+END_SRC

** Manual

If you want to install it manually, it's simple enough, but you should know what you're doing, and you're on your own.

It works by automatically remembering ("dogearing") the place at point when any of three things happens:

Then the user can run a command to view or go to places in the list.

| Command | Action | |------------------+------------------------------------------------------------| | =dogears-mode= | Automatically remember places, according to configuration. | | =dogears-remember= | Manually remember the place at point. | | =dogears-go= | Go to a dogeared place, selected with completion. | | =dogears-back= | Go to previous dogeared place. | | =dogears-forward= | Go to next dogeared place. | | =dogears-list= | Show dogeared places in a tabulated list buffer. | | =dogears-sidebar= | Show Dogears list in a side window. |

** Tips :PROPERTIES: :ID: 6a5b2fdf-1031-4801-a471-b4dd47b953c7 :END:

** 0.2-pre

Additions

Changes

Fixes

** 0.1

First tagged release.

* Credits

Bug reports, feature requests, suggestions — /oh my/!

** Implementation :PROPERTIES: :ID: 3d92e106-2964-4097-a8d4-e4607dc240ab :END:

Internally, Dogears uses the built-in Emacs ~bookmark~ library to make bookmark-like records, however they are stored in ~dogears-list~ rather than ~bookmark-alist~, so they are not accessible with ~bookmark~ commands. Nor is the ~dogears-list~ persisted to a file; it is empty when Emacs starts. If the ~bookmark-make-record-function~ does not return a record for a place, Dogears uses a simple fallback that saves a record referring to the buffer by name, which allows it to remember places in, e.g. the =scratch= buffer. When returning to a place, Dogears uses ~bookmark-jump~, which for many, if not most, modes returns not only to the buffer or file but to the specific location in it. And by using ~bookmark~ internally, Dogears benefits from packages that extend it, like [[https://github.com/alphapapa/org-bookmark-heading][org-bookmark-heading]].

Dogears also uses other built-in Emacs libraries, such as ~which-function~ and ~imenu~, to provide information about the context surrounding a place, such as a function or variable definition, an outline heading, etc.

Some other, similar packages:

GPLv3

Local Variables:

eval: (require 'org-make-toc)

before-save-hook: org-make-toc

org-export-with-properties: ()

org-export-with-title: t

End: