Maintainer: Adam Porter Version: 2.0 URL: https://github.com/alphapapa/navi
copyright: Thorsten Jolitz
copyright-years: 2013+
version: 2.0
licence: GPL 2 or later (free software)
licence-url: http://www.gnu.org/licenses/
part-of-emacs: no
maintainer: Adam Porter
git-repo: https://github.com/alphapapa/navi.git
git-clone: git://github.com/alphapapa/navi.git
inspiration: occur-mode org-mode
keywords: emacs navigation remote-buffer-control
Navi-mode, as its name suggests, enables super-fast navigation and easy structure-editing in Outshine or Org buffers via one-key bindings in associated read-only Navi buffers.
You can think of a navi-buffer as a kind of 'remote-control' for an (adecuately) outline-structured original-buffer. Besides navigation and structure-editing, many common commands can be executed in the original-buffer without (necessarily) leaving the navi-buffer. When switching to the original-buffer and coming back after some modifications, the navi-buffer is always reverted (thus up-to-date).
Besides the many things that can be done from a navi-buffer, its main benefit is to offer a flexible but persistent and rock-solid overview side-by-side to the details of the original buffer. There can be many different navi-buffers alive at the same time, each one of them firmly connected to its associated original buffer. Switching between the 'twin-buffers' is easy and fast. Typically, an outline-structured original buffer in 'show-all' visibility state shares a splitted window with its associated navi-buffer that either shows headlines, keywords, or a combination of both. Instead of cycling visibility in the original buffer itself it is often more convenient to quickly switch to its navi-buffer and use its many different (over-)views.
Navi-mode is implemented on top of occur-mode and thus uses occur as its 'search-engine'. It does not aim to replace occur-mode or to compete with it, it rather specializes occur-mode for a certain use-case. Using navi-mode for remotely controlling Outshine and Org buffers does in no way interfere with occasionally calling 'M-x occur' on these buffers.
Navi-mode is part of the Outshine project, consisting of the three libraries outshine.el, outorg.el and navi-mode.el. For navi-mode to work, the original buffer must be either an org-mode buffer or have outline-minor-mode with outshine extensions activated (and be structured with outshine headers, i.e. outcommented Org headers).
Navi-mode is a special read-only mode (line e.g. occur-mode and dired-mode), thus all its core commands have one-key bindings. However, the command `navi-edit-mode' makes the navi-buffer editable. The edits are directly applied in the associated original buffer. With command `navi-cease-edit' the default read-only mode is turned on again.
Navi-mode's functionality can be divided into the following categories:
-
headline searches: keys '1' to '8' show all headlines up to that level
-
keyword searches: e.g. key 'f' shows functions in many major-modes
-
combined headline and keyword searches: e.g. 'C-3 v' shows variables and headlines up to level 3
-
navigation commands: e.g. keys 'n' and 'p' move to the next/previous line in the navi-buffer. These commands are especially useful in combination with keys 'd', 'o' and 's' that show the current position in the original buffer (or switch to it).
-
action commands: call functions on the thing-at-point in the navi-buffer, to be executed in the 'twin-buffer'.
Besides the mentioned fundamental outline-heading-searches (8 outline-levels) and the 5 basic keyword-searches (:FUN, :VAR, :DB, :OBJ and :ALL), all languages can have their own set of searches and keybindings (see customizable variables `navi-key-mappings' and `navi-keywords').
Use 'M-s n' (`navi-search-and-switch') to open a navi-buffer and immediately switch to it. The new navi-buffer will show the first-level headings of the original-buffer, with point at the first entry. Here is an overview over the available commands in the navi-buffer:
- Show headlines (up-to) different levels:
| key | command | function-name |
|---|---|---|
| 1 … 8 | show levels 1 to 8 | navi-generic-command |
- Navigate up and down in the search results shown in the navi-buffer:
| key | command | function-name |
|---|---|---|
| p | previous | occur-prev |
| n | next | occur-next |
| DEL | down page | scroll-down-command |
| SPC | up page | scroll-up-command |
- Revert the navi-buffer (seldom necessary), show help for the user-defined keyword-searches, and quit the navi-buffer and switch-back to the original-buffer:
| key | command | function-name |
|---|---|---|
| g | revert buffer | navi-revert-function |
| h | show help | navi-show-help |
| q | quit navi-mode and switch | navi-quit-and-switch |
- Switch to the original-buffer and back to the navi-buffer, display an occurence in the original-buffer or go to the occurence:
| key | command | function-name |
|---|---|---|
| M-s n | launch navi-buffer | navi-search-and-switch |
| M-s s | switch to other buffer | navi-switch-to-twin-buffer |
| M-s M-s | ||
| s | ||
| d | display occurrence | occur-mode-display-occurrence |
| o | goto occurrence | navi-goto-occurrence-other-window |
- Structure editing on subtrees and visibility cycling
| key | command | function-name |
|---|---|---|
| TAB | cycle subtrees | navi-cycle-subtree |
| cycle buffer | navi-cycle-buffer | |
| + | Demote Subtree | navi-demote-subtree |
| - | promote subtree | navi-promote-subtree |
| ^ | move up subtree (same level) | navi-move-up-subtree |
| < | move down subtree (same level) | navi-move-down-subtree |
- Miscancellous actions on subtrees (there are more …)
| key | command | function-name |
|---|---|---|
| m | mark thing at point | navi-mark-thing-at-point-and-switch |
| c | copy thing at point | navi-copy-thing-at-point-to-register-s |
| k | kill thing at point | navi-kill-thing-at-point |
| y | yank killed/copied thing | navi-yank-thing-at-point-from-register-s |
| u | undo last change | navi-undo |
| r | narrow to thing at point | navi-narrow-to-thing-at-point |
| w | widen | navi-widen |
| l | query-replace | navi-query-replace |
| i | isearch | navi-isearch |
| e | edit as org (outorg) | navi-edit-as-org |
| . | call fun on thing at point | navi-act-on-thing-at-point |
- Furthermore, there are five (semantically) predefined keyword-searches:
| key | keyword-symbol | searches for |
|---|---|---|
| f | :FUN | functions, macros etc. |
| v | :VAR | vars, consts, customs etc. |
| x | :OBJ | OOP (classes, methods etc) |
| b | :DB | DB (store and select) |
| a | :ALL | all |
- And (potentially) many more user-defined keyword-searches
(example Emacs Lisp):
[KEY] : [SEARCH]
================
a : ALL
f : FUN
v : VAR
x : OBJ
b : DB
F : defun
V : defvar
C : defconst
G : defgroup
U : defcustom
A : defadvice
W : defalias
M : defmarcro
D : defface
S : defstruct
B : defsubst
L : defclass
I : define
J : declare
K : global-set-key
T : add-to-list
Q : setq
H : add-hook
O : hook
X : lambda
Z : ert
R : require
-
Headline-searches and keyword-searches can be combined, e.g.
C-2 f
in an Emacs Lisp (outshine-)buffer shows all headlines up-to level 2 as well as all function, macro and advice definitions in the original-buffer,
C-5 a
shows all headlines up-to level 5 as well as all functions, variables, classes, methods, objects, and database-related definitions. The exact meaning of the standard keyword-searches 'f' and 'a' must be defined with a regexp in the customizable variable `navi-keywords' (just like the user-defined keyword-searches).
When exploring a (potentially big) original buffer via navi-mode, a common usage pattern is the following:
- type e.g '2' and go to the relevant headline
- type 'r' and e.g. '3' in sequence to narrow buffers to the subtree at point and show one deeper level of headlines
- do your thing in the narrowed subtree
- type e.g. '2' and 'w' to first reduce the headline levels shown and then widen the buffers again.
Install the three required libraries:
| navi-mode.el | [navi-mode](https://github.com/alphapapa/navi) |
| outshine.el | [outshine](https://github.com/alphapapa/outshine) |
| outorg.el | [outorg](https://github.com/alphapapa/outorg) |
from the package-manager via MELPA or clone their github-repos. Follow the installation instructions in `outshine.el' and `outorg.el'.
Then install `navi-mode.el' by adding
(require 'navi-mode)
to your .emacs file.
`navi-mode.el' works with [GNU Emacs 24.2.1 (x86_64-unknown-linux-gnu, GTK+ Version 3.6.4) of 2013-01-20 on eric]. No attempts of testing with older versions or other types of Emacs have been made (yet).
| date | author(s) | version |
|---|---|---|
| <2014-09-20 Sa> | Thorsten Jolitz | 2.0 |
| <2013-05-03 Fr> | Thorsten Jolitz | 1.0 |
| <2013-03-11 Mo> | Thorsten Jolitz | 0.9 |