Update documentation in code and README

4 files changed, 156 insertions, 145 deletions

diff --git a/README.org b/README.org
index 3d85b3a..a95109e 100644
--- a/README.org
+++ b/README.org
@@ -41,33 +41,40 @@ This is an extended and actively maintained version of https://github.com/edwtjo
 
 ** Installation
 
- #+BEGIN_SRC sh
+   #+BEGIN_SRC sh
    mkdir -p ~/.emacs.d/plugins; git clone git://github.com/somelauw/evil-org-improved.git ~/.emacs.d/plugins/evil-org-mode
- #+END_SRC
+   #+END_SRC
 
 *** emacs.el
 
- #+begin_src emacs-lisp
-     (add-to-list 'load-path "~/.emacs.d/plugins/evil-org-mode")
-     (require 'evil-org)
-     (evil-org-set-key-theme '(textobjects insert navigation additional))
- #+end_src
- 
- For a more elaborate setup, take a look at [[file:doc/example_config.el][this example]].
+#+begin_src emacs-lisp
+(add-to-list 'load-path "~/.emacs.d/plugins/evil-org-mode")
+(require 'evil-org)
+(add-hook 'org-mode-hook 'evil-org-mode)
+(evil-org-set-key-theme '(textobjects insert navigation additional))
+#+end_src
+
+For a more elaborate setup, take a look at [[file:doc/example_config.el][this example]].
 
 ** See also
 
    - [[https://github.com/edwtjo/evil-org-mode][org-mode by edwtjo]]
-    Original org-mode plugin by edwtjo from which this project was forked
+     Original org-mode plugin by edwtjo from which this project was forked
 
    - [[https://github.com/GuiltyDolphin/org-evil][org-evil by GuiltyDolphin]]
-    Alternative integration of evil and org with different keybindings
+     Alternative integration of evil and org with different keybindings
+
+   - https://github.com/jceb/vim-orgmode
+     Org mode plugin for vim
 
    - http://orgmode.org/
-    The official org-mode website
+     The official org-mode website
 
    - [[http://orgmode.org/orgcard.pdf]]
-    A handy cheat sheet, even if using this plugin
+     A handy cheat sheet, even if using this plugin
+
+   - https://github.com/Somelauw/evil-markdown
+     Similar project for markdown code
 
 ** License
 
diff --git a/doc/example_config.el b/doc/example_config.el
index b3906c7..cde7bf1 100644
--- a/doc/example_config.el
+++ b/doc/example_config.el
@@ -4,33 +4,36 @@
 (require 'hydra)
 
 (add-hook 'org-mode-hook
-          (lambda ()
-            ;; Set key theme(s)
-            (evil-org-set-key-theme '(additional textobjects))
+ (lambda ()
+   ;; Set key theme(s)
+   (evil-org-mode)
+   (evil-org-set-key-theme '(additional textobjects))
 
-            ;; Custom mappings
-            (evil-define-key 'normal evil-org-mode-map
-              (kbd "-") 'org-ctrl-c-minus
-              (kbd "|" 'org-table-goto-column))
+   ;; Custom mappings
+   (evil-define-key 'normal evil-org-mode-map
+     (kbd "-") 'org-ctrl-c-minus
+     (kbd "|") 'org-table-goto-column
+     (kbd "M-o") 'evil-org-insert-subheading
+     (kbd "M-t") 'evil-org-insert-subtodo)
 
-            ;; Configure leader key
-            (evil-leader/set-key-for-mode 'org-mode
-              "t" 'org-todo
-              "T" 'org-show-todo-tree
-              "a" 'org-agenda
-              "c" 'org-archive-subtree
-              "l" 'evil-org-open-links
-              "o" 'evil-org-recompute-clocks)
+   ;; Configure leader key
+   (evil-leader/set-key-for-mode 'org-mode
+     "t" 'org-todo
+     "T" 'org-show-todo-tree
+     "a" 'org-agenda
+     "c" 'org-archive-subtree
+     "l" 'evil-org-open-links
+     "o" 'evil-org-recompute-clocks)
 
-            ;; Define a hydra
-            (defhydra hydra-org-state ()
-              ("h" org-up-element)
-              ("l" org-down-element)
-              ("j" org-forward-element)
-              ("k" org-backward-element)
-              ("H" org-shiftleft)
-              ("L" org-shiftright)
-              ("K" org-shiftup)
-              ("J" org-shiftdown)
-              ("." org-ctrl-c-ctrl-c)
-              ("i" org-cycle))))
+   ;; Define a hydra
+   (defhydra hydra-org-state ()
+     ("h" org-up-element)
+     ("l" org-down-element)
+     ("j" org-forward-element)
+     ("k" org-backward-element)
+     ("H" org-shiftleft)
+     ("L" org-shiftright)
+     ("K" org-shiftup)
+     ("J" org-shiftdown)
+     ("." org-ctrl-c-ctrl-c)
+     ("i" org-cycle))))
diff --git a/doc/keythemes.org b/doc/keythemes.org
index 7335cdc..f27dfec 100644
--- a/doc/keythemes.org
+++ b/doc/keythemes.org
@@ -1,37 +1,38 @@
 * Key themes
   
-The new config is set up in key themes
+  The new config is set up in key themes
 
-To enable all bindings use:
-#+begin_src emacs-lisp
-    (evil-org-set-key-theme '(textobjects insert navigation additional shift leader todo heading))
-#+end_src
+  To enable all bindings use:
+
+  #+begin_src emacs-lisp
+  (evil-org-set-key-theme '(textobjects insert navigation additional shift leader todo heading))
+  #+end_src
 
 ** Basic
-These keys are always enabled
-
-  |-----+-------------------------------|
-  | key | function                      |
-  |-----+-------------------------------|
-  | 'x' | evil-org-delete-char          |
-  | 'X' | evil-org-delete-previous-char |
-  | '$' | org-end-of-line               |
-  | '^' | org-beginning-of-line         |
-  | <   | org-metaleft                  |
-  | >   | org-metaright                 |
-  | (   | org-forward-sentence          |
-  | )   | org-backward-sentence         |
-  | {   | org-forward-paragraph         |
-  | }   | org-backward-paragraph        |
-  | TAB | org-cycle                     |
-  | o   | evil-org-open-below           |
-  | O   | evil-org-open-above           |
-  |-----+-------------------------------|
+   These keys are always enabled
+
+   |-----+-------------------------------|
+   | key | function                      |
+   |-----+-------------------------------|
+   | 'x' | evil-org-delete-char          |
+   | 'X' | evil-org-delete-previous-char |
+   | '$' | org-end-of-line               |
+   | '^' | org-beginning-of-line         |
+   | <   | org-promote-or-dedent         |
+   | >   | org-demote-or-indent          |
+   | (   | org-forward-sentence          |
+   | )   | org-backward-sentence         |
+   | {   | org-forward-paragraph         |
+   | }   | org-backward-paragraph        |
+   | TAB | org-cycle                     |
+   | o   | evil-org-open-below           |
+   | O   | evil-org-open-above           |
+   |-----+-------------------------------|
 
 ** Text objects
-"var" to select an element
-"dar" to delete a subtree
-"2yar" to yank the parent of a subtree
+   "var" to select an element
+   "dar" to delete a subtree
+   "2yar" to yank the parent of a subtree
 
   |-----+-------------+------------------------------------------------|
   | key | function    | explanation                                    |
@@ -41,101 +42,101 @@ These keys are always enabled
   |-----+-------------+------------------------------------------------|
 
 ** Operators
-Operators for promoting/demoting headings and items
+   Operators for promoting/demoting headings and items
 
-">>" to promote a heading
-">ar" to promote a tree
+   ">>" to promote a heading
+   ">ar" to promote a tree
 
-  |-----+----------------------+-------------------------------------|
-  | key | function             | explanation                         |
-  |-----+----------------------+-------------------------------------|
-  | <   | evil-org-shift-left  | Promote all headings in marked area |
-  | >   | evil-org-shift-right | Demote all headings in marked area  |
-  |-----+----------------------+-------------------------------------|
+   |-----+----------------------+-------------------------------------|
+   | key | function             | explanation                         |
+   |-----+----------------------+-------------------------------------|
+   | <   | evil-org-shift-left  | Promote all headings in marked area |
+   | >   | evil-org-shift-right | Demote all headings in marked area  |
+   |-----+----------------------+-------------------------------------|
 
-If you want < and > similar to evil-org-mode, put the following in your init file
+   If you want < and > similar to evil-org-mode, put the following in your init file
 
-#+begin_src emacs-lisp
-  (evil-define-key 'normal evil-org-mode-map
-    (kbd ">") 'org-meta-right
-    (kbd "<") 'org-meta-left)
-#+end_src
+   #+begin_src emacs-lisp
+   (evil-define-key 'normal evil-org-mode-map
+                    (kbd ">") 'org-meta-right
+                    (kbd "<") 'org-meta-left)
+   #+end_src
 
-Or enable the additional key binding theme and use M-h and M-l.
+   Or enable the additional key binding theme and use M-h and M-l.
 
 ** Movement
-If you don't want to use hjkl, you can customize evil-org-movement-bindings.
-
-  |-----+---------------------------------+--------------------------|
-  | key | function                        | explanation              |
-  |-----+---------------------------------+--------------------------|
-  | gh  | outline-up-heading              | Go to parent tree        |
-  | gj  | org-forward-heading-same-level  | Next heading             |
-  | gk  | org-backward-heading-same-level | Previous heading         |
-  | gl  | outline-next-visible-heading    | Go to first subtree      |
-  | gH  | evil-org-top                    | Move to one-star heading |
-  |-----+---------------------------------+--------------------------|
+   If you don't want to use hjkl, you can customize evil-org-movement-bindings.
+
+   |-----+----------------------+--------------------------|
+   | key | function             | explanation              |
+   |-----+----------------------+--------------------------|
+   | gh  | org-element-up       | Go to parent tree        |
+   | gj  | org-forward-element  | Next heading             |
+   | gk  | org-backward-element | Previous heading         |
+   | gl  | org-down-element     | Go to first subtree      |
+   | gH  | evil-org-top         | Move to one-star heading |
+   |-----+----------------------+--------------------------|
 
 ** Additional
-If you don't want to use hjkl, you can customize evil-org-movement-bindings.
-If you want to use these bindings even in insert mode, you can customize evil-org-use-additional-insert.
-
-  |-----+---------------------------------------------+---------------------|
-  | key | function                                    | explanation         |
-  |-----+---------------------------------------------+---------------------|
-  | M-l | org-metaright                               | Demote heading      |
-  | M-h | org-metaleft                                | Promote heading     |
-  | M-k | org-metaup                                  | Move subtree up     |
-  | M-j | org-metadown                                | Move subtree down   |
-  | M-L | org-shiftmetaright                          | Demote subtree      |
-  | M-H | org-shiftmetaleft                           | Promote subtree     |
-  | M-K | org-shiftmetaup                             | Move heading up     |
-  | M-J | org-shiftmetadown                           | Move heading down   |
-  |-----+---------------------------------------------+---------------------|
+   If you don't want to use hjkl, you can customize evil-org-movement-bindings.
+   If you want to use these bindings even in insert mode, you can customize evil-org-use-additional-insert.
+
+   |-----+--------------------+-------------------|
+   | key | function           | explanation       |
+   |-----+--------------------+-------------------|
+   | M-l | org-metaright      | Demote heading    |
+   | M-h | org-metaleft       | Promote heading   |
+   | M-k | org-metaup         | Move subtree up   |
+   | M-j | org-metadown       | Move subtree down |
+   | M-L | org-shiftmetaright | Demote subtree    |
+   | M-H | org-shiftmetaleft  | Promote subtree   |
+   | M-K | org-shiftmetaup    | Move heading up   |
+   | M-J | org-shiftmetadown  | Move heading down |
+   |-----+--------------------+-------------------|
 
 ** Shift
    Disabled by default.
    If you don't want to use hjkl, you can customize evil-org-movement-bindings.
 
-  |-----+----------------+--------------------|
-  | key | function       | explanation        |
-  |-----+----------------+--------------------|
-  | H   | org-shiftleft  | previous todo item |
-  | L   | org-shiftright | next todo item     |
-  | J   | org-shiftdown  | decrease priority  |
-  | K   | org-shiftup    | increase priority  |
-  |-----+----------------+--------------------|
+   |-----+----------------+--------------------|
+   | key | function       | explanation        |
+   |-----+----------------+--------------------|
+   | H   | org-shiftleft  | previous todo item |
+   | L   | org-shiftright | next todo item     |
+   | J   | org-shiftdown  | decrease priority  |
+   | K   | org-shiftup    | increase priority  |
+   |-----+----------------+--------------------|
 
 ** Leader                                                        :deprecated:
    Disabled by default.
 
-  |-----------+---------------------------|
-  | key       | function                  |
-  |-----------+---------------------------|
-  | <leader>a | org-agenda                |
-  | <leader>t | org-show-todo-tree        |
-  | <leader>c | org-archive-subtree       |
-  | <leader>l | evil-org-open-links       |
-  | <leader>o | evil-org-recompute-clocks |
-  |-----------+---------------------------|
+   |-----------+---------------------------|
+   | key       | function                  |
+   |-----------+---------------------------|
+   | <leader>a | org-agenda                |
+   | <leader>t | org-show-todo-tree        |
+   | <leader>c | org-archive-subtree       |
+   | <leader>l | evil-org-open-links       |
+   | <leader>o | evil-org-recompute-clocks |
+   |-----------+---------------------------|
   
-** Todo                                                          :deprecated:
+** Todo
    Disabled by default.
 
-  |-----+---------------------------------------|
-  | key | function                              |
-  |-----+---------------------------------------|
-  | t   | org-todo                              |
-  | T   | org-insert-todo-heading nil           |
-  | M-t | org-insert-todo-heading+org-metaright |
-  |-----+---------------------------------------|
-
-** Heading                                                       :deprecated:
+   |-----+---------------------------------------|
+   | key | function                              |
+   |-----+---------------------------------------|
+   | t   | org-todo                              |
+   | T   | org-insert-todo-heading nil           |
+   | M-t | org-insert-todo-heading+org-metaright |
+   |-----+---------------------------------------|
+  
+** Heading
    Disabled by default.
 
-  |-----+----------------------------------|
-  | key | function                         |
-  |-----+----------------------------------|
-  | O   | org-insert-heading               |
-  | M-o | org-insert-heading+org-metaright |
-  |-----+----------------------------------|
+   |-----+----------------------------------|
+   | key | function                         |
+   |-----+----------------------------------|
+   | O   | org-insert-heading               |
+   | M-o | org-insert-heading+org-metaright |
+   |-----+----------------------------------|
diff --git a/evil-org.el b/evil-org.el
index 800521a..36b6a7a 100644
--- a/evil-org.el
+++ b/evil-org.el
@@ -198,6 +198,7 @@ Argument COUNT number of lines to insert."
     (evil-backward-sentence-begin count)))
 
 (evil-define-motion evil-org-top ()
+  "Find the nearest one-star heading."
   :type exclusive
   :jump t
   (while (org-up-heading-safe)))
@@ -269,8 +270,8 @@ Argument COUNT number of lines to insert."
     (evil-yank beg end type register)
     (org-delete-backward-char count)))
 
-;; recompute clocks in visual selection
 (evil-define-operator evil-org-recompute-clocks (beg end type register yank-handler)
+  "Recompute clocks in visual selection."
   :keep-visual t
   :move-point nil
   (interactive "<r>")
@@ -319,7 +320,6 @@ If a prefix argument is given, links are opened in incognito mode."
   (interactive "<r><vc>")
   (evil-org-generic-open-links beg end (not (null count))))
 
-;; open links in visual selection in incognito mode
 (evil-define-operator evil-org-open-links-incognito (beg end)
   "Open links in visual selection in incognito mode."
   :keep-visual t
@@ -396,7 +396,7 @@ If a prefix argument is given, links are opened in incognito mode."
 
 ;;; Keythemes
 (defun evil-org--populate-base-bindings ()
-  "Bindings that are always be available ."
+  "Bindings that are always available."
   (let-alist evil-org-movement-bindings
     (dolist (state '(normal visual operator motion))
       (evil-define-key state evil-org-mode-map