git clone 'git://github.com/tj64/navi.git'
Author: Thorsten Jolitz
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 author: Thorsten Jolitz author_email: tjolitz AT gmail DOT com git-repo: https://github.com/tj64/navi.git git-clone: git://github.com/tj64/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:
|1 … 8||show levels 1 to 8||navi-generic-command|
|q||quit navi-mode and switch||navi-quit-and-switch|
|M-s n||launch navi-buffer||navi-search-and-switch|
|M-s s||switch to other buffer||navi-switch-to-twin-buffer|
|^||move up subtree (same level)||navi-move-up-subtree|
|<||move down subtree (same level)||navi-move-down-subtree|
|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|
|e||edit as org (outorg)||navi-edit-as-org|
|.||call fun on thing at point||navi-act-on-thing-at-point|
|f||:FUN||functions, macros etc.|
|v||:VAR||vars, consts, customs etc.|
|x||:OBJ||OOP (classes, methods etc)|
|b||:DB||DB (store and select)|
(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.
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,
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:
Install the three required libraries:
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
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).