#+TITLE: worf.el documentation
#+OPTIONS: H:3 num:nil toc:nil
[[https://github.com/abo-abo/worf][Back to github.]]
* Setup :noexport:
#+begin_src emacs-lisp :exports results :results silent
(defun make-html-cursor--replace (x)
(cond ((string= "||\n" x)
((string= "||[" x)
((string-match "||\\*" x)
(replace-regexp-in-string "||\\*" "*" x)))
(substring x 2))))))
(defun make-html-cursor (str x y)
(setq org-export-filter-src-block-functions '(make-html-cursor))
(setq org-html-validation-link nil)
(setq org-html-postamble nil)
(setq org-html-preamble "")
'((bold . "%s")
(code . "%s")
(italic . "%s")
(strike-through . "%s")
(underline . "%s")
(verbatim . "%s")))
(setq org-html-style-default nil)
(setq org-html-head-include-scripts nil)
This extension works similar to [[http://orgmode.org/manual/Speed-keys.html][org-mode's speed keys]], while adding in
a bit of /vi/ flavor, specifically:
** Modal editing
This is just what the speed keys do: pressing ~a~ - ~z~, ~A~ - ~Z~, or
~0~ - ~9~ while the point is positioned as below will call a command
instead of inserting these characters:
As you see, the point has to be either at one of the =*= that start from
the beginning of the line or actually at the beginning of the line,
followed by =#+= which will further be referred to as markup.
** Nouns and verbs
It's just an intuitive way of organizing the key bindings borrowed
from vi: the commands are sentences - combinations of a verb and a
noun used together.
Similar to vi, [[#left][~h~]] / [[#down][~j~]] / [[#up][~k~]] / [[#right][~l~]] are the nouns that represent the
arrow keys. These and additional nouns are listed in the tables below.
*** Nouns table
| key | name |
| [[#down][~j~]] | down |
| [[#up][~k~]] | up |
| [[#left][~h~]] | left |
| [[#right][~l~]] | right |
| [[#added][~a~]] | added |
| [[#property][~p~]] | property |
| [[#tags][~t~]] | tags |
*** Verbs table
| key | name |
| [[#goto][none]] | /goto/ |
| [[#/change/][~c~]] | /change/ |
| [[#change-tree][~cf~]] | /change tree/ |
| [[#change-shift][~cs~]] | /change shift/ |
| [[#keyword][~w~]] | /keyword/ |
| [[#clock][~C~]] | /clock/ |
| [[#delete][~d~]] | /delete/ |
| [[#yank][~y~]] | /yank/ |
| [[#mark][~m~]] | /mark/ |
** ~j~ - down
Move /down/ across headings and markup. Use a number prefix to move
several times at once, i.e. ~2j~ will move two headings down.
When you're in a heading, ~j~ will not enter markup, use [[#right][~l~]] for that
instead, as markup that belongs to a heading can be seen as being
/right/ of that heading. This restriction speeds up the movement
across headings that contain a lot of markup.
When you're in markup, ~j~ will not enter a heading, use [[#left][~h~]] for that
instead, as the heading can be seen as being /left/ of its markup.
This restriction allows to use a huge numeric arg (e.g. ~9j~ or ~99j~)
to move all the way to the last markup of the heading.
The exception to both restrictions is the first markup in the file
that does not belong to any heading.
** ~k~ - up
Move /up/ across headings and markup. Use a number prefix to move
several times at once, i.e. ~3k~ will move three headings up.
Same rules as [[#down][~j~]] apply.
** ~h~ - left
Move /left/ i.e. to the parent heading of current heading or markup.
You can use it e.g. to go from fifth level 3 heading to its parent
level 2 heading, or from the second source block to the parent
** ~l~ - right
Move /right/ (i.e. to the first child of current heading). You can
use it to get to the first markup of the current heading.
** ~a~ - added
Represents /added/ heading. The behavior depends on the currently
Forward to =org-insert-heading-respect-content= (bound to ~C-RET~ in =org-mode=).
Forward to =org-meta-return= (bound to ~M-RET~ in =org-mode=).
Add a new heading with a corresponding keyword.
For example ~wta~ will add a new *TODO*, and ~wna~ will add a new
** ~p~ - property
Represents current heading's /property/. The behavior depends on the
currently active verb:
Move to the property, i.e. open the property drawer and place the
point on the first property.
Change property. This forwards to =org-set-property=, which will
prompt you for the name of the property and it's value.
You can use this to add new properties as well.
Delete property. This forwards to =org-delete-property=.
** ~t~ - tags
Represents current heading's /tags/.
Currently, the only meaningful sentence is ~ct~, which forwards to
Some verbs, such as [[#/change/][~c~]] (change), or [[#change-tree][~cf~]] (change tree) are /sticky/: once you
activate them, they stick around until deactivated or you switch to
another sticky verb (only one can be active at a time). Their
stickiness is represented by a change in the mode line. Each of them
can be deactivated by the same key that activated them, or universally
with ~q~. Currently separate minor modes are used to implement sticky
verbs because their concept is exactly the same.
Other verbs, such as [[#clock][~C~]] (clock), are more like /vi/ verbs, i.e. they
deactivate themselves after the first command.
And just to add to the confusion, some nouns will deactivate a verb
(e.g. ~cwd~), while others won't (e.g. ~cj~).
This verb is active by default. Its effect on the nouns is to move the
** ~c~ - /change/
This is a /sticky/ verb: once you press ~c~, /change/ verb will be
active until you switch to a different verb.
Use the same letter to deactivate a verb as to activate it, i.e. ~c~
will deactivate =worf-change-mode=. ~q~ will universally deactivate
any verb and return you to /goto/ implicit verb.
While =worf-change-mode= is active, ~hjkl~ move the current heading
in appropriate directions: it's the same as holding ~M-~ and using
arrow keys in the default org.
- ~cp~ will change the selected property
- ~ct~ will change current tags
- ~ca~ will add heading above instead of below, like ~a~ does
- ~cn~ will change the name of a source block
** ~cf~ - /change tree/
While =worf-change-tree-mode= is active, ~hjkl~ move the current
heading tree in appropriate directions: it's the same as holding
~S-M-~ and using arrow keys in the default org.
** ~cs~ - /change shift/
While =worf-change-shift-mode= is active, ~hjkl~ act as
~S-~ and arrows in the default org.
** ~w~ /keyword/
You select a keyword e.g. *TODO* or *NEXT* and ~j~ / ~k~ move just by the
selected keyword, skipping all other headings.
Additionally, ~a~ will add a new heading with the appropriate keyword,
e.g. ~wta~ will add a new *TODO*, and ~wna~ will add a new *NEXT*.
** ~C~ - /clock/
This one isn't sticky and has only two nouns that work with it:
- ~i~ (=org-clock-in=)
- ~o~ (=org-clock-out=)
** ~d~ - /delete/
This one isn't sticky and changes the behavior of ~j~ to delete down,
and ~k~ to delete up. You can mix in numbers to delete many times,
i.e. ~d3j~ will delete 3 headings at once.
- ~dp~ will delete the selected property
- ~dn~ will delete the name of the current source block
** ~y~ - /yank/
It's similar to [[#delete][~d~]], but will copy the headings into
the kill ring instead of deleting.
** ~m~ - /mark/
It's similar to [[#delete][~d~]], but will mark the headings instead
* Miscellaneous commands
Some other things included in worf, that don't fit into the
verb-noun structure, are:
** ~[~ - =worf-backward=
Go backwards to closest special position. ~]~ does the same in the opposite direction.
** ~i~ - =worf-tab=
Wraps around =org-cycle=.
Additionally, e.g. ~2i~ will show a summary up to level 2, ~3i~ -
level 3 etc.
** ~I~ - =worf-shifttab=
Just a wrapper for =org-shifttab=.
** ~o~ - =worf-ace-link=
Open a link within current heading that's visible on screen. See
[[https://github.com/abo-abo/ace-link][ace-link]] for a package that uses this method in other modes.
** ~g~ - =worf-goto=
Open a =helm= outline of the current buffer. It's very good when you
want to search/navigate to a heading by word or level. See [[https://github.com/abo-abo/lispy][lispy]] for a
package that uses this method to navigate Lisp code.
** ~L~ - =worf-copy-heading-id=
Copy the link to current heading to the kill ring. This may be useful
when you want to create a lot of links.