hamacs/ha-agendas.org

#+title:  Org Agenda Configuration
#+author: Howard X. Abrams
#+date:   2020-09-18
#+tags: emacs org

A literate programming configuration for fancy agenda and todo lists.

#+begin_src emacs-lisp :exports none
  ;;; ha-agendas --- Configuration for fancy agenda and todo lists. -*- lexical-binding: t; -*-
  ;;
  ;; © 2020-2023 Howard X. Abrams
  ;;   Licensed under a Creative Commons Attribution 4.0 International License.
  ;;   See http://creativecommons.org/licenses/by/4.0/
  ;;
  ;; Author: Howard X. Abrams <http://gitlab.com/howardabrams>
  ;; Maintainer: Howard X. Abrams
  ;; Created: September 18, 2020
  ;;
  ;; This file is not part of GNU Emacs.
  ;;
  ;; *NB:* Do not edit this file. Instead, edit the original literate file at:
  ;;            ~/other/hamacs/ha-agendas.org
  ;;       And tangle the file to recreate this one.
  ;;
  ;;; Code:
#+end_src
* Introduction
All the code we describe in this file needs loading /after/ org.

#+begin_src emacs-lisp
(with-eval-after-load "org"
  (add-to-list 'org-modules 'org-protocol))
#+end_src
* Grouping
Typical agendas have an /order/ to them, but the [[https://github.com/alphapapa/org-super-agenda][org-super-agenda project]] allows you to get specific as well as group them under headings.

Unless you specify otherwise, this is the grouping we'll use:

#+begin_src emacs-lisp
  (use-package org-super-agenda
    :after org
    :init
    (setq org-super-agenda-date-format "%A (%e)"
          org-super-agenda-groups
          '((:name "Accomplishments"
             :todo ("DONE" "CANCELED")
             :order 4)
            (:name "End of Day"
             :habit t
             :order 2)
            (:name "Uncompleted Work"
             :todo "DOING"
             :scheduled past
             :order 0)
            (:name "Today's Tasks"
             :date today
             :order 1)
            (:name "Today's Tasks"
             :scheduled today
             :order 1)
            (:name "Future Work"
             :todo "TODO"
             :scheduled future
             :order 3))))
#+end_src

The task matches a group based on the /code order/, but the =:order= tag allows me to display them in a different order.

The following super agenda is just for /today/ and should be smaller:
#+begin_src emacs-lisp :tangle no
  (setq ha-org-super-agenda-today
        '((:name "Finished"
                 :todo ("DONE" "CANCELED")
                 :order 4)
          (:name "End of Day"
                 :habit t
                 :order 2)
          (:name "Today's Tasks"
                 :todo "DOING"
                 :scheduled past
                 :date today
                 :order 0)))
#+end_src
* Query Views
The [[https://github.com/alphapapa/org-ql][org-ql project]] gives us a /query language/ of sorts (based on s-expressions).

By putting all queries under =org-ql-views=, we can then call ~M-x query~ and select the view to display:

#+begin_src emacs-lisp
  (use-package org-ql
    :after org
    :config
    ;; Often used 'subgroup' that defines a work task
    (setq ha-org-ql-typical-work-tasks
          '(and (tags "work")

                ;; I will always be Supporting the onboarding projects,
                ;; but don't show them (but show descendants):
                (not (and (tags "onboarding")
                          (heading "^Support ")))

                ;; Show a blocking subtask instead of the parent:
                (or (not (children))
                    (not (descendants (todo "TODO" "DOING"))))

                (not (habit))
                (not (done))))

    (setq org-ql-views
          (list (cons "Overview: Today"
                      (list :buffers-files #'org-agenda-files
                            :query `(or (closed :on today)
                                        (and (habit)
                                             (not (done))
                                             (scheduled :to today))
                                        (and ,ha-org-ql-typical-work-tasks
                                             (or (deadline auto)
                                                 (todo "DOING")
                                                 (scheduled :to today)
                                                 (ts-active :on today))))
                            :sort '(priority date)
                            :super-groups 'ha-org-super-agenda-today
                            :title "Today in Me"))

                (cons "Overview: Tomorrow"
                      (list :buffers-files #'org-agenda-files
                            :query '(and (not (done))
                                         (tags "work")
                                         (scheduled :from tomorrow :to tomorrow))
                            :sort '(priority date)
                            :super-groups 'ha-org-super-agenda-today
                            :title "Overview: Tomorrow's tasks"))

                (cons "Calendar: Today"
                      (list :buffers-files #'org-agenda-files
                            :query '(ts-active :on today)
                            :title "Today"
                            :super-groups 'ha-org-super-agenda-today
                            :sort '(priority))))))
#+end_src
* Agenda Interface
We can create a function to start this:
#+begin_src emacs-lisp
(defun ha-todays-agenda ()
  "Display an agenda for today, including tasks and scheduled entries."
  (interactive)
  (org-ql-view "Overview: Today"))
#+end_src

And of course, a keybinding:
#+begin_src emacs-lisp
(ha-leader "a a" '("my agenda" . ha-todays-agenda))
#+end_src
* Technical Artifacts                                :noexport:
Let's provide a name so that the file can be required:

#+begin_src emacs-lisp :exports none
(provide 'ha-agendas)
;;; ha-agendas.el ends here
#+end_src

Before you can build this on a new system, make sure that you put the cursor over any of these properties, and hit: ~C-c C-c~

#+description: A literate programming configuration for fancy agenda and todo lists.

#+property:    header-args:sh :tangle no
#+property:    header-args:emacs-lisp :tangle yes
#+property:    header-args    :results none :eval no-export :comments no mkdirp yes

#+options:     num:nil toc:t todo:nil tasks:nil tags:nil date:nil
#+options:     skip:nil author:nil email:nil creator:nil timestamp:nil
#+infojs_opt:  view:nil toc:t ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js