Org-mode section major update

Added the following new sections to make use of org-mode in Spacemacs.  Still
some work required, but covers the bare basics.

* Headings - how to create them and move them around easily
* Todo states - track progress of your work by labelling headings
* Customise Todo states - create your own states and workflow
* Get Things Done - an example of using todo states (just a link, needs work)

SUMMARY.md

@@ -119,6 +119,10 @@
     * [Gists](github/gists.md)
 * [Debugging](debugging/index.md)
 * [Org-mode](org-mode/index.md)
+    * [Headings](org-mode/headings.md)
+    * [TODO States](org-mode/todo-states.md)
+    * [Customise TODO States](org-mode/todo-states-customise.md)
+    * [Get Things Done](org-mode/get-things-done.md)
     * [Tables](org-mode/tables.md)
     * [Code Blocks](org-mode/code-blocks.md)
     * [Yasnippets](org-mode/yasnippets.md)

org-mode/get-things-done.md

@@ -0,0 +1,7 @@
+# Org-mode: Get Things Done
+
+> ####TODO::work in progress, sorry
+
+Get Things Done is a simple and effective way to manage tasks using Org-mode todo states.
+
+See the article: [Emacs - Get Things Done](https://orgmode.org/worg/org-gtd-etc.html)

org-mode/headings.md

@@ -1,23 +1,42 @@
-# Org-mode headers
+# Org-mode: Headings
 
-You can easily organise and present information by using headers. As headers expand and fold, you can show just the level of information you need at any particular time.
+You can easily organise and present information by using headings. As headings expand and fold, you can show just the level of information you need at any particular time.
 
-[![Spacemacs Org-mode headers](/images/spacemacs-orgmode-headers-example.png)](/images/spacemacs-orgmode-headers-example.png)
+[![Spacemacs Org-mode headings](/images/spacemacs-orgmode-headings-example.png)](/images/spacemacs-orgmode-headings-example.png)
 
-## Reordering headers
+> #### TODO::Videos required to really do this justice
 
-> ####TODO::These sections will be easier to understand with a good video or animated gif.
+## Create a new heading
 
-Org-mode allows you to move headers around very easily
+There seem to be quite a few ways to create a heading and the same commands will do slightly different things based on context, i.e. if they cursor is on a heading or in a table.
 
+Simplest keybinding to create a new heading is `, RET`.  If the line is blank a main heading is created.  If inside a sub-heading, a new sub-heading at the same level is created.
 
-| Vim Normal | Major mode | Description                |
-|------------|------------|----------------------------|
-| `M-j`      | `, J`       | Move heading down          |
-| `M-k`      |  `, K`          | Move heading up            |
-| `M-l`      |  `, L`          | Change to a sub-heading    |
-| `M-h`      |  `, H`          | Change to a parent heading |
-|            |            |                            |
-| `S-M-j`    | `, C-S-j`   | Move sub-heading down parent headings   |
-|            |            |                            |
-|            |            |                            |
+`, M-RET` or `M-RET M-RET` also creates a new heading.  I find this a bit weird, so maybe there is a better way.
+
+### Collapse / Expand headings
+
+`TAB` expands / collapses the heading at the current cursor position.
+
+`S-TAB` will cycle through expanding and collapsing headings at different levels.
+
+### Moving headings and content around
+
+| Keybinding         | Description                                        |
+|--------------------|----------------------------------------------------|
+| `M-h` or `M-🡄`     | Increase the level of the heading                  |
+| `M-l` or `M-🡆`     | Decrease the level of the heading                  |
+| `M-S-h`,`M-S-🡄`    | Increase the level of the heading and sub-headings |
+| `M-S-l` or `M-S-🡆` | Decrease the level of the heading and sub-headings |
+| `M-k` or `M-🡅`     | Move heading up within the same level              |
+| `M-j` or `M-🡇`     | Move heading down within the same level            |
+| `M-S-k` or `M-S-🡅` | Move heading up, jumping over parent headings      |
+| `M-S-j` or `M-S-🡇` | Move heading down, jumping over parent headings    |
+
+> #### Hint::Moving headings with sub-headings
+> If a heading you wish to change contains sub-headings, then also use the `SHIFT` key and all the sub-headings will change along with the heading under the cursor.  Without shift, the heading may not change.
+
+------------------------------------------
+
+> ####Hint::Arrows and other unicode symbols
+> `SPC i u` shows a helm popup allowing you to add a symbol by name.  All the symbol names are listed along with the symbol itself.

org-mode/index.md

@@ -14,4 +14,5 @@ For example, if you want to write a guide to your project, you could create an o
 If you want to see many of the things Org-mode can do, take a look at one of these videos on youtube.
 
 * [Getting started with Org Mode](https://www.youtube.com/watch?v=SzA2YODtgK4) - covers more than what you need to start with
+* [Org-mode todo states](https://www.youtube.com/watch?v=Ck9HXMkNGGY) - interesting ideas with org-mode todo states
 * [Overview of Org Mode - Hack Emacs](https://www.youtube.com/watch?v=SzA2YODtgK4) - older, but has more examples

org-mode/todo-states-customise.md

@@ -0,0 +1,36 @@
+# Customise your own todo states
+
+You can also define your own todo states and workflow to support the way you work.
+
+> #### TODO::Check if there is a better approach
+> You can define `todo` states per `.org` file (to investigate).
+
+Define states and workflow for all `.org` files in the `.spacemacs` file, inside `dotspacemacs/user-config` as follows
+
+```elisp
+  (with-eval-after-load 'org
+    (setq org-todo-keywords
+         '((sequence "todo" "doing" "blocked" "review" "|" "done" "archived"))))
+```
+
+## Setting colours (faces) for todo states to give clearer view of work
+
+```elisp
+  (with-eval-after-load 'org
+    (setq org-todo-keyword-faces
+         '(("todo" . org-warning)
+           ("doing" . "yellow")
+           ("blocked" . "red")
+           ("review" . "orange")
+           ("done" . "green")
+           ("archived" .  "blue"))))
+```
+
+## Automatically log completion date-time
+
+When a heading status enters `DONE`, add a `closed:` property with current date-time stamp
+
+```elisp
+  (with-eval-after-load 'org
+    (setq org-log-done 'time))
+```

org-mode/todo-states.md

@@ -0,0 +1,18 @@
+# Org-mode: Headings States
+
+You can add states to headings to help you track task.
+
+Each heading can be assigned a status label, by default `todo` `doing` `done`
+
+## Cycling through states
+
+When you start working on a task, you can move it from `todo` to `doing` by cycling forward through the todo states.
+
+| Keybinding | Action                                                    |
+|------------|-----------------------------------------------------------|
+| `M-S-RET`  | create a new heading with the default todo status, `todo` |
+| `S-🡆`      | cycle todo state forward                                  |
+| `S-🡄`      | cycle todo state backward                                 |
+
+
+> #### TODO::Add video of todo states