diff --git a/content/emacs/media/emacs-tut-org-agenda.png b/content/emacs/media/emacs-tut-org-agenda.png new file mode 100644 index 000000000..dfacfcae0 Binary files /dev/null and b/content/emacs/media/emacs-tut-org-agenda.png differ diff --git a/content/emacs/media/emacs-tut-org-file.png b/content/emacs/media/emacs-tut-org-file.png new file mode 100644 index 000000000..020a1456f Binary files /dev/null and b/content/emacs/media/emacs-tut-org-file.png differ diff --git a/content/emacs/tutorial.md b/content/emacs/tutorial.md index 3af79bef3..8b2049aec 100644 --- 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. @@ -1136,7 +1137,306 @@ 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 "") 'org-capture) +``` + +> [!tip] +> Capture tasks at any time by pressing F6 t. +> 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* | +|---------------------------------|-----------------------------------| +| TAB | Cycle folding on current heading. | +| shift+TAB | Cycle folding on the whole file. | +| alt+↑ | Move subtree up. | +| alt+↓ | Move subtree down. | +| `M-g i` | Jump to a place in the buffer. | +| `M-RET` | Insert a new heading. | + + +#### 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 +;; org-agenda provides the GTD dashboard +(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>=\"\"" + ((org-agenda-overriding-header "\nCompleted today\n"))))))) + + ;; Press F4 to get things done! + (global-set-key (kbd "") (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 F4 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 by pressing `RET` on a day, +or you can directly type a date delta like: + +- `+3h`: three hours from now. +- `+1d`: tomorrow. +- `+1w`: next week. +- `+1m`: next month. +- `Mon`: next Monday. +- `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 AGEx` in the current day, +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 checking batteries; 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 headings 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> +``` + +> [!tip] +> Schedule tasks with `C-c C-s` to put them at the top of your dashboard. + + +Finally, add the following to record anniversary events: + +```bash +* Anniversaries +%%(diary-anniversary 3 20 1985) GNU Emacs was first released %d years ago +%%(diary-anniversary 5 29 2012) Zuul was created %d years ago +``` + +#### 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 F6 j 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. +> That's a good practice for daily standups and monthly reviews. + +#### 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 that you can use to research the past events. + +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 to avoid repeated file write. + (setq org-archive-subtree-save-file-p nil) + ;; unwind-protext is like try/finally + (unwind-protect + ;; process the entry in reverse to avoid changes in positioning + (mapc (lambda(entry) + (goto-char entry) + (org-archive-subtree)) + (reverse (org-map-entries (lambda () (point)) "TODO=\"DONE\"" 'file))) + ;; Enable auto save, even if an exception is raised. + (setq org-archive-subtree-save-file-p t)) + (org-save-all-org-buffers)) +``` + +--- +To summarize, here are the main actions to implement GTD with Emacs: +- Add tasks with `org-capture`. +- Sort your inbox with `org-refile`. +- Groom your backlog with `org-todo` +- Plan your projects with `org-schedule`. +- Get things done with `org-agenda`. + +Note that Org Mode also provides many additional features, such as: +- Time management with `org-clock`. +- Document publication with `org-export`. +- Literate source code editing with `org-babel`, which is similar to Jupyter notebooks. + +However, I am not familiar with these features because I only use basic Org for Getting Things Done. ### notmuch @@ -1152,6 +1452,8 @@ Emacs contains hundreds of microscopic quality of life features: ### vterm +### org-ql + ### Tramp ```scheme