Add Org tutorial

TristanCacqueray · Oct 8, 2024 · bbeec9b · bbeec9b
1 parent 6425d55
commit bbeec9b
Show file tree

Hide file tree

Showing 3 changed files with 291 additions and 1 deletion.
diff --git a/content/emacs/media/emacs-tut-org-agenda.png b/content/emacs/media/emacs-tut-org-agenda.png
diff --git a/content/emacs/media/emacs-tut-org-file.png b/content/emacs/media/emacs-tut-org-file.png
diff --git a/content/emacs/tutorial.md b/content/emacs/tutorial.md
@@ -24,6 +24,7 @@ allowing you to read news, send emails, play media, and much more!
 > This [file][my-emacs-tut] is licensed under a free/libre copyleft license (GPL or CC BY-SA).
 >
 > **Changelog**
+> - 2024-10-07: added the *Org Mode* section.
 > - 2024-10-07: explained the *Compile* workflow.
 > - 2024-10-05: added the *Development* section.
 
@@ -1135,7 +1136,294 @@ Emacs contains hundreds of microscopic quality of life features:
 
 ### ispell
 
-### org mode
+### Org Mode
+
+[org-mode][org-mode] is arguably the most advanced system for taking notes and organizing information.
+It is a free software that comes with Emacs.
+
+[org-mode]: https://orgmode.org/features.html
+
+In this section we will set up a simple, yet opinionated, Getting Things Done (GTD) workflow,
+as presented by Nicolas P. Rougier in his [Emacs GTD][emacs-gtd].
+This configuration has been proven to work, and I recommend using it as a starting point.
+Add the following to your `~/.emacs`:
+
+```scheme
+;; Adjust org-mode for GTD
+(use-package org
+  :config
+  ;; Define task sequence, `|` separates the completed statuses.
+  (setq org-todo-keywords
+        '((sequence "TODO(t)" "NEXT(n)" "|" "DONE(d)" "CANCELLED(c@/!)")))
+
+  ;; Record the task completion date.
+  (setq org-log-done 'time))
+```
+
+#### Modern Style
+
+Install a sleek-looking style with org-modern.
+The following configuration defines a custom color for the `NEXT`
+keyword that is used by GTD:
+
+```scheme
+;; Modern Org Style
+(use-package org-modern
+  :ensure t
+  :config
+  ;; Add styles for NEXT status
+  (setq org-modern-todo-faces
+        '(("NEXT" :foreground "purple" :weight bold :background "orange")))
+  ;; Activate org-modern
+  (global-org-modern-mode))
+```
+
+#### Your First File
+
+In this section, we will setup your first org file.
+Create a file named `~/org/projects.org` with the following content:
+
+```bash
+* Project name
+** A task
+** Another task
+
+* Another project
+** Yet another task
+```
+
+Here are the commands you can apply to the headings:
+
+| *Command*            | *Description*                      |
+|----------------------|------------------------------------|
+| org-set-property     | Assign a property like *CATEGORY*. |
+| org-set-tags-command | Set the tags.                      |
+| org-todo             | Change the TODO state of an item.  |
+
+
+Perform the following actions:
+
+- Set the **CATEGORY** property for the top headings with the project codename.
+- Optionally add tags, such as related technology names.
+- Set some task statuses with `C-c C-t` or `M-x org-todo`.
+
+Your buffer should look like this:
+
+![emacs-tut-org-file](media/emacs-tut-org-file.png)
+
+> [!note]
+> When a heading has no content, the ▶ indicator might get stuck in the open state: ▼.
+> If that bothers you, add an empty paragraph with a dash `-`; then pressing `TAB` will work as expected.
+
+
+#### Refile and Capture
+
+To move tasks, use the `org-refile` command (`C-x C-w`).
+Add the following settings to make your `projects.org` the default target.
+
+```scheme
+;; Allow moving task from anywhere into your projects:
+(setq org-refile-targets '(("~/org/projects.org" :maxlevel . 1)))
+
+;; Automatically save org files after refile
+(advice-add 'org-refile :after (lambda (&rest _) (org-save-all-org-buffers)))
+```
+
+To add tasks, use the `org-capture` command.
+Add the following settings:
+
+```scheme
+;; Setup capture template to write new tasks to ~/org/inbox.org
+(setq org-capture-templates
+      '(("t" "todo" entry (file "~/org/inbox.org")
+         "* TODO %?\n/Entered on/ %U\n")))
+
+;; Press F6 to capture a task
+(global-set-key (kbd "<f6>") 'org-capture)
+```
+
+> [!tip]
+> Capture tasks at any time by pressing <kbd>F6</kbd> <kbd>t</kbd>.
+> Avoid using refile right away, use org-capture to quikcly move tasks off your mind.
+
+
+#### Editing Org File
+
+Org leverages a few keys to help with editing an Org file:
+
+| *Key*                           | *Description*                     |
+|---------------------------------|-----------------------------------|
+| <kbd>TAB</kbd>                  | Cycle folding on current heading. |
+| <kbd>shift</kbd>+<kbd>TAB</kbd> | Cycle folding on the whole file.  |
+| <kbd>alt</kbd>+<kbd>→</kbd>     | Demote heading.                   |
+| <kbd>alt</kbd>+<kbd>←</kbd>     | Promote heading.                  |
+| <kbd>alt</kbd>+<kbd>↓</kbd>     | Move subtree down.                |
+| <kbd>alt</kbd>+<kbd>↑</kbd>     | Move subtree up.                  |
+| `M-g i`                         | Jump to a place in the buffer.    |
+| `M-RET`                         | Insert a new heading.             |
+
+Here are a couple of useful commands you might need:
+
+| *Command*                   | *Description*                                       |
+|-----------------------------|-----------------------------------------------------|
+| org-toggle-link-display     | Show the literal links.                             |
+| org-tree-to-indirect-buffer | Focus on the current subtree in a dedicated buffer. |
+|                             |                                                     |
+
+
+#### Agenda
+
+In this section, we will set up the agenda view, which is the main user interface you
+will use to get things done.
+Add the following to your Emacs config:
+
+```scheme
+(use-package org-agenda
+  :config
+  ;; The agenda pulls data from the following files:
+  (setq org-agenda-files '("~/org/projects.org" "~/org/inbox.org"))
+
+  ;; The GTD view
+  (setq-default org-agenda-custom-commands
+   '(("g" "Get Things Done (GTD)"
+      ((agenda ""
+         ((org-agenda-skip-function '(org-agenda-skip-entry-if 'deadline))
+          (org-deadline-warning-days 0)))
+       (todo "NEXT"
+         ((org-agenda-skip-function '(org-agenda-skip-entry-if 'deadline))
+          (org-agenda-prefix-format "  %i %-12:c [%e] ")
+          (org-agenda-overriding-header "\nTasks\n")))
+       (tags-todo "inbox"
+         ((org-agenda-prefix-format "  %?-12t% s")
+          (org-agenda-overriding-header "\nInbox\n")))
+       (tags "CLOSED>=\"<today>\""
+         ((org-agenda-overriding-header "\nCompleted today\n")))))))
+
+  ;; Press F4 to get things done!
+  (global-set-key (kbd "<f4>") (lambda () (interactive) (org-agenda nil "g"))))
+```
+
+> [!note]
+> We don't need to use `use-package` because org-agenda is built into Emacs, but
+> that helps keep your config nice and tidy.
+
+This setup is well documented in Nicolas's [Emacs GTD][emacs-gtd] paper,
+so I won't explain the settings in detail. What you need to know is that,
+pressing <kbd>F4</kbd> will display a dashboard with four sections:
+
+- The current week; see the next section for scheduling events.
+- The list of tasks marked as `NEXT`.
+- The list of tasks captured in the *inbox* that need to be refiled.
+- The list of tasks completed today.
+
+From that view, you can use the usual commands such as `org-todo` and `org-refile`.
+Press `RET` to visit the file.
+The view looks like this:
+
+![emacs-tut-org-agenda](media/emacs-tut-org-agenda.png)
+
+> [!note]
+> Add the following header at the top of your `~/org/inbox.org` to see the untriaged tasks:
+> ```bash
+> #+FILETAGS: inbox
+> ```
+
+[emacs-gtd]: https://www.labri.fr/perso/nrougier/GTD/index.html
+
+#### Scheduling
+
+Schedule a task with `org-schedule` (`C-x C-s`); this command pops up the Emacs calendar to
+select a date. You can pick the date in the calendar, or type a date selection like:
+
+- `+3h`: three hours from now.
+- `+1d`: tomorrow.
+- `+1w`: next week.
+- `+1m`: next month.
+- `Mon`: next Monday.
+- `20`: next 20th day of the month.
+- `12-25`: next Dec 25th.
+- `YY-MM-DD`: a fixed date.
+
+When a task has a scheduled property, it will appear in the calendar.
+If an open task is scheduled in the past, it appears as `Sched` in the calendar,
+reminding you that you forgot to complete a scheduled task.
+
+You can make an event repeat with the following time syntax:
+
+- `<2024-11-01 Fri +1m -3d>` for paying the rent; the task is required every month.
+- `<2024-11-16 Sat .+2m>` for changing toothbrush; marking this DONE shifts the date to two month after today.
+- `<2008-02-10 Sun ++1w>` for calling your mom; marking this DONE shifts the date by at least one week
+
+For example, add the following heading to get started. Note that the first item is not a task, it's just a reminder for tri-weekly event:
+
+```bash
+* Work
+** Sprint review
+SCHEDULED: <2024-10-09 Wed 09:00 ++3w>
+
+* Home
+** TODO Pay rent
+SCHEDULED: <2024-11-01 Fri +1m -3d>
+
+** TODO Change toothbrush
+SCHEDULED: <2024-11-16 Sat .+2m>
+
+** TODO Call mum
+SCHEDULED: <2008-02-10 Sun ++1w>
+```
+
+Finally, add the following to record anniversary events:
+
+```bash
+* Anniversaries
+%%(diary-anniversary 5 29 2012) Zuul was created %d years ago
+```
+
+> [!tip]
+> Schedule tasks to put them at the top of your dashboard.
+
+
+#### Journaling
+
+You can write a journal with org-capture, add the following template:
+
+```scheme
+;; Add a new org-capture 'j' for journaling
+(add-to-list 'org-capture-templates
+  '("j" "Journal" entry (file+olp+datetree "~/org/journal.org")
+    "* %?\n")
+  t)
+```
+
+Press <kbd>F6</kbd> <kbd>j</kbd> to record an event. It will be written to
+your `~/org/journal.org` using date tree headings.
+
+> [!tip]
+> Use journal capture to keep track of what you are doing.
+
+#### Archive
+
+When a task or project is no longer relevant, use the `org-archive-subtree`
+to clean up your org file. This command moves the content to an archive file.
+
+Here is a useful command to archive all completed tasks:
+
+```scheme
+;; From: https://stackoverflow.com/a/70131908
+;; With auto save disabled
+(defun org-archive-done-tasks ()
+  "Archive all tasks marked DONE in the file."
+  (interactive)
+  ;; Disable auto save
+  (setq org-archive-subtree-save-file-p nil)
+  (unwind-protect
+      (mapc (lambda(entry)
+              (goto-char entry)
+              (org-archive-subtree))
+            ;; process the entry in reverse to avoid changes in positioning
+            (reverse (org-map-entries (lambda () (point)) "TODO=\"DONE\"" 'file)))
+      (setq org-archive-subtree-save-file-p t)))
+```
 
 ### notmuch
 
@@ -1151,6 +1439,8 @@ Emacs contains hundreds of microscopic quality of life features:
 
 ### vterm
 
+### org-ql
+
 ### Tramp
 
 ```scheme